@cakejp/design-system 0.11.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": 47,
-      "primitives": 42,
+      "foundations": 50,
+      "primitives": 47,
       "ec": 24,
-      "total": 113
+      "total": 121,
+      "note": "counts は各ティアの実装ファイル数（scripts/check-drift.sh が src/components/<tier>/*.tsx と突き合わせる）。subcomponents / deprecatedAliases は含まない。"
     }
   },
   "foundations": [
@@ -26,9 +29,22 @@
     {
       "name": "Alert",
       "path": "src/components/foundations/alert.tsx",
+      "subcomponents": [
+        "AlertTitle",
+        "AlertDescription"
+      ],
       "variants": [
-        "default",
-        "destructive"
+        "success",
+        "info",
+        "error",
+        "warning",
+        "inline-info",
+        "inline-caution",
+        "inline-warning"
+      ],
+      "rules": [
+        "bordered variant（success/info/error/warning）は title/description/icon/action の prop-based API に対応（旧 Banner 相当）",
+        "inline variant（inline-info/inline-caution/inline-warning）も同じ prop-based API に対応（#109）。フォーム内・セクション内の軽量な補足情報用。アイコンは20pxで自動選択"
       ]
     },
     {
@@ -75,7 +91,8 @@
         "ghost",
         "link",
         "inverse",
-        "ghost-inverse"
+        "ghost-inverse",
+        "overlay"
       ],
       "sizes": [
         "xs",
@@ -89,7 +106,12 @@
         "aria-label必須（アイコンのみの場合）"
       ],
       "rules": [
-        "<button>を直接使わない。必ずButtonコンポーネントを使う"
+        "<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'で円形にできる"
       ]
     },
     {
@@ -109,22 +131,42 @@
         "CardContent",
         "CardFooter"
       ],
+      "variants": {
+        "surface": [
+          "default",
+          "primary"
+        ]
+      },
       "rules": [
         "paddingはCard本体のp-4で一括管理。全幅コンテンツは-mx-4で突き破る",
-        "子要素の縦間隔はCard本体のflex-col gap-4(16px)で一括管理。直下の子にmargin-top/bottom/space-yを足さない（gapと二重がけになり間延びする）。丸アイコンはIconBadgeを使う（外側marginを持たない）"
+        "子要素の縦間隔はCard本体のflex-col gap-4(16px)で一括管理。直下の子にmargin-top/bottom/space-yを足さない（gapと二重がけになり間延びする）。丸アイコンはIconBadgeを使う（外側marginを持たない）",
+        "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と紐付ける"
       ]
@@ -148,6 +190,7 @@
     {
       "name": "DataTable",
       "path": "src/components/foundations/data-table.tsx",
+      "formBinding": "none",
       "rules": [
         "管理画面のテーブルはui/tableでなくこちらを使う。ソート・選択行・アクションメニュー対応",
         "ActionCellのメニュー操作は行のonClickへ伝播しない（本体でstopPropagation済み）。行クリック選択との併用時も利用側ガードは不要"
@@ -177,9 +220,38 @@
       "name": "DropdownMenu",
       "path": "src/components/foundations/dropdown-menu.tsx"
     },
+    {
+      "name": "Field",
+      "path": "src/components/foundations/field.tsx",
+      "formBinding": "layout",
+      "subcomponents": [
+        "FieldLabel",
+        "FieldSet",
+        "FieldLegend",
+        "FieldGroup",
+        "FieldDescription",
+        "FieldError",
+        "FieldSeparator"
+      ],
+      "rules": [
+        "フォーム全体の骨格を組む補助群。ラベル+入力+エラーが一体で済むなら 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": "Form",
       "path": "src/components/foundations/form.tsx",
+      "formBinding": "layout",
+      "subcomponents": [
+        "FormField",
+        "FormItem",
+        "FormLabel",
+        "FormControl",
+        "FormDescription",
+        "FormMessage"
+      ],
       "accessibility": [
         "aria-describedbyでエラーメッセージを紐付ける"
       ]
@@ -193,23 +265,29 @@
       "path": "src/components/foundations/icon-badge.tsx",
       "variants": [
         "md",
+        "ml",
         "lg"
       ],
       "rules": [
-        "丸アイコンバッジ（md=44px/lg=72px）。アイコンを淡いアクセント背景の円で囲む装飾要素",
+        "丸アイコンバッジ（md=44px/ml=48px/lg=72px）。アイコンを淡いアクセント背景の円で囲む装飾要素",
         "外側marginを持たない。縦間隔は親Cardのflex-col gap-4(16px)に委ねる（二重がけ防止）",
         "アイコン色はcurrentColor(--Object-Accent-Primary)を継承。中のアイコンにcolorを渡さない",
-        "アイコンサイズはバッジが固定(md=20px/lg=38px)。アイコン側にsizeを渡さない"
+        "アイコンサイズはバッジが固定(md=20px/ml=24px/lg=38px)。アイコン側にsizeを渡さない"
       ]
     },
     {
       "name": "Input",
       "path": "src/components/foundations/input.tsx",
+      "formBinding": "register",
       "accessibility": [
         "必ずLabelと紐付ける"
       ],
       "rules": [
-        "<input>を直接使わない。type='email'/'tel'を適切に指定する"
+        "<input>を直接使わない。type='email'/'tel'を適切に指定する",
+        "高さは 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 とテストで検証する"
       ]
     },
     {
@@ -247,8 +325,44 @@
     {
       "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操作可能",
+        "エラー表示はaria-describedbyでFieldErrorと接続"
+      ],
+      "rules": [
+        "<input type='file'>を直接書かない。汎用の添付（PDF/CSV/画像混在）はFileInputを使う",
+        "画像1枚の入力（プレビュー+形式/サイズ検証+値のバインド）はImageInputを使う",
+        "複数枚の画像を並べて管理するグリッドはImageUploaderを使う",
+        "複数選択時（multiple）は選択済みを「n件選択」で集約表示",
+        "maxSize（バイト）超過ファイルは受理せずonErrorを呼ぶ"
       ]
     },
     {
@@ -265,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 属性セレクタではない）"
       ]
     },
     {
@@ -293,15 +409,31 @@
         "アニメーションはpulseのみ許可"
       ]
     },
+    {
+      "name": "SkipLink",
+      "path": "src/components/foundations/skip-link.tsx",
+      "category": "navigation",
+      "accessibility": [
+        "WCAG 2.4.1（Bypass Blocks）対応。キーボード／SR ユーザーがヘッダーの反復リンクを飛ばして本文へ移動する",
+        "aria/文言は日本語（既定「コンテンツへ移動」）"
+      ],
+      "rules": [
+        "sr-only で常時視覚には出さず、フォーカス時のみ左上に可視化する（focus:not-sr-only）",
+        "スキップ先 <main id> は href（既定 #main-content）と一致させる",
+        "全シェル（StandardPageShell / FunnelShell / WorkspaceShell / AdminShell / MypageShell）が DOM 先頭に標準内蔵する。シェルを使う場合は個別に置かない（skipLink={false} で無効化）"
+      ]
+    },
     {
       "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）で呼ぶ"
       ]
     },
     {
@@ -311,6 +443,7 @@
     {
       "name": "Switch",
       "path": "src/components/foundations/switch.tsx",
+      "formBinding": "controller",
       "accessibility": [
         "Label必須"
       ]
@@ -334,20 +467,27 @@
     {
       "name": "Textarea",
       "path": "src/components/foundations/textarea.tsx",
+      "formBinding": "register",
       "accessibility": [
         "Label必須"
+      ],
+      "rules": [
+        "文字数カウンタは 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",
@@ -366,6 +506,23 @@
       "name": "BannerCarousel",
       "path": "src/components/primitives/banner-carousel.tsx"
     },
+    {
+      "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": "StickyActionBar",
       "path": "src/components/primitives/sticky-action-bar.tsx",
@@ -395,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",
@@ -411,6 +597,21 @@
         "Tagと違い押せる・削除できる"
       ]
     },
+    {
+      "name": "DatePicker",
+      "path": "src/components/primitives/date-picker.tsx",
+      "formBinding": "controller",
+      "subcomponents": [
+        "DateTimePicker"
+      ],
+      "rules": [
+        "input type='date' 禁止ルールの実装済みの正解形。Popover+Calendar を毎回手組みしない",
+        "trigger の選択値は M月D日（曜日）表記、カレンダーは日本語ロケール",
+        "選択範囲は min/max、個別不可日は disabledDates で指定する",
+        "DateTimePicker は JST 前提で Date をそのまま扱う（TZ 変換しない）",
+        "FormField の children に置き、id を htmlFor と揃えて label/エラーと接続する"
+      ]
+    },
     {
       "name": "EmptyState",
       "path": "src/components/primitives/empty-state.tsx",
@@ -421,8 +622,19 @@
     {
       "name": "ErrorState",
       "path": "src/components/primitives/error-state.tsx",
+      "variants": {
+        "kind": [
+          "error",
+          "notFound"
+        ]
+      },
+      "subcomponents": [
+        "NotFoundIllustration"
+      ],
       "rules": [
-        "色+アイコン+テキスト必須。リトライアクションを含める"
+        "kind='error'（既定）は色+アイコン+テキスト必須。リトライアクションを含める",
+        "kind='notFound' は 404 向け。イラスト・見出し・説明が既定で入るため action（トップへ戻る等）だけ渡せばよい",
+        "NotFoundIllustration は単体 export。consumer が独自レイアウトで使う場合に流用する"
       ]
     },
     {
@@ -441,6 +653,8 @@
     {
       "name": "FormField",
       "path": "src/components/primitives/form-field.tsx",
+      "formBinding": "layout",
+      "exportedAs": "CakeFormField",
       "variants": {
         "descriptionPosition": [
           "above",
@@ -449,7 +663,8 @@
       },
       "rules": [
         "Label+Input+エラーメッセージをセットで管理",
-        "グリッド横並び時は descriptionPosition='below' で高さを揃える"
+        "グリッド横並び時は descriptionPosition='below' で高さを揃える",
+        "npm 経由では CakeFormField として import する（foundations/form.tsx の FormField と名前が衝突するため別名で export）"
       ]
     },
     {
@@ -466,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",
@@ -473,6 +734,10 @@
         "upload",
         "delete",
         "grid"
+      ],
+      "rules": [
+        "複数枚の画像を並べて管理するグリッド。ファイル選択の口は持たず、追加はonAddでconsumerが実装する",
+        "画像1枚の入力（プレビュー+検証+値のバインド）はImageInputを使う"
       ]
     },
     {
@@ -525,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",
@@ -536,7 +816,8 @@
     },
     {
       "name": "SearchBar",
-      "path": "src/components/primitives/search-bar.tsx"
+      "path": "src/components/primitives/search-bar.tsx",
+      "formBinding": "none"
     },
     {
       "name": "SearchPanel",
@@ -563,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が反転する）"
       ]
     },
     {
@@ -576,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時だけ拡大する"
       ]
     },
     {
@@ -595,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 は初期値だけでなく、マウント後の外部変更にも表示が追従する"
       ]
     },
     {
@@ -618,18 +908,28 @@
       "name": "SectionNav",
       "path": "src/components/primitives/section-nav.tsx",
       "category": "navigation",
+      "variants": [
+        "vertical",
+        "horizontal"
+      ],
       "rules": [
         "ページ内セクション移動（アンカー／目次）専用。href=\"#section-id\" のページ内スクロールに使う",
         "ページ間遷移に使わない → SideNav を使う",
         "チェブロン・矢印を足さない（遷移アフォーダンスを持たせない。同一画面内の位置移動に見せる）",
         "WorkspaceShell の sectionNav にはこれを使う（SideNav を流用しない）",
-        "固有幅・背景・境界を持たない（w-full）。パネル化・幅決定はシェル／利用側の責務"
+        "固有幅・背景・境界を持たない（w-full）。パネル化・幅決定はシェル／利用側の責務",
+        "orientation=\"vertical\"（既定）は縦積み目次。orientation=\"horizontal\" は Tabs アンダーバー式の横並び（ガイド・FAQ 等の長い静的ページのページ内ジャンプ、overflow-x-auto 対応）",
+        "sticky は内蔵しない。horizontal を貼り付ける場合は利用側が className=\"sticky top-14 …\" を付与し、ジャンプ先セクションに scroll-mt-* を付ける",
+        "IntersectionObserver は内包しない。activeKey は利用側が制御する（AnchorNav の新設は却下、本コンポーネントの variant で担う）"
       ]
     },
     {
       "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 を積む",
@@ -637,20 +937,30 @@
         "あくまで枠。プロダクトのロゴ・タブ項目・ナビ項目・文言を焼き込まない。header / bottomTab は利用側（ec 層）が組み立てて渡す",
         "bottomTab を渡すと main の下余白（pb-20 相当）はシェルが管理する。ページ側で pb-20 を書かない（付け忘れ／二重がけの構造的防止）",
         "左右 padding は持たない（Container の責務）。中身は Section（全幅背景帯）＋ Container（中央寄せ・左右余白）で組む",
-        "管理画面は AdminShell、複数情報をまたぐ集中編集は WorkspaceShell、マイページ配下は MypageShell を使う"
+        "管理画面は AdminShell、複数情報をまたぐ集中編集は WorkspaceShell、マイページ配下は MypageShell を使う",
+        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content、SkipLink の飛び先と一致）。sr-only で視覚無影響。skipLink={false} で無効化。ページ側で手組みしない"
       ]
     },
     {
       "name": "WorkspaceShell",
       "path": "src/components/primitives/workspace-shell.tsx",
       "kind": "shell",
-      "variants": [],
+      "deprecatedAliases": [
+        "WorkspaceLayout"
+      ],
+      "variants": [
+        "headerLayout=start",
+        "headerLayout=center"
+      ],
       "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で非表示"
+        "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} で無効化"
       ]
     },
     {
@@ -664,12 +974,26 @@
         "あくまで枠。ステップ定義（名前・数）・文言・商品データを焼き込まない。steps / activeStep は利用側（ドメイン）が渡す",
         "グローバルナビ・BottomTabBar・パンくずを持たない（構造的に置けない）。離脱を誘う導線を出さず購入に集中させる",
         "bottomAction（StickyActionBar 等）を渡すと本文の下余白はシェルが管理する。ページ側で pb を書かない（付け忘れ／二重がけの構造的防止）",
-        "左右 padding は持たない（Container の責務）。管理画面の複雑な集中編集は WorkspaceShell を使う（EC 購入導線＝FunnelShell）"
+        "左右 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"
+      "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 と併用可（両方付与される）"
+      ]
     },
     {
       "name": "AdminSideNav",
@@ -678,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）で出し分ける関数を渡す"
       ]
@@ -697,13 +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）自体は他事業（ジョブボードの管理画面等）でも再利用できる"
+        "既定値は props で差し替え可能で、骨格（Header + SideNav + Main）自体は他事業（ジョブボードの管理画面等）でも再利用できる",
+        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化",
+        "地がSurface-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き"
       ]
     },
     {
@@ -724,7 +1059,8 @@
         "サイドナビは既定で ec/_mypage-menu-data の mypageMenuGroups を使用。activeMenu で現在ページを強調する",
         "既定値は props で差し替え可能（menuGroups / breadcrumbs / bottomNavItems / headerActions）で、骨格（ヘッダー＋2カラム＋BottomTabBar）自体は他事業（ジョブボードのマイページ等）でも再利用できる",
         "breadcrumbs 省略時は「ホーム > {ユーザー}さまのマイページ > {title}」を自動生成する",
-        "マイページトップ（Dashboard）はメインカラムを白背景で持たずセクションごとにカード化する別パターンなので、この shell を使わない"
+        "マイページトップ（Dashboard）はメインカラムを白背景で持たずセクションごとにカード化する別パターンなので、この shell を使わない",
+        "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
       ]
     },
     {
@@ -774,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",
@@ -788,6 +1127,9 @@
         "favorite",
         "discount-badge",
         "rating"
+      ],
+      "rules": [
+        "captionは規格・仕様の短い自由記述（例: \"1kg / 冷蔵\"）。価格表示の直下にtypo-body-xs / Text-Medium-Emphasisで表示。tags（配送方法等のenum variant）とは別物で代替不可"
       ]
     },
     {
@@ -818,6 +1160,13 @@
     {
       "name": "ProductOption",
       "path": "src/components/ec/product-option.tsx",
+      "formBinding": "layout",
+      "subcomponents": [
+        "OptionQuantity",
+        "OptionSelect",
+        "OptionText",
+        "OptionImageUpload"
+      ],
       "variants": [
         "quantity",
         "select",
@@ -831,6 +1180,9 @@
     {
       "name": "RatingStars",
       "path": "src/components/ec/rating-stars.tsx",
+      "subcomponents": [
+        "SparkleIcon"
+      ],
       "features": [
         "sparkle-icon",
         "review-count"
@@ -852,6 +1204,7 @@
     {
       "name": "ReviewForm",
       "path": "src/components/ec/review-form.tsx",
+      "formBinding": "none",
       "features": [
         "rating",
         "text",
@@ -861,6 +1214,9 @@
     {
       "name": "ReviewSummary",
       "path": "src/components/ec/review-summary.tsx",
+      "subcomponents": [
+        "ReviewItem"
+      ],
       "features": [
         "average-score",
         "star-gauge"
@@ -884,7 +1240,9 @@
       "path": "src/components/ec/product-list-item.tsx",
       "category": "display",
       "rules": [
-        "カート/注文履歴/レビュー variant を持つ商品リスト行"
+        "カート/注文履歴/レビュー variant を持つ商品リスト行",
+        "captionは規格・仕様の短い自由記述（例: \"1kg / 冷蔵\"）。価格表示の直下にtypo-body-xs / Text-Medium-Emphasisで表示。tags（配送方法等のenum variant）とは別物",
+        "subtotal/subtotalLabel（既定\"小計\"）はcart variant専用。数量セレクタ行の右側（収まらなければ下に折り返し）に¥{カンマ区切り}で表示。BtoB/法人ECのロット購入等、商品ごとの単価×数量の内訳を明示したい場合に使う"
       ]
     }
   ]