// Use when writing or editing files in src/content/learn/. Provides Learn page structure and tone.
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 any React documentation. Provides voice, tone, and style rules for all doc types.
Use when writing or editing files in src/content/blog/. Provides blog post structure and conventions.
| name | docs-writer-learn |
| description | Use when writing or editing files in src/content/learn/. Provides Learn page structure and tone. |
Voice: Patient teacher guiding a friend through concepts Tone: Conversational, warm, encouraging
For tone, capitalization, jargon, and prose patterns, invoke /docs-voice.
---
title: Page Title
---
<Intro>
1-3 sentences introducing the concept. Use *italics* for new terms.
</Intro>
<YouWillLearn>
* Learning outcome 1
* Learning outcome 2
* Learning outcome 3-5
</YouWillLearn>
## Section Name {/*section-id*/}
Content with Sandpack examples, Pitfalls, Notes, DeepDives...
## Another Section {/*another-section*/}
More content...
<Recap>
* Summary point 1
* Summary point 2
* Summary points 3-9
</Recap>
<Challenges>
#### Challenge title {/*challenge-id*/}
Description...
<Hint>
Optional guidance (single paragraph)
</Hint>
<Sandpack>
{/* Starting code */}
</Sandpack>
<Solution>
Explanation...
<Sandpack>
{/* Fixed code */}
</Sandpack>
</Solution>
</Challenges>
For pages that introduce a chapter (like describing-the-ui.md, managing-state.md):
<YouWillLearn isChapter={true}>
* [Sub-page title](/learn/sub-page-name) to learn...
* [Another page](/learn/another-page) to learn...
</YouWillLearn>
## Preview Section {/*section-id*/}
Preview description with mini Sandpack example
<LearnMore path="/learn/sub-page-name">
Read **[Page Title](/learn/sub-page-name)** to learn how to...
</LearnMore>
## What's next? {/*whats-next*/}
Head over to [First Page](/learn/first-page) to start reading this chapter page by page!
Important: Chapter intro pages do NOT include <Recap> or <Challenges> sections.
For step-by-step tutorials (like tutorial-tic-tac-toe.md):
<Intro>
Brief statement of what will be built
</Intro>
<Note>
Alternative learning path offered
</Note>
Table of contents (prose listing of major sections)
## Setup {/*setup*/}
...
## Main Content {/*main-content*/}
Progressive code building with ### subsections
No YouWillLearn, Recap, or Challenges
Ends with ordered list of "extra credit" improvements
For pages with heavy API documentation (like typescript.md):
<YouWillLearn>
* [Link to section](#section-anchor)
* [Link to another section](#another-section)
</YouWillLearn>
## Sections with ### subsections
## Further learning {/*further-learning*/}
No Recap or Challenges
All headings require IDs in {/*kebab-case*/} format:
## Section Title {/*section-title*/}
### Subsection Title {/*subsection-title*/}
#### DeepDive Title {/*deepdive-title*/}
ID Generation Rules:
:, ?, !, ., parentheses)Examples:
{/*whats-react*/}{/*step-1-create-the-context*/}{/*conditional-ternary-operator--*/}Show broken/problematic code BEFORE the solution:
// 🔴 Avoid: comment// ✅ Good: commentBuild understanding in layers:
For multi-step processes:
As section headings:
### Step 1: Action to take {/*step-1-action*/}
### Step 2: Next action {/*step-2-next-action*/}
As inline lists:
To implement this:
1. **Declare** `inputRef` with the `useRef` Hook.
2. **Pass it** as `<input ref={inputRef}>`.
3. **Read** the input DOM node from `inputRef.current`.
After Sandpack examples, encourage experimentation:
Help readers build intuition:
"When you're not sure whether some code should be in an Effect or in an event handler, ask yourself why this code needs to run."
<Intro> - First after frontmatter<YouWillLearn> - After Intro (standard/chapter pages)<Note>, <Pitfall>, <DeepDive> placed contextually<Recap> - Before Challenges (standard pages only)<Challenges> - End of page (standard pages only)For component structure and syntax, invoke /docs-components.
For Sandpack file structure, naming conventions, code style, and pedagogical markers, invoke /docs-sandpack.
Link to /learn:
Link to /reference:
[concept name](/learn/page-name)
[`useState`](/reference/react/useState)
[section link](/learn/page-name#section-id)
[MDN](https://developer.mozilla.org/...)
Important: Learn pages typically do NOT use --- dividers. The heading hierarchy provides sufficient structure. Only consider dividers in exceptional cases like separating main content from meta/contribution sections.
Do:
Don't:
--- dividers between sections## Title {/*title-id*/}isChapter={true} and <LearnMore>/docs-components Callout Spacing RulesFor component patterns, invoke /docs-components. For Sandpack patterns, invoke /docs-sandpack.