docs(PBI-49): add debug-labels BEM pattern doc + CLAUDE.md entry
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Scrum4Me Agent
parent
68a2439b72
commit
f33a18c0fa
3 changed files with 117 additions and 0 deletions
|
|
@ -99,6 +99,7 @@ Volledige MCP-tool documentatie: [docs/runbooks/mcp-integration.md](./docs/runbo
|
||||||
| Web Push | `docs/patterns/web-push.md` |
|
| Web Push | `docs/patterns/web-push.md` |
|
||||||
| Job-config resolver (PBI-67) | `lib/job-config.ts` ↔ `scrum4me-mcp/src/lib/job-config.ts` |
|
| 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-id op component-root | `docs/patterns/debug-id.md` |
|
||||||
|
| Debug-labels (BEM) | `docs/patterns/debug-labels.md` |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -73,6 +73,8 @@ Auto-generated on 2026-05-09 from front-matter and headings.
|
||||||
| Title | Status | Updated |
|
| Title | Status | Updated |
|
||||||
|---|---|---|
|
|---|---|---|
|
||||||
| [Bidirectionele async-comms MCP-agent ↔ user](./patterns/claude-question-channel.md) | active | 2026-05-03 |
|
| [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 |
|
| [Entity Dialog](./patterns/dialog.md) | active | 2026-05-08 |
|
||||||
| [iron-session](./patterns/iron-session.md) | active | 2026-05-03 |
|
| [iron-session](./patterns/iron-session.md) | active | 2026-05-03 |
|
||||||
| [Prisma Client singleton](./patterns/prisma-client.md) | active | 2026-05-03 |
|
| [Prisma Client singleton](./patterns/prisma-client.md) | active | 2026-05-03 |
|
||||||
|
|
|
||||||
114
docs/patterns/debug-labels.md
Normal file
114
docs/patterns/debug-labels.md
Normal file
|
|
@ -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 `<body>`.
|
||||||
|
|
||||||
|
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 (
|
||||||
|
<footer
|
||||||
|
className="..."
|
||||||
|
{...debugProps('status-bar')}
|
||||||
|
>
|
||||||
|
{/* inhoud */}
|
||||||
|
</footer>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`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: `<root>__<sub>`. 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 (
|
||||||
|
<footer
|
||||||
|
className="..."
|
||||||
|
{...debugProps('status-bar')}
|
||||||
|
>
|
||||||
|
<span data-debug-id="status-bar__copyright">
|
||||||
|
© {new Date().getFullYear()} Scrum4Me
|
||||||
|
</span>
|
||||||
|
<span data-debug-id="status-bar__build-info">
|
||||||
|
v{version} · gebouwd op {buildDate}
|
||||||
|
{isDev && <DebugToggle />}
|
||||||
|
</span>
|
||||||
|
</footer>
|
||||||
|
)
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Welke sub-elementen instrumenteren
|
||||||
|
|
||||||
|
| Instrumenteer | Voorbeelden |
|
||||||
|
|---|---|
|
||||||
|
| Interactieve elementen | `<button>`, triggers, links, tabs |
|
||||||
|
| Sectie-headers | `<h1>` t/m `<h6>` |
|
||||||
|
| Primaire inhoudstitels of -tekst | hoofdtitel van een kaart, badge-label |
|
||||||
|
|
||||||
|
Bij twijfel: **skip**. Liever te weinig dan ruis.
|
||||||
|
|
||||||
|
## Wat NIET instrumenteren
|
||||||
|
|
||||||
|
| Categorie | Reden |
|
||||||
|
|---|---|
|
||||||
|
| `components/ui/*` | shadcn-primitives — herbruikt op te veel plekken, id zou clashen |
|
||||||
|
| `app/(...)/page.tsx` | v1 scope is alleen `components/` |
|
||||||
|
| Bridges / mounts | Niet-renderende wrappers (`notifications-bridge`, `realtime-bridge`, …) |
|
||||||
|
| Hooks-only files | Files die alleen hooks exporteren en niets renderen |
|
||||||
|
|
||||||
|
## Geen `data-debug-label`
|
||||||
|
|
||||||
|
Het attribuut heet uitsluitend `data-debug-id`. Er bestaat geen `data-debug-label`.
|
||||||
|
De `app/globals.css` tooltip leest `attr(data-debug-id)` — een tweede attribuut
|
||||||
|
zou alleen verwarring geven.
|
||||||
|
|
||||||
|
## Gerelateerde bestanden
|
||||||
|
|
||||||
|
| Bestand | Rol |
|
||||||
|
|---|---|
|
||||||
|
| `lib/debug.ts` | `debugProps()`-helper; retourneert `{}` in productie |
|
||||||
|
| `stores/debug-store.ts` | Zustand-store voor `debugMode`-state en `toggleDebugMode` |
|
||||||
|
| `components/shared/status-bar-debug-toggle.tsx` | `{ }`-knop — synchroniseert localStorage en `body.debug-mode` |
|
||||||
|
| `app/globals.css` | `body.debug-mode [data-debug-id]` — outline + hover-tooltip |
|
||||||
Loading…
Add table
Add a link
Reference in a new issue