ksk-design-system 1.44.0 → 1.46.0

package/AGENTS.md

@@ -20,9 +20,15 @@ contracts/rules.json                     # 禁止パターン43件・AIアンチ
 contracts/components.json               # 全132コンポーネントの定義・バリアント・ルール
 contracts/design-context.json           # DESIGN.md と正本ファイルの関係・AI向け検査方針
 tokens.json                             # カラー・スペーシング・シャドウトークン
+contracts/token-hex-cache.json          # semantic トークンのデフォルトテーマ解決済み hex（テーマ依存キーは meta.themeDependentKeys 参照・自動生成）
 src/components/COMPONENT_LOOKUP.md      # バリアント・インポートパス一覧（自動生成）
+contracts/screen-patterns.json          # 画面実装前にどのシェル/パターンを使うかの decisionTree・crudMatrix
+contracts/composition.json              # 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度）
 ```
 
+画面（ページ/ダイアログ等）を実装・修正する場合は、まず `contracts/screen-patterns.json` の
+decisionTree でシェル/パターンを選び、`contracts/composition.json` で内部の並べ方を確認すること。
+
 UI コンポーネント・画面の生成/修正・レビューの前には、必ず
 `.claude/skills/ksk-design-system/SKILL.md` を読み、その判断基準に従うこと
 （トークン選定・コンポーネント選択・レビュー優先順位・例外運用。迷ったら同ディレクトリの `references/` を参照）。
@@ -32,6 +38,15 @@ UI コンポーネント・画面の生成/修正・レビューの前には、
 
 コンポーネントを新規作成する前に `COMPONENT_LOOKUP.md` で同等品がないか確認すること。
 
+### ローカル二重実装ゲート
+
+DS に無いと思っても consumer 側に別台帳を作らないこと。最初に `contracts/components.json` と
+`COMPONENT_LOOKUP.md` を検索し、consumer では `npx ksk-ds check-duplicates ./src --strict` を実行する。
+それでも不足する場合は DS 側に issue を登録する。やむを得ない一時実装には、削除条件と issue を
+`// ksk-ds-local-fallback: DS に X が追加されたら削除 (issue #123)` の形式で残すこと。
+
+Storybook 全体を横断で視覚監査する（定期監査・リリース前総点検）場合は `.claude/skills/audit-pages/SKILL.md` の手順に従うこと。
+
 ---
 
 ## 必須: ファイル編集後に実行するコマンド
@@ -118,6 +133,8 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **tokens.json** | カラー・スペーシング・シャドウトークンの機械可読定義 |
 | **src/components/COMPONENT_LOOKUP.md** | 全112コンポーネントのバリアント・インポートパス（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
+| **contracts/screen-patterns.json** | 画面実装前にどのシェル/パターンを使うかを決める decisionTree・crudMatrix |
+| **contracts/composition.json** | 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度） |
 
 ---
 

package/CLAUDE.md

@@ -4,6 +4,7 @@
 
 UI を書く前に必ず確認すること:
 
+- [ ] 画面の骨格は `contracts/screen-patterns.json` の decisionTree で選んだか
 - [ ] 既存コンポーネントを `src/components/COMPONENT_LOOKUP.md` で確認したか（手書き・再定義は禁止）
 - [ ] 色は semantic token（`var(--Surface-*)` / `var(--Brand-Primary)` 等）か。Tailwind標準色・生 `#hex` は禁止
 - [ ] `border` は色を併記したか（`border-[var(--Border-Low-Emphasis)]` 等）。Tailwind v4 では無色 border は currentColor になり、消費側の濃色テキストで黒ずむ（preset.css の base layer が保険だが明示が原則）
@@ -77,8 +78,11 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 | **contracts/rules.json** | 禁止パターン32件・AIアンチパターン10件・アクセシビリティ要件 |
 | **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コンポーネントのバリアント・インポートパス一覧（自動生成） |
 | **DESIGN.md** | AI エージェント向け視覚言語サマリ（トークン＋意図・voice・motion） |
+| **contracts/screen-patterns.json** | 画面実装前にどのシェル/パターンを使うかを決める decisionTree・crudMatrix |
+| **contracts/composition.json** | 選んだパターン内部の並べ方（骨格構造・余白リズム・カード階層・テキスト階層・CTA優先度） |
 
 **セッション開始時 / コードを書く前に必ず読む:**
 1. `contracts/rules.json` の `prohibited` と `aiPatterns`（AIが典型的に犯すパターン集）を確認
@@ -86,9 +90,19 @@ Brand色を差し替え（10行）→ Primitive Layer → Semantic Layer → Bri
 3. `contracts/design-context.json` で `DESIGN.md` と正本ファイルの関係を確認
 4. `src/components/COMPONENT_LOOKUP.md` で既存コンポーネントを確認（手書き・再定義の防止）
 5. `tokens.json` でカラー・余白・影・タイポのトークンを確認
+6. 画面（ページ/ダイアログ等）を実装する場合は `contracts/screen-patterns.json` の decisionTree でシェル/パターンを選び、`contracts/composition.json` で内部の並べ方を確認
+
+### ローカル二重実装ゲート
+
+DS に無いと思っても consumer 側に別台帳を作らないこと。最初に `contracts/components.json` と
+`COMPONENT_LOOKUP.md` を検索し、consumer では `npx ksk-ds check-duplicates ./src --strict` を実行する。
+それでも不足する場合は DS 側に issue を登録する。やむを得ない一時実装には、削除条件と issue を
+`// ksk-ds-local-fallback: DS に X が追加されたら削除 (issue #123)` の形式で残すこと。
 
 **`.tsx` を編集したら `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行すること。**
 
+Storybook 全体を横断で視覚監査する（定期監査・リリース前総点検・「全ページ確認して」）場合は `.claude/skills/audit-pages/SKILL.md` を使う。
+
 ---
 
 ## ディレクトリ構成

package/DESIGN.md

@@ -46,6 +46,7 @@ rounded:
 spacing:
   unit: "4px"      # 4px グリッド（scale: 0,4,8,12,16,20,24,28,32,36,40,44,48,...）
   page: "16px"     # 基準画面端マージン。実レイアウトは Screen / Shell の padding contract を優先
+  section: { xs: "32px", sm: "40px", md: "48px", lg: "56px", xl: "64px", 2xl: "80px" }
 elevation:                                          # 影色は neutral（Gray-900 ベース rgba(17,24,39,…)）でテーマ非依存
   sm: "0 1px 2px 0 rgba(0, 0, 0, 0.05)"
   md: "0 0 8px rgba(20, 20, 20, 0.08)"
@@ -98,7 +99,7 @@ EC/BtoC 系）を回すのが狙い。
 `DESIGN.md` は Google DESIGN.md の「front matter + rationale」形式を参考にした **AI 向け配布サマリ**であり、
 実装正本ではない。KSK の正本は次のファイルに置く。
 
-- `tokens.json`: primitive / semantic / dark semantic / typography / spacing / shadow / touch target。
+- `tokens.json`: primitive / semantic / dark semantic / typography / spacing / responsive breakpoint / shadow / touch target。
 - `src/styles/*.css`: 実際に publish される CSS custom properties と typography / glass utilities。
 - `contracts/rules.json`: 禁止パターン、AI anti-pattern、a11y、consumer lint の正本。
 - `contracts/components.json`: component 名、variant、subcomponent、usage rule、件数の正本。
@@ -116,9 +117,9 @@ KSK の必須正本・publish 依存にせず、KSK 固有の multi-theme / nati
 |---|---|---|
 | ブランド | `var(--Brand-Primary)` | `#2563EB` |
 | 背景(白/薄灰) | `var(--Surface-Primary)` / `-Secondary` | `#FFFFFF` / `#F9FAFB` |
-| 文字(強/中/弱) | `var(--Text-High/Medium/Low-Emphasis)` | `#111827` / `#374151` / `#6B7280` |
+| 文字(強/中/弱) | `var(--Text-High/Medium/Low-Emphasis)` <!-- docs-drift-ignore: --Text-High/Medium/Low-Emphasis --> | `#111827` / `#374151` / `#6B7280` |
 | 罫線 | `var(--Border-Low-Emphasis)` | `#E5E7EB` |
-| 状態 | `--Success/Warning/Caution/Info-Base` | `#16A34A` / `#EA580C` / `#DC2626` / `#2563EB` |
+| 状態 | `--Success/Warning/Caution/Info-Base` <!-- docs-drift-ignore: --Success/Warning/Caution/Info-Base --> | `#16A34A` / `#EA580C` / `#DC2626` / `#2563EB` |
 
 - **状態色の正本**: 上記は `*-Base`（テキスト/アイコン基準＝Primitive **600**）。`tokens.json` を正本とし、本表はその要約。
   バッジ/ピル等の強調 **fill** は別ロール `--Surface-*-Strong`（Primitive **500**）で、わざと一段明るい。役割が違うだけで矛盾ではない。
@@ -140,6 +141,7 @@ KSK の必須正本・publish 依存にせず、KSK 固有の multi-theme / nati
 ## Layout & Spacing
 
 - **4px グリッド**。余白・サイズは 4 の倍数（scale 0–60）。
+- セクション同士の縦リズムは `--Space-Section-{xs..2xl}`（32–80px）を使い、コンポーネント内の gap scale と分離する。
 - 画面端マージン: 16px を基準にしつつ、実レイアウトでは `Screen` / shell component の padding contract を優先する。
 - **タッチターゲット**（モバイル）: WCAG 2.5.5 / Apple HIG に従い主要操作（ボタン/アイコンボタン/入力/ナビ）の
   **min は 44px** 以上、推奨 48px。44 未満が避けられない **チップ（min 32px）は hitSlop**（不可視の拡張タップ領域）で

package/MIGRATION.md

@@ -105,3 +105,7 @@ npm run build
 ```
 
 それから本番デプロイへ。
+
+## 関連
+
+- [UPDATING.md](./UPDATING.md) — 消費側（DS を npm 依存に持つプロジェクト）向けのアップデート手順（バージョンの読み方・PR 作業手順）

package/PUBLISHING.md

@@ -5,7 +5,8 @@
 > **配布方式**: v1.36.0 以降は npm レジストリ経由で配布する。
 > `npm publish --access public` で公開し、各消費リポジトリの
 > `package.json` は `ksk-design-system@X.Y.Z` を参照する。
-> 消費リポ: belle-todo / trip_todo / ninshin-todo / yokoku-app / pawly（いずれも `~/LocalDev/` 直下）。
+> 対象の消費リポ一覧は `scripts/update-consumers.sh` の `DEFAULT_REPOS` が正本
+> （単体リポ・monorepo が混在し、`~/LocalDev/` と `~/LocalDev/Examination/` 配下にまたがる）。
 
 ## 前提
 
@@ -15,18 +16,32 @@
 ## 最短手順（推奨）
 
 ```bash
-bash scripts/release.sh minor   # patch / minor / major / x.y.z
+# release branch で package.json / package-lock.json と契約 version を更新
+# PR を main にマージ
+RUN_ID="$(gh run list --workflow=publish.yml --branch=main --limit=1 \
+  --json databaseId --jq '.[0].databaseId')"
+gh run watch "$RUN_ID" --exit-status
 ```
 
-これだけ。中で以下を全部やる:
+main への version 変更を `.github/workflows/publish.yml` が検知し、npm Trusted
+Publishing (OIDC) で以下を自動実行する:
 
-1. `git diff --quiet` & main ブランチチェック（曜日チェック）
-2. `npm run check`
-3. `npm version <level>`（tag 切り）
-4. `npm pack`（prepack で `dist/` を生成し、中身を検証）
-5. `npm publish --access public`
-6. `git push origin main --tags`
-7. `bash scripts/update-consumers.sh <version>`（5 リポへ PR 自動作成）
+1. npm 上の最新版と `package.json` の version を比較
+2. `npm ci`
+3. `npm publish`（prepack で `dist/` を生成）
+4. `vX.Y.Z` tag と GitHub Release を作成
+
+公開後、レジストリ反映を確認してから消費リポへ配布する:
+
+```bash
+npm view ksk-design-system@<version> version --json
+npm dist-tag ls ksk-design-system
+bash scripts/update-consumers.sh <version>
+```
+
+PR では `npm run check`、`npm test`、`npm pack --dry-run` を通してからマージする。
+ローカル認証による手動公開が必要な場合だけ `bash scripts/release.sh <version>` を
+フォールバックとして使う。
 
 > v1.35.0 で旧名 `@ksk/design-system` 互換 tgz の生成は廃止。
 > 消費5リポ + todo-shared が新名 `ksk-design-system` に移行済。
@@ -148,13 +163,20 @@ bash scripts/update-consumers.sh <version> <影響リポ...>
 ## 注意
 
 - 配布前に必ず `npm pack --dry-run` で中身確認
-- npm registry 公開には `npm login` 済みであること
+- 通常公開は Trusted Publishing (OIDC) を使う。`npm login` は
+  `scripts/release.sh` でローカル公開へフォールバックする場合のみ必要
 - `package.json#exports` を変更したら必ず利用側プロジェクトでの import を試す
 - 金曜午後のリリースは厳禁（週末に障害対応できない）
 - メジャーリリースは月初の月曜が望ましい（フィードバック収集期間が取れる）
 
 ## npm 公開について
 
-v1.36.0 以降は npm registry 経由配布。GitHub Actions による自動 publish はなく、
-ローカルの `npm login` 済み環境から `scripts/release.sh` で公開する。
-CI/CD に戻す場合は、NPM_TOKEN の Secrets 登録と workflow の再作成をセットで行うこと。
+v1.36.0 以降は npm registry 経由配布。通常公開は
+`.github/workflows/publish.yml` と npm Trusted Publishing (OIDC) を使うため、
+長寿命の `NPM_TOKEN` やローカルの `npm login` は不要。
+workflow が利用できない緊急時だけ、`scripts/release.sh` のローカル公開へ
+フォールバックする。
+
+## 関連
+
+- [UPDATING.md](./UPDATING.md) — 消費側（DS を npm 依存に持つプロジェクト）向けのアップデート手順

package/README.md

@@ -37,7 +37,7 @@ Brand 色を差し替えるだけで業種に合わせた配色に切り替わ
 
 React 19 + TypeScript / Vite / **Tailwind CSS v4** / shadcn/ui（Radix UI）/ CVA / iconsax-reactjs / Storybook
 
-**Peer dependencies**: `react` 18 or 19, `react-dom`, `tailwindcss` ^4, `radix-ui`, `@radix-ui/react-slot`, `iconsax-reactjs`
+**Peer dependencies**: `react` 18 or 19, `react-dom`, `tailwindcss` ^4
 
 ## 🚀 使い方
 
@@ -48,11 +48,18 @@ npm install ksk-design-system
 ```
 
 ```css
-/* プロジェクトの CSS */
+/* globals.css / app.css（CSS の場所に応じて ../../ の数を調整） */
+@import "tailwindcss";
 @import "ksk-design-system/preset";
+@import "ksk-design-system/themes/default";
 @import "./themes/my-client.css"; /* Brand 色を差し替えたテーマ */
+@source "../../node_modules/ksk-design-system/dist";
 ```
 
+Tailwind CSS v4 は `node_modules` を既定では走査しません。`@source` がないと、
+DS 内部だけで使うレイアウト・サイズ・状態クラスが生成されず、コンポーネントの表示や操作が崩れます。
+consumer 側の Tailwind と DS を同じビルドで処理するため、上記の設定をセットで使用してください。
+
 ```tsx
 import { Button, Card, Input, FormField } from "ksk-design-system"
 ```
@@ -75,6 +82,80 @@ npx ksk-ds lint --changed
 // ksk-ds-allow-custom-ui: medical chart requires bespoke interaction
 ```
 
+### Jest（CommonJS）でコンポーネントをテストする
+
+このパッケージは **ESM-only** です。CJS との dual build は配布せず、Jest
+側で DS とその ESM 依存を `babel-jest` の変換対象にします。Vitest など
+ESM をネイティブに扱うランナーでは、以下の設定は不要です。
+
+Jest 29 では Babel 7 系を使います（Babel 8 は `babel-jest@29` の peer
+範囲外です）。
+
+```bash
+npm install --save-dev \
+  jest@29.7.0 babel-jest@29.7.0 jest-environment-jsdom@29.7.0 \
+  @babel/core@^7.28.0 @babel/preset-env@^7.28.0 \
+  @babel/preset-react@^7.28.0 @babel/preset-typescript@^7.28.0
+```
+
+```js
+// babel.config.cjs
+module.exports = {
+  presets: [
+    ["@babel/preset-env", { targets: { node: "current" } }],
+    ["@babel/preset-react", { runtime: "automatic" }],
+    ["@babel/preset-typescript", { allExtensions: true, isTSX: true }],
+  ],
+}
+```
+
+```js
+// jest.config.cjs
+module.exports = {
+  testEnvironment: "jsdom",
+  transform: {
+    "^.+\\.m?[jt]sx?$": "babel-jest",
+  },
+  transformIgnorePatterns: [
+    "<rootDir>/node_modules/.pnpm/(?!(ksk-design-system|radix-ui|iconsax-reactjs|@radix-ui\\+[^@]+)@)",
+    "node_modules/(?!.pnpm|ksk-design-system|radix-ui|@radix-ui|iconsax-reactjs)",
+  ],
+  moduleNameMapper: {
+    "\\.(css|less|sass|scss)$": "<rootDir>/test/style-mock.cjs",
+    "^ksk-design-system/(preset|styles(?:\\.css)?|glass|tokens/(?:primitive|semantic|typography|categorical)|themes/(?:default|blue|orange|green|violet|cobalt))$":
+      "<rootDir>/test/style-mock.cjs",
+  },
+}
+```
+
+```js
+// test/style-mock.cjs
+module.exports = {}
+```
+
+この構成なら `ksk-design-system` をコンポーネント単位で mock せず、そのまま
+render できます。リポジトリ内では、実際に `npm pack` した tgz を空の Jest
+プロジェクトへインストールする再現テストを実行できます。
+
+```bash
+npm run test:jest-consumer
+```
+
+React Native / Expo の `jest-expo` でも考え方は同じです。既存の Expo preset
+は維持し、`transformIgnorePatterns` の除外対象へ
+`ksk-design-system` と利用する ESM peer を加えてください。
+
+### Consumer duplicate check
+
+DS に存在する部品を consumer 側で再実装しないよう、コンポーネント名の重複検査を同梱しています。
+
+```bash
+npx ksk-ds check-duplicates
+npx ksk-ds check-duplicates ./src --strict
+```
+
+既定は助言モードで終了コード 0、`--strict` は重複候補があると終了コード 1 です。正本は同梱の `contracts/components.json` であり、consumer 側に別の「昇格候補台帳」を作らないでください。
+
 ### Media overlay utilities
 
 動画・写真の上に文字や操作を置く場合は、`--Text-on-Media` と `.text-on-media` / `.text-on-media-secondary`、上下の `.media-scrim-top` / `.media-scrim-bottom` を使います。TikTok / Reels 型の操作群は `MediaActionCluster` が glass ボタン、ラベル、safe-area anchor、idle auto-hide をまとめて扱います。
@@ -186,6 +267,7 @@ DS コンポーネントを最大限活用したモックが `src/prototypes/`
 - **ライブ Storybook**: https://ksk-design-system.vercel.app — 全コンポーネントのバリアント・テーマ切り替えを操作可能
 - **npm**: https://www.npmjs.com/package/ksk-design-system
 - 設計思想・トークン体系の詳細は `CLAUDE.md` / `DESIGN.md` を参照
+- バージョンアップ時の確認事項・PR 手順は `UPDATING.md` を参照
 
 ## 📈 ダウンロード数
 

package/RELEASE.md

@@ -70,7 +70,7 @@ GitHub Releases にコピペできるテンプレ:
 
 ```md
 ### Breaking Changes
-- `OldComponent` を削除。`NewComponent` を使ってください。
+- `OldComponent` を削除。`NewComponent` を使ってください。<!-- docs-drift-ignore: OldComponent NewComponent -->
   自動移行: `npx ksk-design-system codemod v1-to-v2 ./src`
 - 詳細: [MIGRATION.md](./MIGRATION.md)
 ```
@@ -80,3 +80,4 @@ GitHub Releases にコピペできるテンプレ:
 - [PUBLISHING.md](./PUBLISHING.md) — 実際の手順
 - [MIGRATION.md](./MIGRATION.md) — メジャー毎の移行ガイド
 - [scripts/codemod/README.md](./scripts/codemod/README.md) — codemod 雛形と使い方
+- [UPDATING.md](./UPDATING.md) — 消費側（DS を npm 依存に持つプロジェクト）向けのアップデート手順

package/UPDATING.md

@@ -0,0 +1,160 @@
+# Updating Guide — `ksk-design-system` を使うプロジェクト向け
+
+`ksk-design-system` を npm 依存として利用しているプロジェクト（消費リポ）が、
+バージョンアップ時に何を確認し、どう作業すればよいかをまとめたガイド。
+
+DS 本体側のリリース運用は [RELEASE.md](./RELEASE.md) / [PUBLISHING.md](./PUBLISHING.md)、
+破壊変更の詳細は [MIGRATION.md](./MIGRATION.md) を参照。本ファイルは**消費側**の視点に特化する。
+
+---
+
+## 1. 前提
+
+- `package.json` の依存は通常キャレット指定（`"ksk-design-system": "^1.x.x"`）。
+  `npm install` するだけでは **patch/minor は自動では上がらない**（lockfile が既存バージョンを固定するため）。
+  実際にバージョンを上げるのは `npm install ksk-design-system@latest` 等を明示的に実行したときだけ。
+- したがって「アップデート」は自動で降ってくるものではなく、**意図的な PR 作業**として扱う。
+  無警戒に `npm update` を通常の依存更新作業に混ぜない。
+
+## 2. 1.x でのバージョンの読み方
+
+[Semantic Versioning](https://semver.org/lang/ja/) に従う。`X.Y.Z` の各桁の意味:
+
+| 種別 | 意味 | 対応要否 |
+|---|---|---|
+| **patch**（`X.Y.Z` の Z） | バグ修正・内部最適化のみ | 対応不要。そのまま上げてよい |
+| **minor**（`X.Y.Z` の Y） | 新コンポーネント・新 prop 追加など機能追加。既存 API は壊れない想定だが、**視覚的な変更**（デフォルト値の見た目調整など）が入ることがある。まれに識別子の rename 等「要対応」の変更も minor で入る | 上げた後は画面を目視確認。**必ず [MIGRATION.md](./MIGRATION.md) の当該バージョン節を確認**する |
+| **major**（`X.Y.Z` の X） | 2.0 以降、正式な破壊変更を含むリリース | [MIGRATION.md](./MIGRATION.md) 必読。codemod / 手動移行が前提 |
+
+**実例（minor だが要対応だったケース）**: v1.34.0 で npm パッケージ名が `@ksk/design-system` → `ksk-design-system` に変更された。
+機能的な破壊変更ではないため minor リリースだったが、消費側は `import` 文とpackage.json の依存名を一括置換する必要があった。
+「minor だから確認不要」と決めつけず、必ず MIGRATION.md の該当バージョン節に目を通すこと。
+
+## 3. いつ・誰が上げるか
+
+DS メンテナが新バージョンを `npm publish` した後、`scripts/update-consumers.sh` を実行して
+対象の消費リポに対して一括で bump PR を自動起票する（各リポに `chore/bump-ds-<version>` ブランチを作成し、
+`package.json` の書き換え・`npm install`・commit・push・`gh pr create` まで自動で行う）。
+
+- 対象リポの一覧は `scripts/update-consumers.sh` のデフォルト引数が正本。バージョンや対象は都度変わりうるため、本書に固定のリポ名・リポ数は書かない。
+- 各消費リポ側の作業は、**起票された PR の内容を確認してマージする**こと（下記チェックリスト参照）。
+- 緊急のホットフィックス（本番障害対応）の場合も同じ流れで、影響リポに絞って配布されることがある。
+
+## 4. 手順（消費リポ側で手動アップデートする場合）
+
+一括 PR を待たずに自分で上げる場合、または一括 PR の内容を検証する場合の手順:
+
+```bash
+# 1. 現在のバージョンと最新版を確認
+npm view ksk-design-system version
+cat node_modules/ksk-design-system/package.json | grep '"version"'
+
+# 2. 作業ブランチを切る
+git checkout -b chore/bump-ds-<version>
+
+# 3. 最新化
+npm install ksk-design-system@latest
+# 特定バージョンを指定する場合:
+# npm install ksk-design-system@1.44.0
+
+# 4. 非推奨 API の残存を検査（read-only。書き換えは行わない）
+npx ksk-design-system check-migration ./src
+
+# 5. 検出があれば MIGRATION.md の該当バージョン節の手順に従って移行する
+#    （codemod が提供されているバージョンは MIGRATION.md に実行コマンドが記載される。
+#      提供がないバージョンは MIGRATION.md の before/after に沿って手動で置換）
+git diff   # 移行で src を書き換えた場合は意図通りか必ず目視確認
+
+# 6. ビルド・lint・テスト
+npm run build
+npm run lint
+npm test
+
+# 7. 目視確認（視覚変更があり得る minor 以上は特に）
+npm run dev   # または storybook 等、対象プロジェクトの起動コマンド
+
+# 8. commit / push / PR
+#    依存ファイルに加え、移行（codemod / 手動置換）で書き換えたソースも忘れずに stage する
+git add package.json package-lock.json
+git add <移行で変更した src 配下のファイル>   # 変更がある場合。git status で漏れがないか確認
+git commit -m "chore: ksk-design-system を <version> に更新"
+git push -u origin chore/bump-ds-<version>
+gh pr create
+```
+
+手動移行が必要な項目（codemod で拾いきれないもの）は [MIGRATION.md](./MIGRATION.md) の
+「移行作業の進め方」節を参照。
+
+### Tailwind CSS v4 の走査設定
+
+アップデート後も、consumer のエントリCSSには次の構成を維持する。
+CSSファイルの場所に応じて `../../` の数だけ調整する。
+
+```css
+@import "tailwindcss";
+@import "ksk-design-system/preset";
+@import "ksk-design-system/themes/default";
+@source "../../node_modules/ksk-design-system/dist";
+```
+
+`@source` を外すと、DS内部だけで使われるクラスが生成されない。`dist` のプリビルドCSSと
+consumer側Tailwindを重ねる二重ビルド方式にも切り替えないこと。
+
+## 5. していい・ダメ早見表
+
+| していい | ダメ |
+|---|---|
+| `^1.x.x` のようなキャレット指定で依存を宣言する | `"*"` や `"latest"` で依存バージョンを固定禁止にする（意図しない破壊変更を無警戒に取り込む） |
+| `npm install ksk-design-system@latest` で明示的に更新する | `node_modules/ksk-design-system` の中身を直接編集する（次の `npm install` で消え、変更が誰にも共有されない） |
+| アップデート専用の PR（`chore/bump-ds-*`）を切る | 機能開発 PR に依存バージョン更新を混ぜる（レビューが困難になり、ロールバック時に機能ごと戻ってしまう） |
+| `npx ksk-design-system check-migration ./src` で非推奨 API の残存を確認する | 警告を無視して非推奨 API を放置したままメジャーへ上げる |
+| MIGRATION.md を確認してから minor/major を上げる | バージョン種別だけを見て「minor だから安全」と確認を省略する |
+
+## 6. トラブル時
+
+### ロールバック
+
+問題が出た場合は前バージョンに戻す:
+
+```bash
+npm install ksk-design-system@<前のバージョン>
+git diff package.json package-lock.json   # 意図通り戻ったか確認
+```
+
+戻した後は、DS 側の Issue に再現手順を添えて報告する（下記「Issue 起票先」参照）。
+
+### npm キャッシュが反映されない
+
+`npm view ksk-design-system version` で最新バージョンが取得できない、
+または `npm install` 後もバージョンが変わらない場合:
+
+```bash
+npm cache verify                                  # まずキャッシュの整合性を確認
+npm install ksk-design-system@<version>           # バージョンを明示して再取得
+```
+
+publish 直後は registry への反映に数分かかることがあるため、少し待ってから再実行する。
+それでも解決しない場合は `npm cache clean --force` の後に上記の再取得を試す。
+**追跡済みの `package-lock.json` を削除しないこと**（lockfile 全体が再生成され、
+無関係な依存まで差分に混ざる）。
+
+### peer dependency 警告
+
+`npm install` 時に React / Tailwind CSS のバージョン不一致警告が出ることがある。
+`package.json#peerDependencies` の範囲を確認し、警告の対象パッケージ自体を先に更新してから
+`ksk-design-system` を上げる。警告を `--force` / `--legacy-peer-deps` で握りつぶして進めない。
+
+### Issue 起票先
+
+DS 本体のバグ・想定外の破壊変更に遭遇した場合は、
+`ksk-design-system` リポジトリ（[GitHub](https://github.com/ekusiek716/ksk-design-system)）に Issue を起票する。
+再現手順・バージョン（更新前後）・エラーメッセージを添えること。
+
+## 7. 関連ドキュメント
+
+| ファイル | 役割 |
+|---|---|
+| [RELEASE.md](./RELEASE.md) | DS 側のリリースサイクル・運用ルール（メンテナ向け） |
+| [PUBLISHING.md](./PUBLISHING.md) | DS 側の公開・配布手順（`npm publish` 〜 `update-consumers.sh`。メンテナ向け） |
+| [MIGRATION.md](./MIGRATION.md) | バージョン間の変更点・破壊変更の詳細（消費側が上げる際に必読） |
+| **本ファイル（UPDATING.md）** | 消費側がアップデート PR をどう作業するかの手順書 |

package/bin/card-child-spacing.js

@@ -0,0 +1,111 @@
+import ts from "typescript"
+
+const SPACING_CLASS =
+  /(?:^|[\s"'`:({[])-?(?:mt|mb|my|space-y)-[^\s"'`})\]]+/
+
+function tagNameOf(node, sourceFile) {
+  if (ts.isJsxElement(node)) {
+    return node.openingElement.tagName.getText(sourceFile)
+  }
+  if (ts.isJsxSelfClosingElement(node)) {
+    return node.tagName.getText(sourceFile)
+  }
+  return ""
+}
+
+function openingOf(node) {
+  if (ts.isJsxElement(node)) return node.openingElement
+  if (ts.isJsxSelfClosingElement(node)) return node
+  return null
+}
+
+function hasMediaVariant(opening, sourceFile) {
+  const attribute = opening.attributes.properties.find(
+    (property) =>
+      ts.isJsxAttribute(property) &&
+      property.name.getText(sourceFile) === "variant",
+  )
+  if (!attribute || !ts.isJsxAttribute(attribute) || !attribute.initializer) {
+    return false
+  }
+  if (ts.isStringLiteral(attribute.initializer)) {
+    return attribute.initializer.text === "media"
+  }
+  if (
+    ts.isJsxExpression(attribute.initializer) &&
+    attribute.initializer.expression &&
+    (ts.isStringLiteral(attribute.initializer.expression) ||
+      ts.isNoSubstitutionTemplateLiteral(attribute.initializer.expression))
+  ) {
+    return attribute.initializer.expression.text === "media"
+  }
+  return false
+}
+
+function spacingClassOf(node, sourceFile) {
+  const opening = openingOf(node)
+  if (!opening) return null
+  const className = opening.attributes.properties.find(
+    (property) =>
+      ts.isJsxAttribute(property) &&
+      property.name.getText(sourceFile) === "className",
+  )
+  if (!className || !ts.isJsxAttribute(className) || !className.initializer) {
+    return null
+  }
+  const raw = className.initializer.getText(sourceFile)
+  return raw.match(SPACING_CLASS)?.[0]?.trim() ?? null
+}
+
+function directJsxRoots(node, visit) {
+  if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+    visit(node)
+    return
+  }
+  if (ts.isJsxFragment(node)) {
+    for (const child of node.children) directJsxRoots(child, visit)
+    return
+  }
+  if (ts.isJsxExpression(node) && !node.expression) return
+  ts.forEachChild(node, (child) => directJsxRoots(child, visit))
+}
+
+export function inspectCardChildSpacing(source, filePath = "source.tsx") {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TSX,
+  )
+  const findings = []
+
+  function walk(node) {
+    if (
+      ts.isJsxElement(node) &&
+      tagNameOf(node, sourceFile) === "Card" &&
+      !hasMediaVariant(node.openingElement, sourceFile)
+    ) {
+      for (const child of node.children) {
+        directJsxRoots(child, (root) => {
+          const spacingClass = spacingClassOf(root, sourceFile)
+          if (!spacingClass) return
+          const position = sourceFile.getLineAndCharacterOfPosition(
+            root.getStart(),
+          )
+          findings.push({
+            line: position.line + 1,
+            tag: tagNameOf(root, sourceFile),
+            spacingClass,
+          })
+        })
+      }
+      ts.forEachChild(node, walk)
+      return
+    }
+    ts.forEachChild(node, walk)
+  }
+
+  walk(sourceFile)
+  return findings
+}