# Storybook Journeys

> 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).

- Skill: `jagreehal/storybook-journeys` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jagreehal/storybook-journeys`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/storybook-journeys/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/storybook-journeys

---


# Storybook Journeys

## Critical rules

- Journeys are products, not demos: mount real pages with real providers; MSW is the world; `play` is the script.
- Every journey needs ≥3 states: happy path, validation/client error, and server error / empty / edge.
- Prefer role/label queries; never brittle CSS selectors or fixed `setTimeout` delays.
- Centralize typed fixtures; small per-story MSW handlers — no live backends, no leaking globals.
- Story titles use product language (`Journeys/...`); page journeys use `layout: 'fullscreen'` by default.
- Before WRONG/CORRECT samples or folder/naming choices, read the matching resource below.

## Workflow

1. Define journey boundary: entry screen, key actions, success criteria, error states.
2. Before placing files or choosing storyboard shape, read [references/conventions.md](references/conventions.md).
3. Build a minimal Journey Harness (router, theme, auth, query client, flags) if the page needs it.
4. Add MSW handlers per story state (success, 403/500, slow/empty as relevant).
5. Write CSF: mount page/harness; keep args sparse; a11y-friendly selectors.
6. Add `play`: `userEvent` + `waitFor`; assert a meaningful end state on the happy path.
7. Optionally wire Storybook Test Runner for headless CI.
8. For WRONG vs CORRECT patterns, read [references/examples.md](references/examples.md).

## Resources

- [references/examples.md](references/examples.md) — journey vs atomic, fixtures, selectors. Read when authoring.
- [references/conventions.md](references/conventions.md) — folders, naming, storyboard options, defaults. Read when structuring.

## Validation

- [ ] Stories run offline via MSW
- [ ] Happy path `play` reaches a meaningful end state
- [ ] ≥1 error/edge story with distinct handlers
- [ ] Role/label queries only; fixtures centralized and typed
- [ ] `Journeys/…` naming; fullscreen layout for pages
- [ ] (If requested) Test Runner passes headless

## Constraints

- Atomic component variants belong in `react-development` / `react-testable-storybookable`, not here.
- Adjacent: `testing-strategy` (pyramid), `validation-boundary` / `result-types` (mock shapes), `ui-design-principles`, `agent-browser`, `fn-args-deps`, `observability`.