From f33a18c0fa8cdd86eb0f9fc2f897faaaad456dce Mon Sep 17 00:00:00 2001 From: Scrum4Me Agent <30029041+madhura68@users.noreply.github.com> Date: Sat, 9 May 2026 22:41:10 +0200 Subject: [PATCH] docs(PBI-49): add debug-labels BEM pattern doc + CLAUDE.md entry Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 1 + docs/INDEX.md | 2 + docs/patterns/debug-labels.md | 114 ++++++++++++++++++++++++++++++++++ 3 files changed, 117 insertions(+) create mode 100644 docs/patterns/debug-labels.md diff --git a/CLAUDE.md b/CLAUDE.md index 605ad72..4ed8cdc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -99,6 +99,7 @@ Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbo | Web Push | `docs/patterns/web-push.md` | | Job-config resolver (PBI-67) | `lib/job-config.ts` ↔ `scrum4me-mcp/src/lib/job-config.ts` | | Debug-id op component-root | `docs/patterns/debug-id.md` | +| Debug-labels (BEM) | `docs/patterns/debug-labels.md` | --- diff --git a/docs/INDEX.md b/docs/INDEX.md index ce5557d..99d880b 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -73,6 +73,8 @@ Auto-generated on 2026-05-09 from front-matter and headings. | Title | Status | Updated | |---|---|---| | [Bidirectionele async-comms MCP-agent ↔ user](./patterns/claude-question-channel.md) | active | 2026-05-03 | +| [Debug-id op component-root](./patterns/debug-id.md) | active | 2026-05-09 | +| [Debug-labels: BEM data-debug-id patroon](./patterns/debug-labels.md) | active | 2026-05-09 | | [Entity Dialog](./patterns/dialog.md) | active | 2026-05-08 | | [iron-session](./patterns/iron-session.md) | active | 2026-05-03 | | [Prisma Client singleton](./patterns/prisma-client.md) | active | 2026-05-03 | diff --git a/docs/patterns/debug-labels.md b/docs/patterns/debug-labels.md new file mode 100644 index 0000000..a688f7d --- /dev/null +++ b/docs/patterns/debug-labels.md @@ -0,0 +1,114 @@ +--- +title: "Debug-labels: BEM data-debug-id patroon" +status: active +audience: [ai-agent, contributor] +language: nl +last_updated: 2026-05-09 +when_to_read: "Wanneer je een component aanmaakt of aanpast en debug-ids wilt toevoegen aan sub-elementen." +--- + +# Patroon: Debug-labels (BEM data-debug-id) + +## Doel + +`data-debug-id` geeft Claude (en ontwikkelaars) een ondubbelzinnige naam voor elk +DOM-element. In plaats van "de blauwe knop rechtsonder" zeg je `status-bar__build-info` +— uniek, herleidbaar naar de broncode, en grep-baar. + +## Toggle + +Een `{ }`-knop verschijnt alleen in development (`NODE_ENV !== 'production'`) in de +`StatusBar`. De knop beheert `localStorage['scrum4me:debug-mode']` via +`stores/debug-store.ts` en zet de klasse `debug-mode` op ``. + +In `app/globals.css` activeren de regels onder `body.debug-mode [data-debug-id]`: +- een dashed outline rondom elk geïnstrumenteerd element, +- een hover-tooltip die de waarde van `data-debug-id` toont. + +In productie worden geen `data-debug-id`-attributen gerenderd — `debugProps()` retourneert +een leeg object wanneer `NODE_ENV === 'production'`. + +## Patroon + +### Root-element + +De root van elke named-component gebruikt `debugProps()` uit `@/lib/debug`: + +```tsx +import { debugProps } from '@/lib/debug' + +export function StatusBar() { + return ( + + ) +} +``` + +`debugProps(id)` plaatst `data-debug-id={id}` in development en `{}` in productie. +De `id` is de kebab-case variant van de bestandsnaam, bijv. `status-bar` voor +`components/shared/status-bar.tsx`. + +### Sub-elementen (BEM) + +Interactieve of significante sub-elementen krijgen een inline `data-debug-id` met +BEM-notatie: `__`. Sub-elementen schrijven het attribuut **direct** (niet +via `debugProps`), want ze zijn altijd genest binnen het root-element en zichtbaar +alleen samen met de root: + +```tsx +export function StatusBar() { + return ( +
+ + © {new Date().getFullYear()} Scrum4Me + + + v{version} · gebouwd op {buildDate} + {isDev && } + +
+ ) +} +``` + +## Welke sub-elementen instrumenteren + +| Instrumenteer | Voorbeelden | +|---|---| +| Interactieve elementen | `