Scrum4Me/docs/patterns/debug-labels.md

---
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 |