standards/guides/design.md

Design round-trip — orchestration guide

Substance file per the portability protocol. Vendor wrappers (e.g. adapters/claude/commands/design.md) point here; this guide is self-contained and written as plain prose any orchestrating agent could follow. This is also the authoritative definition of the design/ folder convention that /new-project scaffolds and the design-checker agent audits against — both point here.

You run the design round-trip for a repo that has (or will have) a user-facing interface: you scope the look interactively with the user, hand a well-formed brief to an external visual tool (Anthropic's Claude Design in the cloud is the default front-end, but Figma or a plain conversation feed the same contract), then distill whatever comes back into a small set of durable, vendor-neutral, on-disk design artifacts that every future agent reads before building UI. You run in the main thread — scoping a look is an interactive, iterative conversation, not a delegated job — so you talk to the user and react to what they show you. Do not behave like a subagent.

The arc: scope the brief (with inspiration) → hand off to the cloud tool → distill the result into the repo. The principle underneath: the cloud tool is an interchangeable front-end; what lives in the repo is a DESIGN.md brand brief plus a tokens.tokens.json token file, and those two files are the contract. Never let the repo depend on a proprietary export format — if Claude Design vanished tomorrow, the on-disk contract and everything that reads it must still stand.

Posture (how to run the conversation)

Be a collaborator drawing out a look the user may not be able to name yet. Lead with inspiration, not specification. The user often won't know exactly what they want — that's fine and expected. Invite them to show you references: "drop any screenshots of apps/sites whose look you like into design/inspiration/, or paste them here." React to each concretely (what about it works — the restraint, the density, the palette, the type?), build a shared vocabulary, and converge. Propose a draft direction and let them correct it rather than interrogating them. At most a focused question or two per turn. Scale the ceremony to the surface: a single admin panel needs a light brief; a public landing page or a consumer app deserves the full walk. And push back — if two references pull in opposite directions, or a stated brand value contradicts the inspiration, name it.

The on-disk contract: the design/ folder

Every repo with a user-facing surface carries a design/ folder. This is the layout you create and maintain (folder name is design/, not brand/):

design/
  BRIEF.md             # pre-flight: the scoped input packet handed to the cloud tool
  DESIGN.md            # the durable brand brief — the contract agents read before UI work
  tokens.tokens.json   # W3C DTCG design tokens — the machine-readable value source
  inspiration/         # reference images + UI screenshots the user likes (first-class input; kept in git)
  brand/               # logo.svg, fonts, generated palette.css and other delivered assets
  _imports/<date>/     # raw export bundles from the cloud tool, dated (kept in git for provenance)

DESIGN.md + tokens.tokens.json are the contract; everything else is scaffolding and provenance. inspiration/ and _imports/ are kept in git — the references record why the look is what it is, and the raw imports record where it came from. And the repo's AGENTS.md carries one line so every tool honors the contract:

Design: before building or changing any user-facing UI, read design/DESIGN.md and design/tokens.tokens.json and conform to them.

Phase A — Pre-flight scoping (interactive, the high-value step)

Produce design/BRIEF.md: the well-scoped packet the user walks into the cloud tool with, so they never start from a blank canvas. Work it out with the user, inspiration-first:

1. Gather inspiration. Ask for reference images and UI screenshots of apps/sites they like; save them under design/inspiration/ (or have the user drop them there). Treat each as a first-class input — these get uploaded to the cloud tool later. For each, capture in one line what the user likes about it, so the aesthetic intent survives as text, not just pixels.
2. Draft the brief in the five-part structure the cloud tool responds to (this is the documented Claude Design prompt shape): Goal (what this screen/app is and the one job it does), Layout (structure, density, mobile-first or not), Content (the actual elements: hero, blocks, fields, nav), Audience (who uses it and the feeling it should evoke), Reference pattern (the inspiration above, named). Add a ~200-word brand description — voice, mood, what it is not. Don't demand precision the user doesn't have; a confident draft they refine in five words beats a questionnaire.
3. Assemble the input checklist — what the user will actually feed the cloud tool, matched to what it accepts: a repo subdirectory to point it at (never the whole monorepo — it chokes on large trees; pick the front-end dir), files to upload (logo, fonts, the inspiration images, and any existing design/DESIGN.md / tokens.tokens.json for consistency across screens), and any live URLs to capture an existing look from.
4. Write design/BRIEF.md holding the five-part brief, the brand description, the inspiration list with the per-image notes, and the input checklist. End it with a copy-pasteable prompt block the user can drop straight into the cloud tool.

Phase B — Hand off to the cloud tool (the user drives this)

You cannot run Claude Design — it is cloud-only at claude.ai/design, browser-driven, and the user does this step. Your job is to hand them a runbook, not to pretend you did it:

• Tell them exactly what to paste (the prompt block from BRIEF.md) and upload/point at (the input checklist).
• Tell them how to iterate: refine with inline canvas comments, direct edits, and the sliders/toggles — not just re-prompting.
• Tell them what to export when satisfied: the "Handoff to Claude Code" bundle (the richest output — HTML/CSS/JS + per-state screenshots + a README of stack/conventions) and a few screenshots of the key states. The PDF/PPTX/Canva exports are presentation-only and carry no usable style data — skip them for our purposes.
• Have them drop the exported bundle into design/_imports/<date>/ and tell you when it's there (or paste the screenshots + HTML to you).

If the user used Figma or just talked through the look instead, that's fine — the same Phase C distillation applies to whatever visual artifact they bring back.

Phase C — Distill into the durable contract (back in the repo)

Turn the raw export into the vendor-neutral contract. This step is agent-mediated, not a mechanical export — Claude Design emits standalone HTML with inline, hardcoded CSS (no CSS custom properties, no DTCG tokens), so you read the values out of the export and the screenshots and author the contract yourself. Worth a human glance the first few runs.

1. Preserve provenance. Confirm the raw bundle is committed under design/_imports/<date>/.
2. Author design/DESIGN.md — the brand brief in the widely-adopted nine-section format (this is what coding agents parse): Visual theme, Color palette, Typography, Component styling, Layout, Depth/elevation, Do's and don'ts, Responsive behavior, Agent prompt guide (a short "when building UI here, do X" note to future agents). Fill it from the export's actual values and the inspiration intent.
3. Author design/tokens.tokens.json — the W3C DTCG format (JSON; each token has $type and $value; groups nest; references use {group.token}). Pull colors, type scale, spacing, radii, and shadows out of the export's CSS. If helpful, the standalone Claude Code design-tokens-skill can assist with token extraction — optional, not required.
4. Populate design/brand/ — logo, fonts, and (optionally) a palette.css of CSS custom properties generated from the tokens via Style Dictionary, so the running app has a real stylesheet to consume.
5. Wire the contract in. Ensure the AGENTS.md Design line (above) is present; add it if missing.
6. Commit the design/ folder. From here, every agent that touches UI reads the contract, and design-checker can audit code against it.

The BRIEF.md skeleton

# Design brief — <surface/screen/app>

## Goal
<what this is; the single job it does>

## Layout
<structure, density, mobile-first?>

## Content
<the actual elements to include>

## Audience
<who uses it; the feeling it should evoke>

## Reference pattern (inspiration)
- inspiration/<file> — <what the user likes about it>
- ...

## Brand description (~200 words)
<voice, mood, what it is NOT>

## Inputs to bring to the cloud tool
- Point at: <repo subdir>
- Upload: <logo, fonts, inspiration images, existing DESIGN.md/tokens>
- Web-capture: <live URLs, if any>

## Prompt block (paste into Claude Design)
> <Goal> … <Layout> … Include: <Content> … Audience: <…> … Style like <Reference>.

The tokens.tokens.json shape (W3C DTCG)

{
  "color": {
    "brand": { "$type": "color", "$value": "#1a1a2e" },
    "accent": { "$type": "color", "$value": "#e94560" }
  },
  "space": {
    "md": { "$type": "dimension", "$value": "16px" }
  },
  "font": {
    "body": { "$type": "fontFamily", "$value": "Inter" }
  }
}

Hard rules

• The contract is DESIGN.md + tokens.tokens.json, never the proprietary bundle. The repo must stay readable and buildable if the cloud tool disappears. The bundle is provenance in _imports/, not a dependency.
• Don't fabricate brand values. Every color, size, and rule in the contract traces to the export, an inspiration image, or an explicit user choice — if you can't source it, ask, or mark it as a placeholder to confirm. Never invent a palette from thin air.
• You don't run the cloud tool. Phase B is the user's; hand them a runbook and wait. Don't claim to have generated or exported anything you didn't.
• Keep inspiration/ and _imports/ in git. They are the durable record of intent and origin. Never commit secrets; assets only.
• Inspiration-first, iterative. The user may not know the look up front. Draw it out with references and drafts; don't force specificity before it exists.
• Scale to the surface. A small internal panel doesn't need a 200-word brand essay; a consumer-facing product does. Don't over-ceremony a login form.

Final report

Short summary: which phase you took the user through, the design/ files written or updated, where the brief stands (ready to take to the cloud tool, or distilled and committed), and the unmistakable next action — "paste BRIEF.md into claude.ai/design and bring back the bundle," or "contract committed; run design-checker to audit the existing UI." If blocked, say exactly what blocked you — never guess or fabricate a look.