storybook-stories

Storybook Stories

Overview

Storybook is a frontend workshop for building UI components in isolation. Stories are written in Component Story Format 3 (CSF3), which uses object syntax with args for type-safe component documentation and testing.

When to use: Component documentation with live examples, interaction testing with play functions, visual regression testing, accessibility validation, design system maintenance, isolated component development.

When NOT to use: End-to-end testing (use Playwright/Cypress), API integration testing (use Vitest/Jest), full application testing (use browser automation), performance testing (use Lighthouse/WebPageTest).

Quick Reference

Pattern	API	Key Points
Basic story	export const Default: Story = { args }	Use args for simple single components
Complex story	export const Example: Story = { render }	Use render for multi-component layouts
Meta configuration	const meta = { component, args } satisfies Meta	Define defaults and argTypes
Interaction test	play: async ({ canvas, userEvent, args })	canvas and userEvent provided directly
User interaction	await userEvent.click(element)	Always await userEvent methods
Query elements	canvas.getByRole('button')	Prefer getByRole over other queries
Assertions	await expect(args.onPress).toHaveBeenCalled()	Use storybook/test assertions
beforeEach hook	beforeEach: async ({ args }) => {}	Setup mocks before story renders
Play composition	await OtherStory.play?.(context)	Reuse setup across stories
Autodocs	tags: ['autodocs']	Enable automatic documentation
Controls customization	argTypes: { variant: { control: 'select' } }	Configure control panel
Decorators	decorators: [withTheme]	Add wrappers or context providers
Parameters	parameters: { layout: 'centered' }	Configure addon behavior per story
Chromatic snapshot	parameters: { chromatic: { delay: 300 } }	Control visual regression captures
Disable snapshot	parameters: { chromatic: { disableSnapshot: true } }	Skip story in visual tests
A11y testing	await expect(button).toHaveAccessibleName()	Validate accessible labels

Common Mistakes

Mistake	Correct Pattern
Using args with multi-component layouts	Use render for complex compositions
Not awaiting userEvent methods	Always await: await userEvent.click(button)
Using within(canvasElement) manually	Destructure canvas from play context directly
Using getByTestId first	Prefer getByRole, getByLabelText, getByText
Missing default args at meta level	Add args to meta to prevent placeholder controls
Exposing non-serializable props	Disable className, ref, style in argTypes
Not composing play functions	Reuse setup with await BaseStory.play?.(context)
Forgetting to mock callbacks	Use fn() for event handlers: args: { onPress: fn() }
Missing accessible names for icon buttons	Add aria-label or use aria-labelledby
Not scoping queries for portal content	Use within(canvasElement.ownerDocument.body)
Using boolean && for conditional rendering	Use ternary in stories for consistent snapshots
Not waiting for animations	Wrap assertions in waitFor for async state

Common Fixes

Problem	Solution
Controls show placeholders	Add args at meta level with default values
Serialization error	Disable className, ref, style in argTypes
Portal element not found	Search body instead of canvas
Animation timing issues	Wrap assertions in waitFor
Multiple buttons found	Add { name: '...' } to getByRole
A11y test failing	Add label prop or aria-label

Delegation

• Story structure review: Use code-reviewer skill for CSF3 pattern validation
• Accessibility audit: Use Explore agent to discover ARIA patterns across stories
• Visual regression analysis: Use Task agent to investigate Chromatic failures

References

• Story writing patterns and CSF3 syntax
• Interaction tests with play functions
• Component documentation and controls
• Visual testing with Chromatic