TomasValleDuran/ui-ux-playbook

UI/UX Playbook

De bonnes interfaces naissent de trois éléments réunis : un point de vue clair (qui, quel travail, quelle sensation), un système cohérent (tokens + composants) et des centaines de détails corrects (états, motion, accessibilité, copy). Ce playbook orchestre l’arsenal de compétences qui couvrent chaque partie.

Workflow pour toute tâche UI

Adaptez-le : une retouche de bouton nécessite les étapes 5 à 7 ; une nouvelle application les nécessite toutes.

1. Brief — Qui est la personne, quel est le travail (verbe), quel contexte/appareil, quelle sensation doit-elle dégager (mots concrets). Inférer à partir du codebase et de la demande ; ne poser qu’une seule question si une contrainte critique est inconnue (plateforme, marque existante, public).
2. Direction — choisir le caractère esthétique et interactif avant le code. Regarder 2 à 4 références réelles pour ce type d’écran (ui-stack-advisor/references/inspiration.md).
3. Système — tokens et DESIGN.md (design-system-builder ; couleurs via color-theory). Projet existant ? Lire et suivre son système ; l’étendre, ne pas le dupliquer.
4. Stack — bibliothèques de composants/motion (ui-stack-advisor). Utiliser des primitives accessibles ; ne pas réinventer les boîtes de dialogue, menus, combobox, sélecteurs de date, toasts.
5. Construction — structure et hiérarchie d’abord (layout, typographie, espacement), puis couleur, puis détail. Contenu réel, pas de lorem ipsum. Tous les états : chargement, vide, erreur, partiel, succès, désactivé, contenu long.
6. Motion — seulement là où elle a un but (feedback, continuité, changement d’état) ; voir les compétences motion.
7. Vérifier visuellement — rendre l’interface (serveur de dev + Playwright/Chrome MCP/simulateur), vérifier aux tailles réelles (390, 768, 1280+ ; petit téléphone, tablette), les deux thèmes, clavier uniquement, zoom 200 % / Dynamic Type le plus grand. Corriger ce que l’on voit par lots.
8. Révision — exécuter la checklist pré-livraison ci-dessous ou une compétence de révision.

Quelle compétence pour quoi (routage)

Besoin	Charger
Direction esthétique pour pages d’atterrissage, marketing, design visuel distinctif	frontend-design
UI produit (tableaux de bord, SaaS, admin, outils) avec mémoire de design persistante	interface-design
Système de design, tokens, thèmes, tokens multi-plateformes, DESIGN.md	design-system-builder
Choix/dérivation des couleurs, palettes, couleurs mode sombre, contraste, sécurité daltoniens	color-theory (génère) · better-colors (audite)
Typographie : échelle, habillage, fonctionnalités de police, troncature	better-typography
Layout : regroupement, alignement, responsive, espace i18n	better-layout
Polissage : coins, ombres, icônes, alignement optique	better-ui
Révision/correction d’accessibilité (WCAG 2.2)	better-accessibility
UX copy, libellés, erreurs, états vides	better-writing
Révision classée de l’écran complet sur tous les aspects ci-dessus	better-interface · révision de branche/PR : interface-review
Choix des bibliothèques de composants/animation/widgets	ui-stack-advisor
Philosophie d’animation, assouplissements, durées, ressorts, sensation des composants	emil-design-eng
Créer une animation web	animate · plusieurs éléments ensemble : choreograph
Révision / audit / correction des animations saccadées	review-animations · improve-animations · animation-performance
Motion fluide de type Apple, gestes, matériaux (web ou natif)	apple-design
Web mobile donnant une sensation native (PWA, tactile, 100vh, safe areas)	mobile-native
Conception et révision React Native / Expo	mobile-design · animation : animate-expo · compétences plugin Expo : expo-native-ui, expo-ui, expo-design-system, expo-animation, expo-router
Spécificités shadcn/ui	shadcn (plugin Vercel)
Galerie de variantes / états des composants / test de résistance	variant · state-machine · break (invoqué par l’utilisateur)
Graphiques et visualisation de données tableaux de bord	dataviz
Figma ↔ code	Compétences MCP Figma (figma-design-to-code, figma-generate-library, …)

Règle de conflit : lorsque deux compétences sont en désaccord, le DESIGN.md/système existant du projet prévaut, puis le brief de l’utilisateur, puis la compétence la plus spécifique (par ex. animate-expo sur emil-design-eng dans une application Expo). Ne pas empiler plusieurs compétences de direction esthétique sur une même tâche — en choisir une (frontend-design ou interface-design).

Aide-mémoire des normes

Accessibilité (WCAG 2.2 AA — base légale aux États‑Unis (ADA/508), dans l’UE (European Accessibility Act, en vigueur depuis juin 2025) et dans de nombreux autres pays)

• Contraste 4,5:1 pour le texte, 3:1 pour les grands textes et les composants UI/graphiques significatifs
• Tout doit pouvoir être utilisé au clavier ; focus visible (2.4.7) non masqué par une UI collante (2.4.11) ; ordre logique
• Taille des cibles ≥ 24×24 px CSS (2.5.8) — concevoir pour 44×44
• Le glisser a une alternative à un seul pointeur (2.5.7)
• Étiquettes pour chaque champ de saisie, erreurs identifiées en texte, aucune information par la seule couleur
• Le texte se redimensionne à 200 % / se réorganise à 320 px de large sans défilement horizontal (1.4.10)
• Respecter reduced motion ; pas de flash > 3/s ; contenu en mouvement automatique > 5s doit pouvoir être mis en pause
• Emplacement d’aide cohérent (3.2.6), pas de ressaisie redondante (3.3.7), authentification accessible — pas de tests cognitifs, autoriser le collage/gestionnaires de mots de passe (3.3.8)
• HTML sémantique d’abord ; ARIA uniquement pour combler les lacunes. Natif : labels/traits d’accessibilité (iOS), contentDescription/semantics (Android/Compose), accessibilityLabel/accessibilityRole (RN)

Plateformes

• iOS (HIG) : cibles 44×44pt, barre d’onglets pour la navigation de premier niveau (≤5), pile de navigation avec balayage arrière, feuilles avec detents, SF Symbols, Dynamic Type, couleurs sémantiques, Liquid Glass pour la couche de contrôle (iOS 26+), haptiques pour événements significatifs
• Android (Material 3 / Expressive) : cibles 48×48dp, barre de navigation/rail/tiroir par classe de largeur, retour prédictif, edge-to-edge avec safe areas, couleur dynamique, échelle typographique M3
• Détails et différences : references/mobile-standards.md

Performance (Core Web Vitals, 75e percentile) : LCP ≤ 2,5s · INP ≤ 200ms · CLS ≤ 0,1. Répondre à une entrée en ~100ms ; afficher une progression pour tout ce qui dure > 400ms (seuil de Doherty) ; squelettes pour le contenu, spinners pour les actions ; UI optimiste là où c’est sûr. Mobile : 60/120ips, garder le thread JS libre (Reanimated worklets), listes virtualisées.

Principes UX : 10 heuristiques de Nielsen + Lois de l’UX (Fitts, Hick, Jakob, Miller/regroupement, Tesler, Doherty, pic-fin, esthétique-utilisabilité, Von Restorff, Gestalt). Recommandations de patterns pour formulaires, navigation, recherche, tableaux, onboarding, états vides/erreur/chargement, notifications, paramètres, actions destructrices : references/ux-principles-and-patterns.md.

Éthique : pas de dark patterns (confirmshaming, annulation piège à cafard, consentement pré-coché, fausse urgence, frais cachés, harcèlement). Ils sont de plus en plus illégaux (DSA/DMA de l’UE, règles FTC de click-to-cancel, règles GDPR sur le consentement) et érodent la confiance.

Checklist UI pré-livraison

• Objectif de chaque écran évident en 5 secondes ; une action principale par vue
• Hiérarchie lisible en plissant les yeux (taille/poids/contraste, pas seulement la couleur)
• Espacement, coins, typographie, couleur issus uniquement des tokens ; cohérent avec DESIGN.md
• États chargement, vide, erreur, partiel, hors ligne et contenu long conçus
• Formulaires : libellés, types de saisie/autocomplete corrects, erreurs en ligne, saisie conservée lors d’une erreur, pas de blocage du collage
• Clavier : ordre de tabulation, focus visible, Escape ferme les superpositions, le focus revient au déclencheur
• Lecteur d’écran : noms/rôles/états, régions live pour les mises à jour asynchrones, structure des titres
• Contraste mesuré dans les deux thèmes ; rien n’est véhiculé par la seule couleur
• Responsive à 320 / 390 / 768 / 1024 / 1440 ; cibles tactiles ≥ 44 ; pas d’affordances uniquement au survol
• Motion intentionnelle, ≤ 300ms pour l’UI, interruptible, reduced motion respectée
• Copy : verbes spécifiques sur les boutons, erreurs expliquant la correction, terminologie cohérente, prêt pour l’i18n (pas de chaînes concaténées, place pour +30–40 % de texte, propriétés logiques compatibles RTL)
• Performance : images dimensionnées/lazy, polices préchargées/swappées, pas de changement de layout, listes longues virtualisées
• Résultat rendu examiné (captures d’écran aux tailles réelles), pas seulement le code

Audit de code web avec l’ensemble complet des règles (focus, formulaires, animation, typographie, contenu, images, performance, navigation, tactile, thèmes, i18n, hydratation, copy, anti-patrons) : lire references/web-interface-guidelines.md et rapporter sous forme fichier:ligne - problème.

Références

• references/web-interface-guidelines.md — Web Interface Guidelines de Vercel (vendues, MIT) pour audits de code
• references/ux-principles-and-patterns.md — heuristiques, Lois de l’UX, et bonnes pratiques par pattern
• references/mobile-standards.md — iOS HIG + essentiels Material 3 et différences entre plateformes
• references/arsenal.md — chaque compétence UI installée : source, licence, utilité, mise à jour ; extras optionnels