ksk-design-system 2.15.0 → 2.17.0

package/MIGRATION.md

@@ -20,6 +20,23 @@ 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.17.0 の導入注意
+
+以下はv2.17.0の導入注意です。consumerへの展開・アプリ配布は別工程で、次回のまとめ展開で反映します。
+
+- **Banner の読み上げ（#740・既定の読み上げの変更）**: これまで variant に関係なく `role="alert"`（今の読み上げに割り込む）でしたが、`info` / `success` は `role="status"`（読み上げの区切りで伝える）に変わります。`warning` / `caution` は従来どおり `role="alert"` です。見た目は変わりません。info / success でも割り込ませたい画面は `live="assertive"`、画面を開いたときから出ている静的な説明は `live="off"`（role なし）を指定してください。`role` を明示している呼び出しは従来どおりそちらが優先です。テストで `getByRole("alert")` により info / success の Banner を探している場合は `getByRole("status")` に直してください。
+- **DetailSheetHeader の閉じるだけの形（#742・既定の見た目の変更）**: title / titleEditor / description / leading / children のどれも渡さない（閉じるボタン・trailing だけの）ヘッダーは、下線と下余白（`border-b pb-4`）を出さなくなります。className で `border-0 pb-0` 等を上書きしていた場合は外せます。従来の下線が要る画面は `bordered` を指定してください。
+- **FormField `as="group"` 内の ChipSelector 単一選択の名前（#741・既定の読み上げの変更）**: #734 では内側の radiogroup に名前を結ばない方針でしたが、radiogroup は WAI-ARIA 1.2 で名前が必須で外側の group の名前は継承されないため、`aria-label` / `aria-labelledby` を省いた単一選択はラベルを `aria-labelledby` で結ぶように変わります（PillToggle `semantics="radio"` も同じ）。複数選択は従来どおり結びません。明示した指定は優先されます。見た目は変わりません。
+- 追加のみ（既定の見た目・読み上げは不変）: PillToggle の `aria-label` / `aria-labelledby`・`semantics="radio"`（フォームの値選び向け。FormField `as="group"` の中では radiogroup をそのラベルで名付ける。#741）、MonthCalendarHeader の `trailing`（#743）。
+
+## 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への展開・アプリ配布は別工程で、次回のまとめ展開で反映します。

package/RELEASE.md

@@ -2,6 +2,37 @@
 
 `ksk-design-system` のリリーススケジュール・運用ルール。
 
+## v2.17.0（2026-10-18）
+
+2.16.0以降に、consumer側の上書きをなくすためのAPIを4件追加したminorリリース。追加のみのAPIが中心です。次の3点は既定の読み上げ・見た目が変わります。
+
+- Banner の読み上げが variant で変わります。`info` / `success` は `role="status"`（読み上げの区切りで伝える）になり、`warning` / `caution` は従来どおり `role="alert"` です。割り込ませたい画面は `live="assertive"`、静的な説明は `live="off"` を指定します（#740）。
+- 閉じるボタン・trailing だけの `DetailSheetHeader` は、下線と下余白を出さなくなります。従来の下線が要る画面は `bordered` を指定します（#742）。
+- FormField `as="group"` の中の ChipSelector 単一選択（radiogroup）は、`aria-label` / `aria-labelledby` を省くとラベルを `aria-labelledby` で結ぶようになり、読み上げ名が付きます。見た目は変わりません（#741）。
+
+主な追加は次のとおりです。
+- Banner に `live`（#740）。
+- PillToggle に `aria-label` / `aria-labelledby`・`semantics="radio"`・`name`（#741）。
+- DetailSheetHeader に `bordered`（#742）。
+- MonthCalendarHeader に `trailing`（#743）。
+
+導入時は [2.17.0の注意](./MIGRATION.md#v2170-の導入注意) を確認してください。npm公開・タグ・GitHub Releaseはversion変更のmainマージ後に `publish.yml` が実行します。consumerへの取り込みとアプリ配布は別工程で、今回のDS公開準備には含めません。
+
+## 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点は既定の挙動・見た目が変わります。

package/contracts/components.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "2.15.0",
+    "version": "2.17.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 73,
@@ -827,13 +827,18 @@
         "md"
       ],
       "props": {
-        "fullWidth": "boolean (既定 false) — 横幅いっぱいに広げ、各項目を等幅にする(issue #500)。既定はラベル幅(w-fit)"
+        "fullWidth": "boolean (既定 false) — 横幅いっぱいに広げ、各項目を等幅にする(issue #500)。既定はラベル幅(w-fit)",
+        "aria-label / aria-labelledby": "string — 何を選ぶ欄かの読み上げ名(issue #741)。FormField as=\"group\" の中では省いてよい（semantics=\"radio\" は radiogroup をそのラベルで名付ける）",
+        "semantics": "\"tabs\" | \"radio\" (既定 \"tabs\") — 読み上げの役割(issue #741)。tabs=tablist/tab（表示の切り替え）、radio=radiogroup/radio（フォームの値選び）。見た目・矢印キー操作は同じ",
+        "name": "string — semantics=\"radio\" のときのフォーム送信名(issue #741)。<form> の中で選択中の value が FormData に入る"
       },
       "rules": [
         "Use for 2-4 options only. 1行固定の segmented control で折り返せない。",
         "5択以上・折り返しが要る単一選択は ChipSelector の selectionMode=\"single\" を使う(issue #418)。選択中の1つだけ見せて畳む場合は CollapsibleChipField(issue #419)。パネル連動が要るなら Tabs。",
         "等幅・全幅にしたいときは fullWidth を使う。className=\"grid w-full grid-cols-N\" で TabsList に届かせる回避策は内部構造依存なので使わない(issue #500)。",
-        "pill の trigger は透明な before 擬似要素でタップ領域を44pxまで確保済み。消費側で [role=\"tab\"] に追加の min-height を当てないこと(見えている面がトラックより高くなる)。"
+        "pill の trigger は透明な before 擬似要素でタップ領域を44pxまで確保済み。消費側で [role=\"tab\"] に追加の min-height を当てないこと(見えている面がトラックより高くなる)。",
+        "semantics=\"radio\" の項目（[role=\"radio\"] / data-slot=\"pill-toggle-item\"）も同じ before でタップ領域を確保済み。追加の min-height を当てない(issue #741)。",
+        "名前を付ける: 見える見出しがあれば aria-labelledby、無ければ aria-label。フォームの値選び（性別・単位など）は semantics=\"radio\" にし、FormField as=\"group\" で包む（radiogroup 自身もそのラベルで名付けるので aria-label は不要）。画面内の表示の切り替え（一覧の絞り込み・週/月）は既定の tabs のまま(issue #741)"
       ]
     },
     {
@@ -876,7 +881,7 @@
         "leftButtonProps": "Button の属性・ref（variant / size / onClick / children を除く）",
         "shareButtonProps": "Button の属性・ref（variant / size / onClick / children を除く）",
         "headerProps": "title を除く header の属性・ref を根へ転送（issue #649）",
-        "leftLabelVisible": "boolean — 左ボタンに leftLabel の文字も表示（高さ 44px・文字は max-w-28 で省略し title 属性で全文・タイトルの左右を px-32 に広げる。既定 false。issue #729）"
+        "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",
@@ -1471,7 +1476,9 @@
       "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）",
+        "読み上げは live で使い分ける（issue #740）。assertive=role=\"alert\"（今の読み上げに割り込む: 保存の失敗・期限切れなど、操作の結果ですぐ伝えるもの）/ polite=role=\"status\"（読み上げの区切りで伝える: 常時表示の案内・完了の知らせ）/ off=role なし（画面を開いたときから出ている静的な説明）。既定は variant から決まる: warning / caution=assertive、info / success=polite。常時出している注意帯（layout=\"bar\" のサンプルモード表示など）は live=\"polite\" か \"off\" にする。role を明示した場合はそちらが優先"
       ]
     },
     {
@@ -1684,7 +1691,8 @@
         "horizontal で枠の無い入力欄（variant=\"inline\"）を置くときは targetSize=\"comfortable\" で 44px の当たり判定を持たせる。外側に py-2 を足して稼がない（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）"
+        "区切り線で並べる項目行の一覧は FieldGroup variant=\"rows\"（divide-y + 直下の FormField に py-3）に入れる。FormField に className=\"py-3\" を足さない（issue #720）",
+        "FormField as=\"group\" の中の radiogroup（ChipSelector single・PillToggle semantics=\"radio\"）は aria-label / aria-labelledby を省くとラベルを aria-labelledby で結ぶ（radiogroup は名前必須・外側の group の名前は継承されない。issue #741）。複数選択の ChipSelector と PillToggle tabs は結ばない（issue #734）"
       ]
     },
     {
@@ -1705,7 +1713,7 @@
       ],
       "rules": [
         "FieldSet は gap-6（24px）、FieldGroup は gap-4（16px）の縦リズムを正本とする",
-        "詳細シートの区切り線の一覧は FieldGroup variant=\"rows\"（子の間に Border-Low-Emphasis の線・直下の FormField に上下 12px）。CollapsibleChipField は自前の py-3 を持つのでそのまま並べる。divide-y と py-3 を自作しない（issue #720）",
+        "詳細シートの区切り線の一覧は 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 で渡す",
@@ -1882,6 +1890,7 @@
         "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）",
+        "閉じるボタン（と trailing）だけのヘッダーは title 等を渡さなければ下線・下余白が自動で消える。className で border-0 / pb-0 を上書きしない。明示するときは bordered={true | false}（issue #742）",
         "Sheet / Dialog の中の文字列 title はシート / ダイアログの名前（SheetTitle / DialogTitle）として描かれる。sr-only の SheetTitle / DialogTitle を併用しない（id が重複する。同じ Content の Title の登録数で検出し、開発ビルドで console.error）。別の Title で名前を付けるときだけ overlayTitle={false}（issue #727）"
       ]
     },
@@ -1981,7 +1990,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 を省いてよい。単一選択（radiogroup）はラベルを aria-labelledby で結ぶ（radiogroup は名前必須・外側の group の名前は継承されない。issue #741）。複数選択（role=group）は結ばず外側の group が名前を持つ（issue #734）。明示した指定が優先"
       ]
     },
     {
@@ -2862,6 +2872,8 @@
         "native は未提供（INTENTIONAL_NATIVE_GAPS）",
         "分類の識別色（カテゴリ別の予定）は 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）",
+        "見出しの右に置く部品（「月／週」の PillToggle size=\"sm\"・追加ボタン等）は MonthCalendarHeader trailing に渡す（前後の月ボタンの右・前後ボタンが無くても右側に出る）。見出しの外で flex を組んで並べない（issue #743）",
         "週の帯 ⇄ 月全体の開閉は MonthCalendarExpandToggle（expanded / onExpandedChange・読み上げ名は固定で状態は aria-expanded・aria-controls に MonthCalendar の id）を grid の下に置き、expanded を view=\"month\" / \"week\" に渡す。Button ghost icon-sm w-full で自作しない（issue #721）"
       ]
     },
@@ -3306,7 +3318,8 @@
         "暗色サイドバーは 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",
-        "上端の safe-area は safeAreaTop（ヘッダーは下線込み 64px + 安全領域、lg 以上のサイドバーと mobileDrawer のドロワーも上に足す。header が無いときは本文の列）。アプリ内で全画面に重ねるときは className=\"h-full\" と組み、外枠に pt-[var(--Safe-Area-Inset-Top)] や背景を書かない（外枠は fixed と重ね順だけ。issue #724）"
+        "上端の 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/token-hex-cache.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Semantic Token Hex Cache",
-    "version": "2.15.0",
+    "version": "2.17.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",