@cakejp/design-system 0.22.1 → 0.24.0

package/contracts/components.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "Cake.jp Design System — Component Contracts",
-    "version": "0.22.1",
+    "version": "0.24.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "kind": "kind:\"shell\" は複数ページで再利用されるレイアウト枠（AdminShell / WorkspaceShell / MypageShell 等）。無印は部品コンポーネント。固有ページを組むときは該当 shell から始める。src/components/pages/ 配下のストーリーは特定ページ専用・非配布のため contracts の対象外。",
     "naming": "コンポーネント名は**用途ではなく機能**で付ける。用途名（QuantitySelector = カート数量）にすると、同じ機能を別の文脈で探した人が見つけられず二重実装が生まれる（実例: 用途名だったため NumberInput が別途作られ、意匠の違うステッパーが 2 つになった）。「〜Selector」「〜Picker」等の用途接尾辞を付ける前に、その部品が何をするものかで名前が付けられないかを先に検討する。既存名を機能名へ変える場合は deprecatedAliases に旧名を残す。",
@@ -46,7 +46,11 @@
       ],
       "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で自動選択"
+        "inline variant（inline-info/inline-caution/inline-warning）も同じ prop-based API に対応（#109）。フォーム内・セクション内の軽量な補足情報用。アイコンは20pxで自動選択",
+        "読み上げの強さは variant で既定が決まる。error / warning / inline-caution / inline-warning は role=\"alert\"（即時に割り込む）、success / info / inline-info は role=\"status\"（遮らない）。live=\"alert\" | \"status\" | \"off\" で変えられ（off は role なし）、role を直接渡せばそれが最優先。画面表示時から出ている静的な補足に assertive な alert を使わない"
+      ],
+      "props": [
+        "live?: \"alert\" | \"status\" | \"off\" — 読み上げの強さ。未指定は variant の既定（error / warning 系は alert、success / info / inline-info は status）"
       ]
     },
     {
@@ -60,6 +64,10 @@
         "破壊的操作の確認に使用。削除ボタン押下後に必ず挟む",
         "幅上限は default=480px / sm=320px。SP では画面端から上下左右 40px の余白を保つ（コンポーネントが持つので consumer 側で margin を足さない）",
         "AlertDialogContent の size（default / sm）は DialogContent の size（sm / md / lg / xl）とは別物。値も意味も異なる（AlertDialog は確認文面向けの 2 段で、広い段は無い）。広い幅が要る入力・表示は AlertDialog ではなく Dialog / ResponsiveDialog にする"
+      ],
+      "accessibility": [
+        "閉じると、その回に開く直前にフォーカスがあった要素（opener）へフォーカスを戻す。Trigger を使わず state で開いた（一覧の行のボタンから開く等）ときも body へ落ちない。opener が DOM から消えている・disabled・inert のときは Radix 既定（Trigger へ戻す）に任せる。止めたいときは onCloseAutoFocus で event.preventDefault() する（consumer の指定が先に呼ばれる）",
+        "日本語入力の変換中（isComposing / keyCode 229）の Esc では閉じない（変換の取り消しで入力中の内容を失わないため）。consumer の onEscapeKeyDown は先に呼ばれる。変換していない Esc は従来どおり閉じる"
       ]
     },
     {
@@ -147,7 +155,7 @@
         "高さは size='default'=44px（h-11） / xs=24px / sm=32px / lg=48px / xl=56px / hero=min 56px。default はフォーム入力コントロール（Input / SelectTrigger default / DatePicker trigger）と同じ 44px なので、入力行にボタンを並置しても揃う",
         "アイコンのみは icon-xs=24px / icon-sm=32px / icon=36px / icon-lg=40px / icon-xl=44px。入力コントロール（Input / SearchBar / SelectTrigger）の横に並べるときは icon-xl を使う（他は高さが揃わず、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='tertiary'（Surface-Neutral-Tertiary地+Text-High-Emphasis文字のニュートラルなグレー）を使う。主CTAの隣に置く2番目のボタンでも、役割が後退なら secondary ではなく tertiary",
         "variant='secondary' を使うのは、主CTAと別方向の“前進”を促す副CTAのとき（例: 主='購入する' に対し 副='サンプルを見る'）",
         "variant='outline' は白地（Surface-Primary）+ 1px の黒系の枠（Border-High-Emphasis）+ Text-High-Emphasis 文字で、ブランド色を使わない準主役の前進アクション。「一覧を見る」のような移動ボタン、一覧・カードで1件ごとに繰り返す操作（商品カードの「カートに追加」等）、ブックマーク等の保存トグルのボタン本体の代わりに使う。hover / active は ghost と同じ薄い下地（Hover-Text-Button / Active-Text-Button）。ブランド色を使ってよい場所は contracts/composition.json の brandColorUsage（正本）",
         "variant='link' は補助リンク（「もっと見る」「利用規約を見る」等）の意匠で、ブランド色を使わない。Text-Medium-Emphasis + 常時下線（hover で Text-High-Emphasis）。disabled は Text-Disable",
@@ -189,9 +197,9 @@
       "rules": [
         "paddingはCard本体のp-4で一括管理。全幅コンテンツは-mx-4で突き破る",
         "子要素の縦間隔は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' で上書きする"
+        "surface='default'(既定)は --card-surface(親から伝播したサーフェス文脈)→無ければ --card(Surface-Secondary。light はベージュ)。surface='primary'は文脈に関係なく白(Surface-Primary)で固定する",
+        "Section background='subtle'|'accent-subtle' と、地がSurface-Neutral-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' で上書きする"
       ]
     },
     {
@@ -312,6 +320,7 @@
       "rules": [
         "管理画面のテーブルはui/tableでなくこちらを使う。ソート・選択行・アクションメニュー対応",
         "ActionCellのメニュー操作は行のonClickへ伝播しない（本体でstopPropagation済み）。行クリック選択との併用時も利用側ガードは不要",
+        "DataTableRow の onClick は、セル内の操作（Select の選択肢・入力欄・リンク・ボタン・Portal 先のポップアップ）から来たクリックでは呼ばれない。onKeyDown も Enter / Space はセル内の操作要素から来たものを渡さない（Tab・矢印は素通し）。セルの td に data-table-ignore-row-click を付けるとそのセル内の操作も行へ伝えない。利用側で target を見て弾く必要は無い",
         "見出し文字を出さない列（選択・操作・並び替えハンドル）は DataTableHead の srLabel で読み上げ用ラベルを付ける。空の <th> は列の意味が支援技術に伝わらない（axe: empty-table-header）",
         "DataTableLinkCell は linkComponent でリンク実装を差し替えられる（next/link 等）。未指定なら素の <a>。external:true のリンクは framework のリンク部品へ通す意味が無いため常に素の <a target=_blank> にフォールバックする（#236）",
         "DataTableLinkCell は Server Component のまま使える。linkComponent を渡すためだけに、Next.js App Router の呼び出し側を \"use client\" にする必要はない（#264）",
@@ -349,6 +358,11 @@
         "div.fixed.inset-0で自作しない。ESC・Tab・背景スクロールを自動処理",
         "幅は DialogContent の size で選ぶ（sm 400px / md 512px / lg 640px / xl 800px。sm 以上の画面で効く）。SP は段に関係なく画面端から 16px を残して収まる。size 未指定は従来の幅（sm:max-w-lg）のままで、preset が --container-lg を 960px に再定義しているため実幅は 960px（512px ではない）。幅を決めたい画面は size を明示する。段に無い幅のために className で max-w を直書きしない（どうしても要るときだけ sm:max-w-[…] で上書き。size より className が勝つ）。名前付きの max-w-md / max-w-lg / max-w-xl は preset が --container-* を再定義して Tailwind 既定と別の値になるので使わない（px の任意値で書く）",
         "DialogContent の size（sm / md / lg / xl）は AlertDialogContent の size（default / sm）とは別物。値も意味も異なる"
+      ],
+      "accessibility": [
+        "閉じると、その回に開く直前にフォーカスがあった要素（opener）へフォーカスを戻す。Trigger を使わず state で開いた（一覧の行のボタンから開く等）ときも body へ落ちない。opener が DOM から消えている・disabled・inert のときは Radix 既定（Trigger へ戻す）に任せる。止めたいときは onCloseAutoFocus で event.preventDefault() する（consumer の指定が先に呼ばれる）",
+        "DialogContent は開いたとき中へ自動フォーカスしない（Radix の既定を止めている）。consumer が onOpenAutoFocus を渡すと、この既定は外れて渡した関数に任される（event.preventDefault() しなければ Radix 既定どおり中の最初のフォーカス可能要素へ移る）。開いたとき特定の入力欄へ移したい画面は onOpenAutoFocus でその要素を focus() し、event.preventDefault() する",
+        "日本語入力の変換中（isComposing / keyCode 229）の Esc では閉じない（変換の取り消しで入力中の内容を失わないため）。consumer の onEscapeKeyDown は先に呼ばれる。変換していない Esc は従来どおり閉じる"
       ]
     },
     {
@@ -356,6 +370,10 @@
       "path": "src/components/foundations/drawer.tsx",
       "rules": [
         "SP 専用のボトムシート（スワイプで閉じるクイックビュー等）。PC 幅でも全幅ボトムシートのまま開き間延びするため、PC を含む画面ではResponsiveDialog（768px 以上で中央 Dialog に自動切替）を使う"
+      ],
+      "accessibility": [
+        "閉じると、その回に開く直前にフォーカスがあった要素（opener）へフォーカスを戻す。Trigger を使わず state で開いた（一覧の行のボタンから開く等）ときも body へ落ちない。opener が DOM から消えている・disabled・inert のときは Radix 既定に任せる。止めたいときは onCloseAutoFocus で event.preventDefault() する（consumer の指定が先に呼ばれる）",
+        "日本語入力の変換中（isComposing / keyCode 229）の Esc では閉じない（変換の取り消しで入力中の内容を失わないため）。consumer の onEscapeKeyDown は先に呼ばれる。変換していない Esc は従来どおり閉じる"
       ]
     },
     {
@@ -383,7 +401,12 @@
         "フォーム全体の骨格を組む補助群。ラベル+入力+エラーが一体で済むなら FormField が最短。ラベル・入力・説明・エラーを個別に組むときは Field + FieldLabel を使う",
         "Field は 1 フィールド分の箱（縦リズムの最小単位）。orientation='vertical'（既定）/'horizontal'/'responsive'。responsive は FieldGroup の @container/field-group を基準に狭い=縦・広い=横へ切り替わる",
         "余白は縦リズムに従う（FieldSet=gap-6 / FieldGroup=gap-4）。手で mt-/mb- を足さない",
-        "見出しは FieldLegend、グループ横断の区切りは FieldSeparator を使う"
+        "見出しは FieldLegend、グループ横断の区切りは FieldSeparator を使う",
+        "<legend> は fieldset の枠側に描かれ flex の並びに入らないため、FieldSet の gap は legend の直下に効かない（既定では 0px）。legend の下を空けたいときは mb- を手で足さず FieldSet の gap を指定する（子の間隔と legend の下が同じ段になる）。詰めた並びは gap=\"sm\" + FieldLegend size=\"sm\""
+      ],
+      "props": [
+        "FieldSet: gap?: sm | md | lg — 子の間隔（opt-in。8 / 16 / 24px）。指定すると FieldLegend の下にも同じ間隔を空ける。未指定は従来どおり gap-6 で legend の直下は 0px",
+        "FieldLegend: size?: md | sm — md（既定）= typo-label-lg + Text-High-Emphasis / sm = typo-label-md + Text-Medium-Emphasis（絞り込みの選択肢グループ等の小見出し）"
       ]
     },
     {
@@ -495,12 +518,16 @@
       ],
       "rules": [
         "中身の最大幅は Radix の available-width（画面内に使える幅）まで。長い項目や className で渡した広い幅でも、幅 390px の画面で右へはみ出さない（収まる幅・既定幅には効かない）"
+      ],
+      "accessibility": [
+        "日本語入力の変換中（isComposing / keyCode 229）の Esc では閉じない（変換の取り消しで入力中の内容を失わないため。Combobox / MultiSelect の検索欄にも効く）。consumer の onEscapeKeyDown は先に呼ばれる。変換していない Esc は従来どおり閉じる"
       ]
     },
     {
       "name": "Progress",
       "path": "src/components/foundations/progress.tsx",
       "accessibility": [
+        "value（0〜max。max 未指定は 100。範囲外は丸める。帯の長さは value / max の割合）は aria-valuenow と data-state（loading / complete）に反映され、読み上げで進み具合が伝わる。value 未指定・null・NaN は不確定（indeterminate）で aria-valuenow が付かない。用途名は aria-label / aria-labelledby で渡す（未指定は「進捗」）",
         "forced-colors（Windows のハイコントラスト）では進んだ部分を Highlight、全体の範囲を CanvasText の輪郭線（outline。レイアウトに影響しない）で示す。通常表示は変わらない"
       ]
     },
@@ -517,7 +544,9 @@
       ],
       "accessibility": [
         "各RadioGroupItemにラベルテキスト必須。ラベルは children として RadioGroupItem の内側に書く（<RadioGroupItem value='x'>ラベル</RadioGroupItem>）。RadioGroupItem が内部で <label> 相当の関連付けまで行うため、外側に <Label htmlFor> を併置してはいけない（ラベル重複になる）",
-        "variant=\"chip\" の選択中は、forced-colors（Windows のハイコントラスト）では Highlight の地 + HighlightText で示す（Chip の selected と同じ）。通常表示は変わらない"
+        "variant=\"chip\" の選択中は、forced-colors（Windows のハイコントラスト）では Highlight の地 + HighlightText で示す（Chip の selected と同じ）。通常表示は変わらない",
+        "FormField 配下では role=radiogroup（RadioGroup 本体）が FormField のラベル id を aria-labelledby で、説明・エラーを aria-describedby / aria-invalid で受け取る（tile / chip 共通）。<label for> は radiogroup に名前を付けないため。利用側の aria-label / aria-labelledby / aria-invalid の明示が優先され、aria-describedby は連結される。FormField の外で使うときは RadioGroup に日本語の aria-label を書く",
+        "variant=\"tile\" の選択中の点は、forced-colors（Windows のハイコントラスト）では Highlight（無効時は GrayText）で塗る。点は背景色で描いているため、そのままでは Canvas に置き換わって選択中でも中が空に見える。通常表示は変わらない"
       ],
       "props": [
         "children: ラベル本文（必須。tile/chip 共通）",
@@ -590,7 +619,9 @@
       ],
       "accessibility": [
         "SheetTitle は必須（ダイアログの読み上げ名）",
-        "フォーカスは既定で自動移動する（開く=Sheet の中へ / 閉じる=トリガーへ戻る）。WCAG 2.4.3。autoFocus={false} は止める必要がある特別な場合だけ使う（issue #233）"
+        "フォーカスは既定で自動移動する（開く=Sheet の中へ / 閉じる=開く直前の要素へ戻る）。WCAG 2.4.3。autoFocus={false} は止める必要がある特別な場合だけ使う（issue #233）",
+        "閉じると、その回に開く直前にフォーカスがあった要素（opener）へフォーカスを戻す。Trigger を使わず state で開いた（一覧の行のボタンから開く等）ときも body へ落ちない。opener が DOM から消えている・disabled・inert のときは Radix 既定（Trigger へ戻す）に任せる。開いたまま SheetContent を作り直しても（key の変更など）記録を引き継ぐ。止めたいときは onCloseAutoFocus で event.preventDefault() する（consumer の指定が先に呼ばれる）",
+        "日本語入力の変換中（isComposing / keyCode 229）の Esc では閉じない（変換の取り消しで入力中の内容を失わないため）。consumer の onEscapeKeyDown は先に呼ばれる。変換していない Esc は従来どおり閉じる"
       ]
     },
     {
@@ -631,7 +662,7 @@
         "範囲スライダーの Home / End はフォーカス中のつまみを、そのつまみが動ける範囲の端（隣のつまみ ± minStepsBetweenThumbs × step、無ければ min / max）へ動かす（WAI-ARIA APG Multi-Thumb Slider）。つまみが 1 つのときは Radix の既定のまま",
         "つまみの数は value / defaultValue の配列の長さ。どちらも無いときは Radix の既定値 [min] に合わせて 1 つ",
         "forced-colors（Windows のハイコントラスト）では選択範囲を Highlight、レールを CanvasText の輪郭線（outline）で示す。通常表示は変わらない",
-        "溝は高コントラストのとき --Surface-Control-Track（3:1 以上）に切り替わる。溝の色は bg-[var(--Surface-Control-Track,var(--Surface-Tertiary))] の形で書く。高コントラスト時の溝と選択範囲（ブランド色）は明るさが近く、区別は色相が中心。値はつまみの位置で伝わる（つまみは 3:1 を満たす）"
+        "溝は高コントラストのとき --Surface-Control-Track（3:1 以上）に切り替わる。溝の色は bg-[var(--Surface-Control-Track,var(--Surface-Neutral-Tertiary))] の形で書く。高コントラスト時の溝と選択範囲（ブランド色）は明るさが近く、区別は色相が中心。値はつまみの位置で伝わる（つまみは 3:1 を満たす）"
       ]
     },
     {
@@ -782,7 +813,8 @@
         "PC のサブメニューは DropdownMenu の Portal / collision handling を使い、side=right / align=start / collisionPadding=8 で viewport 内に収める。絶対配置の flyout を手組みしない",
         "PC のサブメニューは hover とクリックに加え、Enter / Space / ArrowDown で開き Escape で閉じてトリガーへフォーカスを戻す。hover 起動時はメニューへフォーカスを移さず、トリガーと Portal 間は短い close delay で橋渡しする",
         "linkComponent でリンク実装を差し替えられる（next/link 等）。未指定なら素の <a>。PC レールの項目・サブメニューのポップアップ・SP ドロワーの項目とサブ項目のすべてに効く。ポップアップ内のリンクは Radix の asChild 越しに描かれるため、ref と任意の属性を <a> まで転送する実装を渡す（next/link は転送する）。aria-current=page は linkComponent 経由でも付く（#236）。SP ドロワー内のリンク（項目・サブ項目）を押すと onOpenChange(false) が呼ばれる（クライアント遷移ではページが再読み込みされず、ドロワーが開いたまま新しいページに重なるのを防ぐ）",
-        "この部品は Client Component のため、React Server Components では Server Component から linkComponent を渡せない（実行時に Functions cannot be passed directly to Client Components で落ちる）。Next.js App Router では呼び出し側のファイルを \"use client\" にする。エラーメッセージは \"use server\" を示唆するが正解は逆（#264）"
+        "この部品は Client Component のため、React Server Components では Server Component から linkComponent を渡せない（実行時に Functions cannot be passed directly to Client Components で落ちる）。Next.js App Router では呼び出し側のファイルを \"use client\" にする。エラーメッセージは \"use server\" を示唆するが正解は逆（#264）",
+        "SP ドロワー内のリンクを押すと onOpenChange(false) が呼ばれるが、Cmd/Ctrl/Shift/Alt 付きクリック・中クリック・target が _self 以外（_blank 等）のリンクでは呼ばない（別タブで開くだけで今の画面は移らないため）。通常の左クリックは SPA の preventDefault 遷移でも閉じる"
       ]
     },
     {
@@ -870,7 +902,7 @@
       "rules": [
         "フィルター・ステータスタブに使う。ToggleGroup+Badge手書き禁止",
         "Tagと違い押せる・削除できる",
-        "selected の見た目はブランド色を使わず、Surface-Tertiary 地 + Text-High-Emphasis 文字 + 内側 1px の黒系の枠（Border-High-Emphasis。inset-ring で描くので未選択→選択でサイズは変わらない）。chipVariants の variant='selected' に対応し、selected prop が自動で選ぶ。variant='accent'（薄いブランド色地）は明示指定の互換のために残してあるが、選択中の表示には使わない（contracts/composition.json の brandColorUsage）。count バッジの選択中は Surface-Primary 地 + Text-High-Emphasis",
+        "selected の見た目はブランド色を使わず、Surface-Neutral-Tertiary 地 + Text-High-Emphasis 文字 + 内側 1px の黒系の枠（Border-High-Emphasis。inset-ring で描くので未選択→選択でサイズは変わらない）。chipVariants の variant='selected' に対応し、selected prop が自動で選ぶ。variant='accent'（薄いブランド色地）は明示指定の互換のために残してあるが、選択中の表示には使わない（contracts/composition.json の brandColorUsage）。count バッジの選択中は Surface-Primary 地 + Text-High-Emphasis",
         "removable の削除ボタンは data-slot=\"chip-remove\"（本体は data-slot=\"chip-trigger\"）。読み上げ名は removeLabel（既定「削除」）。削除可能な Chip が複数並ぶ場面では「{ラベル}を削除」のように対象が分かる名前を渡す",
         "linkComponent でリンク実装を差し替えられる（next/link 等）。未指定なら素の <a>。href 指定時のリンク（removable のときは本体のリンク）に効く。href 付きでも onClick と aria-* / data-* などは <a> に渡る（遷移は止めない）。type / disabled / form* / name / value など button 専用の属性は渡さない（#236）",
         "removable を指定するときは、削除ボタンに onClick を付けるため React Server Components では Server Component から描けない（実行時に Event handlers cannot be passed to Client Component props で落ちる。linkComponent の有無によらない）。Next.js App Router では呼び出し側のファイルを \"use client\" にする。removable でなければ Server Component のまま使える（#264）"
@@ -934,12 +966,16 @@
         "検索が必要な単一選択に使う。少数候補はSelectまたはRadioGroupを使う",
         "Popover + Command の検索・キーボード操作を内包する",
         "制御コンポーネント。value と onValueChange を必ず渡す（非制御では選択が反映されない）",
-        "FormField の children に置けば id / aria-labelledby / aria-describedby / aria-invalid を自動で受け取る（FormField の error で aria-invalid=true）。FormField を使わないときは id / aria-invalid / aria-describedby を明示して FieldError に接続する"
+        "FormField の children に置けば id / aria-labelledby / aria-describedby / aria-invalid を自動で受け取る（FormField の error で aria-invalid=true）。FormField を使わないときは id / aria-invalid / aria-describedby を明示して FieldError に接続する",
+        "絞り込みは label と keywords（別名・読み）の部分一致。大文字小文字・全角半角（NFKC）・ひらがな/カタカナ・漢字に挟まれた「ヶ/ケ/ヵ/が」（市ヶ谷/市ケ谷・霞が関/霞ケ関）を区別しない（src/lib/search-normalize.ts の matchesSearch）。読みで探させたい候補は keywords にカタカナかひらがなで入れる",
+        "絞り込みは連続した部分一致かどうかの二値で、cmdk 既定の fuzzy スコア（飛び飛びの文字の一致・一致度順の並べ替え）は使わない。当たった候補は options の並びのまま表示する（前方一致を上に出したい等は、options を呼び出し側で並べ替えて渡す）"
       ],
       "accessibility": [
         "aria-invalid のときトリガーに赤 1px（Border-Caution）の内側リング（inset-ring）を出す。トリガーは枠幅 0 の Button tertiary なので border では描かない（高さは変わらない）。キーボードフォーカス時は外側のフォーカスリングと同時に表示される",
         "forced-colors（Windows のハイコントラスト）では box-shadow が消えるため、aria-invalid のときだけ CanvasText の輪郭線（outline。レイアウトに影響しない）で境界を出す。通常表示は変わらない",
-        "トリガーは枠を持たない。高コントラストのときだけ内側へ 1px の輪郭（HIGH_CONTRAST_OUTLINE・--Border-Control）が出て 3:1 以上になる（エラー時は輪郭を透明にし、赤の内側リングをそのまま見せる）。トリガーに border を足して直さない"
+        "トリガーは枠を持たない。高コントラストのときだけ内側へ 1px の輪郭（HIGH_CONTRAST_OUTLINE・--Border-Control）が出て 3:1 以上になる（エラー時は輪郭を透明にし、赤の内側リングをそのまま見せる）。トリガーに border を足して直さない",
+        "選択中は読み上げ名の後ろに選択中の値が続く（例「都道府県 東京都」）。名前の先頭は 利用側の aria-labelledby → aria-label（無ければ placeholder）→ FormField のラベル の順で、値の要素を aria-labelledby で指す。未選択のときは従来どおり（値も placeholder も足さない）",
+        "候補一覧のポップアップ（Popover の role=dialog）はトリガーと同じ出どころの名前を持つ（利用側の aria-labelledby → aria-label / placeholder → FormField のラベル）。無名の dialog にしない"
       ]
     },
     {
@@ -975,6 +1011,8 @@
       ],
       "accessibility": [
         "autoPlay は、動きを減らす設定（prefers-reduced-motion: reduce）のときは自動再生しない。矢印・ドットでの移動もスムーズスクロールせず瞬時に切り替える。停止ボタンは持たない",
+        "フォーカスをリングだけで示す。矢印・ドットは FOCUS_RING_ONLY を使い、ring-[var(--Focus-High-Emphasis)]/50 を直書きしない（高コントラストのときだけ不透明な --Focus-Ring-Control に切り替わる）",
+        "PC（@[960px]）で隠れている（opacity-0）前へ・次への矢印は、キーボードフォーカスが来たら見える（@[960px]:focus-visible:opacity-100）",
         "丸いボタンの枠は高コントラストのとき --Border-Control（3:1 以上）に切り替わる。枠色は border-[var(--Border-Control,var(--Border-Medium-Emphasis))] の形で書く（既定の見た目は変わらない）"
       ]
     },
@@ -990,12 +1028,15 @@
         "trigger の選択値は M月D日（曜日）表記、カレンダーは日本語ロケール",
         "選択範囲は min/max、個別不可日は disabledDates で指定する",
         "DateTimePicker は JST 前提で Date をそのまま扱う（TZ 変換しない）",
-        "FormField の children に置くだけで trigger が id（label の htmlFor と一致）・aria-labelledby（FormField のラベル + 表示中の日付 / placeholder）・aria-describedby（説明・エラー）・aria-invalid（error 時 true）を受け取る。id の手書きは不要（明示した id / aria-invalid が優先、aria-describedby は連結）"
+        "FormField の children に置くだけで trigger が id（label の htmlFor と一致）・aria-labelledby（FormField のラベル + 表示中の日付 / placeholder）・aria-describedby（説明・エラー）・aria-invalid（error 時 true）を受け取る。id の手書きは不要（明示した id / aria-invalid が優先、aria-describedby は連結）",
+        "カレンダーで選択中の日をもう一度押しても値は消えない（同じ日のまま閉じる。DateTimePicker は時刻も保つ）。値を空に戻す手段は clearable の × だけなので、任意項目（null 許容）では clearable を付ける",
+        "カレンダーは開くたびに、値があれば選択中の日の月、無ければ今月を表示する（defaultMonth を渡せばそちらが優先）。DateTimePicker も同じ"
       ],
       "props": [
         "id?: string",
         "aria-invalid?: boolean",
-        "aria-describedby?: string"
+        "aria-describedby?: string",
+        "defaultMonth?: Date — カレンダーを開いたときに表示する月（value より優先）"
       ],
       "accessibility": [
         "aria-invalid のとき trigger の枠は Input / Select と同じ Border-Caution",
@@ -1088,7 +1129,7 @@
         "グローバルナビ・BottomTabBar・パンくずを持たない（構造的に置けない）。離脱を誘う導線を出さず購入に集中させる",
         "bottomAction（StickyActionBar 等）を渡すと本文の下余白はシェルが管理する。ページ側で pb を書かない（付け忘れ／二重がけの構造的防止）",
         "左右 padding は持たない（Container の責務）。管理画面の複雑な集中編集は WorkspaceShell を使う（EC 購入導線＝FunnelShell）",
-        "地がSurface-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き",
+        "地がSurface-Neutral-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き",
         "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
       ]
     },
@@ -1137,13 +1178,19 @@
       ],
       "accessibility": [
         "autoPlay は、動きを減らす設定（prefers-reduced-motion: reduce）のときは自動再生しない。矢印・ドットでの移動もスムーズスクロールせず瞬時に切り替える。停止ボタンは持たない",
+        "矢印・ドットも同じリング（FOCUS_RING_ONLY）で示す",
+        "PC（@[960px]）で隠れている（opacity-0）前へ・次への矢印は、キーボードフォーカスが来たら見える（@[960px]:focus-visible:opacity-100）",
         "フォーカスをリングだけで示す。色は FOCUS_RING_ONLY（内側に描くなら FOCUS_RING_INSET）を使い、ring-[var(--Focus-High-Emphasis)]/50 を直書きしない。高コントラストのときだけ不透明なリング（--Focus-Ring-Control・3:1 以上）に切り替わる",
         "丸いボタンの枠は高コントラストのとき --Border-Control（3:1 以上）に切り替わる。枠色は border-[var(--Border-Control,var(--Border-Medium-Emphasis))] の形で書く（既定の見た目は変わらない）"
       ]
     },
     {
       "name": "ImageGallery",
-      "path": "src/components/primitives/image-gallery.tsx"
+      "path": "src/components/primitives/image-gallery.tsx",
+      "accessibility": [
+        "操作子（矢印・ドット・サムネイル・お気に入り・ブックマーク）は写真の上に置くため、フォーカスをリングだけで示す。色は FOCUS_RING_ONLY（overflow-hidden の中で切れるなら FOCUS_RING_INSET）を使い、ブラウザ既定の outline に頼らない・ring-[var(--Focus-High-Emphasis)]/50 を直書きしない（高コントラストのときだけ不透明な --Focus-Ring-Control に切り替わる）",
+        "サムネイル列は overflow のスクロール領域がリング（3px）を切り取らないよう、4px の余白を内側に取り同じ分だけ負マージンで外へ戻している（静止時のレイアウトは変わらない）。サムネイル列の余白を詰めない"
+      ]
     },
     {
       "name": "ImageInput",
@@ -1214,7 +1261,12 @@
       "name": "KebabMenu",
       "path": "src/components/primitives/kebab-menu.tsx",
       "rules": [
-        "テーブル行アクション用"
+        "テーブル行アクション用",
+        "一覧の各行に置くときは menuLabel に対象が分かる名前（例: 「苺のショートケーキのメニュー」）を渡す。既定の「メニュー」のままだと全行が同じ名前になり、読み上げ・音声操作で区別できない",
+        "トリガーの見た目は 32px のまま、当たり判定は tap-target で 44px に広げている。隣のボタンとの間は 12px 以上空ける（当たり判定が重ならないように）"
+      ],
+      "props": [
+        "menuLabel?: string — トリガーの読み上げ名（aria-label）。既定「メニュー」"
       ]
     },
     {
@@ -1260,7 +1312,8 @@
         "選択済み Chip を削除すると、フォーカスは次の Chip の削除ボタン → 無ければ直前の Chip → Chip が残らなければトリガーへ移る（body に落ちない）",
         "forced-colors（Windows のハイコントラスト）では box-shadow が消えるため、aria-invalid のときだけ CanvasText の輪郭線（outline。レイアウトに影響しない）で境界を出す。通常表示は変わらない",
         "選択済み Chip の削除ボタンの名前は「{項目のラベル}を削除」（Chip の removeLabel に渡す）",
-        "トリガーは枠を持たない。高コントラストのときだけ内側へ 1px の輪郭（HIGH_CONTRAST_OUTLINE・--Border-Control）が出て 3:1 以上になる（エラー時は輪郭を透明にし、赤の内側リングをそのまま見せる）。トリガーに border を足して直さない"
+        "トリガーは枠を持たない。高コントラストのときだけ内側へ 1px の輪郭（HIGH_CONTRAST_OUTLINE・--Border-Control）が出て 3:1 以上になる（エラー時は輪郭を透明にし、赤の内側リングをそのまま見せる）。トリガーに border を足して直さない",
+        "候補一覧のポップアップ（Popover の role=dialog）はトリガーと同じ出どころの名前を持つ（利用側の aria-labelledby → aria-label / placeholder → FormField のラベル）。無名の dialog にしない"
       ]
     },
     {
@@ -1345,7 +1398,10 @@
         "formatOptions?: Intl.NumberFormatOptions",
         "locale?: string",
         "inputId?: string",
-        "label?: string"
+        "label?: string",
+        "name?: string — フォーム送信名。FormData に素の数値で入る（editable かつ formatOptions 無しは入力欄に、桁区切り表示・editable=false は hidden input に付く）",
+        "inputRef?: Ref<HTMLInputElement> — 内部の入力欄への ref",
+        "inputProps?: NumberInputInputProps — 内部の入力欄に渡す属性（onFocus / onBlur / onKeyDown / autoComplete / data-* 等。値・id・name・aria・disabled は除く）"
       ],
       "rules": [
         "DSの数値入力はすべてこれを使う。生の input type=\"number\" は使わない（カート数量・価格・在庫・ポイント等すべて）",
@@ -1355,7 +1411,8 @@
         "桁区切り・通貨表示は formatOptions を渡す（編集中は素の数値になる）。JPY の全角￥は半角¥に正規化される",
         "旧名 QuantitySelector は用途名だったため機能名に改名した。旧名は deprecated alias として残るが新規利用は不可",
         "FormField の children に置くと、入力欄が id（label の htmlFor と一致）・aria-describedby（説明・エラー）・エラー状態（FormField の error。見た目の赤枠と aria-invalid）を受け取る。label を指定しなければ名前も FormField のラベルになる（入力欄・グループ = ラベル、増減ボタン =「ラベル 減らす / 増やす」）。明示した inputId / label / error が優先。FormField の外の DOM は変わらない",
-        "高コントラストのとき、md は枠が --Border-Control（3:1 以上）に、sm は地の色を変えずに内側へ 1px の輪郭（HIGH_CONTRAST_OUTLINE）を足す。既定の見た目は変わらない"
+        "高コントラストのとき、md は枠が --Border-Control（3:1 以上）に、sm は地の色を変えずに内側へ 1px の輪郭（HIGH_CONTRAST_OUTLINE）を足す。既定の見た目は変わらない",
+        "その他の props（onFocus / onBlur / data-* 等）はグループの div に付く（従来どおり）。入力欄だけに付けたいイベント・属性は inputProps、ref は inputRef で渡す。onFocus / onBlur は部品の処理の後、onKeyDown は部品のキー処理の前に呼ばれる（preventDefault で Enter 確定・矢印キーの増減を止められる）"
       ],
       "accessibility": [
         "error のとき入力欄に aria-invalid=\"true\" を付ける（見た目の赤枠と同時）",
@@ -1601,7 +1658,7 @@
         "primaryActionはワークスペース全体の上位アクション（公開申請・承認依頼等）がある場合のみ。セクション／行単位の操作はコンテンツ内に置く",
         "標準の編集はAdminShellのStandard Page（Edit）（旧Form Page）。複雑・複数情報をまたぐ集中編集・没入執筆のみWorkspaceShellを使う",
         "sectionNavは編集内ナビ（アンカー／ステップ）のみ。PCでサイド表示・SPで非表示",
-        "地がSurface-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き",
+        "地がSurface-Neutral-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き",
         "a11y: DOM 先頭に SkipLink を標準内蔵し <main id> を制御できる（mainId 既定 main-content）。sr-only で視覚無影響。skipLink={false} で無効化"
       ]
     }
@@ -1629,7 +1686,7 @@
         "ヘッダーの水平 padding（px-4 @md:px-6）は main の gutter（p-4 @md:p-6）と同値。片方だけ変えるとヘッダー内要素と h1 の左端がズレるので、変えるときは両方揃える",
         "既定値は 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は据え置き",
+        "地がSurface-Neutral-Secondaryなので、シェルが配下Cardのサーフェス文脈（--card-surface: Surface-Primary）を宣言する → Cardはsurface未指定のまま白で地から浮く（#150）。darkは据え置き",
         "linkComponent でリンク実装を差し替えられる（next/link 等）。未指定なら素の <a>。サイドナビ（AdminSideNav）の項目・サブメニューとパンくずのリンクに効く（#236）",
         "この部品は Client Component のため、React Server Components では Server Component から linkComponent を渡せない（実行時に Functions cannot be passed directly to Client Components で落ちる）。Next.js App Router では呼び出し側のファイルを \"use client\" にする。エラーメッセージは \"use server\" を示唆するが正解は逆（#264）"
       ]
@@ -1713,7 +1770,10 @@
     },
     {
       "name": "OrderSummary",
-      "path": "src/components/ec/order-summary.tsx"
+      "path": "src/components/ec/order-summary.tsx",
+      "rules": [
+        "画面下に固定する既定は BottomTabBar（高さ 52px + 下端の safe-area）の真上に重なる位置（bottom-[calc(52px+env(safe-area-inset-bottom))]）。safe-area が 0 の環境では 52px のまま。BottomTabBar に banner を付けない場合は、consumer 側で bottom を足し直さない。banner を付けると BottomTabBar がその高さ分だけ高くなり、この固定位置では banner の下端に重なるため、その画面だけ className で bottom を banner の高さ分上げる"
+      ]
     },
     {
       "name": "PaymentMethodDisplay",
@@ -1748,6 +1808,7 @@
       ],
       "variants": {},
       "accessibility": [
+        "写真の上のお気に入りボタンは FOCUS_RING_ONLY のフォーカスリングを持つ（ブラウザ既定の outline に頼らない）",
         "丸いボタンの枠は高コントラストのとき --Border-Control（3:1 以上）に切り替わる。枠色は border-[var(--Border-Control,var(--Border-Medium-Emphasis))] の形で書く（既定の見た目は変わらない）"
       ]
     },
@@ -1801,6 +1862,7 @@
         "この部品は Server Component のまま使える。linkComponent を渡すためだけに、Next.js App Router の呼び出し側を \"use client\" にする必要はない（#264）"
       ],
       "accessibility": [
+        "ブックマークボタンは overflow-hidden の行の中なので、内側に描く FOCUS_RING_INSET のフォーカスリングを持つ（ブラウザ既定の outline に頼らない）",
         "丸いボタンの枠は高コントラストのとき --Border-Control（3:1 以上）に切り替わる。枠色は border-[var(--Border-Control,var(--Border-Medium-Emphasis))] の形で書く（既定の見た目は変わらない）"
       ]
     },

package/contracts/composition.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "Cake.jp Design System — Composition Contracts",
-    "version": "0.22.1",
+    "version": "0.24.0",
     "description": "ページ骨格・視覚階層・余白リズムの機械可読な正本。画面パターンを選んだ後の「実際の組み方」を規定する。ページの外枠（モバイル/デスクトップ/管理）、商品グリッドの列数、余白の4段リズム、Surface のネスト階層、テキスト階層、CTA の優先順位を構造化する。人間向けの解説は guidelines/composition/layout.md・guidelines/composition/hierarchy.md・guidelines/overview.md。",
     "source": "guidelines/composition/layout.md, guidelines/composition/hierarchy.md, guidelines/overview.md, guidelines/components/button.md（CTA 密度ルール）を正本化",
     "roleSeparation": "screen-patterns.json はページ種別（Standard Page / Focused Workspace / ResponsiveDialog / Dialog）を選ぶための契約。composition.json は選んだ後、その骨格をどう組むか（外枠構造・余白リズム・階層）の契約。前者=何を使うか、後者=どう並べるか。",
@@ -126,11 +126,11 @@
     "description": "Surface のネストは3層まで。入れ子で背景を一段ずつ落として階層を表現する。",
     "layers": [
       { "depth": 1, "token": "--Surface-Primary", "hex": "#FFFFFF", "usage": "メインのコンテンツカード" },
-      { "depth": 2, "token": "--Surface-Secondary", "hex": "#FBF9F8", "usage": "ネストしたセクション・交互行" },
-      { "depth": 3, "token": "--Surface-Tertiary", "hex": "#F4F2F1", "usage": "抑えたコンテナ・無効領域" }
+      { "depth": 2, "token": "--Surface-Secondary", "hex": "#FCF9F2", "usage": "情報をまとめる押せない面（説明ボックス・フォームのまとまり・表の見出し行）。light はベージュ" },
+      { "depth": 3, "token": "--Surface-Tertiary", "hex": "#FCF9F2", "usage": "抑えたコンテナ（Section subtle・Alert 中立）。light は Secondary と同じベージュ。無効領域・押せる部品の地は --Surface-Neutral-Tertiary（#F4F2F1）" }
     ],
-    "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 が反転する）。"
+    "rule": "ネストは3層まで。4層目以降は情報設計を見直す。背景は Surface トークンで明示（未指定で親を透かさない）。ベージュ（Surface-Secondary / Tertiary）は押せない面だけに使い、押せる部品・hover / 選択 / 無効の地・溝・画像の仮の地・画面全体の地は Surface-Neutral-Secondary / Neutral-Tertiary（グレー）を使う。",
+    "surfaceContext": "色地 Section（background='subtle'|'accent-subtle'）と、地が Surface-Neutral-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.* に対応。",
@@ -149,7 +149,7 @@
     "priority": [
       { "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": "tertiary", "role": "Tertiary action / 後退・中立アクション（戻る・キャンセル・閉じる・スキップ・あとで）", "appearance": "ニュートラルなグレー（Surface-Neutral-Tertiary 地 + Text-High-Emphasis 文字）", "note": "他 DS の secondary に相当する見た目。主 CTA の隣に置く「戻る」「キャンセル」はこれを使う" },
       { "variant": "outline", "role": "準主役の前進アクション（ブランド色を使わない）。「一覧を見る」等の移動ボタン、一覧・カードで1件ごとに繰り返す操作（商品カードの「カートに追加」等）、ブックマーク等の保存トグルのボタン本体", "appearance": "白地（Surface-Primary）+ 1px の黒系の枠（Border-High-Emphasis）+ Text-High-Emphasis 文字。hover / active は薄い下地（Hover-Text-Button / Active-Text-Button）", "note": "ブランド色を使わないので何個並んでもよい。ただし繰り返す操作は見た目が増えるので、ボタンに頼らずカード全体のリンクで足りるときは置かない" },
       { "variant": "ghost", "role": "Minimal action（メニュー・ツールバー内）", "appearance": "下地なし・hover で薄い下地" },
       { "variant": "link", "role": "補助リンク（「もっと見る」「利用規約を見る」等のインラインの移動）", "appearance": "ブランド色を使わない。Text-Medium-Emphasis（グレー）+ 常時下線。hover で Text-High-Emphasis", "note": "セクション見出し横の「もっと見る」は SectionHeader が同じ意匠で描く" }
@@ -168,7 +168,7 @@
   "brandColorUsage": {
     "description": "ブランド色を使ってよい場所と使わない場所。ブランド色が付いた部品が画面に多いと、どれが主役か分からなくなり目立ちすぎる。そのため「1つの主 CTA」「価格の最強調」「入力部品のオン状態」など、色そのものが意味を持つ場所にだけ使う。色相に依存しない書き方にしてあり、ブランド色が別の色相に変わってもこのルールは同じ（トークン名や hex ではなく役割で判断する）。",
     "brandTokens": ["--Brand-Cake-Orange", "--Brand-Cake-Orange-Light", "--Brand-Cake-Orange-Ultra-Light", "--Text-Accent-Primary", "--Surface-Accent-Primary-Light", "--Object-Accent-Primary", "--Border-Accent-Primary"],
-    "principle": "強調は色の量ではなく、サイズ・余白・配置・文字の太さで作る。ブランド色の部品が1ビューポートに複数あるなら、主役以外は黒系（Text-High-Emphasis / Border-High-Emphasis）かグレー（Text-Medium-Emphasis / Surface-Tertiary）に落とす。",
+    "principle": "強調は色の量ではなく、サイズ・余白・配置・文字の太さで作る。ブランド色の部品が1ビューポートに複数あるなら、主役以外は黒系（Text-High-Emphasis / Border-High-Emphasis）かグレー（Text-Medium-Emphasis / Surface-Neutral-Tertiary）に落とす。",
     "allowed": [
       { "place": "1ビューポートに1つの主 CTA", "use": "Button variant=\"default\"（暗背景の上は inverse）", "note": "ctaHierarchy の default。副 CTA の secondary もアクセント色なので、主 CTA と合わせて画面の「前進アクション」を2つ程度に絞る" },
       { "place": "価格の最強調", "use": "typo-label-lg + --Text-Accent-Primary（PriceDisplay 等）", "note": "textHierarchy.accentNote と同じ。font-bold は足さない" },
@@ -183,12 +183,12 @@
       { "place": "一覧・カードで1件ごとに繰り返す操作（商品カードの「カートに追加」、クーポンの「獲得する」等）", "instead": "Button variant=\"outline\"（ProductCard のカートボタンは対応済み）", "note": "件数分だけブランド色のベタ塗りが並び、一覧全体がブランド色に染まって見える" },
       { "place": "ブックマーク・お気に入り等の保存トグルのボタン本体（「ブックマークを追加」「保存」）", "instead": "Button variant=\"outline\"（保存済みは文言とアイコンの形で示す。ブランド色のベタ塗りにしない）", "note": "保存は主 CTA ではなく補助の操作" },
       { "place": "「もっと見る」「すべて見る」「一覧を見る」等の移動", "instead": "文字リンクは Button variant=\"link\"（SectionHeader の moreHref も同じ意匠）。ボタンにするときは variant=\"outline\"（黒ベタ塗りにしない）", "note": "色ではなく下線で「押せる」ことを示す" },
-      { "place": "ナビの選択中表示（チップ・タブ・サイドナビ・ボトムタブ）", "instead": "Text-High-Emphasis の文字・下線・左ライン（Tabs の underbar が見本）。チップは Chip の selected（グレー地 + 黒系の枠）", "note": "選択中を色の薄い地で塗らない。Chip の selected は対応済み（Surface-Tertiary 地 + Text-High-Emphasis 文字 + 内側 1px の Border-High-Emphasis の枠）。今の SideNav / BottomTabBar / SectionNav / SubNav はブランド色のままで、変更は別途（未対応）" },
+      { "place": "ナビの選択中表示（チップ・タブ・サイドナビ・ボトムタブ）", "instead": "Text-High-Emphasis の文字・下線・左ライン（Tabs の underbar が見本）。チップは Chip の selected（グレー地 + 黒系の枠）", "note": "選択中を色の薄い地で塗らない。Chip の selected は対応済み（Surface-Neutral-Tertiary 地 + Text-High-Emphasis 文字 + 内側 1px の Border-High-Emphasis の枠）。今の SideNav / BottomTabBar / SectionNav / SubNav はブランド色のままで、変更は別途（未対応）" },
       { "place": "評価の星・評価の数値", "instead": "RatingStars は --Text-High-Emphasis（黒系）。入力用の星（ReviewForm の選択済み）はブランド色のまま", "note": "表示用の評価はブランド色の目立つ要素にしない" },
       { "place": "装飾目的の成功色・アクセント色の情報ラベル（「最短 〇月〇日お届け」等）", "instead": "--Text-Medium-Emphasis（Text-Success は成功メッセージ・結果の状態だけに使う）", "note": "情報ラベルを色で目立たせない" }
     ],
     "rules": [
-      "新しい部品や画面でブランド色を使うときは、allowed のどれに当たるかを説明できること。当たらないなら黒系・グレー系（Text-High-Emphasis / Text-Medium-Emphasis / Border-High-Emphasis / Surface-Tertiary）か、Button の outline / link を使う",
+      "新しい部品や画面でブランド色を使うときは、allowed のどれに当たるかを説明できること。当たらないなら黒系・グレー系（Text-High-Emphasis / Text-Medium-Emphasis / Border-High-Emphasis / Surface-Neutral-Tertiary）か、Button の outline / link を使う",
       "ブランド色のベタ塗り・薄い地は、1ビューポートに主 CTA 1つと、状態を示す小さな印を除いて置かない",
       "文字リンクにブランド色（--Text-Accent-Primary）を使わない。リンクは下線で示す。価格の最強調だけがアクセント色の文字",
       "DS 内に notAllowed に当たる既存部品が残っているときは、新規実装にそれを真似しない（部品の追従は個別に行う）"

package/contracts/rules.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "Cake.jp Design System — Rules Contracts",
-    "version": "0.22.1",
+    "version": "0.24.0",
     "description": "禁止パターン・アクセシビリティ要件・ライティングルールの構造化定義。lint-scratch.sh と check-drift.sh で自動検証。"
   },
   "prohibited": [

package/contracts/screen-patterns.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "Cake.jp Design System — Screen Patterns Contracts",
-    "version": "0.22.1",
+    "version": "0.24.0",
     "description": "CRUD 機能でどの画面パターンを使うかの機械可読な判断基準。5パターンの定義・CRUD 対応・決定木・編集UIの観点比較を構造化する。人間向けの解説は guidelines/foundations/screen-patterns.md。",
     "source": "GitHub issue #37 CRUDの画面設計の型化と基本パターンの整備",
     "relatedContract": "本契約はページ種別の選択（何を使うか）を担う。選んだ後の骨格の組み方（外枠構造・余白リズム・視覚階層）は contracts/composition.json を参照する。",

package/dist/components/ec/admin-shell.js

@@ -132,20 +132,20 @@ function se({
   skipLink: y,
   linkComponent: c
 }) {
-  const S = c ?? "a", [N, h] = b.useState(!1), k = /* @__PURE__ */ r(M, { children: [
-    /* @__PURE__ */ r("button", { className: "relative flex items-center justify-center size-10 shrink-0 rounded-lg hover:bg-[var(--Surface-Secondary)]", "aria-label": "通知", children: [
+  const N = c ?? "a", [S, h] = b.useState(!1), k = /* @__PURE__ */ r(M, { children: [
+    /* @__PURE__ */ r("button", { className: "relative flex items-center justify-center size-10 shrink-0 rounded-lg hover:bg-[var(--Surface-Neutral-Secondary)]", "aria-label": "通知", children: [
       /* @__PURE__ */ e(F, { size: 20, className: "text-[var(--Text-High-Emphasis)]" }),
       /* @__PURE__ */ e("span", { className: "absolute top-1.5 right-1.5 size-2 rounded-full bg-[var(--Surface-Caution)]" })
     ] }),
-    /* @__PURE__ */ e("button", { className: "flex items-center justify-center size-10 shrink-0 rounded-full bg-[var(--Surface-Tertiary)]", "aria-label": "プロフィール", children: /* @__PURE__ */ e(I, { size: 20, className: "text-[var(--Text-Medium-Emphasis)]" }) })
+    /* @__PURE__ */ e("button", { className: "flex items-center justify-center size-10 shrink-0 rounded-full bg-[var(--Surface-Neutral-Tertiary)]", "aria-label": "プロフィール", children: /* @__PURE__ */ e(I, { size: 20, className: "text-[var(--Text-Medium-Emphasis)]" }) })
   ] });
   return (
-    // 地が Surface-Secondary なので、配下 Card の既定サーフェスを白に切り替える文脈を宣言する
+    // 地が Surface-Neutral-Secondary なので、配下 Card の既定サーフェスを白に切り替える文脈を宣言する
     // （#150 の Section と同じ仕組み。dark は半透明白が重なって浮くため据え置き）。
     /* @__PURE__ */ r(
       "div",
       {
-        className: "@container flex min-h-screen bg-[var(--Surface-Secondary)] [--card-surface:var(--Surface-Primary)] dark:[--card-surface:var(--Surface-Secondary)]",
+        className: "@container flex min-h-screen bg-[var(--Surface-Neutral-Secondary)] [--card-surface:var(--Surface-Primary)] dark:[--card-surface:var(--Surface-Secondary)]",
         "data-slot": "admin-shell",
         children: [
           y !== !1 && /* @__PURE__ */ e(R, { href: `#${f}` }),
@@ -155,7 +155,7 @@ function se({
               items: v,
               activeKey: t,
               drawerTitle: u ?? s,
-              open: N,
+              open: S,
               onOpenChange: h,
               linkComponent: c
             }
@@ -187,7 +187,7 @@ function se({
               (n || l) && /* @__PURE__ */ r("div", { className: "mb-4 space-y-1", children: [
                 n && n.length > 0 && /* @__PURE__ */ e("nav", { className: "flex items-center gap-1 typo-body-sm text-[var(--Text-Low-Emphasis)]", "aria-label": "パンくず", children: n.map((o, d) => /* @__PURE__ */ r(b.Fragment, { children: [
                   d > 0 && /* @__PURE__ */ e(L, { size: 12 }),
-                  o.href ? /* @__PURE__ */ e(S, { href: o.href, className: "hover:text-[var(--Text-Accent-Primary)] transition-colors", children: o.label }) : /* @__PURE__ */ e("span", { className: "text-[var(--Text-High-Emphasis)]", children: o.label })
+                  o.href ? /* @__PURE__ */ e(N, { href: o.href, className: "hover:text-[var(--Text-Accent-Primary)] transition-colors", children: o.label }) : /* @__PURE__ */ e("span", { className: "text-[var(--Text-High-Emphasis)]", children: o.label })
                 ] }, d)) }),
                 l && /* @__PURE__ */ e("h1", { className: "typo-heading-2xl text-[var(--Text-High-Emphasis)]", children: l })
               ] }),

package/dist/components/ec/anniversary-card.js

@@ -30,7 +30,7 @@ function A({
         /* @__PURE__ */ r("div", { className: "flex items-center justify-between gap-2", children: [
           /* @__PURE__ */ r("div", { className: "flex items-center gap-2", children: [
             /* @__PURE__ */ e("p", { className: "typo-label-md text-[var(--Text-High-Emphasis)]", children: n }),
-            /* @__PURE__ */ e("span", { className: "typo-label-xs text-[var(--Text-Medium-Emphasis)] bg-[var(--Surface-Secondary)] px-2 py-0.5 rounded-full", children: c })
+            /* @__PURE__ */ e("span", { className: "typo-label-xs text-[var(--Text-Medium-Emphasis)] bg-[var(--Surface-Neutral-Secondary)] px-2 py-0.5 rounded-full", children: c })
           ] }),
           h
         ] }),

package/dist/components/ec/chart-controls.js

@@ -2,11 +2,11 @@ import { jsxs as l, jsx as a } from "react/jsx-runtime";
 import "react";
 import { cn as c } from "../../lib/utils.js";
 import { Switch as d } from "../foundations/switch.js";
-const h = [
+const u = [
   { value: "daily", label: "日別" },
   { value: "weekly", label: "週別" },
   { value: "monthly", label: "月別" }
-], u = [
+], h = [
   { value: "3M", label: "3M" },
   { value: "6M", label: "6M" },
   { value: "12M", label: "12M" },
@@ -24,13 +24,13 @@ function n({
       onClick: s,
       className: c(
         "px-3 py-1 rounded typo-label-sm transition-colors",
-        t ? "bg-[var(--Brand-Cake-Orange)] text-[var(--Text-on-Inverse)]" : "text-[var(--Text-Medium-Emphasis)] hover:text-[var(--Text-High-Emphasis)] hover:bg-[var(--Surface-Secondary)]"
+        t ? "bg-[var(--Brand-Cake-Orange)] text-[var(--Text-on-Inverse)]" : "text-[var(--Text-Medium-Emphasis)] hover:text-[var(--Text-High-Emphasis)] hover:bg-[var(--Surface-Neutral-Secondary)]"
       ),
       children: r
     }
   );
 }
-function g({
+function N({
   granularity: t = "daily",
   onGranularityChange: s,
   period: r = "3M",
@@ -50,7 +50,7 @@ function g({
       children: [
         /* @__PURE__ */ l("div", { className: "flex items-center gap-1.5", children: [
           /* @__PURE__ */ a("span", { className: "typo-label-sm text-[var(--Text-Low-Emphasis)]", children: "粒度" }),
-          /* @__PURE__ */ a("div", { className: "flex items-center gap-0.5", children: h.map((e) => /* @__PURE__ */ a(
+          /* @__PURE__ */ a("div", { className: "flex items-center gap-0.5", children: u.map((e) => /* @__PURE__ */ a(
             n,
             {
               active: t === e.value,
@@ -62,7 +62,7 @@ function g({
         ] }),
         /* @__PURE__ */ l("div", { className: "flex items-center gap-1.5", children: [
           /* @__PURE__ */ a("span", { className: "typo-label-sm text-[var(--Text-Low-Emphasis)]", children: "期間" }),
-          /* @__PURE__ */ a("div", { className: "flex items-center gap-0.5", children: u.map((e) => /* @__PURE__ */ a(
+          /* @__PURE__ */ a("div", { className: "flex items-center gap-0.5", children: h.map((e) => /* @__PURE__ */ a(
             n,
             {
               active: r === e.value,
@@ -87,5 +87,5 @@ function g({
   );
 }
 export {
-  g as ChartControls
+  N as ChartControls
 };