# 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 establish the look — by scoping a fresh design, importing prior guidelines, or extracting the de-facto design already in the code — then (optionally) take it through 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), and distill the result 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** — establishing 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: **read the situation → establish the design intent → (optionally) round-trip through the cloud tool → distill into the repo → promote what you learned.** 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 (fresh/redesign runs) 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 / prior guidelines, 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 0 — Read the situation, pick the on-ramp Before anything, determine which of four situations you're in — it sets the whole run: - **Refine** — `design/DESIGN.md` already exists. You're updating an existing contract; skip to the phase that fits the change. - **Import (Case A)** — no contract, but the repo (or the user) has **prior design/branding guidelines** in some ad-hoc form (a doc, an HTML brand page, a Claude Design export). Go to Phase A → *Import*. - **Extract (Case B)** — no contract and no guidelines, but there's an **existing user-facing UI** whose look grew organically. Go to Phase A → *Extract*. - **Fresh** — no contract and no UI yet (a new or pre-UI project). Go to Phase A → *Fresh*. Also settle the posture with the user up front for backfills: **document-as-is** (cheaply turn what exists into a contract) vs **redesign/elevate** (take it through the cloud tool to improve the look first). Document-as-is skips Phase B; redesign runs it. ## Phase A — Establish the design intent Pick the branch from Phase 0. All three converge on Phase C (the contract). **Fresh — inspiration-first scoping → `design/BRIEF.md`.** Produce the 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 / UI screenshots; save under `design/inspiration/`. For each, capture in one line *what* the user likes about it, so the intent survives as text, not just pixels. 2. **Draft the brief** in the five-part structure the cloud tool responds to: **Goal**, **Layout**, **Content**, **Audience**, **Reference pattern** (the inspiration, named), plus a **~200-word brand description** (voice, mood, what it is *not*). 3. **Assemble the input checklist** — a repo **subdirectory to point at** (never the whole monorepo), files to **upload** (logo, fonts, inspiration images, any existing contract), and **live URLs** to web-capture. 4. **Write `design/BRIEF.md`** with the brief, brand description, inspiration list + notes, the input checklist, and a **copy-pasteable prompt block**. **Import (Case A) — locate → map → gap-fill → reconcile.** 1. **Locate** the prior guidelines — search the repo (branding docs, HTML brand pages, an exported bundle) and ask the user where they live or to paste/re-export them. Drop the raw artifact into `design/_imports//` for provenance. 2. **Map** their content onto our nine-section `DESIGN.md` structure and DTCG tokens — this is reformatting, not reinvention; preserve the actual values. 3. **Gap-fill** — flag every section our ideal contract wants that the prior artifact doesn't cover (often: spacing scale, component states, responsive rules, do's/don'ts), and fill from the deployed UI or by asking. 4. **Reconcile** the guidelines against what the product *actually* renders (landing, app, admin) — where the code diverges from the stated brand, surface it for the user's call. **Extract (Case B) — inventory → reconcile → (then formalize in Phase C).** 1. **Inventory the as-built design.** Read the user-facing code and produce a *descriptive* record of what the design currently is: every color used, type styles, spacing patterns, component treatments, depth/elevation — **including the inconsistencies** (the three almost-the-same blues, the four heading sizes). A read-only `design-checker` cannot do this (it needs a contract to check against), so inventory here in the main thread, optionally delegating a read-only reader to gather the raw values. 2. **Reconcile with the user.** Surface the conflicts and let them make the **canonical calls** — which blue is *the* blue, which scale is *the* scale. Organically-arrived-at does not mean correct; their taste decides. This is the high-value human step; don't auto-resolve it. ## Phase B — (Optional) cloud round-trip Run this only for **fresh** designs that need the visual tool, or **redesign/elevate** backfills. Document-as-is backfills skip it. You cannot run Claude Design — it is cloud-only at `claude.ai/design`, browser-driven, and the user does this step. Hand them a runbook: - What to **paste** (the prompt block from `BRIEF.md`) and **upload/point at** (the checklist). - How to **iterate**: inline canvas comments, direct edits, sliders/toggles — not just re-prompting. - What to **export**: the **"Handoff to Claude Code" bundle** (richest — HTML/CSS/JS + per-state screenshots + a README of stack/conventions) and a few **screenshots**. PDF/PPTX/ Canva are presentation-only — skip them. Drop the bundle into `design/_imports//`. If the user used Figma or just talked through the look, that's fine — the same Phase C applies. ## Phase C — Distill into the durable contract Turn the input — a cloud export, imported guidelines, or a reconciled inventory — into the vendor-neutral contract. When distilling a Claude Design export, note it 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 values out of the export/screenshots and author the contract yourself. Worth a human glance the first few runs. 1. **Preserve provenance.** Confirm the raw input is committed under `design/_imports//`. 2. **Author `design/DESIGN.md`** in the nine-section format 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). 3. **Author `design/tokens.tokens.json`** — W3C DTCG (JSON; each token has `$type` and `$value`; groups nest; references use `{group.token}`). Pull colors, type scale, spacing, radii, shadows from the input. The standalone Claude Code `design-tokens-skill` can assist — optional. 4. **Populate `design/brand/`** — logo, fonts, optionally a `palette.css` generated from the tokens via Style Dictionary. 5. **Wire the contract in.** Ensure the `AGENTS.md` **Design line** is present; add if missing. 6. **Commit** the `design/` folder. For backfills, then fan out **`design-checker`**: the gap between the just-canonicalized contract and the current code is a **cleanup backlog** — capture it to that repo's `ROADMAP.md` (don't silently fix it in the same pass). ## Phase D — Promote learnings (close the loop) A `/design` run teaches you things. **Two kinds, harvested from two places:** the **pre-flight scoping conversation** (Phase A — what kinds of questions drew the look out, what inspiration prompts worked, where the brief was thin) and the **distillation** (Phase C — how the export actually behaved, what token-mapping heuristics held up, what tripped you). At the end of every run, ask: *did this surface something generalizable about the **process** — not a fact about this project's brand?* - **If yes, promote it to the global standard.** Propose an edit to *this* file (`~/Projects/standards/guides/design.md`) — usually a new bullet under **Field notes** below, or a refinement to a phase — so the next repo inherits it. Recurring `design-checker` violation patterns get the same treatment in `guides/design-checker.md`. - **Keep the scope rule.** *Brand facts* (this palette, this voice) live in the repo's `design/DESIGN.md`. *Process learnings* (how to scope, how to distill) live here in the global guide. Never cross them. - Show the diff and the rationale; don't silently rewrite the standard (per `how-i-work.md`). ## 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 traces to an export, an inspiration image, prior guidelines, the as-built code, or an explicit user choice — if you can't source it, ask, or mark it a placeholder to confirm. Never invent a palette from thin air. - **Backfill reconciliation is the user's call.** When the as-built design is inconsistent, you surface the conflicts; the user picks the canonical value. Don't auto-resolve taste. - **Document-as-is vs redesign is the user's call,** settled in Phase 0. - **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. - **Promote process learnings, not brand facts.** Phase D feeds the global guide; brand facts stay in the repo. ## Field notes *Accreted, field-tested learnings about the process — appended by Phase D as real runs teach us things. Brand facts never go here; only generalizable process/distillation knowledge.* - *(seed, from research 2026-06-16 — confirm on first live run)* Claude Design exports standalone HTML with **inline, hardcoded CSS** — not CSS custom properties or DTCG tokens. Plan for Phase C token extraction to be agent-authored from the values, not a file copy. - *(seed, from research 2026-06-16)* The richest export is the **"Handoff to Claude Code" bundle** — HTML/CSS/JS + per-state screenshots + a README naming the target stack/conventions. Read that README first; it carries implementation intent beyond the visuals. PDF/PPTX/Canva exports are presentation-only and carry no usable style data. - *(seed, from research 2026-06-16)* On input, **point Claude Design at a front-end subdirectory, not the whole monorepo** — large trees choke the codebase scan. It accepts text prompts, image/doc uploads, live-URL web capture, and Figma files. ## Final report Short summary: the on-ramp taken (refine/import/extract/fresh) and posture (document/redesign), the `design/` files written or updated, where the run stands (brief ready for the cloud tool, or contract distilled and committed), any `design-checker` cleanup backlog captured, any Phase-D learning promoted to this guide, and the unmistakable next action. If blocked, say exactly what blocked you — never guess or fabricate a look.