react-conventions

React Conventions

Imported from Kevin's wiki (wiki/style/react.md). Cross-reference: sigil-conventions.mdc (component rules), sigil-design-system.mdc (token consumption), css-ui-enforcement.mdc (styling stack).

Styling

All UI via className={cn(...)} and Tailwind utilities. No CSS modules or co-located .css for normal components. Raw CSS belongs almost only in globals.css. Do not combine style={{ ... }} with Tailwind on the same node. See css-ui-enforcement.mdc.

Rules of Hooks

Hooks are identified by position in an array. Call order must be identical on every render.

• Hooks at the top level of a component or custom hook only.
• Before any conditional logic.
• No hooks inside conditions, loops, event handlers, callbacks passed to useMemo/useReducer/useEffect, or after early returns.
• Most common violation: early return before hooks. Move hooks above the conditional.

Custom Hooks

Name the hook after what it returns, not what it does internally. useOrgData > useFetchAndCacheOrgDataWithLoading.

Exhaustive Dependencies

useEffect, useMemo, useCallback dependency arrays must include every referenced value. Missing dependencies cause stale closures. If adding a dependency causes an infinite loop, restructure (extract to ref, memoize the dependency, move to event handler) — do not suppress the warning.

setState in Effects

The React compiler flags synchronous setState inside effect bodies. Canonical alternative: useSyncExternalStore. Migrate incrementally.

Linting Rules (Ultracite/oxlint)

Rule	Severity	Notes
react-hooks/rules-of-hooks	error	Non-negotiable, never disable
react-hooks/exhaustive-deps	warn	Fix stale closures, do not suppress
react/self-closing-comp	error	<Foo /> not <Foo></Foo>
react/jsx-curly-brace-presence	error	No {"text"} when text suffices

Architecture-Policy Rules

Custom ESLint rules for repo-specific patterns that oxlint cannot express: