veza/docs/FRONTEND_AUDIT_VISUAL.md

# Audit visuel exhaustif du frontend Veza

**Date:** 2026-02-07  
**Objectif:** Identifier les causes précises de la "mocheté" perçue (layout, composants, couleurs, contrastes, typographie, cohérence).

---

## 1. Résumé exécutif

Le frontend souffre de **plusieurs facteurs cumulés** : palette d’accents incohérente (teal + magenta/purple + vert + rouge), manque de profondeur (cartes trop plates), éléments "placeholder" visibles (ex. "0%" en rouge partout), barre de lecture disproportionnée, et typographie potentiellement dégradée (Rajdhani + erreurs glyph). Les correctifs ciblent des fichiers et variables précis ci-dessous.

---

## 2. Palette et couleurs

### 2.1 Incohérence des couleurs d’accent

| Contexte | Couleur utilisée | Fichier / token | Problème |
|----------|------------------|-----------------|----------|
| Élément actif sidebar, bouton play, "NETWORK STABLE" | **Teal / cyan** (primary) | `--primary: oklch(0.75 0.18 195)` dans `index.css` | Cohérent comme accent principal. |
| Badges sidebar (Live Sessions 3, Channels 12) | **Magenta / violet** (`secondary`) | `Sidebar.tsx` L195 : `bg-secondary/20 text-secondary` ; `--secondary: oklch(0.65 0.25 330)` | **Hors palette** par rapport au teal ; donne une impression de "troisième couleur" non intégrée. |
| Pourcentages positifs, "ACTIVE", "NETWORK STABLE" (dot) | **Vert** (lime/success) | `StatCard.tsx` (lime), succès sémantique | Un **vert** distinct du teal pour "positif" crée une **double convention** (teal vs vert) pour des états similaires. |
| Tendances négatives, "Expired Warranty", Sign Out | **Rouge** (destructive) | `AdminDashboardStatCard.tsx`, `Sidebar.tsx` (Live icon) | Correct sémantiquement mais **trop présent** si utilisé aussi pour "0%" (voir §3). |

**Recommandations :**

- **Badges sidebar** : remplacer `secondary` (magenta) par une variante du primary (ex. `primary` ou `cyan-500`) ou un token dédié "badge" aligné sur la charte. Fichier : `apps/web/src/components/layout/Sidebar.tsx` (L194–201).
- **États "positif"** : unifier soit sur teal, soit sur vert, et documenter (ex. teal = interactif/actif, vert = succès/variation positive uniquement).

### 2.2 Manque de profondeur (cartes, fonds)

- **Cartes dashboard** : variante `glass` ou `default` avec bordures/ombres très légères (`border-white/5`, `shadow-black/5`). Fichiers : `components/ui/card.tsx` (variants `glass`, `default`), `AdminDashboardStatCard.tsx`, `AdminDashboardTrafficCard.tsx`.
- **Recherche header** : `bg-muted/50 border border-border` — contraste faible avec le fond, la zone "Search Network..." se fond dans le fond.
- **Dark mode** : `--card: oklch(0.18 0.02 265)` très proche de `--background: oklch(0.15 0.02 265)` dans `index.css` (.dark), donc **peu de relief**.

**Recommandations :**

- Augmenter légèrement la différence luminance card vs background (ex. card à 0.20–0.22, background 0.15).
- Donner aux cartes une bordure ou une ombre un peu plus marquée (ex. `border-border` plus visible, `shadow-lg` avec teinte légère).
- Barre de recherche : fond ou bordure un peu plus marqués pour l’affordance (ex. `bg-card` ou `border-white/10`).

### 2.3 Fichiers à modifier (couleurs)

- `apps/web/src/index.css` : variables `.dark` (--card, --background), éventuellement --border.
- `apps/web/src/components/layout/Sidebar.tsx` : classes des badges (remplacer secondary par primary/cyan).
- `apps/web/src/components/layout/Header.tsx` : input search (classes bg/border).

---

## 3. Composants "placeholder" ou trompeurs

### 3.1 "0%" en rouge sur toutes les cartes (Admin)

- **Comportement** : `AdminDashboardStatCard` affiche un badge de tendance (`trend`) avec `trend > 0` → vert, sinon **rouge**. Si l’API ne renvoie pas de tendances (ou renvoie 0), on obtient **"0%" en rouge sur chaque carte**.
- **Fichiers** : `AdminDashboardStatCard.tsx` (L46–57), `AdminDashboardView.tsx` (L48–50 : `trend: stats.trends?.users` etc.), `useAdminDashboardView.ts` (stats venant de l’API).
- **Impact** : ressemble à une erreur ou à une donnée non implémentée, ce qui renforce l’impression d’interface inachevée.

**Recommandations :**

- Ne pas afficher le badge de tendance quand `trend === undefined` (ou null). Afficher "0%" seulement si la métrique a du sens (ex. "0% de variation" explicite).
- Si `trend === 0`, éviter le style "erreur" (rouge) : utiliser un style neutre (muted) ou masquer.

### 3.2 Graphique "Traffic Flux"

- **Comportement** : `AdminDashboardTrafficCard` utilise des barres **aléatoires** (`Math.random()`) et des labels factices ("SYS_INIT", "BUFFERING_NODES...", "LIVE_DATA"). Aucune donnée réelle, aucun axe Y, pas de grille lisible.
- **Fichier** : `apps/web/src/components/admin/admin-dashboard-view/AdminDashboardTrafficCard.tsx`.
- **Impact** : l’intitulé "HOLOGRAPHIC STREAMING INTERFACE" promet un élément avancé alors que le rendu est clairement un placeholder.

**Recommandations :**

- Soit brancher de vraies données + axes + légende claire, soit remplacer par un message du type "Données à venir" ou un skeleton, et éviter un faux graphique.

### 3.3 Bouton "Sign In" alors que l’utilisateur est connecté

- **Constat** (d’après captures) : un bouton "Sign In" peut apparaître à côté d’un utilisateur déjà identifié (ex. "vezadev").
- **À vérifier** : `Header.tsx` / `Navbar.tsx` — affichage conditionnel du bouton de connexion vs profil. S’assurer que "Sign In" n’est affiché que lorsque `!isAuthenticated`.

---

## 4. Layout et espacement

### 4.1 Barre de lecture (MiniPlayer / GlobalPlayer)

- **Taille** : `MiniPlayer` utilise `h-24` (96px) en barre fixe. Les contrôles (notamment le bouton play) sont très mis en avant (teal, grande taille).
- **Impact** : la barre occupe une part importante de la hauteur et attire trop l’attention sur les pages où la lecture n’est pas le focus (ex. Gear Locker, Academy, Admin).
- **Fichiers** : `apps/web/src/components/player/MiniPlayer.tsx` (L36 : `h-24`), `PlayerControls.tsx`, `PlayPauseButton.tsx`.

**Recommandations :**

- Réduire la hauteur sur desktop (ex. `h-20` ou `h-18`) et/ou rendre le contraste du bouton play un peu moins fort (même teal mais moins saturé ou plus petit).
- Barre de progression : déjà fine ; envisager une hauteur un peu plus visible pour la partie "remplie" (accessibilité + lisibilité).

### 4.2 Espacement entre sections (sidebar)

- **Constat** : les blocs "MY STUDIO", "VEZA NETWORK", etc. ont un espacement vertical serré entre le titre de section et le premier lien.
- **Fichier** : `apps/web/src/components/layout/Sidebar.tsx` (structure des sections).
- **Recommandation** : ajouter un peu de marge au-dessus des titres de section (ex. `mt-4` ou `space-y-1` entre titre et premier item) pour clarifier la hiérarchie.

### 4.3 Cartes dashboard (Command Center)

- **Constat** : les quatre petites cartes (Tracks Listened, Messages Sent, etc.) sont serrées ; le texte et les pourcentages peuvent sembler denses.
- **Fichiers** : vues dashboard qui utilisent `StatCard` ou équivalent ; grille (ex. `grid-cols-4`, `gap-6`).
- **Recommandation** : garder les layout primitives (pas de valeurs arbitraires) mais ajuster `gap` ou `padding` des cartes pour plus de respiration (ex. `p-6` déjà présent, éventuellement `gap-8`).

---

## 5. Typographie

### 5.1 Police Rajdhani

- **Usage** : `--font-sans: 'Rajdhani', ...` dans `index.css` (@theme inline). Utilisée pour le corps et une grande partie de l’UI.
- **Problème connu** : les erreurs console "downloadable font: Glyph bbox was incorrect" (Rajdhani) indiquent des **glyphes mal déclarés** dans le fichier de police. Conséquences possibles : rendu moins net, décalages, ou fallback partiel vers une autre police.
- **Fichiers** : `index.html` (lien Google Fonts), `apps/web/src/index.css` (--font-sans).

**Recommandations :**

- Vérifier la source de la police (version, subset) et si possible utiliser une version mise à jour ou un autre fournisseur.
- En parallèle, prévoir un fallback explicite (ex. `'Rajdhani', 'Inter', system-ui, sans-serif`) pour limiter les effets si Rajdhani pose problème.

### 5.2 Hiérarchie et lisibilité

- **Texte secondaire** : `text-muted-foreground` (oklch(0.70 0.01 265) en dark) peut être trop proche du fond sur certains écrans, ce qui réduit le contraste et la hiérarchie.
- **Recommandation** : augmenter très légèrement la luminance ou le contraste de `--muted-foreground` en dark (ex. 0.72–0.75) et valider avec un outil WCAG.

---

## 6. Contrastes et accessibilité

### 6.1 Éléments à faible contraste

- **Bordures** : `border-white/5`, `border-white/10` — très subtiles, peu visibles pour certains utilisateurs.
- **Icônes** : petites icônes en `text-muted-foreground` dans les cartes et le player ; contraste insuffisant pour une identification rapide.
- **Progress bar** (player) : barre de progression très fine ; partie "remplie" (teal) lisible, mais le rail peut manquer de contraste.

**Recommandations :**

- Utiliser au minimum `border-white/10` pour les séparations importantes, et réserver `white/5` aux détails purement décoratifs.
- Icônes secondaires : envisager une couleur un peu plus claire (ex. `text-foreground/70`) ou une taille légèrement supérieure pour les actions importantes.

### 6.2 Champs mot de passe en HTTP

- **Constat** : message navigateur "Password fields present on an insecure (http://) page" en dev. Ce n’est pas un problème de design mais de contexte (HTTPS en prod recommandé).

---

## 7. Cohérence et système de design

### 7.1 Double jeu de tokens (KŌDŌ vs design-tokens)

- **index.css** : variables type `--primary`, `--cyan-500`, `--card`, etc. (oklch).
- **design-tokens.css** : variables `--kodo-void`, `--kodo-cyan`, `--kodo-text-dim`, etc. (rgb).
- **Composants** : certains utilisent `primary` / `cyan-500`, d’autres `text-kodo-cyan`, `bg-kodo-steel`, etc. (ex. `StatCard.tsx` : `text-kodo-cyan`, `bg-kodo-steel/10`).
- **Risque** : dérives de teintes entre les deux systèmes et maintenance plus difficile.

**Recommandation :**

- À moyen terme, unifier sur un seul jeu de tokens (idéalement celui de `index.css` étendu en Tailwind) et migrer progressivement les `kodo-*` vers les tokens sémantiques (primary, muted, etc.).

### 7.2 Variantes de cartes

- **card.tsx** propose plusieurs variants : `default`, `elevated`, `ghost`, `outline`, `muted`, `glass`, `interactive`, `glow`, `glowMagenta`, `spotlight`. L’usage de `glass` partout (admin, etc.) donne un rendu très uniforme et plat.
- **Recommandation** : utiliser `default` ou `elevated` pour les cartes de contenu principal afin de retrouver un peu d’ombre et de relief, et réserver `glass` à des blocs spécifiques (panneaux, overlays).

---

## 8. Synthèse des actions prioritaires

| Priorité | Action | Fichier(s) principal(aux) |
|----------|--------|----------------------------|
| P0 | Unifier la couleur des badges sidebar (primary au lieu de secondary) | `Sidebar.tsx` |
| P0 | Ne pas afficher le badge "0%" en rouge quand trend est 0 ou undefined ; style neutre ou masqué | `AdminDashboardStatCard.tsx` |
| P1 | Donner plus de relief aux cartes (card vs background, bordure/ombre) | `index.css` (.dark), `card.tsx` |
| P1 | Remplacer ou clarifier le graphique "Traffic Flux" (données réelles ou placeholder explicite) | `AdminDashboardTrafficCard.tsx` |
| P1 | Vérifier l’affichage "Sign In" quand l’utilisateur est connecté | `Header.tsx`, `Navbar.tsx` |
| P2 | Réduire la prééminence visuelle du player (hauteur, taille du bouton play) | `MiniPlayer.tsx`, `PlayerControls.tsx` |
| P2 | Améliorer l’affordance de la barre de recherche (fond/bordure) | `Header.tsx` |
| P2 | Renforcer le contraste du texte secondaire et des bordures en dark | `index.css` |
| P3 | Unifier les tokens (kodo-* vs primary/muted) et documenter la charte | `design-tokens.css`, `index.css`, composants |
| P3 | Corriger ou contourner les glyphes Rajdhani (source font, fallback) | `index.html`, `index.css` |

---

## 9. Fichiers modifiables (référence rapide)

- **Couleurs / thème** : `apps/web/src/index.css` (variables :root et .dark).
- **Sidebar** : `apps/web/src/components/layout/Sidebar.tsx`.
- **Header** : `apps/web/src/components/layout/Header.tsx`.
- **Cartes** : `apps/web/src/components/ui/card.tsx` ; `AdminDashboardStatCard.tsx`, `AdminDashboardTrafficCard.tsx`.
- **Player** : `apps/web/src/components/player/MiniPlayer.tsx`, `PlayerControls.tsx`, `PlayPauseButton.tsx`.
- **Dashboard** : `apps/web/src/components/admin/admin-dashboard-view/AdminDashboardView.tsx`, `useAdminDashboardView.ts`.
- **Typographie** : `apps/web/index.html` (fonts), `apps/web/src/index.css` (--font-sans, @layer base).

Cet audit peut servir de base pour des tickets (P0 → P3) et pour une checklist avant refonte visuelle plus large.