React Frontend

Verify before implementing: For App Router patterns, React 19 APIs, or version-specific behavior, look up current docs (Context7 query-docs if available, else the framework's official docs via web search) before writing code. Training data may lag current releases.

Working rules

• Keep derived state in render and user actions in event handlers; use effects for external synchronization.
• Give async work a lifecycle and cancellation policy; represent failure separately from pending and empty data.
• Preserve focus when hiding interactive regions and exercise keyboard navigation in a real browser.
• Validate and authorize every public server action; send only needed fields across server/client boundaries.
• Measure performance changes and test user-visible behavior, not type-checking alone.

Effects Decision Tree

Effects are escape hatches -- most logic should NOT use effects.

Effect rules:

• Never suppress the linter -- fix the code instead
• Use updater functions (setItems(prev => [...prev, item])) to remove state dependencies
• Move objects/functions inside effects to stabilize dependencies
• useEffectEvent for non-reactive values (e.g., theme in a connection effect)
• Always return cleanup for subscriptions, connections, listeners
• Data fetching cancellation (pick by situation): AbortController for fetch; ignore flag for non-cancellable promises; React Query handles both automatically

Discipline

• Simplicity first -- every change as simple as possible, impact minimal code
• Only touch what's necessary -- avoid introducing unrelated changes
• No hacky workarounds -- if a fix feels wrong, step back and implement the clean solution
• Before adding a new abstraction, verify it appears in 3+ places

References

• [testing.md](./references/testing.md) -- Component, hook, and mocking test examples
• [e2e-testing.md](./references/e2e-testing.md) -- Playwright E2E patterns

Verify

• TypeScript compiles with zero errors
• No suppressed lint rules (eslint-disable, @ts-ignore) in new code
• useEffect dependency arrays not manually overridden
• No forwardRef usage in React 19+ projects (use ref prop directly)

Task-specific references

Read the relevant reference before implementing or reviewing the matching behavior:

• For component types, state ownership, async races, focus, or cached query behavior: [components-and-state.md](./references/components-and-state.md).
• For performance, React APIs, Next.js boundaries, caching, or Tailwind integration: [rendering-and-frameworks.md](./references/rendering-and-frameworks.md).
• For component, hook, browser, or integration test changes: [test-selection.md](./references/test-selection.md).

Existing specialized references, when the corresponding topic applies: