atomic-design-poc/docs/project/readable-codebase/RD-33-claude-md-and-mdx.md

# RD-33 — CLAUDE.md, `atomic-design.mdx` and the `ui-component` skill

Status: done
Phase: 5 — fix the docs that describe this flow

## Why

This arc added a context, a lint rule and a component contract. Three agent-facing documents
still describe the app as it was before.

CLAUDE.md is the file every agent reads first. It does not name the `overzicht` context that
RD-03 created, and it does not name the `max-lines` budget that RD-02 enforces. An agent that
follows it writes a 400-line page into the wrong context and meets a red build it was never
warned about.

`atomic-design.mdx` credits `eslint.config.mjs` with the layer rules. Dependency-cruiser
enforces them. Crediting the wrong tool sends the next reader to the wrong file.

## Read first

- `docs/project/readable-codebase/PLAN.md` §3c (line 604, the step contract), §4a (line 721,
  the layer move) and phase 5 items 4 and 5 (line 837).
- `CLAUDE.md` — sections "1. DDD", "2. Atomic design", "5. Testing" and "Enforced, not just
  hoped-for".
- `libs/shared/docs/atomic-design.mdx:60`, `libs/shared/docs/layers.mdx:41-45`.
- `.claude/skills/ui-component/SKILL.md`.

## Decisions (pre-made, do not relitigate)

1. **CLAUDE.md gains `overzicht` in three places.** The context list in section 1, the alias
   list (`@overzicht/*`, which `apps/ssp/tsconfig.json:9` already declares), and the
   cross-context arrow. The rule in `.dependency-cruiser.ssp.js:8` is `overzicht: ['registratie']`,
   so the arrow is `overzicht → registratie → libs/shared|beheer`.
2. **CLAUDE.md gains the `max-lines` budget** under "Enforced, not just hoped-for", stated as
   the rule states it: 250 lines, `skipBlankLines` and `skipComments`, over
   `{apps,libs}/**/*.{page,component,section,step}.ts` (`eslint.config.mjs:64-68`). Say that
   250 is reachable, not a style-guide default — the dashboard page is 42 lines.
3. **CLAUDE.md gains the step-component contract**, in section 2 beside the atomic rules. Three
   clauses, from PLAN §3c: inputs down, one narrow output up, and `dispatch` is never passed
   down. Add the corollary: a step gets **no** story of its own, because the wizard's story
   already mounts it by seeding the machine.
4. **The `libs/beheer` title rule is already in CLAUDE.md.** RD-28 landed it. Verify the
   sentence is there and correct; do not write it a second time.
5. **`atomic-design.mdx:60` names the wrong tool.** The layer rules are dependency-cruiser
   (`npm run dep:check`, `.dependency-cruiser.base.js` plus one file per app). ESLint owns the
   `any` ban and `max-lines`. Name each tool for what it actually does.
6. **`atomic-design.mdx` gains the step contract and the layer table**, so the Storybook reader
   and the CLAUDE.md reader get the same rule. The table is the shape RD-27 produced:
   `libs/shared/src/ui/atoms|molecules|organisms/` and `libs/shared/src/layout/`, with the note
   that `layout/` deliberately holds several layers.
7. **`layers.mdx` is missing the `overzicht` arrow.** Its list at lines 41-45 predates RD-03.
   Add the same arrow as decision 1. This is one line, in the same commit, because the two
   documents state the same rule and must not disagree.
8. **The `ui-component` skill's example paths are pre-monorepo.** Lines 44-46 read
   `src/app/shared/ui/button/`, `src/app/shared/ui/async/` and `src/app/shared/layout/wizard-shell/`.
   They are now `libs/shared/src/ui/atoms/button/`, `libs/shared/src/ui/molecules/async/` and
   `libs/shared/src/layout/wizard-shell/`. Lines 8, 13 and 24 say `shared/ui/` where the folder
   is now the layer — name the layer folder, because that is the whole point of RD-27.
9. **CLAUDE.md:153 and CLAUDE.md:259 carry the same stale-path defect.** Both cite
   `libs/shared/src/ui/async`, which RD-27 moved to `libs/shared/src/ui/molecules/async`. Fix
   both in this commit, alongside decision 8's identical fix in the skill file.

## Files

- `CLAUDE.md`
- `libs/shared/docs/atomic-design.mdx`
- `libs/shared/docs/layers.mdx`
- `.claude/skills/ui-component/SKILL.md`

## Steps

1. CLAUDE.md: decisions 1, 2, 3, and the check in decision 4.
2. `atomic-design.mdx`: decisions 5 and 6.
3. `layers.mdx`: decision 7.
4. `.claude/skills/ui-component/SKILL.md`: decision 8.
5. `npm run ci --full`.

## Acceptance criteria

- [x] `grep -n overzicht CLAUDE.md` returns the context, the alias and the arrow.
- [x] `grep -n max-lines CLAUDE.md` returns the budget, with the glob and the two skip options.
- [x] CLAUDE.md states the step contract and the "no story for a step" corollary.
- [x] No document credits `eslint.config.mjs` with the layer rules.
- [x] Every path in `.claude/skills/ui-component/SKILL.md` resolves.
- [x] `npm run ci --full` is green.

## Verification

1. `npm run ci --full`. This ticket edits two `.mdx` files, and only `build-storybook` catches
   a broken MDX import. Plain `npm run ci` does not build Storybook.
2. `npm run storybook` — open Foundations, Atomic design and Layers. Both pages render, and the
   new table is readable at a narrow width.
3. `grep -oE '\`[^\`]_(apps|libs)/[^\`]_\`' .claude/skills/ui-component/SKILL.md | tr -d '\`' |
   xargs ls -d` — every path resolves.

## Out of scope

- `ARCHITECTURE.md` (RD-31) and `fp-tea-atomic-design.md` (RD-32).
- The other skills in `.claude/skills/`. Only `ui-component` carries stale layer paths.
- Renaming `ui/dashboard/`. RD-36 owns that, and it runs after this ticket.

## Risks

1. **A broken MDX import passes `npm run ci` and fails CI.** This is PLAN risk 7. Run `--full`.
2. **CLAUDE.md is long, and a rule added in the wrong section is a rule nobody finds.** Put
   each addition in the section that already owns its subject: contexts in 1, the step contract
   in 2, the lint budget in "Enforced, not just hoped-for".
3. **Two documents, one rule.** `layers.mdx` and CLAUDE.md both state the cross-context arrows.
   Write the same arrow in both, or the next reader gets to choose which one to believe.