1---2name: storybook-journeys3description: >-4 Authors Storybook journeys that document real user flows with MSW and5 meaningful states. Use this skill when building or reviewing Storybook stories6 for multi-step UX flows. Do not use when/for scaffolding a new testable7 component (use react-testable-storybookable) or live production browser8 automation (use agent-browser).9version: 1.2.010libraries: ["msw", "@storybook/test", "@storybook/addon-interactions", "storybook"]11---1213# Storybook Journeys1415## Critical rules1617- Journeys are products, not demos: mount real pages with real providers; MSW is the world; `play` is the script.18- Every journey needs ≥3 states: happy path, validation/client error, and server error / empty / edge.19- Prefer role/label queries; never brittle CSS selectors or fixed `setTimeout` delays.20- Centralize typed fixtures; small per-story MSW handlers — no live backends, no leaking globals.21- Story titles use product language (`Journeys/...`); page journeys use `layout: 'fullscreen'` by default.22- Before WRONG/CORRECT samples or folder/naming choices, read the matching resource below.2324## Workflow25261. Define journey boundary: entry screen, key actions, success criteria, error states.272. Before placing files or choosing storyboard shape, read [references/conventions.md](references/conventions.md).283. Build a minimal Journey Harness (router, theme, auth, query client, flags) if the page needs it.294. Add MSW handlers per story state (success, 403/500, slow/empty as relevant).305. Write CSF: mount page/harness; keep args sparse; a11y-friendly selectors.316. Add `play`: `userEvent` + `waitFor`; assert a meaningful end state on the happy path.327. Optionally wire Storybook Test Runner for headless CI.338. For WRONG vs CORRECT patterns, read [references/examples.md](references/examples.md).3435## Resources3637- [references/examples.md](references/examples.md) — journey vs atomic, fixtures, selectors. Read when authoring.38- [references/conventions.md](references/conventions.md) — folders, naming, storyboard options, defaults. Read when structuring.3940## Validation4142- [ ] Stories run offline via MSW43- [ ] Happy path `play` reaches a meaningful end state44- [ ] ≥1 error/edge story with distinct handlers45- [ ] Role/label queries only; fixtures centralized and typed46- [ ] `Journeys/…` naming; fullscreen layout for pages47- [ ] (If requested) Test Runner passes headless4849## Constraints5051- Atomic component variants belong in `react-development` / `react-testable-storybookable`, not here.52- Adjacent: `testing-strategy` (pyramid), `validation-boundary` / `result-types` (mock shapes), `ui-design-principles`, `agent-browser`, `fn-args-deps`, `observability`.
jagreehal