grant/standards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add existing-repo on-ramp and Phase-D learning loop to /design

Browse Source 
- Phase 0 routes a run by situation: refine / import prior guidelines
  (Case A) / extract the de-facto design from organic UI (Case B) / fresh,
  plus a document-as-is vs redesign posture. Lets /design backfill repos
  that grew a look organically, not just scope new ones.
- Phase D promotes generalizable PROCESS learnings back into this guide —
  harvested from both the pre-flight scoping conversation and the Phase-C
  distillation — with a Field notes section that accretes them. Brand facts
  stay in the repo's DESIGN.md; process knowledge improves the global standard.
- Seed Field notes with research-verified Claude Design export facts.
This commit is contained in:
Keysat
2026-06-16 10:48:03 -05:00
parent bb27e4c32a
commit 7f3b007e1a
2 changed files with 153 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files
adapters/claude/commands/design.md
+5 -4
View File
@@ -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) 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 "settings screen"] argument-hint: [optional: the surface to design, e.g. "landing page", or "backfill"]
allowed-tools: Bash, Read, Edit, Write, Grep, Glob, Agent allowed-tools: Bash, Read, Edit, Write, Grep, Glob, Agent
--- ---
Run the design round-trip for this repo's user-facing interface. Run the design round-trip for this repo's user-facing interface — a fresh design, or
Optional surface from me (may be empty): $ARGUMENTS 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 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 scoping conversation, the cloud-tool hand-off runbook, and how to distill the result back
guides/design.md
+148 -85
View File
@@ -7,20 +7,21 @@ definition of the `design/` folder convention that `/new-project` scaffolds and
`design-checker` agent audits against — both point here.* `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 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, 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 but Figma or a plain conversation feed the same contract), and distill the result into a
into a small set of **durable, vendor-neutral, on-disk design artifacts** that every future small set of **durable, vendor-neutral, on-disk design artifacts** that every future agent
agent reads before building UI. You run in the **main thread** — scoping a look is an 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 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. 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 The arc: **read the situation → establish the design intent → (optionally) round-trip
result into the repo.** The principle underneath: the cloud tool is an interchangeable through the cloud tool → distill into the repo → promote what you learned.** The principle
front-end; what lives in the repo is a `DESIGN.md` brand brief plus a `tokens.tokens.json` underneath: the cloud tool is an interchangeable front-end; what lives in the repo is a
token file, and *those two files are the contract*. Never let the repo depend on a `DESIGN.md` brand brief plus a `tokens.tokens.json` token file, and *those two files are the
proprietary export format — if Claude Design vanished tomorrow, the on-disk contract and contract*. Never let the repo depend on a proprietary export format — if Claude Design
everything that reads it must still stand. vanished tomorrow, the on-disk contract and everything that reads it must still stand.
## Posture (how to run the conversation) ## Posture (how to run the conversation)
@@ -42,12 +43,12 @@ create and maintain (folder name is `design/`, not `brand/`):
``` ```
design/ 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 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 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) 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 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) _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 `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:** before building or changing any user-facing UI, read `design/DESIGN.md` and
> `design/tokens.tokens.json` and conform to them. > `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 Before anything, determine which of four situations you're in — it sets the whole run:
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 - **Refine** — `design/DESIGN.md` already exists. You're updating an existing contract; skip
like; save them under `design/inspiration/` (or have the user drop them there). Treat each to the phase that fits the change.
as a first-class input — these get uploaded to the cloud tool later. For each, capture in - **Import (Case A)** — no contract, but the repo (or the user) has **prior design/branding
one line *what* the user likes about it, so the aesthetic intent survives as text, not just guidelines** in some ad-hoc form (a doc, an HTML brand page, a Claude Design export). Go to
pixels. Phase A → *Import*.
2. **Draft the brief** in the five-part structure the cloud tool responds to (this is the - **Extract (Case B)** — no contract and no guidelines, but there's an **existing user-facing
documented Claude Design prompt shape): **Goal** (what this screen/app is and the one job UI** whose look grew organically. Go to Phase A → *Extract*.
it does), **Layout** (structure, density, mobile-first or not), **Content** (the actual - **Fresh** — no contract and no UI yet (a new or pre-UI project). Go to Phase A → *Fresh*.
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) 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 ## Phase A — Establish the design intent
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 Pick the branch from Phase 0. All three converge on Phase C (the contract).
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 **Fresh — inspiration-first scoping → `design/BRIEF.md`.**
C distillation applies to whatever visual artifact they bring back. 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/<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.
Turn the raw export into the vendor-neutral contract. **This step is agent-mediated, not a **Extract (Case B) — inventory → reconcile → (then formalize in Phase C).**
mechanical export** — Claude Design emits standalone HTML with *inline, hardcoded* CSS (no 1. **Inventory the as-built design.** Read the user-facing code and produce a *descriptive*
CSS custom properties, no DTCG tokens), so you read the values out of the export and the record of what the design currently is: every color used, type styles, spacing patterns,
screenshots and author the contract yourself. Worth a human glance the first few runs. 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/<date>/`. ## Phase B — (Optional) cloud round-trip
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**, Run this only for **fresh** designs that need the visual tool, or **redesign/elevate**
**Component styling**, **Layout**, **Depth/elevation**, **Do's and don'ts**, **Responsive backfills. Document-as-is backfills skip it. You cannot run Claude Design — it is cloud-only
behavior**, **Agent prompt guide** (a short "when building UI here, do X" note to future at `claude.ai/design`, browser-driven, and the user does this step. Hand them a runbook:
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` - What to **paste** (the prompt block from `BRIEF.md`) and **upload/point at** (the checklist).
and `$value`; groups nest; references use `{group.token}`). Pull colors, type scale, - How to **iterate**: inline canvas comments, direct edits, sliders/toggles — not just
spacing, radii, and shadows out of the export's CSS. If helpful, the standalone Claude Code re-prompting.
`design-tokens-skill` can assist with token extraction — optional, not required. - What to **export**: the **"Handoff to Claude Code" bundle** (richest — HTML/CSS/JS +
4. **Populate `design/brand/`** — logo, fonts, and (optionally) a `palette.css` of CSS custom per-state screenshots + a README of stack/conventions) and a few **screenshots**. PDF/PPTX/
properties generated from the tokens via Style Dictionary, so the running app has a real Canva are presentation-only — skip them. Drop the bundle into `design/_imports/<date>/`.
stylesheet to consume.
5. **Wire the contract in.** Ensure the `AGENTS.md` **Design line** (above) is present; add it If the user used Figma or just talked through the look, that's fine — the same Phase C applies.
if missing.
6. **Commit** the `design/` folder. From here, every agent that touches UI reads the contract, ## Phase C — Distill into the durable contract
and `design-checker` can audit code against it.
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. 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 ## The `BRIEF.md` skeleton
@@ -147,7 +194,6 @@ screenshots and author the contract yourself. Worth a human glance the first few
## Reference pattern (inspiration) ## Reference pattern (inspiration)
- inspiration/<file> — <what the user likes about it> - inspiration/<file> — <what the user likes about it>
- ...
## Brand description (~200 words) ## Brand description (~200 words)
<voice, mood, what it is NOT> <voice, mood, what it is NOT>
@@ -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 - **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 repo must stay readable and buildable if the cloud tool disappears. The bundle is provenance
in `_imports/`, not a dependency. in `_imports/`, not a dependency.
- **Don't fabricate brand values.** Every color, size, and rule in the contract traces to the - **Don't fabricate brand values.** Every color, size, and rule traces to an export, an
export, an inspiration image, or an explicit user choice — if you can't source it, ask, or inspiration image, prior guidelines, the as-built code, or an explicit user choice — if you
mark it as a placeholder to confirm. Never invent a palette from thin air. 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 - **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. claim to have generated or exported anything you didn't.
- **Keep `inspiration/` and `_imports/` in git.** They are the durable record of intent and - **Keep `inspiration/` and `_imports/` in git.** They are the durable record of intent and
origin. Never commit secrets; assets only. origin. Never commit secrets; assets only.
- **Inspiration-first, iterative.** The user may not know the look up front. Draw it out with - **Promote process learnings, not brand facts.** Phase D feeds the global guide; brand facts
references and drafts; don't force specificity before it exists. stay in the repo.
- **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. ## 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 ## Final report
Short summary: which phase you took the user through, the `design/` files written or updated, Short summary: the on-ramp taken (refine/import/extract/fresh) and posture (document/redesign),
where the brief stands (ready to take to the cloud tool, or distilled and committed), and the the `design/` files written or updated, where the run stands (brief ready for the cloud tool, or
unmistakable next action — "paste `BRIEF.md` into claude.ai/design and bring back the bundle," contract distilled and committed), any `design-checker` cleanup backlog captured, any Phase-D
or "contract committed; run `design-checker` to audit the existing UI." If blocked, say learning promoted to this guide, and the unmistakable next action. If blocked, say exactly what
exactly what blocked you — never guess or fabricate a look. blocked you — never guess or fabricate a look.