better-colors

カラー

このスキルでは、カラーシステムを構築し、監査します。カラースケールを生成し、各ステップを役割とトークン名に対応付け、表記法を変換し、描画されたコントラストのペアを測定します。

測定していないコントラスト値を報告してはいけません。また、計算できる色を推定してはいけません。表記法、色味を加えたニュートラルカラー、グラデーションの補間色空間はプロジェクトの選択であり、検出結果ではありません。役割の対応付けの誤り、基準を満たさないペア、色域外のステップは検出結果です。以下でいう知覚的な明度はすべて、0 から 1 までの OKLCH L を指します。

ペアが基準を満たす必要があるかどうかは、better-accessibility の対象です。サーフェス、シャドウ、アイコンの色は better-ui の対象です。

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

プロジェクトのトークンと表記法を再利用します。oklch() があちこちに混在するシステムより、一貫した hex システムのほうが優れています。

新しいシステムでは、oklch() が最適なデフォルトです。数値が以下のカラースケールのルールどおりに振る舞うためです。それ以外の場合は、カラ―ライブラリを使えば、プロジェクト独自の表記法で同じカラースケールを生成できます（color-formats.md）。

システムは色ではなくカラースケールで構成する

ニュートラルカラーのカラースケールを1つ、アクセントカラーのカラースケールを1つ、そしてプロダクトで実際に描画するステータスカラーのカラースケールだけを用意します。どこからもインポートされない warning カラースケールは、ピクセルをひとつも変えない保守作業を生みます。ひと目で区別しなければならないものが2つある場合に限り、2つ目のアクセントカラーの色相を追加します。それ以外の場合は、1つのアクセントカラーのカラースケールのステップを増やします。

すべてのステップに役割を持たせる

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

プリミティブには色相、セマンティックトークンには役割を名前として付ける

プリミティブは値（--blue-600）を表し、コンポーネントには決して適用しません。セマンティックトークンは役割（--color-text-secondary）を表し、プリミティブを参照します。コンポーネントが参照するのは、この層だけです。この境界があるからこそ、コンポーネントに手を加えずにテーマの色を付け替えられます（token-naming.md）。

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

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

カラースケール全体で色相を維持する

カラースケールは最初から最後まで同じ色相を保ち、中間で最も鮮やかになり、明るい側ではより細かいステップになります。見た目で調整せず、カラ―ライブラリで生成します（palette-generation.md）。

1色につき1つの意味

インターフェース全体で、色は1つの目的にのみ使います。OKLCH 色相が 15° 以内のものは同じ色として扱います（color-usage.md）。意味を伝える手段として色だけに頼ってはいけません。アイコンまたはラベルと組み合わせます。これは better-accessibility の対象です。

ビューごとに塗りつぶし色を使うアクションは1つだけにする

塗りつぶし色で主要な強調を示す場合は、主要アクション1つだけに使用し、同列のアクションはニュートラルカラーのままにします。色はラベルではなく背景に使います。塗りつぶしボタンは離れたところからでも主要アクションだと分かりますが、ニュートラルカラーのボタンにアクセントカラーのテキストを使うと、リンクのように見えます。

すでに別の方法で強調を示している階層は維持します。色付きの背景を複数使ってもかまいません。ただし、同列の要素同士を競わせるのではなく、異なる状態やカテゴリを表す場合に限ります。

描画されたペアを測定してから報告する

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

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

色空間は見た目を決めるものであり、正しさを左右する設定ではありません。デフォルトは in oklab とし、色相の異なる2色のグラデーションが中間で灰色になる場合は in oklch を使います（color-usage.md）。

完了前の確認

パターン	修正
トークンが存在するのに、コンポーネントファイルで16進数、rgb( または oklch( の値が使われている	プロジェクトの表記法に従って、ロールトークンを再利用するか追加します
それ以外は16進数で記述されているコードベースに、oklch( の値が1つある	移行が対象範囲でない限り、既存の表記法に合わせます
コンポーネントファイルで var(--blue-600) または bg-blue-600 が使われている	セマンティックトークンをプリミティブに割り当てて、それを使います
--color-blue-button や --color-sidebar-gray のように、色相またはコンポーネント名を含むセマンティック名	--color-accent-solid、--color-bg-surface のように、役割に応じた名前に変更します
--color-primary と --color-text-primary の両方が定義されている	ブランドトークンを accent に変更します
color: 内に border または separator トークンがある、または background: 内に text トークンがある	不足している役割のトークンを追加します
明度だけが異なる hsl( のランプ値	プロジェクトの表記法に従って、知覚上の色相を一定にして再構築します
50～200 のステップ間の OKLCH L の差が、ランプ中間部のステップ間の差と同程度に大きい	明度の低い側を、ステップあたり約 0.04～0.05 に調整します
すべての色相のランプに同じ彩度またはクロマの値が使われている	それぞれの色相の最大値に対する同じ比率を使います
ステータス色相がアクセント色相から 15° 以内にある	少なくとも 15° 離すか、破壊的なアクションに異なるスタイルを与えます
ダークトークンがライトランプのステップ順を逆にしただけになっている	アクセントのクロマを下げ、暗い側の幅を広げ、すべてのペアを再測定します
prefers-color-scheme と .dark クラスの両方で色トークンが設定されている	切り替え方法を1つ選び、一貫して使います
色相を変えて明度をそのままにするコントラスト修正	チャネルコントラストが反応する明度を変更します
prefers-contrast: more で、1つのブロック内の両方の表示モードの色を上書きしている	表示モードごとに、コントラストを高めた値を設定します
/50、rgba(、transparent を使った color-mix( など、アルファ値を含む色の上にテキストがある	描画結果を測定するか、不透明なトークンを使います
Tailwind の 500 の塗りつぶし色に text-white が使われている	測定します。多くの 500 色では白とのコントラストが 4.5:1 を満たさないため、塗りつぶし色を 600 に変更します
sRGB の値が事前に宣言されていないのに、sRGB の範囲を超えるクロマの oklch() が使われている	先に sRGB の値を宣言し、続いて @media (color-gamut: p3) 内に鮮やかな色の値を宣言します

報告

重大度。 HIGH は、コンテンツを読めなくするか、誤解を招くセマンティックカラーを割り当てる問題です。MEDIUM は、テーマ、トークン、または色域に関する、目立つ不具合です。LOW は、局所的な仕上げの問題です。

表示箇所にかかわらず、3つの症状がひと目で HIGH に該当します。これは better-interface の重大度引き上げ条件に一致します。描画結果のコントラスト比が必要な比率を満たさない本文またはコントロールのテキスト、状態や意味を色だけで表していること、そして意味に反したセマンティックカラーの使用です。

検証。 ブラウザーを使わない場合は、トークン値、宣言されているすべての色の色域、両方のテーマブロックの有無、宣言されたトークンペアから算出したコントラストを確認します。ブラウザーを使う場合は、不透明度や背後の画像も含めてテキストの背後に実際に描画される背景を、ライトとダークの両方で測定します。実行できなかった確認はすべて Not verified と報告します。

形式。 指摘事項は、違反している原則ごとにまとめ、重大度順に並べます。根本原因ごとに1行とし、該当する場所をすべて記載します。

重大度	場所	変更前	変更後	理由

場所 は path/to/file:line の形式です。理由 には原則とユーザーへの影響を記載します。

HIGH が1件でも残る場合は最後に Block、それ以外は Approve と記載し、残りの作業は表に残します。確認していない範囲について Approve と判断してはいけません。報告事項がない場合は、「対応が必要な色の指摘事項はありません」と記載し、検証結果を報告します。