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



## 緻密なトークン戦略

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

```css title="src/styles/global.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 })`で登録します。カスタムプロパティの定義だけではユーティリティは増えません。

```ts title="zfb.config.ts"
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)" },
      },
    },
  }),
);
```

```css title="src/styles/global.css (after package imports)"
: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）

| トークン | 値 | 使用例 |
|-------|-------|---------------|
| `hsp-2xs` | `0.125rem` (2px) | `px-hsp-2xs` |
| `hsp-xs` | `0.375rem` (6px) | `px-hsp-xs` |
| `hsp-sm` | `0.5rem` (8px) | `gap-x-hsp-sm` |
| `hsp-md` | `0.75rem` (12px) | `px-hsp-md` |
| `hsp-lg` | `1rem` (16px) | `px-hsp-lg` |
| `hsp-xl` | `1.5rem` (24px) | `px-hsp-xl` |
| `hsp-2xl` | `2rem` (32px) | `px-hsp-2xl` |

### 垂直スペーシング（vsp）

| トークン | 値 | 使用例 |
|-------|-------|---------------|
| `vsp-3xs` | `0.25rem` (4px) | `py-vsp-3xs` |
| `vsp-2xs` | `0.4375rem` (7px) | `py-vsp-2xs` |
| `vsp-xs` | `0.875rem` (14px) | `py-vsp-xs` |
| `vsp-sm` | `1.25rem` (20px) | `gap-y-vsp-sm` |
| `vsp-md` | `1.5rem` (24px) | `py-vsp-md` |
| `vsp-lg` | `1.75rem` (28px) | `py-vsp-lg` |
| `vsp-xl` | `2.5rem` (40px) | `py-vsp-xl` |
| `vsp-2xl` | `3.5rem` (56px) | `py-vsp-2xl` |

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

```html
<!-- 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>
```

[Dynamic content unavailable in text export]

`hsp-lg`は`1rem`ですが`vsp-lg`は`1.75rem`と、垂直軸は大きいサイズほど広がります。これは意図的な設計です。垂直方向の流れには水平方向のリズムより多くの余白が必要です。



## 要素サイズ

### アイコンサイズ

| トークン | 値 | 使用例 |
|-------|-------|---------------|
| `icon-xs` | `0.75rem` (12px) | `w-icon-xs h-icon-xs` |
| `icon-sm` | `1rem` (16px) | `w-icon-sm h-icon-sm` |
| `icon-md` | `1.25rem` (20px) | `w-icon-md h-icon-md` |
| `icon-lg` | `1.5rem` (24px) | `w-icon-lg h-icon-lg` |

## エレベーション

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

| トークン | 値 | 使用例 |
|-------|-------|---------------|
| `lg` | `0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)` | `shadow-lg` |

## タイポグラフィ

### フォントサイズ

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

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `micro` | `0.75rem` / 12px | `text-micro` |
| `caption` | `0.875rem` / 14px | `text-caption` |
| `small` | `1rem` / 16px | `text-small` |
| `body` | `1.2rem` / 19.2px | `text-body` |
| `title` | `1.4rem` / 22.4px | `text-title` |
| `heading` | `3rem` / 48px | `text-heading` |
| `display` | `3.75rem` / 60px | `text-display` |

### フォントウェイト

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `normal` | `400` | `font-normal` |
| `medium` | `500` | `font-medium` |
| `semibold` | `600` | `font-semibold` |
| `bold` | `700` | `font-bold` |

### 行の高さ

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `tight` | `1.25` | `leading-tight` |
| `snug` | `1.375` | `leading-snug` |
| `normal` | `1.5` | `leading-normal` |
| `relaxed` | `1.625` | `leading-relaxed` |

### 字間（Letter Spacing）

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

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `tight` | `-0.025em` | `tracking-tight` |
| `normal` | `normal` | `tracking-normal` |
| `wide` | `0.05em` | `tracking-wide` |
| `wider` | `0.1em` | `tracking-wider` |

### フォントファミリー

| トークン | スタック | 使用例 |
|-------|-------|---------|
| `sans` | システムサンセリフスタック | `font-sans` |
| `mono` | システムモノスペーススタック | `font-mono` |

```html
<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）

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `DEFAULT` | `0.25rem` (4px) | `rounded` |
| `lg` | `0.5rem` (8px) | `rounded-lg` |
| `full` | `9999px` | `rounded-full` |

```html
<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>
```

## ブレークポイント

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `sm` | `640px` | `sm:flex` |
| `lg` | `1024px` | `lg:grid-cols-2` |
| `xl` | `1280px` | `xl:max-w-[80rem]` |

```html
<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 を使ってください。

| トークン | 値 | 使用例 |
|-------|-------|---------------|
| `content` | `0` | `z-content` |
| `local-1` | `1` | `z-local-1` |
| `local-2` | `2` | `z-local-2` |
| `local-3` | `3` | `z-local-3` |
| `sidebar` | `10` | `z-sidebar` |
| `toolbar` | `20` | `z-toolbar` |
| `dropdown` | `30` | `z-dropdown` |
| `popover` | `40` | `z-popover` |
| `modal-backdrop` | `50` | `z-modal-backdrop` |
| `modal` | `60` | `z-modal` |
| `toast` | `70` | `z-toast` |
| `tooltip` | `80` | `z-tooltip` |
| `drag` | `90` | `z-drag` |

## カラー

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

カラートークンシステム、カラースキーム、カスタマイズの詳細は[カラーリファレンス](https://zudo-doc.takazudomodular.com/ja/docs/reference/color)を参照してください。

## 別の `@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を共有するページでは生成ルールと最終的に適用される宣言を確認してください。

## 使用ルール

[Dynamic content unavailable in text export]

カスタムプロパティは値を供給し、wind設定はユーティリティ名を登録します。トークンや手書きクラスを追加したときは生成CSSを確認してください。



### 推奨

```html
<!-- 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>
```

### 非推奨

```html
<!-- 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**（ナビゲーション用のリンク）：

```html
<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 が欠けている）：

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

**NG**（コントロール）：

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