veza/apps/web/docs/AUDIT_UI_UX_VISUEL_COMPLET.md

Audit UI/UX visuel complet — Qualité Discord/Spotify-like

Date : 8 février 2025
Rôle : Lead Frontend Engineer + Design Systems Architect + UX Reviewer
Référents : Discord (densité, sidebar, clarté), Spotify (rythme, listes, player), Linear, Notion
Source de vérité visuelle : Storybook (full layout), baselines visual-tests/, code shell et tokens.

Méthodologie : Analyse fondée sur le code du shell (DashboardLayout, Sidebar, Header, GlobalPlayer), les tokens (index.css, DESIGN_TOKENS.md, APP_SHELL.md), les rapports existants (UI_UX_AUDIT_DISCORD_SPOTIFY_QUALITY.md, VISUAL_AUDIT_REPORT.md) et l’analyse des assets dans visual-tests/baselines/. Les baselines actuelles (dashboard, library, header) décrivent des écrans de login lorsque l’app est capturée sans session ; pour une observation directe du shell complet, ouvrir Storybook sur App/Layouts/DashboardLayout → Dashboard – full layout (port 6006).

---

1. Résumé exécutif (10–15 lignes)

L’interface Veza se situe aujourd’hui entre produit soigné et produit premium. Le shell (sidebar, header, main, player) est structuré et tokenisé : largeurs, marges, z-index et transitions sont centralisés dans index.css et APP_SHELL.md. La hiérarchie typographique et le rythme des pages principales (Dashboard, cartes, listes) sont maîtrisés sur les vues authentifiées. Les écarts qui empêchent le niveau Discord/Spotify sont : (1) baselines visuelles qui reflètent souvent l’état login (redirection non authentifiée), donc peu de captures du shell complet ; (2) valeurs arbitraires restantes (modales, quelques vues) et typo (text-[10px]) ; (3) scrollbar et effets globaux définis à plusieurs endroits ; (4) patterns Error/Empty et focus-visible pas encore systématiques. Impression utilisateur : application moderne, dark theme cohérent, player et sidebar soignés ; la dernière couche de polish (micro-interactions, contraste secondaire, un seul système de scrollbar) manque pour atteindre le niveau “premium”.

---

2. Constats visuels majeurs (avec références)

2.1 Source des observations

• Storybook : stories App/Layouts/DashboardLayout — Default (shell + placeholder), Dashboard – full layout, Playlists – full layout, Library – full layout, Settings, Profile. Viewport desktop, MSW actif. Recommandation : considérer Storybook comme source de vérité pour le shell et lancer les captures Playwright sur ces stories (pas seulement sur l’app avec auth).
• Baselines actuelles (visual-tests/baselines/) : les captures dashboard-desktop-dark.png, header-desktop-dark.png, library-desktop-dark.png décrivent dans l’analyse des images des écrans de login (Welcome Back, Sign in, boutons sociaux). Cela indique soit une redirection login quand l’auth n’est pas disponible pendant la capture, soit un nommage à clarifier. Pour un audit shell complet, s’appuyer sur les stories full layout Storybook.
• Code : DashboardLayout.tsx, Sidebar.tsx, Header.tsx, GlobalPlayer.tsx, index.css (tokens shell), DESIGN_TOKENS.md, APP_SHELL.md.

2.2 Shell & structure globale

Élément	Constat visuel / code	Niveau
Sidebar	Largeur tokenisée : 15rem (expanded), 5rem (collapsed). Classes w-sidebar-expanded, w-sidebar-collapsed, transition-shell. Sections (My Studio, Veza Network, Commerce, Library, System), labels en text-xs uppercase, items px-3 py-2 rounded-lg, indicateur actif sidebar-active-indicator. Densité proche Discord (liste de canaux).	Correct à premium
Header	h-header (4rem), backdrop-blur-md, position left-header-expanded / left-header-collapsed selon sidebar. Recherche type Spotify (rounded-full, placeholder “What do you want to play?”). Badge “Online”, notifications, theme toggle, user menu. Rapport avec le main : pt-main dégage le header.	Correct
Player	Barre flottante bottom-6, lg:left-main-expanded / lg:left-main-collapsed, rounded-2xl, backdrop-blur-2xl, barre de progression en haut, h-20 md:h-24. Animation d’entrée slide-in-from-bottom-4 fade-in duration-500, player-bar-entrance avec prefers-reduced-motion respecté. Poids visuel fort mais contenu principal reste prioritaire.	Robuste
Alignement global	Main : pt-main, pb-main, px-4 md:px-8, max-w-layout-content mx-auto. Marges gauche lg:ml-main-expanded / lg:ml-main-collapsed. Grille cohérente.	Correct

Conclusion shell : niveau actuel correct à premium. Structure claire, tokens respectés, transitions fluides. La seule réserve : sur les captures “app” (non-Storybook), si l’utilisateur n’est pas authentifié, le shell n’est pas visible — d’où l’importance des stories full layout pour la régression visuelle.

2.3 Rythme visuel & spacing

• Dashboard : space-y-6 page, gap-4 grille stats, gap-6 grille activité. Cartes en Card variant="glass" avec transition-all duration-[var(--duration-normal)]. Padding contenu p-6 pb-24.
• Sidebar : space-y-6 entre sections, space-y-0.5 entre items, px-3 py-2 items, px-4 py-4 header sidebar.
• Tokens : --layout-gap, --layout-gap-sm, --layout-gap-lg documentés. Échelle Tailwind utilisée (gap-2, gap-3, gap-4, p-3, p-4, etc.).
• Où le rythme est maîtrisé : grilles Dashboard, espacement sidebar, padding main, espacement entre cartes.
• Où il peut casser la lecture : rapports arbitraires signalent encore des gap-[Xpx] ou p-[Xpx] dans certains composants (modales, vues métier) ; à migrer vers l’échelle ou tokens pour un rythme 100 % cohérent type Discord/Spotify.

2.4 Hiérarchie typographique

• Titres : text-3xl font-display font-bold (Dashboard welcome), text-2xl font-bold (valeurs stats), sous-titres text-sm / text-xs text-muted-foreground.
• Sidebar : sections en text-xs font-medium uppercase tracking-wider, items text-sm font-medium.
• Player : titre piste text-sm md:text-base font-display font-bold, artiste text-xs text-muted-foreground.
• Reste de text-[10px] : listé dans UI_UX_AUDIT_DISCORD_SPOTIFY_QUALITY.md (Navbar, Badge, Admin, MetadataForm, etc.) — à migrer vers text-xs sauf exceptions documentées (ex. avatar xs).
• Contraste principal / secondaire : text-foreground vs text-muted-foreground utilisé ; à vérifier ratio AA sur muted-foreground (audit a11y recommandé).

2.5 Couleurs, contrastes, surfaces

• Fonds : bg-background, sidebar bg-[var(--sidebar)], header bg-transparent backdrop-blur-md, cartes variant="glass", player bg-black/80 border border-white/10.
• Hover / focus : hover:bg-sidebar-accent, hover:bg-white/5, focus-visible:ring-2 focus-visible:ring-primary/50 sur Sidebar et Header. Cartes hover:border-primary/50.
• Impression : l’UI “respire” grâce au dark theme, aux espacements et au blur ; pas d’écrasement visuel. Profondeur par bordures légères et ombres sémantiques (shadow-card, shadow-player-hover).

2.6 Composants (qualité perçue)

Composant	Classe	Commentaire
Sidebar (nav items, sections)	Robuste	États actif/hover/focus cohérents, transitions tokenisées.
Header (search, menu user)	Correct	Recherche lisible, menu dropdown ; focus-visible présent.
GlobalPlayer (barre, controls)	Robuste	Entrée animée, barre de progression, hover sur barre.
Cartes Dashboard (stats, activité)	Correct	Glass, hover border, pas de surcharge.
Boutons (primaire, ghost)	Correct	Focus ring, transitions.
Inputs (login/register vus en baselines)	Correct	Rounded-xl, contraste OK ; lien “Don’t have an account? Sign up” signalé en contraste faible dans les descriptions d’images → à renforcer.
Modales (max-h)	Fragile	Plusieurs max-h-[85vh] / max-h-[80vh] encore en dur → migrer vers tokens .max-h-layout-modal*.

2.7 Micro-interactions & motion

• Présent : transition-shell (sidebar), duration-[var(--duration-fast)] / --duration-normal sur Header, Sidebar, cartes, player. Animation d’entrée player (slide-in-from-bottom-4, fade-in). prefers-reduced-motion: reduce désactive transition-shell et player-bar-entrance.
• Où une animation apporte du sens : déjà en place sur le player (entrée, hover barre). À étendre : feedback hover/focus uniforme sur toutes les listes et cards cliquables ; loading states sur boutons (spinner) pour les actions async.

---

3. Points forts (à préserver absolument)

1. Shell tokenisé : une seule source (index.css) pour sidebar, header, main, player (largeurs, marges, offsets, z-index). Classes utilitaires .pt-main, .pb-main, .ml-main-expanded, .transition-shell, etc.
2. Layout primitives : max-w-layout-content, min-h-layout-main, min-h-layout-page, tokens modales/lyrics documentés dans DESIGN_TOKENS.md et APP_SHELL.md.
3. Transitions et durées : variables --duration-fast, --duration-normal, --duration-slow, --ease-out, --ease-in-out utilisées dans le shell et les composants critiques ; pas de duration-200 en dur.
4. Ombres sémantiques : .shadow-card, .shadow-modal, .shadow-tooltip, .shadow-player-thumb, .shadow-queue-item-current, etc. — cohérence et maintenabilité.
5. Sidebar : structure claire (sections, labels, indicateur actif), focus-visible et hover cohérents, transition expand/collapse fluide.
6. GlobalPlayer : positionnement aligné sur la sidebar (lg:left-main-*), entrée animée, barre de progression toujours visible, reduced-motion respecté.
7. Stories full layout : DashboardLayout avec Dashboard, Playlists, Library, Settings, Profile — référence visuelle et base pour tests de régression.
8. Skeletons : présents sur de nombreuses vues (Library, Playlist, Track, Chat, Settings, Profile) pour états Loading.
9. Règles et outillage : ESLint no-restricted-syntax sur valeurs arbitraires, script report-arbitrary-values.mjs, procédure visual-tests documentée.

---

4. Points faibles critiques (ce qui empêche le niveau premium)

1. Captures visuelles shell : les baselines “dashboard”, “library”, “header” peuvent montrer l’écran de login si l’app est capturée sans session. Le shell complet (sidebar + header + main + player) n’est pas garanti dans la régression actuelle. Impact : régressions layout shell non détectées.
2. Valeurs arbitraires restantes : modales (max-h-[85vh], etc.), quelques vues (LiveStreamDetailView, APIPlaygroundView, etc.), typo text-[10px] dans plusieurs fichiers. Impact : incohérence et maintenance difficile.
3. Scrollbar et effets globaux : définitions dans index.css, global-effects.css et fixDisplayIssues.ts — risque d’incohérence selon l’ordre de chargement. Impact : expérience variable, sentiment “bricolé”.
4. Contraste secondaire : texte “Don’t have an account? Sign up” et similaires (muted-foreground) signalés comme faible contraste dans les analyses d’images. Impact : accessibilité et lisibilité en dessous du niveau AA sur certains textes secondaires.
5. Patterns Error / Empty : pas unifiés (toast vs bannière vs bloc inline ; messages et CTA empty hétérogènes). Impact : expérience incohérente en cas d’erreur ou liste vide.
6. Focus-visible : pas sur tous les contrôles (Select, certaines listes, certaines cards). Impact : navigation clavier et a11y incomplètes.
7. Réduction de mouvement : partielle (effets décoratifs) ; pas étendue à toutes les transitions du shell/player dans un seul bloc prefers-reduced-motion. Impact : utilisateurs sensibles au motion pas toujours respectés.

---

5. Top 10 des améliorations à plus fort impact

#	Amélioration	Impact visuel	Risque	Effort
1	Capturer le shell en Storybook : ajouter des tests Playwright qui ouvrent les stories DashboardLayout (Default, DashboardFullLayout) et capturent sidebar + header + main + player. Mettre à jour la doc visual-tests.	Élevé (régression shell détectée)	Faible	M
2	Unifier la scrollbar : une seule source (index.css ou global-effects) avec variables CSS ; retirer ou cantonner les injections dans fixDisplayIssues.	Élevé (cohérence perçue)	Moyen	S
3	Tokens modales : utiliser .max-h-layout-modal, .max-h-layout-modal-sm, etc. partout ; supprimer les max-h-[XXvh] dans les modales.	Moyen (design system)	Faible	M
4	Contraste muted-foreground : mesurer et ajuster --muted-foreground (dark) pour ratio ≥ 4.5:1 ; corriger les liens secondaires (ex. “Sign up”).	Élevé (lisibilité, a11y)	Faible	S
5	Pattern Error unifié : composant ou pattern (page vs liste vs formulaire) + usage systématique.	Moyen (cohérence)	Faible	M
6	Pattern Empty unifié : structure commune (titre, description, CTA) + style cohérent pour librairie vide, playlist vide, queue vide, recherche sans résultat.	Moyen (cohérence)	Faible	M
7	Focus-visible sur tous les contrôles : audit des éléments focusables (Select, listes, cards cliquables) et ajout du ring cohérent.	Élevé (a11y, clavier)	Faible	M
8	Migration text-[10px] → text-xs : avec exceptions documentées (avatar xs, etc.).	Moyen (typo cohérente)	Faible	S
9	Réduction de mouvement complète : étendre @media (prefers-reduced-motion: reduce) à toutes les transitions du shell et du player (sidebar, header, player bar).	Moyen (a11y)	Faible	S
10	Micro-interactions : hover/focus explicites sur list items et cards cliquables ; loading spinner sur boutons d’action async.	Moyen (polish)	Faible	M

---

6. Recommandations structurantes

6.1 Design system

• Consolider une seule définition des effets globaux (scrollbar, noise) et la documenter dans DESIGN_TOKENS.md.
• Documenter les exceptions typo (avatar xs, etc.) et les tokens modales/lyrics déjà en place.
• Ajouter un court guide “Empty state” et “Error handling” dans docs/ et les lier depuis DESIGN_TOKENS ou STORYBOOK_CONTRACT.

6.2 Layout

• Continuer à utiliser uniquement les classes shell tokenisées (pt-main, pb-main, lg:ml-main-*, left-header-*, lg:left-main-*) ; pas de marges/padding en dur pour le shell.
• Valider les breakpoints 320, 768, 1024, 1280 sur les stories full layout (grilles, listes, sidebar overlay).

6.3 Composants

• Classe chaque nouveau composant “feature” avec états Loading (skeleton), Error, Empty dans les stories (référence STORYBOOK_CONTRACT.md).
• Étendre l’usage des ombres sémantiques (shadow-card, shadow-modal) et éviter les shadow-[...] arbitraires.
• Boutons : feedback loading (spinner ou disabled) sur toutes les actions async.

6.4 Motion

• Utiliser uniquement les variables --duration-* et --ease-* pour les transitions.
• Centraliser la logique prefers-reduced-motion: reduce (déjà partiellement en place) pour shell et player ; ne pas ajouter d’animations décoratives sans les désactiver en reduced-motion.

---

7. Verdict honnête

Aujourd’hui, cette UI est à environ 70–75 % d’une qualité Discord/Spotify-like.

• Shell et structure : 85 % — très proche (tokens, alignements, player).
• Rythme et spacing : 75 % — bon sur les pages principales ; reste des arbitraires et quelques incohérences.
• Typographie : 70 % — hiérarchie claire ; reste des text-[10px] et contraste secondaire à renforcer.
• Couleurs et surfaces : 80 % — thème cohérent, ombres sémantiques.
• Composants : 70 % — sidebar et player robustes ; modales et patterns Error/Empty à unifier.
• Motion : 75 % — transitions tokenisées et reduced-motion partiel ; micro-interactions à étendre.

Les 2–3 prochaines semaines ciblant : (1) captures shell Storybook + unification scrollbar, (2) tokens modales + contraste muted-foreground, (3) patterns Error/Empty et focus-visible, feront franchir le cap “produit premium” de façon visible et durable.

---

8. Références

• docs/DESIGN_TOKENS.md — tokens layout, typo, ombres, transitions.
• docs/APP_SHELL.md — shell, variables CSS, classes utilitaires, responsive.
• docs/UI_UX_AUDIT_DISCORD_SPOTIFY_QUALITY.md — lacunes détaillées, phases A/B/C.
• visual-tests/README.md — procédure capture/compare/update.
• src/components/layout/DashboardLayout.stories.tsx — stories full layout.
• src/index.css — tokens shell, .transition-shell, .pt-main, .pb-main, etc.