コンポーネントトークン
--zdc-* という上書きの接合点 — コンポーネントを直接編集せずにスタイル（タイポグラフィ・形状・レイアウト）を再ブランディングするための公開API。
zudo-docは、レイアウトおよびコンテンツのコンポーネントを@takazudo/zudo-docパッケージから提供しています。これらのコンポーネントはTailwindユーティリティクラスをハードコードしており、ドキュメントページのタイトルは文字どおり<h1 class="text-heading font-bold">です。配布されるコンポーネントとしてはこれが正しい設計ですが（コンポーネントファースト戦略を参照）、利用者には次の疑問が残ります。自分の持ち物ではないコンポーネントを、どうやって再スタイリングするのか？
その答えが--zdc-*コンポーネントトークンです。これはパッケージが「サポート対象の上書き接合点」として公開している、小さく厳選されたCSSカスタムプロパティの集合です。自分の:rootでいずれか1つを再定義すれば、該当するコンポーネントがすべてのルートで再スタイリングされます。!importantもイジェクトも不要です。
コンポーネントライブラリの所有権の逆転
通常のコンポーネントファーストの指針はこうです。コンポーネント自体が抽象である。だから別の見た目が欲しければコンポーネントを変更すればよい。 これはコンポーネントが自分のものであれば成り立ちます。しかしここではそうではありません。コンポーネントはnode_modules/@takazudo/zudo-docの中にあります。これを編集するということは、コンポーネント全体をフォークまたはイジェクトすることを意味し、外側から上書きしようとすれば、レイヤー化されていないTailwindユーティリティの詳細度と!importantで戦うことになります。どちらも好ましくない選択肢です。
そこで結論が逆転します。コンポーネントのファイルを編集できないとき、コンポーネントトークンこそがあなたの作業範囲になるのです。コンポーネントの内部に手を入れるのではなく、コンポーネントがすでに読み取っている値を再定義します。コンポーネントファーストの原則はパッケージ内部では依然として有効であり、--zdc-*という接合点は、その原則が外側に向けて公開している継ぎ目にすぎません。
Info
これは「コンポーネントファーストだからコンポーネントトークンは不要」という考え方の逆です。その近道は、コンポーネントを自分が所有していることを前提にしています。自分の所有物ではないパッケージ化されたコンポーネントにとって、コンポーネントトークンは唯一のクリーンな上書きポイントです。だからこそ、カスタマイズはまさにそこに置かれるべきなのです。
1行で上書きする
すべての--zdc-*トークンは同じ方法で再定義します。:rootで宣言するだけです。インポートするAPIも、ラップするコンポーネントも、実行するビルドステップもありません。
: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）に供給されます。全体像はデザインシステムとカラーを参照してください。
--zdc-*トークンはTier 3 — コンポーネントスコープです。ただし.zd-content内部のTier 3カラー変数（参照すべきでない非公開の実装詳細）とは異なり、--zdc-*トークンは公開APIとして提供されています。つまり、再定義することを前提とした、安定したドキュメント化済みの名前です。これらは、カラーシステムがすでに採用している実績あるパターンを拡張したものです。カラーシステムでは:rootで--zd-*パレットトークンを再定義するとサイト全体のテーマが切り替わります。--zdc-*は、その1行で完結する:root上書きモデルをコンポーネントタイポグラフィにもたらします。
トークンリファレンス
以下の表は、すべての--zdc-*トークンの一覧です。レジストリから直接生成しているため、パッケージが配布する内容と常に一致します。
トークンはレンダリングサーフェスによって分かれています。コンテンツトークンは.zd-contentプロズ領域を対象とし（@takazudo/として配布）、クロームトークンはアプリシェル（サイドバーナビゲーション、目次、カードグリッド）を対象とします（@takazudo/として配布）。
コンテンツトークン
| 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 styled content links (the text-accent underline path in ContentLink; excludes block and hash-link variants). Set to none to remove underlines from content 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-surface-radius メタノブ
--zdc-surface-radiusはレジストリのエントリではありません — それ自体の背後にあるCSSルールは存在しません。--zdc-card-radiusのデフォルトチェーンの中にリンクとして存在します：
var(--zdc-card-radius, var(--zdc-surface-radius, var(--radius-DEFAULT))):rootで--zdc-surface-radiusを設定すると、このチェーンに参加しているすべてのサーフェスが一度に角丸になります — 各トークンを個別に上書きする必要がありません：
:root {
--zdc-surface-radius: 0.75rem; /* すべてのサーフェスをまとめて角丸にする */
}これは「すべてをまとめて角丸にする」ノブです。個別のサーフェスは、それぞれの--zdc-card-radius（または将来のサーフェストークン）を直接設定することで個別に上書きできます。メタノブが有効なのは、サーフェスごとのトークンが未設定の場合のみです。
Tip
フォントファミリー（-font）、フォントウェイト（-weight）、レタースペーシング（-tracking）は、単一のfontショートハンドにまとめず、粒度の細かい別々のトークンとして保持しています。CSSのfontショートハンドは、明示しなかったサブプロパティ（サイズ、行の高さ、スタイル）をすべてリセットしてしまいます。これではバイト単位で同一のデフォルトが壊れるうえ、制御の幅も狭まります — ファミリーとサイズを書き直さずにウェイトだけを変えることができなくなるのです。独立したつまみは、独立したトークンのままにしてあります。
Design Token Panelでは編集できない
これらはソースレベルの上書き接合点であり、リアルタイムに調整する値ではありません。
Note
Design Token Panelは、セマンティックなスペーシング・フォント・サイズ・カラーのトークンをブラウザ上でライブ編集します。--zdc-*コンポーネントトークンは、意図的にその対象外です。これらはコンポーネントが所有する再ブランディングの接合点であり、:root（src/内）で一度設定するものであって、実行時にドラッグして調整するつまみではありません。パネルでトークンを探しても見つからない場合、それはコンポーネントトークンです。スタイルシートで設定してください。
全トークンの確認方法
上の表を支えるレジストリが、型付けされた信頼できる情報源です。これはパッケージから@takazudo/（COMPONENT_TOKENS配列）としてエクスポートされており、完全で最新の一覧 — トークン名、コンポーネント、デフォルト値、説明 — がこのページだけでなくコード上でも型チェック付きで確認できます。パッケージが新しいコンポーネントトークンを追加すると、そのエクスポートに反映され、このリファレンスもそこから再生成されます。