diff --git a/.claude/skills/ui-component/SKILL.md b/.claude/skills/ui-component/SKILL.md index a565b35..fbb77ca 100644 --- a/.claude/skills/ui-component/SKILL.md +++ b/.claude/skills/ui-component/SKILL.md @@ -5,13 +5,13 @@ description: Add a shared UI building block (atom, molecule, organism) with its # UI component (atom / molecule / organism) -First: check `shared/ui/` and `shared/layout/` — a new page should be composition of -existing blocks. Only add a block when nothing fits. +First: check `libs/shared/src/ui/` and `libs/shared/src/layout/` — a new page should be +composition of existing blocks. Only add a block when nothing fits. ## Rules -- **Folder = atomic layer**: `shared/ui/` atoms → molecules → organisms; - `shared/layout/` templates. Each level only uses levels below. +- **Folder = atomic layer**: `libs/shared/src/ui/` atoms → molecules → organisms; + `libs/shared/src/layout/` templates. Each level only uses levels below. - Standalone component, **English name** (shared = language-agnostic), signal `input()`s only, `inject()` over constructor DI. - **Atoms are thin wrappers over CIBG Huisstijl (Bootstrap 5.2) classes** (`btn`, @@ -21,7 +21,8 @@ existing blocks. Only add a block when nothing fits. - **Tokens only** — `var(--rhc-*)` / `var(--app-*)`, never hardcoded colors (`npm run check:tokens` fails the build; escape hatch: `token-ok` marker + reason). - **No hardcoded Dutch** in shared components — expose copy as `input()`s with - `$localize` defaults; the domain caller supplies the text (see `shared/ui/async`). + `$localize` defaults; the domain caller supplies the text (see + `libs/shared/src/ui/molecules/async`). - Components with content-projected slots export a spread constant so callers import one thing: `export const ASYNC = [AsyncComponent, AsyncLoadedDirective, …] as const;` @@ -41,9 +42,10 @@ UI test surface. ## Worked examples -- Atom: `src/app/shared/ui/button/` — typed variant API over `btn` classes. -- Molecule: `src/app/shared/ui/async/` — slot directives, localizable input defaults, spread constant. -- Template: `src/app/shared/layout/wizard-shell/` — the canonical wizard outline. +- Atom: `libs/shared/src/ui/atoms/button/` — typed variant API over `btn` classes. +- Molecule: `libs/shared/src/ui/molecules/async/` — slot directives, localizable input + defaults, spread constant. +- Template: `libs/shared/src/layout/wizard-shell/` — the canonical wizard outline. ## Verify diff --git a/CLAUDE.md b/CLAUDE.md index 39353d5..44aead4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,10 +81,11 @@ session protocol is the worked example of this in practice. `apps//src/app///` for an app-local context; `libs//src//` for a cross-app library (WP-67). Two apps today: `apps/ssp` (Zorgverlener self-service — -contexts `auth`, `registratie`, `herregistratie`, `brief` (letter-composition teaching -slice), `showcase` (teaching page, not a feature; **sanctioned** to read every context in -its own app — nothing imports it)) and `apps/behandelportal` (Behandelaar backoffice, -ADR-0002 — contexts `auth`, `behandeling`). Two cross-app libraries: `libs/shared` (the +contexts `auth`, `overzicht` (the portal home; composes `registratie`'s dashboard sections +plus its own cross-context nav sections), `registratie`, `herregistratie`, `brief` +(letter-composition teaching slice), `showcase` (teaching page, not a feature; **sanctioned** +to read every context in its own app — nothing imports it)) and `apps/behandelportal` +(Behandelaar backoffice, ADR-0002 — contexts `auth`, `behandeling`). Two cross-app libraries: `libs/shared` (the design system + kernel + generated API client — no business logic) and `libs/beheer` (the admin/stamdata context, identical for both apps today — WP-67 folded a silently-diverging duplicate copy back into one). `auth` is deliberately **not** shared even though today it's @@ -106,10 +107,11 @@ depend on `libs/beheer` either — it stays the base). `ui`/`layout` never impor lint-enforced (per app, since each app is cruised against its own tsconfig — WP-67's `.dependency-cruiser.base.js` + one thin `.dependency-cruiser..js` per app). An app may not import the other app's source directly. Cross-context only -`herregistratie → registratie → libs/shared|beheer`, `auth → libs/shared|beheer`, -`brief → libs/shared|beheer` (ssp); `behandeling → libs/shared|beheer`, `auth → -libs/shared|beheer` (behandelportal). Imports use aliases as direction statements: -`@shared/* @beheer/* @auth/* @registratie/* @herregistratie/* @brief/*` (ssp) — +`overzicht → registratie → libs/shared|beheer`, `herregistratie → registratie → +libs/shared|beheer`, `auth → libs/shared|beheer`, `brief → libs/shared|beheer` (ssp); +`behandeling → libs/shared|beheer`, `auth → libs/shared|beheer` (behandelportal). Imports use +aliases as direction statements: +`@shared/* @beheer/* @auth/* @overzicht/* @registratie/* @herregistratie/* @brief/*` (ssp) — `@shared/* @beheer/* @auth/* @behandeling/*` (behandelportal); each app's own `tsconfig.json` declares its full map (the root `tsconfig.json` intentionally has no `paths` — see its comment). `domain/` imports nothing from Angular. @@ -129,6 +131,18 @@ the design system does the visuals. (Where CIBG lacks a class — e.g. `skeleton `// CIBG-GAP EXTENSION:` marker; see ADR-0003. `alert` is **not** such a case: it wraps the vendored `.feedback feedback-*` classes.) +**The step-component contract.** A wizard step follows the same rule as +`address-fields.component.ts`: values in, events out, no internal state. Three clauses: + +1. **Inputs down.** A step reads its data only from `input()`s the container passes it. +2. **One narrow output up.** A step emits one specific event, not the container's whole + `dispatch`. +3. **`dispatch` is never passed down.** The container owns the Model and decides what a + step's event means; a step never calls `dispatch` itself. + +Corollary: a step gets **no** story of its own. The wizard's own story already mounts every +step, because it seeds the machine. + ### 3. State: make illegal states unrepresentable Default reflex — **if you're about to add a second/third boolean to track state, @@ -136,7 +150,7 @@ model a discriminated union instead.** Three tools, all in `libs/shared/src/appl - **`RemoteData`** (`remote-data.ts`) — `Loading | Empty | Failure{error} | Success{value}`. Combine sources with `map`/`map2`/`andThen` (Failure > Loading > Success). - Render it via the `` molecule (`libs/shared/src/ui/async`) — one of four + Render it via the `` molecule (`libs/shared/src/ui/molecules/async`) — one of four templates, mutually exclusive by construction. Default loading spinner/skeleton is delay-gated (~250ms) so fast connections don't flash. - **Elm-style store** (`store.ts` → `createStore(initial, reduce)`) — all state in @@ -242,7 +256,7 @@ organism doesn't get its own `Organisms/` bucket). (`` $localize`:@@context.key:Tekst` ``). Source locale is `nl`; a second locale is a translation file, not a code change (the seam). Shared/English components must **not** hardcode Dutch — expose copy as `input()`s with localizable defaults; the domain caller - supplies the text (see `libs/shared/src/ui/async`). Format-validation messages in + supplies the text (see `libs/shared/src/ui/molecules/async`). Format-validation messages in `domain/value-objects/` stay co-located but are still `$localize`-wrapped. - **Forms = one idiom.** Any form with validation or submission uses a `*.machine.ts` (Model/Msg/reduce) + value objects + a `submit-*` command returning `Result` — the @@ -272,7 +286,10 @@ organism doesn't get its own `Organisms/` bucket). - Prettier; `.editorconfig`. tsconfig: `noImplicitReturns`, `noPropertyAccessFromIndexSignature`, `noFallthroughCasesInSwitch`, `isolatedModules`. - **Enforced, not just hoped-for:** `npm run lint` (`eslint.config.mjs`, scoped to - `{apps,libs}/**`) fails the build on `any`; `npm run dep:check` + `{apps,libs}/**`) fails the build on `any`; the same config's `max-lines` rule caps every + `{apps,libs}/**/*.{page,component,section,step}.ts` file at 250 lines + (`skipBlankLines: true`, `skipComments: true`). 250 is reachable, not a style-guide + default — the dashboard page lands at 42 lines. `npm run dep:check` (`.dependency-cruiser.base.js` + one `.dependency-cruiser..js` per app, WP-67) fails on illegal imports — `domain/` importing Angular, a context importing "upward" (the `herregistratie → registratie → shared`, `auth → shared` direction), an app importing the diff --git a/docs/project/readable-codebase/RD-33-claude-md-and-mdx.md b/docs/project/readable-codebase/RD-33-claude-md-and-mdx.md new file mode 100644 index 0000000..ff49f20 --- /dev/null +++ b/docs/project/readable-codebase/RD-33-claude-md-and-mdx.md @@ -0,0 +1,109 @@ +# 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. diff --git a/docs/project/readable-codebase/README.md b/docs/project/readable-codebase/README.md index ac8efac..ab306b8 100644 --- a/docs/project/readable-codebase/README.md +++ b/docs/project/readable-codebase/README.md @@ -127,7 +127,7 @@ two. Note that RD-15 exists because 22 abandoned agent worktrees are still on di | RD-30 | Archive the finished backlogs (16,300 lines) + an archive README | 01 | | done | | RD-31 | `ARCHITECTURE.md` section 6a: symbols not lines, 2 dead paths, new names | 03, 08, 16 | | done | | RD-32 | `fp-tea-atomic-design.md`: 11 broken paths + the broken anchor | 27 | | done | -| RD-33 | CLAUDE.md + `atomic-design.mdx` + the `ui-component` skill | 03, 27, 29 | yes | todo | +| RD-33 | CLAUDE.md + `atomic-design.mdx` + the `ui-component` skill | 03, 27, 29 | yes | done | | RD-34 | _(optional)_ `NO_SUBORGS`/`NO_TABLES` become `RemoteData.Empty` | 11 | | todo | | RD-35 | _(optional, last, alone)_ upload `type:` discriminant to `tag:` | 27 | | todo | | RD-36 | `ui/dashboard/` → `ui/overzicht-secties/` + 2 stale `dashboard.page` paths | 04 | yes | todo | diff --git a/libs/shared/docs/atomic-design.mdx b/libs/shared/docs/atomic-design.mdx index 58abbc0..9a54dd9 100644 --- a/libs/shared/docs/atomic-design.mdx +++ b/libs/shared/docs/atomic-design.mdx @@ -57,9 +57,36 @@ atoms — that is the whole point: fewer things to understand, nothing bespoke p ## The rule, enforced **Each layer only uses layers below it, and dependencies point inward.** This is not a -convention you have to remember — `eslint.config.mjs` fails the build if `domain/` imports -Angular, or if a context imports "upward". See [the FP-in-the-UI primer](?path=/docs/foundations-fp-in-the-ui--docs) -for how the same discipline shapes state and effects. +convention you have to remember — `npm run dep:check` (dependency-cruiser) fails the build if +`domain/` imports Angular, or if a context imports "upward". `eslint.config.mjs` enforces a +different rule: the `any` ban, and a `max-lines` budget (250 lines, `skipBlankLines`, +`skipComments`) on every `{apps,libs}/**/*.{page,component,section,step}.ts` file — reachable, +not a style-guide default, since the dashboard page lands at 42 lines. See +[the FP-in-the-UI primer](?path=/docs/foundations-fp-in-the-ui--docs) for how the same +discipline shapes state and effects. + +## The layer folders + +| Layer | Where | +| --------- | --------------------------------------------------------------------------------------------------------------------------- | +| Atoms | `libs/shared/src/ui/atoms/` | +| Molecules | `libs/shared/src/ui/molecules/` | +| Organisms | `libs/shared/src/ui/organisms/` | +| Templates | `libs/shared/src/layout/` — deliberately holds several layers; its own organisms are chrome that only its own templates use | + +## The step-component contract + +A wizard step follows the same rule as `address-fields.component.ts`: values in, events +out, no internal state. + +1. **Inputs down.** A step reads its data only from `input()`s the container passes it. +2. **One narrow output up.** A step emits one specific event, not the container's whole + `dispatch`. +3. **`dispatch` is never passed down.** The container owns the Model and decides what a + step's event means; a step never calls `dispatch` itself. + +Corollary: a step gets **no** story of its own. The wizard's own story already mounts every +step, because it seeds the machine. ## A composition chain, live diff --git a/libs/shared/docs/layers.mdx b/libs/shared/docs/layers.mdx index 2715ad9..0b982d5 100644 --- a/libs/shared/docs/layers.mdx +++ b/libs/shared/docs/layers.mdx @@ -38,6 +38,7 @@ different login flows, so the two copies are expected to diverge. **Dependencies only point inward, in one declared direction between contexts:** ``` +overzicht → registratie → libs/shared|beheer (ssp) herregistratie → registratie → libs/shared|beheer (ssp) auth → libs/shared|beheer (ssp) brief → libs/shared|beheer (ssp)