テーマ設定

いくつかの設定トークンで見た目を調整したり、theme.css で任意の CSS 変数を上書きしたり、カスタムコンポーネント向けに Tailwind ユーティリティまで踏み込んだりできます。

Blume のテーマはトークン駆動で、ライトモードとダークモードにそのまま対応しています。必要な分だけ手を伸ばせます。よくあるケースにはいくつかの設定トークン、任意のデザイントークンを上書きするなら theme.css、カスタムコンポーネントには Tailwind ユーティリティを使えます。

設定トークン

日常的に使うつまみは、設定ファイルの theme の下にあります:

theme: {
  accent: "teal",   // a named preset or any CSS color
  radius: "md",     // none | sm | md | lg
  mode: "system",   // system | light | dark
  toggle: true,     // show the light/dark toggle
  fonts: {          // self-hosted Google Fonts
    display: "inter",
    body: "inter",
    mono: "ibm-plex-mono",
  },
}

アクセント

アクセントカラーは、インタラクティブな要素や強調される要素に色味を加えます。ステップのマーカー、アクティブなタブ、バッジ、カードのホバーなどです。名前付きプリセット、または任意の CSS カラーを使えます:

theme: {
  accent: "#ff0066", // hex, oklch(), rgb()… anything CSS understands
}

名前付きプリセット: blue（デフォルト）、green、orange、pink、purple、red、teal。各プリセットにはライトモード用のより暗い色合いとダークモード用のより明るい色合いがあるため、アクセントのテキストやボタンのラベルはどちらのモードでも WCAG AA のコントラスト（4.5:1）を満たします。

文字列を指定すると両方のカラーモードに適用されます。モードごとに異なるアクセントを設定したい場合はオブジェクトを渡してください。

"deep purple" や # のない 16 進数の値のように、プリセットでも CSS カラーでもない値を指定すると、その値を設定している blume.config.ts の行で BLUME_THEME_COLOR_INVALID の警告が出ます。ブラウザーはその値を使うスタイルを無視するためです。同じチェックは action、background、そして Open Graph カードの seo.og.palette にも適用されます。カスタムプロパティ（var(--brand)）、color-mix()、その他のカラー関数は、書いたとおりにそのまま受け付けられます。

ボタンのラベルやステップの番号など、アクセントまたはアクションの塗りの上に置かれるテキストは、その色に対して白が AA を満たす場合は白になり、そうでない場合は暗い色になります。明るいアクセントには、追加の設定なしで暗いラベルが使われます。blume audit は、カスタムのアクセント、アクション、背景を同じ基準でチェックします。

角丸

radius は、カード、コードブロック、コールアウト、入力欄で共通して使われる角の丸みを設定します。none、sm、md（デフォルト）、lg のいずれかです。

カラーモード

mode は初期のカラースキームを設定します:

• system（デフォルト） — 読者の OS の設定に従う
• light / dark — いずれかのスキームをデフォルトにする

ヘッダーのトグルで読者はいつでも切り替えられ、その選択は再訪時にも記憶されます。ダークモードは <html> 要素の data-theme="dark" 属性によって適用されます。

単一のスキームだけを提供するには、toggle: false を設定します。ヘッダーからトグルがなくなり、すべてのページが mode で表示されます。トグルが削除される前にもう一方のスキームを選んでいた読者に対しても同様です:

theme: {
  mode: "dark",
  toggle: false,
}

mode: "system" と toggle: false を組み合わせると、各読者の OS の設定に従い、読者がそれを上書きする手段はなくなります。

フォント

fonts は 3 つの役割ごとに書体を設定します:

• display — 見出し（h1〜h6）
• body — 本文、UI、散文
• mono — コードブロックとインラインコード

見出しにはテーマ側でディスプレイ向けの字間（-0.05em）が設定されるため、display にどのフォントを選んでも — デフォルトの Inter のような本文向けフォントでも — フォント自体のトラッキングに頼らず、見出しサイズで正しく表示されます。

それぞれ厳選された Google Font がデフォルトになっているので、Blume は最初から意図のある見た目になります:

theme: {
  fonts: {
    display: "inter",         // default
    body: "inter",            // default
    mono: "ibm-plex-mono",    // default
  },
}

変更したい役割だけを設定してください。残りはデフォルトのままです:

theme: {
  fonts: { display: "geist" }, // body + mono stay Inter / IBM Plex Mono
}

フォントはセルフホストされます。Blume がビルド時にダウンロードして自分のサイトから配信するため、実行時に Google へのリクエストは発生せず、レイアウトシフトもありません（Astro がフォールバックのメトリクスに合わせた書体を自動生成します）。

素の文字列は、以下の厳選セットに含まれる Google Fonts のスラッグです:

任意のプロバイダーのファミリー

厳選セットに含まれていないファミリー（たとえば非ラテン文字をカバーするもの）が必要ですか？ファミリーの正確な名前を指定したオブジェクトを渡してください。同じようにセルフホストされ、最適化されます:

theme: {
  fonts: {
    display: { name: "Noto Sans JP", weights: [400, 700] },
    body: { name: "Noto Sans JP", weights: [400, 500, 700] },
  },
}

• name — プロバイダーが表記しているとおりの正確なファミリー名。
• provider — ファミリーの提供元: google（デフォルト）、fontsource、bunny、fontshare。
• weights — 読み込むウェイト。数値、または "100..900" のような可変フォントの範囲で指定します。デフォルトは [400, 500, 600, 700]。
• subsets — 読み込む文字サブセット。プロバイダーの名前で指定します（latin、latin-ext、vietnamese、cyrillic、greek など）。デフォルトは latin に加えて、設定したロケールが必要とするもの — 詳しくは以下を参照してください。
• fallback — フォントの読み込み中や欠けているグリフに使われるシステムスタック: sans、serif、mono。mono の役割では mono、それ以外では sans がデフォルトです。

サブセットとロケール

Google、Bunny、Fontsource は各ファミリーを文字体系ごとのサブセットに分割しており、@font-face が生成されるのは読み込んだサブセットだけです。Blume はそのリストを i18n.locales から導き出します。ベトナム語、ポーランド語、ロシア語、ギリシャ語のロケールを持つサイトでは latin に加えて vietnamese、latin-ext、cyrillic、greek が読み込まれるため、ダイアクリティカルマークや非ラテン文字がシステムフォールバックではなく選んだフォントで表示されます。i18n ブロックがないサイトや、Latin-1 の言語だけのサイトでは latin のみが読み込まれます。ブラウザーはそのサブセットの文字をページが使っている場合にのみダウンロードし、プリロードも同じリストに従います。

導き出されたリストを上書きしたい場合は、ファミリーに subsets を設定します。たとえば、単一ロケールのサイトでコンテンツがそのロケールからは導かれない文字体系を必要とする場合です:

theme: {
  fonts: {
    body: { name: "Be Vietnam Pro", subsets: ["latin", "vietnamese"] },
  },
}

inter のような厳選スラッグもロケールから導かれたリストに従います。それらのファミリーでサブセットを固定したい場合もオブジェクト形式を使ってください。

ローカルのフォントファイル

自分が所有しているフォント（あるいはどのプロバイダーも配信していないフォント）は、プロジェクト内のフォントファイルを役割に指定します。各バリアントが 1 つの @font-face になります:

theme: {
  fonts: {
    display: {
      name: "Berkeley Mono",
      variants: [
        { src: "./fonts/BerkeleyMono-Regular.woff2", weight: 400 },
        { src: "./fonts/BerkeleyMono-Bold.woff2", weight: 700 },
      ],
    },
  },
}

パスはプロジェクトルートからの相対で解決されます。weight と style（normal、italic、oblique）は省略可能です。省略した場合、Astro がフォントファイルから読み取ります。

システムスタックに戻したいですか？theme.css で --blume-font-* トークンを直接上書きしてください。

ダークモードの色

accent と background は 1 つのルールに従います。文字列は両方のカラーモードに適用され、{ light, dark } オブジェクトは各モードを個別に設定します:

theme: {
  accent: { light: "blue", dark: "teal" },
  background: {
    light: "#ffffff",
    dark: "#0a0a0a",
  },
}

いずれの色も、名前付きプリセットまたは任意の CSS カラーを受け取ります。background（および backgroundImage）ではどちらのキーも省略でき、片方のモードだけを上書きできます。background: { dark: "#0a0a0a" } はライトモードの背景をデフォルトのままにします。

アクションカラー

action は、主要なコールトゥアクションと action 系の Tailwind ユーティリティ（bg-action、text-action）に使われる二次的なアクセントです。デフォルトは accent と同じです:

theme: {
  action: "#ff0066",
}

背景画像

backgroundImage でコンテンツの背後に背景画像を設定できます。URL か public/ 配下のパスを指定します。色と同じく、文字列は両方のモードに適用され、{ light, dark } オブジェクトは各モードの画像を設定します:

theme: {
  backgroundImage: {
    light: "/bg-light.svg",
    dark: "/bg-dark.svg",
  },
}

theme.css

プロジェクトルートに theme.css を置くと、任意のデザイントークンを上書きできます。カスケードの最後のレイヤーなので、デフォルトや設定トークンよりも優先されます:

:root {
  --blume-accent: oklch(0.68 0.14 180);
  --blume-radius: 0.5rem;
}

:root[data-theme="dark"] {
  --blume-background: oklch(0.16 0 0);
}

ライトモード用のトークンは :root の下に、ダークモード用は :root[data-theme="dark"] の下に設定します。カラートークンにはダークセレクタのより高い詳細度で宣言された組み込みのダーク値があるため、:root だけで --blume-accent、--blume-background などを上書きしてもライトモードにしか適用されません。両方のモードを変えたい場合はダーク用のブロックも宣言してください。

theme.css はサイトの Tailwind エントリにインライン展開されるため、その中で Tailwind のディレクティブも使えます。モノレポで知っておきたいのが @source です。Blume はユーティリティクラスを求めてプロジェクトをスキャンしますが、兄弟のワークスペースパッケージからコンポーネントを import しているページでは、そのパッケージもスキャンする必要があります。theme.css からの相対パスで指定すれば — これは Tailwind の標準的なルールです — Blume がそのパスを生成されるスタイルシートに引き継ぎます:

@source "../../packages/ui/src";

デザイントークン

厳選リスト外のフォントを使う、あるいはシステムスタックにフォールバックするには、--blume-font-* トークンに任意のフォントスタックを設定します:

:root {
  --blume-font-body: ui-sans-serif, system-ui, sans-serif;
}

Tailwind ユーティリティ

Blume のテーマは内部的に Tailwind v4 で構築されており、プロジェクトの .astro、.jsx、.mdx、.ts、.tsx ファイルもスキャンされます。そのため、Tailwind のセットアップなしで、カスタムコンポーネントやページをユーティリティクラスでスタイリングできます。すべてのトークンがユーティリティとして公開されているので、コンポーネントは自動的にテーマに追従します:

カスケードの順序

スタイルは 3 つのレイヤーで解決され、後のレイヤーが前のレイヤーを上書きします: