Skip to content
Documentation

ADR-016: Storybook IA & Navigation

Decision

The Storybook sidebar has a fixed allowlist of root sections (including Legal Components for specialized legal-document patterns), a capped depth, and a three-layer wayfinding model (tree, tags, badges). All roots collapse by default, section landing pages are ordered with a 00- prefix, and internal links are authored as relative .mdx paths and generated, never hardcoded.

Key rules

  • Canonical root sections (allowlist): 00 — Start Here, Components, Foundations, Patterns, Legal Components, Templates, ZZ - Deprecated. Never create a new root section without proposing an addition to this ADR.
  • Sidebar depth cap is 3 levels for all roots.
  • Storybook owns components, patterns, and microapps only — general documentation (ADRs, engineering practices, AI/agent skills, product specs, compliance) lives in docs/ and is served by the Astro Starlight site at docs-site/, not Storybook. There is no Docs root.
  • Check the allowlist before writing any new story title — use an existing root.
  • “Move” means placing the file in the folder that represents its sidebar location.
  • Tree placement expresses the primary outcome: Components/<Family>/<Name> or Patterns/<WorkflowArea>/<Name>.
  • use:* tags signal cross-cutting use cases (use:auth, use:forms, use:legal); the use:* vocabulary is closed — check the canonical list before inventing a new tag.
  • status:* tags signal maturity and mirror ADR-010 labels: status:experimental, status:beta, status:stable.
  • ESLint rules local/story-title-taxonomy and local/closed-tag-vocab enforce the taxonomy in CI.
  • All root sections collapse by default — never set a root to expanded by default. The collapsedRoots config lives only in .storybook/manager.tsx.
  • .storybook/storybook-roots.ts is the single source of truth for roots, auto-generated by scripts/sync-storybook-roots.mjs — never hand-edit it; manual edits are overwritten. Run the sync script whenever a new root section is added.
  • Section landing pages (overview/hub files) use a 00- filename prefix (00-overview.mdx, 00-start-here.mdx) so they sort first within their folder. This still applies to src/stories/** and templates/**.
  • The docs/ landing-page, cross-link-resolution, and link-map rules formerly in this section were Storybook-specific mechanics for the retired docs/ → Storybook glob. docs/ now builds through the Astro Starlight site at docs-site/, which resolves relative .mdx links and page hierarchy natively — see ADR-018. pnpm run docs:landing:check, generate-link-map, and check-storybook-links still run against docs/ today but are legacy holdovers pending a Starlight-native replacement; do not add new dependencies on navigateStorybookParent or ?path=/docs/... URLs for docs/ content.

Why

A fixed root allowlist plus a depth cap keeps the sidebar shallow and predictable, while the tree/tags/badges split lets a story express its primary outcome by location and its cross-cutting use by closed-vocabulary tags. Collapsing every root by default keeps the initial view scannable, and routing all root config through a single generated source file prevents drift. Authoring links as relative .mdx paths and generating the final URLs means a path change never silently breaks a cross-reference.

Applies when

You are creating, moving, or renaming a story; assigning tags; adding a root section or editing the manager configuration; creating a documentation section or landing page; or writing internal cross-links between Storybook doc pages.

  • ADR-010 — component maturity versioning (the status:* labels this taxonomy mirrors).
  • ADR-019 — Storybook draft state (the draft tag).
  • ADR-018 — single MDX format.
  • ADR-019 — deprecated root governance.
  • ADR-020 — docs folder convention and IA.
  • ADR-020 — docs IA canonical decision map.
  • ADR-017 — Storybook documentation truthfulness.
  • ADR-024 — engineering practices internal taxonomy.