Review, improve, rewrite, author, or plan Storybook documentation in /docs. Use this when asked to review docs, improve a page, rewrite documentation, draft new docs, or advise on docs strategy.
This file owns Storybook-specific editorial, MDX component, frontmatter, and validation rules. It does not own doc-type identification, mode routing, or intervention logic — those belong in docs-strategy.md.
Voice and Tone
Point of View
Second person ("you") for addressing the reader — this is the default.
First person plural ("we") when speaking from Storybook's perspective (e.g., "We recommend…") or walking through something together (e.g., "Let's take a look…").
Do not use first person singular ("I") or third person for the reader ("the user").
Tone
Professional but conversational — write as if explaining to a colleague, not a textbook.
Encouraging without being excessive — "That's great!" is fine occasionally; avoid over-the-top enthusiasm.
Solution-focused — emphasize what readers can accomplish rather than limitations.
Direct and confident — state recommendations clearly ("We recommend…") rather than hedging unnecessarily.
Sentence Structure
Prefer active voice over passive ("Storybook renders the component" not "The component is rendered by Storybook").
Use short, direct sentences for emphasis and introductions.
Longer sentences are acceptable when explaining complex relationships, but avoid run-ons.
Lead with purpose — open sections by stating what something is or why it matters, not with background.
Instructions
Use imperative mood for step-by-step instructions: "Run this command", "Add the following", "Create a new file".
Use suggestive phrasing for optional or alternative approaches: "You can also…", "You might want to…".
Use declarative phrasing to introduce code examples with context: "To define the args of a single story, use the args CSF story key:".
Contractions
Use contractions naturally (don't, can't, won't, you'll, it's, we're) — they reinforce the conversational tone.
Avoid contractions in callout warnings or other serious/cautionary contexts where precision matters.
Technical Terms
Define key terms on first use, then use them freely afterward (e.g., "Component Story Format (CSF)" then "CSF").
Link to related concepts rather than re-explaining them inline.
Assume basic web development knowledge (HTML, CSS, JavaScript, components) — don't over-explain fundamentals.
Block-level JSX elements (e.g. <Callout>, <details>, <If>) follow these rules:
New line before and after elements (unless the content before/after is a comment, in which case there should be no new line between the comment and the element).
New line before and after content inside elements (<summary> is an exception — no new line between the opening <details> tag and the <summary> tag).
Content is not indented, except when the content would normally be indented (e.g. nested list items, content inside code blocks).
Good example:
<If renderer={['react']}>
Other content.
<Callout variant="info">
This is a callout.
- This is a list item inside the callout
- This is a nested list item inside the callout
```json
{
"key": "value"
}
```
</Callout>
More other content.
<details>
<summary>This is a summary</summary>
This is content inside the details element.
</details>
More other content.
</If>
{/* End supported renderers */}
Bad example:
<If renderer={['react']}>
Other content.
<Callout>
This is a callout.
- This is a list item inside the callout
- This is a nested list item inside the callout
```json
{
"key": "value"
}
```
</Callout>
More other content.
<details>
<summary>This is a summary</summary>
This is content inside the details element.
</details>
More other content.
</If>
{/* End supported renderers */}
Validation
Items marked [auto] above are checked by yarn docs:check (see scripts/docs/check-docs.ts). Items marked [oxfmt] are handled by yarn fmt:write.
These are final-stage validation tools. Run them after structural and editorial work is complete, not as the first step.
