DESIGN.MD imports and pitfalls

[debuggerpk]

Open Design Brands — field report for new design system builds

Provenance: distilled from the importing DESIGN.md package build, verified against the installed daemon (Open Design 0.21.0, release-stable) — from bundle source or by direct experiment, not folklore. Client-agnostic: hand this to any session starting a new brand. The Rexun project itself (brand.json description block, BRAND.md, preview/, colors_and_type.css) is the living reference implementation of every rule below.

---

1. The mental model

The Brands pipeline is one-directional and regeneration-happy:

brand.json (source) ──► od brand finalize <brand-id> ──► system/ (tokens, seed, theme, BRAND-SYSTEM.md)
                                                     ├─► DESIGN.md (derived)
                                                     ├─► guide.md (derived — from BRAND.md if present)
                                                     └─► registered store (user:<name>)

• The engine is not broken when it overwrites your work — it is working as designed. Any file it owns, it rewrites. Design around that, never against it.
• Downstream agents (new projects, future sessions) never see brand.json. They see only the rendered store body — brandToDesignMd(brand). A fact that isn't in the rendered output does not exist for them.

2. What the engine owns vs. what you own

Engine-owned — rewritten on every finalize, never hand-edit: DESIGN.md, guide.md, system/seed.json, system/variables*.css, system/tokens.*.json, system/theme.json, system/BRAND-SYSTEM.md, system/artifacts/*, the store body.

You-owned — finalize never touches: brand.json (it derives from this), BRAND.md (authored record; the engine reads it when regenerating guide.md — the pipeline's only authored preference), preview/*, ui_kits/*, colors_and_type.css, plans/READMEs.

3. What the system overrides (the wipe list — all verified)

Attempt	Result
Unknown top-level keys in brand.json (e.g. a tokens mirror)	Dropped — the schema round-trip keeps known keys only
Unknown keys inside seed	Dropped — SEED_FIELD_TYPES whitelists exactly 20 antd fields (colorPrimary…motion); proven with a probe key
Non-canonical colors[] roles (primitive, state rows)	Filtered on write-back — only the 7 canonical roles survive (background, surface, foreground, muted, border, accent, accent-secondary)
Hand-edits to DESIGN.md	Wiped on next finalize, by design
Composer/post-processing scripts for DESIGN.md	"Work" exactly once, then the doc regresses on the next finalize. Banned pattern.

The one slot everyone assumes is an escape hatch — brand.json.seed — is not. BRAND-SYSTEM.md calls it "persistent overrides"; that's true only for the 20 whitelisted antd fields.

4. The sanctioned carriers (survive finalize and reach downstream)

1. brand.json.description — the load-bearing channel. The parser passes it through verbatim (isStr(o.description) ? o.description : "" — no trim, no newline collapsing, no length cap) and the generator renders it as markdown at the top of the body, before the five derived sections. This carries the rule sections (Context / Components / Motion / Anti-patterns) and the full token architecture (## Token scales: color architecture table, spacing, radius/icons/controls, type scale, elevation, opacity ramp).
2. typography[].notes — rendered verbatim per font slot (weights, mono + tabular-nums rules).
3. layout.postureRules — rendered as posture lines (radius, card-first, runtime axes, rem rule).
4. seed — the 20 antd fields only; the sanctioned home for engine-level re-theme values (primary color, radii, fonts). This is why re-themes are durable.
5. colors[] — keep exactly 7 canonical roles; scales/architecture do not go here (filtered), they go in description.

Rule of thumb: if knowledge must survive finalize and reach another session, it must sit inside one of these five carriers. Anything else is session memory and evaporates.

5. Hidden limitations & the Claude Design alignment

• brandToDesignMd(brand) hardcodes exactly five ## sections (Color Palette, Typography, Voice & Tone, Imagery, Layout). No brand field except description can add a heading.
• The package audit (tools connectors design-system-package-audit --path .) runs validateDesignRules, which requires ## -level headings matching eight groups — context/product, color/palette, typography/type, spacing/layout, component, motion/interaction, voice/brand, anti-pattern (substring, lowercase; ### doesn't count) — plus an 800-byte floor. Out of the box the generator cannot emit four of those headings. The audit's own code calls this a "Claude Design-style package" check: it expects a rich authored rules document, while the extractor emits a thin spec. That mismatch is engine-internal; authoring the four rule sections into description is the sanctioned bridge. Every new brand hits this — plan for it.
• finalize itself re-registers the store. Don't build separate store-push machinery — a hand-rolled push fails with WORKSPACE_CONTEXT_REQUIRED; finalize already carries the authority.
• The registered store (user:<name>) is exactly one markdown file. No CSS, no component files, no assets travel with a design system. A new project that gets "only the system" gets a specification, not a kit — components get rebuilt from spec, not picked. To make picking literal: seed the new project's Design Files with the token sheet + preview cards, or attach the repo as a linked code folder.

6. Pitfalls (so you don't repeat them)

1. Fighting the engine with post-processing. Composing authored sections into DESIGN.md after finalize regresses silently. DESIGN.md is derived output, always.
2. Assuming seed passes anything through. Tested: unknown keys vanish; only 20 fields survive.
3. Trusting a top-level brand.json mirror. 286 declarations of token architecture wiped in one finalize.
4. Hallucinated replicas. Three preview cards drifted from source: timeline connectors colored by their own step instead of look-ahead, progress cycle/floater wrong, and a whole "menu" card inventing a dropdown that doesn't exist (the real component is a responsive nav shell). Rule: build every replica by reading the component's full source first — all sub-files, all states (row.svelte hid a 151-line subsystem) — and prefer the live app over stories (stories referenced icon names absent from the icon registry).
5. Specimens without a reading. Variable-width encodings must demonstrate what they're for ("how many are in danger?") with realistic summed values; ship the bare variant first if that's the usage default, labeled variant second.
6. Toggle-less showcase pages. Every page showcasing components/tokens/layouts carries working theme + density toggles — no exceptions. Standard widget: fixed pill, Light/Dark → color-scheme on <html>, Comfortable/Dense → data-density, localStorage applied pre-paint, tokens remap at :root, zero per-component dark logic. Insert idempotently with a marker comment; files-with-marker must equal files-in-scope (43/43 in the Rexun case).
7. A text-index catalog as the front door. Comprehensive replica cards behind a list of links reads as a dismissal of the work. The catalog is a visual gallery — live mini-specimen per component, family-grouped, every link resolving.
8. px creep. Even when repo source itself writes 2px, express 0.125rem. All CSS values in rem; semantic aliases only; raw hex never leaves :root.
9. Size discipline. Replica cards stay under ~200 lines each.

7. The playbook for a new client design system

1. Extract the client's DESIGN.md/tokens into brand.json — canonical fields only (description, colors[] ×7, typography + notes, layout + postureRules, seed ≤ 20 antd fields).
2. Author description immediately as the complete markdown spec: the four audit-required rule sections (Context, Components, Motion, Anti-patterns) + ## Token scales with the full architecture (color architecture table, spacing, radius/icons/controls, type scale with line-heights, elevation, opacity ramp). This one field is what makes the system un-mistakeable downstream.
3. od brand finalize <brand-id> — DESIGN.md, guide.md, system/, store all derive.
4. Verify the derivation — rg the derived DESIGN.md for every authored heading; spot-diff derived tables against the source token sheet (zero drift).
5. Audit — tools connectors design-system-package-audit --path . with fail-on-warnings; must be ok:true, 0 errors, 0 warnings. Re-run after every mutation.
6. Replicate components from source — one preview card per component (preview/components-<family>-<name>.html), built from full component source, repo-exact tokens/geometry/a11y, <200 lines, rem everywhere, registry icons only.
7. Insert the runtime-axes widget on every showcase page; verify the marker count.
8. Rebuild the catalog as a visual gallery — live specimen per component, family-grouped, honest stats, all links resolving.
9. When the system "goes back," the answer is always: change brand.json (or BRAND.md), re-finalize — never edit derived files.

8. Known gaps — stop re-litigating these

• No schema passthrough for arbitrary brand.json keys (upstream ask filed, showcase-plan.md Feat/support star us #5). Until then: description.
• colors[] role whitelist blocks primitive/state rows. Until then: color architecture table in description.
• Audit vs. generator mismatch on required headings. Until then: rule sections in description.
• Store carries one markdown file — no component kit travels with a system. Until then: seed new projects with files manually.
• Stories can lie; component source and the live app are the truth.