21 Grams UI – Polissage d'interface (UI Uplift)
Une passe sur une interface utilisateur qui existe déjà. 21 Grams UI (le package UI de la famille 21 Grams) ne refait pas le design du produit et n'apporte pas son propre kit UI. Il supprime les signes d'une interface construite par IA et applique un ensemble fixe de règles via les composants et les jetons que le projet possède déjà, afin que le résultat paraisse réfléchi, rapide et reste ancré dans le produit.
Règle zéro : utiliser les composants du projet
Chaque modification passe par ce que le projet utilise déjà. 21 Grams UI ne crée jamais un jeu de composants parallèle.
- Faire un inventaire avant de toucher à quoi que ce soit. Noter les jetons de design ou le thème (variables CSS, config Tailwind, fichiers de thème), la bibliothèque de composants (shadcn/ui, Radix, MUI, Chakra, un kit maison, un système de design client), le jeu d'icônes, la bibliothèque de graphiques et la bibliothèque d'animation. Enregistrer comment chaque composant partagé est nommé et où il se trouve.
- Corriger les choses là où elles vivent. Une règle concernant un bouton va dans le
Buttondu projet (un jeton, une variante, une propriété ou ses styles), jamais dans une copie isolée sur un seul écran. Une règle de couleur ou de rayon va dans le jeton, pas dans des valeurs codées en dur. - Ne jamais ajouter un composant quand un existe déjà pour le travail, et ne jamais ajouter de dépendance (kit UI, jeu d'icônes, bibliothèque de graphiques ou d'animation) pour obtenir un effet 21 Grams UI. Utiliser ce qui est installé. Sans bibliothèque d'animation, utiliser les transitions CSS.
- Quand une pièce manque vraiment (pas de contrôle segmenté, pas d'interrupteur), la construire à partir des primitives et des jetons existants du projet, en suivant sa structure de fichiers et sa nomenclature. Le mentionner dans le rapport.
- Les valeurs du style maison sont des valeurs par défaut pour les lacunes uniquement.
rules/ettokens/tokens.cssdonnent des valeurs pour ce que le projet n'a pas décidé. Les mapper sur les jetons du projet. Ne jamais collertokens.cssà côté d'un système existant. - La marque reste celle du projet. Les couleurs de marque, les polices, les logos, le style d'icônes et la voix ne sont jamais remplacés. 21 Grams UI change comment ils sont utilisés (contraste, hiérarchie, espacement, mouvement), pas ce qu'ils sont.
Priorité : les mots de l'utilisateur, puis le système de design et la marque du projet, puis le style maison 21 Grams UI. Les principes, astuces et techniques d'animation s'appliquent partout, exprimés dans les composants du projet.
Ce qu'il contient
- Style maison. Huit domaines dans
rules/:radius.md(12/8/4 emboîté),buttons.md(36px, pression .97),motion.md(fluide, depuis le déclencheur, sans rebond),type.md(serré, peu de tailles),spacing.md(échelle 4pt groupée),colour.md(un accent, AA),elevation.md(remplissages tonaux),copy.md(sobre et utile). Plus trois fichiers composants :icons.md(un seul style, line, solid ou duotone, jamais mélangé),charts.md(ligne, colonne et barres horizontales) ettoggles.md(interrupteur et contrôle segmenté). Les valeurs par défaut sont danstokens/tokens.css. - Les 20 principes. Principes d'UX et d'animation dans
references/principles.md. - Les 10 astuces de design. Détails d'artisanat CSS dans
references/design-hacks.md. - Les 20 techniques d'animation. Règles de mouvement au niveau implémentation (origines, durées, décalage, pression, glisser, mise en page partagée) dans
references/animation-craft.md. - Les 10 astuces typographiques. Largeur grasse réservée, trim de boîte de texte, décalage de soulignement, espacement d'exposant, affichage fluide, petites majuscules pour acronymes, guillemets courbes, troncature médiane, césure automatique et titres limités en lignes, dans
references/typography.md. - Les 20 règles anti-débraillé. Indices de composition et de contenu (badges de remplissage, étiquettes redondantes, italiques aléatoires, mono décoratif, illustration abstraite, fonctionnalités de poids égal, titres vagues, lueurs, alignement optique, états de chargement) dans
references/unslop.md.
Si une compétence de visualisation de données est installée, la charger également dès qu'un graphique est impliqué.
Flux de travail
- Faire l'inventaire (règle zéro). Si le projet n'a aucun système de design, le dire et utiliser les valeurs par défaut du style maison.
- Auditer avant de changer quoi que ce soit. Parcourir l'écran ou le composant et lister les constats regroupés par domaine (radius … copie), numéro de principe, numéro d'astuce et numéro de technique. Utiliser les listes de vérification à la fin de
references/principles.md,references/design-hacks.md,references/animation-craft.md,references/typography.md,references/unslop.mdetrules/icons.md. Chaque constat obtient le fichier et la ligne, ce qui ne va pas, la correction et dans quel composant ou jeton existant la correction va. Signaler chaque endroit où une règle 21 Grams UI entre en conflit avec le système de design du projet, pour que l'utilisateur décide qui l'emporte. - Montrer l'audit à l'utilisateur sous forme d'une courte liste et demander avant d'appliquer des changements larges. Les petites corrections évidentes dans le périmètre demandé peuvent être appliquées directement.
- Appliquer les corrections dans cet ordre : jetons → composants partagés → écrans. Maintenir les diffs limités à ce qui a été audité et dans les conventions du projet (formatage, lint, nommage).
- Vérifier dans le navigateur. Captures d'écran avant et après de chaque écran modifié. Vérifier les états survol, pression, focus, chargement, erreur, les deux thèmes et le mouvement réduit. Mesurer le contraste des boutons et du texte ; ne pas se fier à l'œil. Pour le mouvement, enregistrer l'avant et l'après si possible. Une page avant/après avec un séparateur glissable et des interactions fonctionnelles des deux côtés est la manière la plus claire de réviser un polissage.
- Rapporter ce qui a changé par domaine, principe, astuce et technique, quels composants et jetons ont été touchés, et tout ce qui est resté non fait.
Style maison en un coup d'œil (valeurs par défaut pour les lacunes)
- Rayon 12 conteneurs / 8 contrôles / 4 petites pièces, emboîté comme extérieur − remplissage. Pas de pilules sauf tags et toggles.
- Boutons 36px (32 compact, 40 important), rayon 8, 14/500, un primaire solide, un primaire par vue, survol = changement de couleur uniquement, pression = changement de couleur +
scale(.97)150ms, chargement conserve la largeur. - Mouvement : pas de rebond sur l'interface quotidienne. Menus 220ms entrée / 175ms sortie depuis
scale(.95)au déclencheur, panneaux 240 / 190, entrées avec ease-out, sorties avec ease-in (~80% de l'entrée), lignes de liste décalées de 30ms, interactions fréquentes instantanées. - Typographie : les polices du projet (Geist quand il n'y en a pas). Mono est réservé au code, jamais pour les étiquettes, les surtitres, les badges, les horodatages ou les chiffres (
tabular-numsdans le sans aligne les figures). Tailles 12/14/16/22/28, graisses 400/500/600, en-têtes −0.022em, au plus quatre tailles par écran. Sur mobile, les titres montent d'un cran : section 18, carte 16. - Bouton d'envoi sur chat mobile : un bouton icône seule 44×44 en forme d'avion en papier avec
aria-label="Send". - Espacement : échelle 4pt. Plus serré à l'intérieur des groupes qu'entre eux (4 / 6 / 16 / 24–32 / 48). Chevron de sélection à 12px du bord droit,
padding-right36px. - Couleur : un accent (actions, focus, sélection), couleurs de statut séparées, texte des boutons ≥ 4.5:1 dans les deux thèmes avec
--on-accentpar thème. - Élévation : les surfaces au repos sont un pas de remplissage sans bordure ni ombre. Seules les couches flottantes obtiennent un anneau et une ombre. Le mode sombre est plus clair par couche.
- Icônes : un seul style par produit, line, solid ou duotone, et jamais mélangé dans un menu, une navigation, une barre d'outils, une liste ou une carte. Les états sélectionnés changent la couleur, pas le style de l'icône. Une seule bibliothèque d'icônes, une seule largeur de trait, une seule taille par groupe.
- Copie : boutons verbe + objet, erreurs avec cause et correction, casse de phrase, pas d'emoji, pas de mots accrocheurs.
Non-négociables (issus des 20 principes)
- Un mouvement d'interface déclenché par l'utilisateur dure 120–300ms, et les sorties sont environ 80% de l'entrée. Jamais de
linearpour un déplacement. - L'easing correspond à la direction : entrée ease-out, sortie ease-in, A→B à l'écran ease-in-out. Pas de dépassement sur l'interface quotidienne.
- Les interactions à haute fréquence (navigation clavier, surlignage de liste, onglets dans les outils) sont instantanées.
- Chaque entrée est reconnue en moins de 100ms. Utiliser une UI optimiste pour les sauvegardes. Montrer une progression au-delà de 400ms.
- Les zones de clic font au moins 44×44 sur tactile et 32×32 sur bureau dense, même si l'icône est plus petite.
- Une seule action au focus et une seule action principale par vue. Assombrir le contexte quand quelque chose prend le focus.
- Les longs nombres sont groupés. Les champs de saisie acceptent les formats désordonnés et renvoient la valeur nettoyée.
- Emplacement et icônes standard sauf s'il y a une raison de faire autrement.
- Chaque état d'un composant est conçu : inactif, survol, pressé, chargement, succès, erreur, désactivé.
prefers-reduced-motion: supprimer le mouvement, le scale et le dépassement, conserver un bref changement d'opacité.
Non-négociables (issus des 10 astuces)
- Rayon emboîté : intérieur = extérieur − remplissage.
- Les bordures sont alpha (
rgb(0 0 0 / .12)), jamais un hexagone gris uni sur des surfaces variées. - Palettes et dégradés en OKLCH (
in oklchsur les dégradés). - L'épaisseur de trait des icônes correspond à la graisse du texte adjacent.
- Les défileurs horizontaux s'estompent sur les bords avec un masque.
- Les changements d'icônes se fondent avec
filter: blur(4px). - Mode sombre : chaque couche plus haute est plus claire (page < carte < menu).
- Pleine hauteur mobile :
dvh/svh, jamais100vhnu. - Photos de produit sur fond blanc sur cartes teintées :
mix-blend-mode: multiply.
Non-négociables (issus des 10 astuces typographiques)
- Le passage en gras au survol ou à la sélection ne décale jamais la mise en page (réserver la largeur du gras).
- Les étiquettes sur une seule ligne dans les boutons et badges sont centrées optiquement (
text-box-trim). - Les soulignements de liens évitent les jambages descendants (
text-underline-offset: 0.2em). Les exposants ne cassent pas le rythme des lignes. - Ponctuation réelle dans la copie : guillemets courbes, apostrophes, tirets en-demi,
…. - Les noms qui diffèrent à la fin sont tronqués au milieu. Les titres de cartes dans les grilles sont limités au même nombre de lignes.
Non-négociables (issus des 20 techniques d'animation)
- Les popovers et menus sortent de leur déclencheur (
transform-originau déclencheur), commencent àscale(.95), jamaisscale(0), et sortent en retournant dans le déclencheur. - Les anciens et nouveaux états se chevauchent. Il n'y a jamais d'image vide entre Enregistrer et Enregistré.
- Les glissements suivent le pointeur 1:1 sans transition pendant le maintien, et s'étirent au-delà des limites.
- Carte → détail étend le même élément (
layoutId/ transition de vue partagé), jamais un remplacement déconnecté. - Les contrôles segmentés et les onglets révèlent l'étiquette active avec un masque qui se déplace avec l'indicateur.
- Les boutons mobiles s'étirent d'environ 12% (préservant la surface). Le succès obtient une pulsation.
Signes IA à éliminer
Styles d'icônes mélangés (une maison solide à côté d'un dossier contour, une icône contour qui devient solide à la sélection), deux bibliothèques d'icônes sur un même écran, emoji utilisé comme icône, badges "NOUVEAU" de remplissage au-dessus des titres, surtitres qui répètent le titre, un mot en italique ou en mono aléatoire dans un titre, étiquettes en mono, surtitres, badges, horodatages ou chiffres (mono majuscule "tech" comme // 01 STATUT), orbes 3D brillants à la place du vrai produit, rangées de cartes de fonctionnalités égales, titres "X, rencontre Y.", bordures de dégradé lumineuses, dégradés indigo vers violet, texte en dégradé, ombres colorées brillantes, le même rayon de 16px partout (rayon intérieur égal au rayon extérieur), boutons en pilule à côté d'entrées arrondies, agrandissement au survol sur les cartes et boutons, ease-in-out 300ms partout, fondu vers le haut au chargement de page, p-6 gap-6 uniforme, cartes dans les cartes, ombre plus bordure plus rayon sur chaque bloc, gris-500 pour tout texte secondaire, emoji dans les titres, et copie comme "Débloquez", "Boostez", "Sans couture" ou "Oups !".
Crédits
Les principes, astuces et techniques d'animation sont paraphrasés et étendus à partir de cinq vidéos courtes de design : "20 Principles of UX & Animation", "10 Niche Design Hacks", "20 Ways to Make Beautiful AI Animations", "10 Niche Typography Hacks" et "20 Ways to Unslop AI Designs". Voir le README pour les crédits.