ksk-design-system 1.56.0 → 1.58.0

package/AGENTS.md

@@ -38,6 +38,7 @@ UI を書く前に必ず確認すること:
 - [ ] CSS でベンダープレフィックス併記する場合、**`-webkit-` を先・標準形を後**に書いたか（消費側の minifier が同一プロパティとして dedupe し後勝ちのみ残すため。逆順だと Firefox で静かに無効化。`node scripts/check-prefix-order.mjs` が CI で検出）
 - [ ] flex 行（flex-col でない flex）で shrink-0 の兄弟と可変テキストを並べるとき、テキスト側に `flex-1`（+ 必要なら `min-w-[...]` 下限）を付けたか（`min-w-0` だけだと 1 文字ずつ折り返すまで潰れる。issue #293。`node scripts/check-flex-shrink.mjs` が CI で検出、例外は `ksk-lint-ignore KFX001 -- 理由`）
 - [ ] クラス名は**完全な文字列**で書いたか（`` `bg-${color}` `` のような動的合成は静的抽出できず消費側で CSS が生成されない。分岐は三項演算子か cva variant で。`scripts/generate-source-safelist.mjs` が検出）
+- [ ] コントロールの寸法（高さ・横 padding・角丸・カード余白）を書くとき、固定の `h-10` / `px-4` / `p-6` ではなく product theme の公開変数（`h-[var(--Control-Height-Md)]` / `p-[var(--Product-Card-Padding)]`）を参照したか（issue #364。許可リストは `contracts/product-theme-overrides.json`。Button 系は `--Control-*`、Input/Textarea/SelectTrigger は `--Field-*` とスケールが別）
 - [ ] `.tsx` 編集後に `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行したか
 - [ ] `FormField` を import する前にどちらか確認したか（react-hook-form の Controller と統合するなら `RhfFormField`＝`ui/form` の `FormField` を index.ts で別名 export したもの。単純な label+error 表示は `patterns/form-field` の `FormField`。迷ったら後者）
 
@@ -77,6 +78,7 @@ tokens.json                             # カラー・スペーシング・シ
 contracts/token-hex-cache.json          # semantic トークンのデフォルトテーマ解決済み hex（テーマ依存キーは meta.themeDependentKeys 参照・自動生成）
 src/components/COMPONENT_LOOKUP.md      # バリアント・インポートパス一覧（自動生成）
 contracts/screen-patterns.json          # 画面実装前にどのシェル/パターンを使うかの decisionTree・crudMatrix
+contracts/product-theme-overrides.json   # プロダクト単位で上書きしてよい CSS 変数の許可リスト（寸法・面）
 contracts/composition.json              # 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度）
 ```
 
@@ -220,6 +222,8 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **src/components/COMPONENT_LOOKUP.md** | 全コンポーネントのバリアント・インポートパス一覧（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
 | **contracts/screen-patterns.json** | 画面実装前にどのシェル/パターンを使うかを決める decisionTree・crudMatrix |
+| **contracts/deprecations.json** | 非推奨 API の正本台帳（移行先・削除予定。MIGRATION.md の一覧節と check-migration CLI の入力） |
+| **contracts/product-theme-overrides.json** | プロダクト単位で上書きしてよい CSS 変数の許可リスト（寸法・面。既定値は src/styles/product-theme.css・lint は P049） |
 | **contracts/composition.json** | 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度） |
 
 ---
@@ -241,6 +245,7 @@ src/
 │   ├── semantic.css   # Layer 2: 用途別トークン
 │   ├── typography.css # typo-* ユーティリティ
 │   ├── motion.css     # duration / easing トークン（--Motion-*）
+│   ├── product-theme.css    # プロダクト単位で上書きしてよい寸法・面の公開変数（issue #364）
 │   └── source-safelist.css  # @source safelist（自動生成・手で編集しない / issue #258）
 ├── themes/            # default / orange / green / violet / blue
 ├── preset.css         # 外部プロジェクト向けプリセット
@@ -270,6 +275,12 @@ npm run generate:lookup
 # DESIGN.md contract 検査
 npm run lint:design
 
+# 非推奨 API 台帳の整合検査（台帳 ⇔ 実ソースの @deprecated JSDoc）
+npm run lint:deprecations
+
+# MIGRATION.md の「非推奨 API 一覧」節を台帳から再生成
+npm run generate:migration-doc
+
 # @source safelist 再生成（新しい Tailwind クラスを使ったら実行）
 npm run generate:safelist
 

package/CLAUDE.md

@@ -38,6 +38,7 @@ UI を書く前に必ず確認すること:
 - [ ] CSS でベンダープレフィックス併記する場合、**`-webkit-` を先・標準形を後**に書いたか（消費側の minifier が同一プロパティとして dedupe し後勝ちのみ残すため。逆順だと Firefox で静かに無効化。`node scripts/check-prefix-order.mjs` が CI で検出）
 - [ ] flex 行（flex-col でない flex）で shrink-0 の兄弟と可変テキストを並べるとき、テキスト側に `flex-1`（+ 必要なら `min-w-[...]` 下限）を付けたか（`min-w-0` だけだと 1 文字ずつ折り返すまで潰れる。issue #293。`node scripts/check-flex-shrink.mjs` が CI で検出、例外は `ksk-lint-ignore KFX001 -- 理由`）
 - [ ] クラス名は**完全な文字列**で書いたか（`` `bg-${color}` `` のような動的合成は静的抽出できず消費側で CSS が生成されない。分岐は三項演算子か cva variant で。`scripts/generate-source-safelist.mjs` が検出）
+- [ ] コントロールの寸法（高さ・横 padding・角丸・カード余白）を書くとき、固定の `h-10` / `px-4` / `p-6` ではなく product theme の公開変数（`h-[var(--Control-Height-Md)]` / `p-[var(--Product-Card-Padding)]`）を参照したか（issue #364。許可リストは `contracts/product-theme-overrides.json`。Button 系は `--Control-*`、Input/Textarea/SelectTrigger は `--Field-*` とスケールが別）
 - [ ] `.tsx` 編集後に `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行したか
 - [ ] `FormField` を import する前にどちらか確認したか（react-hook-form の Controller と統合するなら `RhfFormField`＝`ui/form` の `FormField` を index.ts で別名 export したもの。単純な label+error 表示は `patterns/form-field` の `FormField`。迷ったら後者）
 
@@ -67,6 +68,7 @@ tokens.json                             # カラー・スペーシング・シ
 contracts/token-hex-cache.json          # semantic トークンのデフォルトテーマ解決済み hex（テーマ依存キーは meta.themeDependentKeys 参照・自動生成）
 src/components/COMPONENT_LOOKUP.md      # バリアント・インポートパス一覧（自動生成）
 contracts/screen-patterns.json          # 画面実装前にどのシェル/パターンを使うかの decisionTree・crudMatrix
+contracts/product-theme-overrides.json   # プロダクト単位で上書きしてよい CSS 変数の許可リスト（寸法・面）
 contracts/composition.json              # 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度）
 ```
 
@@ -220,6 +222,8 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **src/components/COMPONENT_LOOKUP.md** | 全コンポーネントのバリアント・インポートパス一覧（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
 | **contracts/screen-patterns.json** | 画面実装前にどのシェル/パターンを使うかを決める decisionTree・crudMatrix |
+| **contracts/deprecations.json** | 非推奨 API の正本台帳（移行先・削除予定。MIGRATION.md の一覧節と check-migration CLI の入力） |
+| **contracts/product-theme-overrides.json** | プロダクト単位で上書きしてよい CSS 変数の許可リスト（寸法・面。既定値は src/styles/product-theme.css・lint は P049） |
 | **contracts/composition.json** | 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度） |
 
 ---
@@ -241,6 +245,7 @@ src/
 │   ├── semantic.css   # Layer 2: 用途別トークン
 │   ├── typography.css # typo-* ユーティリティ
 │   ├── motion.css     # duration / easing トークン（--Motion-*）
+│   ├── product-theme.css    # プロダクト単位で上書きしてよい寸法・面の公開変数（issue #364）
 │   └── source-safelist.css  # @source safelist（自動生成・手で編集しない / issue #258）
 ├── themes/            # default / orange / green / violet / blue
 ├── preset.css         # 外部プロジェクト向けプリセット
@@ -270,6 +275,12 @@ npm run generate:lookup
 # DESIGN.md contract 検査
 npm run lint:design
 
+# 非推奨 API 台帳の整合検査（台帳 ⇔ 実ソースの @deprecated JSDoc）
+npm run lint:deprecations
+
+# MIGRATION.md の「非推奨 API 一覧」節を台帳から再生成
+npm run generate:migration-doc
+
 # @source safelist 再生成（新しい Tailwind クラスを使ったら実行）
 npm run generate:safelist
 

package/DESIGN.md

@@ -171,6 +171,10 @@ KSK の必須正本・publish 依存にせず、KSK 固有の multi-theme / nati
 影は5段（`--shadow-sm/md/lg/dialog/tooltip`）。面は md、浮く要素（dropdown/popover）は lg、
 モーダルは dialog。**境界は影＋1px罫線**で表現し、濃い影の多用は避ける。
 
+横スクロール中の固定列だけは方向付きの影を使う（`--shadow-sticky-inline-start` /
+`--shadow-sticky-inline-end`）。命名は論理方向で、inline-start = 行の先頭側に固定された列が
+末尾方向へ落とす影。生の `rgba()` を直書きせず、必ずこのトークンを参照する。
+
 ## Shapes
 
 角丸はトークン化（ベタ書き禁止）。**面 < モーダル < シート**の順で丸くなる。
@@ -265,6 +269,48 @@ Portal に載る要素（Dialog / Sheet / Popover / Toast 等）は DOM 上の
 `z-10` / `z-20` のような小さい素の値は「コンポーネント内部の重なり」用途で、
 このグローバルスケールの対象外。
 
+## Product Theme Override（プロダクト単位の寸法調整）
+
+マルチテーマ（Brand 10行差し替え）が切り替えるのは**色だけ**。コントロールの高さ・横 padding・
+角丸・カードの余白は、消費プロダクトが CSS 変数を上書きして調整する。className を何十箇所も
+書き換える運用（exam-kit の Card 角丸13箇所 = issue #332）を、変数1行に畳むための層。
+
+既定値は `src/styles/product-theme.css`、**上書きしてよい変数の許可リストは
+`contracts/product-theme-overrides.json` が正本**。ここに無い変数（`--Hover-*` / `--Z-*` /
+`--glass-*` など）は内部実装で、上書きすると DS を上げた瞬間に静かに壊れる。
+`npx ksk-ds lint <consumer>/src` の **P049** が消費側 CSS を検査する。
+
+| family | 変数 | 既定値 | 使う部品 |
+|---|---|---|---|
+| Control | `--Control-Height-{Xs,Sm,Md,Lg,Xl}` | 24 / 32 / 40 / 48 / 56px | Button の size |
+| Control | `--Control-Padding-X-{Xs,Sm,Md,Lg,Xl}` | 8 / 12 / 16 / 24 / 32px | Button の size |
+| Control | `--Control-Gap` / `--Control-Radius` | 8px / ピル | Button のアイコン間隔・角丸 |
+| Field | `--Field-Height-{Sm,Md,Lg}` | 36 / 48 / 56px | Input / SelectTrigger |
+| Field | `--Field-Padding-X-{Sm,Md,Lg}` / `--Field-Padding-Y` | 10 / 12 / 16px / 8px | Input / Textarea / SelectTrigger |
+| Field | `--Field-Min-Height` / `--Field-Radius` | 80px / 8px | Textarea / フィールド共通の角丸 |
+| Product | `--Product-Card-Padding` / `--Product-Card-Gap` | 24px / 24px | Card（default バリアント） |
+| Product | `--Product-Page-Padding-Y` | 24px | AdminShell の `<main>` 縦 padding |
+| Chip | `--Chip-Radius` | ピル | Chip の pill 角丸 |
+| Tabs | `--Control-Height-Md` / `--Control-Padding-X-{Sm,Md}` / `--Control-Radius` / `--Field-Radius` | 40px / 12・16px / ピル / 8px | TabsList / TabsTrigger（Control・Field を再利用） |
+
+- **Control と Field はスケールが別**。ksk のフィールドは元々ボタンより背が高く（Input は 48px、
+  Button の既定は 40px）、横 padding も狭い。片方に畳むとどちらかの実寸が変わるので分けている。
+- 参照は arbitrary value（`h-[var(--Control-Height-Md)]`）。Motion / Layering / Radius と同じ
+  「semantic 変数を Tailwind の任意値で読む」流儀に揃えてある。`@theme` のユーティリティ化はしない
+  （`:root` 以外のスコープに当てた上書きが効かなくなるため）。
+- 上書きは `:root` でも任意の要素でもよい。カスケードだけで解決するので Server Component のまま使える。
+- タップ領域（`Button size="icon-xl"` = 44px）と FAB（58px）は意図的にこのスケールの外に置いている。
+  product theme で縮められると HIG の最小タップ領域を割るため。同じ理由で **Chip の高さ・横 padding**
+  （sm/md/lg の縦 margin が「44px タッチターゲット - 本体高さ」の手計算値）と **Tabs の pill 高さ
+  （44px、Control スケールの 40/48px のどちらとも不一致）** も配線していない。
+- **Checkbox / RadioGroup / Switch**（20px の `size-5` トグル）は「コントロールの高さ」という概念が
+  当てはまらないため、この契約の対象外。
+- **AppShell / MarketingShell / MobileAppShell** はページ本文の padding をシェル自身が持たず
+  （`Container` の gutter か呼び出し側の `contentClassName` に委ねている）、対象外。
+  `AdminShell` の `<main>` だけが `--Product-Page-Padding-Y` を持つ。
+- 色は従来どおり semantic トークン（`--Surface-*` / `--Text-*` / `--Brand-*`）と Brand ランプの
+  上書きで調整する。カードの面は `--card-surface`、角丸は `--Radius-Surface` が既存の公開シーム。
+
 ## Components
 
 代表例（トークン参照で構成）。

package/MIGRATION.md

@@ -3,6 +3,40 @@
 メジャーバージョン間の移行ガイド。
 patch / minor は原則破壊変更なし、自動アップグレード可（例外: **v1.34.0 で npm パッケージ名を変更**。import の置換が必要。下記参照）。
 
+<!-- deprecations:start（自動生成・手で編集しない） -->
+
+## 非推奨 API 一覧
+
+正本は [`contracts/deprecations.json`](./contracts/deprecations.json)。この節はそこから生成しています。
+
+消費側での残存件数は次のコマンドで数えられます（read-only・残件があれば exit 1）:
+
+```bash
+npx ksk-ds check-migration ./src
+```
+
+| API | 使われ方 | 移行先 | 非推奨にした版 | 削除予定 |
+| --- | --- | --- | --- | --- |
+| `ListItem.interactive` | `<ListItem interactive>` | href または onClick を ListItem 自体へ渡す | 1.46.0 | v2.0.0 |
+| `ChipSelector.multiple` | `<ChipSelector multiple>` | selectionMode（multiple={false} は selectionMode="single"、multiple は selectionMode="multiple"） | unreleased | v2.0.0 |
+| `PillToggle.onValueChange` | `<PillToggle onValueChange>` | onChange | 1.49.0 | v2.0.0 |
+| `ProductCard.deliveryLabel` | `<ProductCard deliveryLabel>` | なし（v1.30.0 以降は描画されないため、渡している箇所は削除する） | 1.30.1 | v2.0.0 |
+| `Progress.tone` | `<Progress tone>` | variant | 1.40.1 | v2.0.0 |
+
+各エントリの補足:
+
+- **ListItem.interactive**（issue #207） — 外側の Link / button でラップする既存コードの視覚互換用に残している。 実装: src/components/patterns/list-item.tsx
+- **ChipSelector.multiple**（issue #352） — 既定が true（複数選択）で「渡し忘れると静かに壊れる側」に倒れているため新規実装では使わない。 実装: src/components/patterns/chip-selector.tsx / src/native/components/ChipSelector.tsx
+- **PillToggle.onValueChange**（issue #264） — 後方互換エイリアス。onChange を併せて渡した場合は onChange が優先される。 実装: src/components/ui/pill-toggle.tsx
+- **ProductCard.deliveryLabel** — 既存 consumer の型互換のためだけに残している no-op prop。 実装: src/components/patterns/commerce/product-card.tsx
+- **Progress.tone** — React Native 版のみ。既存 RN consumer 向けの互換。 実装: src/native/components/Progress.tsx
+
+削除は「全消費リポで `check-migration` の残件が 0」を条件に、`削除予定` のメジャーリリースで行います。
+
+<!-- deprecations:end -->
+
+---
+
 ## v2.0 (未リリース)
 
 まだメジャー破壊変更の予定はなし。
@@ -133,6 +167,15 @@ export default [
 
 これで codemod が拾えなかった旧 API の使用を検出できる。
 
+### Step 3.5. 非推奨 API の残存を数える
+
+```bash
+npx ksk-ds check-migration ./src
+```
+
+`contracts/deprecations.json` の非推奨 API が何件残っているかを、識別子別・ファイル別に出す
+（read-only・残件があれば exit 1 なので CI にも置ける）。
+
 ### Step 4. 動作確認
 
 ```bash