back
loading skill details...
Best practices for building and documenting component libraries with Storybook
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 pipelinedon't have the plugin yet? install it then click "run inline in claude" again.