ksk-design-system 1.46.1 → 1.48.1

package/AGENTS.md

@@ -16,8 +16,8 @@
 
 ```
 .claude/skills/ksk-design-system/SKILL.md  # 判断Skill: 実装・レビューの判断基準（正本への索引）
-contracts/rules.json                     # 禁止パターン43件・AIアンチパターン10件・a11y要件
-contracts/components.json               # 全132コンポーネントの定義・バリアント・ルール
+contracts/rules.json                     # 禁止パターン・AIアンチパターン・a11y要件（件数・内容は rules.json が正本）
+contracts/components.json               # 全コンポーネントの定義・バリアント・ルール
 contracts/design-context.json           # DESIGN.md と正本ファイルの関係・AI向け検査方針
 tokens.json                             # カラー・スペーシング・シャドウトークン
 contracts/token-hex-cache.json          # semantic トークンのデフォルトテーマ解決済み hex（テーマ依存キーは meta.themeDependentKeys 参照・自動生成）
@@ -127,11 +127,11 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | ファイル | 内容 |
 |---------|------|
 | **AGENTS.md**（本ファイル） | 概要・技術スタック・コマンド・クイックスタート |
-| **contracts/components.json** | 全112コンポーネントの構造化定義（バリアント・アクセシビリティ要件） |
-| **contracts/rules.json** | 禁止パターン32件・AIアンチパターン10件・アクセシビリティ要件 |
+| **contracts/components.json** | 全コンポーネントの構造化定義（バリアント・アクセシビリティ要件。総数は meta.counts が正本） |
+| **contracts/rules.json** | 禁止パターン・AIアンチパターン・アクセシビリティ要件（正本: rules.json） |
 | **contracts/design-context.json** | `DESIGN.md` の役割・正本ファイル・外部 DESIGN.md 参照方針 |
 | **tokens.json** | カラー・スペーシング・シャドウトークンの機械可読定義 |
-| **src/components/COMPONENT_LOOKUP.md** | 全112コンポーネントのバリアント・インポートパス（自動生成） |
+| **src/components/COMPONENT_LOOKUP.md** | 全コンポーネントのバリアント・インポートパス（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
 | **contracts/screen-patterns.json** | 画面実装前にどのシェル/パターンを使うかを決める decisionTree・crudMatrix |
 | **contracts/composition.json** | 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度） |
@@ -143,20 +143,20 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 ```
 src/
 ├── components/
-│   ├── ui/           # 汎用UIコンポーネント 56個
+│   ├── ui/           # 汎用UIコンポーネント
 │   ├── patterns/
-│   │   ├── commerce/ # EC系 11個
-│   │   ├── admin/    # 管理画面系 8個
-│   │   ├── shells/   # レイアウトシェル 3個
-│   │   └── ...       # 汎用パターン 34個
+│   │   ├── commerce/ # EC系
+│   │   ├── admin/    # 管理画面系
+│   │   ├── shells/   # レイアウトシェル
+│   │   └── ...       # 汎用パターン
 │   └── icons/
 ├── styles/
 │   ├── primitive.css  # Layer 1: 原色パレット
 │   ├── semantic.css   # Layer 2: 用途別トークン
-│   └── typography.css # typo-* ユーティリティ 17クラス
+│   └── typography.css # typo-* ユーティリティ
 ├── themes/            # default / orange / green / violet / blue
 ├── preset.css         # 外部プロジェクト向けプリセット
-└── index.ts           # Public API（112コンポーネント）
+└── index.ts           # Public API（全コンポーネント）
 ```
 
 ---

package/CLAUDE.md

@@ -54,18 +54,31 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 
 ## AIモデルの使い分け方針
 
+（同一モデルで実装と検証を兼ねない — 同じバイアスを共有し独立検証にならない）
+
+### Fable 5 が使えるとき
+
 | モデル | 用途 |
 |--------|------|
 | `claude-fable-5` | 最難関の設計・長時間エージェント作業のみ（高コストのため温存） |
 | `claude-opus-4-8` | 通常のUI実装・レビュー・リファクタの既定 |
 
-**検証ループを使う場合:** 実装 = Fable 5 / 検証 = Opus 4.8 のように実装者と検証者で別モデルを使う（同一モデルは同じバイアスを共有し独立検証にならない）。
+**検証ループ:** 実装 = Fable 5 / 検証 = Opus 4.8
 
 **Fable 5 使用時の注意:**
 - thinking は常時オン（パラメータ省略でデフォルトに任せる）
 - refusal 時は `fallbacks` で Opus 4.8 に自動フォールバック
 - 30日データ保持が必須
 
+### Fable 5 が使えないとき（アクセス終了・休止期間）
+
+| モデル | 用途 |
+|--------|------|
+| `claude-opus-4-8` | 設計・UI実装・レビュー・リファクタの既定 |
+| `claude-sonnet-5` | 機械的な一括修正・定型作業（トークン節約） |
+
+**検証ループ:** 実装 = Opus 4.8 / 検証 = Sonnet 5
+
 ---
 
 ## ドキュメント構成
@@ -74,12 +87,12 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 |---------|------|
 | **CLAUDE.md**（本ファイル） | 概要・技術スタック・コマンド・クイックスタート（Claude Code用） |
 | **AGENTS.md** | 同上（Codex用。セッション開始時の読み込み指示・編集後コマンドを明記） |
-| **contracts/components.json** | 全112コンポーネントの構造化定義（バリアント・アクセシビリティ要件） |
-| **contracts/rules.json** | 禁止パターン32件・AIアンチパターン10件・アクセシビリティ要件 |
+| **contracts/components.json** | 全コンポーネントの構造化定義（バリアント・アクセシビリティ要件。総数は meta.counts が正本） |
+| **contracts/rules.json** | 禁止パターン・AIアンチパターン・アクセシビリティ要件（正本: rules.json） |
 | **contracts/design-context.json** | `DESIGN.md` の役割・正本ファイル・外部 DESIGN.md 参照方針 |
 | **tokens.json** | カラー・スペーシング・シャドウトークンの機械可読定義 |
 | **contracts/token-hex-cache.json** | semantic トークンのデフォルトテーマ解決済み hex（テーマ依存キーは meta.themeDependentKeys 参照・自動生成） |
-| **src/components/COMPONENT_LOOKUP.md** | 全112コンポーネントのバリアント・インポートパス一覧（自動生成） |
+| **src/components/COMPONENT_LOOKUP.md** | 全コンポーネントのバリアント・インポートパス一覧（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
 | **contracts/screen-patterns.json** | 画面実装前にどのシェル/パターンを使うかを決める decisionTree・crudMatrix |
 | **contracts/composition.json** | 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度） |
@@ -110,20 +123,20 @@ Storybook 全体を横断で視覚監査する（定期監査・リリース前
 ```
 src/
 ├── components/
-│   ├── ui/           # 汎用UIコンポーネント 56個
+│   ├── ui/           # 汎用UIコンポーネント
 │   ├── patterns/
-│   │   ├── commerce/ # EC系 11個
-│   │   ├── admin/    # 管理画面系 8個
-│   │   ├── shells/   # レイアウトシェル 3個
-│   │   └── ...       # 汎用パターン 34個
+│   │   ├── commerce/ # EC系
+│   │   ├── admin/    # 管理画面系
+│   │   ├── shells/   # レイアウトシェル
+│   │   └── ...       # 汎用パターン
 │   └── icons/
 ├── styles/
 │   ├── primitive.css  # Layer 1: 原色パレット
 │   ├── semantic.css   # Layer 2: 用途別トークン
-│   └── typography.css # typo-* ユーティリティ 17クラス
+│   └── typography.css # typo-* ユーティリティ
 ├── themes/            # default / orange / green / violet / blue
 ├── preset.css         # 外部プロジェクト向けプリセット
-└── index.ts           # Public API（112コンポーネント）
+└── index.ts           # Public API（全コンポーネント）
 ```
 
 ---

package/MIGRATION.md

@@ -10,7 +10,9 @@ patch / minor は原則破壊変更なし、自動アップグレード可（例
 破壊変更を入れる際にはここに以下を書く:
 1. 削除した識別子 / prop の一覧（rename テーブル）
 2. before / after コード例
-3. 自動移行コマンド: `npx ksk-design-system codemod v1-to-v2 ./src`
+3. 自動移行コマンド: `npx ksk-design-system codemod <name> ./src`（`<name>` は
+   そのリリースで追加した `scripts/codemod/<name>.mjs`。利用できる名前は
+   `npx ksk-design-system codemod` で一覧できる）
 4. 手動対応が必要な項目（codemod では拾えないケース）
 
 ---

package/RELEASE.md

@@ -41,6 +41,7 @@ T+1w  次の patch で旧 API を完全削除
 |---|---|---|---|
 | 2026-05-30 | v1.21.2 | Sheet (`side="bottom"` / `swipeToClose` / `bottom-glass`) が仮想キーボード表示時にシート上端を画面外へ出さないよう `visualViewport` 監視で修正（PR #12） | モバイルの入力付きボトムシートでタイトル/ドラッグハンドルが隠れる不具合を解消 |
 | 2026-06-13 | v1.31.1 | `.glass-specular > *` が**絶対配置の子要素**の `position`/`z-index` を踏み潰す問題を `:not(.absolute):not(.fixed):not(.sticky)` 除外で修正 | glass 面に重ねた絶対配置オーバーレイ（閉じる × 等）が consumer 側の `absolute`/`z-*` を奪われ角からはみ出す不具合を解消 |
+| 2026-07-27 | v1.48.1 | native の Modal 系オーバーレイ（Sheet plain/snap・Celebration overlay・emoji bounce）で、Modal 表示前に入口アニメーションを開始すると要素が不可視位置に残る問題を onShow 起点＋二重 fallback で修正（#250）。併せて snap sheet の gesture 状態バグ 3 件（アニメ中の再ドラッグでパネルが飛ぶ／再オープン時に下スワイプが効かない／`dismissible`・`onClose` が初回 render のまま固定）を修正 | iOS 実機で「透明なオーバーレイだけが残り操作不能」になる進行不能バグを解消。#249 で snap sheet のみ対処した同一原因が plain sheet と Celebration に残っていた |
 
 新しいホットフィックスがあれば追記する。
 
@@ -71,7 +72,7 @@ GitHub Releases にコピペできるテンプレ:
 ```md
 ### Breaking Changes
 - `OldComponent` を削除。`NewComponent` を使ってください。<!-- docs-drift-ignore: OldComponent NewComponent -->
-  自動移行: `npx ksk-design-system codemod v1-to-v2 ./src`
+  自動移行: `npx ksk-design-system codemod vX-to-vY ./src`
 - 詳細: [MIGRATION.md](./MIGRATION.md)
 ```
 

package/bin/check-duplicates.js

@@ -68,12 +68,29 @@ function loadComponentRegistry(contractsPath) {
   const contracts = JSON.parse(readFileSync(contractsPath, "utf8"))
   const registry = new Map()
 
+  const add = (name, tier, path) => {
+    if (typeof name !== "string" || name.length === 0) return
+    const matches = registry.get(name) ?? []
+    matches.push({ tier, path })
+    registry.set(name, matches)
+  }
+
   for (const tier of ["ui", "patterns", "commerce", "admin", "shells"]) {
     for (const component of contracts[tier] ?? []) {
       if (typeof component?.name !== "string" || typeof component?.path !== "string") continue
-      const matches = registry.get(component.name) ?? []
-      matches.push({ tier, path: component.path })
-      registry.set(component.name, matches)
+
+      // contracts の name は「import できる名前」とは限らない。
+      // `exported: false` は実装ファイル名 / グループ名 / 型のみの export で、
+      // その名前で import することはできない。ここに登録してしまうと、
+      // consumer のローカル実装を「DS にある」と誤検知し、存在しない export を
+      // import しろと案内してしまう。実際に import できる名前だけを登録する。
+      if (component.exported === false) {
+        for (const sub of component.subcomponents ?? []) add(sub, tier, component.path)
+        continue
+      }
+
+      add(component.exportedAs ?? component.name, tier, component.path)
+      for (const alias of component.deprecatedAliases ?? []) add(alias, tier, component.path)
     }
   }
 

package/bin/init.js

@@ -12,9 +12,10 @@
 //   npx ksk-design-system demo [dir]    # DS リポを clone + setup（お試し用）
 //   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 } from "node:fs"
+import { copyFileSync, existsSync, readdirSync } from "node:fs"
 import { dirname, join, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 import { spawnSync } from "node:child_process"
@@ -26,6 +27,9 @@ const args = process.argv.slice(2)
 const cmd = args[0] || "init"
 const force = args.includes("--force")
 
+/** scripts/codemod/ 配下にあるが codemod として呼べないもの（雛形・読み取り専用スキャナ） */
+const NON_CODEMOD = new Set(["template", "check-migration"])
+
 if (cmd === "help" || cmd === "--help" || cmd === "-h") {
   console.log(`ksk-design-system CLI
 
@@ -40,6 +44,9 @@ if (cmd === "help" || cmd === "--help" || cmd === "-h") {
   npx ksk-ds check-migration ./src    非推奨 API の残存を検査（read-only）
   npx ksk-ds check-duplicates [DIR]    DS と同名のローカル実装を検査
   npx ksk-ds check-duplicates --strict 検出時に exit 1（CI 向け）
+  npx ksk-ds codemod                   利用できる codemod を一覧
+  npx ksk-ds codemod <name> [DIR] --dry 破壊変更の自動移行（事前確認）
+  npx ksk-ds codemod <name> [DIR]      破壊変更の自動移行（書き込み）
 `)
   process.exit(0)
 }
@@ -65,6 +72,10 @@ if (cmd === "check-duplicates") {
   process.exit(status)
 }
 
+if (cmd === "codemod") {
+  process.exit(runCodemod(args.slice(1)))
+}
+
 if (cmd === "demo") {
   runDemo(args.slice(1))
   process.exit(0)
@@ -76,6 +87,74 @@ if (cmd !== "init" && cmd !== "postinstall") {
   process.exit(1)
 }
 
+// ─── codemod ────────────────────────────────────────────────
+// MIGRATION.md / RELEASE.md / scripts/codemod/README.md が案内している
+// `npx ksk-design-system codemod <name> ./src` の実体。
+// `scripts/codemod/<name>.mjs` を解決して node で起動し、残りの引数
+// （対象ディレクトリ・--dry）はそのまま渡す。
+
+function codemodDir() {
+  return join(pkgRoot, "scripts", "codemod")
+}
+
+function listCodemods() {
+  const dir = codemodDir()
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".mjs"))
+    .map((f) => f.replace(/\.mjs$/, ""))
+    .filter((name) => !NON_CODEMOD.has(name))
+    .sort()
+}
+
+function printAvailableCodemods() {
+  const available = listCodemods()
+  if (available.length === 0) {
+    console.error(`\n現在提供されている codemod はありません。`)
+    console.error(`破壊変更に対応する codemod はリリース時に追加され、`)
+    console.error(`MIGRATION.md に実行コマンドが記載されます。`)
+    console.error(`\n非推奨 API の残存を数えるだけなら:`)
+    console.error(`  npx ksk-ds check-migration ./src`)
+    return
+  }
+  console.error(`\n利用できる codemod:`)
+  for (const name of available) console.error(`  ${name}`)
+}
+
+function runCodemod(rest) {
+  const name = rest.find((a) => !a.startsWith("--"))
+
+  if (!name) {
+    console.error(`使い方: npx ksk-design-system codemod <name> [DIR] [--dry]`)
+    printAvailableCodemods()
+    return 1
+  }
+
+  // pkgRoot の外へ抜ける名前・codemod ではないファイルを弾く
+  if (!/^[A-Za-z0-9._-]+$/.test(name) || NON_CODEMOD.has(name)) {
+    console.error(`✗ codemod 名が不正です: ${name}`)
+    printAvailableCodemods()
+    return 1
+  }
+
+  const scriptPath = join(codemodDir(), `${name}.mjs`)
+  if (!existsSync(scriptPath)) {
+    console.error(`✗ codemod が見つかりません: ${name}`)
+    console.error(`  期待したパス: ${scriptPath}`)
+    printAvailableCodemods()
+    return 1
+  }
+
+  // name だけ取り除いて残り（DIR / --dry 等）をそのまま渡す
+  const nameIndex = rest.indexOf(name)
+  const forwarded = rest.filter((_, i) => i !== nameIndex)
+  const res = spawnSync(process.execPath, [scriptPath, ...forwarded], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  })
+  return res.status ?? 1
+}
+
 function runDemo(rest) {
   const consumerCwd = process.cwd()
   const targetDir = rest.find((a) => !a.startsWith("--")) || "ksk-ds-demo"

package/contracts/components.json

@@ -1,15 +1,31 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "1.46.1",
+    "version": "1.48.1",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 67,
-      "patterns": 56,
+      "patterns": 57,
       "commerce": 12,
       "admin": 8,
       "shells": 3,
-      "total": 146
+      "total": 147
+    },
+    "exportNaming": {
+      "_doc": "contracts の name が `import { name } from \"ksk-design-system\"` で解決できるかを示す。__tests__/contracts-export-integrity.test.ts が src/index.ts の実 export と突き合わせて固定する。",
+      "exported": "既定 true。false のとき name は実装ファイル名 / グループ名であり import できない。実際に import できる名前は subcomponents に列挙する。",
+      "exportedAs": "name とは別名で export される場合の実 export 名（例: FormField を KskFormField として出す等）。未使用なら省略する。",
+      "deprecatedAliases": "互換のために残している旧 export 名。新規利用は禁止。eslint/deprecated.js の DEPRECATED と同期させる（テストで固定）。",
+      "note": "型のみの export（`export type { Toast }`）は値として import できないため exported:false 扱いにする。"
+    },
+    "formBinding": {
+      "_doc": "react-hook-form との繋ぎ方。consumer と AI が「この部品は {...register()} を直接 spread できるのか」を判断するための機械可読フィールド。",
+      "register": "ネイティブ input/textarea を描画し props を素通し・ref を転送する。`<Input {...register(\"x\")} />` がそのまま動く（非制御。初期値は ref 経由で DOM に書かれ onChange は発火しない）。",
+      "controller": "value / onChange が独自シグネチャ、または Radix の onValueChange / onCheckedChange。`<Controller render={({field}) => ...} />` が必要。",
+      "layout": "値を持たないラベル / レイアウト用ラッパ。",
+      "none": "フォーム部品ではない。",
+      "rule": "register / controller を宣言したら __tests__/react-hook-form-integration.test.tsx に登場させること（defaultValues の初期表示 / reset() 追従 / 操作での値更新の 3 点）。__tests__/form-binding-contract.test.ts がこれを強制する。",
+      "rollout": "段階導入中。formBinding が未宣言のフォーム部品はまだ分類していないという意味であり、「フォーム部品ではない」という意味ではない。"
     }
   },
   "ui": [
@@ -63,6 +79,7 @@
     },
     {
       "name": "Input",
+      "formBinding": "register",
       "path": "src/components/ui/input.tsx",
       "description": "テキスト入力フィールド。h-12, rounded-sm, セマンティックトークン使用。必ずLabelとセットで使う。",
       "variants": [],
@@ -169,6 +186,7 @@
     },
     {
       "name": "DateField",
+      "formBinding": "controller",
       "path": "src/components/ui/date-field.tsx",
       "description": "DatePicker を \"YYYY-MM-DD\" ISO 文字列 API でラップする adapter。バックエンド/store が ISO date 文字列で日付を保持する場合に使う。value=\"\" が未選択を表す。",
       "variants": [],
@@ -183,6 +201,7 @@
     },
     {
       "name": "Textarea",
+      "formBinding": "register",
       "path": "src/components/ui/textarea.tsx",
       "description": "複数行テキスト入力。コメント・説明文など長文入力に使用。必ずLabelとセットで使う。",
       "variants": [],
@@ -197,6 +216,7 @@
     },
     {
       "name": "Label",
+      "formBinding": "layout",
       "path": "src/components/ui/label.tsx",
       "description": "フォームラベル。すべての入力コントロールに対して必須。htmlForで入力と紐付ける。",
       "variants": [],
@@ -218,6 +238,7 @@
     },
     {
       "name": "Checkbox",
+      "formBinding": "controller",
       "path": "src/components/ui/checkbox.tsx",
       "description": "チェックボックス。label/description/count を渡すと自動で行型レイアウトに（filter sidebar 型）。",
       "variants": [],
@@ -231,6 +252,7 @@
     },
     {
       "name": "RadioGroup",
+      "formBinding": "controller",
       "path": "src/components/ui/radio-group.tsx",
       "description": "ラジオボタングループ。単一選択に使用。各RadioGroupItemにLabelが必要。",
       "variants": [],
@@ -240,6 +262,7 @@
     },
     {
       "name": "Switch",
+      "formBinding": "controller",
       "path": "src/components/ui/switch.tsx",
       "description": "トグルスイッチ。設定のON/OFFなど即時反映するアクションに使用。",
       "variants": [],
@@ -483,6 +506,7 @@
     },
     {
       "name": "Toast",
+      "exported": false,
       "path": "src/components/ui/toast.tsx",
       "description": "トースト通知。操作結果フィードバックに使用。2 つの呼び出し方をサポート: (1) <Toaster> + useToast() の Provider モード、(2) sonner ライクな fire-and-forget API (`toast.success(...)` 等) — 後者は Toaster 不要で、初回呼び出し時に document.body 直下へ portal root を自動挿入する。",
       "variants": [
@@ -499,6 +523,11 @@
         "新規 action prop で右側に CTA ボタン (元に戻す / 再試行 等) を表示できる",
         "保存完了・接続復旧・同期開始など一時的な操作結果は Banner ではなく toast.* helper を使う",
         "connectionRestored / saveComplete / retryStarted / retryFailed helper を提供"
+      ],
+      "subcomponents": [
+        "Toaster",
+        "useToast",
+        "toast"
       ]
     },
     {
@@ -517,6 +546,7 @@
     },
     {
       "name": "NumberInput",
+      "formBinding": "controller",
       "path": "src/components/ui/number-input.tsx",
       "description": "数値入力コンポーネント。+/-ボタン付き。min/max/stepのガード・通貨フォーマット対応。<input type='number'>の代替。",
       "features": [
@@ -756,6 +786,7 @@
     },
     {
       "name": "Slider",
+      "formBinding": "controller",
       "path": "src/components/ui/slider.tsx",
       "description": "数値スライダー。価格帯フィルタ・音量など連続値の入力。範囲スライダー（2ハンドル）も対応。",
       "accessibility": [
@@ -786,6 +817,7 @@
     },
     {
       "name": "CheckboxCard",
+      "exported": false,
       "path": "src/components/ui/checkbox-card.tsx",
       "description": "カード型チェックボックス。複数選択のカード型UI。単一選択には RadioGroup を使用。",
       "accessibility": [
@@ -796,6 +828,10 @@
         "CheckboxCardGroup でグループ化",
         "expandedContent で選択時展開",
         "badge でタグ表示"
+      ],
+      "subcomponents": [
+        "CheckboxCardGroup",
+        "CheckboxCardItem"
       ]
     },
     {
@@ -1234,6 +1270,7 @@
     },
     {
       "name": "Form",
+      "exported": false,
       "path": "src/components/patterns/form.tsx",
       "description": "フォームコンテナ。FormRoot/FormSection/FormActionsで構成。複数FormFieldをまとめる。",
       "subcomponents": [
@@ -1774,6 +1811,31 @@
         "対象要素が見つからない step は画面中央フォールバック"
       ]
     },
+    {
+      "name": "PromptCoordinatorProvider/AutoPrompt",
+      "exported": false,
+      "path": "src/components/patterns/prompt-coordinator.tsx",
+      "description": "自動表示プロンプトを排他制御する headless Provider。priority 降順 + FIFO、同一 id coalesce、表示間隔、全体抑制を提供。",
+      "variants": [],
+      "sizes": [],
+      "accessibility": [
+        "headless: rendered prompt owns dialog semantics and focus management"
+      ],
+      "rules": [
+        "表示条件・頻度・永続化・内容は consumer が管理する",
+        "自動表示プロンプトだけを登録し、ユーザー操作起点の dialog は登録しない",
+        "active prompt を閉じるときは release を必ず呼ぶ"
+      ],
+      "subcomponents": [
+        "PromptCoordinatorProvider",
+        "AutoPrompt",
+        "usePromptCoordinator",
+        "usePromptSlot",
+        "suppressAutoPrompts",
+        "isAutoPromptSuppressed",
+        "AUTO_PROMPT_SUPPRESSION_EVENT"
+      ]
+    },
     {
       "name": "CookieConsent",
       "path": "src/components/patterns/cookie-consent.tsx",
@@ -1793,6 +1855,7 @@
     },
     {
       "name": "ListSkeleton / GridSkeleton",
+      "exported": false,
       "path": "src/components/patterns/list-skeletons.tsx",
       "description": "リスト型 (上部フィルタ + N 行) / グリッド型 (M×N カード) の汎用 Skeleton レイアウト。同一ファイルに 2 component。",
       "variants": [],
@@ -1806,6 +1869,10 @@
         "ListSkeleton: rowHeight で 1 行高",
         "GridSkeleton: columns 1-4 + cardHeight で調整",
         "React Native consumer は ksk-design-system/native/ui の ListSkeleton / GridSkeleton alias を使う"
+      ],
+      "subcomponents": [
+        "ListSkeleton",
+        "GridSkeleton"
       ]
     },
     {
@@ -1878,6 +1945,7 @@
     },
     {
       "name": "SettingsSection / SettingsListRow",
+      "exported": false,
       "path": "src/components/patterns/settings-section.tsx",
       "description": "設定画面の group/card/danger section と row。title / description / action / leading / rightSlot を持ち、switch / badge / button を安定配置する。",
       "variants": [
@@ -1902,6 +1970,10 @@
         "設定一覧で ad-hoc flex row を作らず SettingsListRow を使う",
         "switch / badge / button は rightSlot に置く",
         "danger variant は削除・ログアウトなど不可逆操作のグループに限定する"
+      ],
+      "subcomponents": [
+        "SettingsSection",
+        "SettingsListRow"
       ]
     },
     {
@@ -1928,6 +2000,7 @@
     },
     {
       "name": "CompactFilePicker / ImageAttachmentPicker",
+      "exported": false,
       "path": "src/components/patterns/compact-file-picker.tsx",
       "description": "mobile sheet 内で使う compact file/image picker。hidden input trigger、preview、remove affordance、label、description、disabled/loading state を DS 化する。",
       "features": [
@@ -1952,10 +2025,15 @@
         "Native では DocumentPicker/ImagePicker を起動する onPress trigger として使う",
         "object URL の生成/破棄は consumer state 側で管理し、DS には src と id を渡す",
         "画像 preview/delete の row/grid boilerplate を consumer に置かない"
+      ],
+      "subcomponents": [
+        "CompactFilePicker",
+        "ImageAttachmentPicker"
       ]
     },
     {
       "name": "QuickActionGrid / ActionTile",
+      "exported": false,
       "path": "src/components/patterns/quick-action-grid.tsx",
       "description": "ショートカット/絵文字 action の button tile と grid。icon/emoji、label、description、meta、selected/disabled/loading state、2/3/4 column または auto-fit を持つ。",
       "variants": [
@@ -1976,6 +2054,10 @@
         "shortcut row/grid の columns/gap を consumer 側で決め打ちしない",
         "children には ActionTile を使う",
         "選択状態は selected prop を使う"
+      ],
+      "subcomponents": [
+        "QuickActionGrid",
+        "ActionTile"
       ]
     }
   ],

package/contracts/token-hex-cache.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Semantic Token Hex Cache",
-    "version": "1.46.1",
+    "version": "1.48.1",
     "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",