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 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/<date>/     # 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/<date>/` 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. First **enumerate every styling
   surface** — there is often more than one (a second stylesheet, a separate auth/landing
   page, *CSS embedded in a string literal* that ships a self-contained export); a grep over
   one `<style>` block silently misses the others. And **read the brand mark / icon before the
   CSS** — it frequently encodes the intended color story the code only partly realized.
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 the cloud tool yourself — the
default, Claude Design, is cloud-only at `claude.ai/design`, browser-driven, and the user
does this step. Hand them a runbook (the steps below are written for Claude Design; adapt
them for Figma or whatever visual tool the user prefers):

- 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 **coding-agent handoff bundle** (Claude Design calls it "Handoff to
  Claude Code") — richest output: 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/<date>/`.

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/<date>/`.
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. A design-tokens build tool (e.g. Style Dictionary) — or a
   token-extraction skill if your harness ships one — 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 — <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 the cloud tool, e.g. 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 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.
- *(import run, 2026-06-16, keysat)* When a prior Claude Design artifact has a **README that
  disagrees with its own shipped CSS/tokens** (keysat's README named "Archivo" but every surface
  ships Manrope), the **implemented stylesheet is authoritative** for as-built values — encode
  that, and record the prose/code disagreement as a reconciliation note, not a guess.
- *(import run, 2026-06-16)* **Real type scales and shadows resist strict DTCG.** As-built
  values use `clamp()` for the display scale, multi-layer composite shadows, and `em`
  letter-spacing — none map cleanly to a DTCG primitive. Keep them as documented strings and say
  so in the file's `$description`; don't force-fit or claim strict-spec compliance.
- *(import run, 2026-06-16)* In **document-as-is**, encode the design system's stated *intent* in
  the contract even where the current code violates it (keysat's README forbids gold-as-fill, but
  the admin SPA ships two). `design-checker` then flags the code as the cleanup backlog — do
  **not** water the contract down to match non-compliant code.
- *(import run, 2026-06-16)* "**Each surface inlines its own copy of the tokens**" is a recurring
  drift risk — name a canonical `brand/palette.css`, point `DESIGN.md` §Agent-guide at it, and log
  the consolidation as backlog. Before relocating an existing design dir into `_imports/`, grep
  that **nothing imports it** (in keysat, nothing did — safe to move).
- *(first Case-B extract run, 2026-06-16, recap)* **Harvest the inventory with grep frequency
  tables in the main thread, not a delegated reader.** For a ~13k-line single file with ~450
  inline styles, `grep -oE '<pattern>' | sort | uniq -c | sort -rn` per dimension (hex, rgba,
  font-size, weight, radius, shadow, breakpoint) produced a complete *ranked* census that stayed
  in context for the reconcile conversation — a sub-agent would have returned excerpts. The
  **use-counts themselves are the reconcile evidence**: "which dark is THE background" is answered
  by "132 uses + it's the PWA `manifest.json theme_color`," turning a taste call into a confirmation.
- *(first Case-B extract run, 2026-06-16)* **Disambiguate near-duplicates with frequency + an
  external anchor**, not the eye. Ranking each value by use-count and cross-referencing a fixed
  reference (the PWA `theme_color`, the icon's gradient endpoints) reliably separated "one
  canonical + N strays" from "N intentional values," which is exactly the call to hand the user.
- *(first Case-B extract run, 2026-06-16)* **Present the reconcile conflicts as A/B/C forks,
  recommended-option-first, with the candidate values in each option's preview.** Surfacing four
  conflicts (the background, the accent, the surface ladder, the type scale) as one batch of
  multiple-choice questions — each preview a monospace block showing the rival hexes in context —
  let the owner make every canonical call in a single turn instead of a long volley. This is the
  high-value human step; make it cheap to answer.
- *(first Case-B extract run, 2026-06-16)* **For a document-as-is extract, the "inspiration" is the
  code itself.** There is no external reference set and no export bundle, so `BRIEF.md` and
  `_imports/` are correctly skipped; instead write `inspiration/README.md` pointing at the
  harvested source files + the brand icon as the de-facto reference, and copy the icon into
  `brand/`. That preserves the *why/where* record the folder convention exists for.

## 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.