Two process learnings: render hue/shade reconcile candidates as pixels
(Chrome headless screenshot of an in-context vignette) rather than relying
on hex/monospace previews; and how to absorb one owner-driven accent in a
document-as-is extract (single canonical hue, distinguish overlap by
treatment not a second color, surface the collision before picking).
Three process learnings from the 2026-06-19 Ten31 mobile round-trip:
- Output read via the DesignSync MCP is a multi-file app on Claude Design's
own template runtime using CSS custom properties (incl. a dark/light
switch) — qualifies the seed note about "inline hardcoded CSS" (that's the
export-bundle path, not the MCP project-read path). Read the shell first,
then each sub-app's --var block + DCLogic for derived-field formulas.
- DesignSync reads into context only (no bulk download / no screenshots):
byte-capture the representative source + a manifest README; use
`jq -r .content` on the harness-persisted result for large files.
- A redesign can return more scope than the brief asked for (a light theme);
record it but write scope-expanding additions as proposed-not-canonical
pending an explicit owner decision, surfaced as an A/B reconcile question.
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