Init claude config (#8265)

2026-02-21 19:31:57 +00:00 · 2026-01-27 10:22:10 -05:00
parent ed876185c3
commit 303e6b4c6d
9 changed files with 1435 additions and 0 deletions
--- a/.claude/agents/docs-reviewer.md
+++ b/.claude/agents/docs-reviewer.md
@@ -0,0 +1,77 @@
+---
+name: docs-reviewer
+description: "Use after editing docs to review changes. Orchestrates docs-writer-learn, docs-writer-reference, docs-components, and docs-sandpack skills to validate structure, components, and style"
+model: opus
+color: cyan
+---
+
+# React Documentation Reviewer Agent
+
+You are an expert reviewer for React documentation. Your role is to validate documentation changes for consistency, correctness, and adherence to established patterns.
+
+## Available Skills
+
+You have access to specialized skills that define the authoritative patterns for React docs. **Always invoke the relevant skills** to get the current patterns:
+
+| Skill | When to Use |
+|-------|-------------|
+| `docs-writer-learn` | Reviewing files in `src/content/learn/` |
+| `docs-writer-reference` | Reviewing files in `src/content/reference/` |
+| `docs-components` | Validating MDX components (DeepDive, Pitfall, Note, Recipes, Challenges) |
+| `docs-sandpack` | Validating interactive code examples |
+
+## Review Process
+
+1. **Identify changed files** - Check git status or read the files to review
+2. **Determine document type** based on path:
+   - `src/content/learn/**` → Invoke `docs-writer-learn`
+   - `src/content/reference/**` → Invoke `docs-writer-reference`
+3. **Invoke component skills** for any MDX components or Sandpack examples in the file
+4. **Read the patterns reference** at `.claude/docs/react-docs-patterns.md` for comprehensive details
+5. **Validate against each skill's requirements**
+6. **Run verification commands**
+7. **Report issues with specific line numbers and fixes**
+
+## Verification Commands
+
+These commands can help identify issues (user may run manually):
+
+```bash
+yarn lint-heading-ids    # Check heading ID format
+yarn lint                # Check for ESLint issues
+yarn deadlinks           # Check for broken links
+```
+
+## Issue Reporting Format
+
+```
+## Documentation Review Results
+
+### Errors (must fix)
+- **Line 45**: Missing heading ID. Change `## Events` to `## Events {/*events*/}`
+- **Line 78**: `<DeepDive>` missing `####` heading as first child
+
+### Warnings (recommended)
+- **Line 23**: Capitalize "effect" to "Effect" when referring to the React concept
+
+### Summary
+- Errors: X
+- Warnings: Y
+- Status: PASS | BLOCKED (fix errors before committing)
+```
+
+## Key Validation Points
+
+These are quick checks - see the skills for full details:
+
+### All Documents
+- All `##`, `###`, `####` headings have explicit IDs: `{/*lowercase-with-hyphens*/}`
+- React terms capitalized: Hook, Effect, State, Context, Ref, Component
+- Uses "you" to address the reader
+- No time estimates ("quick", "simple", "easy")
+- Internal links use relative paths (`/learn/...`, `/reference/...`)
+
+### Invoke Skills For
+- **Structure validation** → `docs-writer-learn` or `docs-writer-reference`
+- **Component usage** → `docs-components`
+- **Code examples** → `docs-sandpack`
--- a/.claude/docs/react-docs-patterns.md
+++ b/.claude/docs/react-docs-patterns.md
@@ -0,0 +1,637 @@
+# React Documentation Patterns Reference
+
+Comprehensive reference for React documentation patterns. Use this when writing or reviewing docs.
+
+---
+
+## Document Templates
+
+### Learn Page Template (`src/content/learn/`)
+
+```mdx
+---
+title: Your Page Title
+---
+
+<Intro>
+
+Opening paragraph introducing the topic. Use *italics* for new terms being defined. Keep it to 1-2 sentences that hook the reader.
+
+</Intro>
+
+<YouWillLearn>
+
+* Bullet point of what reader will learn
+* Another learning outcome
+* Keep to 3-5 items
+
+</YouWillLearn>
+
+## First Section {/*first-section*/}
+
+Content with <Sandpack> examples...
+
+<Recap>
+
+* Summary bullet of key point
+* Another summary point
+
+</Recap>
+
+<Challenges>
+
+#### Challenge Title {/*challenge-id*/}
+
+Challenge description...
+
+<Sandpack>
+{/* problem code */}
+</Sandpack>
+
+<Solution>
+
+Explanation and solution...
+
+<Sandpack>
+{/* solution code */}
+</Sandpack>
+
+</Solution>
+
+</Challenges>
+```
+
+### Reference Page Template (`src/content/reference/`)
+
+```mdx
+---
+title: hookName
+---
+
+<Intro>
+
+`hookName` is a React Hook that lets you [brief description].
+
+\`\`\`js
+const result = hookName(arg)
+\`\`\`
+
+</Intro>
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `hookName(arg)` {/*hookname*/}
+
+Call `hookName` at the top level of your component to...
+
+\`\`\`js
+import { hookName } from 'react';
+
+function MyComponent() {
+  const result = hookName(initialValue);
+  // ...
+\`\`\`
+
+[See more examples below.](#usage)
+
+#### Parameters {/*parameters*/}
+
+* `arg`: Description of the parameter.
+
+#### Returns {/*returns*/}
+
+Description of return value.
+
+#### Caveats {/*caveats*/}
+
+* Caveat about usage.
+* Another important caveat.
+
+---
+
+## Usage {/*usage*/}
+
+### Common Use Case {/*common-use-case*/}
+
+Explanation with <Sandpack> examples...
+
+---
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Common Problem {/*common-problem*/}
+
+How to solve it...
+```
+
+---
+
+## Tone & Voice Guidelines
+
+### Learn Pages
+- Conversational, friendly
+- Address the reader as "you"
+- "Here's what that looks like..."
+- "You might be wondering..."
+- "Let's see how this works..."
+
+### Reference Pages
+- Precise, technical
+- Still use "you" but more direct
+- "Call `useState` at the top level..."
+- "This Hook returns..."
+
+### Universal Rules
+- **Capitalize React terms:** Hook, Effect, State, Context, Ref, Component, Transition
+- **Capitalize:** Server Component, Client Component, Server Action, Error Boundary, Suspense
+- **Use proper product names:** ESLint, TypeScript, JavaScript (not lowercase)
+- **Use bold** for key concepts: **state variable**, **event handler**
+- **Use italics** for new terms being defined: *event handlers*
+- Avoid "simple", "easy", "just" - these can be dismissive
+- Prefer concrete examples over abstract explanations
+- No time estimates ("quick", "takes X minutes")
+- Frame feature differences as "capabilities" not "advantages/disadvantages"
+- Avoid passive voice and jargon
+
+### Avoiding Jargon
+
+React docs explain technical concepts in plain language. Follow these patterns:
+
+**Don't use CS jargon without explanation:**
+- ❌ "State updates are atomic"
+- ✅ "React waits until all state updates are done before re-rendering"
+
+- ❌ "Components must be idempotent"
+- ✅ "Given the same inputs, a component always returns the same output"
+
+- ❌ "Rendering must be deterministic"
+- ✅ "React expects the same inputs to produce the same result"
+
+**Terms to avoid or always explain:**
+- "atomic" → describe what actually happens (all-or-nothing, batched together)
+- "idempotent" → "same inputs, same output"
+- "deterministic" → "predictable", "same result every time"
+- "memoize/memoization" → "remember the result", "skip recalculating"
+- "referentially transparent" → avoid entirely, explain the behavior
+- "invariant" → "rule that must always be true", "requirement"
+- "reify" → avoid entirely, describe what's being created
+
+**Use analogies the docs already establish:**
+- Rendering = preparing food in a kitchen
+- Committing = placing the order on the table
+- Batching = waiter collecting the full order before going to kitchen
+- State = snapshot/photograph at a moment in time
+- Pure functions = math formulas (y = 2x always gives same result)
+
+**Pattern: Explain behavior, then name it**
+```markdown
+React waits until all code in the event handlers has run before
+processing your state updates. This is called *batching*.
+```
+
+Not:
+```markdown
+React uses batching to process state updates atomically.
+```
+
+---
+
+## Code Style Rules (Enforced in PR Review)
+
+These rules are strictly enforced during PR review:
+
+### Component Definitions
+```js
+// ✅ Correct - function declaration
+function MyInput({ value, onChange, ref }) {
+  return <input value={value} onChange={onChange} ref={ref} />;
+}
+export default MyInput;
+
+// 🚫 Wrong - arrow function for component
+const MyInput = ({ value, onChange, ref }) => {
+  return <input value={value} onChange={onChange} ref={ref} />;
+};
+```
+
+### Event Handlers
+```js
+// ✅ Correct - use 'e' for event parameter
+<button onClick={(e) => e.preventDefault()}>
+
+// 🚫 Wrong - using 'event' (can conflict with global)
+<button onClick={(event) => event.preventDefault()}>
+```
+
+### createRoot Pattern
+```js
+// ✅ Correct - two lines
+const root = createRoot(document.getElementById('root'));
+root.render(<App />);
+
+// 🚫 Wrong - chained
+createRoot(document.getElementById('root')).render(<App />);
+```
+
+### State vs Ref Decision
+```js
+// ✅ Use ref when value is not used for rendering
+const isMounted = useRef(false);
+
+// 🚫 Don't use state if not rendering based on it
+const [isMounted, setIsMounted] = useState(false); // triggers re-render
+```
+
+### Hydration-Safe Code
+```js
+// ✅ Correct - same output on server and client
+function App() {
+  const [count, setCount] = useState(0);
+  return <div>{count}</div>;
+}
+
+// 🚫 Wrong - different output causes hydration mismatch
+function App() {
+  const isClient = typeof window !== 'undefined';
+  return <div>{isClient ? 'Client' : 'Server'}</div>;
+}
+```
+
+## Line Length Guidelines
+
+Keep lines short enough to avoid horizontal scrolling on small screens:
+- Prose: ~80 characters
+- Code: ~60-70 characters preferred
+- If longer, break into multiple lines
+
+## Anti-Patterns to Avoid
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| `const Comp = () => {}` | Not standard for components | `function Comp() {}` |
+| `onClick={(event) => ...}` | Conflicts with global | `onClick={(e) => ...}` |
+| `useState` for non-rendered values | Unnecessary re-renders | Use `useRef` instead |
+| Reading `window` during render | Hydration mismatch | Check in useEffect |
+| Single-line if statements | Harder to read/debug | Use multiline with braces |
+| Chained `createRoot().render()` | Less clear | Two separate statements |
+| `//...` without space | Inconsistent style | Use `// ...` with space |
+| Tabs for indentation | Inconsistent rendering | Use 2 spaces |
+| Deprecated `ReactDOM.render` | Outdated API | Use `createRoot` |
+| Fake package names | Confusing readers | Use `'./your-storage-layer'` |
+| `PropsWithChildren` | Outdated pattern | Use `children?: React.ReactNode` |
+| Missing `key` in lists | Causes warnings | Always include `key` prop |
+
+---
+
+## forwardRef and memo Patterns
+
+### forwardRef with Named Function
+```js
+// ✅ Correct - named function for display name
+const MyInput = forwardRef(function MyInput(props, ref) {
+  return <input {...props} ref={ref} />;
+});
+
+// 🚫 Wrong - anonymous function
+const MyInput = forwardRef((props, ref) => {
+  return <input {...props} ref={ref} />;
+});
+```
+
+### memo with Named Function
+```js
+// ✅ Correct - preserves component name
+const Greeting = memo(function Greeting({ name }) {
+  return <h1>Hello, {name}</h1>;
+});
+
+// 🚫 Wrong - loses component name in DevTools
+const Greeting = memo(({ name }) => {
+  return <h1>Hello, {name}</h1>;
+});
+```
+
+---
+
+## MDX Component Decision Tree
+
+### `<Pitfall>`
+**Use for:** Common mistakes that cause bugs or unexpected behavior.
+
+```mdx
+<Pitfall>
+
+React components must start with a capital letter or they won't work!
+
+</Pitfall>
+```
+
+### `<Note>`
+**Use for:** Important clarifications, conventions, or tips.
+
+```mdx
+<Note>
+
+The convention is to name state variables like `[something, setSomething]`.
+
+</Note>
+```
+
+### `<DeepDive>`
+**Use for:** Optional deep technical content. **Must have `####` heading as first child.**
+
+```mdx
+<DeepDive>
+
+#### Why does this work? {/*why-does-this-work*/}
+
+Technical explanation that's optional for understanding the main concept...
+
+</DeepDive>
+```
+
+### `<Sandpack>`
+**Use for:** Interactive code examples.
+
+```mdx
+<Sandpack>
+
+\`\`\`js
+export default function App() {
+  return <h1>Hello</h1>;
+}
+\`\`\`
+
+\`\`\`css
+h1 { color: blue; }
+\`\`\`
+
+</Sandpack>
+```
+
+### `<Recipes>`
+**Use for:** Multiple related examples showing variations.
+
+```mdx
+<Recipes titleText="Examples of useState" titleId="examples-basic">
+
+#### Counter (number) {/*counter-number*/}
+
+Description...
+
+<Sandpack>
+{/* code */}
+</Sandpack>
+
+<Solution />
+
+#### Text field (string) {/*text-field-string*/}
+
+Description...
+
+<Sandpack>
+{/* code */}
+</Sandpack>
+
+<Solution />
+
+</Recipes>
+```
+
+### `<Challenges>`
+**Use for:** End-of-page exercises (Learn pages only).
+
+```mdx
+<Challenges>
+
+#### Fix the bug {/*fix-the-bug*/}
+
+Problem description...
+
+<Hint>
+Optional hint text.
+</Hint>
+
+<Sandpack>
+{/* problem code */}
+</Sandpack>
+
+<Solution>
+
+Explanation...
+
+<Sandpack>
+{/* solution code */}
+</Sandpack>
+
+</Solution>
+
+</Challenges>
+```
+
+---
+
+## Sandpack Patterns
+
+> **Comprehensive guidelines:** See `.claude/skills/docs-sandpack/SKILL.md` for complete Sandpack patterns including package.json usage, hidden/active files, file structure, and code size limits.
+
+### Quick Reference
+
+| Pattern | When to Use |
+|---------|-------------|
+| `hidden` | package.json, data files, API mocks, infrastructure |
+| `active` | File containing primary teaching concept |
+| Single file | Basic hooks, simple concepts (70% of examples) |
+| Multi-file | Imports, context, component reuse (30% of examples) |
+
+### File Naming
+- Main file: ` ```js ` (no prefix)
+- Supporting files: ` ```js src/FileName.js `
+- Active file (reference pages): ` ```js src/File.js active `
+- Hidden files: ` ```js src/data.js hidden `
+- CSS: ` ```css `
+- Package.json (for dependencies): ` ```json package.json `
+
+### Line Highlighting
+```mdx
+\`\`\`js {2-4}
+function Example() {
+  // These lines (2-4)
+  // will be
+  // highlighted
+  return null;
+}
+\`\`\`
+```
+
+### Code References (for callouts)
+```mdx
+\`\`\`js [[1, 4, "age"], [2, 4, "setAge"]]
+// Creates numbered callouts pointing to specific code
+\`\`\`
+```
+
+### Expected Errors (for intentionally broken examples)
+```mdx
+\`\`\`js {expectedErrors: {'react-compiler': [7]}}
+// Line 7 will show as expected error
+\`\`\`
+```
+
+### Multiple Files
+```mdx
+<Sandpack>
+
+\`\`\`js src/App.js
+import Gallery from './Gallery.js';
+
+export default function App() {
+  return <Gallery />;
+}
+\`\`\`
+
+\`\`\`js src/Gallery.js
+export default function Gallery() {
+  return <h1>Gallery</h1>;
+}
+\`\`\`
+
+\`\`\`css
+h1 { color: purple; }
+\`\`\`
+
+</Sandpack>
+```
+
+### External Dependencies
+```mdx
+<Sandpack>
+
+\`\`\`js
+import { useImmer } from 'use-immer';
+// ...
+\`\`\`
+
+\`\`\`json package.json
+{
+  "dependencies": {
+    "immer": "1.7.3",
+    "use-immer": "0.5.1",
+    "react": "latest",
+    "react-dom": "latest",
+    "react-scripts": "latest"
+  }
+}
+\`\`\`
+
+</Sandpack>
+```
+
+---
+
+## Common Patterns
+
+### Showing Wrong vs Right Code
+
+```mdx
+\`\`\`js
+// 🚩 Don't mutate state like this:
+obj.x = 10;
+setObj(obj);
+\`\`\`
+
+\`\`\`js
+// ✅ Replace state with a new object:
+setObj({
+  ...obj,
+  x: 10
+});
+\`\`\`
+```
+
+### Table Comparisons
+
+```mdx
+| passing a function (correct)     | calling a function (incorrect)     |
+| -------------------------------- | ---------------------------------- |
+| `<button onClick={handleClick}>` | `<button onClick={handleClick()}>` |
+```
+
+### Linking to Other Pages
+
+```mdx
+[Read more about state](/learn/state-a-components-memory)
+[See the `useState` reference](/reference/react/useState)
+```
+
+### Inline Code Annotations
+
+Use `<CodeStep>` for numbered callouts in prose:
+
+```mdx
+The <CodeStep step={1}>current state</CodeStep> is initially set to the <CodeStep step={3}>initial state</CodeStep> you provided.
+```
+
+### Troubleshooting Sections
+
+Error headings must follow this format:
+
+```markdown
+### I'm getting an error: "Too many re-renders" {/*too-many-re-renders*/}
+
+This error usually means...
+```
+
+Not:
+```markdown
+### Too many re-renders error {/*too-many-re-renders*/}
+```
+
+---
+
+## Blog Post Guidelines
+
+### Updating Old Blog Posts
+- Never break existing links; add redirects when URLs change
+- Do not rewrite history; add update notes with dates instead of replacing text
+- Use format: `**Update (Month Year):** New information here.`
+
+### Announcing Features
+- Do not promise or oversell features that are not yet available
+- If a feature is "upcoming," say so explicitly
+- Include FAQ sections for anticipated developer questions
+- Focus on correctness over marketing language
+
+---
+
+## React 19+ Documentation Patterns
+
+### Documenting API Changes
+When APIs change between versions, document both patterns:
+
+```mdx
+Starting in React 19, you can render `<SomeContext>` as a provider:
+
+\`\`\`js
+<SomeContext value={value}>
+  {children}
+</SomeContext>
+\`\`\`
+
+In older versions of React, use `<SomeContext.Provider>`:
+
+\`\`\`js
+<SomeContext.Provider value={value}>
+  {children}
+</SomeContext.Provider>
+\`\`\`
+```
+
+### Version Notes
+- Use "Starting in React 19..." for new patterns
+- Use "In older versions of React..." for legacy patterns
+- Add version badges where appropriate
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -0,0 +1,26 @@
+{
+  "skills": {
+    "suggest": [
+      {
+        "pattern": "src/content/learn/**/*.md",
+        "skill": "docs-writer-learn"
+      },
+      {
+        "pattern": "src/content/reference/**/*.md",
+        "skill": "docs-writer-reference"
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(yarn lint:*)",
+      "Bash(yarn lint-heading-ids:*)",
+      "Bash(yarn lint:fix:*)",
+      "Bash(yarn tsc:*)",
+      "Bash(yarn check-all:*)",
+      "Bash(yarn fix-headings:*)",
+      "Bash(yarn deadlinks:*)",
+      "Bash(yarn prettier:diff:*)"
+    ]
+  }
+}
--- a/.claude/skills/docs-components/SKILL.md
+++ b/.claude/skills/docs-components/SKILL.md
@@ -0,0 +1,142 @@
+---
+name: docs-components
+description: MDX component patterns for React documentation. Invoke when adding DeepDive, Pitfall, Note, Recipes, or Challenges to docs.
+---
+
+# MDX Component Patterns
+
+## `<Pitfall>`
+
+Common mistakes that cause bugs. Use for errors readers will likely make.
+
+```mdx
+<Pitfall>
+
+React components must start with a capital letter or they won't work!
+
+</Pitfall>
+```
+
+## `<Note>`
+
+Important clarifications, conventions, or tips. Less severe than Pitfall.
+
+```mdx
+<Note>
+
+The convention is to name state variables like `[something, setSomething]`.
+
+</Note>
+```
+
+## `<DeepDive>`
+
+Optional deep technical content. **First child must be `####` heading with ID.**
+
+```mdx
+<DeepDive>
+
+#### Why does this work? {/*why-does-this-work*/}
+
+Technical explanation that's optional for understanding the main concept...
+
+</DeepDive>
+```
+
+## `<Recipes>`
+
+Multiple related examples showing variations. Each recipe needs `<Solution />`.
+
+```mdx
+<Recipes titleText="Examples of useState" titleId="examples-basic">
+
+#### Counter (number) {/*counter-number*/}
+
+Description...
+
+<Sandpack>
+{/* code */}
+</Sandpack>
+
+<Solution />
+
+#### Text field (string) {/*text-field-string*/}
+
+Description...
+
+<Sandpack>
+{/* code */}
+</Sandpack>
+
+<Solution />
+
+</Recipes>
+```
+
+## `<Challenges>`
+
+End-of-page exercises. **Learn pages only.** Each challenge needs problem + solution Sandpack.
+
+```mdx
+<Challenges>
+
+#### Fix the bug {/*fix-the-bug*/}
+
+Problem description...
+
+<Hint>
+Optional hint text.
+</Hint>
+
+<Sandpack>
+{/* problem code */}
+</Sandpack>
+
+<Solution>
+
+Explanation...
+
+<Sandpack>
+{/* solution code */}
+</Sandpack>
+
+</Solution>
+
+</Challenges>
+```
+
+## `<CodeStep>` (Use Sparingly)
+
+Numbered callouts in prose. Pairs with code block annotations.
+
+**Important:** Use at most 2-3 colors in any given explanation. Excessive highlighting is distracting.
+
+✅ **Good use** - highlighting key concepts:
+```mdx
+React will compare the <CodeStep step={2}>dependencies</CodeStep> with the dependencies you passed...
+```
+
+🚫 **Avoid** - excessive highlighting:
+```mdx
+When an <CodeStep step={1}>Activity</CodeStep> boundary is <CodeStep step={2}>hidden</CodeStep> during its <CodeStep step={3}>initial</CodeStep> render...
+```
+
+**Guidelines:**
+- Maximum 2-3 different colors per explanation
+- Don't highlight every keyword - only key concepts
+- Use for terms in prose, not entire code blocks
+- Maintain consistent usage within a section
+
+---
+
+## Other Available Components
+
+**Version/Status:** `<Canary>`, `<CanaryBadge />`, `<Experimental>`, `<ExperimentalBadge />`, `<Deprecated>`, `<RSC>`, `<RSCBadge />`, `<NextMajor>`, `<Wip>`
+
+**Visuals:** `<Diagram>`, `<DiagramGroup>`, `<Illustration>`, `<IllustrationBlock>`, `<CodeDiagram>`, `<FullWidth>`
+
+**Console:** `<ConsoleBlock level="error|warning">`, `<ConsoleBlockMulti>`, `<ConsoleLogLine>`
+
+**Specialized:** `<TerminalBlock>`, `<BlogCard>`, `<TeamMember>`, `<YouTubeIframe>`, `<ErrorDecoder />`, `<LearnMore>`, `<Math>`, `<MathI>`, `<LanguageList>`
+
+See existing docs for usage examples of these components.
--- a/.claude/skills/docs-sandpack/SKILL.md
+++ b/.claude/skills/docs-sandpack/SKILL.md
@@ -0,0 +1,315 @@
+---
+name: docs-sandpack
+description: Sandpack patterns for React documentation. Invoke when adding interactive code examples.
+---
+
+# Sandpack Patterns
+
+## File Naming
+
+| Pattern | Usage |
+|---------|-------|
+| ` ```js ` | Main file (no prefix) |
+| ` ```js src/FileName.js ` | Supporting files |
+| ` ```js src/File.js active ` | Active file (reference pages) |
+| ` ```js src/data.js hidden ` | Hidden files |
+| ` ```css ` | CSS styles |
+| ` ```json package.json ` | External dependencies |
+
+**Critical:** Main file must have `export default`.
+
+## Line Highlighting
+
+```mdx
+```js {2-4}
+function Example() {
+  // Lines 2-4
+  // will be
+  // highlighted
+  return null;
+}
+```
+
+## Code References (numbered callouts)
+
+```mdx
+```js [[1, 4, "age"], [2, 4, "setAge"]]
+// Creates numbered markers pointing to "age" and "setAge" on line 4
+```
+
+## Expected Errors (intentionally broken examples)
+
+```mdx
+```js {expectedErrors: {'react-compiler': [7]}}
+// Line 7 shows as expected error
+```
+
+## Multi-File Example
+
+```mdx
+<Sandpack>
+
+```js src/App.js
+import Gallery from './Gallery.js';
+
+export default function App() {
+  return <Gallery />;
+}
+```
+
+```js src/Gallery.js
+export default function Gallery() {
+  return <h1>Gallery</h1>;
+}
+```
+
+```css
+h1 { color: purple; }
+```
+
+</Sandpack>
+```
+
+## External Dependencies
+
+```mdx
+<Sandpack>
+
+```js
+import { useImmer } from 'use-immer';
+// ...
+```
+
+```json package.json
+{
+  "dependencies": {
+    "immer": "1.7.3",
+    "use-immer": "0.5.1",
+    "react": "latest",
+    "react-dom": "latest",
+    "react-scripts": "latest"
+  }
+}
+```
+
+</Sandpack>
+```
+
+## Code Style in Sandpack (Required)
+
+Sandpack examples are held to strict code style standards:
+
+1. **Function declarations** for components (not arrows)
+2. **`e`** for event parameters
+3. **Single quotes** in JSX
+4. **`const`** unless reassignment needed
+5. **Spaces in destructuring**: `({ props })` not `({props})`
+6. **Two-line createRoot**: separate declaration and render call
+7. **Multiline if statements**: always use braces
+
+### Don't Create Hydration Mismatches
+
+Sandpack examples must produce the same output on server and client:
+
+```js
+// 🚫 This will cause hydration warnings
+export default function App() {
+  const isClient = typeof window !== 'undefined';
+  return <div>{isClient ? 'Client' : 'Server'}</div>;
+}
+```
+
+### Use Ref for Non-Rendered State
+
+```js
+// 🚫 Don't trigger re-renders for non-visual state
+const [mounted, setMounted] = useState(false);
+useEffect(() => { setMounted(true); }, []);
+
+// ✅ Use ref instead
+const mounted = useRef(false);
+useEffect(() => { mounted.current = true; }, []);
+```
+
+## Additional Code Quality Rules
+
+### Always Include Keys in Lists
+```js
+// ✅ Correct
+{items.map(item => <li key={item.id}>{item.name}</li>)}
+
+// 🚫 Wrong - missing key
+{items.map(item => <li>{item.name}</li>)}
+```
+
+### Use Realistic Import Paths
+```js
+// ✅ Correct - descriptive path
+import { fetchData } from './your-data-layer';
+
+// 🚫 Wrong - looks like a real npm package
+import { fetchData } from 'cool-data-lib';
+```
+
+### Console.log Labels
+```js
+// ✅ Correct - labeled for clarity
+console.log('User:', user);
+console.log('Component Stack:', errorInfo.componentStack);
+
+// 🚫 Wrong - unlabeled
+console.log(user);
+```
+
+### Keep Delays Reasonable
+```js
+// ✅ Correct - 1-1.5 seconds
+setTimeout(() => setLoading(false), 1000);
+
+// 🚫 Wrong - too long, feels sluggish
+setTimeout(() => setLoading(false), 3000);
+```
+
+## Updating Line Highlights
+
+When modifying code in examples with line highlights (`{2-4}`), **always update the highlight line numbers** to match the new code. Incorrect line numbers cause rendering crashes.
+
+## File Name Conventions
+
+- Capitalize file names for component files: `Gallery.js` not `gallery.js`
+- After initially explaining files are in `src/`, refer to files by name only: `Gallery.js` not `src/Gallery.js`
+
+---
+
+## Sandpack Example Guidelines
+
+### Package.json Rules
+
+**Include package.json when:**
+- Using external npm packages (immer, remarkable, leaflet, toastify-js, etc.)
+- Demonstrating experimental/canary React features
+- Requiring specific React versions (`react: beta`, `react: 19.0.0-rc-*`)
+
+**Omit package.json when:**
+- Example uses only built-in React features
+- No external dependencies needed
+- Teaching basic hooks, state, or components
+
+**Always mark package.json as hidden:**
+```mdx
+```json package.json hidden
+{
+  "dependencies": {
+    "react": "latest",
+    "react-dom": "latest",
+    "react-scripts": "latest",
+    "immer": "1.7.3"
+  }
+}
+```
+```
+
+**Version conventions:**
+- Use `"latest"` for stable features
+- Use exact versions only when compatibility requires it
+- Include minimal dependencies (just what the example needs)
+
+### Hidden File Patterns
+
+**Always hide these file types:**
+
+| File Type | Reason |
+|-----------|--------|
+| `package.json` | Configuration not the teaching point |
+| `sandbox.config.json` | Sandbox setup is boilerplate |
+| `public/index.html` | HTML structure not the focus |
+| `src/data.js` | When it contains sample/mock data |
+| `src/api.js` | When showing API usage, not implementation |
+| `src/styles.css` | When styling is not the lesson |
+| `src/router.js` | Supporting infrastructure |
+| `src/actions.js` | Server action implementation details |
+
+**Rationale:**
+- Reduces cognitive load
+- Keeps focus on the primary concept
+- Creates cleaner, more focused examples
+
+**Example:**
+```mdx
+```js src/data.js hidden
+export const items = [
+  { id: 1, name: 'Item 1' },
+  { id: 2, name: 'Item 2' },
+];
+```
+```
+
+### Active File Patterns
+
+**Mark as active when:**
+- File contains the primary teaching concept
+- Learner should focus on this code first
+- Component demonstrates the hook/pattern being taught
+
+**Effect of the `active` marker:**
+- Sets initial editor tab focus when Sandpack loads
+- Signals "this is what you should study"
+- Works with hidden files to create focused examples
+
+**Most common active file:** `src/index.js` or `src/App.js`
+
+**Example:**
+```mdx
+```js src/App.js active
+// This file will be focused when example loads
+export default function App() {
+  // ...
+}
+```
+```
+
+### File Structure Guidelines
+
+| Scenario | Structure | Reason |
+|----------|-----------|--------|
+| Basic hook usage | Single file | Simple, focused |
+| Teaching imports | 2-3 files | Shows modularity |
+| Context patterns | 4-5 files | Realistic structure |
+| Complex state | 3+ files | Separation of concerns |
+
+**Single File Examples (70% of cases):**
+- Use for simple concepts
+- 50-200 lines typical
+- Best for: Counter, text inputs, basic hooks
+
+**Multi-File Examples (30% of cases):**
+- Use when teaching modularity/imports
+- Use for context patterns (4-5 files)
+- Use when component is reused
+
+**File Naming:**
+- Main component: `App.js` (capitalized)
+- Component files: `Gallery.js`, `Button.js` (capitalized)
+- Data files: `data.js` (lowercase)
+- Utility files: `utils.js` (lowercase)
+- Context files: `TasksContext.js` (named after what they provide)
+
+### Code Size Limits
+
+- Single file: **<200 lines**
+- Multi-file total: **150-300 lines**
+- Main component: **100-150 lines**
+- Supporting files: **20-40 lines each**
+
+### CSS Guidelines
+
+**Always:**
+- Include minimal CSS for demo interactivity
+- Use semantic class names (`.panel`, `.button-primary`, `.panel-dark`)
+- Support light/dark themes when showing UI concepts
+- Keep CSS visible (never hidden)
+
+**Size Guidelines:**
+- Minimal (5-10 lines): Basic button styling, spacing
+- Medium (15-30 lines): Panel styling, form layouts
+- Complex (40+ lines): Only for layout-focused examples
--- a/.claude/skills/docs-writer-learn/SKILL.md
+++ b/.claude/skills/docs-writer-learn/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: docs-writer-learn
+description: Auto-suggested when working on src/content/learn/**/*.md files. Provides Learn page structure and tone guidance.
+---
+
+# Learn Page Writer
+
+## Template Structure
+
+```mdx
+---
+title: Your Page Title
+---
+
+<Intro>
+Opening paragraph (1-2 sentences). Use *italics* for new terms.
+</Intro>
+
+<YouWillLearn>
+* Learning outcome (3-5 items)
+</YouWillLearn>
+
+## First Section {/*first-section*/}
+Content with Sandpack examples...
+
+<Recap>
+* Summary bullet points
+</Recap>
+
+<Challenges>
+{/* End-of-page exercises */}
+</Challenges>
+```
+
+## Tone
+
+Conversational and friendly:
+- "Here's what that looks like..."
+- "You might be wondering..."
+- "Let's see how this works..."
+
+## Component Decision Tree
+
+| When you need to... | Use |
+|---------------------|-----|
+| Warn about common mistakes that cause bugs | `<Pitfall>` |
+| Clarify a convention or tip | `<Note>` |
+| Explain optional deep technical details | `<DeepDive>` |
+| Show multiple related variations | `<Recipes>` |
+| Add end-of-page exercises | `<Challenges>` |
+
+For component patterns, invoke `/docs-components`. For Sandpack patterns, invoke `/docs-sandpack`.
+
+## Critical Rules
+
+1. **Heading IDs required:** `## Title {/*title-id*/}` (lowercase, hyphens)
+2. **Capitalize React terms** when referring to the React concept (not general usage):
+   - Core: Hook, Effect, State, Context, Ref, Component, Fragment
+   - Concurrent: Transition, Action, Suspense
+   - Server: Server Component, Client Component, Server Function, Server Action
+   - Patterns: Error Boundary
+   - Canary: Activity, View Transition, Transition Type
+   - General usage stays lowercase: "the page transitions" (not React), "takes an action" (not React)
+3. **DeepDive must start with `####` heading**
+4. **Sandpack main file needs `export default`**
+5. **Avoid:** "simple", "easy", "just", time estimates
--- a/.claude/skills/docs-writer-reference/SKILL.md
+++ b/.claude/skills/docs-writer-reference/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: docs-writer-reference
+description: Auto-suggested when working on src/content/reference/**/*.md files. Provides Reference page structure and tone guidance.
+---
+
+# Reference Page Writer
+
+## Template Structure
+
+```mdx
+---
+title: hookName
+---
+
+<Intro>
+`hookName` is a React Hook that lets you [brief description].
+
+```js
+const result = hookName(arg)
+```
+
+</Intro>
+
+<InlineToc />
+
+---
+
+## Reference {/*reference*/}
+
+### `hookName(arg)` {/*hookname*/}
+
+Call `hookName` at the top level of your component to...
+
+#### Parameters {/*parameters*/}
+* `arg`: Description of the parameter.
+
+#### Returns {/*returns*/}
+Description of return value.
+
+#### Caveats {/*caveats*/}
+* Important caveat about usage.
+
+---
+
+## Usage {/*usage*/}
+
+### Common Use Case {/*common-use-case*/}
+Explanation with Sandpack examples...
+
+---
+
+## Troubleshooting {/*troubleshooting*/}
+
+### Common Problem {/*common-problem*/}
+How to solve it...
+```
+
+## Formatting Details
+
+### Intro Section
+- Single non-wrapping opening line describing the API purpose:
+  - Hooks: `` `useHookName` is a React Hook that lets you [capability]. ``
+  - Other APIs: `` `apiName` lets you [capability]. ``
+- Code signature showing usage with `?` for optional parameters:
+  ```js
+  const [state, setState] = useState(initialState)
+  const cachedFn = useCallback(fn, dependencies)
+  const [optimisticState, addOptimistic] = useOptimistic(state, updateFn?);
+  ```
+
+### Parameters Section
+- Use bullet format: `* \`paramName\`: description`
+- Mark optional params: `* **optional** \`paramName\`: description`
+- Optional params in signature use `?`: `useOptimistic(state, updateFn?)`
+
+### Returns Section
+- Single return: prose description
+- Multiple returns (like useState): use numbered list:
+  ```
+  1. `state`: The current state value...
+  2. `setState`: A function to update the state...
+  ```
+
+### Code Examples
+- Show import and 5-10 lines of practical usage
+- Link to usage: `[See more examples below.](#usage)`
+
+## Tone
+
+Precise and technical: "Call `useState` at the top level...", "This Hook returns..."
+
+## Component Decision Tree
+
+| When you need to... | Use |
+|---------------------|-----|
+| Warn about common mistakes that cause bugs | `<Pitfall>` |
+| Clarify a convention or tip | `<Note>` |
+| Explain optional deep technical details | `<DeepDive>` |
+| Show multiple related variations | `<Recipes>` |
+
+For component patterns, invoke `/docs-components`. For Sandpack patterns, invoke `/docs-sandpack`.
+
+## Critical Rules
+
+1. **Heading IDs required:** `## Title {/*title-id*/}` (lowercase, hyphens)
+2. **Capitalize React terms** when referring to the React concept (not general usage):
+   - Core: Hook, Effect, State, Context, Ref, Component, Fragment
+   - Concurrent: Transition, Action, Suspense
+   - Server: Server Component, Client Component, Server Function, Server Action
+   - Patterns: Error Boundary
+   - Canary: Activity, View Transition, Transition Type
+   - General usage stays lowercase: "the page transitions" (not React), "takes an action" (not React)
+3. **DeepDive must start with `####` heading**
+4. **Sandpack main file needs `export default`**
+5. **Active file syntax:** ` ```js src/File.js active `
+6. **Avoid:** "simple", "easy", "just", time estimates
+7. **Error headings in Troubleshooting:** Use `### I'm getting an error: "[message]" {/*id*/}`
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,6 @@ public/fonts/**/Optimistic_*.woff2

 # rss
 public/rss.xml
+
+# claude local settings
+.claude/*.local.*
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,52 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this repository.
+
+## Project Overview
+
+This is the React documentation website (react.dev), built with Next.js 15.1.11 and React 19. Documentation is written in MDX format.
+
+## Development Commands
+
+```bash
+yarn build         # Production build
+yarn lint          # Run ESLint
+yarn lint:fix      # Auto-fix lint issues
+yarn tsc           # TypeScript type checking
+yarn check-all     # Run prettier, lint:fix, tsc, and rss together
+```
+
+## Project Structure
+
+```
+src/
+├── content/           # Documentation content (MDX files)
+│   ├── learn/         # Tutorial/learning content
+│   ├── reference/     # API reference docs
+│   ├── blog/          # Blog posts
+│   └── community/     # Community pages
+├── components/        # React components
+├── pages/             # Next.js pages
+├── hooks/             # Custom React hooks
+├── utils/             # Utility functions
+└── styles/            # CSS/Tailwind styles
+```
+
+## Code Conventions
+
+### TypeScript/React
+- Functional components only
+- Tailwind CSS for styling
+
+### Documentation Style
+
+When editing files in `src/content/`, the appropriate skill will be auto-suggested:
+- `src/content/learn/` - Learn page structure and tone
+- `src/content/reference/` - Reference page structure and tone
+
+For MDX components (DeepDive, Pitfall, Note, etc.), invoke `/docs-components`.
+For Sandpack code examples, invoke `/docs-sandpack`.
+
+See `.claude/docs/react-docs-patterns.md` for comprehensive style guidelines.
+
+Prettier is used for formatting (config in `.prettierrc`).