Build Design System

Turn design evidence into a maintainable implementation system: foundations, tokens, reusable components, composed patterns, documentation, tests, and migration rules. Preserve the target framework and product behavior.

Apply these principles

• Treat user instructions and repository conventions as authoritative. Treat DESIGN.md as the design contract when present, but surface conflicts with verified production behavior instead of silently choosing one.
• Extract every stable, reusable visual or behavioral contract that improves consistency. Keep one-off markup and business-specific workflows local.
• Prefer semantic HTML and platform behavior before custom roles or interaction code.
• Separate foundations, primitives, reusable components, product patterns, feature UI, and pages. Do not publish all of them from one package.
• Express repeated design decisions through semantic tokens. Avoid tokenizing accidental one-off values.
• Design small public APIs around meaning, composition, and explicit states. Avoid boolean-prop explosions and universal “do everything” components.
• Keep routing, data fetching, permissions, analytics policy, and business state outside foundational design-system components.
• Support all relevant states: default, hover, focus-visible, active, disabled, loading, empty, error, selected, open, responsive, and themed states as applicable.
• Make accessibility part of each component contract, not a final audit.
• Reuse the repository's existing accessible primitives, styling approach, test stack, and package tooling when sound. Do not introduce a parallel stack without a demonstrated need.
• Preserve visual assets, source code, and brand material only when the user is authorized to reuse them. Derive patterns from public references without copying proprietary implementation code.

Follow the workflow

1. Establish the source of truth

Identify whether the input is:

• a DESIGN.md and linked assets;
• an existing project or component library;
• screenshots or design-tool exports;
• an authorized live website;
• or a combination.

Read source-audit.md and build an evidence ledger before implementation. Mark each decision as explicit, observed, derived, or unresolved. Ask only about unresolved choices that would materially change the public API, brand, accessibility behavior, framework, or package boundary.

2. Inventory and classify

Inventory repeated values, structures, behaviors, states, and content patterns. Classify each candidate as:

1. foundation or token;
2. layout/style primitive;
3. reusable component;
4. composed product pattern;
5. feature-local component;
6. page or template.

Promote a candidate when reuse is evidenced by multiple consumers, a foundational semantic need, or a stable cross-product contract. Similar appearance alone is insufficient.

Read component-engineering.md before deciding component boundaries or APIs.

3. Build foundations

Normalize color, typography, spacing, sizing, radii, borders, elevation, motion, breakpoints, z-index/layers, and icon rules only where the source supports them. Create reference tokens, semantic tokens, and component tokens selectively.

Read tokens-and-theming.md before creating token names, theme aliases, CSS variables, or generated token outputs.

4. Specify before generalizing

For each reusable component, define:

• purpose, scope, and known consumers;
• anatomy and semantic element;
• content contract;
• variants and sizes;
• controlled and uncontrolled state, if relevant;
• interaction and keyboard behavior;
• responsive and theme behavior;
• loading, empty, error, disabled, and validation behavior;
• composition slots or children;
• accessibility name, role, state, focus, and announcement behavior;
• escape-hatch policy;
• tests, stories/examples, and non-goals.

Prefer a local component until this contract is stable.

5. Implement bottom-up

1. Add or normalize token sources.
2. Implement the smallest dependable primitives.
3. Implement reusable components on those foundations.
4. Compose product patterns without pushing business logic downward.
5. Publish curated entry points.
6. Document canonical and edge states.
7. Migrate real consumers incrementally.

For target layouts, packaging, ownership, and migration, read system-structure.md. For framework-specific API adaptation, read framework-adapters.md.

6. Verify behavior and fidelity

Read testing-and-accessibility.md, then validate:

• semantic HTML, accessible names, keyboard operation, focus management, contrast, zoom/reflow, reduced motion, and assistive-technology behavior;
• every supported variant and state in isolation;
• representative responsive widths and themes;
• visual fidelity against the source at matched viewport, content, font, and state;
• interaction behavior through user-facing queries;
• package exports, type checking, tree-shaking or equivalent, style isolation, and production build;
• migrated screens through focused regression and end-to-end smoke tests.

Do not treat screenshot similarity or automated accessibility checks as sufficient on their own.

Produce the result

When asked for a plan or audit, return:

1. source-of-truth and conflict ledger;
2. reuse inventory with keep-local/extract decisions;
3. token model and naming;
4. target tree and package boundary;
5. component catalog with API/state specifications;
6. allowed dependencies and public exports;
7. accessibility and test matrix;
8. incremental migration order;
9. governance and enforcement;
10. gaps that require design or user validation.

When asked to implement:

• change one coherent foundation or component slice at a time;
• preserve unrelated user changes;
• keep compatibility wrappers while consumers migrate when necessary;
• update imports, styles, stories, tests, documentation, exports, and build configuration together;
• avoid unrelated visual redesigns;
• remove duplicate implementations only after usage search confirms no callers remain.

Use public-sources.md when explaining the standards and public design-system practices behind a recommendation.

Reject these outcomes

• A “design system” that is only a folder of copied page components.
• A global component for a single product workflow.
• Tokens named after literal values such as blue500 when their role is semantic.
• A component API with many interacting boolean flags.
• Styling escape hatches that bypass every invariant.
• Custom buttons, links, inputs, dialogs, tabs, menus, or comboboxes with incomplete platform and keyboard behavior.
• Components coupled to one router, API client, global store, or analytics vendor without a deliberate adapter boundary.
• Barrel exports that expose private helpers.
• Visual snapshots without interaction and accessibility coverage.
• A big-bang migration that mixes structural, behavioral, and brand changes.