joo6077/design-audit

Pièges (Gotchas)

1. Interdiction d'évaluer la qualité du code — N'évaluez pas l'architecture, les performances ou le style de code. Ne jugez que la conformité aux principes de conception.

2. Interdiction de multiplier les FAIL "jeton non utilisé" — Dans les projets sans système de jetons de conception, ne déclarez pas systématiquement FAIL pour "jeton non utilisé". Si aucun système de jetons n'existe, laissez une NOTE recommandant l'utilisation de la compétence design-system.

3. Catégorie Accessibilité obligatoire — Même si visuellement cela semble correct, vérifiez impérativement : rapport de contraste (WCAG 2.2 AA 4.5:1), cibles tactiles, indicateurs de focus, connexion des étiquettes de formulaires, nouveaux critères WCAG 2.2 (Focus Not Obscured 2.4.11 AA, Dragging Movements 2.5.7 AA, Accessible Authentication Min 3.3.8 AA). En cas d'omission, REJECT.

   Références des cibles tactiles (mises à jour le 2026-04-11) :

   • WCAG 2.2 SC 2.5.8 Target Size (Minimum) — AA = 24×24 CSS px (exceptions : espacement suffisant / texte en ligne / agent utilisateur / essentiel)
   • WCAG 2.2 SC 2.5.5 Target Size (Enhanced) — AAA = 44×44 CSS px
   • Apple HIG 44pt = recommandation pratique pour les appareils tactiles (directives de la plateforme)

   Dans les rapports existants, le fait de n'indiquer que "44×44pt" peut amener le lecteur à interpréter cela comme une "exigence WCAG AA" : précisez donc la distinction entre AA/AAA/recommandation de la plateforme. Source : W3C WCAG 2.2 SC 2.5.8, W3C What's New in WCAG 2.2.

4. Inclusion de la détection des anti-patrons IA — La catégorie Authenticité doit obligatoirement être incluse. Les border-radius uniformes, les palettes violet-bleu génériques, les répétitions de structures identiques, les effets décoratifs sans but sont des motifs de FAIL.

5. Classification de sévérité obligatoire — Chaque élément FAIL doit être accompagné de sa sévérité : Critical (accessibilité, éthique), Major (hiérarchie, cohérence), Minor (ajustements de détail). Un rapport FAIL sans sévérité est incomplet.

6. Interdiction des jugements subjectifs — "C'est joli", "C'est correct ainsi" ne peuvent pas servir de justification. Chaque PASS/FAIL doit reposer sur les principes et critères numériques définis dans audit-criteria.md.

7. Inclusion des écrans d'état/d'exception — N'inspectez pas seulement l'écran principal. Si le code contient des états vides, des états d'erreur, des états de chargement, des états de données excessives/insuffisantes, inspectez-les également.

8. Distinction des éléments non vérifiables par code — Pour les éléments impossibles à juger par analyse statique (rendu runtime, interactions réelles), marquez-les [미검증] (non vérifié) au lieu de PASS/FAIL et indiquez la méthode de vérification manuelle.

9. Interdiction de confondre heuristiques et catégories — Les 10 heuristiques de Nielsen sont un cadre de points de vue pour l'évaluation. Le jugement réel doit toujours être effectué en les mappant aux critères des 10 catégories de audit-criteria.md (Typography, Color, Spacing, Accessibility, Interaction, Motion, Visual Hierarchy, Layout & Grid, Ethical Design, Authenticity).

10. Audit règle par règle — Vérification exhaustive des 10 catégories avant la déclaration d'achèvement — Avant le verdict APPROVE/REJECT, il faut parcourir l'ensemble des 10 catégories × points de contrôle clés de audit-criteria.md et inclure dans le rapport un tableau spécifiant pour chaque élément PASS / FAIL / [미검증]. Ne regroupez pas certaines catégories sous "sans objet" sans en donner la raison. Un audit qui saute des catégories n'est pas un audit (skill-design-guide §3.6, correspondant à l'audit règle par règle).

11. Vérification préalable de la décidabilité binaire — Vérification de la possibilité de jugement binaire avant de commencer l'audit — Après avoir défini le périmètre d'audit, vérifiez d'abord pour chaque élément FAIL attendu s'il est possible de le juger de manière binaire (PASS/FAIL) uniquement à partir du code, du style et des jetons. Les éléments nécessitant un rendu runtime, une interaction réelle ou une comparaison avec MCP Figma sont immédiatement classés en [미검증] et ne doivent pas être considérés comme PASS. Les non-vérifiés se comptent en deux compteurs : invalid_evidence ([미검증:INVALID] · [미검증] sans suffixe) : 0 cas permet un jugement normal, 1 cas autorise un PASS + mention d'avertissement, 2 cas ou plus = REJECT même sans FAIL individuel. Les [미검증:ENV] remplissant les 4 conditions sont comptés séparément comme env_gaps et n'entrent pas dans le calcul du REJECT ; si verified_coverage est inférieur à 0.60, c'est BLOCKED. Cette règle est la version canonique du §Canonical Unverified-Evidence Protocol de harness/docs/guides/qa-evaluation-guide.md, article « Seuil de 2 », et n'est pas redéfinie ici. Elle doit avoir la même valeur que la copie de la règle 8 du design-reviewer (conformité agent-design-guide §3.5 Binary Decidability, côté compétence).

12. Porte de validité des preuves — "Avoir une preuve" est différent de "la preuve démontre" — Si le Gotcha 11 traite de pouvoir obtenir une preuve, cet article traite du cas où on a bien une preuve mais elle ne démontre rien. Avant de confirmer un PASS, faites passer les 4 vérifications. Si l'une d'elles échoue, ce n'est pas PASS mais [미검증].

    #	Vérification	Exemple d'échec (contexte d'audit)
    1	Non vide	Citation d'un snapshot de 0 octet, d'un log ne contenant que des erreurs
    2	Activation	0 nœud de texte cible pour le contrôle de contraste, mais déclarer "Pas de violation de contraste : PASS"
    3	Falsifiabilité	Utiliser comme oracle un grep qui donne toujours le même résultat quel que soit le code
    4	Source	Adopter comme preuve le commentaire du développeur "vérification d'accessibilité faite" ou un message de commit

    Jugement 0 correspondance — Un grep à 0 résultat a deux sens. Seul un 0 intentionnel (après avoir compté le nombre de fichiers cibles et vérifié que le motif correspond ailleurs) peut servir de base à un PASS. Un 0 vide (erreur de chemin, fichier vide, motif ne correspondant jamais) est un échec de mesure et donne [미검증]. Dans la phrase justificative, mentionnez les trois éléments ensemble sous la forme N fichiers cibles · validation du motif · 0 correspondance.

    Règle spéciale pour les rendus visuels — Une capture montrant un écran vide, une liste vide ou uniquement des placeholders n'est pas une preuve de PASS mais un signal d'échec de vérification. Lorsque vous utilisez une capture comme preuve, désignez l'élément concret exigé par la condition. Si vous ne pouvez pas le désigner, la preuve est invalide. Pour chaque capture, consultez ../../references/visual-change-protocol.md §3 checklist de capture (débordement, glyphes cassés, chips/badges et alignement, chevauchement debug). Une capture qui échoue sur un point ne peut pas être utilisée comme preuve PASS. Source : harness/docs/guides/qa-evaluation-guide.md §Evidence Validity Gate.

13. Audit comparatif Avant/Après — Un changement hors périmètre intentionnel est FAIL — Lorsque vous auditez un changement (basé sur git diff), ne regardez pas seulement l'état statique mais confrontez le périmètre demandé au périmètre réel des modifications. Si la demande ciblait une propriété visuelle spécifique (bordure uniquement, couleur uniquement, espacement uniquement) mais que le même élément voit également modifier son background / fill / radius / shadow / spacing / typography, c'est un FAIL Major. Si une couleur de maquette approuvée ou une couleur d'application existante est remplacée par un jeton de projet ou une palette par défaut, c'est un FAIL Major (violation de priorité). Le rapport d'audit se termine par un bloc EVIDENCE (before / after / proof / zone hors périmètre). Détails : ../../references/visual-change-protocol.md.

14. Couverture de propagation des décisions — Une décision confirmée appliquée seulement à certaines surfaces est Major FAIL — Si .design/decisions.yaml existe, avant l'audit des 10 catégories, jugez la couverture (il ne s'agit pas d'ajouter une catégorie — c'est une vérification préalable). Pour chaque decision_id avec status: approved, parcourez required_surfaces[] : (a) s'il n'y a ni golden ni assertion visible par l'utilisateur → FAIL (b) s'il y a un golden mais aucune assertion visible/count/height → FAIL (c) les surfaces omises dans excluded_surfaces sans raison constituent un trou de couverture → FAIL. Sévérité : Major, Critical pour une décision touchant l'accessibilité ou l'éthique. Les décisions status: superseded (remplacées) ne jugent pas la place de l'écran : on vérifie seulement que superseded_by pointe bien vers une autre décision approved de la même liste. S'il n'y a pas de manifest, on ne FAIL pas : on rapporte NO_MANIFEST et on exclut du périmètre d'audit — 0 cible n'est pas la même chose que passer. Schéma, article 4 de la règle, vérificateur exécutable : ../../references/visual-change-protocol.md §6 Decision Propagation Manifest.

15. Précisez le canal de preuve — Ne jugez pas un écran d'application via artifact_snapshot — Chaque preuve citée doit être accompagnée du nom du canal (artifact_snapshot / dom_snapshot / browser_user_visible / device_user_visible). Une phrase PASS doit contenir les 5 éléments : viewport · route/state · visible locator · count/height · screenshot/golden id. S'il en manque un seul, ce n'est pas PASS mais [미검증]. Définition des canaux : ../../references/visual-change-protocol.md §7 Evidence Channels. Le protocole en cas de conflit entre un rapport d'échec utilisateur et une preuve personnelle est défini dans harness/docs/guides/skill-design-guide.md §3.8 · harness/docs/guides/agent-design-guide.md §10, qui sont les textes canoniques, non redéfinis ici — ne contredisez pas une observation utilisateur dans le rapport d'audit.

Processus

Étape 1 : Déterminer la cible et le mode

Déterminez le périmètre d'audit en fonction du chemin et du mode spécifiés par l'utilisateur :

• Chemin de fichier → ce fichier uniquement
• Chemin de répertoire → tous les fichiers liés à l'interface utilisateur dans les sous-répertoires
• Non spécifié → fichiers d'interface utilisateur récemment modifiés (basé sur git diff)

Modes :

• quick (par défaut) — Parcours rapide des 10 catégories. Concentrez-vous sur les FAIL Critical et Major.
• deep — Vérification exhaustive incluant les états d'exception, breakpoints responsives, mode sombre et détails d'accessibilité.

Étape 2 : Vérifier les catégories d'audit

Inspectez les 10 catégories dans l'ordre. Points de contrôle clés pour chaque catégorie :

Catégorie	Points de contrôle clés	Critère de sévérité
Typography	Cohérence de l'échelle typographique, interligne (plage par système d'écriture — voir references/audit-criteria.md ligne interligne), corps de texte min. 14px (mobile) / 16px (web)	Major
Color	Contraste texte WCAG 2.2 AA 4.5:1, utilisation de jetons sémantiques, maintien du contraste en mode sombre, vérification du fallback sRGB lors de l'utilisation de la gamme étendue OKLCH/P3. Référence APCA Lc (informative) : Lc 75~90 pour le corps, Lc 60+ pour le non-texte, Lc < 15 = invisible. L'APCA exige un contraste différencié selon la taille et le poids de la police, donc une police fine nécessite un contraste plus élevé. Le critère de jugement est WCAG 2.2 AA ; APCA est une référence pour la future version WCAG 3.0 WD	Critical (contraste) / Major (jeton)
Spacing	Cohérence de l'échelle d'espacement, cibles tactiles WCAG 2.2 SC 2.5.8 AA ≥24×24 CSS px (AAA SC 2.5.5 = 44×44), hiérarchie des marges entre/dans les groupes	Critical (tactile) / Major (échelle)
Accessibility	Interdiction de transmettre l'état uniquement par la couleur, indicateur de focus, étiquettes de formulaire, texte alternatif, 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
Interaction	Retour d'action, indicateur de chargement, affichage d'erreur, chemin d'annulation/retour, UX glisser-déposer uniquement → alternative pointeur unique (WCAG 2.2 SC 2.5.7)	Major
Motion	Pertinence de l'animation, durée 200~500ms, prise en compte de prefers-reduced-motion	Major
Visual Hierarchy	Différence de ratio titre/corps/légende, mise en valeur du contenu clé par contraste, séparation des groupes par marges	Major
Layout & Grid	Alignement sur la grille, cohérence des gouttières, stratégie responsive aux breakpoints principaux, responsive niveau composant recommandé avec container-type: inline-size + @container (taille de requête supportée : Chrome 105 · Firefox 110 · Safari 16). Vérification Container Queries : les breakpoints de page se font avec media queries, les breakpoints de composants avec container queries. Utilisation des unités cqw/cqi, définition des breakpoints basés sur le point de cassure du contenu (pas sur des cibles d'appareils) recommandée	Major
Ethical Design	Absence des 12 types de dark patterns, clarté du consentement, symétrie des parcours d'inscription/désinscription	Critical
Authenticity	Répétition d'une même structure 3 fois ou plus, palette générique, décoration sans but, copie générique, incohérence avec les conventions des écrans existants ayant le même rôle	Minor~Major

Étape 3 : Appeler l'agent design-reviewer

Utilisez l'outil Agent pour créer un sous-agent design-reviewer :

Appel d'outil Agent :
- subagent_type: design-reviewer
- prompt: "Évaluez les fichiers suivants selon les principes de conception en mode [quick|deep] : [liste des fichiers cibles]"

L'agent analyse en lecture seule et renvoie les résultats par catégorie : PASS/FAIL/미검증.

Étape 4 : Mise en forme du rapport

Mettez en forme les résultats de l'agent selon le format templates/audit-report.md.

Chaque élément FAIL doit obligatoirement inclure :

• Fichier : ligne
• Sévérité (Critical / Major / Minor)
• Principe violé (avec source)
• Orientation concrète d'amélioration (sans dépendance de stack)

S'il y a au moins 1 élément non vérifié, ajoutez dans le rapport le récapitulatif de validité (Gotcha 12) :

## Validité des preuves
- Preuves inspectées : {{n}}
- Invalides : {{k}} [ID élément — n° de vérification échouée — raison]
- Cumul non vérifié : `invalid_evidence` {{a}} / `env_gaps` {{b}} / `verified_coverage` {{c}}

Étape 5 : Verdict final

• FAIL 0 + invalid_evidence 0 + verified_coverage 0.60 ou plus + L3 10/10 → APPROVE (indiquez le nombre de env_gaps)
• 1 FAIL de couverture de propagation de décision ou plus → REJECT (condition préalable distincte du jugement des 10 catégories — Gotcha 14. L'absence de manifest n'est pas un FAIL mais un rapport NO_MANIFEST)
• Code de sortie 2 de la vérification de propagation (SCHEMA_ERROR) = forme d'entrée incorrecte ne permettant pas le jugement → REJECT — même si violations=0 s'affiche sans ligne FAIL, ne l'interprétez pas comme un succès. Code de sortie 3 (NO_SURFACE · NO_DECISION) = comme NO_MANIFEST, rapport avec 0 cible
• 1 FAIL Critical ou plus → REJECT (immédiatement)
• Uniquement des FAIL Major/Minor → REJECT + liste d'améliorations par priorité
• FAIL 0 mais invalid_evidence ≥ 2 → REJECT (seuil Gotcha 11)
• FAIL 0, invalid_evidence < 2, verified_coverage = (nombre d'éléments jugés total − env_gaps) / nombre d'éléments jugés total < 0.60 → BLOCKED (insufficient_verified_coverage — relancez une commande de revérification puis réauditez)
• Même avec FAIL 0, si couverture L3 < 10/10 (une catégorie sautée parmi les 10) → REJECT + mention des catégories restantes (catégorie sautée = FAIL — règle 11 du reviewer)
• FAIL 0, invalid_evidence 1, verified_coverage 0.60 ou plus, L3 10/10 → APPROVE + mention des éléments non vérifiés et méthode de vérification manuelle

Structure d'un rapport REJECT :

1. Liste des FAIL Critical (correction immédiate nécessaire)
2. Liste des FAIL Major (correction avant le prochain sprint)
3. Liste des FAIL Minor (amélioration recommandée)
4. Éléments [미검증] (vérification manuelle nécessaire — distinction [미검증:ENV] / [미검증:INVALID])

Si l'audit porte sur une modification (basée sur git diff), le rapport se termine par un bloc EVIDENCE (Gotcha 13) :

## EVIDENCE
- before: [preuve de l'état avant modification — fichier : ligne ou capture]
- after:  [preuve de l'état après modification]
- proof:  [commande et sortie étayant le jugement]
- zone hors périmètre : [preuve d'absence de changement / ou éléments traités en FAIL]

Références

• references/audit-criteria.md — Détail des critères d'audit par catégorie
• templates/audit-report.md — Format de sortie du rapport
• ../../references/visual-change-protocol.md — Priorité des changements visuels · isolation des changements partiels · bloc de preuves · §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 — Texte canonique du protocole de priorité des rapports d'échec utilisateur
• harness/docs/guides/qa-evaluation-guide.md §Canonical Unverified-Evidence Protocol · §Evidence Validity Gate — Seuils des non vérifiés · Texte canonique des 4 vérifications de validité