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

• grep -n overzicht CLAUDE.md returns the context, the alias and the arrow.
• grep -n max-lines CLAUDE.md returns the budget, with the glob and the two skip options.
• CLAUDE.md states the step contract and the "no story for a step" corollary.
• No document credits eslint.config.mjs with the layer rules.
• Every path in .claude/skills/ui-component/SKILL.md resolves.
• 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.