SocialGouv/ultra11y

ultra11y — Prüfung von WCAG 2.2 AA und Erstellung barrierefreien Markups

Bei der Barrierefreiheit sieht ein automatisiertes Tool nur einen Teil des Problems. ultra11y begegnet dem mit einer Arbeitsteilung: Die deterministische, installierfreie Engine (node scripts/ultra11y.mjs <Befehl> — kein npm install, kein Schlüssel; der JSX/TSX-Parser ist im Bundle eingebettet) erledigt die mechanische Arbeit — erkennt maschinell prüfbare Nichtkonformitäten und ordnet sie dem richtigen WCAG-Erfolgskriterium zu — und der aktive Codierungsagent entscheidet über die Beurteilungskriterien selbst — Alternativtextrelevanz, Linkzweck im Kontext, Lesereihenfolge — statisch, anhand der von der Engine gesammelten Beweise (verify --manual), wobei jedes Urteil durch verify/check abgesichert ist. Nur die wirklich gerenderten DOM-Kriterien (berechneter Kontrast, sichtbarer Fokus, Zoom/Reflow, Inhalte bei Hover) fallen in den scan-Bereich (axe-core in einem echten Browser); ein Mensch ist höchstens als optionale Aufsicht vorgesehen. Gatter verhindern, dass halluzinierte Nichtkonformitäten überleben, und nichts ist stillschweigend „konform".

Verwechseln Sie Regeln nicht mit Kriterien. Das Bundle enthält 93 statische Prüfungen, WCAG AA hat 55 Erfolgskriterien, und RGAA hat 106 Kriterien. Mehrere Regeln können ein Kriterium belegen, eine Regel kann zu mehreren Paketkriterien beitragen, und die meisten Kriterien bleiben offen, bis ein Scan oder eine Beurteilung erfolgt. Die einzige ehrliche Ausführungsabdeckung ist die Live-Provenienz-Zählung des Rasters (moteur + scan + agent, plus etwaige benannte unentscheidbare Reste), niemals ein festes Versprechen wie „48 Agent-Kriterien". GitHub-Zusammenfassungen zeigen daher entschieden/gesamt, keinen Prozentsatz über die kleine entschiedene Teilmenge.

WCAG 2.2 Level AA ist der weltweite Kern. Landesstandards — das französische RGAA, das US-amerikanische Section 508, die EU-EN 301 549 — sind einsteckbare Standards-Pakete, die ihre Kriterien auf WCAG abbilden. Fügen Sie --standard rgaa hinzu, um jeden Befehl und jede Ausgabe neu zu schlüsseln — einschließlich audit, Ergebnisse und allem; stecken Sie ein externes Paket zur Laufzeit ein mit --pack ./pack.json (oder einer .ultra11yrc.json), ohne Neuerstellung; oder tragen Sie Ihr Land bei (siehe references/standards.md). Pakete (und ihre konkreten Umsetzungsleitfäden — die RGAA SocialGouv/etalab guten/schlechten Muster) können KI-gestützt und durch pack check abgesichert werden, sodass eine erfundene Zuordnung niemals durchkommt — siehe references/packs.md und references/guidance.md.

Der Großteil der Arbeit liegt bei Ihnen. Von den 55 WCAG 2.2 AA Erfolgskriterien kann die Engine 3 direkt entscheiden; 14 benötigen eine gerenderte Seite (scan) und 38 sind Beurteilungsentscheidungen, die der Agent trifft. Eine saubere Ausführung der Engine ist also ein Ausgangspunkt, niemals ein Urteil — und references/adjudication.md ist die Seite, mit der Sie tatsächlich arbeiten.

Kernregeln:

1. Erfinden Sie niemals eine Nichtkonformität: Jede NC zitiert ein reales, auflösbares Element (check verifiziert es).
2. Native HTML zuerst, ARIA zuletzt; duplizieren Sie niemals implizite Semantik.
3. Erfinden Sie auch niemals eine Konformität: Ein C wird genau wie ein NC zitiert — es benennt in citations[] die gesammelten Beweise, die es bestanden hat, wobei jeder Anker auflösbar ist und aus den tatsächlich vorgelegten Beweisen dieses Kriteriums stammt. Ein Kriterium, das ohne Beweise vorgelegt wird, kann überhaupt nicht C sein; es bleibt manual. Ebenso wenig kann ein Kriterium, dessen Auswertung UNVOLLSTÄNDIG war (evidenceComplete: false), bestanden werden: Ein Kriterium, von dem Ihnen ein Teil gezeigt wurde, kann immer noch an dem, was Sie gesehen haben, scheitern, aber es kann niemals über das hinaus bestanden werden, was Sie nicht gesehen haben. Und ein beurteiltes C wird niemals mit einem von der Engine entschiedenen zusammengeführt: Berichte listen es separat auf und halten es aus der automatischen Bestehensquote heraus. 3b. Was Ihnen gezeigt wird, ist die gesamte Population, einmal pro unterschiedlichem Ding gesagt. Beweise sind ein repräsentatives Element pro INHALTSKLASSE, mit occurrences, den anderen Ankern in alsoAt, und den pages, auf denen es vorkommt — 887 Links über 38 erfasste Seiten sind 97 unterschiedliche (Text, href)-Paare. Das Urteil über das repräsentative Element gilt für alle, was ein ehrliches C erreichbar macht; und ein Zitat, das irgendein Vorkommen einer Klasse nennt, die das Kriterium trägt, wird akzeptiert, also zitieren Sie das, das Sie tatsächlich geöffnet haben.
4. Rest ist explizit, niemals stillschweigend konform: Der KI-Agent beurteilt jedes Beurteilungskriterium selbst (verify --manual, abgesichert), und die Rendering-Kriterien gehen an scan — das jetzt C abschließt (decidedBy: "scan"), wenn jede Regel, die ein Kriterium trägt, auf jeder Seite im Umfang ausgeführt wurde und nichts gemeldet hat, und schweigt, wenn selbst eine Seite Signale unvollständig waren. Jedes noch nicht bewiesene Kriterium bleibt „manuell zu bewerten" — kein Status ohne ein aufgezeichnetes, begründetes Urteil. Um dies zu einem Gatter und nicht nur zu einer Hoffnung zu machen, schlägt check --in <audit.json> --require-decided fehl, solange noch etwas zu bewerten ist, und --allow-undecided <file> nimmt die Kriterien, die Sie wirklich nicht entscheiden können, jedes mit seinem Grund (eine benannte Liste, niemals ein Schwellenwert). --require-decided=pages hält JEDES eigene Raster jeder Seite an denselben Standard: Ein Kriterium, das auf einem Pfad fehlschlägt, ist für den Durchlauf entschieden und kann dennoch auf den Pfaden, auf denen es nie ausgelöst wurde, niemandes Urteil sein, woran ein seitenweises Ergebnis tatsächlich gemessen wird. Die ausgegebene Arbeitsliste ist maßgeblich. Sie kann absichtlich ein Kriterium enthalten, dessen ausführungsweiter Status bereits NC ist, weil dieser Fehler das Kriterium auf den anderen Seiten nicht entschieden hat. Ein solches Element ist nicht redundant: Geben Sie ein begründetes Urteil dafür zurück (oder einen expliziten manual-Grund), lassen Sie es niemals leer, weil die globale Zählung entschieden aussieht.
5. Schlagen Sie das Kriterium nach; erinnern Sie sich niemals daran. criteria [--standard <pack>] <id> — oder ultra11y_criteria über MCP — gibt den eigenen Wortlaut des Kriteriums, seine nummerierten Tests und die Glossardefinitionen, die diese Tests zitieren, zurück. RGAA 8.3 ist nicht „die Seite benötigt ein lang-Attribut"; es ist Test 8.3.1 mit zwei alternativen Bedingungen, und das Glossar entscheidet, was seine Begriffe bedeuten. Ein Prüfblock, der 8.3.1 nach dem Lesen zitiert, ist fundiert; einer, der es aus dem Gedächtnis zitiert, ist eine Vermutung, die eine Referenz trägt. Bevor Sie gegen einen Landesstandard prüfen, führen Sie den Plan aus (ultra11y_method): Er sagt Ihnen, wie viele seiner Kriterien noch eine Beurteilung benötigen, um ein C zu erhalten — für RGAA 104 von 106. Siehe references/mcp.md.
6. Das ENDGÜLTIGE gerenderte semantische HTML muss korrekt sein. Die Engine sieht nur den Quellcode; eine Komponentenbibliothek (DSFR/MUI…) oder .vue/.svelte/.astro SFC verbirgt das eigentliche Markup, daher ist eine grüne Quellcode-Prüfung kein Beweis. Überprüfen Sie das produzierte semantische HTML — installieren Sie den berührungslosen Capture-Harvester (render --setup), sodass jede von Ihren Tests gerenderte Komponente in .ultra11y/captures serialisiert und geprüft wird, wobei audit --require-captures die blinden Flecken absichert. Siehe references/automation.md / rendered.md.
7. Sprache: ÜBERGEBEN Sie IMMER --lang passend zur Sprache Ihrer Konversation mit dem Benutzer; fragen Sie den Benutzer bei Mehrdeutigkeit. Ohne das Flag erkennt die CLI automatisch (Repository <html lang> → die Standard-Gebietsschemaeinstellung des aktiven Standards → Englisch) — ein skript-/CI-Fallback, kein Ersatz für die Übergabe von --lang selbst.
8. Technische Token bleiben auf Englisch, selbst in französischem Prosa. In jedem französischen Dokument, das Sie verfassen (Berichtskommentare, PRD, Tracker-Tickets, Urteilsbegründungen), sind Attribut-/Element-/Rollenamen und ihre Werte Code, kein Prosa — übersetzen Sie sie niemals: aria-live bleibt aria-live (niemals „région live"), genauso für tabindex, alt, role="alert", Landmarken-Rollennamen. Der eigene fr-Katalog der Engine folgt dem; passen Sie sich an. Normatives Standardvokabular (RGAA-Wortlaut wie „lien d'évitement") behält sein offizielles Französisch.

Die Referenzbibliothek

Fachwissen zuerst, dann die Werkzeuge. Lesen Sie die, die zur vorliegenden Frage passt.

Barrierefreiheits-Wissen
references/adjudication.md	Wie man jedes der 52 Kriterien entscheidet, die die Engine übergibt — die Entscheidungsregel, wann NA legitim ist, die Fragen
references/naming.md	Berechnung des zugänglichen Namens, 2.5.3 Label-in-Name, visuell verstecktes CSS, Benennung von Bildern/SVG/Figuren
references/widgets.md	ARIA APG zusammengesetzte Muster, Tastaturverträge, Fokusverwaltung, SPA-Routenwechsel, Live-Regionen
references/forms-and-errors.md	Labels und Anleitungen, die autocomplete-Tokenliste, Fehlererkennung/-vorschlag/-vermeidung, redundante Eingabe, zugängliche Authentifizierung
references/structure.md	Überschriften, Landmarken, Listen und dl, einfache und komplexe Tabellen, sinnvolle Reihenfolge
references/media-and-motion.md	Untertitel/Audiobeschreibung/Transkripte, Zeigergesten, Zielgröße, Orientierung, Ref low, reduzierte Bewegung
references/forbidden-patterns.md	15 Anti-Patterns: schlecht → warum → native Lösung → Kriterium
references/focus-and-logic.md	Die Fokus-/Tastaturkriterien, die Sie betreffen, und wie Sie darüber argumentieren
references/criteria.md	Die 55 Kriterien: Stufe, Automatisierbarkeitsklasse, Engine-Regeln, Paketzuordnung (generiert)
references/rgaa-automation.md	RGAA 4.1.2: generierte 106-Kriterien-/258-Test-Matrix, entscheidende Regeln, Kandidatensignale und Stillepolitik
references/act.md	Was die Engine messbar erkennt — und was sie nachweislich nicht erkennt (generiert)

Ausführen des Werkzeugs
references/runbook.md	Der zuverlässige Durchlauf: das eine Rezept, der zu verwendende Transport und warum, und was ein Durchlauf kostet. Lesen Sie dies, bevor Sie für eine Beurteilung bezahlen
references/claude-code-report.md	Claude Codes detaillierter Veröffentlichungspfad: gerenderter Umfang, direkte Beurteilung, adversarielle Verifikation, Markdown + HTML + seitenweise Beweise
references/audit.md	Der Prüfzyklus von Ende zu Ende und die normative Seitenstichprobe
references/judgment.md	Die Beurteilungs- + Widerlegungs-Arbeitslisten, Urteilsvokabular, Fail-Close-Falt
references/verify.md	Die check/verify-Gatter
references/false-positives.md	Wo ein Befund dennoch falsch sein kann und wie man ihn widerlegt
references/rendered.md · references/automation.md	Prüfung von produziertem HTML, Captures, Hooks und CI
references/harnesses.md	Wo dies läuft: Claude Code, Codex CLI, OpenCode und der AGENTS.md-Fallback
references/orchestrators.md	Steuerung der Engine über einen Workflow-Engine / Nicht-GitHub-CI: Pinning, die Sechs-Schritte-Pipeline, Exit-Codes, der Ticketsatz als JSON für jeden Tracker
references/ci.md	`--format sarif
references/pages.md	Seiten-Snapshots + das seitenweise Kriterienraster (pages) und seine Ehrlichkeitsregeln
references/e2e.md	render --e2e: Prüfung einer Seite während Ihres Playwright/Cypress-Durchlaufs
references/devtools.md	dev: das Live-Overlay während des Bauens und das seitenweise Dashboard
references/extension.md	Die Browser-Erweiterung: Prüfung der Seite, die Sie gerade ansehen, über den Seitenwagen
references/dynamic.md	Der scan-Bereich: Laufzeiten, Sonden, authentifizierte Seiten
references/scale.md	Fokussierung einer Prüfung auf ein großes Repository
references/fix.md · references/correction.md	Anwenden von Korrekturen, nach Priorität, ohne Regressionen
references/prd.md	Der Prüfblock als Backlog (Markdown)
references/tickets.md	Erfassen dieses Backlogs als Tickets: GitHub, GitLab, Jira, und in welcher Granularität
references/standards.md · references/packs.md · references/guidance.md	Länderstandards, Erstellen eines Pakets, Umsetzungsleitfäden
references/mcp.md	Die Standards als Regel-Engine: Schlagen Sie ein Kriterium nach, anstatt sich daran zu erinnern — seine nummerierten Tests, die von ihm definierten Begriffe, die Korrektur und der Arbeitsplan. Als MCP-Tools und std://-Ressourcen oder dieselben Daten in der CLI
references/methodology.md	Status, Bestehensquote, Schweregrade, Berichtsformat
references/cross-file.md	--graph: Importe und dateiübergreifende Regeln
references/orchestration.md	Aufteilen der Beurteilungsphasen auf Unteragenten

Nach Situation wählen

• „Erstellen Sie einen detaillierten Prüfbericht in Claude Code" → Verwenden Sie die aktive Claude-Sitzung als Prüfer, schließen Sie die gerenderten und beurteilten Kriterien ab, hinterfragen Sie seine Behauptungen und veröffentlichen Sie dann den datierten Markdown-Bericht, druckbares HTML und belegte seitenweise Dossiers. Lesen Sie references/claude-code-report.md. Dies ist das interaktive Veröffentlichungsprofil; schließen Sie mit seinem vollständigen Satz von Ergebnissen ab. Die kompakte Zusammenfassung ist der CI-Zweig unten.
• „Prüfung / Konformitätsbericht" → node scripts/ultra11y.mjs audit … --json, dann report (Synthesetabelle + ein Prüfkonformitätsblock pro NC-Kriterium — derselbe Block, den prd und tickets verwenden), dann check; lesen Sie references/audit.md.
• „Code, der von einer Bibliothek gerendert wird (DSFR, MUI…) oder einer .vue/.svelte/.astro SFC / falsche Negative vermeiden" → Prüfen Sie das produzierte HTML, nicht die Quellvorlage. Am einfachsten: Installieren Sie den berührungslosen Capture-Harvester (render --setup), sodass Ihre Tests jede gerenderte Komponente in .ultra11y/captures serialisieren (automatisch eingelesen, Ergebnisse der Quellkomponente zugeordnet; render --coverage und audit --require-captures verfolgen blinde Flecken). Oder render (Build→Prüf-Rezept oder SSR-Snapshot --scaffold) dann audit auf der Ausgabe und scan für berechnetes Rendering. SFC-Quellcode-Ergebnisse werden als preliminary (ein scope.sourceTemplate-Vorbehalt) gekennzeichnet; lesen Sie references/rendered.md.
• „Ein Befund scheint falsch / falsch positiv bei einer Komponente" → Die Engine unterdrückt automatisch die meisten falsch-positiven Ergebnisse bei Komponenten (Slot/Prop-injizierte Namen, Komponentenkinder, dynamische Bindungen, bedingte Überschriften) und markiert SFC-/Bibliotheksquellcode-Ergebnisse als preliminary; bestätigen oder widerlegen Sie den Rest mit verify --apply; lesen Sie references/false-positives.md.
• „Großes Repository / intelligent prüfen" → Fokus: --changed (git diff), Vorlagenpriorisierung, Deduplizierung, --max-files; lesen Sie references/scale.md.
• „Dateiübergreifende Analyse (Baum + Abhängigkeiten), JSX/TSX als echter AST" → audit --graph löst Importe auf und wendet dateiübergreifende Regeln an

…

[gekürzt zur Übersetzung]