デザインシステム

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

zudo-docはzfbのzudo-windコンパイラーと緻密なトークン戦略を使用します。値は通常のCSSカスタムプロパティで定義し、パッケージのプリセットで対応するユーティリティトークンを登録します。このリファレンスの対象は整合したzfb 4.3.3ファミリーです。

緻密なトークン戦略

スキャフォールドは公開パッケージCSSをインポートし、通常のCSSで値を上書きします。

@layer zw-reset, zd-flow;
@import "@takazudo/zudo-doc/theme.css";
@import "@takazudo/zudo-doc/content.css";
@import "@takazudo/zudo-doc/page-loading.css";
@import "@takazudo/zudo-doc/features.css";

:root {
  --font-sans: "Inter", system-ui, sans-serif;
}

theme.cssはカスタムプロパティと、手書きの@layer baseリセット補正を提供します。プリセットはreset: "owned-v1"を選択します。zudo-windのリセットにパッケージの補正を加える構成であり、Tailwindのリセットとバイト単位で同一ではありません。このCSSエントリーではTailwindのインポート、@source、safelist CSS、@themeによる登録を使いません。

使用できるユーティリティの語彙

text-caption、bg-accent、px-hsp-md、w-icon-sm、z-modalなど、プロジェクトの名前付きトークンを使用します。flex、hidden、grid-cols-3などの構造ユーティリティや、対応する明示的な長さm-[13px]も利用できます。Tailwindのすべての綴りに対応しているわけではありません。

プリセットはspacingUnitを指定しません。p-4などゼロ以外の数値スペーシングに暗黙の0.25remスケールはありません。名前付きスペーシングか角括弧内の明示的な長さを使います。ゼロとpxは利用できます。bg-blue-500などのデフォルトパレット名は登録されません。名前付きgroup/peer、peer-checked、ring、animationには通常のCSSを記述します。

パッケージのクラスは公開@takazudo/zudo-doc/wind.jsonマニフェストで宣言されます。プロジェクトのクラスはzfbのスキャナーが検出できる形で記述します。新しいセマンティックユーティリティはzudoDoc({ wind })で登録します。カスタムプロパティの定義だけではユーティリティは増えません。

import { defineConfig } from "@takazudo/zfb/config";
import { zudoDoc } from "@takazudo/zudo-doc/config";

export default defineConfig(
  zudoDoc({
    siteName: "My Docs",
    wind: {
      tokens: {
        colors: { brand: "var(--project-brand)" },
      },
    },
  }),
);

:root {
  --project-brand: var(--zd-accent);
}

zfbはこの上書きをプリセットへ深くマージし、ほかのパッケージトークンを保持します。wind: falseは生成を明示的に無効にします。外観の切り替えには引き続きhtml[data-theme]とカスタムプロパティを使い、dark: falseのため別のdarkユーティリティテーマは作りません。

pnpm exec zfb wind audit --project-root . --fail-on errorを実行します。このフラグによりerror診断がコマンド失敗になります。ただし成功しても条件式内のすべてのクラスの検出や、必要なCSSルールの生成を保証しません。このリポジトリではpnpm check:package-wind-manifestも実行し、代表的なページの生成CSSとcomputed valueを確認します。

スペーシング

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>

max-sm、max-lg、max-xlは設定したピクセル値未満の幅に適用されます。mdや2xlは設定されていません。

Z-index Tier

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

カラー

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

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

別の @theme との共存

ホスト側の別のTailwindビルドが@themeを使う場合も、zudo-docのエントリーでは通常の:rootプロパティとzudo-windのトークン設定を使用します。ホスト側は別の名前空間を使ってください。zudo-docは23個の名前空間なし--color-*エイリアスと--color-zd-*接頭辞を予約しています。これらを再定義すると、CSSの生成元にかかわらずパッケージのクロームに影響します。

プロジェクトの上書きより前に@takazudo/zudo-doc/theme.cssをインポートします。パレットリセットやtheme-no-reset.cssの選択肢はありません。既存の--color-zd-*エイリアスはwindのカラートークンとして登録されています。生の--zd-*プロパティはカラースキームプロバイダーが所有します。複数のCSSを共有するページでは生成ルールと最終的に適用される宣言を確認してください。

使用ルール

推奨

<!-- 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 トークン戦略のセクションがトレードオフを扱っています。