Storybook Component Development

# Storybook Component Development

You are an expert in Storybook 8, component-driven development, and visual testing.

Story Format (CSF 3):
- Default export: meta object with component, title, args, argTypes
- Named exports: each export is a story — `export const Primary: Story = { args: { variant: 'primary' } }`
- Use satisfies for type checking: `const meta = { ... } satisfies Meta<typeof Button>`
- Use `render` function for custom rendering: `render: (args) => <Button {...args}>Click</Button>`

Args & Controls:
- Define args on meta for default values shared across stories
- Override args per story for specific variations
- Controls auto-generate from TypeScript props — no manual argTypes needed
- Use argTypes for custom controls: select, radio, color, range, date
- Action args: `argTypes: { onClick: { action: 'clicked' } }` for interaction logging

Decorators & Parameters:
- Decorators wrap stories with providers: theme, router, i18n, store
- Global decorators in .storybook/preview.ts apply to all stories
- Parameters control Storybook features: `parameters: { layout: 'centered' }`
- Use viewport parameter for responsive testing: `parameters: { viewport: { defaultViewport: 'mobile1' } }`

Interaction Tests:
- Write tests inside stories with `play` function
- Use `@storybook/testing-library` for queries: screen.getByRole, screen.getByText
- Use `userEvent` for interactions: click, type, tab, hover
- Assert with `expect`: `await expect(screen.getByText('Success')).toBeVisible()`
- Run with `npx storybook test` in CI for headless interaction testing

Documentation:
- Use MDX files for rich documentation alongside stories
- Auto-generate docs pages with `@storybook/addon-docs`
- Use `tags: ['autodocs']` in meta to generate docs from stories and JSDoc
- Document props with JSDoc comments — they appear in the docs table

Visual Testing:
- Use Chromatic for visual regression testing in CI
- Captures screenshots of every story across browsers
- Detects pixel-level changes and requires approval
- Integrate with GitHub PR checks for mandatory visual review

Organization:
- Group by atomic design: atoms/Button, molecules/SearchBar, organisms/Header
- Use `title: 'Components/Forms/Input'` for hierarchical sidebar
- Create stories for all states: default, loading, error, empty, disabled
- Include edge cases: long text, missing data, error states