axe-core in den Entwickler-Workflow integrieren

1. axe-core als Bibliothek: der Motor hinter vielen Testing-Tools

axe-core ist im Kern eine JavaScript-Bibliothek, die eine gerenderte Seite gegen einen festen Satz von Regeln prüft und für jeden Treffer eine strukturierte Meldung mit betroffenem Element, verletzter Regel und zugehörigem WCAG-Erfolgskriterium zurückgibt. Diese Engine wird nicht neu erfunden, sobald ein neues Tool erscheint, sondern von Deque Systems zentral gepflegt und von Dritt-Werkzeugen als Abhängigkeit eingebunden, weshalb axe DevTools im Browser, Lighthouse in Chrome und jest-axe in der Unit-Test-Suite in aller Regel dieselben Grundbefunde liefern.

Für ein Entwicklungsteam bedeutet das: Wer versteht, wie axe-core als Bibliothek funktioniert, versteht damit gleichzeitig einen großen Teil der automatisierten Barrierefreiheitsprüfung im gesamten Ökosystem, unabhängig davon, ob die konkrete Oberfläche eine Browser-Extension, ein Kommandozeilen-Runner oder ein Storybook-Addon ist. Das erleichtert es, ein einziges gemeinsames Regelverständnis im Team zu etablieren, statt für jedes Tool eine eigene Interpretation zu pflegen.

2. Die Grenzen automatisierter Erkennung: nur 30 bis 40 Prozent der WCAG-Kriterien

Deque selbst gibt an, dass axe-core zuverlässig zwischen 30 und 40 Prozent der WCAG-Erfolgskriterien automatisiert prüfen kann, weil viele Kriterien eine inhaltliche oder kontextuelle Bewertung erfordern, die eine Maschine schlicht nicht leisten kann. Ob ein Alt-Text den Bildinhalt sinnvoll beschreibt, ob eine Fehlermeldung tatsächlich verständlich ist oder ob die Tab-Reihenfolge einer komplexen Formularseite logisch nachvollziehbar bleibt, kann axe-core nicht bewerten. Es kann lediglich feststellen, ob überhaupt ein Alt-Attribut vorhanden ist, nicht ob dessen Inhalt sinnvoll ist.

Dieses Wissen um die Grenze ist entscheidend, damit ein Team nicht in die Falle tappt, eine grüne axe-core-Prüfung mit vollständiger Barrierefreiheit zu verwechseln. Eine Seite ohne axe-core-Fehler kann trotzdem für Screenreader-Nutzende unbrauchbar sein, etwa weil eine Live-Region fehlt, eine Fokusreihenfolge unlogisch springt oder eine Interaktion sich rein visuell, aber nicht semantisch korrekt verhält. Automatisierte Werkzeuge wie axe-core sind ein Sicherheitsnetz gegen offensichtliche technische Fehler, kein Ersatz für manuelle Prüfung und echtes Nutzertesten.

3. Die axe DevTools Browser-Extension im täglichen Einsatz

Die axe DevTools Extension für Chrome und Firefox bindet axe-core direkt in die Browser-Entwicklertools ein und erlaubt einen vollständigen Seiten-Scan mit einem einzigen Klick, ohne dass irgendein Code geschrieben oder ein Build-Schritt ausgeführt werden muss. Für Entwicklerinnen und Entwickler, die gerade an einer Produktdetailseite oder einem Formular im Hyvä-Theme arbeiten, ist dieser Scan die schnellste Möglichkeit, unmittelbar nach einer Änderung zu prüfen, ob neue Verstöße gegen Kontrast, fehlende Labels oder ungültige ARIA-Attribute entstanden sind.

Über den reinen automatisierten Scan hinaus bietet die Extension auch geführte Tests, sogenannte Intelligent Guided Tests, bei denen Kriterien, die axe-core nicht automatisiert prüfen kann, als strukturierte Checkliste mit konkreten Fragen präsentiert werden, etwa ob eine Bildbeschreibung inhaltlich zum Bild passt. Diese geführten Tests schließen einen Teil der Lücke zwischen den 30 bis 40 Prozent automatisierter Abdeckung und einer vollständigen manuellen Prüfung, ohne dass dafür ein separates Tool nötig wäre.

4. axe-core in Storybook integrieren: Komponenten isoliert prüfen

Storybook eignet sich besonders gut für axe-core, weil dort jede Komponente in einem isolierten, kontrollierten Zustand gerendert wird, unabhängig von Seitenkontext oder Ladezustand einer echten Magento-Seite. Das offizielle Addon @storybook/addon-a11y bindet axe-core direkt in jede Story ein und zeigt Verstöße als eigenes Panel neben der Komponente an, sodass ein neues Button- oder Formular-Feld-Design geprüft werden kann, lange bevor es überhaupt in eine echte Seite eingebaut wird.

Der entscheidende Unterschied zur CI-Pipeline liegt im Zeitpunkt: Während eine CI-Prüfung erst beim Push oder Merge-Request greift, meldet das Storybook-Addon Verstöße bereits während der Entwicklung der Komponente selbst, in Echtzeit, während die Story im Browser geöffnet ist. Das verkürzt die Feedback-Schleife von Minuten oder Stunden auf Sekunden und macht Barrierefreiheit zu einem Bestandteil des Komponenten-Designs statt zu einem nachträglichen Korrekturschritt.

// .storybook/main.js
export default {
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-a11y', // rendert axe-core-Ergebnisse im Accessibility-Panel
  ],
};

// .storybook/preview.js
export const parameters = {
  a11y: {
    // Regelsatz auf WCAG 2.1 AA einschraenken, konsistent mit dem Shop-Standard
    config: {
      runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21aa'] },
    },
  },
};

5. axe-core direkt in der lokalen Entwicklung nutzen

Neben Storybook lässt sich axe-core auch ganz ohne zusätzliches Tooling direkt in der Browser-Konsole gegen eine lokal laufende Magento- oder Hyvä-Seite ausführen, indem das Skript einmalig über die Konsole geladen und anschließend axe.run() aufgerufen wird. Dieser Weg eignet sich besonders für einen schnellen Ad-hoc-Check während der Arbeit an einer einzelnen Seite, etwa direkt nach dem Speichern einer .phtml-Datei und dem Neuladen der Seite im Browser.

Für ein etwas dauerhafteres lokales Setup lohnt sich ein kleines Bookmarklet oder ein npm-Skript, das axe-core gegen eine laufende Entwicklungsinstanz ausführt und das Ergebnis direkt im Terminal ausgibt, ohne dass dafür die Browser-Extension geöffnet werden muss. So bleibt der Check so nah wie möglich am eigentlichen Entwicklungsfluss und erzeugt keine zusätzliche Reibung, die Entwickler dazu verleiten würde, den Schritt einfach zu überspringen.

6. Abgrenzung zur CI-Pipeline: Entwickler-Feedback statt Merge-Gate

Eine automatisierte axe-core-Prüfung in der CI-Pipeline, wie sie in einem anderen Artikel dieser Reihe beschrieben wird, verfolgt einen fundamental anderen Zweck als der Einsatz im Entwickler-Workflow: Sie ist ein Gate, das einen Merge-Request bei bekannten, klar definierten Regressionen blockiert, und sie läuft nach der eigentlichen Entwicklungsarbeit, oft Minuten oder Stunden nach der letzten Code-Änderung. Der Entwickler-Workflow mit Storybook, Browser-Extension und lokalem Check hingegen liefert Feedback in dem Moment, in dem eine Komponente entsteht, und verhindert damit, dass ein Fehler überhaupt erst bis zum Commit gelangt.

Beide Ebenen ergänzen sich, ersetzen sich aber nicht gegenseitig: Die CI-Pipeline ist das Sicherheitsnetz für den Fall, dass ein Fehler trotz lokaler Prüfung durchrutscht oder ein Entwickler den lokalen Check aus Zeitdruck übersprungen hat, während der lokale Workflow die Zahl der Fehler reduziert, die überhaupt erst bis zur CI-Stufe vordringen. Ein Team, das nur auf die CI-Pipeline setzt, verlagert Barrierefreiheit an das Ende des Prozesses, wo eine Korrektur teurer ist als am Anfang.

7. Regelsatz und Tags gezielt konfigurieren

axe-core organisiert seine Regeln über Tags wie wcag2a, wcag2aa, wcag21aa oder best-practice, wodurch sich die Prüfung präzise auf den tatsächlich angestrebten Konformitätsgrad einschränken lässt, statt pauschal alle verfügbaren Regeln gegen jede Komponente laufen zu lassen. Ein Shop, der WCAG 2.1 AA als Ziel definiert hat, sollte diesen Tag-Filter konsequent in Storybook, in der Browser-Extension-Konfiguration und in der CI-Pipeline identisch setzen, damit alle drei Ebenen dieselbe Grundlage prüfen und keine widersprüchlichen Ergebnisse liefern.

Für einzelne, bewusst akzeptierte Ausnahmen, etwa ein Drittanbieter-Widget, dessen Markup nicht verändert werden kann, unterstützt axe-core gezielte Ausschlüsse über Selektoren oder einzelne Regel-IDs, sodass ein bekannter, nicht behebbarer Fehler nicht bei jedem einzelnen Lauf erneut als Rauschen erscheint. Solche Ausschlüsse gehören dokumentiert und regelmäßig überprüft, damit sie nicht stillschweigend zu einer dauerhaften Ausrede werden, echte Fehler zu ignorieren.

8. Vom Finding zum Fix: Workflow im Team etablieren

Ein axe-core-Befund, der lokal während der Entwicklung auftaucht, sollte in derselben Sitzung behoben werden, in der die Komponente entsteht, weil der Kontext dann noch vollständig präsent ist und die Korrektur meist nur wenige Minuten kostet. Wird der Befund stattdessen ignoriert und erst später, etwa bei einem separaten Accessibility-Audit, wieder aufgegriffen, muss sich eine andere Person erneut in den Code einarbeiten, was den gesamten Prozess deutlich verlangsamt.

Damit dieser Sofort-Fix-Reflex im Team tatsächlich entsteht, hilft eine klare, gemeinsam getragene Regel: Jede neue Komponente durchläuft vor dem ersten Commit mindestens einen Storybook-Scan oder einen Extension-Check, und ein bewusst akzeptierter, nicht behobener Befund wird niemals stillschweigend übergangen, sondern explizit als Ticket mit Begründung dokumentiert. So bleibt nachvollziehbar, welche Entscheidung getroffen wurde, statt dass Wissen allein im Kopf einer einzelnen Person existiert.

9. Praxisbeispiel: eine Hyvä-Komponente mit axe-core prüfen

Am Beispiel eines Mini-Cart-Dropdowns im Hyvä-Theme zeigt sich der Zusammenspiel aller drei Ebenen konkret: Während der Entwicklung meldet die axe DevTools Extension sofort, dass der Öffnen-Button kein zugängliches Label besitzt, weil nur ein SVG-Icon ohne Text enthalten ist. Die Korrektur mit einem aria-label direkt im Alpine.js-Template ist in weniger als einer Minute erledigt und wird unmittelbar im Browser erneut geprüft, statt erst Stunden später in einem CI-Report aufzutauchen.

Derselbe Test lässt sich anschließend als automatisierter Regressionsschutz in einer Storybook-Story für die Komponente hinterlegen, sodass jede künftige Änderung am Mini-Cart automatisch erneut gegen dieselbe Regel geprüft wird, ohne dass dafür ein manueller Schritt nötig wäre.

<!-- vor der Korrektur: Button ohne zugaengliches Label -->
<button @click="miniCartOpen = true" class="relative">
  <svg class="w-6 h-6" aria-hidden="true"><!-- Warenkorb-Icon --></svg>
</button>

<!-- nach der Korrektur: axe-core meldet keinen Verstoss mehr -->
<button
  @click="miniCartOpen = true"
  class="relative"
  :aria-label="`Warenkorb, ${cartCount} Artikel`"
>
  <svg class="w-6 h-6" aria-hidden="true"><!-- Warenkorb-Icon --></svg>
</button>

10. Zusammenfassung

11. FAQ: axe-core im Entwickler-Workflow: Das Wichtigste auf einen Blick