Component Spec Template

What This Template Is For

A component spec is the definitive reference for how a single UI element works. It documents every state, variant, interaction, and edge case so designers and engineers build the same thing without ambiguity. The spec answers questions that mockups cannot: What happens when the label text is 200 characters long? What does the error state look like? What keyboard shortcuts does this support? How does it behave on a 320px screen?

Most component bugs trace back to unspecified states. The designer delivered a mockup showing the default and hover state, but nobody defined the disabled state, the loading state, the error state, or the overflow behavior. The engineer made reasonable guesses. The PM filed bugs because the guesses did not match the intended behavior. The component spec prevents this cycle by forcing every state to be explicitly defined before implementation begins.

This template works for any reusable UI element: buttons, inputs, dropdowns, modals, cards, tables, navigation items, and custom components. It pairs well with the design system documentation template for cataloging components as part of a broader system. For teams running formal handoff reviews, the design review template provides a structured checkpoint to validate the spec before engineering starts. Understanding the concept of cognitive load helps PMs make better decisions about component complexity and when to simplify.

How to Use This Template

1. Start with the Component Overview. Name the component, describe its purpose in one sentence, and list where it appears in the product. This anchors the spec in real usage rather than abstract component theory.
2. Draw the anatomy diagram. Label every visual element of the component: icon, label, helper text, border, background, indicator. This creates a shared naming convention between design and engineering.
3. Define all states. Most interactive components have at least 6 states: default, hover, focus, active/pressed, disabled, and error. Some have loading, selected, and read-only states as well. For each state, specify the visual treatment and any behavioral changes.
4. Define all variants. Size variants (small, medium, large), style variants (primary, secondary, ghost), and context variants (inline, standalone) should each be documented with their use cases.
5. Specify interaction behavior: click, keyboard, touch, and screen reader interactions. Include tab order, arrow key behavior, and ARIA attributes.
6. Document edge cases. What happens with very long text? What about empty data? RTL languages? High contrast mode? The edge cases section prevents the most common implementation surprises.

The Template

Component Overview

Anatomy

Label every distinct visual element of the component.

 ┌─────────────────────────────┐
 │  [Icon]  [Label]     [▼]   │  ← Container
 │                             │
 │  [Helper text]              │  ← Supporting text
 └─────────────────────────────┘

States

Variants

Interaction Behavior

Mouse / Touch:

• ☐ Click triggers [action]
• ☐ Hover shows [visual feedback]
• ☐ Long press triggers [action, if applicable]
• ☐ Drag behavior: [none / reorderable / resizable]

Keyboard:

• ☐ Tab moves focus to/from the component
• ☐ Enter or Space triggers the primary action
• ☐ Escape closes/dismisses (if applicable)
• ☐ Arrow keys [behavior if applicable]
• ☐ Type-ahead search [if applicable]

Screen Reader:

• ☐ ARIA role: [button / combobox / listbox / etc.]
• ☐ ARIA label: [How the component is announced]
• ☐ ARIA expanded/selected/checked: [State announcements]
• ☐ Live region: [For dynamic content changes]

Responsive Behavior

Edge Cases

Design Tokens

Filled Example: Multi-Select Dropdown

Component Overview

Anatomy

 ┌──────────────────────────────────────┐
 │  [Tag] [Tag] [Tag]  [input] [Clear ✕]│  ← Container (selected tags + input)
 └──────────────────────────────────────┘
 ┌──────────────────────────────────────┐
 │  🔍 [Search input]                   │  ← Dropdown header
 ├──────────────────────────────────────┤
 │  ☑ Option A                          │  ← Selected option
 │  ☐ Option B                          │  ← Unselected option
 │  ☐ Option C                          │  ← Unselected option
 │  ☑ Option D                          │  ← Selected option
 ├──────────────────────────────────────┤
 │  3 of 12 selected                    │  ← Footer (count)
 └──────────────────────────────────────┘

States

Variants

Interaction Behavior

Mouse / Touch:

• ☑ Click on container opens dropdown, focuses search input
• ☑ Click on option toggles selection (checkbox updates, tag added/removed)
• ☑ Click on tag "x" removes that selection
• ☑ Click on clear button removes all selections
• ☑ Click outside dropdown closes it, preserving selections

Keyboard:

• ☑ Tab focuses the container. Second Tab moves past the component
• ☑ Enter or Space on container opens dropdown
• ☑ Arrow keys navigate options within the open dropdown
• ☑ Enter or Space on an option toggles its selection
• ☑ Escape closes dropdown without changing selections
• ☑ Backspace on empty input removes the last selected tag
• ☑ Typing filters the option list (type-ahead search)

Screen Reader:

• ☑ ARIA role: combobox on container, listbox on dropdown, option on each row
• ☑ ARIA label: "[Field label], multi-select, N items selected"
• ☑ aria-expanded="true/false" on container reflecting dropdown state
• ☑ aria-selected="true/false" on each option
• ☑ aria-activedescendant updates as arrow keys move focus within dropdown
• ☑ Live region announces selection changes: "Option A selected. 3 of 12 selected."

Edge Cases

Common Mistakes to Avoid

• Documenting only the happy path. The default and hover states are the easy ones. The bugs live in error, loading, disabled, overflow, and empty states. Spec every state explicitly. Use the usability testing process to validate that edge cases work before launch.
• Skipping keyboard behavior. Every interactive component must be fully operable by keyboard. This is not a nice-to-have. It is a WCAG requirement and a legal obligation in many markets.
• Defining variants without use cases. Three size variants and four style variants create 12 combinations. If you cannot name a real screen where each combination appears, you are building unused complexity. Start with the variants you need today.
• Using screenshots instead of specs. Screenshots show one state at one viewport width. They cannot communicate transitions, keyboard behavior, overflow handling, or responsive behavior. Screenshots are supplements to a spec, not substitutes.
• Not defining the token contract. If the spec says "gray border" instead of referencing a design token (--border-default), the engineer will pick a gray hex value that does not match the system. Always reference tokens.

Key Takeaways

• Spec every state explicitly: default, hover, focus, active, disabled, error, loading, and read-only
• Define keyboard and screen reader behavior as first-class requirements, not afterthoughts
• Document edge cases (overflow, empty data, async failure) to prevent implementation guesswork
• Reference design tokens by name, not by raw color or size values
• Include filled examples with real product scenarios to make the spec concrete

About This Template

Created by: Tim Adair

Last Updated: 3/5/2026

Version: 1.0.0

License: Free for personal and commercial use