Component Library Development

Build, document, and maintain component libraries with clear APIs, comprehensive variants, state coverage, usage examples, and Storybook integration.

Workflow

Step 1: Define the Component

Before building, answer:

1. What problem does this component solve? What UI need does it address?
2. Where is it used? List the screens or flows that need it.
3. Does something similar exist? Check the existing library for overlap.
4. What are the variants? Size, color, layout, or behavioral variations.
5. What are the states? Default, hover, active, focus, disabled, loading, error.

### Component Definition: [Name]

**Purpose**: [One sentence description]
**Category**: [Layout / Input / Display / Feedback / Navigation / Overlay]
**Usage frequency**: [Every page / Common / Occasional / Rare]
**Existing alternatives**: [None / Extends X / Replaces Y]

Step 2: Design the Props API

Design a clean, consistent API:

### Props API: [ComponentName]

| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| variant | 'primary' | 'secondary' | 'ghost' | 'danger' | 'primary' | No | Visual style variant |
| size | 'sm' | 'md' | 'lg' | 'md' | No | Component size |
| disabled | boolean | false | No | Prevents interaction |
| loading | boolean | false | No | Shows loading indicator |
| children | ReactNode | - | Yes | Content to render |
| onClick | () => void | - | No | Click handler |
| className | string | - | No | Additional CSS classes |
| as | ElementType | 'button' | No | Render as different element |
| icon | ReactNode | - | No | Icon element |
| iconPosition | 'left' | 'right' | 'left' | No | Icon placement |
| fullWidth | boolean | false | No | Expand to container width |

API design principles:

• Sensible defaults: Most common usage should require minimal props
• Consistent naming: Use the same prop names across components (size, variant, disabled)
• Composition over configuration: Prefer children and slots over many specific props
• Type safety: Use union types for constrained values, not arbitrary strings
• Forward refs: Always forward refs for DOM access
• Spread remaining props: Pass extra props to the root element

Step 3: Define Variants and States

### Variants

| Variant | Use Case | Visual Description |
|---------|----------|-------------------|
| primary | Main actions, one per section | Filled background, white text |
| secondary | Supporting actions | Outlined, brand color text |
| ghost | Tertiary actions, toolbars | No border, text only |
| danger | Destructive actions | Red filled or outlined |

### Sizes

| Size | Height | Font Size | Padding | Icon Size |
|------|--------|-----------|---------|-----------|
| sm | 32px | 13px | 8px 12px | 16px |
| md | 40px | 14px | 10px 16px | 20px |
| lg | 48px | 16px | 12px 24px | 24px |

### States Matrix

| State | Visual Change | Cursor | Interactive |
|-------|--------------|--------|-------------|
| default | Standard | pointer | Yes |
| hover | Darken background 10% | pointer | Yes |
| active | Darken background 20%, scale 0.98 | pointer | Yes |
| focus | 2px focus ring, 2px offset | pointer | Yes |
| disabled | Opacity 0.5 | not-allowed | No |
| loading | Spinner replaces content | wait | No |

Step 4: Write Usage Examples

### Usage Examples

#### Basic Usage
\`\`\`jsx
<Button onClick={handleSave}>Save changes</Button>
\`\`\`

#### With Variants
\`\`\`jsx
<Button variant="primary">Save</Button>
<Button variant="secondary">Cancel</Button>
<Button variant="ghost">Skip</Button>
<Button variant="danger">Delete</Button>
\`\`\`

#### With Icons
\`\`\`jsx
<Button icon={<PlusIcon />}>Add item</Button>
<Button icon={<DownloadIcon />} iconPosition="right">Export</Button>
<Button icon={<TrashIcon />} variant="danger">Remove</Button>
\`\`\`

#### Loading State
\`\`\`jsx
<Button loading={isSubmitting}>
  {isSubmitting ? 'Saving...' : 'Save changes'}
</Button>
\`\`\`

#### As Link
\`\`\`jsx
<Button as="a" href="/settings">Go to settings</Button>
\`\`\`

#### Full Width
\`\`\`jsx
<Button fullWidth>Sign in</Button>
\`\`\`

Step 5: Document Accessibility

### Accessibility

**Keyboard behavior**:
- Enter/Space: Activates the button
- Tab: Moves focus to the next focusable element
- Disabled buttons are still focusable for discoverability (aria-disabled)

**ARIA**:
- Uses native <button> element (no role needed)
- Loading state: aria-busy="true", aria-label updates to include "loading"
- Icon-only buttons: Must have aria-label

**Screen reader announcements**:
- Default: Reads button text
- Loading: "[Button text], loading"
- Disabled: "[Button text], dimmed" (platform-dependent)

**Focus management**:
- Focus ring visible on keyboard navigation, hidden on mouse click
- Uses :focus-visible for keyboard-only focus styles

Step 6: Create Storybook Stories

Write stories for each visual permutation:

• Default story: Uses Storybook controls/args for interactive exploration of all props
• Variants story: Renders all variants side by side for visual comparison
• Sizes story: Renders all sizes for scale reference
• States story: Shows default, disabled, loading, and error states together
• Composition story: Shows the component used with other components in realistic context

Each story should be self-contained and demonstrate one aspect of the component.

Examples

Example 1: Button Component

User: "Build a Button component for our library." Response: Define 4 variants (primary, secondary, ghost, danger), 3 sizes (sm, md, lg), full state coverage, icon support, polymorphic rendering (as prop), and loading state. Include Storybook stories and accessibility docs.

Example 2: Modal Component

User: "Document our existing Modal component." Response: Audit the current props, identify missing documentation, write usage examples for common patterns (confirmation, form, informational), document focus trap behavior, Escape to close, click-outside behavior, and animation specs.

Example 3: Form Input System

User: "Create a set of form input components." Response: Design a consistent API across TextInput, Select, Checkbox, Radio, and Textarea. Shared props: label, error, hint, disabled, required. Shared patterns: error display, label association, focus styles. Document each component and the system conventions.

Best Practices

1. Composition over configuration. Prefer building complex UIs by composing simple components rather than adding props for every use case. A Button that takes 30 props is a red flag.
2. Consistent API across components. If Button uses size="sm", then Input, Badge, and Avatar should too. Inconsistency creates cognitive overhead.
3. Test every state. Storybook stories should cover: all variants, all sizes, disabled, loading, error, empty, with icon, without icon, long text, truncated text. If a state exists, it has a story.
4. Accessibility is a requirement. Every component ships with keyboard behavior, ARIA attributes, and screen reader testing documented. Non-negotiable.
5. Forward refs and spread props. Components should be transparent wrappers around DOM elements. Forward refs for imperative access. Spread unused props to the root element.
6. Document the why. The props table says what exists. The usage guidelines say when to use each option and why. Both are needed.
7. Version and changelog. Breaking API changes need versioning. A changelog helps consumers know what changed and how to migrate.
8. Design tokens, not hardcoded values. Every color, size, and spacing value should reference a token. This makes theming possible and updates systematic.