Scrum4Me Agent f33a18c0fa docs(PBI-49): add debug-labels BEM pattern doc + CLAUDE.md entry

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-05-09 22:41:10 +02:00

3.6 KiB

Raw Blame History

title

status

audience

language

last_updated

when_to_read

Debug-labels: BEM data-debug-id patroon

active

ai-agent

contributor

2026-05-09

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:

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:

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

3.6 KiB Raw Blame History