カラー

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

zudo-docは3層カラー戦略を採用し、サイト上のすべての色をテーマ切り替え可能にしています。デフォルトのTailwindテーマはインポートされず、@themeブロックで--color-*: 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プロパティを通じて、デフォルトのパレットスロットマッピングをオーバーライドできます。値はパレットインデックス（数値）または直接のカラー文字列のいずれかです：

"My Custom Scheme": {
  // ...palette, background, foreground...
  semantic: {
    accent: 6,              // palette[6]を使用 — カラー値の重複なし
    accentHover: 14,         // palette[14]を使用
    surface: "#f4efdd",      // 直接のカラー文字列（パレットにない色）
  },
},

カラー文字列を繰り返す代わりにパレットインデックスを使用することで、重複を排除し、パレットカラーが変更された際（例：カラー調整パネル経由）にセマンティックカラーが同期されるようになります。

同じnumber | string型（ColorRefと呼ばれます）はcursor、selectionBg、selectionFgでもサポートされています：

"My Theme": {
  background: "#1a1a2e",
  foreground: "#e0e0e0",
  cursor: 6,            // カラーを重複させる代わりにpalette[6]を使用
  selectionBg: "#3a3a5e",
  selectionFg: 15,       // palette[15]を使用
  palette: [...],
  shikiTheme: "one-dark-pro",
},

解決ロジックは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: "Default Dark",  // ここを変更
  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 — ColorRef（パレットインデックスまたはカラー文字列）
• palette — 16要素のタプル（カラースロット 0〜15）
• shikiTheme — シンタックスハイライト用のShikiテーマ名
• semantic（オプション）— ColorRef値（パレットインデックスまたはカラー文字列）によるデフォルトパレットスロットマッピングのオーバーライド

やってはいけないこと

<!-- 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);
}