// Use when writing any React documentation. Provides voice, tone, and style rules for all doc types.
Use when adding interactive RSC (React Server Components) code examples to React docs using <SandpackRSC>, or when modifying the RSC sandpack infrastructure.
Use when creating new React documentation pages or updating existing ones. Accepts instructions like "add optimisticKey reference docs", "update ViewTransition with Activity", or "transition learn docs".
Comprehensive MDX component patterns (Note, Pitfall, DeepDive, Recipes, etc.) for all documentation types. Authoritative source for component usage, examples, and heading conventions.
Use when adding interactive code examples to React docs.
Use when writing or editing files in src/content/blog/. Provides blog post structure and conventions.
Use when writing or editing files in src/content/learn/. Provides Learn page structure and tone.
| name | docs-voice |
| description | Use when writing any React documentation. Provides voice, tone, and style rules for all doc types. |
useState, startTransition, <Suspense>| Type | Tone | Example |
|---|---|---|
| Learn | Conversational | "Here's what that looks like...", "You might be wondering..." |
| Reference | Technical | "Call useState at the top level...", "This Hook returns..." |
| Blog | Accurate | Focus on facts, not marketing |
Note: Pitfall and DeepDive components can use slightly more conversational phrasing ("You might wonder...", "It might be tempting...") even in Reference pages, since they're explanatory asides.
Pattern: Explain behavior first, then name it.
✅ "React waits until all code in event handlers runs before processing state updates. This is called batching."
❌ "React uses batching to process state updates atomically."
Terms to avoid or explain:
| Jargon | Plain Language |
|---|---|
| atomic | all-or-nothing, batched together |
| idempotent | same inputs, same output |
| deterministic | predictable, same result every time |
| memoize | remember the result, skip recalculating |
| referentially transparent | (avoid - describe the behavior) |
| invariant | rule that must always be true |
| reify | (avoid - describe what's being created) |
Allowed technical terms in Reference pages:
Use established analogies sparingly—once when introducing a concept, not repeatedly:
| Concept | Analogy |
|---|---|
| Components/React | Kitchen (components as cooks, React as waiter) |
| Render phases | Restaurant ordering (trigger/render/commit) |
| State batching | Waiter collecting full order before going to kitchen |
| State behavior | Snapshot/photograph in time |
| State storage | React storing state "on a shelf" |
| State purpose | Component's memory |
| Pure functions | Recipes (same ingredients → same dish) |
| Pure functions | Math formulas (y = 2x) |
| Props | Adjustable "knobs" |
| Children prop | "Hole" to be filled by parent |
| Keys | File names in a folder |
| Curly braces in JSX | "Window into JavaScript" |
| Declarative UI | Taxi driver (destination, not turn-by-turn) |
| Imperative UI | Turn-by-turn navigation |
| State structure | Database normalization |
| Refs | "Secret pocket" React doesn't track |
| Effects/Refs | "Escape hatch" from React |
| Context | CSS inheritance / "Teleportation" |
| Custom Hooks | Design system |
Wrong vs Right code:
\`\`\`js
// 🚩 Don't mutate state:
obj.x = 10;
\`\`\`
\`\`\`js
// ✅ Replace with new object:
setObj({ ...obj, x: 10 });
\`\`\`
Table comparisons:
| passing a function | calling a function |
| `onClick={handleClick}` | `onClick={handleClick()}` |
Linking:
[Read about state](/learn/state-a-components-memory)
[See `useState` reference](/reference/react/useState)
this preservationWhen APIs change between versions:
Starting in React 19, render `<Context>` as a provider:
\`\`\`js
<SomeContext value={value}>{children}</SomeContext>
\`\`\`
In older versions:
\`\`\`js
<SomeContext.Provider value={value}>{children}</SomeContext.Provider>
\`\`\`
Patterns: