bompus/hr-better-colors

Couleurs

Un système de couleurs est un petit ensemble de rampes, nommées par rôle et vérifiées par rapport aux fonds sur lesquels elles s'affichent réellement. La plupart des bugs de couleur sont des bugs système. Une valeur choisie isolément, un jeton emprunté parce qu'il semblait correct, une paire que personne n'a mesurée.

Ne signalez jamais une valeur de contraste que vous n'avez pas mesurée, et n'estimez jamais une couleur que vous pourriez calculer. Les couleurs sont l'une des rares préoccupations d'interface pour lesquelles il existe une réponse exacte, alors fournissez la réponse exacte.

Les exigences de contraste appartiennent à hr-better-accessibility. Les surfaces, les ombres et les couleurs d'icônes sont en dehors de cette compétence.

Adaptez-vous au système de couleurs du projet

Réutilisez les jetons et la notation du projet. Une deuxième représentation ajoutée pour corriger une valeur rend la palette plus difficile à raisonner. Un système hexadécimal cohérent est préférable à un système hexadécimal parsemé d'oklch().

Une fois que les jetons existent, appliquez-les avec une règle de lint ou un test de garde qui échoue sur un littéral de couleur en dehors des fichiers de jetons, avec une courte liste blanche pour les endroits qui ont besoin de valeurs brutes par conception. Une règle "utiliser les jetons" écrite sans vérification derrière dérive.

Pour un nouveau système, oklch() est le meilleur choix par défaut, car ses nombres se comportent comme les règles de rampe ci-dessous le décrivent. Partout ailleurs, une bibliothèque de couleurs produit la même rampe dans la notation du projet (color-formats.md).

Un système est constitué de rampes, pas de couleurs

Une rampe neutre, une rampe d'accentuation et seulement les rampes de statut que le produit affiche réellement. Une rampe warning que rien n'importe est une maintenance pour zéro pixel. Une deuxième teinte d'accentuation gagne sa place uniquement lorsque deux choses doivent être distinguables au premier coup d'œil.

Chaque étape a un emploi

Une rampe n'est pas un dégradé pour choisir à l'œil. Chaque étape existe parce qu'un rôle en a besoin : fond de page, survol de composant, bordure, remplissage solide, texte du corps. Ne générez pas d'étape qu'aucun rôle ne consomme. Les conventions Tailwind 50–950 et Radix 1–12 correspondent à ces rôles (palette-structure.md).

Nommez les primitives par teinte, les sémantiques par rôle

Les primitives nomment une valeur (--blue-500) et ne sont jamais appliquées dans un composant. Les jetons sémantiques nomment un emploi (--color-text-secondary), pointent vers une primitive et sont le seul niveau que les composants référencent.

Cette séparation est ce qui rend le thème possible. Sans elle, le mode sombre implique d'auditer chaque utilisation pour déterminer laquelle signifiait "l'accentuation" et laquelle voulait simplement du bleu (token-naming.md).

Utilisez un jeton uniquement dans son rôle

N'empruntez jamais un jeton parce que sa valeur est correcte aujourd'hui. Un séparateur utilisé comme couleur de texte fonctionne jusqu'à ce que les bordures deviennent plus claires, puis le texte les suit. Si un rôle n'a pas de jeton, ajoutez le jeton.

Maintenez la teinte sur toute la rampe

Quatre propriétés définissent une rampe bien formée :

• Les étapes suivent une progression de luminosité perçue délibérée (palette-generation.md).
• La teinte reste constante d'un bout à l'autre.
• La vivacité atteint son maximum au milieu de la rampe et diminue aux deux extrémités.
• Les étapes sont plus denses à l'extrémité claire qu'à l'extrémité sombre.

Les deux extrémités s'arrêtent avant le noir et le blanc purs, qui ne peuvent pas du tout porter de teinte. Utilisez une bibliothèque de couleurs plutôt que d'estimer à l'œil (palette-generation.md).

Une couleur, une signification

Utilisez une couleur dans un seul but sur toute l'interface, en traitant tout ce qui se trouve à moins de 15° de teinte comme la même couleur. Si l'accentuation signifie interactif, cette teinte sur un texte statique indique aux utilisateurs de cliquer sur quelque chose qui n'est pas cliquable, et un élément interactif rendu neutre induit tout autant en erreur. La couleur n'est jamais le seul porteur de sens, ce qui relève de hr-better-accessibility.

Remplissez exactement une action par vue

Lorsque la couleur de remplissage code l'importance primaire, une action primaire la reçoit et les homologues restent neutres. Mettez la couleur sur le fond, pas sur le libellé. Un bouton rempli se lit comme primaire à travers la pièce ; un texte de couleur d'accentuation sur un bouton neutre se lit comme un lien.

Plusieurs fonds colorés sont acceptables lorsqu'ils codent des états ou des catégories distincts plutôt que de rivaliser en tant qu'homologues.

Mesurez la paire rendue, puis signalez

Mesurez un premier plan par rapport au fond sur lequel il s'affiche réellement, pas par rapport au fond de la page. Lorsqu'une paire échoue, signalez la paire, sa valeur mesurée et le seuil qu'elle manque, puis laissez les couleurs tranquilles. C'est une décision de conception. Modifiez-les uniquement lorsqu'on vous le demande, et mesurez à nouveau après (contrast.md).

Choisissez un espace d'interpolation pour les dégradés

L'espace est un aspect, pas un réglage de correction.

• in oklab est le meilleur choix par défaut : luminosité uniforme, pas de surprise de teinte.
• in oklch parcourt la roue chromatique plutôt que de passer par le milieu, restant vif et balayant chaque teinte entre les arrêts. Utilisez-le lorsqu'un dégradé à deux teintes devient gris au milieu.
• La valeur par défaut sRGB assombrit et atténue le point médian. C'est ce que la plupart des interfaces ont déjà, car c'est ce que vous obtenez sans rien demander.

Voir color-usage.md.

Avant de terminer

Erreur	Correction
Une valeur brute là où le projet a un jeton	Réutilisez ou ajoutez le jeton de rôle, dans la notation du projet
Une valeur oklch() isolée insérée dans une base de code hexadécimale	Conservez la notation établie à moins qu'une migration ne soit prévue
Une primitive comme --blue-500 utilisée directement dans un composant	Pointez un jeton sémantique vers elle
Jeton nommé pour son apparence (--color-blue-button) ou sa première utilisation (--color-sidebar-gray)	Nommez-le pour son rôle : --color-accent-solid, --color-bg-surface
--color-primary signifiant la marque et --color-text-primary signifiant le texte du corps	Réservez accent pour la marque ; laissez primary signifier "le plus important de son groupe"
Jeton sémantique utilisé en dehors de son rôle (séparateur comme texte)	Ajoutez un jeton pour le rôle manquant ; n'empruntez jamais par valeur
Rampe construite en faisant varier la luminosité HSL	Reconstruisez en fonction de la luminosité perçue avec une teinte constante
Rampe espacée uniformément sur toute la plage	Resserrer l'extrémité claire jusqu'à ce que 50 et 100 se lisent comme deux surfaces
Même nombre de saturation réutilisé sur toutes les teintes	Faites correspondre la proportion du maximum de chaque teinte, pas la valeur brute
Teinte de statut qui entre en collision avec la teinte d'accentuation	Déplacez-la jusqu'à ce que destructif et primaire se lisent distinctement côte à côte
Mode sombre réalisé en inversant mécaniquement la palette claire	Inversez comme point de départ, puis réduisez la vivacité, élargissez l'extrémité sombre et revérifiez chaque paire
prefers-color-scheme définissant certains jetons et une classe .dark en définissant d'autres	Choisissez un mécanisme de commutation et utilisez-le partout
Contraste corrigé en changeant la teinte	Changez la luminosité, le canal auquel le contraste répond
Couleur P3 sans solution de repli sRGB	Déclarez d'abord la valeur sRGB, puis remplacez-la dans @media (color-gamut: p3)

Rapports

Gravité. HIGH rend le contenu illisible ou attribue une couleur sémantique trompeuse. MEDIUM est un échec notable de thème, de jeton ou de gamut. LOW est un problème d'ajustement isolé.

Vérification. Sans navigateur : valeurs des jetons, le gamut de chaque couleur déclarée, les deux blocs de thème présents et le contraste calculé à partir de la paire de jetons déclarée. Avec un navigateur : le fond réellement affiché derrière le texte, y compris l'opacité et toute image en dessous, mesuré en mode clair et sombre. Une paire défaillante est signalée, pas repeinte. Signalez chaque vérification que vous n'avez pas pu effectuer comme Non vérifié.

Format. Regroupez les conclusions sous le principe qu'elles violent, classées par gravité, une ligne par cause racine listant chaque emplacement où elle apparaît :

Gravité	Emplacement	Avant	Après	Pourquoi

Emplacement est chemin/vers/fichier:ligne. Pourquoi nomme le principe et l'impact utilisateur.

Signalez Bloqué lorsque tout HIGH persiste, Approuvé sinon, en laissant le reste dans le tableau comme travail à faire. N'approuvez jamais une couverture que vous n'avez pas inspectée. S'il n'y a rien à signaler, indiquez "Aucun résultat de couleur exploitable" et signalez la vérification.