ksk-design-system 1.59.0 → 1.60.0

package/AGENTS.md

@@ -17,7 +17,7 @@
   末尾が `codex-pr-review-guidelines` のマーカー）で囲み同期対象から除外する
 - 片方だけ編集したら **`node scripts/check-agents-docs-sync.mjs`**（`npm run check` に
   組み込み済み）を実行し、乖離が無いことを確認する
-- `templates/CLAUDE.md` / `templates/AGENTS.md`（postinstall で配布するテンプレート）も
+- `templates/CLAUDE.md` / `templates/AGENTS.md`（`npx ksk-ds init` で配布するテンプレート）も
   同じ仕組みで同期検査の対象
 
 ## 実装前セルフチェック（AI必読・最優先）

package/CLAUDE.md

@@ -17,7 +17,7 @@
   末尾が `codex-pr-review-guidelines` のマーカー）で囲み同期対象から除外する
 - 片方だけ編集したら **`node scripts/check-agents-docs-sync.mjs`**（`npm run check` に
   組み込み済み）を実行し、乖離が無いことを確認する
-- `templates/CLAUDE.md` / `templates/AGENTS.md`（postinstall で配布するテンプレート）も
+- `templates/CLAUDE.md` / `templates/AGENTS.md`（`npx ksk-ds init` で配布するテンプレート）も
   同じ仕組みで同期検査の対象
 
 ## 実装前セルフチェック（AI必読・最優先）

package/DESIGN.md

@@ -311,6 +311,15 @@ Portal に載る要素（Dialog / Sheet / Popover / Toast 等）は DOM 上の
   `AdminShell` の `<main>` だけが `--Product-Page-Padding-Y` を持つ。
 - 色は従来どおり semantic トークン（`--Surface-*` / `--Text-*` / `--Brand-*`）と Brand ランプの
   上書きで調整する。カードの面は `--card-surface`、角丸は `--Radius-Surface` が既存の公開シーム。
+- **primitive を直接上書きしてよいのは Brand（`--Primitive-Brand-*`）と Neutral
+  （`--Primitive-Gray-50〜900` / `--Primitive-White` / `--Primitive-Black`）の2つのアイデンティティ
+  パレットだけ**（issue #377）。warm gray のように DS 既定の cool gray と世界観が違うプロダクトは
+  Neutral ランプごと差し替える。status 系（Red / Green / Blue / Yellow / Orange）の色調整は
+  semantic 層（`--Surface-Caution` / `--Text-Success` / `--Caution-Base` 等）で行う — 上書き1箇所で
+  済み、DS が primitive の割り当てを変えても壊れない。
+  **Neutral を差し替えたらコントラストは消費側の責任**。Gray は `--Text-High-Emphasis`（本文色）や
+  `--Surface-Secondary` を駆動するので、本文×背景が WCAG AA（4.5:1）を満たすか light / dark 両方で
+  実測すること。DS の `scripts/check-contrast.mjs` は DS 既定パレットしか見ていない。
 - **`--Product-Type-Scale`**（issue #371/#372 の stract-ui からの逆輸入）は `typo-*` の font-size に
   `calc(<px> * var(--Product-Type-Scale, 1))` として一律で掛かる乗数。line-height は unitless、
   letter-spacing は em のため font-size の変化に自動で連動し、別途スケールしない。

package/MIGRATION.md

@@ -53,6 +53,27 @@ npx ksk-ds check-migration ./src
 
 ## v1 系内の minor 変更（参考）
 
+### 次のリリース — `postinstall` による AI ルールファイル自動設置を廃止（要確認）
+
+これまで `npm install ksk-design-system` の `postinstall` フックが、消費側の
+プロジェクトルートに `CLAUDE.md` / `AGENTS.md`（`node_modules` 内の DS ルールを指す
+薄いポインタ）を自動設置していた。**この自動設置を廃止し、明示コマンドに一本化した。**
+
+```bash
+npx ksk-ds init          # 設置（既存ファイルはスキップ）
+npx ksk-ds init --force  # 既存ファイルを最新テンプレートで上書き
+```
+
+**既に設置済みの消費リポは対応不要。** 元々 `postinstall` は既存ファイルを上書きしない
+仕様だったため、設置済みのプロジェクトでは実質 no-op だった。影響を受けるのは
+**新規に DS を導入するプロジェクトの初回だけ**で、`npm install` の後に上記を 1 回実行する。
+
+廃止の理由は、install 時にプロジェクトルートへ AI エージェント向け指示ファイルを書き込む
+挙動が、サプライチェーン検査で「同意なき AI エージェント制御面の設置」として Critical 判定
+されるため。LPM Firewall が 1.49.2 / 1.51.1 をこの理由でブロック判定しており、
+`postinstall` を持つ限りバージョンを上げても判定が引き継がれる。あわせて
+`INIT_CWD` 参照も削除し、書き込み先はコマンドを実行したディレクトリに固定した。
+
 ### 次のリリース — PillToggle の onChange/onValueChange 統一（破壊変更なし）
 
 `PillToggle` のみ他コンポーネント（Switch 等の native 系を除く）と異なり `onValueChange`

package/README.md

@@ -48,6 +48,21 @@ Tailwind 4.1 で導入された `@source inline()` を使うため）
 npm install ksk-design-system
 ```
 
+AI コーディング（Claude Code / Codex）を使うプロジェクトでは、続けて 1 回だけ実行します。
+
+```bash
+npx ksk-ds init
+```
+
+プロジェクトルートに `CLAUDE.md` / `AGENTS.md`（`node_modules` 内の DS ルールを指す薄いポインタ）を
+設置します。AI エージェントは `node_modules` 配下を自動では読まないため、このファイルが無いと
+DS のルールが適用されません。既存ファイルはスキップされ、更新は `--force` で上書きします。
+
+> **v1.60.0 で `postinstall` による自動設置を廃止しました。** install 時にプロジェクトルートへ
+> AI 指示ファイルを書き込む挙動は、サプライチェーン検査で「同意なき AI エージェント制御面の設置」
+> として Critical 判定されるためです（LPM Firewall が 1.49.2 / 1.51.1 をこの理由でブロック判定）。
+> v1.59.0 以前から更新する場合、既に設置済みのファイルはそのまま使えます。
+
 ```css
 /* globals.css / app.css（CSS の場所に応じて ../../ の数を調整） */
 @import "tailwindcss";

package/bin/init.js

@@ -6,6 +6,12 @@
 // プロジェクトルートに AGENTS.md / CLAUDE.md（node_modules 内の DS ルールを
 // 参照する薄いポインタ）を置く必要がある。
 //
+// 設置は **明示実行のみ**（`npx ksk-ds init`）。install 時に自動で置く
+// postinstall フックは v1.60.0 で廃止した。install-time にプロジェクトルートへ
+// AI 指示ファイルを書き込む挙動は、サプライチェーン検査で
+// 「同意なき AI エージェント制御面の設置」として Critical 判定されるため
+// （LPM Firewall が 1.49.2 / 1.51.1 をこの理由でブロック判定）。
+//
 // Usage:
 //   npx ksk-design-system init          # AGENTS.md + CLAUDE.md を設置
 //   npx ksk-design-system init --force  # 既存ファイルを上書き
@@ -13,7 +19,6 @@
 //   npx ksk-ds lint src                 # contracts/rules.json に基づき consumer UI を検査
 //   npx ksk-ds check-duplicates src     # DS と同名のローカル実装を検査
 //   npx ksk-ds codemod <name> ./src     # scripts/codemod/<name>.mjs を実行
-//   npx ksk-design-system postinstall   # npm postinstall から呼ばれる silent モード
 
 import { copyFileSync, existsSync, readdirSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
@@ -82,7 +87,7 @@ if (cmd === "demo") {
   process.exit(0)
 }
 
-if (cmd !== "init" && cmd !== "postinstall") {
+if (cmd !== "init") {
   console.error(`未知のコマンド: ${cmd}`)
   console.error(`npx ksk-design-system help を参照してください`)
   process.exit(1)
@@ -209,32 +214,18 @@ function runDemo(rest) {
   console.log(``)
 }
 
-// ─── postinstall モードのガード ─────────────────────────────
-// INIT_CWD は npm install が実行されたディレクトリ（consumer のルート）。
-// 未設定、または pkgRoot と同じ場合は DS 自身のインストールコンテキストなのでスキップ。
-const isPostinstall = cmd === "postinstall"
-const consumerRoot = process.env.INIT_CWD || process.cwd()
-
-if (isPostinstall) {
-  // DS 自身を開発している場合（INIT_CWD が pkgRoot）はスキップ
-  if (!process.env.INIT_CWD || resolve(consumerRoot) === pkgRoot) {
-    process.exit(0)
-  }
-  // consumer のルートに package.json が無ければスキップ（安全のため）
-  if (!existsSync(join(consumerRoot, "package.json"))) {
-    process.exit(0)
-  }
-}
+// ─── init（明示実行のみ）─────────────────────────────────────
+// 書き込み先はコマンドを叩いたディレクトリ。install 時の暗黙実行が無くなったので
+// INIT_CWD 等の環境変数は参照しない。
+const consumerRoot = process.cwd()
 
 const files = [
   { src: "templates/AGENTS.md", dest: "AGENTS.md", label: "Codex 用" },
   { src: "templates/CLAUDE.md", dest: "CLAUDE.md", label: "Claude Code 用" },
 ]
 
-if (!isPostinstall) {
-  console.log("ksk-design-system init")
-  console.log("AI (Claude / Codex) 向けルールファイルを設置します。\n")
-}
+console.log("ksk-design-system init")
+console.log("AI (Claude / Codex) 向けルールファイルを設置します。\n")
 
 let created = 0
 let skipped = 0
@@ -244,33 +235,21 @@ for (const { src, dest, label } of files) {
   const destPath = join(consumerRoot, dest)
 
   if (!existsSync(srcPath)) {
-    if (!isPostinstall) {
-      console.error(`  ✗ テンプレートが見つかりません: ${srcPath}`)
-    }
-    process.exit(isPostinstall ? 0 : 1)
+    console.error(`  ✗ テンプレートが見つかりません: ${srcPath}`)
+    process.exit(1)
   }
 
   if (existsSync(destPath) && !force) {
-    if (!isPostinstall) {
-      console.log(`  ⏭  ${dest} は既に存在するためスキップ（--force で上書き）`)
-    }
+    console.log(`  ⏭  ${dest} は既に存在するためスキップ（--force で上書き）`)
     skipped++
     continue
   }
 
   copyFileSync(srcPath, destPath)
-  if (isPostinstall) {
-    console.log(`[ksk-design-system] ${dest} をプロジェクトルートに設置しました`)
-  } else {
-    console.log(`  ✓ ${dest} を設置しました（${label}）`)
-  }
+  console.log(`  ✓ ${dest} を設置しました（${label}）`)
   created++
 }
 
-if (isPostinstall) {
-  process.exit(0)
-}
-
 console.log(`\n完了: ${created} 作成 / ${skipped} スキップ`)
 
 if (created > 0) {

package/bin/lint.js

@@ -10,16 +10,36 @@ const DEFAULT_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx"])
  * engine: "product-theme-override" を持つルールだけをここに流す（issue #364）。
  */
 const CSS_EXTENSIONS = new Set([".css"])
+// ビルド生成物。ここを走査すると、バンドルされた DS 自身の CSS を
+// 「consumer が DS 変数を上書きしている」と誤認して P049 が大量に出る（#378）。
+// Next.js の `output: "export"` は out/、Nuxt は .output/、Vercel/Turbo は
+// それぞれ .vercel/ .turbo/ を既定の出力先にする。
 const DEFAULT_IGNORES = [
   ".git",
   ".next",
+  ".nuxt",
+  ".output",
+  ".svelte-kit",
+  ".turbo",
+  ".vercel",
   "build",
   "coverage",
   "dist",
+  ".claude",
   "node_modules",
+  "out",
   "storybook-static",
 ]
 
+// パス単位で除外するもの（セグメント名だけでは絞れないケース）。
+// Capacitor は web のビルド成果物をネイティブプロジェクト配下へコピーするので、
+// そこも DS 自身の CSS を含む（#378）。`public` をセグメントで除外すると
+// Next.js の public/ まで巻き込むため、パス形で限定する。
+const DEFAULT_IGNORE_PATHS = [
+  "ios/App/App/public",
+  "android/app/src/main/assets/public",
+]
+
 export async function runLintCli(argv, { cwd = process.cwd(), pkgRoot = resolve(".") } = {}) {
   const options = parseArgs(argv)
   const rulesPath = resolve(pkgRoot, "contracts/rules.json")
@@ -182,7 +202,9 @@ function readProductThemeContract(pkgRoot) {
   const path = resolve(pkgRoot, "contracts/product-theme-overrides.json")
   if (!existsSync(path)) return null
   try {
-    return loadProductThemeContract(JSON.parse(readFileSync(path, "utf8")))
+    // pkgRoot を渡すと「DS に実在する変数」だけを違反にする（issue #377）。
+    // DS の CSS が読めない環境では接頭辞一致だけの従来判定へフォールバックする。
+    return loadProductThemeContract(JSON.parse(readFileSync(path, "utf8")), { pkgRoot })
   } catch {
     return null
   }
@@ -323,6 +345,7 @@ function shouldIgnorePath(relPath, options) {
   if (!relPath || relPath === ".") return false
   const parts = relPath.split("/")
   if (parts.some((part) => DEFAULT_IGNORES.includes(part))) return true
+  if (DEFAULT_IGNORE_PATHS.some((ignored) => relPath.includes(ignored))) return true
   return options.excludes.some((exclude) => relPath.includes(exclude))
 }
 

package/bin/product-theme-override.js

@@ -1,5 +1,5 @@
 /**
- * P049 — product theme の許可リスト外の DS 変数上書きを検出する（issue #364）
+ * P049 — product theme の許可リスト外の DS 変数上書きを検出する（issue #364 / #377）
  *
  * 消費プロダクトの CSS が `:root { --Surface-Primary: … }` のように DS の
  * CSS 変数を上書きするのは、契約 `contracts/product-theme-overrides.json` の
@@ -10,31 +10,90 @@
  * 判定:
  *   1. CSS のコメントを落とす
  *   2. カスタムプロパティ宣言（`--Foo: value;`）を行番号付きで拾う
- *   3. `dsVariableNamespaces` のどれかで始まり、`allowedVariables` に無いものを違反とする
+ *   3. `dsVariableNamespaces` のどれかで始まり、`allowedVariables` に無く、
+ *      かつ **DS 自身の CSS に実在する** ものを違反とする
  *
- * `var(--Foo)` の**参照**は対象外（読むのは自由）。宣言だけを見る。
+ * 3 の「実在する」条件は issue #377。接頭辞一致だけだと、消費側が DS の命名に
+ * 寄せて作った独自変数（`--Surface-Inverse-Hover` のように DS には無い名前）まで
+ * 「DS の上書き」と誤検出する。DS に存在しない変数は上書きしようがない。
+ * DS の CSS を読めない環境（パッケージ構成が変わった等）では従来どおり
+ * 接頭辞一致だけで判定してフォールバックする。
  */
+import { existsSync, readFileSync, readdirSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+/** カスタムプロパティの**宣言**。`var(--Foo, …)` の参照はコロンの前が `(` なので一致しない。 */
+const DECLARATION = /(^|[;{}\s])(--[A-Za-z0-9_-]+)\s*:/g
+
+/**
+ * DS 自身の CSS 変数を宣言しているファイル群（npm package の `files` にも含まれる）。
+ * 生成ファイルを増やさずに実行時へ集めるので、DS 側の CSS を足してもドリフトしない。
+ */
+const DS_CSS_DIRS = ["src/styles", "src/themes"]
+const DS_CSS_FILES = ["src/preset.css"]
 
 /** CSS コメントを、行数を保ったまま空白に置き換える */
 function stripCssComments(source) {
   return source.replace(/\/\*[\s\S]*?\*\//g, (block) => block.replace(/[^\n]/g, " "))
 }
 
+/**
+ * DS が実際に宣言している CSS 変数名を集める。
+ * 読めない場合は null を返し、呼び出し側は接頭辞一致だけの判定へフォールバックする。
+ *
+ * @param {string} pkgRoot ksk-design-system パッケージのルート
+ * @returns {Set<string> | null}
+ */
+export function collectDsDeclaredVariables(pkgRoot) {
+  if (!pkgRoot) return null
+  const files = []
+  for (const dir of DS_CSS_DIRS) {
+    const abs = resolve(pkgRoot, dir)
+    if (!existsSync(abs)) continue
+    try {
+      for (const name of readdirSync(abs)) {
+        if (name.endsWith(".css")) files.push(join(abs, name))
+      }
+    } catch {
+      // 読めないディレクトリは黙って飛ばす（他のファイルで足りることがある）
+    }
+  }
+  for (const file of DS_CSS_FILES) {
+    const abs = resolve(pkgRoot, file)
+    if (existsSync(abs)) files.push(abs)
+  }
+  if (files.length === 0) return null
+
+  const names = new Set()
+  for (const file of files) {
+    let source
+    try {
+      source = readFileSync(file, "utf8")
+    } catch {
+      continue
+    }
+    for (const match of stripCssComments(source).matchAll(DECLARATION)) names.add(match[2])
+  }
+  return names.size > 0 ? names : null
+}
+
 /**
  * @param {string} source CSS ソース
- * @param {{ allowed: Set<string>, namespaces: string[] }} contract
+ * @param {{ allowed: Set<string>, namespaces: string[], declared?: Set<string> | null }} contract
  * @returns {Array<{ line: number, name: string }>}
  */
 export function inspectProductThemeOverrides(source, contract) {
   const stripped = stripCssComments(source)
   const findings = []
-  // 宣言のみを拾う。`var(--Foo, …)` の参照はコロンの前に `(` が来るため一致しない。
-  const DECLARATION = /(^|[;{}\s])(--[A-Za-z0-9_-]+)\s*:/g
+  const declared = contract.declared ?? null
 
   for (const match of stripped.matchAll(DECLARATION)) {
     const name = match[2]
     if (contract.allowed.has(name)) continue
     if (!contract.namespaces.some((prefix) => name.startsWith(prefix))) continue
+    // DS に実在しない名前は「DS の上書き」ではない（issue #377）。
+    // 一覧が取れなかったときは従来どおり接頭辞一致だけで判定する。
+    if (declared && !declared.has(name)) continue
     findings.push({
       line: stripped.slice(0, match.index).split(/\r?\n/).length,
       name,
@@ -43,10 +102,16 @@ export function inspectProductThemeOverrides(source, contract) {
   return findings
 }
 
-/** 契約 JSON から判定に使う形へ畳む */
-export function loadProductThemeContract(contract) {
+/**
+ * 契約 JSON から判定に使う形へ畳む。
+ *
+ * @param {object} contract contracts/product-theme-overrides.json の中身
+ * @param {{ pkgRoot?: string }} [options] pkgRoot を渡すと「DS に実在する変数」だけに絞る
+ */
+export function loadProductThemeContract(contract, { pkgRoot } = {}) {
   return {
     allowed: new Set(Object.values(contract.allowedVariables ?? {}).flat()),
     namespaces: Array.isArray(contract.dsVariableNamespaces) ? contract.dsVariableNamespaces : [],
+    declared: collectDsDeclaredVariables(pkgRoot),
   }
 }

package/contracts/components.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "1.59.0",
+    "version": "1.60.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 68,

package/contracts/product-theme-overrides.json

@@ -19,7 +19,8 @@
     "scope": ":root（アプリ全体）または任意の要素（その配下だけ）",
     "allowedPattern": "preset の後に、ここで許可された CSS 変数だけを上書きする",
     "forbiddenPattern": "消費プロダクト側に tokens.json / semantic.css / preset.css のコピーや独自 Tailwind preset を作らない。許可リストに無い内部変数を上書きしない",
-    "lintRule": "P049（npx ksk-ds lint が消費側 CSS を検査する）"
+    "lintRule": "P049（npx ksk-ds lint が消費側 CSS を検査する）",
+    "contrastResponsibility": "neutralPalette（--Primitive-Gray-* / White / Black）を差し替えたら、本文×背景のコントラストは消費プロダクト側の責任になる。Gray は --Text-High-Emphasis（本文色）・--Text-Medium-Emphasis・--Surface-Secondary・--Border-Low-Emphasis など semantic.css の 33 箇所を駆動しているため、差し替え後に本文テキスト×各 Surface が WCAG AA（4.5:1、大きい文字は 3:1）を満たすか必ず実測すること。DS 側の scripts/check-contrast.mjs は DS 既定パレット向けの検査で、消費側の差し替えは見ていない。light / dark の両方を確認する。"
   },
   "allowedVariables": {
     "brandColor": [
@@ -34,23 +35,66 @@
       "--Primitive-Brand-800",
       "--Primitive-Brand-900"
     ],
+    "neutralPalette": [
+      "--Primitive-Gray-50",
+      "--Primitive-Gray-100",
+      "--Primitive-Gray-200",
+      "--Primitive-Gray-300",
+      "--Primitive-Gray-400",
+      "--Primitive-Gray-500",
+      "--Primitive-Gray-600",
+      "--Primitive-Gray-700",
+      "--Primitive-Gray-800",
+      "--Primitive-Gray-900",
+      "--Primitive-White",
+      "--Primitive-Black"
+    ],
     "semanticColor": [
       "--Surface-Primary",
       "--Surface-Secondary",
       "--Surface-Tertiary",
       "--Surface-Accent-Primary-Light",
+      "--Surface-Inverse",
       "--Text-High-Emphasis",
       "--Text-Medium-Emphasis",
       "--Text-Low-Emphasis",
       "--Text-Accent-Primary",
       "--Text-on-Inverse",
+      "--Text-on-Inverse-Secondary",
+      "--Object-on-Inverse",
       "--Border-Low-Emphasis",
       "--Border-Medium-Emphasis",
       "--Border-Accent-Primary",
       "--Brand-Primary",
       "--Brand-Action",
       "--Focus-High-Emphasis",
-      "--card-surface"
+      "--card-surface",
+      "--Surface-Caution",
+      "--Surface-Caution-Subtle",
+      "--Surface-Caution-Strong",
+      "--Surface-Success",
+      "--Surface-Success-Subtle",
+      "--Surface-Warning",
+      "--Surface-Info",
+      "--Surface-Info-Subtle",
+      "--Text-Caution",
+      "--Text-Caution-on-Inverse",
+      "--Text-Success",
+      "--Text-Warning",
+      "--Text-Info",
+      "--Border-Caution",
+      "--Border-Success",
+      "--Border-Warning",
+      "--Border-Info",
+      "--Object-Caution",
+      "--Object-Success",
+      "--Object-Warning",
+      "--Object-Info",
+      "--Caution-Base",
+      "--Caution-Action",
+      "--Success-Base",
+      "--Warning-Base",
+      "--Info-Base"
     ],
     "controlSize": [
       "--Control-Height-Xs",
@@ -134,7 +178,7 @@
     "--glass-",
     "--card-surface"
   ],
-  "namespaceNote": "P049 が「DS の変数を上書きしている」と判定する接頭辞。ここに該当し allowedVariables に無い変数を消費側 CSS が宣言していたら契約違反。shadcn 互換の小文字ブリッジ（--primary / --border 等）は消費側アプリが同名変数を持つことがあるため対象外。",
+  "namespaceNote": "P049 が「DS の変数を上書きしている」と判定する接頭辞。ここに該当し、かつ DS 自身の CSS（src/preset.css / src/styles/*.css / src/themes/*.css）に実在し、allowedVariables に無い変数を消費側 CSS が宣言していたら契約違反。接頭辞は一致するが DS に実在しない名前（消費側が DS の命名に寄せて作った独自変数。例: --Surface-Inverse-Hover）は上書きではないので対象外（issue #377）。DS の CSS が読めない環境では接頭辞一致だけで判定する。shadcn 互換の小文字ブリッジ（--primary / --border 等）は消費側アプリが同名変数を持つことがあるため対象外。",
   "wiredComponents": {
     "Button": [
       "--Control-Height-*",
@@ -166,7 +210,9 @@
     "許可リストに無い変数（--Hover-* / --glass-* / --Z-* などの内部変数）は消費側から上書きしない。必要なら DS 側に issue を立てて公開変数を増やす。",
     "DS 側で新しくサイズ・角丸を持つコンポーネントを作るときは、固定の h-* / px-* / rounded-* ではなく Control / Field 変数を arbitrary value（h-[var(--Control-Height-Md)]）で参照する。",
     "Control（Button 系）と Field（Input / Textarea / SelectTrigger）はスケールが別。ksk のフィールドは元々ボタンより背が高いため、片方に畳むと実寸が変わる。",
-    "色は semantic トークン経由でのみ上書きする。Primitive を直接参照するのは Brand ランプ（--Primitive-Brand-*）だけが例外。",
+    "primitive を直接上書きしてよいのは Brand（--Primitive-Brand-*）と Neutral（--Primitive-Gray-* / --Primitive-White / --Primitive-Black）の2つのアイデンティティパレットだけ。status 系（Red / Green / Blue / Yellow / Orange）の色調整は semantic 層（--Surface-Caution / --Text-Success / --Caution-Base 等）で行う。semantic を直接上書きするほうが、上書き1箇所で済み、DS 側が primitive の割り当てを変えても壊れない。",
+    "neutralPalette（Gray 10段 + White / Black）は Brand と並ぶアイデンティティのパレット層。warm gray など DS 既定の cool gray と違う世界観を持つプロダクトはここを差し替える。ただし Gray は --Text-High-Emphasis（本文色）や --Surface-Secondary を駆動するため、差し替えたら本文×背景のコントラストが WCAG AA（4.5:1）を満たすか消費側で必ず確認すること（light / dark 両方）。DS 側のコントラスト検査は DS 既定パレットしか見ていない。",
+    "色は semantic トークン経由でのみ上書きする。Primitive を直接参照するのは Brand ランプ（--Primitive-Brand-*）と Neutral ランプ（--Primitive-Gray-* / White / Black）だけが例外。",
     "Checkbox / RadioGroup / Switch（20px の size-5 トグル）は意図的にこの契約の対象外。「コントロールの高さ」という概念が当てはまらない固定サイズのため、Control 変数を当てると意味が壊れる。",
     "Chip は角丸（--Chip-Radius）だけを配線し、高さ・横 padding は配線しない。sm/md/lg の縦 margin（my-*）は「44px タッチターゲット - 本体高さ」ちょうどの手計算値で、height を変数化すると当たり判定の math が壊れる。",
     "AppShell / MarketingShell / MobileAppShell はページ本文の padding をシェル自身が持たない（Container の gutter か呼び出し側の contentClassName に委ねている）ため product theme の対象外。AdminShell の <main> だけが --Product-Page-Padding-Y を持つ。",

package/contracts/token-hex-cache.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Semantic Token Hex Cache",
-    "version": "1.59.0",
+    "version": "1.60.0",
     "description": "semantic / semanticDark トークン（var(--Primitive-*) 参照）を実 hex に解決したサイドカー生成物。hex はデフォルト（Blue）テーマでの解決値であり、Brand 系（meta.themeDependentKeys に列挙）はテーマ差し替え（orange/green/violet 等）で実色が変わる。テーマ別の完全解決値は `ksk-design-system/native` エクスポート（バンドル済み native トークンモジュール）の themes を参照。tokens.json 本体のスキーマは変更せず、AI がこのファイルだけで実色を把握できるようにし、primitive 値の変更による semantic 実色のドリフトを --check で機械検出する。",
     "generatedBy": "scripts/generate-token-hex-cache.mjs",
     "theme": "default",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ksk-design-system",
-  "version": "1.59.0",
+  "version": "1.60.0",
   "type": "module",
   "description": "KSK Design System — フリーランス向けマルチテーマ対応デザインシステム",
   "license": "MIT",
@@ -174,7 +174,6 @@
     "test:a11y": "vitest run --config vitest.a11y.config.ts",
     "check": "tsc -p tsconfig.app.json --noEmit && tsc -p tsconfig.type-tests.json --noEmit && bash scripts/lint-scratch.sh && bash scripts/check-deps.sh && node scripts/check-published-deps.mjs && node scripts/check-css-setup.mjs && bash scripts/check-drift.sh && node scripts/check-screen-contracts.mjs && node scripts/check-docs-drift.mjs && node scripts/check-agents-docs-sync.mjs && node scripts/check-contrast.mjs && node scripts/check-design-md.mjs && node scripts/check-tailwind-v4.mjs && node scripts/check-prefix-order.mjs && node scripts/check-flex-shrink.mjs && node scripts/check-deprecations.mjs && node scripts/generate-migration-doc.mjs --check && bash scripts/check-responsive.sh && node scripts/generate-component-lookup.mjs --check && node scripts/generate-platform-tokens.mjs --check && node scripts/generate-token-hex-cache.mjs --check && node scripts/generate-source-safelist.mjs --check && tsc -p tsconfig.native.json --noEmit && node scripts/check-native-parity.mjs && node scripts/generate-native-component-lookup.mjs --check",
     "check:agent": "npm run lint && npm run check && npm test && npm run lint:story-reuse",
-    "postinstall": "node bin/init.js postinstall",
     "version": "node scripts/sync-version.mjs",
     "mcp:build": "cd mcp-server && npm install && npm run build",
     "mcp:start": "node mcp-server/dist/index.js"

package/templates/AGENTS.md

@@ -1,5 +1,5 @@
 <!--
-  このファイルは ksk-design-system の postinstall で自動設置されました。
+  このファイルは `npx ksk-ds init` で設置されました。
   最新ルールを取り込むには: npx ksk-ds init --force
 -->
 

package/templates/CLAUDE.md

@@ -1,5 +1,5 @@
 <!--
-  このファイルは ksk-design-system の postinstall で自動設置されました。
+  このファイルは `npx ksk-ds init` で設置されました。
   最新ルールを取り込むには: npx ksk-ds init --force
 -->