component-docs

Component Documentation Generator

Overview

Generate comprehensive component documentation including API references, usage examples, accessibility guidelines, and design specifications. Create documentation that serves both designers and developers.

When to Use

• Documenting new components
• Creating component API references
• Writing usage guidelines
• Building a design system documentation site

Quick Reference: Documentation Sections

Section	Purpose	Audience
Overview	What the component does	All
When to Use	Decision guidance	Designers
Props/API	Technical reference	Developers
Examples	Code snippets	Developers
Variants	Visual options	All
States	Interactive states	Designers
Accessibility	A11y guidelines	All
Design Specs	Spacing, tokens used	Designers
Do/Don't	Usage guidance	All

The Process

1. Identify component scope: What does it do, what doesn't it do?
2. Define props interface: All configurable options
3. Create examples: Basic, advanced, edge cases
4. Document variants: Visual variations
5. Add accessibility: ARIA, keyboard, screen reader
6. Include design specs: Spacing, colors, typography tokens
7. Write guidelines: When to use, when not to

---

Component Documentation Template

# Button

Buttons allow users to take actions and make choices with a single tap.

## Overview

The Button component is used for triggering actions. Use buttons to submit forms,
navigate between pages, or trigger in-page functionality.

## When to Use

| Scenario | Recommendation |
|----------|----------------|
| Primary action | Use `variant="primary"` |
| Secondary action | Use `variant="secondary"` |
| Destructive action | Use `variant="danger"` |
| Navigation | Consider using a Link instead |
| In forms | Use `type="submit"` |

## Import

```tsx
import { Button } from '@acme/design-system';

Basic Usage

<Button onClick={handleClick}>Click me</Button>

Props

Prop	Type	Default	Description
variant	'primary' | 'secondary' | 'ghost' | 'danger'	'primary'	Visual style variant
size	'sm' | 'md' | 'lg'	'md'	Button size
disabled	boolean	false	Disables the button
loading	boolean	false	Shows loading spinner
fullWidth	boolean	false	Makes button 100% width
leftIcon	ReactNode	-	Icon before text
rightIcon	ReactNode	-	Icon after text
type	'button' | 'submit' | 'reset'	'button'	HTML button type
onClick	(event: MouseEvent) => void	-	Click handler
children	ReactNode	-	Button label

Variants

Primary

Use for the main action on a page or in a form.

<Button variant="primary">Save changes</Button>

Secondary

Use for secondary actions that support the primary action.

<Button variant="secondary">Cancel</Button>

Ghost

Use for tertiary actions or in dense UIs.

<Button variant="ghost">Learn more</Button>

Danger

Use for destructive actions like delete.

<Button variant="danger">Delete account</Button>

Sizes

<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

Size	Height	Font Size	Use Case
sm	32px	14px	Compact UIs, tables
md	40px	16px	Default, most uses
lg	48px	18px	Hero sections, emphasis

States

Default

<Button>Default</Button>

Hover

Slightly darkened background. Applied automatically on mouse hover.

Active

Pressed state with slight scale reduction.

Focus

Focus ring appears on keyboard focus (focus-visible).

Disabled

<Button disabled>Disabled</Button>

• 50% opacity
• Cursor changes to not-allowed
• Click events are ignored

Loading

<Button loading>Saving...</Button>

• Shows spinner icon
• Button is disabled
• Label remains for width consistency
• aria-busy="true" for screen readers

With Icons

// Icon before text
<Button leftIcon={<PlusIcon />}>Add item</Button>