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

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

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>

// Icon after text <Button rightIcon={<ArrowRightIcon />}>Continue</Button>

// Icon only (use aria-label) <Button aria-label="Settings"> <SettingsIcon /> </Button>

## Full Width

<Button fullWidth>Sign up</Button>

## Button Groups

<div className="button-group"> <Button variant="secondary">Cancel</Button> <Button variant="primary">Save</Button> </div>

## Accessibility

### Keyboard Navigation

| Key | Action |
|-----|--------|
| `Tab` | Move focus to button |
| `Enter` | Activate button |
| `Space` | Activate button |

### ARIA

- Uses native `<button>` element
- `aria-disabled` when disabled (maintains focusability)
- `aria-busy` when loading
- `aria-pressed` for toggle buttons

### Screen Readers

- Ensure button has accessible name (text content or aria-label)
- Loading state announced via aria-busy
- Icon-only buttons require aria-label

### Focus Management

- Focus ring visible on keyboard focus (not mouse)
- 2px outline with 2px offset
- Meets WCAG 2.4.7 Focus Visible

## Design Specifications

### Spacing

| Element | Token | Value |
|---------|-------|-------|
| Horizontal padding (sm) | `--spacing-sm` | 8px |
| Horizontal padding (md) | `--spacing-md` | 16px |
| Horizontal padding (lg) | `--spacing-lg` | 24px |
| Icon gap | `--spacing-xs` | 4px |
| Button group gap | `--spacing-sm` | 8px |

### Colors

| Variant | Background | Text | Border |
|---------|------------|------|--------|
| Primary | `--color-primary-500` | white | - |
| Primary:hover | `--color-primary-600` | white | - |
| Secondary | transparent | `--color-gray-700` | `--color-gray-300` |
| Ghost | transparent | `--color-gray-700` | - |
| Danger | `--color-error-500` | white | - |

### Typography

| Size | Token | Weight |
|------|-------|--------|
| sm | `--text-sm` (14px) | 500 |
| md | `--text-base` (16px) | 500 |
| lg | `--text-lg` (18px) | 500 |

### Other

| Property | Token | Value |
|----------|-------|-------|
| Border radius | `--radius-md` | 8px |
| Focus ring | `--color-primary-500` | 2px solid |
| Transition | - | 150ms ease |

## Do's and Don'ts

### Do ✅

- Use clear, action-oriented labels ("Save", "Delete", "Continue")
- Place primary action on the right in button groups
- Use loading state for async actions
- Provide aria-label for icon-only buttons

### Don't ❌

- Don't use vague labels ("Click here", "Submit")
- Don't use more than one primary button per view
- Don't disable buttons without explanation
- Don't use buttons for navigation (use Links)

## Related Components

- [Link](/components/link) - For navigation
- [IconButton](/components/icon-button) - Icon-only variant
- [ButtonGroup](/components/button-group) - Multiple buttons together
- [ToggleButton](/components/toggle-button) - Stateful toggle

## Changelog

| Version | Changes |
|---------|---------|
| 1.2.0 | Added `loading` prop |
| 1.1.0 | Added `ghost` variant |
| 1.0.0 | Initial release |

---

API Documentation Template

For TypeScript components:

## API Reference

### ButtonProps

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> { /**

• Visual style variant
• @default 'primary'

*/ variant?: 'primary' | 'secondary' | 'ghost' | 'danger';

/**

• Button size
• @default 'md'

*/ size?: 'sm' | 'md' | 'lg';

/**

• Shows loading spinner and disables button
• @default false

*/ loading?: boolean;

/**

• Makes button full width of container
• @default false

*/ fullWidth?: boolean;

/**

• Icon element to display before text

*/ leftIcon?: React.ReactNode;

/**

• Icon element to display after text

*/ rightIcon?: React.ReactNode;

/**

• Button content (label)

*/ children: React.ReactNode; }

### Ref

The Button component forwards its ref to the underlying `<button>` element.

const buttonRef = useRef<HTMLButtonElement>(null); <Button ref={buttonRef}>Click me</Button>

### CSS Classes

| Class | Description |
|-------|-------------|
| `.btn` | Base button styles |
| `.btn--primary` | Primary variant |
| `.btn--secondary` | Secondary variant |
| `.btn--ghost` | Ghost variant |
| `.btn--danger` | Danger variant |
| `.btn--sm` | Small size |
| `.btn--md` | Medium size |
| `.btn--lg` | Large size |
| `.btn--loading` | Loading state |
| `.btn--full-width` | Full width modifier |

---

Auto-Generation from TypeScript

generate-component-docs.ts:

import ts from 'typescript';
import fs from 'fs';

interface PropDoc {
  name: string;
  type: string;
  description: string;
  defaultValue?: string;
  required: boolean;
}

function extractPropsFromInterface(
  sourceFile: ts.SourceFile,
  interfaceName: string
): PropDoc[] {
  const props: PropDoc[] = [];

  function visit(node: ts.Node) {
    if (ts.isInterfaceDeclaration(node) && node.name.text === interfaceName) {
      node.members.forEach((member) => {
        if (ts.isPropertySignature(member) && member.name) {
          const name = member.name.getText(sourceFile);
          const type = member.type?.getText(sourceFile) || 'unknown';
          const required = !member.questionToken;

          // Extract JSDoc
          const jsDoc = ts.getJSDocTags(member);
          const description = ts.getJSDocCommentsAndTags(member)
            .map((c) => c.getText())
            .join(' ')
            .replace(/\/\*\*|\*\/|\*/g, '')
            .trim();

          const defaultTag = jsDoc.find((t) => t.tagName.text === 'default');
          const defaultValue = defaultTag?.comment?.toString();

          props.push({ name, type, description, defaultValue, required });
        }
      });
    }
    ts.forEachChild(node, visit);
  }

  visit(sourceFile);
  return props;
}

function generatePropsTable(props: PropDoc[]): string {
  let md = '| Prop | Type | Default | Required | Description |\n';
  md += '|------|------|---------|----------|-------------|\n';

  for (const prop of props) {
    const required = prop.required ? 'Yes' : 'No';
    const defaultVal = prop.defaultValue || '-';
    md += `| \`${prop.name}\` | \`${prop.type}\` | ${defaultVal} | ${required} | ${prop.description} |\n`;
  }

  return md;
}

// Usage
const sourceCode = fs.readFileSync('./components/Button.tsx', 'utf-8');
const sourceFile = ts.createSourceFile(
  'Button.tsx',
  sourceCode,
  ts.ScriptTarget.Latest,
  true
);

const props = extractPropsFromInterface(sourceFile, 'ButtonProps');
const table = generatePropsTable(props);

console.log(table);

---

Documentation Site Structure

docs/
├── getting-started/
│   ├── installation.md
│   ├── quick-start.md
│   └── theming.md
├── foundations/
│   ├── colors.md
│   ├── typography.md
│   ├── spacing.md
│   └── icons.md
├── components/
│   ├── primitives/
│   │   ├── button.md
│   │   ├── input.md
│   │   └── text.md
│   ├── composite/
│   │   ├── card.md
│   │   ├── modal.md
│   │   └── dropdown.md
│   └── layout/
│       ├── stack.md
│       ├── grid.md
│       └── container.md
├── patterns/
│   ├── forms.md
│   ├── navigation.md
│   └── data-display.md
└── resources/
    ├── changelog.md
    ├── migration.md
    └── contributing.md

---

Best Practices

1. Lead with examples: Show code before explaining 2. Be consistent: Use same structure for all components 3. Include visuals: Screenshots, diagrams, live demos 4. Document edge cases: Empty states, long text, RTL 5. Keep it updated: Automate where possible 6. Cross-reference: Link related components 7. Show context: Include realistic usage scenarios 8. Test your examples: Ensure code snippets work