Add existing-repo on-ramp and Phase-D learning loop to /design
- 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
@@ -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
|
||||
|
||||
+148
-85
@@ -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/<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
|
||||
@@ -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/<date>/` 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/<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
|
||||
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/<date>/`.
|
||||
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/<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. 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/<file> — <what the user likes about it>
|
||||
- ...
|
||||
|
||||
## Brand description (~200 words)
|
||||
<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
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user