Architekturentscheidung (ADR): Entkopplung von _label und _ariaLabel bei wiederholten Aktionen

[deleonio]

Status: Vorgeschlagen
Datum: 26.01.2026
Kontext: UI-Komponenten / Design System / Accessibility

1. Einleitung und Zielsetzung

Diese Architekturentscheidung beschreibt, wie interaktive Elemente in Listen und Tabellen so benannt werden, dass sie gleichzeitig:

• visuell konsistent und UX-gerecht bleiben,
• für Screenreader-Nutzer eindeutig verständlich sind,
• und für Sprachsteuerung eindeutig adressierbar sind.

Kern der Entscheidung ist die kontrollierte Entkopplung des sichtbaren Properties _label vom assistiven Property _ariaLabel.

Regel wird konform umgesetzt: https://www.w3.org/WAI/WCAG22/Understanding/label-in-name.html

2. Personas als Bewertungsrahmen

Diese Entscheidung wird entlang dreier Personas bewertet.

Persona A — Sehender, nicht eingeschränkter Nutzer

• Bedient die Oberfläche mit Maus, Touch oder Tastatur.
• Erkennt Kontext visuell (Zeile, Spalte, Nachbarinhalte).
• Erwartet homogene Beschriftungen (z. B. überall „Speichern“).

➡ Wahrnehmung über _label.

Persona B — Blinder Nutzer (Screenreader)

• Navigiert strukturell über Screenreader.
• Ist auf eindeutige, kontextreiche Namen angewiesen.

➡ Wahrnehmung über _ariaLabel.

Persona C — Sehender Nutzer mit motorischer Einschränkung (Sprachsteuerung)

• Kann visuell erkennen, welcher Button korrekt ist.
• Kann diesen aber nicht anklicken, sondern nur per Sprache auslösen.
• Erwartet eindeutige, sprechbare Elementnamen.

Wichtig:
Am Button steht sichtbar nur:

_label = "Speichern"

In derselben Zeile existiert zusätzlicher sichtbarer Kontext (z. B. „4“, „Rechnung 4711“, „Max Mustermann“).
Dieser Kontext fließt in:

_ariaLabel = "Speichern Zeile 4"

➡ Wahrnehmung über _ariaLabel in Beziehung zu _label.

3. Ausgangslage (Ist-Zustand)

• Jede interaktive Komponente besitzt ein _label.
• Dieses _label wird intern auch als assistiver Name verwendet.

Damit gilt aktuell:

_ariaLabel = _label

Dieses Modell funktioniert für einmalige Aktionen (z. B. „Speichern“ im Dialog), versagt aber in wiederholten Strukturen.

4. Problemstellung

In Listen und Tabellen treten identische Aktionen mehrfach auf:

• _label = "Speichern"
• _label = "Löschen"
• _label = "Bearbeiten"

Visuell ist dies korrekt und erwartet.

Assistiv entstehen jedoch Probleme:

• Screenreader-Nutzer hören mehrere identische Elementnamen.
• Sprachsteuerung kann ein Element nicht eindeutig auswählen („Klicke Speichern“ ist mehrdeutig).

Damit entsteht ein Zielkonflikt:

• UX fordert kurze, homogene _label.
• Barrierefreiheit fordert eindeutige Namen.

5. Architekturentscheidung

Wir erlauben explizit, dass sich _ariaLabel vom _label unterscheiden darf.

5.1 Fallback-Regel

Wenn _ariaLabel nicht gesetzt ist:

_ariaLabel = _label

5.2 Kontextregel

In wiederholten Strukturen wird _ariaLabel um sichtbaren Kontext ergänzt:

_label = "Speichern"
_ariaLabel = "Speichern Rechnung 4711"

Kontext stammt aus sichtbarem Zeileninhalt.

5.3 Teilstring-Regel

Wenn _ariaLabel gesetzt wird, gilt:

_ariaLabel muss _label als Teilstring enthalten.

6. Argumentation anhand der Personas

6.1 Wirkung für Persona A (sehender Nutzer)

• Sieht weiterhin nur _label.
• UI bleibt homogen.
• Kein Informationsverlust.

6.2 Wirkung für Persona B (Screenreader)

• Hört eindeutige _ariaLabel.
• Kann Aktionen eindeutig zuordnen.

6.3 Wirkung für Persona C (Sprachsteuerung)

• Sieht Kontext in der Zeile.
• Spricht _ariaLabel.
• Bedienung wird eindeutig möglich.

7. Visualisierung: Wahrnehmungsebenen

flowchart TB
  subgraph UI["UI (sichtbar)"]
    row["Zeile: 4 | Rechnung 4711 | [Button: 'Speichern']"]
  end

  subgraph Props["Properties"]
    label["_label = 'Speichern'"]
    aria["_ariaLabel = 'Speichern Rechnung 4711'"]
  end

  subgraph Personas["Personas"]
    A["Persona A\n(sehend)"]
    B["Persona B\n(Screenreader)"]
    C["Persona C\n(Sprachsteuerung)"]
  end

  row --> label
  row --> aria

  label --> A
  aria --> B
  aria --> C

Loading

Dieses Diagramm zeigt die Trennung zwischen sichtbarer UI-Ebene (_label) und assistiver Ebene (_ariaLabel).

8. Visualisierung: Erzeugung des _ariaLabel

flowchart LR
  label["_label: 'Speichern'"] --> compose["Compose: _ariaLabel := _label + Kontext"]
  ctx["Kontext: 'Rechnung 4711'"] --> compose
  compose --> aria["_ariaLabel: 'Speichern Rechnung 4711'"]

Loading

Dieses Diagramm zeigt, dass _ariaLabel deterministisch aus _label und sichtbarem Kontext entsteht.

9. Visualisierung: Entscheidungslogik

flowchart TD
  start([Interaktives Element]) --> repeated{Wiederholt sich _label?}
  repeated -- Nein --> ok1[Kein _ariaLabel nötig]
  repeated -- Ja --> inList{Liste/Tabelle?}
  inList -- Nein --> ok2[_ariaLabel optional]
  inList -- Ja --> need[Setze _ariaLabel := _label + Kontext]
  need --> check{_ariaLabel enthält _label?}
  check -- Ja --> done([OK])
  check -- Nein --> fail([Fehler])

Loading

10. Konsequenzen

Positiv

• Deutlich bessere Bedienbarkeit für Screenreader.
• Sprachsteuerung wird zuverlässig nutzbar.
• Visuelle UX bleibt unverändert.

Negativ / Risiken

• Nutzer sehen nur _label, müssen ggf. _ariaLabel sprechen.

  • Abmilderung: Kontext ist sichtbar.

• Risiko inkonsistenter Benennung.

  • Abmilderung: technische Validierung.

Anhang A: Developer Guidelines

A1. Grundregeln

• _label: sichtbare Beschriftung.
• _ariaLabel: assistiver Name.

Fallback:

_ariaLabel = _label

Teilstring-Regel:

• _ariaLabel muss _label enthalten.

A2. Wann _ariaLabel setzen?

• Wiederholte Aktionen in Tabellen/Listen: Pflicht
• Einmalige Aktionen: meist nicht nötig
• Icon-only Buttons: Pflicht

A3. Aufbau eines guten _ariaLabel

Formel:

_ariaLabel = "<_label> <Kontext>"

Kontext muss sichtbar sein:

• sichtbare ID (Rechnung 4711)
• Name/Titel (Max Mustermann)
• sichtbare Zeilennummer

A4. Do / Don’t

Do:

_label="Speichern"
_ariaLabel="Speichern Rechnung 4711"

Don’t:

_label="Speichern"
_ariaLabel="Aktion 4"

A5. Technische Checks

• _ariaLabel enthält _label
• _ariaLabel ist eindeutig im Row-Scope
• Kontext ist sichtbar