First real /design run (keysat import, document-as-is). Generalizable
process learnings, per the Phase-D loop:
- implemented CSS/tokens are authoritative over prose when they disagree
- real type scales/shadows resist strict DTCG — keep as documented strings
- encode stated intent even where code violates it; the gap is the backlog
- "each surface inlines its own tokens" is a recurring drift risk; grep
before relocating a design dir into _imports
- 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.
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.
Keysat