CSS変数テーマ

--hg-* CSSカスタムプロパティ名前空間、定義された変数、デフォルト値、テーマ注入メカニズム。

HyperGenはCSSカスタムプロパティ（CSS変数）を使用して、ホストアプリケーションのデザインシステムをサンドボックス化されたiframeにブリッジします。すべてのHyperGenテーマ変数は--hg-*名前空間にあります。

テーマ注入の仕組み

ホストアプリケーションがデザイントークン（色、フォント、スペーシング、角丸）を収集し、--hg-*変数にマッピング。
ホストがCSSカスタムプロパティのキー-値ペアを含むvarsオブジェクト付きのhg:theme postMessageをiframeに送信。
iframeのpostMessageブリッジが各変数をdocument.documentElement.styleに設定し、var(--hg-*)経由ですべてのコンテンツが利用可能に。
エージェント生成HTMLがCSS内でこれらの変数を参照し、ホストのビジュアルデザインを継承。

ホスト: "プライマリカラーは#7c3aed"
  │
  ├── マッピング: --hg-accent: #7c3aed
  │
  └── postMessage({ type: "hg:theme", vars: { "--hg-accent": "#7c3aed" } })
        │
        └── iframe: document.documentElement.style.setProperty("--hg-accent", "#7c3aed")
              │
              └── エージェントCSS: background: var(--hg-accent)  →  #7c3aedとしてレンダリング

定義済み変数

カラー変数

変数	必須	デフォルト	説明
`--hg-surface`	しなければならない (MUST)	`#ffffff`	プライマリ背景サーフェス色。
`--hg-surface-elevated`	すべきである (SHOULD)	`#f9fafb`	浮き出たサーフェス（カード、ポップオーバー、モーダル）。
`--hg-text`	しなければならない (MUST)	`#111827`	プライマリテキスト色。
`--hg-text-muted`	すべきである (SHOULD)	`#6b7280`	セカンダリ / ミュートテキスト色。
`--hg-accent`	しなければならない (MUST)	`#7c3aed`	インタラクティブ要素（ボタン、リンク）のアクセント / ブランドカラー。
`--hg-accent-fg`	しなければならない (MUST)	`#ffffff`	アクセント色の背景上のテキスト前景色。
`--hg-border`	しなければならない (MUST)	`#e5e7eb`	ボーダーとセパレーター色。
`--hg-background`	してもよい (MAY)	`transparent`	iframeのbody背景。デフォルトは透明で、ホストの背景が透けて見える。

タイポグラフィ変数

変数	必須	デフォルト	説明
`--hg-font-family`	すべきである (SHOULD)	`system-ui, -apple-system, sans-serif`	ベースフォントファミリー。
`--hg-font-mono`	すべきである (SHOULD)	`ui-monospace, monospace`	コードブロック用等幅フォントファミリー。
`--hg-font-size`	してもよい (MAY)	`16px`	ベースフォントサイズ。
`--hg-line-height`	してもよい (MAY)	`1.5`	ベース行の高さ。

スペーシング変数

変数	必須	デフォルト	説明
`--hg-space-1`	すべきである (SHOULD)	`4px`	極小スペーシング（タイトなギャップ、アイコンパディング）。
`--hg-space-2`	すべきである (SHOULD)	`8px`	小スペーシング（要素のギャップ、コンパクトなパディング）。
`--hg-space-4`	すべきである (SHOULD)	`16px`	中スペーシング（セクションパディング、カードパディング）。
`--hg-space-8`	すべきである (SHOULD)	`32px`	大スペーシング（セクションマージン、主要なセパレーター）。

シェイプ変数

変数	必須	デフォルト	説明
`--hg-radius`	すべきである (SHOULD)	`8px`	デフォルトボーダー半径。
`--hg-radius-sm`	してもよい (MAY)	`4px`	小ボーダー半径（チップ、バッジ）。
`--hg-radius-lg`	してもよい (MAY)	`12px`	大ボーダー半径（カード、モーダル）。

必須変数と任意変数

ホストアプリケーションは5つの必須カラー変数（--hg-surface、--hg-text、--hg-accent、--hg-accent-fg、--hg-border）を提供しなければなりません (MUST)。これらはエージェント生成UIがホストと視覚的に整合するために必要な最小限です。

その他の変数はすべてすべきである (SHOULD)またはしてもよい (MAY)です。ホストが変数を提供しない場合、エージェントはデフォルト値を含むvar()フォールバック構文を使用しなければなりません (MUST):

/* 良い例: フォールバックによりテーマ注入なしでもUIが動作 */
background: var(--hg-surface-elevated, #f9fafb);
border-radius: var(--hg-radius, 8px);
font-family: var(--hg-font-family, system-ui, -apple-system, sans-serif);

デフォルトテーマ

リファレンス実装はデフォルトのライトテーマを提供します。実装は、すべての必須変数を提供する限り、異なるデフォルトを使用してもよいです (MAY)。

:root {
  /* Colors (required) */
  --hg-surface: #ffffff;
  --hg-surface-elevated: #f9fafb;
  --hg-text: #111827;
  --hg-text-muted: #6b7280;
  --hg-accent: #7c3aed;
  --hg-accent-fg: #ffffff;
  --hg-border: #e5e7eb;

  /* Typography */
  --hg-font-family: system-ui, -apple-system, sans-serif;
  --hg-font-mono: ui-monospace, monospace;
  --hg-font-size: 16px;
  --hg-line-height: 1.5;

  /* Spacing */
  --hg-space-1: 4px;
  --hg-space-2: 8px;
  --hg-space-4: 16px;
  --hg-space-8: 32px;

  /* Shape */
  --hg-radius: 8px;
  --hg-radius-sm: 4px;
  --hg-radius-lg: 12px;
}

テーマ更新

ホストはiframeのライフタイム中に複数のhg:themeメッセージを送信してもよいです (MAY)。各メッセージは加算的です — 指定された変数を設定し、以前に設定されたものはクリアしません。

一般的なシナリオ:

ダークモード切り替え: ホストがダークモード値ですべてのカラー変数を再送信。
ユーザー設定の変更: ホストが変数のサブセットを更新（アクセントカラーのみなど）。
初期 + 遅延: ホストが必須変数を即座に送信し、完全なテーマの読み込み後にオプション変数を送信。

// Toggle to dark mode
controller.setTheme({
  "--hg-surface": "#1a1a2e",
  "--hg-surface-elevated": "#16213e",
  "--hg-text": "#e0e0e0",
  "--hg-text-muted": "#9ca3af",
  "--hg-accent": "#8b5cf6",
  "--hg-accent-fg": "#ffffff",
  "--hg-border": "#374151",
});

エージェント使用ガイドライン

エージェントは、ホストとの視覚的な整合性を確保するために、生成されるすべてのCSSで--hg-*変数を使用すべきです (SHOULD):

<style>
  .result-card {
    background: var(--hg-surface-elevated, #f9fafb);
    color: var(--hg-text, #111827);
    border: 1px solid var(--hg-border, #e5e7eb);
    border-radius: var(--hg-radius, 8px);
    padding: var(--hg-space-4, 16px);
    font-family: var(--hg-font-family, system-ui, sans-serif);
  }
  .result-card h2 {
    color: var(--hg-text, #111827);
    margin: 0 0 var(--hg-space-2, 8px);
  }
  .result-card .muted {
    color: var(--hg-text-muted, #6b7280);
  }
  .result-card button {
    background: var(--hg-accent, #7c3aed);
    color: var(--hg-accent-fg, #ffffff);
    border: none;
    border-radius: var(--hg-radius-sm, 4px);
    padding: var(--hg-space-2, 8px) var(--hg-space-4, 16px);
    cursor: pointer;
  }
</style>

エージェントは以下をすべきではありません (SHOULD NOT):

プライマリUI要素（背景、テキスト、ボーダー、ボタン）にハードコードされた色値を使用する。
--hg-*変数を無視した独自のカラースキームを定義する。
:rootの--hg-*変数をオーバーライドする（ホストのテーマ注入と競合するため）。

エージェントは、コンポーネント内部の値（アニメーション時間、特定のレイアウト寸法など）にカスタムCSS変数（--hg-*名前空間外）を使用してもよいです (MAY)。

変数名前空間の拡張

ここで定義されたもの以外に追加のテーマ変数が必要な実装は、サブ名前空間を使用すべきです (SHOULD):

--hg-x-myapp-sidebar-width: 280px;
--hg-x-myapp-header-height: 64px;

--hg-x-プレフィックスは拡張変数を示します。標準HyperGen変数は--hg-x-プレフィックスを使用してはなりません (MUST NOT)。

CSS変数テーマ

目次