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.
• Bind cache keys to the request's identity. A tenant-scoped key can receive another tenant's response when server session state changes first. Keep request scope and cache identity consistent throughout context switches. Verify isolation with mounted consumers, in-flight requests, and failed refetches.
• 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. With React Query, pass the query function's signal to the transport, such as queryFn: ({ signal }) => fetch(url, { signal }). Without consuming that signal, an unused query can finish and populate the cache; do not describe that behavior as transport cancellation.
• A settled request is not completed initialization. Consume a one-time initialization latch only after applying usable data or observing a successful terminal empty result. Test empty-then-populated responses within one mount. Verify that later refetches preserve user edits.

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: Component, hook, and mocking test examples
• 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.
• For performance, React APIs, Next.js boundaries, or caching: rendering-and-frameworks.md.
• For Tailwind CSS: utilities, @theme tokens, CVA/tailwind-variants, dark mode, v3-to-v4 migration, or overflow and hidden pitfalls: tailwind.md.
• For component, hook, browser, or integration test changes: test-selection.md.
• For synchronizing JSON locale files or reviewing translations: locale-synchronization.md.

Existing specialized references, when the corresponding topic applies:

• Tailwind details behind tailwind.md: tailwind-configuration.md, tailwind-v3-to-v4.md, tailwind-class-composition.md, tailwind-component-patterns.md, tailwind-layout-patterns.md.