Storybook 10.4's docs are deep and well-structured for the happy path, but the 10.0 launch left a trail of dead links to its own headline features, version requirements that disagree across pages, and React-only constraints that aren't surfaced where non-React users will look.
1. Headline 10.0 features ("CSF Next" / "CSF factories") have no docs page (critical)
Location:/docs/api/csf-factories, /docs/api/csf-next, referenced from /releases/10.0, /docs/writing-stories/typescript, /docs/api/csf
Problem: The 10.0 release notes promote "Typesafe CSF factories Preview specifically designed for React developers," and /docs/writing-stories/typescript tells the reader "CSF Next (currently in preview) provides significantly improved TypeScript support, which infers component types automatically and requires no explicit typing for most cases." Both /docs/api/csf-factories and /docs/api/csf-next return HTTP 404. There is no canonical page describing the API, the tradeoffs, or how to opt in.
Consequence: A developer reading the release notes or TypeScript guide and clicking through to learn how to actually use CSF Next/CSF factories lands on a 404. Agents indexing the docs hit the same dead end and will either hallucinate an API or refuse the task. The flagship feature of the major release is effectively undocumented in the docs site.
The fix: Ship /docs/api/csf-factories (or /docs/api/csf-next) with the opt-in mechanism, code examples, the React-only constraint, and a migration path from CSF 3. Until then, replace mentions of "CSF Next" with a link to an RFC or GitHub discussion so the reference resolves to something real.
2. Migration guide tells you to leave test-runner; the test-runner page is gone (critical)
Problem: The 10 migration guide says: "Projects using React, Vue, or Svelte with Vite should consider migrating from test-runner to addon-vitest." But /docs/writing-tests/test-runner returns 404. Meanwhile, /docs/writing-tests/in-ci quietly switches to a Vitest-based script — "test-storybook": "vitest --project=storybook" — without ever explaining the relationship to the old test-runner or what changed.
Consequence: Users on Storybook 8/9 with an existing test-runner setup are told to migrate, but cannot read about the thing they're migrating from. The CI page assumes Vitest with no note that this is new, so anyone whose CI still uses the legacy runner sees a script that won't match their installation. This is a migration guide pointing at a hole.
Code verification
Runtime snippet checks
Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.
The fix: Either keep the test-runner page live for the duration of the 10.x branch with a clear "deprecated, migrate to addon-vitest" banner, or replace the dead URL with a redirect to a dedicated migration page that shows the before/after for package.json and CI configs.
3. Node.js requirement contradicts itself across pages (significant)
Location:/docs/get-started/install vs /docs/releases/migration-guide
Problem: The install page lists "Node.js 20+" in its Version Requirements. The 10 migration guide says: "Node 20.19+ or 22.12+ is now required." Those are not the same. A user on Node 20.10 satisfies the install page's listed requirement but violates the migration guide's stated minimum.
Consequence: Developers and CI configs pinning to Node 20.x as instructed will pass the install page's stated check and then hit failures the migration guide warned about. Agents reading the install page as authoritative will generate setup scripts that fail on 20.10–20.18.
The fix: Pick one source of truth (20.19+ / 22.12+) and replicate it verbatim on the install page, the migration guide, and the system requirements section of llms-full.txt. Add the specific minor versions, not "20+".
4. MDX docs are React-only — buried where Vue/Angular/Svelte users won't see it (significant)
Location:/docs/writing-docs/mdx
Problem: The MDX page contains this critical constraint mid-page: "Storybook's implementation is React-only. That means your documentation is rendered in React, while your stories render in the runtime of your choice." Nothing in /docs/writing-docs/autodocs, the Get Started flow, or the framework-specific guides surfaces this. The manifest tag in /docs/writing-stories/tags similarly says "Included in component/docs manifests (React only)" with no broader callout. The MCP/AI section also limits itself to React.
Consequence: A Vue or Angular team adopts Storybook, builds a docs strategy around MDX, then discovers their non-React project has a React renderer running their docs — which has consequences for bundle size, lifecycle hooks, and provider setup. Same for teams expecting AI/MCP support on non-React projects.
The fix: Add a "Framework support" callout at the top of /docs/writing-docs/mdx, /docs/ai, /docs/writing-stories/tags, and the framework landing pages stating which features are React-only. Mirror this in llms.txt so agents don't recommend MDX/AI features to non-React projects.
5. Legacy URLs that the broader ecosystem still links to 404 (significant)
Problem:/docs/migration-guide returns 404 — the canonical page now lives at /docs/releases/migration-guide. /docs/configure/integration/environment-variables also 404s while sibling pages under /docs/configure/integration/* exist; the actual env-vars page is at /docs/configure/environment-variables. These are exactly the URL shapes that blog posts, Stack Overflow answers, and prior versions of the docs would have linked to.
Consequence: Inbound links from external content, search engine results, and AI agents that learned the old URL pattern (/docs/migration-guide, /docs/configure/integration/...) all hit 404. Developers don't realize the content exists at a different path and assume the docs were removed.
The fix: Add HTTP 301 redirects from these legacy paths to the canonical pages. This is a 30-minute job and recovers a long tail of broken external links.
6. Doc Blocks and Portable Stories landing pages are nav-only stubs (significant)
Problem: Both pages render as landing/nav pages without substantive content in the body — the actual documentation lives only in child pages (doc-block-meta, doc-block-controls, portable-stories-vitest, portable-stories-jest, portable-stories-playwright). There is no overview of what doc blocks exist, how they compose, or which test framework's portable-stories variant you should pick.
Consequence: A developer landing on the parent page from search or a deep link has to manually drill through sidebar entries to discover what's available. Agents fetching the parent URL get nothing actionable. Picking between portable-stories for Vitest vs Jest vs Playwright requires reading three pages with no comparison.
The fix: Each parent page should include a table listing every child block/variant with a one-line description and a use-case ("Use Vitest when... Jest when... Playwright when..."). Same for doc blocks — an index of all blocks with their of/include/exclude shape is the minimum useful content.
7. Visual testing docs collapse into the maintainer's commercial product (significant)
Location:/docs/writing-tests/visual-testing
Problem: The "Visual Tests" page reads as a Chromatic onboarding guide: npx storybook@latest add @chromatic-com/storybook, baseline acceptance UI, chromatic.config.json settings (projectId, buildScriptName, debug, zip). The page is titled as a generic Storybook capability ("Storybook offers native visual testing capabilities through Chromatic") but offers no alternative path — no documentation of how to do visual regression with Playwright snapshots, Percy, Loki, or any non-Chromatic tool, despite Chromatic being a paid product from the same maintainer (disclosed in the footer: "maintenance by Chromatic").
Consequence: A developer who doesn't want a SaaS dependency, or whose org won't approve one, reads the page and concludes Storybook has no visual testing story at all. The conflict-of-interest framing (Chromatic maintains Storybook, and Storybook's docs treat Chromatic as the only visual-testing answer) goes undisclosed in the body of the page.
The fix: Reframe the page as "Visual testing options" with Chromatic as one (the recommended) path and link to at least one self-hosted alternative. Disclose the Chromatic/Storybook relationship inline, not just in the site footer.
8. Installer command grammar is inconsistent across pages (significant)
The install page documents npm create storybook@latest --features docs test a11y, but the a11y page says to install the addon separately with npx storybook add @storybook/addon-a11y — without acknowledging the feature-flag path or which is canonical for a fresh install.
Consequence: An agent or a developer following an end-to-end setup ends up running two different commands (npm create ... --features a11y and npx storybook add @storybook/addon-a11y) that may or may not be idempotent. There's no statement of which to prefer.
The fix: Add a short "When to use which command" section to /docs/addons/install-addons: --features at create time, npx storybook add afterward, never both for the same addon. Mention this in the per-addon install instructions too.
Location:/docs/api/main-config vs /docs/api/main-config/main-config
Problem: The scraped data confirms that /docs/api/main-config/main-config works as the table of main config options, while the parent /docs/api/main-config is a navigation shell. This is an unusual URL pattern (a child page named identically to its parent path segment) and reads like an export bug from a docs generator.
Consequence: External links and agent indexers expect /docs/api/main-config to be the canonical reference. The duplicated segment is also a search/SEO anti-pattern.
The fix: Either flatten the URL (put the content at /docs/api/main-config) or add a 301 from the parent path to the canonical one. While doing it, expose indexers as something more than (⚠️ Experimental) with no link — currently the table entry can't be drilled into.
10. CLI options page documents storybook ai setup but doesn't say what it does (minor)
Location:/docs/api/cli-options, /docs/ai
Problem: The CLI reference lists storybook ai setup [options] with flags -o, --output <path> and --package-manager <type>, but no description of what the command does. /docs/ai describes the agentic setup ("Set up Storybook for me with npx storybook@latest init...") and MCP server but doesn't reference the ai setup subcommand or the --output flag that writes a prompt to a file.
Consequence: A developer scanning storybook --help or the CLI reference sees ai setup and doesn't know whether to use it, the npx storybook add @storybook/addon-mcp path, or the agentic prompt. The three flows are not reconciled.
The fix: Add a one-paragraph description to storybook ai setup in the CLI reference describing what --output writes and how the output feeds into the agentic setup flow on /docs/ai. Cross-link the two pages.
11. Telemetry-disable mechanism documented three ways without precedence (minor)
Location:/docs/configure/telemetry
Problem: The page lists three ways to opt out (disableTelemetry: true in main config, --disable-telemetry CLI flag, STORYBOOK_DISABLE_TELEMETRY=true env var) without saying which takes precedence if a CI environment sets one and a project config sets another. Also doesn't say whether disableTelemetry: true survives storybook@latest upgrade automigrations.
Consequence: Organizations with strict data-egress policies can't verify that one of the methods is sufficient or whether they need belt-and-suspenders. Agents writing configs for hardened environments don't know which knob to touch.
The fix: State the precedence order explicitly and confirm whether disableTelemetry is preserved across upgrades.
What they do well
llms.txt and llms-full.txt exist — Storybook is one of the few sites in this audit class to ship an LLM index, and it includes a deep TOC.
CSF and writing-stories docs are genuinely thorough — the args/decorators/play-function trio is well-cross-referenced with consistent code examples.
AI contribution policy is unusually clear — disclose AI use, no AI-only PRs, the 3-day auto-close rule. This is rarer than it should be.
Top 3 recommendations
Ship the CSF Next / CSF factories page — the 10.0 release is the moment users go looking, and the page is missing.
Backfill redirects and the test-runner page — /docs/migration-guide, /docs/writing-tests/test-runner, and /docs/configure/integration/environment-variables are high-traffic legacy URLs that should at minimum 301.
Lock down version requirements in one place — the Node 20+ vs 20.19+ contradiction is the kind of thing that costs every team a half-day, and it's a five-minute fix.