zudo-docは、レイアウトおよびコンテンツのコンポーネントを`@takazudo/zudo-doc`パッケージから提供しています。これらのコンポーネントはzudo-windユーティリティクラスをハードコードしており、ドキュメントページのタイトルは文字どおり`<h1 class="text-heading font-bold">`です。配布されるコンポーネントとしてはこれが正しい設計ですが（[コンポーネントファースト戦略](https://zudo-doc.takazudomodular.com/ja/docs/reference/component-first)を参照）、利用者には次の疑問が残ります。自分の持ち物ではないコンポーネントを、どうやって再スタイリングするのか？

その答えが`--zdc-*`**コンポーネントトークン**です。これはパッケージが「サポート対象の上書き接合点」として公開している、小さく厳選されたCSSカスタムプロパティの集合です。自分の`:root`でいずれか1つを再定義すれば、該当するコンポーネントがすべてのルートで再スタイリングされます。`!important`もイジェクトも不要です。

## コンポーネントライブラリの所有権の逆転

通常のコンポーネントファーストの指針はこうです。_コンポーネント自体が抽象である。だから別の見た目が欲しければコンポーネントを変更すればよい。_ これはコンポーネントが自分のものであれば成り立ちます。しかしここではそうではありません。コンポーネントは`node_modules/@takazudo/zudo-doc`の中にあります。これを編集するということは、コンポーネント全体をフォークまたはイジェクトすることを意味し、外側から上書きしようとすれば、レイヤー化されていないzudo-windユーティリティの詳細度と`!important`で戦うことになります。どちらも好ましくない選択肢です。

そこで結論が逆転します。コンポーネントのファイルを編集できないとき、**コンポーネントトークンこそがあなたの作業範囲になる**のです。コンポーネントの内部に手を入れるのではなく、コンポーネントがすでに読み取っている値を再定義します。コンポーネントファーストの原則はパッケージ内部では依然として有効であり、`--zdc-*`という接合点は、その原則が外側に向けて公開している継ぎ目にすぎません。

[Dynamic content unavailable in text export]

これは「コンポーネントファーストだからコンポーネントトークンは不要」という考え方の逆です。その近道は、コンポーネントを自分が所有していることを前提にしています。自分の所有物ではないパッケージ化されたコンポーネントにとって、コンポーネントトークンは唯一のクリーンな上書きポイントです。だからこそ、カスタマイズはまさにそこに置かれるべきなのです。



## 1行で上書きする

すべての`--zdc-*`トークンは同じ方法で再定義します。`:root`で宣言するだけです。インポートするAPIも、ラップするコンポーネントも、実行するビルドステップもありません。

```css title="src/styles/global.css"
:root {
  --zdc-doc-title-font: "Georgia", serif;
  --zdc-doc-title-weight: 800;
}
```

この1ブロックだけで、すべてのページ — ドキュメントページ、ホームページ、タグページ、バージョンページ — のタイトル`<h1>`が再ブランディングされます。`:root`はグローバルであり、背後のルールはレイヤー化されておらず、コンポーネント自身のユーティリティクラスを上回る十分な詳細度を持っているためです。`!important`は必要なく、パッケージのソースに触れることもありません。

デフォルト値は意図的に「見えない」ように作られています。各トークンは既存のデザイントークンまたは`inherit`にフォールバックします（たとえば`--zdc-doc-title-weight`は元の`font-bold`ユーティリティに対応する`var(--font-weight-bold)`がデフォルトです）。そのため、何も上書きしないプロジェクトは従来とバイト単位で同一にレンダリングされます。実際に変更したいトークンだけを選んで有効化する仕組みです。

## 3層トークン戦略における位置づけ

zudo-docのトークンは3つの層に整理されており、各層は1つ上の層のみを参照します。生の**パレット**値（Tier 1）が**セマンティック**トークン（Tier 2）に流れ込み、それが**コンポーネント**トークン（Tier 3）に供給されます。全体像は[デザインシステム](https://zudo-doc.takazudomodular.com/ja/docs/reference/design-system)と[カラー](https://zudo-doc.takazudomodular.com/ja/docs/reference/color)を参照してください。

`--zdc-*`トークンはTier 3 — コンポーネントスコープです。ただし`.zd-content`内部のTier 3カラー変数（参照すべきでない非公開の実装詳細）とは異なり、`--zdc-*`トークンは**公開APIとして提供されています**。つまり、再定義することを前提とした、安定したドキュメント化済みの名前です。これらは、カラーシステムがすでに採用している実績あるパターンを拡張したものです。カラーシステムでは`:root`で`--zd-*`パレットトークンを再定義するとサイト全体のテーマが切り替わります。`--zdc-*`は、その1行で完結する`:root`上書きモデルをコンポーネントタイポグラフィにもたらします。

## トークンリファレンス

以下の表は、すべての`--zdc-*`トークンの一覧です。レジストリから直接生成しているため、パッケージが配布する内容と常に一致します。

トークンは**レンダリングサーフェス**によって分かれています。コンテンツトークンは`.zd-content`プロズ領域を対象とし（`@takazudo/zudo-doc/content.css`として配布）、クロームトークンはアプリシェル（ドキュメントの body、ヘッダー、サイドバーナビゲーション、目次、カードグリッド）を対象とします（`@takazudo/zudo-doc/features.css`として配布）。

### コンテンツトークン

| Token | Component | Default | What it controls |
| --- | --- | --- | --- |
| `--zdc-doc-title-font` | `doc-title` | `inherit` | Font family of the page-title `<h1>` (doc-page titles plus the home, tag, and versions page titles that share `text-heading`). |
| `--zdc-doc-title-weight` | `doc-title` | `var(--font-weight-bold)` | Font weight of the page-title `<h1>`. |
| `--zdc-doc-title-tracking` | `doc-title` | `var(--tracking-normal)` | Letter spacing of the page-title `<h1>`. Defaults to `var(--tracking-normal)` (resolves to `normal` — byte-identical to the browser default). |
| `--zdc-doc-h2-font` | `heading-h2` | `inherit` | Font family of content `<h2>` headings. |
| `--zdc-doc-h2-weight` | `heading-h2` | `var(--font-weight-bold)` | Font weight of content `<h2>` headings. |
| `--zdc-doc-h2-tracking` | `heading-h2` | `var(--tracking-normal)` | Letter spacing of content `<h2>` headings. |
| `--zdc-doc-h3-weight` | `heading-h3` | `var(--font-weight-bold)` | Font weight of content `<h3>` headings. |
| `--zdc-doc-h4-weight` | `heading-h4` | `var(--font-weight-semibold)` | Font weight of content `<h4>` headings. |
| `--zdc-doc-prose-font` | `doc-prose` | `var(--font-sans)` | Font family of the `.zd-content` prose area. Redefine to use a distinct body font for doc content; headings with `--zdc-doc-*-font: inherit` inherit this value. |
| `--zdc-doc-link-decoration` | `content-link` | `underline` | Text decoration of prose links only — the `text-accent underline` path in ContentLink (`a.text-accent.underline`); excludes block and hash-link variants and never matches chrome links, including the underlined home hero and footer copyright rows (those are `text-fg`). Set to `none` to remove underlines from prose links. |
| `--zdc-admonition-radius` | `admonition` | `0 var(--radius-DEFAULT) var(--radius-DEFAULT) 0` | Border radius of admonition/callout blocks. Defaults to the current value (0 on the left edges, `--radius-DEFAULT` on the right — the flush-left accent look). |
| `--zdc-admonition-border-width` | `admonition` | `4px` | Width of the admonition left accent border. |

### クロームトークン

| Token | Component | Default | What it controls |
| --- | --- | --- | --- |
| `--zdc-card-radius` | `card-grid` | `var(--zdc-surface-radius, var(--radius-DEFAULT))` | Border radius of nav/doc card anchors (doc-card-grid, nav-card-grid, category-nav). Chains through `--zdc-surface-radius` — see below. |
| `--zdc-content-max-width` | `doc-content-band` | `clamp(50rem,75vw,90rem)` | Max width of the doc reading column (sidebar-present case). The no-sidebar 80 rem variant is handled separately by `[data-zd-nosidebar]` in features.css. |
| `--zdc-toc-width` | `toc` | `280px` | Width of the desktop Table of Contents right rail. |
| `--zdc-nav-active-indicator-color` | `nav-active` | `var(--color-fg)` | Background color of the active sidebar nav link (the inversion fill that marks the current page). |
| `--zdc-nav-active-weight` | `nav-active` | `var(--font-weight-medium)` | Font weight of the active sidebar nav link. |
| `--zdc-chrome-font` | `chrome` | `var(--font-sans)` | Base font family of the document `body` — the seam that lets a theme pack's `--font-sans` reach the whole app shell (header, sidebar, TOC, breadcrumb, footer), not just `.zd-content` prose. Redefine `--font-sans` to restyle chrome and content together, or `--zdc-chrome-font` directly to move the shell independently of prose. |
| `--zdc-header-font` | `header` | `var(--zdc-chrome-font, var(--font-sans))` | Font family of the site header (`header[data-header]`). A no-op until redefined; set it to give the header its own face (for example a display font for the wordmark and nav) without touching the rest of the chrome. |
| `--zdc-header-logo-font` | `header-logo` | `inherit` | Font family of the site-name anchor (`a[data-header-logo]`) only. Theme packs with explicit logo fonts preserve their existing family as fallback. |
| `--zdc-header-logo-weight` | `header-logo` | `var(--font-weight-bold)` | Font weight of the site-name anchor only. Theme packs with explicit logo weights preserve their existing weight as fallback. |
| `--zdc-sidebar-font` | `sidebar` | `var(--zdc-chrome-font, var(--font-sans))` | Font family of the navigation sidebar. The selector names both the desktop rail (`#desktop-sidebar`) and the mobile drawer (`aside[data-zd-mobile-sidebar]`) — 本番ビルドでは両方に一致します（詳細は表の下の注記を参照）。 |
| `--zdc-toc-font` | `toc` | `var(--zdc-chrome-font, var(--font-sans))` | Font family of the table of contents. The selector names both the desktop rail (`nav[data-zd-toc]`) and the mobile TOC (`div[data-zd-mobile-toc]`) — 本番ビルドでは両方に一致します（詳細は表の下の注記を参照）。 |

[Dynamic content unavailable in text export]

`--zdc-sidebar-font`と`--zdc-toc-font`は、すべてのパックが設定すべきトークンではなく、オプションのサーフェスごとのアートディレクション用フックです — クロームフォントシーム（`--zdc-chrome-font`、デフォルトは`--font-sans`）だけで、シェル全体に一貫したひとつの書体を届けられ、これは同梱されているすべてのテーマパックが望んでいることです。これらのトークンに手を伸ばすのは、パックがサイドバーまたは目次だけを他のクロームとあえて異なる書体にしたい場合に限られます。

コンポーネントのセレクターはデスクトップとモバイルのクロームを対象にします。ビルドしたページと繰り返しのクライアントナビゲーションで computed value を確認してください。実効的な identity と props が変わらないアイランドは保持され、変更時は描画スコープが再作成されます。



### ワードマークのタイポグラフィ

ロゴトークンはサイト名だけを変更し、ナビゲーション、検索、言語切り替えの書体は維持します。デフォルトテーマはヘッダーの書体を継承し、`--font-weight-bold`を使用します。同梱パックは上書きするまで各パックのロゴ書体とウェイトを維持します。各トークンは独立して使用でき、宣言を削除するとテーマのフォールバックに戻ります。

```css title="src/styles/global.css"
:root {
  --zdc-header-logo-font: "Georgia", serif;
  --zdc-header-logo-weight: 400;
}
```

### `--zdc-surface-radius` メタノブ

`--zdc-surface-radius`は**レジストリのエントリではありません** — それ自体の背後にあるCSSルールは存在しません。`--zdc-card-radius`のデフォルトチェーンの中にリンクとして存在します：

```
var(--zdc-card-radius, var(--zdc-surface-radius, var(--radius-DEFAULT)))
```

`:root`で`--zdc-surface-radius`を設定すると、このチェーンに参加しているすべてのサーフェスが一度に角丸になります — 各トークンを個別に上書きする必要がありません：

```css title="src/styles/global.css"
:root {
  --zdc-surface-radius: 0.75rem; /* rounds all surfaces at once */
}
```

これは「すべてをまとめて角丸にする」ノブです。個別のサーフェスは、それぞれの`--zdc-card-radius`（または将来のサーフェストークン）を直接設定することで個別に上書きできます。メタノブが有効なのは、サーフェスごとのトークンが未設定の場合のみです。

[Dynamic content unavailable in text export]

フォントファミリー（`-font`）、フォントウェイト（`-weight`）、レタースペーシング（`-tracking`）は、単一の`font`ショートハンドにまとめず、粒度の細かい別々のトークンとして保持しています。CSSの`font`ショートハンドは、明示しなかったサブプロパティ（サイズ、行の高さ、スタイル）をすべてリセットしてしまいます。これではバイト単位で同一のデフォルトが壊れるうえ、制御の幅も狭まります — ファミリーとサイズを書き直さずにウェイトだけを変えることができなくなるのです。独立したつまみは、独立したトークンのままにしてあります。



## Design Token Panelでは編集できない

これらは**ソースレベルの上書き接合点**であり、リアルタイムに調整する値ではありません。

[Dynamic content unavailable in text export]

[Design Token Panel](https://zudo-doc.takazudomodular.com/ja/docs/reference/design-token-panel)は、セマンティックなスペーシング・フォント・サイズ・カラーのトークンをブラウザ上でライブ編集します。`--zdc-*`コンポーネントトークンは、意図的にその対象外です。これらはコンポーネントが所有する再ブランディングの接合点であり、`:root`（`src/styles/global.css`内）で一度設定するものであって、実行時にドラッグして調整するつまみではありません。パネルでトークンを探しても見つからない場合、それはコンポーネントトークンです。スタイルシートで設定してください。



## 全トークンの確認方法

上の表を支えるレジストリが、型付けされた信頼できる情報源です。これはパッケージから`@takazudo/zudo-doc/component-tokens`（`COMPONENT_TOKENS`配列）としてエクスポートされており、完全で最新の一覧 — トークン名、コンポーネント、デフォルト値、説明 — がこのページだけでなくコード上でも型チェック付きで確認できます。パッケージが新しいコンポーネントトークンを追加すると、そのエクスポートに反映され、このリファレンスもそこから再生成されます。