storybook-docs

Storybook Documentation Skill

Generate comprehensive UI component documentation using Storybook with MDX, autodocs, and design system integration.

Capabilities

• Configure Storybook docs addon
• Generate component documentation from stories
• Write MDX story documentation
• Configure autodocs for automatic documentation
• Integrate design system documentation
• Configure accessibility addon integration
• Export static documentation sites
• Integrate with Chromatic for visual testing

Usage

Invoke this skill when you need to:

• Document React/Vue/Angular component libraries
• Create interactive component documentation
• Build design system documentation
• Generate API reference from component props
• Set up component playground documentation

Inputs

Input Example

{
  "projectPath": "./packages/components",
  "framework": "react",
  "outputDir": "docs/components",
  "includeAccessibility": true,
  "generateMdx": true
}

Output Structure

docs/components/
├── index.html                    # Documentation home
├── iframe.html                   # Story iframe
├── assets/
│   ├── manager.js
│   └── preview.js
├── sb-addons/                    # Addon assets
├── sb-common-assets/
├── sb-manager/
├── sb-preview/
└── stories.json                  # Story metadata

Storybook Configuration

.storybook/main.ts

import type { StorybookConfig } from '@storybook/react-vite';

const config: StorybookConfig = {
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
  ],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-a11y',
    '@storybook/addon-designs',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
  docs: {
    autodocs: 'tag', // Generate docs for components with autodocs tag
    defaultName: 'Documentation',
  },
  typescript: {
    reactDocgen: 'react-docgen-typescript',
    reactDocgenTypescriptOptions: {
      shouldExtractLiteralValuesFromEnum: true,
      shouldRemoveUndefinedFromOptional: true,
      propFilter: (prop) =>
        prop.parent ? !/node_modules/.test(prop.parent.fileName) : true,
    },
  },
};

export default config;

.storybook/preview.ts

import type { Preview } from '@storybook/react';
import { themes } from '@storybook/theming';

const preview: Preview = {
  parameters: {
    actions: { argTypesRegex: '^on[A-Z].*' },
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
    docs: {
      theme: themes.light,
      toc: {
        contentsSelector: '.sbdocs-content',
        headingSelector: 'h1, h2, h3',
        title: 'Table of Contents',
        disable: false,
      },
    },
    backgrounds: {
      default: 'light',
      values: [
        { name: 'light', value: '#ffffff' },
        { name: 'dark', value: '#1a1a1a' },
        { name: 'gray', value: '#f5f5f5' },
      ],
    },
  },
  tags: ['autodocs'],
};

export default preview;

Story Patterns

Component Story Format (CSF3)

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

/**
 * Button component for user interactions.
 *
 * ## Usage
 * ```tsx
 * import { Button } from '@mylib/components';
 *
 * <Button variant="primary" onClick={handleClick}>
 *   Click me
 * </Button>
 * ```
 *
 * ## Accessibility
 * - Uses native button element for proper semantics
 * - Supports keyboard navigation
 * - Includes ARIA attributes for loading/disabled states
 */
const meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  parameters: {
    layout: 'centered',
    docs: {
      description: {
        component: 'Primary UI component for user interaction',
      },
    },
  },
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'tertiary', 'danger'],
      description: 'Visual style variant',
      table: {
        type: { summary: 'ButtonVariant' },
        defaultValue: { summary: 'primary' },
      },
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
      description: 'Button size',
    },
    disabled: {
      control: 'boolean',
      description: 'Disables the button',
    },
    loading: {
      control: 'boolean',
      description: 'Shows loading spinner',
    },
    onClick: {
      action: 'clicked',
      description: 'Click handler',
    },
  },
  args: {
    onClick: fn(),
  },
} satisfies Meta<typeof Button>;

export default meta;
type Story = StoryObj<typeof meta>;

/**
 * Primary button for main actions.
 */
export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Primary Button',
  },
};

/**
 * Secondary button for less prominent actions.
 */
export const Secondary: Story = {
  args: {
    variant: 'secondary',
    children: 'Secondary Button',
  },
};

/**
 * Danger button for destructive actions.
 * Use sparingly and with confirmation dialogs.
 */
export const Danger: Story = {
  args: {
    variant: 'danger',
    children: 'Delete',
  },
  parameters: {
    docs: {
      description: {
        story: 'Use for destructive actions like delete or remove.',
      },
    },
  },
};

/**
 * Loading state with spinner.
 */
export const Loading: Story = {
  args: {
    variant: 'primary',
    loading: true,
    children: 'Saving...',
  },
};

/**
 * Disabled state.
 */
export const Disabled: Story = {
  args: {
    variant: 'primary',
    disabled: true,
    children: 'Disabled',
  },
};

/**
 * Size variants comparison.
 */
export const Sizes: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '1rem', alignItems: 'center' }}>
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </div>
  ),
  parameters: {
    docs: {
      description: {
        story: 'Available size variants for different contexts.',
      },
    },
  },
};

MDX Documentation

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

<Meta of={ButtonStories} />

# Button

<Canvas of={ButtonStories.Primary} />

The Button component is used for triggering actions in forms, dialogs,
and throughout the interface.

## Import

```tsx
import { Button } from '@mylib/components';

Usage

<Button variant="primary" onClick={handleClick}>
  Click me
</Button>

Props

Variants

Primary

Use the primary variant for the main action on a page.

Secondary

Use secondary for less prominent actions.

Danger

Use danger variant for destructive actions. Always confirm with users.

States

Loading

Display a loading spinner when an action is in progress.

Disabled

Disable buttons when actions are not available.

Sizes

Accessibility

• Uses semantic <button> element
• Supports keyboard focus and activation
• Includes aria-disabled when disabled
• Loading state announced to screen readers

Design Guidelines

Do

• Use clear, action-oriented labels
• Show loading state for async actions
• Disable when action is unavailable

Don't

• Don't use for navigation (use Link)
• Don't stack multiple primary buttons
• Don't disable without explanation

All Stories

Autodocs Configuration

Per-Component Autodocs

// Component with JSDoc for autodocs
import { FC, ReactNode } from 'react';

export interface CardProps {
  /** Card title displayed in header */
  title: string;
  /** Optional subtitle below title */
  subtitle?: string;
  /** Card content */
  children: ReactNode;
  /** Visual variant */
  variant?: 'elevated' | 'outlined' | 'filled';
  /** Whether card is interactive/clickable */
  interactive?: boolean;
  /** Click handler for interactive cards */
  onClick?: () => void;
}

/**
 * Card component for grouping related content.
 *
 * @example
 * ```tsx
 * <Card title="Welcome" variant="elevated">
 *   <p>Card content goes here</p>
 * </Card>
 * ```
 */
export const Card: FC<CardProps> = ({
  title,
  subtitle,
  children,
  variant = 'elevated',
  interactive = false,
  onClick,
}) => {
  // Implementation
};

Autodocs Customization

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

const meta: Meta<typeof Card> = {
  title: 'Components/Card',
  component: Card,
  tags: ['autodocs'],
  parameters: {
    docs: {
      description: {
        component: `
Cards are surfaces that display content and actions on a single topic.

They should be easy to scan for relevant and actionable information.
Elements, like text and images, should be placed on them in a way
that clearly indicates hierarchy.
        `,
      },
    },
  },
  argTypes: {
    children: {
      control: 'text',
      description: 'Card content',
      table: {
        category: 'Content',
      },
    },
    title: {
      table: {
        category: 'Content',
      },
    },
    variant: {
      table: {
        category: 'Appearance',
      },
    },
    interactive: {
      table: {
        category: 'Behavior',
      },
    },
  },
};

export default meta;

Design System Documentation

Design Tokens MDX

{/* DesignTokens.mdx */}
import { Meta, ColorPalette, ColorItem, Typeset } from '@storybook/blocks';

<Meta title="Foundations/Design Tokens" />

# Design Tokens

Design tokens are the visual design atoms of the design system.

## Colors

### Primary

<ColorPalette>
  <ColorItem
    title="Primary"
    subtitle="Brand colors"
    colors={{
      'Primary 50': '#E3F2FD',
      'Primary 100': '#BBDEFB',
      'Primary 500': '#2196F3',
      'Primary 700': '#1976D2',
      'Primary 900': '#0D47A1',
    }}
  />
</ColorPalette>

### Semantic

<ColorPalette>
  <ColorItem
    title="Success"
    colors={{ Success: '#4CAF50' }}
  />
  <ColorItem
    title="Warning"
    colors={{ Warning: '#FF9800' }}
  />
  <ColorItem
    title="Error"
    colors={{ Error: '#F44336' }}
  />
</ColorPalette>

## Typography

<Typeset
  fontSizes={['12px', '14px', '16px', '20px', '24px', '32px']}
  fontWeight={400}
  sampleText="The quick brown fox jumps over the lazy dog"
  fontFamily="Inter, system-ui, sans-serif"
/>

Icons Documentation

{/* Icons.mdx */}
import { Meta, IconGallery, IconItem } from '@storybook/blocks';
import * as Icons from '../icons';

<Meta title="Foundations/Icons" />

# Icons

Icon library for the design system.

<IconGallery>
  <IconItem name="Add"><Icons.Add /></IconItem>
  <IconItem name="Edit"><Icons.Edit /></IconItem>
  <IconItem name="Delete"><Icons.Delete /></IconItem>
  <IconItem name="Search"><Icons.Search /></IconItem>
  <IconItem name="Settings"><Icons.Settings /></IconItem>
</IconGallery>

Accessibility Addon Integration

A11y Configuration

// .storybook/preview.ts
import type { Preview } from '@storybook/react';

const preview: Preview = {
  parameters: {
    a11y: {
      config: {
        rules: [
          { id: 'color-contrast', enabled: true },
          { id: 'label', enabled: true },
          { id: 'button-name', enabled: true },
        ],
      },
      options: {
        runOnly: {
          type: 'tag',
          values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'],
        },
      },
    },
  },
};

export default preview;

Per-Story A11y

export const AccessibleButton: Story = {
  args: {
    children: 'Submit Form',
    'aria-label': 'Submit the contact form',
  },
  parameters: {
    a11y: {
      config: {
        rules: [{ id: 'color-contrast', enabled: true }],
      },
    },
  },
};

Static Export

Build Documentation

# Build static documentation site
npx storybook build --docs -o docs/components

# With custom output
npx storybook build --docs -o public/design-system

package.json Scripts

{
  "scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "build-docs": "storybook build --docs -o docs/components",
    "test-storybook": "test-storybook"
  }
}

Workflow

1. Analyze components - Scan for React/Vue/Angular components
2. Generate stories - Create story files for components
3. Extract props - Use react-docgen for prop documentation
4. Create MDX - Generate MDX documentation pages
5. Configure autodocs - Set up automatic documentation
6. Build static - Export static documentation site

Dependencies

{
  "devDependencies": {
    "@storybook/react": "^8.0.0",
    "@storybook/react-vite": "^8.0.0",
    "@storybook/addon-essentials": "^8.0.0",
    "@storybook/addon-a11y": "^8.0.0",
    "@storybook/addon-interactions": "^8.0.0",
    "@storybook/addon-links": "^8.0.0",
    "@storybook/addon-designs": "^8.0.0",
    "@storybook/blocks": "^8.0.0",
    "@storybook/test": "^8.0.0",
    "react-docgen-typescript": "^2.2.0"
  }
}

Best Practices Applied

• Use CSF3 for story format
• Document props with JSDoc comments
• Include usage examples in MDX
• Group related args with table.category
• Add accessibility testing
• Include design guidelines
• Export static documentation

References

• Storybook Docs: https://storybook.js.org/docs
• Storybook Addons: https://storybook.js.org/integrations
• MDX Documentation: https://storybook.js.org/docs/writing-docs/mdx
• Autodocs: https://storybook.js.org/docs/writing-docs/autodocs
• Chromatic: https://www.chromatic.com/

Target Processes

• sdk-doc-generation.js
• interactive-tutorials.js
• how-to-guides.js
• docs-as-code-pipeline.js