デザインシステム

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

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

タイトトークン戦略

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

scaffold の src/styles/global.css は、Tailwind の preflight（リセット）と utilities（ユーティリティクラス）のみをインポートした後、パッケージのトークンスタイルシートをインポートします。デフォルトの Tailwind テーマ層は意図的にスキップされます:

@layer zd-preflight, zd-flow;
@import "tailwindcss/preflight" layer(zd-preflight);
@import "tailwindcss/utilities";
@import "@takazudo/zudo-doc/theme.css";
@import "@takazudo/zudo-doc/safelist.css";
@import "@takazudo/zudo-doc/content.css";
@import "@takazudo/zudo-doc/page-loading.css";
@import "@takazudo/zudo-doc/features.css";

/* Override package defaults here when the project needs to. */
@theme {
  /* e.g. --color-accent: oklch(0.6 0.2 250); */
}

@takazudo/zudo-doc/theme.css がデフォルトの @theme トークンを提供します。パッケージのソースである packages/zudo-doc/src/theme.css が唯一の情報源であり、scaffold の後続の空の @theme ブロックは上書きポイントです。出荷されるブロックは --color-*: initial で始まり、プロジェクトのカラートークンを再追加する前に Tailwind のデフォルトパレットを消去します。

利用できるTailwindの語彙

タイトトークン戦略は Tailwind のユーティリティ構文を取り除くものではありません。トークンを持つユーティリティを絞り込みます。MDX やコンポーネントでは以下のプロジェクト語彙を使ってください。

scaffold は @source のカバレッジと Tailwind の自動検出によって、MDX コンテンツ、src/components/、src/chrome-bindings.tsx、pages/ を走査します。走査対象外の場所で使ったクラスはスタイルなしのマークアップとして出力されるため、新しいソース位置を導入するときは @source ディレクティブを追加してください。

Tailwind のデフォルト語彙を再有効化するには、tailwindcss/theme をインポートするか、プロジェクトの @theme 上書きブロックに必要なトークンを定義します。値がプロジェクトのデザイン言語の一部なら、ローカルのセマンティックトークンを優先してください。

この語彙を MDX コンポーネントで使う例は、カスタムコンポーネントを参照してください。

スペーシング

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

水平スペーシング（hsp）

垂直スペーシング（vsp）

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

<!-- Horizontal padding + vertical padding -->
<div class="px-hsp-lg py-vsp-md">Content with asymmetric spacing</div>

<!-- Grid with dual-axis gaps -->
<div class="grid gap-x-hsp-md gap-y-vsp-lg">Grid items</div>

要素サイズ

アイコンサイズ

エレベーション

定義されているシャドウトークンは1つだけです。

タイポグラフィ

フォントサイズ

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

フォントウェイト

行の高さ

字間（Letter Spacing）

4段階のスケールです。大きな見出しには tracking-tight を使うと視覚的に引き締まり、tracking-normal はブラウザのデフォルトにリセットします。tracking-wide / tracking-wider はラベルやスモールキャップスのテキストに適しています。

フォントファミリー

<h1 class="text-heading font-bold leading-tight">Page Title</h1>
<p class="text-body font-normal leading-normal">Body text</p>
<code class="text-small font-mono">inline code</code>

角丸（Border Radius）

<button class="rounded bg-accent text-bg">Default radius</button>
<div class="rounded-lg bg-surface">Card with larger radius</div>
<span class="rounded-full bg-muted">Pill badge</span>

ブレークポイント

<div class="px-hsp-sm sm:px-hsp-md lg:px-hsp-lg xl:px-hsp-xl">
  Responsive horizontal padding
</div>

Z-index Tier

任意のスタック値ではなく、意味を持つ z-index tier を使ってください。

カラー

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

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

使用ルール

推奨

<!-- Semantic color tokens -->
<p class="text-fg">Primary text</p>
<div class="bg-surface border border-muted">Panel</div>
<a class="text-accent hover:text-accent-hover">Link</a>

<!-- Spacing tokens -->
<div class="px-hsp-lg py-vsp-md">Proper spacing</div>
<div class="gap-x-hsp-sm gap-y-vsp-md">Grid gaps</div>

<!-- Typography tokens -->
<h2 class="text-title font-semibold leading-tight">Heading</h2>

非推奨

<!-- DON'T: Tailwind defaults — not defined and produce nothing -->
<div class="p-4 bg-gray-500 text-sm">Broken</div>

<!-- DON'T: Hardcoded hex — breaks theming -->
<div class="bg-[#1e1e2e] text-[#f8f8f2]">Breaks on theme switch</div>

デフォルトトークンは @takazudo/zudo-doc/theme.css から提供され、packages/zudo-doc/src/theme.css が唯一の情報源です。scaffold の src/styles/global.css はそれらのデフォルトをインポートし、プロジェクトの上書きポイントを提供します。

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

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

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

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

<a class="text-accent hover:underline focus-visible:underline">Link</a>
<a class="text-fg hover:text-accent hover:underline focus-visible:underline">Sidebar item</a>

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

<!-- DON'T: mouse users get an underline, keyboard users don't -->
<a class="text-fg hover:underline">Inaccessible to keyboard focus</a>

NG（コントロール）：

<!-- DON'T: buttons use border/bg hover, not underline -->
<button class="hover:underline">Use hover:bg-accent/10 instead</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 トークン戦略のセクションがトレードオフを扱っています。