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

```markdown
# 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)

```json
{
  "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.