Documentation & Storybook

Why Documentation Matters

A design system is only as good as its documentation. Without clear docs, developers won't know how to use components correctly, and adoption will suffer. Great documentation includes interactive examples, usage guidelines, and API references.

Getting Started with Storybook

Storybook is the industry standard for building and documenting UI components in isolation.

# Initialize Storybook in your project
npx storybook@latest init

# Start Storybook development server
npm run storybook

# Build static Storybook for deployment
npm run build-storybook

Writing Stories

Stories define the different states and variations of your components:

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'outline', 'ghost'],
      description: 'The visual style of the button',
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
    },
    isLoading: {
      control: 'boolean',
    },
    disabled: {
      control: 'boolean',
    },
  },
};

export default meta;
type Story = StoryObj;

// Primary variant (default)
export const Primary: Story = {
  args: {
    children: 'Primary Button',
    variant: 'primary',
  },
};

// All variants
export const Variants: Story = {
  render: () => (
    

      Primary
      Secondary
      Outline
      Ghost
    
  ),
};

// All sizes
export const Sizes: Story = {
  render: () => (
    

      Small
      Medium
      Large
    
  ),
};

// Loading state
export const Loading: Story = {
  args: {
    children: 'Saving...',
    isLoading: true,
  },
};

// With icon
export const WithIcon: Story = {
  render: () => (
    
      
      Send Email
    
  ),
};

Autodocs (Automatic Documentation)

Storybook can automatically generate documentation from your TypeScript types and JSDoc comments:

// Button.tsx
export interface ButtonProps {
  /** The visual style of the button */
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  
  /** The size of the button */
  size?: 'sm' | 'md' | 'lg';
  
  /** Shows a loading spinner and disables the button */
  isLoading?: boolean;
  
  /** The content to display inside the button */
  children: React.ReactNode;
  
  /** Called when the button is clicked */
  onClick?: () => void;
}

/**
 * Primary UI component for user interaction.
 * Use buttons to trigger actions, submit forms, or navigate.
 */
export const Button = ({ variant = 'primary', size = 'md', ...props }: ButtonProps) => {
  // ...
};

// In *.stories.tsx, add the autodocs tag
const meta: Meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],  // Enables automatic documentation
};

MDX Documentation

Combine Markdown with JSX for rich documentation pages:

{/* Button.mdx */}
import { Canvas, Meta, Story, Controls } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';



# Button

Buttons trigger actions, submit forms, or navigate to new pages.

## Usage Guidelines

- Use **Primary** buttons for the main action on a page
- Use **Secondary** buttons for less important actions  
- Use **Outline** buttons for cancel or back actions
- Only one Primary button per section

## Interactive Example





## All Variants



## Accessibility

- Always include visible text or aria-label
- Buttons are focusable with keyboard
- Loading state announces to screen readers

## Do's and Don'ts

✅ **Do**
- Use action verbs: "Save", "Submit", "Delete"
- Keep text short and clear

❌ **Don't**  
- Don't use vague text like "Click here"
- Don't use multiple primary buttons in one section

Storybook Addons

Visual Regression Testing

// Install Chromatic
npm install --save-dev chromatic

// Add to package.json
{
  "scripts": {
    "chromatic": "chromatic --project-token=YOUR_TOKEN"
  }
}

// Run visual tests
npm run chromatic

// Or in CI (GitHub Actions)
// .github/workflows/chromatic.yml
name: Chromatic
on: push
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx chromatic --project-token=${{ secrets.CHROMATIC_TOKEN }}

Alternative Documentation Tools