storybook

SKILL.md

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