デザインシステム

zudo-docのタイトトークン戦略 — スペーシング、タイポグラフィ、カラーなど。

zudo-docはタイトトークン戦略を採用しています。Tailwindフレームワーク全体をインポートするのではなく、preflightとutilitiesのみを読み込み、デフォルトテーマ層を完全にスキップします。小さく意図的なデザイントークンのセットをゼロから定義します。このページでは、スペーシング、タイポグラフィ、カラー、角丸、ブレークポイントの全体像を解説します。

タイトトークン戦略

Tailwind CSSには数百の組み込み値（カラー、スペーシングスケール、フォントサイズなど）が用意されています。テーマ切り替え可能なプロジェクトでは、これらのデフォルト値が問題を引き起こします。ハードコードされた値はテーマ変更を無視し、一貫性を崩します。

zudo-docではsrc/styles/global.css内で選択的インポートを使い、preflight（リセット）とutilities（ユーティリティクラス）のみを読み込んでいます。デフォルトテーマ層は完全にスキップされます:

@import "tailwindcss/preflight";
@import "tailwindcss/utilities";

@theme {
  --color-*: initial;  /* Tailwindのデフォルトカラーをリセット */
  --color-bg: var(--zd-bg);
  --color-fg: var(--zd-fg);
  /* ... */
}

@themeブロックは--color-*: initialで始まり、Tailwindのデフォルトカラートークンをすべて消去してからプロジェクトトークンを定義します。@theme内で明示的に定義されたトークンのみが機能します。未定義のトークン（p-4やbg-gray-500など）を使っても効果はありません。値自体が存在しないためです。これにより無効なトークンはビルドエラーやスタイル欠落として現れ、視覚的なバグにはなりません。

スペーシング

zudo-docではスペーシングを**水平（hsp）と垂直（vsp）**の2軸に分離しています。レイアウトにおいてそれぞれ異なる役割を果たすためです。水平スペーシングはインラインのリズムやガターを制御し、垂直スペーシングはコンテンツの流れやセクション間の余白を制御します。垂直スケールは大きいサイズほど広がり、コンテンツにより多くの余白を与えます。

水平スペーシング（hsp）

垂直スペーシング（vsp）

両軸とも0（0px）とpx（1px）のユーティリティ値も含まれます。

<!-- 水平パディング + 垂直パディング -->
<div class="px-hsp-lg py-vsp-md">非対称なスペーシングのコンテンツ</div>

<!-- 2軸ギャップのグリッド -->
<div class="grid gap-x-hsp-md gap-y-vsp-lg">グリッドアイテム</div>

タイポグラフィ

フォントサイズ

各セマンティックロールは抽象スケール（--text-scale-*）のステップを参照します。以下は解決後のサイズです。

フォントウェイト

行の高さ

フォントファミリー

<h1 class="text-heading font-bold leading-tight">ページタイトル</h1>
<p class="text-body font-normal leading-normal">本文テキスト</p>
<code class="text-small font-mono">インラインコード</code>

角丸（Border Radius）

<button class="rounded bg-accent text-bg">デフォルトの角丸</button>
<div class="rounded-lg bg-surface">大きめの角丸のカード</div>
<span class="rounded-full bg-muted">ピルバッジ</span>

ブレークポイント

<div class="px-hsp-sm sm:px-hsp-md lg:px-hsp-lg xl:px-hsp-xl">
  レスポンシブな水平パディング
</div>

カラー

カラーは3層戦略を採用しています。生のパレット値（Tier 1）がセマンティックトークン（Tier 2）に流れ込み、さらにコンポーネントスコープのトークン（Tier 3）に供給されます。各層は上の層のみを参照するため、カラースキームを切り替えるとサイト全体が一括で更新されます。

カラートークンシステム、カラースキーム、カスタマイズの詳細はカラーリファレンスを参照してください。

使用ルール

推奨

<!-- セマンティックカラートークン -->
<p class="text-fg">メインテキスト</p>
<div class="bg-surface border border-muted">パネル</div>
<a class="text-accent hover:text-accent-hover">リンク</a>

<!-- スペーシングトークン -->
<div class="px-hsp-lg py-vsp-md">適切なスペーシング</div>
<div class="gap-x-hsp-sm gap-y-vsp-md">グリッドギャップ</div>

<!-- タイポグラフィトークン -->
<h2 class="text-title font-semibold leading-tight">見出し</h2>

非推奨

<!-- NG: Tailwindデフォルト — 未定義で何も表示されない -->
<div class="p-4 bg-gray-500 text-sm">表示されない</div>

<!-- NG: ハードコードされたhex — テーマ切り替えで壊れる -->
<div class="bg-[#1e1e2e] text-[#f8f8f2]">テーマ切り替え時に壊れる</div>

すべてのトークンはsrc/styles/global.cssで定義されています。このファイルがデザインシステムの唯一の情報源です。

インタラクションのルール

リンク要素にホバー時の下線を使う

遷移する 要素（<a href>、またはリンクとして振る舞う要素）は、ホバー時とキーボードフォーカス時にアンダーラインを表示します。ボタン、トグル、コントロールは対象外で、ボーダー／背景の変化で代替します。

OK（ナビゲーション用のリンク）：

<a class="text-accent hover:underline focus-visible:underline">リンク</a>
<a class="text-fg hover:text-accent hover:underline focus-visible:underline">サイドバー項目</a>

NG（focus-visible が欠けている）：

<!-- NG: マウスだけ下線、キーボード操作では出ない -->
<a class="text-fg hover:underline">キーボードフォーカスで下線が出ない</a>

NG（コントロール）：

<!-- NG: ボタンは下線ではなくボーダー／背景ホバーを使う -->
<button class="hover:underline">代わりに hover:bg-accent/10 などを使う</button>

hover:underline focus-visible:underline のペアが正規形です。必ず両方を書き、片方だけにはしないでください。実装例：packages/zudo-doc/src/header/header.tsx、src/components/site-tree-nav.tsx、packages/zudo-doc/src/footer/footer.tsx。

より深い背景（ライト／ダークのコントラスト、下線だけで足りるか色の変化も必要か）は、ローカルの /css-wisdom スキルを参照してください。light-mode/dark-mode と three-tier トークン戦略のセクションがトレードオフを扱っています。