カラークラスター

カラータブが colorExtras を持つ TabConfig から ColorClusterDataConfig を派生させる方法、パレット + セマンティックティアモデル、ColorScheme、スキームプリセット。

カラータブ（パレット + ベースロール + セマンティックテーブル + スキームリスト）は、予約済み id 'color' を持つ TabConfig によって駆動されます。タブの tiers はパレットとセマンティックのデータを TierItem の配列として保持し、同じ TabConfig の colorExtras フィールドがティア以外のメタデータ（ベースロール、カラースキーム、パネル設定）を保持します。パネルは内部でこれを resolveColorClusterFromTab を介して ColorClusterDataConfig へブリッジします。

このページでは、カラータブの TabConfig 構造、ColorClusterExtras の形状、ColorScheme 型、マルチクラスターのサポート、そしてホスト提供のスキームプリセットについて説明します。

カラータブの TabConfig 構造

カラータブ用の TabConfig は、他のタブと同じ形状に従いますが、2 つの制約があります。

1. id は 'color'（プライマリ）または 'color-secondary'（セカンダリ）でなければなりません。

2. colorExtras が存在しなければなりません。カラーの apply パイプラインが必要とするティア以外のメタデータを保持します。

パレットティア

パレットティアは、アイテムがすべて type.kind === 'color' を持ち、referencesTier を持たない最初のティアです。各アイテムは 1 つのパレットスロットを表し、その cssVar は apply 時に書き込まれる CSS カスタムプロパティです（例: --myapp-palette-0）。

内部ブリッジは、最初のアイテムの cssVar の末尾の数字列を {n} に置き換えることで paletteCssVarTemplate を派生させます。

--myapp-palette-0  →  --myapp-palette-{n}

セマンティックティア

セマンティックティアは、referencesTier がパレットティアの id を指す最初のティアです。各セマンティックアイテムの default はパレットアイテムの id を保持し、その id を引くことでデフォルトのパレットインデックスが得られます。

ユーザーがセマンティックトークンをオーバーライドすると、apply パイプラインは参照先のパレットアイテムの cssVar を読み取り、そのセマンティックスロットに対して var(--that-cssVar) を出力します。

最小構成の例

import type { TabConfig } from '@takazudo/zdtp';

export const colorTab: TabConfig = {
  id: 'color',
  label: 'Color',
  tiers: [
    {
      id: 'palette',
      label: 'Palette',
      items: [
        { id: 'p0', cssVar: '--myapp-palette-0', label: 'P0', default: '#1a1a2e', type: { kind: 'color' } },
        { id: 'p1', cssVar: '--myapp-palette-1', label: 'P1', default: '#16213e', type: { kind: 'color' } },
        { id: 'p2', cssVar: '--myapp-palette-2', label: 'P2', default: '#0f3460', type: { kind: 'color' } },
        { id: 'p3', cssVar: '--myapp-palette-3', label: 'P3', default: '#e94560', type: { kind: 'color' } },
      ],
    },
    {
      id: 'semantic',
      label: 'Semantic',
      referencesTier: 'palette',
      items: [
        { id: 'bg',      cssVar: '--myapp-color-bg',      label: 'Background', default: 'p0', type: { kind: 'color' } },
        { id: 'surface', cssVar: '--myapp-color-surface',  label: 'Surface',    default: 'p1', type: { kind: 'color' } },
        { id: 'accent',  cssVar: '--myapp-color-accent',   label: 'Accent',     default: 'p3', type: { kind: 'color' } },
      ],
    },
  ],
  colorExtras: {
    id: 'myapp',
    baseRoles: { background: '--myapp-palette-0', foreground: '--myapp-palette-3' },
    baseDefaults: { background: 0, foreground: 3 },
    defaultShikiTheme: 'github-dark',
    colorSchemes: {
      'Default Dark': {
        background: 0, foreground: 3, cursor: 3, selectionBg: 2, selectionFg: 3,
        palette: ['#1a1a2e', '#16213e', '#0f3460', '#e94560'],
        shikiTheme: 'github-dark',
      },
    },
    panelSettings: {
      colorScheme: 'Default Dark',
      colorMode: false,
    },
  },
};

セマンティック専用ティア（semantic: true）

上記のパレットティアは構造的に検出されます。すなわち、referencesTier を持たず、アイテムが kind: 'color' である最初のティアです。このヒューリスティックは、番号付きのパレットスロットを一切持たず、名前付きセマンティックトークン（--zd-danger、--zd-warning、--zd-info など）だけを提供するデザインシステムでは破綻します。セマンティックティア自身の kind: 'color' アイテムが、不正なパレットと誤認されてしまうためです（issue #458）。

TierConfig.semantic: true を設定すると、そのティアはあらゆる場所でパレットティア検出の対象外になります。バリデーション、resolveColorClusterFromTab、内部の findPaletteTier ヘルパーは、アイテムが color 種別であってもそれをパレットとして扱いません。唯一のティアが semantic: true である Color TabConfig は、孤立したセマンティックティア（lone semantic tier）です。

import type { TabConfig } from '@takazudo/zdtp';

export const colorTab: TabConfig = {
  id: 'color',
  label: 'Color',
  colorExtras: {
    id: 'myapp',
    baseRoles: {},
    baseDefaults: {},
    defaultShikiTheme: 'github-dark',
    colorSchemes: {},
    panelSettings: { colorScheme: 'default', colorMode: false },
  },
  tiers: [
    {
      id: 'semantic',
      label: 'Semantic',
      semantic: true, // no palette tier anywhere in this TabConfig
      items: [
        { id: 'danger',  cssVar: '--zd-danger',  label: 'Danger',  default: 'oklch(0.55 0.22 25)', type: { kind: 'color', format: 'oklch' } },
        { id: 'warning', cssVar: '--zd-warning', label: 'Warning', default: 'oklch(0.75 0.18 80)', type: { kind: 'color', format: 'oklch' } },
        { id: 'info',    cssVar: '--zd-info',    label: 'Info',    default: 'oklch(0.6 0.1 230)',  type: { kind: 'color', format: 'oklch' } },
      ],
    },
  ],
};

孤立したセマンティックティアの帰結として、resolveColorClusterFromTab は paletteSize: 0 を報告し、Color タブはそれに応じてレンダリングします。

孤立したセマンティックティアは、referencesRamps を併用して、その行の一部（またはすべて）を別のタブにあるパレットから供給することもできます。詳しくは次のセクションを参照してください。

タブをまたぐランプ参照（referencesRamps）

TierConfig.referencesRamps を使用できるのは、id が正確に color または color-secondary である TabConfig 内の semantic: true ティアだけです。このフィールドは 1 つ以上のランプソース、すなわちセマンティックティアの行が参照できるアイテムを持つティア（任意で別タブ上のもの）を宣言します。

referencesRamps?: readonly { tab?: string; tier: string }[];

それ以外の親タブ id は configure 時に拒否されます。各エントリはティアの id と、任意でソース側の tab id を指定します（tab を省略すると「このタブ」を意味します）。assertValidPanelConfig は宣言されたすべてのソースを事前に検証します。未知のタブやティアは、いずれかの行がレンダリングされる前に、明確な configure 時エラーを投げます。

実例: Palette タブがカラータブのセマンティックティアに値を供給する

import type { TabConfig } from '@takazudo/zdtp';

// The ramp source — a standalone Palette tab (no colorExtras: see
// [Grouped palette tab](../recipes/grouped-palette-tab.mdx) for the full
// rationale). Two ramps, "base" and "accent".
export const paletteTab: TabConfig = {
  id: 'palette',
  label: 'Palette',
  tiers: [
    {
      id: 'base',
      label: 'Base',
      items: [
        { id: 'base-0', cssVar: '--palette-base-0', label: 'Base 0', default: 'oklch(0.98 0 0)', type: { kind: 'color', format: 'oklch' } },
        { id: 'base-1', cssVar: '--palette-base-1', label: 'Base 1', default: 'oklch(0.7 0 0)',  type: { kind: 'color', format: 'oklch' } },
        { id: 'base-2', cssVar: '--palette-base-2', label: 'Base 2', default: 'oklch(0.2 0 0)',  type: { kind: 'color', format: 'oklch' } },
      ],
    },
    {
      id: 'accent',
      label: 'Accent',
      items: [
        { id: 'accent-0', cssVar: '--palette-accent-0', label: 'Accent 0', default: 'oklch(0.65 0.2 250)', type: { kind: 'color', format: 'oklch' } },
        { id: 'accent-1', cssVar: '--palette-accent-1', label: 'Accent 1', default: 'oklch(0.45 0.2 250)', type: { kind: 'color', format: 'oklch' } },
      ],
    },
  ],
};

// The Color tab: a lone semantic tier that references BOTH of the Palette
// tab's ramps.
export const colorTab: TabConfig = {
  id: 'color',
  label: 'Color',
  colorExtras: {
    id: 'myapp',
    baseRoles: {},
    baseDefaults: {},
    defaultShikiTheme: 'github-dark',
    colorSchemes: {},
    panelSettings: { colorScheme: 'default', colorMode: false },
  },
  tiers: [
    {
      id: 'semantic',
      label: 'Semantic',
      semantic: true,
      referencesRamps: [
        { tab: 'palette', tier: 'base' },   // ramp source #1 (the default)
        { tab: 'palette', tier: 'accent' }, // ramp source #2
      ],
      items: [
        {
          id: 'surface',
          cssVar: '--zd-surface',
          label: 'Surface',
          // A bare ramp-item id resolves against the FIRST declared ramp
          // source (referencesRamps[0] — here, "base").
          default: 'base-1',
          type: { kind: 'color', format: 'oklch' },
        },
        {
          id: 'brand',
          cssVar: '--zd-brand',
          label: 'Brand',
          // "tierId:itemId" picks a NON-first ramp source by name.
          default: 'accent:accent-1',
          type: { kind: 'color', format: 'oklch' },
        },
      ],
    },
  ],
};

resolveColorClusterFromTab は、各行のマニフェストのデフォルトを { ref } の SemanticValue へ派生させます。

cluster.semanticDefaults['surface'] === { ref: { tab: 'palette', tier: 'base',   item: 'base-1' } }
cluster.semanticDefaults['brand']   === { ref: { tab: 'palette', tier: 'accent', item: 'accent-1' } }

apply パイプラインはそれぞれについてライブな var(...) 参照を出力します。解決済みのスナップショットではありません。そのため、Palette タブで --palette-accent-1 を調整すると、再 apply することなく --zd-brand が即座に再着色されます。

surface -> --zd-surface: var(--palette-base-1)
brand   -> --zd-brand:   var(--palette-accent-1)

パネル UI では、referencesRamps ティア上の行はグループ化された <select> としてレンダリングされます。宣言された各ランプソース（Base、Accent）ごとに 1 つの <optgroup> があり、加えてその行をスタンドアロンのリテラルカラーへ切り替える "Literal…" オプションがあります（次のセクションを参照）。別のランプオプションを選ぶと新しい { ref } マッピングが永続化され、"Literal…" を選ぶと、その行の現在解決されているカラーを初期値とする { literal } マッピングが永続化されます。

SemanticValue のマッピング形状

セマンティックティア（referencesTier 方式または semantic: true）のすべてのアイテムは、1 つの SemanticValue へ解決されます。

export type SemanticValue =
  | number
  | 'bg'
  | 'fg'
  | { literal: string }
  | { literal: { light: string; dark: string } }
  | { ref: { tab?: string; tier: string; item: string } };

モード別リテラルと colorMode.defaultMode

ClusterPanelSettings.colorMode.defaultMode（下記で説明）は、モード別リテラルが関わると 2 つ目の役割を担います。すなわち、パネル自身のスウォッチプレビューに使う側（'light' または 'dark'）を選択し、また実ブラウザーで light-dark() を解決できない場所（エクスポートプレビュー、SSR シード）でのフラットなフォールバックとしても使われます。これは出力される内容を変えません。applyColorState / buildApplyOverrides は常に完全な light-dark(<light>, <dark>) 関数を出力します。defaultMode はパネル自身が表示する、あるいはフォールバックする値にのみ影響します。

ただし、これに付随する color-scheme: light dark 宣言は DOM 限定です。applyColorState は適用先のルートにこれを設定しますが、buildApplyOverrides（ディスクエミッター）はできません。routeTokensToFiles は -- 接頭辞を持つプロパティ名しか書き換えず、ベアな color-scheme プロパティにはそれがないためです。したがって、ディスクへ出力されたトークンに依存するホストは、自身のトークン CSS で color-scheme を自ら宣言する必要があります（generateLightDarkCssProperties を参照）。

panelSettings: {
  colorScheme: 'default',
  colorMode: { defaultMode: 'dark', lightScheme: 'Light', darkScheme: 'Dark' },
},

リグレッション: #459 以前の形状は影響を受けない

従来の 2 ティア構成のパレット + セマンティッククラスター（このページで先に説明した referencesTier 駆動の形状）は、変わらずそのまま動作します。number のインデックスマッピングは引き続き PaletteSelector ドロップダウンとしてレンダリングされ、引き続き var(--palette-item-cssVar) を出力します。semantic: true と referencesRamps は純粋に追加的なものです。これらを設定しないタブは、#459 以前とまったく同じ挙動になります。

最小のエンドツーエンド例

以下のスニペットは、グループ化された Palette タブ（base / accent のランプ）と、唯一のティアが semantic: true である Color タブを備えた configurePanel({...}) の呼び出しを構成します。この Color タブは、#459 以降の 3 つの SemanticValue 形状をすべて並べて実演します。すなわち、タブをまたぐ { ref }、スタンドアロンの { literal }、そして（TierItem.default では表現できないため実行時の状態の手動編集による）モード別の { literal: { light, dark } } です。

import { configurePanel } from '@takazudo/zdtp';
import type { TabConfig, PanelConfig } from '@takazudo/zdtp';

const paletteTab: TabConfig = {
  id: 'palette',
  label: 'Palette',
  tiers: [
    {
      id: 'base',
      label: 'Base',
      items: [
        { id: 'base-0', cssVar: '--palette-base-0', label: 'Base 0', default: 'oklch(0.98 0 0)', type: { kind: 'color', format: 'oklch' } },
        { id: 'base-1', cssVar: '--palette-base-1', label: 'Base 1', default: 'oklch(0.7 0 0)',  type: { kind: 'color', format: 'oklch' } },
      ],
    },
    {
      id: 'accent',
      label: 'Accent',
      items: [
        { id: 'accent-0', cssVar: '--palette-accent-0', label: 'Accent 0', default: 'oklch(0.65 0.2 250)', type: { kind: 'color', format: 'oklch' } },
      ],
    },
  ],
};

const colorTab: TabConfig = {
  id: 'color',
  label: 'Color',
  colorExtras: {
    id: 'myapp',
    baseRoles: {},
    baseDefaults: {},
    defaultShikiTheme: 'github-dark',
    colorSchemes: {},
    panelSettings: { colorScheme: 'default', colorMode: false },
  },
  tiers: [
    {
      id: 'semantic',
      label: 'Semantic',
      semantic: true,
      referencesRamps: [{ tab: 'palette', tier: 'base' }, { tab: 'palette', tier: 'accent' }],
      items: [
        // { ref } — bare id resolves against the first ramp source ("base").
        { id: 'brand', cssVar: '--zd-brand', label: 'Brand', default: 'base-1', type: { kind: 'color', format: 'oklch' } },
        // { literal } — a standalone color, unrelated to any ramp.
        { id: 'info', cssVar: '--zd-info', label: 'Info', default: 'oklch(0.6 0.1 230)', type: { kind: 'color', format: 'oklch' } },
        // Manifest default is a single-mode literal; the per-mode pair below
        // is layered on top of the seeded state at runtime.
        { id: 'danger', cssVar: '--zd-danger', label: 'Danger', default: 'oklch(0.55 0.22 25)', type: { kind: 'color', format: 'oklch' } },
      ],
    },
  ],
};

const config: PanelConfig = {
  storagePrefix: 'myapp-design-token-panel',
  consoleNamespace: 'myapp',
  modalClassPrefix: 'myapp-design-token-panel-modal',
  schemaId: 'myapp-design-tokens/v1',
  exportFilenameBase: 'myapp-design-tokens',
  tabs: [paletteTab, colorTab],
};

configurePanel(config);

// Optional: seed "danger" with a per-mode literal, exactly as the panel's own
// "Per-mode" editor checkbox would produce it. (Sketch — the real call site
// reads the current state via the panel's persisted-state helpers rather than
// constructing ColorTweakState by hand.)
// state.color.semanticMappings.danger = {
//   literal: { light: 'oklch(0.55 0.22 25)', dark: 'oklch(0.7 0.19 25)' },
// };

ColorClusterExtras

カラー TabConfig の colorExtras フィールドは、ティアモデルに収まらないすべてのメタデータを保持します。

export interface ColorClusterExtras {
  /** Stable id forwarded to internal cluster helpers. */
  id: string;
  /** Optional label for Color-tab section headings. Falls back to `id.toUpperCase()`. */
  label?: string;
  /** CSS custom-property names for terminal base roles. */
  baseRoles: Partial<Record<BaseRoleKey, string>>;
  /** Fallback palette indices when a scheme omits a base role. */
  baseDefaults: Partial<Record<BaseRoleKey, number>>;
  /** Fallback shikiTheme name when a scheme lacks one. Inert when no shiki integration. */
  defaultShikiTheme: string;
  /** Bundled color-scheme registry keyed by display name. Pass `{}` when unused. */
  colorSchemes: Record<string, ColorScheme>;
  /** Panel-level scheme settings. */
  panelSettings: ClusterPanelSettings;
}

export type BaseRoleKey = 'background' | 'foreground' | 'cursor' | 'selectionBg' | 'selectionFg';

baseRoles は部分マップです。クラスターは、そのデザインシステムが公開するターミナルロールのみを宣言します。空のマップも有効で、宣言されたロールのみが apply 時に CSS の書き込みを発生させます。

ColorScheme

export type ColorRef = number | string;

export interface ColorScheme {
  background: ColorRef;
  foreground: ColorRef;
  cursor: ColorRef;
  selectionBg: ColorRef;
  selectionFg: ColorRef;
  palette: readonly string[]; // length must equal the palette tier's item count
  shikiTheme: string;
  semantic?: Record<string, ColorRef>; // keys must be a subset of the semantic tier's item ids
}

ColorScheme は完全に解決されたスナップショットです。パレットの hex 値に加え、ベースロールとセマンティックロールがどのパレットインデックスを指すかを固定するロール割り当てを持ちます。

ColorRef

• number は palette へのインデックスを参照します（例: 2 → palette[2]）。

• string はリテラルのカラー値です（#33ff33 のような hex、rgb(...) など）。短縮記法の "bg" はスキームの背景に、"fg" は前景に解決されます。

パレット長の不変条件

ColorScheme.palette.length は、パレットティアのアイテム数と一致しなければなりません。パレット長が一致しないスキームは初期化時に拒否されます。

セマンティックキーの不変条件

ColorScheme.semantic のキーは、セマンティックティアのアイテム id のサブセットでなければなりません。スキームは新しいセマンティックトークンを導入できません。ティアモデルが正典となる語彙です。

ClusterPanelSettings

ColorClusterExtras.panelSettings の中で保持されます。

export interface ClusterPanelSettings {
  /** Scheme name to seed state from when `colorMode` is `false`. */
  colorScheme: string;
  /**
   * `false` disables scheme-to-`data-theme` binding only; it does not disable
   * per-mode editing or change what gets emitted. An object honours `data-theme`
   * on `<html>` and switches schemes on init.
   */
  colorMode: false | { defaultMode: 'light' | 'dark'; lightScheme: string; darkScheme: string };
}

内部ブリッジ: resolveColorClusterFromTab

resolveColorClusterFromTab(tab, tabs = [tab]) は、colorExtras を持つ任意の TabConfig から ColorClusterDataConfig を派生させます。パネルが 'color' および 'color-secondary' タブを処理する際に自動的に呼び出されます。第 2 引数はパネルの完全な tabs 配列です。これを渡すことで、セマンティックティアのタブをまたぐ referencesRamps（上記参照）が、別タブにあるランプティアに対して解決されます。引数が 1 つだけの呼び出しは [tab] にフォールバックするため、渡したタブ上のタブをまたぐ { ref } はベストエフォートでしか解決されず、エミッターはそれをスキップします。

ホストがこれを直接呼び出すことはありません。テストや高度なホストツール向けに cluster-config から公開されています。

import { resolveColorClusterFromTab } from '@takazudo/zdtp';

const cluster = resolveColorClusterFromTab(colorTab, config.tabs);
// cluster.paletteSize, cluster.paletteCssVarTemplate, cluster.semanticDefaults, ...

タブに colorExtras がない場合は undefined を返します。

マルチクラスターのサポート

id: 'color-secondary' を持つ 2 つ目の TabConfig を与えると、セカンダリのカラーセクションが有効になります。

configurePanel({
  // ...
  tabs: [
    colorTab,         // id: 'color'
    colorSecondaryTab, // id: 'color-secondary'
    // ... other tabs
  ],
});

解決は、panel-config からエクスポートされる resolveSecondaryColorClusterFromTabs(tabs) を介して行われます。

ホスト提供のスキームプリセット

PanelConfig.colorPresets は任意の、ホストが提供するプリセットマップで、Color タブの「Scheme...」ドロップダウンに表示されます。デフォルトは {} で、パッケージはプリセットを一切同梱しません。

ドロップダウンでのマージ順

<option disabled>Scheme...</option>
... colorExtras.colorSchemes (insertion order) ...
<hr />
... colorPresets (alphabetical) ...

キーが衝突した場合、ロード時のルックアップではクラスターにバンドルされたスキームが優先されます。ドロップダウンは両方のエントリをレンダリングします。視覚的な重複排除は対象外です。

setPanelColorPresets() による遅延アタッチ

大きなプリセットライブラリは、インラインの SSR 設定ブロブが肥大化するのを避けるために遅延させることができます。

import { setPanelColorPresets } from '@takazudo/zdtp';

void import('./large-preset-library').then(({ presets }) => {
  setPanelColorPresets(presets);
});

完全な契約については setPanelColorPresets を参照してください。

Apply の挙動

ユーザーが Color タブで Apply をクリックすると、パイプラインは次を行います。

1. パレットアイテムを反復します（パレットティアが存在する場合。孤立した semantic: true タブにはありません）。各スロットについて paletteTier.items[i].cssVar ← palette[i] を書き込みます。

2. baseRoles を反復します。cssName ← palette[state[roleKey]] を書き込みます。存在しないロールは書き込みを行いません。

3. セマンティックアイテムを反復します。各アイテムの SemanticValue マッピングを解決し、上記の SemanticValue のマッピング形状 の表に従って出力します。インデックスまたは { ref } マッピングには var(...)、{ literal } にはリテラル文字列をそのまま、モード別の { literal: { light, dark } } には light-dark(<light>, <dark>)（加えて適用先のルートに color-scheme: light dark。DOM apply のみ。上記のモード別リテラルの注意点を参照）を出力します。

clearAppliedStyles は、クラスターが設定し得たすべての CSS プロパティを削除します（パレット + ベースロール + セマンティック + モード別リテラルが残した color-scheme）。

関連ページ

• PanelConfig.tabs — Color TabConfig を指定する場所。

• トークン階層 — TabConfig / TierConfig / TierItem の完全な型リファレンス。

• Apply パイプライン — ティアリゾルバー + ティアをまたぐ参照が CSS 変数の出力をどう駆動するか。