/react-code

name: react-code
description: Applies GAIA's patterns and conventions for writing and editing React components and hooks. Use this skill whenever writing or reviewing React components, hooks, or event handlers, or deciding on component extraction. Also trigger when deciding whether a manual memo or "use no memo" is justified under React Compiler, debugging stale closures or infinite re-renders, weighing a new dependency against a web-platform API or a hand-rolled primitive, choosing a React 19 idiom, or reaching for React's form Actions instead of React Router's form handling.

React Code

Write and edit React components, pages, routes, hooks, and forms following project conventions.

Contents: Reach for the Platform First; Pre-Flight Gates; Memoization: compiler-first; Component Structure; Data Loading; Route-Page Architecture; References.

Reach for the Platform First

Before installing a package or hand-rolling a primitive, follow the reuse order in Simplicity First (`.claude/rules/coding-guidelines.md`). On the frontend:

• **Existing project code** covers form inputs (Gate 2); a project component wins over a native element, since a wrapper exists for a reason.
• **Web platform** means a browser API or native element (`Intl`, `URL`, `structuredClone()`, `<dialog>`, modern CSS).
• **Installed dependency:** for component/hook traps Claude often hand-rolls (client-only/useHydrated, sse, debounce-fetcher), see the remix-utils decision map at `wiki/dependencies/remix-utils.md` before reinventing.

Pre-Flight Gates

Run each gate when its pattern appears in your changes.

Gate 1: Hook Check

**Before writing `useEffect`:** decide whether it should be an Effect at all. Lint (`react-you-might-not-need-an-effect`) reports the ones that should not: state derived from props or state, user-event logic, chained updates, notifying a parent, and resetting state on a prop change. An Effect is right when it synchronizes with an external system (browser API, third-party widget, network). Add cleanup (a fetch aborts its `AbortController`; a client that cannot cancel uses an `ignore` flag: `references/hook-patterns.md`).

**Before writing `useMemo`, `useCallback`, or `memo`:** don't; see `## Memoization: compiler-first`.

**`useState`:** for an absent initial value, prefer `undefined` over `null` (never-null convention): `useState<T>()` is already typed `T | undefined`.

Gate 2: Form Element Check

**Before writing `<input>`, `<select>`, `<textarea>`, or `<input type="checkbox">`:**

| Native element | Use instead (`~/components/ui/...`) | | -------------------------------------- | ------------------------------------------------------------------------------------ | | `<input type="text">` (any text type) | `Input` (`input`) | | `<input type="checkbox">` | `Checkbox` (`checkbox`); a group is one `Checkbox` per option in a `FieldSet` | | `<input type="radio">` / radio group | `RadioGroup` and `RadioGroupItem` (`radio-group`) in a `FieldSet` | | `<select>` | `NativeSelect` and `NativeSelectOption` (`native-select`) | | `<textarea>` | `Textarea` (`textarea`) | | `<label>` | `FieldLabel` (`field`), or `Label` (`label`) outside a `Field` | | Field with label + error + description | `ConformField` around the ui control; a group uses the `field` parts | | `<button>` | `Button` (`button`) |

**Exceptions (native OK):** `<input type="hidden">`, `<input type="file">`, `<input type="range">`.

A raw ui control carries no label or error wiring. Put a single form control in `ConformField` and compose a group, as `references/conform-forms.md` shows (one pattern per control type). Render options from an array with `.map`.

**CRITICAL, `@conform-to/zod`:** Always import from `/v4` subpath. The default export targets Zod v3 and causes a runtime error that typecheck and build do NOT catch (lint flags the bare import).

// BAD, runtime error
import {parseWithZod} from '@conform-to/zod';
// GOOD
import {parseWithZod} from '@conform-to/zod/v4';

See `references/conform-forms.md` for full Conform + Zod wiring. Beyond the import path, all Zod schemas use Zod 4 syntax, `wiki/dependencies/Zod.md` is the canonical Zod 3 → Zod 4 migration map (`z.strictObject`, top-level string formats, etc.).

Gate 3: Translation Check

**Before writing ANY user-visible string in JSX:**

Every string a user can see or hear, including `aria-label`, `alt`, `title` and placeholder attributes, must come from a `t()` call. Lint (`i18next/no-literal-string`) reports raw JSX text but not attributes, so `aria-label`, `alt`, `title`, and placeholders are yours to check. This applies to new components, new UI sections, and modifications that add visible text. The only exceptions are punctuation-only strings, single-character symbols, developer-facing content (console.log, comments, test assertions), and approximate skeleton-loader placeholder text standing in for a dynamic runtime value. Skeleton text that mirrors static `t()` content must still use `t()` (see the skeleton-loaders skill).

1. Add the translation key to the appropriate namespace file in `app/languages/en/` (and any other locale folders present, copying the English string verbatim as a placeholder) 2. Use `t('key')` in the component, never a string literal 3. **One `useTranslation()` per component**: never multiple calls for different namespaces 4. Use `{ns: 'other'}` as second arg to `t()` for cross-namespace access 5. Choose the most-used namespace for `useTranslation()` to m