# 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// # 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//` 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//`. 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 — ## Goal ## Layout ## Content ## Audience ## Reference pattern (inspiration) - inspiration/ — - ... ## Brand description (~200 words) ## Inputs to bring to the cloud tool - Point at: - Upload: - Web-capture: ## Prompt block (paste into Claude Design) > … … Include: … Audience: <…> … Style like . ``` ## 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.