lksnmnn/product-ui

Interface Utilisateur Produit

Une application est une surface de travail : les utilisateurs y reviennent pour accomplir une tâche. Chaque élément mérite sa place en servant cette tâche. L'objectif est une familiarité acquise — une personne habituée aux outils de cette catégorie reconnaît chaque contrôle au premier coup d'œil, et l'interface se fond dans la tâche.

Ces règles s'appliquent à toute application. Ce qui est spécifique à un projet — cibles de périphériques, système de conception, composants, direction, dérive connue — se trouve dans le fichier projet ; construisez à partir de celui-ci. Avant de considérer un écran comme terminé, exécutez revision.md.

Le fichier projet

Recherchez-le dans cet ordre : un chemin nommé dans CLAUDE.md ou AGENTS.md, puis .claude/product-ui.md. Lorsqu'il n'existe pas, créez .claude/product-ui.md à partir de templates/project.md avant la première construction :

1. Trouvez le système de conception : fichiers de tokens (propriétés CSS personnalisées, un thème Tailwind, un JSON de tokens), la bibliothèque de composants (dans le dépôt components/ui, shadcn, MUI, Radix, …), les fichiers de story.
2. Listez les éléments de base dont un écran a besoin (structure de page, tableau, champ de formulaire, état vide, boîte de dialogue, toast, …) avec leurs chemins. Marquez chaque élément manquant comme manquant ; n'inventez jamais un chemin.
3. Notez les dérives observées : les endroits où le code enfreint une règle ci-dessous.
4. Demandez à l'utilisateur les cibles de périphériques par application et qui possède le langage visuel (une équipe de conception, ou les développeurs). Suggérez des cibles en fonction de l'intention de l'application.

N'écrivez que ce que vous avez vérifié. Pointez CLAUDE.md vers le fichier pour que les sessions ultérieures le trouvent.

Lorsque le projet n'a pas de direction visuelle et que la surface ne doit pas paraître générique, exécutez d'abord la règle direction-conception ; elle enregistre son résultat dans le même fichier.

Objectif d'abord

Avant la mise en page, écrivez en une ligne chacun :

• le travail que l'écran sert et la personne qui l'effectue ;
• la première lecture : la première chose qu'ils regardent lorsque l'écran s'ouvre ;
• l'action principale et la fréquence à laquelle ils la répètent ;
• les cibles de périphériques : téléphone, tablette, ordinateur portable, grand écran, à partir du fichier projet.

Chaque région de l'écran correspond à une de ces lignes. Une région qui ne correspond à aucune est supprimée.

Contenu réel

Construisez et jugez avec un contenu semblable à la production : des noms réels de longueur réaliste, le titre le plus long possible, 0, 1, 7 et 500 éléments, une valeur facultative manquante, une traduction 30 % plus longue que l'anglais. "Jean Dupont", "Acme SARL", "Lorem ipsum", "Élément 1" et les nombres ronds cachent tous les problèmes de mise en page et sont la première chose qui fait qu'un écran semble généré. Lorsque les données du domaine sont inconnues, demandez un échantillon ou déduisez-en un à partir du schéma.

Chaque taille

Un écran est optimisé pour son périphérique principal et fonctionne à tous les autres points de rupture avec les mêmes fonctionnalités. Chaque taille reçoit le motif qui lui convient, et non une copie réduite du bureau : une barre latérale devient un tiroir ou un rail d'icônes, un tableau devient une liste empilée, un volet divisé devient une page avec une étape de retour, le survol devient une commande visible, une barre d'outils dense devient un menu de débordement. Une fonctionnalité qui disparaît en dessous d'un point de rupture est une anomalie.

Rien ne défile horizontalement à une largeur cible : ni la page, ni une liste dans son propre conteneur. Les colonnes de texte libre (noms, titres, e-mails, noms de fichiers) se rétrécissent et se tronquent avec le texte complet au survol ; seule une grille vraiment large (une matrice, une chronologie) peut défiler, et cela est indiqué.

Sur les grands moniteurs, le contenu conserve une mesure lisible : les blocs de texte restent en dessous de ~75 caractères par ligne, les formulaires conservent leur largeur de colonne, et un tableau peut s'agrandir tandis que ses colonnes de texte libre prennent l'espace.

Navigation

• La navigation globale liste les sections de l'application et reste la même sur chaque écran.
• Une section possédant ses propres sous-zones peut ajouter une couche locale (une deuxième colonne ou des onglets). Chaque couche n'affiche que son propre niveau : aucune couche ne répète les entrées d'une autre, et deux entrées ne partagent jamais une étiquette.
• Le périmètre — organisation, espace de travail ou compte sur lequel l'écran agit — est défini par un sélecteur, affiché une fois.
• Chaque page est à au plus deux choix de la navigation globale, et la navigation locale reste visible sur le périphérique principal.
• Le chrome au-dessus de la première commande reste petit : un fil d'Ariane ne répète jamais le titre de la page en dessous.
• Une application comportant plus de quelques sections ou de nombreux enregistrements propose une recherche rapide (⌘K / Ctrl+K) qui trouve les pages et les enregistrements par nom ou identifiant collé.

Densité

• Affichez l'ensemble de travail à la fois. Une liste qu'une personne scanne ou compare est un tableau avec une ligne par élément ; une grille de cartes est réservée aux quelques éléments dont l'image ou l'aperçu constitue le contenu.

• La hauteur des lignes suit le contenu : lignes d'une ligne 36–44 px, une ligne avec une deuxième ligne ou une vignette jusqu'à 64 px ; le remplissage ne prend jamais plus de hauteur que le contenu.

• L'écart entre les éléments apparentés est plus petit que l'écart entre les groupes, de sorte que le regroupement se lit à partir de l'espacement seul.

• Chaque élément d'une ligne mérite sa place. Testez chacun :

  • tâche : il sert à trouver, comparer, ouvrir ou agir sur l'élément, pour le travail de cet écran ;
  • supprimer : sa suppression fait perdre quelque chose dont la personne a besoin ; sinon, il disparaît, ou se déplace vers la vue détaillée ;
  • redondance : il ne répète aucune colonne, aucun filtre actif ni aucun titre de page ;
  • explicite : il se lit sans survol, info-bulle ou légende, et un statut est un mot, jamais une couleur seule ;
  • ordre : ce qui identifie l'élément en premier, puis les faits que les gens comparent, les actions en dernier.

  Un fait manquant est aussi une anomalie : lorsque les gens ouvrent élément après élément pour comparer une valeur, cette valeur a sa place dans la ligne.

• Une ligne par ligne par défaut. Les faits secondaires se trouvent dans leur propre colonne ou une deuxième ligne atténuée, jamais dans une info-bulle que la personne doit survoler pour comparer.

• Les titres, descriptions et textes d'aide sont aussi courts que le travail le permet. Une description de page qui répète le titre est supprimée.

• L'espace blanc sépare les groupes ; il ne remplit jamais un écran clairsemé pour le faire paraître plein.

• Une boîte (bordure, arrière-plan, ombre) marque une chose sur laquelle la personne agit comme une unité. Le regroupement seul se fait avec de l'espace ou une règle ; une carte à l'intérieur d'une carte est une anomalie.

Hiérarchie

• Une action principale par vue, visuellement principale, en haut à droite de son périmètre (en-tête de page ou en-tête de panneau). Les actions secondaires sont en contour ou fantômes ; les actions destructrices sont placées en dernier.
• Chaque taille, espace, couleur et rayon provient du système de conception de la surface et reste à l'intérieur de celui-ci. Une valeur arbitraire (text-[10px], p-[13px], un hex brut) est une anomalie ; le correctif est l'étape la plus proche, ou un nouveau token lorsqu'aucune étape ne convient.
• Le poids et la couleur portent la hiérarchie avant la taille.
• La couleur porte du sens : l'accent marque l'action principale, la sélection et l'état. Une couleur de statut n'apparaît que là où un statut existe.
• Les icônes accompagnent une étiquette là où elles accélèrent la reconnaissance (navigation, actions fréquentes) et se tiennent seules uniquement pour les actions universelles (fermer, rechercher, plus) avec un nom accessible. Une icône sur chaque bouton, titre ou carte est une décoration.
• Une valeur en lecture seule s'affiche sous forme de texte, jamais comme une entrée.
• Une commande que le rôle du spectateur ne peut pas utiliser est masquée, décidée par la même capacité que le serveur vérifie. Lorsque savoir que l'action existe est important, elle s'affiche désactivée avec la raison ("Seuls les administrateurs peuvent inviter").
• Le texte nomme ce que les gens reconnaissent, pas l'infrastructure qui le sous-tend : pas de noms de fournisseurs ou de pipelines à moins que le public ne travaille directement avec eux. La navigation ne liste aucune fonctionnalité non construite ou désactivée.

Rédaction

Le texte d'interface fait partie de la conception et est le révélateur le plus rapide d'un écran généré.

• Un bouton indique ce qu'il fait, sous forme de verbe et de son objet : "Inviter un membre", "Exporter CSV". Jamais "Soumettre", "OK", "Cliquez ici", "Commencer" dans une application.
• Le bouton de confirmation répète le verbe de la question : "Supprimer 3 fichiers ?" → "Supprimer les fichiers".
• Casse de phrase pour chaque étiquette, titre et bouton. Pas de points d'exclamation, pas de "Oups", pas de "Réussi", pas de "S'il vous plaît".
• Le feedback énonce le résultat dans les termes de la personne : "Facture envoyée à finance@…", pas "Opération terminée avec succès".
• Un état vide indique ce qui appartient ici et comment cela arrive ici, en une ou deux phrases simples. Pas d'esprit, pas de remplissage d'illustration, pas de "Rien à voir ici".
• Pas de voix marketing à l'intérieur d'un outil : supprimez "fluide", "sans effort", "puissant", "débloquer", "surpuissant", "magique", "alimenté par l'IA" et toute phrase qui fait l'éloge du produit.
• Un terme par concept dans toute l'application ; le glossaire vit dans le fichier projet.
• Les nombres, dates et unités suivent un format par application ; les décomptes utilisent le pluriel correct ("1 fichier", "2 fichiers").

Listes et tableaux

• Les nombres alignés à droite avec tabular-nums ; le texte aligné à gauche.
• Les horodatages utilisent un format fixe par application, jamais la locale par défaut du navigateur, et ne sont jamais tronqués. Les écrans de surveillance associent l'heure relative ("il y a 3 min") à l'heure absolue au survol, ou l'inverse.
• Les en-têtes nomment la colonne en un ou deux mots ; les en-têtes triables trient au clic.
• La recherche, les filtres, le tri, la page et l'élément ouvert vivent dans l'URL, de sorte qu'une vue survit au rechargement, au retour et à un lien partagé.
• Une ligne est un vrai lien vers son élément : toute la ligne l'ouvre, et Cmd-clic ouvre un nouvel onglet.
• Chaque référence dans une ligne — une personne, une organisation, un travail, un identifiant — renvoie vers sa propre page.
• Les actions par ligne se trouvent à la fin de la ligne dans une colonne stable, visible au repos ; au minimum, elles apparaissent sur les écrans tactiles. Un contrôle qui prend des clics tout en étant invisible est un bug.
• Le travail en lot propose des cases à cocher de sélection, un tout sélectionner, et une barre d'actions groupées lorsque la personne traite les éléments par lots.
• Pagination ou fenêtrage au-delà de ~50 lignes ; le nombre est toujours visible. Un filtre qui délimite l'ensemble (un intervalle de mois) remplace la pagination lorsque la limite est affichée.
• Les puces de filtre peuvent porter des décomptes ; elles font alors office de résumé de la page.

Formulaires

• Étiquettes au-dessus des champs, une colonne, dans l'ordre dans lequel la personne pense aux données.
• Validez lors de la perte de focus et lors de la soumission ; l'erreur se trouve sous son champ et indique comment la corriger.
• Les valeurs par défaut sont la réponse la plus courante. Les champs facultatifs sont marqués facultatifs, les champs obligatoires ne sont pas marqués.
• La soumission sur un formulaire de création ou d'action reste activée. La soumission d'une entrée invalide met le focus sur le premier champ invalide et indique comment le corriger sous ce champ.
• La sauvegarde sur un formulaire d'édition peut rester désactivée jusqu'à ce que quelque chose change, puisque rien n'attend d'être sauvegardé ; une fois que quelque chose change, il est activé, la règle ci-dessus s'applique, et une indication "Modifications non enregistrées" à côté montre l'état.
• Une sauvegarde par vue. Quitter avec des modifications non enregistrées demande confirmation.
• Un contrôle est désactivé pendant que sa propre action est en cours, afin qu'il ne puisse pas être déclenché deux fois.
• Un formulaire court ou un champ unique se modifie en ligne ; une boîte de dialogue est réservée à une tâche ciblée qui ne doit pas perdre son contexte.
• Les entrées utilisent le type correct et autocomplete (email, tel, one-time-code, …) afin que les téléphones affichent le bon clavier et que les navigateurs les remplissent.
• Un déclencheur de téléchargement de fichier est un bouton focalisable qui ouvre le sélecteur, et accepte également un glisser-déposer.
• Une page qui configure ce qu'une autre surface dessine (une intégration, une marque, un modèle) affiche un aperçu de cette surface à côté de ses paramètres.

Actions et commentaires

• Une action avec un retour possible (restaurer, désarchiver, réactiver) s'exécute immédiatement et propose annuler, sans confirmation préalable. Un interrupteur est son propre annuler et nécessite uniquement un commentaire immédiat.
• Une action sans retour possible obtient une confirmation qui nomme ce qui est perdu ("Supprimer 3 documents"). Une action qui semble réversible mais n'a pas d'inverse est traitée comme irréversible jusqu'à ce que l'inverse existe.
• Chaque action répond en moins de 100 ms : mise à jour optimiste, état en attente sur le contrôle, ou squelette là où le contenu atterrira.
• Un travail qui prend plus de quelques secondes s'exécute en arrière-plan avec une progression visible, et survit à la navigation.
• Les erreurs indiquent ce qui s'est passé et quoi faire ensuite, à côté de l'endroit où cela s'est produit.

La matrice des états

Chaque vue embarque tous ses états, conçus, non par défaut :

État	Forme
chargement	un squelette dans la disposition que le contenu prendra
vide	indique ce qui appartient ici et propose l'action pour l'ajouter
filtré-vide	indique que le filtre n'a rien trouvé et propose de l'effacer
partiel	les parties qui se sont chargées s'affichent ; la partie en échec affiche sa propre erreur, jamais un zéro
accès refusé	indique qui peut voir ceci et comment obtenir l'accès, et propose une voie de sortie
erreur	ce qui a échoué, une nouvelle tentative, le reste de l'écran toujours utilisable
complet	le contenu réel à volume réaliste, incluant les noms longs et de nombreuses lignes

Chaque contrôle interactif a des états par défaut, survol, focus-visible, actif, désactivé et en attente.

Sur un tableau de bord, chaque tuile et graphique possède ses propres états : une lecture en échec affiche sa propre erreur, jamais un zéro ou un graphique vide. Un tableau de bord s'ouvre sur ce qui nécessite une attention, pas sur une rangée de cartes métriques ; un nombre n'apparaît qu'avec la comparaison qui le rend significatif (cible, période précédente) et une définition convenue par l'équipe. Les graphiques suivent la règle dataviz lorsqu'elle est installée.

Accessibilité et thèmes

• Le texte du corps respecte un contraste de 4,5:1, le texte large et les limites des contrôles de 3:1, dans chaque thème. Le gris atténué sur fond gris est l'échec le plus courant.
• Le focus est toujours visible et jamais coupé ; l'anneau de focus est conçu, pas le navigateur par défaut supprimé.
• Chaque contrôle a un nom accessible ; un bouton avec seulement une icône obtient aria-label. Les points de repère (nav, main) et un h1 par page.
• Le texte se redimensionne à 200 % et la disposition tient.
• Lorsque l'application prend en charge un thème sombre, il est conçu : ses propres étapes de surface et un accent réglé, pas des couleurs inversées. Révisez chaque écran dans les deux.

Ergonomie

• La tâche principale se termine à partir du clavier : l'ordre de tabulation suit l'ordre de lecture, Entrée soumet, Échap ferme, le focus revient d'où il vient.
• Les cibles de clic mesurent au moins 24 × 24 px, les plus fréquentes plus grandes, 44 px sur le tactile ; la zone de clic couvre toute la ligne ou l'étiquette, pas seulement l'icône.
• Les actions fréquentes se trouvent près de ce sur quoi elles agissent. La distance et le clic …

[La suite est tronquée pour la traduction]