bompus/hr-better-colors

Farben

Ein Farbsystem besteht aus einer kleinen Menge von Verläufen, die nach ihrer Rolle benannt und gegen die Hintergründe überprüft werden, auf denen sie tatsächlich gerendert werden. Die meisten Farbfehler sind Systemfehler. Ein isoliert ausgewählter Wert, ein Token, der ausgeliehen wurde, weil er richtig aussah, ein Paar, das niemand gemessen hat.

Melden Sie niemals einen Kontrastwert, den Sie nicht gemessen haben, und schätzen Sie niemals eine Farbe, die Sie berechnen könnten. Farben sind eines der wenigen Interface-Probleme, für die es eine exakte Antwort gibt – liefern Sie also die exakte Antwort.

Kontrastanforderungen gehören zu hr-better-accessibility. Oberflächen, Schatten und Symbolfarben liegen außerhalb dieser Fähigkeit.

Stimmen Sie mit dem Farbsystem des Projekts überein

Verwenden Sie die Tokens und die Schreibweise des Projekts weiter. Eine zweite Darstellung, die hinzugefügt wird, um einen Wert zu korrigieren, macht die Palette schwerer nachvollziehbar. Ein konsistentes Hex-System ist besser als Hex mit verstreutem oklch().

Sobald die Tokens existieren, erzwingen Sie sie mit einer Lint-Regel oder einem Guard-Test, der bei einem Farbliteral außerhalb der Token-Dateien fehlschlägt – mit einer kurzen Positivliste für Stellen, die aus Designgründen Rohwerte benötigen. Eine schriftliche „Verwende Tokens“-Regel ohne dahinterstehende Prüfung drifft ab.

Für ein neues System ist oklch() der beste Standard, da sich seine Zahlen so verhalten, wie es die untenstehenden Regeln für Verläufe beschreiben. Überall sonst erzeugt eine Farbbibliothek denselben Verlauf in der Schreibweise des Projekts (color-formats.md).

Ein System sind Verläufe, nicht Farben

Ein neutraler Verlauf, ein Akzentverlauf und nur die Statusverläufe, die das Produkt tatsächlich rendert. Ein warning-Verlauf, den nichts importiert, ist Wartungsaufwand für null Pixel. Ein zweiter Akzentfarbton verdient seinen Platz nur, wenn zwei Dinge auf einen Blick unterscheidbar sein müssen.

Jeder Schritt hat eine Aufgabe

Ein Verlauf ist kein Farbverlauf, aus dem man nach Augenmaß auswählt. Jeder Schritt existiert, weil eine Rolle ihn braucht: Seitenhintergrund, Hover-Zustand eines Elements, Rand, Vollfläche, Textkörper. Erzeugen Sie keinen Schritt, den keine Rolle konsumiert. Sowohl die Tailwind-Konvention 50–950 als auch die Radix-Konvention 1–12 bilden diese Rollen ab (palette-structure.md).

Benennen Sie Primitive nach Farbton, Semantik nach Rolle

Primitive benennen einen Wert (--blue-500) und werden niemals in einer Komponente angewendet. Semantische Tokens benennen eine Aufgabe (--color-text-secondary), verweisen auf ein Primitiv und sind die einzige Ebene, auf die Komponenten zugreifen.

Diese Trennung ermöglicht Theming. Ohne sie muss der Dunkelmodus jede Verwendung prüfen, um herauszufinden, welche den Akzent und welche einfach nur Blau meinte (token-naming.md).

Verwenden Sie ein Token nur in seiner Rolle

Leihen Sie niemals ein Token aus, nur weil sein Wert heute richtig ist. Ein Trennzeichen, das als Textfarbe verwendet wird, funktioniert, bis Rahmen heller werden – und dann wird der Text mit heller. Wenn eine Rolle kein Token hat, fügen Sie das Token hinzu.

Halten Sie den Farbton über den gesamten Verlauf

Vier Eigenschaften definieren einen wohlgeformten Verlauf:

• Die Schritte folgen einer bewussten wahrgenommenen Helligkeitsprogression (palette-generation.md).
• Der Farbton bleibt durchgängig konstant.
• Die Lebendigkeit erreicht ihren Höhepunkt in der Mitte des Verlaufs und fällt an beiden Enden ab.
• Die Schritte liegen am hellen Ende dichter als am dunklen Ende.

Beide Enden stoppen kurz vor reinem Schwarz und Weiß, die überhaupt keinen Farbton tragen können. Verwenden Sie eine Farbbibliothek, anstatt nach Augenmaß zu arbeiten (palette-generation.md).

Eine Farbe, eine Bedeutung

Verwenden Sie eine Farbe für einen einzigen Zweck in der gesamten Oberfläche und behandeln Sie alles innerhalb von 15° Farbtonabweichung als dieselbe Farbe. Wenn der Akzent interaktiv bedeutet, signalisiert dieser Farbton auf statischem Text den Benutzern, auf etwas zu klicken, das nicht klickbar ist, und ein interaktives Element, das neutral gerendert wird, führt ebenso in die Irre. Farbe ist niemals der alleinige Bedeutungsträger – das obliegt hr-better-accessibility.

Füllen Sie genau eine Aktion pro Ansicht

Wenn gefüllte Farbe primäre Betonung codiert, erhält eine primäre Aktion diese Farbe und gleichrangige bleiben neutral. Setzen Sie die Farbe auf den Hintergrund, nicht auf das Label. Ein gefüllter Button lesen Sie von weitem als primär; akzentfarbener Text auf einem neutralen Button wirkt wie ein Link.

Mehrere farbige Hintergründe sind in Ordnung, wenn sie unterschiedliche Zustände oder Kategorien codieren, anstatt als gleichrangige Konkurrenten aufzutreten.

Messen Sie das gerenderte Paar, dann melden Sie

Messen Sie einen Vordergrund gegen den Hintergrund, auf dem er tatsächlich gerendert wird – nicht gegen den Seitenhintergrund. Wenn ein Paar nicht besteht, melden Sie das Paar, seinen gemessenen Wert und den Schwellenwert, den es verfehlt, und lassen Sie die Farben dann in Ruhe. Sie sind eine Designentscheidung. Ändern Sie sie nur, wenn Sie darum gebeten werden, und messen Sie danach erneut (contrast.md).

Wählen Sie einen Interpolationsraum für Verläufe

Der Raum ist eine Frage des Aussehens, nicht der Korrektheit.

• in oklab ist der beste Standard: gleichmäßige Helligkeit, keine Farbton-Überraschungen.
• in oklch wandert um das Farbrad herum, anstatt durch die Mitte zu gehen, bleibt lebendig und durchläuft jeden Farbton zwischen den Stopps. Greifen Sie danach, wenn ein Zweifarbenverlauf in der Mitte grau wird.
• Der sRGB-Standard verdunkelt und dämpft den Mittelpunkt. Er ist das, was die meisten Oberflächen bereits haben, weil er ohne weiteres Zutun entsteht.

Siehe color-usage.md.

Bevor Sie fertig sind

Fehler	Korrektur
Ein Rohwert, wo das Projekt einen Token hat	Token für die Rolle in der Schreibweise des Projekts wiederverwenden oder hinzufügen
Ein isolierter oklch()-Wert in einer Hex-Codebasis	Die etablierte Schreibweise beibehalten, es sei denn, eine Migration ist geplant
Ein Primitiv wie --blue-500, das direkt in einer Komponente verwendet wird	Ein semantisches Token darauf verweisen lassen
Token nach Aussehen (--color-blue-button) oder Ersterwähnung (--color-sidebar-gray) benannt	Nach Rolle benennen: --color-accent-solid, --color-bg-surface
--color-primary bedeutet die Marke und --color-text-primary bedeutet Fließtext	accent für die Marke reservieren; primary = „am prominentesten in seiner Gruppe“
Semantisches Token außerhalb seiner Rolle verwendet (Trennzeichen als Text)	Token für die fehlende Rolle hinzufügen; niemals nach Wert ausleihen
Verlauf durch Variation der HSL-Helligkeit erstellt	Neuaufbau gegen wahrgenommene Helligkeit mit konstantem Farbton
Verlauf gleichmäßig über den gesamten Bereich verteilt	Helles Ende zusammenziehen, bis 50 und 100 wie zwei verschiedene Oberflächen aussehen
Gleicher Sättigungswert, der über Farbtöne hinweg wiederverwendet wird	Den Anteil des jeweiligen Maximums jedes Farbtons verwenden, nicht den Rohwert
Status-Farbton kollidiert mit dem Akzentfarbton	Verschieben, bis zerstörend und primär nebeneinander unterscheidbar sind
Dunkelmodus durch mechanische Umkehrung der Hellpalette erstellt	Als Startpunkt umkehren, dann Lebendigkeit reduzieren, das dunkle Ende verbreitern und jedes Paar erneut prüfen
prefers-color-scheme setzt einige Tokens und eine .dark-Klasse setzt andere	Einen einzigen Wechselmechanismus wählen und durchgängig verwenden
Kontrast durch Änderung des Farbtons behoben	Helligkeit ändern – den Kanal, auf den Kontrast reagiert
P3-Farbe ohne sRGB-Fallback	Zuerst den sRGB-Wert deklarieren, dann innerhalb @media (color-gamut: p3) überschreiben

Berichterstattung

Schweregrad. HIGH macht Inhalte unlesbar oder weist eine irreführende semantische Farbe zu. MEDIUM ist ein auffälliger Theme-, Token- oder Farbraumfehler. LOW ist ein isolierter Feinschliff.

Verifikation. Ohne Browser: Token-Werte, der Farbraum jeder deklarierten Farbe, das Vorhandensein beider Theme-Blöcke und der aus dem deklarierten Token-Paar berechnete Kontrast. Mit Browser: der tatsächlich hinter dem Text gerenderte Hintergrund, einschließlich Deckkraft und eventuell darunterliegender Bilder, gemessen sowohl im Hell- als auch im Dunkelmodus. Ein nicht bestandenes Paar wird gemeldet, nicht übermalt. Melden Sie jede Prüfung, die Sie nicht durchführen konnten, als Nicht verifiziert.

Format. Gruppieren Sie die Ergebnisse unter dem Prinzip, das sie verletzen, geordnet nach Schweregrad, eine Zeile pro Ursache, die jede Fundstelle auflistet:

Schweregrad	Fundstelle	Vorher	Nachher	Grund

Fundstelle ist pfad/zu/datei:zeile. Grund nennt das Prinzip und die Auswirkung auf den Benutzer.

Melden Sie Block (Blockiert), solange ein HIGH besteht, andernfalls Approve (Genehmigen) und lassen Sie den Rest in der Tabelle als zu erledigende Arbeit stehen. Genehmigen Sie niemals eine Abdeckung, die Sie nicht geprüft haben. Falls nichts zu melden ist, geben Sie an: „Keine feststellbaren Farbprobleme“ und melden Sie die Verifikation.