@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.84

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

@@ -1,5 +1,8 @@
 // @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.
 // @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+// @overlay-open-skip: 本檔絕大多數 story 直接 render ProfileCard(內容不藏在浮層,snapshot 可見);
+//   唯一 HoverCard demo 只示範「hover 整合」消費方式,open-state 內容已由同檔直接 render 的
+//   stories 完整快照,forced defaultOpen 反而讓浮層蓋住旁邊的說明。
 // @anatomy-rationale:
 //   SizeMatrix N/A — ProfileCard 是固定寬度(320px)hover content template,
 //     不提供 size prop;所有尺寸 token 已於 Overview「Layout Token」段列出
@@ -51,12 +54,7 @@ export const Overview: Story = {
             subtitle="Design Engineer · Engineering"
             status="online"
             statusMessage="目前 Sprint 23 衝刺中,訊息可能稍慢回覆"
-            actions={
-              <>
-                <Button variant="primary" size="sm" startIcon={MessageCircle}>傳訊</Button>
-                <Button variant="tertiary" size="sm" startIcon={UserPlus}>追蹤</Button>
-              </>
-            }
+            actions={<ProfileCardDefaultActions />}
             fields={[
               { label: 'Email', value: 'ada.chen@example.com' },
               { label: '團隊', value: 'Engineering' },
@@ -228,18 +226,13 @@ export const SectionMatrix: Story = {
 
       <div>
         <H3>+ Actions</H3>
-        <Desc>加上快速動作——留言區 hover 顯示「傳訊」/「追蹤」,減少跳轉 profile 頁的摩擦。</Desc>
+        <Desc>加上快速動作——留言區 hover 顯示「Chat」/「Audio call」(canonical `ProfileCardDefaultActions`),減少跳轉 profile 頁的摩擦。</Desc>
         <div className="border border-dashed border-divider rounded-md p-4 inline-block">
           <ProfileCard
             name="Diana Lin"
             subtitle="Engineering Manager"
             status="online"
-            actions={
-              <>
-                <Button variant="primary" size="sm" startIcon={MessageCircle}>傳訊</Button>
-                <Button variant="tertiary" size="sm" startIcon={UserPlus}>追蹤</Button>
-              </>
-            }
+            actions={<ProfileCardDefaultActions />}
           />
         </div>
       </div>
@@ -271,12 +264,7 @@ export const SectionMatrix: Story = {
             subtitle="Design Engineer · Engineering"
             status="online"
             statusMessage="目前專案 Sprint 23 衝刺中"
-            actions={
-              <>
-                <Button variant="primary" size="sm" startIcon={MessageCircle}>傳訊</Button>
-                <Button variant="tertiary" size="sm" startIcon={UserPlus}>追蹤</Button>
-              </>
-            }
+            actions={<ProfileCardDefaultActions />}
             fields={[
               { label: 'Email', value: 'ada.chen@example.com' },
               { label: '團隊', value: 'Engineering' },
@@ -366,14 +354,14 @@ export const HoverCardIntegration: Story = {
         </Desc>
         <div className="border border-border rounded-lg p-6 flex items-center gap-8">
           {[
-            { name: 'Ada Chen（範例人名）', subtitle: 'Design Engineer', status: 'online' as const },
-            { name: 'Alice Wang', subtitle: 'Frontend Engineer', status: 'busy' as const },
-            { name: 'Bob Chen', subtitle: 'PM, Growth', status: 'away' as const },
+            { name: 'Ada Chen', subtitle: 'Design Engineer', status: 'online' as const, avatarUrl: 'https://i.pravatar.cc/80?u=ada-chen' },
+            { name: 'Alice Wang', subtitle: 'Frontend Engineer', status: 'busy' as const, avatarUrl: 'https://i.pravatar.cc/80?u=alice-wang' },
+            { name: 'Bob Chen', subtitle: 'PM, Growth', status: 'away' as const, avatarUrl: 'https://i.pravatar.cc/80?u=bob-chen' },
           ].map(p => (
             <HoverCard key={p.name}>
               <HoverCardTrigger asChild>
                 <span className="inline-block cursor-pointer">
-                  <Avatar alt={p.name} size={40} status={p.status} />
+                  <Avatar src={p.avatarUrl} alt={p.name} size={40} status={p.status} />
                 </span>
               </HoverCardTrigger>
               <HoverCardContent align="start" className="p-0">{/* sideOffset 不 override — spec 禁止事項(default 即 OVERLAY_SIDE_OFFSET) */}
@@ -381,6 +369,7 @@ export const HoverCardIntegration: Story = {
                   name={p.name}
                   subtitle={p.subtitle}
                   status={p.status}
+                  avatar={{ src: p.avatarUrl, alt: p.name }}
                   fields={[
                     { label: 'Email', value: `${p.name.split(' ')[0].toLowerCase()}@example.com` },
                     { label: '團隊', value: 'Engineering' },

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

@@ -57,13 +57,13 @@ ProfileCard 是**三層 chrome 結構**(2026-04-23 canonical):
 │ BODY(可垂直捲動)            │  ← Status section(v12 conditional)+ Info fields(always-render)
 │ ↕ 空間不足時此區捲動         │    Status undefined → 整 status block skip
 ├─────────────────────────────┤
-│ FOOTER(固定不捲)            │  ← View more(hover context 必含,詳「View More」)
+│ FOOTER(固定不捲)            │  ← View more(傳 onViewMore 時顯示,詳「View More」)
 └─────────────────────────────┘
 ```
 
 - **Header 固定**:Profile + Actions 一體,**不捲動**(使用者的視覺 anchor:誰 + 可對他做什麼)
 - **Body 可捲動**:Status section + Info fields。以 `<ScrollArea>` 包(cross-OS overlay 捲軸)
-- **Footer 固定**:View more **永遠可見**(hover preview 的 escape hatch 到完整 profile)
+- **Footer 固定**:傳入 `onViewMore` 時 View more 固定於底(條件渲染 `{onViewMore && …}`,未傳則不渲染 footer)——是 hover preview 到完整 profile 的 escape hatch(對齊本 spec「View More」段 + `profile-card.tsx` footer 條件渲染)
 
 **Status section v12 conditional rule(2026-05-14 user 拍板)**:`status` 在 production 一定會被設定(每個 user 都有 presence state)。如果 status undefined,**唯一可能性 = 資料還沒讀到(loading transient)**,**不**是「user 沒設定狀態」。所以 status undefined 期間 → **整 status block 隱藏**(等資料到才 render),**禁** render「Status not set」這種 placeholder 文字(語義錯,user presence 不會「沒設定」)。**此規則 ProfileCard-specific 不外推至 DS 其他元件**(FileItem / DescriptionList / DataTable cell 各自 placeholder 邏輯 unrelated)。
 
@@ -134,7 +134,7 @@ ProfileCard 的 default actions **是 `Chat + Audio call`**(chat app 標配,cano
 
 - **Name / Subtitle 超長**:自然換行撐高 header,不截斷(text column 最小高度對齊 avatar,見「Profile Header」)
 - **Status / statusMessage 缺值**:status undefined = loading transient → 整 status block 隱藏(v12 rule,見「結構」);ProfileCard **無整卡 loading prop**,資料未到的整卡呈現由 consumer 決定
-- **Info fields 缺值**:default fields 永遠 render,缺資料顯 `—` placeholder(section 結構不收合);consumer `fields` label 撞 default 時 consumer 值 win(dedup canonical,詳 `profile-card.tsx`)
+- **Info fields 缺值**:default fields 永遠 render,缺資料顯半形 `-` placeholder(`text-foreground`——對齊 DS 空值顯示 canonical:不可編輯供檢視的空值同 readonly 值色;section 結構不收合);consumer `fields` label 撞 default 時 consumer 值 win(dedup canonical,詳 `profile-card.tsx`)
 - **內容過長**:Body 在固定高度內以 ScrollArea 捲動,不 clamp 行數(見「Status 區」)
 
 ---

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

@@ -105,7 +105,7 @@ const STATUS_LABEL: Record<StatusType, string> = {
  * 各自不一致(同 person 在 DataTable / PeoplePicker / avatar.principles 看起來不同)。
  *
  * v11 canonical(歷史):ProfileCard 當時 always renders 4 default sections — 缺 data → 顯
- * `EMPTY_PLACEHOLDER`("—")。現行:default fields 縮為 2(v15.7)+ status 條件 render(v12),
+ * `EMPTY_PLACEHOLDER`("-")。現行:default fields 縮為 2(v15.7)+ status 條件 render(v12),
  * 「視覺結構 SSOT 在此元件,不依賴 consumer」原則不變。
  *
  * ── 對齊 world-class ──
@@ -128,7 +128,7 @@ const DEFAULT_FIELD_LABEL: Record<ProfileCardDefaultFieldKey, string> = {
   employeeNumber: 'Employee number',
 }
 
-const FIELD_PLACEHOLDER = '—'
+const FIELD_PLACEHOLDER = '-'
 
 export interface ProfileCardProps extends React.HTMLAttributes<HTMLDivElement> {
   name: string
@@ -139,7 +139,7 @@ export interface ProfileCardProps extends React.HTMLAttributes<HTMLDivElement> {
   actions?: React.ReactNode
   /**
    * Consumer 傳的 field 資料(partial)。預設 keys 走 `NAMECARD_DEFAULT_FIELD_KEYS` —
-   * 只有 id / employeeNumber 兩個 default field 永遠 render(缺資料顯 `—`);email / phone /
+   * 只有 id / employeeNumber 兩個 default field 永遠 render(缺資料顯 `-`);email / phone /
    * department / location 等其他欄位一律 opt-in by consumer 透過本 prop 傳入。Consumer 想新增
    * 自訂 field 直接傳入(在 default 之後 append),想 override default key value 也直接傳。
    */
@@ -178,7 +178,7 @@ const ProfileCard = React.forwardRef<HTMLDivElement, ProfileCardProps>(
     //
     // **Dedup canonical(2026-05-07 v15.8 fix Bug E)**:consumer 的 `fields` array 若含
     // label 撞 default(eg. 「ID」「Employee number」),consumer 值 win — defaults 那一行
-    // 跳過(否則 same label 連 render 兩次,如 default placeholder `—` + consumer 真值)。
+    // 跳過(否則 same label 連 render 兩次,如 default placeholder `-` + consumer 真值)。
     // 這是遷移期 forgiving 行為:DEV warn 提示應改用 `defaultFieldValues`,但 production
     // 不破壞既有 consumer。對齊 React `key` 唯一性 + Linear / Slack profile card 一 label
     // 一 row idiom。
@@ -292,7 +292,7 @@ const ProfileCard = React.forwardRef<HTMLDivElement, ProfileCardProps>(
                   message 是一組;沒 status 就沒 status message)。缺 statusMessage 顯 placeholder。 */}
               <DescriptionList>
                 <DescriptionItem label="Status message">
-                  {statusMessage ?? <span className="text-fg-muted">{FIELD_PLACEHOLDER}</span>}
+                  {statusMessage ?? <span className="text-foreground">{FIELD_PLACEHOLDER}</span>}
                 </DescriptionItem>
               </DescriptionList>
             </div>
@@ -304,7 +304,7 @@ const ProfileCard = React.forwardRef<HTMLDivElement, ProfileCardProps>(
               {allFields.map((f) => (
                 <DescriptionItem key={f.label} label={f.label}>
                   {f.value === FIELD_PLACEHOLDER
-                    ? <span className="text-fg-muted">{FIELD_PLACEHOLDER}</span>
+                    ? <span className="text-foreground">{FIELD_PLACEHOLDER}</span>
                     : f.value}
                 </DescriptionItem>
               ))}

package/src/components/ProgressBar/progress-bar.anatomy.stories.tsx

@@ -74,8 +74,10 @@ export const Overview = {
                   <div className="h-full rounded-full bg-info" style={{ width: '45%' }} />
                 </div>
               </div>
+              {/* 2026-07-14 dim-55 修:`--magenta`/`--magenta-subtle` 不存在(semantic magenta namespace
+                  只有 hover/active)→ anatomy 圖解標記屬 categorical 靜態色,消費 primitive step token */}
               <span className="rounded px-2 py-0.5 text-[11px] font-mono border border-dashed"
-                style={{ borderColor: 'var(--magenta)', backgroundColor: 'var(--magenta-subtle)', color: 'var(--magenta)' }}>affix</span>
+                style={{ borderColor: 'var(--color-magenta-6)', backgroundColor: 'var(--color-magenta-1)', color: 'var(--color-magenta-7)' }}>affix</span>
             </div>
             <span className="text-[10px] text-fg-muted font-mono">wrapper: flex items-center gap-2 · bar: flex-1 min-w-0</span>
           </div>

package/src/components/ProgressBar/progress-bar.principles.stories.tsx

@@ -129,7 +129,7 @@ export const UsageGuidance: Story = {
               </div>
             </div>
           </Frame>
-          <Label>✅ 每檔一條,整體進度由使用者自然感知(2/3 完成)</Label>
+          <Label>✅ 每檔一條,整體進度由使用者自然感知(1 檔完成、2 檔進行中)</Label>
         </Rule>
 
         <Rule

package/src/components/ProgressBar/progress-bar.stories.tsx

@@ -1,6 +1,10 @@
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.anatomy.stories.tsx#AlignmentRule
 import type { Meta, StoryObj } from '@storybook/react'
+import type { ColumnDef } from '@tanstack/react-table'
 import { FileText, Table as TableIcon } from 'lucide-react'
 import { ProgressBar } from './progress-bar'
+import { DataTable } from '@/design-system/components/DataTable/data-table'
+import '@/design-system/components/DataTable/column-types' // ColumnMeta declaration merging
 
 const meta: Meta<typeof ProgressBar> = {
   title: 'Design System/Components/ProgressBar/展示',
@@ -70,50 +74,54 @@ export const BatchTask: Story = {
 }
 
 // ── 真實情境 3: DataTable cell inline 進度 ─────────────────────────────
+// 2026-07-14 audit(R1 A.2):手刻 table markup → 消費真 <DataTable>(對齊 Skeleton
+// TableRowLoading 同款 consumer-自訂-cell 模式;columns 不設 meta.type 走自訂 cell)。
 
-export const InlineTableCell: Story = {
-  name: 'DataTable 儲存格內進度',
-  render: () => {
-    const rows = [
-      { name: 'Acme Corp 專案', quota: 45, status: 'inProgress' as const },
-      { name: 'Globex 整合', quota: 78, status: 'inProgress' as const },
-      { name: 'Initech 改版', quota: 100, status: 'success' as const },
-      { name: 'Umbrella 導入', quota: 12, status: 'inProgress' as const },
-      { name: 'Wonka 客製化', quota: 95, status: 'error' as const },
-    ]
-    return (
-      <div className="flex flex-col gap-4 w-[560px]">
-        <SectionTitle>配額使用率(DataTable inline)</SectionTitle>
-        <SectionDesc>
-          Table cell 內顯示配額使用率(4px 細線不搶走主要欄位的閱讀重量)。value affix 讓使用者快速讀數字。
-        </SectionDesc>
-        <div className="border border-border rounded-md overflow-hidden bg-surface">
-          <table className="w-full text-body">
-            <thead className="bg-muted text-caption text-fg-secondary">
-              <tr>
-                <th className="text-left px-4 py-2 font-medium">專案</th>
-                <th className="text-left px-4 py-2 font-medium w-[240px]">配額使用率</th>
-              </tr>
-            </thead>
-            <tbody>
-              {rows.map((r) => (
-                <tr key={r.name} className="border-t border-divider">
-                  <td className="px-4 py-3">
-                    <div className="flex items-center gap-2">
-                      <FileText size={16} className="text-fg-muted shrink-0" />
-                      {r.name}
-                    </div>
-                  </td>
-                  <td className="px-4 py-3">
-                    <ProgressBar value={r.quota} status={r.status} affix="value" />
-                  </td>
-                </tr>
-              ))}
-            </tbody>
-          </table>
-        </div>
+interface QuotaRow {
+  name: string
+  quota: number
+  status: 'inProgress' | 'success' | 'error'
+}
+
+const quotaRows: QuotaRow[] = [
+  { name: 'Acme Corp 專案', quota: 45, status: 'inProgress' },
+  { name: 'Globex 整合', quota: 78, status: 'inProgress' },
+  { name: 'Initech 改版', quota: 100, status: 'success' },
+  { name: 'Umbrella 導入', quota: 12, status: 'inProgress' },
+  { name: 'Wonka 客製化', quota: 95, status: 'error' },
+]
+
+const quotaColumns: ColumnDef<QuotaRow>[] = [
+  {
+    id: 'name',
+    header: '專案',
+    cell: ({ row }) => (
+      <div className="flex items-center gap-2">
+        <FileText size={16} className="text-fg-muted shrink-0" />
+        {row.original.name}
       </div>
-    )
+    ),
   },
+  {
+    id: 'quota',
+    header: '配額使用率',
+    meta: { width: 240 },
+    cell: ({ row }) => (
+      <ProgressBar value={row.original.quota} status={row.original.status} affix="value" />
+    ),
+  },
+]
+
+export const InlineTableCell: Story = {
+  name: 'DataTable 儲存格內進度',
+  render: () => (
+    <div className="flex flex-col gap-4 w-[560px]">
+      <SectionTitle>配額使用率(DataTable inline)</SectionTitle>
+      <SectionDesc>
+        Table cell 內顯示配額使用率(4px 細線不搶走主要欄位的閱讀重量)。value affix 讓使用者快速讀數字。
+      </SectionDesc>
+      <DataTable columns={quotaColumns} data={quotaRows} getRowId={(r) => r.name} height="auto" />
+    </div>
+  ),
 }
 

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

@@ -1,7 +1,6 @@
 import type { Meta } from '@storybook/react'
 import { useState } from 'react'
 import { RadioGroup, RadioGroupItem } from './radio-group'
-import { SelectionItem } from '@/design-system/components/SelectionControl/selection-item'
 
 const meta: Meta = {
   title: 'Design System/Components/RadioGroup/設計規格',
@@ -287,20 +286,18 @@ const InspectorInner = () => {
           {/* Live preview */}
           <div className="px-10 py-8 rounded-lg bg-canvas border border-divider flex items-center justify-center gap-6">
             <RadioGroup defaultValue={checked === 'checked' ? 'preview' : undefined} className="flex gap-4">
-              <SelectionItem
+              <RadioGroupItem
                 size={size}
-                control={<RadioGroupItem value="preview" id="preview-radio" size={size} disabled={state === 'disabled'} />}
+                value="preview"
                 label="信用卡"
                 description={withDescription ? '支援 Visa / Mastercard / JCB,結帳時直接扣款' : undefined}
-                htmlFor="preview-radio"
                 disabled={state === 'disabled'}
               />
-              <SelectionItem
+              <RadioGroupItem
                 size={size}
-                control={<RadioGroupItem value="other" id="preview-other" size={size} disabled={state === 'disabled'} />}
+                value="other"
                 label="ATM 轉帳"
                 description={withDescription ? '取得虛擬帳號後 3 天內完成付款' : undefined}
-                htmlFor="preview-other"
                 disabled={state === 'disabled'}
               />
             </RadioGroup>
@@ -534,26 +531,9 @@ export const SizeMatrix = {
             <div key={sz} className="flex flex-col gap-2">
               <span className="text-[11px] text-fg-muted font-mono">size="{sz}" ({SIZE_SPECS[sz].controlPx}px)</span>
               <RadioGroup defaultValue="a">
-                <SelectionItem
-                  size={sz}
-                  control={<RadioGroupItem value="a" id={`sz-${sz}-a`} size={sz} />}
-                  label="即時"
-                  htmlFor={`sz-${sz}-a`}
-                />
-                <SelectionItem
-                  size={sz}
-                  control={<RadioGroupItem value="b" id={`sz-${sz}-b`} size={sz} />}
-                  label="每日摘要"
-                  description="每天晚上 9 點寄一次"
-                  htmlFor={`sz-${sz}-b`}
-                />
-                <SelectionItem
-                  size={sz}
-                  control={<RadioGroupItem value="c" id={`sz-${sz}-c`} size={sz} disabled />}
-                  label="每週摘要"
-                  htmlFor={`sz-${sz}-c`}
-                  disabled
-                />
+                <RadioGroupItem size={sz} value="a" label="即時" />
+                <RadioGroupItem size={sz} value="b" label="每日摘要" description="每天晚上 9 點寄一次" />
+                <RadioGroupItem size={sz} value="c" label="每週摘要" disabled />
               </RadioGroup>
             </div>
           ))}
@@ -629,8 +609,10 @@ const StateBehaviorInner = () => {
       {/* Whole group disabled */}
       <div className="flex flex-col gap-3">
         <span className="text-caption font-medium text-fg-secondary">行為 3:整組 disabled(Field context 接管)</span>
+        {/* 架構理由(移出 user-visible Desc,per story-rules.md 人話原則):item 經 useResolvedFieldDisabled
+            繼承 Field 的 disabled;SSOT = field-controls.spec.md cascade 段。 */}
         <Desc>
-          整個 RadioGroup 放在 disabled 的 Field 內時,所有 item 經 useResolvedFieldDisabled 繼承 disabled——consumer 不需逐 item 傳 disabled(SSOT:field-controls.spec.md cascade 段)。下方示意為靜態模擬(逐 item 傳 disabled 重現相同視覺);實際使用以 {'<Field disabled>'} 包裹即可。
+          整組放進停用的 Field 時,裡面每個選項會自動一起變灰,不需逐一設定。下方為靜態示意(逐 item 傳 disabled 重現相同視覺);實際使用以 {'<Field disabled>'} 包裹即可。
         </Desc>
         <div className="flex gap-6 items-start">
           <div className="px-6 py-5 rounded-lg bg-canvas border border-divider min-w-[280px]">

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

@@ -1,7 +1,6 @@
 // @story-trait-rationale: hasSizes 由 anatomy.stories.tsx SizeMatrix auto-compile owns size showcase(2026-05-15 F-migration);Default scenario 由 WithLabel / HorizontalLayout 等真實 form 情境 story 覆蓋。
 import type { Meta, StoryObj } from '@storybook/react'
 import { RadioGroup, RadioGroupItem } from './radio-group'
-import { SelectionItem } from '@/design-system/components/SelectionControl/selection-item'
 
 const meta: Meta<typeof RadioGroupItem> = {
   title: 'Design System/Components/RadioGroup/展示',
@@ -12,6 +11,10 @@ const meta: Meta<typeof RadioGroupItem> = {
 export default meta
 type Story = StoryObj<typeof RadioGroupItem>
 
+// 2026-07-14 dim-68 修:展示層原直用 internal <SelectionItem control={...} htmlFor>(selection-item.spec.md
+// 「何時用」明文禁止裸用)→ 收斂為公開 <RadioGroupItem value label description>(自動 wire SelectionItem
+// + id/htmlFor),與同元件 principles / anatomy 層一致 — 三層 story 一律示範公開 API。
+
 // @story-trait-rationale: pre-existing trait gaps tracked separately; this PR scope = add Modes story with display card.
 /* ── 四模式 ── */
 export const Modes: Story = {
@@ -21,35 +24,35 @@ export const Modes: Story = {
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">edit</h3>
         <RadioGroup defaultValue="yearly" aria-label="付款方案(edit mode demo)">
-          <SelectionItem control={<RadioGroupItem value="monthly" id="m-edit" />} label="月付方案" htmlFor="m-edit" />
-          <SelectionItem control={<RadioGroupItem value="yearly" id="y-edit" />} label="年付方案" description="每年 $2,990，省下兩個月" htmlFor="y-edit" />
-          <SelectionItem control={<RadioGroupItem value="lifetime" id="l-edit" />} label="終身方案" htmlFor="l-edit" />
+          <RadioGroupItem value="monthly" label="月付方案" />
+          <RadioGroupItem value="yearly" label="年付方案" description="每年 $2,990，省下兩個月" />
+          <RadioGroupItem value="lifetime" label="終身方案" />
         </RadioGroup>
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">display</h3>
         <RadioGroup mode="display" value="yearly" aria-label="付款方案(display mode demo)">
-          <SelectionItem control={<RadioGroupItem value="monthly" id="m-disp" />} label="月付方案" htmlFor="m-disp" />
-          <SelectionItem control={<RadioGroupItem value="yearly" id="y-disp" />} label="年付方案" description="每年 $2,990，省下兩個月" htmlFor="y-disp" />
-          <SelectionItem control={<RadioGroupItem value="lifetime" id="l-disp" />} label="終身方案" htmlFor="l-disp" />
+          <RadioGroupItem value="monthly" label="月付方案" />
+          <RadioGroupItem value="yearly" label="年付方案" description="每年 $2,990，省下兩個月" />
+          <RadioGroupItem value="lifetime" label="終身方案" />
         </RadioGroup>
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
-        <RadioGroup value="yearly" aria-label="付款方案(readonly mode demo)">
-          <SelectionItem control={<RadioGroupItem value="monthly" id="m-ro" readOnly />} label="月付方案" htmlFor="m-ro" />
-          <SelectionItem control={<RadioGroupItem value="yearly" id="y-ro" readOnly />} label="年付方案" htmlFor="y-ro" />
-          <SelectionItem control={<RadioGroupItem value="lifetime" id="l-ro" readOnly />} label="終身方案" htmlFor="l-ro" />
+        <RadioGroup mode="readonly" value="yearly" aria-label="付款方案(readonly mode demo)">
+          <RadioGroupItem value="monthly" label="月付方案" />
+          <RadioGroupItem value="yearly" label="年付方案" />
+          <RadioGroupItem value="lifetime" label="終身方案" />
         </RadioGroup>
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">disabled</h3>
         {/* mode="disabled" → Radix Root disabled 原生 propagate 全 item(radio 控件真停用);
-            SelectionItem disabled 另管 label 降色 — 雙傳對齊「停用」story 寫法 */}
+            RadioGroupDisabledContext 同步讓每個 item 的 label/description 降 text-fg-disabled */}
         <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 />
+          <RadioGroupItem value="monthly" label="月付方案" />
+          <RadioGroupItem value="yearly" label="年付方案" />
+          <RadioGroupItem value="lifetime" label="終身方案" />
         </RadioGroup>
       </div>
     </div>
@@ -58,7 +61,7 @@ export const Modes: Story = {
 
 // @story-trait-rationale: States retired 2026-05-17 per audit Dim 24 —
 //   anatomy.stories.tsx SizeMatrix + StateBehavior own size/state trait grid。
-//   展示層保留 typical real-product Group 情境(Vertical/Horizontal/Modes/Disabled)。
+//   展示層保留 typical real-product Group 情境(Vertical/Horizontal/Modes)。
 
 /* ── 垂直 Group ── */
 export const VerticalGroup: Story = {
@@ -69,9 +72,9 @@ export const VerticalGroup: Story = {
         <div key={size}>
           <p className="text-caption text-fg-muted mb-1">size="{size}"</p>
           <RadioGroup defaultValue="monthly">
-            <SelectionItem size={size} control={<RadioGroupItem value="monthly" id={`${size}-monthly`} size={size} />} label="月付方案" htmlFor={`${size}-monthly`} />
-            <SelectionItem size={size} control={<RadioGroupItem value="yearly" id={`${size}-yearly`} size={size} />} label="年付方案" description="每年 $2,990，省下兩個月" htmlFor={`${size}-yearly`} />
-            <SelectionItem size={size} control={<RadioGroupItem value="lifetime" id={`${size}-lifetime`} size={size} />} label="終身方案" htmlFor={`${size}-lifetime`} />
+            <RadioGroupItem size={size} value="monthly" label="月付方案" />
+            <RadioGroupItem size={size} value="yearly" label="年付方案" description="每年 $2,990，省下兩個月" />
+            <RadioGroupItem size={size} value="lifetime" label="終身方案" />
           </RadioGroup>
         </div>
       ))}
@@ -84,20 +87,14 @@ export const Horizontal: Story = {
   name: '水平排列',
   render: () => (
     <RadioGroup defaultValue="light" className="flex gap-6 max-w-md">
-      <SelectionItem control={<RadioGroupItem value="light" id="h-light" />} label="淺色" htmlFor="h-light" />
-      <SelectionItem control={<RadioGroupItem value="dark" id="h-dark" />} label="深色" htmlFor="h-dark" />
-      <SelectionItem control={<RadioGroupItem value="system" id="h-system" />} label="系統" htmlFor="h-system" />
+      <RadioGroupItem value="light" label="淺色" />
+      <RadioGroupItem value="dark" label="深色" />
+      <RadioGroupItem value="system" label="系統" />
     </RadioGroup>
   ),
 }
 
-/* ── Disabled ── */
-export const Disabled: Story = {
-  name: '停用',
-  render: () => (
-    <RadioGroup defaultValue="bank" className="max-w-sm">
-      <SelectionItem control={<RadioGroupItem value="bank" id="dis-a" disabled />} label="銀行轉帳" description="帳單已開立,付款方式鎖定" htmlFor="dis-a" disabled />
-      <SelectionItem control={<RadioGroupItem value="invoice" id="dis-b" disabled />} label="月結發票" description="需企業方案才能使用" htmlFor="dis-b" disabled />
-    </RadioGroup>
-  ),
-}
+// @story-trait-rationale: Disabled retired 2026-07-14 per audit Dim 24 —
+//   disabled 覆蓋已由 Modes story 的 disabled 列 + anatomy StateBehavior
+//   「Mutual Exclusion + Disabled Item Matrix」owns;對齊 Checkbox / Switch
+//   同 Family 已 retire 的獨立 Disabled story。

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

@@ -10,7 +10,8 @@ import { useFieldContext, useResolvedFieldMode, useResolvedFieldDisabled, useRes
 import { SelectionItem } from "@/design-system/components/SelectionControl/selection-item"
 import type { LucideIcon } from "lucide-react"
 import type { AvatarData } from "@/design-system/components/Avatar/avatar"
-import { EMPTY_DISPLAY, fieldWrapperStyles } from "@/design-system/components/Field/field-wrapper"
+import { fieldWrapperStyles } from "@/design-system/components/Field/field-wrapper"
+import { useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 
 // ── RadioGroup display mode ─────────────────────────────────────────────────
 // RadioGroup mode='display' 時:Group 不渲染 Radix primitive(無 radio 視覺),
@@ -44,6 +45,11 @@ export interface RadioGroupProps
 // (item 已支援 readOnly prop + data-[readonly] 樣式;Radix Root 無 readOnly,故用 context)。
 const RadioGroupReadonlyContext = React.createContext(false)
 
+// group-level disabled(standalone <RadioGroup disabled>)→ context 傳給 items,讓 SelectionItem
+// label/description 也降 text-fg-disabled(Radix Root disabled 只 propagate 給 radio 圈、不碰 label 色)。
+// 對齊本檔 RadioGroupReadonlyContext 既有模式 + spec「Disabled」邊界案例(Group-level disabled 視覺繼承 SelectionItem SSOT text-fg-disabled)。
+const RadioGroupDisabledContext = React.createContext(false)
+
 // walk children 找 control.value === selectedValue 的 SelectionItem label(display / readonly-in-Field 共用)
 function findSelectedRadioLabel(children: React.ReactNode, selectedValue: string | undefined): React.ReactNode {
   let selectedLabel: React.ReactNode = null
@@ -73,6 +79,7 @@ const RadioGroup = React.forwardRef<
 >(({ className, mode, variant: _chrome, value, defaultValue, ...props }, ref) => {
   // 2026-06-08 SSOT cascade:resolvedMode 經 resolver hook 讀 fieldCtx(原 root 完全不讀 → <Field disabled>/<Field mode> 失效)
   const resolvedMode = useResolvedFieldMode({ mode, disabled: (props as { disabled?: boolean }).disabled })
+  const emptyDisplay = useFieldEmptyDisplay()
   const fieldCtx = useFieldContext()
   // readonly 灰框 size:走 SSOT resolver(RadioGroup 無 size prop → ctx > 'md')
   const resolvedBoxSize = useResolvedFieldSize(undefined, 'md') as 'sm' | 'md' | 'lg'
@@ -100,7 +107,7 @@ const RadioGroup = React.forwardRef<
   if (resolvedMode === 'display') {
     const selectedValue = (value ?? defaultValue) as string | undefined
     if (!selectedValue) {
-      return <div {...restDomProps} ref={ref as React.Ref<HTMLDivElement>} 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={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span></div>
     }
     const selectedLabel = findSelectedRadioLabel(props.children, selectedValue)
     return (
@@ -136,7 +143,7 @@ const RadioGroup = React.forwardRef<
       >
         {selectedValue
           ? <span className="text-foreground">{selectedLabel ?? selectedValue}</span>
-          : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>}
+          : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>}
       </div>
     )
   }
@@ -145,20 +152,34 @@ const RadioGroup = React.forwardRef<
   // mode='readonly' → context 傳 readOnly 給 items(item 渲染為 data-[readonly] 鎖互動 + aria-readonly)。
   return (
     <RadioGroupReadonlyContext.Provider value={resolvedMode === 'readonly'}>
-      <RadioGroupPrimitive.Root
-        className={cn("grid", className)}
-        value={value}
-        defaultValue={defaultValue}
-        {...props}
-        disabled={resolvedMode === 'disabled'}
-        ref={ref}
-      />
+      <RadioGroupDisabledContext.Provider value={resolvedMode === 'disabled'}>
+        <RadioGroupPrimitive.Root
+          className={cn("grid", className)}
+          value={value}
+          defaultValue={defaultValue}
+          // Field 內:role="radiogroup" 的 <div> 無法被 <label for> 命名 → 自讀 fieldCtx 接
+          // aria-labelledby / aria-invalid / aria-describedby(field-context.ts「下游 control 需自讀
+          // labelId」;對齊 slider.tsx / Rating / TimePicker 的 fieldLabelId 接線 + 上方 readonly-in-Field 分支)。
+          // standalone(無 Field)時皆 undefined,consumer 的 {...props} aria-* 照舊生效(置於 spread 前故可被覆蓋)。
+          aria-labelledby={fieldCtx?.labelId}
+          aria-invalid={fieldCtx?.invalid || undefined}
+          aria-describedby={fieldCtx?.descriptionId}
+          // a11y(2026-07-14 dim-10):readonly 語意放 radiogroup(aria-readonly 合法 role;
+          // 對齊上方 readonly-in-Field 分支 L133)。item(role=radio)不帶 aria-readonly —
+          // axe 實證 radio 不允許該屬性,item 靠 data-readonly + tabIndex + click guard 鎖互動。
+          aria-readonly={resolvedMode === 'readonly' || undefined}
+          {...props}
+          disabled={resolvedMode === 'disabled'}
+          ref={ref}
+        />
+      </RadioGroupDisabledContext.Provider>
     </RadioGroupReadonlyContext.Provider>
   )
 })
 RadioGroup.displayName = 'RadioGroup'
 // Field layout 宣告：RadioGroup 是 block primitive（多項堆疊），
-// 進入 <Field> 時 control area 自動切 items-start + padding-top 公式對齊。
+// 進入 <Field> 時 control area 自動切 items-start（block 分支不設 min-h、不加 padding-top,
+// 高度由內容決定;額外加 paddingTop 會 double padding — field.tsx block control area SSOT）。
 // Convention 詳見 components/Field/field.spec.md「Control area:Inline vs Block」段落。
 ;(RadioGroup as unknown as { fieldLayout: 'block' }).fieldLayout = 'block'
 
@@ -261,7 +282,10 @@ const RadioGroupItem = React.forwardRef<
     // RadioGroupItem 的 label 是「該選項」的 label（每 item 各自擁有），
     // FieldLabel 則是整個 RadioGroup 的 label。
     // 因此 RadioGroupItem 的 label 不因 Field context 被忽略。
-    const resolvedDisabled = useResolvedFieldDisabled(disabled)
+    // group-level disabled(standalone <RadioGroup disabled>)也要降 label/description 色 —— Radix Root
+    // disabled 只 propagate 給 radio 圈,label 色由 SelectionItem disabled 決定,故讀 RadioGroupDisabledContext 補上。
+    const groupDisabled = React.useContext(RadioGroupDisabledContext)
+    const resolvedDisabled = useResolvedFieldDisabled(disabled) || groupDisabled
     // group-level readonly(RadioGroup mode='readonly')或 item-level readOnly,任一 true 即鎖互動。
     const groupReadonly = React.useContext(RadioGroupReadonlyContext)
     const effectiveReadonly = readOnly || groupReadonly
@@ -274,7 +298,9 @@ const RadioGroupItem = React.forwardRef<
         id={inputId}
         ref={ref}
         disabled={resolvedDisabled}
-        aria-readonly={effectiveReadonly || undefined}
+        // a11y(2026-07-14 dim-10):item(role=radio)不帶 aria-readonly — axe 實證 radio 不允許
+        // 該屬性(readonly 語意由 Root role=radiogroup 宣告,見上方 L167-170)。item 靠
+        // data-readonly + tabIndex + click guard 鎖互動。
         data-readonly={effectiveReadonly || undefined}
         tabIndex={effectiveReadonly ? -1 : undefined}
         className={cn(radioItemVariants({ size }), className)}
@@ -331,7 +357,7 @@ export const radioGroupMeta = {
   },
   sizes: {
     // iconSize = 渲染指示器尺寸(對齊 checkbox/switch meta 慣例:checkbox iconSize=真 Check glyph 12/12/16)。
-    // Radio 指示器是 filled dot 非 glyph,真值 = dotSize 8/8/10(radio-group.tsx:179);
+    // Radio 指示器是 filled dot 非 glyph,真值 = 上方 `const dotSize` map 8/8/10;
     // 控件框 16/16/20 與 Checkbox 對齊但那是 box 非「指示器」,不入此鍵(避免 metadata 語意 drift)。
     sm: { fieldHeight: 28, iconSize: 8, typography: 'body' },
     md: { fieldHeight: 32, iconSize: 8, typography: 'body' },