Guides React component architecture, state management, and engineering discipline. Use when building React components, designing component architecture, implementing state management, or reviewing UI code structure. For design quality (typography, color, spacing, anti-patterns), see the design-setup skill.
Disciplined React component architecture — file structure, state management, prop boundaries, and loading/error/empty state coverage.
File structure — colocate tests, hooks, and types with components:
src/components/
TaskList/
TaskList.tsx # Component
TaskList.test.tsx # Tests
use-task-list.ts # Custom hook (if complex logic)
types.ts # Component-specific types
Rules:
Is the state used by only this component?
→ useState
Shared between 2-3 siblings?
→ Lift to parent
Read-heavy, rarely written (theme, auth, locale)?
→ Context
Derived from URL (filters, pagination, sort)?
→ URL state (searchParams)
Remote data with caching needs?
→ Server state (React Query, SWR)
Complex client state used app-wide?
→ Global store (Zustand, Redux) — last resort
For typography, color, spacing, accessibility depth, and AI anti-pattern avoidance — see the design-setup skill. Run /design-review for a scored design audit.
aria-busy="true" on loading containers| Rationalization | Reality |
|---|---|
| "Accessibility is nice-to-have" | It's a legal requirement in many jurisdictions and a quality signal. |
| "We'll make it responsive later" | 3x harder to retrofit. Mobile-first from the start. |
| "This component is too small to need its own test" | Small components are the easiest to test. No excuse to skip. |
| "We don't need empty states yet" | Users hit empty states on first use. It's the first impression. |
After implementing UI: