ksk-design-system 1.70.0 → 2.0.1

package/AGENTS.md

@@ -50,8 +50,9 @@ UI を書く前に必ず確認すること:
 - [ ] **インタラクティブな部品は a11y 既定値を自分で持つか**。`accessibilityRole` と、状態（selected / disabled / checked）の `accessibilityState` 反映は**呼び出し側の義務にしない**。呼び出し側の明示値が優先される形で部品が既定を持つ（#311: Chip が role を持たず、スクリーンリーダーにただのテキストとして扱われた）
 - [ ] **モードを持つ部品（単一/複数選択・開閉など）の既定値は、間違えて使うと壊れる側にしていないか**。既定で済ませた呼び出しが静かに誤動作する組み合わせ（例: ChipSelector の既定 `multiple=true` を単一選択のつもりで使うと、押しても values[0] が現在値のまま切り替わらない）は、既定を安全側へ倒すか、必須 prop にして省略をコンパイルエラーにする
 - [ ] **名前付きスロット（meta / description 等）は「何を・どこに置くか」を JSDoc に書いたか**。書いていないスロットは consumer に流用され、想定外の位置崩れになる（#309: ActionTile の meta に選択チェックを入れられ、左下に浮いた）
+- [ ] **内部で要素を掴む部品は、consumer の `ref` を `useComposedRef` で合成したか**（`src/lib/compose-ref.ts`）。自前で `typeof ref === "function" ? ref(node) : ...` と書くと consumer のコールバック ref が返した cleanup を捨てる。インラインのアロー ref も毎 render で identity が変わり detach → attach を繰り返す（#510: dialog / responsive-overlay-frame / use-value-length / quick-action-grid の4か所で同じ型を出した）
 
-いずれも lint では拾えない設計判断なので、レビューではこの4点を明示的に見る。
+いずれも lint では拾えない設計判断なので、レビューではこの5点を明示的に見る。
 
 ---
 

package/CLAUDE.md

@@ -50,8 +50,9 @@ UI を書く前に必ず確認すること:
 - [ ] **インタラクティブな部品は a11y 既定値を自分で持つか**。`accessibilityRole` と、状態（selected / disabled / checked）の `accessibilityState` 反映は**呼び出し側の義務にしない**。呼び出し側の明示値が優先される形で部品が既定を持つ（#311: Chip が role を持たず、スクリーンリーダーにただのテキストとして扱われた）
 - [ ] **モードを持つ部品（単一/複数選択・開閉など）の既定値は、間違えて使うと壊れる側にしていないか**。既定で済ませた呼び出しが静かに誤動作する組み合わせ（例: ChipSelector の既定 `multiple=true` を単一選択のつもりで使うと、押しても values[0] が現在値のまま切り替わらない）は、既定を安全側へ倒すか、必須 prop にして省略をコンパイルエラーにする
 - [ ] **名前付きスロット（meta / description 等）は「何を・どこに置くか」を JSDoc に書いたか**。書いていないスロットは consumer に流用され、想定外の位置崩れになる（#309: ActionTile の meta に選択チェックを入れられ、左下に浮いた）
+- [ ] **内部で要素を掴む部品は、consumer の `ref` を `useComposedRef` で合成したか**（`src/lib/compose-ref.ts`）。自前で `typeof ref === "function" ? ref(node) : ...` と書くと consumer のコールバック ref が返した cleanup を捨てる。インラインのアロー ref も毎 render で identity が変わり detach → attach を繰り返す（#510: dialog / responsive-overlay-frame / use-value-length / quick-action-grid の4か所で同じ型を出した）
 
-いずれも lint では拾えない設計判断なので、レビューではこの4点を明示的に見る。
+いずれも lint では拾えない設計判断なので、レビューではこの5点を明示的に見る。
 
 ---
 

package/MIGRATION.md

@@ -17,11 +17,12 @@ npx ksk-ds check-migration ./src
 
 | API | 使われ方 | 移行先 | 非推奨にした版 | 削除予定 |
 | --- | --- | --- | --- | --- |
-| `ListItem.interactive` | `<ListItem interactive>` | href または onClick を ListItem 自体へ渡す | 1.46.0 | v2.0.0 |
-| `ChipSelector.multiple` | `<ChipSelector multiple>` | selectionMode（multiple={false} は selectionMode="single"、multiple は selectionMode="multiple"） | unreleased | v2.0.0 |
-| `PillToggle.onValueChange` | `<PillToggle onValueChange>` | onChange | 1.49.0 | v2.0.0 |
-| `ProductCard.deliveryLabel` | `<ProductCard deliveryLabel>` | なし（v1.30.0 以降は描画されないため、渡している箇所は削除する） | 1.30.1 | v2.0.0 |
-| `Progress.tone` | `<Progress tone>` | variant | 1.40.1 | v2.0.0 |
+| `ListItem.interactive` | `<ListItem interactive>` | href または onClick を ListItem 自体へ渡す | 1.46.0 | v3.0.0 |
+| `ChipSelector.multiple` | `<ChipSelector multiple>` | selectionMode（multiple={false} は selectionMode="single"、multiple は selectionMode="multiple"） | 2.0.0 | v3.0.0 |
+| `PillToggle.onValueChange` | `<PillToggle onValueChange>` | onChange | 1.49.0 | v3.0.0 |
+| `ProductCard.deliveryLabel` | `<ProductCard deliveryLabel>` | なし（v1.30.0 以降は描画されないため、渡している箇所は削除する） | 1.30.1 | v3.0.0 |
+| `Progress.tone` | `<Progress tone>` | variant | 1.40.1 | v3.0.0 |
+| `ProgressRing.thickness` | `<ProgressRing thickness>` | strokeWidth（Web の同名 prop と語彙を揃えた。値の意味・既定値 6 は同じ） | 2.0.0 | v3.0.0 |
 
 各エントリの補足:
 
@@ -30,6 +31,7 @@ npx ksk-ds check-migration ./src
 - **PillToggle.onValueChange**（issue #264） — 後方互換エイリアス。onChange を併せて渡した場合は onChange が優先される。 実装: src/components/ui/pill-toggle.tsx
 - **ProductCard.deliveryLabel** — 既存 consumer の型互換のためだけに残している no-op prop。 実装: src/components/patterns/commerce/product-card.tsx
 - **Progress.tone** — React Native 版のみ。既存 RN consumer 向けの互換。 実装: src/native/components/Progress.tsx
+- **ProgressRing.thickness**（issue #495） — Native だけが持っていた別名。同じ「線の太さ」を Web は strokeWidth と呼んでいたため、両方を触る実装者が読み替えを強いられていた。両方渡された場合は strokeWidth を優先する。 実装: src/native/components/ProgressRing.tsx
 
 削除は「全消費リポで `check-migration` の残件が 0」を条件に、`削除予定` のメジャーリリースで行います。
 
@@ -37,9 +39,31 @@ npx ksk-ds check-migration ./src
 
 ---
 
-## v2.0 (未リリース)
+## v2.0.0
 
-まだメジャー破壊変更の予定はなし。
+**破壊変更は peerDependencies の要件変更 1 点のみ。** 識別子 / prop の削除・rename は
+無いので、コードの書き換えも codemod も要りません。
+
+| 項目 | v1 系 | v2.0.0 |
+|---|---|---|
+| `react` / `react-dom` | `^18.0.0 \|\| ^19.0.0` | `^19.0.0` |
+| `react-native` | `>=0.74.0` | `>=0.78.0` |
+
+- **React 19 / RN 0.78 以上を使っている場合: 対応不要**。`npm install ksk-design-system@2`
+  で上げるだけで、API は v1.70 系＋今回の機能追加のまま
+- **React 18 のまま使いたい場合**: `ksk-design-system@^1` に固定してください。
+  v1 系に React 19 専用化は入っていません
+
+major にした理由は、`^1.x` を指定している React 18 利用者が自動で拾うと
+インストールが失敗しうるため（実装は元から React 19 の ref-as-prop 前提で、
+React 18 では `ref` が無言で無視されていた）。詳細は下の
+「peerDependencies の要件変更」節と issue #502 を参照。
+
+なお v1 系で非推奨にした prop（`ListItem.interactive` ほか 5 件）は
+**v2.0.0 では削除していません**。削除は「全消費リポで `check-migration` の
+残件が 0」を条件に v3.0.0 で行います。
+
+## v3.0 (未リリース)
 
 破壊変更を入れる際にはここに以下を書く:
 1. 削除した識別子 / prop の一覧（rename テーブル）
@@ -51,9 +75,48 @@ npx ksk-ds check-migration ./src
 
 ---
 
+## peerDependencies の要件変更（インストールに影響）
+
+### peerDependencies を React 19 のみに狭める（issue #502）
+
+**インストール要件が変わります。** `peerDependencies` を実装の実態に合わせました:
+
+| 依存 | 変更前 | 変更後 |
+|---|---|---|
+| `react` | `^18.0.0 \|\| ^19.0.0` | `^19.0.0` |
+| `react-dom` | `^18.0.0 \|\| ^19.0.0` | `^19.0.0` |
+| `react-native` | `>=0.74.0` | `>=0.78.0` |
+
+理由: `Input` / `Textarea` / `Dialog` / `QuickActionGrid` などは React 19 の
+ref-as-prop（関数コンポーネントが `ref` を通常の prop として受け取る仕様）で書かれており、
+`forwardRef` を一切使っていません。React 18 でこれらに `ref` を渡すと
+`Function components cannot be given refs` の警告が出て `ref` は呼ばれません。
+つまり `^18.0.0` の宣言は**もともと実態と合っていませんでした**。今回は嘘の互換宣言を消す
+だけで、React 19 の利用者にとってのコード変更はありません。
+
+`react-native` を `>=0.78.0` にしたのは、React 19 を同梱する最初の RN が 0.78 のため
+（0.74〜0.77 は React 18 系で、`react: ^19.0.0` と両立しません）。
+
+**移行手順**
+
+- React 19 / RN 0.78 以上を使っている場合: **対応不要**（DS を上げるだけ）
+- React 18 のまま使いたい場合: `ksk-design-system@^1` に固定するか、React 19 へ上げてください。
+  DS 側に React 18 互換の実装を残す予定はありません
+
+なお `examples/native-sandbox`（リポジトリ内の開発用サンドボックス。npm 配布物には含まれず、
+DS を npm から install もしません）は react-native-web 0.19 の都合で React 18 のままです。
+消費側の要件には影響しません。
+
+
+**リリース種別**: **v2.0.0（major）で公開**。ランタイム API は変わらず React 19 利用者には
+無影響だが、`^1.x` を指定している React 18 / RN 0.74〜0.77 の利用者が自動で拾うと
+install に失敗しうるため、SemVer どおり major に倒した。
+
+---
+
 ## v1 系内の minor 変更（参考）
 
-### 次のリリース — `ResponsiveOverlayFrame` に `preset="plain"` を追加（issue #486）
+### v1.70.0 — `ResponsiveOverlayFrame` に `preset="plain"` を追加（issue #486）
 
 `side="bottom"` の経路は必ず `BottomSheetFrame` の preset を通るため、
 `sm:`（640px 以上）でフロートカード化し、内側 padding も落ちる（`p-0`）。
@@ -99,7 +162,7 @@ npx ksk-ds check-migration ./src
 - `desktopPosition` は `"center"` / `"top"` のみ。`"fullscreen"` は plain の
   幅指定と噛み合わないため型で禁止している。
 
-### 次のリリース — `ResponsiveOverlayFrame` が float / float-glass シートを受けられるようになった（issue #479）
+### v1.69.0 — `ResponsiveOverlayFrame` が float / float-glass シートを受けられるようになった（issue #479）
 
 #472 で入った `ResponsiveOverlayFrame` は内部で `BottomSheetFrame`（`side="bottom"` 固定）を
 使うため、左右・下に余白を持つカード型のシート（`side="float"` / `"float-glass"`）を
@@ -163,7 +226,7 @@ global CSS（`!important`）を残す必要があった。
   `side="bottom"` 専用なので、`snapPoints` と float 系の併用は snap もデスクトップ変換も
   効かない「何も起きない」組み合わせになる。どちらかに寄せること。
 
-### 次のリリース — `ResponsiveOverlayFrame` 追加（`BottomSheetFrame` + 消費側デスクトップ CSS からの移行 / issue #472）
+### v1.67.0 — `ResponsiveOverlayFrame` 追加（`BottomSheetFrame` + 消費側デスクトップ CSS からの移行 / issue #472）
 
 `BottomSheetFrame` はモバイルの preset（`mobile-full` / `mobile-page` /
 `mobile-form`）を持つ一方でデスクトップでは中央モーダルにならず、消費側は
@@ -235,7 +298,7 @@ global CSS で `position` / `transform` / `width` / `max-height` / `radius` を
 既存の `BottomSheetFrame` / `ResponsiveDialogContent` は非推奨ではない
 （モバイル専用面・preset 不要の面では引き続きそのまま使う）。
 
-### 次のリリース — `typescript` が必須依存から optional peer dependency になった（issue #409）
+### v1.62.0 — `typescript` が必須依存から optional peer dependency になった（issue #409）
 
 CLI の1ルール（P046）のためだけに typescript（24MB）が全 consumer の
 node_modules に入っていたのを解消した。install サイズが減り、`ksk-ds lint` の
@@ -248,7 +311,7 @@ node_modules に入っていたのを解消した。install サイズが減り
   typescript を追加すること
 
 
-### 次のリリース — `ksk-ds lint` の severity 語彙が `warn` → `warning` に統一（要確認）
+### v1.62.0 — `ksk-ds lint` の severity 語彙が `warn` → `warning` に統一（要確認）
 
 `--format json` の `results[].severity` と text 出力の severity 表記が、これまで
 `"warn"` と `"warning"` で不統一だった（contract の `contracts/rules.json` は
@@ -272,7 +335,7 @@ text 出力の要約行も `0 error / 3 warn` → `0 error / 3 warning` に変
 - **未知のオプションはエラー終了**（従来は黙って捨てられ、CI に書いた
   `--strict` が無言で効かないまま緑になっていた）
 
-### 次のリリース — `ksk-ds lint` の escape がルール単位・行単位で書けるようになった
+### v1.62.0 — `ksk-ds lint` の escape がルール単位・行単位で書けるようになった
 
 ファイル全体・全ルールを無期限に外す `// ksk-ds-allow-custom-ui: 理由` は
 後方互換で残るが**非推奨**。新規はルール単位を使う（issue #405）:
@@ -288,7 +351,7 @@ ignore は効かない。あわせて escape マーカーは**文字列リテラ
 無効化されていた）。既に short な理由を書いていたファイルは lint が復活するので、
 理由を書き足すか違反を直すこと。
 
-### 次のリリース — 自動生成物と DS 自身のトークン CSS を lint 対象外にした
+### v1.62.0 — 自動生成物と DS 自身のトークン CSS を lint 対象外にした
 
 - 先頭 12 行に自動生成マーカー（`AUTO-GENERATED` / `DO NOT EDIT` / `自動生成` 等）を
   持つファイルは全ルールを skip する（issue #408）。直す先は生成物ではなく生成元。
@@ -296,7 +359,7 @@ ignore は効かない。あわせて escape マーカーは**文字列リテラ
   トークン定義 CSS を対象外にする（issue #407）。`vendor/ksk-design-system/**` のように
   DS を再梱包しているリポで P049 が大量に出ていたのが解消する。
 
-### 次のリリース — `Footer` の `paymentIcons` 既定値が空になった（挙動変更）
+### v1.62.0 — `Footer` の `paymentIcons` 既定値が空になった（挙動変更）
 
 `Footer` は `paymentIcons` を省略すると `["VISA", "Master", "JCB", "AmEx", "PayPay", "LINE Pay"]`
 の決済バッジを既定で描画していた。EC 以外のプロダクトでも「取り扱っていない決済手段」が
@@ -313,7 +376,7 @@ ignore は効かない。あわせて escape マーカーは**文字列リテラ
 
 `paymentIcons` を明示的に渡していた箇所は影響なし。
 
-### 次のリリース — `postinstall` による AI ルールファイル自動設置を廃止（要確認）
+### v1.60.0 — `postinstall` による AI ルールファイル自動設置を廃止（要確認）
 
 これまで `npm install ksk-design-system` の `postinstall` フックが、消費側の
 プロジェクトルートに `CLAUDE.md` / `AGENTS.md`（`node_modules` 内の DS ルールを指す
@@ -334,7 +397,7 @@ npx ksk-ds init --force  # 既存ファイルを最新テンプレートで上
 `postinstall` を持つ限りバージョンを上げても判定が引き継がれる。あわせて
 `INIT_CWD` 参照も削除し、書き込み先はコマンドを実行したディレクトリに固定した。
 
-### 次のリリース — PillToggle の onChange/onValueChange 統一（破壊変更なし）
+### v1.49.0 — PillToggle の onChange/onValueChange 統一（破壊変更なし）
 
 `PillToggle` のみ他コンポーネント（Switch 等の native 系を除く）と異なり `onValueChange`
 を主 API として案内していたため、`onChange` に統一した（issue #264⑥）。
@@ -351,7 +414,7 @@ npx ksk-ds init --force  # 既存ファイルを最新テンプレートで上
 `onChange` と `onValueChange` を両方渡した場合は `onChange` が優先される。
 `onValueChange` は将来のメジャーバージョンで削除予定。
 
-### 次のリリース — Tailwind 4.1 以上が必要（要確認）
+### v1.49.0 — Tailwind 4.1 以上が必要（要確認）
 
 preset に DS 内部ユーティリティの safelist（`src/styles/source-safelist.css`・自動生成）を同梱した（issue #258）。
 これにより、消費側の `@source ".../ksk-design-system/dist"` の設定漏れやパスずれで

package/README.md

@@ -42,6 +42,19 @@ Tailwind 4.1 で導入された `@source inline()` を使うため）
 
 ## 🚀 使い方
 
+### 動作要件
+
+**React 19 以上が必須です。** コンポーネントは React 19 の ref-as-prop（関数コンポーネントが
+`ref` を通常の prop として受け取る仕様）を前提に実装しているため、React 18 では
+`Function components cannot be given refs` の警告が出て `ref` が届きません（issue #502）。
+
+| 依存 | 必要バージョン |
+|---|---|
+| react / react-dom | `^19.0.0` |
+| react-native（Native を使う場合） | `>=0.78.0`（React 19 を同梱する最初の RN） |
+| tailwindcss（Web を使う場合） | `^3.4.17 \|\| ^4.1.0` |
+| typescript | `>=5.0.0` |
+
 ### Web (Next.js / Vite / 任意の React 環境)
 
 ```bash
@@ -392,6 +405,8 @@ import { BottomTabBar } from "ksk-design-system"
 
 ### React Native / Expo
 
+React Native は **0.78 以上**（React 19 を同梱する最初の RN）が必要です。
+
 `ksk-design-system/native/ui` から直接 RN 用コンポーネント export（134 個）を import できます。iOS 26 の **Liquid Glass** にも対応:
 
 ```tsx

package/bin/lint.js

@@ -394,31 +394,48 @@ export async function runLintCli(argv, { cwd = process.cwd(), pkgRoot = resolve(
   // 手書きファイルにマーカーを書けば lint を丸ごと回避できる構造のため、
   // 何が skip されたかを常に可視化して悪用をレビューで見つけられるようにする）。
   const generatedSkipped = []
+  // 列挙後に消えて読めなかったファイルも、generatedSkipped と同じ理由で
+  // 無言にしない（issue #498）。黙って飛ばすと、その1ファイルの違反が
+  // exit 0 のまま検査から抜け落ちたことに気づけない。
+  const missingSkipped = []
 
   for (const file of files) {
-    if (isAutoGeneratedSource(readFileSync(file, "utf8"))) {
-      generatedSkipped.push(normalize(relative(cwd, file)))
-      continue
-    }
-    if (CSS_EXTENSIONS.has(extname(file))) {
-      // productThemeContract が読めない環境（contracts/product-theme-overrides.json
-      // が無い）でも P050 は動かせるので、CSS ルールが 1 件でもあれば走査する
-      // （P049 側は contract が null なら lintCssFile 内で個別に skip する）。
-      if (cssRules.length > 0) {
-        findings.push(
-          ...lintCssFile(file, cwd, cssRules, productThemeContract, dsCssIdentity, pkgRoot),
-        )
+    // 列挙してから読むまでの間にファイルが消えることがある（issue #498）。
+    // watch ビルドや生成スクリプトと同時に lint を回すと現実に起きるため、
+    // ENOENT のときだけ静かに飛ばす（他のエラーは握り潰さず投げる）。
+    // lintFile / lintCssFile も内部で同じファイルを読み直すので、
+    // 1 ファイル分の処理をまとめて包む。
+    try {
+      if (isAutoGeneratedSource(readFileSync(file, "utf8"))) {
+        generatedSkipped.push(normalize(relative(cwd, file)))
+        continue
       }
-      continue
+      if (CSS_EXTENSIONS.has(extname(file))) {
+        // productThemeContract が読めない環境（contracts/product-theme-overrides.json
+        // が無い）でも P050 は動かせるので、CSS ルールが 1 件でもあれば走査する
+        // （P049 側は contract が null なら lintCssFile 内で個別に skip する）。
+        if (cssRules.length > 0) {
+          findings.push(
+            ...lintCssFile(file, cwd, cssRules, productThemeContract, dsCssIdentity, pkgRoot),
+          )
+        }
+        continue
+      }
+      findings.push(
+        ...lintFile(file, cwd, sourceRules, { ...options, inspectCardChildSpacing, pkgRoot }),
+      )
+    } catch (error) {
+      if (error && error.code === "ENOENT") {
+        missingSkipped.push(normalize(relative(cwd, file)))
+        continue
+      }
+      throw error
     }
-    findings.push(
-      ...lintFile(file, cwd, sourceRules, { ...options, inspectCardChildSpacing, pkgRoot }),
-    )
   }
 
   const summary = summarize(findings)
   if (options.format === "json") {
-    console.log(JSON.stringify({ results: findings, summary, generatedSkipped }, null, 2))
+    console.log(JSON.stringify({ results: findings, summary, generatedSkipped, missingSkipped }, null, 2))
   } else {
     printText(findings, summary)
     if (generatedSkipped.length > 0) {
@@ -428,6 +445,13 @@ export async function runLintCli(argv, { cwd = process.cwd(), pkgRoot = resolve(
           (generatedSkipped.length > 5 ? ` ほか ${generatedSkipped.length - 5} 件` : ""),
       )
     }
+    if (missingSkipped.length > 0) {
+      console.log(
+        `[ksk-ds lint] 走査中に読めなくなった ${missingSkipped.length} ファイルを skip: ` +
+          missingSkipped.slice(0, 5).join(", ") +
+          (missingSkipped.length > 5 ? ` ほか ${missingSkipped.length - 5} 件` : ""),
+      )
+    }
   }
 
   if (summary.errors > 0) return 1
@@ -611,7 +635,16 @@ function collectTargetFiles(cwd, targets, options) {
 function collect(abs, cwd, options, out) {
   const rel = normalize(relative(cwd, abs))
   if (shouldIgnorePath(rel, options)) return
-  const stat = statSync(abs)
+  // readdirSync で名前を得てから statSync するまでの間に消えることがある
+  // （issue #498。watch ビルドや生成スクリプトと同時に走らせたとき）。
+  // 列挙できなかったものは対象に入れない。他のエラーはそのまま投げる。
+  let stat
+  try {
+    stat = statSync(abs)
+  } catch (error) {
+    if (error && error.code === "ENOENT") return
+    throw error
+  }
   if (stat.isDirectory()) {
     for (const entry of readdirSync(abs)) {
       collect(join(abs, entry), cwd, options, out)

package/contracts/components.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "1.70.0",
+    "version": "2.0.1",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 68,
@@ -272,7 +272,7 @@
       "variants": [],
       "accessibility": [
         "Must pair with <Label>",
-        "native (src/native/components/CheckboxField.tsx, RadioGroup.tsx): accessibilityState に加え aria-checked / aria-disabled を既定で併記する（react-native-web 0.21 は accessibilityState を aria-* へ変換しないため。RN peerDependency >=0.74.0 の aria-* props を直接渡す）。行内の装飾用インナー Checkbox/丸印は aria-hidden も併記して二重の role=checkbox/radio を防ぐ"
+        "native (src/native/components/CheckboxField.tsx, RadioGroup.tsx): accessibilityState に加え aria-checked / aria-disabled を既定で併記する（react-native-web 0.21 は accessibilityState を aria-* へ変換しないため。RN peerDependency >=0.78.0 の aria-* props を直接渡す）。行内の装飾用インナー Checkbox/丸印は aria-hidden も併記して二重の role=checkbox/radio を防ぐ"
       ],
       "rules": [
         "label を渡すと <label> でラップされ行全体がクリッカブルになる",
@@ -372,8 +372,10 @@
         "safeArea(既定 true) で top/fullscreen の safe-area 回避を制御。false でオプトアウト",
         "autoFocus は first-input / title / ref / false を指定可能",
         "description prop は sr-only description を自動生成する",
+        "子として置いた DialogDescription は自動で aria-describedby に紐付く（#485）。呼び出し側で id / aria-describedby を明示した場合はそちらが優先。Description を置かないダイアログでは aria-describedby を出さない（Radix の Missing Description 警告抑制）",
         "DialogTitle は level=\"page\"|\"section\"|\"card\" で見出しの役割を指定する（値は contracts/composition.json の textHierarchy と1対1）。未指定時は position=\"fullscreen\" 配下で page 相当、それ以外は従来の typo-heading-lg",
-        "native (src/native/components/Dialog.tsx): position=\"center\"(既定) / \"top\" / \"fullscreen\" を持ち、fullscreen は四辺・top は上端の safe-area を避ける。実測 inset は SafeAreaInsetsProvider から供給し、未供給なら回避量 0（従来どおり）"
+        "native (src/native/components/Dialog.tsx): position=\"center\"(既定) / \"top\" / \"fullscreen\" を持ち、fullscreen は四辺・top は上端の safe-area を避ける。実測 inset は SafeAreaInsetsProvider から供給し、未供給なら回避量 0（従来どおり）",
+        "modal な Dialog の content は aria-modal=\"true\" を出力する（modal={false} では出さない）。開いているモーダルの横断判定は useHasOpenModal() / useOpenModalCount() を使い、consumer 側で data-state 等の内部属性を直接読まない（#505）"
       ],
       "variants": {
         "position": [
@@ -411,9 +413,11 @@
         "safeArea(既定 true) は上記2つの回避をまとめてオプトアウトする prop。他の side には効果なし",
         "autoFocus は first-input / title / ref / false を指定可能",
         "description prop はRadix管理IDの sr-only description を自動生成する",
+        "子として置いた SheetDescription は自動で aria-describedby に紐付く（#485）。呼び出し側で aria-describedby を明示した場合はそちらが優先。Description を置かないシートでは aria-describedby を出さない",
         "SheetTitle は level=\"page\"|\"section\"|\"card\" で見出しの役割を指定する（値は contracts/composition.json の textHierarchy と1対1）。未指定時は BottomSheetFrame preset=\"mobile-full\"|\"mobile-page\" 配下で page 相当、それ以外は従来の typo-heading-lg",
         "native (src/native/components/Sheet.tsx): safeArea(既定 true) で side=\"top\" の上端 inset 退避と、画面いっぱいに近い side=\"bottom\" の食い込み分の退避を行う。実測 inset は SafeAreaInsetsProvider から供給し、未供給なら回避量 0（従来どおり）",
-        "native (src/native/components/Sheet.tsx): surfaceColor でパネル（および snap モードの footer）の面色を上書きできる。未指定なら theme.surface.primary（従来どおり）。scrim の色は変えない（issue #448）"
+        "native (src/native/components/Sheet.tsx): surfaceColor でパネル（および snap モードの footer）の面色を上書きできる。未指定なら theme.surface.primary（従来どおり）。scrim の色は変えない（issue #448）",
+        "modal な Sheet の content は aria-modal=\"true\" を出力する（modal={false} では出さない）。開いているモーダルの横断判定は useHasOpenModal() / useOpenModalCount() を使い、consumer 側で data-state 等の内部属性を直接読まない（#505）"
       ],
       "variants": {
         "titleLevel": [
@@ -603,7 +607,8 @@
         "両 API は内部で同じ singleton store を共有するため、<Toaster> がある場合はそれを優先し auto-mounted viewport は描画しない",
         "新規 action prop で右側に CTA ボタン (元に戻す / 再試行 等) を表示できる",
         "保存完了・接続復旧・同期開始など一時的な操作結果は Banner ではなく toast.* helper を使う",
-        "connectionRestored / saveComplete / retryStarted / retryFailed helper を提供"
+        "connectionRestored / saveComplete / retryStarted / retryFailed helper を提供",
+        "viewport の下端 offset は product theme の公開変数 --Toast-Viewport-Offset-Bottom（既定 1rem = 従来の bottom-4）で調整する。下部タブバー / FAB と重なるプロダクトは :root で持ち上げる。[data-slot=\"toast-viewport\"] を消費側 CSS から直接狙わない（issue #503）"
       ],
       "props": {
         "Toaster.regionLabel": "string (既定 \"通知\") — viewport (role=\"region\") の aria-label（issue #428）",
@@ -620,15 +625,20 @@
     {
       "name": "ProgressRing",
       "path": "src/components/ui/progress-ring.tsx",
-      "description": "円形プログレス表示。SVGベース。0〜100の進捗を円弧で表示。中央にラベル（%またはカスタム）表示。",
+      "description": "円形プログレス表示。SVGベース。0〜100の進捗を円弧で表示。中央にラベル（%またはカスタム）表示。サイズはプリセット4種に加えて px 数値、線の太さは strokeWidth、配色は color / trackColor（semantic トークンのみ）で上書きできる（issue #480）。",
       "sizes": [
         "sm",
         "md",
         "lg",
-        "xl"
+        "xl",
+        "number(px)"
       ],
       "rules": [
-        "Use for circular progress only. Use <Progress> for linear progress bar."
+        "Use for circular progress only. Use <Progress> for linear progress bar.",
+        "size はまずプリセット（sm=32 / md=48 / lg=64 / xl=96px）から選ぶ。既存デザインの実寸に合わせる必要があるときだけ px の数値を渡す。",
+        "color / trackColor は semantic トークンの var(--...) 文字列のみ。生 hex と --Primitive-* は型で受け付けない（P015）。",
+        "strokeWidth が径の半分以上でも描画は消えず、描ける最大幅へ丸められる。",
+        "線の太さは Web / Native とも strokeWidth。Native の thickness は非推奨エイリアスで 3.0.0 で削除される（issue #495。2.0.0 では削除していない）。両方渡した場合は strokeWidth が優先される。"
       ]
     },
     {
@@ -656,9 +666,14 @@
         "sm",
         "md"
       ],
+      "props": {
+        "fullWidth": "boolean (既定 false) — 横幅いっぱいに広げ、各項目を等幅にする(issue #500)。既定はラベル幅(w-fit)"
+      },
       "rules": [
         "Use for 2-4 options only. 1行固定の segmented control で折り返せない。",
-        "5択以上・折り返しが要る単一選択は ChipSelector の selectionMode=\"single\" を使う(issue #418)。選択中の1つだけ見せて畳む場合は CollapsibleChipField(issue #419)。パネル連動が要るなら Tabs。"
+        "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 を当てないこと(見えている面がトラックより高くなる)。"
       ]
     },
     {
@@ -864,7 +879,8 @@
       "rules": [
         "Action に variant=destructive でデストラクティブCTA",
         "Cancel は variant=tertiary デフォルト",
-        "AlertDialog open時は既存Popoverを閉じ、stale layerを確認面の上に残さない"
+        "AlertDialog open時は既存Popoverを閉じ、stale layerを確認面の上に残さない",
+        "content は常に aria-modal=\"true\"（Radix の AlertDialog は非 modal にできない）。開いているモーダルの横断判定は useHasOpenModal() / useOpenModalCount()（#505）"
       ]
     },
     {
@@ -2023,15 +2039,24 @@
       "accessibility": [
         "role=dialog",
         "aria-modal",
-        "aria-label"
+        "aria-label",
+        "フォーカストラップ（Tab/Shift+Tab を面の中で循環）",
+        "Escape で離脱",
+        "閉じたら元の位置へフォーカス復帰"
       ],
       "rules": [
         "isCoachCompleted/markCoachCompleted で完了状態を永続化",
         "対象要素が見つからない step は画面中央フォールバック",
-        "ボタン文言・aria-label の i18n は labels prop で渡す（未指定は既定文言のまま・後方互換）"
+        "ボタン文言・aria-label の i18n は labels prop で渡す（未指定は既定文言のまま・後方互換）",
+        "autoFocus / restoreFocusOnClose / closeOnEsc は Dialog / Sheet と同じ prop 名・既定 true。Escape は onSkip（未指定なら onComplete）を呼ぶ",
+        "aria-modal=\"true\" を名乗るため、Tab/Shift+Tab を面の中に閉じ込める。トラップは Radix の FocusScope（trapped + loop）に載せる＝下に開いている Dialog / Sheet のスコープを pause できる。自前の document リスナーだとフォーカスの取り合いになり、下のモーダルへ引き戻される（issue #504）",
+        "バルーン（CoachMark の Content）は PortalContainerProvider で FocusScope の中へ描画する。スコープ外に出るとトラップの対象から外れる（issue #504）"
       ],
       "props": {
-        "labels": "{ next?, done?, skip?, ariaLabel? } — ボタン文言と overlay の aria-label。i18n はアプリ側で解決して渡す。done 未指定なら next にフォールバック（issue #477）"
+        "labels": "{ next?, done?, skip?, ariaLabel? } — ボタン文言と overlay の aria-label。i18n はアプリ側で解決して渡す。done 未指定なら next にフォールバック（issue #477）",
+        "autoFocus": "boolean (既定 true) — 表示時に最初の操作子へフォーカスを移す。false は「操作子を自動で選ばない」でフォーカスは面自体へ移る（外に置くとトラップが成立しないため）。Dialog / Sheet と違い ref は受けない（面の中に消費側の要素が無いため。issue #504）",
+        "restoreFocusOnClose": "boolean (既定 true) — 閉じたら開く前のフォーカス位置へ戻す（issue #504）",
+        "closeOnEsc": "boolean (既定 true) — Escape で onSkip（未指定なら onComplete）を呼ぶ（issue #504）"
       }
     },
     {
@@ -2243,7 +2268,8 @@
         "preset=\"plain\" は BottomSheetFrame を通さない素の bottom シート(全幅・下端固定・p-6・max-h-90dvh のまま)で、デスクトップだけ中央モーダル(32rem / min(90dvh,46rem))になる。padding が効く(issue #486)",
         "description / autoFocus / restoreFocusOnClose / closeOnEsc / zIndex を両分岐へ透過",
         "snap sheet はデスクトップでもシートのまま",
-        "ResponsiveOverlayFooter がモバイルのみキーボード追従になる"
+        "ResponsiveOverlayFooter がモバイルのみキーボード追従になる",
+        "デスクトップ(中央モーダル)分岐もソフトキーボードで max-height を縮める(issue #487)。幅 1024px 以上のタッチ端末(iPad 横向き)向け。JS(visualViewport)の inline style と html[data-kb-open] + --kb-h の CSS フォールバックの両方が効く。CSS フォールバックの --kb-h は「キーボードがビューポートを覆っている高さ」で、レイアウトビューポート自体が縮む環境(interactive-widget=resizes-content)では 0 のままにする(書くと二重に引いて面が潰れる)。JS 経路はキーボード高さを layoutHeight - (visualHeight + visualOffsetTop) * scale で求め、ピンチズーム由来の縮みを倍率で打ち消す(visualViewport はズームでも縮むため)。発火は編集可能な要素へのフォーカスをゲートにする"
       ],
       "rules": [
         "必ず <ResponsiveDialog> の子として使う(境界の判定は ResponsiveDialog の context が持つ)",
@@ -2252,6 +2278,8 @@
         "デスクトップ側にだけ効かせたい className は desktopClassName、モバイル側は mobileClassName を使う",
         "左右・下に余白を持つカード型のシートは side=\"float\"(Liquid Glass なら \"float-glass\")を使う。surface=\"glass\"(glass-strong)とは素材が別物で、float-glass との併用は型エラー(ガラスの二重適用防止)",
         "side / preset ごとに効く prop が判別ユニオンで分かれている: preset 経路は preset / surface / desktopPosition、float 系と preset=\"plain\" は padding。効かない組み合わせは黙って無視されずコンパイルエラーになる(型テスト test/types/responsive-overlay-frame.tsx)",
+        "デスクトップ分岐のキーボード補正は max-height だけで lift(bottom)は当てない。DialogContent は top:50% + translate-y:-50% で位置決めしているため bottom を足すと両拘束になり高さが縦一杯へ伸びる。中央寄せのキャップは 100dvh - 2*kb(100dvh - kb では下端がキーボードへ潜り込む。desktopPosition=\"top\" / \"fullscreen\" は上端固定なのでキーボード 1 回分 / #487)",
+        "3 つのデスクトップ分岐(preset / plain / float 系)はすべて data-frame=\"responsive-overlay-frame\" + data-side + data-position を出す。consumer が独自のキーボード補正を当てる場合もこの属性で絞る(#487)",
         "float-glass の実スクロールは src/styles/sheet-keyboard.css の :is(sheet-content, dialog-content)[data-side=\"float-glass\"] が担う。.glass-specular の overflow:hidden が非レイヤー CSS で className を踏み潰すため、className だけでは効かない(#337 / #479)"
       ],
       "subcomponents": [

package/contracts/deprecations.json

@@ -21,8 +21,8 @@
     },
     "policy": "エントリの削除条件は「全消費リポで check-migration の残件が 0」。削除は removeIn のメジャーリリースで行う。",
     "counts": {
-      "total": 5,
-      "prop": 5,
+      "total": 6,
+      "prop": 6,
       "export": 0
     }
   },
@@ -34,8 +34,10 @@
       "prop": "interactive",
       "since": "1.46.0",
       "replacement": "href または onClick を ListItem 自体へ渡す",
-      "removeIn": "2.0.0",
-      "sources": ["src/components/patterns/list-item.tsx"],
+      "removeIn": "3.0.0",
+      "sources": [
+        "src/components/patterns/list-item.tsx"
+      ],
       "issue": "#207",
       "note": "外側の Link / button でラップする既存コードの視覚互換用に残している。"
     },
@@ -44,9 +46,9 @@
       "kind": "prop",
       "component": "ChipSelector",
       "prop": "multiple",
-      "since": "unreleased",
+      "since": "2.0.0",
       "replacement": "selectionMode（multiple={false} は selectionMode=\"single\"、multiple は selectionMode=\"multiple\"）",
-      "removeIn": "2.0.0",
+      "removeIn": "3.0.0",
       "sources": [
         "src/components/patterns/chip-selector.tsx",
         "src/native/components/ChipSelector.tsx"
@@ -61,8 +63,10 @@
       "prop": "onValueChange",
       "since": "1.49.0",
       "replacement": "onChange",
-      "removeIn": "2.0.0",
-      "sources": ["src/components/ui/pill-toggle.tsx"],
+      "removeIn": "3.0.0",
+      "sources": [
+        "src/components/ui/pill-toggle.tsx"
+      ],
       "issue": "#264",
       "note": "後方互換エイリアス。onChange を併せて渡した場合は onChange が優先される。"
     },
@@ -73,8 +77,10 @@
       "prop": "deliveryLabel",
       "since": "1.30.1",
       "replacement": "なし（v1.30.0 以降は描画されないため、渡している箇所は削除する）",
-      "removeIn": "2.0.0",
-      "sources": ["src/components/patterns/commerce/product-card.tsx"],
+      "removeIn": "3.0.0",
+      "sources": [
+        "src/components/patterns/commerce/product-card.tsx"
+      ],
       "note": "既存 consumer の型互換のためだけに残している no-op prop。"
     },
     {
@@ -84,9 +90,25 @@
       "prop": "tone",
       "since": "1.40.1",
       "replacement": "variant",
-      "removeIn": "2.0.0",
-      "sources": ["src/native/components/Progress.tsx"],
+      "removeIn": "3.0.0",
+      "sources": [
+        "src/native/components/Progress.tsx"
+      ],
       "note": "React Native 版のみ。既存 RN consumer 向けの互換。"
+    },
+    {
+      "id": "ProgressRing.thickness",
+      "kind": "prop",
+      "component": "ProgressRing",
+      "prop": "thickness",
+      "since": "2.0.0",
+      "replacement": "strokeWidth（Web の同名 prop と語彙を揃えた。値の意味・既定値 6 は同じ）",
+      "removeIn": "3.0.0",
+      "sources": [
+        "src/native/components/ProgressRing.tsx"
+      ],
+      "issue": "#495",
+      "note": "Native だけが持っていた別名。同じ「線の太さ」を Web は strokeWidth と呼んでいたため、両方を触る実装者が読み替えを強いられていた。両方渡された場合は strokeWidth を優先する。"
     }
   ]
 }