better-colors

色

カラーシステムとは、役割ごとに名前を付けた少数の色の段階を一貫して適用し、実際に表示される背景に対して検証したものです。色に関する問題のほとんどは、システムに関する問題です。単独で選んだ値、見た目がよかったから借用したトークン、あるいは誰も測定していない色の組み合わせが原因です。コントラスト要件は better-accessibility、サーフェス、シャドウ、アイコンの色は better-ui の担当です。

クイックリファレンス

カテゴリー	用途	リファレンス
構造	システムに必要な色の段階、各ステップの役割、ニュートラルカラー、ステータスカラー、既存パレットの監査	palette-structure.md
生成	ブランドカラーを基にした色の段階の作成、複数の色相を使うシステム、ダークモード	palette-generation.md
命名	プリミティブ層とセマンティック層、役割の一覧、命名規則、アンチパターン	token-naming.md
使用方法	色ごとに意味をひとつにすること、強調、グラデーション、文化、外観のバリエーション	color-usage.md
コントラスト	APCA と WCAG によるチェック、失敗の報告、依頼に応じた修正	contrast.md
形式	表記法の選択、変換、色域と P3 のフォールバック	color-formats.md
レビュー出力形式	重大度スケール、指摘事項の表、検証、判定	review-output.md

基本原則

1. プロジェクトのカラーシステムに合わせる

プロジェクトに既存のトークンと表記法があれば、それを再利用します。ひとつの値を修正するために別の色表現を導入すると、パレットの理解は容易になるどころか難しくなります。oklch() が散在する 16 進数表記のシステムより、一貫した 16 進数表記のシステムのほうが優れています。表記法自体は問題ではありません。まったく新しいシステムを作る場合は、oklch() が最適なデフォルトです。数値の振る舞いが、以下で説明する色の段階のルールに合っているためです。それ以外の場合は、プロジェクトで使われている表記法にかかわらず、同じ色の段階を生成できるカラーライブラリを使います（color-formats.md）。

2. システムとは色の集まりではなく、色の段階です

ニュートラルカラーの段階をひとつ、アクセントカラーの段階をひとつ用意し、ステータスカラーの段階は、プロダクトで実際に表示するものだけにします。どこからも読み込まれない warning の段階は、ピクセルをひとつも生まないのにメンテナンスが必要です。ふたつ目のアクセントカラーの色相を加えるのは、ひと目で区別すべきものがふたつある場合に限ります。

3. 各ステップには役割があります

色の段階は、見た目で選ぶためのグラデーションではありません。各ステップは、ページ背景、コンポーネントのホバー、境界線、塗りつぶし、本文テキストなど、必要な役割があるから存在します。どの役割にも使われないステップは生成しないでください。Tailwind の 50–950 と Radix の 1–12 の慣例は、どちらもこれらの役割に対応しています（palette-structure.md）。

4. プリミティブには色相、セマンティックトークンには役割を付ける

プリミティブは値を表す名前（--blue-500）を持ち、コンポーネントには適用しません。セマンティックトークンは役割を表す名前（--color-text-secondary）を持ち、プリミティブを参照します。コンポーネントが参照するのはこの層だけです。この境界があるからテーマを設定できます。境界がなければ、ダークモードへの対応時に、どの用途が「アクセントカラー」を意味し、どの用途が単に青を必要としていたのか、すべての使用箇所を監査しなければなりません（token-naming.md）。

5. トークンはその役割にのみ使う

値が今は適切だからといって、別の役割のトークンを流用しないでください。区切り線用の色をテキストに使うと、境界線を薄くしたときにテキストも一緒に薄くなってしまいます。役割に対応するトークンがなければ、そのトークンを追加してください。

6. 色の段階全体で色相を保つ

ステップは 知覚上の 明るさが均等に変化し、色相は最初から最後まで一定に保たれます。鮮やかさは中間のステップで最大になり、両端に向かって低下します。また、ステップは暗い側より明るい側に密に配置します。両端は純粋な黒と白を避けます。純粋な黒と白には色相を持たせられないためです。目視で選ぶのではなく、カラーライブラリを使ってください（palette-generation.md）。

7. 1 色に 1 つの意味を持たせる

インターフェース全体で、1 色は 1 つの目的にのみ使用します。色相が 15° 以内のものは、同じ色として扱います。アクセントカラーがインタラクティブ要素を意味する場合、その色を静的なテキストに使うと、クリックできないものをクリックするようユーザーに促してしまいます。インタラクティブ要素をニュートラルカラーで表示するのも、同様に誤解を招きます。意味を伝える手段を色だけに頼ることは決してありません。この要件は better-accessibility が担います。

8. 1 つのビューにつき、塗りつぶしは 1 つのアクションだけに使う

塗りつぶしカラーで主要な強調を表す場合、主要なアクション 1 つにのみ使い、同列のアクションはニュートラルカラーのままにします。色はラベルではなく背景に使います。塗りつぶしボタンは離れた場所から見ても主要なアクションとして伝わりますが、ニュートラルなボタン上のアクセントカラーのテキストはリンクのように見えます。複数の色付き背景を使う場合も、同列の要素同士で競合させるのではなく、異なる状態やカテゴリを表すのであれば問題ありません。

9. 実際に描画されるペアを測定してから、結果を報告する

前景色はページ背景ではなく、実際に描画される背景色との組み合わせで測定します。ペアが基準を満たさない場合は、そのペア、測定値、および満たしていないしきい値を報告し、色はそのままにします。プロジェクトの色はデザイン上の判断です。依頼された場合にのみ変更し、変更後に再測定します（contrast.md）。

10. グラデーションの補間空間を選ぶ

補間空間は見た目を決めるものであり、正しさの設定ではありません。in oklab は最適なデフォルトです。明るさが均一で、色相に予想外の変化がありません。in oklch は中間を通るのではなく色相環に沿って進むため、鮮やかさを保ったままストップ間の色相を巡ります。独特の見た目を生み出し、2 色相のグラデーションの中間がグレーになる場合の解決策になります。sRGB のデフォルトは定番の見た目で、暗くくすんだ中間色は、すでに多くのインターフェースで見られるものです（color-usage.md）。

よくある間違い

間違い	修正方法
プロジェクトにトークンがあるのに、生の値を使う	プロジェクトで既存の表記法に従い、適切なロールトークンを再利用するか追加します
16 進コードを使うコードベースに、単独の oklch() 値を追加する	色システムの移行が対象範囲でない限り、既存の表記法を維持します
コンポーネントで --blue-500 のようなプリミティブを直接使う	セマンティックトークンからその値を参照し、そのトークンを使います
見た目（--color-blue-button）や最初の用途（--color-sidebar-gray）にちなんだトークン名を付ける	役割に基づいて名前を付けます。例：--color-accent-solid、--color-bg-surface
--color-primary がブランドを意味し、--color-text-primary が本文テキストを意味する	ブランドには accent を使い、primary は「同じグループ内で最も目立つもの」を意味するようにします
セマンティックトークンを本来の役割以外で使う（区切り線の色をテキストに使うなど）	不足している役割のトークンを追加します。値だけを理由に別のトークンを流用してはいけません
HSL の明度を変えてランプを作る	色相を一定に保ち、知覚される明るさに基づいて作り直します
ランプを全範囲に均等に配置する	明るい側の間隔を詰めます。50 と 100 は、2 つのサーフェスとして見分けられる必要があります
色相が異なる色に同じ彩度の数値を再利用する	生の値ではなく、各色相固有の最大値に対する同じ比率に合わせます
アクセントカラーと競合する色相をステータスに使う	破壊的アクションと主要なアクションを並べて見たときに区別できるまで色相を移動します
ライトパレットを機械的に反転してダークモードを作る	反転を出発点とし、鮮やかさを抑え、暗い側の幅を広げ、すべてのペアを再確認します
prefers-color-scheme で一部のトークンを設定し、.dark クラスで別のトークンを設定する	切り替えの仕組みを 1 つ選び、全体で統一して使います
コントラストが基準を満たさない	そのペア、測定値、満たしていないしきい値を報告します。色の変更は依頼された場合にのみ行います
色相を変えてコントラストを修正する	コントラストが反応するチャンネルである明度を変えます
sRGB のフォールバックがない P3 カラー	まず sRGB の値を宣言し、その後 @media (color-gamut: p3) 内で上書きします
反対の色相間のグラデーションが中間でグレーになる	極座標系（in oklch）に切り替えるか、2 色相の中間の色相で中間ストップを追加します
ライトモードでしかパレットを検証しない	どちらの表示モードでも、前景色と背景色のすべてのペアを再確認します

報告

すべての確認済みの指摘事項が、検証結果と判定を添えてreview-output.mdに記載されると、単独の色レビューは完了です。better-interfaceでは、代わりにそのフォーマットが適用されます。