component-design-spec

Component Design Spec

Before you start

Gather the following from the user. If anything is missing, ask before proceeding:

1. What component is being specified? — Name and one-sentence purpose
2. Where does it appear? — Pages, layouts, or parent components that will consume it
3. What design system does it belong to? — Existing system with tokens, or standalone
4. What are the usage scenarios? — The 2-5 most common ways this component will be used
5. Are there existing implementations? — Current components being replaced or extended
6. What are the constraints? — Framework, browser support, performance budgets, package size limits

Spec template

1. Component Overview

Name:           [PascalCase component name]
Purpose:        [One sentence — what it does and why it exists]
Category:       [Primitive / Composite / Pattern]
Status:         [Proposed / In Review / Approved / Implemented]

Categories: Primitive (low-level, no domain logic: Button, Input), Composite (combines primitives: SearchField, DatePicker), Pattern (opinionated layout: DataTable, NavigationBar).

2. Props API

Define every prop with type, default, and description. Example format:

interface ComponentProps {
  children: React.ReactNode;
  variant: 'primary' | 'secondary' | 'ghost' | 'danger';
  size?: 'sm' | 'md' | 'lg';   // default: 'md'
  disabled?: boolean;            // default: false
  loading?: boolean;             // default: false
  onClick?: (event: React.MouseEvent) => void;
}

Rules: name props after what they control (variant="danger" not color="red"), default booleans to false, use string literal enums, follow onAction callback convention. If >10 props, consider composition.

3. States

State	Trigger	Visual Change	Behavior Change
Default	Initial render	Base styling	Fully interactive
Hover	Mouse enter	Background darkens	Tooltip may appear
Focus	Keyboard tab	Focus ring visible	Accepts Enter/Space
Active	Mouse down / Enter	Scale down slightly	Action fires on release
Disabled	disabled={true}	Opacity reduced	No events fire
Loading	loading={true}	Spinner replaces icon	No events fire
Error	Validation failure	Red border, error icon	Error message shown