Requirements

Always use destructured props in function parameters
Define TypeScript types inline with the destructured props
Avoid creating separate interfaces for component props
Avoid non-destructured props that require additional destructuring inside the component
Use available UI components from the component library
Use CSS variables from globals.css for consistent theming
Use Tailwind v4 syntax (see Tailwind v4 Syntax)
DO NOT add icon margin in Button, DropdownMenuItem: use gap-2 instead
Use useEffectEvent to extract non-reactive logic from Effects (see Separating Events from Effects)
NEVER suppress the dependency linter with eslint-disable - use useEffectEvent instead
Use custom breakpoint syntax for responsive design (see )

<example> ```tsx // ✅ Good - Let the compiler optimize function ExpensiveComponent({ data, onClick }) { const processedData = expensiveProcessing(data); <div> {processedData.map(item => ( <Item key={item.id} onClick={() => handleClick(item)} /> ))} </div> ); } <example> ```tsx // ✅ Good - Simple event handler function TodoList({ todos, onToggle }) { const handleToggle = (id) => { onToggle(id); }; <ul> {todos.map(todo => ( <TodoItem key={todo.id} todo={todo} onToggle={() => handleToggle(todo.id)} /> ))} </ul> ); } <example> ```tsx // ✅ Good - The compiler can memoize after early returns function ThemeProvider({ children, theme }) { if (!children) { return null; } <example> ```tsx // ✅ Acceptable - useMemo for effect dependency control function DataFetcher({ filters }) { // Documented reason: Prevent effect from re-running when filters object // reference changes but values remain the same const stableFilters = useMemo( () => ({ ...filters }), [filters.category, filters.status, filters.dateRange] ); <example> ```tsx // ❌ Anti-pattern: useState + useEffect for derived data function FilteredList({ items, filter }) { const [filtered, setFiltered] = useState([]); </example> <example> ```tsx // ❌ Invalid: Reading ref during render function Component() { const ref = useRef(0); const value = ref.current; // Don't read during render! return <div>{value}</div>; } </example> <example type="invalid"> ```tsx // ❌ Avoid - deriving state and triggering events inside an Effect function ProductPage({ product }: Props) { const [isInCart, setIsInCart] = useState(false); </example> <example> ```tsx // ❌ Without useEffectEvent - Reconnects on theme change function ChatRoom({ roomId, theme }) { useEffect(() => { const connection = createConnection(serverUrl, roomId); connection.on('connected', () => { showNotification('Connected!', theme); // Makes Effect reactive to theme }); connection.connect(); return () => connection.disconnect(); }, [roomId, theme]); // ❌ Unnecessary reconnection </example> <example> ```tsx // ❌ Suppressing linter creates stale closure function Component() { const [canMove, setCanMove] = useState(true); </example> <example type="invalid"> ```tsx // ❌ WRONG - Passing Effect Event as prop function Component() { const handleClick = useEffectEvent(() => { // ... }); </example> <critical> - Use Effect Events to separate reactive and non-reactive logic in Effects - Effect Events always see latest props/state without causing Effect re-runs - NEVER suppress dependency linter - use useEffectEvent instead - Only call Effect Events from inside Effects, never pass to other components or as props - **Dual-use pattern**: If a function is needed in BOTH props/handlers AND Effects, create TWO versions: regular function for props, Effect Event wrapper for Effects - Pass reactive values as arguments to Effect Events for clarity - Common patterns: event listeners with current state, notifications with current theme, analytics with current context, keyboard shortcuts that need latest state </critical> <example> ```tsx // ✅ Good - Clean iteration function ProductList({ products, onAddToCart }) { return ( <div> {products.map(product => { const discountedPrice = product.price * (1 - product.discount);

### Red Flags - STOP Before "Fixing" If you're about to: - Replace `useState + useEffect` with `useMemo` that reads `ref.current` → STOP - Add `eslint-disable` for either rule → STOP, use decision tree - "Fix" one error and immediately get the other → STOP, you're cycling ### Rationalization Table | Excuse | Reality | |--------|---------| | "useMemo fixes derived state" | Only if you don't read refs during render | | "I'll read ref in useMemo since it runs during render" | useMemo IS render. Ref rules still apply. | | "Effect was the problem" | Maybe, but check if you're now violating ref rules | | "This is simple, I know what to do" | The cycle happens because you skip the decision tree | ### Cleanup and Strict Mode - Always return a cleanup when the Effect allocates resources (connections, listeners, timers). React calls cleanup before re-running the Effect and on unmount. - Expect every Effect to mount → cleanup → mount in development. Production runs once, but development ensures your Effect is resilient. - Avoid side-stepping cleanup by storing mutable singletons in refs. This leaves background work running across navigations and breaks invariants. ### React Compiler Considerations - Because the compiler stabilizes values for you, do not introduce `useMemo`/`useCallback` purely to satisfy Effect dependency linting. Refactor the Effect so it depends on real inputs. - Let the dependency array express actual inputs. Suppressing ESLint warnings or omitting deps makes compiler output unreliable. - Prefer custom hooks (`useData`, `useOnlineStatus`) to bundle complex Effect logic once. This keeps call sites simple and lets the compiler optimize the hook body. <example> ```tsx // ✅ Effect that syncs with an external API and cleans up export function VideoPlayer({ src, isPlaying }: Props) { const ref = useRef<HTMLVideoElement | null>(null); useEffect(() => { const node = ref.current; if (!node) { return; } if (isPlaying) { void node.play(); } else { node.pause(); } return () => { node.pause(); }; }, [isPlaying]); return <video ref={ref} src={src} playsInline loop />; }

This mixes reactive synchronization with event-driven logic. Use `useEffectEvent` if you need to read current props without re-running the Effect. See [Separating Events from Effects](#separating-events-from-effects). </example> <critical> - **Derived data**: Compute inline during render. No useState + useEffect. - **External systems**: setState in Effect IS valid (DOM, browser APIs, subscriptions). - **Refs**: Never read/write during render (except lazy init). Read in Effects/handlers. - **Resources with cleanup**: useMemo for creation, useEffect for cleanup. - Use Effects only for external synchronization; keep render pure and events in handlers. - Always implement cleanup so mount → cleanup → mount cycles behave correctly. - Do not fight dependency linting with manual memoization; rely on actual inputs. </critical> ## Separating Events from Effects ### Principle Event handlers and Effects serve different purposes in React: - **Event handlers**: Run in response to specific user interactions. Non-reactive logic. - **Effects**: Run when synchronization with external systems is needed. Reactive to dependencies. - **Effect Events** (`useEffectEvent`): Extract non-reactive logic from Effects when you need both behaviors. ### Choosing Between Event Handlers and Effects Ask: "Does this run because of a specific interaction, or because the component needs to stay synchronized?" <example> ```tsx // ✅ Good - Combines both patterns appropriately function ChatRoom({ roomId }) { const [message, setMessage] = useState(''); // Event handler: runs on user click function handleSendClick() { sendMessage(message); } // Effect: keeps connection synchronized with roomId useEffect(() => { const connection = createConnection(serverUrl, roomId); connection.connect(); return () => connection.disconnect(); }, [roomId]); return ( <> <h1>Welcome to the {roomId} room!</h1> <input value={message} onChange={e => setMessage(e.target.value)} /> <button onClick={handleSendClick}>Send</button> </> ); }

React

React

Requirements

Tailwind v4 Syntax

Component Patterns

Design Tokens

Variable Architecture

Data Attribute Styling Patterns

Styling with data-state

Radix UI Data Attributes

Common State Patterns

Using data-slot for Component Targeting

Global CSS with data-slot

data-slot Naming Conventions

When to Use Data Attributes vs Props

React Compiler

Context

Core Principle

Requirements

DO NOT Use Manual Memoization

When Manual Memoization IS Acceptable

Examples

Component Memoization

Event Handlers

Computed Values

Conditional Memoization

Acceptable Use Case: Effect Dependencies

Effects

Principle

When to Add an Effect

When Not to Add an Effect

Derived State: Compute During Render, Not in Effects

Ref Access Rules

Reactive Values and Reactive Logic

Extracting Non-Reactive Logic with useEffectEvent

Critical Rules and Limitations

Common Patterns

Lists and Iteration

Extract Errors

Frontend Patterns

Coding Standards

Coding Standards

Coding Standards

Frontend Patterns