@qijenchen/design-system 0.1.0-beta.85 → 0.1.0-beta.86

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

@@ -1,4 +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.
+// @overlay-open-skip: 本檔為 usage-guidance(設計原則)story——每個 Rule 卡片以「關閉的 trigger 按鈕」並排比較 Popover / Dialog / DropdownMenu / Tooltip 何時用;全部 defaultOpen 會讓多個 portal 疊在一起、視覺全毀。overlay 開啟狀態的視覺覆蓋由 popover.stories.tsx(展示)+ popover.anatomy.stories.tsx(Inspector defaultOpen)負責。
 import React from 'react'
 import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'
@@ -217,7 +218,8 @@ export const UsageGuidance: Story = {
           <PopoverTrigger asChild>
             <Button variant="tertiary" size="sm" startIcon={Filter}>篩選</Button>
           </PopoverTrigger>
-          <PopoverContent align="start">
+          {/* naked popover(無 PopoverTitle)→ 自傳 aria-label 讓 role="dialog" 有 accessible name(popover.spec.md A11y) */}
+          <PopoverContent align="start" aria-label="篩選任務">
             <PopoverBody>
               <CheckboxGroup>
                 <Checkbox defaultChecked label="我的任務" />
@@ -255,33 +257,52 @@ export const VisualAlignmentRule: Story = {
         title="Popover 與 Dialog 共用 overlay-surface 視覺語言"
         note="bg-surface-raised / border-border / rounded-lg / elevation-200 完全一致。Header / Body / Footer 內 padding 來自 overlay-surface pattern 主檔(px-loose py-tight)。差異:(1) Popover 是 non-modal 無 overlay 遮罩,(2) Popover 鎖 layout-space=md(header 精簡);Dialog 不鎖 layout-space,全繼承 page(md page → 16 / lg page → 24)。兩者 ui-size 都繼承 page"
       >
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="tertiary">Popover</Button>
-          </PopoverTrigger>
-          <PopoverContent align="start">
-            <PopoverHeader><PopoverTitle>Header</PopoverTitle></PopoverHeader>
-            <PopoverBody><p className="text-body">Body 區域</p></PopoverBody>
-            <PopoverFooter>
-              <Button variant="tertiary" size="sm">取消</Button>
-              <Button variant="primary" size="sm">套用</Button>
-            </PopoverFooter>
-          </PopoverContent>
-        </Popover>
-        <Dialog>
-          <DialogTrigger asChild>
-            <Button variant="tertiary">Dialog</Button>
-          </DialogTrigger>
-          <DialogContent autoHeight maxWidth="360px">
-            <DialogHeader><DialogTitle>Header</DialogTitle></DialogHeader>
-            <DialogBody><p className="text-body">Body 區域</p></DialogBody>
-            <DialogFooter>
-              <Button variant="tertiary">取消</Button>
-              <Button variant="primary">套用</Button>
-            </DialogFooter>
-          </DialogContent>
-        </Dialog>
-        <Label>↑ 兩個浮層視覺語言一致,consumer 切換不會產生視覺斷層</Label>
+        {/* @overlay-open-skip:視覺語言比較卡片——同一「顯示欄位」內容分別以 Popover / Dialog 呈現,證明 chrome 視覺完全一致;trigger 刻意關閉並排(見檔頭 escape),開啟態覆蓋於展示 / anatomy */}
+        <div className="flex flex-col items-start gap-2">
+          <Popover>
+            <PopoverTrigger asChild>
+              <Button variant="tertiary">顯示欄位</Button>
+            </PopoverTrigger>
+            <PopoverContent align="start">
+              <PopoverHeader><PopoverTitle>顯示欄位</PopoverTitle></PopoverHeader>
+              <PopoverBody>
+                <CheckboxGroup>
+                  <Checkbox defaultChecked label="狀態" />
+                  <Checkbox defaultChecked label="負責人" />
+                  <Checkbox label="到期日" />
+                </CheckboxGroup>
+              </PopoverBody>
+              <PopoverFooter>
+                <Button variant="tertiary" size="sm">重設</Button>
+                <Button variant="primary" size="sm">套用</Button>
+              </PopoverFooter>
+            </PopoverContent>
+          </Popover>
+          <Label>↑ 同一內容以 Popover 呈現(non-modal 輕量浮層)</Label>
+        </div>
+        <div className="flex flex-col items-start gap-2">
+          <Dialog>
+            <DialogTrigger asChild>
+              <Button variant="tertiary">顯示欄位</Button>
+            </DialogTrigger>
+            <DialogContent autoHeight maxWidth="360px">
+              <DialogHeader><DialogTitle>顯示欄位</DialogTitle></DialogHeader>
+              <DialogBody>
+                <CheckboxGroup>
+                  <Checkbox defaultChecked label="狀態" />
+                  <Checkbox defaultChecked label="負責人" />
+                  <Checkbox label="到期日" />
+                </CheckboxGroup>
+              </DialogBody>
+              <DialogFooter>
+                <Button variant="tertiary">重設</Button>
+                <Button variant="primary">套用</Button>
+              </DialogFooter>
+            </DialogContent>
+          </Dialog>
+          <Label>↑ 同一內容以 Dialog 呈現(modal 阻斷背景)</Label>
+        </div>
+        <Label>↑ 容器不同、chrome 視覺語言完全一致,consumer 切換不會產生視覺斷層</Label>
       </Rule>
 
       <Rule

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

@@ -152,11 +152,13 @@ canonical 判斷:「使用者 click 單項是否立即改變系統狀態?」是
 
 ## 邊界案例
 
-- **極長內容**: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」。
+- **極長內容**:PopoverContent 設 `max-h-[var(--radix-popover-content-available-height)]`(popover.tsx:103),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**:layout-space 鎖 `md`(header / footer padding 精簡);ui-size 繼承 page(見「定位」段)。
+- **空內容 / loading / error / validation ownership**:Popover shell **不擁有**這些狀態——由 `PopoverBody` 內的 consumer 內容層負責:空狀態放 `<Empty>`、載入放 `<Skeleton>`、錯誤放 `<Alert>`、表單驗證放 `<Field>` 的 `FieldError`。structural pattern 的職責邊界 SSOT 見 `../../patterns/overlay-surface/overlay-surface.spec.md` SurfaceBody「邊界」段(loading / error / empty 屬 consumer 內容層)。
+- **disabled ownership**:Popover 容器無 disabled 態;trigger 的 disabled 由 trigger 元件自管(`<Button disabled>`),content 內控件各自的 disabled 由該控件負責(對應 `StateBehavior` story「職責邊界」段)。
 
 ---
 
@@ -164,7 +166,7 @@ canonical 判斷:「使用者 click 單項是否立即改變系統狀態?」是
 
 焦點 / 鍵盤 / ARIA 行為分兩層——**DS 覆寫**(改 Radix 預設)與 **Radix 內建**(沿用)：
 
-- **開啟焦點(DS 覆寫)**：DS 以 `onOpenAutoFocus` 覆寫 Radix 預設 autofocus(見 `popover.tsx` `handlePopoverOpenAutoFocus`),開啟時把焦點落在 body 第一個可互動元素。Radix 預設會先 focus 右上 close X,DS 覆寫以避免觸發 tooltip leak(對齊 Material / Polaris「open 時 focus 落首個有意義控制」)。**注意**:若移除此 default handler,行為會回退成 Radix 預設 focus close X
+- **開啟焦點(DS 覆寫)**：DS 以 `onOpenAutoFocus` 覆寫 Radix 預設 autofocus(見 `popover.tsx` `handlePopoverOpenAutoFocus`),開啟時把焦點落在 body 第一個**表單控件**(`input` / `textarea` / `select` / `button`,排除右上 close X);查無表單控件時退回 footer 按鈕,再無則落在 content 容器(`role="dialog"`)本身。Radix 預設會先 focus 右上 close X,DS 覆寫以避免觸發 tooltip leak(對齊 Material / Polaris「open 時 focus 落首個有意義控制」;selector 與 `dialog.tsx handleOpenAutoFocus` 同一套 DS canonical)。**注意**:(1) 若移除此 default handler,行為會回退成 Radix 預設 focus close X;(2) selector 只認表單控件——body 若只含 `a[href]` / `[tabindex]` / `contenteditable` 類可聚焦內容,焦點會落在 content 容器而非該內容,consumer 需自傳 `onOpenAutoFocus` 指定要聚焦的元素 <!-- @benchmark-unverified: Material / Polaris focus-on-open pattern per frontmatter benchmark list; DS canonical selector = dialog.tsx handleOpenAutoFocus -->
 - **關閉返回(Radix 內建)**：關閉時 focus return to trigger
 - **Esc 關閉(Radix 內建)**：按 Esc 自動關閉並返回焦點
 - **Focus trap(Radix 內建,僅 modal)**：`modal={true}` 時焦點鎖在 content 內

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

@@ -205,7 +205,7 @@ export const SectionMatrix: Story = {
     <div className="flex flex-col gap-10">
       <div>
         <H3>Minimal — profile header + View more</H3>
-        <Desc>最小形式:avatar + name + subtitle + **View more**(hover context 必含,見 spec「View more canonical」)。@mention hover 場景 user 點 View more 跳完整 profile。</Desc>
+        <Desc>最小形式:avatar + name + subtitle + **View more**(hover context 必含 — canonical owner 見 avatar.spec.md「onViewMore 為 hover context 必含」段;顯示條件見本元件 spec「View More」節)。@mention hover 場景 user 點 View more 跳完整 profile。</Desc>
         <div className="border border-dashed border-divider rounded-md p-4 inline-block">
           <ProfileCard name="Alice Wang" subtitle="Frontend Engineer" onViewMore={() => {}} />
         </div>

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

@@ -24,7 +24,7 @@ import { ItemContent } from '@/design-system/patterns/element-anatomy/item-anato
  * 跨 consumer(avatar.principles / profile-card.stories / future product code)應該用
  * 同一組預設,避免每個範例各自發明 action 組合,讓 reader 誤以為 action 會隨情境自動變。
  *
- * ── 使用方式(hover context 必含 onViewMore,見 profile-card.spec.md 「View more」節)──
+ * ── 使用方式(hover context 必含 onViewMore — canonical owner 見 avatar.spec.md「onViewMore 為 hover context 必含」段;顯示條件見 profile-card.spec.md「View More」節)──
  *   <ProfileCard name="..." actions={<ProfileCardDefaultActions />} onViewMore={...} />
  *
  * ── 何時要換成自訂 action ──

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

@@ -91,7 +91,7 @@ export const Overview = {
           {STATUSES.map((s) => (
             <div key={s} className="flex items-center gap-4">
               <div className="w-28 shrink-0">
-                <ProgressBar value={s === 'success' ? 100 : s === 'error' ? 60 : 45} status={s} />
+                <ProgressBar value={s === 'success' ? 100 : s === 'error' ? 60 : 45} status={s} aria-label={`${s} 狀態範例`} />
               </div>
               <span className="font-mono text-caption w-20 text-fg-secondary">{s}</span>
               <span className="text-caption text-fg-secondary">{STATUS_TOKEN[s].desc}</span>
@@ -193,6 +193,7 @@ const InspectorInner = () => {
             type="range" min={0} max={100} value={value}
             onChange={(e) => setValue(Number(e.target.value))}
             className="w-[240px]"
+            aria-label="調整進度值"
           />
           <span className="text-[11px] font-mono text-fg-secondary tabular-nums w-10">{value}%</span>
         </div>
@@ -203,7 +204,7 @@ const InspectorInner = () => {
         {/* Left: preview */}
         <div className="flex flex-col gap-5 min-w-[360px]">
           <div className="px-6 py-10 rounded-lg bg-canvas border border-divider">
-            <ProgressBar value={value} status={status} affix={affixNode} />
+            <ProgressBar value={value} status={status} affix={affixNode} aria-label="即時預覽進度" />
           </div>
 
           {/* Blueprint:顯示 track 高度 + fill 寬度 */}
@@ -317,7 +318,7 @@ export const ColorMatrix = {
                 <Td mono>{s}</Td>
                 <Td>
                   <div className="w-[180px]">
-                    <ProgressBar value={s === 'success' ? 100 : 60} status={s} />
+                    <ProgressBar value={s === 'success' ? 100 : 60} status={s} aria-label={`${s} 狀態色彩範例`} />
                   </div>
                 </Td>
                 <Td><TokenCell token="--secondary" /></Td>
@@ -336,9 +337,9 @@ export const ColorMatrix = {
       <div className="flex flex-col gap-3">
         <span className="text-caption font-medium text-fg-secondary">含 affix 預覽</span>
         <div className="flex flex-col gap-3 max-w-[420px]">
-          <ProgressBar value={42} status="inProgress" affix="value" />
-          <ProgressBar value={100} status="success" affix="status-icon" />
-          <ProgressBar value={68} status="error" affix="status-icon" />
+          <ProgressBar value={42} status="inProgress" affix="value" aria-label="進行中含百分比範例" />
+          <ProgressBar value={100} status="success" affix="status-icon" aria-label="完成含狀態圖示範例" />
+          <ProgressBar value={68} status="error" affix="status-icon" aria-label="失敗含狀態圖示範例" />
         </div>
       </div>
     </div>
@@ -368,7 +369,7 @@ export const AffixBehavior = {
             配額使用率、下載進度等需要精確數字時使用。
           </p>
           <div className="w-[360px]">
-            <ProgressBar value={45} status="inProgress" affix="value" />
+            <ProgressBar value={45} status="inProgress" affix="value" aria-label="含百分比的進度範例" />
           </div>
         </div>
 
@@ -381,9 +382,9 @@ export const AffixBehavior = {
             inProgress → 無 icon(inProgress 非終態)。
           </p>
           <div className="flex flex-col gap-2 w-[360px]">
-            <ProgressBar value={100} status="success" affix="status-icon" />
-            <ProgressBar value={72} status="error" affix="status-icon" />
-            <ProgressBar value={50} status="inProgress" affix="status-icon" />
+            <ProgressBar value={100} status="success" affix="status-icon" aria-label="完成狀態範例" />
+            <ProgressBar value={72} status="error" affix="status-icon" aria-label="失敗狀態範例" />
+            <ProgressBar value={50} status="inProgress" affix="status-icon" aria-label="進行中狀態範例" />
             <span className="text-footnote text-fg-muted">↑ inProgress 傳 status-icon 時不渲染 icon,且因無 affix 內容而 collapse 成純 bar(無 wrapper、無 gap,與不傳 affix 等價)</span>
           </div>
         </div>
@@ -398,7 +399,7 @@ export const AffixBehavior = {
             <ProgressBar
               value={42}
               status="inProgress"
-             
+              aria-label="可取消的進度範例"
               affix={
                 <Button variant="text" size="xs" iconOnly startIcon={X} aria-label="取消上傳" />
               }
@@ -406,7 +407,7 @@ export const AffixBehavior = {
             <ProgressBar
               value={66}
               status="inProgress"
-             
+              aria-label="含資料量的進度範例"
               affix={<span className="text-caption text-fg-muted tabular-nums shrink-0">1.3 / 2.0 MB</span>}
             />
           </div>
@@ -419,7 +420,7 @@ export const AffixBehavior = {
             不包 wrapper,ProgressBar 本身就是整個元件。適合 FileItem 的 compact mode(上方已有檔名文字)。
           </p>
           <div className="w-[360px]">
-            <ProgressBar value={55} status="inProgress" />
+            <ProgressBar value={55} status="inProgress" aria-label="純 bar 進度範例" />
           </div>
         </div>
       </div>

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

@@ -7,6 +7,7 @@ import LinkTo from '@storybook/addon-links/react'
 import { Paperclip, X, FileText, Table as TableIcon } from 'lucide-react'
 import { ProgressBar } from './progress-bar'
 import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
+import { FileItem } from '@/design-system/components/FileItem/file-item'
 import { Button } from '@/design-system/components/Button/button'
 
 const meta: Meta = {
@@ -105,31 +106,15 @@ export const UsageGuidance: Story = {
           note="每個檔案一條 ProgressBar 已足夠表達整體狀態(使用者自然從完成數量推算),再加一條總 bar 會造成視覺重複與同步邏輯漂移。Dropbox / Google Drive 都只顯示每檔 bar。"
         >
           <Frame width={480}>
-            <div className="flex flex-col gap-3">
-              <div>
-                <div className="flex items-center gap-2 mb-1">
-                  <Paperclip size={16} className="text-fg-muted" />
-                  <span className="text-body flex-1 truncate">會議記錄_0418.docx</span>
-                </div>
-                <ProgressBar value={100} status="success" affix="status-icon" />
-              </div>
-              <div>
-                <div className="flex items-center gap-2 mb-1">
-                  <Paperclip size={16} className="text-fg-muted" />
-                  <span className="text-body flex-1 truncate">簡報素材.zip</span>
-                </div>
-                <ProgressBar value={62} status="inProgress" affix="value" />
-              </div>
-              <div>
-                <div className="flex items-center gap-2 mb-1">
-                  <Paperclip size={16} className="text-fg-muted" />
-                  <span className="text-body flex-1 truncate">截圖.png</span>
-                </div>
-                <ProgressBar value={0} status="inProgress" />
-              </div>
+            {/* 上傳列表載體 = FileItem(compact list gap-1 canonical;內部消費 ProgressBar)—
+                不手組 Paperclip + 檔名 + ProgressBar(見下方「檔案上傳 UI → 用 FileItem」rule) */}
+            <div className="flex flex-col gap-1">
+              <FileItem mode="compact" name="會議記錄_0418.docx" status="completed" />
+              <FileItem mode="compact" name="簡報素材.zip" status="uploading" progress={62} />
+              <FileItem mode="compact" name="截圖.png" status="uploading" progress={0} />
             </div>
           </Frame>
-          <Label>✅ 每檔一條,整體進度由使用者自然感知(1 檔完成、2 檔進行中)</Label>
+          <Label>✅ 每檔一條(FileItem 內建),整體進度由使用者自然感知(1 檔完成、2 檔進行中)</Label>
         </Rule>
 
         <Rule

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

@@ -37,6 +37,7 @@ const SectionDesc = ({ children }: { children: React.ReactNode }) => (
 // ── Default(基本範例) ──────────────────────────────────────────────────
 
 export const Default: Story = {
+  name: '預設',
   args: { value: 45, status: 'inProgress', affix: 'value' },
   render: (args) => (
     <div className="w-[360px]">
@@ -64,7 +65,7 @@ export const BatchTask: Story = {
           <span className="text-body-lg font-medium flex-1">匯入客戶名單</span>
           <span className="text-caption text-fg-muted tabular-nums">812 / 1,250 筆</span>
         </div>
-        <ProgressBar value={65} status="inProgress" affix="value" />
+        <ProgressBar value={65} status="inProgress" affix="value" aria-label="匯入客戶名單進度" />
         <p className="text-footnote text-fg-muted">
           處理中,請勿關閉此視窗。預計剩餘 28 秒。
         </p>
@@ -107,7 +108,12 @@ const quotaColumns: ColumnDef<QuotaRow>[] = [
     header: '配額使用率',
     meta: { width: 240 },
     cell: ({ row }) => (
-      <ProgressBar value={row.original.quota} status={row.original.status} affix="value" />
+      <ProgressBar
+        value={row.original.quota}
+        status={row.original.status}
+        affix="value"
+        aria-label={`${row.original.name} 配額使用率`}
+      />
     ),
   },
 ]

package/src/components/README.md

@@ -22,6 +22,7 @@
 - `Checkbox/` — `checkbox.tsx` + `checkbox-group.tsx`(2026-04-21 CheckboxGroup merge 自 separate folder,對齊 standalone + group 世界級慣例)+ `boolean-display.tsx`(table cell 顯示)
 - `Menu/` — `menu-item.tsx`(家族預留位)
 - `SelectionControl/` — `selection-item.tsx`(Checkbox/Radio 共享的 row layout primitive home)
+- `PeoplePicker/` — `people-picker.tsx` + `person-display.tsx`(`PersonDisplay` / `MultiPersonDisplay` / `PersonAvatarTag`)+ `avatar-stack-overflow.ts` + `people-picker-helpers.ts`。**compound rationale**:全部共享 `PersonValue` 資料模型 + avatar 視覺規則,且 picker↔display 雙向消費(edit 選人 / view 渲染已選)。`PersonDisplay` 為**唯一現存 cross-component view primitive**(可脫離 picker 用於 DataTable cell / detail panel,見 `Field/field-controls.spec.md`「唯一現存 cross-component view primitive」),經 `PeoplePicker` root barrel + subpath 一併公開——與 `Checkbox/boolean-display.tsx`(table-cell 顯示 co-located)同型共居先例
 
 **判斷 compound vs 單獨 folder**:
 - 元件能**獨立 lifecycle / 獨立使用** → 各自獨立 folder(Button / Input / Select)

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

@@ -169,9 +169,14 @@ export const Overview = {
           <div className="flex flex-col gap-2 items-start">
             <span className="text-[11px] text-fg-muted font-medium">搭配 SelectionItem</span>
             <div className="inline-flex items-center border-2 border-dashed border-primary/30 rounded-md px-3 py-2.5 gap-2">
-              {[{ name: 'control', color: 'info' }, { name: 'control', color: 'success' }, { name: 'control', color: 'magenta' }].map((s) => (
-                <span key={s.name} className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
-                  style={{ borderColor: `var(--${s.color})`, backgroundColor: `var(--${s.color}-subtle)`, color: `var(--${s.color})` }}>{s.name}</span>
+              {/* magenta 為 primitive(無 --magenta semantic token)→ 顯式 --color-magenta-{6,1,7}(ProgressBar 同款修法) */}
+              {[
+                { name: 'control', border: 'var(--info)', bg: 'var(--info-subtle)', text: 'var(--info)' },
+                { name: 'control', border: 'var(--success)', bg: 'var(--success-subtle)', text: 'var(--success)' },
+                { name: 'control', border: 'var(--color-magenta-6)', bg: 'var(--color-magenta-1)', text: 'var(--color-magenta-7)' },
+              ].map((s, i) => (
+                <span key={i} className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
+                  style={{ borderColor: s.border, backgroundColor: s.bg, color: s.text }}>{s.name}</span>
               ))}
             </div>
             <span className="text-[10px] text-fg-muted font-mono">flex items-start gap-2 · control 在一行文字高度的容器內置中</span>

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

@@ -15,7 +15,7 @@ type Story = StoryObj<typeof RadioGroupItem>
 // 「何時用」明文禁止裸用)→ 收斂為公開 <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.
+// @story-trait-rationale: pre-existing trait gaps tracked separately; this PR scope = add Modes story with view card.
 /* ── 四模式 ── */
 export const Modes: Story = {
   name: '四模式',
@@ -30,8 +30,8 @@ export const Modes: Story = {
         </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)">
+        <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+        <RadioGroup mode="view" value="yearly" aria-label="付款方案(view 模式示範)">
           <RadioGroupItem value="monthly" label="月付方案" />
           <RadioGroupItem value="yearly" label="年付方案" description="每年 $2,990，省下兩個月" />
           <RadioGroupItem value="lifetime" label="終身方案" />

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

@@ -13,21 +13,24 @@ import type { AvatarData } from "@/design-system/components/Avatar/avatar"
 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 視覺),
+// ── RadioGroup view mode ────────────────────────────────────────────────────
+// RadioGroup mode='view' 時:Group 不渲染 Radix primitive(無 radio 視覺),
 // 改由 RadioGroup 本體 walk props.children,找 control.value === selectedValue 的
 // SelectionItem,把它的 label 渲染為單一純文字 span(其他選項不顯示)。
 // 對齊 Carbon read-only single-select(只顯示 selected 內容)+ Airtable / Notion read-only。
-// 實作在 RadioGroup forwardRef 內(見下方 mode === 'display' 分支)。
+// 實作在 RadioGroup forwardRef 內(見下方 mode === 'view' 分支)。
 
 // ── RadioGroup ──────────────────────────────────────────────────────────────
 
 export interface RadioGroupProps
-  extends React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root> {
+  // asChild Omit(2026-07-18 決策2):RadioGroup 恆持有多個 radio item → <Root asChild> 的
+  // Radix Slot React.Children.only crash;view/readonly 模式更直接渲染固定 <div> 忽略之。
+  // children 保留(edit 容器內容 + view/readonly 走訪選中 label,見 body cast @line ~105)。
+  extends Omit<React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Root>, 'asChild'> {
   /**
    * Field mode(2026-05-05 Phase B3 align):
    *   edit     — 一般可互動 RadioGroup(預設)
-   *   display  — **純展示**:不渲染 Radix Root / 任何 radio 視覺;RadioGroup 本體 walk
+   *   view     — **純展示**:不渲染 Radix Root / 任何 radio 視覺;RadioGroup 本體 walk
    *              children,僅 control.value === group.value 那筆把 label 渲染為純文字 span。
    *              對齊 Carbon read-only / DataTable single-select cell read mode。
    *   readonly — standalone:ReadonlyContext 傳 items 鎖互動保留視覺;Field 內:灰框 + 選中項 label(不渲染 radio 群組)
@@ -50,7 +53,7 @@ const RadioGroupReadonlyContext = React.createContext(false)
 // 對齊本檔 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 共用)
+// walk children 找 control.value === selectedValue 的 SelectionItem label(view / readonly-in-Field 共用)
 function findSelectedRadioLabel(children: React.ReactNode, selectedValue: string | undefined): React.ReactNode {
   let selectedLabel: React.ReactNode = null
   React.Children.forEach(children, (child) => {
@@ -83,12 +86,12 @@ const RadioGroup = React.forwardRef<
   const fieldCtx = useFieldContext()
   // readonly 灰框 size:走 SSOT resolver(RadioGroup 無 size prop → ctx > 'md')
   const resolvedBoxSize = useResolvedFieldSize(undefined, 'md') as 'sm' | 'md' | 'lg'
-  // mode='display' — 純展示 selected option 的 label,不渲染任何 radio control 視覺。
+  // mode='view' — 純展示 selected option 的 label,不渲染任何 radio control 視覺。
   // 對齊 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 都靜默失效。
+  // 2026-07-04 修:view / readonly-in-Field 分支的 <div> 原丟棄剩餘 props(id/data-*/aria-*)
+  // 且不轉發 forwardRef ref → 自家 radio-group.stories.tsx view demo 傳的 aria-label 都靜默失效。
   // 抽出 Radix 專屬 non-DOM props,其餘 DOM props 於兩分支 spread 轉發(與 Checkbox/Switch 同修);
   // edit 主路徑不受影響(Root 仍 spread 完整 props)。
   const {
@@ -104,7 +107,7 @@ const RadioGroup = React.forwardRef<
     ...restDomProps
   } = props as RadioGroupProps & { asChild?: boolean }
 
-  if (resolvedMode === 'display') {
+  if (resolvedMode === 'view') {
     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={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span></div>
@@ -223,7 +226,9 @@ const dotSize: Record<string, number> = { sm: 8, md: 8, lg: 10 }
 type RadioItemPrimitiveProps = React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>
 
 export interface RadioGroupItemProps
-  extends RadioItemPrimitiveProps,
+  // asChild / children Omit(2026-07-18 決策2):item 固定渲染 Indicator dot(<Circle/>)—
+  // children 被固定 Indicator 靜默覆蓋,asChild 破壞 radio 結構。對齊 Checkbox 收窄。label 走 `label` prop。
+  extends Omit<RadioItemPrimitiveProps, 'asChild' | 'children'>,
     VariantProps<typeof radioItemVariants> {
   /**
    * Inline label。提供時 RadioGroupItem 自動透過 SelectionItem 包裝，
@@ -273,9 +278,9 @@ const RadioGroupItem = React.forwardRef<
     const sizeKey = size ?? 'md'
     const dotPx = dotSize[sizeKey]
 
-    // 注意:RadioGroup mode='display' 的純文字渲染由 RadioGroup 本體 walk-children 處理
-    // (見上方 RadioGroup forwardRef 的 mode === 'display' 分支),RadioGroupItem 在 display
-    // mode 下不會被獨立 render,故此處無 display 分支。
+    // 注意:RadioGroup mode='view' 的純文字渲染由 RadioGroup 本體 walk-children 處理
+    // (見上方 RadioGroup forwardRef 的 mode === 'view' 分支),RadioGroupItem 在 view
+    // mode 下不會被獨立 render,故此處無 view 分支。
 
     // 注意：Radio 的 label 語意與 Checkbox/Switch 不同——
     // Checkbox/Switch 的 label 就是該 control 的唯一 label（被 Field context 接管），

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

@@ -188,7 +188,7 @@ const InspectorInner = () => {
               precision={precision}
               readOnly={readOnly}
               disabled={disabled}
-              aria-label={readOnly ? `平均評分 ${value} 星，共 5 星` : undefined}
+              aria-label={readOnly ? `平均評分 ${value} 星，共 5 星` : `為這次體驗評分，目前 ${value} 星，共 5 星`}
             />
           </div>
           <div className="text-caption text-fg-muted font-mono">

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

@@ -76,8 +76,8 @@ export const UsageGuidance: Story = {
       {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
       <div>
       <Rule
-        title="❌ readOnly 不加 aria-label"
-        note="純視覺的星星螢幕閱讀器讀不出「4.7 分」。readOnly Rating 的 aria-label 必填，描述「幾星、共幾星、幾則評論」。"
+        title="❌ standalone readOnly 不給可存取名稱"
+        note="純視覺的星星螢幕閱讀器讀不出「4.7 分」。standalone readOnly Rating 必須有可存取名稱——傳 aria-label 描述目前分數與滿分（如「平均評分 4.5 星，共 5 星」）；包在 Field 內時由 aria-labelledby 自動指向 FieldLabel，免傳 aria-label。評論數只在畫面確實顯示時才加進描述。"
       >
         <div className="flex flex-col gap-2 w-[320px] p-4 border border-border rounded-md">
           <Rating value={4.5} readOnly precision="half" size="md" aria-label="平均評分 4.5 星，共 5 星" />
@@ -260,7 +260,7 @@ export const YellowStarConvention: Story = {
     <div>
       <Rule
         title="黃星 = 世界級 convention，破壞 = 破壞使用者直覺"
-        note="Amazon / Yelp / Google Reviews / Shopify / Airbnb / TripAdvisor 全部用黃星。使用者的視覺記憶已經把「黃星 = 評分」綁定——換成品牌 primary 色（藍 / 綠 / 紫）會讓使用者多花一瞬間「這是什麼？」。這一瞬間就是設計 bug。"
+        note="黃 / 金色星是星級評分最通用的視覺慣例——Amazon 商品評分、Google 地點評分都用金黃星，使用者的視覺記憶早已把「黃星 = 評分」綁定。換成品牌 primary 色（藍 / 綠 / 紫）會讓使用者多花一瞬間「這是什麼？」，這一瞬間就是設計 bug。（少數平台改用自家色：Yelp 紅星、Tripadvisor 綠色圓點 bubble——但黃 / 金星仍是跨平台最通用的星級評分色。）"
       >
         <div className="flex flex-col gap-2">
           <Rating value={4.5} readOnly precision="half" size="lg" aria-label="標準黃星" />

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

@@ -36,7 +36,7 @@ Rating 是**離散 1–5 分評分元件**——使用者對商品、服務、
 
 | 情境 | 改用 | 原因 |
 |------|------|------|
-| 純資訊標記（「熱門」「Beta」「新品」）| `Badge` | Rating 是量化 1–5 分，不是分類標籤 |
+| 純資訊標記（「熱門」「Beta」「新品」）| `Tag` | Rating 是量化 1–5 分，不是分類標籤;文字分類標記走 Tag(Badge 僅 count/dot 兩模式,無文字承載) |
 | 非 1–5 的連續數值（音量、亮度、價格範圍）| `Slider` | Rating 是離散 tier，Slider 是連續值 |
 | 二元喜歡 / 不喜歡（thumbs up/down、like）| `Switch` 或自組 icon button | Like 是 binary，Rating 是 graded 1–5 |
 | 多維度評比（服務 / 品質 / 速度 各 5 分）| 自組多個 Rating 縱向排列 | 單一 Rating 只表達單一維度 |
@@ -210,7 +210,7 @@ Star icon 渲染時明確設 `stroke="none"`(Lucide Star 預設 `stroke="current
 ## 相關
 
 - **`Slider`** — 連續數值選擇（0–100、音量、亮度、價格區間）。Rating vs Slider 分界：離散 tier = Rating，連續值 = Slider
-- **`Badge`** — 靜態分類標記（「熱門」「Beta」「NEW」）。Rating 是量化，Badge 是分類
+- **`Tag`** — 靜態文字分類標記（「熱門」「Beta」「NEW」）。Rating 是量化,Tag 是文字分類(Badge 僅 count/dot,不承載文字)
 - **`Switch`** — 二元 on/off。Rating 是 graded，Switch 是 binary
 - **`Button iconOnly + pressed={liked}`** — 愛心 / like 的正確實作
 - **Color token 例外** — `color.spec.md`「共用 `--warning` 色相但語境不同」段落

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

@@ -113,21 +113,7 @@ export const InField: Story = {
 }
 
 /* @story-trait-rationale: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。 */
-/* ── 停用狀態 ── */
-export const Disabled: Story = {
-  name: '停用狀態',
-  render: () => (
-    <div className="flex flex-col gap-4 w-[420px]">
-      <p className="text-caption text-fg-muted">
-        評分期限已過的舊訂單，Rating 顯示使用者當初給的分數但無法再修改。
-      </p>
-      <div className="flex items-center gap-3 p-3 border border-border rounded-md bg-surface">
-        <div className="flex-1">
-          <div className="text-body font-medium">訂單 #A-2025-11-03</div>
-          <div className="text-caption text-fg-muted mt-[var(--item-gap-label-desc-scanning)]">評分期限已過</div>
-        </div>
-        <Rating value={4} disabled aria-label="此訂單已完成評分 4 星，無法修改" />
-      </div>
-    </div>
-  ),
-}
+// @story-trait-rationale: Disabled retired per audit Dim 24 —
+//   disabled 覆蓋已由 anatomy.stories.tsx StateBehavior 的 disabled live case
+//   (value=4 disabled)owns;對齊 Checkbox / Switch / RadioGroup 同 Family
+//   已 retire 的獨立 Disabled story,不重複展示同一 state。

package/src/components/Rating/rating.tsx

@@ -12,7 +12,7 @@ import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useRes
  *
  * ── 使用情境 ──
  * - review / feedback:商品評分 / 服務評分(可編輯 + 唯讀兩種)
- * - display:已提交評分的唯讀呈現(商品清單星等)
+ * - view:已提交評分的唯讀呈現(商品清單星等)
  *
  * ── 視覺 ──
  * 填色用 `var(--warning)`(yellow-6,世界級黃星 convention;與 warning 語意共用色相
@@ -112,6 +112,10 @@ const Rating = React.forwardRef<HTMLDivElement, RatingProps>(
     //   - Standalone(無 Field context) → default `xs`(24px,對齊 Avatar / Tag sm / iOS HIG standalone)
     // consumer 可傳 size 顯式 override。世界級對照:Material Rating standalone 24dp、
     // Ant Rate in Form 跟 Form.itemSize,standalone 24px。
+    // 2026-07-18 決策4:max dev-warn(spec canonical ≤7;維持 number 型別不收窄,對齊 MUI Rating.max)。
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production' && (max > 7 || max < 1 || Math.round(max) !== max)) {
+      console.warn(`[DS] Rating max ${max} 超出 canonical 範圍 1-7(或非整數)。建議 ≤7 顆星(對齊世界級 review-stars)。`)
+    }
     const fieldCtx = useFieldContext()  // 保留:aria-labelledby 用 fieldCtx.labelId
     // 2026-06-08 SSOT:<Field disabled> cascade(原 isInteractive 只看 local disabled prop)
     const disabled = useResolvedFieldDisabled(disabledProp)

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

@@ -255,7 +255,7 @@ export const SolvesDataTableBug: Story = {
 
       <Rule
         title="解法 — ScrollArea overlay 捲軸,跨 OS 一致不吃寬度"
-        note="同一份表格,改用 ScrollArea 包起來、額外渲染 horizontal ScrollBar。macOS 與 Windows 呈現完全一致,右側 Status 欄不被裁切。這是 DataTable 遷移到 ScrollArea 的主要動機。"
+        note="同一份表格,改用 ScrollArea 包起來、額外渲染 horizontal ScrollBar。macOS 與 Windows 呈現完全一致,右側 Status 欄不被裁切。此組合限外層包 height='auto' 表格的 demo 場景;DataTable 中央捲動區本體走 native overflow-x-auto(pinned column 結構需求,見 scroll-area.spec.md「何時用」例外 + data-table.spec.md「捲軸 canonical」)。"
       >
         <div className="w-[560px]">
           <ScrollArea className="border border-success/40 rounded-md bg-surface">

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

@@ -132,7 +132,7 @@ Radix Viewport 內建 wrapper `min-width:100%; display:table`——這是**水
 
 ## 相關
 
-- `../DataTable/data-table.spec.md` — 主要 consumer(橫向捲動跑版問題的解法來源)
+- `../DataTable/data-table.spec.md` — 歷史動機來源(橫向捲動跑版問題),**非 consumer**:DataTable 中央捲動區走 native `overflow-x-auto`(0 import,見上方「何時用」例外 +「捲軸 canonical」節)
 - `../Sheet/sheet.spec.md` — body 捲動
 - `../Dialog/dialog.spec.md` — body 捲動
 - `../Sidebar/sidebar.spec.md` — nav 長列表捲動

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

@@ -20,7 +20,8 @@ import { cn } from '@/lib/utils'
  * 捲動時浮現(hover / scroll 自動顯示)。
  *
  * ── 何時用 ──
- * - DataTable 橫向捲動(水平跑版最明顯場景)
+ * - 寬內容橫向捲動(寬表格類 demo / 程式碼區塊;例外:DataTable 中央捲動區走 native
+ *   overflow-x-auto + scrollLeft 同步,不用 ScrollArea — 見 scroll-area.spec.md「何時用」)
  * - Sheet / Dialog 垂直內容捲動(body 太長)
  * - Sidebar nav 長列表
  * - 任何「內容可能溢出容器」且「跨 OS 視覺必須一致」的場景
@@ -33,7 +34,9 @@ import { cn } from '@/lib/utils'
 
 const ScrollArea = React.forwardRef<
   React.ElementRef<typeof ScrollAreaPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root> & {
+  // asChild Omit(2026-07-18 決策2):Root 恆渲染固定三子節點(Viewport + ScrollBar + Corner)
+  // → <Root asChild> Radix Slot React.Children.only crash。children 保留(路由進固定 Viewport)。
+  Omit<React.ComponentPropsWithoutRef<typeof ScrollAreaPrimitive.Root>, 'asChild'> & {
     /** 2026-07-08(WM 戰役 R2):Radix Viewport 內建 wrapper `display:table; min-width:100%`
      *  讓垂直捲動容器內的 flex 多欄佈局以 max-content 佈局、突破 100% 寬(WM 兩欄 dialog
      *  右欄被裁 33px 實證)。垂直捲動場景 opt-in 此 prop 中和為 block/w-full(水平捲動