| name | component-spec |
| description | Define component API, states, variants, and ARIA requirements before writing a line of implementation code. Gates component work behind a confirmed spec. |
| version | 0.1.0 |
| level | 2 |
| triggers | ["component spec","spec this component","before I build this","define this component","/component-spec"] |
| context_files | ["context/project.md"] |
| steps | [{"name":"Identity","description":"Name the component. Identify its category (input, display, navigation, feedback, layout)."},{"name":"Props API","description":"Define all props — name, type, default, required/optional. No undocumented props."},{"name":"States","description":"Enumerate every visual state — default, hover, active, focus, disabled, loading, error, empty."},{"name":"Variants","description":"List named variants (size, color, shape). Each variant is a prop value, not a separate component."},{"name":"Accessibility","description":"Specify ARIA role, aria-label pattern, keyboard navigation, focus ring, screen reader behavior."},{"name":"Responsive","description":"Define breakpoint behavior. What changes at mobile? What collapses or stacks?"},{"name":"Confirm","description":"Present spec. Wait for explicit confirmation before writing implementation."}] |
Component Spec Skill
Write the spec before writing the component. A confirmed spec prevents the cycle of building, seeing it does not match intent, rebuilding, and realizing the API is wrong for the context.
What Claude Gets Wrong Without This Skill
Claude builds what it guesses the component needs. It chooses an API surface based on the first use case it imagines. States get omitted because they were not considered upfront — the disabled state looks like the active state because both were never defined. Variants proliferate as separate components instead of being parameterized.
The deeper failure: ARIA is bolted on at the end if at all. A button that triggers a dialog does not have aria-haspopup. A toggle does not have aria-checked. An input does not have an aria-describedby pointing to its error message. These are not optional — they are the difference between a component that works and one that excludes users.
Where to Find Component Inspiration
Before writing the spec, look at how others have solved this component:
- 21st.dev — Component-level inspiration. Search by component type (button, card, input, modal).
- CodePen — Live examples with source. Filter by Most Loved.
- Shadcn/UI — Accessible, unstyled components with clean API patterns.
- Radix UI primitives — The reference standard for accessible interactive components.
- Headless UI — Tailwind-adjacent accessible components.
Do not copy visual style from these sources. Copy API patterns and state enumeration — what states did they handle that you missed?
Phase Gates
Identity — hard gate
Name the component and classify it:
| Category | Examples |
|---|
| Input | Button, TextField, Select, Checkbox, Toggle, Slider |
| Display | Card, Badge, Avatar, Tag, Tooltip, Chip |
| Navigation | Tabs, Breadcrumb, Pagination, Sidebar, NavLink |
| Feedback | Alert, Toast, Progress, Skeleton, Spinner |
| Layout | Divider, Spacer, Grid, Stack, Container |
| Overlay | Modal, Drawer, Popover, Dropdown, Sheet |
Classification determines which state set applies and which ARIA patterns are mandatory.
Props API
Define every prop explicitly:
