ksk-design-system 1.43.0 → 1.45.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,8 @@ UI コンポーネント・画面の生成/修正・レビューの前には、
 
 コンポーネントを新規作成する前に `COMPONENT_LOOKUP.md` で同等品がないか確認すること。
 
+Storybook 全体を横断で視覚監査する（定期監査・リリース前総点検）場合は `.claude/skills/audit-pages/SKILL.md` の手順に従うこと。
+
 ---
 
 ## 必須: ファイル編集後に実行するコマンド
@@ -118,6 +126,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,12 @@ 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` で内部の並べ方を確認
 
 **`.tsx` を編集したら `bash scripts/lint-scratch.sh`、コンポーネント増減時は `npm run check` を実行すること。**
 
+Storybook 全体を横断で視覚監査する（定期監査・リリース前総点検・「全ページ確認して」）場合は `.claude/skills/audit-pages/SKILL.md` を使う。
+
 ---
 
 ## ディレクトリ構成

package/DESIGN.md

@@ -116,9 +116,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**）で、わざと一段明るい。役割が違うだけで矛盾ではない。

package/MIGRATION.md

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

package/PUBLISHING.md

@@ -158,3 +158,7 @@ bash scripts/update-consumers.sh <version> <影響リポ...>
 v1.36.0 以降は npm registry 経由配布。GitHub Actions による自動 publish はなく、
 ローカルの `npm login` 済み環境から `scripts/release.sh` で公開する。
 CI/CD に戻す場合は、NPM_TOKEN の Secrets 登録と workflow の再作成をセットで行うこと。
+
+## 関連
+
+- [UPDATING.md](./UPDATING.md) — 消費側（DS を npm 依存に持つプロジェクト）向けのアップデート手順

package/README.md

@@ -186,6 +186,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,145 @@
+# 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) の
+「移行作業の進め方」節を参照。
+
+## 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/init.js

@@ -36,6 +36,7 @@ if (cmd === "help" || cmd === "--help" || cmd === "-h") {
   npx ksk-ds lint src                 DS-first ルール違反を検査
   npx ksk-ds lint src --format json   CI 向け JSON 出力
   npx ksk-ds lint --changed           Git 差分のみ検査
+  npx ksk-ds check-migration ./src    非推奨 API の残存を検査（read-only）
 `)
   process.exit(0)
 }
@@ -46,6 +47,12 @@ if (cmd === "lint") {
   process.exit(status)
 }
 
+if (cmd === "check-migration") {
+  const { runCheckMigrationCli } = await import("../scripts/codemod/check-migration.mjs")
+  const status = runCheckMigrationCli(args.slice(1))
+  process.exit(status)
+}
+
 if (cmd === "demo") {
   runDemo(args.slice(1))
   process.exit(0)

package/contracts/components.json

@@ -1,15 +1,15 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "1.43.0",
+    "version": "1.45.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 61,
-      "patterns": 52,
+      "patterns": 54,
       "commerce": 12,
       "admin": 8,
       "shells": 3,
-      "total": 136
+      "total": 138
     }
   },
   "ui": [
@@ -294,7 +294,7 @@
     {
       "name": "Sheet",
       "path": "src/components/ui/sheet.tsx",
-      "description": "サイドパネル・ボトムシート。フィルター・メニュー・補助入力に使用。モーダルより軽いコンテキストに。snapPoints でスナップ式、swipeToClose で下スワイプ閉じを有効化。autoFocus / restoreFocusOnClose / closeOnEsc / bodyScrollLock でフォーカス・スクロール挙動を制御可能。",
+      "description": "サイドパネル・ボトムシート。フィルター・メニュー・補助入力に使用。モーダルより軽いコンテキストに。snapPoints でスナップ式、swipeToClose で下スワイプ閉じを有効化。autoFocus / restoreFocusOnClose / closeOnEsc / bodyScrollLock でフォーカス・スクロール挙動を制御可能。 多段（シートの上にシート）では open 順に overlay/content の z-index が自動繰り上げされ、zIndex / overlayClassName で上書き可能。",
       "subcomponents": [
         "SheetTrigger",
         "SheetContent",
@@ -428,10 +428,13 @@
     {
       "name": "Skeleton",
       "path": "src/components/ui/skeleton.tsx",
-      "description": "読み込み中プレースホルダ。width/height/rounded shorthand 対応。",
+      "description": "読み込み中プレースホルダ。width/height/rounded shorthand 対応。SkeletonText は lines 指定の複数行テキストプレースホルダ（最終行短縮）。",
       "rules": [
         "数値は px、文字列は CSS 値として渡る",
         "rounded: none/sm/md/lg/xl/2xl/full プリセット"
+      ],
+      "subcomponents": [
+        "SkeletonText"
       ]
     },
     {
@@ -967,6 +970,24 @@
         "Color + icon + text. Include retry action."
       ]
     },
+    {
+      "name": "Prose",
+      "path": "src/components/patterns/prose.tsx",
+      "description": "静的文書（プライバシーポリシー・利用規約等）の本文レンダラー。sections: {title, body: string[]}[] を受けて見出し+段落を統一タイポで描画する。native の Prose.tsx と props 形が一致。",
+      "rules": [
+        "見出しは typo-heading-md、段落は typo-body-md",
+        "DocumentPage の子として使う想定だが単体でも利用可"
+      ]
+    },
+    {
+      "name": "DocumentPage",
+      "path": "src/components/patterns/document-page.tsx",
+      "description": "プライバシーポリシー・利用規約などの静的文書ページ。タイトル・最終更新日・本文（Prose）を固定スペーシングで組む。native の DocumentScreen.tsx に対応（web は単体ページのため命名を DocumentPage とし、戻るナビは呼び出し側のシェルに委ねる）。",
+      "rules": [
+        "本文は max-w-2xl に収めて読みやすい行長にする",
+        "戻るナビは持たない。必要なら呼び出し側のレイアウトシェルで用意する"
+      ]
+    },
     {
       "name": "SectionHeader",
       "path": "src/components/patterns/section-header.tsx",
@@ -1620,9 +1641,10 @@
     {
       "name": "BottomSheetFrame",
       "path": "src/components/patterns/bottom-sheet-frame.tsx",
-      "description": "SheetContent の responsive outer frame preset。mobile-full / mobile-form / desktop-floating を宣言し、DetailSheetScaffold と KeyboardAwareSheetFooter を内側で合成する。",
+      "description": "SheetContent の responsive outer frame preset。mobile-full / mobile-page（iOS ページシート風・上端 2rem ギャップ）/ mobile-form / desktop-floating を宣言し、DetailSheetScaffold と KeyboardAwareSheetFooter を内側で合成する。",
       "variants": [
         "mobile-full",
+        "mobile-page",
         "mobile-form",
         "desktop-floating"
       ],
@@ -1848,7 +1870,7 @@
     {
       "name": "BottomTabBar",
       "path": "src/components/patterns/commerce/bottom-tab-bar.tsx",
-      "description": "SP 下部固定タブナビゲーション。default と pill（iOS 26 Liquid Glass）バリアント。pill は centerAction・ラベル表示・inverse tone・mobile shell max-width・floatingPosition（left/center/right）に対応。",
+      "description": "SP 下部固定タブナビゲーション。default と pill（iOS 26 Liquid Glass）バリアント。pill は centerAction・ラベル表示・inverse tone・mobile shell max-width・floatingPosition（left/center/right）に対応。選択カプセルはアイコン+ラベルを包む水滴（droplet）で、タブ切替時にスライドして移動する。scrollEdge でバー背後に progressive blur（iOS 26 scroll edge effect）を敷ける。",
       "features": [
         "badge",
         "centerAction",
@@ -1859,6 +1881,8 @@
         "maxWidth",
         "inverse-tone",
         "floatingPosition",
+        "sliding-selection-platter",
+        "scrollEdge",
         "native Expo Router tabBar adapter",
         "native hidden routes"
       ],

package/contracts/composition.json

@@ -0,0 +1,126 @@
+{
+  "meta": {
+    "name": "KSK Design System — Composition Contracts",
+    "version": "0.1.0",
+    "description": "選んだ画面パターン内部で、シェル骨格・余白リズム・カード階層・テキスト階層・CTA優先度をどう組むかを定義する機械可読契約。roleSeparation: contracts/screen-patterns.json が「どのパターン（シェル・crud・遷移）を使うか」を decisionTree で決め、本ファイルはその内部を「どう並べるか」を pageSkeletons/spacingRhythm/cardHierarchy/textHierarchy/ctaHierarchy で決める。requiredComponents/optionalComponents は contracts/components.json の実在名と一致すること（scripts/check-screen-contracts.mjs で検証）。"
+  },
+  "pageSkeletons": {
+    "mobile": {
+      "requiredComponents": ["MobileAppShell"],
+      "optionalComponents": ["MobileAppHeader", "BottomTabBar", "MobileTabBar", "MobileFloatingActionButton", "NavigationBar"],
+      "implementation": "src/components/patterns/mobile-app-shell.tsx",
+      "structure": [
+        "MobileAppShell (min-h-dvh, bg-[var(--Surface-Secondary)], mx-auto max-width=430 で中央プレビュー)",
+        "  header slot: sticky top-0 z-40 (MobileAppHeader 等)",
+        "  main (bottomPadding prop により pb-20/pb-28 をシェル側が自動付与。消費側で個別に padding-bottom を積み増さない)",
+        "    content wrapper (contentClassName)",
+        "  bottomNav slot: fixed inset-x-0 bottom-0 z-40, pb-[env(safe-area-inset-bottom)] をシェルが処理",
+        "  fab slot: bottomNav の上に浮くレイヤーとしてシェルが配置"
+      ],
+      "rules": [
+        "下部固定要素（BottomTabBar/MobileFloatingActionButton）分の余白は MobileAppShell の bottomPadding prop（\"bottom-nav\" | \"bottom-nav-fab\"）に持たせる。ページ側で pb-* を手書きしない（シェルとの二重計上を防ぐ）",
+        "safe-area-inset-bottom の吸収はシェルの責務。消費側コンポーネントで env(safe-area-inset-bottom) を再実装しない",
+        "モバイル起点のプロダクトが PC 対応する場合は desktopSidebar slot を使い、同一シェル内で lg: 分岐する（screen-patterns.json の判断基準と同じ。デスクトップ起点の業務/Web ページであれば最初から AppShell を選ぶ — MobileAppShell からの差し替えや viewport 分岐での併用はしない）"
+      ]
+    },
+    "desktop": {
+      "requiredComponents": ["AppShell"],
+      "optionalComponents": ["Breadcrumb", "SectionHeader", "SubNav"],
+      "implementation": "src/components/patterns/shells/app-shell.tsx",
+      "structure": [
+        "AppShell (flex flex-col min-h-screen, bg-[var(--Surface-Primary)])",
+        "  topBar slot: sticky top-0 z-40, border-b, h-14, px-4",
+        "  main (flex-1。bottomNav が渡された場合のみ pb-16 をシェルが自動付与)",
+        "  bottomNav slot: fixed bottom-0 inset-x-0 z-40, h-14（PC でモバイル的下部ナビを使う場合のみ）"
+      ],
+      "rules": [
+        "topBar の高さ（h-14=56px）は固定値。ページ側で高さを変えたい場合は topBar 内の要素で padding 調整し、シェルの h-14 自体は変更しない",
+        "bottomNav を渡すページは main に pb-16 が自動で付くため、ページ側で追加の下部余白を積まない"
+      ]
+    },
+    "admin": {
+      "requiredComponents": ["AdminShell"],
+      "optionalComponents": ["DataTable", "SearchPanel", "StatusTabs", "BulkActions"],
+      "implementation": "src/components/patterns/shells/admin-shell.tsx",
+      "structure": [
+        "AdminShell (flex h-screen, bg-[var(--Surface-Secondary)])",
+        "  sidebar slot: aside hidden lg:flex, border-r, bg-[var(--Surface-Primary)], ScrollArea でラップ済み（sidebarWidth prop で幅調整、既定 w-64）",
+        "  header slot: 任意。border-b, h-16, px-6",
+        "  main: flex-1 overflow-auto p-6（ページコンテンツの外周余白はここで確保済み）"
+      ],
+      "rules": [
+        "main の p-6（24px）がページ外周の既定余白。ページ側で二重に外周 padding を足さない",
+        "sidebar は lg 未満で hidden になる（モバイル用の代替ナビは呼び出し側の責務。AdminShell 自体はモバイル用ドロワーを持たない）",
+        "sidebarWidth を変える場合、hidden lg:flex は維持し幅クラスのみ差し替える"
+      ]
+    },
+    "marketing": {
+      "requiredComponents": ["MarketingShell"],
+      "optionalComponents": ["Footer", "BannerCarousel", "CountdownHero", "PhotoHero"],
+      "implementation": "src/components/patterns/shells/marketing-shell.tsx",
+      "structure": [
+        "MarketingShell (flex flex-col min-h-screen, bg-[var(--Surface-Primary)])",
+        "  header slot: sticky top-0 z-40, bg-[var(--Surface-Primary)]/95 backdrop-blur, h-16, px-6 lg:px-16",
+        "  main: flex-1",
+        "  footer slot: border-t, bg-[var(--Surface-Secondary)], py-12, px-6 lg:px-16"
+      ],
+      "rules": [
+        "左右の外周余白は px-6（モバイル）/ lg:px-16（デスクトップ）をシェルの header/footer が既に持つ。main 直下のセクションはページ側で同じ px-6 lg:px-16 を明示して揃える（シェルは main 自体に横 padding を強制しないため）",
+        "header は backdrop-blur 前提の半透明背景。header 直下に実質同色の不透明要素を重ねる場合は視覚的な二重線に注意する"
+      ]
+    }
+  },
+  "spacingRhythm": {
+    "levels": [
+      { "level": 0, "spacing": "4px (gap-1)", "usage": "ラベルと補助テキストなど、同一要素内の密接な関連情報" },
+      { "level": 1, "spacing": "8px〜12px (gap-2 / gap-3)", "usage": "アイコンとテキスト、ボタン同士の横並び、FormActions の要素間" },
+      { "level": 2, "spacing": "16px (gap-4)", "usage": "FormSection 内のフィールド間、カード内のブロック間" },
+      { "level": 3, "spacing": "24px (gap-6)", "usage": "FormRoot のセクション間、ページ内の主要ブロック間の既定リズム" }
+    ]
+  },
+  "cardHierarchy": {
+    "layers": [
+      { "depth": 0, "token": "var(--Surface-Secondary)", "usage": "ページ/シェルの背景（AdminShell・MobileAppShell 等の基底面）" },
+      { "depth": 1, "token": "var(--Surface-Primary)", "usage": "最初の浮き上がり面。Card / シート / ヘッダー・サイドバーなどページ背景の上に乗る面" },
+      { "depth": 2, "token": "var(--Surface-Tertiary)", "usage": "Card 内部でさらに一段沈める領域（コードブロック風の埋め込み、入れ子カード等）" },
+      { "depth": 3, "token": "var(--Surface-Quaternary)", "usage": "選択・ホバーなどインタラクション状態の強調背景（常設の階層としては使わない）" }
+    ],
+    "note": "hex 値は書かない。実測値が要る場合は contracts/token-hex-cache.json（デフォルトテーマ解決済み）を参照する。"
+  },
+  "textHierarchy": {
+    "tree": [
+      { "role": "画面タイトル / H1", "typo": "typo-heading-2xl", "color": "var(--Text-High-Emphasis)" },
+      { "role": "セクション見出し / H2", "typo": "typo-heading-xl", "color": "var(--Text-High-Emphasis)" },
+      { "role": "カード見出し / H3", "typo": "typo-heading-md", "color": "var(--Text-High-Emphasis)" },
+      { "role": "本文", "typo": "typo-body-md", "color": "var(--Text-High-Emphasis)" },
+      { "role": "補助本文 / 説明文", "typo": "typo-body-sm", "color": "var(--Text-Medium-Emphasis)" },
+      { "role": "ラベル（フォーム・ボタン・ナビ）", "typo": "typo-label-md", "color": "var(--Text-High-Emphasis)" },
+      { "role": "メタ情報 / タイムスタンプ", "typo": "typo-label-sm", "color": "var(--Text-Low-Emphasis)" },
+      { "role": "法的表記 / 注釈", "typo": "typo-caption", "color": "var(--Text-Low-Emphasis)" },
+      { "role": "暗背景・画像上のテキスト", "typo": "typo-on-image", "color": "var(--Text-on-Inverse)" }
+    ]
+  },
+  "ctaHierarchy": {
+    "priority": [
+      { "variant": "default", "role": "primary", "note": "1ビューポート1つまで。最重要 CTA（保存・購入・次へ 等）" },
+      { "variant": "accent", "role": "primary-decorative", "note": "primary と同格だがブランドグラデーションで一段強く目立たせたい特別な CTA（ヒーローセクション等）。default と併用しない" },
+      { "variant": "secondary", "role": "secondary", "note": "primary と並ぶ選択肢・戻る" },
+      { "variant": "secondary-switch", "role": "secondary-selected", "note": "secondary のトグル選択状態（選択中のフィルタ切替等）" },
+      { "variant": "tertiary", "role": "tertiary", "note": "primary/secondary より弱い並列アクション" },
+      { "variant": "ghost", "role": "low-emphasis", "note": "文字寄りの補助操作" },
+      { "variant": "link", "role": "inline", "note": "本文内リンク相当の操作" },
+      { "variant": "destructive", "role": "danger", "note": "削除・取り消し等。alert-dialog / ConfirmDialog 内で使うことが多い" },
+      { "variant": "inverse", "role": "primary-on-dark", "note": "暗背景・ヒーローセクション上の primary 相当" },
+      { "variant": "ghost-inverse", "role": "low-emphasis-on-dark", "note": "暗背景上の ghost 相当" },
+      { "variant": "glass", "role": "primary-on-glass", "note": "Liquid Glass 背景上の CTA" },
+      { "variant": "glass-inverse", "role": "primary-on-glass-dark", "note": "暗背景上の Liquid Glass CTA" },
+      { "variant": "glass-accent", "role": "primary-on-glass-accent", "note": "FAB 等、glass より一段強い主要アクション" }
+    ],
+    "rules": [
+      "primary（default）は1ビューポートにつき1つまで。同一ビューポートに複数の primary CTA を並べない",
+      "destructive は確認なしの即時実行トリガーにしない。alert-dialog / ConfirmDialog を経由させる",
+      "同一画面で glass 系と非 glass 系の CTA variant を隣接して混在させない（背景コンテキストが揃っている範囲でのみ glass 系を使う）",
+      "CTA の優先度は上記 priority 配列の並び順を優先度の正本とする。同一画面に variant が複数出る場合、視覚的な強さの順序は配列順と一致させる"
+    ]
+  }
+}

package/contracts/design-context.json

@@ -53,6 +53,30 @@
         "storybook coverage hints",
         "DS-first recipes"
       ]
+    },
+    {
+      "path": "contracts/token-hex-cache.json",
+      "owns": [
+        "default-theme resolved semantic hex values (generated sidecar; theme-dependent keys listed in meta.themeDependentKeys)"
+      ]
+    },
+    {
+      "path": "contracts/screen-patterns.json",
+      "owns": [
+        "screen shell/pattern selection (decisionTree)",
+        "crud-to-pattern mapping",
+        "edit UI selection criteria (dialog vs page vs focused workspace)"
+      ]
+    },
+    {
+      "path": "contracts/composition.json",
+      "owns": [
+        "page skeleton structure per shell",
+        "spacing rhythm",
+        "card/surface depth hierarchy",
+        "text hierarchy (typo-* x Text-* tokens)",
+        "CTA priority hierarchy (Button variant ordering)"
+      ]
     }
   ],
   "designMd": {