テーマ・動的配色

テーマの真実は document.documentElement 上の --md-sys-color-* です。コンポーネントは React Context ではなく CSS 変数だけを読みます。色やライト/ダークの切替は、その変数を書き換えるだけです。

参考: Material Design 3 公式ガイドライン m3.material.io/styles/color/system/overview

一本の書き込み API

import { syncDocumentTheme, generateScheme } from '@m3-baseui/react-tailwind';

// シードから生成して :root へ
syncDocumentTheme({ mode: 'dark', seed: '#6750A4' });

// ホスト色や任意パレットを直接渡す（VS Code webview など）
const colors = /* --vscode-* 等から組み立てた Scheme */;
syncDocumentTheme({ mode: 'light', colors });

// ライト/ダークだけ切替（インライン色を消して tokens.css に戻す）
syncDocumentTheme({ mode: 'dark' });

優先順位は colors → seed → ベースライン（tokens.css）です。 Dialog / Menu などのポータルも :root を継承するため、別途 html 同期は不要です。

ThemeProvider（React 糖衣）

必須ではありません。mode トグル（useTheme）や seed 連動が欲しいときの薄いラッパです。既定で document.documentElement に書き込みます。

<ThemeProvider
  seed="#6750A4"
  scheme="tonalSpot"
  mode="system"
  contrast="standard"
>
  {children}
</ThemeProvider>

// ホストテーマ: colors を渡す（seed より優先）
<ThemeProvider colors={hostScheme} mode="dark">
  {children}
</ThemeProvider>

Prop	型	既定値	説明
`colors`	`Scheme`	—	明示スキーム。ホスト色・動的切替向け。seed より優先
`seed`	`string`	—	16 進シード色。Dynamic Color で light/dark を生成
`scheme`	`SchemeVariant`	`tonalSpot`	seed 用バリアント
`mode`	`'light' \| 'dark' \| 'system'`	`system`	ライト / ダーク / OS（または resolveMode）
`resolveMode`	`() => 'light' \| 'dark'`	prefers-color-scheme	mode=system 時の解決。VS Code body class 等を渡せる
`target`	`'document' \| 'scope'`	`document`	書き込み先。通常は document のまま
`contrast`	`'standard' \| 'medium' \| 'high'`	`standard`	seed 生成時のコントラスト

動的切替（React）

const [mode, setMode] = useState<'light' | 'dark'>('light');
const [seed, setSeed] = useState('#6750A4');

useLayoutEffect(() => {
  return syncDocumentTheme({ mode, seed });
}, [mode, seed]);

// または ThemeProvider の props / useTheme().setMode で同様に切替

トークンと CSS 変数

色はチャンネル三値（例: 103 80 164）で保持され、 rgb(var(--md-sys-color-primary)) のように参照します。トークンの単一ソースは packages/tokens/src/tokens.ts です。

Tailwind 利用時は @m3-baseui/tokens/theme.css が @theme プリセットへマップし、bg-primary 等のユーティリティが使えます。