Component Spec

Use this when you need to document a new or existing UI component for a design system -- its variants, states, behavior rules, accessibility requirements, and usage guidelines. Produces a specification that designers and engineers can build from consistently.

Related skills: Pair with /style-guide for foundational tokens. Feed accessibility requirements from /accessibility-audit. Use /interaction-pattern-library for cross-component interaction consistency.

Process

Step 1: Gather inputs

Ask the user to provide:

1. Component name -- what is this component called in the design system?
2. Purpose -- what problem does this component solve? When should someone use it vs. alternatives?
3. Visual reference -- Figma link, screenshot, or description of the component
4. Existing implementation -- is there a current version? What's wrong with it or missing?
5. Design tokens -- does the team have a token system (colors, spacing, typography)?

Step 2: Define anatomy

Break the component into its constituent parts:

## {{Component Name}}

**Purpose:** (One sentence -- when and why to use this component)
**Category:** (Navigation / Input / Feedback / Layout / Data Display / Action)

### Anatomy

| Part | Required? | Description |
|------|-----------|-------------|
| (e.g., Label) | Yes / No | (What it is and where it appears) |
| (e.g., Icon) | No | (Leading or trailing icon slot) |
| (e.g., Helper text) | No | (Supplementary text below the input) |

Step 3: Define variants

### Variants

| Variant | When to use | Visual difference |
|---------|-------------|-------------------|
| Primary | Default, main actions | (describe) |
| Secondary | Supporting actions alongside primary | (describe) |
| Destructive | Irreversible actions (delete, remove) | (describe) |
| Ghost/Tertiary | Low-emphasis actions, inline links | (describe) |

Step 4: Define states

### States

| State | Visual treatment | Behavior |
|-------|-----------------|----------|
| Default | (describe) | Ready for interaction |
| Hover | (describe change) | Cursor changes, visual feedback |
| Focus | (describe focus indicator) | Keyboard navigation indicator, meets 3:1 contrast |
| Active/Pressed | (describe) | Visual feedback during click/tap |
| Disabled | (describe -- reduced opacity, no pointer) | Non-interactive, skip in tab order |
| Loading | (describe -- spinner, skeleton, progress) | Blocks re-submission, shows progress |
| Error | (describe -- border color, icon, message) | Connected to error message via aria-describedby |
| Success | (describe) | Confirmation feedback |

Step 5: Accessibility specification

### Accessibility

| Requirement | Implementation |
|------------|----------------|
| **Role** | (ARIA role if not implicit -- e.g., role="dialog") |
| **Keyboard** | (How to operate -- Enter, Space, Escape, Arrow keys) |
| **Focus management** | (Tab order, focus trap if modal, return focus on close) |
| **Screen reader** | (What is announced -- label, state, live region updates) |
| **Color independence** | (Icons, borders, or text supplement color indicators) |
| **Target size** | (Minimum 24x24px per WCAG 2.5.8, 44x44px recommended for touch) |
| **Motion** | (Respects prefers-reduced-motion? Describe reduced behavior) |

Step 6: Usage guidelines

### Do / Don't

| Do | Don't |
|----|-------|
| (Correct usage example) | (Common misuse to avoid) |
| (Correct usage example) | (Common misuse to avoid) |

### Content guidelines
- Label text: (rules -- e.g., "2-4 words, sentence case, start with verb")
- Helper text: (rules -- e.g., "One sentence max, no period")
- Error text: (rules -- e.g., "State what went wrong and how to fix it")

### When to use vs. alternatives
- Use **{{this component}}** when: (scenario)
- Use **{{alternative}}** instead when: (scenario)

Step 7: Review

Present the spec and ask:

• Does this cover all the variants your team needs?
• Are there states or interactions I missed?
• Does the accessibility spec match your team's standards?
• Should I spec related components that pair with this one?

Output location

Present the spec as formatted text in the conversation. For design system documentation, export to Notion, Storybook, or the team's component docs.