Vibe Codingでの色の見やすさ改善：ライト・ダークモードと操作状態の確認
この記事で学べること
- ライト・ダークモードと、ホバー・選択・フォーカスを組み合わせて色を確認する理由
- 色の判断基準と用途別の色指定を共有し、AIへの指示に反映する方法
- コードの変更箇所をレビューするときに、毎回同じ表示状態と対象箇所を確認する方法
通常表示だけでは気づけなかった色の問題
このサイトを作り始めたころは、通常の表示で文字が読める色を選べば十分だと考えていました。しかし、ダークモードやライトモードを切り替えたり、ボタンやカードを操作したりすると、文字が読みにくくなる、選択した項目が分かりにくくなる、といった問題が繰り返し起きました。
確認が必要だったのは、通常の表示に加えて、ホバー（ポインターを重ねた状態）、選択済み、フォーカス（キーボードなどの操作対象になっている状態）の見え方です。色のアクセシビリティ（文字や操作状態を見分けやすくするための配慮）は、色を一つずつ選ぶだけでは保てませんでした。
Vibe Coding（自然言語でAIに指示しながら実装する進め方）を続けるなかで、テーマと操作状態の組み合わせを、実装前にAIへ伝えるルールに含める必要があると分かりました。そこで、確認項目をハーネス（AIに渡すルール、作業手順、検証方法をまとめた仕組み）に組み込み、自動検査と画面上の確認を分けています。
この記事では、このサイトで起きた問題と、その再発を減らすために整えたルールを紹介します。期待していた見え方と実際の表示の違い、問題が起きた条件、次の実装で使う判断基準を通じて、自分のサイトでも何を確認すべきか考えられるようにまとめます。
テーマと操作状態の組み合わせによる見え方の違い
最初は「このボタンの色が薄い」「このカードの選択状態が見えにくい」と、問題が見つかった箇所の色を個別に直していました。しかし、原因を確かめると、ある色だけの問題ではなく、テーマと操作状態の組み合わせによって見え方が変わることが問題でした。
たとえば、ライトモードの通常表示では読みやすくても、ダークモードでホバーすると文字色と背景色が近づき、読みにくくなることがあります。また、選択済みのカードの文字は読めても、フォーカスリング（操作対象を示す枠）が背景や影に埋もれ、どのカードを操作しているか分からなくなることもあります。
AIは短時間で見た目の整った初稿を作ってくれます。ただし、その初稿ですべてのテーマと操作状態が確認されているとは限りません。ライト・ダークの両テーマについて、通常表示、ホバー、選択、フォーカスの見え方を対照表で確認する必要があります。
WCAG 2.2（ウェブのアクセシビリティに関する国際的なガイドライン）のコントラスト最小要件では、通常のテキストは少なくとも4.5:1、大きなテキストは少なくとも3:1のコントラスト比が求められます。[1] コントラスト比は、文字と背景などの明るさの差を数値で表したものです。
通常表示のスクリーンショットを見るだけでは、操作したときの読みやすさは確認できません。テーマと操作状態に加え、背景や文字サイズも組み合わせて確かめる必要があります。
手動レビューと自動検査の限界
すべてを手作業で確認しようとすると、実装のたびに確認項目を思い出す必要があります。記事カード、クイズ、サイドバー、ページネーション（ページを切り替えるための表示）、タグリンクなど、似たUI（画面上の操作要素）が増えるほど、確認する状態も増えていきます。
自動検査ツールは、確認を助けてくれます。ただし、W3Cは、すべてのアクセシビリティ項目を自動で確認できるわけではなく、人による確認が必要だと説明しています。[2]
そこで、このサイトでは、AIへの指示、共有ルール、用途別の色指定、差分レビュー（コードの変更箇所の確認）、ブラウザでの表示確認を一連の作業として扱うことにしました。ツールの導入だけで完了とせず、自動で確認できる範囲と人が判断する範囲を分けています。
コンポーネント実装前に共有する色のルール
まず、コンポーネント（ボタンやカードなど、再利用できる画面要素）を追加・変更するときの確認項目を整理しました。このサイトでは、src/components/ 配下のコンポーネントに適用するアクセシビリティのルールを、shared/rules/component-accessibility.md に置いています。
色の選び方は、実装のたびにAIが判断するのではなく、この共有ルールに沿って決めます。新しいコンポーネントでは、通常表示、ホバー、フォーカス、選択状態の色を、既存の用途別CSS変数から選ぶ方針にしています。CSS変数は、色や余白などの値に名前を付け、複数の箇所から参照できる仕組みです。
優先して使うCSS変数は、UIの用途に応じて分けています。
| UIの用途 | 優先するCSS変数 |
|---|---|
| リンクやボタン型のUI | --btn-ghost-* |
| 選択肢や番号バッジ型のUI | --btn-choice-* |
| 丸いアイコンや番号を囲むコンテナ | --topic-btn-icon-* |
このルールがあれば、AIが毎回 --sl-color-accent を直接使ったり、任意の color-mix()（色を混ぜるCSSの関数）で新しい状態色を作ったりすることを避けやすくなります。
既存のCSS変数で必要な色を表現できない場合は、先に用途名を持つCSS変数を追加します。コンポーネントの中だけに色を指定するのではなく、ほかの実装でも参照できる形にします。
用途別CSS変数による修正結果の共有
src/styles/custom.css には、ライト・ダークの両テーマで使うボタン、選択肢、トピックアイコン、ページネーション用のCSS変数をまとめています。個別のコンポーネントを直した結果をここに反映すれば、次の実装でも同じ色指定を使えます。
確認するときは、テーマ、操作、選択の有無、背景、色の修正方法を分けて見ています。
| 観点 | 確認する状態・対象 | 共有ルールや実装での工夫 |
|---|---|---|
| テーマ | ライト／ダーク | 同じ用途名のCSS変数を両テーマで定義する |
| 操作 | 通常表示／ホバー／フォーカス | focus-visible とホバー時の色を同じ場所で確認する |
| 選択 | 未選択／選択済み | --btn-choice-* のように選択用のCSS変数を分ける |
| 背景 | カード／サイドバー／本文 | 近い用途の既存コンポーネントを参照する |
| 修正方法 | 個別の色指定／CSS変数の追加 | 再利用する色には用途名を付けて共有する |
focus-visible は、主にキーボード操作などでフォーカスを視覚的に示す必要があるときに、枠などのスタイルを適用するためのCSSの指定です。
この表は、AIへの指示と私自身のレビューの両方で使っています。人による確認を省くためではなく、毎回同じ観点で同じ箇所を確認できるようにするためのものです。
AIへの指示に明記するテーマと操作状態
以前は、AIに「アクセシビリティに配慮して」「ダークモードでも見やすくして」と依頼していました。しかし、この指示だけでは、どの状態を確認してほしいのか十分に伝わりません。
今は、次のようにテーマと操作状態を具体的に示しています。
新しい選択カードコンポーネントを実装してください。
色と状態の条件:
- ライトモードとダークモードの両方で確認する
- デフォルト、ホバー、フォーカス、選択済み状態を定義する
- 既存の --btn-choice-* CSS変数を優先する
- 新しい color-mix() を直接追加しない
- 通常テキストは WCAG AA のコントラストを満たす前提で調整する
- focus-visible のアウトラインが背景や影に埋もれないようにする
実装後に、各状態で使ったCSS変数と未確認の状態を短く報告してください。指示例の「デフォルト」は通常表示、「WCAG AA」はWCAGの適合レベルの一つを指します。ここでは、そのレベルで求められるテキストのコントラストを満たすように依頼しています。
特に重視しているのは、最後の「未確認の状態を報告してください」という指示です。AIが完成したと報告しても、確認していない状態が残っていることがあります。未確認の箇所を残したまま完了扱いにしないよう、報告の形式もハーネスに含めています。
差分レビューで確認する色指定と状態表示
実装後は、ブラウザで見た目を確認する前に、コードの変更箇所を見ます。色のアクセシビリティについては、次の点を重点的に確認しています。
- 既存のCSS変数を使わず、コンポーネント内に新しい状態色を直接書いていないか
- ライトモードだけ、またはダークモードだけの指定になっていないか
:hoverはあるのに、:focus-visibleがない状態になっていないか- 選択済みであることを、背景色だけで伝えていないか
- フォーカスリングが、影、枠線、背景色に埋もれていないか
disabled、aria-selected、aria-currentなどが示す状態と、画面上の見え方が一致しているか
最後の項目にある disabled は操作できない状態、aria-selected は選択状態、aria-current は現在の項目を示す属性です。コードで指定した状態と見た目がずれていないかを確かめます。
現在のハーネスでは、これらの確認を完全に自動化しているわけではありません。npm run harness:check は、ブログ品質、リポジトリ上の主張、重複、共有ハーネスの不整合を検出しますが、すべての色の組み合わせの見やすさを判断するものではありません。
そのため、共有ルールと差分レビューを組み合わせたうえで、ブラウザでも表示を確認します。機械で検出できる問題を確認し、色が伝える意味や実際の見え方は人が判断する、という分担にしています。
まとめ：テーマと表示状態を組み合わせた色の確認
Vibe Codingで色の見やすさを保つには、ライト・ダークの両テーマと、通常表示・ホバー・選択・フォーカスの各状態を組み合わせて確認する必要があります。確認項目を実装前の共有ルールとAIへの指示に含め、用途別CSS変数で色指定を共有することで、同じ問題の再発を減らせます。
差分レビューと自動検査で見落としを減らし、色が伝える意味や実際の見え方は人が画面で確認します。まず利用頻度の高いUI要素を一つ選び、確認するテーマと状態の組み合わせを整理すると、確認の対象を具体的にできます。
参考文献
- W3C, Web Content Accessibility Guidelines (WCAG) 2.2, 2024年12月12日
- W3C Web Accessibility Initiative, Selecting Web Accessibility Evaluation Tools, 2024年5月13日更新
最新のリリースやアップデートの詳細は、公式サイト・公式ドキュメントを確認してください。