component-spec
owl-listener/designer-skills
Write complete, implementable component specifications for design systems.
What is component-spec?
Component Spec guides you through creating thorough specifications for reusable UI components. Use it when defining a library component with full coverage of anatomy, variants, states, accessibility, and usage rules.
- Structures component specs with overview, anatomy, variants, props/API, states, behavior, accessibility, and usage guidelines
- Covers all visual variants (size, style, layout) and interactive states (hover, focus, active, disabled, loading, error)
- Documents ARIA roles, keyboard navigation, screen reader support, and focus management for accessibility
- Generates do/don't examples and content rules for consistent component usage
- Specifies responsive behavior and edge cases for implementation clarity
How to install component-spec
npx skills add https://github.com/owl-listener/designer-skills --skill component-specHow to use component-spec
- 1.Run `npx skills add https://github.com/owl-listener/designer-skills --skill component-spec` to install
- 2.Provide the component name and primary use case (e.g., 'Button for primary actions')
- 3.Follow the spec structure: start with overview, then anatomy, variants, props, states, behavior, accessibility, and usage
- 4.Include concrete examples for each variant and state combination
- 5.Document edge cases, responsive breakpoints, and keyboard interactions explicitly
- 6.Review the spec with both designers and developers before finalizing
Use cases
- Defining a new button, input, or card component for a design system
- Documenting variant combinations (size × style × state) for a complex component
- Creating accessibility requirements for a custom form control or modal
- Writing implementation guidelines for developers building from design specs
- Establishing usage rules and related-component relationships for a component library
- Design system leads and component owners
- UX/UI designers creating reusable component libraries
- Frontend developers implementing design system components
- Design-to-development teams needing shared component documentation
component-spec FAQ
Use component-spec to define a single reusable library component with full technical and design detail. Use documentation-template for a broader reusable doc scaffold or template structure.
Use component-spec for atomic, reusable UI components (button, input, card). Use pattern-library for problem-solution patterns or higher-level interaction patterns.
Provide a visual breakdown of the component's required and optional elements, labeling each part and explaining its purpose and constraints.
Include ARIA roles, required keyboard shortcuts, screen reader announcements, focus management strategy, and any color-contrast or sizing requirements.
Yes, include code examples for props/API, key states, and usage patterns. Write for both designers and developers so examples should show intent and behavior, not just syntax.
Full instructions (SKILL.md)
Source of truth, from owl-listener/designer-skills.
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
- Overview — Name, description, when to use / not use
- Anatomy — Visual breakdown, required vs optional elements
- Variants — Size (sm/md/lg), style (primary/secondary/ghost), layout
- Props/API — Name, type, default, description, required status
- States — Default, hover, focus, active, disabled, loading, error
- Behavior — Interactions, animations, responsive behavior, edge cases
- Accessibility — ARIA roles, keyboard nav, screen reader, focus management
- 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
Related skills
More from owl-listener/designer-skills and the wider catalog.
content-strategy
Define what content a product needs, how it's structured, and who owns it.
critique-brand-consistency
Audit UI screens against brand guidelines (mood, voice, tokens) for compliance and consistency.
critique-color
Audit colour contrast, palette coherence, and semantic meaning on a single screen.
critique-composition
Critique spatial balance, whitespace, rhythm, and gestalt grouping in screen layouts.
critique-information-density
Evaluate screen information density, cognitive load, and content prioritization to reduce overwhelm.
critique-typography
Audit typography on screens for scale compliance, readability, consistency, and token usage.