ksk-design-system 2.0.0 → 2.1.0

package/AGENTS.md

@@ -279,6 +279,9 @@ npm run lint:design
 # 非推奨 API 台帳の整合検査（台帳 ⇔ 実ソースの @deprecated JSDoc）
 npm run lint:deprecations
 
+# `Closes #N` 誤リンク監査（gh 必須。npm run check には入っていない）
+npm run audit:issue-links -- --recent 60
+
 # MIGRATION.md の「非推奨 API 一覧」節を台帳から再生成
 npm run generate:migration-doc
 
@@ -293,8 +296,25 @@ npm run test:interaction
 
 # a11y 機械検証（axe-core。全ストーリー対象。issue #261）
 npm run test:a11y
+
+# 旧 Radix 固定の回帰テスト（consumer が古い Radix を掴む条件を再現。issue #516）
+npm run test:legacy-radix
 ```
 
+**`Closes #N` 誤リンク監査について（issue #486 が由来）:**
+
+- PR 本文の `Closes #N` が**別 issue を閉じてしまう**事故を検出する。実例:
+  PR #488 が `Closes #486` を書きながら実装したのは ResponsiveOverlayFrame で、
+  issue #486（BottomTabBar pill の面）は**未実装のまま自動クローズ**され、
+  消費側がリリースされない要望を待ち続けていた。
+- 判定は `contracts/components.json` のコンポーネント名を語彙にして、
+  「PR が触った / 言及したコンポーネント」と「issue が指すコンポーネント」に
+  共通要素が 1 つも無ければ疑う。どちらかが空（インフラ・トークン系）なら
+  判定材料なしとして黙って飛ばす — **見逃してでも誤検知を出さない**方針。
+- `gh` CLI（ネットワーク）が要るため `npm run check` には**含めない**。
+  リリース前の棚卸しと、疑わしい PR を見つけたときに手で回す。
+- 単発検査は `npm run audit:issue-links -- --pr 488`。
+
 **interaction テストについて（issue #256）:**
 
 - 実体は Storybook の play 関数。`@storybook/addon-vitest` + vitest browser mode（playwright chromium）で
@@ -325,6 +345,20 @@ npm run test:a11y
   `eslint/icon-button-aria-label.js`（`ksk-a11y/icon-button-aria-label`）で lint 時に検出する
   （`.stories.tsx` は対象外）。
 
+**旧 Radix 回帰テストについて（issue #516）:**
+
+- DS の node_modules は ref churn 修正済みの Radix を解決するため、`npm test` では
+  「consumer が古い Radix を掴んだときだけ落ちる」種類の回帰を**原理的に再現できない**
+  （#516 は belle-todo で初めて表面化した）。
+- `npm run test:legacy-radix` は当時 belle-todo が解決していた radix-ui@1.4.3 を
+  `node_modules/.ksk-legacy-radix` へ install し、`vitest.legacy-radix.config.ts` の
+  alias でそちらを掴ませて `test/legacy-radix/` を回す。CI では常時実行。
+- 併せて `package.json` の `radix-ui` / `@radix-ui/react-slot` の下限を安全版へ固定して
+  いる（`scripts/check-radix-floor.mjs` が `npm run check` で検査。正本データと版ごとの
+  差分は `scripts/radix-ref-churn.mjs`）。
+- **オーバーレイ系（Dialog / Sheet / ResponsiveOverlayFrame）や `useComposedRef` を
+  触ったら `npm run test:legacy-radix` を回すこと。**
+
 ---
 
 ## カラートークン体系（3層構造）

package/CLAUDE.md

@@ -279,6 +279,9 @@ npm run lint:design
 # 非推奨 API 台帳の整合検査（台帳 ⇔ 実ソースの @deprecated JSDoc）
 npm run lint:deprecations
 
+# `Closes #N` 誤リンク監査（gh 必須。npm run check には入っていない）
+npm run audit:issue-links -- --recent 60
+
 # MIGRATION.md の「非推奨 API 一覧」節を台帳から再生成
 npm run generate:migration-doc
 
@@ -293,8 +296,25 @@ npm run test:interaction
 
 # a11y 機械検証（axe-core。全ストーリー対象。issue #261）
 npm run test:a11y
+
+# 旧 Radix 固定の回帰テスト（consumer が古い Radix を掴む条件を再現。issue #516）
+npm run test:legacy-radix
 ```
 
+**`Closes #N` 誤リンク監査について（issue #486 が由来）:**
+
+- PR 本文の `Closes #N` が**別 issue を閉じてしまう**事故を検出する。実例:
+  PR #488 が `Closes #486` を書きながら実装したのは ResponsiveOverlayFrame で、
+  issue #486（BottomTabBar pill の面）は**未実装のまま自動クローズ**され、
+  消費側がリリースされない要望を待ち続けていた。
+- 判定は `contracts/components.json` のコンポーネント名を語彙にして、
+  「PR が触った / 言及したコンポーネント」と「issue が指すコンポーネント」に
+  共通要素が 1 つも無ければ疑う。どちらかが空（インフラ・トークン系）なら
+  判定材料なしとして黙って飛ばす — **見逃してでも誤検知を出さない**方針。
+- `gh` CLI（ネットワーク）が要るため `npm run check` には**含めない**。
+  リリース前の棚卸しと、疑わしい PR を見つけたときに手で回す。
+- 単発検査は `npm run audit:issue-links -- --pr 488`。
+
 **interaction テストについて（issue #256）:**
 
 - 実体は Storybook の play 関数。`@storybook/addon-vitest` + vitest browser mode（playwright chromium）で
@@ -325,6 +345,20 @@ npm run test:a11y
   `eslint/icon-button-aria-label.js`（`ksk-a11y/icon-button-aria-label`）で lint 時に検出する
   （`.stories.tsx` は対象外）。
 
+**旧 Radix 回帰テストについて（issue #516）:**
+
+- DS の node_modules は ref churn 修正済みの Radix を解決するため、`npm test` では
+  「consumer が古い Radix を掴んだときだけ落ちる」種類の回帰を**原理的に再現できない**
+  （#516 は belle-todo で初めて表面化した）。
+- `npm run test:legacy-radix` は当時 belle-todo が解決していた radix-ui@1.4.3 を
+  `node_modules/.ksk-legacy-radix` へ install し、`vitest.legacy-radix.config.ts` の
+  alias でそちらを掴ませて `test/legacy-radix/` を回す。CI では常時実行。
+- 併せて `package.json` の `radix-ui` / `@radix-ui/react-slot` の下限を安全版へ固定して
+  いる（`scripts/check-radix-floor.mjs` が `npm run check` で検査。正本データと版ごとの
+  差分は `scripts/radix-ref-churn.mjs`）。
+- **オーバーレイ系（Dialog / Sheet / ResponsiveOverlayFrame）や `useComposedRef` を
+  触ったら `npm run test:legacy-radix` を回すこと。**
+
 ---
 
 ## カラートークン体系（3層構造）

package/MIGRATION.md

@@ -116,7 +116,7 @@ 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`）。
@@ -162,7 +162,7 @@ install に失敗しうるため、SemVer どおり major に倒した。
 - `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"`）を
@@ -226,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`）を持つ一方でデスクトップでは中央モーダルにならず、消費側は
@@ -298,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` の
@@ -311,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` は
@@ -335,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）:
@@ -351,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）。直す先は生成物ではなく生成元。
@@ -359,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 以外のプロダクトでも「取り扱っていない決済手段」が
@@ -376,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 ルールを指す
@@ -397,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⑥）。
@@ -414,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/UPDATING.md

@@ -202,6 +202,23 @@ publish 直後は registry への反映に数分かかることがあるため
 `package.json#peerDependencies` の範囲を確認し、警告の対象パッケージ自体を先に更新してから
 `ksk-design-system` を上げる。警告を `--force` / `--legacy-peer-deps` で握りつぶして進めない。
 
+### Radix の版が古いまま固定されている（`Maximum update depth exceeded`）
+
+DS の依存 `radix-ui` は **`^1.6.1`**（#516 対応以降）。1.6.1 未満の Radix は
+合成 ref（`composeRefs`）を毎 render 作り直すため、DS のオーバーレイ面（Dialog / Sheet /
+ResponsiveOverlayFrame）が再描画を無限に誘発することがある（issue #516。belle-todo が
+radix-ui@1.4.3 を解決していて踏んだ）。
+
+症状が出たら、消費リポで実際に解決されている版を確認する:
+
+```bash
+npm ls radix-ui @radix-ui/react-focus-scope @radix-ui/react-presence
+```
+
+`radix-ui@1.6.1` 未満が出る場合は lockfile が古い版を固定している。`npm install` で
+DS の下限に追随させる（`overrides` で Radix を固定しているなら、その固定を外すか
+1.6.1 以上へ上げる）。
+
 ### Issue 起票先
 
 DS 本体のバグ・想定外の破壊変更に遭遇した場合は、

package/contracts/components.json

@@ -1,7 +1,7 @@
 {
   "meta": {
     "name": "KSK Design System — Component Contracts",
-    "version": "2.0.0",
+    "version": "2.1.0",
     "description": "全コンポーネントの構造化定義。バリアント・アクセシビリティ要件・使用ルールを機械可読形式で管理。",
     "counts": {
       "ui": 68,

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 も変わらない。"
+    "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 にして生成させない）を併せて宣言する。"
   },
   "allowedVariables": {
     "brandColor": [
@@ -165,6 +165,11 @@
       "--Nav-Pill-Padding-X",
       "--Nav-Pill-Padding-Y",
       "--Nav-Pill-Gap",
+      "--Nav-Pill-Surface",
+      "--Nav-Pill-Backdrop",
+      "--Nav-Pill-Border",
+      "--Nav-Pill-Shadow",
+      "--Nav-Pill-Specular",
       "--Nav-Item-Min-Height",
       "--Nav-Item-Gap",
       "--Nav-Center-Action-Size",
@@ -267,9 +272,15 @@
       "--Nav-Center-Action-*",
       "--Nav-Selected-*"
     ],
-    "ResponsiveDialog": ["--Overlay-Desktop-Breakpoint"],
-    "ResponsiveOverlayFrame": ["--Overlay-Desktop-Breakpoint"],
-    "Toast": ["--Toast-Viewport-Offset-Bottom"]
+    "ResponsiveDialog": [
+      "--Overlay-Desktop-Breakpoint"
+    ],
+    "ResponsiveOverlayFrame": [
+      "--Overlay-Desktop-Breakpoint"
+    ],
+    "Toast": [
+      "--Toast-Viewport-Offset-Bottom"
+    ]
   },
   "aiGuidance": [
     "プロダクト差分は、まずこの契約の CSS 変数上書きで表現する。className での個別上書きを何十箇所にも散らさない。",

package/contracts/token-hex-cache.json

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

package/dist/index.js

@@ -1022,13 +1022,30 @@ function $t(e, t) {
 	e && typeof e == "object" && (e.current = t);
 }
 function en(e, t) {
-	return u.useCallback((n) => {
-		e(n);
-		let r = $t(t, n);
-		return () => {
-			e(null), r ? r() : $t(t, null);
+	let n = u.useRef(e), r = u.useRef(t), i = u.useRef(null), a = u.useRef(null), o = u.useRef(null), s = u.useCallback(() => {
+		let e = o.current;
+		e && (o.current = null, e.cleanup ? e.cleanup() : $t(e.ref, null));
+	}, []), c = u.useCallback((e, t) => {
+		o.current = {
+			ref: e,
+			cleanup: $t(e, t)
 		};
-	}, [e, t]);
+	}, []);
+	return u.useInsertionEffect(() => {
+		n.current = e, r.current = t;
+		let l = i.current;
+		if (l != null) {
+			if (a.current !== e) {
+				let t = a.current;
+				a.current = e, t?.(null), e(l);
+			}
+			o.current?.ref !== t && (s(), c(t, l));
+		}
+	}), u.useCallback((e) => (i.current = e, a.current = e == null ? null : n.current, n.current(e), s(), e != null && c(r.current, e), () => {
+		i.current = null;
+		let e = a.current;
+		a.current = null, e?.(null), s();
+	}), [c, s]);
 }
 //#endregion
 //#region src/lib/title-level.tsx
@@ -12689,8 +12706,8 @@ function of(e) {
 }
 var sf = "min(85dvh, 46rem)", cf = "min(90dvh, 46rem)";
 function lf(e, t, n) {
-	let r = u.useRef(null), [i, a] = u.useState(0), o = u.useCallback((e) => {
-		r.current = e, a((e) => e + 1);
+	let r = u.useRef(null), [i, a] = u.useState(null), o = u.useCallback((e) => {
+		r.current = e, a(e);
 	}, []), [s, c] = u.useState();
 	return u.useLayoutEffect(() => {
 		let n = r.current;
@@ -13072,8 +13089,8 @@ function Ef(e) {
 		liftInset: e === "lift" ? t : 0
 	};
 }
-function Df({ className: e, items: t, centerAction: n, showLabels: r, tone: i = "default", maxWidth: a, variant: o = "default", pillPosition: s = "fixed", floatingPosition: c = "center", keyboardBehavior: l = "stay", scrollEdge: u = !1, navLabel: d = "メインナビゲーション", ...f }) {
-	let p = Ef(l);
+function Df({ className: e, items: t, centerAction: n, showLabels: r, tone: i = "default", maxWidth: a, variant: o = "default", pillPosition: s = "fixed", floatingPosition: c = "center", keyboardBehavior: l = "stay", scrollEdge: u = !1, navLabel: d = "メインナビゲーション", showOnDesktop: f = !1, ...p }) {
+	let m = Ef(l);
 	return o === "pill" ? /* @__PURE__ */ B(kf, {
 		className: e,
 		items: t,
@@ -13084,29 +13101,31 @@ function Df({ className: e, items: t, centerAction: n, showLabels: r, tone: i =
 		pillPosition: s,
 		floatingPosition: c,
 		scrollEdge: u,
-		keyboardState: p,
+		keyboardState: m,
 		navLabel: d,
-		...f
+		showOnDesktop: f,
+		...p
 	}) : /* @__PURE__ */ B(Of, {
 		className: e,
 		items: t,
-		keyboardState: p,
+		keyboardState: m,
 		navLabel: d,
-		...f
+		showOnDesktop: f,
+		...p
 	});
 }
-function Of({ className: e, items: t, keyboardState: n, style: r, navLabel: i = "メインナビゲーション", ...a }) {
+function Of({ className: e, items: t, keyboardState: n, style: r, navLabel: i = "メインナビゲーション", showOnDesktop: a = !1, ...o }) {
 	return /* @__PURE__ */ B("nav", {
 		"data-slot": "bottom-tab-bar",
 		"data-keyboard-behavior": n.keyboardBehavior,
 		"data-keyboard-open": n.isKeyboardOpen || void 0,
 		"aria-label": i,
-		className: G("fixed inset-x-0 z-[var(--Z-Nav)] transition-all duration-[var(--Motion-Duration-Base)]", n.keyboardBehavior === "lift" ? "bottom-[var(--ksk-bottom-tab-bar-keyboard-inset)]" : "bottom-0", "border-t border-[var(--Border-Low-Emphasis)] bg-[var(--Surface-Primary)]", "pb-[env(safe-area-inset-bottom)] lg:hidden", n.shouldHide && "translate-y-2 opacity-0 pointer-events-none invisible", e),
+		className: G("fixed inset-x-0 z-[var(--Z-Nav)] transition-all duration-[var(--Motion-Duration-Base)]", n.keyboardBehavior === "lift" ? "bottom-[var(--ksk-bottom-tab-bar-keyboard-inset)]" : "bottom-0", "border-t border-[var(--Border-Low-Emphasis)] bg-[var(--Surface-Primary)]", "pb-[env(safe-area-inset-bottom)]", a ? "lg:block" : "lg:hidden", n.shouldHide && "translate-y-2 opacity-0 pointer-events-none invisible", e),
 		style: {
 			"--ksk-bottom-tab-bar-keyboard-inset": `${n.liftInset}px`,
 			...r
 		},
-		...a,
+		...o,
 		children: /* @__PURE__ */ B("div", {
 			className: "flex h-14 items-center justify-around px-1",
 			children: t.map((e) => /* @__PURE__ */ B(Af, {
@@ -13116,17 +13135,17 @@ function Of({ className: e, items: t, keyboardState: n, style: r, navLabel: i =
 		})
 	});
 }
-function kf({ className: e, items: t, centerAction: n, showLabels: r, tone: i = "default", maxWidth: a = 430, pillPosition: o = "fixed", floatingPosition: s = "center", scrollEdge: c = !1, keyboardState: l, style: d, navLabel: f = "メインナビゲーション", ...p }) {
-	let m = !!n || r === !0, h = r ?? !!n, g = n ? Math.ceil(t.length / 2) : t.length, _ = t.slice(0, g), v = t.slice(g), y = u.useRef(null), [b, x] = u.useState(null), [S, C] = u.useState(!1), w = u.useCallback(() => {
-		let e = y.current;
+function kf({ className: e, items: t, centerAction: n, showLabels: r, tone: i = "default", maxWidth: a = 430, pillPosition: o = "fixed", floatingPosition: s = "center", scrollEdge: c = !1, keyboardState: l, style: d, navLabel: f = "メインナビゲーション", showOnDesktop: p = !1, ...m }) {
+	let h = !!n || r === !0, g = r ?? !!n, _ = n ? Math.ceil(t.length / 2) : t.length, v = t.slice(0, _), y = t.slice(_), b = u.useRef(null), [x, S] = u.useState(null), [C, w] = u.useState(!1), T = u.useCallback(() => {
+		let e = b.current;
 		if (!e) return;
 		let t = e.querySelector("[data-platter-anchor]");
 		if (!t) {
-			x(null);
+			S(null);
 			return;
 		}
 		let n = e.getBoundingClientRect(), r = t.getBoundingClientRect();
-		x((e) => {
+		S((e) => {
 			let t = {
 				x: r.left - n.left,
 				y: r.top - n.top,
@@ -13136,66 +13155,66 @@ function kf({ className: e, items: t, centerAction: n, showLabels: r, tone: i =
 			return e && Math.abs(e.x - t.x) < .5 && Math.abs(e.y - t.y) < .5 && Math.abs(e.w - t.w) < .5 && Math.abs(e.h - t.h) < .5 ? e : t;
 		});
 	}, []);
-	Tf(w), u.useEffect(() => {
-		if (b && !S) {
-			let e = requestAnimationFrame(() => C(!0));
+	Tf(T), u.useEffect(() => {
+		if (x && !C) {
+			let e = requestAnimationFrame(() => w(!0));
 			return () => cancelAnimationFrame(e);
 		}
-	}, [b, S]), u.useEffect(() => {
-		let e = y.current;
+	}, [x, C]), u.useEffect(() => {
+		let e = b.current;
 		if (!e || typeof ResizeObserver > "u") return;
-		let t = new ResizeObserver(w);
+		let t = new ResizeObserver(T);
 		return t.observe(e), () => t.disconnect();
-	}, [w]);
-	let T = s === "left" || s === "right", E = {
+	}, [T]);
+	let E = s === "left" || s === "right", D = {
 		"--ksk-bottom-tab-bar-keyboard-inset": `${l.liftInset}px`,
-		...m && !T ? {
+		...h && !E ? {
 			width: "calc(100vw - 24px)",
 			maxWidth: a
 		} : {},
-		...T ? { maxWidth: "calc(100vw - 92px)" } : {},
+		...E ? { maxWidth: "calc(100vw - 92px)" } : {},
 		...d
 	};
 	return /* @__PURE__ */ V(z, { children: [c && /* @__PURE__ */ B("div", {
 		"aria-hidden": "true",
-		className: G("inset-x-0 bottom-0 z-[var(--Z-Sticky)] h-28 lg:hidden", "glass-scroll-edge-bottom", "transition-opacity duration-[var(--Motion-Duration-Base)]", o === "fixed" ? "fixed" : "absolute", l.shouldHide && "opacity-0")
+		className: G("inset-x-0 bottom-0 z-[var(--Z-Sticky)] h-28", p ? "lg:block" : "lg:hidden", "glass-scroll-edge-bottom", "transition-opacity duration-[var(--Motion-Duration-Base)]", o === "fixed" ? "fixed" : "absolute", l.shouldHide && "opacity-0")
 	}), /* @__PURE__ */ V("nav", {
 		"data-slot": "bottom-nav-pill",
 		"data-tone": i,
 		"data-keyboard-behavior": l.keyboardBehavior,
 		"data-keyboard-open": l.isKeyboardOpen || void 0,
 		"aria-label": f,
-		className: G("z-[var(--Z-Nav)] lg:hidden transition-all duration-[var(--Motion-Duration-Base)]", o === "fixed" ? "fixed" : "absolute", l.keyboardBehavior === "lift" ? "bottom-[calc(env(safe-area-inset-bottom)_+_12px_+_var(--ksk-bottom-tab-bar-keyboard-inset))]" : "bottom-[calc(env(safe-area-inset-bottom)_+_12px)]", s === "left" && "left-3 right-20", s === "right" && "right-3 left-20", s === "center" && "left-1/2 -translate-x-1/2", "flex items-center rounded-full glass-specular", i === "inverse" ? "glass-dark" : "glass", m ? "min-h-[var(--Nav-Pill-Min-Height)] gap-[var(--Nav-Pill-Gap)] px-[var(--Nav-Pill-Padding-X)] py-[var(--Nav-Pill-Padding-Y)]" : "h-[58px] gap-0 px-3", l.shouldHide && "translate-y-2 opacity-0 pointer-events-none invisible", e),
-		style: E,
-		...p,
-		ref: y,
+		className: G("z-[var(--Z-Nav)] transition-all duration-[var(--Motion-Duration-Base)]", p ? "lg:flex" : "lg:hidden", o === "fixed" ? "fixed" : "absolute", l.keyboardBehavior === "lift" ? "bottom-[calc(env(safe-area-inset-bottom)_+_12px_+_var(--ksk-bottom-tab-bar-keyboard-inset))]" : "bottom-[calc(env(safe-area-inset-bottom)_+_12px)]", s === "left" && "left-3 right-20", s === "right" && "right-3 left-20", s === "center" && "left-1/2 -translate-x-1/2", "flex items-center rounded-full glass-specular", i === "inverse" ? "glass-dark" : "glass", h ? "min-h-[var(--Nav-Pill-Min-Height)] gap-[var(--Nav-Pill-Gap)] px-[var(--Nav-Pill-Padding-X)] py-[var(--Nav-Pill-Padding-Y)]" : "h-[58px] gap-0 px-3", l.shouldHide && "translate-y-2 opacity-0 pointer-events-none invisible", e),
+		style: D,
+		...m,
+		ref: b,
 		children: [
-			b && /* @__PURE__ */ B("span", {
+			x && /* @__PURE__ */ B("span", {
 				"aria-hidden": "true",
 				"data-slot": wf,
 				"data-nav-platter": !0,
-				className: G("absolute left-0 top-0 rounded-full pointer-events-none", S && "transition-[transform,width,height] duration-[var(--Motion-Duration-Base)] ease-[var(--Motion-Easing-Standard)] motion-reduce:transition-none"),
+				className: G("absolute left-0 top-0 rounded-full pointer-events-none", C && "transition-[transform,width,height] duration-[var(--Motion-Duration-Base)] ease-[var(--Motion-Easing-Standard)] motion-reduce:transition-none"),
 				style: {
-					width: b.w,
-					height: b.h,
-					transform: `translate3d(${b.x}px, ${b.y}px, 0)`
+					width: x.w,
+					height: x.h,
+					transform: `translate3d(${x.x}px, ${x.y}px, 0)`
 				}
 			}),
-			_.map((e, t) => /* @__PURE__ */ B(Af, {
+			v.map((e, t) => /* @__PURE__ */ B(Af, {
 				item: e,
 				compact: !0,
-				showLabel: h,
+				showLabel: g,
 				tone: i,
-				suppressPlatter: b !== null
+				suppressPlatter: x !== null
 			}, `${e.href ?? e.label}-${t}`)),
 			n ? /* @__PURE__ */ B(jf, { item: n }) : null,
-			v.map((e, t) => /* @__PURE__ */ B(Af, {
+			y.map((e, t) => /* @__PURE__ */ B(Af, {
 				item: e,
 				compact: !0,
-				showLabel: h,
+				showLabel: g,
 				tone: i,
-				suppressPlatter: b !== null
-			}, `${e.href ?? e.label}-${t + g}`))
+				suppressPlatter: x !== null
+			}, `${e.href ?? e.label}-${t + _}`))
 		]
 	})] });
 }
@@ -13265,11 +13284,11 @@ function Mf() {
 		})
 	});
 }
-function Nf({ tabs: e, activeTab: t, onSelect: n, addAction: r, floatingPosition: i = "center", className: a }) {
-	let o = u.useCallback((e) => {
+function Nf({ tabs: e, activeTab: t, onSelect: n, addAction: r, floatingPosition: i = "center", showOnDesktop: a = !1, className: o }) {
+	let s = u.useCallback((e) => {
 		let t = e.target;
 		t instanceof Element && t.closest("button, a")?.blur();
-	}, []), s = e.map((e) => {
+	}, []), c = e.map((e) => {
 		let r = e.key === t, i = e.Icon;
 		return {
 			label: e.label,
@@ -13285,7 +13304,7 @@ function Nf({ tabs: e, activeTab: t, onSelect: n, addAction: r, floatingPosition
 			onClick: () => n(e.key),
 			tabKey: e.key
 		};
-	}), c = r ? {
+	}), l = r ? {
 		label: "",
 		ariaLabel: r.ariaLabel ?? r.label,
 		icon: /* @__PURE__ */ B(Mf, {}),
@@ -13293,15 +13312,16 @@ function Nf({ tabs: e, activeTab: t, onSelect: n, addAction: r, floatingPosition
 		onClick: r.onClick
 	} : void 0;
 	return /* @__PURE__ */ B(Df, {
-		className: a ? `lg:hidden ${a}` : "lg:hidden",
+		className: a ? o : o ? `lg:hidden ${o}` : "lg:hidden",
 		variant: "pill",
 		pillPosition: "fixed",
 		floatingPosition: i,
 		showLabels: !0,
 		keyboardBehavior: "hide",
-		onPointerUpCapture: o,
-		items: s,
-		centerAction: c
+		onPointerUpCapture: s,
+		items: c,
+		centerAction: l,
+		showOnDesktop: a
 	});
 }
 //#endregion

package/dist/types/components/patterns/commerce/bottom-tab-bar.d.ts

@@ -76,6 +76,20 @@ interface BottomTabBarProps extends React.ComponentProps<"nav"> {
     scrollEdge?: boolean;
     /** nav 要素の aria-label。@default "メインナビゲーション" */
     navLabel?: string;
+    /**
+     * デスクトップ幅（`lg` = 1024px 以上）でもナビを表示するか（issue #486）。
+     *
+     * DS の既定はモバイル専用（`lg:hidden`）。PC ではサイドナビや
+     * ヘッダーナビへ切り替えるアプリを想定しているため。
+     * **デスクトップ用シェルを持たず、全幅でこのナビを出し続けたいアプリ**
+     * （消費側でこれを `className="lg:flex"` で毎回打ち消していた）は
+     * `showOnDesktop` を渡す。
+     *
+     * `variant="pill"` では scroll edge の装飾帯も一緒に追従する。
+     *
+     * @default false（従来どおり lg 以上で非表示）
+     */
+    showOnDesktop?: boolean;
 }
 /**
  * BottomTabBar — モバイルのグローバルナビゲーション。
@@ -112,6 +126,22 @@ interface BottomTabBarProps extends React.ComponentProps<"nav"> {
  *   `--Nav-Selected-Surface` / `-Shadow` は**宣言したときだけ** DS 既定
  *   （`.glass-accent` / ガラスの選択プラッター）を置き換える。未宣言なら
  *   tone / dark の出し分けは従来どおり DS 側が持つ。
+ * - `--Nav-Pill-Surface` / `-Backdrop` / `-Border` / `-Shadow` / `-Specular`
+ *   … pill 本体の面（issue #486）。DS 既定は Liquid Glass（`.glass`、
+ *   `tone="inverse"` は `.glass-dark`）で、これも**宣言したときだけ**効く。
+ *   背後コンテンツの可読性を優先して不透明なナビにしたい場合に使う:
+ *
+ *   ```css
+ *   :root {
+ *     --Nav-Pill-Surface: var(--Surface-Primary);
+ *     --Nav-Pill-Backdrop: none;             （ガラスのぼかしを切る）
+ *     --Nav-Pill-Specular: none;             （スペキュラ / 屈折リムも消す）
+ *     --Nav-Pill-Shadow: 0 4px 16px rgb(0 0 0 / 0.12);
+ *   }
+ *   ```
+ *
+ *   `className` で `.glass` を打ち消すことはできない（Tailwind ユーティリティ
+ *   ではないため tailwind-merge が落とせない）ので、面の変更は必ずこの変数で行う。
  * - 寸法系が効くのは prominent レイアウト（`showLabels` か `centerAction` が
  *   ある pill）。アイコンのみの compact pill は契約外で固定。
  *
@@ -142,6 +172,6 @@ interface BottomTabBarProps extends React.ComponentProps<"nav"> {
  *
  * いずれも呼び出し側の義務にしていない（明示値があればそちらが優先）。
  */
-declare function BottomTabBar({ className, items, centerAction, showLabels, tone, maxWidth, variant, pillPosition, floatingPosition, keyboardBehavior, scrollEdge, navLabel, ...props }: BottomTabBarProps): React.JSX.Element;
+declare function BottomTabBar({ className, items, centerAction, showLabels, tone, maxWidth, variant, pillPosition, floatingPosition, keyboardBehavior, scrollEdge, navLabel, showOnDesktop, ...props }: BottomTabBarProps): React.JSX.Element;
 export { BottomTabBar };
 export type { BottomTabBarAction, BottomTabBarFloatingPosition, BottomTabBarItem, BottomTabBarKeyboardBehavior, BottomTabBarProps, };

package/dist/types/components/patterns/commerce/mobile-tab-bar.d.ts

@@ -22,6 +22,11 @@ interface MobileTabBarProps<T extends string> {
      * addAction と併用しない片側フロート + FAB 併置レイアウトで使う。
      */
     floatingPosition?: BottomTabBarFloatingPosition;
+    /**
+     * デスクトップ幅（`lg` = 1024px 以上）でもナビを表示するか（issue #486）。
+     * BottomTabBar へそのままパススルーする。@default false
+     */
+    showOnDesktop?: boolean;
     className?: string;
 }
 /**
@@ -34,6 +39,6 @@ interface MobileTabBarProps<T extends string> {
  * - 内部は BottomTabBar（variant="pill", pillPosition="fixed", showLabels,
  *   keyboardBehavior="hide"）の薄いラッパー。floatingPosition はパススルー。
  */
-declare function MobileTabBar<T extends string>({ tabs, activeTab, onSelect, addAction, floatingPosition, className, }: MobileTabBarProps<T>): React.JSX.Element;
+declare function MobileTabBar<T extends string>({ tabs, activeTab, onSelect, addAction, floatingPosition, showOnDesktop, className, }: MobileTabBarProps<T>): React.JSX.Element;
 export { MobileTabBar };
 export type { MobileTabBarAddAction, MobileTabBarProps, MobileTabItem };

package/dist/types/components/patterns/responsive-overlay-frame.d.ts

@@ -13,6 +13,25 @@ import { type SheetSurface } from "./sheet-surface";
  * float 系では `preset` は効かず、代わりに `padding` が効く。
  */
 type ResponsiveOverlaySide = "bottom" | "float" | "float-glass";
+/**
+ * 面に実際に効いている `max-height`（実測値）。
+ *
+ * 既定キャップは className でも上書きできる（desktopClassName の max-h ユーティリティ）。
+ * inline style は className より強いので、経路の既定値だけを見て畳むと
+ * consumer が締めたキャップを緩めてしまう（#487 の Codex レビュー指摘）。
+ * 補正が当たっていない間の computed 値を読めば、className / inline style /
+ * 経路の既定のどれで決まっていても「いま効いているキャップ」が取れる。
+ *
+ * 補正が当たっている間は自分の inline 値を読み返してしまうので、その間だけ
+ * inline の max-height を外して測り、すぐ戻す（layout effect の中なので
+ * 塗り替えは挟まらない）。「Sheet からの切り替え直後にすでにキーボードが
+ * 出ている」（iPad を境界跨ぎで回転した等）ケースでも初回から実測できる
+ * ようにするため、active を理由に測定を諦めない（#487 の Codex レビュー指摘）。
+ */
+export declare function useEffectiveMaxHeight(active: boolean, consumerInlineMaxHeight: string, classSignature: string): {
+    setElement: (node: HTMLDivElement | null) => void;
+    measured: string | undefined;
+};
 /**
  * ズームを打ち消したソフトキーボード高さ（レイアウト px / issue #487）。
  *

package/dist/types/lib/compose-ref.d.ts

@@ -17,6 +17,13 @@ export declare function assignRef<T>(ref: React.Ref<T> | undefined, node: T | nu
  * - consumer が cleanup を返していれば、それを呼ぶ
  * - 返していなければ（object ref / 旧来のコールバック ref）`null` を書き戻す
  *
+ * **返すコールバック ref の identity は固定する**（issue #516）。React は
+ * コールバック ref の identity が render 間で変わると detach → re-attach を
+ * 行うため、`internal` / `external` を依存にして毎 render 作り直すと、
+ * consumer が毎 render 新しい関数を渡す呼び出し面（Radix の composeRefs が
+ * 生成する合成関数など）で ref chain 全体の付け外しが増える。identity を
+ * 固定し、差し替えは insertion effect で node を付け替えることで吸収する。
+ *
  * @param internal 内部側の setter。attach 時に node、detach 時に null で呼ばれる
  * @param external consumer から渡された ref（未指定可）
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ksk-design-system",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "KSK Design System — フリーランス向けマルチテーマ対応デザインシステム",
   "license": "MIT",
@@ -164,6 +164,7 @@
     "lint:prefix-order": "node scripts/check-prefix-order.mjs",
     "lint:screen-contracts": "node scripts/check-screen-contracts.mjs",
     "lint:deprecations": "node scripts/check-deprecations.mjs",
+    "audit:issue-links": "node scripts/check-issue-close-links.mjs",
     "lint:migration-doc": "node scripts/generate-migration-doc.mjs --check",
     "generate:migration-doc": "node scripts/generate-migration-doc.mjs",
     "metrics": "node scripts/download-metrics.mjs",
@@ -178,6 +179,7 @@
     "check:native-parity": "node scripts/check-native-parity.mjs",
     "check:native-lookup": "node scripts/generate-native-component-lookup.mjs --check",
     "test": "vitest run",
+    "test:legacy-radix": "node scripts/test-legacy-radix.mjs",
     "test:consumer:web": "npm run build:lib && node scripts/test-packed-web-consumer.mjs",
     "test:consumer:native": "npm run build:lib && node scripts/test-packed-native-consumer.mjs",
     "test:consumer:cli": "node scripts/test-packed-cli-consumer.mjs",
@@ -185,18 +187,18 @@
     "test:watch": "vitest",
     "test:interaction": "vitest run --config vitest.storybook.config.ts",
     "test:a11y": "vitest run --config vitest.a11y.config.ts",
-    "check": "tsc -p tsconfig.app.json --noEmit && tsc -p tsconfig.type-tests.json --noEmit && bash scripts/lint-scratch.sh && bash scripts/check-deps.sh && node scripts/check-published-deps.mjs && node scripts/check-css-setup.mjs && bash scripts/check-drift.sh && node scripts/check-screen-contracts.mjs && node scripts/check-docs-drift.mjs && node scripts/check-agents-docs-sync.mjs && node scripts/check-contrast.mjs && node scripts/check-design-md.mjs && node scripts/check-tailwind-v4.mjs && node scripts/check-prefix-order.mjs && node scripts/check-flex-shrink.mjs && node scripts/check-deprecations.mjs && node scripts/check-rules-contract.mjs && node scripts/sync-version.mjs --check && node scripts/generate-migration-doc.mjs --check && bash scripts/check-responsive.sh && node scripts/generate-component-lookup.mjs --check && node scripts/generate-platform-tokens.mjs --check && node scripts/generate-token-hex-cache.mjs --check && node scripts/generate-source-safelist.mjs --check && tsc -p tsconfig.native.json --noEmit && node scripts/check-native-parity.mjs && node scripts/generate-native-component-lookup.mjs --check",
+    "check": "tsc -p tsconfig.app.json --noEmit && tsc -p tsconfig.type-tests.json --noEmit && bash scripts/lint-scratch.sh && bash scripts/check-deps.sh && node scripts/check-published-deps.mjs && node scripts/check-radix-floor.mjs && node scripts/check-css-setup.mjs && bash scripts/check-drift.sh && node scripts/check-screen-contracts.mjs && node scripts/check-docs-drift.mjs && node scripts/check-agents-docs-sync.mjs && node scripts/check-contrast.mjs && node scripts/check-design-md.mjs && node scripts/check-tailwind-v4.mjs && node scripts/check-prefix-order.mjs && node scripts/check-flex-shrink.mjs && node scripts/check-deprecations.mjs && node scripts/check-rules-contract.mjs && node scripts/sync-version.mjs --check && node scripts/generate-migration-doc.mjs --check && bash scripts/check-responsive.sh && node scripts/generate-component-lookup.mjs --check && node scripts/generate-platform-tokens.mjs --check && node scripts/generate-token-hex-cache.mjs --check && node scripts/generate-source-safelist.mjs --check && tsc -p tsconfig.native.json --noEmit && node scripts/check-native-parity.mjs && node scripts/generate-native-component-lookup.mjs --check",
     "check:agent": "npm run lint && npm run check && npm test && npm run lint:story-reuse",
     "version": "node scripts/sync-version.mjs",
     "mcp:build": "cd mcp-server && npm install && npm run build",
     "mcp:start": "node mcp-server/dist/index.js"
   },
   "dependencies": {
-    "@radix-ui/react-slot": "^1.0.0",
+    "@radix-ui/react-slot": "^1.3.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "iconsax-reactjs": "^0.0.8",
-    "radix-ui": "^1.0.0",
+    "radix-ui": "^1.6.1",
     "react-day-picker": "^10.0.1",
     "react-hook-form": "^7.75.0",
     "tailwind-merge": "^3.5.0"
@@ -260,18 +262,19 @@
     "iconsax-reactjs": "^0.0.8",
     "jsdom": "^25.0.1",
     "playwright": "^1.62.0",
-    "radix-ui": "^1.4.3",
+    "radix-ui": "^1.6.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-native": "^0.86.0",
     "react-native-web": "^0.21.2",
+    "semver": "^7.8.5",
     "storybook": "^10.4.6",
     "tailwindcss": "^4.2.1",
     "tw-animate-css": "^1.4.0",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.48.0",
     "vite": "^8.1.3",
     "vitest": "^4.1.7",
-    "zod": "^4.4.2",
-    "typescript": "^6.0.3"
+    "zod": "^4.4.2"
   }
 }

package/src/components/COMPONENT_LOOKUP.md

@@ -168,7 +168,7 @@
 
 | Component | Import | Variants | Stories |
 |-----------|--------|----------|---------|
-| BottomTabBar | `@/components/patterns/commerce/bottom-tab-bar` | — | Default, Pill — iOS 26 Liquid Glass, Pill — on light background, Liquid Glass — center action, Liquid Glass — labels visible, Liquid Glass — 5 items, Liquid Glass — over dark photo/gradient, Liquid Glass — light fallback, Liquid Glass — sliding selection (interactive), Liquid Glass — scroll edge effect, Floating position — left + FAB, Floating position — right + FAB, Keyboard behavior — hide |
+| BottomTabBar | `@/components/patterns/commerce/bottom-tab-bar` | — | Default, Pill — iOS 26 Liquid Glass, Pill — on light background, Liquid Glass — center action, Liquid Glass — labels visible, Liquid Glass — 5 items, Liquid Glass — over dark photo/gradient, Liquid Glass — light fallback, Liquid Glass — sliding selection (interactive), Liquid Glass — scroll edge effect, Floating position — left + FAB, Floating position — right + FAB, Keyboard behavior — hide, Pill の面を不透明にする（--Nav-Pill-*）, デスクトップ幅でも表示する（showOnDesktop） |
 | FilterBar | `@/components/patterns/commerce/filter-bar` | — | Default, Interactive |
 | ImageCarousel | `@/components/patterns/commerce/image-carousel` | — | Banner, Square, Video, AutoPlay |
 | MobileTabBar | `@/components/patterns/commerce/mobile-tab-bar` | — | Default, With addAction (center CTA), floatingPosition=, ProductCustomization |

package/src/styles/bottom-nav.css

@@ -8,7 +8,7 @@
    （belle-todo）が壊れ、`!important` の山が残った事故が由来。
 
    ── 寸法は product-theme.css の --Nav-* が担当（:root に既定値あり）。
-   ── 面（背景・境界・影）はここが担当し、**既定値を :root に置かない**。
+   ── 面（背景・backdrop・境界・影）はここが担当し、**既定値を :root に置かない**。
       var(--Nav-*, <DS 既定>) の形で書き、消費側が宣言したときだけ上書きされる。
       宣言しなければ tone="inverse" / dark の出し分けは従来どおり DS が持つ。
 
@@ -28,6 +28,50 @@
    SSR / 計測前に面を兼ねるタブ本体・アイコン領域）に当たる。
    ============================================================= */
 
+/* ─── pill 本体の面（issue #486）───
+   DS 既定は Liquid Glass（`.glass` / tone="inverse" は `.glass-dark`）。
+   背後コンテンツの可読性を優先して**不透明な面**にしたい消費側が、
+   内部クラスに触らず面だけ差し替えられるようにする。
+
+   `.glass` / `.glass-dark` と同じ詳細度（0,1,0）だが、glass.css より後に
+   読み込まれるこのファイルが勝つ（中央アクションと同じ手口）。
+   フォールバックは `.glass` 自身が使う内部変数そのものなので、
+   未宣言時のレンダリングは 1px も変わらない。
+
+   backdrop-filter は `none` を宣言すればガラスのぼかしを完全に切れる。
+   -webkit- を先・標準形を後に書く（消費側 minifier の dedupe 対策）。 */
+[data-slot="bottom-nav-pill"] {
+  background: var(--Nav-Pill-Surface, var(--glass-bg));
+  -webkit-backdrop-filter: var(--Nav-Pill-Backdrop, var(--glass-blur));
+  backdrop-filter: var(--Nav-Pill-Backdrop, var(--glass-blur));
+  border: var(--Nav-Pill-Border, 0.5px solid var(--glass-border));
+  box-shadow: var(--Nav-Pill-Shadow, var(--glass-highlight), var(--glass-shadow));
+}
+
+[data-slot="bottom-nav-pill"][data-tone="inverse"] {
+  background: var(--Nav-Pill-Surface, var(--glass-bg-dark));
+  -webkit-backdrop-filter: var(--Nav-Pill-Backdrop, var(--glass-blur-media-dark));
+  backdrop-filter: var(--Nav-Pill-Backdrop, var(--glass-blur-media-dark));
+  border: var(--Nav-Pill-Border, 0.5px solid var(--glass-border-dark));
+  box-shadow: var(
+    --Nav-Pill-Shadow,
+    inset 0 1px 0 rgba(255, 255, 255, 0.12),
+    0 8px 32px rgba(0, 0, 0, 0.28)
+  );
+}
+
+/* ─── pill のスペキュラ / 屈折リム（issue #486）───
+   `.glass-specular` の ::before（レンズ上面）と ::after（エッジの屈折リム）は
+   面を不透明にしても残るため、ガラスを切りたい消費側にはノイズになる。
+
+   既定は `.glass-specular` 自身と同じ `content: ""` なので**未宣言なら何も変わらない**。
+   `--Nav-Pill-Specular: none` を宣言すると擬似要素そのものが生成されなくなり、
+   リムとスペキュラが消える。 */
+[data-slot="bottom-nav-pill"]::before,
+[data-slot="bottom-nav-pill"]::after {
+  content: var(--Nav-Pill-Specular, "");
+}
+
 /* ─── 中央アクションの面 ───
    .glass-accent と同じ詳細度（0,1,0）なので、glass.css より後に読み込まれる
    このファイルが勝つ。フォールバックは .glass-accent 自身が同じ要素に載せる