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

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'
@@ -31,12 +34,30 @@ import { ItemContent } from '@/design-system/patterns/element-anatomy/item-anato
  *
  * Chat + Audio call 是 **default**,不是 **only**——consumer 可覆寫,但需有明確理由。
  */
-export const ProfileCardDefaultActions = () => (
-  <>
-    <Button variant="tertiary" size="sm" startIcon={MessageCircle}>Chat</Button>
-    <Button variant="tertiary" size="sm" startIcon={Phone} endIcon={ChevronDown}>Audio call</Button>
-  </>
-)
+export const ProfileCardDefaultActions = ({
+  onChat,
+  onCall,
+}: {
+  /** Chat 按鈕 handler(2026-07-06 user 拍板:預設鈕必可接線,未傳 = dev-warn;PersonData.onChat 自動 forward) */
+  onChat?: () => void
+  /** Audio call 按鈕 handler(ChevronDown 下拉行為留 v2,先接主 callback) */
+  onCall?: () => void
+}) => {
+  // Dev-mode warning(對齊本檔 defaultFieldValues dev-warn 先例):預設 actions 沒接 handler
+  // = 按鈕點了永遠沒反應(2026-07-06 D4 finding);production 必傳 callback 或自組 actions。
+  if (process.env.NODE_ENV !== 'production' && !onChat && !onCall) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[DS ProfileCard] ProfileCardDefaultActions 未接 onChat/onCall——按鈕點擊無反應。請傳入 callback(PersonData.onChat/onCall 會自動 forward)或自組 actions。'
+    )
+  }
+  return (
+    <>
+      <Button variant="tertiary" size="sm" startIcon={MessageCircle} onClick={onChat}>Chat</Button>
+      <Button variant="tertiary" size="sm" startIcon={Phone} endIcon={ChevronDown} onClick={onCall}>Audio call</Button>
+    </>
+  )
+}
 
 /**
  * ProfileCard — 人員 HoverCard 的內容元件

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,10 @@ 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)
+  // 'checked' = 選定持續態(card 式 = border+text primary;2026-07-07 meta 詞彙統一補列)
+  states: ['default', 'hover', 'checked', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-disabled', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'],

package/src/components/Rating/rating.anatomy.stories.tsx

@@ -11,18 +11,21 @@ export default meta
 
 /* ── Data ─────────────────────────────────────────────── */
 
-type SizeKey = 'sm' | 'md' | 'lg'
+type SizeKey = 'xs' | 'sm' | 'md' | 'lg'
 type PrecisionKey = 'full' | 'half'
 type ModeKey = 'interactive' | 'readOnly' | 'disabled'
 
-const SIZES: SizeKey[] = ['sm', 'md', 'lg']
-// 對齊 item-anatomy inline Avatar(sm=20 / md=24 / lg=24),詳見 rating.spec.md「Icon 尺寸對齊 Avatar inline」
-const SIZE_PX: Record<SizeKey, number> = { sm: 20, md: 24, lg: 24 }
+const SIZES: SizeKey[] = ['xs', 'sm', 'md', 'lg']
+// 對齊 item-anatomy inline Avatar(sm=20 / md=24 / lg=24),詳見 rating.spec.md「為什麼不完全對齊 icon tier — Icon 尺寸對齊 Avatar inline」
+const SIZE_PX: Record<SizeKey, number> = { xs: 20, sm: 20, md: 24, lg: 24 }
 
+// 對齊 rating.spec.md「Size」表 canonical:xs = standalone 預設（商品卡 / 評論列表旁 / 搜尋結果 row,
+// component default）,sm/md/lg 為 Field 配對尺寸(2026-07-04 補 xs — SizeMatrix 不該藏預設尺寸)
 const SIZE_USE: Record<SizeKey, string> = {
-  sm: '商品列表、搜尋結果、DataTable cell',
-  md: '一般卡片、評論列表、商品詳情（預設）',
-  lg: '送出評分的 review form 主 CTA 區',
+  xs: 'Standalone 預設 — 商品卡 / 評論列表旁（component default,container 24 / icon 20）',
+  sm: 'Field sm 並排（Field 配對尺寸）',
+  md: 'Field 預設 — 一般表單評分欄位',
+  lg: '送出評分的 review form、強調的主 CTA 區塊',
 }
 
 /* ═══════════════════════════════════════════════════════════════════════════
@@ -363,7 +366,7 @@ export const SizeMatrix = {
         <tbody>
           {SIZES.map((sz) => (
             <tr key={sz}>
-              <Td mono>{sz}{sz === 'md' ? ' ★default' : ''}</Td>
+              <Td mono>{sz}{sz === 'md' ? ' ★Field default' : ''}</Td>
               <Td mono>{SIZE_PX[sz]}px</Td>
               <Td mono>gap-1 (4px)</Td>
               <Td>{SIZE_USE[sz]}</Td>

package/src/components/Rating/rating.principles.stories.tsx

@@ -288,7 +288,7 @@ export const YellowStarConvention: Story = {
               <Rating value={4.5} readOnly precision="half" size="lg" aria-label="誤用範例" icon={Star} />
             </div>
           </div>
-          <Label warn>藍星讓使用者猶豫「這是什麼」→ 一瞬間流失 = 設計 bug</Label>
+          <Label warn>藍星讓使用者猶豫「這是什麼」→ 一瞬間流失 = 設計 bug。（上例外層雖掛 color: var(--primary)，渲染仍是黃星——星色由 rating.tsx fill 硬綁 --warning，非 currentColor，機械保證此誤用做不出來）</Label>
         </div>
       </Rule>
     </div>

package/src/components/Rating/rating.spec.md

@@ -72,13 +72,13 @@ Rating 是**離散 1–5 分評分元件**——使用者對商品、服務、
 | `md` | 32px(`h-field-md`) | 24px | **Field 預設**。一般表單評分欄位 | field md |
 | `lg` | 36px(`h-field-lg`) | 24px | 送出評分的 review form、強調的主 CTA 區塊 | field lg |
 
-### Standalone vs Field 尺寸選擇(canonical)
+### 為什麼不 default md — Standalone vs Field 尺寸選擇(canonical)
 
 - **Standalone 展示**(非 Field 內):用 **`xs`**(container 24 / icon 20)——對齊 Avatar sm 20px / Tag sm;Airbnb / Yelp 商品卡星星亦此大小 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 - **Field 內**(`<Field>` 表單內當 control):跟 Field size 對應傳 sm/md/lg(Field 預設 md)
 - 世界級對照:Material Rating standalone ≈ 24dp;Ant Rate 在 Form 內跟 Form itemSize。兩種 context 分開設計,不強求單一預設 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
-### Icon 尺寸對齊 **Avatar inline**,不對齊 icon tier(2026-04-21 AR48 canonical)
+### 為什麼不完全對齊 icon tier — Icon 尺寸對齊 **Avatar inline**(2026-04-21 AR48 canonical)
 
 Rating 的 **container 高度消費 `--field-height-*` token**(sm=28 / md=32 / lg=36),讓它可以與 Input / Select / NumberInput / Button 等 field-height family 元件並排時 row-align 一致。
 

package/src/components/Rating/rating.stories.tsx

@@ -40,7 +40,7 @@ export const ReadOnlyProductRating: Story = {
                 value={p.rating}
                 readOnly
                 precision="half"
-                size="sm"
+                size="xs"
                 aria-label={`平均評分 ${p.rating} 星，共 5 星,${p.count} 則評論`}
               />
               <span className="text-caption text-fg-secondary">{p.rating}</span>

package/src/components/Rating/rating.tsx

@@ -261,10 +261,10 @@ function StarIcon({ Icon, sizePx, fillRatio, isHalf, interactive, onHover, onCli
 
   // Half: 兩個重疊 icon,左半 filled / 右半 empty + 兩個 hover zone 切半星
   return (
-    <span className="relative inline-flex" style={{ width: sizePx, height: sizePx }}>
-      <Icon size={sizePx} fill={FILL_EMPTY} stroke="none" className="absolute inset-0" style={{ color: FILL_EMPTY }} />
+    <span aria-hidden className="relative inline-flex" style={{ width: sizePx, height: sizePx }}>
+      <Icon size={sizePx} fill={FILL_EMPTY} stroke="none" aria-hidden className="absolute inset-0" style={{ color: FILL_EMPTY }} />
       <span className="absolute inset-0 overflow-hidden" style={{ width: sizePx * fillRatio }}>
-        <Icon size={sizePx} fill={FILL_FILLED} stroke="none" style={{ color: FILL_FILLED }} />
+        <Icon size={sizePx} fill={FILL_FILLED} stroke="none" aria-hidden style={{ color: FILL_FILLED }} />
       </span>
       {interactive && (
         <>

package/src/components/ScrollArea/scroll-area.spec.md

@@ -3,6 +3,7 @@ component: ScrollArea
 family: self-contained
 variants: {}
 sizes: {}
+traits: []  # Radix wrapper 捲軸 primitive,無 trait variants(R3 trait enforce 無適用項;2026-07-04 dim 29 補宣告)
 benchmark:
   - Radix ScrollArea primitive: github.com/radix-ui/primitives/tree/main/packages/react/scroll-area
 ---

package/src/components/ScrollArea/scroll-area.tsx

@@ -92,7 +92,7 @@ ScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.displayName
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const scrollAreaMeta = {
   component: 'ScrollArea',
-  family: null, // non-family composite / overlay / layout
+  family: 'self-contained', // 對齊 scroll-area.spec.md frontmatter(SSOT;同 Separator/OverflowIndicator meta 寫法)
   variants: {
 
   },

package/src/components/SegmentedControl/segmented-control.anatomy.stories.tsx

@@ -168,8 +168,8 @@ export const StateBehavior: Story = {
             <tbody>
               <tr><Td>Unselected</Td><Td><TokenCell token="--surface" display="bg-surface" /></Td><Td><TokenCell token="--fg-secondary" display="text-fg-secondary" /></Td><Td><TokenCell token="--border" display="border-border" /></Td><Td>—</Td></tr>
               <tr><Td>Hover unselected</Td><Td><TokenCell token="--surface" display="bg-surface(不變)" /></Td><Td><TokenCell token="--foreground" display="text-foreground" /></Td><Td><TokenCell token="--border-hover" display="border-border-hover" /></Td><Td mono>z-[5](hover 邊框浮上)</Td></tr>
-              <tr><Td>Selected</Td><Td><TokenCell token="--surface" display="bg-surface" /></Td><Td><TokenCell token="--primary-hover" display="text-primary-hover" /></Td><Td><TokenCell token="--primary-hover" display="border-primary-hover" /></Td><Td mono>z-10(浮在相鄰 item border 上)</Td></tr>
-              <tr><Td>Disabled</Td><Td>灰化</Td><Td>灰化</Td><Td>—</Td><Td>—</Td></tr>
+              <tr><Td>Selected</Td><Td><TokenCell token="--surface" display="bg-surface" /></Td><Td><TokenCell token="--primary" display="text-primary" /></Td><Td><TokenCell token="--primary" display="border-primary" /></Td><Td mono>z-10(浮在相鄰 item border 上)</Td></tr>
+              <tr><Td>Disabled</Td><Td>bg-surface(不變)</Td><Td>text-fg-disabled</Td><Td>border-border(不變,hover 鎖定)</Td><Td>—</Td></tr>
             </tbody>
           </table>
         </div>
@@ -289,7 +289,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"  ARIA / Pattern  :繼承 Radix toggle-group primitive 的無障礙預設——整組 role=\"group\",每個 item role=\"radio\"(type=\"single\" 互斥選一),鍵盤導覽由 primitive 處理。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — 進入整組(只有一個 tab 停留點,落在選中項;沒選就落第一項)\n- ←/→ — 在 item 之間移動 roving focus(只移焦點,不切換選取)。WAI-ARIA APG 對水平 segmented/radio group 的主要導覽鍵\n- ↑/↓ — 同 ←/→,也會在 item 間移動 roving focus。Radix toggle-group 未鎖 orientation(沿用 default 雙軸 roving),APG 接受 group 同時支援兩軸方向鍵\n- Enter / Space — 選取目前 focus 的 item\n\n  Focus  :採 roving tabindex——整組共用一個 tab 停留點,方向鍵在 item 間移動焦點(選取仍需 Enter/Space/click);不是 Dialog 那種把焦點關在裡面的 focus trap。Focus ring 對齊 Button:focus-visible:ring-2 ring-ring ring-offset-1(box-shadow ring,非 CSS outline)。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
+      <p className="whitespace-pre-line">{"  ARIA / Pattern  :繼承 Radix toggle-group primitive 的無障礙預設——整組 role=\"group\",每個 item role=\"radio\"(type=\"single\" 互斥選一),鍵盤導覽由 primitive 處理。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — 進入整組(只有一個 tab 停留點,落在選中項;沒選就落在上次 focus 過的 item,初次進入才是第一項)\n- ←/→ — 在 item 之間移動 roving focus(只移焦點,不切換選取)。WAI-ARIA APG 對水平 segmented/radio group 的主要導覽鍵\n- ↑/↓ — 同 ←/→,也會在 item 間移動 roving focus。Radix toggle-group 未鎖 orientation(沿用 default 雙軸 roving),APG 接受 group 同時支援兩軸方向鍵\n- Enter / Space — 選取目前 focus 的 item\n\n  Focus  :採 roving tabindex——整組共用一個 tab 停留點,方向鍵在 item 間移動焦點(選取仍需 Enter/Space/click);不是 Dialog 那種把焦點關在裡面的 focus trap。Focus ring 對齊 Button:focus-visible:ring-2 ring-ring ring-offset-1(box-shadow ring,非 CSS outline)。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
     </div>
   ),
 }

package/src/components/SegmentedControl/segmented-control.spec.md

@@ -58,6 +58,7 @@ SegmentedControl 是**互斥多選一的 compact control**——從 2–5 個選
 | 只有 1 個 | `Button pressed` | 沒有選擇語意 |
 | 切換的是 container 結構（整塊 view 有自己的 header / toolbar / filters）| `Tabs` | 見下「與 Tabs 的分界」 |
 | 選項需要描述文字 / 複雜排版 | `RadioGroup` | compact control 不支援多行內容 |
+| 頁碼導覽（大量資料翻頁） | `Pagination` | 位置導覽非互斥選值——頁數動態、可摺疊、數字無語意（見 `../Pagination/pagination.spec.md` 近親分界） |
 
 ---
 
@@ -207,7 +208,9 @@ SegmentedControl 必須能塞進 `Field` 容器（就像 `Input` / `Button` / `S
 
 ### 選中 / 未選
 
-- **選中**：文字與邊框都用 `--primary-hover`（底色維持 surface 不變）——pill 風格元件（Chip / SegmentedControl）共用的選中規則；selected item 提升 z-index 讓邊框浮在相鄰 item 之上，避免被重疊的 border 切掉（class 實作見 `segmented-control.tsx` `data-[state=on]` cva）
+- **選中**：文字與邊框都用 `--primary`（底色維持 surface 不變）——pill 風格元件（Chip / SegmentedControl）共用的選中規則（semantic.css「選中狀態」段 SSOT；2026-07-06 拍板自 primary-hover 改 base，hover 階專屬瞬時態）；selected item 提升 z-index 讓邊框浮在相鄰 item 之上，避免被重疊的 border 切掉（class 實作見 `segmented-control.tsx` `data-[state=on]` cva）。**❌ 選中態不得用 primary-hover**
+- **選中之上的 hover**：`--primary-hover` 同時染文字與邊框——選中元素的 hover = 同色相升 hover 階（2026-07-06 拍板；Button pressed hover 家族 + Ant active hover 同派，跟 Chip 一致），不用 neutral 灰底
+- **disabled × 選中疊加**：disabled 全滅（primary 描邊/染字退場 → `border-border` + `fg-disabled`）——M24 state > emphasis，跟 Chip 一致（2026-07-07 補明文）
 - **未選**：surface 底 + `--fg-secondary` 文字 + `--border` 邊框
   - hover：文字轉 `--foreground` + 邊框加深一階（`--border-hover`）+ 微提升 z-index；不改 bg，避免 hover 狀態與 selected 搶戲
 
@@ -256,7 +259,7 @@ Items 之間 `-ml-px`（除了第一個）讓相鄰 border 重疊、視覺上只
 
 ## 為何無 ColorMatrix
 
-- **無 ColorMatrix**:SegmentedControl 沒有 Button 那種強調層級 variant(primary / secondary / tertiary / text)——只有「選中 / 未選」兩種 **state**,色彩變化純由 state 驅動(底色恆為 `bg-surface` 不變;選中 = `text-primary-hover` + `border-primary-hover`;未選 hover = `text-foreground`,詳「狀態」段)。這是 pill 風格元件(Chip / SegmentedControl)共用的選中規則,非 Button variant。因此 ColorMatrix(逐 variant 列色)不適用,狀態色已在 `StateBehavior` 完整覆蓋。
+- **無 ColorMatrix**:SegmentedControl 沒有 Button 那種強調層級 variant(primary / secondary / tertiary / text)——只有「選中 / 未選」兩種 **state**,色彩變化純由 state 驅動(底色恆為 `bg-surface` 不變;選中 = `text-primary` + `border-primary`;未選 hover = `text-foreground`,詳「狀態」段)。這是 pill 風格元件(Chip / SegmentedControl)共用的選中規則,非 Button variant。因此 ColorMatrix(逐 variant 列色)不適用,狀態色已在 `StateBehavior` 完整覆蓋。
 
 對應 anatomy story:`Overview` + `Inspector` + `SizeMatrix` + `StateBehavior` + 元件特有 `FullWidthMatrix` + `IconOnlyMatrix` + `Accessibility`。Inspector 用 Storybook Controls 即時切 `size` × `fullWidth` × `iconOnly`(取代 Figma inspect);三張矩陣 story(`SizeMatrix` / `FullWidthMatrix` / `IconOnlyMatrix`)則提供結構性並排對照,兩者互補。
 
@@ -275,7 +278,7 @@ Items 之間 `-ml-px`（除了第一個）讓相鄰 border 重疊、視覺上只
 
 **Keyboard 行為**:
 
-- Tab — 進入 group(focus 在第一個或選中項)
+- Tab — 進入 group(focus 落在選中項;無選中時落在上次 focus 過的 item——Radix roving focus 記住停留點,初次進入才是第一項)
 - ←/→ — 在 item 間移動 roving focus(只移焦點,不切換選取)。WAI-ARIA APG 對水平 segmented/radio group 的主要導覽鍵
 - ↑/↓ — 同 ←/→,也會在 item 間移動 roving focus。Radix `toggle-group` 未鎖 `orientation`(沿用 default 雙軸 roving),APG 接受 group 同時支援兩軸方向鍵
 - Enter / Space — 選取目前 focus 的 item
@@ -291,6 +294,7 @@ Items 之間 `-ml-px`（除了第一個）讓相鄰 border 重疊、視覺上只
 - `button.spec.md`
 - `chip.spec.md`
 - `horizontal-overflow.spec.md`
+- `pagination.spec.md`
 - `radio-group.spec.md`
 - `select.spec.md`
 - `slider.spec.md`

package/src/components/SegmentedControl/segmented-control.tsx

@@ -105,6 +105,11 @@ const SegmentedControl = React.forwardRef<
     const resolvedSize = useResolvedFieldSize<SegmentedControlSize>(sizeProp, 'md')  // SSOT:統一 size resolution(原散落 ?? fieldCtx?.size ?? 'md')
     const resolvedDisabled = useResolvedFieldDisabled(disabled)
 
+    // 2026-07-04:恆 controlled mirror(見下方 onValueChange 註解)— uncontrolled consumer 的
+    // defaultValue 收進 internal state,Radix 永遠拿 controlled value → deselect 空值可攔。
+    const [internalValue, setInternalValue] = React.useState(defaultValue ?? '')  // '' = controlled 無選取(恆 controlled 從 mount 起,避免 un→controlled 切換)
+    const resolvedValue = value !== undefined ? value : internalValue
+
     // Memoize provider value(2026-04-22 D3 perf audit):避免每次父 render 重建 4-field object
     // 讓 children SegmentedControlItem 不必要 re-render
     const ctxValue = React.useMemo(
@@ -117,12 +122,16 @@ const SegmentedControl = React.forwardRef<
         <ToggleGroupPrimitive.Root
           ref={ref}
           type="single"
-          value={value}
-          defaultValue={defaultValue}
+          value={resolvedValue}
           onValueChange={(v) => {
             // Radix 的 single ToggleGroup 允許 deselect（返回空字串）
-            // SegmentedControl 是 radio 語意，不允許空值——忽略 deselect
-            if (v) onValueChange?.(v)
+            // SegmentedControl 是 radio 語意，不允許空值——忽略 deselect。
+            // 2026-07-04 修:原 uncontrolled(只傳 defaultValue)時 Radix 內部 state 直通,
+            // 點已選中項照樣 deselect 成空值(spec:236「恆有一值」失守)→ wrapper 恆 controlled
+            // (internalValue mirror),空字串一律不進 state 也不呼叫 consumer callback。
+            if (!v) return
+            if (value === undefined) setInternalValue(v)
+            onValueChange?.(v)
           }}
           disabled={resolvedDisabled}
           className={cn(segmentedControlVariants({ fullWidth }), className)}
@@ -166,12 +175,19 @@ const itemVariants = cva(
     'disabled:hover:text-fg-disabled disabled:hover:border-border',
     // hover（未選）：border 加深一階 + 文字轉深，對齊 Input / Chip hover
     'hover:text-foreground hover:border-border-hover hover:z-[5]',
-    // selected: 文字 + 邊框都用 primary-hover,底色維持 bg-surface 不變 (跟 Chip 一致)
-    //   ── 這是 pill 風格元件 (Chip / SegmentedControl) 的 canonical 選中規則:
-    //      primary-hover 同時染文字和線條;底色不改 (不用 primary-subtle)。
-    //      Tabs 是 underline 風格,規則不同 (文字 foreground + 底線 primary-hover)。
+    // selected: 文字 + 邊框都用 primary base,底色維持 bg-surface 不變 (跟 Chip 一致)
+    //   ── 這是 pill 風格元件 (Chip / SegmentedControl) 的 canonical 選中規則(SSOT = semantic.css「選中狀態」段):
+    //      primary base 同時染文字和線條;底色不改 (不用 primary-subtle)。
+    //      2026-07-06 user 拍板:持續選中 hover 階 → base(三家世界級「瞬時弱、持續強」實錘)。
+    //      Tabs 是 underline 風格,規則不同 (文字 foreground + 底線 primary)。
     //   z-10 讓 border 浮在相鄰 item 之上
-    'data-[state=on]:text-primary-hover data-[state=on]:border-primary-hover data-[state=on]:z-10',
+    'data-[state=on]:text-primary data-[state=on]:border-primary data-[state=on]:z-10',
+    // 選中之上的 hover = 同色相升 hover 階(2026-07-06 user 拍板;Button pressed hover 家族
+    // + Ant active hover 同派;跟 Chip 一致,顯式宣告解掉 CSS 平手 source-order 脆弱性)
+    'data-[state=on]:hover:text-primary-hover data-[state=on]:hover:border-primary-hover',
+    // disabled × selected 疊加(2026-07-07 user 拍板統一;M24 disabled 全滅,同 Chip)
+    'data-[state=on]:disabled:border-border data-[state=on]:disabled:text-fg-disabled',
+    'data-[state=on]:disabled:hover:border-border data-[state=on]:disabled:hover:text-fg-disabled',
     // item 連體：除第一個外，-ml-px 讓相鄰 border 重疊
     'first:rounded-l-md last:rounded-r-md',
     '[&:not(:first-child)]:-ml-px',
@@ -290,10 +306,12 @@ export const segmentedControlMeta = {
     md: { fieldHeight: 32, typography: 'body', iconSize: 16, purpose: '預設 — form field 對齊' },
     lg: { fieldHeight: 36, typography: 'body-lg', iconSize: 20, purpose: 'touch / prominent CTA' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 2026-07-04 audit 對齊:cva 無 active(按下)專屬樣式,移除 'active'
+  // 'selected' = data-[state=on](2026-07-07 meta 詞彙統一補列:持續選中一律 'selected';cva 無按壓 active 樣式)
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
     bg: ['bg-surface'],
-    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],
+    fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground', 'text-primary'], // selected 態 cva data-[state=on]:text-primary 實際消費(2026-07-06 選中改 base)
     ring: ['ring-ring'],
   },
   defaultSize: 'md',

package/src/components/Select/select.anatomy.stories.tsx

@@ -62,7 +62,7 @@ const TOKEN_MAP: Record<ModeKey, Record<StateKey, ColorSpec>> = {
   },
 }
 
-// Error state tokens (edit only) — traced from select.tsx line 177-178
+// Error state tokens (edit only) — traced from select.tsx:431/444/598(NativeSelect 兩處 + CustomSelect trigger)
 // border-error hover:border-error-hover, focus-within:border-error
 const ERROR_TOKENS: Record<StateKey, ColorSpec> = {
   default:  { bg: '--surface', text: '--foreground', border: '--error',       icon: '--fg-muted' },
@@ -324,7 +324,7 @@ export const Overview = {
                 ['onOpenChange', '(open: boolean) => void', '—', 'open 狀態變更 callback'],
                 ['showDisplayEndIcon', 'boolean', 'false', 'display 模式渲 ChevronDown(DataTable cell 對齊)'],
                 ['selectedItemRenderer', '(opt: SelectOption) => ReactNode', '—', 'trigger 已選項目客製 render(PeoplePicker 用)'],
-                ['disabled', 'boolean', '—', '原生屬性，自動覆蓋 mode 為 disabled'],
+                ['disabled', 'boolean', '—', '原生屬性；未傳 mode 時 resolve 為 disabled 樣式（顯式 mode prop 恆優先，見 useResolvedFieldMode）'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
               ))}

package/src/components/Select/select.spec.md

@@ -273,7 +273,7 @@ Select 的值套用時機是**由 onChange handler 的副作用決定**，不是
 
 ## Loading
 
-`loading?: boolean`(forward 給 SelectMenu SSOT,2026-05-15 audit B 補):dropdown body 內取代 options 顯 `<Empty icon={<CircularProgress size={48}/>}/>`(消費 既有 empty.spec.md「現有消費者」SelectMenu loading row SSOT)+ `aria-busy`。Trigger 不變(chevron 保留,user 隨時可開)。對齊 MUI Autocomplete `loadingText` 雙層 + Ant Select loading,反 trigger spinner 派。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+`loading?: boolean`(forward 給 SelectMenu SSOT,2026-05-15 audit B 補;**2026-07-04 Q3 拍板措辭修訂 — 不清空 stale options**):spinner 只在**無可顯示選項時**佔 empty slot 顯 `<Empty icon={<CircularProgress size={48}/>}/>`(cmdk `CommandEmpty` 機制;已有 options 時保留顯示,不取代)+ `aria-busy`。Trigger 不變(chevron 保留,user 隨時可開)。Benchmark 實查:MUI Autocomplete 官方逐字「shows the loadingText in place of suggestions **only if there are no suggestions to show**」/ Ant Select 清空是 consumer 自選(demo select-users.tsx setOptions([]))非元件行為 — 原「取代 options」是過度宣稱,code 行為即世界級共識。
 
 ---
 
@@ -313,12 +313,13 @@ Select 是 **Field Controls family 成員**——互動狀態(focus / invalid /
 
 ## A11y 預設
 
-**ARIA / Pattern**:依裝置分兩條路徑。桌機(非觸控)觸發點是容器 `<div>`,標記 `role="combobox"` + `aria-expanded` / `aria-haspopup="listbox"`,選項在浮層 listbox 裡;searchable 模式時容器內另放可打字篩選的 `<input>`。手機(觸控)改用瀏覽器原生 `<select>` element,直接取得作業系統內建的無障礙與 picker。兩路徑皆由 Field wrapper 補 `aria-invalid` / `aria-required` / `aria-describedby` / `aria-errormessage`。
+**ARIA / Pattern**:依裝置分兩條路徑。桌機(非觸控)觸發點是容器 `<div>`,標記 `role="combobox"` + `aria-expanded` / `aria-haspopup="listbox"`,選項在浮層 listbox 裡;searchable 模式時容器內另放可打字篩選的 `<input>`(開啟時實際聚焦的元素,accessible name 直接接在 input 本身:有 Field label 時 `aria-labelledby` 指向之、consumer `aria-label` 優先,兩者皆無時 fallback「搜尋選項」——與 Combobox 搜尋框 `searchAriaLabel` 同 canonical)。手機(觸控)改用瀏覽器原生 `<select>` element,直接取得作業系統內建的無障礙與 picker。兩路徑皆由 Field wrapper 補 `aria-invalid` / `aria-required` / `aria-describedby` / `aria-errormessage`。
 
 **Keyboard 行為**:
 
 - Tab — 聚焦到觸發點
 - Enter / Space — 展開選單(searchable 模式則直接進入打字篩選)
+- ↓ — 選單關閉時亦可直接展開(APG combobox 展開鍵,與 Combobox 同 pattern;展開後不攔,讓方向鍵導覽選單)
 - ↑ / ↓ — 選單展開後在選項間移動
 - Esc — 關閉選單(清除值走右側 clear 按鈕,非 Esc)