Component

Design system component workflow. Figma to production, DS-compliant.

Agent Capabilities

Fallback rule: If Figma MCP is unavailable, the skill works from text input and codebase analysis. Warn the user and proceed.

Actions

Flow

Recommended (new component):
  spec → spec-review → doc → ship → review

Quick (simple component):
  ship {name} [figma-link]

Maintenance (existing component):
  review {path}    or    doc {path}

Spec validation:
  spec-review {spec-path}

System-wide:
  audit {directory}    or    audit {figma-link}

Each action is standalone — usable independently without requiring prior actions.

Philosophy

• Figma-first: Figma is the primary input. Design context drives structure, API, and implementation.
• Principles over opinions: Grounded in Atomic Design, BEM, DTCG, WCAG — not arbitrary preferences.
• Reuse > create: Scan existing tokens, variables, typography BEFORE generating. Never invent.
• Human-in-the-loop: Never create a new token without user approval.
• Zero hardcoded values: Every hex, px, hardcoded spacing/color/radius is a CRITICAL violation.
• Adapt to project: Read CLAUDE.md + codebase. Match the project's naming, not the skill's.
• Stack-agnostic: Works with React, Vue, Svelte, Angular, Web Components — no hardcoded framework.

Figma Integration

When a Figma link is provided, the skill calls get_design_context from Figma MCP:

Figma link provided?
  │
  ├─ YES → Call get_design_context(fileKey, nodeId)
  │         → Receives: code + screenshot + contextual hints
  │         → Extract: component hierarchy, props, variants, tokens used
  │         → Cross-reference with codebase conventions
  │         → Proceed with enriched context
  │
  └─ NO  → Proceed from codebase / manual input only

Combined failure state:
  Figma MCP unavailable AND no component in codebase AND no spec in ds/specs/active/?
    → Error: "No context available. Provide a Figma link with MCP configured,
       create the component first, or run /component spec {name} with a description."

URL parsing:

• figma.com/design/:fileKey/:fileName?node-id=:nodeId → convert - to : in nodeId
• figma.com/design/:fileKey/branch/:branchKey/:fileName → use branchKey as fileKey

Token Scan Protocol

Before any ship or review action, scan the project for existing design tokens:

1. SCAN sources (in order):
   - CSS custom properties (--*)
   - SCSS/LESS variables ($*, @*)
   - Tailwind config (tailwind.config.*)
   - CSS-in-JS theme objects
   - Design token files (tokens.json, *.tokens.*)

2. DETECT naming pattern:
   - Prefix convention (--color-*, --bg-*, $spacing-*)
   - Tier structure (primitive → semantic → component)
   - Categorization (color, spacing, typography, radius, shadow)

3. MATCH Figma values to existing tokens:
   - Color: match hex/rgba to nearest token
   - Spacing: match px values to spacing scale
   - Typography: match font-size/weight/family to type tokens
   - Radius: match border-radius to radius tokens

4. FLAG missing tokens:
   - Value needed but no token exists → ASK user
   - Present options: closest match, create new, custom
   - NEVER create a token without user approval

Action Router

User input
  │
  ├─ "spec", "spec component",
  │  "component spec"                   → Load references/actions/spec.md
  │
  ├─ "doc", "document component",
  │  "component doc"                    → Load references/actions/doc.md
  │
  ├─ "ship", "ship component",
  │  "implement component",
  │  "component ship"                   → Load references/actions/ship.md
  │
  ├─ "review", "review component",
  │  "component review",
  │  "check component"                  → Load references/actions/review.md
  │
  ├─ "spec-review", "spec-review component",
  │  "component spec-review",
  │  "review spec"                      → Load references/actions/spec-review.md
  │
  └─ "audit", "audit component",
     "component audit",
     "audit ds", "audit design system"  → Load references/actions/audit.md

Loading rule: Read the action file BEFORE executing. The action file contains all logic, principles references, and templates needed.

Input detection:

Input contains figma.com URL?
  YES → Extract fileKey + nodeId, call Figma MCP
  NO  → Check if input is a file path (contains / or .)
    YES → Load from codebase
    NO  → Treat as component name, search codebase

Project Structure (in user's project)

ds/
├── specs/
│   ├── active/       ← Current specs (from spec action)
│   ├── shipped/      ← Components delivered
│   └── dropped/      ← Abandoned specs
└── audits/
    ├── active/       ← Current audit findings
    ├── shipped/      ← Fixes applied
    └── dropped/      ← Won't fix

ComponentName/
├── ComponentName.{ext}  (detected from project)
├── doc.md             ← Generated by doc action
├── ComponentName.test.ts
└── index.ts

Principles

Standards that inform every action. Loaded by review and audit for compliance checks.

Templates

File Templates (generated output files)

Output Templates (chat status messages)

Configuration

All behavior is configurable by editing the skill files directly.

References

Actions:

• Spec | Doc | Ship | Review | Spec-Review | Audit

Principles:

• Composition | Naming | Tokens | Props API | Accessibility

Templates (files):

• Spec | Doc | Audit Report

Output (chat):

• Spec | Doc | Ship | Review | Spec-Review | Audit