Tips & Tricks (更新: 2026/6/2)

Claude Codeでダークモードを実装する実務ガイド

CSS変数、prefers-color-scheme、localStorage、hydration対策まで含むダークモード実装ガイド。

Claude Codeでダークモードを実装する実務ガイド

最初に決めるべきこと

Claude Codeでダークモードを実装するときに大事なのは、Claude Codeに「見た目を整えて」と丸投げしないことです。初心者ほど、動いた瞬間に完成だと思いがちですが、実務では空データ、スマホ幅、アクセシビリティ、既存CSSとの衝突、広告やコードブロックの表示まで確認して初めて公開できます。この記事では、ダークモードを小さく安全に導入し、あとから壊れにくい形へ育てる手順をまとめます。

関連する基礎は Claude Codeデザインシステム、Claude Codeのアクセシビリティ対応、Claude Codeでコードレビュー も合わせて確認してください。公式情報は Claude Code docs, MDN prefers-color-scheme, MDN color-scheme, WCAG contrast を参照します。Claude Codeへの指示では「対象ファイル」「禁止事項」「確認観点」を先に渡すと、生成される差分の品質が安定します。

Claude Codeへの安全な依頼文

この画面にダークモードを実装してください。
既存のコンポーネント構造を壊さず、変更ファイルを最小化してください。
ユースケース、落とし穴、アクセシビリティ、スマホ表示、失敗時の表示を確認してください。
コード例はコピペで動く形にし、最後にレビュー観点を箇条書きで返してください。

このプロンプトの狙いは、Claude Codeに「完成形のUI」ではなく「壊れにくい変更プロセス」を作らせることです。特に既存サイトでは、派手な改善よりも、離脱を増やさず、問い合わせや購入導線を邪魔しないことが重要です。

ユースケースのチェックリスト

  1. ランディングページのファーストビュー改善。CTAの近くで視線を誘導するが、本文や価格表の可読性は落とさない。
  2. SaaS管理画面の状態変化。保存完了、エラー、読み込み中、空データを分かりやすくする。
  3. 記事サイトや商品ページの回遊改善。関連記事、料金表、相談導線を自然に見つけてもらう。
  4. チーム開発のレビュー短縮。Claude Codeに差分と確認観点を同時に出させ、レビュー担当が見る場所を減らす。

実装例

:root {
  color-scheme: light;
  --color-page: #ffffff;
  --color-surface: #f8fafc;
  --color-text: #0f172a;
  --color-muted: #475569;
  --color-border: #dbe3ef;
  --color-link: #2563eb;
  --color-focus: #f59e0b;
}

[data-theme="dark"] {
  color-scheme: dark;
  --color-page: #0b1120;
  --color-surface: #111827;
  --color-text: #f8fafc;
  --color-muted: #cbd5e1;
  --color-border: #334155;
  --color-link: #93c5fd;
  --color-focus: #fbbf24;
}

body {
  background: var(--color-page);
  color: var(--color-text);
}

:focus-visible {
  outline: 3px solid var(--color-focus);
  outline-offset: 3px;
}

const storageKey = "theme";
const root = document.documentElement;
const stored = localStorage.getItem(storageKey);
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
const theme = stored === "light" || stored === "dark" ? stored : prefersDark ? "dark" : "light";

root.dataset.theme = theme;

type Theme = "light" | "dark" | "system";

export function ThemeToggle({ value, onChange }: { value: Theme; onChange: (theme: Theme) => void }) {
  return (
    <fieldset aria-label="Theme">
      {(["light", "dark", "system"] as const).map((theme) => (
        <button
          key={theme}
          type="button"
          aria-pressed={value === theme}
          onClick={() => onChange(theme)}
        >
          {theme}
        </button>
      ))}
    </fieldset>
  );
}

テーマのちらつき（最初の一瞬だけ色が違う問題）を防ぐ

ダークモードで最初にぶつかる落とし穴が、ページを開いた一瞬だけ明るい画面が見えてから暗くなる「ちらつき」です。英語ではFOUC（Flash of Unstyled Content）やテーマのフラッシュと呼ばれます。原因は、HTMLが表示されたあとにJavaScriptでテーマを切り替えているからです。CSSやReactの読み込みを待ってからdata-themeを付けると、その待ち時間のあいだは初期色（多くは明るい色）が見えてしまいます。

対策は、テーマを決めるごく短いスクリプトを、本文より前（<head>の中）で同期的に実行することです。次のように、保存済みの設定と端末の設定だけを見て、画面が描かれる前にdata-themeを確定させます。

<script>
  (function () {
    var stored = localStorage.getItem("theme");
    var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
    var theme = stored === "light" || stored === "dark" ? stored : prefersDark ? "dark" : "light";
    document.documentElement.dataset.theme = theme;
  })();
</script>

ポイントは、このスクリプトを軽くして、本文の描画より先に走らせることです。重い処理やReactの初期化をここに入れると、結局ちらつきが戻ります。AstroやNext.jsでも、フレームワークのハイドレーション（サーバーで作ったHTMLに、ブラウザ側で動きを付ける処理）を待たずにテーマを確定できるよう、この小さなスクリプトだけは別扱いにします。サーバー側では端末の設定を知れないため、初回は端末設定を尊重し、ユーザーが切り替えたらlocalStorageに保存して次回から優先する、という流れが扱いやすいです。

コントラスト・画像・影をダークでも読めるようにする

色を反転しただけでは、ダークモードは完成しません。明るい画面で十分だったコントラストが、暗い背景では足りなくなることがあります。本文と背景のコントラスト比は、WCAGが示す4.5:1以上を目安に確認します。特に、薄いグレーの補足テキスト、プレースホルダー、無効状態のボタンは、暗い背景で読めなくなりやすい部分です。

画像と影も調整が必要です。白を前提に作ったロゴやアイコンは、暗い背景で縁が消えます。透過PNGは背景色を敷くか、ダーク用の差し替えを用意します。影は、明るい背景では濃いグレーで効果的でも、暗い背景ではほとんど見えません。影に頼っていた境界は、--color-borderのような枠線で表現し直すと、どちらのテーマでも構造が分かります。

要素ライトでの前提ダークでの調整
補足テキスト薄いグレーで十分明度を上げてコントラストを確保
ロゴ・アイコン白背景前提背景を敷くかダーク用に差し替え
影濃いグレーで境界を表現枠線（border）で表現し直す
状態色鮮やかな緑・赤彩度を落とし、アイコンも添える

最後に、グラフや図、ステータスの色（成功は緑、警告は赤など）も見直します。彩度の高い色は暗い背景でギラついて読みにくいので、ダーク用に少し落ち着いた色を用意します。色だけで状態を伝えず、アイコンやラベルも添えると、コントラストが弱い環境や色覚特性のある読者にも伝わります。Claude Codeにレビューさせるときは、「ダーク背景でコントラストが落ちる箇所」「白前提の画像」「影で表現している境界」を具体的に探させると、見落としが減ります。

落とし穴チェックリスト

  • 目的が曖昧なまま実装すると、見た目は良くてもCVRが下がります。CTA、フォーム、価格表の邪魔をしていないか確認します。
  • スマホ幅で横スクロールが出ると、検索流入の読者がすぐ離脱します。375px幅で必ず確認します。
  • 色や動きだけで意味を伝えるとアクセシビリティが落ちます。テキスト、状態ラベル、フォーカス表示を残します。
  • ライブラリを増やしすぎると、初回表示が重くなります。まずCSSと小さなJSで足りるかを判断します。
  • Claude Codeの提案をそのまま採用せず、既存の設計トークン、命名規則、テスト方法に合わせます。

レビュー手順

実装後は、Claude Codeにもう一度レビューだけを依頼します。「変更したファイル」「削った方がよい処理」「失敗ケース」「手動確認」を分けて出させると、見落としが減ります。加えて、Playwrightやブラウザのスマホ表示で横幅、コードブロック、CTA、広告枠を確認します。

マネタイズにつなげる見方

ダークモードの実装は装飾ではありません。問い合わせ、資料請求、購入、研修申込へ向かう読者の迷いを減らすための改善です。自社サイトでClaude Codeの導入やレビュー体制を整えたい場合は、Claude Code研修・相談 で、既存画面を題材にした改善手順を相談できます。

追加のレビュー観点

  • 変更前後のスクリーンショットを並べ、CTA、広告、本文、コードブロックが読みやすいか確認します。
  • Claude Codeの提案をそのまま採用せず、削れる処理、命名の違和感、既存CSSとの競合を質問します。
  • 本番反映前に、スマホ、デスクトップ、キーボード操作、低速回線、空データを一通り見ます。

この記事で紹介した内容を実際に試した結果

この手順は、既存のブログUIを壊さない前提で、スマホ幅375px、通常表示、低速回線、キーボード操作を見ながら確認しました。Claude Codeには一度に全部を任せず、実装、レビュー、修正の3段階に分ける方が、差分が読みやすく品質も安定しました。

#Claude Code #dark mode #CSS variables #frontend #accessibility
無料

無料PDF: Claude Code はじめてのチートシート

まずは無料PDFで基本コマンドと最初の使い方をまとめて確認してください。登録後はそのままテンプレート集や導入相談にも進めます。

スパムは送りません。登録情報は厳重に管理します。

Claude Codeを仕事で使える形にしませんか？

無料PDFで基礎を固めたあと、すぐ使えるテンプレート集で試し、必要なら業務自動化や導入相談まで進められます。

テンプレート集を見る 導入相談を見る
Masa

この記事を書いた人

Masa

Claude Codeの実務活用、導入設計、収益導線改善を検証しているエンジニア。10言語の技術メディアを運営中。

PR

関連書籍・参考図書

この記事のテーマに関連する書籍を楽天ブックスで探せます。

※ 当サイトは楽天市場のアフィリエイトプログラムに参加しています。上記リンクから商品をご購入いただくと、運営者に紹介料が支払われる場合があります。

関連記事

次に使える教材・相談

PROMPT 50
販売中 note

Claude Code プロンプトテンプレート集 50選

開発・レビュー・調査・資料作成ですぐ使える、コピペOKのプロンプト集です。

500円 noteで見る

教材一覧を見る

テンプレート・設定ガイド・Tips集