React Development

React Development

Critical rules

• Frameworks are adapters, not architectures — business logic and Views stay portable.
• No any, no as. No framework imports in components/, hooks/, lib/, or queries/.
• Container orchestrates data; View is prop-driven and framework-free.
• Use DI handlers (user actions) and optional deps (platform capabilities) — never routers in Views.
• Handle loading, error, empty, and offline. Accessibility is required (WCAG 2.1 AA baseline).
• Test what pays: domain logic and critical flows, not snapshots.
• Before Container/View examples, patterns, interactions, or Storybook setup, read the matching resource below.

Workflow

1. Split presentation from framework: View props + handlers; Container owns router/query.
2. Before choosing state mechanisms or Query/URL/form patterns, read references/patterns.md.
3. Choose the simplest state fit: React Query (server), URL/nuqs (shareable UI), useState/useReducer (local), Context (feature subtree), Zustand only after measuring.
4. Avoid prop drilling deeper than 3 levels; restructure or introduce context.
5. Enforce ESLint boundary rules so framework imports cannot leak into portable layers.
6. Before interaction/a11y polish, read references/interactions.md.
7. Add Storybook stories for main variants; before Storybook-first setup, read references/storybook.md.
8. For WRONG vs CORRECT Container/View and handlers/deps, read references/examples.md.

Resources

• references/examples.md — Container/View, handlers/deps, a11y WRONG/CORRECT. Read when implementing or reviewing.
• references/patterns.md — React Query, URL state, React 19, forms, hooks, folders, ESLint. Read before data/state work.
• references/interactions.md — keyboard, targets, forms, feedback, animation, a11y, performance. Read before polish.
• references/storybook.md — per-component stories, MSW, play functions. Read when adding stories.

Validation

• Presentational code has no framework imports; boundary ESLint passes
• Container/View split; DI handlers/deps for side effects
• URL state parsed once at boundary with Zod (or nuqs)
• React Query with a stable key factory
• Loading, error, empty states; skeletons match final layout
• Keyboard-operable; visible :focus-visible; hit targets ≥24px / ≥44px mobile
• Icon-only buttons have aria-label; prefers-reduced-motion respected
• Storybook covers main variants; tests only where they add value

Constraints

• Throwaway spikes may prototype first; then apply this architecture before shipping.
• Adjacent: storybook-journeys (page flows), ui-design-principles (visual), agent-browser (browser verify), testing-strategy, validation-boundary, fn-args-deps, strict-typescript.