08. AstroPaperの配色テーマをカスタマイズする | Cloud AI エンジニア入門ガイド

この章の全体像として、7つのトークン、Tailwindとの接続、切り替えの仕組み、変更の進め方の4つを番号順に並べ、両モードで読める配色に変えられるようになることを示した図

シリーズ目次前章: 07. AstroPaperのMarkdown表現とアセットの扱い次章: 09. AstroPaperの検索・RSS・サイトマップ

Open Table of contents

この章のねらい
7つのカラートークン
配色を変えてみる
- コントラスト比を確認する
- 既定の配色を参考にする
Tailwind CSSとのつながり
テーマ切り替えの仕組み
切り替えボタンを消す
本文まわりの調整
フォントを変える
変更の進め方
要点
参考資料

この章のねらい

見た目を自分のものにする、いちばん手軽な方法が配色の変更です。7つの色を書き換えるだけでサイト全体の印象が変わる仕組みと、その裏で動いているテーマ切り替えの流れを見ていきます。

7つのカラートークン

配色は src/styles/theme.css にまとまっています。

/* Light theme values */
:root,
[data-theme="light"] {
  --background: #fdfdfd;
  --foreground: #282728;
  --accent: #006cac;
  --accent-foreground: #ffffff;
  --muted: #e6e6e6;
  --muted-foreground: #6b7280;
  --border: #ece9e9;
}

/* Dark theme values */
[data-theme="dark"] {
  --background: #212737;
  --foreground: #eaedf3;
  --accent: #ff6b01;
  --accent-foreground: #ffffff;
  --muted: #343f60;
  --muted-foreground: #afb9ca;
  --border: #ab4b08;
}src/styles/theme.css

--background のように -- で始まるものをCSSカスタムプロパティ（CSS変数）と呼びます。値を1か所で定義し、いろいろな場所から参照できる仕組みです。

7つのトークンの役割は次のとおりです。

トークン	役割	主な使用箇所
`--background`	ページの背景色	`<body>` 全体
`--foreground`	基本の文字色	本文、見出し
`--accent`	強調色	リンク、記事タイトル、フォーカス枠
`--accent-foreground`	強調色の上に載る文字色	選択範囲の文字
`--muted`	控えめな背景色	タグ、カード、コードの枠
`--muted-foreground`	控えめな文字色	日付、補足文
`--border`	区切り線の色	罫線、枠線

触るのはこの7つ×2セットだけです。個々のコンポーネントのCSSを開く必要はありません。

既定値と使用箇所を並べます。

7つのカラートークンについて、ライトとダークの既定色と主な使用箇所を一覧にした図

配色を変えてみる

たとえば緑を基調にしたい場合、--accent を書き換えます。

:root,
[data-theme="light"] {
  --background: #fdfdfd;
  --foreground: #282728;
  --accent: #0f766e;
  --accent-foreground: #ffffff;
  --muted: #e6e6e6;
  --muted-foreground: #6b7280;
  --border: #ece9e9;
}src/styles/theme.css

保存すればすぐに反映されます。リンク、記事タイトル、フォーカス枠がまとめて緑になります。

コントラスト比を確認する

配色を変えたら必ずコントラスト比を見てください。背景色と文字色の明暗差を表す数値で、低いと読めなくなります。

用途	推奨される比率
本文などの通常サイズの文字	4.5:1 以上
大きな文字（18pt以上または太字14pt以上）	3:1 以上
ボタンの枠など操作部品の境界	3:1 以上

ブラウザの開発者ツールで色を選ぶと比率が出ます。オンラインのコントラストチェッカーでも構いません。テーマ側がアクセシビリティを整えているので、ここで崩さないでください。

危ないのは --accent です。リンクは本文中に混ざるので、背景に対して差が要ります。

既定の配色を参考にする

AstroPaper公式に、配色例を紹介した記事があります。ゼロから色を決めるのはしんどいので、そこから選んで貼り付けるのが早いです。

Tailwind CSSとのつながり

theme.css の冒頭には、次のブロックがあります。

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-accent: var(--accent);
  /* ... */
}src/styles/theme.css

Tailwind CSS v4 の記法で、CSS変数をTailwindのクラス名として使えるように登録する、という意味です。この登録があるから、テーマ側のコードはこう書けます。

<div class="bg-background text-foreground">...</div>
<a class="text-accent">...</a>

つまり、theme.css の変数を変えれば、bg-background などを使っているすべての場所に反映されるという関係になっています。新しい色を足したい場合は、@theme inline にも登録すればTailwindのクラスとして使えるようになります。

変数から画面までは、4つの段をまっすぐつないだ形になっています。

theme.cssの変数がtheme inlineでTailwindのクラス名として登録され、テーマ内部のクラス指定を経て画面全体へ反映される流れを示した図

テーマ切り替えの仕組み

ライトモードとダークモードの切り替えは、<html> 要素の data-theme 属性で行われます。この属性が dark になると、[data-theme="dark"] の側の変数が有効になります。

動作の順序を追います。

ページ読み込み時とボタン操作時のテーマ決定手順を示したシーケンス図

インラインスクリプトが先に走る理由

src/layouts/Layout.astro の <head> には、次のスクリプトが直接埋め込まれています。

<script is:inline>
  (function () {
    const stored = localStorage.getItem("theme");
    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
    const theme = stored ?? (prefersDark ? "dark" : "light");
    const root = document.firstElementChild;
    root?.setAttribute("data-theme", theme);
    root?.classList.toggle("dark", theme === "dark");
    window.__theme = { value: theme };
  })();
</script>src/layouts/Layout.astro

FOUC（Flash of Unstyled Content）対策です。ダークモードの人がページを開いた瞬間、一瞬だけ白い画面が見える。あれを防ぎます。ブラウザが最初の描画をする前に data-theme を確定させたいので、is:inline を付けて他のスクリプトより先に同期実行しています。

判定の優先順位

localStorage に保存された設定があれば、それを使う
なければ、OSの「ダークモード」設定に従う

一度ボタンで切り替えると、その選択が localStorage に保存され、次回以降はそちらが優先されます。

OS設定の変更への追従

src/scripts/theme.ts には、OS側の設定変更を監視する処理も入っています。

window
  .matchMedia("(prefers-color-scheme: dark)")
  .addEventListener("change", ({ matches }) => {
    themeValue = matches ? DARK : LIGHT;
    persist();
  });src/scripts/theme.ts

読者がOSの表示モードを切り替えたら、ページを開いたままでも追従します。

モバイルのブラウザ枠まで合わせる

theme.ts は、<meta name="theme-color"> に現在の背景色を書き込みます。これによりAndroidのブラウザ上部の色がページ背景と一致し、統一感が出ます。画面遷移中に色が点滅しないよう、遷移前に値を引き継ぐ処理も入っています。

切り替えボタンを消す

ライトモードだけで運用したい場合は、設定で切り替えボタンを非表示にできます。

features: {
  lightAndDarkMode: false,
},astro-paper.config.ts

ただし、この設定で消えるのはヘッダーの切り替えボタンだけです。features.lightAndDarkMode を参照しているのは src/components/Header.astro のボタン描画部分だけで、テーマを決めているインラインスクリプトはこの設定を見ていません。

const stored = localStorage.getItem("theme");
const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
const theme = stored ?? (prefersDark ? "dark" : "light");src/layouts/Layout.astro

そのため false にしただけでは、OSをダークモードにしている読者や過去にダークへ切り替えたことのある読者には、ダーク配色のまま切り替え手段だけが消えた状態になります。

本当にライトモードで固定したい場合は、次の3か所も合わせて変更してください。

対象	変更内容
`src/layouts/Layout.astro` のインラインスクリプト	`const theme = "light";` に固定する
`src/scripts/theme.ts` の `getPreferredTheme`	`LIGHT` を返すようにする
`src/scripts/theme.ts` 末尾の `prefers-color-scheme` 監視	OS設定に追従しないよう削除する

設定だけを変えた場合と、本当に固定した場合の違いは次のとおりです。

設定をfalseにしても消えるのは切り替えボタンだけでダーク配色は残ることと、ライト固定にするために変更が必要な3か所を並べた図

配色そのものを変えたいだけなら、theme.css のライト側の値を書き換えるほうが簡単です。

本文まわりの調整

配色以外の見た目、たとえば見出しの大きさや行間は src/styles/typography.css にあります。

@plugin "@tailwindcss/typography";

@layer base {
  .app-prose {
    @apply prose;

    h3 {
      @apply italic;
    }

    li {
      @apply marker:text-accent;
    }
    /* ... */
  }
}src/styles/typography.css

app-prose は、記事本文を囲むクラス名です。Tailwindのタイポグラフィ機能を土台に、AstroPaper向けの調整が上書きされています。「H3が斜体になる」「箇条書きの記号がアクセント色になる」といった特徴は、ここで指定されています。

本文の最大幅は src/styles/global.css で定義されています。

@utility max-w-app {
  @apply max-w-3xl;
}src/styles/global.css

max-w-3xl を max-w-4xl などに変えると、コンテンツ幅が広がります。ただし1行が長くなると読みにくくなります。広げすぎないでください。

フォントを変える

書体は astro.config.ts で指定されています。

fonts: [
  {
    name: "Google Sans Code",
    cssVariable: "--font-google-sans-code",
    provider: fontProviders.google(),
    fallbacks: ["monospace"],
    weights: [300, 400, 500, 600, 700],
    styles: ["normal", "italic"],
    formats: ["woff", "ttf"],
  },
],astro.config.ts

Astroのフォント機能を使い、Google Fontsから取得しています。書体を変えるときは name を変更し、theme.css の --font-app が参照している変数名と対応が取れているかを確認します。

日本語のサイトなら、日本語グリフを含む書体を足すと読みやすくなります。ただしフォントファイルは重いので、表示速度と天秤にかけてください。

変更の進め方

配色は、いじり始めると際限がなくなります。次の順で進めてください。

--accent だけを変えて全体の印象を見る
--background と --foreground を調整する
--muted 系と --border を、背景になじむ範囲で微調整する
ライトとダークの両方でコントラスト比を確認する
必要ならタイポグラフィと幅を調整する

影響範囲の大きい色から決めます。

accentから始めて背景と文字、控えめな色、コントラスト比の確認、タイポグラフィの調整へと進む5段階の手順を上から順に並べた図

要点

配色は src/styles/theme.css の7つのカラートークンに集約されており、ライト・ダークで2セット定義する。
@theme inline によってトークンがTailwindのクラス名と結び付いているため、変数を変えるだけで全体へ反映される。
テーマは <html> の data-theme 属性で切り替わり、描画前に走るインラインスクリプトが白画面のちらつきを防いでいる。
判定は「保存済みの選択 → OSの設定」の順で、OS設定の変更にもその場で追従する。
lightAndDarkMode: false が消すのは切り替えボタンだけであり、ライトモード固定にはインラインスクリプトと theme.ts の変更も要る。
色を変えたら必ずコントラスト比（本文4.5:1以上）を確認し、ライト・ダークの両方で読めることを確かめる。

参考資料

AstroPaper 配色カスタマイズガイド — トークンと変更手順
AstroPaper 既定の配色例 — そのまま使える配色
テンプレート同梱ソース src/styles/theme.css / typography.css / global.css
テンプレート同梱ソース src/scripts/theme.ts と src/layouts/Layout.astro — 切り替えの実装
Tailwind CSS: Theme variables — @theme の記法
WCAG 2.2 コントラスト比の達成基準 — 必要な比率
Astro: Fonts — フォント設定

シリーズ目次前章: 07. AstroPaperのMarkdown表現とアセットの扱い次章: 09. AstroPaperの検索・RSS・サイトマップ