Design System Implementation

This skill ensures that all new or modified UI is implemented in line with the project design system, rather than inventing ad-hoc styles.

Use it when:

• Implementing a new component, page, or flow.
• Refactoring existing UI to match the design system.
• Extending the design system with carefully considered new patterns.

It is designed to be used after a design system has been created (for example via the design-system-from-reference workflow).

Inputs and assumptions

• The project design system is defined in:
  • design/design-system.json (implementation-level source of truth).
  • Optionally design/design.json (higher-level style guide).
• The user can describe:
  • What they want to build or change (component/page/flow).
  • Any relevant constraints (framework, routing, data layer, accessibility).
• The codebase uses a consistent framework (e.g., React + Tailwind, or another typical web stack).

If design/design-system.json is missing, this skill should not free-style a new design system. Instead, it should:

• Ask the user to confirm whether a design system exists elsewhere.
• Suggest running the design-system-from-reference workflow first.

Core responsibilities

When building or updating UI, this skill must:

1. Load and understand the design system

   • Ingest design/design-system.json (and design/design.json if present).
   • Identify:
     • Tokens (colors, spacing, radii, typography scales, shadows, etc.).
     • Component definitions and their variants.
     • Layout and spacing rules.
     • Interaction states and motion guidelines.
   • Summarize back to the user how the design system wants buttons, inputs, cards, navigation, etc. to look and behave.

2. Map the request to existing patterns

   • For a new request (e.g., "build a billing settings page"):
     • Break the UI into sections and components.
     • For each part, map it to existing component types or patterns in the design system.
   • If something genuinely new is needed:
     • Propose how it fits into existing patterns (e.g., "This is a variant of the card component with…").
     • Avoid inventing totally unrelated styling unless the user explicitly wants to extend the system.

3. Implement using the design system

   • Use only tokens, utility classes, and component recipes defined by the design system whenever possible.
   • Avoid arbitrary inline styles or one-off Tailwind utilities that conflict with the system.
   • Respect:
     • Typography hierarchy (headings, body, labels, etc.).
     • Spacing scale and layout rules.
     • Color usage rules for states (primary, secondary, error, warning, success, disabled, etc.).
     • Motion and interaction patterns.
   • Keep code production-quality: clear structure, accessible semantics (ARIA, labels, keyboard navigation), and sensible component boundaries.

4. Handle extensions carefully

   • When the design system does not explicitly cover a case:
     • First, try to express the new UI using combinations or variants of existing components.
     • If an extension is truly needed, propose an addition to design/design-system.json:
       • Describe new tokens, component variants, or layout rules.
       • Ensure they are consistent with the existing system.
     • Present the proposed JSON patch or snippet to the user for review before updating the design system.

5. Validate adherence

   • After generating code, briefly explain how it follows the design system:
     • Which tokens/variants were used.
     • How spacing/typography align with the rules.
   • If any deliberate deviations were made (e.g., an experimental component), call them out clearly.

Suggested workflow when invoked

1. Confirm context
   • Ask the user:
     • What they want built or changed.
     • Where in the codebase it lives (paths, existing components).
     • Whether there is an existing design system JSON; if unsure, search for design/design-system.json.
2. Load design system files
   • Open design/design-system.json (and design/design.json if present) and summarize the relevant parts for this task.
3. Plan the implementation
   • Break the UI into logical components/sections.
   • For each, decide which design system components or patterns to use.
   • Share this plan with the user and pause for confirmation.
4. Implement incrementally
   • Update or create components in small, reviewable steps.
   • After each significant chunk (e.g., a component or page section), pause and:
     • Show the diff or the new code.
     • Explain how it adheres to the design system.
5. Optional: update the design system
   • If new patterns were introduced, propose JSON additions/changes for design/design-system.json.
   • Only modify the design system after explicit user approval.
6. Summarize and hand off
   • Recap what was built/changed and how it aligns with the design system.
   • List any follow-ups (e.g., applying the same patterns to other screens, updating docs).

Interaction with other skills

• When combined with design-system-from-reference:
  • Run design-system-from-reference first to create or update the design system files.
  • Then use this design-system-implementation skill for all subsequent UI work.
• When combined with frontend-design-concept:
  • Use frontend-design-concept for exploring bold conceptual directions.
  • Once a direction is chosen and codified into the design system, use design-system-implementation to roll out consistent implementations across the app.