Design System

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, ui-component-patterns, responsive-design, web-accessibility, or web-design-guidelines. 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
• Prepare a design-system handoff for Figma, code tokens, primitives, and downstream frontend work

When not to use this skill

• The main task is reusable primitive / slot / variant API design or component-family extraction → use ui-component-patterns
• 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-design-guidelines
• 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: component API details to ui-component-patterns, responsive verification to responsive-design

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 reusable component API → ui-component-patterns
• one page’s layout breakage → responsive-design
• one accessibility failure or remediation plan → web-accessibility
• one broad UX/UI critique → web-design-guidelines

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, keep the system naming/tokens here but route API design to ui-component-patterns
• 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-design-guidelines

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
- `ui-component-patterns`:
- `responsive-design`:
- `web-accessibility`:
- `web-design-guidelines`:

## 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; component API extraction belongs in ui-component-patterns."
• "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
• route component-family API design to ui-component-patterns

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, component-API, accessibility, or broad-audit work. 5. Leave a compact packet another human or agent can follow. 6. Keep the alias narrow: frontend-design-system remains a compatibility redirect, not a peer canonical skill.

References

• System modes
• Token and governance checklist
• Scope boundaries
• Design-system packet template
• Compatibility alias
• Component architecture neighbor
• Responsive layout neighbor
• Accessibility neighbor
• Broad UI audit neighbor

Design System Packet Template

# 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:
- Promotion/review threshold:

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

## Accessibility baseline
- Contrast:
- Focus visibility:
- Reduced motion:
- Semantic expectations:

## Route-outs
- `ui-component-patterns`:
- `responsive-design`:
- `web-accessibility`:
- `web-design-guidelines`:

## Open decisions
- ...

Use this packet as the default final artifact unless the user explicitly asks for a raw mock, token file, or implementation code.

Design System Scope Boundaries

Use design-system when the job is to define or refactor shared UI-system rules across multiple pages, products, or component families.

Keep work in design-system when

• the team needs shared token scales, semantic naming, density policy, motion rules, or breakpoint policy
• the question is about primitive naming, contribution governance, or cross-product visual language
• multiple surfaces need one coherent system direction before local implementation proceeds
• the right deliverable is a compact Design System Packet, not a page-only critique or component-only API spec

Route to ui-component-patterns when

• the main task is designing or refactoring one reusable primitive or component-family API
• the question is about variants, slots, compound components, controlled-vs-uncontrolled ownership, or Storybook/example coverage
• system naming may stay here, but the real implementation brief belongs there

Route to responsive-design when

• the main task is viewport/container adaptation, overflow control, breakpoint behavior, reflow, or mobile layout verification
• the system may define breakpoint or density policy here, but the actual layout-collapse strategy belongs there

Route to web-accessibility when

• the main task is accessibility remediation or verification
• the user is asking about keyboard/focus behavior, semantic HTML, ARIA, labels, contrast failures, or manual assistive-technology checks
• this skill should keep only the shared baseline expectations

Route to web-design-guidelines when

• the main task is a broad page or flow critique for hierarchy, clarity, polish, CTA emphasis, consistency, or launch readiness
• the user wants a UI audit packet rather than shared-system governance

Canonical vs alias rule

If the request is about general UI-system direction, design-system should win. The alias frontend-design-system survives only as a compatibility redirect for exact-name workflows.

Mixed cases

When a request spans multiple lanes, split the answer explicitly:

• design-system owns shared rules and governance
• neighboring skills own component API architecture, layout adaptation, accessibility remediation, or broad critique

Do not hide unclear ownership by calling every frontend question “design-system work.”

Design System Modes

Use this file before answering so design-system stays a shared-system skill rather than a page mock or component-API dump.

1. Foundations mode

Choose this when the team needs shared token and policy decisions:

• color / semantic token naming
• typography scale
• spacing, radius, elevation, density, and motion rules
• breakpoint policy that multiple products or surfaces should inherit

Good output: a concise foundations section inside the final Design System Packet.

2. Cross-surface alignment mode

Choose this when multiple surfaces must feel coherent without becoming identical:

• marketing site + app shell
• dashboard + settings + form flows
• public product pages + logged-in workspace

Good output: shared rules plus surface-specific differences.

3. Primitive governance mode

Choose this when the real question is policy around shared primitives:

• what should become a primitive
• naming rules for shared primitives
• when to promote product-local UI into the system
• ownership/review process for system changes

Route actual prop/slot/variant API design to ui-component-patterns.

4. System handoff mode

Choose this when the system direction is mostly settled and the job is to leave a clean packet for design/dev execution.

Good output: the Design System Packet with scope, foundations, primitive policy, surface guidance, accessibility baseline, and route-outs.

5. System review mode

Choose this when inconsistency is suspected but the owning skill is unclear.

Questions to ask:

• is the problem really shared-system governance?
• is it actually a component-API issue?
• is it a responsive-layout issue?
• is it an accessibility remediation issue?
• is it a broad UI/UX audit problem?

If most answers point elsewhere, route out early.

Token and Governance Checklist

Use this checklist before changing shared system rules.

Foundations

• Are semantic tokens preferred over one-off literal values?
• Are typography, spacing, radius, elevation, and motion scales named consistently?
• Are breakpoint or density rules defined at the system level only when multiple surfaces truly share them?
• Are reduced-motion and contrast expectations captured as system baseline rather than as optional polish?

Primitive policy

• Which primitives are truly shared across products or surfaces?
• Which UI pieces should remain product-local wrappers instead of becoming primitives?
• Are primitive names tied to role/pattern rather than one screen?
• Is there a clear promotion rule from product-local UI into the shared system?

Governance

• Who can add or rename tokens?
• What review is required before introducing new primitives or system states?
• What evidence is needed before broadening the system (reuse, cross-surface need, maintenance savings)?
• What should route to ui-component-patterns, responsive-design, web-accessibility, or web-design-guidelines instead of staying here?

Accessibility baseline

• Contrast expectations stated?
• Focus visibility expectations stated?
• Reduced-motion posture stated?
• Semantic expectations for shared primitives stated?

Output discipline

• Are the shared rules stated before examples?
• Is the final packet concise enough for downstream execution?
• Are open decisions called out explicitly instead of hidden in examples?