ksk-design-system 2.14.0 → 2.16.0

package/MIGRATION.md

@@ -20,6 +20,22 @@ patch / minor は原則破壊変更なし、自動アップグレード可（例
 - **余白・項目行・ダイアログ・アプリ枠・予定の色（#711–#716）**: Container / ChipFilterBar の `gutter="fluid"`（`--Container-Gutter-Fluid`）、FormField の `orientation="horizontal"`・Input / Textarea の `targetSize="comfortable"`、Dialog の `centerFrom`・`height="fill"`・`size="2xl"`・`DialogHeader variant="bar"`、FieldSet の `gap`・FieldLegend の `size="sm"`、MobileAppShell の `viewport="fixed"`・`safeAreaTop`・`safeAreaBottom`・`bottomPadding="native-tab-bar"`（`--Native-Tab-Bar-Height`。ネイティブ側が書く任意フック <!-- docs-drift-ignore: --Native-Tab-Bar-Height -->）、MonthCalendar / AgendaList の予定の `accentColor` を追加します。すべて任意指定で、既定の見た目は変わりません。
 - **CollapsibleChipField の見出し（#717）**: `label` の既定の見た目が `typo-label-sm` + `Text-Medium-Emphasis`（12px）から、フォームの項目名と同じ `typo-label-md` + `Text-High-Emphasis`（14px 太字）に変わります（同じ詳細シートの `<Label>` / `FormField` と大きさをそろえるため）。従来の見た目が要る画面は `labelSize="sm"` を指定してください。展開中の選択肢のまとまりは見える見出しと `aria-labelledby` で結ばれます（`ariaLabel` を指定した場合は従来どおり `aria-label`）。`label` も `icon` も渡さない行は、先頭の 24px の空きが無くなります。native の CollapsibleChipField は変わりません。
 
+## v2.16.0 の導入注意
+
+以下はv2.16.0の導入注意です。consumerへの展開・アプリ配布は別工程で、次回のまとめ展開で反映します。
+
+- **FieldGroup `variant="rows"` の余白が FormField 以外の行にも付く（#733・既定の見た目の変更）**: 直下の FormField 以外（Switch の行・ImageAttachmentPicker・Banner 等）にも上下 12px（`py-3`）が付きます。これらに `py-3` を手で書いていた場合は同じ値なので外せます。`my-*` のマージンは足し算になるので外してください。CollapsibleChipField は対象外（従来どおり）。
+- **NavigationBar `leftLabelVisible` の文字幅の上限（#732）**: title ありのときの左の文字幅の上限が 176px になります（title なしは上限なし）。
+- 追加のみ（既定の見た目は不変）: FormField `as="group"` 内の ChipSelector が名前なしの警告を出さない（外側の group が名前を持つ。#734）、Banner の `onDismiss` / `dismissLabel`（#735）、MonthCalendarHeader の `live`（#736）、AdminShell の `overlay`（背景の inert は重ねる側で付ける。#737）。
+
+## v2.15.0 の導入注意
+
+以下はv2.15.0の導入注意です。consumerへの展開・アプリ配布は別工程で、次回のまとめ展開で反映します。
+
+- **DetailSheetHeader の文字列 title がシート / ダイアログの名前になる（#727・既定動作の変更）**: Sheet / Dialog（ResponsiveOverlayFrame・BottomSheetFrame・SideDrawerFrame 経由を含む）の中で `DetailSheetHeader title="…"` に文字列を渡すと、その見出しを SheetTitle / DialogTitle（Radix の Title）として描き、シート / ダイアログの読み上げ名（`aria-labelledby`）にします。見た目（`typo-heading-lg`）は変わりません。`data-slot` が `sheet-title` / `dialog-title` になり、`autoFocus="title"` の対象にもなります。**同じシートに sr-only の `SheetTitle` / `DialogTitle` を別に置いている場合は消してください**（残すと id が重複します。開発ビルドで console.error）。従来どおり別の Title で名前を付けたい画面は `overlayTitle={false}` を指定してください。オーバーレイの外・AlertDialog の中・`titleEditor` や ReactNode の `title` は変わりません。
+- **DetailSheetHeader の leading が空のときの題名の位置（#729）**: `leading` を渡さない（null / undefined / false）見出しは左の列を描かなくなり、題名が 12px 左へ寄ってヘッダーの左の余白（20px）にそろいます（従来は幅 0 の列と 12px の間隔が残っていました）。`[data-slot="detail-sheet-header-leading"]` もその場合は出ません。
+- **MonthCalendarExpandToggle の読み上げ名（#721）**: 読み上げ名（label）は開閉で変わらず 1 つです。開いているかどうかは `aria-expanded` が伝えます。開閉で文言を切り替えていた独自ボタンから置き換える場合は、label を 1 つにしてください。
+
 <!-- deprecations:start（自動生成・手で編集しない） -->
 
 ## 非推奨 API 一覧

package/RELEASE.md

@@ -2,6 +2,41 @@
 
 `ksk-design-system` のリリーススケジュール・運用ルール。
 
+## v2.16.0（2026-10-18）
+
+2.15.0以降に、NavigationBarの文字付きの戻るの切れを直し、consumer側の上書きをなくすためのAPIを5件追加したminorリリース。追加のみのAPIが中心です。次の1点は既定の見た目が変わります。
+
+- FieldGroup `variant="rows"` の余白が、直下の FormField 以外の行（Switch の行・Banner 等）にも上下12pxで付きます。手書きの `py-3` は外せます。`my-*` は足し算になるので外します（#733）。
+
+主な変更は次のとおりです。
+- NavigationBar `leftLabelVisible` が、title ありで左・中央・右の3列になり、375pxでも「戻る」と長めのタイトルが見えるようにしました。文字幅の上限は176pxです。title なしは左ラベルが残り幅で省略され、右の要素を押し出しません（#732）。
+- FormField `as="group"` の中の ChipSelector が、名前を指定しなくても警告を出さないようにしました（#734）。
+- Banner に `onDismiss` / `dismissLabel`（#735）。
+- MonthCalendarHeader に `live`（#736）。
+- AdminShell に `overlay`。シェル内の Sheet / Dialog の暗転が下に隠れません（#737）。
+
+導入時は [2.16.0の注意](./MIGRATION.md#v2160-の導入注意) を確認してください。npm公開・タグ・GitHub Releaseはversion変更のmainマージ後に `publish.yml` が実行します。consumerへの取り込みとアプリ配布は別工程で、今回のDS公開準備には含めません。
+
+## v2.15.0（2026-10-17）
+
+2.14.0以降に、consumer側の上書きをなくすためのAPIを10件追加したminorリリース。追加のみのAPIが中心です。次の2点は既定の挙動・見た目が変わります。
+
+- シート / ダイアログの中の `DetailSheetHeader` の文字列 title を、そのシート / ダイアログの名前として描くようにしました。従来どおりにするには `overlayTitle={false}` を指定します（#727）。
+- `leading` を渡さない `DetailSheetHeader` は左の空き列を作らず、題名が12px左へ寄ります（#729）。
+
+主な追加は次のとおりです。
+- FormFieldに `as="group"`、FieldGroupに `variant="rows"`（#720）。
+- 月カレンダーの見出し `MonthCalendarHeader` と開閉ボタン `MonthCalendarExpandToggle`。開閉ボタンの読み上げ名は1つで、状態は `aria-expanded` が伝えます（#721）。
+- DetailSheetHeader / DialogHeaderに `onClose` / `closeLabel`（#722）。
+- DS部品の既定文言のロケールを切り替える `KskLabelsProvider`（#723）。
+- AdminShellに `safeAreaTop`（#724）。
+- Chipの色アニメーションをホバー端末のみにし、Android Chromeのちらつきを抑えました（#725）。
+- 下部ナビの選択面のぼかしを調整できるようにしました（#726）。
+- composition.json の admin 節を実装に合わせました（#728）。
+- NavigationBarに文字付きの戻る `leftLabelVisible`（#729）。
+
+導入時は [2.15.0の注意](./MIGRATION.md#v2150-の導入注意) を確認してください。npm公開・タグ・GitHub Releaseはversion変更のmainマージ後に `publish.yml` が実行します。consumerへの取り込みとアプリ配布は別工程で、今回のDS公開準備には含めません。
+
 ## v2.14.0（2026-10-17）
 
 2.13.0以降に、consumer側の上書きをなくすためのAPIを7件追加したminorリリース。追加のみのAPIが中心です。

package/contracts/components.json

@@ -1,15 +1,15 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "2.14.0",
+    "version": "2.16.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
-      "ui": 72,
+      "ui": 73,
       "patterns": 69,
       "commerce": 12,
       "admin": 8,
       "shells": 3,
-      "total": 164
+      "total": 165
     },
     "exportNaming": {
       "_doc": "contracts の name が `import { name } from \"ksk-design-system\"` で解決できるかを示す。__tests__/contracts-export-integrity.test.ts が src/index.ts の実 export と突き合わせて固定する。",
@@ -426,8 +426,9 @@
         "スマホは全画面・PC は中央のモーダルにする作業面は position=\"fullscreen\" + centerFrom（\"sm\" | \"md\" | \"lg\"）。境界以上で center と同じ位置・角丸・影・size の幅になる。className に md:!max-w-* / md:!h-* を書いて全画面を打ち消さない（issue #713）",
         "height=\"fill\" は中央表示（center / centerFrom の境界以上）の高さを画面 - 4rem に固定する。見取り図・表など中身の量で枠が伸び縮みすると困る面向け（issue #713）",
         "size は sm(400) / md(480・既定) / lg(640) / xl(800) / 2xl(1024px・issue #713)",
+        "帯の閉じるボタンは DialogHeader variant=\"bar\" onClose={() => setOpen(false)}（右端に Button ghost icon-lg 48px + 閉じるアイコン 20px。読み上げ名は closeLabel、既定は KskLabelsProvider の close＝「閉じる」）。DialogClose + Button を trailing に自作しない（issue #722）",
         "全画面ダイアログ（padding={false}）の上端の帯は DialogHeader variant=\"bar\"（下線・左右 24px・上下 12px）+ trailing（閉じるボタン等）。DialogHeader に border-b / flex-row / px を自作しない（issue #713）",
-        "height=\"fill\" は position=\"top\" と centerFrom の無い fullscreen では効かない（開発ビルドで警告）。DialogHeader variant=\"bar\" の trailing（閉じるボタン）は必須（省略すると開発ビルドで警告）。centerFrom の中央表示は center と同じ ksk-squircle の角（issue #713）"
+        "height=\"fill\" は position=\"top\" と centerFrom の無い fullscreen では効かない（開発ビルドで警告）。DialogHeader variant=\"bar\" は onClose か trailing のどちらかが必須（どちらも無いと開発ビルドで警告）。centerFrom の中央表示は center と同じ ksk-squircle の角（issue #713）"
       ],
       "variants": {
         "position": [
@@ -530,6 +531,28 @@
         "container に渡す ref は useState の setter などで安定させる（毎レンダー変わると開いている Portal が unmount/remount される）"
       ]
     },
+    {
+      "name": "KskLabelsProvider",
+      "path": "src/components/ui/ksk-labels.tsx",
+      "description": "DS 部品の既定文言（スキップリンク・管理画面のメニュー・FormField の必須/任意・閉じるボタン・NavigationBar の戻る/閉じる/シェア・カレンダー見出し）と MonthCalendar / AgendaList の locale 既定をまとめて切り替える Provider（issue #723）。アプリの一番外側に 1 回置く。",
+      "subcomponents": [
+        "useKskLabels",
+        "useKskLocale",
+        "KSK_DEFAULT_LABELS"
+      ],
+      "variants": [],
+      "sizes": [],
+      "accessibility": [
+        "読み上げ名（skip link・メニューボタン・閉じるボタン・カレンダーの前後ボタン等）を画面の言語にそろえる。英語の画面に日本語の読み上げが混ざらないようにする"
+      ],
+      "rules": [
+        "優先順位は「部品に渡した prop > Provider の labels > Provider の locale の既定（ja / en） > 日本語（Provider 無し）」",
+        "英語のアプリは <KskLabelsProvider locale=\"en\"> を 1 回置く。部品ごとに skipLinkLabel / mobileMenuLabel / closeLabel を渡して回らない",
+        "i18n の文言で差し替えるときは labels に t() の結果を渡す（入れ子の Provider は外側の labels に重ねる）",
+        "React context なので SSR でリクエスト間に共有されない。Toast の fire-and-forget 経路の文言は従来どおり configureToast（Toaster は props）",
+        "Provider を置かないときの文言は従来どおり日本語（後方互換）"
+      ]
+    },
     {
       "name": "Tooltip",
       "path": "src/components/ui/tooltip.tsx",
@@ -852,7 +875,8 @@
         "transparent": "boolean — 背景なし",
         "leftButtonProps": "Button の属性・ref（variant / size / onClick / children を除く）",
         "shareButtonProps": "Button の属性・ref（variant / size / onClick / children を除く）",
-        "headerProps": "title を除く header の属性・ref を根へ転送（issue #649）"
+        "headerProps": "title を除く header の属性・ref を根へ転送（issue #649）",
+        "leftLabelVisible": "boolean — 左ボタンに leftLabel の文字も表示（高さ 44px・文字は title なしなら幅の上限なし（右の要素を押し出さず残り幅で省略）・title ありなら max-w-44（176px・日本語8文字が収まる）で省略し title 属性で全文。title ありは左|中央|右の 3 列 grid（左右は同じ幅）で、短い文言ならタイトルが広く残る。既定 false。issue #729）"
       },
       "accessibility": [
         "aria-label auto-set for back/close/share",
@@ -861,7 +885,8 @@
       "rules": [
         "タイトルは absolute 中央配置",
         "glass=true は写真・グラデーション背景上でのみ使用",
-        "Button size=\"icon-xl\" (44px Apple HIG minimum)"
+        "Button size=\"icon-xl\" (44px Apple HIG minimum)",
+        "文字付きの戻るボタン（「＜ メニューに戻る」）は leftLabelVisible + leftLabel。NavigationBar をやめて Button を並べて自作しない（issue #729）"
       ]
     },
     {
@@ -1446,7 +1471,8 @@
       "rules": [
         "Color + icon + text (never color alone)",
         "density: default(gap-3 p-4) / compact(gap-2 px-3 py-2)。余白を詰めたいときは density=\"compact\"。`!p-2` 等の className で上書きしない（issue #683）",
-        "layout: card(既定・角丸の囲み) / bar(全幅・角丸なし・下線のみ)。画面上端の注意帯は layout=\"bar\" を使い、div で帯を自作しない（issue #683。native Banner は画像バナーで別 API のため Web のみ）"
+        "layout: card(既定・角丸の囲み) / bar(全幅・角丸なし・下線のみ)。画面上端の注意帯は layout=\"bar\" を使い、div で帯を自作しない（issue #683。native Banner は画像バナーで別 API のため Web のみ）",
+        "閉じるボタンは onDismiss（右端の icon-sm ghost・読み上げ名は dismissLabel、既定は KskLabels の close）。閉じる処理は consumer が持つ。×ボタンを自作して並べない（issue #735）"
       ]
     },
     {
@@ -1594,6 +1620,7 @@
         "square"
       ],
       "rules": [
+        "選択の切り替えのちらつき（Android Chrome）は DS が抑える: 色のアニメーションは hover:hover かつ pointer:fine の端末だけ、本体・× ボタン・中の要素のタップのハイライトは透明。consumer の CSS で [data-slot=chip] の transition / -webkit-tap-highlight-color を打ち消さない（issue #725）",
         "Tag (表示専用) との違いは interactive 性",
         "soldOut は斜線オーバーレイ + disabled",
         "href を渡すと <a> でレンダリング",
@@ -1656,7 +1683,10 @@
         "長いフォームでは FieldGroup の中に FormField を並べる",
         "ラベル左置きの項目行は orientation=\"horizontal\"（左のラベル列の幅は labelWidth・既定 5rem、複数行の中身は labelAlign=\"start\"）。説明文・エラーは右の列の下段に出る。Label に w-20 等を付けて行を自作しない（issue #712）",
         "horizontal で枠の無い入力欄（variant=\"inline\"）を置くときは targetSize=\"comfortable\" で 44px の当たり判定を持たせる。外側に py-2 を足して稼がない（issue #712）",
-        "orientation=\"horizontal\" は置き場所の幅（@container）が 15rem 未満なら縦積みに戻る。endLabel は入力欄の右に出る（issue #712）"
+        "orientation=\"horizontal\" は置き場所の幅（@container）が 15rem 未満なら縦積みに戻る。endLabel は入力欄の右に出る（issue #712）",
+        "チップ・トグル・ラジオ等の選択肢のまとまりを右（下）に置く行は as=\"group\"（ラベルは span[id]、中身の列は role=group + aria-labelledby、説明文・エラーは aria-describedby）。<span> + <div role=\"group\"> + w-20 のラベルで行を自作しない。htmlFor は渡さない（開発ビルドで警告）。required は読み上げに伝わらないので、必須は description か label の文言で補う（issue #720）",
+        "区切り線で並べる項目行の一覧は FieldGroup variant=\"rows\"（divide-y + 直下の FormField に py-3）に入れる。FormField に className=\"py-3\" を足さない（issue #720）",
+        "FormField as=\"group\" の中の ChipSelector（single）は aria-label / aria-labelledby を省いても名前なしの警告が出ない（外側の group がラベルで名前を持つ。内側へ同じ名前は結ばない = 二重読み上げにしない。issue #734）"
       ]
     },
     {
@@ -1677,6 +1707,7 @@
       ],
       "rules": [
         "FieldSet は gap-6（24px）、FieldGroup は gap-4（16px）の縦リズムを正本とする",
+        "詳細シートの区切り線の一覧は FieldGroup variant=\"rows\"（子の間に Border-Low-Emphasis の線・直下の要素（FormField に限らず Switch の行・ImageAttachmentPicker・Banner 等。FieldSeparator / FieldLegend / FieldDescription / FieldError は除く。詳細度 0 なので子の py-* が勝つ）に上下 12px）。CollapsibleChipField は自前の py-3 を持つのでそのまま並べる。divide-y と py-3 を自作しない（issue #720 / #733）",
         "個々の入力は既存 FormField を FieldGroup 内に並べる",
         "FieldDescription はセクション・グループの補足、FieldError はグループ単位のエラーに使う",
         "グループ横断の区切りは FieldSeparator を使い、中央ラベルは children で渡す",
@@ -1850,7 +1881,10 @@
         "SheetContent 内で使い、Sheet の autoFocus=false と組み合わせる",
         "KebabMenu は DetailSheetHeader trailing に置く",
         "editable title は titleEditor slot に置く",
-        "DetailSheetHeader の titleEditor には <CommitInput variant=\"inline-title\" aria-label=… /> を渡す（issue #675）"
+        "DetailSheetHeader の titleEditor には <CommitInput variant=\"inline-title\" aria-label=… /> を渡す（issue #675）",
+        "閉じるボタンは DetailSheetHeader onClose（trailing の右端に Button ghost icon 40px + 閉じるアイコン 20px。読み上げ名は closeLabel、既定は KskLabelsProvider の close＝「閉じる」）。trailing に閉じる Button を自作しない（issue #722）",
+        "leading を渡さないときは左の列を描かない（題名の左端がヘッダーの左の余白にそろう）。空の leading を埋めるために <span /> 等を渡さない（issue #729）",
+        "Sheet / Dialog の中の文字列 title はシート / ダイアログの名前（SheetTitle / DialogTitle）として描かれる。sr-only の SheetTitle / DialogTitle を併用しない（id が重複する。同じ Content の Title の登録数で検出し、開発ビルドで console.error）。別の Title で名前を付けるときだけ overlayTitle={false}（issue #727）"
       ]
     },
     {
@@ -1949,7 +1983,8 @@
         "Use selectionMode=\"single\" for single-select (multiple=false は非推奨). Use max to limit selection count.",
         "Do not patch selected flicker in consumer CSS; Chip handles Android tap highlight and touch transition behavior.",
         "PillToggle は 2〜4 択の segmented control 専用。5択以上・折り返しが要る単一選択はこの selectionMode=\"single\" を使う(issue #418)。",
-        "グループ名は aria-labelledby（見出しの id）か aria-label で渡す(issue #666)。単一選択の radiogroup は名前が必須で、どちらも無いと開発ビルドで console.warn する。id / aria-describedby もルートへ渡せる。native は accessibilityLabel / accessibilityLabelledBy"
+        "グループ名は aria-labelledby（見出しの id）か aria-label で渡す(issue #666)。単一選択の radiogroup は名前が必須で、どちらも無いと開発ビルドで console.warn する。id / aria-describedby もルートへ渡せる。native は accessibilityLabel / accessibilityLabelledBy",
+        "FormField as=\"group\" の中では aria-label / aria-labelledby を省いても警告が出ない（外側の group が名前を持つ）。明示した指定が優先（issue #734）"
       ]
     },
     {
@@ -2812,7 +2847,9 @@
       "path": "src/components/patterns/month-calendar.tsx",
       "description": "予定付きの月カレンダー（issue #679）。日ごとの予定を一覧する予定表（日付を選ぶ入力は Calendar / DatePicker）。今日・選択日・土日・月外セル・予定チップ・「+n件」の見た目を DS が持つ。",
       "subcomponents": [
-        "buildMonthWeeks"
+        "buildMonthWeeks",
+        "MonthCalendarHeader",
+        "MonthCalendarExpandToggle"
       ],
       "accessibility": [
         "WAI-ARIA grid パターン: role=grid / row / columnheader / gridcell、タブストップは 1 つ（roving tabindex。選択日 → 今日 → 1 日）",
@@ -2826,7 +2863,10 @@
         "スマホの週の帯は view=\"week\"（フォーカス中の日を含む 1 週だけ。矢印キーで週が移る。issue #704）、日ごとの予定の中身は AgendaList を下に置く。週ストリップ・アジェンダを Button unstyled で自作しない",
         "土日の色は weekendTone（既定 true。日曜 Text-Caution / 土曜 Text-Accent-Primary・Calendar と同じ語彙）",
         "native は未提供（INTENTIONAL_NATIVE_GAPS）",
-        "分類の識別色（カテゴリ別の予定）は MonthCalendarEvent.accentColor に var(--Categorical-N) を渡す。md 以上はチップの先頭の点、md 未満は日付の下の点（tone より優先）。チップの面と文字は tone のまま。renderEvent の中で色の点を自作しない（issue #716）"
+        "分類の識別色（カテゴリ別の予定）は MonthCalendarEvent.accentColor に var(--Categorical-N) を渡す。md 以上はチップの先頭の点、md 未満は日付の下の点（tone より優先）。チップの面と文字は tone のまま。renderEvent の中で色の点を自作しない（issue #716）",
+        "月の見出し（月名・今日へ・前後の月）は MonthCalendarHeader（month・onToday / onPrev / onNext・size md=スマホ / lg=PC・headingLevel）を grid の上に置く。前後は icon-sm + aria-label（既定「前の月」「次の月」）。見出しは aria-live=\"polite\" で月の切り替えを読み上げる。h2 + Button で自作しない（issue #721）",
+        "見出しは月が変わると aria-live で読み上げる。一覧のスクロールで月が変わる画面は MonthCalendarHeader live={false} で切る（issue #736）",
+        "週の帯 ⇄ 月全体の開閉は MonthCalendarExpandToggle（expanded / onExpandedChange・読み上げ名は固定で状態は aria-expanded・aria-controls に MonthCalendar の id）を grid の下に置き、expanded を view=\"month\" / \"week\" に渡す。Button ghost icon-sm w-full で自作しない（issue #721）"
       ]
     },
     {
@@ -3018,6 +3058,7 @@
         "Use floatingPosition='left'|'right' (variant='pill' only) when a FAB is placed on the opposite side; default 'center' keeps the existing centered float.",
         "Native Expo Router / React Navigation consumers should use createExpoRouterTabBar instead of local floating tab bars.",
         "寸法・面のプロダクト差分は公開 CSS 変数 --Nav-*（--Nav-Pill-* / --Nav-Item-* / --Nav-Center-Action-* / --Nav-Selected-*）で表現する。contracts/product-theme-overrides.json の nav グループが正本（issue #471）。",
+        "選択面（選択中のタブの下に敷くプラッター）のぼかしは --Nav-Selected-Backdrop（既定 none・例: var(--glass-blur-sm)）。[data-slot=\"bottom-nav-selected-surface\"] に backdrop-filter を直書きしない（issue #726）",
         "消費側は DS の内部マークアップ（[data-slot=\"bottom-nav-pill\"] > :is(a, button)、span:first-child / span:last-child、[data-global-nav-add-icon]）を !important や :has() で叩かない。DOM を狙う場合も公開 data-slot だけを使う。",
         "--Nav-Item-Min-Height / --Nav-Center-Action-Size は max(44px, var(...)) で参照するため、44px（HIG のタップ領域下限）より縮まない。",
         "--Nav-Center-Action-Surface / -Border / -Shadow と --Nav-Selected-Surface / -Shadow は宣言したときだけ DS 既定（.glass-accent / ガラスの選択プラッター）を置き換える。未宣言なら tone / dark の出し分けは DS 側が持つ。",
@@ -3268,7 +3309,9 @@
         "header と main の既定 gutter は内蔵 Container が担うためページ側で外周 padding を重ねない",
         "暗色サイドバーは sidebarTone=\"inverse\"（aside を Surface-Inverse にする）。中のナビは SidebarNav tone=\"inverse\"、ロゴ・フッターの文字も Text-on-Inverse 系にする（issue #680）",
         "lg 未満でナビへ辿れるようにするときは mobileDrawer（issue #705）。ヘッダー左端のメニューボタン（44px・aria-expanded・aria-label 既定「メニューを開く」）から左の Sheet に同じ sidebar を開く。ハンバーガーと Sheet side=\"left\" を consumer で自作しない",
-        "ドロワー内のリンク（a[href]）と SidebarNav の項目を押すと閉じる（closeMobileDrawerOnNavigate 既定 false、明示 true で有効）。開閉の制御は mobileDrawerOpen / onMobileDrawerOpenChange"
+        "ドロワー内のリンク（a[href]）と SidebarNav の項目を押すと閉じる（closeMobileDrawerOnNavigate 既定 false、明示 true で有効）。開閉の制御は mobileDrawerOpen / onMobileDrawerOpenChange",
+        "上端の safe-area は safeAreaTop（ヘッダーは下線込み 64px + 安全領域、lg 以上のサイドバーと mobileDrawer のドロワーも上に足す。header が無いときは本文の列）。アプリ内で全画面に重ねるときは className=\"h-full\" と組み、外枠に pt-[var(--Safe-Area-Inset-Top)] や背景を書かない（外枠は fixed と重ね順だけ。issue #724）",
+        "アプリ内で全画面に重ねるときは overlay（fixed inset-0 z-[var(--Z-Overlay)] h-full を DS が持つ。Sheet / Dialog の overlay と同じ層で、後に開いたものが上に出る）。背景の inert は重ねる側が付ける。className で fixed / z-index を書かない（issue #737）"
       ]
     },
     {

package/contracts/composition.json

@@ -44,13 +44,16 @@
       "implementation": "src/components/patterns/shells/admin-shell.tsx",
       "structure": [
         "AdminShell (flex h-screen, bg-[var(--Surface-Secondary)])",
-        "  sidebar slot: aside hidden lg:flex, border-r, bg-[var(--Surface-Primary)], ScrollArea でラップ済み（sidebarWidth prop で幅調整、既定 w-64）",
-        "  header slot: 任意。border-b, h-16。内蔵 Container(size=fluid) が px-6 を担当",
+        "  sidebar slot: aside hidden lg:flex, border-r, ScrollArea でラップ済み（sidebarWidth prop で幅調整、既定 w-64）。面は sidebarTone で決まる: \"default\"（既定）= bg-[var(--Surface-Primary)] + Border-Low-Emphasis、\"inverse\" = bg-[var(--Surface-Inverse)] + Text-on-Inverse（issue #680）",
+        "  mobileDrawer（任意・既定 false）: lg 未満のヘッダー左端にメニューボタン（icon-xl 44px・aria-expanded）を出し、左の Sheet（w-72 max-w-[85vw]・swipeToClose）に同じ sidebar slot を開く。header が無いときは lg 未満だけメニューボタンのヘッダーを出す（issue #705）",
+        "  header slot: 任意。border-b, h-16。内蔵 Container(size=fluid) が px-6 を担当。safeAreaTop で上端の safe-area を header（下線込み 64px + 安全領域）・lg 以上の aside・mobileDrawer のドロワーの上に足す（issue #724）",
         "  main: flex-1 overflow-auto。内蔵 Container(size=fluid, className=py-6) が p-6 相当の外周余白を担当"
       ],
       "rules": [
         "main の p-6（24px）がページ外周の既定余白。ページ側で二重に外周 padding を足さない",
-        "sidebar は lg 未満で hidden になる（モバイル用の代替ナビは呼び出し側の責務。AdminShell 自体はモバイル用ドロワーを持たない）",
+        "sidebar は lg 未満で hidden になる。lg 未満でナビへ辿れるようにするときは mobileDrawer（開閉の制御は mobileDrawerOpen / onMobileDrawerOpenChange、ナビ項目で閉じるのは closeMobileDrawerOnNavigate）。ハンバーガーと Sheet side=\"left\" を呼び出し側で自作しない（issue #705）",
+        "暗色サイドバーは sidebarTone=\"inverse\"。中のナビは SidebarNav tone=\"inverse\"、ロゴ・フッターの文字も Text-on-Inverse 系にする。aside に bg を className で上書きしない（issue #680）",
+        "アプリ内で全画面に重ねて出す管理画面は safeAreaTop + className=\"h-full\"。外枠は fixed と重ね順だけにし、safe-area の余白と背景を外枠に書かない（issue #724）",
         "sidebarWidth を変える場合、hidden lg:flex は維持し幅クラスのみ差し替える",
         "sidebar 内のロゴ行に border-b、フッター行に border-t を入れない。罫線は sidebar 右端の縦線と header 下の横線の 2 本だけに絞る（#253/#254）",
         "sidebar slot の直下は flex grow flex-col にし、フッターは mt-auto で下端へ置く。h-full は使わない（slot は Radix ScrollArea の viewport ラッパー配下＝height:auto で % height が解決されない。shell 側がそのラッパーを min-h-full の縦 flex に矯正しているので grow が効く）",

package/contracts/product-theme-overrides.json

@@ -23,7 +23,7 @@
     "statusPaletteNote": "statusPalette は「消費側が DS の primitive を自分の Tailwind alias（--color-sun-800 等）の実体として使っている」ケース向けの公開段（issue #384）。@theme inline の alias は生成ユーティリティに var(--Primitive-*) が直接展開されるため、alias 側を dark で差し替えても効かず、primitive を上書きする以外の経路が無い。公開しているのは status の tint 段（-50 × 4色）と、依頼のあったアクセント段（Red-600 / Green-700）だけ。-50 は DS の .dark ブロックが一切参照していない（dark の Surface-Caution/Success/Warning/Info は -900 と実値）ので、dark 内での上書きは DS コンポーネントに対して無害。light では --Surface-Caution / --Surface-Success / --Surface-Warning / --Surface-Info を駆動するので上書きは効く。アクセント段は light / dark の両方で DS semantic を駆動するため、パレット全段ではなく依頼ベースで1段ずつ開ける。",
     "statusPaletteSideEffects": "--Primitive-Red-600 は --Caution-Base（light / dark 共通）と、dark の --Active-Destructive-Button を駆動する。dark で Red-600 を Red-500(#EF4444) より明るい値に差し替えると、destructive ボタンの active が hover より明るくなり押下の階調が反転する。差し替えるなら --Hover-Destructive-Button との明度関係を実測すること。--Primitive-Green-700 は light の --Text-Success / --Success-Base のみを駆動する（dark は Green-400 なので影響なし）。",
     "contrastResponsibility": "neutralPalette（--Primitive-Gray-* / White / Black）を差し替えたら、本文×背景のコントラストは消費プロダクト側の責任になる。Gray は --Text-High-Emphasis（本文色）・--Text-Medium-Emphasis・--Surface-Secondary・--Border-Low-Emphasis など semantic.css の 33 箇所を駆動しているため、差し替え後に本文テキスト×各 Surface が WCAG AA（4.5:1、大きい文字は 3:1）を満たすか必ず実測すること。DS 側の scripts/check-contrast.mjs は DS 既定パレット向けの検査で、消費側の差し替えは見ていない。light / dark の両方を確認する。",
-    "navSurfaceNote": "--Nav-Center-Action-Surface / -Border / -Shadow と --Nav-Selected-Surface / -Shadow は例外的に :root へ既定値を置いていない（issue #471）。DS 既定は tone=\"inverse\" / dark で出し分ける素材（.glass-accent・ガラスの選択プラッター）で、単一の :root 値に畳めないため。src/styles/bottom-nav.css が var(--Nav-*, <DS 既定>) の形で持ち、消費側が宣言したときだけ上書きされる。宣言しなければレンダリングは 1px も変わらない。 --Nav-Pill-Surface / -Backdrop / -Border / -Shadow / -Specular も同じ扱い（issue #486）。pill 本体の DS 既定は Liquid Glass（.glass / tone=\"inverse\" は .glass-dark）で、背後コンテンツの可読性を優先して不透明面にしたい消費側のための口。フォールバックは .glass 自身の内部変数そのものなので、宣言しなければレンダリングは 1px も変わらない。ぼかしを完全に切るなら --Nav-Pill-Backdrop: none、ガラスのスペキュラ / 屈折リムまで消すなら --Nav-Pill-Specular: none（擬似要素の content を none にして生成させない）を併せて宣言する。"
+    "navSurfaceNote": "--Nav-Center-Action-Surface / -Border / -Shadow と --Nav-Selected-Surface / -Shadow / -Backdrop は例外的に :root へ既定値を置いていない（issue #471）。DS 既定は tone=\"inverse\" / dark で出し分ける素材（.glass-accent・ガラスの選択プラッター）で、単一の :root 値に畳めないため。src/styles/bottom-nav.css が var(--Nav-*, <DS 既定>) の形で持ち、消費側が宣言したときだけ上書きされる。宣言しなければレンダリングは 1px も変わらない。 --Nav-Pill-Surface / -Backdrop / -Border / -Shadow / -Specular も同じ扱い（issue #486）。--Nav-Selected-Backdrop（issue #726）は選択プラッターのぼかし。DS 既定は none で、:where() の詳細度 0 で当てるので、宣言しなければレンダリングは変わらない（例: --Nav-Selected-Backdrop: var(--glass-blur-sm)）。pill 本体の DS 既定は Liquid Glass（.glass / tone=\"inverse\" は .glass-dark）で、背後コンテンツの可読性を優先して不透明面にしたい消費側のための口。フォールバックは .glass 自身の内部変数そのものなので、宣言しなければレンダリングは 1px も変わらない。ぼかしを完全に切るなら --Nav-Pill-Backdrop: none、ガラスのスペキュラ / 屈折リムまで消すなら --Nav-Pill-Specular: none（擬似要素の content を none にして生成させない）を併せて宣言する。"
   },
   "allowedVariables": {
     "brandColor": [
@@ -186,7 +186,8 @@
       "--Nav-Center-Action-Border",
       "--Nav-Center-Action-Shadow",
       "--Nav-Selected-Surface",
-      "--Nav-Selected-Shadow"
+      "--Nav-Selected-Shadow",
+      "--Nav-Selected-Backdrop"
     ],
     "overlay": [
       "--Overlay-Desktop-Breakpoint"

package/contracts/token-hex-cache.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Semantic Token Hex Cache",
-    "version": "2.14.0",
+    "version": "2.16.0",
     "description": "semantic / semanticDark トークン（var(--Primitive-*) 参照）を実 hex に解決したサイドカー生成物。hex はデフォルト（Blue）テーマでの解決値であり、Brand 系（meta.themeDependentKeys に列挙）はテーマ差し替え（orange/green/violet 等）で実色が変わる。テーマ別の完全解決値は `ksk-design-system/native` エクスポート（バンドル済み native トークンモジュール）の themes を参照。tokens.json 本体のスキーマは変更せず、AI がこのファイルだけで実色を把握できるようにし、primitive 値の変更による semantic 実色のドリフトを --check で機械検出する。",
     "generatedBy": "scripts/generate-token-hex-cache.mjs",
     "theme": "default",