sparkle-design-cli 2.4.1 → 2.5.0-beta.1

package/README.md

@@ -2,6 +2,19 @@
 
 Sparkle Design のプロジェクト初期セットアップ、CSS 生成、導入先プロジェクト向けのアンチパターン検査、AI エージェント向け guard 設定を行う CLI ツールです。
 
+この README には**導入して動かすまでに要る最低限**だけを置いています。個別の詳細は下記を参照してください。
+
+| ドキュメント                                   | 内容                                                                        |
+| ---------------------------------------------- | --------------------------------------------------------------------------- |
+| [docs/anti-patterns.md](docs/anti-patterns.md) | `check` の抑制方法、新セマンティックトークンへの移行、余白スケール          |
+| [docs/config.md](docs/config.md)               | `sparkle.config.json` の `extend`（フォント追加・カスタムカラー・任意 CSS） |
+| [docs/theming.md](docs/theming.md)             | 複数のテーマ配色を 1 デプロイでサポートする（`generate --scope`）           |
+| [docs/manual-setup.md](docs/manual-setup.md)   | Next.js / Vite 以外への手動セットアップ                                     |
+| [docs/plugins.md](docs/plugins.md)             | アンチパターン検査をプラグインで拡張する                                    |
+| [CONTRIBUTING.md](CONTRIBUTING.md)             | このリポジトリ自体の開発手順                                                |
+
+**有効なルールの一覧はドキュメントではなく `npx sparkle-design-cli rules` が出します。**
+
 ## クイックスタート
 
 既存の Next.js / Vite プロジェクトで以下を実行するだけで導入完了します。詳細は [`setup` セクション](#setup-プロジェクトのフルセットアップ) を参照してください。
@@ -57,6 +70,9 @@ npx sparkle-design-cli check src --strict
 
 # AI 向けに JSON で検査結果と手動確認項目を取得
 npx sparkle-design-cli check src --format json
+
+# 現在有効なアンチパターンルールを一覧表示（プラグイン由来のものも含む）
+npx sparkle-design-cli rules
 ```
 
 ### generate: 基本的な使用方法
@@ -101,7 +117,7 @@ sparkle-design-cli generate --globals-path src/styles/app.css
 # CI 向け: @source 注入や Tailwind import 欠落などの失敗を exit 1 にする
 sparkle-design-cli generate --strict
 
-# 単一バンドル内でランタイムにテーマ切替したい場合（詳細は「複数のテーマ配色を1デプロイでサポートしたい場合」参照）
+# 単一バンドル内でランタイムにテーマ切替したい場合（詳細は docs/theming.md 参照）
 sparkle-design-cli generate -c ./config/sparkle.admin.json --scope '[data-tenant-theme="admin"]' -o ./src/styles/sparkle-admin-scope.css
 ```
 
@@ -116,7 +132,7 @@ sparkle-design-cli generate -c ./config/sparkle.admin.json --scope '[data-tenant
   - デザインシステムパッケージが `package.json` に入っているのに Tailwind エントリ CSS が見つからない
   - エントリ CSS はあるが `@import "tailwindcss";` が書かれていない（警告メッセージに追記すべき行まで actionable に表示）
   - エントリ CSS への書き込みに失敗した
-- `--scope <セレクタ>`: `@theme inline` には触れず、セマンティックトークン（`--color-primary-*` 等）だけを実値までリテラル化して指定セレクタの中にラップ出力する。単一バンドル内でランタイムにテーマ切替したい場合向け（`-o/--output` の指定が必須）。詳細は「複数のテーマ配色を1デプロイでサポートしたい場合」の「ケース B」を参照
+- `--scope <セレクタ>`: `@theme inline` には触れず、セマンティックトークン（`--color-primary-*` 等）だけを実値までリテラル化して指定セレクタの中にラップ出力する。単一バンドル内でランタイムにテーマ切替したい場合向け（`-o/--output` の指定が必須）。詳細は[docs/theming.md](docs/theming.md) の「ケース B」を参照
 
 ### check: アンチパターン検査
 
@@ -139,143 +155,47 @@ sparkle-design-cli check --help
 #### check オプション一覧
 
 - `-h, --help`: ヘルプメッセージを表示
-- `--strict`: 違反が見つかった場合に exit code 1 で終了
+- `--strict`: **`error` の違反があるか、実行に失敗して未検査のルールがある**場合に exit code 1 で終了（`warning` / `info` は exit code に影響しません）
 - `--format <text|json>`: 出力形式。AI 連携では `json` を推奨
 
-#### 現在検出するルール
-
-- フォーム入力に Dialog を使わない
-- DialogCancel/DialogAction を Button で二重ラップしない
-- children なしの Button に prefixIcon / suffixIcon を使わない
-- Material Symbols を className 直書きで使わない
-- shadcn/ui 既定 token を Sparkle Design 内へ持ち込まない
-- Tailwind デフォルト typography を Sparkle Design コンポーネント内で使わない
-- CardTitle に typography 系クラスを付与しない
-- CardControl に Button / IconButton 以外を入れない
-- Card 系コンポーネントのデフォルト padding を安易に上書きしない
-- asChild 使用時に prefixIcon / suffixIcon / isLoading を使わない
-- Sparkle Design コンポーネントでは isDisabled を使う
-- Button の prefixIcon / suffixIcon に JSX を渡さない
-- Icon の children にテキストを渡さない
-- クリック可能な Card は ClickableCard を使う（button / a / role="button" でラップしない）
-
-#### 導入先での推奨設定
-
-```json
-{
-  "scripts": {
-    "lint:sparkle": "npx --yes sparkle-design-cli check src --strict"
-  }
-}
-```
-
-AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
+#### ルールの強さ（severity）
 
-#### アンチパターン検知の拡張（プラグイン）
+すべてのルールは強さを持ちます。すべてを同じ重みで扱うと、全部を過剰に守って不自然な実装になるか、全部を読み流すかの両極端に振れるためです。
 
-他のコンポーネントライブラリ（社内拡張など）に固有のアンチパターン検知を、`sparkle-design-cli` 本体に変更を加えず追加できる拡張機構があります。
+| 強さ      | 意味                                   | `--strict` / stop-hook   |
+| --------- | -------------------------------------- | ------------------------ |
+| `error`   | 例外なし。必ず直す                     | **失敗させる（exit 1）** |
+| `warning` | 原則ダメだが、理由があれば例外を認める | 失敗させない（報告のみ） |
+| `info`    | 参考。従わなくてもよい選択肢           | 失敗させない（報告のみ） |
 
-##### 仕組み
+出力には `path:line [severity] [rule-id] 説明` の形で強さとルール ID が入ります。ルール ID は内容が変わっても変えないので、指摘の根拠を後から辿れます。
 
-プラグインを提供するパッケージは、自身の `package.json` に検知ルールのエントリを宣言します:
+JSON 出力では `summary.severityCounts` に内訳が、`summary.blockingFindingCount` に exit code へ効く件数が入ります。
 
-```json
-{
-  "name": "@your-org/your-design-extensions",
-  "sparkleCli": {
-    "antiPatterns": "./anti-patterns/index.js"
-  }
-}
-```
+**ルールの実行に失敗した場合**（プラグインの不具合など）は、`report.skippedRules` と `summary.skippedRuleCount` に記録され、`--strict` は失敗します。ルールが落ちた状態は「違反ゼロ」ではなく「検査していない」ためです。stderr にも警告が出ます（同じルールについては 1 回だけ）。
 
-エントリファイルは `defineAntiPatternPlugin` を使ってプラグインを default export します:
-
-```js
-import { defineAntiPatternPlugin } from 'sparkle-design-cli/plugin';
-
-export default defineAntiPatternPlugin({
-  groups: [
-    {
-      id: 'your-org-foocard-nesting',
-      check: {
-        description: 'FooCard を別の FooCard でラップしないでください。',
-        recommendation: '入れ子表示が必要なら FooStack を使ってください。',
-        pattern: /<FooCard[^>]*>[\s\S]*?<FooCard/g,
-      },
-    },
-  ],
-  manualReviewReminders: [
-    {
-      id: 'your-org-foocard-color',
-      message: 'FooCard の color token が brand に揃っているか確認してください。',
-    },
-  ],
-});
-```
+#### 検出するルールを調べる
 
-##### 複雑な検出（`match` とヘルパー）
-
-単純な正規表現では安全に書けない検出（accessible name の有無、prop の組み合わせ、JSX 式を意識した走査など）には、`check.pattern` の代わりに `check.match` を使います。`match` は `(content, helpers)` で呼ばれ、第 2 引数の `helpers` に JSX パースヘルパーが **CLI から注入** されます。各パッケージがパース処理を再実装して同じ false-positive / negative を踏むのを防ぐ仕組みです。
-
-```js
-// sparkle-design-cli を import しない（plain object を default export）
-export default {
-  groups: [
-    {
-      id: 'your-org-avatar-accessible-name',
-      check: {
-        description: 'Avatar に accessible name がありません。',
-        recommendation: 'aria-label か alt を指定してください。',
-        // helpers = { matchOpeningTags, hasProp, isMultipleTypeProp, findOpeningTagEnd }
-        match: (content, { matchOpeningTags, hasProp }) =>
-          matchOpeningTags(
-            content,
-            'Avatar',
-            (props) =>
-              !hasProp(props, 'src') &&
-              !hasProp(props, 'aria-label') &&
-              !hasProp(props, 'aria-labelledby')
-          ),
-      },
-    },
-  ],
-};
+```bash
+npx sparkle-design-cli rules              # severity 別に一覧表示
+npx sparkle-design-cli rules --format json
 ```
 
-注入されるヘルパー（`check.match` の第 2 引数）:
-
-| ヘルパー                                        | 用途                                                                                 |
-| ----------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `matchOpeningTags(content, tagName, predicate)` | `<Tag ...>` / `<Tag ... />` を走査し predicate が真のものを `{ index, text }` で返す |
-| `hasProp(propsBlock, propName)`                 | prop が指定されているかを厳密判定（`aria-*` / `data-*` を誤検出しない）              |
-| `isMultipleTypeProp(propsBlock)`                | `type` が静的に `"multiple"` か判定（動的式は `false`）                              |
-| `findOpeningTagEnd(content, startIdx)`          | 低レベル: 開きタグの閉じ `>` のオフセット（文字列 / JSX 式を考慮）。無ければ `-1`    |
-
-> 💡 `match` を使うプラグインは（上の `pattern` 例の `defineAntiPatternPlugin` import と違い）`sparkle-design-cli` を **import せず** plain object として default export してください。`helpers` はランタイムで CLI が注入するため import は不要で、生 JS のまま配布され npx 経由で実行される consumer 環境でも確実に解決されます。`pattern` と `match` は排他で、どちらか一方のみ指定します。
-
-##### 自動 discovery
+**一覧をドキュメントに書かないのは、有効なルールがプロジェクトごとに違うためです。** プラグインはコンシューマの `package.json` から自動発見されるので、固定の一覧はプラグインを入れた利用者にとって最初から不正確になります。
 
-`sparkle-design-cli check` 実行時、CLI は consumer プロジェクトの `package.json` の `dependencies` / `devDependencies` / `peerDependencies` / `optionalDependencies` を走査し、`sparkleCli.antiPatterns` を宣言しているパッケージを発見次第ロードしてビルトインのルールにマージします。
+個別ルールの背景・移行手順・抑制方法は [docs/anti-patterns.md](docs/anti-patterns.md) を参照してください。
 
-- プラグインパッケージが install されていなければ何も起きません
-- ロードや評価で失敗したプラグインは warn を出してスキップし、残りのルールで check は継続されます
-- ルール ID はビルトイン・他プラグインと名前空間を共有するため、`your-org-` のようなプレフィックスを付けて衝突を避けてください
-
-> ⚠️ **信頼境界**: プラグインのエントリファイルは `import()` で **任意の JavaScript を実行** します。これは Node.js の通常のパッケージ依存と同じ性質ですが、`sparkle-design-cli check` 実行時に走るコードが増えるという点で意識しておく必要があります。プラグインは信頼できる org / 著者のパッケージのみインストールしてください。
-
-##### 契約仕様の確認
-
-最新の契約仕様は CLI から直接出力できます:
-
-```bash
-# 契約 shape のドキュメントを出力
-npx --yes sparkle-design-cli plugin-spec
+#### 導入先での推奨設定
 
-# 現在のプロジェクトで discover されたプラグインを一覧
-npx --yes sparkle-design-cli plugin-spec --list
+```json
+{
+  "scripts": {
+    "lint:sparkle": "npx --yes sparkle-design-cli check src --strict"
+  }
+}
 ```
 
-完全な型定義は `node_modules/sparkle-design-cli/lib/plugin-api.js` の JSDoc を参照してください。
+AI エージェントや CI からこの `lint:sparkle` を呼ぶ運用にすると、ガイドラインの注意書きだけに頼らず機械的に検査できます。
 
 ### setup: プロジェクトのフルセットアップ
 
@@ -332,120 +252,6 @@ npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaf
 
 `setup` は通常実行時も JSON サマリーを stdout に表示します。`--dry-run` を付けると、その JSON を表示したままファイル変更だけを抑止します。
 
-### 手動セットアップ（Next.js / Vite 以外のプロジェクト向け）
-
-`setup` コマンドは **Next.js App Router** と **Vite** を前提に scaffold / entry CSS の配置を自動判定します。Remix / Astro / TanStack Start など他のフレームワークや、独自ディレクトリ構成のプロジェクトでは自動判定が外れるため、以下の手順で手動セットアップすることを推奨します。
-
-#### 手順
-
-**1. パッケージをインストール**
-
-```bash
-# 本体
-pnpm add sparkle-design        # or npm install / yarn add / bun add
-
-# Tailwind v4
-pnpm add -D tailwindcss @tailwindcss/postcss
-```
-
-**2. `sparkle.config.json` をプロジェクトルートに作成**
-
-```json
-{
-  "primary": "blue",
-  "font-pro": "Inter",
-  "font-mono": "JetBrains Mono",
-  "radius": "md"
-}
-```
-
-選択肢の詳細は本 README の「[設定オプション](#設定オプション)」を参照してください。
-
-**3. `postcss.config.mjs` をプロジェクトルートに作成**
-
-```js
-export default {
-  plugins: {
-    '@tailwindcss/postcss': {},
-  },
-};
-```
-
-**4. Tailwind エントリ CSS を自前で用意**
-
-既存プロジェクトに組み込む場合、`@import "tailwindcss";` を含む CSS ファイル（例: `src/styles/app.css`）があればそれを使います。無ければ作成してアプリケーションのエントリから import します。
-
-**5. `generate` を実行**
-
-```bash
-npx --yes sparkle-design-cli generate
-```
-
-これで `sparkle-design.css` が `src/app/sparkle-design.css` に生成され、`SparkleHead.tsx` も同じ場所に出ます。エントリ CSS の検出に失敗する場合は `sparkle.config.json` の `extend.globals-path` に明示指定してください。
-
-```json
-{
-  "primary": "blue",
-  "extend": {
-    "globals-path": "src/styles/app.css"
-  }
-}
-```
-
-**6. フォントの `<link>` タグを手動で配置**
-
-Next.js / Vite 以外ではアプリケーションフレームワークごとに「`<head>` 相当」の配置方法が異なります。自動生成される `SparkleHead.tsx` はそのまま使えるはずですが、使えない場合は中身（`preconnect` + Google Fonts の `<link>` タグ群）を自前のレイアウトにコピーしてください。
-
-たとえば Astro なら `src/layouts/BaseLayout.astro` の `<head>` に直接書きます:
-
-```html
-<link rel="preconnect" href="https://fonts.googleapis.com" />
-<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
-<link
-  rel="stylesheet"
-  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:FILL,wght@0..1,500&display=block"
-/>
-<!-- sparkle.config.json の font-pro / font-mono に合わせた Google Fonts URL -->
-<link
-  rel="stylesheet"
-  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap"
-/>
-<link
-  rel="stylesheet"
-  href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;700&display=swap"
-/>
-```
-
-**7. アンチパターン検査を package.json に追加（任意）**
-
-```json
-{
-  "scripts": {
-    "lint:sparkle": "npx --yes sparkle-design-cli check src --strict",
-    "lint:sparkle:json": "npx --yes sparkle-design-cli check src --format json"
-  }
-}
-```
-
-**8. AI エージェントを使うなら Guard ブロックと hook を手動で配置**
-
-AI ガード（`CLAUDE.md` / `AGENTS.md`）と hook 設定（`.claude/settings.json` / `.cursor/hooks.json` / `.codex/hooks.json`）は `setup` に任せるのが最も楽です。Cursor 用 Guard は rc.4 から AGENTS.md に統一しました（`.cursor/rules/*.mdc` は条件付き読み込みのため）。
-
-```bash
-# ガード追加・hook 設定のみ（パッケージインストールや scaffold はスキップ）
-npx --yes sparkle-design-cli setup --assistant claude --skip-install --skip-scaffold --skip-generate
-```
-
-この `--skip-*` 組み合わせは手動セットアップ済みのプロジェクトに対して Guard + hook だけ差し込むのに使えます。
-
-#### 既知の未対応ケース
-
-- **モノレポ（workspaces）**: `generate` は実行した cwd からパッケージマネージャーを遡及検出しないため、サブパッケージで直接実行するのが確実です。
-- **CSS 以外のエントリ（CSS-in-JS / vanilla-extract 等）**: Sparkle Design は Tailwind v4 の `@source` + CSS variable 前提で作られているため、ビルドパイプラインの外で CSS を扱うソリューションは対象外です。
-- **Tailwind v3**: `@source` ディレクティブ依存のため v4 必須です。
-
-Next.js / Vite 以外で導入したい方で困ったときは Issue で教えていただけると助かります。
-
 ## 設定ファイル (sparkle.config.json)
 
 ### 設定ファイルの作成
@@ -461,233 +267,11 @@ Next.js / Vite 以外で導入したい方で困ったときは Issue で教え
 
 #### Core（プラグインが出力）
 
-- `primary`: プライマリカラー（必須）。次の7色のいずれかを指定してください: `blue` / `red` / `orange` / `yellow` / `purple` / `green` / `pink`。未指定、またはこれら以外の値を指定した場合、`generate` は例外を投げて停止します（そのブランドカラー専用の `--color-primary-*` / `--color-gray-*` を用意していないため、`var()` の参照先が存在せず壊れた CSS になってしまうのを防ぐためのバリデーションです）。7色にないブランドカラーを使いたい場合は [extend.custom-css](#extendcustom-css) を参照してください。
+- `primary`: プライマリカラー（必須）。次の7色のいずれかを指定してください: `blue` / `red` / `orange` / `yellow` / `purple` / `green` / `pink`。未指定、またはこれら以外の値を指定した場合、`generate` は例外を投げて停止します（そのブランドカラー専用の `--color-primary-*` / `--color-gray-*` を用意していないため、`var()` の参照先が存在せず壊れた CSS になってしまうのを防ぐためのバリデーションです）。7色にないブランドカラーを使いたい場合は [docs/config.md の `extend.custom-css`](docs/config.md#extendcustom-css) を参照してください。
 - `font-pro`: プロポーショナルフォント（[Google Fonts](https://fonts.google.com/) の名前）
 - `font-mono`: モノスペースフォント（[Google Fonts](https://fonts.google.com/) の名前）
 - `radius`: 角丸設定（必須）。次のいずれかを指定してください: `none` / `xs` / `sm` / `md` / `lg` / `xl` / `2xl` / `3xl`。未指定、またはこれら以外の値を指定した場合、`primary` と同様に `generate` は例外を投げて停止します（無効な値だと `--radius-action` が壊れた参照のまま出力されるのを防ぐためです）。
 
-### extend セクション（拡張設定）
-
-Figma プラグインが出力する基本4項目に加えて、プロジェクト固有の拡張を `extend` セクションにまとめます。`extend` はオブジェクト直書き（推奨）またはファイルパスを指定できます。
-
-```json
-{
-  "primary": "blue",
-  "font-pro": "Montserrat",
-  "font-mono": "Roboto Mono",
-  "radius": "md",
-  "extend": {
-    "fonts": {
-      "pro": [
-        { "family": "Montserrat", "weights": [500, 600, 700] },
-        { "family": "Noto Sans JP", "weights": [400, 500, 600, 700] }
-      ],
-      "mono": [{ "family": "Roboto Mono", "weights": [400, 700] }]
-    },
-    "source-packages": ["@goodpatch/sparkle-design-internal"],
-    "custom-css": "./src/app/custom-tokens.css"
-  }
-}
-```
-
-ファイル参照も可能です：
-
-```json
-{
-  "primary": "blue",
-  "font-pro": "Montserrat",
-  "font-mono": "Roboto Mono",
-  "radius": "md",
-  "extend": "./sparkle.extend.json"
-}
-```
-
-#### extend.fonts
-
-フォントごとにウェイトを個別指定。`extend.fonts` がない場合は `font-pro` / `font-mono` + デフォルトウェイト `[400, 700]` が使われます。`extend.fonts` が存在しても `fonts.pro` / `fonts.mono` のどちらかが未指定なら、そのスロットのみ `font-pro` / `font-mono` にフォールバックします。同じフォントファミリーが `pro` と `mono` で重複する場合、ウェイトはマージされ import は 1 行に統合されます。
-
-#### extend.source-packages
-
-`sparkle-design` を npm パッケージとして利用する場合に必須。Tailwind エントリ CSS（自動検出）に `@source` ディレクティブを自動挿入します。`sparkle-design` は常にデフォルトで含まれます。
-
-#### extend.custom-css
-
-プロジェクト固有のカスタムトークンの CSS ファイルパス。Tailwind エントリ CSS に `@import` が自動挿入されます。`sparkle-design.css` に直接追加すると `generate` 実行時に上書きされるため、必ず別ファイルに分離してください。
-
-この `@import` は `sparkle-design.css` の直後に挿入されるため、`custom-css` 側で書いた `:root { --color-xxx: ... }` は CSS の cascade（後勝ち）でそのまま `sparkle-design.css` のトークンを上書きします。属性セレクタや `!important` を使う必要はありません。
-
-##### カスタムブランドカラーを primary にしたい場合
-
-`primary` は 7 色のいずれかしか受け付けません（前述の Core セクション参照）。7 色にないブランドカラーを使いたい場合は、`primary` は 7 色から見た目が近いものを仮に選んだ上で、`extend.custom-css` で `--color-primary-*` と `--color-gray-*` をブランドカラー基準の値で丸ごと再定義してください。`primary` の選択自体は `custom-css` 側の定義で完全に上書きされるため実質的な意味を持たなくなりますが、フィールドとしては有効な値を入れておく必要があります。
-
-```css
-/* custom-tokens.css */
-:root {
-  /* ブランドカラー基準の primary パレット（50〜900） */
-  --color-primary-50: oklch(97% 0.02 250);
-  /* ... */
-  --color-primary-500: oklch(55% 0.18 250);
-  /* ... */
-  --color-primary-900: oklch(20% 0.08 250);
-
-  /* primary に合わせた gray パレット（50〜900）も必ず一緒に定義する。
-     gray だけ 7 色デフォルトのままだと、primary だけ浮いて見えるトーンずれが起きる */
-  --color-gray-50: oklch(98% 0.005 250);
-  /* ... */
-  --color-gray-900: oklch(22% 0.01 250);
-}
-```
-
-`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 つのデプロイでサポートする」ケースの推奨パターンです。**「画面ごとに読み込む CSS を切り替える」場合と「1 つの画面内でランタイムに切り替える」場合とで推奨パターンが異なる**ので、まずどちらのケースかを判断してください。
-
-### ケース A: 画面（ビルド）ごとにバリアントが固定される場合 → 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"
-}
-```
-
-```jsonc
-// config/sparkle.employee.json
-{
-  "primary": "green",
-  "font-pro": "Inter",
-  "font-mono": "JetBrains Mono",
-  "radius": "md"
-}
-```
-
-```bash
-npx sparkle-design-cli generate -c ./config/sparkle.admin.json -o ./src/styles/sparkle-admin.css
-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 を分ける、など）。
-
-**重要: この 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` の出力とマージして使えます）。
-- **v2.4.1 以降**: ベース側 `generate` が出す `@theme inline` の各宣言は、プリミティブへの直接参照ではなく同名のセマンティック変数への自己参照（例: `--color-primary-500: var(--color-primary-500)`）になっています。Tailwind v4 は `@theme inline` の宣言右辺をそのまま compiled utility class にインライン展開する仕様のため、これが無いと `.bg-primary-500` 等の compiled utility は最初からプリミティブ変数だけを参照し、`--scope` がセマンティック変数だけを上書きしても utility class には一切反映されません（v2.4.0 はこの自己参照が無く、`--scope` の上書きが compiled utility に効かない状態でした）。v2.4.1 以降を使ってください。
-
-このパターンは、次の「非推奨: 属性スコープでの Tailwind クラス上書き」が抱えていた脆さも同時に解消します。`--scope` が上書きするのは Sparkle が公開しているトークン契約（`--color-primary-*` 等の CSS 変数）だけであり、ユーティリティクラス名やコンポーネント内部の specificity には一切依存しません。そのため、Sparkle 側のコンポーネント実装（クラス名の付け方や compound attribute selector 等）が変わっても、`--scope` の出力が壊れることはありません。
-
-### 非推奨: 単一 CSS + 属性スコープでの Tailwind クラス上書き
-
-`sparkle-design.css` を 1 本のまま、`[data-theme="xxx"] .bg-primary-500 { ... }` のような属性セレクタで Tailwind ユーティリティクラスを個別に上書きする方式は **推奨しません**。
-
-- コンポーネント側の実装詳細（クラス名の付け方や CSS の specificity）に依存するため、Sparkle 側の内部実装（例: 状態別カラーリングで compound attribute selector を使っているコンポーネント）が変わると、`!important` を使っても上書きが効かなくなることがあります。上書き対象は Sparkle が公開している契約（config / トークン）ではなく非公開の実装詳細なので、バージョンアップのたびに壊れるリスクを consumer 側が抱え続けることになります。
-- 上書きが必要なクラス／コンポーネントが増えるたびに、手動でセレクタを足していく必要があり、考慮漏れに気づきにくいです。
-
-上記のリスクを踏まえると、テーマ切り替えは「ケース A: config 分割」または「ケース B: `generate --scope`」+ `extend.custom-css` によるトークンレベルの上書き（cascade 順で確実に勝つ）で完結させる方が、Sparkle のバージョンアップに対しても壊れにくく、見通しの良い実装になります。
-
-### トレードオフ
-
-| 観点           | ケース A: config 分割（推奨・画面ごと固定）                                                                                      | ケース B: `generate --scope`（推奨・単一バンドルでランタイム切替）                           | 属性スコープ上書き（非推奨）                                                                                        |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| 適用シーン     | 1 画面につき常に 1 バリアントだけを読み込める                                                                                    | 1 バンドル内で属性の付け外しだけで切り替えたい                                               | （非推奨のため参考情報）                                                                                            |
-| ファイルサイズ | バリアントの数だけ CSS が増える（各 CSS は 7 色パレット全体を含む）。1 画面 1 バリアントのみ読み込む運用なら実質的な増分は小さい | ベース CSS 1 本 + バリアントごとの軽量な差分 CSS（セマンティックトークンのみ）               | 単一 CSS + 上書き分の差分のみで増分は小さい                                                                         |
-| FOUC リスク    | サーバー側 / ビルド時にバリアントを決定できるならほぼ無し                                                                        | 属性付与のタイミング次第でリスクがある（初期描画後に属性が付くと一瞬デフォルト配色が見える） | クライアント側で属性を付与するタイミング次第でリスクがある                                                          |
-| 保守性         | Sparkle が公開している config / トークンだけに依存するため、コンポーネント内部実装の変更に影響されにくい                         | 同左（トークンだけに依存し、ユーティリティクラス名や specificity に依存しない）              | コンポーネントの内部実装（クラス名・specificity）に依存するため、Sparkle 側の変更で上書きが効かなくなるリスクがある |
-
 ## 出力
 
 - デフォルト出力先: `src/app/sparkle-design.css`
@@ -704,46 +288,6 @@ CLI は **Tailwind エントリ CSS（`@import "tailwindcss"` を含む CSS フ
 
 CSS 仕様上 `@import` は他の at-rule より前に書く必要があるため、順序も適切に整えます。`@import "tailwindcss"` が欠けている場合は先頭に自動追記されます。
 
-## 開発
-
-### セットアップ
-
-```bash
-# submodule（templates/sparkle-variables）を取得
-# ※ 未初期化だと generate とそれに依存するテストが失敗する
-git submodule update --init --recursive
-
-# 依存関係をインストール
-npm install
-
-# パッケージをローカルでリンク
-npm link
-```
-
-### 開発用コマンド
-
-```bash
-npm test                        # Node.js test runner
-npm run test:watch              # テストの watch 実行
-npm run lint                    # ESLint
-npm run lint:fix                # ESLint 自動修正
-npm run format                  # Prettier
-npm run format:check            # Prettier チェックのみ
-npm run sync:anti-pattern-docs  # check ルール一覧を README と隣接リポジトリの JSDoc に同期
-```
-
-> **`sync:anti-pattern-docs` の注意:** このスクリプトは README だけでなく、ワークスペース内の隣接リポジトリ（`../sparkle-design` / `../sparkle-design-internal`）のファイルも書き換える横断スクリプトです。両リポジトリが隣にある Sparkle ワークスペース内で実行してください。
-
-### リリース手順（メンテナ向け）
-
-publish は GitHub Actions の **Publish to npm** workflow 経由。ローカル `npm publish` は禁止。
-
-1. `package.json` の `version` を更新（安定版: `X.Y.Z` / RC: `X.Y.Z-rc.N` / Beta: `X.Y.Z-beta.N`）
-2. `CHANGELOG.md` に該当セクションを追加
-3. PR をマージ後、**Publish to npm** workflow を `channel: auto` で実行
-
-`channel: auto` は `package.json` の version 形式から dist-tag を自動判定します（`-beta.N` → `beta` / `-rc.N` → `next` / それ以外 → `latest`）。既存 RC / Beta を latest に昇格させる場合は、新しい `X.Y.Z` として改めて publish します（`npm dist-tag add` での手動付け替えも可能ですが、version 管理が明確になる前者を推奨）。
-
 ## ライセンス
 
 MIT License - 詳細は [LICENSE](LICENSE) ファイルを参照してください。