@cakejp/design-system 0.12.0 → 0.14.0

package/contracts/components.json

@@ -1,14 +1,18 @@
 {
   "meta": {
     "name": "Cake.jp Design System — Component Contracts",
-    "version": "0.1.0",
+    "version": "0.14.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "kind": "kind:\"shell\" は複数ページで再利用されるレイアウト枠（AdminShell / WorkspaceShell / MypageShell 等）。無印は部品コンポーネント。固有ページを組むときは該当 shell から始める。src/components/pages/ 配下のストーリーは特定ページ専用・非配布のため contracts の対象外。",
+    "naming": "コンポーネント名は**用途ではなく機能**で付ける。用途名（QuantitySelector = カート数量）にすると、同じ機能を別の文脈で探した人が見つけられず二重実装が生まれる（実例: 用途名だったため NumberInput が別途作られ、意匠の違うステッパーが 2 つになった）。「〜Selector」「〜Picker」等の用途接尾辞を付ける前に、その部品が何をするものかで名前が付けられないかを先に検討する。既存名を機能名へ変える場合は deprecatedAliases に旧名を残す。",
+    "exportNaming": "name は原則そのまま @cakejp/design-system から import できる export 名。例外は機械可読に印を付ける — exported:false=name は実装ファイル/グループ名で import できない（実 export は subcomponents 側。例: CheckboxCard → CheckboxCardGroup / CheckboxCardItem）、exportedAs=別名で export される（例: FormField → CakeFormField）、deprecatedAliases=互換のため残す旧 export 名（新規利用禁止）。この対応は __tests__/contracts-export-integrity.test.ts が src/index.ts と突き合わせて固定し、bin/check-duplicates.mjs の照合対象もこの規約に従う。",
+    "formBinding": "react-hook-form との繋ぎ方。formBinding:\"register\"=ネイティブ form control に props/ref を透過するので {...register(\"name\")} を直接 spread できる（Input / Textarea）。formBinding:\"controller\"=Radix ベースで ref が <button> 等に着地する、または値が Date/File など非文字列のため Controller の field.value / field.onChange に繋ぐ。formBinding:\"layout\"=値を持たないレイアウト部品でバインド対象ではない（Field / Form / FormField / ProductOption）。formBinding:\"none\"=値は扱うが単一フィールドのバインド対象ではない自己完結フォーム・複合ウィジェット（DataTable / SearchBar / ReviewForm）。この切り分けは __tests__/react-hook-form-integration.test.tsx が実挙動で固定する（issue #151 / #152）。",
     "counts": {
-      "foundations": 50,
-      "primitives": 44,
+      "foundations": 51,
+      "primitives": 49,
       "ec": 24,
-      "total": 118
+      "total": 124,
+      "note": "counts は各ティアの実装ファイル数（scripts/check-drift.sh が src/components/<tier>/*.tsx と突き合わせる）。subcomponents / deprecatedAliases は含まない。"
     }
   },
   "foundations": [
@@ -16,13 +20,6 @@
       "name": "Accordion",
       "path": "src/components/foundations/accordion.tsx"
     },
-    {
-      "name": "AlertDialog",
-      "path": "src/components/foundations/alert-dialog.tsx",
-      "rules": [
-        "破壊的操作の確認に使用。削除ボタン押下後に必ず挟む"
-      ]
-    },
     {
       "name": "Alert",
       "path": "src/components/foundations/alert.tsx",
@@ -44,6 +41,18 @@
         "inline variant（inline-info/inline-caution/inline-warning）も同じ prop-based API に対応（#109）。フォーム内・セクション内の軽量な補足情報用。アイコンは20pxで自動選択"
       ]
     },
+    {
+      "name": "AlertDialog",
+      "path": "src/components/foundations/alert-dialog.tsx",
+      "sizes": [
+        "default",
+        "sm"
+      ],
+      "rules": [
+        "破壊的操作の確認に使用。削除ボタン押下後に必ず挟む",
+        "幅上限は default=480px / sm=320px。SP では画面端から上下左右 40px の余白を保つ（コンポーネントが持つので consumer 側で margin を足さない）"
+      ]
+    },
     {
       "name": "AspectRatio",
       "path": "src/components/foundations/aspect-ratio.tsx",
@@ -104,6 +113,10 @@
       ],
       "rules": [
         "<button>を直接使わない。必ずButtonコンポーネントを使う",
+        "高さは size='default'=44px（h-11） / xs=24px / sm=32px / lg=48px / xl=56px / hero=min 56px。default はフォーム入力コントロール（Input / SelectTrigger default / DatePicker trigger）と同じ 44px なので、入力行にボタンを並置しても揃う",
+        "⚠️ variant='secondary' はブランドアクセント意匠（Surface-Accent-Primary-Light地+Brand-Cake-Orange文字）。Material/Bootstrap/shadcn の secondary（グレー・控えめ）とは別物なので、他DSの感覚で選ばない",
+        "「戻る」「キャンセル」「閉じる」「スキップ」「あとで」等の後退・中立アクションは variant='tertiary'（Surface-Tertiary地+Text-High-Emphasis文字のニュートラルなグレー）を使う。主CTAの隣に置く2番目のボタンでも、役割が後退なら secondary ではなく tertiary",
+        "variant='secondary' を使うのは、主CTAと別方向の“前進”を促す副CTAのとき（例: 主='購入する' に対し 副='サンプルを見る'）",
         "variant='overlay'は画像・メディアの上に載せる操作ボタン専用（半透過白のSurface-Overlay-Light下地+shadow-md+backdrop-blur-sm）。ImageCarousel矢印と同系の意匠。size='icon'+className='rounded-full'で円形にできる"
       ]
     },
@@ -133,24 +146,37 @@
       "rules": [
         "paddingはCard本体のp-4で一括管理。全幅コンテンツは-mx-4で突き破る",
         "子要素の縦間隔はCard本体のflex-col gap-4(16px)で一括管理。直下の子にmargin-top/bottom/space-yを足さない（gapと二重がけになり間延びする）。丸アイコンはIconBadgeを使う（外側marginを持たない）",
-        "surface='default'(既定)はbg-card(Surface-Secondary)。Surface-Tertiary系(グレーSection)の地の上ではコントラスト不足になるためsurface='primary'(白=Surface-Primary)を使う"
+        "surface='default'(既定)は --card-surface(親から伝播したサーフェス文脈)→無ければ --card(Surface-Secondary)。surface='primary'は文脈に関係なく白(Surface-Primary)で固定する",
+        "Section background='subtle'|'accent-subtle' と、地がSurface-Secondaryのシェル（AdminShell / WorkspaceShell / FunnelShell）の配下では --card-surface が伝播するため、Card は surface 未指定のまま自動で白になる（surface='primary' の明示指定は従来通り有効で優先）",
+        "DSのSectionを使わない自前のグレー地では、親要素に className='[--card-surface:var(--Surface-Primary)]' を宣言すれば配下Cardが白になる（darkにも配慮するなら dark:[--card-surface:var(--Surface-Secondary)] を併記）。1枚だけ地に馴染ませたいときは className='bg-card' で上書きする"
       ]
     },
-    {
-      "name": "CheckboxCard",
-      "path": "src/components/foundations/checkbox-card.tsx"
-    },
-    {
-      "name": "CheckboxGroup",
-      "path": "src/components/foundations/checkbox-group.tsx"
-    },
     {
       "name": "Checkbox",
       "path": "src/components/foundations/checkbox.tsx",
+      "formBinding": "controller",
       "accessibility": [
         "必ずLabelと紐付ける"
       ]
     },
+    {
+      "name": "CheckboxCard",
+      "path": "src/components/foundations/checkbox-card.tsx",
+      "formBinding": "controller",
+      "exported": false,
+      "subcomponents": [
+        "CheckboxCardGroup",
+        "CheckboxCardItem"
+      ]
+    },
+    {
+      "name": "CheckboxGroup",
+      "path": "src/components/foundations/checkbox-group.tsx",
+      "formBinding": "controller",
+      "subcomponents": [
+        "CheckboxGroupItem"
+      ]
+    },
     {
       "name": "Collapsible",
       "path": "src/components/foundations/collapsible.tsx",
@@ -170,6 +196,7 @@
     {
       "name": "DataTable",
       "path": "src/components/foundations/data-table.tsx",
+      "formBinding": "none",
       "rules": [
         "管理画面のテーブルはui/tableでなくこちらを使う。ソート・選択行・アクションメニュー対応",
         "ActionCellのメニュー操作は行のonClickへ伝播しない（本体でstopPropagation済み）。行クリック選択との併用時も利用側ガードは不要"
@@ -202,7 +229,9 @@
     {
       "name": "Field",
       "path": "src/components/foundations/field.tsx",
+      "formBinding": "layout",
       "subcomponents": [
+        "FieldLabel",
         "FieldSet",
         "FieldLegend",
         "FieldGroup",
@@ -211,14 +240,41 @@
         "FieldSeparator"
       ],
       "rules": [
-        "フォーム全体の骨格を組む補助群。個々の入力欄は FormField を使う",
+        "フォーム全体の骨格を組む補助群。ラベル+入力+エラーが一体で済むなら FormField が最短。ラベル・入力・説明・エラーを個別に組むときは Field + FieldLabel を使う",
+        "Field は 1 フィールド分の箱（縦リズムの最小単位）。orientation='vertical'（既定）/'horizontal'/'responsive'。responsive は FieldGroup の @container/field-group を基準に狭い=縦・広い=横へ切り替わる",
         "余白は縦リズムに従う（FieldSet=gap-6 / FieldGroup=gap-4）。手で mt-/mb- を足さない",
         "見出しは FieldLegend、グループ横断の区切りは FieldSeparator を使う"
       ]
     },
+    {
+      "name": "FileInput",
+      "path": "src/components/foundations/file-input.tsx",
+      "formBinding": "controller",
+      "accessibility": [
+        "idをLabel/FormFieldのhtmlForと揃えて紐付ける",
+        "ネイティブ<input type='file'>をvisually-hiddenで内包しキーボード・SR操作可能",
+        "エラー表示はaria-describedbyでFieldErrorと接続"
+      ],
+      "rules": [
+        "<input type='file'>を直接書かない。汎用の添付（PDF/CSV/画像混在）はFileInputを使う",
+        "画像1枚の入力（プレビュー+形式/サイズ検証+値のバインド）はImageInputを使う",
+        "複数枚の画像を並べて管理するグリッドはImageUploaderを使う",
+        "複数選択時（multiple）は選択済みを「n件選択」で集約表示",
+        "maxSize（バイト）超過ファイルは受理せずonErrorを呼ぶ"
+      ]
+    },
     {
       "name": "Form",
       "path": "src/components/foundations/form.tsx",
+      "formBinding": "layout",
+      "subcomponents": [
+        "FormField",
+        "FormItem",
+        "FormLabel",
+        "FormControl",
+        "FormDescription",
+        "FormMessage"
+      ],
       "accessibility": [
         "aria-describedbyでエラーメッセージを紐付ける"
       ]
@@ -245,12 +301,16 @@
     {
       "name": "Input",
       "path": "src/components/foundations/input.tsx",
+      "formBinding": "register",
       "accessibility": [
         "必ずLabelと紐付ける"
       ],
       "rules": [
         "<input>を直接使わない。type='email'/'tel'を適切に指定する",
-        "文字数カウンタは showCount + maxLength で有効化（右下に {現在}/{max}、上限で Text-Caution）。制御/非制御両対応"
+        "高さは 44px（h-11）。フォーム入力コントロールと Button の既定（Input / SelectTrigger default / DatePicker trigger / Button size='default'）は 44px で統一されており、検索+絞り込みセレクト+ボタンのような並置でも揃う",
+        "44px は rules.json の touchTarget『Text input』の min を満たす値であり、DS の既定として採用している。recommended の 48px まで上げたい画面は consumer が className='h-12' で上書きする",
+        "文字数カウンタは showCount + maxLength で有効化（右下に {現在}/{max}、上限で Text-Caution）。制御/非制御両対応",
+        "非制御は react-hook-form の register() / reset() で ref 経由に値が入る実利用経路まで story とテストで検証する"
       ]
     },
     {
@@ -288,33 +348,29 @@
     {
       "name": "RadioGroup",
       "path": "src/components/foundations/radio-group.tsx",
+      "formBinding": "controller",
+      "subcomponents": [
+        "RadioGroupItem"
+      ],
       "variants": [
         "tile",
         "chip"
       ],
       "accessibility": [
-        "各RadioGroupItemにLabel必須"
+        "各RadioGroupItemにラベルテキスト必須。ラベルは children として RadioGroupItem の内側に書く（<RadioGroupItem value='x'>ラベル</RadioGroupItem>）。RadioGroupItem が内部で <label> 相当の関連付けまで行うため、外側に <Label htmlFor> を併置してはいけない（ラベル重複になる）"
+      ],
+      "props": [
+        "children: ラベル本文（必須。tile/chip 共通）",
+        "description?: ReactNode — ラベル下の補足説明（tile のみ）",
+        "expandedContent?: ReactNode — 選択時に展開する追加コンテンツ（tile のみ）"
       ],
       "rules": [
         "variant='tile'（既定）=ラジオ丸+ラベル+補足説明+展開コンテンツのタイル型",
+        "⚠️ タイルの枠（border/角丸/余白/選択状態の意匠）は RadioGroupItem 自身が描画する。consumer 側で <div className='border rounded-lg ...'> 等で囲むと枠が二重になる。囲まずにそのまま並べる",
+        "ラベルは children で渡す。<RadioGroupItem/> と <Label htmlFor> を兄弟に並べる書き方は誤り（枠の二重化＋ラベル重複を招く）",
         "variant='chip'=ラベルを内包したChoice Chip意匠の排他選択（タグ選択・絞り込み等）。ラジオ丸は描画せず、Chip本体と同じchipVariantsを再利用して選択状態をaccent意匠（静止=薄オレンジ/hover=ベタ塗り）で示す。description/expandedContentは持たない。Radixのキーボード操作・a11yは維持"
       ]
     },
-    {
-      "name": "FileInput",
-      "path": "src/components/foundations/file-input.tsx",
-      "accessibility": [
-        "idをLabel/FormFieldのhtmlForと揃えて紐付ける",
-        "ネイティブ<input type='file'>をvisually-hiddenで内包しキーボード・SR操作可能",
-        "エラー表示はaria-describedbyでFieldErrorと接続"
-      ],
-      "rules": [
-        "<input type='file'>を直接書かない。汎用の添付（PDF/CSV/画像混在）はFileInputを使う",
-        "プレビュー付きの画像管理（並び替え・複数サムネイル）はImageUploaderを使う",
-        "複数選択時（multiple）は選択済みを「n件選択」で集約表示",
-        "maxSize（バイト）超過ファイルは受理せずonErrorを呼ぶ"
-      ]
-    },
     {
       "name": "ResponsiveDialog",
       "path": "src/components/foundations/responsive-dialog.tsx",
@@ -329,8 +385,10 @@
     {
       "name": "Select",
       "path": "src/components/foundations/select.tsx",
+      "formBinding": "controller",
       "rules": [
-        "<select>HTMLネイティブを使わない"
+        "<select>HTMLネイティブを使わない",
+        "SelectTrigger の高さは size='default'=44px（h-11）で Input / DatePicker trigger / Button default と揃う。size='sm'=36px。高さは素のクラスで当てているため className='h-12' 等で上書きできる（data 属性セレクタではない）"
       ]
     },
     {
@@ -373,13 +431,22 @@
     },
     {
       "name": "Slider",
-      "path": "src/components/foundations/slider.tsx"
+      "path": "src/components/foundations/slider.tsx",
+      "formBinding": "controller"
     },
     {
-      "name": "Sonner",
-      "path": "src/components/foundations/sonner.tsx",
+      "name": "SocialIcon",
+      "path": "src/components/foundations/social-icon.tsx",
+      "props": [
+        "platform",
+        "tone?: brand | mono",
+        "size?: number"
+      ],
       "rules": [
-        "トースト内にアクションリンクを入れない。左ボーダーではなく背景色全体で状態を表現"
+        "SNS・外部サービスのロゴSVGは手書きせずSocialIconへ集約する",
+        "ブランド色はThird-Partyトークンを使う",
+        "ブランド色の地（LINEの緑・Appleの黒）に載せるときはtone=\"mono\"を指定する。brandのままだとアイコンが地と同色になって消える",
+        "サイズはsize（px）で指定する。classNameのsize-*はinline styleに負ける"
       ]
     },
     {
@@ -389,6 +456,7 @@
     {
       "name": "Switch",
       "path": "src/components/foundations/switch.tsx",
+      "formBinding": "controller",
       "accessibility": [
         "Label必須"
       ]
@@ -412,23 +480,35 @@
     {
       "name": "Textarea",
       "path": "src/components/foundations/textarea.tsx",
+      "formBinding": "register",
       "accessibility": [
         "Label必須"
       ],
       "rules": [
-        "文字数カウンタは showCount + maxLength で有効化（右下に {現在}/{max}、上限で Text-Caution）。制御/非制御両対応"
+        "文字数カウンタは showCount + maxLength で有効化（右下に {現在}/{max}、上限で Text-Caution）。制御/非制御両対応",
+        "非制御は react-hook-form の register() / reset() で ref 経由に値が入る実利用経路まで story とテストで検証する"
       ]
     },
     {
-      "name": "ToggleGroup",
-      "path": "src/components/foundations/toggle-group.tsx",
+      "name": "Toaster",
+      "path": "src/components/foundations/sonner.tsx",
       "rules": [
-        "水平パディングはコンポーネント内に入れない。親が管理する"
+        "トースト内にアクションリンクを入れない。左ボーダーではなく背景色全体で状態を表現",
+        "アプリのルートに <Toaster /> を1つ置き、表示は toast()（sonner の再 export）で呼ぶ"
       ]
     },
     {
       "name": "Toggle",
-      "path": "src/components/foundations/toggle.tsx"
+      "path": "src/components/foundations/toggle.tsx",
+      "formBinding": "controller"
+    },
+    {
+      "name": "ToggleGroup",
+      "path": "src/components/foundations/toggle-group.tsx",
+      "formBinding": "controller",
+      "rules": [
+        "水平パディングはコンポーネント内に入れない。親が管理する"
+      ]
     },
     {
       "name": "Tooltip",
@@ -440,35 +520,30 @@
   ],
   "primitives": [
     {
-      "name": "CoachMark",
-      "path": "src/components/primitives/coach-mark.tsx"
-    },
-    {
-      "name": "BannerCarousel",
-      "path": "src/components/primitives/banner-carousel.tsx"
-    },
-    {
-      "name": "ContentCarousel",
-      "path": "src/components/primitives/content-carousel.tsx",
-      "features": [
-        "scroll-snap",
-        "dots",
-        "arrows",
-        "autoPlay"
-      ],
+      "name": "AdminHeader",
+      "path": "src/components/primitives/admin-header.tsx",
       "rules": [
-        "ReactNode スライド対応（slides: ReactNode[]）。テキスト主体のヒーローバナー用",
-        "画像だけのバナーは ImageCarousel を使う",
-        "矢印・ドットの意匠は ImageCarousel と同一"
+        "管理画面向けの上端固定ヘッダーの汎用枠。左に SP ハンバーガー＋brand、右に actions slot",
+        "文言合成（『{shopName}管理』等）はしない。brand / actions を利用側が組み立てて渡す",
+        "onMenuClick 省略時はハンバーガー非表示"
       ]
     },
     {
-      "name": "StickyActionBar",
-      "path": "src/components/primitives/sticky-action-bar.tsx",
+      "name": "AdminSideNav",
+      "path": "src/components/primitives/admin-side-nav.tsx",
+      "category": "navigation",
       "rules": [
-        "モバイル固定フッターCTA"
+        "管理画面向けサイドナビの汎用枠。PC は左端固定アイコンレール（ホバーでサブメニュー）、SP は制御ドロワー（サブメニューはアコーディオン）",
+        "項目データ（メニュー定義・文言）は全て items prop で受ける。特定事業のメニューを部品側に焼き込まない（Cake.jp 既定は AdminShell が持つ）",
+        "PC レールのラベルは max-w-12 + typo-label-xs + 中央揃えを本体が所有する。5文字超も語のまとまりで折り返せるため、consumer が data-slot セレクタで内部上書きしない",
+        "SP ドロワー開閉は open / onOpenChange で制御する（内部 state を持たない）",
+        "icon は ReactNode か描画コンテキスト（active / placement）で出し分ける関数を渡す"
       ]
     },
+    {
+      "name": "BannerCarousel",
+      "path": "src/components/primitives/banner-carousel.tsx"
+    },
     {
       "name": "BottomTabBar",
       "path": "src/components/primitives/bottom-tab-bar.tsx",
@@ -483,13 +558,42 @@
         "テーブル選択時の一括操作バー。div手書き禁止"
       ]
     },
+    {
+      "name": "CategoryScroll",
+      "path": "src/components/primitives/category-scroll.tsx"
+    },
     {
       "name": "CategoryShortcuts",
       "path": "src/components/primitives/category-shortcuts.tsx"
     },
     {
-      "name": "CategoryScroll",
-      "path": "src/components/primitives/category-scroll.tsx"
+      "name": "ChatComposer",
+      "path": "src/components/primitives/chat-composer.tsx",
+      "formBinding": "controller",
+      "variants": [
+        "submitKey:enter",
+        "submitKey:mod-enter"
+      ],
+      "features": [
+        "attachments",
+        "maxFiles",
+        "maxSizeMb",
+        "maxLength",
+        "isSubmitting"
+      ],
+      "accessibility": [
+        "入力欄はvisually-hiddenのlabel（label prop）とhtmlForで紐付ける",
+        "送信ボタンのaria-labelは日本語（送信 / 送信中）",
+        "添付削除はChipのremovableで操作でき、キーボードで到達できる"
+      ],
+      "rules": [
+        "チャット・問い合わせ・返信の入力欄をTextarea+Buttonで手組みしない",
+        "既定はEnter送信・Shift+Enter改行。長文が主なsubmitKey='mod-enter'を使う",
+        "IME変換中のEnterでは送信しない（日本語入力の誤送信防止）",
+        "添付は内蔵のFileInputで選択し、選択済みはChipのremovableで表示・削除する",
+        "送信中はisSubmittingを立てる（送信ボタン無効化で二重送信を防ぐ）",
+        "<form>を内包しないため、フォーム内に置いても入れ子にならない"
+      ]
     },
     {
       "name": "Chip",
@@ -507,9 +611,62 @@
         "Tagと違い押せる・削除できる"
       ]
     },
+    {
+      "name": "CoachMark",
+      "path": "src/components/primitives/coach-mark.tsx"
+    },
+    {
+      "name": "Combobox",
+      "path": "src/components/primitives/combobox.tsx",
+      "formBinding": "controller",
+      "props": [
+        "options: ComboboxOption[]",
+        "value?: string",
+        "onValueChange?: (value: string) => void",
+        "id?: string",
+        "aria-invalid?: boolean",
+        "aria-describedby?: string"
+      ],
+      "rules": [
+        "検索が必要な単一選択に使う。少数候補はSelectまたはRadioGroupを使う",
+        "Popover + Command の検索・キーボード操作を内包する",
+        "制御コンポーネント。value と onValueChange を必ず渡す（非制御では選択が反映されない）",
+        "FormField と繋ぐときは id を FieldLabel の htmlFor と揃え、エラーは aria-invalid / aria-describedby で FieldError に接続する"
+      ]
+    },
+    {
+      "name": "Container",
+      "path": "src/components/primitives/container.tsx",
+      "variants": [
+        "size: page | narrow | wide | fluid",
+        "gutter: default | tight | none"
+      ],
+      "rules": [
+        "ページ最大幅と左右paddingの唯一の担い手。これを使う親(Section等)は自身で左右paddingを持たない（二重がけ防止）",
+        "縦余白・背景色は持たない（Sectionの責務）"
+      ]
+    },
+    {
+      "name": "ContentCarousel",
+      "path": "src/components/primitives/content-carousel.tsx",
+      "features": [
+        "scroll-snap",
+        "dots",
+        "arrows",
+        "autoPlay",
+        "itemsPerView"
+      ],
+      "rules": [
+        "ReactNode スライド対応（slides: ReactNode[]）。テキスト主体のヒーローバナー用",
+        "itemsPerView=2|3|4 で PC の複数カード表示に対応。SP は1枚表示を維持し、EC 商品以外の求人・記事カード等にも使う",
+        "画像だけのバナーは ImageCarousel を使う",
+        "矢印・ドットの意匠は ImageCarousel と同一"
+      ]
+    },
     {
       "name": "DatePicker",
       "path": "src/components/primitives/date-picker.tsx",
+      "formBinding": "controller",
       "subcomponents": [
         "DateTimePicker"
       ],
@@ -562,6 +719,8 @@
     {
       "name": "FormField",
       "path": "src/components/primitives/form-field.tsx",
+      "formBinding": "layout",
+      "exportedAs": "CakeFormField",
       "variants": {
         "descriptionPosition": [
           "above",
@@ -570,7 +729,40 @@
       },
       "rules": [
         "Label+Input+エラーメッセージをセットで管理",
-        "グリッド横並び時は descriptionPosition='below' で高さを揃える"
+        "グリッド横並び時は descriptionPosition='below' で高さを揃える",
+        "npm 経由では CakeFormField として import する（foundations/form.tsx の FormField と名前が衝突するため別名で export）"
+      ]
+    },
+    {
+      "name": "FunnelShell",
+      "path": "src/components/primitives/funnel-shell.tsx",
+      "kind": "shell",
+      "variants": [],
+      "rules": [
+        "EC 購入導線等のファネル用集中モード（Full Page）のシェル。集中ヘッダー＋進捗インジケータ（steps/activeStep）＋ステップ本体＋任意の bottomAction で構成。min-h-dvh flex flex-col の全高コンテナ",
+        "ヘッダーの基本形は中央ロゴ（logo prop → Header variant=logo-center）。ライブ本番の購入導線（cart_layout.ctp の cartHeader）準拠で離脱導線をロゴのみに絞る。狙いは戻り・離脱をしづらくして途中離脱を抑制すること（＝Header の logo-center は決済・申込ページ用の既定バリアント、本番 cartHeader もロゴクリックが /cart/・thanks に限定）。title+back（Header variant=back）は多段申込等でタイトル・戻るが要る場合の代替形。logo と title はどちらか一方を渡す（logo 優先）",
+        "あくまで枠。ステップ定義（名前・数）・文言・商品データを焼き込まない。steps / activeStep は利用側（ドメイン）が渡す",
+        "グローバルナビ・BottomTabBar・パンくずを持たない（構造的に置けない）。離脱を誘う導線を出さず購入に集中させる",
+        "bottomAction（StickyActionBar 等）を渡すと本文の下余白はシェルが管理する。ページ側で pb を書かない（付け忘れ／二重がけの構造的防止）",
+        "左右 padding は持たない（Container の責務）。管理画面の複雑な集中編集は WorkspaceShell を使う（EC 購入導線＝FunnelShell）",
+        "地がSurface-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き",
+        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
+      ]
+    },
+    {
+      "name": "Header",
+      "path": "src/components/primitives/header.tsx",
+      "variants": [
+        "logo",
+        "logo-center",
+        "back",
+        "back-search"
+      ],
+      "rules": [
+        "variant=\"logo\" の PC 行（@[768px]+）では searchSlot で navItems と actions の間に常設検索を inline 配置できる（flex-1 max-w-[400px] で伸縮）。navItems 無し＋searchSlot だけでも PC 行を描画する",
+        "SP 行に searchSlot は出さない。SP の常設検索は従来どおり bottomSlot で運用する",
+        "bottomSlot はヘッダー下段の全幅スロット（ProductDetailBar 等）。PC 常設検索の置き場に使わない（PC 二段ヘッダーになる）",
+        "actions（HeaderAction）はカート・マイページ等の本来リンクである導線には href を指定する。href 指定時は Button asChild + <a> で描画され、中クリック/新規タブ・リンクコピーが効く。onClick と併用可（両方付与される）"
       ]
     },
     {
@@ -587,6 +779,52 @@
       "name": "ImageGallery",
       "path": "src/components/primitives/image-gallery.tsx"
     },
+    {
+      "name": "ImageInput",
+      "path": "src/components/primitives/image-input.tsx",
+      "formBinding": "controller",
+      "variants": [
+        "aspect:square",
+        "aspect:landscape",
+        "size:sm",
+        "size:md",
+        "size:lg",
+        "objectFit:cover",
+        "objectFit:contain"
+      ],
+      "features": [
+        "preview",
+        "accept",
+        "maxSizeMb",
+        "clear",
+        "formBinding"
+      ],
+      "props": [
+        "value: File | string | null — Fileは新規選択・stringは保存済み画像のURL（必須）",
+        "onChange: (file: File | null) => void — 検証を通ったファイルのみ渡る（必須）",
+        "onBlur?: () => void — フォーカスが部品外へ抜けたとき（React Hook Form の touched 連携）",
+        "id? / name? — 内包 input に付与。FormField の htmlFor と揃える",
+        "accept?: string — 既定 'image/png,image/jpeg'",
+        "maxSizeMb?: number — 既定 2",
+        "error?: string — 外部（RHF等）のエラー。内蔵検証のエラーより優先して表示",
+        "onValidationError?: (error) => void — 検証エラーをモーダル等で出したい場合のみ"
+      ],
+      "accessibility": [
+        "検証エラーはFieldError（role='alert'）にインライン表示し、色だけで伝えない",
+        "内包inputにaria-invalid / aria-describedbyを付けてエラーと紐付ける",
+        "クリアボタンのaria-labelは日本語（画像を削除）",
+        "ファイル選択の口はFileInputを内包し、キーボード・SRで操作できる"
+      ],
+      "rules": [
+        "画像1枚の入力を<input type='file'>+<img>で手組みしない",
+        "value/onChangeの制御コンポーネント。保存済み画像はURL文字列をそのまま渡す",
+        "プレビューのobjectURLは内部でrevokeされる。consumer側でcreateObjectURLしない",
+        "検証エラーの既定はインライン表示。モーダルは強すぎるため既定にしない",
+        "表示サイズはaspect（square/landscape）×size（sm/md/lg）で指定し、任意のw-[Npx]を足さない",
+        "非同期検証（画像寸法チェック等）は持たない。onChange後にconsumer側で検証しerrorで戻す",
+        "汎用の添付はFileInput（foundations）、複数枚のグリッド管理はImageUploader（primitives）"
+      ]
+    },
     {
       "name": "ImageUploader",
       "path": "src/components/primitives/image-uploader.tsx",
@@ -594,6 +832,10 @@
         "upload",
         "delete",
         "grid"
+      ],
+      "rules": [
+        "複数枚の画像を並べて管理するグリッド。ファイル選択の口は持たず、追加はonAddでconsumerが実装する",
+        "画像1枚の入力（プレビュー+検証+値のバインド）はImageInputを使う"
       ]
     },
     {
@@ -612,8 +854,23 @@
       "path": "src/components/primitives/menu-drawer.tsx"
     },
     {
-      "name": "SubNav",
-      "path": "src/components/primitives/sub-nav.tsx"
+      "name": "MultiSelect",
+      "path": "src/components/primitives/multi-select.tsx",
+      "formBinding": "controller",
+      "props": [
+        "options: MultiSelectOption[]",
+        "value?: string[]",
+        "onValueChange?: (value: string[]) => void",
+        "id?: string",
+        "aria-invalid?: boolean",
+        "aria-describedby?: string"
+      ],
+      "rules": [
+        "3件以上を複数選択させる、または候補が多い場合に使う。少数候補はCheckboxGroupを使う",
+        "選択済みは削除可能なChipで表示する",
+        "制御コンポーネント。value と onValueChange を必ず渡す（非制御では選択が反映されない）",
+        "FormField と繋ぐときは id を FieldLabel の htmlFor と揃え、エラーは aria-invalid / aria-describedby で FieldError に接続する"
+      ]
     },
     {
       "name": "NotificationBadge",
@@ -647,17 +904,51 @@
       "path": "src/components/primitives/progress-steps.tsx"
     },
     {
-      "name": "QuantitySelector",
-      "path": "src/components/primitives/quantity-selector.tsx",
+      "name": "NumberInput",
+      "path": "src/components/primitives/number-input.tsx",
+      "formBinding": "controller",
+      "deprecatedAliases": [
+        "QuantitySelector"
+      ],
       "features": [
         "increment",
         "decrement",
-        "trash-icon"
+        "trash-icon",
+        "number-format"
+      ],
+      "sizes": [
+        "sm",
+        "md"
+      ],
+      "props": [
+        "value?: number",
+        "defaultValue?: number",
+        "onChange?: (value: number) => void",
+        "min?: number",
+        "max?: number",
+        "step?: number",
+        "size?: sm | md",
+        "editable?: boolean",
+        "error?: boolean",
+        "showTrash?: boolean",
+        "onDelete?: () => void",
+        "formatOptions?: Intl.NumberFormatOptions",
+        "locale?: string",
+        "inputId?: string"
+      ],
+      "rules": [
+        "DSの数値入力はすべてこれを使う。生の input type=\"number\" は使わない（カート数量・価格・在庫・ポイント等すべて）",
+        "意匠は Figma DS の Adjust 準拠。sm=コンパクト型（カート内）/ md=サークル型（商品詳細・管理画面）。この2つ以外の見た目を新規に作らない",
+        "カート数量では min=1 が標準（0 にしない — 削除は showTrash + onDelete で行う）",
+        "既定は min=1 / max=99 とカート数量向け。価格・在庫など汎用の数値入力では min / max / step を必ず明示する",
+        "桁区切り・通貨表示は formatOptions を渡す（編集中は素の数値になる）。JPY の全角￥は半角¥に正規化される",
+        "旧名 QuantitySelector は用途名だったため機能名に改名した。旧名は deprecated alias として残るが新規利用は不可"
       ]
     },
     {
       "name": "SearchBar",
-      "path": "src/components/primitives/search-bar.tsx"
+      "path": "src/components/primitives/search-bar.tsx",
+      "formBinding": "none"
     },
     {
       "name": "SearchPanel",
@@ -667,29 +958,23 @@
         "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"
+        "background: none | subtle | accent-subtle",
+        "scrim: none | dark | light | bottom-dark"
       ],
       "rules": [
         "全幅の縦リズム＋背景帯。左右paddingを持たない（左右余白はContainerが唯一の担い手）",
+        "背景画像上に文字を載せる場合は backgroundImage + scrim を使う。consumer が gradient overlay を ::before / ::after で手組みしない",
+        "scrim は Surface-Overlay-Light / Dark を使い、dark / light / bottom-dark の意匠を DS が所有する",
         "背景色はSection(全幅)が持ち中央寄せはContainerが持つ → 背景帯は画面端まで・コンテンツは中央寄せが二重がけなしで成立",
-        "縦余白はSP/PCペアで --Space-Section-* トークンを消費（rem直書き撲滅）"
+        "縦余白はSP/PCペアで --Space-Section-* トークンを消費（rem直書き撲滅）",
+        "background='subtle'|'accent-subtle'（色地）は配下に --card-surface: var(--Surface-Primary) を流す → 配下のCardはsurface未指定でも白になる（グレー地にカードが沈む事故を構造で防ぐ）。伝播はCSSカスタムプロパティのみでReact context不使用＝Server Componentのまま使える",
+        "background='none'は文脈をリセットしない。色地Sectionの内側に入れ子にしたnoneは背景が透過して外側の色地が見えるため、配下Cardも白のままが正しい",
+        "darkでは伝播値をSurface-Secondaryに据え置く（darkのSurface-Secondaryは半透明白＝色地に重なって一段明るく浮くのでそもそも沈まない。Surface-Primaryを強制すると地より暗い穴になりelevationが反転する）"
       ]
     },
     {
@@ -697,42 +982,13 @@
       "path": "src/components/primitives/section-header.tsx",
       "variants": [
         "size: 3xl | 2xl | xl | lg | md | sm",
+        "desktopSize: 5xl | 4xl",
         "align: start | center"
       ],
       "rules": [
         "タイトル+もっと見るボタンをCardTitle+Button手書き禁止。SectionHeaderを使う",
-        "中央寄せ大見出し（ランディング/ガイド系）は align=\"center\" を使う。eyebrow プロップに Badge 等を載せられる。手書きの中央寄せ見出し禁止"
-      ]
-    },
-    {
-      "name": "ShareButtons",
-      "path": "src/components/primitives/share-buttons.tsx"
-    },
-    {
-      "name": "SocialLoginButton",
-      "path": "src/components/primitives/social-login-button.tsx"
-    },
-    {
-      "name": "StatusCountTabs",
-      "path": "src/components/primitives/status-count-tabs.tsx",
-      "rules": [
-        "ToggleGroup+Badge手書き禁止。Chip count propを使う"
-      ]
-    },
-    {
-      "name": "Tag",
-      "path": "src/components/primitives/tag.tsx",
-      "rules": [
-        "表示専用。onClickを付けない（押せるものはChip）"
-      ]
-    },
-    {
-      "name": "SideNav",
-      "path": "src/components/primitives/side-nav.tsx",
-      "category": "navigation",
-      "rules": [
-        "ページ間遷移（別 URL へのナビゲーション）に使う。チェブロン付きで「別ページへ移動する」アフォーダンスを持つ",
-        "ページ内アンカー移動（href=\"#...\"）に流用しない → SectionNav を使う（見た目と挙動の不一致を防ぐ）"
+        "中央寄せ大見出し（ランディング/ガイド系）は align=\"center\" を使う。eyebrow プロップに Badge 等を載せられる。手書きの中央寄せ見出し禁止",
+        "3xl（28px）は通常ページの主見出しにも使う。4xl/5xlはLP・マーケティング系ヒーロー専用で、size=\"3xl\" に desktopSize=\"4xl\" または desktopSize=\"5xl\" を加えてPC時だけ拡大する"
       ]
     },
     {
@@ -754,10 +1010,30 @@
         "IntersectionObserver は内包しない。activeKey は利用側が制御する（AnchorNav の新設は却下、本コンポーネントの variant で担う）"
       ]
     },
+    {
+      "name": "ShareButtons",
+      "path": "src/components/primitives/share-buttons.tsx"
+    },
+    {
+      "name": "SideNav",
+      "path": "src/components/primitives/side-nav.tsx",
+      "category": "navigation",
+      "rules": [
+        "ページ間遷移（別 URL へのナビゲーション）に使う。チェブロン付きで「別ページへ移動する」アフォーダンスを持つ",
+        "ページ内アンカー移動（href=\"#...\"）に流用しない → SectionNav を使う（見た目と挙動の不一致を防ぐ）"
+      ]
+    },
+    {
+      "name": "SocialLoginButton",
+      "path": "src/components/primitives/social-login-button.tsx"
+    },
     {
       "name": "StandardPageShell",
       "path": "src/components/primitives/standard-page-shell.tsx",
       "kind": "shell",
+      "deprecatedAliases": [
+        "EcPageShell"
+      ],
       "variants": [],
       "rules": [
         "消費者向け標準ページ（Standard Page（View / Edit））の骨格。composition.json pageSkeletons（mobile / desktop）の実装体。min-h-dvh flex flex-col の全高コンテナに header / main / bottomTab / footer を積む",
@@ -770,72 +1046,65 @@
       ]
     },
     {
-      "name": "WorkspaceShell",
-      "path": "src/components/primitives/workspace-shell.tsx",
-      "kind": "shell",
-      "variants": [
-        "headerLayout=start",
-        "headerLayout=center"
-      ],
+      "name": "StatusCountTabs",
+      "path": "src/components/primitives/status-count-tabs.tsx",
       "rules": [
-        "Focused Workspace（全画面集中編集）のシェル。編集ヘッダー（Header variant=back）+ 任意のセクションナビ + 編集本体で構成",
-        "headerLayout（既定 start）: centerでヘッダーを左=戻る/中央=タイトル/右=primaryActionの3カラムgridに固定し、タイトルを真の中央に揃える（#112）。consumer 側の data-slot セレクタ上書きは不要",
-        "グローバルナビ・パンくずを持たない（構造的に置けない）。集中を妨げる導線は出さない",
-        "primaryActionはワークスペース全体の上位アクション（公開申請・承認依頼等）がある場合のみ。セクション／行単位の操作はコンテンツ内に置く",
-        "標準の編集はAdminShellのStandard Page（Edit）（旧Form Page）。複雑・複数情報をまたぐ集中編集・没入執筆のみWorkspaceShellを使う",
-        "sectionNavは編集内ナビ（アンカー／ステップ）のみ。PCでサイド表示・SPで非表示",
-        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
+        "ToggleGroup+Badge手書き禁止。Chip count propを使う",
+        "activeIndex は初期値だけでなく、マウント後の外部変更にも表示が追従する"
       ]
     },
     {
-      "name": "FunnelShell",
-      "path": "src/components/primitives/funnel-shell.tsx",
-      "kind": "shell",
-      "variants": [],
+      "name": "StickyActionBar",
+      "path": "src/components/primitives/sticky-action-bar.tsx",
       "rules": [
-        "EC 購入導線等のファネル用集中モード（Full Page）のシェル。集中ヘッダー＋進捗インジケータ（steps/activeStep）＋ステップ本体＋任意の bottomAction で構成。min-h-dvh flex flex-col の全高コンテナ",
-        "ヘッダーの基本形は中央ロゴ（logo prop → Header variant=logo-center）。ライブ本番の購入導線（cart_layout.ctp の cartHeader）準拠で離脱導線をロゴのみに絞る。狙いは戻り・離脱をしづらくして途中離脱を抑制すること（＝Header の logo-center は決済・申込ページ用の既定バリアント、本番 cartHeader もロゴクリックが /cart/・thanks に限定）。title+back（Header variant=back）は多段申込等でタイトル・戻るが要る場合の代替形。logo と title はどちらか一方を渡す（logo 優先）",
-        "あくまで枠。ステップ定義（名前・数）・文言・商品データを焼き込まない。steps / activeStep は利用側（ドメイン）が渡す",
-        "グローバルナビ・BottomTabBar・パンくずを持たない（構造的に置けない）。離脱を誘う導線を出さず購入に集中させる",
-        "bottomAction（StickyActionBar 等）を渡すと本文の下余白はシェルが管理する。ページ側で pb を書かない（付け忘れ／二重がけの構造的防止）",
-        "左右 padding は持たない（Container の責務）。管理画面の複雑な集中編集は WorkspaceShell を使う（EC 購入導線＝FunnelShell）",
-        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
+        "モバイル固定フッターCTA"
       ]
     },
     {
-      "name": "Header",
-      "path": "src/components/primitives/header.tsx",
-      "variants": [
-        "logo",
-        "logo-center",
-        "back",
-        "back-search"
-      ],
+      "name": "SubNav",
+      "path": "src/components/primitives/sub-nav.tsx"
+    },
+    {
+      "name": "Tag",
+      "path": "src/components/primitives/tag.tsx",
       "rules": [
-        "variant=\"logo\" の PC 行（@[768px]+）では searchSlot で navItems と actions の間に常設検索を inline 配置できる（flex-1 max-w-[400px] で伸縮）。navItems 無し＋searchSlot だけでも PC 行を描画する",
-        "SP 行に searchSlot は出さない。SP の常設検索は従来どおり bottomSlot で運用する",
-        "bottomSlot はヘッダー下段の全幅スロット（ProductDetailBar 等）。PC 常設検索の置き場に使わない（PC 二段ヘッダーになる）",
-        "actions（HeaderAction）はカート・マイページ等の本来リンクである導線には href を指定する。href 指定時は Button asChild + <a> で描画され、中クリック/新規タブ・リンクコピーが効く。onClick と併用可（両方付与される）"
+        "表示専用。onClickを付けない（押せるものはChip）"
       ]
     },
     {
-      "name": "AdminSideNav",
-      "path": "src/components/primitives/admin-side-nav.tsx",
-      "category": "navigation",
+      "name": "Timeline",
+      "path": "src/components/primitives/timeline.tsx",
+      "features": [
+        "vertical",
+        "custom-marker",
+        "connector"
+      ],
       "rules": [
-        "管理画面向けサイドナビの汎用枠。PC は左端固定アイコンレール（ホバーでサブメニュー）、SP は制御ドロワー（サブメニューはアコーディオン）",
-        "項目データ（メニュー定義・文言）は全て items prop で受ける。特定事業のメニューを部品側に焼き込まない（Cake.jp 既定は AdminShell が持つ）",
-        "SP ドロワー開閉は open / onOpenChange で制御する（内部 state を持たない）",
-        "icon は ReactNode か描画コンテキスト（active / placement）で出し分ける関数を渡す"
+        "本文付きの縦タイムラインに使う。現在位置を示す横型インジケータは ProgressSteps を使う",
+        "marker 省略時は連番。IconBadge 等の ReactNode を渡せる",
+        "コネクター線は Timeline が所有するため consumer が ::before / ::after で手組みしない"
       ]
     },
     {
-      "name": "AdminHeader",
-      "path": "src/components/primitives/admin-header.tsx",
+      "name": "WorkspaceShell",
+      "path": "src/components/primitives/workspace-shell.tsx",
+      "kind": "shell",
+      "deprecatedAliases": [
+        "WorkspaceLayout"
+      ],
+      "variants": [
+        "headerLayout=start",
+        "headerLayout=center"
+      ],
       "rules": [
-        "管理画面向けの上端固定ヘッダーの汎用枠。左に SP ハンバーガー＋brand、右に actions slot",
-        "文言合成（『{shopName}管理』等）はしない。brand / actions を利用側が組み立てて渡す",
-        "onMenuClick 省略時はハンバーガー非表示"
+        "Focused Workspace（全画面集中編集）のシェル。編集ヘッダー（Header variant=back）+ 任意のセクションナビ + 編集本体で構成",
+        "headerLayout（既定 start）: centerでヘッダーを左=戻る/中央=タイトル/右=primaryActionの3カラムgridに固定し、タイトルを真の中央に揃える（#112）。consumer 側の data-slot セレクタ上書きは不要",
+        "グローバルナビ・パンくずを持たない（構造的に置けない）。集中を妨げる導線は出さない",
+        "primaryActionはワークスペース全体の上位アクション（公開申請・承認依頼等）がある場合のみ。セクション／行単位の操作はコンテンツ内に置く",
+        "標準の編集はAdminShellのStandard Page（Edit）（旧Form Page）。複雑・複数情報をまたぐ集中編集・没入執筆のみWorkspaceShellを使う",
+        "sectionNavは編集内ナビ（アンカー／ステップ）のみ。PCでサイド表示・SPで非表示",
+        "地がSurface-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き",
+        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
       ]
     }
   ],
@@ -844,36 +1113,23 @@
       "name": "AdminShell",
       "path": "src/components/ec/admin-shell.tsx",
       "kind": "shell",
+      "deprecatedAliases": [
+        "AdminLayout"
+      ],
+      "subcomponents": [
+        "MissingComponent"
+      ],
       "rules": [
         "管理画面のレイアウトシェル。枠は primitives の AdminSideNav / AdminHeader を組み込む",
         "Cake.jp 管理メニュー8項目＋サブメニュー・通知ベル・プロフィール・『{shopName}管理』を既定値として同梱する（ec 層）",
         "navItems で既定メニューを差し替え可、headerActions でヘッダー右アクションを差し替え可",
+        "⚠️ PC の左サイドナビは 72px のアイコンレール（アイコン+短ラベル、サブメニューは hover ポップアップ）。バッジ+見出し+説明文のようなブランドブロックをレール上部に置く領域は無い。幅広サイドバー前提の画面はこの骨格では置き換えられない",
+        "他ブランドで使う場合、ヘッダー左のブランド表示は brand（ReactNode。既定=『{shopName}管理』の文字列）で差し替える。SP ドロワー上部の見出しは sidebarHeader（ReactNode。既定=shopName）で差し替える",
         "戻る導線（onBack）はパンくずの上に置く。onBack を渡すとシェルが main 内・パンくずより上に戻るボタンを描画する（backLabel で文言変更・既定『戻る』）。子コンテンツ内に戻るリンクを手書きしない",
         "タイトル直下の上位アクション（AI商品作成・PDF出力等）は h1 と同じ左端に左寄せする。右端フロートにしない",
         "既定値は props で差し替え可能で、骨格（Header + SideNav + Main）自体は他事業（ジョブボードの管理画面等）でも再利用できる",
-        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
-      ]
-    },
-    {
-      "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 で現在ページを強調する",
-        "既定値は props で差し替え可能（menuGroups / breadcrumbs / bottomNavItems / headerActions）で、骨格（ヘッダー＋2カラム＋BottomTabBar）自体は他事業（ジョブボードのマイページ等）でも再利用できる",
-        "breadcrumbs 省略時は「ホーム > {ユーザー}さまのマイページ > {title}」を自動生成する",
-        "マイページトップ（Dashboard）はメインカラムを白背景で持たずセクションごとにカード化する別パターンなので、この shell を使わない",
-        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
+        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化",
+        "地がSurface-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き"
       ]
     },
     {
@@ -909,6 +1165,28 @@
       "name": "DeliveryCalendar",
       "path": "src/components/ec/delivery-calendar.tsx"
     },
+    {
+      "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 で現在ページを強調する",
+        "既定値は props で差し替え可能（menuGroups / breadcrumbs / bottomNavItems / headerActions）で、骨格（ヘッダー＋2カラム＋BottomTabBar）自体は他事業（ジョブボードのマイページ等）でも再利用できる",
+        "breadcrumbs 省略時は「ホーム > {ユーザー}さまのマイページ > {title}」を自動生成する",
+        "マイページトップ（Dashboard）はメインカラムを白背景で持たずセクションごとにカード化する別パターンなので、この shell を使わない",
+        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
+      ]
+    },
     {
       "name": "OrderSection",
       "path": "src/components/ec/order-section.tsx",
@@ -923,8 +1201,11 @@
       "path": "src/components/ec/order-summary.tsx"
     },
     {
-      "name": "PaymentMethod",
-      "path": "src/components/ec/payment-method.tsx"
+      "name": "PaymentMethodDisplay",
+      "path": "src/components/ec/payment-method.tsx",
+      "subcomponents": [
+        "CreditCardIcon"
+      ]
     },
     {
       "name": "ProductCard",
@@ -967,9 +1248,26 @@
       "name": "ProductDetailSidebar",
       "path": "src/components/ec/product-detail-sidebar.tsx"
     },
+    {
+      "name": "ProductListItem",
+      "path": "src/components/ec/product-list-item.tsx",
+      "category": "display",
+      "rules": [
+        "カート/注文履歴/レビュー variant を持つ商品リスト行",
+        "captionは規格・仕様の短い自由記述（例: \"1kg / 冷蔵\"）。価格表示の直下にtypo-body-xs / Text-Medium-Emphasisで表示。tags（配送方法等のenum variant）とは別物",
+        "subtotal/subtotalLabel（既定\"小計\"）はcart variant専用。数量セレクタ行の右側（収まらなければ下に折り返し）に¥{カンマ区切り}で表示。BtoB/法人ECのロット購入等、商品ごとの単価×数量の内訳を明示したい場合に使う"
+      ]
+    },
     {
       "name": "ProductOption",
       "path": "src/components/ec/product-option.tsx",
+      "formBinding": "layout",
+      "subcomponents": [
+        "OptionQuantity",
+        "OptionSelect",
+        "OptionText",
+        "OptionImageUpload"
+      ],
       "variants": [
         "quantity",
         "select",
@@ -983,6 +1281,9 @@
     {
       "name": "RatingStars",
       "path": "src/components/ec/rating-stars.tsx",
+      "subcomponents": [
+        "SparkleIcon"
+      ],
       "features": [
         "sparkle-icon",
         "review-count"
@@ -1004,6 +1305,7 @@
     {
       "name": "ReviewForm",
       "path": "src/components/ec/review-form.tsx",
+      "formBinding": "none",
       "features": [
         "rating",
         "text",
@@ -1013,6 +1315,9 @@
     {
       "name": "ReviewSummary",
       "path": "src/components/ec/review-summary.tsx",
+      "subcomponents": [
+        "ReviewItem"
+      ],
       "features": [
         "average-score",
         "star-gauge"
@@ -1030,16 +1335,6 @@
     {
       "name": "StatCard",
       "path": "src/components/ec/stat-card.tsx"
-    },
-    {
-      "name": "ProductListItem",
-      "path": "src/components/ec/product-list-item.tsx",
-      "category": "display",
-      "rules": [
-        "カート/注文履歴/レビュー variant を持つ商品リスト行",
-        "captionは規格・仕様の短い自由記述（例: \"1kg / 冷蔵\"）。価格表示の直下にtypo-body-xs / Text-Medium-Emphasisで表示。tags（配送方法等のenum variant）とは別物",
-        "subtotal/subtotalLabel（既定\"小計\"）はcart variant専用。数量セレクタ行の右側（収まらなければ下に折り返し）に¥{カンマ区切り}で表示。BtoB/法人ECのロット購入等、商品ごとの単価×数量の内訳を明示したい場合に使う"
-      ]
     }
   ]
 }