# 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

- [x] Sidebar shows exactly Foundations → Design System → Domein with the sub-order
      pinned.
- [x] Zero story titles outside the scheme (grep `title:` and eyeball).
- [x] `layers.mdx` renders; existing MDX pages unbroken.
- [x] 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.