Agent Skills: React Testable & Storybookable

React Testable & Storybookable

Critical rules

• A component may depend on props and injectable context only — never network, router, or an unoverridable global store.
• Testability and storybookability are the same property: shared fixtures, shared MSW, shared providers.
• Leaf/presentational stays props-only; push fetching into a thin container.
• Hooks surface explicit idle / loading / success / error; React Query uses a key factory.
• One MSW handler/fixture set backs Vitest, Storybook, and optional local mocks.
• Ship the trio: Component.tsx + Component.stories.tsx + Component.test.tsx.
• Export props types; type stories from them. QueryClient in tests has retry: false.
• Before scaffolding harness files or WRONG/CORRECT samples, read the matching resource below.

Workflow

1. Classify tier: leaf (props), container (hooks + providers), or provider/boundary.
2. Keep API/router out of the leaf; pass data and callbacks as props.
3. Before writing harness or MSW boilerplate, read references/scaffold.md.
4. Add renderWithProviders (theme, router, QueryClient with retries off) and shared fixtures/handlers with failure injection + store reset.
5. For containers that read context, add a test-only provider implementing the same state / actions / meta contract.
6. Scaffold the file trio: scripts/scaffold-component.sh <ComponentName> [target-dir] (see --help).
7. Stories: Default, Empty, Loading, Error; handlers via fn(). Import shared fixtures.
8. Wire Storybook preview with MSW + providers + a11y addon.
9. For WRONG/CORRECT prop, hook, and story patterns, read references/examples.md.

Resources

• references/examples.md — prop-driven, keys/hooks, MSW, trio, test provider. Read when implementing.
• references/scaffold.md — copy-paste harness: utils, MSW, providers, decorators. Read when setting up a project.
• scripts/scaffold-component.sh — generates the component/stories/test trio. Run with --help for usage; refuse overwrite.

Validation

• [ ] Leaf depends only on props + injectable context
• [ ] Explicit status / key factory for hooks
• [ ] Trio present; stories cover Default, Empty, Loading, Error with fn()
• [ ] Stories and tests share fixtures; containers use renderWithProviders + MSW
• [ ] QueryClient retry off; store reset between tests
• [ ] Storybook preview wires MSW + providers + a11y

Constraints

• Page-level flows belong in storybook-journeys. Visual tokens in ui-design-principles. Architecture baseline in react-development.
• Adjacent: result-types, testing-strategy, validation-boundary. Prefer composition patterns over boolean-prop sprawl.