Design system kit

A pipeline, not a menu. Every request goes through the same steps in the same order: find what exists, decide the system, then critique with it. The system comes first, so every critique is a check against a rule instead of a matter of taste.

This skill owns the system: token layers, type, space, radius, elevation, platform sizes, DESIGN.md, governance and the critique against the system. It calls two other skills instead of doing their work:

• color-kit for every color decision: strategy, palette, roles, modes, contrast proof and stack binding.
• ui-ux-kit for every component, state, motion and UX decision, on every platform.

product-polish-workflow audits a shipped product and prototype-wireframe answers one open question with a throwaway. Neither is a step here.

Run all steps. A step can be short (a line or two for a small request), but never skip one silently. If a step does not apply, write Step N: skipped, because ... and move on.

Paths are relative to this folder. Run scripts from specialities/design-system/.

The pipeline

Steps 2 and 3 are the heart of it. Do not critique before Step 2 has produced a system. If the user only asked for a critique, still do Steps 0 to 2 first (the system can be the as-found one, read from their code), and keep them short.

Step 0: Frame

Say in a few lines, and ask only for what is missing, one question at a time with your recommended answer:

• What the product is and who uses it.
• Platforms: mobile, desktop, web, TV, car. Which one leads. Read platforms.
• Region and language (it changes color cautions and layout direction).
• What exists: a repo, a live site, a Stitch project, screenshots, or nothing.
• What the user wants at the end: a system, a critique, a theme, a DESIGN.md, slides, or all of it.

Step 1: Discover

Read what exists. Use every source that applies: code, a website (static extractor and in-browser extractor), a Stitch project, screenshots. Write the as-found sheet. Greenfield means "nothing found", and that is a valid result. See discover.

Step 2: Direction and tokens

1. Choose the non-color ingredients with the user: shape, type voice, motion profile, signature move, density and platform. Use the ingredient library.
2. Load color-kit and run it for the color decisions. It frames the feeling, picks the strategy, builds the palette with this kit's builder, composes the modes, proves the contrast and binds the stack. Share one design/brief.json (see color). Do not state color rules here and do not invent hex values.
3. Build everything in one pass: python3 scripts/theme/theme.py build --from-brief design/brief.json --out design/. It writes light and dark tokens, per-platform overrides, a DESIGN.md, a report and a preview, and exits non-zero on a failed check.
4. If a system already exists and should stay, build from the as-found values instead of re-mixing. If a site is the inspiration, remix from the extraction. Never copy a brand's signature look.

Details: direction, color, motion, DESIGN.md format.

Step 3: Critique

Judge the real screens against the system from Step 2, top-down: purpose and hierarchy, spacing, type, color, shape, states, content, motion, accessibility, and fit for each platform. Every finding names the element and the exact token or value to change. Include what to change in the system itself. See critique and specialities/ui-critique/GUIDE.md.

Step 4: Components and motion

Load ui-ux-kit for each screen or component the system must serve. It specifies states, geometry, motion, UX and platform behavior (including the car and the TV). Record each component here in the system format: variants, sizes, states supported, component tokens that alias semantic tokens, platform mapping and status. See components, motion and the token specs in specialities/design-system/references/ (token-architecture, component-specs, states-and-variants, tailwind-integration).

Step 5: Library and governance

Decide how the system lives: where tokens are the source of truth, how components are built and documented, how changes are tested (visual regression, accessibility linting) and who approves them. See library and governance. Brand slides use the slide tooling in specialities/design-system/ (strategies, layouts, color logic, token validator).

Step 6: Validate

Run every check from validate and handoff and name each with its result. Look at the preview in light and dark at the lead platform's size. A failure sends you back to the step that owns it.

Step 7: Hand off

List the files, how to load them, the first three adoption tasks, the governance note, the assumptions and the rebuild command with the seed. Do not commit.

Rules that hold in every step

1. System first, critique second. No judgment of a screen without a system to judge it by.
2. Use the system that exists. Read the project's tokens, theme and components before proposing values. Keep what works.
3. Every value comes from a scale. Spacing, type, color, radius and motion come from named tokens, not typed ad hoc.
4. Accessibility is built in by the owners. Contrast comes from color-kit and is checked by the builder in both modes. Targets, states and gestures come from ui-ux-kit. This skill records the result and runs the gates.
5. Each platform is its own input and distance. Tokens are shared. Sizes, focus, motion and layout are set per platform.
6. Be specific and distinct. Mix ingredients to fit the brief. Do not start from indigo, Inter and a purple gradient. Pick one signature move.
7. Give exact fixes. Name the element and the value, ordered by impact.
8. Learn from sites, do not clone them. Take mechanics, not a brand's identity.
9. Report what you ran. Every script and check is named with its result.
10. One owner per decision. Color goes to color-kit. Components, motion and UX go to ui-ux-kit. This skill records their output and does not restate their rules. Never invent a hex or a motion time here.

What is in this folder

Bundled helpers, from specialities/design-system/:

Related skills

• color-kit: required at Step 2. Owns palette, roles, modes, contrast proof and stack binding.
• ui-ux-kit: required at Step 4. Owns components, states, motion and UX on every platform.
• challenge-me: stress-test the direction before you build it.
• prototype-wireframe: sketch or prototype a screen before specifying it.
• product-polish-workflow: audit and change a shipped product and run its journey QA. It calls this skill for the system.
• write-plan: turn the adoption plan into tasks.
• verify: prove accessibility or visual claims by running them.
• polyglot-copywriter: clean the prose in DESIGN.md and the report.
• handoff: pause the work and keep the state.

Done when

• Every step ran, or has a one-line reason for being skipped.
• A system exists (built, or read from the code) before any critique was written.
• color-kit ran for the color decisions and ui-ux-kit ran for the components, or each has a reason it was skipped.
• The tokens, DESIGN.md and report exist, and all contrast and platform checks pass.
• Findings name the element and the exact token or value to change.
• Every script that ran is named with its result, and the preview was looked at.