Edwin van den Houdt
f769242f76
Turns the prior roadmap sketch into ordered, gated work packages (enforcement gates, FP/DDD consistency, CIBG fidelity, Storybook curriculum, a11y) from the 2026-07-02 showcase-hardening audit.
80 lines
3.0 KiB
Markdown
80 lines
3.0 KiB
Markdown
# WP-14 — Storybook taxonomy reorg + Layers MDX
|
|
|
|
Status: todo
|
|
Phase: 3 — Storybook as curriculum
|
|
|
|
## 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.
|