joo6077/design-audit

Gotchas

1. Keine Bewertung der Codequalität — Architektur, Performance und Codestil sind nicht zu bewerten. Es wird nur die Einhaltung von Designprinzipien beurteilt.

2. Kein übermäßiger FAIL wegen „Token nicht verwendet“ — In Projekten ohne Design-Tokens darf nicht pauschal „Token nicht verwendet“ als FAIL gewertet werden. Wenn kein Token-System existiert, ist stattdessen eine Note zu hinterlegen, die die Verwendung des design-system-Skills empfiehlt.

3. Kategorie Barrierefreiheit ist Pflicht — Auch wenn etwas visuell in Ordnung aussieht, muss es geprüft werden: Kontrastverhältnis (WCAG 2.2 AA 4,5:1), Touch-Ziele, Fokusindikator, Formular-Label-Verknüpfung, WCAG 2.2 neue SC (Focus Not Obscured 2.4.11 AA, Dragging Movements 2.5.7 AA, Accessible Authentication Min 3.3.8 AA). Wenn dies unterlassen wird, gibt es REJECT.

   Richtlinien für Touch-Ziele (aktualisiert am 11.04.2026):

   • WCAG 2.2 SC 2.5.8 Target Size (Minimum) — AA = 24×24 CSS px (Ausnahmen: ausreichender Abstand / Inline-Text / User-Agent / essenziell)
   • WCAG 2.2 SC 2.5.5 Target Size (Enhanced) — AAA = 44×44 CSS px
   • Apple HIG 44pt = Empfehlung für Touch-Geräte (Plattformrichtlinie)

   Wenn in einem bestehenden Report nur „44×44pt“ angegeben wird, könnten Leser dies fälschlich als „WCAG-AA-Anforderung“ interpretieren. Daher sind AA/AAA/Plattformempfehlungen getrennt anzugeben. Quelle: W3C WCAG 2.2 SC 2.5.8, W3C What's New in WCAG 2.2.

4. Prüfung auf KI-Anti-Patterns einschließen — Die Kategorie Authentizität muss zwingend enthalten sein. Einheitliche border-radius, generische Violett-Blau-Paletten, wiederholte identische Strukturen und dekorative Effekte ohne Zweck sind FAIL-Gründe.

5. Schweregradklassifizierung ist Pflicht — Jeder FAIL-Eintrag muss mit einem Schweregrad versehen werden: Critical (Barrierefreiheit/Ethik), Major (Hierarchie/Konsistenz), Minor (Feinabstimmung). Ein FAIL-Report ohne Schweregrad ist unvollständig.

6. Keine subjektiven Urteile — „Sieht gut aus“ oder „das ist in Ordnung“ sind keine gültigen Begründungen. Jeder PASS/FAIL muss auf den in audit-criteria.md definierten Prinzipien und Zahlenwerten basieren.

7. Zustands-/Fehlerbildschirme einschließen — Nicht nur die Standardbildschirme prüfen. Leere Zustände, Fehlerzustände, Ladezustände und Zustände mit zu vielen/wenigen Daten müssen, falls im Code vorhanden, ebenfalls geprüft werden.

8. Kennzeichnung nicht prüfbarer Punkte — Punkte wie Laufzeit-Rendering oder tatsächliche Interaktionen, die mit statischer Analyse nicht beurteilt werden können, sind nicht als PASS/FAIL, sondern als [UNVERIFIED] zu kennzeichnen und es ist eine Anleitung zur manuellen Überprüfung beizufügen.

9. Keine Verwechslung von Heuristiken und Kategorien — Die 10 Nielsen-Heuristiken sind ein Rahmen für die Bewertungsperspektive. Die eigentliche Beurteilung muss zwingend anhand der 10 Kategorien (Typografie, Farbe, Abstände, Barrierefreiheit, Interaktion, Bewegung, visuelle Hierarchie, Layout & Grid, ethisches Design, Authentizität) des audit-criteria.md erfolgen und darauf abgebildet werden.

10. Rule-by-Rule Audit – Vollständiger Abgleich aller 10 Kategorien vor der Fertigstellungserklärung — Vor der APPROVE/REJECT-Entscheidung müssen alle 10 Kategorien × Kern-Checkpoints aus audit-criteria.md durchlaufen werden. Eine Tabelle mit PASS / FAIL / [UNVERIFIED] für jeden Punkt muss im Report enthalten sein. Einzelne Kategorien dürfen nicht pauschal als „nicht zutreffend“ zusammengefasst werden; es muss ein Grund angegeben werden. Ein Audit, das Kategorien auslässt, ist kein Audit (skill-design-guide §3.6 Rule-by-Rule Audit).

11. Binary Decidability Pre-Check – Prüfung der binären Entscheidbarkeit vor Audit-Beginn — Nach der Festlegung des Prüfumfangs ist für jeden erwarteten FAIL-Punkt zu prüfen: „Ist dieser Punkt allein anhand von Code/Style/Tokens binär als PASS/FAIL entscheidbar?“ Punkte, die Laufzeit-Rendering, tatsächliche Interaktion oder einen MCP-Figma-Abgleich erfordern, sind sofort als [UNVERIFIED] zu klassifizieren und dürfen nicht als PASS durchgewunken werden. UNVERIFIED wird in zwei Zählern erfasst – invalid_evidence ([UNVERIFIED:INVALID] · [UNVERIFIED] ohne Suffix): 0 Fälle = normale Beurteilung, 1 Fall = PASS erlaubt + Warnung, 2 oder mehr Fälle = REJECT, auch ohne einzelne FAILs. [UNVERIFIED:ENV], das alle 4 Anforderungen erfüllt, wird separat als env_gaps gezählt und trägt nicht zum REJECT-Zähler bei. Ist verified_coverage < 0,60, liegt ein BLOCKED-Status vor. Diese Regel ist in den Bestimmungen des „Schwellenwerts 2“ im §Canonical Unverified-Evidence Protocol von harness/docs/guides/qa-evaluation-guide.md definiert und wird hier nicht neu definiert. Sie muss mit der Kopie von Regel 8 des design-reviewer übereinstimmen (agent-design-guide §3.5 Binary Decidability, Spiegelung im Skill).

12. Evidence Validity Gate – „Es gibt einen Beweis“ und „der Beweis beweist etwas“ sind unterschiedlich – Während Gotcha 11 behandelt, ob ein Beweis beschafft werden kann, behandelt dieser Punkt den Fall, dass ein Beweis beschafft wurde, aber nichts beweist. Vor der Bestätigung eines PASS müssen die folgenden 4 Prüfungen bestanden werden. Wenn eine davon fehlschlägt, liegt kein PASS, sondern ein [UNVERIFIED] vor.

    #	Prüfung	Fehlerbeispiel (im Audit-Kontext)
    1	Nicht leer	Zitieren eines 0-Byte-Snapshots oder eines nur Fehler enthaltenden Logs als Beleg
    2	Aktivierung	„Kein Kontrastverstoß, PASS“ obwohl 0 Textknoten für die Kontrastprüfung vorhanden sind
    3	Falsifizierbarkeit	Verwendung eines Grep als Orakel, das bei jedem Code das gleiche Ergebnis liefert
    4	Quelle	Übernahme eines Kommentars des Entwicklers oder einer Commit-Nachricht wie „Barrierefreiheit geprüft“ als Beleg

    0-Treffer-Entscheidung – 0 Treffer bei grep können zweierlei sein. Nur beabsichtigte 0 (Anzahl der Zieldateien wurde zuerst ermittelt, dann wurde bestätigt, dass das Muster an anderer Stelle zutrifft) sind eine PASS-Begründung. Leere 0 (Pfadfehler, leere Dateien, ein Muster, das niemals zutrifft) sind ein Messfehler und ergeben [UNVERIFIED]. In der Begründung müssen alle drei Elemente gemeinsam angegeben werden: Ziel N Dateien · Muster gültig · Treffer 0.

    Sonderregel für Rendering-Ausgaben – Aufnahmen eines leeren Bildschirms, einer leeren Liste oder nur eines Platzhalters sind kein PASS-Beweis, sondern ein Signal für einen fehlgeschlagenen Test. Wenn ein Screenshot als Beleg verwendet wird, muss das konkrete Element benannt werden, das die Bedingung erfüllt. Kann es nicht benannt werden, ist der Beweis ungültig. Für jeden Screenshot muss die Checkliste aus ../../references/visual-change-protocol.md §3 (Überlauf, kaputte Glyphen, Chips/Badges und Linienformen, Debug-Überlappungen) durchgegangen werden. Ein Screenshot, bei dem auch nur ein Punkt zutrifft, darf nicht als PASS-Beweis verwendet werden. Quelle: harness/docs/guides/qa-evaluation-guide.md §Evidence Validity Gate.

13. Before/After-Vergleichsaudit – Änderungen außerhalb des beabsichtigten Bereichs sind FAIL – Bei der Prüfung von Änderungen (basierend auf git diff) darf nicht nur der statische Zustand betrachtet werden. Es muss der angeforderte Umfang mit dem tatsächlichen Änderungsumfang verglichen werden. Wenn eine Anfrage nur eine bestimmte visuelle Eigenschaft betrifft (nur Border, nur Farbe, nur Abstand), das gleiche Element aber auch background / fill / radius / shadow / spacing / typography mitverändert wurden, ist dies ein Major FAIL. Wenn genehmigte Design-Entwürfe oder vorhandene App-Farben durch Projekt-Tokens oder Basis-Paletten ersetzt wurden, ist dies ein Major FAIL (Prioritätsverstoß). Der Audit-Report wird mit einem EVIDENCE-Block (before / after / proof / unbeabsichtigte Bereiche) abgeschlossen. Details: ../../references/visual-change-protocol.md.

14. Decision Propagation Coverage – Wenn eine getroffene Entscheidung nur auf einer Teilfläche angewendet wird, ist das ein Major FAIL – Wenn .design/decisions.yaml existiert, wird vor dem 10-Kategorien-Audit die Abdeckung beurteilt (die Kategorien werden nicht erweitert – es handelt sich um eine Vorbedingungsprüfung). Für jede decision_id mit status: approved wird required_surfaces[] durchlaufen. (a) Wenn weder ein Golden noch eine user-visible Assertion existiert: FAIL. (b) Wenn nur ein Golden, aber keine visible/count/height-Assertion vorhanden ist: FAIL. (c) Wenn eine Fläche ohne Grund in excluded_surfaces fehlt, liegt eine Abdeckungslücke vor: FAIL. Der Schweregrad ist Major, bei Entscheidungen zu Barrierefreiheit/Ethik Critical. Bei Entscheidungen mit status: superseded (ersetzt) wird nicht die Bildschirmfläche beurteilt, sondern nur geprüft, ob superseded_by auf eine andere approved-Entscheidung in derselben Liste verweist. Fehlt das Manifest selbst, wird nicht FAIL, sondern NO_MANIFEST gemeldet und der Punkt vom Prüfumfang ausgeschlossen – 0 Ziele sind nicht gleichbedeutend mit Bestehen. Schema, Regel 4 Abs., ausführbare Prüfung: ../../references/visual-change-protocol.md §6 Decision Propagation Manifest.

15. Den Beweiskanal angeben – App-Bildschirme nicht anhand von artifact_snapshot beurteilen – Jeder als Beleg zitierte Beweis muss mit einem Kanalnamen versehen sein (artifact_snapshot / dom_snapshot / browser_user_visible / device_user_visible). Ein PASS-Satz muss die 5 Elemente viewport · route/state · visible locator · count/height · screenshot/golden id enthalten. Fehlt auch nur eines, liegt kein PASS, sondern ein [UNVERIFIED] vor. Kanaldefinitionen: ../../references/visual-change-protocol.md §7 Evidence Channels. Die Protokolle bei Konflikten zwischen Benutzer-Fehlerberichten und eigenen Beweisen sind in harness/docs/guides/skill-design-guide.md §3.8 · harness/docs/guides/agent-design-guide.md §10 als maßgebliche Quellen definiert und werden hier nicht neu definiert – Benutzerbeobachtungen dürfen nicht mit dem Audit-Report widerlegt werden.

Prozess

Schritt 1: Zielbereich und Modus festlegen

Der Audit-Umfang wird basierend auf dem vom Benutzer angegebenen Pfad und Modus festgelegt:

• Dateipfad → nur diese Datei
• Verzeichnispfad → alle untergeordneten UI-bezogenen Dateien
• Nicht angegeben → zuletzt geänderte UI-Dateien (basierend auf git diff)

Modi:

• quick (Standard) – Schnelle Prüfung aller 10 Kategorien. Konzentration auf Critical/Major-FAILs.
• deep – Vollständige Prüfung inkl. Zustands-/Fehlerbildschirme, responsiver Breakpoints, Dark Mode und detaillierter Barrierefreiheitsaspekte.

Schritt 2: Audit-Kategorien bestätigen

Die 10 Kategorien werden der Reihe nach geprüft. Kern-Checkpoints pro Kategorie:

Kategorie	Kern-Checkpoints	Schweregradkriterium
Typografie	Konsistenz der Typo-Skala, Zeilenhöhe (schriftsystemabhängige Bereiche – references/audit-criteria.md Zeilenhöhenverhältnis-Tabelle), Text mindestens 14px (mobil)/16px (Web)	Major
Farbe	Textkontrast WCAG 2.2 AA 4,5:1, Verwendung semantischer Tokens, Dark-Mode-Kontrast erhalten, sRGB-Fallback bei OKLCH/P3 Wide-Gamut prüfen. APCA Lc-Referenz (informativ): Text Lc 75–90, Nicht-Text Lc 60+, Lc <15 unsichtbar. APCA erfordert differenzierten Kontrast nach Schriftgröße und -stärke; dünne Schriften benötigen höheren Kontrast. Entscheidungsgrundlage ist WCAG 2.2 AA, APCA dient als Referenz für WCAG 3.0 WD	Critical (Kontrast) / Major (Token)
Abstände	Konsistenz der Abstandsskala, Touch-Ziele WCAG 2.2 SC 2.5.8 AA ≥24×24 CSS px (AAA SC 2.5.5 = 44×44), Hierarchie der Abstände zwischen/innerhalb von Gruppen	Critical (Touch) / Major (Skala)
Barrierefreiheit	Keine reine Farbcodierung für Zustände, Fokusindikator, Formular-Label, Alternativtexte, WCAG 2.2 SC 2.4.11 Focus Not Obscured (AA), SC 2.5.7 Dragging Movements (AA), SC 3.3.8 Accessible Authentication Min (AA)	Critical
Interaktion	Aktionsfeedback, Ladeindikator, Fehleranzeige, Abbrechen/Rückgängig-Pfade, Drag-only-UX: Single-Pointer-Alternative (WCAG 2.2 SC 2.5.7)	Major
Bewegung	Zweckmäßigkeit von Animationen, Dauer 200–500 ms, Unterstützung von prefers-reduced-motion	Major
Visuelle Hierarchie	Größenunterschiede zwischen Überschrift/Text/Caption, Hervorhebung von Kerninhalten durch Kontrast, Trennung von Gruppen durch Abstände	Major
Layout & Grid	Grid-Ausrichtung, konsistente Gutter, responsive Strategie für Haupt-Breakpoints, responsive Komponenten: container-type: inline-size + @container empfohlen (Container-Queries-Unterstützung: Chrome 105 · Firefox 110 · Safari 16). Container Queries prüfen: Seitenebene: Media Queries, Komponentenebene: Container Queries. Verwendung von cqw/cqi-Einheiten, Breakpoints basierend auf Inhaltsbrüchen empfohlen (keine Geräteziele)	Major
Ethisches Design	Keine der 12 Dark-Pattern-Arten, explizite Zustimmung, Symmetrie von Anmelde-/Abmelde-Pfaden	Critical
Authentizität	3+ Wiederholungen identischer Strukturen, generische Palette, ziellose Dekoration, generische Texte, Inkonsistenzen mit bestehenden Bildschirmen, die dieselbe Rolle haben	Minor~Major

Schritt 3: Design-Reviewer-Agent aufrufen

Mit dem Agent-Tool wird ein design-reviewer-Subagent erstellt:

Agent-Tool-Aufruf:
- subagent_type: design-reviewer
- prompt: „Bewerte die folgenden Dateien im [quick|deep]-Modus basierend auf Design-Prinzipien: [Liste der Zieldateien]"

Der Agent analysiert schreibgeschützt und gibt die Ergebnisse pro Kategorie als PASS/FAIL/UNVERIFIED zurück.

Schritt 4: Report formatieren

Die Ergebnisse des Agents werden im Format templates/audit-report.md zusammengestellt.

Jeder FAIL-Eintrag muss enthalten:

• Datei:Zeilennummer
• Schweregrad (Critical / Major / Minor)
• Verletztes Prinzip (mit Quellenangabe)
• Konkrete Verbesserungsrichtung (stackunabhängig)

Bei 1 oder mehr UNVERIFIED-Einträgen wird die Gültigkeitszählung in den Report aufgenommen (Gotcha 12):

## Evidence Validity
- Geprüfte Beweise: {{n}} Einträge
- Ungültig befunden: {{k}} Einträge [Punkt-ID – Fehlgeschlagene Prüfnummer – Grund]
- UNVERIFIED-Summe: `invalid_evidence` {{a}} Einträge / `env_gaps` {{b}} Einträge / `verified_coverage` {{c}}

Schritt 5: Endgültige Entscheidung

• FAIL 0 + invalid_evidence 0 + verified_coverage 0,60+ + L3 10/10 → APPROVE (Anzahl env_gaps angeben)
• Decision Propagation Coverage FAIL 1 oder mehr → REJECT (unabhängig von der 10-Kategorien-Entscheidung – Gotcha 14. Fehlendes Manifest ist nicht FAIL, sondern NO_MANIFEST-Meldung)
• Entscheidungs-Propagationsprüfung mit Exit-Code 2(SCHEMA_ERROR): Konnte wegen falscher Eingabeform nicht beurteilt werden → REJECT – Auch wenn violations=0 ausgegeben wird, gilt es nicht als bestanden. Exit-Code 3(NO_SURFACE · NO_DECISION): Wird wie NO_MANIFEST mit 0 Zielen gemeldet
• Critical FAIL 1 oder mehr → REJECT (sofort)
• Nur Major/Minor FAILs → REJECT + priorisierte Verbesserungsliste
• FAIL 0, aber invalid_evidence 2 oder mehr → REJECT (Gotcha 11 Schwellenwert)
• FAIL 0, invalid_evidence < 2, verified_coverage = (Anzahl der beurteilten Prüfpunkte − env_gaps) / Anzahl der beurteilten Prüfpunkte < 0,60 → BLOCKED (insufficient_verified_coverage – Nach erneuter Verifizierung erneut auditieren)
• FAIL 0, aber L3-Abdeckung < 10/10 (eine der 10 Kategorien wurde ausgelassen) → REJECT + Angabe der fehlenden Kategorien (Ausgelassene Kategorien gelten als FAIL – Reviewer-Regel 11)
• FAIL 0, invalid_evidence 1, verified_coverage 0,60+, L3 10/10 → APPROVE + Angabe der UNVERIFIED-Punkte und manuellen Prüfmethode

REJECT-Report-Struktur:

1. Critical FAIL-Liste (sofortige Korrektur erforderlich)
2. Major FAIL-Liste (Korrektur vor dem nächsten Sprint)
3. Minor FAIL-Liste (Verbesserung empfohlen)
4. [UNVERIFIED]-Punkte (manuelle Prüfung erforderlich – Unterscheidung [UNVERIFIED:ENV] / [UNVERIFIED:INVALID])

Bei einem Änderungsaudit (basierend auf git diff) wird der Report mit einem EVIDENCE-Block abgeschlossen (Gotcha 13):

## EVIDENCE
- before: [Beleg für Zustand vor der Änderung – Datei:Zeile oder Screenshot]
- after:  [Beleg für Zustand nach der Änderung]
- proof:  [Befehl und Ausgabe, die die Entscheidung stützen]
- Unbeabsichtigte Bereiche: [Beleg, dass keine Änderungen vorliegen / oder Liste der als FAIL gewerteten Punkte]

Referenzen

• references/audit-criteria.md – Detaillierte Audit-Kriterien pro Kategorie
• templates/audit-report.md – Report-Ausgabeformat
• ../../references/visual-change-protocol.md – Visuelle Änderungspriorität, partielle Änderungsisolierung, Beweisblöcke, §6 Decision Propagation Manifest, §7 Evidence Channels (SSOT)
• harness/docs/guides/skill-design-guide.md §3.8 · harness/docs/guides/agent-design-guide.md §10 – Maßgebliche Quellen für die Prioritätsregeln bei Benutzer-Fehlerberichten
• harness/docs/guides/qa-evaluation-guide.md §Canonical Unverified-Evidence Protocol · §Evidence Validity Gate – Maßgebliche Quellen für den UNVERIFIED-Schwellenwert und die 4 Gültigkeitsprüfungen