mcpField
C
color-contrast

color-contrast

github.com/mgiffordデザイン・UI57195 回インストール6 週間前に更新
リポジトリ

color-contrast について

color-contrast は、HTML、CSS、SVG などの色を実装・レビューする人向けのアクセシビリティスキルです。テキストやコンポーネントの状態、テーマ、強制カラー表示を扱い、色だけで情報を伝えないよう促します。

主な機能

  1. 01テキストのコントラスト要件
  2. 02非テキスト要素のコントラスト
  3. 03色だけに依存した情報伝達の回避
  4. 04強制カラー表示への対応
  5. 05テーマと状態の検証

活用シーン

  1. 01ライト・ダークテーマの文字コントラスト確認
  2. 02アイコン、コントロール、フォーカス状態の検証
  3. 03チャートや状態表示の色依存をレビュー

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mgifford/accessibility-skills --skill color-contrast

インストール後、Claude Code で/color-contrastを入力して読み込まれたか確認します。

同梱ファイルSYNC.md

詳細

色のコントラストに関するアクセシビリティスキル

正規のソース：mgifford/ACCESSIBILITY.md 内の examples/COLOR_CONTRAST_ACCESSIBILITY_BEST_PRACTICES.md このスキルはそのファイルに基づいています。判断に迷った場合は、そちらの例を優先してください。

HTML、CSS、SVG、またはあらゆるビジュアルインターフェース要素で色を選択、実装、またはレビューする際は、常にこれらのルールを適用してください。

基本方針

前景色と背景色のコントラストが十分であることは、ユーザーがテキストを読み、UI コンポーネントを識別し、グラフィックコンテンツを認識し、キーボードフォーカスを追跡するための前提条件です。**情報を伝える手段として、色だけを決して使用しないでください。**コントラストは、不透明度、グラデーション、画像、オーバーレイ、状態、テーマを適用した後に実際に隣接する色によって決まります。パレットが基準を満たしていても、完成したインターフェースが基準を満たすとは限りません。

情報を伝える、またはユーザーの操作を必要とするすべてのビジュアルインターフェース要素は、ライトモード、ダークモード、強制カラー（ハイコントラスト）モードで WCAG 2.2 レベル AA のコントラスト基準を満たす必要があります。

重大度の基準（このスキル）

レベル意味
Criticalコントラストの不備により、コンテンツまたは操作が完全に利用できなくなる
Seriousコントラストの不備により、障害のあるユーザーグループの利用が大きく妨げられる
Moderateコントラストの問題によりユーザビリティが低下するが、コンテンツは部分的に利用できる
Minorベストプラクティスからの逸脱。影響はわずか

時間が限られている場合は、ユーザーへの影響に応じて優先順位を付けてください。（1）タスクの完了に必要なテキスト／コントロール、（2）キーボードフォーカスインジケーターとコンポーネントの状態、（3）エラー／警告／必須フィールド／ステータスメッセージ、（4）ナビゲーション／リンク／ラベル、（5）グラフと情報を伝えるグラフィック、（6）補助的／二次的なコンテンツ。

重大：テキストのコントラスト（WCAG 1.4.3）

テキストの種類最小値（AA）強化基準（AAA）
通常のテキスト（18pt 未満／太字 14pt 未満）4.5:17:1
大きなテキスト（18pt 以上、または太字 14pt 以上）3:14.5:1
ロゴタイプ／純粋に装飾的なテキスト適用除外適用除外
無効化されたコントロール適用除外適用除外

**「大きなテキスト」**とは、通常の太さで 18pt（約 24 CSS px）以上、または太字で 14pt（約 18.67 CSS px）以上のテキストを指します。WCAG の基準は合格か不合格かで判定されます。4.499:1 を 4.5:1 に切り上げないでください。細い書体や特殊な書体には慎重に対応してください。計算上の基準を満たしていても、線が細いために読みにくい場合があります。

この要件は、本文、見出し、リンクテキスト、ボタン／フォームのラベル、プレースホルダーテキスト、ホバー／フォーカス時に表示されるテキスト、検証／ステータスメッセージ、画像として描画されたテキストに適用されます。ロゴタイプ／装飾に対する適用除外を、通常のコンテンツに使われるブランドカラーにまで広げないでください。

CSS で前景色または背景色の一方しか指定されていない場合、もう一方はユーザーの設定によって不明になる可能性があります。色の組み合わせは必ず両方の色を指定してください。

html { background: #ffffff; color: #1b1f23; }
.notice { background: #f2f6fa; color: #243447; }

/* Bad — fails 1.4.3 */
.placeholder { color: #aaaaaa; }
.note { color: #888; }

テキストの画像ではなく、実際のテキストを優先してください（WCAG 1.4.5）。実際のテキストは再配置、サイズ変更、テーマへの適応が可能です。テキストの画像は、表示方法をカスタマイズできる場合、またはそれが不可欠な場合に限り使用してください。

重大：テキスト以外のコントラスト（WCAG 1.4.11）

UI コンポーネントやその状態を識別するために必要な視覚情報と、グラフィックを理解するために必要な部分には、隣接する色との間に3:1 のコントラストが必要です。例：コントロールを識別するチェックボックスの境界、チェック済みの状態を示すチェックマーク、アイコンのみのボタン内のアイコン、スライダーのつまみ／トラック、エラーの境界、読み取りに必要なグラフの線／領域／記号。

これは、装飾的な境界線すべてに 3:1 が必要だという意味ではありません。テキスト、形状、位置、または別の表現ですでにコンポーネント／状態を識別できる場合、コントラストの低い装飾的な境界線は必ずしも必要な情報ではありません。純粋に装飾的なグラフィック、非アクティブ／無効化されたコンポーネント、ロゴ／ブランドマーク、または隣接するテキストを補足するグラフィックには適用されません。

ネイティブコントロールは有力なデフォルトの選択肢です。ブラウザー／OS がユーザーの設定に合わせて調整してくれますが、置き換える場合は、あらゆる状態とモードに対応する責任が生じます。

.checkbox {
  appearance: none;
  inline-size: 1.25rem;
  block-size: 1.25rem;
  border: 2px solid #59636e; /* test against surrounding background */
  border-radius: 0.2rem;
}
.checkbox:checked {
  border-color: #005ea8;
  background-color: #005ea8;
}

未チェック状態の境界線と背景、チェック済み状態の塗りと周囲の背景、さらにチェックマークとチェック済み状態の塗りとのコントラストを測定してください。コードコメントでコントラストが基準を満たすと主張するだけでは不十分です。実際にレンダリングされた組み合わせを測定してください。アイコンの線には currentColor を使うと、ボタンのテキスト色に合わせて変化します。

重大：色の使用（WCAG 1.4.1）

色だけを、情報の伝達、応答の促し、または要素の区別の唯一の手段にしてはいけません。色が意味を担う場合は、視認できるテキスト、形状、パターン、アイコン、またはその他の色以外の手がかりを追加してください。


<label style="color: red;">Email address</label>
<input type="email" style="border-color: red;">


<div class="field" data-state="error">
  <label for="email">Email address <span aria-hidden="true">(required)</span></label>
  <input id="email" type="email" required aria-invalid="true" aria-describedby="email-error">
  <p id="email-error" class="error-message">
    <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">
      <path d="M12 3 2 21h20L12 3Zm0 6v5m0 3v.01"></path>
    </svg>
    Enter an email address in the format [email protected].
  </p>
</div>

本文中のリンクは、色以外の方法でも周囲のテキストと区別できる必要があります。下線を付けるのが最もシンプルで信頼できる方法です。

a {
  color: #005ea8;
  text-decoration-line: underline;
  text-decoration-thickness: max(1px, 0.08em);
}

文書化された例外（WCAG 手法 G183）では、リンクテキストが周囲のテキストと 3:1 以上のコントラストを持ち、ホバー／フォーカス時に色以外の手がかりが加わる場合、デフォルトで下線のないリンクが認められます。これは維持が難しいため、文章では常に下線を付ける方法を推奨します。グラフ／状態インジケーターには、色に加えてラベル、記号、線のスタイル、またはパターンが必要です。別途、テキスト相当の表を用意しても、グラフィック自体のコントラスト要件が免除されるわけではありません。

重大：キーボードフォーカスの表示

WCAG 2.2 AA では、視認できるフォーカスインジケーターが必須です（2.4.7）。2.4.13 フォーカスの表示はレベル AAAです。面積／コントラスト変化の計算式を AA の要件として提示しないでください。作成者が用意したフォーカスインジケーターは、フォーカス状態を識別する視覚情報として、引き続き WCAG 1.4.11 の対象となる場合があります。

/* Start with the browser default; don't remove without a tested replacement */
:focus-visible {
  outline: 3px solid #005fcc;
  outline-offset: 3px;
}

/* Two-color indicator — more robust across light/dark surfaces */
:focus-visible {
  outline: 3px solid #ffffff;
  outline-offset: 2px;
  box-shadow: 0 0 0 5px #111111;
}
@media (forced-colors: active) {
  :focus-visible {
    outline: 3px solid Highlight;
    box-shadow: none;
  }
}

/* NEVER do this without a tested replacement */
:focus { outline: none; }

:focus:not(:focus-visible) { outline: none; } を普遍的なルールとして追加しないでください。ブラウザーは :focus-visible が一致するタイミングをすでに判断しており、一律に無効化するとリスクがあります。あらゆるサーフェスとコンポーネントの状態で、インジケーターの形状、クリッピング、隣接する色をテストしてください。

重大：強制カラーのモード

Windows のハイコントラストモード／forced-colors は、作成者が指定した色をシステムカラーに置き換えます。background-color、box-shadow、または color だけで意味を伝えていると、インターフェースが機能しなくなることがあります。outline は強制カラーでも維持されますが、box-shadow は抑制される場合があります。

@media (forced-colors: active) {
  .status-icon, .icon-button svg { fill: none; stroke: currentColor; }
  [aria-current="page"] { border-block-end: 0.25rem solid currentColor; }
  [aria-invalid="true"] { border: 3px solid Mark; }
}

まずネイティブコントロールとセマンティック HTML を使い、テストで情報が失われると確認された箇所に限り、対象を絞って修正を加えてください。作成者が指定した色を維持することが不可欠であり、ユーザーが選択した複数のシステム配色でテスト済みの場合を除き、forced-color-adjust: none は避けてください。この設定を使うと、その要素はモードによる保護の対象外になります。

テスト方法： アクセシビリティ設定で Windows のハイコントラストを有効にします。Chrome DevTools → Rendering → 「Emulate CSS media feature forced-colors: active」を選択します。Firefox では about:config → ui.forcedColors: 1 を設定します。

中程度：テーマとセマンティックカラーのトークン

単独の色ではなく、前景色と背景色の組み合わせを検証してください。セマンティックトークンを使うと、意図した組み合わせを明示できます。

:root {
  color-scheme: light dark;
  --surface: light-dark(#ffffff, #15191e);
  --text: light-dark(#1b1f23, #f4f6f8);
  --link: light-dark(#005ea8, #73b7f2);
  --control-border: light-dark(#59636e, #a7b0ba);
}
html { background: var(--surface); color: var(--text); }
.card { background: var(--surface); color: var(--text); border: 1px solid var(--control-border); }

プロジェクトのブラウザーサポート方針で許可されている場合は、light-dark() が便利です。古いブラウザー向けにカスタムプロパティのフォールバックを用意してください。手動でテーマセレクターを実装する方法については、skills/light-dark-mode/SKILL.md を参照してください。

CSS の色関数がアクセシビリティを保証すると考えてはいけません — color-mix() は 2 つの入力色の中間色を生成しますが、WCAG の比率を目標にしていません。現在の実装で contrast-color() が選ぶ色は限られており、テキスト／コンポーネント／状態の要件を検証する代わりにはなりません。どちらも適合性テストではなく、実装を補助する手段として扱ってください。

/* Bad: hard-coded value that may fail in dark mode */
.card { background-color: #ffffff; color: #333; }

重大：可変の背景、不透明度、オーバーレイ

グラデーション、画像、動画、半透明のサーフェス上にテキストを表示する場合は、通常の使用で発生し得る描画領域のうち、最も条件の悪い箇所をテストしてください。背後のコンテンツを制御できない場合は、不透明または十分に不透明な背景サーフェスを使用してください。

.hero-title {
  display: inline;
  padding: 0.15em 0.35em;
  color: #ffffff;
  background: #16202a;
  box-decoration-break: clone;
}

親要素の opacity には注意してください。テキストと背景がコンポーネントの背後にあるものと合成され、コントラストを構成する両方の色が変わります。

/* Avoid: reduces opacity of the whole component */
.secondary-card { opacity: 0.6; }
/* Prefer: explicit, validated colors */
.secondary-card { background: #f2f6fa; color: #4d5966; }

自動化ツールで、可変の背景が「未完了」と報告される場合があります。これはテストの制限であり、コンテンツが適合している証拠ではありません。

中程度：個別に検証が必要な状態

ユーザーが遭遇する可能性のあるすべての状態で、各コンポーネントを確認してください。通常、ホバー、キーボードフォーカス、アクティブ／押下中、選択済み／チェック済み、訪問済み、無効／エラー、成功／警告／情報、無効化／非アクティブ、ブラウザーの自動入力、テキスト選択、開いている／展開済み／現在の状態を確認します。サポートするすべてのテーマで繰り返してください。

無効化されたコントロールは、1.4.3／1.4.11 の特定の比率の対象外です。ただし、この例外をデザイン目標にしてはいけません。可能な場合は無効化されたコントロールを識別できるようにし、色だけで無効な状態を伝えないでください。必要に応じて、コントロールを利用できない理由を説明してください。そもそも無効化が必要かどうかも検討してください（理由が説明されないボタンを利用不可にするより、送信時に明確な検証結果を示すほうが理解しやすい場合があります）。

<button type="submit" disabled aria-describedby="submit-help">Submit</button>
<p id="submit-help">Add at least one contact before submitting.</p>

中程度：ユーザーのコントラスト設定

prefers-contrast と forced-colors は異なる状況に対応するもので、どちらもライト／ダークのテーマセレクターではありません。prefers-contrast: more は拡張機能として使用してください。デフォルトの表示は、適合目標をすでに満たしている必要があります。

@media (prefers-contrast: more) {
  :root { --text-muted: var(--text); --control-border: currentColor; }
  a { text-decoration-thickness: 0.15em; }
  :focus-visible { outline-width: 4px; }
}

軽微：APCA — 新興標準（まだ必須ではありません）

Advanced Perceptual Contrast Algorithm（APCA）は、WCAG 3.0 において WCAG 2.x のコントラスト計算式に代わる候補です。細い線や小さなテキストについて、知覚をより正確にモデル化します。APCA はまだ必須ではありません — APCA を試しているチームも、並行して WCAG 2.2 AA を引き続き満たす必要があります。固定の APCA しきい値を現在の WCAG 要件として示してはいけません。実験的な手法は、設計上の補足的な根拠としてのみ扱ってください。

テスト

手動： ソースコードの値ではなく、実際にレンダリングされた前景色と背景色を確認します。テキストの組み合わせは丸めずに測定し、各コンポーネント／状態を見つけるために必要な視覚情報を特定して、関連する隣接色とのコントラストを測定します。すべての背景で Tab キーを使って移動し、フォーカスを確認します。すべてのテーマとコンポーネントの状態をテストします。Windows のハイコントラスト／強制カラーのエミュレーションをテストします。グラデーション、画像、不透明度、オーバーレイ、固定コンテンツ、テキスト選択を手動で確認します。グレースケールや色覚シミュレーションはレビューの補助であり、標準に基づくテストや実際の経験に取って代わるものではありません。

自動：

import { test, expect } from "@playwright/test";
import AxeBuilder from "@axe-core/playwright";

for (const theme of ["light", "dark"]) {
  test(`automated accessibility scan: ${theme}`, async ({ page }) => {
    await page.goto("/");
    await page.locator("html").evaluate((el, value) => { el.dataset.theme = value; }, theme);
    const results = await new AxeBuilder({ page })
      .withTags(["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"])
      .analyze();
    expect(results.violations).toEqual([]);
  });
}

自動化ツールは計算可能なテキストコントラストの不備を多数検出できますが、背景、必要なグラフィカルな詳細、色だけによる区別、フォーカスインジケーターの形状、強制カラーでの不備をすべて確実に判定することはできません。自動化は手動レビューを補助するために使い、置き換えるためには使わないでください。focus-visible と focus-order-semantics は 実在する axe-core のルール ID ではありません。これらを挙げないでください。キーボードフォーカスの表示は手動テストが必要です（実際のルールセットについては skills/axe-rules/SKILL.md を参照してください）。

デザイントークン： 承認済みのトークンの組み合わせを明示的にリスト化し、トークンを変更したときはその組み合わせをテストしてください。有効な使い方ではない組み合わせも多数あるため、すべてのトークンを他のすべてのトークンと照合してテストしないでください。コンポーネントの CSS によってトークンのテストでは対象にならない不透明度やオーバーレイが加わることがあるため、実行時のテストも引き続き必要です。

完了の定義チェックリスト

  • 通常のテキストはすべて、ライトモードとダークモードで 4.5:1 のコントラストを満たしている（または例外を文書化している）
  • 大きなテキストはすべて、ライトモードとダークモードで 3:1 のコントラストを満たしている
  • フォームコントロール、アイコン、データ視覚化要素は 3:1 の非テキストコントラストを満たしている
  • 色だけで伝える情報はない — アイコン、テキスト、色を組み合わせて使用している
  • 本文中のリンクは、色を使わなくても周囲のテキストと区別できる
  • フォーカスインジケーターには outline を使用し、3:1 のコントラストを満たし、すべてのモード／サーフェスで視認できる
  • 色トークンは CSS カスタムプロパティとして定義し、コンポーネントにハードコードされた値がない
  • サポートするすべてのテーマとコンポーネントの状態をテストしている（ホバー、フォーカス、アクティブ、選択済み、訪問済み、エラー、無効、自動入力、テキスト選択）
  • グラデーション／画像／オーバーレイ上のテキストは、最も条件の悪い領域でテストしている
  • 強制カラー／Windows ハイコントラストモードをテストし、意味が失われていない
  • axe-core の color-contrast ルールが CI で合格している（手動レビューも引き続き必要）
  • 無効なコントロールは、不透明度や色だけに頼らず、有効なコントロールと明確に区別できる
  • 承認済みのデザイントークンの組み合わせを文書化し、テストしている

WCAG の主な基準

  • 1.4.1 色の使用（A） — 不適合の場合は重大
  • 1.4.3 コントラスト（最低）（AA） — 通常のテキストで不適合の場合は致命的
  • 1.4.5 テキスト画像（AA）
  • 1.4.6 コントラスト（強化）（AAA）
  • 1.4.11 非テキストコントラスト（AA） — 不適合の場合は重大
  • 2.4.7 フォーカスの可視化（AA）
  • 2.4.13 フォーカスの外観（AAA、WCAG 2.2） — AA の要件ではありません

参考資料

標準化の見通し： WCAG 3.0 で提案されている APCA は、現行の 輝度比モデルを知覚的なコントラストモデルに置き換える予定です。WCAG 3.0 が 公開標準になるまでは、本番環境の適合性評価に APCA を適用しないでください。 以下で最新情報をご確認ください：https://www.w3.org/TR/wcag-3.0/ および https://git.apcacontrast.com/

コメント

Markdown 対応