@cakejp/design-system 0.12.0 → 0.13.0

package/contracts/components.json

@@ -4,11 +4,14 @@
     "version": "0.1.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "kind": "kind:\"shell\" は複数ページで再利用されるレイアウト枠（AdminShell / WorkspaceShell / MypageShell 等）。無印は部品コンポーネント。固有ページを組むときは該当 shell から始める。src/components/pages/ 配下のストーリーは特定ページ専用・非配布のため contracts の対象外。",
+    "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,
+      "primitives": 47,
       "ec": 24,
-      "total": 118
+      "total": 121,
+      "note": "counts は各ティアの実装ファイル数（scripts/check-drift.sh が src/components/<tier>/*.tsx と突き合わせる）。subcomponents / deprecatedAliases は含まない。"
     }
   },
   "foundations": [
@@ -104,6 +107,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,20 +140,33 @@
       "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"
+      "path": "src/components/foundations/checkbox-card.tsx",
+      "formBinding": "controller",
+      "exported": false,
+      "subcomponents": [
+        "CheckboxCardGroup",
+        "CheckboxCardItem"
+      ]
     },
     {
       "name": "CheckboxGroup",
-      "path": "src/components/foundations/checkbox-group.tsx"
+      "path": "src/components/foundations/checkbox-group.tsx",
+      "formBinding": "controller",
+      "subcomponents": [
+        "CheckboxGroupItem"
+      ]
     },
     {
       "name": "Checkbox",
       "path": "src/components/foundations/checkbox.tsx",
+      "formBinding": "controller",
       "accessibility": [
         "必ずLabelと紐付ける"
       ]
@@ -170,6 +190,7 @@
     {
       "name": "DataTable",
       "path": "src/components/foundations/data-table.tsx",
+      "formBinding": "none",
       "rules": [
         "管理画面のテーブルはui/tableでなくこちらを使う。ソート・選択行・アクションメニュー対応",
         "ActionCellのメニュー操作は行のonClickへ伝播しない（本体でstopPropagation済み）。行クリック選択との併用時も利用側ガードは不要"
@@ -202,7 +223,9 @@
     {
       "name": "Field",
       "path": "src/components/foundations/field.tsx",
+      "formBinding": "layout",
       "subcomponents": [
+        "FieldLabel",
         "FieldSet",
         "FieldLegend",
         "FieldGroup",
@@ -211,7 +234,8 @@
         "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 を使う"
       ]
@@ -219,6 +243,15 @@
     {
       "name": "Form",
       "path": "src/components/foundations/form.tsx",
+      "formBinding": "layout",
+      "subcomponents": [
+        "FormField",
+        "FormItem",
+        "FormLabel",
+        "FormControl",
+        "FormDescription",
+        "FormMessage"
+      ],
       "accessibility": [
         "aria-describedbyでエラーメッセージを紐付ける"
       ]
@@ -245,12 +278,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,21 +325,33 @@
     {
       "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",
+      "formBinding": "controller",
       "accessibility": [
         "idをLabel/FormFieldのhtmlForと揃えて紐付ける",
         "ネイティブ<input type='file'>をvisually-hiddenで内包しキーボード・SR操作可能",
@@ -310,7 +359,8 @@
       ],
       "rules": [
         "<input type='file'>を直接書かない。汎用の添付（PDF/CSV/画像混在）はFileInputを使う",
-        "プレビュー付きの画像管理（並び替え・複数サムネイル）はImageUploaderを使う",
+        "画像1枚の入力（プレビュー+形式/サイズ検証+値のバインド）はImageInputを使う",
+        "複数枚の画像を並べて管理するグリッドはImageUploaderを使う",
         "複数選択時（multiple）は選択済みを「n件選択」で集約表示",
         "maxSize（バイト）超過ファイルは受理せずonErrorを呼ぶ"
       ]
@@ -329,8 +379,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 +425,15 @@
     },
     {
       "name": "Slider",
-      "path": "src/components/foundations/slider.tsx"
+      "path": "src/components/foundations/slider.tsx",
+      "formBinding": "controller"
     },
     {
-      "name": "Sonner",
+      "name": "Toaster",
       "path": "src/components/foundations/sonner.tsx",
       "rules": [
-        "トースト内にアクションリンクを入れない。左ボーダーではなく背景色全体で状態を表現"
+        "トースト内にアクションリンクを入れない。左ボーダーではなく背景色全体で状態を表現",
+        "アプリのルートに <Toaster /> を1つ置き、表示は toast()（sonner の再 export）で呼ぶ"
       ]
     },
     {
@@ -389,6 +443,7 @@
     {
       "name": "Switch",
       "path": "src/components/foundations/switch.tsx",
+      "formBinding": "controller",
       "accessibility": [
         "Label必須"
       ]
@@ -412,23 +467,27 @@
     {
       "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",
+      "formBinding": "controller",
       "rules": [
         "水平パディングはコンポーネント内に入れない。親が管理する"
       ]
     },
     {
       "name": "Toggle",
-      "path": "src/components/foundations/toggle.tsx"
+      "path": "src/components/foundations/toggle.tsx",
+      "formBinding": "controller"
     },
     {
       "name": "Tooltip",
@@ -454,10 +513,12 @@
         "scroll-snap",
         "dots",
         "arrows",
-        "autoPlay"
+        "autoPlay",
+        "itemsPerView"
       ],
       "rules": [
         "ReactNode スライド対応（slides: ReactNode[]）。テキスト主体のヒーローバナー用",
+        "itemsPerView=2|3|4 で PC の複数カード表示に対応。SP は1枚表示を維持し、EC 商品以外の求人・記事カード等にも使う",
         "画像だけのバナーは ImageCarousel を使う",
         "矢印・ドットの意匠は ImageCarousel と同一"
       ]
@@ -491,6 +552,35 @@
       "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",
       "path": "src/components/primitives/chip.tsx",
@@ -510,6 +600,7 @@
     {
       "name": "DatePicker",
       "path": "src/components/primitives/date-picker.tsx",
+      "formBinding": "controller",
       "subcomponents": [
         "DateTimePicker"
       ],
@@ -562,6 +653,8 @@
     {
       "name": "FormField",
       "path": "src/components/primitives/form-field.tsx",
+      "formBinding": "layout",
+      "exportedAs": "CakeFormField",
       "variants": {
         "descriptionPosition": [
           "above",
@@ -570,7 +663,8 @@
       },
       "rules": [
         "Label+Input+エラーメッセージをセットで管理",
-        "グリッド横並び時は descriptionPosition='below' で高さを揃える"
+        "グリッド横並び時は descriptionPosition='below' で高さを揃える",
+        "npm 経由では CakeFormField として import する（foundations/form.tsx の FormField と名前が衝突するため別名で export）"
       ]
     },
     {
@@ -587,6 +681,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 +734,10 @@
         "upload",
         "delete",
         "grid"
+      ],
+      "rules": [
+        "複数枚の画像を並べて管理するグリッド。ファイル選択の口は持たず、追加はonAddでconsumerが実装する",
+        "画像1枚の入力（プレビュー+検証+値のバインド）はImageInputを使う"
       ]
     },
     {
@@ -646,9 +790,24 @@
       "name": "ProgressSteps",
       "path": "src/components/primitives/progress-steps.tsx"
     },
+    {
+      "name": "Timeline",
+      "path": "src/components/primitives/timeline.tsx",
+      "features": [
+        "vertical",
+        "custom-marker",
+        "connector"
+      ],
+      "rules": [
+        "本文付きの縦タイムラインに使う。現在位置を示す横型インジケータは ProgressSteps を使う",
+        "marker 省略時は連番。IconBadge 等の ReactNode を渡せる",
+        "コネクター線は Timeline が所有するため consumer が ::before / ::after で手組みしない"
+      ]
+    },
     {
       "name": "QuantitySelector",
       "path": "src/components/primitives/quantity-selector.tsx",
+      "formBinding": "controller",
       "features": [
         "increment",
         "decrement",
@@ -657,7 +816,8 @@
     },
     {
       "name": "SearchBar",
-      "path": "src/components/primitives/search-bar.tsx"
+      "path": "src/components/primitives/search-bar.tsx",
+      "formBinding": "none"
     },
     {
       "name": "SearchPanel",
@@ -684,12 +844,18 @@
       "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,11 +863,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 等を載せられる。手書きの中央寄せ見出し禁止"
+        "中央寄せ大見出し（ランディング/ガイド系）は align=\"center\" を使う。eyebrow プロップに Badge 等を載せられる。手書きの中央寄せ見出し禁止",
+        "3xl（28px）は通常ページの主見出しにも使う。4xl/5xlはLP・マーケティング系ヒーロー専用で、size=\"3xl\" に desktopSize=\"4xl\" または desktopSize=\"5xl\" を加えてPC時だけ拡大する"
       ]
     },
     {
@@ -716,7 +884,8 @@
       "name": "StatusCountTabs",
       "path": "src/components/primitives/status-count-tabs.tsx",
       "rules": [
-        "ToggleGroup+Badge手書き禁止。Chip count propを使う"
+        "ToggleGroup+Badge手書き禁止。Chip count propを使う",
+        "activeIndex は初期値だけでなく、マウント後の外部変更にも表示が追従する"
       ]
     },
     {
@@ -758,6 +927,9 @@
       "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 を積む",
@@ -773,6 +945,9 @@
       "name": "WorkspaceShell",
       "path": "src/components/primitives/workspace-shell.tsx",
       "kind": "shell",
+      "deprecatedAliases": [
+        "WorkspaceLayout"
+      ],
       "variants": [
         "headerLayout=start",
         "headerLayout=center"
@@ -784,6 +959,7 @@
         "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} で無効化"
       ]
     },
@@ -799,6 +975,7 @@
         "グローバルナビ・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} で無効化"
       ]
     },
@@ -825,6 +1002,7 @@
       "rules": [
         "管理画面向けサイドナビの汎用枠。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）で出し分ける関数を渡す"
       ]
@@ -844,14 +1022,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} で無効化"
+        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化",
+        "地がSurface-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き"
       ]
     },
     {
@@ -923,8 +1110,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",
@@ -970,6 +1160,13 @@
     {
       "name": "ProductOption",
       "path": "src/components/ec/product-option.tsx",
+      "formBinding": "layout",
+      "subcomponents": [
+        "OptionQuantity",
+        "OptionSelect",
+        "OptionText",
+        "OptionImageUpload"
+      ],
       "variants": [
         "quantity",
         "select",
@@ -983,6 +1180,9 @@
     {
       "name": "RatingStars",
       "path": "src/components/ec/rating-stars.tsx",
+      "subcomponents": [
+        "SparkleIcon"
+      ],
       "features": [
         "sparkle-icon",
         "review-count"
@@ -1004,6 +1204,7 @@
     {
       "name": "ReviewForm",
       "path": "src/components/ec/review-form.tsx",
+      "formBinding": "none",
       "features": [
         "rating",
         "text",
@@ -1013,6 +1214,9 @@
     {
       "name": "ReviewSummary",
       "path": "src/components/ec/review-summary.tsx",
+      "subcomponents": [
+        "ReviewItem"
+      ],
       "features": [
         "average-score",
         "star-gauge"

package/contracts/composition.json

@@ -122,7 +122,8 @@
       { "depth": 2, "token": "--Surface-Secondary", "hex": "#FBF9F8", "usage": "ネストしたセクション・交互行" },
       { "depth": 3, "token": "--Surface-Tertiary", "hex": "#F4F2F1", "usage": "抑えたコンテナ・無効領域" }
     ],
-    "rule": "ネストは3層まで。4層目以降は情報設計を見直す。背景は Surface トークンで明示（未指定で親を透かさない）。"
+    "rule": "ネストは3層まで。4層目以降は情報設計を見直す。背景は Surface トークンで明示（未指定で親を透かさない）。",
+    "surfaceContext": "色地 Section（background='subtle'|'accent-subtle'）と、地が Surface-Secondary のシェル（AdminShell / WorkspaceShell / FunnelShell）は配下に --card-surface: var(--Surface-Primary) を流すため、その中の Card は surface 未指定でも白（depth 1）になる。DS の Section を使わない自前の色地では、親要素に className='[--card-surface:var(--Surface-Primary)]' を宣言して同じ文脈を作る。dark は伝播値を Surface-Secondary に据え置く（半透明白が地に重なって浮くため、白を強制すると elevation が反転する）。"
   },
   "textHierarchy": {
     "description": "typo-* とテキスト強調トークンの組み合わせで階層を作るツリー。上ほど強い階層。トークン名は tokens.json の typography.* / semantic.text.* に対応。",
@@ -137,17 +138,19 @@
     "accentNote": "価格などの最強調は typo-label-lg + --Text-Accent-Primary（オレンジ）。強調は色ではなく typo 系（heading/label）で表現し、font-bold を足さない。"
   },
   "ctaHierarchy": {
-    "description": "Button の variant 優先順位。1ビューポート内での CTA 密度を制御する。",
+    "description": "Button の variant 優先順位。1ビューポート内での CTA 密度を制御する。⚠️ これは「前進アクションの強さ」の序列であり、画面に並べた2番目のボタンが自動的に secondary になるわけではない。戻る/キャンセル/閉じるのような後退・中立アクションは序列ではなく役割で選ぶ（→ tertiary）。選ぶ前に各項目の appearance（実際の意匠）を必ず確認すること。",
     "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" }
+      { "variant": "default", "role": "Primary CTA（前進・確定）", "appearance": "ブランドオレンジのベタ塗り", "note": "1ビューポートに1つまで（唯一の主 CTA）" },
+      { "variant": "secondary", "role": "Secondary action（前進系の副 CTA。例: 「サンプルを見る」「詳細を見る」）", "appearance": "⚠️ ブランドアクセント（Surface-Accent-Primary-Light 地 + Brand-Cake-Orange 文字）。Material / Bootstrap / shadcn の secondary（グレー・控えめ）とは別物", "note": "アクセント色が付くため、戻る・キャンセル・閉じる等の後退/中立アクションには使わない（→ tertiary）" },
+      { "variant": "tertiary", "role": "Tertiary action / 後退・中立アクション（戻る・キャンセル・閉じる・スキップ・あとで）", "appearance": "ニュートラルなグレー（Surface-Tertiary 地 + Text-High-Emphasis 文字）", "note": "他 DS の secondary に相当する見た目。主 CTA の隣に置く「戻る」「キャンセル」はこれを使う" },
+      { "variant": "ghost", "role": "Minimal action（メニュー・ツールバー内）", "appearance": "下地なし・hover で薄い下地" },
+      { "variant": "link", "role": "Inline link", "appearance": "テキストリンク意匠" }
     ],
     "rules": [
       "default（オレンジ）の CTA は1ビューポートに1つまで。主アクションを1つに絞る",
       "複数アクションを並べる時は default を tertiary / ghost と組み合わせる",
+      "「戻る」「キャンセル」「閉じる」「スキップ」「あとで」は tertiary（グレー）。secondary はアクセント色なので後退アクションに使わない",
+      "secondary を使うのは、主 CTA と別方向の“前進”を促す副 CTA のとき（例: 主=「購入する」に対し副=「サンプルを見る」）",
       "モバイルの全幅下部 CTA は size=\"xl\" + w-full（StickyActionBar 内）"
     ]
   }