component-spec — Claude Code skill: write a component spec
This skill writes a full spec for one design-system component: anatomy, variants, states, accessibility and usage rules. Useful when a library grows and the API needs pinning down.
npx skills add Owl-Listener/designer-skills --skill component-spec -a claude-codeWhat component-spec does
The spec follows eight sections: overview with when to use and when not to, anatomy split into required and optional parts, variants by size and style, a props table, states, behavior, accessibility, and usage guidelines with do and don't examples.
Props get name, type, default, description and required status. States are listed as default, hover, focus, active, disabled, loading and error. Accessibility covers ARIA roles, keyboard navigation, screen reader output and focus management. Behavior is documented apart from appearance: interactions, animations, responsive behavior, edge cases.
The author advises writing for designers and developers at once, with an example for every variant and state. Scope is one component. The description points to documentation-template for a reusable doc scaffold and to pattern-library for a problem-solution pattern.
What it helps with
- pin down a component API before implementation starts
- list button states including loading and error
- document keyboard navigation and focus management
- build a props table with types and defaults
- separate component variants by size and style
Example prompts for the agent
- Write a component spec for Button: props, states, variants
- Spec out the input field with error and loading states
- Break the card anatomy into required and optional elements
How to install component-spec
1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill component-spec -a claude-code2Manually: put the files in place
~/.claude/skills/component-spec/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/component-spec/
1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill component-spec -a codex2Manually: put the files in place
.agents/skills/component-spec/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill component-spec -a cursor2Manually: put the files in place
.cursor/skills/component-spec/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install Owl-Listener/designer-skills component-spec2Manually: put the files in place
.github/skills/component-spec/SKILL.md1Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill component-spec -a gemini-cli2Platform CLI
gemini skills install https://github.com/Owl-Listener/designer-skills --path design-systems/skills/component-specManually: put the files in place
.devin/skills/component-spec/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add Owl-Listener/designer-skills --skill component-spec -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about component-spec
How do I install component-spec in Claude?
Run npx skills add Owl-Listener/designer-skills --skill component-spec -a claude-code. The skill lands at ~/.claude/skills/component-spec/SKILL.md.
What does component-spec do?
It produces a complete spec for a single component: anatomy, variants, props, states, behavior, accessibility and usage rules.
How is component-spec different from documentation-template?
component-spec covers one library component. For a reusable doc scaffold the skill description points to documentation-template, and for a problem-solution pattern to pattern-library.
Source text
SKILL.md · MIT
--- name: component-spec description: Specify one component — props, states, variants, accessibility, and usage rules. Use when defining a library component. For the reusable doc scaffold use `documentation-template`; for a problem-solution pattern use `pattern-library`. --- # Component Spec You are an expert in writing thorough, implementable component specifications for design systems. ## What You Do You create complete component specs covering anatomy, behavior, variants, states, accessibility, and usage. ## Specification Structure 1. **Overview** — Name, description, when to use / not use 2. **Anatomy** — Visual breakdown, required vs optional elements 3. **Variants** — Size (sm/md/lg), style (primary/secondary/ghost), layout 4. **Props/API** — Name, type, default, description, required status 5. **States** — Default, hover, focus, active, disabled, loading, error 6. **Behavior** — Interactions, animations, responsive behavior, edge cases 7. **Accessibility** — ARIA roles, keyboard nav, screen reader, focus management 8. **Usage Guidelines** — Do/don't examples, content rules, related components ## Best Practices - Write for both designers and developers - Include examples for every variant and state - Specify behavior, not just appearance - Consider all input methods - Document edge cases explicitly
© Owl-Listener · MIT · Owl-Listener/designer-skills
