@qijenchen/design-system 0.1.0-beta.80 → 0.1.0-beta.81

package/src/components/OverflowIndicator/overflow-indicator.spec.md

@@ -63,7 +63,7 @@ sm / md 跟 Tag 同階（20/24px），lg 對齊 md（尺寸需求一致，不需
 
 **字級依 shape 分流**：`circle` shape 走元件內建的 `triggerText` map（sm 10px / md·lg 12px）；`tag` shape 直接套 `tagVariants({ size })`（sm 12px / md·lg 14px，見 `tag.spec.md`），刻意對齊 Tag 視覺一致（見上方「trigger 不用 Tag 元件」段）。下方「sm 用 `text-[10px]`」的理由僅適用於 circle shape。
 
-**sm 用 `text-[10px]` 的理由**：sub-footnote 特殊例外,與 Badge 共享「micro-indicator typography」tier——trigger 數字是次要輔助 indicator（非主訊息）,在 20px 小容器內 12px 會擠。完整理由與 pattern-family 說明詳見 `badge.spec.md`「字體例外：`text-[10px]`」。若未來 OverflowIndicator / Badge 以外的元件也需要 sub-footnote 尺寸,應在 typography system 加 `--font-micro` token,再改用 token 而非 arbitrary value。
+**sm 用 `text-[10px]` 的理由**：micro-indicator 特殊例外（10px,與 `--font-footnote` 同值但不消費其 utility——lh 1.3 vs 需要的緊湊行高）,與 Badge 共享「micro-indicator typography」tier——trigger 數字是次要輔助 indicator（非主訊息）,在 20px 小容器內 caption 12px 會擠。完整理由與 pattern-family 說明詳見 `badge.spec.md`「字體例外：`text-[10px]`」。若未來 OverflowIndicator / Badge 以外的元件也需要這個 10px micro-indicator 尺寸,先依 `badge.spec.md`「其他元件不得比照」歸同一 family 討論,確立第三個消費者才升 typography token,而非直接抄 arbitrary value。
 
 ---
 

package/src/components/OverflowIndicator/overflow-indicator.tsx

@@ -158,7 +158,8 @@ export const overflowIndicatorMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 2026-07-04 audit 對齊(spec:95「本身無 hover / active / disabled / selected 變化」;code 有 focus-visible ring tsx:106/121)
+  states: ['default', 'focus-visible'],
   tokens: {
     bg: ['bg-muted'],
     fg: ['text-foreground'],

package/src/components/PeoplePicker/people-picker.anatomy.stories.tsx

@@ -252,7 +252,7 @@ export const ColorMatrix: Story = {
               <tr>
                 <Td mono>disabled</Td>
                 <Td><TokenCell token="--bg-disabled" display="bg-disabled" /></Td>
-                <Td><TokenCell token="--border" /></Td>
+                <Td>—(border transparent)</Td>
                 <Td><TokenCell token="--fg-disabled" display="fg-disabled" /></Td>
               </tr>
               <tr>

package/src/components/PeoplePicker/people-picker.spec.md

@@ -88,7 +88,7 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 | 資料類型 | **人員**（含 Avatar） | 任意（純文字）| 任意（純文字）|
 | 單選 / 多選 | 兩者皆支援（value 類型決定）| 單選 | 多選 |
 | 視覺 prefix | Avatar（必備） | 可選 startIcon | 無 |
-| 底層實作 | Popover + Command + SelectMenu | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu，`select.tsx:570`）/ 觸控 native `<select>`(`select.tsx` NativeSelect) | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu + Tag overlay，`combobox.tsx:699`）/ 觸控 native `<select>`(`combobox.tsx` NativeCombobox) |
+| 底層實作 | Popover + Command + SelectMenu | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu，`select.tsx:582`）/ 觸控 native `<select>`(`select.tsx` NativeSelect) | 桌機自建 listbox（`role="combobox"` div + cmdk SelectMenu + Tag overlay，`combobox.tsx:728`）/ 觸控 native `<select>`(`combobox.tsx` NativeCombobox) |
 | 搜尋 | 永遠啟用（人名本質）；single = inline-trigger（wrap `<Select searchable>`），multi 預設 panel-top（`searchIn='menu'`，`searchIn='trigger'` opt-in）— 對齊本 spec L91-92 SSOT 表 | 可選 `searchable`（單選短列表 → inline-trigger only）| 可選 `searchable` + `searchIn='menu' \| 'trigger'`（多選 → 兩種模式）|
 
 **搜尋型態 SSOT canonical**（A1-A5 spec,2026-05-11;2026-05-12 補 PeoplePicker multi `searchIn` opt-in）：
@@ -147,7 +147,7 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 
 | 共享項 | SSOT owner |
 |---|---|
-| Avatar 左 inset 距 trigger.left = 12px 固定(不隨 size/density 漂移)| 本 spec L94 + `people-picker.tsx:362` `!px-[var(--field-px)]` inject(form context)/ `!px-[var(--table-cell-px)]`(naked variant table cell)|
+| Avatar 左 inset 距 trigger.left = 12px 固定(不隨 size/density 漂移)| 本 spec L175「Avatar 左 inset SSOT」段 + `people-picker.tsx:371` `!px-[var(--field-px)]` inject(form context)/ `!px-[var(--table-cell-px)]`(naked variant table cell)|
 | Avatar+人名視覺 | `person-display.tsx:137-152` `PersonDisplay`(共享 renderer)|
 | 人名按空間 ellipsis | `person-display.tsx:150` `truncate flex-1 min-w-0` |
 | Placeholder ellipsis(inline-search active 時)| `field-wrapper.tsx:244` `bareInputStyles` 含 `truncate` |
@@ -237,7 +237,7 @@ PeoplePicker 是 **composite Field Control**(Field shell + Avatar + SelectMenu),
 
 ## shadcn passthrough 例外說明
 
-PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox>`(multi)),其主 API 為 declarative(value / onChange / size / mode / options...)。**有套 `forwardRef` + HTML root props spread**(codex P2 fix 2026-05-07 v15.10,`people-picker.tsx:110` / L52 / L130 `...rest`):
+PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox>`(multi)),其主 API 為 declarative(value / onChange / size / mode / options...)。**有套 `forwardRef` + HTML root props spread**(codex P2 fix 2026-05-07 v15.10,`people-picker.tsx:111` / L53 / L131 `...rest`):
 
 - **forwardRef + 單一 root**:`PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>`,ref 與 `...rest`(`id` / `data-testid` / `onBlur` / `onFocus` / `aria-*` 等 HTML root props)forward 到內部 trigger 容器(readonly/disabled root div、或 wrapped Select / Combobox 的 root),對齊 DS 既有 Combobox / Select 慣例
 - **`onChange` 走 Omit**:本元件 onChange 用 `(value: PersonValue[]) => void` custom signature,跟 HTMLAttributes onChange 衝突,故 Omit
@@ -251,7 +251,7 @@ PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox
 
 - **Disabled**:`disabled` → `resolvedMode='disabled'`(`useResolvedFieldMode`),走獨立 static-display 分支(`people-picker.tsx`「readonly / disabled」段)——渲染靜態 `<div>` 包 `MultiPersonDisplay` / `PersonDisplay` + `ItemSuffix` ChevronDown 類型身份 indicator(2026-06-26:disabled 保留 chevron、readonly 不顯示;naked variant 依 `showDisplayEndIcon`),**不** wrap Select / Combobox、無 dismiss X、無 inline-search input。token 走 M24 state precedence(`text-fg-disabled`,含 chevron)。
 - **Loading(async people fetch)**:目前 PeoplePicker **未暴露 `loading` prop**(`PeoplePickerProps` 無此欄位,內部也未 forward 給 wrapped Select / Combobox)。consumer 若需 loading 態,在 fetch 完成前自行控制 `people=[]`(走 emptyText 空態)。底層 Select / Combobox / SelectMenu 各有自己的 loading 機制,但尚未經 PeoplePicker API 層轉發。
-- **Empty(no search results)**:`emptyText` 預設「沒有符合的人員」(本 spec L72 已 codify);無 creatable mode(人員不可建立)。
+- **Empty(no search results)**:`emptyText` 預設「沒有符合的人員」(本 spec L80 已 codify);無 creatable mode(人員不可建立)。
 - **Empty(no value selected)**:single mode → trigger 顯 placeholder「請選擇人員」;multi mode `value=[]` → trigger 同 placeholder(無 avatar stack 渲);詳「Trigger display SSOT canonical table」B-D 段。
 - **`people` 清單變動(async fetch 後更新)**:已選 value 顯示不依賴 `people` 查找 — display 路徑直接渲染 value 自帶資料;edit 路徑以人名回查 `people`,查不到降級為純名字 string(initials fallback),不報錯(`people-picker-helpers.ts:74-75`)。選單選項即時跟隨 props 重渲。
 - **RTL**:未實作方向鏡像(avatar stack overlap `-ml-0.5` / 12px inset 皆以 LTR physical 方向設計);RTL 屬 DS-wide 決策,未定(與 Chip / Breadcrumb 同口徑)。

package/src/components/PeoplePicker/people-picker.stories.tsx

@@ -150,7 +150,7 @@ const AsyncDirectoryPicker = () => {
     <div className="flex flex-col gap-2 max-w-xs">
       <PeoplePicker value={val} people={people} onChange={setVal} aria-label="任務協作者" />
       <p className="text-caption text-fg-secondary">
-        Jira 任務「協作者」欄位場景：已選成員隨任務資料先抵達，組織人員名錄約 1.5 秒後才從 API 回來——已選的 avatar 與姓名立即顯示，不等名錄載入。
+        Jira 任務「協作者」欄位場景：已選成員隨任務資料先抵達，組織人員名錄約 1.5 秒後才從 API 回來——已選成員立即顯示、不報錯；名錄未到前 avatar 先以姓名縮寫 fallback 呈現，名錄載入後自動補上頭像。
       </p>
     </div>
   )

package/src/components/PeoplePicker/people-picker.tsx

@@ -1,5 +1,5 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
-// @placeholder-vocabulary-allow: 1-cycle backward-compat — `placeholder` 已加(trigger empty SSOT),`emptyPlaceholder={emptyText}` forward 仍保留讓既有 consumer 不被 silent break;Combobox line 760 `placeholder ?? emptyPlaceholder` fallback → placeholder 永遠 takes precedence。Future cycle 移除 emptyPlaceholder forward(per field-controls.spec.md 共享 contract b)。
+// @placeholder-vocabulary-allow: 2026-07-04 Q4 完成 field-controls.spec.md 共享 contract b — emptyPlaceholder forward 已移除,emptyText 直達 Combobox → SelectMenu emptyText(search-empty 真住所);placeholder 為 trigger empty SSOT。
 // @cell-metric-escape-allow: comment describes RETIRED `tagAreaPaddingLeftPx={8}` magic — current code is surface-guarded (`surface === 'form'` only injects `!px-[var(--field-px)]`; table-cell context untouched, lets naked `!px-[var(--table-cell-px)]` SSOT take over). Hook regex grep'd the comment word, not the live code path. Per (a) fix 2026-05-13 user-approved Path a.
 import * as React from 'react'
 import { ChevronDown } from 'lucide-react'
@@ -67,8 +67,8 @@ export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElem
   placeholder?: string
   /** 搜尋框 placeholder */
   searchPlaceholder?: string
-  /** 搜尋無結果訊息(filtered menu empty)。**僅**用於 SelectMenu noResultsText,
-   *  不再 silent 轉 trigger placeholder(2026-05-12 Issue 4 semantic fix)。 */
+  /** 搜尋無結果訊息(filtered menu empty)。**僅**用於 SelectMenu `emptyText`(菜單空狀態,
+   *  2026-07-04 Q4 接線完成),不轉 trigger placeholder(2026-05-12 Issue 4 semantic fix)。 */
   emptyText?: string
   className?: string
   disabled?: boolean
@@ -139,6 +139,56 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   const isMulti = Array.isArray(value)
   const isEmpty = !value || (isMulti && value.length === 0)
 
+  // 2026-07-05 D3 P0 修:以下派生 + 4 hooks 原宣告在 display/readonly/single/pill 四個 early return
+  // 之後 — 同一 mounted instance 的 resolvedMode 於 edit↔display/disabled 切換(<Field mode>/<Field
+  // disabled> cascade 正是 runtime 翻轉機制)時 hook 數 7→11 變動 → React #310 crash(與 Combobox
+  // beta.76 / LinkInput 2026-07-04 同家族)。全部 hoist 到任何 early return 之前(對齊 select.tsx
+  // 「所有 hooks 必在 early return 前 call」canonical);effect 加 mode/stack guard,邏輯不變。
+  const selectedNames: string[] = !value
+    ? []
+    : Array.isArray(value)
+      ? value.map(v => resolvePerson(v).name)
+      : [resolvePerson(value).name]
+
+  // SSOT visible count compute via formula primitive + ResizeObserver(multi stack mode 專用)
+  const stackContainerRef = React.useRef<HTMLDivElement | null>(null)
+  const [stackVisibleCount, setStackVisibleCount] = React.useState<number | undefined>(undefined)
+  React.useLayoutEffect(() => {
+    if (resolvedMode !== 'edit' || !isMulti || multiDisplay !== 'stack' || selectedNames.length <= 1) {
+      setStackVisibleCount(undefined); return
+    }
+    const root = stackContainerRef.current
+    if (!root) return
+    // 2026-05-15 ROOT CAUSE FIX(user 抓「之前說的問題都還是存在」):
+    // stackContainerRef 透過 mergedStackRef 接 Combobox forwarded ref → root **就是** [role=combobox]
+    // div 自己。原 `root.querySelector('[role=combobox]')` 不找 self 永遠 null → trigger=null →
+    // tagArea=null → available=0 → setStackVisibleCount(0) → 整 stack 全 overflow → fallback 到
+    // Combobox DOM-based useOverflowCount(非 deterministic 那個算法)。修:用 root 自己當 trigger,
+    // 從 root 內找 tagArea(flex-1 min-w-0 div)。
+    const calc = () => {
+      const trigger = root.matches('[role="combobox"]') ? root : root.querySelector<HTMLElement>('[role="combobox"]')
+      const tagArea = trigger?.querySelector<HTMLElement>('div[class*="flex-1"][class*="min-w-0"]')
+      const available = tagArea?.clientWidth ?? trigger?.clientWidth ?? 0
+      const visible = getAvatarStackVisibleCount({
+        availablePx: available,
+        total: selectedNames.length,
+        avatarPx: AVATAR_STACK_AVATAR_PX[size],
+        overflowChipPx: AVATAR_STACK_OVERFLOW_CHIP_PX[size],
+      })
+      setStackVisibleCount(visible)
+    }
+    calc()
+    const ro = new ResizeObserver(calc)
+    ro.observe(root)
+    return () => ro.disconnect()
+  }, [resolvedMode, isMulti, multiDisplay, selectedNames.length, size])
+  // Merge ref:forward to parent + capture for ResizeObserver
+  const mergedStackRef = React.useCallback((el: HTMLDivElement | null) => {
+    stackContainerRef.current = el
+    if (typeof ref === 'function') ref(el)
+    else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = el
+  }, [ref])
+
   // ── mode='display' ────────────────────────────────────────────────────────
   // Default(showDisplayEndIcon=false):裸 PersonDisplay / MultiPersonDisplay — backward compat。
   // Opt-in(showDisplayEndIcon=true,2026-05-08 D-path):Field naked wrapper + ItemSuffix ChevronDown,
@@ -200,11 +250,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   }
 
   // ── edit mode ─────────────────────────────────────────────────────────────
-  const selectedNames: string[] = !value
-    ? []
-    : Array.isArray(value)
-      ? value.map(v => resolvePerson(v).name)
-      : [resolvePerson(value).name]
+  // (selectedNames 派生已 hoist 至檔上方 hooks 區,見 D3 P0 修註解)
 
   // ── single mode → wraps Select ────────────────────────────────────────────
   if (!isMulti) {
@@ -219,8 +265,9 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
         onChange={handleSingleChange}
         searchable
         placeholder={placeholder}
-        // 2026-05-12 Stream C Issue 4 fix(codex Q3):傳 `placeholder` 給 Select trigger empty。
-        // 不再傳 `emptyText`(search-empty semantic 跟 trigger-empty 分離,canonical SSOT)。
+        // 2026-05-12 Issue 4:placeholder = trigger empty。2026-07-04 Q4:emptyText 走 Select →
+        // SelectMenu 接線(search-empty 語意,與 trigger-empty 分離)。
+        emptyText={emptyText}
         defaultOpen={defaultOpen}
         onOpenChange={onOpenChange}
         className={className}
@@ -252,11 +299,10 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
         searchable
         searchPlaceholder={searchPlaceholder}
         // 2026-05-12 Stream C Issue 4(codex Q3):placeholder = trigger empty hint('請選擇人員')
-        // — semantic clean separation;emptyText 不再 silent 轉 trigger placeholder。
-        // emptyPlaceholder backward-compat forward(Combobox line 760 `placeholder ?? emptyPlaceholder` fallback)
-        // 1 cycle:future 移除 emptyPlaceholder forward,emptyText 改傳 SelectMenu noResultsText。
+        // — semantic clean separation。2026-07-04 Q4 拍板完成 1-cycle 承諾:emptyPlaceholder forward
+        // 移除,emptyText 改傳 Combobox → SelectMenu emptyText(search-empty 真住所,菜單空狀態)。
         placeholder={placeholder}
-        emptyPlaceholder={emptyText}
+        emptyText={emptyText}
         wrap={pillWrap}
         defaultOpen={defaultOpen}
         onOpenChange={onOpenChange}
@@ -302,45 +348,8 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   const handleMultiChange = (next: string[]) => {
     onChange?.(next.map(name => findPerson(people, name)))
   }
-  // SSOT visible count compute via formula primitive + ResizeObserver
-  const stackContainerRef = React.useRef<HTMLDivElement | null>(null)
-  const [stackVisibleCount, setStackVisibleCount] = React.useState<number | undefined>(undefined)
-  React.useLayoutEffect(() => {
-    // 注:此 effect 只在 multi stack mode 跑(early return if not stack);length<=1 不需 override
-    if (!isMulti || selectedNames.length <= 1) {
-      setStackVisibleCount(undefined); return
-    }
-    const root = stackContainerRef.current
-    if (!root) return
-    // 2026-05-15 ROOT CAUSE FIX(user 抓「之前說的問題都還是存在」):
-    // stackContainerRef 透過 mergedStackRef 接 Combobox forwarded ref → root **就是** [role=combobox]
-    // div 自己。原 `root.querySelector('[role=combobox]')` 不找 self 永遠 null → trigger=null →
-    // tagArea=null → available=0 → setStackVisibleCount(0) → 整 stack 全 overflow → fallback 到
-    // Combobox DOM-based useOverflowCount(非 deterministic 那個算法)。修:用 root 自己當 trigger,
-    // 從 root 內找 tagArea(flex-1 min-w-0 div)。
-    const calc = () => {
-      const trigger = root.matches('[role="combobox"]') ? root : root.querySelector<HTMLElement>('[role="combobox"]')
-      const tagArea = trigger?.querySelector<HTMLElement>('div[class*="flex-1"][class*="min-w-0"]')
-      const available = tagArea?.clientWidth ?? trigger?.clientWidth ?? 0
-      const visible = getAvatarStackVisibleCount({
-        availablePx: available,
-        total: selectedNames.length,
-        avatarPx: AVATAR_STACK_AVATAR_PX[size],
-        overflowChipPx: AVATAR_STACK_OVERFLOW_CHIP_PX[size],
-      })
-      setStackVisibleCount(visible)
-    }
-    calc()
-    const ro = new ResizeObserver(calc)
-    ro.observe(root)
-    return () => ro.disconnect()
-  }, [isMulti, multiDisplay, selectedNames.length, size])
-  // Merge ref:forward to parent + capture for ResizeObserver
-  const mergedStackRef = React.useCallback((el: HTMLDivElement | null) => {
-    stackContainerRef.current = el
-    if (typeof ref === 'function') ref(el)
-    else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = el
-  }, [ref])
+  // ── edit mode ─────────────────────────────────────────────────────────────
+  // (selectedNames 派生已 hoist 至檔上方 hooks 區,見 D3 P0 修註解)
 
   return (
     <Combobox
@@ -355,7 +364,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
       searchPlaceholder={searchPlaceholder}
       // 2026-05-12 Stream C Issue 4(codex Q3):placeholder = trigger empty('請選擇人員');emptyText = search-empty(僅 backward-compat forward 1 cycle)
       placeholder={placeholder}
-      emptyPlaceholder={emptyText}
+      emptyText={emptyText}
       wrap={false}
       defaultOpen={defaultOpen}
       onOpenChange={onOpenChange}

package/src/components/PeoplePicker/person-display.tsx

@@ -179,8 +179,8 @@ function MultiPersonDisplay({
   /** 傳入時啟用 dismiss(edit mode),callback 接收被移除的 person */
   onRemove?: (person: PersonValue) => void
 }) {
-  if (!value || value.length === 0) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
-
+  // 2026-07-05 D3 P1 修(React #310 家族):3 hooks 原在 empty early return 之後 — value 非空↔空
+  // 切換時 hook 數 0↔3 變動必 crash(現靠 consumer 三元切換 element type 偶然避開)。hoist 到 return 前。
   // 2026-05-15 Bug 3 fix(Claude+Codex Step 5 比稿 consensus):消費 shared `avatar-stack-overflow`
   // primitive。原 inline canvas-based formula 是 dual-implementation 違反 user SSOT「同 cell width 同
   // overflow 判斷」(edit path 用 Combobox useOverflowCount DOM offsetWidth / display path 用 inline
@@ -189,7 +189,7 @@ function MultiPersonDisplay({
   const containerRef = React.useRef<HTMLSpanElement>(null)
   const [measuredCount, setMeasuredCount] = React.useState<number | null>(null)
   React.useLayoutEffect(() => {
-    if (!measured) return
+    if (!measured || !value || value.length === 0) return
     const el = containerRef.current
     if (!el) return
     const calc = () => {
@@ -207,6 +207,8 @@ function MultiPersonDisplay({
     return () => ro.disconnect()
   }, [measured, size, value])
 
+  if (!value || value.length === 0) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+
   const resolvedMax = measured && measuredCount !== null ? measuredCount : (max ?? 3)
   const people = value.map(resolvePerson)
   const visible = people.slice(0, resolvedMax)

package/src/components/Popover/popover.anatomy.stories.tsx

@@ -244,7 +244,7 @@ export const StateBehavior: Story = {
     <div className="flex flex-col gap-8">
       <div>
         <H3>開啟 / 關閉</H3>
-        <Desc>Radix 原生動畫:進場 `fade-in + zoom-in-95 + slide-from-side`,離場鏡像。所有方向都使用 side-aware slide 動畫,浮層看起來從 trigger 「長出來」。</Desc>
+        <Desc>Radix 提供 data-state 切換 + DS Tailwind animate 驅動(popover.tsx L70-71):進場 `fade-in + zoom-in-95 + slide-from-side`,離場鏡像。所有方向都使用 side-aware slide 動畫,浮層看起來從 trigger 「長出來」。</Desc>
         <ul className="text-caption text-fg-muted list-disc pl-5 space-y-1">
           <li>點擊 trigger → 開啟</li>
           <li>點 Popover 外部 → 關閉(click outside)</li>

package/src/components/Popover/popover.spec.md

@@ -24,14 +24,14 @@ Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點
 
 **Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
 
-**視覺對齊 Dialog**：外殼 token 與 Dialog 完全一致（`bg-surface-raised` / `border-border` / `rounded-lg` / `elevation-200`）。差別僅兩點：(1) Popover 是 non-modal 輕量浮層不阻斷背景，(2) **density 永遠鎖 `md`** — Popover 不隨頁面 density 放大（lightweight 浮層保持緊湊）。
+**視覺對齊 Dialog**：外殼 token 與 Dialog 完全一致（`bg-surface-raised` / `border-border` / `rounded-lg` / `elevation-200`）。差別僅兩點：(1) Popover 是 non-modal 輕量浮層不阻斷背景，(2) **layout-space 鎖 `md`** — header / footer padding 不隨頁面放大（輕量 chrome 保持精簡）；**ui-size 不鎖、繼承 page** — 內部控件隨 page 放大、對齊觸發點（2026-06-15 改,原 `data-density` master switch,見 `popover.tsx` docblock）。
 
-**Content size canonical（2026-04-29）**:density lock md → **fields(Input / Select / Checkbox)預設 `size="md"`**(field-height-md 32px,對齊 density)。其餘細節走 SSOT pointer:
+**Content size canonical（2026-04-29,2026-06-15 更新）**:ui-size 繼承 page → **fields(Input / Select / Checkbox)預設隨 page ui-size**(md page = `size="md"` field-height-md 32px;lg page 放大,與觸發點一致)。其餘細節走 SSOT pointer:
 - Chrome corner buttons(close X / refresh / dismiss)→ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」(sm native + v5 trick)
 - Row inline action(panel list row 內 Eye / drag / suffix toggle)→ `patterns/element-anatomy/inline-action.spec.md`「尺寸對照」table(md = 16+18 hover bg)
 - Footer action button → `action-bar.spec.md`(輕量 chrome,sm canonical)
 
-**觸發距離 canonical**：`sideOffset = 8`（px）—— trigger 到 Popover 邊緣的垂直/水平間距。8px 是世界級浮層 idiom（Notion / Linear / Figma / Stripe 皆約 6-8px）;< 4px 會讓浮層貼死 trigger 失去「另一層」感,> 12px 會拉斷 trigger ↔ content 的視覺關聯。Radix/shadcn 預設 4px 太緊,本 DS 改為 8 對齊 overlay primitive 的呼吸感。Dialog 不適用(居中或 full-screen)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**觸發距離 canonical**：`sideOffset = 8`（px）—— trigger 到 Popover 邊緣的垂直/水平間距。8px 是世界級浮層 idiom（Notion / Linear / Figma / Stripe 皆約 6-8px）;< 4px 會讓浮層貼死 trigger 失去「另一層」感,> 12px 會拉斷 trigger ↔ content 的視覺關聯。shadcn 預設 4px 太緊(Radix 原生預設 0 更貼),本 DS 改為 8 對齊 overlay primitive 的呼吸感。Dialog 不適用(居中或 full-screen)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 **Viewport 邊距 canonical**:`collisionPadding = 8`(px)——浮層與 viewport 邊緣的最小間距。當 popover 原本要貼近 viewport 邊(trigger 在頁面最右側、或視窗很窄),Radix 會自動推開 8px 讓浮層不貼死邊界。世界級對照:macOS / iOS / Notion / Figma 的 overflow 選單永遠留視覺呼吸距。`sideOffset` 管 trigger↔popover,`collisionPadding` 管 popover↔viewport,兩者互補。Consumer 不需傳 — 預設值是 canonical。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
@@ -54,7 +54,7 @@ Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點
 其他結構化浮層 spec 若討論 align 應 pointer 指回本節。
 
 **結構化組合（可選）**：PopoverContent 外殼無內距，consumer 可選擇：
-- **單一 body**：包 `<PopoverBody>` 取得 Dialog body 同 padding (`px-loose py-tight`)
+- **單一 body**：包 `<PopoverBody>` 取得 SurfaceBody canonical padding (`px-loose py-tight`,`overlay-surface.spec.md` SSOT;Dialog body 另有 `pb-[--layout-space-bottom]` 特化)
 - **含標題**：組合 `<PopoverHeader>` + `<PopoverBody>`（下分隔線由 Header 提供）
 - **含操作按鈕列**：再加 `<PopoverFooter>`（上分隔線由 Footer 提供）
 
@@ -64,13 +64,13 @@ Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點
 
 **Close X 按鈕(2026-04-22 v5 unbounded canonical)**:所有 `PopoverHeader` 內建右上 X 按鈕,`<Button data-dismiss iconOnly dismiss size="sm" />` native sm(28 md / 32 lg)。透過 SurfaceHeader 的 v5 CSS rule 自動套負 margin 讓 layout 佔位;PopoverHeader 走 `COMPACT_HEADER_SLOT`(= calc(--font-body-size×1.5) = 21 = title line-box,衍生)→ 佔位 21(輕量 chrome,見 `popover.tsx` docblock),非 Dialog 的 24。`hideClose` prop 可讓 composition 元件(如 Coachmark)選擇隱藏。詳 `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
 
-**Header / Footer 高度 canonical**:padding-based(繼承 SurfaceHeader / SurfaceFooter),高度 = max(child layout) + 2×tight。header:slot 佔位 21(`COMPACT_HEADER_SLOT` = title line-box,衍生)→ max(21 title, 21 slot) + 2×12 = **45**,自然比 Dialog / Sheet 48 輕一級(`popover.tsx` PopoverHeader docblock + overlay-surface.tsx 對照);footer:無 override,unbounded 佔位 24 → 48(若只有 unbounded)或自然長(若有 bounded)。詳 `tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」。
+**Header / Footer 高度 canonical**:padding-based(繼承 SurfaceHeader / SurfaceFooter),高度 = max(child layout) + 2×tight。header:slot 佔位 21(`COMPACT_HEADER_SLOT` = title line-box,衍生)→ max(21 title, 21 slot) + 2×12 = **45**,自然比 Dialog / Sheet 48 輕一級(`popover.tsx` PopoverHeader docblock + overlay-surface.tsx 對照);footer:SurfaceFooter **不**套 unbounded slot trick(僅 padding + `border-t`,見 `overlay-surface.spec.md`「為什麼 SurfaceHeader 是 padding-based」)→ 高度 = max(child layout) + 2×tight(sm action button 28 → **52** md)。詳 `tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」。
 
 ---
 
 ## Title typography canonical(non-modal 特化,2026-04-22 v4)
 
-**PopoverTitle 用 `text-body font-medium`(14px),不是 Dialog / Sheet 的 `text-body-lg`(16px)**。這是針對 **non-modal 輕量浮層** 的視覺考量,跟 density 鎖 md 同源的輕量 rationale。
+**PopoverTitle 用 `text-body font-medium`(14px),不是 Dialog / Sheet 的 `text-body-lg`(16px)**。這是針對 **non-modal 輕量浮層** 的視覺考量,跟 layout-space 鎖 md 同源的輕量 rationale。
 
 **重量分級(world-class 共通 pattern)**:
 
@@ -152,11 +152,11 @@ canonical 判斷:「使用者 click 單項是否立即改變系統狀態?」是
 
 ## 邊界案例
 
-- **極長內容**:PopoverContent 設 `max-h-[var(--radix-popover-content-available-height)]`(popover.tsx:65),body 包 `<PopoverBody>`(SurfaceBody `flex-1 min-h-0 overflow-y-auto`)→ viewport 太小時 header / footer 留在視窗內、body 內捲。中間 wrapper 必 forward flex chain,詳 `../../patterns/overlay-surface/overlay-surface.spec.md`「Viewport-aware scroll chain invariant」。
+- **極長內容**:PopoverContent 設 `max-h-[var(--radix-popover-content-available-height)]`(popover.tsx:69),body 包 `<PopoverBody>`(SurfaceBody `flex-1 min-h-0 overflow-y-auto`)→ viewport 太小時 header / footer 留在視窗內、body 內捲。中間 wrapper 必 forward flex chain,詳 `../../patterns/overlay-surface/overlay-surface.spec.md`「Viewport-aware scroll chain invariant」。
 - **Viewport 邊緣**:`collisionPadding = 8` 自動推開(見「Viewport 邊距 canonical」)。
 - **嵌套 Popover**:禁止(見「禁止事項」)。
 - **Dark mode**:殼走 semantic token 自動 adapt(見 `color.spec.md`)。
-- **Density**:永遠鎖 `md`(見「定位」段),不隨頁面 density 放大。
+- **Density**:layout-space 鎖 `md`(header / footer padding 精簡);ui-size 繼承 page(見「定位」段)。
 
 ---
 
@@ -175,13 +175,11 @@ Consumer 無需額外處理 a11y,保留 Radix `data-state` 屬性即可(開啟
 
 ---
 
-## 為何無 Inspector
+## Inspector
 
-Popover 是**浮層容器 primitive**——關鍵決策是 `side` × `align` × `sideOffset`,以及內部 Header / Body / Footer 結構。`PlacementMatrix` 是完整的 side × align 12-cell 矩陣,比互動 Inspector(切單一 side/align)更能呈現所有定位組合。Header / Body / Footer padding 屬 `overlay-surface` SSOT,已由 `ColorMatrix` 的 token 表 + 該 pattern spec 覆蓋。
+`Inspector` 提供互動 Controls 即時切換 PopoverContent 六個關鍵維度:`side` / `align`(12 種定位組合)、`sideOffset`(與 trigger 距離)、`width`(w-72 / w-80 / w-96)、`showHeader` / `showFooter`(chrome 結構開關)。內容區由 consumer 決定,Inspector 聚焦容器層級的可試玩 prop(對齊 `sheet.spec.md`「Inspector」canonical)。`PlacementMatrix` 另以靜態 12-cell side × align 矩陣一眼呈現所有定位組合;Header / Body / Footer padding 屬 `overlay-surface` SSOT,由 `ColorMatrix` 的 token 表 + 該 pattern spec 覆蓋。
 
-Popover 內容完全由 consumer 決定,無自己的 variant/size/disabled 等可試玩 prop——Inspector 對 container 類元件價值低。
-
-對應 anatomy story:保留 `Overview` + 元件特有 `PlacementMatrix`(12-cell side × align 矩陣) + `ColorMatrix` + `SizeMatrix` + `StateBehavior`(open / close / animation)。
+對應 anatomy story:保留 `Overview` + `Inspector` + 元件特有 `PlacementMatrix`(12-cell side × align 矩陣) + `ColorMatrix` + `SizeMatrix` + `StateBehavior`(open / close / animation) + `Accessibility`。
 
 ---
 

package/src/components/Popover/popover.tsx

@@ -134,8 +134,8 @@ PopoverFooter.displayName = "PopoverFooter"
 // PopoverTitle(2026-04-22 v4 non-modal canonical):`text-body font-medium`(14px)
 // Rationale:Popover / Coachmark 屬 **non-modal 輕量浮層**,跟 density 鎖 md 同源的視覺語言 —
 // chrome 全體輕量:
-//   - density 鎖 md(不隨 page 放大)
-//   - dismiss X 透過 v5 unbounded trick layout 佔位 24
+//   - layout-space 鎖 md(ui-size 繼承 page,2026-06-15)
+//   - dismiss X 走 COMPACT_HEADER_SLOT 佔位 21(= title text-body line-box;見 PopoverHeader docblock)
 //   - **title `text-body`(14px)跟 Dialog / Sheet modal 的 body-lg(16px)形成重量級 vs 輕量級視覺區分**
 // 世界級對照:Figma / Notion / Linear / Material 的 popover / filter panel / inline settings
 // 的 header title 多半比 modal dialog title 小一級(16→14 或同比),視覺宣告「此浮層可忽略」

package/src/components/ProfileCard/profile-card.anatomy.stories.tsx

@@ -24,7 +24,7 @@ type InspectorArgs = {
 }
 
 const meta: Meta = {
-  title: 'Design System/Internal/ProfileCard/設計規格',
+  title: 'Design System/Components/ProfileCard/設計規格',
   parameters: { layout: 'padded' },
 }
 export default meta
@@ -97,7 +97,7 @@ export const Overview: Story = {
               {[
                 ['name', 'string', '必填', '姓名(profile header)'],
                 ['subtitle', 'string', '—', '職稱 / 位置 / 描述'],
-                ['avatar', 'AvatarData', '—', '{ src?, alt?, color? };size/status 由 ProfileCard 覆寫'],
+                ['avatar', 'AvatarData', '—', '{ src?, alt, color?, hoverCard? }(alt 必填;未傳 avatar 時以 name 作 fallback alt);size/status 由 ProfileCard 覆寫,hoverCard 不 forward'],
                 ['status', "'online' | 'away' | 'busy' | 'offline'", '—', '觸發 Status section + Avatar 狀態點'],
                 ['statusMessage', 'ReactNode', '—', '狀態說明文字(完整顯示,內容多時 Body 區捲動)'],
                 ['actions', 'ReactNode', '—', 'CTA buttons(通常 2 個 sm Button)'],
@@ -122,7 +122,7 @@ export const Overview: Story = {
               <tr><Td>Card 寬度</Td><Td mono>w-[320px](元件級常數,不抽 token)</Td></tr>
               <tr><Td>Profile header padding</Td><Td mono>px-4 py-3</Td></tr>
               <tr><Td>Profile avatar / text gap</Td><Td mono>gap-3</Td></tr>
-              <tr><Td>Avatar 大小</Td><Td mono>64px(對齊 Avatar.block tier)</Td></tr>
+              <tr><Td>Avatar 大小</Td><Td mono>64px(profile-card.tsx 元件級常數 AVATAR_SIZE;非 item-anatomy AVATAR_SIZE.block tier — block 為 32/32/40)</Td></tr>
               <tr><Td>Actions padding</Td><Td mono>px-4 pb-3 + gap-2</Td></tr>
               <tr><Td>Status / Info padding</Td><Td mono>px-4 py-3</Td></tr>
               <tr><Td>View more padding</Td><Td mono>px-4 py-3</Td></tr>
@@ -376,7 +376,7 @@ export const HoverCardIntegration: Story = {
                   <Avatar alt={p.name} size={40} status={p.status} />
                 </span>
               </HoverCardTrigger>
-              <HoverCardContent align="start" className="p-0" sideOffset={8}>
+              <HoverCardContent align="start" className="p-0">{/* sideOffset 不 override — spec 禁止事項(default 即 OVERLAY_SIDE_OFFSET) */}
                 <ProfileCard
                   name={p.name}
                   subtitle={p.subtitle}

package/src/components/ProfileCard/profile-card.principles.stories.tsx

@@ -8,7 +8,7 @@ import { Avatar } from '@/design-system/components/Avatar/avatar'
 import { Button } from '@/design-system/components/Button/button'
 
 const meta: Meta = {
-  title: 'Design System/Internal/ProfileCard/設計原則',
+  title: 'Design System/Components/ProfileCard/設計原則',
   parameters: { layout: 'padded' },
 }
 export default meta
@@ -87,7 +87,7 @@ export const UsageGuidance: Story = {
       <p>適合 ProfileCard 的真實業務場景(點擊跳轉「展示」頁範例):</p>
       <ul className="space-y-1">
         <li>
-          <LinkTo kind="Design System/Internal/ProfileCard/展示" name="懸停展開 ProfileCard"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">懸停留言者 / PR reviewer / 成員列表的頭像,展開人員詳情卡</span></LinkTo>
+          <LinkTo kind="Design System/Components/ProfileCard/展示" name="懸停展開 ProfileCard"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">懸停留言者 / PR reviewer / 成員列表的頭像,展開人員詳情卡</span></LinkTo>
         </li>
       </ul>
       <p>判斷時對照 spec.md「何時用 / 何時不用」段落。</p>

package/src/components/ProfileCard/profile-card.spec.md

@@ -1,8 +1,7 @@
 ---
 component: ProfileCard
 family: composite
-traits:
-  - isInternal
+traits: []
 variants: {}
 sizes: {}
 benchmark:

package/src/components/ProfileCard/profile-card.stories.tsx

@@ -3,7 +3,7 @@ import { ProfileCard, ProfileCardDefaultActions } from './profile-card'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
 
 const meta: Meta = {
-  title: 'Design System/Internal/ProfileCard/展示',
+  title: 'Design System/Components/ProfileCard/展示',
   parameters: { layout: 'padded' },
 }
 export default meta

package/src/components/ProfileCard/profile-card.tsx

@@ -1,6 +1,9 @@
 /**
- * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
- * 不進 root barrel front-door;由 PeoplePicker(person-display)wrap 消費,end-user app 請用 wrapper 元件。
+ * Public 元件(2026-07-04 Q8 拍板升 public,原 @internal 標記移除)。
+ * 理由:avatar.spec.md「hover 必出 ProfileCard」DS-wide canonical 要求 consumer 直接
+ * import ProfileCard + ProfileCardDefaultActions 組 HoverCard — 按 ui-development.md
+ * 唯一判準(DS 想讓 consumer 直接用 = public)internal 標記是 governance bug;
+ * 世界級對照:Atlassian ProfileCard 同為 public standalone。
  */
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 import * as React from 'react'

package/src/components/RadioGroup/radio-group.principles.stories.tsx

@@ -29,7 +29,7 @@ const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }
 
 const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
   <section className="mb-12">
-    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
     {children}
   </section>
 )

package/src/components/RadioGroup/radio-group.spec.md

@@ -90,7 +90,7 @@ Item-level default / hover / checked / disabled **色彩**與 Checkbox 共用同
 
 繼承 Field family,詳見 `../Field/field-controls.spec.md` + `../Field/form-validation.spec.md`。
 
-**Field 內 readonly(2026-06-12 user 拍板)**:不渲染 radio 群組,改渲染 `fieldWrapperStyles` readonly 灰框 + 選中項 label(= Select readonly 同款,同為單選資料的鎖定呈現);standalone readonly 維持原樣鎖互動(ReadonlyContext)。
+**Field 內 readonly(2026-06-12 user 拍板)**:不渲染 radio 群組,改渲染 `fieldWrapperStyles` readonly 灰框 + 選中項 label(= Select readonly 同款,同為單選資料的鎖定呈現);standalone readonly 維持原樣鎖互動(ReadonlyContext + item onClick preventDefault guard — 2026-07-05 D4 補:`<label htmlFor>` synthetic click 非 pointer event,`pointer-events-none` 攔不到,需 guard 才真鎖)。
 
 ---
 
@@ -112,7 +112,7 @@ Item-level default / hover / checked / disabled **色彩**與 Checkbox 共用同
 - **極長 label / description**:預設不截斷、自然換行(`labelMaxLines` / `descMaxLines` 預設 `'none'`,Clamp 政策 SSOT 見 `checkbox.spec.md`「Clamp 政策」)。
 - **icon / avatar prefix**:`RadioGroupItem` 一級 `icon` / `avatar` props 轉發 `SelectionItem` prefix 槽(2026-06-12 M30;規則 SSOT 見 `checkbox.spec.md` 同段 + `selection-item.spec.md`)。
 - **RTL**:未實作方向鏡像;RTL 屬 DS-wide 決策,未定(與 Chip / Breadcrumb 同口徑)。
-- **Dark mode / density**:走 SelectionItem semantic token 自動 adapt;垂直 gap 隨 layoutSpace token density-aware。
+- **Dark mode / density**:走 SelectionItem semantic token 自動 adapt;垂直行距由 SelectionItem `py = (field-height − 1lh) / 2` 公式消費 uiSize token(`--field-height-*`)生成,隨 density 自動調整(零外部 gap 機制 SSOT 見 `checkbox.spec.md`「群組模式」)。
 
 ---
 

package/src/components/RadioGroup/radio-group.stories.tsx

@@ -44,7 +44,9 @@ export const Modes: Story = {
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">disabled</h3>
-        <RadioGroup value="yearly" aria-label="付款方案(disabled mode demo)">
+        {/* mode="disabled" → Radix Root disabled 原生 propagate 全 item(radio 控件真停用);
+            SelectionItem disabled 另管 label 降色 — 雙傳對齊「停用」story 寫法 */}
+        <RadioGroup mode="disabled" value="yearly" aria-label="付款方案(disabled mode demo)">
           <SelectionItem control={<RadioGroupItem value="monthly" id="m-dis" />} label="月付方案" htmlFor="m-dis" disabled />
           <SelectionItem control={<RadioGroupItem value="yearly" id="y-dis" />} label="年付方案" htmlFor="y-dis" disabled />
           <SelectionItem control={<RadioGroupItem value="lifetime" id="l-dis" />} label="終身方案" htmlFor="l-dis" disabled />

package/src/components/RadioGroup/radio-group.tsx

@@ -80,14 +80,31 @@ const RadioGroup = React.forwardRef<
   // 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。
   // 實作:walk children 找 control.value === selectedValue 的 SelectionItem,render label plain text。
   // (不用 context dispatch 給 RadioGroupItem — SelectionItem layout wrapper 仍會渲染所有 item label)
+  // 2026-07-04 修:display / readonly-in-Field 分支的 <div> 原丟棄剩餘 props(id/data-*/aria-*)
+  // 且不轉發 forwardRef ref → 自家 radio-group.stories.tsx display demo 傳的 aria-label 都靜默失效。
+  // 抽出 Radix 專屬 non-DOM props,其餘 DOM props 於兩分支 spread 轉發(與 Checkbox/Switch 同修);
+  // edit 主路徑不受影響(Root 仍 spread 完整 props)。
+  const {
+    onValueChange: _onValueChange,
+    disabled: _disabled,
+    required: _required,
+    name: _name,
+    orientation: _orientation,
+    dir: _dir,
+    loop: _loop,
+    asChild: _asChild,
+    children: _children,
+    ...restDomProps
+  } = props as RadioGroupProps & { asChild?: boolean }
+
   if (resolvedMode === 'display') {
     const selectedValue = (value ?? defaultValue) as string | undefined
     if (!selectedValue) {
-      return <div role="group" className={cn('grid', className)}><span className="text-fg-muted">{EMPTY_DISPLAY}</span></div>
+      return <div {...restDomProps} ref={ref as React.Ref<HTMLDivElement>} role="group" className={cn('grid', className)}><span className="text-fg-muted">{EMPTY_DISPLAY}</span></div>
     }
     const selectedLabel = findSelectedRadioLabel(props.children, selectedValue)
     return (
-      <div role="group" className={cn('grid', className)}>
+      <div {...restDomProps} ref={ref as React.Ref<HTMLDivElement>} role="group" className={cn('grid', className)}>
         <span className="text-foreground">{selectedLabel ?? selectedValue}</span>
       </div>
     )
@@ -103,6 +120,8 @@ const RadioGroup = React.forwardRef<
     const boxSize = resolvedBoxSize
     return (
       <div
+        {...restDomProps}
+        ref={ref as React.Ref<HTMLDivElement>}
         role="radiogroup"
         aria-readonly="true"
         aria-labelledby={fieldCtx?.labelId}
@@ -260,6 +279,18 @@ const RadioGroupItem = React.forwardRef<
         tabIndex={effectiveReadonly ? -1 : undefined}
         className={cn(radioItemVariants({ size }), className)}
         {...props}
+        // 2026-07-05 D4 修:readOnly 鎖互動補 label 繞道 — <label htmlFor> 的 synthetic click
+        // 不是 pointer event,cva pointer-events-none 攔不到,點 label 文字仍選中。
+        // preventDefault 讓 Radix composeEventHandlers(checkForDefaultPrevented)跳過內部 onCheck;
+        // 必列在 {...props} 之後才不被 consumer onClick 覆蓋(與 Checkbox/Switch 同修)。
+        // 同時攔 Radix roving-focus 的 arrow-key onFocus → click() 路徑(同為 click event)。
+        onClick={(event) => {
+          if (effectiveReadonly) {
+            event.preventDefault()
+            return
+          }
+          props.onClick?.(event)
+        }}
       >
         <RadioGroupPrimitive.Indicator className="grid place-content-center">
           <Circle
@@ -306,7 +337,9 @@ export const radioGroupMeta = {
     md: { fieldHeight: 32, iconSize: 8, typography: 'body' },
     lg: { fieldHeight: 36, iconSize: 10, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 2026-07-04 修 stale meta:移除 'active' — radioItemVariants cva 無 active-state 樣式,
+  // Radix radio 也無 data-state=active(對照 checkboxMeta 正確不含 active)
+  states: ['default', 'hover', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-disabled', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],