Barrierefreiheit im Code-Review verankern

1. Warum Barrierefreiheit ins Code-Review gehört

Barrierefreiheit wird in vielen Teams als Aufgabe für das Projektende behandelt, meist als externer Audit kurz vor dem Launch. Das Problem an diesem Ablauf: Wird eine fehlende Tastaturbedienbarkeit oder ein fehlendes Formular-Label erst Wochen nach dem Merge im Audit gefunden, ist der Code längst produktiv, weitere Features bauen bereits darauf auf, und aus einer Ein-Zeilen-Änderung wird ein Refactoring mit Regressionsrisiko. Ein Accessibility-Check im Code-Review verschiebt den Fehler an den billigsten Punkt im gesamten Entwicklungszyklus: direkt vor dem Merge, während der Autor den Kontext der Änderung noch im Kopf hat und die Korrektur meist nur wenige Minuten kostet.

Dieses Prinzip ist als Shift-Left-Testing bekannt: Qualitätssicherung wandert so früh wie möglich in den Entwicklungsprozess, statt am Ende als separater Prüfschritt angehängt zu werden. Für Magento- und Hyvä-Projekte kommt ein rechtlicher Aspekt hinzu, seit das Barrierefreiheitsstärkungsgesetz (BFSG) 2025 in Kraft getreten ist: Online-Shops mit Endkundengeschäft müssen WCAG 2.2 AA erfüllen. Ein Reviewer, der neue phtml-Templates und Alpine.js-Komponenten mit einer festen Checkliste prüft, verhindert, dass sich Verstöße über Monate im Codebestand ansammeln und am Ende in einem einzigen, teuren Nachbesserungssprint münden.

2. Semantische HTML-Elemente statt Div-Suppe prüfen

Der häufigste Verstoß, der einem Reviewer sofort auffallen sollte, ist die sogenannte Div-Suppe: interaktive Elemente wie Buttons, Links oder Formularfelder werden aus <div> oder <span> mit einem onclick-Handler nachgebaut, statt das passende native Element zu verwenden. Screenreader-Nutzer verlieren dadurch jede Information darüber, dass ein Element überhaupt interaktiv ist, und Tastaturnutzer verlieren automatisch fokussierbare, mit Enter oder Leertaste auslösbare Elemente. Der Reviewer-Check ist einfach zu formulieren: Jedes Element, das eine Aktion auslöst, muss ein <button> sein. Jedes Element, das navigiert, muss ein <a href="..."> sein.

Genauso wichtig sind Landmark-Elemente wie <nav>, <main>, <header>, <footer> und eine lückenlose Überschriftenhierarchie von <h1> bis <h6> ohne übersprungene Ebenen. Screenreader-Nutzer springen mit einem Tastenkürzel direkt zwischen Landmarks und Überschriften, ganz ohne die Seite linear durchzulesen. Fehlt ein <main>-Element in einem neuen Hyvä-Layout-Block, oder springt eine Produktseite von <h2> direkt zu <h4>, bricht genau diese Navigation ab. Das lässt sich in einem Diff meist in Sekunden erkennen, wenn der Reviewer gezielt danach sucht.

<!-- SCHLECHT: Div-Suppe ohne Semantik, Tastatur und Screenreader ausgeschlossen -->
<div class="btn-primary" onclick="addToCart()">
  In den Warenkorb
</div>
<div class="product-nav">
  <div onclick="showTab('description')">Beschreibung</div>
  <div onclick="showTab('reviews')">Bewertungen</div>
</div>

<!-- GUT: native, semantische Elemente mit eingebauter Tastaturbedienbarkeit -->
<button type="button" class="btn-primary" @click="addToCart()">
  In den Warenkorb
</button>
<nav class="product-nav" aria-label="Produktdetails">
  <button type="button" @click="activeTab = 'description'"
          :aria-selected="activeTab === 'description'" role="tab">
    Beschreibung
  </button>
  <button type="button" @click="activeTab = 'reviews'"
          :aria-selected="activeTab === 'reviews'" role="tab">
    Bewertungen
  </button>
</nav>

3. Formulare: Labels, Fehlermeldungen und Pflichtfelder

Formulare sind der Bereich, in dem Barrierefreiheitsfehler am direktesten Umsatz kosten, weil ein Nutzer, der ein Eingabefeld nicht identifizieren kann, den Checkout abbricht. Der wichtigste Reviewer-Check: Jedes <input>, <select> und <textarea> braucht ein zugeordnetes <label> über for/id, niemals nur einen Platzhaltertext. Platzhalter verschwinden beim Tippen, werden von manchen Screenreadern gar nicht vorgelesen und haben zu geringen Kontrast für Nutzer mit Sehbehinderung. Ein Label bleibt dagegen dauerhaft sichtbar und programmatisch mit dem Feld verknüpft.

Fehlermeldungen sind der zweite kritische Punkt: Ein rot eingefärbter Rahmen allein transportiert für Screenreader-Nutzer keine Information. Die Fehlermeldung muss als Text vorhanden und über aria-describedby mit dem Feld verknüpft sein, das Feld selbst braucht aria-invalid="true". Zusammengehörige Radiobuttons oder Checkboxen, etwa bei der Versandartwahl, gehören in ein <fieldset> mit <legend>, damit Screenreader die Gruppenzugehörigkeit ansagen. Pflichtfelder brauchen sowohl das native required-Attribut als auch eine sichtbare Kennzeichnung, damit sehende und nicht-sehende Nutzer dieselbe Information erhalten.

<!-- Accessible Formularfeld mit Label, Pflichtkennzeichnung und Fehlermeldung -->
<div class="form-group">
  <label for="customer-email" class="block font-medium mb-1">
    E-Mail-Adresse <span aria-hidden="true">*</span>
    <span class="sr-only">(Pflichtfeld)</span>
  </label>
  <input
      type="email"
      id="customer-email"
      name="email"
      required
      aria-required="true"
      :aria-invalid="errors.email ? 'true' : 'false'"
      aria-describedby="customer-email-error"
      class="border rounded-lg px-3 py-2 w-full"
  >
  <p id="customer-email-error" class="text-red-600 text-sm mt-1" x-show="errors.email" role="alert">
    Bitte eine gültige E-Mail-Adresse eingeben.
  </p>
</div>

<!-- Zusammengehörige Optionen als Gruppe mit fieldset/legend -->
<fieldset class="border rounded-lg p-4">
  <legend class="font-medium px-2">Versandart</legend>
  <label class="flex items-center gap-2 mb-2">
    <input type="radio" name="shipping" value="standard" checked>
    Standardversand (3-5 Werktage)
  </label>
  <label class="flex items-center gap-2">
    <input type="radio" name="shipping" value="express">
    Expressversand (1 Werktag)
  </label>
</fieldset>

4. Tastaturbedienbarkeit als Pflichtcheck

Der schnellste Accessibility-Check, den ein Reviewer ohne jedes zusätzliche Tool durchführen kann, ist der Tastaturtest: Maus weglegen, mit Tab durch die neue Komponente navigieren, mit Enter oder Leertaste auslösen, mit Escape schließen. Jedes interaktive Element muss auf diesem Weg erreichbar und bedienbar sein, in einer logischen, dem visuellen Layout entsprechenden Reihenfolge. Häufigster Fehler bei selbstgebauten Komponenten wie Custom-Dropdowns: Das Element bekommt zwar einen @click-Handler, aber weder tabindex="0" noch einen @keydown-Handler für Enter und Leertaste, wodurch es für Tastaturnutzer komplett unerreichbar bleibt.

Ein zweiter Klassiker, der in Reviews auffallen sollte: outline: none oder outline: 0 in CSS-Regeln, die den sichtbaren Fokusring entfernen, ohne einen gleichwertigen Ersatz zu definieren. Ohne sichtbaren Fokusindikator verliert ein Tastaturnutzer die Orientierung komplett, weil nicht mehr erkennbar ist, welches Element gerade aktiv ist. Die moderne, korrekte Lösung ist :focus-visible, das den Fokusring nur bei Tastaturnavigation zeigt und bei Maus-Klicks unauffällig bleibt, ganz ohne die früher übliche JavaScript-Krücke zur Unterscheidung von Maus- und Tastaturfokus.

/* SCHLECHT: Fokusring komplett entfernt, keine Alternative definiert */
button:focus,
a:focus,
input:focus {
  outline: none;
}

/* GUT: Fokusring nur für Tastaturnavigation, klar sichtbar */
button:focus-visible,
a:focus-visible,
input:focus-visible,
[tabindex]:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
  border-radius: 4px;
}

/* Maus-Klick bleibt unauffällig, kein störender Ring bei Zeigergeräten */
button:focus:not(:focus-visible) {
  outline: none;
}

/* Custom-Dropdown: sichtbarer Zustand für Tastaturbedienung */
.dropdown-trigger[aria-expanded="true"] {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

5. Fokus-Management bei neuen interaktiven Komponenten

Modals, Dropdown-Menüs, Off-Canvas-Navigation und Toast-Benachrichtigungen sind die Komponententypen, bei denen Fokus-Management-Fehler am häufigsten unbemerkt durch ein Review rutschen, weil sie mit der Maus getestet unauffällig funktionieren. Beim Öffnen eines Modals muss der Fokus programmatisch auf das erste interaktive Element im Modal springen, sonst bleibt der Tastaturfokus unsichtbar irgendwo im Hintergrund liegen, während visuell ein neuer Dialog im Vordergrund erscheint. Innerhalb des offenen Modals muss ein Fokus-Trap verhindern, dass Tab-Navigation aus dem Dialog heraus in den verdeckten Hintergrund springt.

Genauso wichtig, aber noch häufiger vergessen: Beim Schließen des Modals muss der Fokus zurück auf das auslösende Element springen, meist den Button, der das Modal geöffnet hat. Ohne diesen Rücksprung landet der Tastaturfokus nach dem Schließen am Dokumentanfang, und der Nutzer muss sich erneut komplett durch die Seite navigieren. In Alpine.js-Komponenten, wie sie in Hyvä-Themes durchgängig eingesetzt werden, lässt sich dieses Verhalten mit x-init, $refs und einem einfachen Keydown-Handler für Escape und Tab sauber kapseln, ohne zusätzliche JavaScript-Bibliotheken.

// Alpine.js Modal-Komponente mit Fokus-Management und Fokus-Trap
function accessibleModal() {
  return {
    open: false,
    triggerElement: null,

    openModal(event) {
      // Auslösendes Element merken, um Fokus spaeter zurueckzugeben
      this.triggerElement = event.currentTarget;
      this.open = true;
      this.$nextTick(() => {
        // Fokus auf erstes interaktives Element im Modal setzen
        this.$refs.modalPanel.querySelector('button, [href], input')?.focus();
      });
    },

    closeModal() {
      this.open = false;
      // Fokus zurück an das Element, das das Modal geöffnet hat
      this.triggerElement?.focus();
    },

    trapFocus(event) {
      if (event.key === 'Escape') {
        this.closeModal();
        return;
      }
      if (event.key !== 'Tab') return;

      const focusable = this.$refs.modalPanel.querySelectorAll(
        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
      );
      const first = focusable[0];
      const last = focusable[focusable.length - 1];

      if (event.shiftKey && document.activeElement === first) {
        event.preventDefault();
        last.focus();
      } else if (!event.shiftKey && document.activeElement === last) {
        event.preventDefault();
        first.focus();
      }
    }
  };
}

6. ARIA-Attribute korrekt und sparsam einsetzen

Die erste Regel im Umgang mit ARIA lautet: Kein ARIA ist besser als falsches ARIA. Ein <button> mit role="button" ist redundant, aber harmlos. Ein <div> mit role="button", das keinen tabindex und keinen Keydown-Handler besitzt, ist dagegen schädlicher als gar kein ARIA-Attribut, weil es Screenreadern eine Interaktivität vorgaukelt, die tatsächlich nicht vorhanden ist. Reviewer sollten bei jedem role-Attribut prüfen, ob nicht bereits ein natives HTML-Element mit derselben Semantik existiert, das obendrein Tastaturbedienbarkeit gratis mitliefert.

Sinnvoll eingesetzt lösen ARIA-Attribute Probleme, die HTML allein nicht abdeckt: aria-expanded an einem Accordion- oder Dropdown-Trigger kommuniziert den Öffnungszustand, aria-live="polite" an einem Warenkorb-Zähler sorgt dafür, dass Änderungen automatisch angesagt werden, ohne dass der Fokus springt, und aria-label ergänzt fehlenden sichtbaren Text an reinen Icon-Buttons. Wichtig im Review: aria-label überschreibt jeden sichtbaren Text vollständig, weshalb es niemals an Elementen mit bereits vorhandenem, aussagekräftigem Textinhalt verwendet werden sollte, sondern nur dann, wenn tatsächlich kein sichtbarer Text existiert.

7. Automatisierte Checks in CI/CD integrieren

Automatisierte Tools wie axe-core finden zuverlässig etwa 30 bis 50 Prozent aller Barrierefreiheitsfehler, vor allem strukturelle und maschinell prüfbare Probleme wie fehlende Labels, unzureichenden Farbkontrast oder doppelte IDs. Diese Quote klingt niedrig, deckt in der Praxis aber genau die Fehler ab, die am häufigsten versehentlich eingeschleust werden und die ein Reviewer bei zeitlichem Druck am ehesten übersieht. Ein axe-core-Lauf gegen zentrale Templates als Teil der CI-Pipeline verhindert, dass diese Klasse von Fehlern überhaupt bis zum menschlichen Review vordringt, und gibt dem Reviewer die Gewissheit, sich auf die Fälle konzentrieren zu können, die automatisiert nicht erkennbar sind.

Für Hyvä-Projekte bietet sich pa11y-ci als leichtgewichtiges Werkzeug an, das gerenderte Seiten gegen eine Regelliste prüft und bei Verstößen den Build-Status auf Fehler setzt. Wichtig ist, die Regeln bewusst zu kuratieren: Nicht jede WCAG-Regel eignet sich für einen harten CI-Gate, manche produzieren False Positives bei dynamisch generiertem Alpine.js-Markup. Ein pragmatischer Einstieg beschränkt sich auf die Regeln mit der höchsten Präzision, etwa fehlende Labels, fehlende Alt-Texte und unzureichenden Kontrast, und erweitert die Regelmenge schrittweise, sobald das Team Vertrauen in die Ergebnisse gewonnen hat.

{
  "defaults": {
    "timeout": 30000,
    "wait": 500,
    "standard": "WCAG2AA",
    "runners": ["axe", "htmlcs"],
    "ignore": [
      "WCAG2AA.Principle1.Guideline1_4.1_4_3.G18.Fail"
    ]
  },
  "urls": [
    "https://staging.mironsoft.de/",
    "https://staging.mironsoft.de/checkout/cart/",
    "https://staging.mironsoft.de/beispielprodukt.html"
  ]
}

8. Die Checkliste im Pull-Request-Workflow

Eine Checkliste, die niemand liest, bringt keinen Mehrwert. Der wirkungsvollste Ort dafür ist die Pull-Request-Vorlage selbst, als abhakbare Liste, die für jede Änderung mit UI-Auswirkung sichtbar wird. Vier Punkte decken den Großteil der Regressionen ab: Wurden semantische Elemente statt generischer Divs verwendet? Haben alle Formularfelder Labels? Ist die Komponente vollständig per Tastatur bedienbar? Ist der Fokus bei neuen interaktiven Elementen (Modal, Dropdown, Toast) korrekt gesetzt? Diese vier Fragen lassen sich in unter zwei Minuten beantworten und decken die Fehlerklassen ab, die automatisierte Tools am ehesten verpassen.

Entscheidend ist, dass die Checkliste Teil der Definition of Done wird und nicht als optionale Empfehlung im Wiki verstaubt. Ein Reviewer, der ein PR mit neuer interaktiven Komponente approved, ohne den Tastaturtest durchgeführt zu haben, sollte das genauso als unvollständiges Review behandeln wie ein Review ohne Blick auf die Testabdeckung. Manche Teams benennen zusätzlich eine rotierende Accessibility-Verantwortung pro Sprint, damit die Prüfung nicht implizit an alle und damit an niemanden delegiert wird.

9. Gründlichkeit gegen Review-Geschwindigkeit abwägen

Eine vollständige WCAG-2.2-Prüfung mit allen 50 Erfolgskriterien für jeden Pull Request durchzuführen, ist weder praktikabel noch sinnvoll, weil die meisten Änderungen gar keine neuen interaktiven Elemente einführen. Der pragmatische Ansatz ist risikobasiert: Eine reine Textänderung oder eine CSS-Farbanpassung braucht keinen vollen Tastaturtest, eine neue interaktive Komponente wie ein Filterdropdown oder ein Modal dagegen schon. Diese Einstufung lässt sich in der PR-Vorlage direkt als Checkbox abfragen, sodass der Umfang der Prüfung automatisch mit dem Risiko der Änderung skaliert, statt für jede Änderung identisch hoch zu sein.

Automatisierung übernimmt die Fälle mit hoher Präzision und geringem Interpretationsspielraum, etwa fehlende Labels oder Kontrastverstöße. Für den Reviewer bleiben die Fälle, die Urteilsvermögen erfordern: Ist ein Alt-Text tatsächlich aussagekräftig oder nur technisch vorhanden? Ist die Tab-Reihenfolge logisch, auch wenn sie dem DOM entspricht? Diese Aufteilung hält das Review schnell, ohne Gründlichkeit zu opfern, weil der Mensch nur dort geprüft wird, wo Maschinen versagen, und die Maschine dort prüft, wo menschliche Aufmerksamkeit am ehesten nachlässt.

10. Zusammenfassung

Barrierefreiheit im Code-Review löst ein strukturelles Problem: Fehler, die erst in einem späteren Audit auffallen, sind teuer, weil produktiver Code inzwischen darauf aufbaut. Eine feste Checkliste mit vier Kernfragen (semantische Elemente, Formular-Labels, Tastaturbedienbarkeit, Fokus-Management) fängt die häufigsten Regressionen direkt im Pull Request ab, während der Autor den Kontext noch im Kopf hat. Automatisierte Tools wie axe-core und pa11y-ci übernehmen die mechanisch prüfbaren Fälle mit hoher Präzision, sodass der menschliche Reviewer sich auf Urteilsfragen konzentrieren kann, die Maschinen nicht zuverlässig beantworten.

Der entscheidende Hebel für nachhaltige Barrierefreiheit liegt nicht in einem einmaligen, gründlichen Audit, sondern in der konsequenten Anwendung einer schlanken Checkliste über jeden einzelnen Pull Request hinweg. Ein risikobasierter Umfang, der sich an der Art der Änderung orientiert, hält das Review schnell, ohne bei neuen interaktiven Komponenten an Gründlichkeit zu sparen. So bleibt Barrierefreiheit ein fester Bestandteil des täglichen Entwicklungsprozesses statt eines isolierten Compliance-Projekts.

11. FAQ: Barrierefreiheit im Code-Review