diff --git a/adapters/claude/commands/design.md b/adapters/claude/commands/design.md index cabe42b..b564c08 100644 --- a/adapters/claude/commands/design.md +++ b/adapters/claude/commands/design.md @@ -1,11 +1,12 @@ --- -description: Design round-trip — scope a look interactively (inspiration-first), hand a well-formed brief to Claude Design in the cloud, then distill the result into the repo's durable design/ contract (DESIGN.md + DTCG tokens) -argument-hint: [optional: the surface to design, e.g. "landing page" or "settings screen"] +description: Design round-trip — establish a look (scope fresh inspiration-first, import prior guidelines, or extract the de-facto design from existing code), optionally round-trip through Claude Design in the cloud, then distill the result into the repo's durable design/ contract (DESIGN.md + DTCG tokens) +argument-hint: [optional: the surface to design, e.g. "landing page", or "backfill"] allowed-tools: Bash, Read, Edit, Write, Grep, Glob, Agent --- -Run the design round-trip for this repo's user-facing interface. -Optional surface from me (may be empty): $ARGUMENTS +Run the design round-trip for this repo's user-facing interface — a fresh design, or +backfilling an existing repo by importing prior guidelines or extracting its as-built look. +Optional surface/mode from me (may be empty): $ARGUMENTS Your complete orchestration guide — the `design/` folder contract, the inspiration-first scoping conversation, the cloud-tool hand-off runbook, and how to distill the result back diff --git a/guides/design.md b/guides/design.md index 29ba693..f0c2130 100644 --- a/guides/design.md +++ b/guides/design.md @@ -7,20 +7,21 @@ definition of the `design/` folder convention that `/new-project` scaffolds and `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 +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), 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 +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: **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. +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) @@ -42,12 +43,12 @@ create and maintain (folder name is `design/`, not `brand/`): ``` design/ - BRIEF.md # pre-flight: the scoped input packet handed to the cloud tool + 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 from the cloud tool, dated (kept in git for provenance) + _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 @@ -58,75 +59,121 @@ the look is what it is, and the raw imports record *where* it came from. And the > **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) +## Phase 0 — Read the situation, pick the on-ramp -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: +Before anything, determine which of four situations you're in — it sets the whole run: -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. +- **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*. -## Phase B — Hand off to the cloud tool (the user drives this) +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. -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: +## Phase A — Establish the design intent -- 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). +Pick the branch from Phase 0. All three converge on Phase C (the contract). -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. +**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**. -## Phase C — Distill into the durable contract (back in the repo) +**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. -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. +**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. -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. +## 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 @@ -147,7 +194,6 @@ screenshots and author the contract yourself. Worth a human glance the first few ## Reference pattern (inspiration) - inspiration/ — -- ... ## Brand description (~200 words) @@ -183,22 +229,39 @@ screenshots and author the contract yourself. Worth a human glance the first few - **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. +- **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. -- **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. +- **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: 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. +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.