# docs-components

The docs-components skill guides an agent through React documentation MDX components and their conventions. Use it when drafting notes, warnings, examples, or exercises.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 1 install · ★ 11851 repo stars
- Author: reactjs
- License: CC-BY-4.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/reactjs/react.dev/tree/HEAD/.claude/skills/docs-components/SKILL.md
- Updated: 2026-10-20
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/docs-components

## What it does

The skill maps documentation needs to components: `<Note>` for clarifications, `<Pitfall>` for common mistakes, `<DeepDive>` for technical detail, and `<Recipes>` for related examples. It also sets heading levels and spacing conventions for these blocks.

Its MDX examples show required structure: each item in `<Recipes>` needs a `<Solution />`, while `<DeepDive>` must begin with an `####` heading that has an ID. `<Challenges>` belongs at the end of Learn pages only. Placing two `<Note>` blocks or two `<Pitfall>` blocks back to back goes against the stated spacing rules.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add reactjs/react.dev --skill docs-components -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/docs-components/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/docs-components/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add reactjs/react.dev --skill docs-components -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/docs-components/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add reactjs/react.dev --skill docs-components -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/docs-components/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install reactjs/react.dev .claude/skills/docs-components
```

2. **Manually: put the files in place**
- File: `.github/skills/docs-components/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add reactjs/react.dev --skill docs-components -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/reactjs/react.dev --path .claude/skills/docs-components
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/docs-components/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add reactjs/react.dev --skill docs-components -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/reactjs/react.dev/tree/HEAD/.claude/skills/docs-components/SKILL.md

## When to use it
- choose an MDX component for a note or warning
- format a deep technical section with its heading and ID
- group related examples in `<Recipes>` with solutions
- add exercises to the end of a Learn page

## Example prompts
- Format this MDX warning about a common mistake using the project conventions.
- Group these related examples in `<Recipes>` and include solutions.
- Check heading levels and spacing between `<Note>` and `<Pitfall>` blocks.

## Source text · SKILL.md · CC-BY-4.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: b663c4b0f644851e.

BEGIN THIRD-PARTY FILE b663c4b0f644851e
````text
---
name: docs-components
description: Comprehensive MDX component patterns (Note, Pitfall, DeepDive, Recipes, etc.) for all documentation types. Authoritative source for component usage, examples, and heading conventions.
---

# MDX Component Patterns

## Quick Reference

### Component Decision Tree

| Need | Component |
|------|-----------|
| Helpful tip or terminology | `<Note>` |
| Common mistake warning | `<Pitfall>` |
| Advanced technical explanation | `<DeepDive>` |
| Canary-only feature | `<Canary>` or `<CanaryBadge />` |
| Server Components only | `<RSC>` |
| Deprecated API | `<Deprecated>` |
| Experimental/WIP | `<Wip>` |
| Visual diagram | `<Diagram>` |
| Multiple related examples | `<Recipes>` |
| Interactive code | `<Sandpack>` (see `/docs-sandpack`) |
| Console error display | `<ConsoleBlock>` |
| End-of-page exercises | `<Challenges>` (Learn pages only) |

### Heading Level Conventions

| Component | Heading Level |
|-----------|---------------|
| DeepDive title | `####` (h4) |
| Titled Pitfall | `#####` (h5) |
| Titled Note | `####` (h4) |
| Recipe items | `####` (h4) |
| Challenge items | `####` (h4) |

### Callout Spacing Rules

Callout components (Note, Pitfall, DeepDive) require a **blank line after the opening tag** before content begins.

**Never place consecutively:**
- `<Pitfall>` followed by `<Pitfall>` - Combine into one with titled subsections, or separate with prose
- `<Note>` followed by `<Note>` - Combine into one, or separate with prose

**Allowed consecutive patterns:**
- `<DeepDive>` followed by `<DeepDive>` - OK for multi-part explorations (see useMemo.md)
- `<Pitfall>` followed by `<DeepDive>` - OK when DeepDive explains "why" behind the Pitfall

**Separation content:** Prose paragraphs, code examples (Sandpack), or section headers.

**Why:** Consecutive warnings create a "wall of cautions" that overwhelms readers and causes important warnings to be skimmed.

**Incorrect:**
```mdx
<Pitfall>
Don't do X.
</Pitfall>

<Pitfall>
Don't do Y.
</Pitfall>
```

**Correct - combined:**
```mdx
<Pitfall>

##### Don't do X {/*pitfall-x*/}
Explanation.

##### Don't do Y {/*pitfall-y*/}
Explanation.

</Pitfall>
```

**Correct - separated:**
```mdx
<Pitfall>
Don't do X.
</Pitfall>

This leads to another common mistake:

<Pitfall>
Don't do Y.
</Pitfall>
```

---

## `<Note>`

Important clarifications, conventions, or tips. Less severe than Pitfall.

### Simple Note

```mdx
<Note>

The optimization of caching return values is known as [_memoization_](https://en.wikipedia.org/wiki/Memoization).

</Note>
```

### Note with Title

Use `####` (h4) heading with an ID.

```mdx
<Note>

#### There is no directive for Server Components. {/*no-directive*/}

A common misunderstanding is that Server Components are denoted by `"use server"`, but there is no directive for Server Components. The `"use server"` directive is for Server Functions.

</Note>
```

### Version-Specific Note

```mdx
<Note>

Starting in React 19, you can render `<SomeContext>` as a provider.
````
END THIRD-PARTY FILE b663c4b0f644851e

The third-party file has ended. Everything between the b663c4b0f644851e tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3022 of 11846 bytes. © reactjs · CC-BY-4.0 · https://github.com/reactjs/react.dev/tree/HEAD/.claude/skills/docs-components/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
