Storybook Best Practices

You are an expert in building and documenting component libraries with Storybook. Apply these guidelines when creating stories, organizing components, and maintaining design systems.

Project Structure

Directory Organization

• Place stories alongside component files (Component.stories.tsx)
• Use consistent naming conventions for story files
• Organize stories by feature or component type
• Maintain a clear hierarchy matching your component library

File Naming

• Use PascalCase for component story files
• Follow pattern: ComponentName.stories.tsx
• Group related stories in the same file
• Use descriptive story names that explain the variant

Writing Stories

Story Structure

import type { Meta, StoryObj } from '@storybook/react';
import { Component } from './Component';

const meta: Meta<typeof Component> = {
  title: 'Category/Component',
  component: Component,
  parameters: {
    layout: 'centered',
  },
  tags: ['autodocs'],
  argTypes: {
    // Define arg types here
  },
};

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

export const Default: Story = {
  args: {
    // Default props
  },
};

export const Variant: Story = {
  args: {
    variant: 'secondary',
  },
};

Story Best Practices

• Create a Default story showing primary usage
• Add stories for each significant variant
• Include edge cases and error states
• Document interactive states (hover, focus, disabled)
• Show responsive behavior when relevant

Component Documentation

Autodocs

• Enable autodocs for automatic documentation generation
• Write clear JSDoc comments for components and props
• Document prop types, defaults, and requirements
• Include usage examples in component comments

Custom Documentation

• Add MDX files for complex documentation needs
• Include design rationale and usage guidelines
• Document accessibility considerations
• Provide code examples for common use cases

Args and Controls

ArgTypes Configuration

argTypes: {
  variant: {
    control: 'select',
    options: ['primary', 'secondary', 'tertiary'],
    description: 'Visual style variant',
    table: {
      defaultValue: { summary: 'primary' },
    },
  },
  size: {
    control: 'radio',
    options: ['sm', 'md', 'lg'],
  },
  disabled: {
    control: 'boolean',
  },
  onClick: {
    action: 'clicked',
  },
}

Args Best Practices

• Use meaningful default values
• Group related args logically
• Provide descriptions for complex props
• Set up actions for callback props

Decorators and Parameters

Decorators

decorators: [
  (Story) => (
    <ThemeProvider theme={defaultTheme}>
      <Story />
    </ThemeProvider>
  ),
],

• Use decorators for consistent story wrappers
• Apply theme providers at the appropriate level
• Add layout containers when needed
• Keep decorators simple and reusable

Parameters

parameters: {
  layout: 'centered', // or 'fullscreen', 'padded'
  backgrounds: {
    default: 'light',
    values: [
      { name: 'light', value: '#ffffff' },
      { name: 'dark', value: '#1a1a1a' },
    ],
  },
  viewport: {
    defaultViewport: 'responsive',
  },
},

Testing with Storybook

Interaction Testing

import { within, userEvent } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

export const Clickable: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');

    await userEvent.click(button);
    await expect(button).toHaveFocus();
  },
};

Visual Testing

• Configure visual regression testing
• Capture stories at multiple viewports
• Test theme variations (light/dark mode)
• Document visual test coverage

Accessibility Testing

• Enable a11y addon for accessibility checks
• Address all accessibility violations
• Test keyboard navigation in stories
• Document ARIA requirements

Addons and Configuration

Essential Addons

• @storybook/addon-essentials (docs, controls, actions, viewport)
• @storybook/addon-a11y for accessibility testing
• @storybook/addon-interactions for interaction testing
• @storybook/addon-designs for design spec integration

Configuration

// .storybook/main.ts
const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions',
  ],
  framework: {
    name: '@storybook/react-vite',
    options: {},
  },
};

export default config;

Design System Integration

Design Tokens

• Import design tokens from your token system
• Apply tokens consistently in stories
• Document token usage in component docs
• Show token variations in dedicated stories

Theme Support

• Configure theme provider in preview.js
• Create stories for each theme variant
• Test components across all supported themes
• Document theme-specific behavior

Performance

Build Optimization

• Use lazy loading for large story collections
• Optimize static assets
• Configure proper caching
• Monitor and improve build times

Story Performance

• Avoid heavy computations in stories
• Use mock data efficiently
• Lazy load complex dependencies
• Profile and optimize slow stories

Best Practices Summary

• Write stories that serve as living documentation
• Test components in isolation before integration
• Keep stories simple and focused
• Maintain consistency across all stories
• Update stories when components change
• Use stories for design review and QA
• Make accessibility testing part of the workflow
• Integrate with your CI/CD pipeline