1---2name: storybook-journeys3description: Authors Storybook journeys that document real user flows with MSW and meaningful states. Use this skill when building or reviewing Storybook stories for multi-step UX flows. Do not use when/for scaffolding a new testable component (use react-testable-storybookable) or live production browser automation (use agent-browser).4---56# Storybook Journeys78## Critical rules910- Journeys are products, not demos: mount real pages with real providers; MSW is the world; `play` is the script.11- Every journey needs ≥3 states: happy path, validation/client error, and server error / empty / edge.12- Prefer role/label queries; never brittle CSS selectors or fixed `setTimeout` delays.13- Centralize typed fixtures; small per-story MSW handlers — no live backends, no leaking globals.14- Story titles use product language (`Journeys/...`); page journeys use `layout: 'fullscreen'` by default.15- Before WRONG/CORRECT samples or folder/naming choices, read the matching resource below.1617## Workflow18191. Define journey boundary: entry screen, key actions, success criteria, error states.202. Before placing files or choosing storyboard shape, read [references/conventions.md](references/conventions.md).213. Build a minimal Journey Harness (router, theme, auth, query client, flags) if the page needs it.224. Add MSW handlers per story state (success, 403/500, slow/empty as relevant).235. Write CSF: mount page/harness; keep args sparse; a11y-friendly selectors.246. Add `play`: `userEvent` + `waitFor`; assert a meaningful end state on the happy path.257. Optionally wire Storybook Test Runner for headless CI.268. For WRONG vs CORRECT patterns, read [references/examples.md](references/examples.md).2728## Resources2930- [references/examples.md](references/examples.md) — journey vs atomic, fixtures, selectors. Read when authoring.31- [references/conventions.md](references/conventions.md) — folders, naming, storyboard options, defaults. Read when structuring.3233## Validation3435- [ ] Stories run offline via MSW36- [ ] Happy path `play` reaches a meaningful end state37- [ ] ≥1 error/edge story with distinct handlers38- [ ] Role/label queries only; fixtures centralized and typed39- [ ] `Journeys/…` naming; fullscreen layout for pages40- [ ] (If requested) Test Runner passes headless4142## Constraints4344- Atomic component variants belong in `react-development` / `react-testable-storybookable`, not here.45- Adjacent: `testing-strategy` (pyramid), `validation-boundary` / `result-types` (mock shapes), `ui-design-principles`, `agent-browser`, `fn-args-deps`, `observability`.
jagreehal