frontend-audit-visual

Frontend Audit — Visual

Structured, dimension-by-dimension audit of the visual layer of a web frontend. Produces verifiable reports before any code changes.

Core Philosophy

The agent cannot see the rendered result. It compensates by:

1. Working from a token system — no arbitrary hex values, no improvised spacing
2. Auditing one dimension at a time — never "improve everything" in one pass
3. Producing structured reports first, then fixes — diagnosis before prescription
4. Justifying each change in measurable terms — contrast ratio, line-height value, missing CSS rule

---

Step 0 — Collect Context Before Touching Code

Before any audit, fill in this context block (ask the user if missing):

## Contexte visuel du site
- Ambiance cible       : [ex. dark fantasy / éditorial / SaaS / corporate / portfolio]
- Inspirations visuelles : [ex. Notion, A24, Linear, Stripe]
- Émotions recherchées : [ex. confiance, mystère, clarté, énergie]
- Anti-patterns à éviter : [ex. pastel corporate, gradients violets, surcharge d'info]
- Audience             : [ex. adultes 25-45, développeurs, clients B2B]
- Thème                : [clair / sombre / les deux]
- Framework CSS        : [aucun / Tailwind / Bootstrap / autre]
- État actuel          : [existant avec problèmes / greenfield / refonte partielle]

Si le contexte n'est pas fourni : inférer à partir du CSS/HTML existant (palette dominante, polices chargées, structure de classes), proposer le bloc contexte rempli, et attendre la validation de l'utilisateur avant de continuer.

---

Step 1 — Établir ou Extraire les Design Tokens

Adaptation aux frameworks CSS

• Pas de framework : créer les tokens en variables CSS dans :root
• Tailwind : auditer tailwind.config.js comme token system (clés colors, spacing, fontSize, etc.). Les violations = classes utilitaires qui utilisent des valeurs arbitraires (text-[#e94560], p-[13px]) au lieu du système
• Bootstrap : auditer les variables Sass/CSS custom properties de Bootstrap. Les violations = overrides en hex brut hors du système de variables
• Autre framework : identifier son mécanisme de tokens et l'utiliser comme référence

Token system de référence (si aucun framework)

:root {
  /* ── Couleurs (rôles sémantiques) ── */
  --color-bg:             ;  /* fond principal */
  --color-bg-raised:      ;  /* fond surélevé (carte, modal) */
  --color-bg-subtle:      ;  /* fond atténué (sidebar, code) */
  --color-primary:        ;  /* action principale, CTA */
  --color-primary-hover:  ;  /* état hover du primary */
  --color-on-primary:     ;  /* texte sur fond primary */
  --color-text:           ;  /* texte corps */
  --color-text-muted:     ;  /* texte secondaire, légendes */
  --color-text-disabled:  ;  /* texte inactif */
  --color-border:         ;  /* bordures */
  --color-focus-ring:     ;  /* outline de focus */
  --color-danger:         ;  /* erreurs */
  --color-success:        ;  /* succès */

  /* ── Typographie ── */
  --font-sans:     ;
  --font-serif:    ;
  --font-mono:     ;

  --text-xs:   0.75rem;   --text-sm:   0.875rem;
  --text-base: 1rem;      --text-lg:   1.125rem;
  --text-xl:   1.25rem;   --text-2xl:  1.5rem;
  --text-3xl:  1.875rem;  --text-4xl:  2.25rem;

  --leading-tight:  1.25;   --leading-snug:   1.375;
  --leading-normal: 1.5;    --leading-relaxed: 1.625;
  --leading-loose:  1.75;   --leading-body:   1.7;

  --weight-normal: 400;  --weight-medium:   500;
  --weight-semibold: 600;  --weight-bold: 700;

  /* ── Espacement (échelle 4px) ── */
  --space-1: 0.25rem;  --space-2: 0.5rem;   --space-3: 0.75rem;
  --space-4: 1rem;     --space-6: 1.5rem;   --space-8: 2rem;
  --space-12: 3rem;    --space-16: 4rem;    --space-24: 6rem;

  /* ── Layout ── */
  --content-max-width: 68ch;
  --content-wide:      90rem;
  --radius-sm: 0.25rem;  --radius-md: 0.5rem;
  --radius-lg: 1rem;     --radius-full: 9999px;

  /* ── Ombres ── */
  --shadow-sm:  0 1px 2px rgba(0,0,0,.05);
  --shadow-md:  0 4px 6px rgba(0,0,0,.07), 0 2px 4px rgba(0,0,0,.06);
  --shadow-lg:  0 10px 15px rgba(0,0,0,.1), 0 4px 6px rgba(0,0,0,.05);
}

Règle absolue : après cette étape, tout le CSS du projet référence uniquement ces tokens. Aucune couleur hex brute dans les règles de style.

---

Step 2 — Les Cinq Audits Visuels

Effectuer chaque audit séparément. Produire d'abord un rapport de violations, puis les corrections.

---

Audit A — Palette de Couleurs

Objectif : cohérence sémantique + accessibilité WCAG AA + cohérence multi-thème.

Protocole

1. Inventorier toutes les combinaisons texte/fond dans le code
2. Calculer les ratios de contraste
3. Vérifier la cohérence sémantique : les mêmes rôles visuels utilisent-ils les mêmes tokens ?
4. Identifier les couleurs "orphelines" (valeurs hex/rgb hors tokens)
5. Si multi-thème : vérifier que chaque token a une valeur dans chaque thème et que les ratios de contraste sont respectés dans tous les thèmes

Critères WCAG

• Texte normal (< 18pt / < 14pt bold) : 4.5:1 minimum
• Grand texte (≥ 18pt / ≥ 14pt bold) : 3:1 minimum
• Composants UI et graphiques : 3:1 minimum
• Ne jamais utiliser la couleur comme seul vecteur d'information

Format du rapport

## Rapport Palette

### Violations de contraste
| Élément      | Couleur texte | Fond    | Ratio  | Cible | Thème  | Statut |
|-------------|---------------|---------|--------|-------|--------|--------|
| .nav-link   | #8892a4       | #1a1a2e | 3.8:1  | 4.5:1 | sombre | ❌     |

### Couleurs orphelines (hors tokens)
- ligne 142 : `color: #e94560` → remplacer par `var(--color-primary)`
- ligne 287 : `background: #2a2a4a` → pas de token, créer `--color-bg-accent`

### Incohérences sémantiques
- Les liens utilisent 3 couleurs différentes → uniformiser sur `var(--color-primary)`

### Couverture multi-thème (si applicable)
| Token             | Thème clair | Thème sombre | Contraste clair | Contraste sombre |
|-------------------|-------------|--------------|-----------------|------------------|
| --color-text-muted| #666        | #999         | 5.7:1 ✅         | 2.8:1 ❌          |

---

Audit B — Hiérarchie Visuelle

Objectif : chaque niveau de titre doit être immédiatement distinguable du suivant.

Protocole

1. Extraire tous les éléments h1–h6 et leurs propriétés (font-size, font-weight, margin, line-height, letter-spacing)
2. Calculer les ratios de taille entre niveaux adjacents
3. Identifier les éléments visuellement saillants mais sémantiquement incorrects (ou l'inverse)
4. Vérifier la cohérence de l'espacement vertical (margin-top des titres > margin-bottom)

Règles de ratios

• Entre niveaux adjacents : ratio ≥ 1.25× (idéal : 1.333× ou 1.5×)
• Entre h1 et body : ratio ≥ 2×
• Le margin-top d'un titre doit être ≥ 2× son margin-bottom

Format du rapport

## Rapport Hiérarchie

### Échelle typographique actuelle
| Niveau | font-size | weight | Ratio vs. inf. | Problème       |
|--------|-----------|--------|----------------|----------------|
| h1     | 2rem      | 700    | —              |                |
| h2     | 1.75rem   | 700    | 1.14× ⚠️       | trop proche    |
| body   | 1rem      | 400    | —              |                |

### Éléments visuellement dominants sans justification
- .hero-subtitle : 1.5rem/700 → visuellement un h2, sémantiquement un p

---

Audit C — Lisibilité du Contenu Long

Objectif : tout bloc de texte destiné à être lu respecte les conditions ergonomiques de lecture.

Protocole

Identifier les conteneurs de texte long : article, section, .content, .post-body, main p (tout bloc avec plus de 3 phrases consécutives).

Checklist par conteneur

## Rapport Lisibilité

| Critère                      | Actuel  | Cible              | Statut |
|------------------------------|---------|---------------------|--------|
| max-width                    | 100%    | ≤ 70ch              | ❌     |
| line-height                  | 1.4     | ≥ 1.6 (idéal 1.7)   | ⚠️     |
| font-size (desktop)          | 14px    | ≥ 16px              | ❌     |
| inter-paragraphes            | 0       | ≥ 1em               | ❌     |
| text-align                   | justify | left (jamais justify)| ❌     |
| padding mobile (< 768px)     | 0       | ≥ 1rem              | ❌     |
| longueur de ligne moyenne    | ~110ch  | 45–75ch             | ❌     |

---

Audit D — Densité & Espace Négatif

Objectif : chaque vue a un rythme visuel lisible — alternance entre zones denses et zones de respiration.

Protocole

1. Inventorier les zones de contenu principal (header, hero, sections, sidebar, footer)
2. Mesurer l'espacement entre les sections majeures (margin/padding entre siblings directs)
3. Compter les CTA visibles par écran logique (un "écran" = ~100vh de contenu)
4. Identifier les zones où plusieurs éléments visuellement lourds (images, cartes, boutons, titres) sont adjacents sans espace de respiration

Signaux de surcharge

• Plus de 2 CTA primaires par écran logique → compétition visuelle
• Sections majeures espacées de < 2rem → étouffement
• Texte, images et boutons adjacents sans espace négatif ≥ 1.5rem → mur visuel
• Plus de 3 styles de cartes/conteneurs visuellement distincts sur la même page → incohérence
• Absence de section "respiration" (grande marge, image pleine largeur, ou espace vide intentionnel) entre blocs denses

Format du rapport

## Rapport Densité

### Score de densité par zone
| Zone              | Nb éléments lourds | Espacement min | CTA | Verdict     |
|-------------------|--------------------|----------------|-----|-------------|
| Hero              | 3 (titre+img+CTA)  | 0.5rem         | 1   | ⚠️ dense    |
| Section produits  | 8 cartes           | 1rem           | 8   | ❌ surchargé |
| Footer            | 4 colonnes         | 2rem           | 0   | ✅ ok       |

### Problèmes de rythme
- Aucune section de respiration entre Hero et Section produits
- 8 CTA "Acheter" identiques en compétition visuelle → hiérarchiser

---

Audit E — Typographie Web

Objectif : les polices se chargent efficacement, avec des fallbacks corrects, sans flash visuel perturbant.

Protocole

1. Inventorier les polices chargées : @font-face, Google Fonts <link>, imports CSS
2. Vérifier la présence de font-display dans chaque @font-face
3. Vérifier la qualité des fallback stacks (métrique-compatible ? générique en dernier ?)
4. Compter le nombre total de fichiers de police chargés (weights × styles × familles)
5. Vérifier le préchargement des polices critiques (<link rel="preload">)

Signaux de problème

• font-display absent ou auto → FOIT probable (texte invisible pendant chargement)
• Plus de 6 fichiers de police → poids réseau excessif
• Fallback stack vide ou générique seul (font-family: "Inter" sans fallback) → saut de layout au chargement
• Google Fonts sans &display=swap → FOIT
• Police décorative utilisée pour le corps de texte → lisibilité compromise

Format du rapport

## Rapport Typographie Web

### Polices chargées
| Police    | Weights      | Source       | font-display | Fallback stack        | Préchargée |
|-----------|--------------|--------------|--------------|----------------------|------------|
| Inter     | 400,600,700  | Google Fonts | swap ✅       | system-ui, sans-serif | non ⚠️     |
| Playfair  | 700          | @font-face   | absent ❌     | serif                 | non        |

### Problèmes
- 2 familles × 4 weights = 8 fichiers → envisager variable fonts
- Playfair sans font-display → FOIT sur connexions lentes
- Inter non préchargée → le titre clignote au chargement

---

Step 3 — Pipeline de Correction

Après les rapports, corriger dans cet ordre :

1. Token system (Step 1)   → fondation, tout dépend de ça
2. Audit A (Palette)       → les couleurs orphelines polluent tout le reste
3. Audit B (Hiérarchie)    → restructurer l'échelle typographique
4. Audit C (Lisibilité)    → ajustements locaux aux conteneurs de texte
5. Audit D (Densité)       → restructuration de l'espacement entre zones
6. Audit E (Typo web)      → optimisation du chargement de polices

Si l'utilisateur cible un audit précis, commencer par celui-là. L'ordre ci-dessus s'applique quand on fait un audit complet.

Règle d'or : chaque correctif proposé doit :

• Mentionner le token utilisé
• Citer la règle violée (WCAG, ratio, règle d'espacement)
• Être une diff minimale (ne pas refactoriser ce qui n'est pas audité)

---

Step 4 — Validation Post-Correction

## Checklist de validation visuelle

### Palette
- [ ] Toutes les combinaisons texte/fond ≥ 4.5:1 (tous thèmes)
- [ ] Zéro couleur brute hors tokens
- [ ] La même intention visuelle utilise le même token partout

### Hiérarchie
- [ ] Ratio entre niveaux adjacents ≥ 1.25×
- [ ] H1 ≥ 2× la taille du corps
- [ ] margin-top des titres ≥ 2× margin-bottom

### Lisibilité
- [ ] max-width ≤ 70ch sur conteneurs de texte long
- [ ] line-height ≥ 1.6 sur le corps du texte
- [ ] Aucun text-align: justify
- [ ] font-size ≥ 16px sur mobile

### Densité
- [ ] ≤ 2 CTA primaires par écran logique
- [ ] Espacement ≥ 2rem entre sections majeures
- [ ] Au moins 1 zone de respiration entre blocs denses

### Typographie web
- [ ] font-display défini sur toutes les @font-face
- [ ] ≤ 6 fichiers de police (ou variable fonts)
- [ ] Fallback stacks complets sur toutes les font-family
- [ ] Polices critiques préchargées

---

Notes pour l'agent

1. Ne jamais modifier plusieurs dimensions en même temps. Un patch palette + hiérarchie + lisibilité en un bloc est inauditible.
2. Ne jamais inventer de valeurs de tokens. Si une valeur n'existe pas, demander à l'utilisateur.
3. Toujours produire le rapport avant les corrections. L'utilisateur doit valider le diagnostic.
4. Les suggestions de couleurs restent dans la même teinte sauf demande explicite.
5. Le contexte visuel (Step 0) est obligatoire. Inférer si non fourni, mais valider.
6. Cohérence inter-pages : si plusieurs fichiers HTML/vues sont disponibles, vérifier que les tokens sont appliqués uniformément entre les pages, pas seulement dans un fichier isolé.
7. Mode quick audit : si l'utilisateur demande un diagnostic rapide, produire uniquement le tableau de violations par audit (sans les sections détaillées) et proposer d'approfondir les dimensions problématiques.