Qa Storybook

---
name: qa-storybook
description: "[Testing] Storybook visual regression: baselines, responsive breakpoints, state variations, Atomic Design."
argument-hint: "component name | atoms | molecules | organisms | all"

---

# /qa-storybook — Storybook Component Testing

Test Storybook components for visual regression, responsive behavior, and state completeness. Delegates to **ui-ux-expert** agent with Chrome DevTools MCP.

## Usage
```
/qa-storybook Button               # Test a specific component
/qa-storybook atoms                 # Test all atom-tier components
/qa-storybook molecules             # Test all molecule-tier components
/qa-storybook organisms             # Test all organism-tier components
/qa-storybook all                   # Full visual regression run
```

## Supporting Files

- **tooling-stack.md** — SB 9 package map (`storybook/test`, `@storybook/addon-vitest`, a11y addon, Chromatic), determinism rules, CI gating, hosted-vs-dev caveat, boundary with `/qa-accessibility`. **Read first.**
- **play-function-patterns.md** — Canonical interaction-test patterns using `storybook/test` (`expect`, `userEvent`, `fn`, `step`); when `play` is the wrong tool.
- **how-to-test-storybook.md** — What to test per component (rendering, a11y, interactions, visual, composition, i18n, error boundaries); negative/edge scenarios.
- **visual-regression-testing.md** — Test case template for visual regression: baselines, state matrix, tool selection (Chromatic default, Playwright fallback), determinism rules.
- **responsive-component-testing.md** — Responsive testing across the DERIVED viewport sweep (`AUDIT_VIEWPORTS_PX` from `scripts/lib/design-tokens.generated.ts`, never a transcribed width list): layout adaptation, touch targets, text reflow, image scaling.

## Execution

1. **Resolve Storybook URL** from environment: `STORYBOOK_URL` (QA) or `STORYBOOK_DEV_URL` (dev)

2. **Identify target components:**
   - If component name: find matching stories in Storybook
   - If tier (atoms/molecules/organisms): test all components in that Atomic Design tier
   - Baselines captured on-demand and stored in test evidence directories

3. **Delegate to ui-ux-expert** via Task tool (`subagent_type: ui-ux-expert`):
   - Pass component name(s), Storybook URL, baseline directory
   - Agent uses Chrome DevTools MCP for screenshot capture
   - Agent reads supporting files from this skill folder for methodology

4. **For each component, test:**
   - All story variations (default, hover, focus, error, loading, disabled)
   - The derived viewport sweep (`AUDIT_VIEWPORTS_PX` — real ui-kit breakpoint edges, just-below, and fluid midpoints; see `responsive-component-testing.md` §Where the widths come from)
   - Compare against existing baselines if present
   - Flag pixel differences > threshold

5. **Output:**
   - Visual diff report with pass/fail per component/state/viewport
   - New baselines saved to test evidence directory (e.g., `reports/tickets/SprintXX-XX/VCST-XXXX/screenshots/`)
   - Summary: X components tested, Y passed, Z regressions found

## Rules
- Always capture all documented states, not just the default
- Use naming convention: `{story-name}-{viewport}.png`
- Baselines are captured on-demand — no persistent `storybook/` directory needed
- If no baseline exists, the first capture becomes the baseline
- Hosted Storybook is a **production build** — `import.meta.env.DEV === false`. Don't verify DEV-only warnings here (see `tooling-stack.md`).
- A11y assertions: on the **Coffee** and **Red** presets (the two WCAG-gated themes); visual diff still covers all themes. Select via `?globals=themePreset:red;darkMode:light` and confirm the preset applied (async import) before asserting.

## Boundary with `/qa-accessibility`
- `/qa-storybook` — a11y addon **inside stories** (component-isolated, axe rules per component).
- `/qa-accessibility` — full-page audits on storefront/admin (keyboard journeys, landmarks, page-level contrast).
- If a finding reproduces in a story, it belongs here. If it only appears once composed into a page, it belongs to `/qa-accessibility`.
- When you need a **programmatic** axe run on a rendered story (outside the addon — e.g. asserting against a specific story iframe), use the shared `axeRunSnippet()` + `classifyAxeResults()` from `scripts/lib/axe-runner.ts` so severity mapping and the "axe-unavailable ⇒ inconclusive, not clean" rule stay identical to `/qa-accessibility`. Visual pixel-diff stays with Chromatic / Playwright `toHaveScreenshot()` (the agent owns the "intentional change?" verdict); there is no JS-snippet differ.