@cakejp/design-system 0.6.0 → 0.9.0

package/CHANGELOG.md

@@ -7,12 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [Unreleased]
+
+---
+
+## [0.9.0] - 2026-07-08
+
+### ✨ Added
+
+- **EcPageShell**（primitives・新規）: EC 標準ページの骨格。`contracts/composition.json` の pageSkeletons（min-h-dvh / flex-1 / SP の pb-20）を構造的に保証し、bottomTab を渡すと下余白をシェルが自動管理するため付け忘れ・二重がけを防ぐ。ロゴ・タブ項目は焼き込まず全て props で受ける
+- **FunnelShell**（primitives・新規）: EC 購入導線（カート→お届け先→支払い→確認）向けの集中モード。issue #37 MTG フィードバック「EC側にも Full Page（集中モード）があり、ヘッダーが変わる」の実体化。戻る＋進捗インジケータの簡素ヘッダーを持ち、グロナビ・タブバー・パンくずを構造的に持たない離脱抑制の枠。ステップ定義は props で受ける
+- **AdminSideNav / AdminHeader**（primitives・新規）: AdminLayout 内で `MissingComponent` ラップのままだったサイドナビとヘッダーを正式コンポーネント化。項目データは全て props で受け、Cake.jp 固有のメニュー定義は ec の AdminLayout が既定値として持つ。公開 API は完全互換
+
+### 🛡 Internal
+
+- **shell の層分け原則を確立**: primitives＝汎用枠（データ全部 props）/ ec＝Cake.jp 既定値 / pages＝ストーリーのみ非配布、という3層の責務分担を EcPageShell・FunnelShell・AdminSideNav・AdminHeader の実装で徹底。`components.json` の `kind:"shell"` は5件（AdminLayout / WorkspaceLayout / MypageShell / EcPageShell / FunnelShell）に
+- **composition.json**: pageSkeletons（mobile/desktop）に `implementation` フィールドを追加し EcPageShell がこの骨格の実装体であることを明記、FunnelShell の funnel エントリを新設
+- **screen-patterns.json**: 各パターンの `dsComponentsNote` に AdminLayout / EcPageShell / MypageShell / WorkspaceLayout / FunnelShell のシェル使い分け基準を追記
+
+---
+
+## [0.8.0] - 2026-07-08
+
+### ✨ Added
+
+- **contracts/screen-patterns.json**（新規）: CRUD 機能でどの画面パターンを使うか AI・エンジニアが機械的に判断できるようにする契約ファイル。Standard Page（View / Edit）・Focused Workspace・ResponsiveDialog・Dialog の5パターンを定義し、CRUD 対応表と AI が辿れる6ステップ決定木を収録。npm 配布されるため消費側の codex/エンジニアにも届く。人間向け正本は `guidelines/foundations/screen-patterns.md`（issue #37 の型化）
+- **contracts/composition.json**（新規）: ページ骨格・余白リズム4レベル・Card/Text/CTA の階層関係を契約化。CTA「default は1画面1つ」ルールを正式ルールへ昇格
+- **WorkspaceLayout**（primitives・新規）: 全画面集中編集シェル。編集ヘッダーは左に戻る・右上に上位アクションのみを持ち、グロナビ/パンくずを構造的に持たない設計（既存 Header の `variant="back"` + `rightSlot` を再利用し、上位アクションは任意 prop で「ある場合のみ」を型で表現）。`components.json` では `kind:"shell"` に分類
+- **SectionNav**（primitives・新規）: ページ内セクション移動専用の目次型ナビ。サイドバー型の SideNav とはアフォーダンスが異なるため新設し、両者は相互排他ルールで使い分けを明示
+- **components.json の `kind:"shell"`**: AdminLayout / WorkspaceLayout / MypageShell をシェル系コンポーネントとして分類
+- **scripts/check-docs-drift.sh**（新規）: guidelines md 内に書かれたコンポーネント名の実在性を検査。`npm run check` に組込み
+
+### 🐛 Fixed
+
+- **ResponsiveDialog / ChartControls の export 漏れ**: `index.ts` からのエクスポートが欠落しており、消費側で import できなかった問題を修正
+- **Card の `py-0` 残骸による余白ゼロ**: Storybook ストーリー2件で余白が意図せずゼロになっていた問題を修正
+- **guidelines の架空コンポーネント名21箇所**: 実装に存在しないコンポーネント名（例: `TopAppBar` → 実際は `Header`）をドキュメント全体で実名に修正
+- **responsive 違反2件**: `anniversary.stories.tsx` の SP専用実装（レスポンシブクラス0件）に `@md:` コンテナクエリで PC 対応を追加し、`favorites.stories.tsx` の `@container` 宣言漏れ（`@md:` が効いていなかった）を修正
+
+### 🛡 Internal
+
+- **MypageShell を `pages/` から `ec/` へ移動**: `pages/` はストーリー専用・非配布ディレクトリとして純化
+- **Header の重複登録と counts 不整合を修正**: `components.json` で primitives / ec 双方に登録されていた重複を解消
+- **check-drift.sh に重複登録検出を追加**: `.foundations` / `.primitives` / `.ec` 全エントリの `name` / `path` の重複を検出し、重複時は該当ティアを明示して exit 1（過去に Header が primitives と ec に重複登録された事故の再発防止）(#39)
+- **lint 負債211件を解消**: `npm run lint` の既存負債（170 errors / 41 warnings、issue #37 実装前から存在）を eslint.config.js のルール緩和なしで全解消。`no-unused-vars` / Storybook framework 移行 / 冗長 story name 削除 / Fast Refresh 例外の理由コメント化ほか (#40)
+- **全 guidelines md に「正本は contracts」注記を追加**: ドキュメントと契約ファイルの二重管理による齟齬を防止
+
+---
+
+## [0.7.0] - 2026-06-19
+
+### ✨ Added
+
+- **IconBadge**（foundations・新規）: 丸いアイコンバッジ（`md`=44px / `lg`=72px、内部アイコン 20px / 38px）を部品化。淡いアクセント背景（`Surface-Accent-Primary-Light`）の円にアイコンを `currentColor`（`Object-Accent-Primary`）で中央配置。**外側 margin を持たない**設計で、`Card` の `flex-col gap-4`(16px) との「縦余白の二重がけ」を構造的に防ぐ。`import { IconBadge } from "@cakejp/design-system"` で利用可。Storybook に md/lg 両サイズ＋Card 内使用例を追加
+- **Container / Section**（primitives・新規）: ページレイアウトの責務を分離する薄い2部品。`Container`（`size`: page/narrow/wide/fluid、`gutter`: default/tight/none）が**左右余白と中央寄せの唯一の担い手**、`Section`（`spacing`: sm/md/lg/xl、`background`: none/subtle/accent-subtle）が**全幅の縦リズムと背景帯**を持つ。背景は Section・左右 padding は Container と分担することで「背景帯は画面端まで・コンテンツは中央寄せ」を**左右 padding の二重がけなし**で成立させる（consumer の `.section`/`.section-inner` 手書きで起きていた構造バグの恒久対策）。Storybook に推奨パターン例を追加
+- **SectionHeader**: `align="center"` と `eyebrow` スロットを追加。ランディング/ガイド系の中央寄せ大見出し（Eyebrow Badge + Title + Subtitle）に対応。`align` 無指定は `start`（従来の左寄せ＋もっと見る）で**既存の使い方は無変更**
+- **セクション余白トークン `--Space-Section-*`**: `xs`〜`2xl`（32/40/48/56/64/80px・8の倍数）を `preset.css` / `preset-standalone.css`（`./preset-standalone` エントリ）/ `tokens.json`(`spacing.section`) に追加。`spacing.scale`（最大24px）を超えるセクション縦リズム用の意味的トークンで、Tailwind を使わない入口でも参照可能。生CSS/HTML モックの rem 直書きの置換先になる
+
+### 🛡 Internal
+
+- **Card の縦間隔ルールを明文化（二重がけ防止）**: 子要素の縦間隔は Card 本体の `flex-col gap-4`(16px) が一括所有し、直下の子に `margin-top/bottom`・`space-y-*` を足さない旨を `contracts/components.json` の Card ルールに追記（正典）。`AGENTS.md` の「書く前ゲート」にも同趣旨を反映
+- **R18c（補助 lint）**: JSX 直書きの `<Card>` 直下の子の `mt-/mb-/my-/space-y-*` を warning で検出。`contracts/rules.json` ＋ `scripts/lint-scratch.sh` に実装（`CardContent` 等ネストの子は誤検知しないガード込み）し、vitest 回帰テストを追加。別 CSS/module.css の margin は正規表現では検出不可な旨を `note` に明記（本命は上記 Card ルールと IconBadge）
+- **生CSS の rem 直書き lint（R11b/R12b）**: `padding`/`gap`（`padding-inline/block` 等の複合プロパティ含む）の rem 直書きを `contracts/rules.json` に追加し、`lint-scratch.sh` に DS 自身の `src/**/*.css`（および引数で渡した CSS）を対象とした CSS スキャンを配線（`var()` 参照・カスタムプロパティ定義は除外）。R11/R12 は Tailwind 任意値 `[Npx]` しか見ずすり抜けていた経路を補強し、vitest 回帰テストを追加。限界（consumer リポジトリの CSS には届かない）を `note` に明記
+
+### 🐛 Fixed
+
+- **Toast(Sonner)**: ダークモードで状態トースト（success/error/warning/info）の説明文がほぼ不可視になる問題を修正。背景は primitive の明色で固定なのに説明文が semantic（ダークで白に反転）だったため。説明文・cancel ボタンをモード非依存の primitive 色に固定し、error の見出し・アイコンの低コントラストも同時に解消
+
+### 🎨 Changed
+
+- **角丸の統一（#18 シャープ化の追随）**: ProductCard カートボタン / CouponCard CTA / ReviewCard「参考になった」/ Toast(Sonner) アクションボタンの角丸を Button のサイズ対応に統一（`rounded-xl`→`lg`、`rounded-[18px]`→`xl`）。#18 が Button 本体をシャープ化した際に取り残されたボタン風 CTA のコピーを追随させたもの
+
+### 🛡 Internal
+
+- **角丸・シャドウのルールをトークン実態と整合**: `rounded-md`(8px)/`rounded-xl`(14px) と `shadow-md/lg` は preset.css/tokens.json の正規トークンのため許可に変更（禁止は `rounded-3xl/4xl`・任意値・`shadow-xl/2xl` のみに）。SVG ブランド色（fill/stroke 内）と %・fr・vw のコンテナ比率値の例外を明文化（contracts/rules.json AI7 改訂・R53 新設・R8/R11/R12 / lint-scratch.sh / CLAUDE.md・CLAUDE_DEV.md）
+- **lint-scratch に `--components` ティア追加**: foundations/primitives/ec のコンポーネント定義にトークン系チェック（HEX/任意px/角丸/シャドウ）を適用。`npm run check`・pre-commit・PostToolUse hook に配線。例外は `lint-scratch-allow` コメントで明示
+- **tokens.json を preset.css と同期**: radius.2xl〜4xl 追加、shadow.* の値ドリフト解消、overlay 追加
+- 任意値の同値正規化（視覚変化なし）: Button xl `rounded-[14px]`→`rounded-xl`、Tooltip 矢印 `rounded-[2px]`→`rounded-xs`、BottomTabBar `rounded-[18px]`→`rounded-full`、SideNav `pl-[14px]`→`pl-3.5`、AdminLayout `pl-[72px]`→`pl-18` ほか
+
+---
+
 ## [0.6.0] - 2026-06-11
 
 ### ✨ Added
 
 - **ListItem**: インタラクティブ（`href` / `onClick`）な行に hover 背景（`Surface-Tertiary`）と focus-visible リング（`Focus-High-Emphasis`）を追加。`onClick` のみの場合は `role="button"` ＋ Enter / Space キー操作にも対応。表示専用行（href/onClick なし）は変化なし (#21)
 
+### 🎨 Changed
+
+- **Button**: 角丸を全サイズで -4px してシャープ化（よりキリッとした印象に） (#18)
+
 ### 🐛 Fixed
 
 - **border（全コンポーネント）**: 色指定のない `border` を持つ 16 コンポーネントに border 色を明示し、Tailwind v4 のグローバル base reset 非依存に。消費側がリセットを取り込まないと罫線が要素の文字色へ化ける問題を防止。回帰防止 lint（`scripts/check-border-color.mjs`）と「`dist/index.css` import 必須」の明記を追加 (#20)
@@ -23,6 +107,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **lint**: `check-border-color` が CVA 定義内の border も走査するよう拡張（色なし border の回帰防止を強化） (#24)
 - **Storybook**: 「Hostile ctx」検出ツールが Radix Portal（Dialog/Popover 等）の継承漏れも検出できるよう body へのスタイル適用に対応 (#24)
+- **docs**: CLAUDE.md を利用者向け / 開発者向け（CLAUDE_DEV.md）に分離 (#17)
 
 ---
 

package/CLAUDE.md

@@ -19,6 +19,8 @@ PdM や社長が AI（Claude 等）で HTML モックを作る際、このパッ
 |---------|------|----------|
 | **contracts/rules.json** | 禁止パターン・アクセシビリティ要件・ライティングルール | **コード生成前に必ず** |
 | **contracts/components.json** | 全コンポーネントの定義（variants・rules・accessibility） | コンポーネント利用・画面作成時 |
+| **contracts/screen-patterns.json** | 画面パターン判断基準（CRUD・編集/作成/削除UIの選択） | 管理画面・編集/作成/削除UIを作る時 |
+| **contracts/composition.json** | ページ骨格・余白リズム・視覚階層の組み方 | レイアウト・画面構成を組む時 |
 | **tokens.json** | カラー・タイポグラフィ・スペーシング・影・角丸 | トークン値を参照する時 |
 | **CLAUDE_PRODUCTION.md** | 本番実装参照ルール・Figmaチェックリスト・本番サイト対応表 | 本番再現・新規画面作成時 |
 
@@ -31,9 +33,10 @@ PdM や社長が AI（Claude 等）で HTML モックを作る際、このパッ
 | 追加しようとしているもの | DSで確認すること |
 |------------------------|----------------|
 | `::before` / `::after` で装飾（色付きバー・ドット・矢印等） | SectionHeader, Chip, Badge, ListItem の variants |
-| カスタムカラー（`rgba(...)` / `#xxxxxx` / ハードコード） | `tokens.json` のトークン名を使う。存在しないトークンは使わない |
-| カスタムシャドウ（`box-shadow: ...`） | `tokens.json` の `shadow.*` を使う |
-| カスタムボーダー半径（`border-radius: ...px`） | `tokens.json` の `radius.*` を使う |
+| カスタムカラー（`rgba(...)` / `#xxxxxx` / ハードコード） | `tokens.json` のトークン名を使う。存在しないトークンは使わない。例外: サードパーティブランドロゴの SVG `fill=`/`stroke=` 内のみ HEX 直書き可（出典コメント必須） |
+| カスタムシャドウ（`box-shadow: ...`） | `shadow-xs/sm/md/lg`（preset.css が DS 値に再定義済み）または用途別 `shadow-menu/tooltip/dialog/modal/overlay`。`shadow-xl/2xl` 禁止。オーバーレイの `md/lg` は正規仕様 |
+| カスタムボーダー半径（`border-radius: ...px` / `rounded-[Npx]`） | `rounded-xs/sm/md/lg/xl/2xl/full` のみ（= `tokens.json` の `radius.*`、`--radius`=10px 基準で 2/6/8/10/14/18px）。`rounded-3xl` 以上・任意値は禁止 |
+| コンテナ比率の任意値（`px-[22.25%]` 等） | 4px グリッドは px 値のみ対象。%・fr・vw は理由コメント付きで許可 |
 | カスタムフォントサイズ・ウェイト | `tokens.json` の `typography.*` を使う |
 | 新しい `<div>` ラッパーでレイアウト構造を作る | Card, Section, Stack 等のコンポーネントに置き換えられないか確認 |
 | 生の `<button>` `<input>` `<select>` `<textarea>` `<table>` | DS の Button / Input / Select / Textarea / DataTable を使う |

package/contracts/components.json

@@ -3,11 +3,12 @@
     "name": "Cake.jp Design System — Component Contracts",
     "version": "0.1.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
+    "kind": "kind:\"shell\" は複数ページで再利用されるレイアウト枠（AdminLayout / WorkspaceLayout / MypageShell 等）。無印は部品コンポーネント。固有ページを組むときは該当 shell から始める。src/components/pages/ 配下のストーリーは特定ページ専用・非配布のため contracts の対象外。",
     "counts": {
-      "foundations": 46,
-      "primitives": 34,
-      "ec": 23,
-      "total": 103
+      "foundations": 47,
+      "primitives": 42,
+      "ec": 24,
+      "total": 113
     }
   },
   "foundations": [
@@ -109,7 +110,8 @@
         "CardFooter"
       ],
       "rules": [
-        "paddingはCard本体のp-4で一括管理。全幅コンテンツは-mx-4で突き破る"
+        "paddingはCard本体のp-4で一括管理。全幅コンテンツは-mx-4で突き破る",
+        "子要素の縦間隔はCard本体のflex-col gap-4(16px)で一括管理。直下の子にmargin-top/bottom/space-yを足さない（gapと二重がけになり間延びする）。丸アイコンはIconBadgeを使う（外側marginを持たない）"
       ]
     },
     {
@@ -185,6 +187,20 @@
       "name": "HoverCard",
       "path": "src/components/foundations/hover-card.tsx"
     },
+    {
+      "name": "IconBadge",
+      "path": "src/components/foundations/icon-badge.tsx",
+      "variants": [
+        "md",
+        "lg"
+      ],
+      "rules": [
+        "丸アイコンバッジ（md=44px/lg=72px）。アイコンを淡いアクセント背景の円で囲む装飾要素",
+        "外側marginを持たない。縦間隔は親Cardのflex-col gap-4(16px)に委ねる（二重がけ防止）",
+        "アイコン色はcurrentColor(--Object-Accent-Primary)を継承。中のアイコンにcolorを渡さない",
+        "アイコンサイズはバッジが固定(md=20px/lg=38px)。アイコン側にsizeを渡さない"
+      ]
+    },
     {
       "name": "Input",
       "path": "src/components/foundations/input.tsx",
@@ -425,7 +441,10 @@
       "name": "FormField",
       "path": "src/components/primitives/form-field.tsx",
       "variants": {
-        "descriptionPosition": ["above", "below"]
+        "descriptionPosition": [
+          "above",
+          "below"
+        ]
       },
       "rules": [
         "Label+Input+エラーメッセージをセットで管理",
@@ -526,11 +545,41 @@
         "flex"
       ]
     },
+    {
+      "name": "Container",
+      "path": "src/components/primitives/container.tsx",
+      "variants": [
+        "size: page | narrow | wide | fluid",
+        "gutter: default | tight | none"
+      ],
+      "rules": [
+        "ページ最大幅と左右paddingの唯一の担い手。これを使う親(Section等)は自身で左右paddingを持たない（二重がけ防止）",
+        "縦余白・背景色は持たない（Sectionの責務）"
+      ]
+    },
+    {
+      "name": "Section",
+      "path": "src/components/primitives/section.tsx",
+      "variants": [
+        "spacing: sm | md | lg | xl",
+        "background: none | subtle | accent-subtle"
+      ],
+      "rules": [
+        "全幅の縦リズム＋背景帯。左右paddingを持たない（左右余白はContainerが唯一の担い手）",
+        "背景色はSection(全幅)が持ち中央寄せはContainerが持つ → 背景帯は画面端まで・コンテンツは中央寄せが二重がけなしで成立",
+        "縦余白はSP/PCペアで --Space-Section-* トークンを消費（rem直書き撲滅）"
+      ]
+    },
     {
       "name": "SectionHeader",
       "path": "src/components/primitives/section-header.tsx",
+      "variants": [
+        "size: 3xl | 2xl | xl | lg | md | sm",
+        "align: start | center"
+      ],
       "rules": [
-        "タイトル+もっと見るボタンをCardTitle+Button手書き禁止。SectionHeaderを使う"
+        "タイトル+もっと見るボタンをCardTitle+Button手書き禁止。SectionHeaderを使う",
+        "中央寄せ大見出し（ランディング/ガイド系）は align=\"center\" を使う。eyebrow プロップに Badge 等を載せられる。手書きの中央寄せ見出し禁止"
       ]
     },
     {
@@ -558,15 +607,117 @@
     {
       "name": "SideNav",
       "path": "src/components/primitives/side-nav.tsx",
-      "category": "navigation"
+      "category": "navigation",
+      "rules": [
+        "ページ間遷移（別 URL へのナビゲーション）に使う。チェブロン付きで「別ページへ移動する」アフォーダンスを持つ",
+        "ページ内アンカー移動（href=\"#...\"）に流用しない → SectionNav を使う（見た目と挙動の不一致を防ぐ）"
+      ]
+    },
+    {
+      "name": "SectionNav",
+      "path": "src/components/primitives/section-nav.tsx",
+      "category": "navigation",
+      "rules": [
+        "ページ内セクション移動（アンカー／目次）専用。href=\"#section-id\" のページ内スクロールに使う",
+        "ページ間遷移に使わない → SideNav を使う",
+        "チェブロン・矢印を足さない（遷移アフォーダンスを持たせない。同一画面内の位置移動に見せる）",
+        "WorkspaceLayout の sectionNav にはこれを使う（SideNav を流用しない）",
+        "固有幅・背景・境界を持たない（w-full）。パネル化・幅決定はシェル／利用側の責務"
+      ]
+    },
+    {
+      "name": "EcPageShell",
+      "path": "src/components/primitives/ec-page-shell.tsx",
+      "kind": "shell",
+      "variants": [],
+      "rules": [
+        "EC 標準ページ（Standard Page（View / Edit））の骨格。composition.json pageSkeletons（mobile / desktop）の実装体。min-h-dvh flex flex-col の全高コンテナに header / main / bottomTab / footer を積む",
+        "あくまで枠。Cake.jp のロゴ・タブ項目・ナビ項目・文言を焼き込まない。header / bottomTab は利用側（ec 層）が組み立てて渡す",
+        "bottomTab を渡すと main の下余白（pb-20 相当）はシェルが管理する。ページ側で pb-20 を書かない（付け忘れ／二重がけの構造的防止）",
+        "左右 padding は持たない（Container の責務）。中身は Section（全幅背景帯）＋ Container（中央寄せ・左右余白）で組む",
+        "管理画面は AdminLayout、複数情報をまたぐ集中編集は WorkspaceLayout、マイページ配下は MypageShell を使う"
+      ]
+    },
+    {
+      "name": "WorkspaceLayout",
+      "path": "src/components/primitives/workspace-layout.tsx",
+      "kind": "shell",
+      "variants": [],
+      "rules": [
+        "Focused Workspace（全画面集中編集）のシェル。編集ヘッダー（Header variant=back）+ 任意のセクションナビ + 編集本体で構成",
+        "グローバルナビ・パンくずを持たない（構造的に置けない）。集中を妨げる導線は出さない",
+        "primaryActionはワークスペース全体の上位アクション（公開申請・承認依頼等）がある場合のみ。セクション／行単位の操作はコンテンツ内に置く",
+        "標準の編集はAdminLayoutのStandard Page（Edit）（旧Form Page）。複雑・複数情報をまたぐ集中編集・没入執筆のみWorkspaceLayoutを使う",
+        "sectionNavは編集内ナビ（アンカー／ステップ）のみ。PCでサイド表示・SPで非表示"
+      ]
+    },
+    {
+      "name": "FunnelShell",
+      "path": "src/components/primitives/funnel-shell.tsx",
+      "kind": "shell",
+      "variants": [],
+      "rules": [
+        "EC 購入導線等のファネル用集中モード（Full Page）のシェル。集中ヘッダー（Header variant=back）＋進捗インジケータ（steps/activeStep）＋ステップ本体＋任意の bottomAction で構成。min-h-dvh flex flex-col の全高コンテナ",
+        "あくまで枠。ステップ定義（名前・数）・文言・商品データを焼き込まない。steps / activeStep は利用側（ドメイン）が渡す",
+        "グローバルナビ・BottomTabBar・パンくずを持たない（構造的に置けない）。離脱を誘う導線を出さず購入に集中させる",
+        "bottomAction（StickyActionBar 等）を渡すと本文の下余白はシェルが管理する。ページ側で pb を書かない（付け忘れ／二重がけの構造的防止）",
+        "左右 padding は持たない（Container の責務）。管理画面の複雑な集中編集は WorkspaceLayout を使う（EC 購入導線＝FunnelShell）"
+      ]
+    },
+    {
+      "name": "Header",
+      "path": "src/components/primitives/header.tsx"
+    },
+    {
+      "name": "AdminSideNav",
+      "path": "src/components/primitives/admin-side-nav.tsx",
+      "category": "navigation",
+      "rules": [
+        "管理画面向けサイドナビの汎用枠。PC は左端固定アイコンレール（ホバーでサブメニュー）、SP は制御ドロワー（サブメニューはアコーディオン）",
+        "項目データ（メニュー定義・文言）は全て items prop で受ける。特定事業のメニューを部品側に焼き込まない（Cake.jp 既定は AdminLayout が持つ）",
+        "SP ドロワー開閉は open / onOpenChange で制御する（内部 state を持たない）",
+        "icon は ReactNode か描画コンテキスト（active / placement）で出し分ける関数を渡す"
+      ]
+    },
+    {
+      "name": "AdminHeader",
+      "path": "src/components/primitives/admin-header.tsx",
+      "rules": [
+        "管理画面向けの上端固定ヘッダーの汎用枠。左に SP ハンバーガー＋brand、右に actions slot",
+        "文言合成（『{shopName}管理』等）はしない。brand / actions を利用側が組み立てて渡す",
+        "onMenuClick 省略時はハンバーガー非表示"
+      ]
     }
   ],
   "ec": [
     {
       "name": "AdminLayout",
       "path": "src/components/ec/admin-layout.tsx",
+      "kind": "shell",
       "rules": [
-        "管理画面のレイアウトシェル"
+        "管理画面のレイアウトシェル。枠は primitives の AdminSideNav / AdminHeader を組み込む",
+        "Cake.jp 管理メニュー8項目＋サブメニュー・通知ベル・プロフィール・『{shopName}管理』を既定値として内蔵する（ドメイン特化層）",
+        "navItems で既定メニューを差し替え可、headerActions でヘッダー右アクションを差し替え可"
+      ]
+    },
+    {
+      "name": "MypageShell",
+      "path": "src/components/ec/mypage-shell.tsx",
+      "kind": "shell",
+      "variants": [],
+      "features": [
+        "sp-header-back",
+        "pc-logo-header",
+        "pc-breadcrumb",
+        "pc-2column-sidenav",
+        "sp-bottom-tab-bar"
+      ],
+      "rules": [
+        "マイページ配下の固有ページ（注文履歴 / ポイント / クーポン / 会員情報 / お届け先 / ブックマーク / 口コミ / 記念日 等）はこの shell で組む",
+        "本番の mypage_layout.ctp + menu.ctp 準拠。SP は Header(variant=back)+h1+コンテンツ+BottomTabBar、PC は Header(variant=logo)+Breadcrumb+2カラム（SideNav 256px + main）",
+        "サイドナビは ec/_mypage-menu-data の mypageMenuGroups を使用。activeMenu で現在ページを強調する",
+        "breadcrumbs 省略時は「ホーム > {ユーザー}さまのマイページ > {title}」を自動生成する",
+        "マイページトップ（Dashboard）はメインカラムを白背景で持たずセクションごとにカード化する別パターンなので、この shell を使わない"
       ]
     },
     {
@@ -721,10 +872,6 @@
       "name": "StatCard",
       "path": "src/components/ec/stat-card.tsx"
     },
-    {
-      "name": "Header",
-      "path": "src/components/primitives/header.tsx"
-    },
     {
       "name": "ProductListItem",
       "path": "src/components/ec/product-list-item.tsx",

package/contracts/composition.json

@@ -0,0 +1,135 @@
+{
+  "meta": {
+    "name": "Cake.jp Design System — Composition Contracts",
+    "version": "0.1.0",
+    "description": "ページ骨格・視覚階層・余白リズムの機械可読な正本。画面パターンを選んだ後の「実際の組み方」を規定する。ページの外枠（モバイル/デスクトップ/管理）、商品グリッドの列数、余白の4段リズム、Surface のネスト階層、テキスト階層、CTA の優先順位を構造化する。人間向けの解説は guidelines/composition/layout.md・guidelines/composition/hierarchy.md・guidelines/overview.md。",
+    "source": "guidelines/composition/layout.md, guidelines/composition/hierarchy.md, guidelines/overview.md, guidelines/components/button.md（CTA 密度ルール）を正本化",
+    "roleSeparation": "screen-patterns.json はページ種別（Standard Page / Focused Workspace / ResponsiveDialog / Dialog）を選ぶための契約。composition.json は選んだ後、その骨格をどう組むか（外枠構造・余白リズム・階層）の契約。前者=何を使うか、後者=どう並べるか。",
+    "componentNameNote": "本契約のコンポーネント名は src/index.ts のエクスポート実名。guidelines の一部散文にある解説用の別名（TopAppBar / BottomNavigation / BottomAction 等）は実装上それぞれ Header / BottomTabBar / StickyActionBar に対応する。CategoryScroll・CategoryShortcuts は横スクロール／ショートカット群の実装コンポーネント。"
+  },
+  "pageSkeletons": {
+    "description": "ページの外枠。上から順の構成要素と、外枠に課される構造ルールを規定する。手組みの独自シェルを作らず、実名コンポーネントで組む。",
+    "mobile": {
+      "requiredComponents": ["Header", "BottomTabBar"],
+      "optionalComponents": ["StickyActionBar", "CategoryScroll", "CategoryShortcuts"],
+      "implementation": "EcPageShell（primitives, kind:\"shell\"）がこの骨格の実装体。header に Header・bottomTab に BottomTabBar を渡す。bottomTab を渡すと main の下余白（pb-20 相当）をシェルが管理するので、ページ側で pb-20 を書かない。手組みの独自シェルを作らない。",
+      "structure": [
+        "ルート: div.flex.min-h-dvh.flex-col（縦フレックスの全高コンテナ。背景は bg-[var(--Surface-Primary)] を明示）",
+        "上部固定: Header（title / onBack。旧称 TopAppBar）",
+        "スクロール領域: main.flex-1.overflow-y-auto（本文セクション群。高さは flex-1 に委ね、ハードコードしない）",
+        "下部固定: BottomTabBar（グローバルナビ。旧称 BottomNavigation）または StickyActionBar（下部 CTA。旧称 BottomAction）"
+      ],
+      "rules": [
+        "全高レイアウトは min-h-dvh を使う（min-h-screen は不可。モバイルのアドレスバー分ずれる）",
+        "スクロール本文は flex-1 で伸縮させる。高さをハードコードしない",
+        "下部に StickyActionBar（固定 CTA）がある場合、main に pb-20 を付けて本文が隠れないようにする",
+        "モバイルの全ページは原則 Header を上端・BottomTabBar を下端に持つ（下部 CTA ページでは BottomTabBar の代わりに StickyActionBar）",
+        "横スクロールリストは flex.overflow-x-auto.gap-3.[-webkit-overflow-scrolling:touch]（カテゴリ横スクロールは CategoryScroll を使う）"
+      ]
+    },
+    "desktop": {
+      "requiredComponents": ["Container"],
+      "optionalComponents": ["Section", "SectionHeader"],
+      "implementation": "EcPageShell（primitives, kind:\"shell\"）が mobile と共通の実装体。PC では bottomTab（BottomTabBar）が消え下余白も外れる。左右 padding は Container・全幅背景帯は Section が持ち、シェルは持たない。手組みの独自シェルを作らない。",
+      "structure": [
+        "ルート: div.flex.min-h-screen（横フレックス。サイドバー＋本文）",
+        "ナビ: aside（サイドバーまたは上部ナビ。border-r border-[var(--Border-Medium-Emphasis)] で仕切る）",
+        "本文: main.flex-1（中央寄せ幅は Container、全幅背景帯は Section が持つ）"
+      ],
+      "rules": [
+        "デスクトップの全ページはサイドバーまたは上部ナビを必ず持つ",
+        "本文領域は flex-1 で伸縮させる",
+        "仕切り罫線は色を明示する（border-[var(--Border-Medium-Emphasis)]。幅だけの border は currentColor に化ける）",
+        "左右 padding は Container が所有し、背景は Section が所有する（余白の二重がけを防ぐ）"
+      ]
+    },
+    "admin": {
+      "requiredComponents": ["AdminLayout", "AdminSideNav", "AdminHeader"],
+      "optionalComponents": ["SectionHeader", "DataTable", "Section", "Container"],
+      "structure": [
+        "ルート: AdminLayout（管理画面の専用シェル。サイドナビ AdminSideNav・ヘッダー AdminHeader を内包）",
+        "サイドナビ・ヘッダーは AdminLayout 経由で組み込まれる（AdminSideNav / AdminHeader を直接手組みしない）",
+        "本文: AdminLayout の children に space-y-6 のコンテナを置き、ページタイトル（typo-heading-2xl）＋管理コンテンツを並べる"
+      ],
+      "rules": [
+        "管理画面のシェルは AdminLayout を使い、手組みしない",
+        "管理画面の表は DataTable を使う（生の table 禁止）",
+        "ページ直下のセクション間は space-y-6 相当（管理画面の縦リズム）"
+      ]
+    },
+    "funnel": {
+      "requiredComponents": ["FunnelShell", "Header"],
+      "optionalComponents": ["Container", "SectionHeader", "StickyActionBar", "FormField"],
+      "implementation": "FunnelShell（primitives, kind:\"shell\"）がこの骨格の実装体。EC 購入導線（カート→お届け先→支払い→確認 の一直線ファネル）に使う集中モード（Full Page）。集中ヘッダー（Header variant=back）は FunnelShell 経由で組み込む。steps / activeStep で進捗インジケータを出し、bottomAction に StickyActionBar 等を渡す。ステップ定義・文言・商品データはシェルに焼き込まず利用側が渡す。手組みの独自シェルを作らない。",
+      "structure": [
+        "ルート: FunnelShell（min-h-dvh flex flex-col の全高コンテナ。集中ヘッダー＋進捗インジケータ＋本体＋下部 CTA を内包）",
+        "上部固定: FunnelShell 内の Header（variant=back。左上=戻る／中央=タイトル）",
+        "進捗: FunnelShell 内の steps インジケータ（完了=Brand 色・現在=強調・未来=Low-Emphasis の点＋ラベル。SP はラベル省略）",
+        "本文: FunnelShell の children（左右 padding は Container・全幅背景帯は Section が持ち、シェルは持たない）",
+        "下部固定: FunnelShell の bottomAction（StickyActionBar 等の CTA）"
+      ],
+      "rules": [
+        "購入導線のシェルは FunnelShell を使い、手組みしない",
+        "グローバルナビ・BottomTabBar・パンくずを置かない（離脱を誘う導線を出さず購入に集中させる）",
+        "進捗を表示する（steps / activeStep でユーザーの現在地を示す）",
+        "下部 CTA（StickyActionBar）は bottomAction に渡す。本文の下余白はシェルが管理するのでページ側で pb を書かない",
+        "管理画面の複雑な集中編集は WorkspaceLayout を使う（EC 購入導線＝FunnelShell）"
+      ]
+    }
+  },
+  "productGrid": {
+    "description": "商品グリッドのブレークポイント別列数と gap。ProductCard を並べる際の標準。",
+    "breakpoints": [
+      { "viewport": "mobile", "width": "< 640px", "columns": 2, "gap": "gap-3", "tailwind": "grid-cols-2 gap-3" },
+      { "viewport": "tablet", "width": "640–1024px", "columns": 3, "gap": "gap-4", "tailwind": "sm:grid-cols-3 sm:gap-4" },
+      { "viewport": "desktop", "width": "> 1024px", "columns": 4, "gap": "gap-4", "tailwind": "lg:grid-cols-4" }
+    ],
+    "example": "grid grid-cols-2 gap-3 sm:grid-cols-3 sm:gap-4 lg:grid-cols-4",
+    "component": "ProductCard"
+  },
+  "spacingRhythm": {
+    "description": "一貫した余白が視覚階層を生む。4段のリズムを守る。space-y-* / gap-* いずれでも同値。",
+    "levels": [
+      { "level": "page-sections", "spacing": "space-y-8 / gap-8", "usage": "主要セクション間（ページ内の大きな塊の区切り）" },
+      { "level": "section-content", "spacing": "space-y-4 / gap-4", "usage": "セクション内の要素間" },
+      { "level": "related-items", "spacing": "space-y-2 / gap-2", "usage": "密接に関連する要素間" },
+      { "level": "inline", "spacing": "gap-1 / gap-1.5", "usage": "アイコン＋テキスト、ラベル＋値のインライン" }
+    ]
+  },
+  "cardHierarchy": {
+    "description": "Surface のネストは3層まで。入れ子で背景を一段ずつ落として階層を表現する。",
+    "layers": [
+      { "depth": 1, "token": "--Surface-Primary", "hex": "#FFFFFF", "usage": "メインのコンテンツカード" },
+      { "depth": 2, "token": "--Surface-Secondary", "hex": "#FBF9F8", "usage": "ネストしたセクション・交互行" },
+      { "depth": 3, "token": "--Surface-Tertiary", "hex": "#F4F2F1", "usage": "抑えたコンテナ・無効領域" }
+    ],
+    "rule": "ネストは3層まで。4層目以降は情報設計を見直す。背景は Surface トークンで明示（未指定で親を透かさない）。"
+  },
+  "textHierarchy": {
+    "description": "typo-* とテキスト強調トークンの組み合わせで階層を作るツリー。上ほど強い階層。トークン名は tokens.json の typography.* / semantic.text.* に対応。",
+    "tree": [
+      { "role": "page-title", "typo": "typo-heading-2xl", "color": "--Text-High-Emphasis" },
+      { "role": "section-heading", "typo": "typo-heading-lg", "color": "--Text-High-Emphasis" },
+      { "role": "body", "typo": "typo-body-md", "color": "--Text-High-Emphasis" },
+      { "role": "secondary-text", "typo": "typo-body-md", "color": "--Text-Medium-Emphasis" },
+      { "role": "meta", "typo": "typo-body-sm", "color": "--Text-Low-Emphasis", "usage": "メタ情報・タイムスタンプ" },
+      { "role": "smallest-label", "typo": "typo-label-xs", "color": "--Text-Low-Emphasis" }
+    ],
+    "accentNote": "価格などの最強調は typo-label-lg + --Text-Accent-Primary（オレンジ）。強調は色ではなく typo 系（heading/label）で表現し、font-bold を足さない。"
+  },
+  "ctaHierarchy": {
+    "description": "Button の variant 優先順位。1ビューポート内での CTA 密度を制御する。",
+    "priority": [
+      { "variant": "default", "role": "Primary CTA（オレンジ）", "note": "1ビューポートに1つまで（唯一の主 CTA）" },
+      { "variant": "secondary", "role": "Secondary action" },
+      { "variant": "tertiary", "role": "Tertiary action" },
+      { "variant": "ghost", "role": "Minimal action（メニュー・ツールバー内）" },
+      { "variant": "link", "role": "Inline link" }
+    ],
+    "rules": [
+      "default（オレンジ）の CTA は1ビューポートに1つまで。主アクションを1つに絞る",
+      "複数アクションを並べる時は default を tertiary / ghost と組み合わせる",
+      "モバイルの全幅下部 CTA は size=\"xl\" + w-full（StickyActionBar 内）"
+    ]
+  }
+}

package/contracts/rules.json

@@ -98,8 +98,8 @@
       "severity": "warning",
       "category": "color",
       "pattern": "#[0-9A-Fa-f]{6}",
-      "excludes": [".stories.", ".css", "shadow", "components/foundations/", "components/primitives/", "components/ec/"],
-      "message": "HEXハードコード禁止",
+      "excludes": [".stories.", ".css", "shadow", "fill=\"", "stroke=\"", "components/foundations/", "components/primitives/", "components/ec/"],
+      "message": "HEXハードコード禁止（例外: サードパーティブランドロゴの SVG fill/stroke — 例 Amazon #FF9900、Google 4色。出典コメント推奨）",
       "fix": "var(--Brand-Cake-Orange) 等セマンティックトークンを使う"
     },
     {
@@ -132,16 +132,45 @@
       "severity": "warning",
       "category": "spacing",
       "pattern": "p-\\[[0-9]*[13579]px\\]|m-\\[[0-9]*[13579]px\\]",
-      "message": "4pxグリッド外の余白値禁止",
-      "fix": "p-3（12px）等4の倍数のTailwindクラスを使う"
+      "message": "4pxグリッド外の余白値禁止（対象は px 任意値のみ。%・fr・vw 等のコンテナ比率はレイアウト都合で許可＝理由コメント必須）",
+      "fix": "p-3（12px）等4の倍数のTailwindクラスを使う。やむを得ない固有値は lint-scratch-allow コメントで理由を明記"
     },
     {
       "id": "R12",
       "severity": "warning",
       "category": "spacing",
       "pattern": "gap-\\[[0-9]*[13579]px\\]",
-      "message": "4pxグリッド外のgap値禁止",
-      "fix": "gap-1.5（6px）or gap-2（8px）"
+      "message": "4pxグリッド外のgap値禁止（対象は px 任意値のみ）",
+      "fix": "gap-1.5（6px）or gap-2（8px）。Figma 由来のやむを得ない固有値は lint-scratch-allow コメントで理由を明記"
+    },
+    {
+      "id": "R11b",
+      "severity": "warning",
+      "category": "spacing",
+      "target": "css",
+      "pattern": "(padding|padding-(top|bottom|left|right|inline|block)[a-z-]*)\\s*:\\s*[0-9.]+rem",
+      "message": "生CSSで padding を rem 直書き禁止（R11/R12 の Tailwind 任意値検査をすり抜ける経路）",
+      "fix": "spacing トークン（var(--spacing-*)）を使う。セクション縦余白は var(--Space-Section-*) を使う",
+      "note": "limitation: lint-scratch.sh の CSS スキャンは引数で指定したCSS、または引数なし実行時の DS 自身の src/**/*.css が対象。consumer リポジトリの CSS（実バグの front-site.css 等）には届かない＝consumer が DS lint を導入しない限り補助どまり。カスタムプロパティ定義（--Foo: 2rem）はトークン定義なので対象外"
+    },
+    {
+      "id": "R12b",
+      "severity": "warning",
+      "category": "spacing",
+      "target": "css",
+      "pattern": "gap\\s*:\\s*[0-9.]+rem",
+      "message": "生CSSで gap を rem 直書き禁止",
+      "fix": "spacing トークン（var(--spacing-*)）を使う",
+      "note": "limitation: R11b と同様、DS 自身の src/**/*.css のみが対象。var() 参照は除外"
+    },
+    {
+      "id": "R53",
+      "severity": "warning",
+      "category": "elevation",
+      "pattern": "shadow-(xl|2xl)\\b",
+      "excludes": [".stories."],
+      "message": "DS定義外シャドウ禁止（shadow-xl/2xl）",
+      "fix": "shadow-xs/sm/md/lg を使う（preset.css が --shadow-md/lg を DS 値に再定義済み）。オーバーレイは用途別トークン shadow-menu/tooltip/dialog/modal/overlay を推奨。フローティング UI の強い影（md/lg）は意図された正規仕様"
     },
     {
       "id": "R13",
@@ -200,6 +229,16 @@
       "message": "CardのpaddingをCard本体とchildで分離しない",
       "fix": "Card本体が p-4 で管理。全幅コンテンツは -mx-4 で突き破る"
     },
+    {
+      "id": "R18c",
+      "severity": "warning",
+      "category": "spacing",
+      "pattern": "<Card(?:\\s[^>]*)?>\\s*(?:\\{/\\*[\\s\\S]*?\\*/\\}\\s*)?<[^>]*className\\s*=\\s*[\"'`][^\"'`]*(^|\\s)(mt|mb|my|space-y)-",
+      "excludes": [".stories.", "components/foundations/", "components/primitives/", "components/ec/"],
+      "message": "Card直下の子に mt-/mb-/my-/space-y- を足さない（縦間隔はCard本体の flex-col gap-4=16px が一括管理。二重がけで間延びする）",
+      "fix": "余白クラスを外し Card の gap-4 に委ねる。丸アイコンは IconBadge を使う（外側marginを持たない）",
+      "note": "limitation: この正規表現はJSXソース文字列のみを見る。別CSS/module.cssファイルに書かれた margin（実バグの主因）は検出不可。あくまでJSXにTailwindで直書きした場合の補助で、本命は components.json の Card 縦間隔ルール（正典）と IconBadge 部品化"
+    },
     {
       "id": "R19",
       "severity": "error",
@@ -454,10 +493,10 @@
       "id": "AI7",
       "severity": "warning",
       "category": "ai-pattern",
-      "pattern": "rounded-md\\b|rounded-xl\\b|rounded-3xl\\b",
-      "excludes": [".stories.", "components/foundations/", "components/primitives/", "components/ec/"],
-      "message": "AI生成パターン: DS定義外の角丸禁止（rounded-md/xl/3xl）",
-      "fix": "DS定義の角丸のみ使用する"
+      "pattern": "rounded-(3xl|4xl)\\b|rounded-\\[[0-9]",
+      "excludes": [".stories."],
+      "message": "AI生成パターン: DS定義外の角丸禁止（rounded-3xl/4xl・任意値 rounded-[Npx]）",
+      "fix": "DSトークンスケールのみ使用: rounded-xs(2)/sm(6)/md(8)/lg(10)/xl(14)/2xl(18px)/full（--radius=10px 基準）。目安: メニュー・小型コントロール=md、ボタン・入力=lg（Button lg/xl は xl）、コンパクトカード=xl、標準カード・ダイアログ=2xl。例外は lint-scratch-allow コメントで理由を明記"
     },
     {
       "id": "R44",