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 (
+
+ )
+}
+```
+
+## Welke sub-elementen instrumenteren
+
+| Instrumenteer | Voorbeelden |
+|---|---|
+| Interactieve elementen | `