`s means re-implementing all of it, badly. 4. **Users are on worse devices and worse networks than you are.** Assume a mid-range phone on a congested network until measurement proves otherwise. --- ## 2. Component design ### 2.1 Size and responsibility - **Split a component when it has two reasons to change**, not when it hits a line count. A 300-line form that renders one form is fine. A 60-line component that both fetches data and formats currency is not. - **Separate "what it looks like" from "where the data comes from."** A presentational component takes data as input and emits events; a container fetches, mutates, and routes. This is what makes components testable without a network, and reusable in a second context. ```jsx // Presentational: no fetching, no routing, no globals. Trivially testable. function InvoiceRow({ invoice, onMarkPaid }) { … } // Container: knows about the world. function InvoiceRowContainer({ id }) { const { data } = useInvoice(id); const markPaid = useMarkPaid(); return markPaid(id)} />; } ``` - **Do not create an abstraction until the third use.** Two similar components are cheaper than one component with a `variant` prop, a `mode` prop, and four booleans. Premature component abstraction is the most common source of unmaintainable UI code. - **Never add a boolean prop that changes layout structure.** `isCompact`, `isModal`, `showHeader`. Past two of these, the component is really several components sharing a file. Split it. ### 2.2 Props and interfaces - **Make illegal states unrepresentable in the prop types.** Prefer a discriminated union over independent booleans: ```ts // Bad: isLoading && error && data is representable and meaningless. type Props = { isLoading: boolean; error?: Error; data?: User }; // Good: exactly one shape is valid at a time. type Props = | { status: 'loading' } | { status: 'error'; error: Error } | { status: 'ready'; data: User }; ``` - **Pass data, not accessors.** `` over `` when the parent already has the user. The second forces a second fetch or a global lookup and couples a leaf component to your data layer. - **Name event props for what happened, not what to do.** `onSubmit`, `onRowSelect`, `onDismiss`, not `handleClick` or `doSave`. The child reports; the parent decides. - **Default to the safe value.** A `dangerouslyAllowHtml`-style prop must default to off; a `confirmBeforeDelete` prop must default to on. ### 2.3 Composition over configuration Prefer slots/children to a growing config object. ```jsx // Configuration: every new need adds a prop, forever. // Composition: the card owns layout, the caller owns content. ``` The test: if adding one more visual variant requires editing the shared component, the API is configuration and it will keep growing. --- ## 3. State management ### 3.1 Classify state before choosing where to put it There are five kinds. Most state bugs come from putting one kind in the container meant for another. | Kind | Example | Where it belongs | |---|---|---| | **Server state** | Fetched user, product list | A data-fetching cache (React Query, SWR, Apollo, RTK Query). Never hand-rolled in a global store. | | **URL state** | Current page, filters, tab, search query, opened detail id | The URL. It is shareable, bookmarkable, and survives reload for free. | | **Local UI state** | Dropdown open, input draft, hover | `useState` in the component that owns it. | | **Shared UI state** | Theme, sidebar collapsed, toast queue | Context or a small global store. Small, serializable, rarely written. | | **Form state** | Field values, dirty, errors | A form library or a single reducer, not N `useState` calls. | - **Anything a user would expect to survive a refresh or be shareable via link belongs in the URL.** Filters, sort order, pagination, active tab, selected entity. This one rule eliminates a whole class of "why did my state reset" bugs and makes deep-linking free. - **Server state is not application state.** It is a cache of something you do not own. It needs staleness, revalidation, deduplication, and invalidation, which is exactly what a data-fetching library gives you and what a global store does not. Putting fetched data into Redux/Pinia/Zustand by hand means reimplementing cache invalidation manually. ### 3.2 Placement and derivation - **Lift state to the lowest common ancestor, and no higher.** State lifted too far causes re-renders across unrelated subtrees and makes components impossible to reuse. - **Derive, don't sync.** If `fullName` can be computed from `firstName` and `lastName`, compute it during render. Every `useEffect` that writes state in response to other state is a bug in waiting: two sources of truth that will drift. ```js // Bad: an extra render, and a window where the two disagree. useEffect(() => { setTotal(items.reduce(sum, 0)); }, [items]); // Good. const total = items.reduce(sum, 0); ``` - **Reach for a reducer when transitions have rules.** Multiple fields that must change together, or actions only legal in certain states, belong in a reducer or state machine, not scattered `setX` calls whose ordering is load-bearing. ### 3.3 Effects `useEffect` (and equivalents) is for **synchronizing with something outside the component system**: the DOM, a subscription, a timer, an analytics SDK. It is not a lifecycle hook. Do not use an effect to: - transform data for rendering → compute during render - reset state when a prop changes → change the component `key` instead - handle a user event → put the logic in the event handler - fetch data → use a data-fetching library, or the framework's loader/server component **Every effect that subscribes must unsubscribe.** Timers, listeners, observers, sockets, and in-flight requests all need teardown. A component that mounts and unmounts a thousand times must leave nothing behind. ```js useEffect(() => { const controller = new AbortController(); fetchThing({ signal: controller.signal }).then(setThing).catch(ignoreAbort); return () => controller.abort(); // ← not optional }, [id]); ``` **Guard against out-of-order responses.** If `id` changes fast, response 1 can land after response 2. Abort the previous request, or check that the result still matches the current input before committing it. --- ## 4. Data fetching and async UI - **Handle all four states, always.** Idle, loading, error, empty-success. "Empty" is a distinct design problem: zero results needs different copy than zero-ever-created. - **Show skeletons that match the final layout**, not a centered spinner that collapses to content. Matching skeletons eliminate layout shift and read as faster. - **Never render a spinner for under ~200ms of work.** A flash of loading state is worse than a brief pause. Delay the indicator. - **Make errors recoverable.** Every error state needs a retry affordance and text that says what the user can do. "Something went wrong" with no action is a dead end. - **Distinguish error kinds.** Network failure (retry), 401 (re-authenticate), 403 (you cannot do this), 404 (gone), 422 (fix your input), 5xx (our fault, retry later). They need different UI. - **Prevent double-submit at the source.** Disable the trigger while a mutation is in flight and make the handler idempotent. Users double-click; slow networks make it worse. - **Optimistic updates require a rollback path.** Apply the change locally, and on failure restore the previous value *and* tell the user it failed. An optimistic update with no rollback silently lies about persisted data. - **Cancel in-flight requests on unmount and on input change.** Especially search-as-you- type, which should also be debounced (~250–300ms), with the trailing call guaranteed. - **Paginate or virtualize anything unbounded.** Any list that can grow with usage, such as results, feeds, logs, or notifications, needs a limit. Rendering 10,000 rows freezes the main thread regardless of framework. --- ## 5. Forms Forms are where most real UI complexity lives. They deserve deliberate design. - **Use a native `

` with a submit handler.** This gives you Enter-to-submit, implicit submission, autofill, and the browser's own validation semantics. A `

` with a clickable button gives you none of these. - **Validate on the right event.** On blur for the first pass, on change *after* a field has already errored (so the error clears as they fix it), and always on submit. Validating on every keystroke before the user has finished typing is hostile. - **Server validation is authoritative; client validation is a courtesy.** Mirror the rules for fast feedback, but always re-check server-side. The client can be bypassed entirely. See `security-practices` §4. - **Map server field errors back to their fields.** An API returning `{ errors: { email: "already taken" } }` should surface next to the email input, not in a generic banner. Design the error contract for this (see `backend-practices` §4). - **Render every error for a field, not just the first.** A password failing three rules should say so once, not send the user through three round trips. Component libraries that show a single message per field usually need this behaviour turned off explicitly. - **Never clear a user's input on failure.** Retaining what they typed is the difference between an annoyance and a lost form. - **Disable submit while submitting, not while invalid.** A permanently disabled button with no explanation is a dead end. Let them submit and show them what's wrong. - **Associate every input with a ``** via `htmlFor`/`id` or wrapping. Placeholders are not labels: they vanish on focus, fail contrast, and are skipped by some screen readers. - **Wire up autocomplete and input types.** `type="email"`, `inputmode="numeric"`, `autocomplete="one-time-code"`, `autocomplete="new-password"`. These change the mobile keyboard and enable password-manager integration: cheap, high-impact. - **Warn before discarding unsaved changes** on navigation away from a dirty form. --- ## 6. Accessibility Not optional, not a phase-two item, and in many jurisdictions a legal requirement. The majority of the value comes from a small number of rules. ### 6.1 Semantics - **Use the correct element.** `