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

package/package.json

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

package/templates/sparkle-variables/.github/workflows/validate.yml

@@ -0,0 +1,21 @@
+name: Validate tokens
+
+# トークン定義の不整合（同じ情報が 2 箇所にある / リネームの片側だけ適用 /
+# 未定義変数への参照）を、変更のたびに機械で止める。
+# en: Catch token-definition inconsistencies on every change.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - name: Validate token definitions
+        run: node scripts/validate-tokens.mjs

package/templates/sparkle-variables/README.md

@@ -0,0 +1,151 @@
+# sparkle-variables
+
+Sparkle Design のトークン定義。`sparkle-design-cli` と `sparkle-design-theme-settings` の
+**両方から submodule として直接参照される**共有データです。
+
+このリポジトリにビルドはありません。ファイルがそのまま消費されます。
+
+## どの情報の正解がどこにあるか
+
+同じ情報が 2 箇所にあると、必ず片方が古くなります。情報の種類ごとに**正解のファイルを 1 つ**に決めています。
+
+| 情報 | 正解のファイル | 備考 |
+|---|---|---|
+| プリミティブカラー（red / orange / yellow / green / blue / purple / pink、black / white、alpha、`ring`） | `colors.json` | **`gray` はここに置かない**。`ring.normal` は旧 `--color-ring-normal` 用の beta 互換値で、移行先は セマンティックの `border/ring` |
+| グレースケール | `gray.json` | primary ごとに 10 段（0–9）。CLI が `--color-gray-50`〜`900` に展開する |
+| 角丸のプロファイル | `radius.csv` | 行 = プロファイル、列 = セマンティック名 |
+| フォント一覧 | `fontdata.csv` | 消費側は Figma プラグイン `sparkle-design-theme-settings` のみ（CLI は読まない）。**現状 `validate-tokens.mjs` の検査対象外** |
+| セマンティックトークン（色 / 角丸 / シャドウ / タイポグラフィ）と CSS 構造 | `sparkle-design.template.css` | |
+| 最大幅（`--container-*`） | `sparkle-design.template.css` | Figma の `Sizing: Primitives` と 1:1。**余白（`Spacing: Primitives`）はここに置かない** — 理由は下記 |
+| 上記すべての一次情報 | **Figma `Sparkle Design`** | 齟齬があれば Figma が正 |
+
+### なぜ `gray` を `colors.json` に置かないか
+
+`gray` は primary の選択に応じて色味が変わるため `gray.json` が正です。
+両方に置くと CLI の `generateColorTokens` が `--color-gray-*` を二重に出力し、
+後から出る `gray.json` 側が `colors.json` 側を**サイレントに上書き**します。
+見た目は壊れないため目視では気付けません。
+
+この事故は `scripts/validate-tokens.mjs` が検出します。
+
+## 変更するときの注意
+
+### Figma が正
+
+Figma と定義が食い違ったときは Figma を正とします。
+**確信が持てない差分は、どちらかに寄せずに `⚠️ 要確認` とコメントで残す**。
+曖昧さを消したふりをするより、曖昧だと明記したほうが誤読が減ります。
+
+### `radius.csv` の列名を変えるときはテンプレートも同時に
+
+CLI の `processTemplate` は `--radius-<列名>:` への正規表現置換で
+テンプレートのデフォルト値を上書きします。CSV だけリネームすると置換が効かず、
+旧名の変数が残ったまま新名の変数が生成されません。
+
+`scripts/validate-tokens.mjs` がこの片側リネームを検出します。
+
+### セマンティック変数は 2 箇所に書く
+
+テンプレートは同じセマンティック変数を「プレーンな `:root`」と「`@theme inline`」の
+2 箇所に持ちます（`sparkle-design-cli` issue #229 の設計）。
+`@theme inline` 側は**同名変数の自己参照**にします。プリミティブを直接参照すると、
+Tailwind が utility に値をインライン化してしまい、セマンティック変数を
+ランタイムで上書きしても見た目が変わらなくなります。
+
+片方だけに追加する漏れは `scripts/validate-tokens.mjs` が検出します。
+
+### Spacing はトークンにしない、Sizing はトークンにする
+
+Figma には `Spacing: Primitives`（`padding/0`〜`padding/120` の 17 段）と
+`Sizing: Primitives`（`max-width/xs`〜`max-width/7xl` の 11 段）がありますが、
+**CSS 変数として出すのは Sizing だけ**です。理由が正反対だからです。
+
+- **Spacing を出してはいけない。** Tailwind v4 の `p-N` / `m-N` / `gap-N` は
+  `calc(var(--spacing) * N)` にコンパイルされます。ここに `--spacing-16: 1rem` の
+  ような**名前付きキー**を定義すると、その N だけ名前付きの値が優先されます。
+  `p-16` は本来 64px ですが、Figma の `padding/16`（16px）をそのまま変数にすると
+  **4 分の 1 になります**。ビルドは通り、警告も出ず、既存 consumer の余白だけが
+  静かに崩れます。Figma のステップは代わりに `sparkle-design-cli` の `check`
+  ルール（`use-figma-spacing-scale`, severity `info`）で「使ってよい値」として
+  検査する方針です。**このルールはまだリリース済みの CLI には入っていません**
+  （[sparkle-design-cli#76](https://github.com/goodpatch/sparkle-design-cli/pull/76)
+  でリリース予定）。
+- **Sizing は出してよい。** Tailwind の `--container-*` 名前空間は元から
+  名前付きキーだけで構成されていて、動的な計算式を持たないため衝突しません。
+  現在の 11 値は Tailwind のデフォルトと同値なので出力しても実効の変化は
+  ありませんが、Figma が SSOT である以上ここが値の所在地になります。
+  Tailwind の `--container-3xs` / `--container-2xs` は Figma に対応がないため
+  **定義しない**（＝Tailwind のデフォルトのまま残す）方針です。
+
+#### `--container-*` だけ `@theme static` に書く理由
+
+他のトークンは「プレーンな `:root` ＋ `@theme inline` の自己参照」ですが、
+`--container-*` は **`@theme static` に実値**を書きます。Tailwind v4 でこの
+名前空間だけが 2 通りに展開されるためです。
+
+| 使われ方 | 展開結果 |
+|---|---|
+| `max-w-*` / `w-*` / `min-w-*` | `var(--container-*)` |
+| `@sm:` / `@xl:` などの container query バリアント | `@container (width >= 36rem)`（**実値がベタ書き**） |
+
+後者は CSS の仕様上 `var()` を書けません。実際にコンパイルして確認した結果は
+次のとおりです。
+
+| 書き方 | `max-w-*` | container query バリアント |
+|---|---|---|
+| プレーンな `:root` | 追従する | **Tailwind のデフォルトのまま据え置かれる** |
+| `@theme inline` の自己参照 | 追従する | **バリアント自体が生成されない** |
+| `@theme` に実値 | 追従する | 追従する |
+
+そのため、他のトークンに合わせて `:root` ＋ `@theme inline` に「揃える」
+リファクタをしてはいけません。`scripts/validate-tokens.mjs` が、
+`--container-*` がそれらのブロックに現れたら失敗するようにしています。
+
+さらに `static` を付けています。素の `@theme` は **使われていない変数を出力から
+落とす**（tree-shaking）ため、`max-w-6xl` を書いていないプロジェクトでは
+手書き CSS の `var(--container-6xl)` が解決しなくなります。他のトークンは
+プレーンな `:root` にあるので常に参照でき、`--container-*` だけがそうならない
+のは分かりにくいので、`@theme static` で 11 件すべてを必ず出力します。
+
+`scripts/validate-tokens.mjs` が「`--spacing-*` を定義していないこと」と
+「`--container-*` が Figma の 11 件と過不足なく一致し、値が昇順であること」を
+検出します。
+
+### consumer 側のリリース順序
+
+このリポジトリは submodule のコミット pin で参照されるため、変更しても消費側は即座には壊れません。
+ただし **bump する前に**両消費側の対応を揃える必要があります。
+
+```text
+sparkle-variables → sparkle-design-cli → sparkle-design → sparkle-design-internal
+                  ↘ sparkle-design-theme-settings（cli と同時期）
+```
+
+## 検証
+
+```sh
+node scripts/validate-tokens.mjs
+```
+
+以下を機械的にチェックします（CI で PR ごとに実行）。
+
+- 入力ファイル（JSON / CSV / テンプレート）が読めること
+- `gray` の source of truth が `gray.json` 一本であること
+- `colors.json` と `gray.json` の色相が **双方向で** 揃っていること（片方にしか無い色は「選べそうに見えて選べない」状態になる）と、`gray.json` の各色相が 0–9 の 10 段を持つこと
+- `radius.csv` の行・列構造（列数の揃い・空セル）が壊れていないこと
+- `radius.csv` の列名とテンプレートの `--radius-*` 変数が **双方向で** 一致すること。後方互換エイリアスと同名の列が CSV に残っていないこと、および **CSV の各セル値が実在するプリミティブを指すこと**（これが無いと CLI が dangling な `var(--radius-*)` を生成しても素通りする）
+- 角丸のプリセット値がセマンティックキー名と文字列衝突しないこと（CLI の置換が依存する不変条件）
+- **全 primary 候補**でテンプレートに dangling な `var(--*)` 参照が無いこと（`var(--x, fallback)` 形式を含む）
+- テンプレートが `--spacing` / `--spacing-*` を定義していないこと（Tailwind v4 の動的スペーシングを名前付きキーが上書きし、consumer の余白がサイレントに変わるため）
+- `--container-*` が Figma の `Sizing: Primitives` 11 件と **過不足なく** 一致し、値が昇順で、**リテラルの rem** であること（名前は正しいのに値だけ入れ替わっている取り違えと、`var()` を書いて container query バリアントを失う事故を拾う）。`:root` や `@theme inline` 側に書かれていないこと、同名を 2 回書いて後勝ちで上書きしていないことも見る
+- `rem` の値と行末コメントの `px` が一致していること（同じ値を 2 度書いている行が現在 42 行あり、そのすべてが対象。Figma の値は px で来るため、片方だけ直す事故が起きる）
+- セマンティック層（color / radius / shadow）が `:root` と `@theme inline` で揃っていること
+- 同一ブロック内に重複した変数宣言が無いこと（後勝ちでサイレント上書きされるため）
+- `character-*` / `icon-*` クラスが **自分の変数だけを** 参照していること（クラス間の取り違えを検出する）。貼り替え漏れ（未参照の変数 / 未定義の参照）も含む
+- テンプレートの波括弧の釣り合いと、プレースホルダーが CLI の期待どおりの字面であること（大文字小文字のタイポと、`/* {{COLOR_TOKENS}} */` の体裁崩れによる置換 no-op を検出する）
+
+### 検査設計の前提
+
+**「0 件マッチ = 成功」を作らない。** 集合比較だけの検査は、命名変更などで対象を 1 件も拾えなくなったときに黙って合格します。各検査は「最低これだけの件数を実際に見た」ことを表明してから判定するので、検査が空振りしていること自体が失敗になります。
+
+**検査できないこと。** これは構造の検査であって、値の妥当性は見ていません。たとえば `--color-text-high` の参照先を別のグレーに書き換えてもコントラストが壊れるだけで検査は通ります。色の値そのものの正解は Figma です。`fontdata.csv` も現状は検査対象外です。

package/templates/sparkle-variables/colors.json

@@ -1,115 +1,115 @@
 {
   "blue": {
-    "50": "#e5f6ff",
-    "100": "#ceedff",
-    "200": "#97d3ff",
-    "300": "#61b3ff",
-    "400": "#218bff",
-    "500": "#0969da",
-    "600": "#0550ae",
-    "700": "#033d8b",
-    "800": "#0a3069",
-    "900": "#002155"
+    "50": "#f1f8fe",
+    "100": "#d3e9fd",
+    "200": "#a7d1fc",
+    "300": "#7fbafa",
+    "400": "#4ea0f8",
+    "500": "#1d83f7",
+    "600": "#096ae7",
+    "700": "#0e5cbe",
+    "800": "#06489e",
+    "900": "#043676"
   },
   "red": {
-    "50": "#fff6f5",
-    "100": "#ffe5e4",
-    "200": "#ffbbb9",
-    "300": "#ff8182",
-    "400": "#fa4549",
-    "500": "#cf222e",
-    "600": "#a40e26",
-    "700": "#82071e",
-    "800": "#660018",
-    "900": "#4c0014"
+    "50": "#fff0f0",
+    "100": "#ffe1e0",
+    "200": "#ffbab8",
+    "300": "#f78b88",
+    "400": "#f06b66",
+    "500": "#e4534e",
+    "600": "#cd3832",
+    "700": "#b3231e",
+    "800": "#891d1a",
+    "900": "#631513"
   },
   "orange": {
-    "50": "#fff1e5",
-    "100": "#ffd8b5",
-    "200": "#ffb77c",
-    "300": "#fb8f44",
-    "400": "#e16f24",
-    "500": "#bc4c00",
-    "600": "#953800",
-    "700": "#762c00",
-    "800": "#5c2200",
-    "900": "#471700"
+    "50": "#fef6f1",
+    "100": "#fbe4d5",
+    "200": "#f9cdae",
+    "300": "#f3ad7c",
+    "400": "#f0985c",
+    "500": "#e3823c",
+    "600": "#d36922",
+    "700": "#ba5612",
+    "800": "#7c3708",
+    "900": "#4d2205"
   },
   "yellow": {
-    "50": "#fffbe2",
-    "100": "#fdedba",
-    "200": "#fad573",
-    "300": "#f0b800",
-    "400": "#cc8f00",
-    "500": "#9a6700",
-    "600": "#7d4e00",
-    "700": "#633c01",
-    "800": "#4d2d00",
-    "900": "#3b2300"
+    "50": "#fefcec",
+    "100": "#fdf7d3",
+    "200": "#faf0b8",
+    "300": "#f3e081",
+    "400": "#eed255",
+    "500": "#eac210",
+    "600": "#c09c09",
+    "700": "#8b720e",
+    "800": "#5e4d08",
+    "900": "#352a03"
   },
   "purple": {
-    "50": "#fbefff",
-    "100": "#ecd8ff",
-    "200": "#d8b9ff",
-    "300": "#c297ff",
-    "400": "#a475f9",
-    "500": "#8250df",
-    "600": "#6639ba",
-    "700": "#512a97",
-    "800": "#3e1f79",
-    "900": "#2e1461"
+    "50": "#f5f1fe",
+    "100": "#ece2fe",
+    "200": "#d8c5fc",
+    "300": "#c1a3fa",
+    "400": "#ab84f6",
+    "500": "#9367e4",
+    "600": "#7a4bd2",
+    "700": "#643bb0",
+    "800": "#523191",
+    "900": "#392163"
   },
   "green": {
-    "50": "#edfdf0",
-    "100": "#c5f7d0",
-    "200": "#6fdd8b",
-    "300": "#4ac26b",
-    "400": "#2da44e",
-    "500": "#1a7f37",
-    "600": "#116329",
-    "700": "#044f1e",
-    "800": "#003d16",
-    "900": "#002d11"
+    "50": "#ecf9f2",
+    "100": "#d3f3e1",
+    "200": "#afe9ca",
+    "300": "#81dfab",
+    "400": "#53d08b",
+    "500": "#26bb6e",
+    "600": "#21a15f",
+    "700": "#19804b",
+    "800": "#146139",
+    "900": "#0d4025"
   },
   "pink": {
-    "50": "#ffeff7",
-    "100": "#ffd3eb",
-    "200": "#ffadda",
-    "300": "#ff80c8",
-    "400": "#e85aad",
-    "500": "#bf3989",
-    "600": "#99286e",
-    "700": "#772057",
-    "800": "#611347",
-    "900": "#4d0336"
+    "50": "#fdf2f9",
+    "100": "#fae0ef",
+    "200": "#f5c1e1",
+    "300": "#ef9fcf",
+    "400": "#e873b9",
+    "500": "#e043a1",
+    "600": "#ce2289",
+    "700": "#992e6e",
+    "800": "#7e255a",
+    "900": "#571a3e"
   },
   "black": "#000000",
   "white": "#ffffff",
   "black-alpha": {
-    "50": "#0000000D",
-    "100": "#0000001A",
+    "50": "#0000000d",
+    "100": "#0000001a",
     "200": "#00000033",
-    "300": "#0000004D",
+    "300": "#0000004d",
     "400": "#00000066",
     "500": "#00000080",
     "600": "#00000099",
-    "700": "#000000B3",
-    "800": "#000000CC",
-    "900": "#000000E6"
+    "700": "#000000b2",
+    "800": "#000000cc",
+    "900": "#000000e5"
   },
   "white-alpha": {
-    "50": "#FFFFFF0D",
-    "100": "#FFFFFF1A",
-    "200": "#FFFFFF33",
-    "300": "#FFFFFF4D",
-    "400": "#FFFFFF66",
-    "500": "#FFFFFF80",
-    "600": "#FFFFFF99",
-    "700": "#FFFFFFB3",
-    "800": "#FFFFFFCC",
-    "900": "#FFFFFFE6"
+    "50": "#ffffff0d",
+    "100": "#ffffff1a",
+    "200": "#ffffff33",
+    "300": "#ffffff4d",
+    "400": "#ffffff66",
+    "500": "#ffffff80",
+    "600": "#ffffff99",
+    "700": "#ffffffb2",
+    "800": "#ffffffcc",
+    "900": "#ffffffe5"
   },
   "ring": {
-    "normal": "#096cdc"
+    "normal": "#0e5cbe"
   }
 }

package/templates/sparkle-variables/gray.json

@@ -1,86 +1,86 @@
 {
     "blue": {
-        "0": "#f6f8fa",
-        "1": "#eaeef2",
-        "2": "#d0d7de",
-        "3": "#afb8c1",
-        "4": "#8c959f",
-        "5": "#6e7781",
-        "6": "#57606a",
-        "7": "#424a53",
-        "8": "#32383f",
-        "9": "#24292f"
+        "0": "#f3f5f6",
+        "1": "#e4e8ec",
+        "2": "#d6dbe1",
+        "3": "#b8c1cc",
+        "4": "#a1acba",
+        "5": "#8796a7",
+        "6": "#6b7885",
+        "7": "#4d5660",
+        "8": "#3b4249",
+        "9": "#292e33"
     },
     "green": {
-        "0": "#f6f7f6",
-        "1": "#e2e5e2",
-        "2": "#c5cac6",
-        "3": "#a0a8a2",
-        "4": "#7c857e",
-        "5": "#626a64",
-        "6": "#49504b",
-        "7": "#404542",
-        "8": "#2f3230",
-        "9": "#181b19"
+        "0": "#f4f5f4",
+        "1": "#e7e9e8",
+        "2": "#dadddb",
+        "3": "#bfc5c2",
+        "4": "#a9b2ad",
+        "5": "#929c97",
+        "6": "#727e78",
+        "7": "#525b56",
+        "8": "#3f4542",
+        "9": "#2c302e"
     },
     "yellow": {
-        "0": "#f6f5f5",
-        "1": "#e8e6e5",
-        "2": "#d3d1ce",
-        "3": "#b4b1ac",
-        "4": "#8e8a82",
-        "5": "#736f67",
-        "6": "#625f58",
-        "7": "#504e49",
-        "8": "#3f3e3a",
-        "9": "#282724"
+        "0": "#f5f5f4",
+        "1": "#e9e9e7",
+        "2": "#dddcda",
+        "3": "#c4c4c0",
+        "4": "#b1b0aa",
+        "5": "#9b9a93",
+        "6": "#7d7b73",
+        "7": "#5a5953",
+        "8": "#45443f",
+        "9": "#302f2c"
     },
     "orange": {
-        "0": "#efefef",
-        "1": "#cfcdcc",
-        "2": "#b7b4b3",
-        "3": "#969290",
-        "4": "#827d7b",
-        "5": "#635d5a",
-        "6": "#5a5552",
-        "7": "#464240",
-        "8": "#363332",
-        "9": "#2a2726"
+        "0": "#f5f4f4",
+        "1": "#e9e8e7",
+        "2": "#dedbd9",
+        "3": "#c6c1be",
+        "4": "#b2ada9",
+        "5": "#9d9691",
+        "6": "#7f7771",
+        "7": "#5c5651",
+        "8": "#46413e",
+        "9": "#312e2b"
     },
     "red": {
-        "0": "#f4f2f3",
-        "1": "#e2dfdf",
-        "2": "#c7c1c1",
-        "3": "#a79d9d",
-        "4": "#8e8182",
-        "5": "#7e7273",
-        "6": "#6c6263",
-        "7": "#585052",
-        "8": "#443f41",
-        "9": "#262223"
+        "0": "#f5f4f4",
+        "1": "#e9e7e7",
+        "2": "#dedad9",
+        "3": "#c6bfbe",
+        "4": "#b2a9a9",
+        "5": "#9d9191",
+        "6": "#7f7171",
+        "7": "#5c5251",
+        "8": "#463e3e",
+        "9": "#312b2b"
     },
     "purple": {
-        "0": "#f2f1f2",
-        "1": "#d5d4d8",
-        "2": "#c1bfc5",
-        "3": "#a5a2ab",
-        "4": "#94909a",
-        "5": "#797481",
-        "6": "#6e6a75",
-        "7": "#56525c",
-        "8": "#434047",
-        "9": "#333136"
+        "0": "#f4f4f5",
+        "1": "#e8e7e9",
+        "2": "#dbdadd",
+        "3": "#c1bfc5",
+        "4": "#aca9b2",
+        "5": "#95929c",
+        "6": "#76727e",
+        "7": "#55525b",
+        "8": "#413f45",
+        "9": "#2d2c30"
     },
     "pink": {
-        "0": "#f1f0f1",
-        "1": "#d5d1d4",
-        "2": "#c0bbbf",
-        "3": "#a49da1",
-        "4": "#92898f",
-        "5": "#776c73",
-        "6": "#6c6269",
-        "7": "#544d52",
-        "8": "#413b3f",
-        "9": "#322d30"
+        "0": "#f5f4f5",
+        "1": "#e9e7e8",
+        "2": "#dddadc",
+        "3": "#c5bfc3",
+        "4": "#b2a9ae",
+        "5": "#9c9298",
+        "6": "#7e7279",
+        "7": "#5b5257",
+        "8": "#453f43",
+        "9": "#302c2e"
     }
 }

package/templates/sparkle-variables/radius.csv

@@ -1,4 +1,4 @@
-name,divide,minimum,notice,action,halfModal,modal,round
+name,divide,minimum,notice,action,container,modal,round
 none,none,none,none,none,none,none,full
 xs,none,none,none,xs,sm,md,full
 sm,none,none,xs,sm,md,lg,full