Edwin van den Houdt
8b19fad558
Retitle all 49 stories into a sidebar that makes the DDD seam visible: Foundations (curriculum) -> Design System (Atoms/Molecules/Organisms/ Templates/Devtools, everything in shared/ui + shared/layout) -> Domein (Registratie/Herregistratie/Auth/Brief, everything in a context's ui/). Pin the order via storySort. Add layers.mdx explaining the split and linking the enforcing eslint rules; document the story-title convention in CLAUDE.md. Fix a stale "status banner" reference in atomic-design.mdx left over from WP-13's upload-status-banner deletion. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
89 lines
3.7 KiB
Markdown
89 lines
3.7 KiB
Markdown
# WP-14 — Storybook taxonomy reorg + Layers MDX
|
|
|
|
Status: done (<pending commit>)
|
|
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.
|