ksk-design-system 2.16.0 → 2.18.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.18.0 の導入注意
+
+以下はv2.18.0の導入注意です。consumerへの展開・アプリ配布は別工程で、次回のまとめ展開で反映します。
+
+- **FieldSet の見出しの下の間隔（#747・既定の見た目の変更）**: `gap` を省いた FieldSet でも、FieldLegend の下に子の間隔と同じ 24px（`mb-6`）が付きます（これまでは `gap` 指定時だけで、省くと見出しの直下が 0px でした）。見出しの下に `mb-*` / `pb-*` や空の要素を手で足していた場合は外してください。従来どおり見出しの直下を詰めたい画面は `<FieldLegend className="mb-0">` を指定してください（見出しの余白は詳細度 0 なので className が勝ちます）。子の間隔ごと詰めるなら `gap="sm"`（8px）/ `gap="md"`（16px）。FieldSet の className の `gap-*` では見出しの下は変わらないので、間隔は `gap` で指定してください。
+- **StarRating の読み上げ名（#746・既定の読み上げの変更）**: FormField `as="group"` の中で `label` / `aria-label` / `aria-labelledby` を省いた入力用の StarRating は、「評価」ではなくその FormField のラベルで読まれるようになります（radiogroup をラベルに `aria-labelledby` で結ぶ。ChipSelector 単一選択・PillToggle `semantics="radio"` と同じ）。見た目は変わりません。テストで `getByRole("radiogroup", { name: "評価" })` により group 内の StarRating を探している場合は、FormField のラベルで探してください。表示専用（`onChange` なし）は従来どおり値の要約（「4/5点」）で読まれます。native の StarRating は今回の対象外です（読み上げ文言・FormField との結び付けは変わりません）。
+- 追加のみ（Provider 無しの既定は不変）: StarRating の `aria-label` / `aria-labelledby`、KskLabels の `ratingGroup` / `ratingValue` / `ratingStar`（StarRating の既定文言。`{value}` / `{max}` を値に置き換える。`KskLabelsProvider locale="en"` で英語になる。型 `KskLabels` では optional なので、既存の完全な翻訳オブジェクトはそのまま型チェックを通る。全キー解決済みの型は `ResolvedKskLabels`。#746）。contracts の StarRating `sizes` に実装済みの `xl` を追加（#748）。
+
+## 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への展開・アプリ配布は別工程で、次回のまとめ展開で反映します。

package/RELEASE.md

@@ -2,6 +2,35 @@
 
 `ksk-design-system` のリリーススケジュール・運用ルール。
 
+## v2.18.0（2026-10-18）
+
+2.17.0以降に、FieldSet の見出し下の間隔と StarRating の読み上げ名を整えたminorリリース。次の2点は既定の見た目・読み上げが変わります。
+
+- `gap` を省いた FieldSet でも、FieldLegend の下に子の間隔と同じ24px（`mb-6`）が付きます。見出しの直下を詰めたい画面は `<FieldLegend className="mb-0">`、子の間隔ごと詰めるなら `gap="sm"` / `gap="md"` を指定します（#747）。
+- FormField `as="group"` の中で名前を省いた入力用の StarRating は、「評価」ではなくその FormField のラベルで読まれるようになります。見た目は変わりません。native の StarRating は対象外です（#746）。
+
+主な追加は次のとおりです。
+- StarRating に `aria-label` / `aria-labelledby`、KskLabels に `ratingGroup` / `ratingValue` / `ratingStar`（型では optional。#746）。
+- contracts の StarRating `sizes` に実装済みの `xl` を追加（#748）。
+
+導入時は [2.18.0の注意](./MIGRATION.md#v2180-の導入注意) を確認してください。npm公開・タグ・GitHub Releaseはversion変更のmainマージ後に `publish.yml` が実行します。consumerへの取り込みとアプリ配布は別工程で、今回のDS公開準備には含めません。
+
+## 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点は既定の見た目が変わります。

package/contracts/components.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "2.16.0",
+    "version": "2.18.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 73,
@@ -534,7 +534,7 @@
     {
       "name": "KskLabelsProvider",
       "path": "src/components/ui/ksk-labels.tsx",
-      "description": "DS 部品の既定文言（スキップリンク・管理画面のメニュー・FormField の必須/任意・閉じるボタン・NavigationBar の戻る/閉じる/シェア・カレンダー見出し）と MonthCalendar / AgendaList の locale 既定をまとめて切り替える Provider（issue #723）。アプリの一番外側に 1 回置く。",
+      "description": "DS 部品の既定文言（スキップリンク・管理画面のメニュー・FormField の必須/任意・閉じるボタン・NavigationBar の戻る/閉じる/シェア・カレンダー見出し・StarRating の読み上げ名）と MonthCalendar / AgendaList の locale 既定をまとめて切り替える Provider（issue #723）。アプリの一番外側に 1 回置く。",
       "subcomponents": [
         "useKskLabels",
         "useKskLocale",
@@ -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)"
       ]
     },
     {
@@ -843,16 +848,20 @@
       "sizes": [
         "sm",
         "md",
-        "lg"
+        "lg",
+        "xl"
       ],
       "props": {
         "allowClear": "boolean (既定 false) — 有効時、現在値と同じ星の再クリックで onChange(0)",
-        "label": "string (既定 \"評価\") — interactive 時の radiogroup aria-label",
-        "valueLabel": "(value: number, max: number) => string (既定 `${value}/${max}点`) — read-only 時の aria-label",
-        "starLabel": "(value: number) => string (既定 `${value}点`) — interactive 時の各星（radio）の aria-label"
+        "label": "string — interactive 時の radiogroup aria-label。省略時は FormField as=\"group\" の中ならそのラベルを aria-labelledby で結び、それ以外は KskLabels の ratingGroup（既定「評価」）(issue #746)",
+        "aria-label": "string — label と同じ（両方あればこちらが優先）(issue #746)",
+        "aria-labelledby": "string — interactive 時の radiogroup を見える見出しで名付ける。aria-label より優先 (issue #746)",
+        "valueLabel": "(value: number, max: number) => string (既定 KskLabels の ratingValue「{value}/{max}点」) — read-only 時の aria-label",
+        "starLabel": "(value: number) => string (既定 KskLabels の ratingStar「{value}点」) — interactive 時の各星（radio）の aria-label"
       },
       "rules": [
-        "Omit onChange for read-only display. Pass onChange for interactive input."
+        "Omit onChange for read-only display. Pass onChange for interactive input.",
+        "フォームの評価欄は FormField as=\"group\" で包む（radiogroup 自身をそのラベルで名付けるので label / aria-label は不要）。英語の画面は KskLabelsProvider locale=\"en\" で既定文言が切り替わる。星ごとに starLabel を渡して回らない (issue #746)"
       ],
       "accessibility": [
         "入力用（radio）の選択前の星は var(--Border-Control, var(--Border-Medium-Emphasis))。prefers-contrast: more / root の data-contrast=\"more\" のときだけ 3:1 以上に切り替わり、表示専用（role=img）の星は据え置き（issue #636）"
@@ -1472,7 +1481,8 @@
         "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 のみ）",
-        "閉じるボタンは onDismiss（右端の icon-sm ghost・読み上げ名は dismissLabel、既定は KskLabels の close）。閉じる処理は consumer が持つ。×ボタンを自作して並べない（issue #735）"
+        "閉じるボタンは 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 を明示した場合はそちらが優先"
       ]
     },
     {
@@ -1686,7 +1696,7 @@
         "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）"
+        "FormField as=\"group\" の中の radiogroup（ChipSelector single・PillToggle semantics=\"radio\"）は aria-label / aria-labelledby を省くとラベルを aria-labelledby で結ぶ（radiogroup は名前必須・外側の group の名前は継承されない。issue #741）。複数選択の ChipSelector と PillToggle tabs は結ばない（issue #734）"
       ]
     },
     {
@@ -1712,7 +1722,7 @@
         "FieldDescription はセクション・グループの補足、FieldError はグループ単位のエラーに使う",
         "グループ横断の区切りは FieldSeparator を使い、中央ラベルは children で渡す",
         "FormSection は title/description 一体の簡易 API、FieldSet は legend や複数 FieldGroup を明示構成する長いフォーム向け",
-        "詰めた並び（絞り込みシートの選択肢グループ等）は FieldSet gap（sm=8 / md=16 / lg=24px）+ FieldLegend size=\"sm\"（typo-label-md + Text-Medium-Emphasis）。className に space-y-* や typo-* を足して上書きしない。gap 指定時は legend の下にも同じ間隔が付く（未指定の既定は legend の直下 0px のまま）（issue #714）"
+        "詰めた並び（絞り込みシートの選択肢グループ等）は FieldSet gap（sm=8 / md=16 / lg=24px）+ FieldLegend size=\"sm\"（typo-label-md + Text-Medium-Emphasis）。className に space-y-* や typo-* を足して上書きしない。legend の下にも子と同じ間隔が付く（gap 未指定の既定も 24px。v2.17.0 までは未指定だと 0px だった）。legend の直下だけ詰めたいときは <FieldLegend className=\"mb-0\">（legend の余白は詳細度 0 なので className が勝つ）。className の gap-* では legend の下は変わらないので間隔は gap で指定する（issue #714 / #747）"
       ]
     },
     {
@@ -1884,6 +1894,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）"
       ]
     },
@@ -1984,7 +1995,7 @@
         "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",
-        "FormField as=\"group\" の中では aria-label / aria-labelledby を省いても警告が出ない（外側の group が名前を持つ）。明示した指定が優先（issue #734）"
+        "FormField as=\"group\" の中では aria-label / aria-labelledby を省いてよい。単一選択（radiogroup）はラベルを aria-labelledby で結ぶ（radiogroup は名前必須・外側の group の名前は継承されない。issue #741）。複数選択（role=group）は結ばず外側の group が名前を持つ（issue #734）。明示した指定が優先"
       ]
     },
     {
@@ -2866,6 +2877,7 @@
         "分類の識別色（カテゴリ別の予定）は 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）"
       ]
     },

package/contracts/token-hex-cache.json

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