design-system-implementation

name	design-system-implementation
description	Build or update frontend components and pages that strictly adhere to the project design system defined in design/design-system.json (and design/design.json when present).
category	design
license	Complete terms in LICENSE.txt

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.