Design System

Use this skill when the main question is "what shared UI rules should govern this product or product family before we design or refactor individual screens?"

This is the repo's canonical frontend UI-system anchor. It should:

1. classify the system problem,
2. choose the right design-system mode,
3. route neighboring frontend work out early,
4. define a compact system packet another human or agent can execute.

Read references/system-modes.md before choosing an approach. Read references/token-and-governance-checklist.md before changing shared tokens, primitives, or naming rules. Read references/scope-boundaries.md when deciding whether the work belongs here, responsive-design, or web-accessibility. Read references/design-system-packet-template.md before writing the final handoff.

When to use this skill

• Define or refactor a shared design system for a product, product suite, or app + marketing surface
• Set token policy for color, typography, spacing, radius, elevation, motion, and breakpoint scales
• Choose primitive naming rules, contribution boundaries, and reusable visual-language conventions
• Create a coherent system direction for landing pages, dashboards, forms, and component libraries that must feel related
• Turn vague requests like “our UI feels inconsistent” into a system-level direction packet instead of a one-off page redesign
• Review whether a team needs a system decision before component, accessibility, or responsive implementation starts
• Design reusable primitive / slot / variant APIs and extract component families out of ad-hoc UI
• Prepare a design-system handoff for Figma, code tokens, primitives, and downstream frontend work

When not to use this skill

• The main task is viewport adaptation, container-query strategy, overflow, or mobile layout verification → use responsive-design
• The main task is keyboard/focus behavior, WCAG remediation, labels, semantics, contrast, or manual a11y verification → use web-accessibility
• The main task is a broad page or flow critique for hierarchy, CTA clarity, polish, and launch readiness → use web-accessibility
• The task is implementation-only and the system rules are already clear; implement directly instead of reopening system governance

Core idea

A good design system is not a random palette plus a hero-section mock. It is a shared decision layer that defines:

• what stays consistent,
• what may vary by surface,
• which neighboring skill owns the next implementation step,
• and what artifact downstream teams should follow.

Do not let this skill become a catch-all for every frontend concern. System governance stays here; specialist remediation routes out.

Instructions

Step 1: Classify the design-system request before generating examples

Pick one primary mode so the answer stays bounded.

Modes:

• Foundations mode — tokens, scales, naming, motion, density, breakpoint policy
• Cross-surface alignment mode — landing page + dashboard + app-shell consistency, shared hierarchy, shared brand/system language
• Primitive governance mode — when the team needs rules for primitive naming, ownership, contribution boundaries, and promotion from product-local UI into shared primitives
• System handoff mode — package already-decided system rules into a concise artifact for design/dev execution
• System review mode — assess whether inconsistency is really a design-system problem or should route to a neighboring skill

Quick frame:

Design-system request:
- Surface: marketing site + logged-in dashboard
- Primary mode: cross-surface alignment
- System question: shared tokens and hierarchy, separate page-specific layouts
- Likely route-outs: responsive verification to responsive-design, a11y remediation to web-accessibility

Step 2: Define the shared system boundary

Before changing tokens or page direction, decide what the system actually owns.

Keep in design-system when the job is to define:

• token scales and naming rules
• primitive naming and contribution policy
• visual-language principles that should apply across many screens
• breakpoint or density policy that multiple surfaces should inherit
• motion principles and accessibility baseline that many components depend on

Do not keep the work here when the question becomes:

• one page’s layout breakage → responsive-design
• one accessibility failure or remediation plan → web-accessibility
• one broad UX/UI critique → web-accessibility

Step 3: Make the minimum shared decisions first

Do not start by dumping dozens of example tokens.

For each system request, decide these shared layers first:

1. Foundations — color, type, spacing, radius, elevation, motion, density, breakpoints
2. Primitive policy — which primitives exist, how they are named, what is shared vs product-local
3. Surface rules — how landing pages, dashboards, forms, nav, and data-heavy surfaces should differ while staying coherent
4. Accessibility baseline — contrast expectations, focus visibility, reduced-motion posture, semantic expectations
5. Governance — who can add/change tokens or primitives, what must be reviewed, and when work should route to another skill

If a layer is unknown, say so and capture it as an open decision instead of inventing detail.

Step 4: Keep examples subordinate to the rules

Examples are useful only after the shared rules are explicit.

Good example usage:

• show one token naming pattern
• show one page-system contrast between landing and dashboard surfaces
• show one primitive promotion rule
• show one motion baseline or accessibility baseline

Bad example usage:

• dumping a full palette, TS token file, CSS animation sheet, and JSX screen mock before saying what problem the system is solving

Use this rule:

• rules first,
• one or two illustrative examples second,
• handoff packet last.

Step 5: Route neighboring frontend work out early

Mixed requests are normal. Split them explicitly.

Examples:

• if the team asks for button variants, slot structure, and controlled/uncontrolled behavior, define that primitive API here alongside the system naming/tokens
• if the team asks how cards collapse on mobile, keep shared breakpoint policy here but route layout adaptation to responsive-design
• if the team asks whether icon-only buttons meet keyboard/focus/label requirements, keep baseline a11y expectations here but route remediation to web-accessibility
• if the request is “audit this dashboard and tell us what feels off,” route the broad critique to web-accessibility

Do not hide unclear ownership by calling everything “design-system work.”

Step 6: Produce the design-system packet

End with a concise artifact that downstream design/dev work can follow.

Preferred format:

# Design System Packet

## Scope
- Products / surfaces covered:
- Primary mode:
- Shared system goal:

## Foundations
- Color / semantic token rules:
- Typography / spacing / radius / elevation:
- Motion / density / breakpoint policy:

## Primitive policy
- Shared primitives:
- Naming rules:
- What stays product-local:

## Surface guidance
- Landing / marketing:
- Dashboard / app shell:
- Forms / workflows:

## Accessibility baseline
- Contrast / focus / reduced motion / semantics:

## Route-outs
- `responsive-design`:
- `web-accessibility`:

## Open decisions
- ...

If the user asks for a terse answer, keep the same sections but compress them into bullets.

Step 7: Only then add a small illustrative example when needed

Use at most one or two examples and keep them obviously subordinate to the packet.

Healthy example shapes:

• semantic color tokens (surface/default, surface/emphasis, text/muted) instead of giant fixed palettes
• landing-page hero vs dashboard header comparison to show shared hierarchy but different density
• primitive promotion rule such as “shared button stays primitive; billing-upsell banner stays product-local”

Step 8: Finish with a boundary sentence

End with a sentence that prevents overlap drift.

Examples:

• "This packet defines the shared UI system and its primitive APIs; per-feature product components stay product-local."
• "This packet sets breakpoint and density policy; page-level layout fixes belong in responsive-design."
• "This packet sets accessibility baseline expectations; remediation and verification belong in web-accessibility."

Examples

Example 1: shared landing page + dashboard system

Input: "We need one design system for our marketing site and B2B dashboard so tokens, typography, and motion feel related without making both surfaces identical."

Good response shape:

• choose cross-surface alignment mode
• define shared foundations and surface-specific differences
• leave one compact design-system packet
• define the component-family API alongside the shared foundations

Example 2: token and primitive governance

Input: "Our team keeps adding random colors and spacing values. We need naming rules and a review policy for shared primitives."

Good response shape:

• choose foundations or primitive governance mode
• define token/naming rules and review thresholds
• keep one or two naming examples only
• avoid turning the answer into a full page mock

Example 3: mixed system + responsive request

Input: "Should the dashboard and mobile web app share one breakpoint policy, and how should the layout collapse on small screens?"

Good response shape:

• keep shared breakpoint/density policy in design-system
• route the actual collapse strategy and verification to responsive-design
• make the split explicit in the packet

Example 4: accessibility-heavy follow-up

Input: "We already have tokens, but our forms still fail focus visibility and error-state accessibility."

Good response shape:

• note the design-system baseline briefly
• route the real remediation and manual verification to web-accessibility
• do not absorb the full a11y fix into this skill

Best practices

1. Decide the mode first so the skill stays bounded.
2. Define shared rules before examples to avoid overfitting on one mockup.
3. Keep governance explicit: token changes, primitive promotion, and ownership rules are part of the system.
4. Use route-outs early so design-system does not steal layout, accessibility, or broad-audit work.
5. Leave a compact packet another human or agent can follow.

References

• System modes
• Token and governance checklist
• Scope boundaries
• Design-system packet template
• Responsive layout neighbor
• Accessibility neighbor