パネル CSS トークン

--tokentweak-* プライベート変数、panel-tokens.css に組み込まれた自己完結型のダークパレット、モーダルのデータ属性セレクター、ホストアダプターのインポート要件。

パネルには独自の CSS がバンドルされています。利用側で Tailwind に依存することも、ホストの --color-* テーマを読み取ることもありません。このページでは、パネル専用の --tokentweak-* 名前空間、パネルが描画に使用する自己完結型のダークパレット、バンドル済みスタイルシートのモーダルセレクター契約、ホストレイアウト用の dock 変数、別の chrome テーマを求めるホスト向けのパネル専用オーバーライド範囲を明確にします。

パネル専用の名前空間

バンドル済みのスタイルシートは、パネル chrome のすべての変数をパネル専用の名前空間で宣言し、パネルシェル、モーダルのデータ属性、body レベルの機能サーフェスにスコープします。

:where(
  .tokenpanel-shell,
  .tokenpanel-mini-pill,
  [data-design-token-panel-modal],
  .tokenpanel-highlight-settings-popover,
  .tokenpanel-chain-popover,
  .tokenpanel-color-picker,
  .tokenpanel-tooltip,
  .tokenpanel-elpath-label,
  .tokenpanel-elpath-toast,
  .tokenpanel-element-inspect-box,
  .tokenpanel-element-inspect-label,
  .tokenpanel-element-inspect-view
) {
  --tokentweak-pad-md: 12px;
  --tokentweak-gap-sm: 20px;
  --tokentweak-text-body: 19px;
  --radius-tokentweak: …;
  /* …every panel-chrome value lives here */
}

命名規則

• パネル専用の色、フォント、スペーシング、タイポグラフィ、z-index 変数には --tokentweak-* プレフィックスを使用します。共有の角丸トークンには既存の --radius-tokentweak 名を使用します。利用側の名前空間に属する識別子をパネル chrome に含めてはいけません。

• chrome のスタイルシート（panel.css）は、パッケージ所有のトークン（--tokentweak-*、--radius-tokentweak、--tokenpanel-grid-min のようなコンポーネントローカルのレイアウトヒント）だけを読み取る必要があります。--color-* や --font-mono のようなホスト変数を直接読み取ってはいけません。

• トークンシート（panel-tokens.css）は --tokentweak-* の値を具体的な色として宣言し（var(--color-*) は読み取りません）、ホストテーマの変更がパネル chrome へ入り込まないようにします。下記の自己完結型パレットを参照してください。

• ホストレイアウトとの連携用変数は、別の --zdtp-dock-inset-* 名前空間を使用します。これらは dock の claim が有効な間だけ document root に書き込まれ、パネル chrome のテーマ変更用フックではありません。

ファイル

• panel.css — chrome のレイアウト／タイポグラフィ／コントロール。

• panel-tokens.css — --tokentweak-* の宣言。

どちらもパッケージから提供され、Vite のライブラリビルドによって単一の dist/zdtp.css にまとめられます。CSS は ?inline インポートを通じて文字列として dist/index.js にも埋め込まれ、パネルを初めてマウントしたときに <style> 要素として自動的に挿入されます。利用側がスタイルシートを手動でインポートする必要はありません。

./styles サブエクスポート（別名 ./styles.css）は dist/zdtp.css に解決されます。CSS を自身のパイプラインへ含めたい利用側のために、任意の明示的インポートとして引き続き利用できます（SSR hydration、PostCSS、バンドラーによる重複排除など）。

// Optional — only needed to pull CSS into your own pipeline
import '@takazudo/zdtp/styles';

モーダルクラスのプレフィックスとデータ属性セレクター

PanelConfig.modalClassPrefix は、パネルが所有するすべてのモーダル（エクスポート、インポート、適用）の BEM ルートを制御します。ホストが任意の文字列を選ぶと、パネルは ${modalClassPrefix}__overlay、${modalClassPrefix}__panel、${modalClassPrefix}__header などのクラスを出力します。

バンドル済み CSS がキーにするのはデータ属性であり、クラスのプレフィックスではありません。 すべてのモーダル <dialog> 要素は data-design-token-panel-modal="" を出力します（data-design-token-panel-modal-variant には "apply" / "export" / "import" を設定します）。panel.css は、すべてのモーダル chrome のルールを [data-design-token-panel-modal] にアンカーし、[class*='__title'] のような属性セレクターで子要素に一致させます。

このため、ホストが modalClassPrefix をカスタマイズしても、バンドル済みの chrome が引き続き適用されます。リテラルのクラスプレフィックスをセレクターに使うと、デフォルト以外のホストではモーダルにスタイルが適用されません。

クラスプレフィックスは、バンドル済みの chrome の上に独自のルールを重ねたいホストにとって、詳細度の高いフックとして引き続き役立ちます。

自己完結型のパネル chrome パレット

パネル chrome のカラートークンは、panel-tokens.css でプライベートな OKLCH ランプへのセマンティックエイリアスとして宣言されています。パネルは、ホストの --color-* / --font-mono テーマを一切読み取りません。ホストテーマの変更（デモ内でこのパネル自身を使って行ったテーマ調整も含む）が、パネル chrome へ入り込むことはありません。

:where(.tokenpanel-shell, [data-design-token-panel-modal]) {
  /* base-0 は最も暗い地色で、前景に向かって明るくなります。 */
  --tokentweak-palette-base-0: oklch(0.18 0 0);
  --tokentweak-palette-base-1: oklch(0.25 0 0);
  --tokentweak-palette-base-2: oklch(0.34 0 0);
  --tokentweak-palette-base-3: oklch(0.536 0 0);
  --tokentweak-palette-base-4: oklch(0.66 0 0);
  --tokentweak-palette-base-5: oklch(0.8 0 0);
  --tokentweak-palette-base-6: oklch(0.91 0 0);
  --tokentweak-color-fg: var(--tokentweak-palette-base-5);
  --tokentweak-color-bg: var(--tokentweak-palette-base-0);
  --tokentweak-color-muted: var(--tokentweak-palette-base-4);
  --tokentweak-color-border: var(--tokentweak-palette-base-3);
  --tokentweak-color-surface: var(--tokentweak-palette-base-1);
  --tokentweak-color-accent: #d69a66;
  --tokentweak-color-accent-bar: #efb477;
  --tokentweak-color-accent-hover: #a7c0e3;
  --tokentweak-color-code-bg: var(--tokentweak-palette-base-2);
  --tokentweak-color-code-fg: var(--tokentweak-palette-base-6);
  --tokentweak-color-success: #93bb77;
  --tokentweak-color-danger: #da6871;
  --tokentweak-color-warning: #dfbb77;
  --tokentweak-font-mono: Menlo, Monaco, Consolas, 'Liberation Mono',
    'Courier New', monospace;
}

このパレットは、ターミナル風の「Default Dark」スキームを踏襲しています。無彩色のニュートラルカラーに暖色のアクセントと寒色のホバーアクセントを組み合わせることで、どのようなホストの背景上でも、パネルが独立したダークサーフェスとして見えるようにしています。非公開の --tokentweak-palette-base-0 から --tokentweak-palette-base-6 までのランプは、最も暗い地色から明るい順に並び、以下のセマンティックカラーロールは各段階を参照します。

公開範囲

ホストは、パネル chrome のテーマを変更するために、同じスコープ上で次のパネル専用変数をオーバーライドできます。

ホスト向けのオーバーライド範囲

別の chrome テーマを使いたいホストは、.tokenpanel-shell、[data-design-token-panel-modal]、または任意の祖先要素で --tokentweak-* 名へ直接値を割り当てます（パネルのスコープは :where() を使用するため詳細度は 0 です）。

:root {
  --tokentweak-color-bg: #102030;
  --tokentweak-color-fg: #eef;
  --tokentweak-color-accent: #ffb74d;
}

これが、パネル chrome に関するホストのオーバーライド契約のすべてです。--color-* と --font-mono はオーバーライド範囲に含まれません。ホストページ上でこれらへ値を割り当てても、パネルには影響しません。

ホストは --tokentweak-palette-base-* の各段階をオーバーライドし、その段階を参照するすべてのセマンティックロールをまとめて変更することもできます。パネルのデフォルトは詳細度 0 の :where() で定義されるため、--tokentweak-color-* への直接指定は引き続き優先されます。--tokentweak-color-muted が影響するのは補助テキストだけになりました。これまでこの変数でテキストと 1px の区切り線をまとめて変更していたホストは、--tokentweak-color-border も指定してください。

色以外のトークンスケールは具体的なピクセル値です。--tokentweak-pad-* は 2xs/xs/sm/md/lg/xl/2xl に対して 2/6/8/12/16/24/32px、--tokentweak-gap-* は同じ段階に対して 7/14/20/24/28/40/56px、--tokentweak-text-* は micro/caption/small/body/subheading/heading/display に対して 12/14/16/19/22/48/60px です。共有の角丸は --radius-tokentweak: 4px です。セマンティック z-index 値は、ランタイムが使う高い整数値域にある --tokentweak-z-overlay、shell、settings-popover、color-picker、tooltip、command-palette、inspector-box、toast として公開されます。

Dock とページ内 specimen の変数

dock モードでは、document.documentElement 上にホストレイアウト用変数を 1 つ公開します。

claim が解放されると、変数は以前のインライン宣言そのものへ復元されます。dock.reflow: 'body-margin' では対応する body margin も設定されます。'none' では body margin が復元される一方、claim の有効中は root 変数をホストのレイアウト CSS から引き続き利用できます。

ページ内 specimen はパネルシェルではなく、ホスト向けの .tokenpanel-on-page-specimen、.tokenpanel-on-page-specimen-heading、.tokenpanel-on-page-specimen-section、.tokenpanel-on-page-specimen-row クラスを使用します。ホストのフォントと前景色を継承し、背景には Canvas を使い、各 line-height サンプルにはインラインの --tokenpanel-specimen-line ガイド変数を付けます。specimen ノードには data-zdtp-specimen が付き、パネル所有の走査から除外されます。現在の実装は .zdtp-specimen クラスを出力しません。安定したセレクターとして、前述のクラスとデータ属性を使用してください。

不変条件 — パネルパッケージはホストテーマの変数を読み取ってはならない

panel.css と panel-tokens.css のどちらも、--color-* または --font-mono を参照してはいけません。パッケージの CI は grep チェックによってこれを固定します。

grep -n 'var(--color-' src/styles/panel.css        # → 0
grep -n 'var(--font-mono' src/styles/panel.css     # → 0
grep -n 'var(--color-' src/styles/panel-tokens.css # → 0
grep -n 'var(--font-mono' src/styles/panel-tokens.css # → 0

ホストアダプターの副作用インポート（対になる単位としての要件）

利用側は <DesignTokenPanelHost> と対になる、ホストアダプターの副作用インポートを所有する必要があります。パネルのエントリがスタイルシートを自己注入するため ./styles のインポートは任意であり、ホストが静的な CSS パイプラインを必要とする場合だけ使用します。コンポーネントと、@takazudo/zdtp/astro/host-adapter を読み込む同階層の <script> ブロックは 1 つの単位です。常に 2 行とも必要です。

必要な配線の形式は次のとおりです。

<DesignTokenPanelHost config={myPanelConfig} />

<script>
  void import('@takazudo/zdtp/astro/host-adapter');
</script>

動的な void import('...') を使う理由

どちらの形式も機能します。パッケージの package.json は dist/astro/host-adapter.js を sideEffects に列挙しているため、結果を使用するかどうかにかかわらず、Rollup は利用側によるホストアダプターのインポートを保持します。動的形式を推奨される標準の配線とするのは、ホストアダプターのチャンクをページ読み込みのクリティカルパス外で読み込み（既存の color-presets 遅延ローダーパターンを踏襲）、将来 sideEffects を誤設定する可能性があるパッケージング変更に対しても堅牢だからです。

ページ単位の静的インポートを 1 つだけ置かない理由

ブラウザーキャッシュにより、重複する import() のコストは小さくなります（セッションごとにネットワーク取得は 1 回）。また、ラッパーコンポーネントが唯一の正式なマウントポイントなので、そこでインポートが重複しても問題にはなりません。

省略するとどうなるか

このインポートを省略すると、<DesignTokenPanelHost> からの JSON 設定ペイロードを読み取る JS がないままページ上に残ります。そのため、window.<consoleNamespace>.showDesignPanel() を呼び出すと ReferenceError がスローされます。デプロイ済みビルドでの症状は、何も通知されないまま失敗し、パネル chrome が一切描画されないことです。

./astro/host-adapter サブエクスポートは、ビルド済みの dist/astro/host-adapter.js ファイルとその .d.ts 型を指します。

利用側が制御するトークン

パネルの書き込み先となるトークン（各 TierItem の cssVar フィールドに加え、カラータブのベースロール名とセマンティック名）は、すべて利用側が制御します。ホストは --myapp-spacing-hgap-md、--myapp-p0、--myapp-semantic-bg のような名前を自身で選び、パネルはデフォルトの :root sink または設定済みの applySink を通じて書き込みます。

したがって、パッケージの契約は次のようになります。

• 読み取り: パネルは自身の chrome のために利用側の CSS 変数を読み取りません（TierItem.default を通じてデフォルトを保持します）。

• 書き込み: パネルは、利用側が指定した cssVar 文字列と、カラータブの palette / base / semantic 変数だけを、有効な sink を通じて書き込みます。

関連リファレンス

• PanelConfig.modalClassPrefix — モーダルクラスの BEM ルート（バンドル済み CSS がキーにするのはデータ属性です）。

• Token manifest — パネルがデフォルトの root または設定済みの applySink へ書き込む cssVar 名を宣言します。

• Color cluster — apply 時にパネルが書き込む palette / base-role / semantic CSS 変数名を宣言します。