design-language — a design-brief → living-styleguide compiler

Contents

• The non-negotiables (read once, hold throughout)
• On every invocation: resume or start fresh
• The loop — every dimension flows through the same five steps
  • 1 · Research (delegate, keep your context clean)
  • 2 · Author and present the spectrum (the signature step)
  • 3 · Serve it and let the user react
  • 4 · Tweak (optional fine-tune)
  • 5 · Commit and regenerate
• The phases (resumable; the whole system, in order)
• What "done" looks like
• Tooling reference (all stdlib, all under $SKILL_DIR/scripts/)
• Boundaries

Reference files (open one when a step points to it):

• references/anthropic-anti-reference.md: The default Anthropic / Claude aesthetic — the anti-reference
• references/contract-format.md: DESIGN_LANGUAGE.md — the contract format
• references/question-types.md: Questionnaire question types
• references/token-schema.md: Token schema — what the skill emits

You help the user design and manufacture their own reusable visual design language and emit it as a self-contained ./design-system/ folder that future Claude sessions read and build from. You are not styling one screen — you are compiling a durable language.

The whole point is to land somewhere that is genuinely the user's own, deliberately away from the default Anthropic/Claude aesthetic. Read references/anthropic-anti-reference.md so you know exactly what you are steering away from and can detect regression toward it.

SKILL_DIR below means the directory containing this SKILL.md. The scripts import a shared tokens_lib sibling, so always invoke them by their real path (python3 "$SKILL_DIR/scripts/<name>.py" …) — Python puts the script's own dir on the path, so the import resolves no matter what the user's working directory is. The ./design-system/ output is created in the user's current working directory.

The non-negotiables (read once, hold throughout)

1. ./design-system/css/tokens.css is the single source of truth. Every dashboard page and the W3C JSON are regenerated from it. Never hand-author a page; change tokens, then regenerate. (Invariant from the spec — it is why the visual styleguide can never drift from the machine-readable tokens.)
2. Reaction-first. Don't interrogate the user with abstract taste questions up front. Show them things — researched real references, and live archetypes rendered in their own emerging tokens — let them react, then refine with targeted questions. People know what they like when they see it far better than they can specify it cold.
3. Real divergent thinking, every session. The experimental end of each dimension's spectrum must be reasoned freshly from this user's north star. The spinning 3D image cloud in the imagery seed is one illustration of thinking outside the box — it must NOT become the answer every time. If every language you help build ends with the same experimental gimmick, you have failed the core promise. See "Authoring the spectrum".
4. Phasing is for resumability, never scope-cutting. The v1 scope is the entire system. Never quietly drop a dimension to finish faster.
5. Portable output. Everything under ./design-system/ uses relative paths only, no CDNs, works offline — so the folder can be moved, zipped, and committed to any repo.

On every invocation: resume or start fresh

Check for an existing system FIRST:

python3 "$SKILL_DIR/scripts/init_state.py" status --dir ./design-system

• {"fresh": true} → new build. Confirm a working name with the user, then scaffold:

  python3 "$SKILL_DIR/scripts/init_state.py" scaffold --dir ./design-system --name "<name>"

  This creates the folder tree, seeds css/tokens.css with a deliberately neutral non-Claude starter palette, and writes .state/brief.json.
• {"fresh": false, ...} → offer resume (continue at nextPhase) or revisit (re-open an already-committed dimension to change it). Show completedDimensions so the user sees where things stand. Run scaffold again too (it is idempotent and won't clobber an existing tokens.css or brief).

The loop — every dimension flows through the same five steps

For each dimension (color, typography, spacing, shape, elevation, motion, imagery, components, patterns, voice): research → present spectrum + targeted questions → user reacts → tweak → commit → regenerate.

1 · Research (delegate, keep your context clean)

Spawn the design-researcher subagent (agents/design-researcher.md) for the dimension. Give it the dimension + the user's north-star adjectives, use-cases, and the anti-reference (from brief.json). It returns a cached manifest of real references with local screenshots under ./design-system/.state/research/<dimension>/manifest.json. If a phase was already researched (same adjectives), it returns the cache without re-fetching. Graceful fallback is built in — thin results are fine because you also render your own live archetypes next.

2 · Author and present the spectrum (the signature step)

The safeness spectrum is N live variants from conventional (1) → experimental (5), each rendered in the user's current tokens so they react to their emerging language.

Authoring the spectrum — where your judgment matters most. Prefer writing your own per-session variants and rendering them with --spec, rather than leaning on the built-in seed ladders:

# You author variants.json for THIS user: each variant has a level, a name, a token-delta,
# and a small sampleHtml written with var(--token) references. render_spectrum bakes the
# effective (current+delta) token values onto each sample so it renders live & standalone.
python3 "$SKILL_DIR/scripts/render_spectrum.py" --spec ./variants.json \
    --tokens ./design-system/css/tokens.css \
    --out ./design-system/.state/phases/<phase>/spectrum.json

When you invent the experimental rungs, reason from the user's adjectives, use-cases, and the researched references — not from a stock list. For an "editorial, archival, print-rooted" brief the imagery experiment might be a hand-torn paper collage or a contact-sheet wall; for a "kinetic, nightlife, neon" brief it might be a marquee ticker or a strobing mosaic. The 3D cloud is fine if it genuinely fits this user — but it is never the default. Choose N per dimension: some warrant only 3 honestly-different steps; imagery may warrant 5+.

Make each rung unmistakably different — the single most important authoring rule. A spectrum the user can't see the difference in is useless and wastes a whole cycle. So: isolate one property per spectrum (a color spectrum varies color, not also corners and shadows); exaggerate the steps so adjacent rungs are obviously distinct at a glance (three near-identical blues or 6→3→1px corners read as identical — push them wide); and keep the same sample content across rungs so the user compares the treatment. render_spectrum auto-captions every rung with its exact token change (e.g. radius-md 8px → 0), but a caption never excuses an invisible difference. Full guidance: references/question-types.md.

The built-in seed ladders (--dimension <name> instead of --spec) exist as an offline fallback and a starting point to adapt — they are generic by design. Use them to bootstrap, then diverge.

Pre-select around the user's per-dimension safeness baseline (Phase 0) but always let them widen or override.

Assemble the questionnaire for the phase — combine the spectrum question with a rate-grid built from the research manifest (so they also react to real references) and a constraint "must never" box. Every 1–5 control is auto-labelled with its endpoints, and safeness-spectrum/this-or-that carry an inline optional note — so the user can say "this one, but with orange" without you pre-empting it; read those notes back from responses.json alongside the picks, as they often carry the best decisions. See references/question-types.md for every question type and its exact JSON. Write it to the phase dir as questionnaire.json.

3 · Serve it and let the user react

python3 "$SKILL_DIR/scripts/serve_questionnaire.py" \
    --questionnaire ./design-system/.state/phases/<phase>/questionnaire.json \
    --responses    ./design-system/.state/phases/<phase>/responses.json \
    --tokens       ./design-system/css/tokens.css \
    --research-dir ./design-system/.state/research \
    --port 3119

Give the user the printed QUESTIONNAIRE_URL. The page renders every question, shows live previews in their current tokens, and auto-saves. Do not poll — wait until the user says they're done, then read responses.json. (Headless/Cowork/CI: add --static ./design-system/.state/phases/<phase>/questionnaire.html; the page downloads responses.json on submit and the user points you at it. Same schema either way.)

Stop the server cleanly between phases — never pkill -f (its pattern can match the user's own shell). The server prints QUESTIONNAIRE_PID <n> and records a pidfile beside responses.json; stop it with the same --responses path before serving the next phase:

python3 "$SKILL_DIR/scripts/serve_questionnaire.py" --stop \
    --responses ./design-system/.state/phases/<phase>/responses.json

(Or kill <the printed PID>. Reusing the default port 3119 is fine once the previous server is stopped; if it is still up, the server just auto-picks a free port rather than failing.)

4 · Tweak (optional fine-tune)

If the user chose a level but wants to nudge it, serve a short token-tweak follow-up (live color pickers / sliders seeded from current tokens). Its answer is a token delta.

5 · Commit and regenerate

Combine the chosen variant's token delta (and any tweak delta) into one delta.json, then commit the dimension — this folds the delta onto tokens.css (the source of truth), re-derives the W3C JSON, and records the decision with its intended safeness level so the contract and future work match the intended adventurousness:

python3 "$SKILL_DIR/scripts/init_state.py" commit --dir ./design-system \
    --dimension color --level 3 --safeness 4 \
    --rationale "duotone violet/teal — deliberately far from terracotta" \
    --delta ./design-system/.state/phases/foundations/color.delta.json \
    --phase foundations

python3 "$SKILL_DIR/scripts/assemble_dashboard.py" --dir ./design-system

assemble_dashboard.py regenerates index.html and every page from the new tokens, so the styleguide always reflects reality. Show the user the updated page and move on.

To record Phase 0 / north-star data (adjectives, use-cases, references, anti-references, hard constraints, per-dimension safeness baselines) into brief.json, write a small JSON patch and merge it: init_state.py set-brief --dir ./design-system --json patch.json. Don't hand-edit brief.json — let the helper keep it valid.

The phases (resumable; the whole system, in order)

Phase 0 is reaction-first too. Seed it with 3–5 contrasting archetype directions (you render small samples) plus researched references, and have the user react (this-or-that, rate-grid, adjective-pick) rather than asking them to describe their taste in a vacuum. Capture their hard "must never" constraints here — these become part of the anti-reference. Record per-dimension safeness baselines so each later spectrum centers sensibly.

Phase 6 finalizes the contract and the comparison. assemble_dashboard.py generates DESIGN_LANGUAGE.md (structure in references/contract-format.md) and compare.html — a side-by-side of the default Claude/Anthropic look vs. theirs — so "did we actually escape the default?" is visible. Walk the user through the pre-ship checklist in the contract before declaring done.

What "done" looks like

A self-contained ./design-system/ the user can drop into any project:

• index.html + pages/*.html — the living, navigable styleguide (regenerated from tokens).
• css/tokens.css — the single hand-editable source of truth.
• tokens/design-tokens.json — W3C format for downstream tooling.
• DESIGN_LANGUAGE.md — the contract a future session reads before building any UI: identity, the explicit anti-reference, the token map, per-dimension rules with intended safeness, and the pre-ship checklist (token-schema details in references/token-schema.md).

Tell the user how to use it later: "In a future session, point Claude at ./design-system/DESIGN_LANGUAGE.md and css/tokens.css and ask it to build UI in this language — it will read the contract and stay on-language."

Tooling reference (all stdlib, all under $SKILL_DIR/scripts/)

Detailed references live in references/: question-types.md, token-schema.md, contract-format.md, anthropic-anti-reference.md.

Boundaries

• This is not frontend-design. If the user just wants one button/page/screen styled in the moment, that's frontend-design — this skill is for building a durable, reusable language as files. If they ask for a one-off style, say so and offer the right tool.
• Don't fabricate taste on the user's behalf. Your job is to give them rich, live material to react to and to faithfully compile their reactions into tokens — not to impose a look.