atomic-design-poc/docs/backlog/WP-14-storybook-taxonomy.md

WP-14 — Storybook taxonomy reorg + Layers MDX

Status: done (8b19fad) Phase: 3 — Storybook as curriculum

Deviation: the "Layout/" bucket (breadcrumb, site-footer, site-header) wasn't in the Decisions block's explicit scheme, so each got folded into Atoms/Molecules/Organisms by its own doc-comment classification (breadcrumb → Molecules, site-footer/site-header → Organisms, both already documented as such in their component header comments) rather than kept as a separate bucket. Fixing atomic-design.mdx's "status banner" reference (stale since WP-13 deleted upload-status-banner) was caught as a side effect of reviewing every MDX page for broken references — not itself a retitle issue, but the same "unbroken MDX" acceptance criterion covers it.

Why

49 stories sit in a flat Atoms/Molecules/Organisms/Templates/Layout scheme with domain outliers (Registratie/… wizards, one stray Shared UI/Status Badge). The sidebar should tell the repo's actual story: a reusable design system on one side, domain contexts on the other — the DDD seam made visible. The sidebar becomes the curriculum's table of contents.

Read first

• .storybook/preview.ts, .storybook/main.ts
• src/docs/*.mdx (three existing Foundations pages)
• CLAUDE.md naming rule (shared = English, domain = Dutch)

Decisions (pre-made, don't relitigate)

Sidebar scheme (respects the English/Dutch seam):

Foundations/            ← MDX curriculum (all concept pages)
Design System/
  Atoms/… Molecules/… Organisms/… Templates/…   ← everything in shared/ui + shared/layout
Domein/
  Registratie/… Herregistratie/… Brief/… Auth/… ← everything in a context's ui/

• Rule: a component in a context folder gets a Domein/<Context>/ title, full stop (context organisms like aanvraag-block move from Organisms/ to Domein/Registratie/). Component display names stay as authored (the folder tells the context).
• Devtools/ (debug-state) files under Design System/Devtools/.
• Order pinned via parameters.options.storySort: ['Foundations', 'Design System', ['Atoms','Molecules','Organisms','Templates','Devtools'], 'Domein'].

Files

• All *.stories.ts title: fields (~49, mechanical)
• .storybook/preview.ts (storySort)
• Existing src/docs/*.mdx (fix any story references broken by retitling)
• New src/docs/layers.mdx — title Foundations/Layers & Contexts
• CLAUDE.md — the story-title convention (one paragraph in §2 or Conventions)

Steps

1. Retitle all stories per the scheme (fix Shared UI/Status Badge).
2. Add storySort; build Storybook and check the sidebar.
3. layers.mdx: 6 contexts, 5 layers, the inward dependency rule, "this is enforced" (link the eslint rules from WP-03/04), the English/Dutch seam — i.e. the sidebar's own rationale, with links into real stories on both sides.
4. Check every MDX <Canvas of={…}>/story import still resolves (build-storybook catches broken refs — do an explicit pass anyway).
5. Convention into CLAUDE.md.

Acceptance criteria

• Sidebar shows exactly Foundations → Design System → Domein with the sub-order pinned.
• Zero story titles outside the scheme (grep title: and eyeball).
• layers.mdx renders; existing MDX pages unbroken.
• Convention in CLAUDE.md.

Verification

GREEN + npm run test-storybook:ci (the axe run also re-visits every retitled story).

Out of scope

New component stories (WP-15); the remaining curriculum pages (they ship with their invariant-WPs: 05, 07, 08, 13, 17).

Risks

MDX story references breaking on retitle — build-storybook is the catch; fix-forward in the same session.