WIP: Demo run of docs-review skill to update Stories docs section

[kylegach]

Note

This is a demo run of the skill introduced in #34451.

Run #1 (using this skill)

Prompt

Make a plan to improve the writing-stories section of the docs

Plan generated

Also viewable here, with formatting.

PLAN.md

# Plan: Improve the writing-stories docs section

## Context

The `/docs/writing-stories/` section (15 files) is Storybook's primary guide for story authoring. It has solid coverage but suffers from structural issues: the entry page is overloaded (18+ conditional blocks mixing concept/task/reference), sidebar ordering doesn't match a learning progression, composition info is fragmented across 3 pages, and several pages have content gaps or inconsistencies. This plan addresses these issues using the `/docs-review` skill.

---

## Phase 0: Strategy pass on `index.mdx`

**Mode:** `strategy` | **Impact:** Unblocks Phases 1 and 2a

`index.mdx` tries to be an intro, CSF format reference, rendering tutorial, and composition guide simultaneously. Run `/docs-review` in `strategy` mode to produce a split recommendation:

- **Trimmed `index.mdx`** (concept): What a story is, where stories live, CSF at a high level, pointers to sub-pages
- **Move out**: Custom rendering details (React hooks, Solid signals, render functions) to the CSF API reference or a new "Customizing story rendering" task page
- **Move out**: Abbreviated "Using parameters/decorators/play function" sections become a "Next steps" list

**Deliverable:** Strategy artifact with new outline, what to preserve, what to relocate.

---

## Phase 1: Sidebar reordering

**Mode:** `maintenance` (frontmatter only) | **Impact:** High (navigation)

Reorder to match a learning progression:

| File                                  | New order | Rationale                       |
| ------------------------------------- | --------- | ------------------------------- |
| `index.mdx`                           | 1         | Entry point first               |
| `args.mdx`                            | 2         | Core concept                    |
| `typescript.mdx`                      | 3         | Types for what you just learned |
| `parameters.mdx`                      | 4         | Static metadata                 |
| `decorators.mdx`                      | 5         | Wrapping/context                |
| `loaders.mdx`                         | 6         | Async data                      |
| `tags.mdx`                            | 7         | Organization                    |
| `play-function.mdx`                   | 8         | Interaction testing             |
| `naming-components-and-hierarchy.mdx` | 9         | Sidebar org                     |
| `mocking-data-and-modules/`           | 10        | Advanced                        |
| `build-pages-with-storybook.mdx`      | 11        | Advanced composition            |
| `stories-for-multiple-components.mdx` | 12        | Advanced composition            |

---

## Phase 2: High-impact content improvements

### 2a. `index.mdx` -- Rewrite

**Mode:** `rewrite` | **Doc type:** concept

Execute the Phase 0 split:

- 2-sentence intent-setting opening
- Reduce conditional blocks from 18+ to ~6
- Move React Hooks / Solid Signals / custom rendering details out
- Replace inlined sub-page summaries with a "Next steps" list
- Keep: what stories are, where they live, CSF overview, first example

### 2b. `decorators.mdx` -- Improve

**Mode:** `improve` | **Doc type:** task

- Add explanation of _why_ decorator ordering matters (inner renders inside outer) with a concrete example
- Expand "Using decorators to provide data" with one example or replace with direct cross-reference
- Fix stray colon on line 57

### 2c. `loaders.mdx` -- Improve

**Mode:** `improve` | **Doc type:** task

- Reframe opening: lead with use case (async data before render), then clarify when args/mocking are better
- Add "Component loaders" section between story and global levels
- Cross-reference parameter inheritance in "Loader inheritance" section
- Add "See also" link to mocking section

### 2d. `naming-components-and-hierarchy.mdx` -- Improve

**Mode:** `improve` | **Doc type:** task

- Remove "CSF 3.0" version qualifier (it's been default since Storybook 7)
- Add intent-setting opening sentence
- Add connection back to `index.mdx`

---

## Phase 3: Targeted content fixes

### 3a. `mocking-modules.mdx` -- Improve

- Address TODO on line 12: replace React-only inline example with `<CodeSnippets>` or add framework-agnostic note

### 3b. `build-pages-with-storybook.mdx` -- Improve

- Add note for non-React/Solid users pointing to mocking sub-section
- Trim "Avoiding mocking dependencies" (move detailed React context pattern to mocking-providers page)
- Strengthen "Args composition for presentational screens" (the unique value of this page)

### 3c. `play-function.mdx` -- Maintenance

- Remove redundant opening paragraph (nearly identical text repeated)

### 3d. `parameters.mdx` -- Maintenance

- Add cross-reference to `loaders.mdx` in "Rules of parameter inheritance"

---

## Phase 4: Gap-filling

### 4a. New decision guide: "Choosing the right story API"

**Mode:** `author` | **Doc type:** decision guide

Cover:

- **Args vs loaders vs parameters**: Args for controllable inputs, parameters for addon config, loaders for async data
- **Decorators vs render functions**: Decorators for wrapping, render for changing what renders
- **Mocking approaches**: Module vs provider vs network

Place at order ~8, shifting later pages.

### 4b. Cross-reference audit

**Mode:** `maintenance` (all files)

Ensure:

- Each sub-page links to `index.mdx` and related pages
- Mocking section referenced from `loaders.mdx`, `decorators.mdx`, `build-pages-with-storybook.mdx`
- Addons section referenced where addon behavior is discussed

---

## Execution approach

Each step uses `/docs-review` with the specified mode and page. Work through phases sequentially (0 -> 1 -> 2 -> 3 -> 4). Within phases, pages can be done in any order.

## Verification

After each phase:

- Run `yarn docs:check` to validate snippet references and formatting rules
- Run `yarn fmt:write` to auto-format
- Spot-check the Storybook docs site locally or review rendered MDX for readability

Phase 0 strategy result

Also viewable here, with formatting.

phase-0.md

## Strategy Artifact: `docs/writing-stories/index.mdx`

### Audience

Frontend developers new to Storybook who need to understand what stories are and how they're structured before diving into specific APIs (args, parameters, decorators, etc.).

### Page Job

Introduce the concept of stories — what they are, where they live, and how they're structured in CSF — then point readers to sub-pages for deeper topics.

### Primary Doc Type

`concept`

### Diagnosis

The page currently serves **four jobs simultaneously**:

1. **Concept intro** — what a story is, where stories live (good, keep)
2. **CSF format reference** — default exports, named exports, defining stories (partially keep)
3. **Custom rendering tutorial** — render functions, React Hooks, Solid Signals (move out)
4. **Sub-page summaries** — abbreviated sections on play function, parameters, decorators, multi-component stories (replace with "Next steps" links)

This maps to the **"overloaded overview"** antipattern. The page has 18+ `<If>`/`<If notRenderer>` conditional blocks, mixing framework-specific rendering details with universal concepts.

### Recommended Outline

1. Opening (2 sentences)

   • What a story is and why it matters
   • "Args" terminology note (keep existing)

2. Where to put stories (keep as-is)

   • File colocation pattern

3. Component Story Format (streamlined)

   • What CSF is, link to API reference
   • Meta (default export) — brief explanation + one example
   • Named exports — brief explanation + one example
   • Renaming stories (keep, it's short)

4. Writing stories with args (streamlined from "How to write stories")

   • Multiple stories building on each other (Secondary, Tertiary)
   • Reusing args across components (ButtonGroup example)
   • Live editing with Controls (keep videos)

5. Next steps (replace current inlined summaries)

   • Links to: args, parameters, decorators, play function, custom rendering, multi-component stories

### What to Relocate

| Content                                               | Current location                                      | Destination                                                                    |
| ----------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------ |
| Custom rendering (render functions, story/meta level) | "Custom rendering" subsection                         | Keep a 1-sentence mention + link to CSF API reference (`../api/csf/index.mdx`) |
| React Hooks example                                   | `<If renderer="react">` block                         | CSF API reference or remove (it's an edge case, not intro material)            |
| Solid Signals example                                 | `<If renderer="solid">` block                         | CSF API reference or remove                                                    |
| Svelte CSF children/`asChild` details                 | `<If renderer="svelte">` blocks in "Defining stories" | Svelte-specific section of CSF API reference                                   |
| "Using the play function" summary                     | Section under "How to write stories"                  | Replace with one-line link in "Next steps"                                     |
| "Using parameters" summary                            | Section under "How to write stories"                  | Replace with one-line link in "Next steps"                                     |
| "Using decorators" summary                            | Section under "How to write stories"                  | Replace with one-line link in "Next steps"                                     |
| "Stories for two or more components"                  | Final section                                         | Replace with one-line link in "Next steps"                                     |

### Preserve List

- Opening definition of what a story is (both Svelte and non-Svelte variants)
- "Args" terminology note
- "Where to put stories" section (entire)
- CSF explanation and link to API reference
- Meta/default export example (`button-story-default-export-with-component.md`)
- Named export / defining stories example (`button-story-with-args.md`)
- "Rename stories" section
- Args reuse pattern (Secondary/Tertiary example + ButtonGroup example)
- Controls videos and explanation
- Static title analysis callout (non-Svelte)

### Expected Impact

- Conditional blocks reduced from 18+ to ~6 (Svelte CSF vs standard CSF at intro level only)
- Page becomes a clear concept page with a learning funnel to sub-pages
- Custom rendering details move to where users look them up (API reference), not where they learn what stories are

Output summary

Phase 0 — Strategy artifact written to docs/writing-stories/phase-0.md

Phase 1 — Sidebar reordered to match learning progression (13 pages,
typescript.mdx now has explicit order)

Phase 2 — High-impact content improvements:
- 2a: Rewrote index.mdx — removed custom rendering details (React Hooks, Solid
Signals, Svelte children/asChild), removed inlined sub-page summaries (play
function, parameters, decorators, multi-component), added "Next steps" section.
Conditional blocks reduced from 18+ to 6.
- 2b: Improved decorators.mdx — fixed stray colon, replaced vague "provide data"
section with direct cross-references, added decorator ordering explanation with
visual diagram
- 2c: Improved loaders.mdx — reframed opening (use case first, alternatives
second), added "Component loaders" section, added cross-reference to parameter
inheritance
- 2d: Improved naming-components-and-hierarchy.mdx — added intent-setting opening
 with link back to index

Phase 3 — Targeted content fixes:
- 3a: Replaced TODO in mocking-modules.mdx with framework-agnostic callout
- 3b: Improved build-pages-with-storybook.mdx — consolidated mocking section into
 a concise list, trimmed "Avoiding mocking dependencies" to a short paragraph
with cross-reference, added non-React/Solid callout
- 3c: Removed redundant opening paragraph in play-function.mdx
- 3d: Added loaders cross-reference to parameters.mdx

Phase 4 — Gap-filling:
- 4a: Authored new choosing-the-right-api.mdx decision guide (args vs params vs
loaders, decorators vs render functions, mocking approaches, quick reference
table)
- 4b: Cross-reference audit — populated empty mocking-data-and-modules/index.mdx,
 added "See also" sections to all three mocking sub-pages, fixed broken fragment
link in stories-for-multiple-components.mdx

All changes pass yarn fmt:write and yarn docs:check.

Run #2 (using this skill)

Prompt

Make a plan to improve the writing-stories section of the docs

Plan generated

Also viewable here, with formatting.

PLAN-2.md

# Plan: Re-review writing-stories docs with section-level classification

## Context

The `docs/writing-stories/` section was already improved by a demo run of `/docs-review`, but that run used the **old skill** that treated mixed doc types as an antipattern. The skill has since been updated (`2d1f06a2671`) to support **section-level classification** — well-structured secondary sections (e.g., a task section within a concept page) are now evaluated by their own doc type's criteria rather than triggering split recommendations.

The previous run was too aggressive in some places, stripping well-structured secondary task sections that should have been preserved. This plan re-runs `/docs-review` on pages that need correction, using the updated skill.

---

## Pages that need a fresh `/docs-review` pass

### 1. `index.mdx` — Rewrite (restore secondary sections)

**Mode:** `rewrite` | **Primary type:** concept | **Secondary sections:** task

The demo run converted this from a comprehensive tutorial into essentially a table of contents, removing multiple secondary task sections with code examples:

- "Custom rendering" (framework-specific task guidance with code)
- "Using the play function" (interaction testing with code example)
- "Using parameters" (configuration with code example)
- "Using decorators" (wrapper functionality with code examples)
- "Stories for two or more components" (multi-component pattern with examples)

These were **well-structured secondary task sections** within a concept overview — exactly the pattern the updated skill now supports. The rewrite should restore inline examples while keeping the streamlined structure.

**What to preserve from the demo run:** The improved opening, the "Where to put stories" cleanup, the CSF streamlining, the "Next steps" section (as addition, not replacement).

**What to restore from `next`:** Secondary task sections with code examples, adapted to be clearly headed and properly scoped. Use the phase-0.md strategy artifact as a guide, but don't strip task sections just because they're a different doc type.

### 2. `build-pages-with-storybook.mdx` — Improve (restore context container pattern)

**Mode:** `improve` | **Primary type:** task | **Secondary sections:** task (framework-specific)

The demo run removed the detailed "Avoiding mocking dependencies" section (React/Solid only) which included:

- Context-based container approach explanation
- File structure example
- Multiple implementation code examples
- Mocking containers in Storybook example

This was replaced with 3 summary paragraphs pointing to mocking-providers. The removed content is a well-structured, framework-specific task section that provides implementation details not found in the linked page.

**Action:** Re-run `/docs-review` to evaluate whether this content should be restored as a secondary task section, or whether the mocking-providers page adequately covers it.

### 3. `decorators.mdx` — Improve (evaluate with section-level lens)

**Mode:** `improve` | **Primary type:** concept | **Secondary sections:** task, reference

The demo run's changes here were mostly good (decorator ordering diagram, cleaner cross-refs). Re-run to evaluate secondary sections (e.g., "Context" reference section, framework-specific task sections) with the updated criteria.

### 4. `loaders.mdx` — Improve (component loaders + section evaluation)

**Mode:** `improve` | **Primary type:** concept | **Secondary sections:** task, reference

Two issues:

1. The "Component loaders" section (added by demo run) has only prose — needs a code example
2. Re-evaluate secondary sections with the updated skill

### 5. `args.mdx` — Improve (evaluate with section-level lens)

**Mode:** `improve` | **Primary type:** concept | **Secondary sections:** task, reference

Demo run changes were mostly formatting cleanup. Re-run to evaluate the React-specific "Setting args from within a story" task section and "Mapping to complex arg values" reference section with updated criteria.

---

## Pages that are fine as-is

These pages had appropriate changes from the demo run that don't conflict with section-level classification:

- `typescript.mdx` — formatting cleanup only
- `parameters.mdx` — cross-reference additions
- `play-function.mdx` — redundant opening removed
- `naming-components-and-hierarchy.mdx` — CSF 3.0 qualifier removed, opening added
- `tags.mdx` — formatting cleanup
- `mocking-data-and-modules/*.mdx` — formatting and cross-reference improvements
- `stories-for-multiple-components.mdx` — formatting cleanup
- `choosing-the-right-api.mdx` — new page, well-structured

---

## Cross-reference audit (after re-reviews)

**Mode:** `maintenance` across all files

After the above passes settle, do a final cross-reference pass:

1. Add `choosing-the-right-api.mdx` to "Next steps" in `index.mdx`
2. Link `choosing-the-right-api.mdx` from `args.mdx`, `parameters.mdx`, `loaders.mdx`, `decorators.mdx`
3. Ensure back-links to `index.mdx` from sub-pages that lack them

---

## Execution sequence

1. `/docs-review` rewrite `index.mdx` (highest impact — shapes the rest)
2. `/docs-review` improve `build-pages-with-storybook.mdx`
3. `/docs-review` improve `decorators.mdx`, `loaders.mdx`, `args.mdx` (can be done in any order)
4. Cross-reference audit (`maintenance` mode, all files)
5. Verification: `yarn docs:check` && `yarn fmt:write`

## Verification

- `yarn docs:check` — validate snippet references, formatting, links
- `yarn fmt:write` — auto-format
- Spot-check rendered output for sidebar ordering, secondary section headings, and link correctness

## Critical files

- `docs/writing-stories/index.mdx` — restore secondary task sections
- `docs/writing-stories/build-pages-with-storybook.mdx` — restore context container pattern
- `docs/writing-stories/loaders.mdx` — add component loaders code example
- `docs/writing-stories/decorators.mdx` — evaluate secondary sections
- `docs/writing-stories/args.mdx` — evaluate secondary sections
- `.agents/skills/docs-review/SKILL.md` — the updated skill definition
- `.agents/skills/docs-review/references/docs-strategy.md` — section-level classification rules

Output summary

# Summary: Re-review writing-stories docs with section-level classification

## Context

The `docs/writing-stories/` section had a prior demo run of the `/docs-review` skill that used an older version of the skill which treated mixed doc types as an antipattern. The skill was then updated (`2d1f06a2671`) to support **section-level classification** — well-structured secondary sections (e.g., a task section within a concept page) are now evaluated by their own doc type's criteria rather than triggering split recommendations.

This meant the demo run had been too aggressive in several places, stripping secondary task sections that were actually well-structured. This work re-ran `/docs-review` on affected pages using the updated skill.

---

## Step 1: `index.mdx` — Rewrite

**Problem:** The demo run converted this page from a comprehensive introductory tutorial into essentially a table of contents. Five secondary task sections with code examples were removed and replaced with a bare "Next steps" link list.

**Changes:**

- Restored the **"Custom rendering"** section under "Defining stories" — full Svelte CSF (template snippets, `asChild`, meta-level render) and non-Svelte (render functions at story and meta level) content with code examples and callouts
- Restored **"Working with React Hooks"** and **"Working with Solid Signals"** framework-specific subsections under custom rendering, scoped with `<If renderer>` blocks
- Restored **"Using the play function"** section with `login-form-with-play-function.md` snippet and link to the interactions panel, plus a "For more details" link to `play-function.mdx`
- Restored **"Using parameters"** section with `parameters-in-meta.md` snippet, the backgrounds screenshot, and explanation of parameter levels, plus a "For more details" link to `parameters.mdx`
- Restored **"Using decorators"** section with `button-story-component-decorator.md` snippet, links to decorator levels and addons, plus a "For more details" link to `decorators.mdx`
- Restored **"Stories for two or more components"** section with three code snippets (`list-story-starter.md`, `list-story-expanded.md`, `list-story-reuse-data.md`) and a callout linking to the multi-component stories workflow page
- Added `choosing-the-right-api.mdx` to the "Next steps" list
- Streamlined "Next steps" to avoid duplicating the sections now restored inline (removed args, typescript, parameters, decorators, play function, stories for multiple components; kept choosing the right API, naming/hierarchy, tags, mocking)
- Fixed two deprecated `<IfRenderer>` tags to `<If>` (caught by `yarn docs:check`)

**Preserved from demo run:** Improved opening paragraph, cleaner "Where to put stories" section, streamlined CSF explanation, "Next steps" section (now supplementary rather than the sole content after CSF).

## Step 2: `build-pages-with-storybook.mdx` — Improve

**Problem:** The demo run removed the detailed "Avoiding mocking dependencies" section (React/Solid only), replacing it with 3 summary paragraphs that point to `mocking-providers.mdx`. However, the mocking-providers page covers *how to mock providers with decorators*, not the container-context splitting architecture pattern. The removed content was a well-structured, framework-specific task section with implementation details not found elsewhere.

**Changes:**

- Restored the full **container-context splitting pattern** within the `<If renderer={['react', 'solid']}>` block:
  - Introductory explanation of the approach (why context over direct imports)
  - File structure example (`ProfilePage.js`, `ProfilePageContainer.js`, `ProfilePageContext.js`, etc.)
  - Callout about global container context
  - Step-by-step implementation with 4 code snippet references:
    - `mock-context-create.md` — creating the React context
    - `mock-context-in-use.md` — using `useContext` in the presentational component
    - `mock-context-container.md` — mocking containers in Storybook
    - `mock-context-container-provider.md` — providing containers in the app
    - `mock-context-container-global.md` — mocking global containers in preview
  - Three sub-headings: "Mocking containers in Storybook", "Providing containers to your application", "Mocking global containers in Storybook"
- Improved editorial clarity (e.g., "you" instead of "let's look at", tighter intro paragraphs)

## Step 3: `decorators.mdx` — Maintenance

**Problem:** Minor formatting inconsistency in the "Context for mocking" reference section.

**Changes:**

- Fixed missing spaces in the property list: `argTypes`, `parameters`, `viewMode` now consistently have a space before the dash separator

**Assessment:** Page was otherwise well-structured. All secondary sections (task sections for markup wrapping, Vue-specific features, decorator levels; reference section for context properties and inheritance rules) were properly headed and followed their own doc type shapes. No content restoration needed.

## Step 4: `loaders.mdx` — Improve

**Problem:** The "Component loaders" section (added by the demo run) had only one sentence of prose and no code example. Every other level (story-level with `loader-story.md`, global-level with `storybook-preview-global-loader.md`) had a `<CodeSnippets>` block. This broke the consistent pattern and left readers without a concrete example.

**Changes:**

- Created a new snippet file `docs/_snippets/component-loader.md` with examples for all renderers (Angular, React JS/TS, Solid JS/TS, Svelte CSF/CSF3 JS/TS, Vue JS/TS, Web Components JS/TS). Each example shows `loaders` on the default export / meta (as opposed to the story-level snippet which has it on the named export).
- Added `<CodeSnippets path="component-loader.md" />` to the "Component loaders" section

## Step 5: `args.mdx` — No changes (assessment only)

**Assessment:** Page is well-structured with properly classified secondary sections:

- Task sections: story/component/global args, args composition, "modify any aspect"
- Reference sections: URL args, complex arg mapping, addon usage (in details block)
- Framework-specific task section: React "Setting args from within a story" with `<If renderer="react">`

All secondary sections have clear headings and follow their own doc type shapes. No conflicts with section-level classification. No edits needed.

## Step 6: Cross-reference audit

**Added `choosing-the-right-api.mdx` links to 4 pages:**

- `args.mdx` — added to intro paragraph: "For help deciding between args, parameters, and loaders, see choosing the right API"
- `parameters.mdx` — added to opening paragraph: "For help deciding between parameters, args, and loaders, see choosing the right API"
- `loaders.mdx` — added to intro guidance paragraph: "For help deciding between loaders, args, and parameters, see choosing the right API"
- `decorators.mdx` — added to intro paragraph: "For help deciding between decorators and render functions, see choosing the right API"

**Added `index.mdx` back-links to 2 pages:**

- `decorators.mdx` — changed "When writing stories" to link to `./index.mdx`
- `play-function.mdx` — added "For an introduction to writing stories, see Stories" to opening paragraph

**Final cross-reference coverage:**

- `choosing-the-right-api.mdx` linked from 6 pages (was 2)
- `index.mdx` linked from 6 sub-pages (was 4)

## Verification

- `yarn fmt:write` — passes clean (all files formatted)
- `yarn docs:check` — passes clean (no errors: all snippet paths valid, no deprecated components, no broken heading hierarchy, no formatting violations)

## Files modified

| File | Change type |
|------|------------|
| `docs/writing-stories/index.mdx` | Rewrite — restored 5 secondary task sections |
| `docs/writing-stories/build-pages-with-storybook.mdx` | Improve — restored container-context pattern |
| `docs/writing-stories/decorators.mdx` | Maintenance — formatting fix + cross-references |
| `docs/writing-stories/loaders.mdx` | Improve — component loaders code example + cross-reference |
| `docs/writing-stories/args.mdx` | Cross-reference only |
| `docs/writing-stories/parameters.mdx` | Cross-reference only |
| `docs/writing-stories/play-function.mdx` | Cross-reference only |
| `docs/_snippets/component-loader.md` | New file — component-level loader snippet |

[github-actions]

	Fails
🚫	PR is marked with "ci: do not merge" label.
🚫	PR is not labeled with one of: ["cleanup","BREAKING CHANGE","feature request","bug","documentation","maintenance","build","dependencies"]
🚫	PR is not labeled with one of: ["ci:normal","ci:merged","ci:daily","ci:docs"]
🚫	PR description is missing the mandatory "#### Manual testing" section. Please add it so that reviewers know how to manually test your changes.

Generated by 🚫 dangerJS against 89965f9

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR restructures Storybook's "writing-stories" documentation with a multi-phase plan, reorganizes sidebar navigation order across twelve pages, trims index.mdx to focus on conceptual content, and introduces a new decision guide page. Updates include content refactoring in mocking and loader documentation, improved cross-references, and sidebar order adjustments to reflect a recommended learning progression.

Changes

Cohort / File(s)	Summary
Documentation Planning & Guides docs/writing-stories/PLAN.md, docs/writing-stories/phase-0.md, docs/writing-stories/choosing-the-right-api.mdx	Added multi-phase restructuring plan, phase-0 strategy document for index.mdx refactor, and new decision guide comparing story APIs (args vs parameters vs loaders, decorators vs render functions, mocking approaches).
Index Page Refactoring docs/writing-stories/index.mdx	Significant trimming of conditional renderer-specific content, removal of custom rendering and API subsections, repurposing as simplified conceptual entry with "Writing stories with args" section and "Next steps" link list. Adjusted sidebar order from 2 to 1.
Sidebar Order Updates docs/writing-stories/args.mdx, docs/writing-stories/typescript.mdx, docs/writing-stories/parameters.mdx, docs/writing-stories/decorators.mdx, docs/writing-stories/tags.mdx, docs/writing-stories/play-function.mdx, docs/writing-stories/naming-components-and-hierarchy.mdx, docs/writing-stories/build-pages-with-storybook.mdx, docs/writing-stories/stories-for-multiple-components.mdx	Updated sidebar.order frontmatter across nine pages to reorganize navigation flow, reflecting intended learning progression (args→typescript→parameters→decorators→tags→play→naming→build→stories-for-multiple).
Mocking & Build Documentation Updates docs/writing-stories/build-pages-with-storybook.mdx, docs/writing-stories/mocking-data-and-modules/index.mdx, docs/writing-stories/mocking-data-and-modules/mocking-modules.mdx, docs/writing-stories/mocking-data-and-modules/mocking-network-requests.mdx, docs/writing-stories/mocking-data-and-modules/mocking-providers.mdx	Refactored build-pages mocking sections to point to centralized index, replaced container/context patterns with framework-conditional guidance, added renderer-agnostic callout in mocking-modules, and added cross-reference "See also" sections across mocking pages.
API Documentation Clarifications docs/writing-stories/decorators.mdx, docs/writing-stories/loaders.mdx, docs/writing-stories/parameters.mdx	Updated decorator guidance on context-provider wrapping and dependency ordering, reframed loaders as async pre-render setup instead of performance escape-hatch, added note about loaders following parameter inheritance pattern.
Navigation Link Updates docs/writing-stories/naming-components-and-hierarchy.mdx, docs/writing-stories/stories-for-multiple-components.mdx	Adjusted introductory content to position naming page after initial stories and changed fragment link from anchor to base page reference.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Vue: Make globals reactive in decorators #33562: Modifies docs/writing-stories/decorators.mdx to add Vue reactive-globals decorator guidance, directly related to the decorator documentation updates in this PR.
• Docs: Adjust mocking modules #32808: Updates docs/writing-stories/mocking-data-and-modules/mocking-modules.mdx with troubleshooting guidance, extending the mocking documentation changes in this PR.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/writing-stories/loaders.mdx (1)

35-42: ⚠️ Potential issue | 🟡 Minor

Clarify loader concurrency semantics to match runtime behavior.

Line 37 currently says all loaders run in parallel, but execution is parallel within each level and sequential across levels (global → component → story). The current phrasing can mislead readers about override behavior.

Suggested patch

-- All loaders run in parallel
+- Loaders at the same level run in parallel
+- Loader levels run sequentially: global, then component, then story
 - All results are merged into the `loaded` field in the story context
 - If there are keys that overlap, "later" loaders take precedence (from lowest to highest):

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/writing-stories/loaders.mdx` around lines 35 - 42, The docs incorrectly
state "All loaders run in parallel"; update the text around the `loaders` and
`loaded` field to clarify that loaders run in parallel only within each level
but are executed sequentially across levels (global → component → story), with
results merged into the `loaded` field and later levels overriding earlier ones;
also keep that within each level loaders run in the order they are defined (and
that within-level parallelism means simultaneous execution of that level's
loaders).

🧹 Nitpick comments (2)

docs/writing-stories/mocking-data-and-modules/mocking-modules.mdx (1)

12-16: Consider removing nearby duplicate wording for renderer applicability.

This callout is helpful, but the same point is repeated again in Line 38. Keeping one canonical mention would tighten the page.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/writing-stories/mocking-data-and-modules/mocking-modules.mdx` around
lines 12 - 16, The Callout component paragraph ("The examples on this page use
React, but the mocking techniques apply to all renderers.") is duplicated later
(around Line 38); remove or consolidate the duplicate so there is a single
canonical mention — either keep the existing Callout text and delete the
repeated sentence at Line 38, or replace both with one consolidated Callout to
the same effect; update surrounding copy if necessary to avoid changing page
meaning.

docs/writing-stories/PLAN.md (1)

29-43: Clarify that this ordering table is pre–Phase 4 (or update it to final).

Given the new page at order 8, these values now differ from implemented sidebar orders in this PR. A short note here would prevent confusion for future readers.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/writing-stories/PLAN.md` around lines 29 - 43, Update the ordering table
in PLAN.md to either mark it explicitly as "pre–Phase 4" or adjust the "New
order" numbers to match the final sidebar order; mention the new page
play-function.mdx (order 8) and any shifted entries (e.g.,
typing/typescript.mdx, parameters.mdx, decorators.mdx) so readers won't be
confused. Add a one-line clarifying note immediately above or below the table
stating "This table shows pre–Phase 4 ordering" (or replace the numbers with the
final implemented order), and ensure the note references the table entries like
index.mdx, args.mdx, play-function.mdx, and the mocking-data-and-modules/
section so it's clear which pages are affected.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/writing-stories/phase-0.md`:
- Around line 28-49: The unlabeled fenced code block that begins with the list
("1. Opening..." through "5. Next steps...") must be labeled to satisfy
markdownlint MD040; change the opening fence from ``` to ```text (and leave the
closing ``` unchanged) so the block is explicit; target the fenced block
containing the lines starting with "1. Opening (2 sentences)" and ending with
"5. Next steps (replace current inlined summaries)" and update only the opening
backticks to include the "text" language tag.

---

Outside diff comments:
In `@docs/writing-stories/loaders.mdx`:
- Around line 35-42: The docs incorrectly state "All loaders run in parallel";
update the text around the `loaders` and `loaded` field to clarify that loaders
run in parallel only within each level but are executed sequentially across
levels (global → component → story), with results merged into the `loaded` field
and later levels overriding earlier ones; also keep that within each level
loaders run in the order they are defined (and that within-level parallelism
means simultaneous execution of that level's loaders).

---

Nitpick comments:
In `@docs/writing-stories/mocking-data-and-modules/mocking-modules.mdx`:
- Around line 12-16: The Callout component paragraph ("The examples on this page
use React, but the mocking techniques apply to all renderers.") is duplicated
later (around Line 38); remove or consolidate the duplicate so there is a single
canonical mention — either keep the existing Callout text and delete the
repeated sentence at Line 38, or replace both with one consolidated Callout to
the same effect; update surrounding copy if necessary to avoid changing page
meaning.

In `@docs/writing-stories/PLAN.md`:
- Around line 29-43: Update the ordering table in PLAN.md to either mark it
explicitly as "pre–Phase 4" or adjust the "New order" numbers to match the final
sidebar order; mention the new page play-function.mdx (order 8) and any shifted
entries (e.g., typing/typescript.mdx, parameters.mdx, decorators.mdx) so readers
won't be confused. Add a one-line clarifying note immediately above or below the
table stating "This table shows pre–Phase 4 ordering" (or replace the numbers
with the final implemented order), and ensure the note references the table
entries like index.mdx, args.mdx, play-function.mdx, and the
mocking-data-and-modules/ section so it's clear which pages are affected.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 97b1298c-71e2-4413-8a44-fd3bf7caba89

📥 Commits

Reviewing files that changed from the base of the PR and between 805b048 and d82faaa.

📒 Files selected for processing (18)

• docs/writing-stories/PLAN.md
• docs/writing-stories/args.mdx
• docs/writing-stories/build-pages-with-storybook.mdx
• docs/writing-stories/choosing-the-right-api.mdx
• docs/writing-stories/decorators.mdx
• docs/writing-stories/index.mdx
• docs/writing-stories/loaders.mdx
• docs/writing-stories/mocking-data-and-modules/index.mdx
• docs/writing-stories/mocking-data-and-modules/mocking-modules.mdx
• docs/writing-stories/mocking-data-and-modules/mocking-network-requests.mdx
• docs/writing-stories/mocking-data-and-modules/mocking-providers.mdx
• docs/writing-stories/naming-components-and-hierarchy.mdx
• docs/writing-stories/parameters.mdx
• docs/writing-stories/phase-0.md
• docs/writing-stories/play-function.mdx
• docs/writing-stories/stories-for-multiple-components.mdx
• docs/writing-stories/tags.mdx
• docs/writing-stories/typescript.mdx

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Add a language tag to the fenced block to satisfy markdownlint.

Line 28 opens an unlabeled fenced block, which triggers MD040.

Suggested patch

-```
+```text
 1. Opening (2 sentences)
    - What a story is and why it matters
    - "Args" terminology note (keep existing)
@@
 5. Next steps (replace current inlined summaries)
    - Links to: args, parameters, decorators, play function, custom rendering, multi-component stories
-```
+```

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	```
	1. Opening (2 sentences)
	- What a story is and why it matters
	- "Args" terminology note (keep existing)
	2. Where to put stories (keep as-is)
	- File colocation pattern
	3. Component Story Format (streamlined)
	- What CSF is, link to API reference
	- Meta (default export) — brief explanation + one example
	- Named exports — brief explanation + one example
	- Renaming stories (keep, it's short)
	4. Writing stories with args (streamlined from "How to write stories")
	- Multiple stories building on each other (Secondary, Tertiary)
	- Reusing args across components (ButtonGroup example)
	- Live editing with Controls (keep videos)
	5. Next steps (replace current inlined summaries)
	- Links to: args, parameters, decorators, play function, custom rendering, multi-component stories
	```

🧰 Tools

🪛 markdownlint-cli2 (0.22.0)

[warning] 28-28: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/writing-stories/phase-0.md` around lines 28 - 49, The unlabeled fenced
code block that begins with the list ("1. Opening..." through "5. Next
steps...") must be labeled to satisfy markdownlint MD040; change the opening
fence from ``` to ```text (and leave the closing ``` unchanged) so the block is
explicit; target the fenced block containing the lines starting with "1. Opening
(2 sentences)" and ending with "5. Next steps (replace current inlined
summaries)" and update only the opening backticks to include the "text" language
tag.