┌──────────────┐
         │   Visual     │  Chromatic TurboSnap
         │  Regression  │  (snapshot diffs)
         ├──────────────┤
         │ Accessibility│  @storybook/addon-a11y
         │   (a11y)     │  (axe-core scans)
         ├──────────────┤
         │ Interaction  │  play() functions
         │   Tests      │  (@storybook/test)
         ├──────────────┤
         │  Unit Tests  │  Vitest + storybookTest
         │  (stories)   │  plugin
         └──────────────┘

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { expect, fn, userEvent, within } from 'storybook/test'
import { Button } from './Button'

const meta = {
  component: Button,
  args: {
    onClick: fn(),
  },
} satisfies Meta<typeof Button>

export default meta
type Story = StoryObj<typeof meta>

export const Primary: Story = {
  args: {
    label: 'Click me',
    variant: 'primary',
  },
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement)
    const button = canvas.getByRole('button', { name: /click me/i })

    await userEvent.click(button)
    await expect(args.onClick).toHaveBeenCalledOnce()
    await expect(button).toHaveStyle({ backgroundColor: 'rgb(37, 99, 235)' })
  },
}

// vitest.config.ts
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  plugins: [storybookTest()],
  test: {
    setupFiles: ['./vitest.setup.ts'],
  },
})

# 1. Generate component + CSF3 story
# 2. Run tests via MCP
results = run-story-tests(
    stories=[{ "storyId": "button--primary" }],
    a11y=True
)
# 3. If failures: read violations, fix, retry (max 3)
# 4. Preview in chat for visual confirmation
preview-stories(stories=[{ "storyId": "button--primary" }])

npx storybook add @storybook/addon-mcp   # current: 0.6.0, Apr 2026
# Enable docs toolset in .storybook/main.ts:
#   componentsManifest: true    # was experimentalComponentsManifest (SB 10.3 rename, default-on)
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project

// Manual accessibility checking — unreliable and not repeatable
import type { Meta, StoryObj } from '@storybook/react'
import { Button } from './Button'

const meta = { component: Button } satisfies Meta<typeof Button>
export default meta
type Story = StoryObj<typeof meta>

export const IconOnly: Story = {
  args: {
    icon: <SearchIcon />,
    // No aria-label — screen readers cannot identify the button
    // No automated test catches this
  },
}

import type { Meta, StoryObj } from '@storybook/react'
import { expect, within } from '@storybook/test'
import { Button } from './Button'

const meta = {
  component: Button,
  tags: ['autodocs'],
  parameters: {
    a11y: {
      config: {
        rules: [
          { id: 'color-contrast', enabled: true },
          { id: 'button-name', enabled: true },
        ],
      },
    },
  },
} satisfies Meta<typeof Button>

export default meta
type Story = StoryObj<typeof meta>

export const IconOnly: Story = {
  args: {
    icon: <SearchIcon />,
    'aria-label': 'Search',  // accessible name for icon-only button
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement)
    const button = canvas.getByRole('button', { name: /search/i })
    await expect(button).toBeVisible()
    await expect(button).toHaveAccessibleName('Search')
  },
}

export const DisabledState: Story = {
  args: {
    label: 'Submit',
    disabled: true,
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement)
    const button = canvas.getByRole('button', { name: /submit/i })
    await expect(button).toBeDisabled()
    // a11y addon automatically checks contrast, ARIA, focus management
  },
}

// .storybook/main.ts — register a11y addon
const config: StorybookConfig = {
  addons: [
    '@storybook/addon-vitest',
    '@storybook/addon-a11y',  // runs axe-core on every story
  ],
}

// Separate documentation maintained manually — drifts from reality
// docs/components/Button.mdx
import { Button } from '../components/Button'

# Button

| Prop | Type | Default |
|------|------|---------|
| label | string | — |
| variant | 'primary' \| 'secondary' | 'primary' |
| size | 'sm' \| 'md' \| 'lg' | 'md' |

// ^ This table is manually maintained and already out of date
// The component added a 'danger' variant last sprint

// Button.stories.tsx — autodocs generates the docs page
import type { Meta, StoryObj } from '@storybook/react'
import { fn } from 'storybook/test'
import { Button } from './Button'

const meta = {
  component: Button,
  tags: ['autodocs'],  // generates a Docs page for this component
  args: {
    onClick: fn(),
  },
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger'],
      description: 'Visual style variant of the button',
      table: { defaultValue: { summary: 'primary' } },
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
      description: 'Button size affecting padding and font size',
      table: { defaultValue: { summary: 'md' } },
    },
  },
} satisfies Meta<typeof Button>

export default meta
type Story = StoryObj<typeof meta>

/** The default button style used for primary actions. */
export const Primary: Story = {
  args: { label: 'Click me', variant: 'primary' },
}

/** Secondary button for less prominent actions. */
export const Secondary: Story = {
  args: { label: 'Cancel', variant: 'secondary' },
}

/** Danger variant for destructive actions like delete. */
export const Danger: Story = {
  args: { label: 'Delete', variant: 'danger' },
}

// Button.tsx — JSDoc comments appear in autodocs
interface ButtonProps {
  /** Text displayed inside the button */
  label: string
  /** Visual style variant */
  variant?: 'primary' | 'secondary' | 'danger'
  /** Button size affecting padding and font size */
  size?: 'sm' | 'md' | 'lg'
  /** Click handler */
  onClick?: () => void
}

# .github/workflows/chromatic.yml — full snapshots every time
name: Chromatic
on: pull_request
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          # No TurboSnap — snapshots ALL stories on every PR
          # 500 stories × 3 viewports = 1500 snapshots per PR

# .github/workflows/chromatic.yml — TurboSnap enabled
name: Chromatic
on: pull_request
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # required for TurboSnap git comparison
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          onlyChanged: true  # enable TurboSnap
          externals: |
            - 'src/styles/**'
            - 'public/fonts/**'
          traceChanged: 'expanded'
          skip: 'dependabot/**'

// .storybook/main.ts — ensure correct build for TurboSnap
const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  framework: '@storybook/react-vite',
  // TurboSnap works automatically with Vite's module graph
}

// CSF2 pattern — no type inference, verbose
import { ComponentStory, ComponentMeta } from '@storybook/react'
import { Button } from './Button'

export default {
  title: 'Components/Button',
  component: Button,
} as ComponentMeta<typeof Button>

const Template: ComponentStory<typeof Button> = (args) => <Button {...args} />

export const Primary = Template.bind({})
Primary.args = {
  label: 'Click me',
  variant: 'primary',
  onClck: () => {},  // typo not caught — no type checking on args
}

// CSF3 pattern — full type inference via satisfies
import type { Meta, StoryObj } from '@storybook/react'
import { fn } from 'storybook/test'
import { Button } from './Button'

const meta = {
  component: Button,
  args: {
    onClick: fn(),  // fn() provides mock tracking
  },
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'danger'],
    },
  },
} satisfies Meta<typeof Button>

export default meta
type Story = StoryObj<typeof meta>

export const Primary: Story = {
  args: {
    label: 'Click me',
    variant: 'primary',
    // onClck: () => {},  // TypeScript ERROR — catches typo at compile time
  },
}

export const Secondary: Story = {
  args: {
    label: 'Cancel',
    variant: 'secondary',
  },
}

export const WithLongLabel: Story = {
  args: {
    label: 'This is a button with a very long label to test overflow',
    variant: 'primary',
  },
}

// No play function — behavior is only verified by opening Storybook and clicking manually
import type { Meta, StoryObj } from '@storybook/react'
import { LoginForm } from './LoginForm'

const meta = { component: LoginForm } satisfies Meta<typeof LoginForm>
export default meta
type Story = StoryObj<typeof meta>

export const SubmitForm: Story = {
  args: {
    onSubmit: () => console.log('submitted'),  // no mock tracking
  },
  // No play function — manual testing only
}

import type { Meta, StoryObj } from '@storybook/react'
import { expect, fn, userEvent, within } from '@storybook/test'
import { LoginForm } from './LoginForm'

const meta = {
  component: LoginForm,
  args: {
    onSubmit: fn(),
  },
} satisfies Meta<typeof LoginForm>

export default meta
type Story = StoryObj<typeof meta>

export const SubmitForm: Story = {
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement)

    // Simulate user filling out the form
    await userEvent.type(canvas.getByLabelText(/email/i), 'user@example.com')
    await userEvent.type(canvas.getByLabelText(/password/i), 'SecureP@ss1')
    await userEvent.click(canvas.getByRole('button', { name: /sign in/i }))

    // Assert the callback was called with form data
    await expect(args.onSubmit).toHaveBeenCalledWith({
      email: 'user@example.com',
      password: 'SecureP@ss1',
    })
  },
}

export const ValidationError: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement)

    // Submit empty form
    await userEvent.click(canvas.getByRole('button', { name: /sign in/i }))

    // Assert validation messages appear
    await expect(canvas.getByText(/email is required/i)).toBeVisible()
    await expect(canvas.getByText(/password is required/i)).toBeVisible()
  },
}

// Using vi.mock — leaks between stories, breaks isolation
import type { Meta, StoryObj } from '@storybook/react'
import { vi } from 'vitest'
import { UserProfile } from './UserProfile'

// This mock leaks to ALL stories in this file and potentially others
vi.mock('@/lib/api', () => ({
  fetchUser: vi.fn().mockResolvedValue({ name: 'John', role: 'admin' }),
}))

const meta = { component: UserProfile } satisfies Meta<typeof UserProfile>
export default meta
type Story = StoryObj<typeof meta>

export const AdminUser: Story = {}
export const RegularUser: Story = {}  // Still sees admin mock — no isolation

// .storybook/preview.ts — registration only, runs once at startup
import { sb } from '@storybook/test'

// Register modules to mock — use dynamic import(), not string paths
sb.mock(import('../src/lib/api'))

// UserProfile.stories.tsx
import type { Meta, StoryObj } from '@storybook/react'
import { expect, mocked, within } from '@storybook/test'
import { UserProfile } from './UserProfile'
import { fetchUser } from '@/lib/api'

const meta = {
  component: UserProfile,
} satisfies Meta<typeof UserProfile>

export default meta
type Story = StoryObj<typeof meta>

export const AdminUser: Story = {
  async beforeEach() {
    // mocked() accesses the spy registered in preview.ts
    mocked(fetchUser).mockResolvedValue({ name: 'John', role: 'admin' })
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement)
    await expect(canvas.getByText('Admin')).toBeVisible()
  },
}

export const RegularUser: Story = {
  async beforeEach() {
    mocked(fetchUser).mockResolvedValue({ name: 'Jane', role: 'user' })
  },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement)
    await expect(canvas.getByText('User')).toBeVisible()
  },
}

// Using deprecated test-runner — requires running Storybook server
// package.json
{
  "scripts": {
    "test-storybook": "test-storybook --url http://localhost:6006"
  },
  "devDependencies": {
    "@storybook/test-runner": "^0.17.0"  // deprecated in Storybook 9
  }
}

// Separate test config for Storybook — duplication
// test-runner-jest.config.js
module.exports = {
  testMatch: ['**/*.stories.*'],
  transform: { /* separate transform config */ },
}

// vitest.config.ts — stories run as native Vitest tests
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'
import { defineConfig } from 'vitest/config'

export default defineConfig({
  plugins: [storybookTest()],
  test: {
    setupFiles: ['./vitest.setup.ts'],
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
  },
})

// .storybook/main.ts — register the addon
import type { StorybookConfig } from '@storybook/react-vite'

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: [
    '@storybook/addon-vitest',
    '@storybook/addon-a11y',
  ],
  framework: '@storybook/react-vite',
}

export default config

// vitest.setup.ts — global setup for story tests
import '@testing-library/jest-dom/vitest'

import type { StorybookConfig } from '@storybook/react-vite'

const config: StorybookConfig = {
  stories: ['../src/**/*.stories.@(ts|tsx)'],
  addons: [
    '@storybook/addon-vitest',
    '@storybook/addon-a11y',
    '@storybook/addon-interactions',
    '@storybook/addon-themes',
    '@storybook/addon-viewport',
  ],
  framework: '@storybook/react-vite',
  docs: {
    autodocs: 'tag',  // generate docs for stories with 'autodocs' tag
  },
}

export default config

PR opened
├── Vitest (interaction + smoke)     ~2 min
│   ├── Stories with play() → interaction tests
│   ├── Stories without play() → smoke tests (render without error)
│   └── a11y addon → accessibility violations fail tests
├── Chromatic (visual regression)    ~3 min with TurboSnap
│   ├── TurboSnap → only changed stories snapshotted
│   ├── Visual diff review in Chromatic UI
│   └── Auto-accept on dependabot/renovate PRs
└── Lint + Type Check                ~1 min
    ├── ESLint with storybook plugin
    └── tsc --noEmit

name: Storybook CI
on:
  pull_request:
    branches: [main]

jobs:
  interaction-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx vitest --project=storybook --reporter=junit --outputFile=results.xml
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: test-results
          path: results.xml

  visual-regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          onlyChanged: true
          externals: |
            - 'src/styles/**'
            - 'public/fonts/**'

  a11y-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci
      - run: npx vitest --project=storybook --reporter=default
        env:
          STORYBOOK_A11Y_STRICT: 'true'

// CSF3 (recommended)
export const Primary: Story = {
  args: { label: 'Click me' },
}

npx storybook@latest migrate csf-2-to-3 --glob="src/**/*.stories.tsx"

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

import { sb } from '@storybook/test'
sb.mock(import('../src/api/client'), { spy: true })

import { mocked } from '@storybook/test'
import { fetchUser } from '../src/api/client'

export const WithUser: Story = {
  beforeEach: () => {
    mocked(fetchUser).mockResolvedValue({ id: '1', name: 'Test' })
  },
}

import type { Meta, StoryObj } from '@storybook/react'
import { ServerComponent } from './ServerComponent'

const meta = {
  component: ServerComponent,
  // RSC stories work without additional configuration in SB 10
} satisfies Meta<typeof ServerComponent>

// vitest.config.ts
import { storybookTest } from '@storybook/addon-vitest/vitest-plugin'

export default defineConfig({
  plugins: [storybookTest({ parallel: true })],
})

# 1. Upgrade
npx storybook@latest upgrade

# 2. Run codemods (handles most breaking changes)
npx storybook@latest automigrate

# 3. Verify
npm run storybook        # visual check
npx vitest               # run story tests
npx chromatic            # visual regression baseline

npm uninstall @storybook/test-runner
npm install -D @storybook/addon-vitest

// Before
import { action } from '@storybook/addon-actions'
args: { onClick: action('clicked') }

// After
import { fn } from '@storybook/test'
args: { onClick: fn() }

// Before (scattered imports)
import { action } from '@storybook/addon-actions'
import { within, userEvent } from '@storybook/testing-library'

// After (unified under @storybook/test)
import { fn, within, userEvent, expect } from '@storybook/test'