Barrierefreie Webentwicklung mit Astro: Ein Workflow, der WCAG ernst nimmt

Warum Astro – und warum ein eigenes Template

Ja, ich betreue hier und da noch bestehende WordPress-Projekte. Wenn ein Kunde das explizit möchte, liefere ich das auch. Aber die Zukunft der Webentwicklung liegt aus meiner Sicht im Jamstack – statische Generierung, entkoppelte Architekturen, maximale Performance. Innerhalb dieser Kategorie habe ich mich bewusst für Astro entschieden, nachdem ich zuvor mit Eleventy gearbeitet habe.

Das Problem, das jeder kennt, der regelmäßig Projekte aufsetzt: Man fängt jedes Mal bei Null an. Oder fast bei Null. Routing, Layouts, SEO-Grundlagen, Bildoptimierung, Deployment-Config – alles Dinge, die man schon dutzendmal gelöst hat, aber immer wieder neu zusammenstellt.

Deshalb pflege ich ein eigenes Template. Nicht als Produkt, sondern als persönliche Basis, um schnell produktiv zu sein. Ich hatte das schon für Astro 5 veröffentlicht und habe es jetzt für Astro v6 komplett überarbeitet. Diesmal aber mit einigen Eigenentwicklungen, die ich ebenfalls freigegeben habe – Tools, die aus konkreten Projekterfahrungen entstanden sind und die ich inzwischen in jedem Projekt einsetze.

Was mich dabei immer gestört hat: Accessibility-Prüfung war entweder ein manueller Aufwand am Ende des Projekts oder ein externer Scan, dessen Ergebnisse ich für den Kunden irgendwo aufbereiten musste. Vorher-Nachher-Vergleiche, Status-Reports, Nachweise für die WCAG-Konformität – alles Handarbeit. Und seit dem Barrierefreiheitsstärkungsgesetz ist das keine optionale Fleißaufgabe mehr, sondern für viele Unternehmen Pflicht.

Das war der Anlass, mich intensiver mit automatisierter Accessibility-Prüfung zu beschäftigen. Und weil ich gleichzeitig ein Reporting-Ziel hatte – saubere PDF-Reports mit Typst generieren, die man einem Kunden zeigen kann – hat sich beides zusammengefügt.

Das Problem mit Accessibility in der Praxis

Barrierefreiheit ist kein neues Thema. WCAG 2.1 existiert seit 2018. Das Barrierefreiheitsstärkungsgesetz (BFSG) verpflichtet ab Juni 2025 Unternehmen, die Produkte oder Dienstleistungen an Verbraucher anbieten, zur digitalen Barrierefreiheit. Die Anforderungen sind dokumentiert, die Standards klar.

Trotzdem scheitern die meisten Projekte nicht am Wissen, sondern am Workflow.

Der typische Ablauf sieht so aus: Ein Projekt wird gebaut, geht live, und irgendwann – Wochen oder Monate später – prüft jemand die Accessibility. Mit Lighthouse im Browser, einem externen Scanner oder einem manuellen Audit. Die Ergebnisse sind ernüchternd: fehlende Alt-Texte, kaputte Heading-Hierarchien, Formulare ohne Labels, Links ohne Namen.

Das Problem ist nicht, dass diese Fehler schwer zu beheben wären. Das Problem ist der Zeitpunkt. Wenn ein Fehler erst nach dem Deployment auffällt, ist er teuer. Der Code ist gemergt, das Design abgenommen, der Kunde hat abgenickt. Jede Korrektur ist jetzt ein Change Request.

Shift Left: Qualität vor dem Deploy

In der Softwareentwicklung gibt es ein Prinzip, das dieses Problem adressiert: Shift Left. Die Idee ist simpel – Qualitätsprüfungen so früh wie möglich im Entwicklungsprozess verankern. Nicht nach dem Release. Nicht nach dem Deploy. Sondern vor dem Deploy.

Für Security ist das längst Standard. Linter prüfen Code auf Schwachstellen, bevor er committed wird. CI-Pipelines lassen keine Merge Requests durch, die Sicherheitschecks nicht bestehen.

Für Accessibility passiert das fast nie. Die meisten Teams behandeln WCAG-Konformität als Post-Launch-Aufgabe. Das ist so, als würde man erst nach dem Umzug prüfen, ob das Haus eine Tür hat.

Der Workflow: Drei Schichten, ein Ziel

Was ich in meinen Projekten umgesetzt habe, ist ein dreischichtiger Ansatz. Jede Schicht fängt andere Fehler, zu einem anderen Zeitpunkt, mit anderen Werkzeugen.

Schicht 1: Statische Analyse nach dem Build

Die erste Schicht greift direkt nach dem Astro-Build. Kein Browser, kein JavaScript-Rendering, keine Netzwerkzugriffe. Reine HTML-Analyse der generierten Dateien.

Dafür habe ich @casoon/astro-post-audit gebaut – eine Astro-Integration, die sich in den Build-Prozess einklinkt und nach dem Generieren aller Seiten automatisch prüft.

Was geprüft wird:

• HTML-Grundlagen: <html lang>, <title>, Viewport-Meta, Heading-Hierarchie
• Bilder: Fehlende Alt-Texte, dekorative Bilder ohne alt=""
• Links und Buttons: Interaktive Elemente ohne zugänglichen Namen
• Formulare: Inputs ohne Labels, fehlende Fieldsets
• SEO-Signale: Canonical Tags, Meta-Descriptions, Open Graph, JSON-LD
• Interne Links: Kaputte Verweise, fehlende Trailing Slashes, Orphan Pages
• Sitemap-Konsistenz: Abgleich zwischen Canonical-URLs und Sitemap-Einträgen

// astro.config.mjs
import postAudit from '@casoon/astro-post-audit';

export default defineConfig({
  integrations: [
    postAudit({
      preset: 'strict',
      sitemap: { require: true },
      links: { checkExternal: true },
    }),
  ],
});

Der entscheidende Punkt: Wenn ein Check fehlschlägt, bricht der Build ab. Kein Deploy mit kaputtem SEO oder fehlenden Alt-Texten. Das ist kein optionaler Report, den man ignorieren kann. Es ist ein Gate.

Die gesamte Prüfung läuft in unter einer Sekunde – auch bei 400+ Seiten.

Schicht 2: Browser-basierte Audits mit dem Accessibility-Tree

Statische Analyse hat Grenzen. Sie sieht nur den HTML-Code, nicht das, was der Browser daraus macht. ARIA-Attribute, dynamische Inhalte, berechnete Accessible Names – all das existiert erst im Browser.

Dafür gibt es auditmysite – einen Accessibility-Checker, der über das Chrome DevTools Protocol (CDP) den nativen Accessibility-Tree extrahiert und gegen 22 WCAG-Regeln prüft.

# Einzelne Seite prüfen
auditmysite https://example.com

# Gesamte Website via Sitemap
auditmysite --sitemap https://example.com/sitemap.xml

# Report als PDF
auditmysite --sitemap https://example.com/sitemap.xml --format pdf

Während Tools wie axe-core hauptsächlich den gerenderten DOM analysieren, greift auditmysite direkt auf den nativen Accessibility-Tree des Browsers zu – also die Struktur, die Screenreader tatsächlich nutzen. Das ist näher an der Realität als jede DOM-basierte Analyse. Unter der Haube ist es in Rust geschrieben, was bei größeren Websites spürbar schneller ist, aber das ist ein Implementierungsdetail. Installierbar über Homebrew oder als Download.

22 WCAG-Regeln (Level A und AA, teilweise AAA) decken die häufigsten Probleme ab: fehlende Alt-Texte, inkonsistente Heading-Hierarchien, unzureichende Farbkontraste, nicht-fokussierbare Elemente, falsche ARIA-Attribute, Formulare ohne Labels, generische Linktexte.

Schicht 3: E2E-Tests mit axe-core

Die dritte Schicht sind Playwright-Tests mit integriertem axe-core. Diese laufen gegen die gerenderte Seite – mit JavaScript, mit Interaktionen, mit realen Nutzungsszenarien.

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test('Homepage hat keine Accessibility-Violations', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

test('Kontaktformular ist zugänglich', async ({ page }) => {
  await page.goto('/kontakt/');
  await page.getByLabel('Name').fill('Test');
  await page.getByLabel('E-Mail').fill('test@example.com');
  await page.getByRole('button', { name: 'Senden' }).click();
  // Prüfe, ob Fehlermeldungen zugänglich sind
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations).toEqual([]);
});

Diese Tests fangen Fehler, die weder statische Analyse noch einzelne Seiten-Audits finden: Modale Dialoge ohne Focus-Trap, dynamisch geladene Inhalte ohne ARIA-Live-Regionen, Formulare mit unzugänglicher Fehlerbehandlung.

Build-Performance messen

Ein Aspekt, der oft übersehen wird: Jede Integration, die den Build verlangsamt, wird irgendwann abgeschaltet. Deshalb messe ich, wo die Build-Zeit tatsächlich hängenbleibt.

Dafür gibt es @casoon/astro-speed-measure – eine Integration, die den gesamten Build-Prozess profiliert:

• Wie lange braucht jede Astro-Integration?
• Welche Vite-Plugins sind die langsamsten?
• Welche Seiten dauern am längsten zu generieren?
• Wie groß sind die generierten Assets?

import speedMeasure from '@casoon/astro-speed-measure';

export default defineConfig({
  integrations: [
    speedMeasure({
      output: ['console', 'json'],
      baseline: true, // Vergleich mit vorherigem Build
    }),
  ],
});

Das Ergebnis nach jedem Build: Eine Tabelle mit den 10 langsamsten Seiten, den 10 größten Assets und der Gesamtzeit pro Phase. Optional als JSON-Baseline, sodass man Trends über mehrere Builds vergleichen kann.

Wichtig: astro-speed-measure misst die Build-Phase – Integrationen, Vite-Plugins, Seiten-Generierung. Nicht den Post-Audit selbst. Aber genau das hilft bei der Einordnung: Wenn der gesamte Build 12 Sekunden dauert und der Post-Audit unter einer Sekunde liegt, weiß man, dass das Audit-Tooling nicht das Problem ist.

Der Gesamtworkflow

Zusammengefasst sieht der Workflow so aus:

Jede Schicht fängt andere Fehler:

• Schicht 1 fängt strukturelle Fehler: fehlende Alt-Texte, kaputte Links, falsche Heading-Hierarchie. Schnell, automatisch, bei jedem Build.
• Schicht 2 fängt semantische Fehler: falsche ARIA-Rollen, unzureichende Kontraste, nicht-fokussierbare Elemente. Gründlich, regelmäßig, vor dem Release.
• Schicht 3 fängt Interaktionsfehler: modale Dialoge, dynamische Inhalte, Formular-Flows. Gezielt, bei Feature-Änderungen.

Was das Template zeigt

Die beiden Astro-Integrationen sind eingebaut im astro-v6-template – einem Open-Source Monorepo-Template für Astro v6, das zeigt, wie Schicht 1 und 3 in einem echten Projekt aussehen. auditmysite (Schicht 2) läuft als eigenständiges CLI-Tool gegen die deployte oder lokal gestartete Seite.

Das Template enthält:

• Monorepo mit pnpm Workspaces (Landing Page + Blog als separate Apps)
• Shared Design Tokens und Komponenten
• Tailwind v4 mit CSS-first Config
• i18n (Deutsch/Englisch) mit Astros nativem Routing
• Auto-generierte Open Graph Images
• Content Security Policy mit SHA-256 Nonces
• Playwright E2E Tests mit axe-core
• @casoon/astro-post-audit für Post-Build-Checks
• @casoon/astro-speed-measure für Build-Performance

Live-Demo: astrov6.casoon.dev und astrov6blog.casoon.dev

Der Quellcode ist auf GitHub: github.com/casoon/astro-v6-template

Reporting: Vorher-Nachher für den Kunden

Ein Punkt, der bei den meisten Audit-Tools zu kurz kommt: Das Ergebnis muss nicht nur technisch korrekt sein, sondern auch kommunizierbar. Wenn ich einem Kunden sage “Ihre Website hat 47 WCAG-Violations”, hilft das niemandem. Was hilft, ist ein Report, der zeigt: Das war der Stand vor dem Projekt. Das ist der Stand jetzt. Das wurde behoben, das steht noch aus.

auditmysite generiert Reports als JSON, HTML und PDF. Die PDF-Variante nutzt Typst als Satzsystem – dasselbe Tooling, mit dem ich auch Angebote und Rechnungen generiere. Strukturierte Daten rein, sauberes Dokument raus. Kein manuelles Formatieren, kein Copy-Paste aus Browser-Tools.

Das klingt nach einem Detailproblem. Aber in der Praxis ist es der Unterschied zwischen einem Tool, das Entwickler nutzen, und einem Workflow, den man auch in der Kundenbeziehung einsetzen kann. WCAG-Konformität ist seit dem BFSG keine freiwillige Zusatzleistung mehr – und wer dem Kunden einen nachvollziehbaren Nachweis liefern kann, hat einen echten Vorteil.

Einordnung

Barrierefreiheit wird oft behandelt wie ein Feature, das man am Ende dazuschraubt. Ein Audit vor dem Launch, ein paar Fixes, ein Häkchen auf der Checkliste.

Das funktioniert nicht. Nicht bei 400 Seiten. Nicht bei regelmäßigen Content-Updates. Nicht wenn drei verschiedene Teams an einer Website arbeiten.

Was funktioniert, ist ein Workflow, der Accessibility als Qualitätskriterium behandelt – gleichwertig mit Tests, Linting und Security. Automatisiert, reproduzierbar und schnell genug, um bei jedem Build zu laufen. Und mit einem Reporting, das man dem Kunden auf den Tisch legen kann.

Und ja – ich bin mir bewusst, dass Websites als Medium eine Übergangsphase sind. Seit 20 Jahren erfüllen sie im Kern zwei Funktionen: informieren und Konsum anregen. Beides kann KI perspektivisch besser, direkter und personalisierter. Irgendwann wird die KI selbst das Interface sein – kein Browser, keine URL, keine gerenderte Seite dazwischen. Websites werden dann im Geschichtsbuch landen, irgendwo zwischen Kassettenlaufwerken und Telefonbüchern.

Aber dieses „irgendwann” ist nicht morgen. Und solange Menschen Websites bauen, nutzen und darüber Geschäfte machen, sollten diese Websites für alle zugänglich sein. Gerade weil das Medium endlich ist, gibt es keinen Grund, die verbleibende Zeit mit halbgaren Lösungen zu verbringen.

KI-gestützter Workflow: Claude, Skills und MCP

Ein Workflow, der bei jedem Build automatisch prüft, ist gut. Ein Workflow, bei dem die KI beim Entwickeln direkt die richtigen Patterns vorschlägt, ist besser.

In meinem Setup arbeite ich mit Claude Code und nutze Skills – vordefinierte Anweisungen, die Claude kontextbezogen aktiviert. Für Accessibility heißt das: Wenn ich eine neue Komponente baue, kennt Claude die WCAG-Anforderungen, die Template-Konventionen und die passenden ARIA-Patterns. Nicht als generisches Wissen, sondern abgestimmt auf den konkreten Stack.

Dazu kommt MCP (Model Context Protocol) als Brücke zwischen KI und Tooling. Über MCP-Server kann Claude direkt auf Projektressourcen zugreifen – etwa auf die CSS-Komponenten-Bibliothek Webspire, die ich für UI-Patterns und Design-Tokens nutze. Webspire liefert vorgefertigte, accessible CSS-Effekte (Glassmorphism, Animationen, Hover-States), die bereits auf Barrierefreiheit geprüft sind: prefers-reduced-motion wird respektiert, Kontrastverhältnisse stimmen, Fokus-States sind sichtbar.

Der Vorteil: Claude schlägt nicht irgendwelche CSS-Snippets vor, sondern die konkreten Webspire-Klassen, die im Projekt bereits eingebunden sind. Kein Copy-Paste aus Dokumentation, keine manuellen Anpassungen. Die KI kennt den Kontext und liefert Code, der zum Projekt passt – inklusive der Accessibility-Grundlagen.

Das ist kein futuristisches Konzept, sondern mein täglicher Arbeitsablauf. Skills definieren die Regeln, MCP liefert den Kontext, und die drei Audit-Schichten prüfen das Ergebnis. Zusammen ergibt sich ein Workflow, in dem Barrierefreiheit nicht nachträglich geprüft, sondern von Anfang an eingebaut wird.

Die Tools dafür sind Open Source:

• auditmysite – WCAG-Checker in Rust, Reports als JSON/HTML/PDF
• @casoon/astro-post-audit – Post-Build-Audits für Astro
• @casoon/astro-speed-measure – Build-Performance messen
• astro-v6-template – Alles integriert in einem Template
• Webspire – CSS-Komponenten-Bibliothek mit Accessibility-Fokus