AgentSkillsCN

design-system-implementation

严格遵循 design/design-system.json（若存在，则同时参照 design/design.json）中定义的项目设计系统，构建或更新前端组件与页面。

SKILL.md
--- frontmatter
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.