sparkle-design-cli 2.3.1 → 2.4.0

package/README.md

@@ -100,6 +100,9 @@ sparkle-design-cli generate --globals-path src/styles/app.css
 
 # CI 向け: @source 注入や Tailwind import 欠落などの失敗を exit 1 にする
 sparkle-design-cli generate --strict
+
+# 単一バンドル内でランタイムにテーマ切替したい場合（詳細は「複数のテーマ配色を1デプロイでサポートしたい場合」参照）
+sparkle-design-cli generate -c ./config/sparkle.admin.json --scope '[data-tenant-theme="admin"]' -o ./src/styles/sparkle-admin-scope.css
 ```
 
 #### generate オプション一覧
@@ -113,6 +116,7 @@ sparkle-design-cli generate --strict
   - デザインシステムパッケージが `package.json` に入っているのに Tailwind エントリ CSS が見つからない
   - エントリ CSS はあるが `@import "tailwindcss";` が書かれていない（警告メッセージに追記すべき行まで actionable に表示）
   - エントリ CSS への書き込みに失敗した
+- `--scope <セレクタ>`: `@theme inline` には触れず、セマンティックトークン（`--color-primary-*` 等）だけを実値までリテラル化して指定セレクタの中にラップ出力する。単一バンドル内でランタイムにテーマ切替したい場合向け（`-o/--output` の指定が必須）。詳細は「複数のテーマ配色を1デプロイでサポートしたい場合」の「ケース B」を参照
 
 ### check: アンチパターン検査
 
@@ -536,22 +540,65 @@ Figma プラグインが出力する基本4項目に加えて、プロジェク
 
 `primary` だけを差し替えて `gray` を既定のままにすると、コンポーネントの枠線・背景・テキストに使われる gray 系トークンと primary のトーンが揃わなくなるため、gray も必ずセットで再定義してください。
 
+##### `character-*` に無いウェイト（SemiBold 等）を使いたい場合
+
+`character-*` utility の `font-weight` は Regular(400) / Bold(700) の 2 値のみで、SemiBold(600) や Medium(500) に対応する `character-*` は存在しません（Sparkle Design のプリミティブトークンである `fontWeights.text.regular` / `fontWeights.text.bold` がこの 2 値のみを持つため）。
+
+日本語見出しでは Bold(700) が視覚的に重すぎると判断して SemiBold(600) を使いたい、といったプロジェクト固有のウェイト方針がある場合は、`character-*` に SemiBold バリアントの追加を待つのではなく、`extend.custom-css` で独自のユーティリティクラスを定義してください。**`className="character-3-regular-pro font-semibold"` のように Tailwind の `font-semibold` を併用する方法は機能しません**。`sparkle-design.css` は Tailwind の後・`@layer utilities` 内に読み込まれるよう意図的に設計されており（同一詳細度なら後着のルールが勝つ cascade layers の仕様上）、`character-*` 側の `font-weight` が常に優先されるためです。
+
+```css
+/* custom-typography.css */
+@layer utilities {
+  /* character-3（16px/24px）の SemiBold バリアント。
+     font-family / font-size / letter-spacing / line-height は
+     character-* と同じプリミティブトークンをそのまま流用し、
+     font-weight だけプロジェクト独自の 600 に差し替える */
+  .character-3-semibold-pro {
+    font-family: var(--font-family-pro);
+    font-size: var(--font-size-16);
+    font-weight: 600;
+    letter-spacing: var(--letter-spacing-wider);
+    line-height: var(--line-height-24);
+  }
+}
+```
+
+`character-*-semibold-*` は既存の `character-*-regular-*` / `character-*-bold-*` と別名のクラスなので、cascade の競合は起きません。`extend.custom-css` は `sparkle-design.css` の直後に `@import` されるため、上記のように新規クラスを追記するだけで有効になります（上書きではないので `!important` や記述順の工夫も不要です）。
+
+使用するフォントファミリーが実際に 600 ウェイトのファイルを読み込んでいるかも確認してください。`extend.fonts.pro` / `extend.fonts.mono` の `weights` に `600` を含めていないと、`font-weight: 600` を指定してもブラウザによる疑似太字（faux bold）にフォールバックし、正しい SemiBold の字形になりません。
+
+将来 Sparkle Design 本体が正式に `character-N-semibold-*` token を追加した場合は、cascade 上は consumer 側の `custom-css` 定義が勝ち続けるため、その時点で自前定義は削除して本体の token に乗り換えてください（放置すると Sparkle 側の値が更新されても気づかず古い定義が使われ続けます）。
+
+なお `check` の `tailwind-typography` ルールは `font-semibold` / `font-medium` を検出対象に含めていますが、`character-*-semibold-*` のような独自クラスに置き換えた行は検出パターンに一致しないため、`sparkle-disable-line` を付けなくても違反として検出されなくなります。
+
 ## 複数のテーマ配色を 1 デプロイでサポートしたい場合
 
-管理画面と一般ユーザー画面で配色を出し分けたい、テナントごとに固定の配色バリアントを切り替えたいなど、「少数（数種類程度）の固定配色を 1 つのデプロイでサポートする」ケースの推奨パターンです。
+管理画面と一般ユーザー画面で配色を出し分けたい、テナントごとに固定の配色バリアントを切り替えたいなど、「少数（数種類程度）の固定配色を 1 つのデプロイでサポートする」ケースの推奨パターンです。**「画面ごとに読み込む CSS を切り替える」場合と「1 つの画面内でランタイムに切り替える」場合とで推奨パターンが異なる**ので、まずどちらのケースかを判断してください。
+
+### ケース A: 画面（ビルド）ごとにバリアントが固定される場合 → config を分割して複数の CSS を生成する
 
-### 推奨: config を分割して複数の CSS を生成する
+管理画面 / 一般ユーザー画面でレイアウトごと entry CSS を分けられる、role や tenant に応じて import する CSS を切り替えられる、など「1 画面につき常に 1 バリアントだけを読み込む」運用ができる場合の推奨パターンです。
 
 `generate` は `-c/--config` と `-o/--output` を組み合わせることで、任意の config から任意の出力先へ CSS を生成できます。バリアントの数だけ config ファイルを用意し、バリアントの数だけ `generate` を実行してください（1 config に複数テーマをまとめて生成する機能はありませんが、CI やスクリプトで複数回呼び出せば十分に運用できます）。
 
 ```jsonc
 // config/sparkle.admin.json
-{ "primary": "blue", "font-pro": "Inter", "font-mono": "JetBrains Mono", "radius": "md" }
+{
+  "primary": "blue",
+  "font-pro": "Inter",
+  "font-mono": "JetBrains Mono",
+  "radius": "md"
+}
 ```
 
 ```jsonc
 // config/sparkle.employee.json
-{ "primary": "green", "font-pro": "Inter", "font-mono": "JetBrains Mono", "radius": "md" }
+{
+  "primary": "green",
+  "font-pro": "Inter",
+  "font-mono": "JetBrains Mono",
+  "radius": "md"
+}
 ```
 
 ```bash
@@ -559,7 +606,68 @@ npx sparkle-design-cli generate -c ./config/sparkle.admin.json -o ./src/styles/s
 npx sparkle-design-cli generate -c ./config/sparkle.employee.json -o ./src/styles/sparkle-employee.css
 ```
 
-あとは consumer 側で、表示するバリアントに応じてどちらの CSS を読み込むかを切り替えるだけです（例: role / tenant を判定できるレイアウト単位で `import "./sparkle-admin.css"` と `import "./sparkle-employee.css"` を出し分ける、Next.js のルートグループごとに読み込む entry CSS を分ける、など）。**同時に両方を読み込まない**（1 画面につき常に 1 バリアントだけを読み込む）ようにすると、後述のファイルサイズ増加の影響を最小化できます。
+あとは consumer 側で、表示するバリアントに応じてどちらの CSS を読み込むかを切り替えるだけです（例: role / tenant を判定できるレイアウト単位で `import "./sparkle-admin.css"` と `import "./sparkle-employee.css"` を出し分ける、Next.js のルートグループごとに読み込む entry CSS を分ける、など）。
+
+**重要: この 2 つの CSS を同時に import してはいけません。** これはファイルサイズ最適化の話ではなく **correctness 上のハード制約** です。`generate` が出力する CSS は `@theme inline { ... }` という Tailwind v4 の at-rule を含みますが、Tailwind の仕様上 `@theme`（`@theme inline` を含む）は **stylesheet の top-level にしか置けず、かつ 1 種類のトークン定義として扱われます**。2 つの `generate` 出力を同時 import すると、両方の `@theme inline` が同じ top-level スコープで衝突し、後に読み込んだ方の値で utility class（`bg-primary-500` 等）の意味がビルド時に固定されてしまいます（`data-*` 属性の付け外しのようなランタイム操作では変わりません）。**1 画面につき常に 1 バリアントだけを読み込む**構成でのみ、この方式は安全に使えます。
+
+「1 つの画面内で属性の付け外しだけでテーマを切り替えたい（ページ遷移や再ビルドを伴わない）」場合は、このケース A ではなく次のケース B を使ってください。
+
+### ケース B: 単一バンドル内でランタイムに切り替えたい場合 → `generate --scope`
+
+SPA の 1 つの JS バンドル内で、`<html data-tenant-theme="admin">` のような属性の付け外しだけで配色を切り替えたい（ページ遷移・再デプロイを伴わない）場合のパターンです。ケース A の「config 分割 + 複数 `generate` の CSS を同時 import する」は、上記の理由（`@theme inline` の衝突）でこのケースには使えません。
+
+Tailwind v4 では、この種のランタイム切り替え（dark mode 等）を公式に次のパターンでサポートしています（[Tailwind公式ドキュメント](https://tailwindcss.com/docs/colors#using-css-variables)より）:
+
+```css
+@import "tailwindcss";
+
+:root {
+  --acme-canvas-color: oklch(0.967 0.003 264.542);
+}
+
+[data-theme="dark"] {
+  --acme-canvas-color: oklch(0.21 0.034 264.665);
+}
+
+@theme inline {
+  --color-canvas: var(--acme-canvas-color);
+}
+```
+
+ポイントは、`@theme inline` は top-level に **1 つだけ** 置いたまま、実際に切り替えたい値は `@theme` を使わない普通の `:root` / `[data-attr]` スコープ付きセレクタで **参照先の CSS 変数** を上書きする、という構成です。`generate --scope` はこの「参照先を差し替える」役割を、`sparkle.config.json` の解決ロジックを再利用しながら自動生成します。
+
+```bash
+# ベース（デフォルト表示）となるバリアントは今まで通り通常の generate
+npx sparkle-design-cli generate -c ./config/sparkle.employee.json -o ./src/styles/sparkle-employee.css
+
+# 追加バリアントは --scope で「セマンティックトークンだけをセレクタでラップした差分 CSS」を生成する
+npx sparkle-design-cli generate -c ./config/sparkle.admin.json \
+  --scope '[data-tenant-theme="admin"]' \
+  -o ./src/styles/sparkle-admin-scope.css
+```
+
+```css
+/* entry CSS: 両方を同時に import してよい */
+@import "tailwindcss";
+@import "./sparkle-employee.css"; /* @theme inline を含む通常の generate 出力（ベース） */
+@import "./sparkle-admin-scope.css"; /* --scope の出力。@theme inline は含まない */
+```
+
+```html
+<!-- ランタイムでこの属性を付け外しするだけで配色が切り替わる。ページ遷移・再ビルド不要 -->
+<html data-tenant-theme="admin"></html>
+```
+
+`--scope` の出力は次の性質を持ちます:
+
+- `@theme inline` には一切触れない（ベース側の `generate` 出力にある 1 つだけがそのまま有効であり続ける）ので、ケース A のような衝突は起きません。
+- `--color-primary-*` 等の **セマンティックトークン** を、admin config の解決結果に基づいて実値（`oklch(...)`）までリテラル化した上で `--scope` のセレクタの中に閉じ込めます。プリミティブ（`--color-blue-*` 等）ではなくセマンティックトークンを上書き対象にしているのがポイントで、デフォルトでは `primary` と `info` が同じプリミティブ（例: `blue`）を共有しているため、もしプリミティブ側を上書きしてしまうと `primary` を変えたつもりが `info` まで巻き込んで変わってしまいます。`--scope` はこの巻き込みが起きないよう、セマンティック層で解決してから出力します。
+- `--radius-*` / `--shadow-*` は普遍的な共有スケール値（テナント間で衝突しない）なので `var()` 参照のまま出力されます。`config.radius` がバリアントごとに異なれば、その解決結果もちゃんと反映されます。
+- フォント import・`@source`・SparkleHead.tsx・globals.css パッチ等、ドキュメント全体に関わる**出力**は行いません。これらはベース側の通常 `generate` が既に担っているため、バリアントごとに重複させる必要はありません。ただし `font-pro` / `font-mono` 等の **validation 自体**は通常の `generate` と同様に適用されます（出力しないだけで、config の妥当性チェックは変わりません）。
+- `-o/--output` の指定が必須です（既定の `sparkle-design.css` を誤って上書きしないため）。`--strict` / `--globals-path` とは併用できません（`--scope` はグローバル CSS のパッチを行わないため）。
+- 現状 `primary` は 7 色パレットからの選択のみ対応しています。7 色にないカスタムブランドカラーを `--scope` の変数だけで表現したい場合は、`extend.custom-css` の要領で手動でセレクタ配下に `--color-primary-*` を定義してください（`--scope` の出力とマージして使えます）。
+
+このパターンは、次の「非推奨: 属性スコープでの Tailwind クラス上書き」が抱えていた脆さも同時に解消します。`--scope` が上書きするのは Sparkle が公開しているトークン契約（`--color-primary-*` 等の CSS 変数）だけであり、ユーティリティクラス名やコンポーネント内部の specificity には一切依存しません。そのため、Sparkle 側のコンポーネント実装（クラス名の付け方や compound attribute selector 等）が変わっても、`--scope` の出力が壊れることはありません。
 
 ### 非推奨: 単一 CSS + 属性スコープでの Tailwind クラス上書き
 
@@ -568,15 +676,16 @@ npx sparkle-design-cli generate -c ./config/sparkle.employee.json -o ./src/style
 - コンポーネント側の実装詳細（クラス名の付け方や CSS の specificity）に依存するため、Sparkle 側の内部実装（例: 状態別カラーリングで compound attribute selector を使っているコンポーネント）が変わると、`!important` を使っても上書きが効かなくなることがあります。上書き対象は Sparkle が公開している契約（config / トークン）ではなく非公開の実装詳細なので、バージョンアップのたびに壊れるリスクを consumer 側が抱え続けることになります。
 - 上書きが必要なクラス／コンポーネントが増えるたびに、手動でセレクタを足していく必要があり、考慮漏れに気づきにくいです。
 
-上記のリスクを踏まえると、テーマ切り替えは config 分割 + `extend.custom-css` によるトークンレベルの上書き（cascade 順で確実に勝つ）で完結させる方が、Sparkle のバージョンアップに対しても壊れにくく、見通しの良い実装になります。
+上記のリスクを踏まえると、テーマ切り替えは「ケース A: config 分割」または「ケース B: `generate --scope`」+ `extend.custom-css` によるトークンレベルの上書き（cascade 順で確実に勝つ）で完結させる方が、Sparkle のバージョンアップに対しても壊れにくく、見通しの良い実装になります。
 
 ### トレードオフ
 
-| 観点 | config 分割（推奨） | 属性スコープ上書き（非推奨） |
-| --- | --- | --- |
-| ファイルサイズ | バリアントの数だけ CSS が増える（各 CSS は 7 色パレット全体を含むため、1 バリアントあたりのベースコストは一定）。1 画面 1 バリアントのみ読み込む運用なら実質的な増分は小さい | 単一 CSS + 上書き分の差分のみで増分は小さい |
-| FOUC リスク | サーバー側 / ビルド時にバリアントを決定できるならほぼ無し。クライアント側でバリアント判定後に切り替える場合は他方式と同程度のリスクがある | クライアント側で属性を付与するタイミング次第でリスクがある（初期描画後に属性が付くと一瞬デフォルト配色が見える） |
-| 保守性 | Sparkle が公開している config / トークンだけに依存するため、コンポーネント内部実装の変更に影響されにくい | コンポーネントの内部実装（クラス名・specificity）に依存するため、Sparkle 側の変更で上書きが効かなくなるリスクがある |
+| 観点           | ケース A: config 分割（推奨・画面ごと固定）                                                                                      | ケース B: `generate --scope`（推奨・単一バンドルでランタイム切替）                           | 属性スコープ上書き（非推奨）                                                                                        |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| 適用シーン     | 1 画面につき常に 1 バリアントだけを読み込める                                                                                    | 1 バンドル内で属性の付け外しだけで切り替えたい                                               | （非推奨のため参考情報）                                                                                            |
+| ファイルサイズ | バリアントの数だけ CSS が増える（各 CSS は 7 色パレット全体を含む）。1 画面 1 バリアントのみ読み込む運用なら実質的な増分は小さい | ベース CSS 1 本 + バリアントごとの軽量な差分 CSS（セマンティックトークンのみ）               | 単一 CSS + 上書き分の差分のみで増分は小さい                                                                         |
+| FOUC リスク    | サーバー側 / ビルド時にバリアントを決定できるならほぼ無し                                                                        | 属性付与のタイミング次第でリスクがある（初期描画後に属性が付くと一瞬デフォルト配色が見える） | クライアント側で属性を付与するタイミング次第でリスクがある                                                          |
+| 保守性         | Sparkle が公開している config / トークンだけに依存するため、コンポーネント内部実装の変更に影響されにくい                         | 同左（トークンだけに依存し、ユーティリティクラス名や specificity に依存しない）              | コンポーネントの内部実装（クラス名・specificity）に依存するため、Sparkle 側の変更で上書きが効かなくなるリスクがある |
 
 ## 出力
 

package/bin/sparkle-design.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { generateCSS } from '../lib/generate-css.js';
+import { generateCSS, generateScopedCSS } from '../lib/generate-css.js';
 import { checkProject } from '../lib/check.js';
 import { setupAssistant } from '../lib/setup.js';
 import { runStopHook } from '../lib/stop-hook.js';
@@ -23,6 +23,7 @@ function parseGenerateOptions(args) {
     outputPath: null,
     globalsPath: null,
     strict: false,
+    scope: null,
     help: false,
   };
 
@@ -42,6 +43,9 @@ function parseGenerateOptions(args) {
       i += 1;
     } else if (arg === '--strict') {
       options.strict = true;
+    } else if (arg === '--scope') {
+      options.scope = requireOptionValue(args, i, '--scope');
+      i += 1;
     } else {
       throw new Error(`Unknown option for generate: ${arg}`);
     }
@@ -150,6 +154,10 @@ Generate:
   sparkle-design-cli generate --output ./styles/design.css
   sparkle-design-cli generate -c ./config/custom.json -o ./dist/styles.css
 
+  # 単一バンドル内でランタイムにテーマ切替したい場合（--scope。詳細は README 参照）
+  sparkle-design-cli generate -c ./config/sparkle.employee.json -o ./src/styles/sparkle-employee.css
+  sparkle-design-cli generate -c ./config/sparkle.admin.json --scope '[data-tenant-theme="admin"]' -o ./src/styles/sparkle-admin-scope.css
+
 Check:
   sparkle-design-cli check
   sparkle-design-cli check src --strict
@@ -180,6 +188,13 @@ Generate options:
   --globals-path <path>      Tailwind エントリポイント CSS のパス (default: 自動検出)
   --strict                   globals.css への @source 注入等が失敗したら exit 1
                              (CI 向け。既定は warn + 継続で後方互換を維持)
+  --scope <selector>         単一バンドル内でランタイムにテーマ切替したい場合の出力モード。
+                             @theme inline には触れず、セマンティックトークン（--color-primary-* 等）
+                             だけを実値までリテラル化して指定セレクタの中にラップ出力する
+                             （例: '[data-tenant-theme="admin"]'）。-o/--output の指定が必須。
+                             --strict / --globals-path とは併用不可（グローバル CSS を
+                             パッチしないため）。詳細は README の「単一バンドルでランタイム
+                             切替する場合」を参照
 
 sparkle.config.json の設定フィールド:
 
@@ -305,6 +320,25 @@ async function main() {
         process.exit(0);
       }
 
+      if (options.scope !== null) {
+        // --scope はグローバル CSS（@source / globals.css パッチ）や
+        // --strict の warn-vs-exit1 昇格ロジックに一切関与しない。両方
+        // 指定できてしまうと、指定した --strict / --globals-path が
+        // 効いているように見えて実際には黙って無視される（silent no-op）
+        // ため、組み合わせ自体を早期に拒否する。
+        // en: --scope never touches @source/globals.css patching or
+        // --strict's warn-vs-exit1 escalation. Silently accepting them
+        // together would look like they're honored while doing nothing —
+        // reject the combination up front instead.
+        if (options.strict || options.globalsPath) {
+          throw new Error(
+            '--scope は --strict / --globals-path と併用できません（--scope はグローバル CSS のパッチを行わないため）'
+          );
+        }
+        generateScopedCSS(options.configPath, options.outputPath, options.scope);
+        return;
+      }
+
       generateCSS(options.configPath, options.outputPath, options.globalsPath, {
         strict: options.strict,
       });

package/lib/anti-pattern-rules.js

@@ -925,7 +925,7 @@ const BUILTIN_ANTI_PATTERN_GROUPS = [
     check: {
       description: 'Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない',
       recommendation:
-        'text-sm / text-xs / text-base / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。ただし character-* に対応する token が無いサイズ（text-[10px] 等の arbitrary value、あるいは意図的に token 外のサイズを使う場合）は、同一行または直前行に `// sparkle-disable-line tailwind-typography` コメントを付けて例外扱いとして残すこともできます。',
+        'text-sm / text-xs / text-base / font-medium / font-semibold / font-bold は character-* utility に置き換えてください。ただし character-* に対応する token が無いサイズ（text-[10px] 等の arbitrary value、あるいは意図的に token 外のサイズを使う場合）は、同一行または直前行に `// sparkle-disable-line tailwind-typography` コメントを付けて例外扱いとして残すこともできます。font-medium(500) / font-semibold(600) は character-* に対応する token が無いため、`extend.custom-css` で独自クラスを定義してください（詳細は README の「character-* に無いウェイトを使いたい場合」参照）。',
       pattern: /\b(text-(?:xs|sm|base|lg|xl|2xl)|font-(?:medium|semibold|bold|normal|light))\b/g,
     },
     featureSection: lines([
@@ -946,6 +946,8 @@ const BUILTIN_ANTI_PATTERN_GROUPS = [
       '```',
       '',
       'Sparkle Design コンポーネント内では `character-*-pro` / `character-*-mono` を使用する。character-1（12px）より小さい指定や、対応 token が無いサイズは Tailwind の arbitrary value (`text-[10px]` 等) で表現するか、`// sparkle-disable-line tailwind-typography` で個別に例外指定する。',
+      '',
+      '`font-medium` / `font-semibold`（500 / 600）は character-* に対応する token が存在しない。`character-N-regular-pro font-semibold` のように Tailwind の font-weight ユーティリティを併用しても、character-* が意図的に Tailwind の後に読み込まれる cascade 設計のため上書きされず効かない。これらのウェイトが必要な場合は `extend.custom-css` で `character-N-semibold-pro` のような独自クラスを定義し、font-family / font-size / letter-spacing / line-height は character-* と同じプリミティブトークンを流用する（詳細は README の「character-* に無いウェイトを使いたい場合」）。',
     ]),
     jsdocTargets: [],
   },

package/lib/generate-css.js

@@ -87,9 +87,7 @@ function resolveExtend(config, configPath = null) {
       throw err;
     }
     if (typeof extend !== 'object' || extend === null || Array.isArray(extend)) {
-      const err = new Error(
-        `extend ファイルの中身は object である必要があります: ${extendPath}`
-      );
+      const err = new Error(`extend ファイルの中身は object である必要があります: ${extendPath}`);
       err.code = 'E_EXTEND_FILE_INVALID_SHAPE';
       throw err;
     }
@@ -167,7 +165,9 @@ function assertSafeFontWeights(weights, label) {
 
 function assertSafePackageName(name, label) {
   if (typeof name !== 'string' || !NPM_PACKAGE_SAFE.test(name)) {
-    const err = new Error(`${label} は有効な npm パッケージ名ではありません (${JSON.stringify(name)})`);
+    const err = new Error(
+      `${label} は有効な npm パッケージ名ではありません (${JSON.stringify(name)})`
+    );
     err.code = 'E_UNSAFE_PACKAGE_NAME';
     throw err;
   }
@@ -522,12 +522,7 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
   // wildcard として広く置換してしまう L-2 型の regex injection 両方を防げる。
   // en: Restrict replacement to a whitelist of known config keys so unknown /
   // adversarial keys cannot smuggle regex metacharacters into the template.
-  const TEMPLATE_KEY_ALLOWLIST = new Set([
-    'primary',
-    'radius',
-    'font-pro',
-    'font-mono',
-  ]);
+  const TEMPLATE_KEY_ALLOWLIST = new Set(['primary', 'radius', 'font-pro', 'font-mono']);
   const ALPHANUMERIC_KEY = /^[a-z0-9-]+$/;
   Object.entries(config).forEach(([key, value]) => {
     // 配列・オブジェクト・拡張フィールドはスキップ
@@ -589,6 +584,312 @@ function processTemplate(template, config, grayMapping, radiusMapping, colors) {
   return { css: processedCSS, resolvedFonts };
 }
 
+/**
+ * `generate --scope` 用のテンプレート解析エラーを投げる。
+ * sparkle-variables 側でテンプレートのマーカーコメント/構造が変わると
+ * ここで検知され、silent に壊れた scope CSS を出すことなく loud に停止する。
+ * @param {string} label 'primitive' | 'semantic'
+ * @param {string} detail 具体的な失敗内容
+ */
+function throwScopeTemplateShapeChanged(label, detail) {
+  const err = new Error(
+    `generate --scope 用のテンプレート解析に失敗しました（${label}: ${detail}）。` +
+      'sparkle-variables のテンプレート構造が変わった可能性があります。CLI 側の対応が必要です。'
+  );
+  err.code = 'E_SCOPE_TEMPLATE_SHAPE_CHANGED';
+  throw err;
+}
+
+/**
+ * `markerComment` の直後にある最初の `:root { ... }` ブロックの中身を抜き出す。
+ * sparkle-design.template.css は同じセマンティックトークン定義を
+ * 「プレーンな :root」（issue #229 対応前から存在。ランタイムで CSS 変数として
+ * 読める汎用ブロック）と「@theme inline」（Tailwind ユーティリティ生成用。
+ * top-level 必須で nest 不可）の 2 箇所に重複して持つ。`generate --scope` は
+ * 後者には一切触れず、前者（プレーンな :root、Tailwind の at-rule 制約を
+ * 受けない）だけを抽出してセレクタでラップし直す。
+ * en: Extract the content of the first `:root { ... }` block right after
+ * `markerComment`. The template intentionally duplicates the semantic tokens
+ * as both a plain `:root` block and an `@theme inline` block (the latter
+ * exists solely to trigger Tailwind's utility-class generation and must stay
+ * top-level per Tailwind v4's spec). `generate --scope` only ever touches the
+ * plain `:root` copy, since it isn't subject to that at-rule constraint.
+ * @param {string} cssText processTemplate 済みの CSS 全文
+ * @param {string} markerComment ブロック直前の目印コメント
+ * @param {string} label エラーメッセージ用ラベル
+ * @returns {string} :root { と対応する \n} の間の中身
+ */
+function extractRootBlockContent(cssText, markerComment, label) {
+  const markerIndex = cssText.indexOf(markerComment);
+  if (markerIndex === -1) {
+    throwScopeTemplateShapeChanged(label, `マーカーコメントが見つかりません: ${markerComment}`);
+  }
+  const braceStart = cssText.indexOf(':root {', markerIndex);
+  if (braceStart === -1) {
+    throwScopeTemplateShapeChanged(label, ':root ブロックの開始位置が見つかりません');
+  }
+  const contentStart = braceStart + ':root {'.length;
+  const closeIndex = cssText.indexOf('\n}', contentStart);
+  if (closeIndex === -1) {
+    throwScopeTemplateShapeChanged(label, ':root ブロックの終端が見つかりません');
+  }
+  return cssText.slice(contentStart, closeIndex);
+}
+
+/**
+ * プリミティブ `:root` ブロックの中身から `--color-*` の実値（リテラル）だけを
+ * Map に集める。`var(...)` を値に持つ宣言（プリミティブブロックには通常無いが
+ * 念のため）は解決対象にならないため除外する。
+ * @param {string} primitiveBlockContent extractRootBlockContent の戻り値
+ * @returns {Map<string, string>} `--color-blue-500` -> `oklch(...)` 等
+ */
+function buildPrimitiveColorValueMap(primitiveBlockContent) {
+  const map = new Map();
+  const pattern = /(--color-[\w-]+):\s*([^;]+);/g;
+  let match = pattern.exec(primitiveBlockContent);
+  while (match !== null) {
+    const [, varName, rawValue] = match;
+    const value = rawValue.trim();
+    if (!value.startsWith('var(')) {
+      map.set(varName, value);
+    }
+    match = pattern.exec(primitiveBlockContent);
+  }
+  return map;
+}
+
+/**
+ * セマンティックブロック内の `var(--color-*)` 参照を、プリミティブの実値まで
+ * 再帰的に解決してリテラル値に置き換える（`--radius-*` / `--shadow-*` は対象外
+ * のまま var() 参照を維持する — こちらは共有ロール衝突が起きない普遍的な
+ * スケール値のため、スコープ上書きでも安全に参照を残せる）。
+ *
+ * セマンティックトークンには `--color-neutral-*` → `--color-gray-*`（プリミティブ）
+ * のような1段の間接参照だけでなく、`--color-divider-low` → `--color-neutral-100`
+ * → `--color-gray-100` のような2段の間接参照も含まれるため、単純な1パス置換では
+ * 解決しきれない。解決できた宣言を都度 Map に足し込みながら複数パス回すことで、
+ * 間接参照の段数に依存せず解決する。
+ *
+ * プリミティブ（`--color-blue-*` 等）ではなくセマンティックトークン
+ * （`--color-primary-*` 等）をリテラル化してからスコープに閉じ込めるのがポイント:
+ * デフォルトでは `primary` と `info` が同じプリミティブ（例: blue）を共有して
+ * いるため、プリミティブ側をスコープ上書きすると primary を変えたつもりが
+ * info まで巻き込んで変わってしまう（issue #229 の議論）。セマンティック層で
+ * 実値に固定してしまえば、この巻き込みは起こらない。
+ * en: Flatten `var(--color-*)` references (not `--radius-*`/`--shadow-*`,
+ * which are safe shared universal scales) down to literal values, resolving
+ * multi-level indirection (divider -> neutral -> gray) over several passes.
+ * Flattening at the semantic layer (not the primitive layer) avoids the
+ * cross-role bleed where overriding a shared primitive like `blue` would
+ * unintentionally also change every other role that happens to reference it
+ * (e.g. `info` defaults to the same primitive as `primary`).
+ * @param {string} semanticBlockContent extractRootBlockContent の戻り値
+ * @param {Map<string, string>} primitiveMap buildPrimitiveColorValueMap の戻り値
+ * @returns {string} `var(--color-*)` がすべてリテラル値に置き換わった内容
+ * @throws {Error} 5パス以内に解決しきれない参照が残った場合（`E_SCOPE_UNRESOLVED_COLOR_VAR`）
+ */
+function flattenSemanticColorVars(semanticBlockContent, primitiveMap) {
+  const resolved = new Map(primitiveMap);
+  const declPattern = /(--color-[\w-]+):\s*([^;]+);/g;
+  // `(?:\s*,[^()]*)?` オプショナルで CSS の fallback 引数（`var(--x, fallback)`）
+  // も含めてマッチする。プリミティブは常に定義済みなので fallback 側は無視して
+  // 実値に置き換えてよい。これが無いと `var(--color-x, fallback)` 形式の参照が
+  // マッチせずスルーされ、`stillUnresolved` チェック（下記）でも検知されない
+  // まま非リテラルな var() がスコープ出力に紛れ込んでしまう。
+  // en: The optional `(?:\s*,[^()]*)?` also matches CSS fallback args
+  // (`var(--x, fallback)`). Without it, a fallback-form reference would
+  // silently pass through unflattened AND unflagged by the unresolved-check
+  // below, defeating the "fail loud" guarantee.
+  const colorVarRefPattern = /var\((--color-[\w-]+)(?:\s*,[^()]*)?\)/g;
+  let content = semanticBlockContent;
+
+  for (let pass = 0; pass < 5; pass += 1) {
+    let match = declPattern.exec(content);
+    while (match !== null) {
+      const [, name, rawValue] = match;
+      const value = rawValue.trim();
+      if (!value.startsWith('var(') && !resolved.has(name)) {
+        resolved.set(name, value);
+      }
+      match = declPattern.exec(content);
+    }
+    declPattern.lastIndex = 0;
+
+    let changed = false;
+    content = content.replace(colorVarRefPattern, (full, varName) => {
+      const literal = resolved.get(varName);
+      if (literal === undefined) {
+        return full;
+      }
+      changed = true;
+      return literal;
+    });
+
+    if (!changed) break;
+  }
+
+  const stillUnresolved = content.match(colorVarRefPattern);
+  if (stillUnresolved) {
+    const err = new Error(
+      `generate --scope: 次の色トークン参照を実値に解決できませんでした: ${stillUnresolved.join(', ')}`
+    );
+    err.code = 'E_SCOPE_UNRESOLVED_COLOR_VAR';
+    throw err;
+  }
+
+  return content;
+}
+
+// `--scope` に渡すセレクタ文字列は生成 CSS にそのまま埋め込まれるため、denylist
+// （`{` `}` `/*` 等の既知の危険文字だけを弾く）ではなく **allowlist** で検証する。
+// denylist だと `;` や `@` を見落とすと `@import url(...);` のような文が
+// ラップ用の `{` の手前で「閉じて」しまい、後続の `{ ... }` が無関係な空セレクタ
+// ルールとして扱われる（意図した上書きが消え、任意の外部 CSS import が
+// 差し込まれる）CSS injection を許してしまう。CSS セレクタが実際に必要とする
+// 文字集合（英数字・空白・属性セレクタ用の `[]="'`・クラス/ID の `.` `#`・
+// 疑似クラスの `:`・結合子 `>` `+` `~`・複数セレクタ区切りの `,`）だけを許可し、
+// それ以外（`;` `@` `{` `}` `/` `\` 等）は default-deny にする。
+// en: Validate --scope with an ALLOWLIST, not a denylist. A denylist that
+// misses `;`/`@` lets a value like `@import url(...);` terminate before the
+// wrapping `{`, turning the intended override into a dropped empty-selector
+// rule while smuggling an arbitrary external `@import` — a real CSS
+// injection bypass. Only allow the character set real CSS selectors need.
+// `\s` は使わない — 改行/CR も許可してしまい、複数行にまたがる injection の
+// 余地を残す。CSS セレクタは1行で書くのが通常のため、空白はスペース/タブのみ許可する。
+// en: Use an explicit space/tab class instead of `\s` — `\s` also matches
+// newlines/CR, which would defeat the point of rejecting multi-line values.
+const SCOPE_SELECTOR_SAFE_PATTERN = /^[A-Za-z0-9_\-.,:>+~=[\]"' \t#]+$/;
+
+/**
+ * `--scope` のセレクタ文字列を検証する。
+ * @param {unknown} selector
+ * @throws {Error} 空文字列、非文字列、または許可されていない文字を含む場合（`E_UNSAFE_SCOPE_SELECTOR`）
+ */
+function assertSafeScopeSelector(selector) {
+  if (typeof selector !== 'string' || selector.trim().length === 0) {
+    const err = new Error('--scope には空でないセレクタ文字列を指定してください');
+    err.code = 'E_UNSAFE_SCOPE_SELECTOR';
+    throw err;
+  }
+  if (!SCOPE_SELECTOR_SAFE_PATTERN.test(selector)) {
+    const err = new Error(
+      `--scope に許可されていない文字が含まれています（CSS セレクタとして使える英数字・` +
+        `[ ] = " ' . : > + ~ # , 空白のみ許可）: ${JSON.stringify(selector)}`
+    );
+    err.code = 'E_UNSAFE_SCOPE_SELECTOR';
+    throw err;
+  }
+}
+
+const PRIMITIVE_ROOT_MARKER = '/* Primitive Tokens */';
+const SEMANTIC_ROOT_MARKER =
+  '/* セマンティックトークン - CSS変数としてランタイムで利用可能にする */';
+
+/**
+ * 単一バンドル内でランタイムにテーマ配色を切り替えたいケース（issue #229）向けの
+ * `generate` バリアント。通常の `generate` が出力する `@theme inline`（top-level
+ * 必須で nest 不可）には一切触れず、セマンティックトークン（`--color-primary-*`
+ * 等）だけを実値までリテラル化した上で、指定セレクタの中に閉じ込めて出力する。
+ *
+ * ベースとなる CSS（`@theme inline` を含む通常の `generate` 出力）を1つ、
+ * バリアントごとにこの `generateScopedCSS` の出力を1つ、という組み合わせで
+ * 同時 import すれば、`@theme inline` の重複によるビルド衝突を起こさずに
+ * `[data-tenant-theme="..."]` のようなランタイム属性でテーマを切り替えられる
+ * （README.md の「単一バンドルでランタイム切替する場合」参照）。
+ *
+ * フォント import・`@source`・SparkleHead.tsx・globals.css パッチなど
+ * ドキュメント全体に関わる **出力** は行わない（ベース側の通常 `generate` 実行が
+ * 既に担っているため、バリアントごとに重複させる必要が無い）。ただし内部的に
+ * `processTemplate`（通常の `generate` と共通）を経由するため、フォント設定
+ * （`font-pro` / `font-mono` / `fonts.*`）の validation（`assertSafeFontFamily` /
+ * `assertSafeFontWeights` 等）自体は通常の `generate` と同様に適用される。
+ * 出力しないだけで、config の妥当性チェックは変わらず全項目に効く。
+ *
+ * en: A `generate` variant for runtime theme switching within a single bundle
+ * (issue #229). Never touches `@theme inline` (which Tailwind v4 requires to
+ * stay top-level and un-nestable) — instead flattens only the semantic color
+ * tokens down to literal values and wraps them in the given selector. Pair one
+ * normal `generate` run (the base CSS, with `@theme inline`) with one
+ * `generateScopedCSS` run per variant; importing both simultaneously is safe
+ * because the scoped output never redeclares `@theme inline`.
+ *
+ * @param {string|null} configPath カスタム設定ファイルのパス（オプション）
+ * @param {string} outputPath 出力先パス（必須。既定の sparkle-design.css を
+ *   誤って上書きしないよう、省略時は throw する）
+ * @param {string} scopeSelector 出力全体をラップするセレクタ（例: `[data-tenant-theme="admin"]`）
+ * @returns {{ outputPath: string, scopeSelector: string }}
+ */
+export function generateScopedCSS(configPath, outputPath, scopeSelector) {
+  if (!outputPath) {
+    const err = new Error(
+      '--scope 指定時は -o/--output の指定が必須です（既定の sparkle-design.css を誤って上書きしないため）'
+    );
+    err.code = 'E_SCOPE_OUTPUT_REQUIRED';
+    throw err;
+  }
+  assertSafeScopeSelector(scopeSelector);
+
+  console.log(
+    `🎯 スコープ限定でセマンティックトークンを生成します（scope: ${scopeSelector}）...\n`
+  );
+
+  const rawConfig = loadConfig(configPath);
+  const config = resolveExtend(rawConfig, configPath);
+  const template = loadTemplate();
+  const colors = loadColors();
+  const grayMapping = loadGrayMapping();
+  const radiusMapping = loadRadiusMapping();
+
+  assertValidRadius(config.radius, radiusMapping);
+
+  const { css: processedCSS } = processTemplate(
+    template,
+    config,
+    grayMapping,
+    radiusMapping,
+    colors
+  );
+
+  const primitiveBlock = extractRootBlockContent(processedCSS, PRIMITIVE_ROOT_MARKER, 'primitive');
+  const semanticBlock = extractRootBlockContent(processedCSS, SEMANTIC_ROOT_MARKER, 'semantic');
+
+  const primitiveMap = buildPrimitiveColorValueMap(primitiveBlock);
+  const flattenedSemanticBlock = flattenSemanticColorVars(semanticBlock, primitiveMap);
+
+  const header = [
+    `/* Sparkle Design — スコープ限定テーマ上書き（scope: ${scopeSelector}） */`,
+    '/* generate --scope により自動生成されます。@theme inline は含まれません。 */',
+    '/* 手動編集した場合、再度 generate --scope を実行すると上書きされます。 */',
+    '',
+  ].join('\n');
+
+  const outputCSS = `${header}${scopeSelector} {${flattenedSemanticBlock}\n}\n`;
+
+  const resolvedOutputPath = path.resolve(outputPath);
+  // `writeCSS()` と同じエラーメッセージ（MESSAGES.CSS_WRITE_FAILED）で統一する。
+  // ただし `writeCSS()` と異なり `process.exit(1)` は呼ばない — throw のままに
+  // しておくことで、bin/sparkle-design.js の外側 catch が一律 exit 1 に昇格
+  // させる既存の仕組みに乗せられ、かつテストから try/catch で検証できる
+  // （process.exit を直接呼ぶとテストプロセスごと落ちてしまう）。
+  // en: Reuse writeCSS()'s error message for consistency, but keep throwing
+  // (not process.exit) so bin/sparkle-design.js's outer catch handles the
+  // exit-1 escalation uniformly and tests can assert on the thrown error.
+  try {
+    const outputDir = path.dirname(resolvedOutputPath);
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+    fs.writeFileSync(resolvedOutputPath, outputCSS, 'utf8');
+  } catch (error) {
+    const err = new Error(MESSAGES.CSS_WRITE_FAILED(error.message));
+    err.code = 'E_SCOPE_CSS_WRITE_FAILED';
+    throw err;
+  }
+  console.log(`✅ スコープ限定 CSS を生成しました: ${resolvedOutputPath}`);
+
+  return { outputPath: resolvedOutputPath, scopeSelector };
+}
+
 /**
  * 生成されたCSSをファイルに書き出す
  * @param {string} cssContent CSS内容
@@ -898,10 +1199,7 @@ export function generateCSS(
   // index.html (Astro / Remix / plain SPA) must not receive Sparkle's
   // managed block.
   const cwdForHtml = process.cwd();
-  if (
-    isViteProject(cwdForHtml) &&
-    fs.existsSync(path.resolve(cwdForHtml, 'index.html'))
-  ) {
+  if (isViteProject(cwdForHtml) && fs.existsSync(path.resolve(cwdForHtml, 'index.html'))) {
     const htmlResult = upsertViteIndexHtmlFonts(cwdForHtml, resolvedFonts);
     if (htmlResult.status === 'created' || htmlResult.status === 'updated') {
       const displayPath = path.relative(cwdForHtml, htmlResult.path) || htmlResult.path;
@@ -1007,4 +1305,11 @@ export {
   removeFontImportsFromCSS,
   updateGlobalsWithFonts,
   manageFontImports,
+  // generate --scope 内部ヘルパー（テスト用）
+  extractRootBlockContent,
+  buildPrimitiveColorValueMap,
+  flattenSemanticColorVars,
+  assertSafeScopeSelector,
+  PRIMITIVE_ROOT_MARKER,
+  SEMANTIC_ROOT_MARKER,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparkle-design-cli",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Sparkle Design CLI — プロジェクトセットアップ、CSS・フォント生成、アンチパターン検査、AI エージェント（Claude Code / Cursor / Codex）向けのガードと hook 設定まで一括で行う sparkle-design 公式 CLI。",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",