カラー

zudo-docの3層カラー戦略、パレットシステム、カラースキーム、カスタマイズ。

zudo-docは3層カラー戦略を採用し、サイト上のすべての色をテーマ切り替え可能にしています。Tailwindのデフォルトカラーはすべてinitialにリセットされ、プロジェクトトークンのみが機能します。これにより、カラースキームを切り替えるだけでサイト全体が一括で更新されます。

3層カラー戦略

カラーは3つの層で構成されています。各層は上位の層のみを参照します：

この階層構造により：

• パレットの差し替え（カラースキーム変更）→ サイト全体が更新
• セマンティックトークンの再マッピング（例：accentをシアンから青に変更）→ accentを使用するすべてのコンポーネントが更新
• コンポーネントトークンのオーバーライド → 他のコンポーネントに影響なし

Tier 1：16色パレット

zudo-docのカラーシステムは16色パレットを採用しています。各カラースキームは16のインデックスカラースロットに加え、背景、前景、選択色の値を提供します。

パレットスロット

パレットカラーの注入方法

ColorSchemeProviderコンポーネント（src/components/color-scheme-provider.astro）がアクティブなカラースキームを読み取り、ビルド時に:rootにCSSカスタムプロパティを注入します：

:root {
  --zd-bg: #282a36;
  --zd-fg: #f8f8f2;
  --zd-cursor: #f8f8f2;
  --zd-sel-bg: #44475a;
  --zd-sel-fg: #ffffff;
  --zd-0: #21222c;   /* パレットスロット 0（Black） */
  --zd-1: #ff5555;   /* パレットスロット 1（Red） */
  /* ... --zd-15 まで続く */
}

これらの--zd-*プロパティがすべての基準値です。セマンティックトークン、コンポーネントトークン、Tailwindユーティリティ — すべてがこれらに帰結します。

Tier 2：セマンティックトークン

src/styles/global.cssの@themeブロックが、パレットプロパティをデザイン上の意味を持つTailwind互換トークンにマッピングします：

@theme {
  --color-*: initial;  /* Tailwindデフォルトをすべてリセット */

  /* ベース */
  --color-bg: var(--zd-bg);
  --color-fg: var(--zd-fg);
  --color-sel-bg: var(--zd-sel-bg);
  --color-sel-fg: var(--zd-sel-fg);

  /* パレット直接アクセス（p0–p15） */
  --color-p0: var(--zd-0);
  --color-p1: var(--zd-1);
  /* ... --color-p15 まで続く */

  /* セマンティックエイリアス */
  --color-surface: var(--zd-surface);
  --color-muted: var(--zd-muted);
  --color-accent: var(--zd-accent);
  --color-accent-hover: var(--zd-accent-hover);
  --color-code-bg: var(--zd-code-bg);
  --color-code-fg: var(--zd-code-fg);
  --color-success: var(--zd-success);
  --color-danger: var(--zd-danger);
  --color-warning: var(--zd-warning);
  --color-info: var(--zd-info);
}

@themeに登録されると、標準のTailwindユーティリティクラスとして使用できます：bg-surface、text-accent、border-mutedなど。

セマンティックトークンリファレンス

スキームごとのセマンティックオーバーライド

各カラースキームはsrc/config/color-schemes.tsのsemanticプロパティを通じて、デフォルトのパレットスロットマッピングをオーバーライドできます。例えば、Draculaはmutedをカスタムグレーにオーバーライドし、Solarized Lightはaccentをマゼンタに再マッピングしています：

"Solarized Light": {
  // ...palette, background, foreground...
  semantic: {
    accent: "#d33682",     // デフォルトのシアンではなくマゼンタ
    accentHover: "#6c71c4",
    surface: "#f4efdd",
  },
},

解決ロジックはsrc/config/color-scheme-utils.tsにあり、各セマンティックプロパティは明示的にオーバーライドされていない場合、デフォルトのパレットスロットにフォールバックします。

Tier 3：コンポーネントトークン

一部のコンポーネントは、Tier 2のセマンティックトークンを参照する独自のカラー変数を定義しています。これらは内部的な実装の詳細です。

コンテンツタイポグラフィ

.zd-contentクラスはセマンティックトークンを使用した直接的な要素スタイリングを提供します（外部タイポグラフィプラグイン不要）：

.zd-content {
  color: var(--color-fg);
  font-size: var(--text-body);
  line-height: var(--leading-relaxed);
}

.zd-content :where(a) {
  color: var(--color-accent);
}

.zd-content :where(code:not(pre code)) {
  color: var(--color-code-fg);
  background-color: var(--color-code-bg);
}

.zd-content :where(li::marker) {
  color: var(--color-muted);
}
/* ... */

カラートークンの使い方

セマンティックトークンを優先

標準的なUIパターンにはセマンティックトークンを使用します：

<!-- テキスト -->
<p class="text-fg">メインテキスト</p>
<p class="text-muted">補助テキスト</p>
<a class="text-accent hover:text-accent-hover">リンク</a>

<!-- 背景 -->
<div class="bg-bg">ページ背景</div>
<div class="bg-surface">パネルやサイドバー</div>

<!-- ボーダー -->
<div class="border border-muted">ボーダー付き要素</div>

必要に応じてパレットトークンにフォールバック

適切なセマンティックトークンがない場合はp0〜p15を使用します — バッジ、装飾要素、ステータスインジケーターなどに：

<span class="text-p1">エラーテキスト（赤）</span>
<span class="text-p2">成功テキスト（緑）</span>
<span class="text-p3">警告テキスト（黄）</span>
<span class="text-p4">情報テキスト（青）</span>

カラースキーム

アクティブなカラースキームを変更するには、src/config/settings.tsを編集します：

export const settings = {
  colorScheme: "Dracula",  // ここを変更
  siteName: "zudo-doc",
  // ...
};

デフォルトテーマ

zudo-docにはライトテーマとダークテーマのデフォルトが含まれています。利用可能なスキームはsrc/config/color-schemes.tsを参照してください。

カスタムカラースキームの追加

src/config/color-schemes.tsのcolorSchemesオブジェクトに新しいエントリを追加します：

"My Theme": {
  background: "#1a1a2e",
  foreground: "#e0e0e0",
  cursor: "#e0e0e0",
  selectionBg: "#3a3a5e",
  selectionFg: "#e0e0e0",
  palette: [
    "#16213e", "#e74c3c", "#2ecc71", "#f39c12",  // 0-3: Black, Red, Green, Yellow
    "#3498db", "#9b59b6", "#1abc9c", "#ecf0f1",  // 4-7: Blue, Magenta, Cyan, White
    "#2c3e50", "#e67e73", "#55d98d", "#f5b041",  // 8-11: Bright Black–Yellow
    "#5dade2", "#bb8fce", "#48c9b0", "#fdfefe",  // 12-15: Bright Blue–White
  ],
  shikiTheme: "one-dark-pro",
  // オプション：セマンティックのデフォルトをオーバーライド
  semantic: {
    muted: "#7f8c8d",
    surface: "#1f1f3a",
  },
},

ColorSchemeインターフェースに必要なプロパティ：

• background、foreground、cursor、selectionBg、selectionFg — ベースカラー
• palette — 16要素のタプル（カラースロット 0〜15）
• shikiTheme — シンタックスハイライト用のShikiテーマ名
• semantic（オプション）— セマンティックトークンのデフォルトパレットスロットマッピングをオーバーライド

やってはいけないこと

<!-- NG -->
<div class="bg-gray-800 text-blue-500">色が表示されない</div>

<!-- OK -->
<div class="bg-surface text-accent">正しく動作する</div>

<!-- NG -->
<div class="bg-[#1e1e2e]">テーマ切り替えで壊れる</div>

<!-- OK -->
<div class="bg-p0">どのテーマにも適応する</div>

/* NG */
.my-component {
  color: var(--tw-prose-links);
}

/* OK */
.my-component {
  color: var(--color-accent);
}