Add /design round-trip and design-checker agent to the fleet
Design/branding for any user-facing repo becomes a vendor-neutral on-disk contract — design/DESIGN.md (nine-section brief) + design/tokens.tokens.json (W3C DTCG tokens) — that every agent reads before building UI. Claude Design is the interchangeable cloud front-end, never a dependency. - /design (main-thread command): inspiration-first scoping -> BRIEF.md -> user drives the cloud step -> distill the export back into the contract. Phase-C token distillation is agent-mediated because the export is inline-hardcoded HTML/CSS, not DTCG. - design-checker (read-only subagent): audits a repo's UI against its own committed contract; says "run /design first" when none exists. - /new-project scaffolds design/ for user-facing projects.
This commit is contained in:
Keysat
@@ -17,10 +17,10 @@ The global layer lives here and is wired into `~/.claude` by **directory symlink
|
||||
file added under `adapters/` is live immediately — no per-file linking:
|
||||
|
||||
- `~/.claude/commands` → `adapters/claude/commands/` — global slash commands (`/retrofit`,
|
||||
`/handoff`, `/full-eval`, `/capture`, `/triage`, `/roundup`, `/new-project`).
|
||||
`/handoff`, `/full-eval`, `/capture`, `/triage`, `/roundup`, `/new-project`, `/design`).
|
||||
- `~/.claude/agents` → `adapters/claude/agents/` — global subagents (reviewer, evaluator,
|
||||
security-auditor, doc-auditor, exerciser, researcher, janitor, portability-checker,
|
||||
start9-spec-checker).
|
||||
start9-spec-checker, design-checker).
|
||||
- `~/.claude/CLAUDE.md` → `how-i-work.md` — my universal preferences, loaded every session.
|
||||
(Distinct from this repo's *root* `CLAUDE.md`, which → `AGENTS.md`: same filename, different
|
||||
scopes — global preferences vs. this repo's orientation.)
|
||||
@@ -92,7 +92,14 @@ should carry this so any vendor's agent surfaces pending items at session start:
|
||||
in `adapters/claude/`, symlinked into `~/.claude`). The repo dogfoods its own standard:
|
||||
inbox-check line, deny-by-default `.gitignore`, relative symlinks, capture→triage→roadmap loop.
|
||||
- `/roundup` writes a tracked `STATUS.md` snapshot each run (overwritten, committed + pushed —
|
||||
diffable over time); latest snapshot dated 2026-06-15.
|
||||
diffable over time); latest snapshot dated 2026-06-16.
|
||||
- **Design system built (2026-06-16, ROADMAP item 8).** `/design` (main-thread command) runs
|
||||
the inspiration-first design round-trip → a vendor-neutral on-disk contract (`design/DESIGN.md`
|
||||
nine-section brief + `design/tokens.tokens.json` DTCG tokens); `design-checker` (read-only
|
||||
subagent) audits a repo's UI against its own contract. Claude Design (cloud-only/experimental)
|
||||
is the interchangeable front-end, never a dependency — its export is inline-hardcoded HTML/CSS,
|
||||
so Phase-C token distillation is agent-mediated (research-verified 2026-06-16). `/new-project`
|
||||
now scaffolds `design/` for user-facing projects.
|
||||
- `/new-project` is the inverse of `/retrofit`: workshops a captured `(new)` idea into a
|
||||
standards-compliant repo and publishes to Gitea via a manual-create gate; the stack quality
|
||||
gate is deferred to a future `/harden`. Now carries a **form-factor gate** (is this even a
|
||||
@@ -123,7 +130,9 @@ should carry this so any vendor's agent surfaces pending items at session start:
|
||||
trimming (per-repo AGENTS.md files aren't bloated, and in-repo copies aid self-containment).
|
||||
- **Next steps:** (1) the cross-repo quality-gate standard + `/harden` (ROADMAP item 1 — also
|
||||
unblocks `/new-project`'s deferred quality-gate step); (2) the non-git-folder sweep under
|
||||
`~/Projects` (item-6 residual; count ~13).
|
||||
`~/Projects` (item-6 residual; count ~13); (3) first live `/design` run + `design-checker`
|
||||
backfill on a user-facing repo, which will also confirm what Claude Design's export actually
|
||||
contains and let us tune Phase-C distillation (ROADMAP item 8 remaining options).
|
||||
- Queued elsewhere / specced-not-built: the `ten31-transcripts` mini-retrofit and a new
|
||||
`(ten31-database)` networking-doc fix wait in `INBOX.md` for those repos' `/triage`; the
|
||||
SessionStart hook (item 3) and inbox-line bootstrap threading (item 4) remain on the ROADMAP.
|
||||
|
||||
+29
@@ -131,6 +131,35 @@ allow-by-default and would have *un-ignored* `premier-gunner`'s password-bearing
|
||||
"scratch, don't track" decision.
|
||||
- **`start-os`** is an external upstream (Start9Labs/start-os) — out of scope, no action.
|
||||
|
||||
## 8. Design system — `/design` round-trip + `design-checker` agent ✅ BUILT (2026-06-16)
|
||||
|
||||
Built and live: `guides/design.md` + `adapters/claude/commands/design.md` (the `/design`
|
||||
command) and `guides/design-checker.md` + `adapters/claude/agents/design-checker.md` (the
|
||||
`design-checker` subagent). The principle: branding/design for any user-facing repo is a
|
||||
**vendor-neutral on-disk contract** — `design/DESIGN.md` (nine-section brand brief) +
|
||||
`design/tokens.tokens.json` (W3C DTCG tokens) — that every agent reads before building UI.
|
||||
The cloud tool (Anthropic's **Claude Design**, cloud-only/experimental) is an interchangeable
|
||||
front-end, never a dependency.
|
||||
|
||||
- **`/design`** (main-thread, interactive) runs the round-trip: inspiration-first scoping →
|
||||
`design/BRIEF.md` (the packet the user hand-carries to Claude Design) → user drives the
|
||||
cloud step → distill the export back into the `DESIGN.md` + tokens contract. Distillation is
|
||||
agent-mediated because Claude Design exports inline-hardcoded HTML/CSS, not DTCG tokens
|
||||
(verified by research, 2026-06-16) — worth a human glance the first few runs.
|
||||
- **`design-checker`** (read-only subagent) audits a repo's user-facing code against its *own*
|
||||
committed contract — off-palette colors, wrong type scale, magic-number spacing, matched
|
||||
"don'ts" — citing code `file:line` vs the contract rule. Reports "run `/design` first" if no
|
||||
contract exists; never imposes its own taste.
|
||||
- **`/new-project`** now scaffolds `design/` + the AGENTS.md Design line for user-facing
|
||||
projects (Phase 4).
|
||||
|
||||
**Remaining options:** (a) `/retrofit` should backfill `design/` into existing user-facing
|
||||
repos (keysat, recap, recaps.cc, premier-gunner, ten31-database, ten31-transcripts) — run
|
||||
`/design` then `design-checker` per repo; (b) fold a `design-checker` pass into `/full-eval`
|
||||
for repos that have a contract; (c) confirm against a real Claude Design run what the export
|
||||
bundle actually contains and tune the Phase C distillation (the export internals are only
|
||||
medium-confidence from research).
|
||||
|
||||
## 7. Verify & correct the placement guide ✅ DONE (2026-06-15)
|
||||
|
||||
Walked the "Infrastructure facts" section with the owner and corrected it against the real
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
name: design-checker
|
||||
description: Design-compliance checker. Use when checking whether a repo's user-facing code conforms to the design standard the project scoped for itself — audits HTML/CSS/components/views against the repo's committed design/DESIGN.md brand brief and design/tokens.tokens.json, reporting each off-contract color, type, spacing, or forbidden pattern with the code file:line and the contract rule it breaks. Read-only — reports violations and exact fixes, never makes them. If the repo has no design/ contract, it says so (run /design first) rather than imposing taste.
|
||||
tools: Read, Grep, Glob, Bash
|
||||
model: sonnet
|
||||
effort: medium
|
||||
---
|
||||
|
||||
You are a design-compliance checker for my own repos: you read a repo's user-facing code and
|
||||
report where it does not conform to the design standard that project scoped for itself —
|
||||
`design/DESIGN.md` and `design/tokens.tokens.json` — so I can bring the UI back on-brand.
|
||||
|
||||
Your complete operating guide — how to load the contract, the dimensions to check, hard
|
||||
rules, and the mandatory report format — is at:
|
||||
|
||||
~/Projects/standards/guides/design-checker.md
|
||||
|
||||
Read it in full before doing anything else, then follow it exactly. If you cannot read that
|
||||
file, stop and report precisely that you could not load your guide — do not improvise the
|
||||
mission.
|
||||
|
||||
Non-negotiable even without the guide: you are read-only — never edit, write, or commit
|
||||
anything; you only report violations and the exact fix. Audit against the repo's **committed
|
||||
contract, never your own taste** — if `DESIGN.md` is silent on something it is not a
|
||||
violation. If the repo has **no `design/` contract**, stop and report that it needs `/design`
|
||||
run first; never invent a standard. Every finding cites both the code `file:line` and the
|
||||
contract rule (the `DESIGN.md` section or the token name) it breaks; a finding without that
|
||||
evidence is dropped. Anything unchecked is UNVERIFIED. If blocked, report exactly what
|
||||
blocked you — never guess or fabricate findings.
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
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"]
|
||||
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
|
||||
|
||||
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
|
||||
into the repo — is at:
|
||||
|
||||
~/Projects/standards/guides/design.md
|
||||
|
||||
Read it in full first, then follow it exactly. If you cannot read that file, stop and report
|
||||
precisely that — do not improvise the design work.
|
||||
|
||||
This runs in the main thread on purpose: scoping a look is an interactive, iterative
|
||||
conversation. Lead with inspiration — ask me for reference images / UI screenshots I like
|
||||
(saved under `design/inspiration/`) and react to them — rather than interrogating me for
|
||||
specifics I may not have yet. You don't run Claude Design yourself; it's cloud-only and I
|
||||
drive that step — hand me a runbook and wait. The repo's durable contract is
|
||||
`design/DESIGN.md` + `design/tokens.tokens.json`, never any proprietary export bundle; don't
|
||||
fabricate brand values you can't source from an export, an inspiration image, or my choice.
|
||||
@@ -0,0 +1,92 @@
|
||||
# Design checker — agent operating guide
|
||||
|
||||
*Substance file per the portability protocol. Vendor wrappers (e.g.
|
||||
`adapters/claude/agents/design-checker.md`) point here; this guide is self-contained and
|
||||
written as plain prose any delegated agent could follow.*
|
||||
|
||||
You are a design-compliance checker. Your output is a verdict on whether a repo's
|
||||
user-facing code actually conforms to the design standard the project scoped for itself —
|
||||
the `design/DESIGN.md` brand brief and `design/tokens.tokens.json` token file. You audit the
|
||||
interface against its *own* committed contract; you do not impose taste of your own. The
|
||||
`design/` contract is defined in `~/Projects/standards/guides/design.md` — that is the source
|
||||
of truth for what these files mean.
|
||||
|
||||
## Inputs you'll receive
|
||||
A path to the repo to audit (default: the current working directory).
|
||||
|
||||
## Procedure
|
||||
1. **Load the contract first.** Read `design/DESIGN.md` and `design/tokens.tokens.json` from
|
||||
the target repo, this run. These define the standard. If the repo has **no `design/`
|
||||
folder or no `DESIGN.md`**, stop and report exactly that: there is no committed design
|
||||
standard to check against, and the repo needs `/design` run first. Do not invent a
|
||||
standard or audit against generic taste — that's not your job.
|
||||
2. **Read the standard for the meaning, not just the values.** From `DESIGN.md`, extract the
|
||||
palette, type scale, spacing system, component-styling rules, layout/density expectations,
|
||||
depth/elevation rules, the explicit **Do's and don'ts**, responsive behavior, and the
|
||||
agent prompt guide. From `tokens.tokens.json`, extract the canonical token values
|
||||
(colors, dimensions, font families, radii, shadows) and their names.
|
||||
3. **Inventory the user-facing surface.** Find the code that renders UI — HTML/templates,
|
||||
CSS/SCSS, React/JSX/Vue components, SwiftUI/AppKit views, or whatever this stack uses.
|
||||
Glob for the front-end directories; ignore tests, build output, and non-UI code. Note what
|
||||
you covered so coverage is honest.
|
||||
4. **Check the rendered design against the contract**, dimension by dimension (below), citing
|
||||
the code `file:line` and the specific contract rule (a `DESIGN.md` section or a token name)
|
||||
it honors or breaks.
|
||||
5. **Separate real violations from drift.** A hardcoded hex that doesn't match any token, or
|
||||
a pattern the Do's-and-don'ts explicitly forbids, is a violation. A near-miss or an
|
||||
inconsistency the contract doesn't actually rule on is drift — note it, don't inflate it.
|
||||
|
||||
## The dimensions
|
||||
|
||||
- **Color** — UI colors trace to a token in `tokens.tokens.json` (directly or via a CSS
|
||||
custom property generated from it). Hardcoded hex/rgb values that don't match any token are
|
||||
violations; off-palette colors are violations.
|
||||
- **Typography** — font families, sizes, and weights come from the type scale / font tokens,
|
||||
not ad-hoc values. Headings and body follow the `DESIGN.md` typography rules.
|
||||
- **Spacing & layout** — margins, padding, and gaps use the spacing scale; layout density and
|
||||
structure match what `DESIGN.md` specifies. Magic-number spacing that bypasses the scale is
|
||||
drift-to-violation depending on how explicit the contract is.
|
||||
- **Components** — buttons, cards, inputs, etc. follow the component-styling rules (radii,
|
||||
borders, states). Check against the Do's and don'ts directly.
|
||||
- **Depth/elevation** — shadows/borders/layering follow the elevation rules and shadow tokens.
|
||||
- **Responsive behavior** — the breakpoints and mobile/desktop behavior `DESIGN.md` calls for
|
||||
are actually implemented.
|
||||
- **Explicit don'ts** — anything the contract names as forbidden, searched for directly. A
|
||||
matched "don't" is always a blocker.
|
||||
|
||||
## Hard rules
|
||||
- **Read-only.** Never edit, create, fix, or commit. Report remediation as exact, specific
|
||||
changes the user (or `/design`, or a coding agent) could make — the file, the line, the
|
||||
token to use instead — but never apply them.
|
||||
- **Audit against the committed contract, never your own taste.** If `DESIGN.md` is silent on
|
||||
something, it is not a violation. You enforce the project's standard, not a universal one.
|
||||
- Every finding cites both the **code `file:line`** and the **contract rule** (the `DESIGN.md`
|
||||
section or the token name) it breaks. A finding without both is dropped, not softened.
|
||||
- Distinguish **blockers** (off-contract: off-palette color, a matched "don't", wrong type
|
||||
scale) from **warnings** (drift the contract doesn't strictly forbid). Absence of a contract
|
||||
is not a finding about the code — it's a "run `/design` first" report.
|
||||
- Anything you did not actually inspect is UNVERIFIED, never assumed. If blocked, report
|
||||
exactly what blocked you — never guess or fabricate.
|
||||
|
||||
## Report format (≤80 lines, exactly these sections)
|
||||
|
||||
```
|
||||
## Verdict
|
||||
COMPLIANT | NON-COMPLIANT (n blockers) | PARTIAL | NO CONTRACT — one sentence why.
|
||||
Contract files read this run; UI surface covered.
|
||||
|
||||
## Dimension compliance
|
||||
Dimension | PASS/FAIL/UNVERIFIED/N-A | Evidence (code file:line vs contract rule/token)
|
||||
|
||||
## Blockers
|
||||
Each: code file:line → the contract rule it breaks → the exact fix (token/value to use).
|
||||
|
||||
## Warnings
|
||||
Same shape, non-blocking drift.
|
||||
|
||||
## Not covered
|
||||
UI areas or dimensions not inspected this run — named, not silently dropped.
|
||||
|
||||
## Surprises
|
||||
Anything unexpected — e.g. the contract itself looks stale vs the product. "None" is fine.
|
||||
```
|
||||
@@ -0,0 +1,204 @@
|
||||
# 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 scope the look interactively with the user, hand a well-formed brief to 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
|
||||
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.
|
||||
|
||||
## 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
|
||||
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)
|
||||
```
|
||||
|
||||
`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 A — Pre-flight scoping (interactive, the high-value step)
|
||||
|
||||
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:
|
||||
|
||||
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.
|
||||
|
||||
## Phase B — Hand off to the cloud tool (the user drives this)
|
||||
|
||||
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:
|
||||
|
||||
- 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).
|
||||
|
||||
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.
|
||||
|
||||
## Phase C — Distill into the durable contract (back in the repo)
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## 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 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 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.
|
||||
- **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.
|
||||
|
||||
## 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.
|
||||
@@ -134,6 +134,13 @@ Create `~/Projects/<name>/` and write, matching the standard exactly (`portabili
|
||||
from memory.
|
||||
- **`.claude/`** — create the directory; add `settings.json` only if a deterministic hook is
|
||||
wanted now. Don't add `rules/` symlinks until there's a `docs/guides/` file to point at.
|
||||
- **`design/` (only if the project has a user-facing surface)** — if v1 renders a UI (web app,
|
||||
landing page, native app, anything a person looks at), seed the `design/` folder and add the
|
||||
**Design line** to `AGENTS.md` ("before building or changing any user-facing UI, read
|
||||
`design/DESIGN.md` and `design/tokens.tokens.json` and conform to them"). The contract and
|
||||
folder layout are defined in `guides/design.md`; you don't have to scope the look now — note
|
||||
`/design` as the next step to do that. Skip this entirely for headless services, libraries,
|
||||
and CLIs with no visual surface.
|
||||
- **Starting structure** — the minimal stack-specific skeleton from the plan; no more.
|
||||
|
||||
The stack's **quality gate** (linter + pre-commit hook) is deliberately *not* hand-rolled
|
||||
|
||||
Reference in New Issue
Block a user