静的なトークンダッシュボード

共有する tabs を Preact の TokenDashboard に渡して、通常のページにトークン一覧を表示します。

Preact の名前付きエクスポート TokenDashboard を使うと、ドキュメントのページ内に トークン一覧を表示できます。同じ tabs データをパネルと読み取り専用ページで共有します。 静的サイトではビルド時にレンダリングし、ダッシュボードを hydrate せずに HTML と CSS を配信できます。

ビルド時にも読めるトークン定義にする

タブ定義を、型だけを import するデータモジュールに切り出します。 ダッシュボードのページからは、このモジュールを直接 import します。 configurePanel()、ブラウザーのグローバル変数、ストレージへのアクセス、 ホストアダプターの import は、パネル用のブラウザーエントリーに置いてください。

// token-tabs.ts — data only; safe to import during a site build.
import type { TabConfig } from '@takazudo/zdtp/dashboard';

export const tokenTabs: readonly TabConfig[] = [{
  id: 'space',
  label: 'Spacing',
  tiers: [{
    id: 'scale',
    label: 'Scale',
    preview: 'bar',
    items: [{
      id: 'space-md',
      cssVar: '--site-space-md',
      label: 'Medium',
      default: '1rem',
      type: { kind: 'length', step: 0.25, unit: 'rem' },
    }],
  }],
}];

既存の PanelConfig の tabs にも tokenTabs を渡します。 共有するのはソースの定義であり、パネルの実行中の状態との接続ではありません。

Preact のページとしてレンダリングする

Preact をレンダリングできるホストを使い、必要に応じて TSX の jsxImportSource を "preact" に設定します。ZDTP は Preact を通常の依存関係として持ちますが、ホスト自身の JSX／SSR コード用にはホスト側でも Preact を宣言します。 ダッシュボードの import はパネルを初期化せず、パネル用のスタイルシートも必要としません。

// TokenPage.tsx — ordinary Preact TSX, rendered by your static host.
import { TokenDashboard } from '@takazudo/zdtp/dashboard';
import { tokenTabs } from './token-tabs';

export default function TokenPage() {
  return <TokenDashboard tabs={tokenTabs} mode="light" title="Site tokens" />;
}

静的なページにクライアントアイランドは不要です。Preact のサーバーレンダラーを 直接使うホストなら、通常のビルド処理の中で preact-render-to-string により このコンポーネントをレンダリングできます。このパッケージが提供するのはコンポーネントで、 HTML 書き出し用の API や CLI ではありません。React アダプターは今回の対象外です。

独立したスタイルシートを読み込む

コンポーネントの JavaScript は CSS を import しません。 @takazudo/zdtp/dashboard/styles.css を、ホストの CSS 処理を通じて一度読み込みます。 静的ホストでも利用しやすい方法は、ビルド時にパッケージの公開エクスポートを 公開アセットのディレクトリへコピーし、ページの head からリンクすることです。

// scripts/copy-dashboard-css.mjs — run before your site build.
import { copyFile, mkdir } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';

await mkdir('public/vendor', { recursive: true });
await copyFile(
  fileURLToPath(import.meta.resolve('@takazudo/zdtp/dashboard/styles.css')),
  'public/vendor/zdtp-dashboard.css',
);

<link rel="stylesheet" href="/vendor/zdtp-dashboard.css" />

コピー用スクリプトはホストプロジェクトのルートで実行します。 public/ と URL は、フレームワークやデプロイ先のベースパスに合わせてください。 プレイグラウンドでは、ビルドフックで静的ビルド時と開発サーバー起動時にコピーします。 ページは通常のスタイルシートリンクを使うため、JavaScript を無効にしてもスタイルが適用されます。

JavaScript の import から CSS を出力するバンドラーでは、代わりにレイアウトや スタイル用エントリーで次のように読み込めます。

import '@takazudo/zdtp/dashboard/styles.css';

すべての静的ホストがこの副作用 import に対応するとは限りません。 グローバル CSS だけを処理するホストでは、その処理系が解決できる CSS の @import、 または上記の明示的なコピーとリンクを使い、出力された HTML と CSS を確認してください。

ホストのテーマに外観を合わせる

ホスト側で祖先要素に color-scheme を設定すると、枠・背景・ラベルなどがその設定に 従います。たとえば、アプリのテーマ切り替えで html の data-theme を更新します。

html { color-scheme: light; }
html[data-theme='dark'] { color-scheme: dark; }

<TokenDashboard tabs={tokenTabs} chrome="host" mode="light" title="Light inventory" />
<TokenDashboard tabs={tokenTabs} chrome="host" mode="dark" title="Dark inventory" />

ダッシュボードはメディアクエリーを使わないため、アプリで明示的に選んだテーマが OS の設定より優先されます。枠やラベルは専用の CSS カスタムプロパティを使い、 一覧のトークンを参照しません。省略時の chrome="light" はライト表示に固定され、 chrome="dark" はホストの設定にかかわらずダーク表示になります。

mode は引き続き、宣言されたモード別の既定値と見本内の color-scheme を選びます。 ホストと一覧のモードは独立しているため、ホスト light × 一覧 light、ホスト light × 一覧 dark、ホスト dark × 一覧 light、ホスト dark × 一覧 dark の4通りを表示できます。 デモの「Dark host」を 切り替えると、2つの一覧で4通りを確認できます。この切り替えは CSS だけで動作します。

Chrome とモード対応行の両方をページに従わせる 1 つの一覧には、両方の prop へ host を指定します。

<TokenDashboard
  tabs={tokenTabs}
  chrome="host"
  mode="host"
  title="ページに従う一覧"
  id="page-following"
/>

4 つの公開 Chrome 入力は祖先に設定できるため、兄弟のインスタンスを変えずに 1 つだけ カスタムパレットへ変更できます。

<div style="--zdtp-dashboard-light-bg: #fff7ed; --zdtp-dashboard-light-fg: #7c2d12; --zdtp-dashboard-dark-bg: #1c1917; --zdtp-dashboard-dark-fg: #fed7aa">
  <TokenDashboard tabs={tokenTabs} chrome="host" mode="host" title="暖色のダッシュボード Chrome" />
</div>

入力は --zdtp-dashboard-light-bg、--zdtp-dashboard-light-fg、 --zdtp-dashboard-dark-bg、--zdtp-dashboard-dark-fg です。ダッシュボードはこれらを 継承値として保持し、背景、前景、ミュート色、ボーダー、カード、診断、サンプル面を light-dark() と color-mix() で派生させます。ルートは透明なので、周囲の面はホストページが管理します。

両モードを表示する・一部を埋め込む

mode="light" と mode="dark" のインスタンスを並べてレンダリングできます。 各プレビューのスコープは独自の color-scheme と CSS 変数の宣言を持ち、 :root を書き換えません。省略時のモードは light です。 任意の id を指定する場合は、呼び出し元で重複しない値を管理します。ID の自動生成はありません。

小さな一覧を埋め込む場合は、タブデータの一部を渡してホスト側の幅を制限します。 参照トークンが依存するティアも含めてください。参照先がなければ、サンプルの代わりに 診断メッセージが表示されます。デモには 両モードの全一覧と、幅を絞ったスペーシング一覧があります。

3 つの絞り込みインスタンスを組み合わせる

モード依存性は、モード依存の行を参照する行も含めて行単位で計算されます。 そのため、混在するティアも分割後は両リージョンに現れます。2 つのモードのスナップショットと 共有セクションを 1 つのコンパクトな一覧にする場合は、依存行をモードごとに 1 回ずつ、独立行を 全体で 1 回レンダリングします。

<TokenDashboard
  tabs={tokenTabs}
  mode="light"
  include="mode-dependent"
  title="ライト依存トークン"
  id="tokens-light"
/>
<TokenDashboard
  tabs={tokenTabs}
  mode="dark"
  include="mode-dependent"
  title="ダーク依存トークン"
  id="tokens-dark"
/>
<TokenDashboard
  tabs={tokenTabs}
  chrome="host"
  include="mode-independent"
  title="共有トークン"
  id="tokens-shared"
/>

モード依存行は最初の 2 インスタンスにそれぞれ 1 回ずつ現れ、独立行は 3 つ目に全体で 1 回だけ現れます。サブセットを作るときは、同じデータに参照先のティアも含めてください。 非表示の宣言は表示中のエイリアスを解決するために保持されます。

既存のプレビュー情報には TierConfig.preview を使います。 テキストエディターで編集する色や影には、previewOverrides で CSS 変数ごとに 表示方法を指定できます。別のマニフェストを作る必要はありません。

<TokenDashboard
  tabs={tokenTabs}
  previewOverrides={{
    // These keys must match variables in your tabs.
    '--site-accent': 'color',
    '--site-card-shadow': 'shadow',
  }}
/>

好きな文章を見本にする

余白は実寸の定規、パレットのティアは色見本をまとめた表示になります。 文字の見本は横長の行なので、折り返しや行間を比較できます。 好きな文章をビルド時に渡してください。

<TokenDashboard
  tabs={[...tokenTabs, {
    id: 'type', label: 'Typography', tiers: [{
      id: 'body-size', label: 'Body size', preview: 'size', items: [{
        id: 'body', label: 'Body', cssVar: '--site-body-size', default: '18px',
        type: { kind: 'length', step: 1, unit: 'px' },
      }],
    }],
  }]}
  previewText={'A quiet page gives each sentence room to breathe.\n\n好きな文章で、文字の大きさと行間を確かめましょう。'}
/>

編集欄ではなく静的な prop です。省略すると長めの英語・日本語の文章を使い、 previewText="" なら空の見本を保ちます。フォントはローカルの利用可能なものと CSS のフォールバックを使います。定規は非負の px/rem、ゼロ、解決できる直接の エイリアスに対応し、未対応の長さは推測した図を出さず値を残します。 大きな定規やパレットは内部でスクロールし、キーボードでフォーカスできます。 グループ化、文字見本の基準、プレビューの制約は リファレンスをご覧ください。

このページで確認できるもの

一覧が表示するのは、アイテムの既定値、モード別の colorExtras.semanticDefaults、 明示的な baseDefaults による宣言済みの既定値です。 参照行には宣言元の値と、対応する CSS や参照先のテキストを表示します。 名前付きカラースキームのプリセット、パネルの初期化処理、保存済みの編集は適用しないため、 パネルの初期値や現在値とは異なる場合があります。ピル付きの行も customDefault へ置き換えず、 auto などの特別値を含めて item.default を保持します。

calc()、var()、light-dark() などは式のまま表示します。 サンプルはブラウザーの実際の CSS コンテキストを使うため、すべてのホストで同じピクセル寸法、 インストール済みフォント、解決済みの色になるという保証ではありません。 外部変数の不足など、コンテキストに依存する値も診断とともに読める形で残します。 曖昧な参照、循環、参照先の欠落、安全に扱えない宣言には、誤解を招くサンプルを表示しません。 任意の Notes HTML や URL・マスク用のアセットは表示・読み込みしません。

公開 props とプレビューの挙動はダッシュボードのリファレンス、 共有するデータ型はトークンマニフェストのリファレンスをご覧ください。