oakoss 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-reviewerskill for CSF3 pattern validation - Accessibility audit: Use
Exploreagent to discover ARIA patterns across stories - Visual regression analysis: Use
Taskagent to investigate Chromatic failures
References
- Story writing patterns and CSF3 syntax
- Interaction tests with play functions
- Component documentation and controls
- Visual testing with Chromatic