storybook

mindrally

•

6155 months ago

Source Raw

Best practices for building and documenting component libraries with Storybook

Quick Install

npxskills add mindrally/skills--skill storybook

Instructions

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

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360