Narraitor: Skill for Claude Code

Storybook <-> app parity

1. Purpose

Storybook (ADR-012) is the canonical surface for what components should look like — and simultaneously the most common source of false confidence about how they behave. This skill defines the promotion ladder and the parity checks between tiers.

2. When to use

Storybook/app disagreements; authoring stories; reviewing "component is done" claims; promoting a component into a real route.

3. When not to use

• Pure visual-token drift within one surface → narraitor-debugging-playbook theming row.
• Deciding to ship a feature → narraitor-feature-experiment-lifecycle (parity is one of its gates).

4. Inputs required

The component, its stories (src/stories/), its real usage site(s), and the store slices it reads.

5. Procedure

The promotion ladder — a component holds exactly one status:

S0 renders-in-isolation-only   (story exists, mock props)        <- BLOCKING status
S1 mock-data-only              (story seeds stores via withStores; MSW answers /api) <- BLOCKING status
S2 integrated                  (works in the running app with real hydrated IndexedDB state)
S3 QA-verified                 (exercised in a real flow incl. failure paths; evidence recorded)

"Done" requires >= S2 with evidence; user-facing features require S3. S0/S1 are legitimate development states but BLOCK any done/integrated claim.

Parity checklist (run when promoting or when tiers disagree):

1. Prop/data parity — story args vs what the app actually passes. Diff the real call site, not the README.
2. State parity — withStores seed shape vs real store shape after hydration. Stores are NOT auto-reset between stories; a story can pass by leeching a previous story's seed. Seed every dependency explicitly.
3. Render parity — same state → same output. If not: environment differences (Next Image, fonts, themeInitScript, missing provider/context in the app tree).
4. Interaction parity — events update real stores in the app, not just Storybook actions. Click it in the app; watch the store slice change (IndexedDB db narraitor-state).
5. Network parity — MSW canned responses (.storybook/msw/handlers.ts) are happy-path only. The real route can return errors, malformed payloads, or take seconds (timeout ceiling 120s). Exercise loading/error/empty in the APP, not only as story variants.
6. Runtime semantics — hydration (component renders pre-hydration in the app; Storybook seeds synchronously so it never sees that window), App Router navigation (Storybook mocks the router as a logger), and multi-second AI latency.
7. Perf parity — no re-render storm in the app that Storybook's isolated tree hides (React DevTools profiler on the real route when the component subscribes to hot stores like narrativeStore).
8. Cross-context — light and dark (colorScheme toolbar in Storybook, narraitor-color-scheme in the app) + mobile viewport; for data components, >= 2 worlds/characters. There's one design system since ADR-013, so light/dark is the whole matrix.