First extract->reconcile run (recap) surfaced generalizable process
learnings: harvest the inventory with grep frequency tables in the main
thread (counts are the reconcile evidence), disambiguate near-duplicates
with frequency plus an external anchor, present conflicts as
recommended-first A/B/C forks with value previews, and treat the code
itself as the inspiration for a document-as-is extract (skip BRIEF and
_imports, write provenance). Also refine the Extract phase to enumerate
every styling surface and read the brand mark before the CSS.
Keep "Claude Design" only as the named default visual tool (like naming
Figma); generalize the spots that assumed the coding harness is Claude:
- Phase B framed as "the cloud tool" (Claude Design as default; adapt for Figma)
- export named the "coding-agent handoff bundle" (Claude Design's term noted)
- token extraction points at Style Dictionary / any harness skill, not Claude Code
- BRIEF prompt block paste target generalized
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