Frontend

Design System Export Skill — building satellite products from a composed design system

---

name: design-system-export description: > Use this skill whenever a STANDALONE product surface is built from an existing project's design system — an embeddable player/widget, a docs or blog page, a static site, a portal, a share card: anything that ships the project's look OUTSIDE the main app shell. Triggers: "reuse our components in", "extract the CSS for", "standalone page", "embed", "make it match the app". It exists because the naive approach — copy the classes you think you need into a hand-rolled page — reliably fails in a specific, expensive way.

The failure this prevents (lived, twice-priced)

A mature design system's CSS is composed, not atomic. Classes assume their ancestor context: surface-tier backgrounds set on parents, generic flow rules keyed to a host wrapper (.panel > *-style), cumulative gutter/inset sums, root-derived scale variables. Copy a class without its host chain and it renders wrong — and because ONE structural mismatch surfaces as dozens of visual symptoms, the builder "fixes" them one by one as styling patches. Hours later the surface is a fork of the design system that still doesn't match.

Failure pattern: STRIPPED-SHELL-HOST-MISMATCH (see FAILURE-PATTERNS.md). The mismatch count is the DOM distance from the real host. Patching styles treats the symptom N times; fixing the host treats the cause once.

The three laws

1. HOST-FIRST — the unit of reuse is HOST CHAIN + HELPERS + CLASSES

Never classes alone. A satellite mounts its components inside a REAL host structure from the app — the same wrapper DOM the app builds, constructed by the SAME JS builder functions. If the satellite shows a slider, it ships the app's slider module and calls its factory; a hand-built lookalike is a hand-roll across a repo boundary (HELPER-HAND-ROLL). If no real host fits the satellite's shape, that is a DESIGN decision for the operator — not a license to approximate.

Corollary — patches go UPSTREAM: a defect found in a satellite is fixed in the app source, then the satellite regenerates. A satellite never patches its copied CSS/JS (a patched copy is a fork that rots — the curated-copy failure).

2. Extraction is GENERATED, never hand-curated

The satellite's CSS/JS subset is produced by an extractor script that:

1. walks the satellite's rendered DOM on the live dev environment and collects every class actually in use;
2. pulls each class's rules plus every ancestor-context rule that can match it (descendant/child selectors whose right side matches — the part hand-curation always misses);
3. ships the full design-token block verbatim — tokens are never subsetted or forked; skinning = swapping token VALUES (a theme file), never editing extracted rules;
4. emits an extraction manifest (classes, rules, source hashes) so the next regenerate is a reviewable diff.

3. Acceptance = MEASURED PARITY (the two-mismatch tripwire)

Before ANY styling patch on a satellite:

• Render the same component in the APP and in the SATELLITE; getBoundingClientRect() both; compare per element. Geometry is measured on the live render, never derived from CSS source (LAYOUT-DERIVED-NOT-MEASURED).
• Two-mismatch rule: ≥2 geometry mismatches on ONE component = a HOST problem. STOP patching styles. Fix the host chain, re-measure. This is the tripwire that converts a 3-hour grind into a 10-minute host fix.
• End every satellite verification with a screenshot a human (or the coordinator) actually looks at.

Mechanics

• design/satellite-manifest.json (path configurable) registers every satellite surface file. It is the isolation boundary: app code never imports satellite files; satellites consume app files read-only.
• satellite-gate.js hook (this stack): any commit staging a manifest-listed file requires a Satellite: trailer — parity-measured (<what/how>) or n/a (<why>). Enable via the satellite block in stack.config.json.
• Governance parity: satellite surfaces obey the full design canon of the parent project (no new classes, tokens only, no native UI leaks — whatever the project's rules are, they apply unreduced).
• State + privacy: a satellite embedded on third-party pages runs stateless by default (no localStorage, no telemetry) unless the project's privacy policy explicitly says otherwise.

Lifecycle

1. Charter — one paragraph in an owning spec: what it is, who embeds it, which app components it mounts.
2. Host build — real host + real helpers, inside the main repo, verified at measured parity against the app.
3. Extract — the generator produces the standalone bundle.
4. Publish — bundle to the satellite's home (repo/CDN/pages), provenance and license carried; the main repo stays the single source of truth.
5. Regenerate on drift — upstream changes to consumed classes/helpers re-run the extractor; the extraction-manifest diff is the review surface.

Why satellites at all (the strategy note)

A satellite is the cheapest honest marketing a tool project has: a free, useful, embeddable piece of the real product that trains its future users on the real interface before the product ships. It only works if it IS the real interface — which is exactly what the three laws guarantee.