@qijenchen/design-system 0.1.0-beta.75 → 0.1.0-beta.76

package/src/components/DatePicker/date-picker.anatomy.stories.tsx

@@ -33,7 +33,7 @@ const COLOR_MAP: Record<ModeKey, Partial<Record<StateKey, ColorSpec>>> = {
     disabled: { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent',     icon: '--fg-disabled' },
   },
   readonly: {
-    default:  { bg: '--bg-readonly', text: '--foreground',  border: 'transparent',     icon: '--fg-muted' },
+    default:  { bg: '--bg-readonly', text: '--foreground',  border: 'transparent',     icon: '—' },
   },
   disabled: {
     default:  { bg: '--bg-disabled', text: '--fg-disabled', border: 'transparent',     icon: '--fg-disabled' },
@@ -50,9 +50,9 @@ interface SizeSpec {
 }
 
 const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
-  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, clearHover: 18 },
-  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, clearHover: 18 },
-  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, clearHover: 22 },
+  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, clearHover: 18 },
+  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, clearHover: 18 },
+  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, clearHover: 22 },
 }
 
 const MODE_DESC: Record<ModeKey, string> = {
@@ -172,7 +172,7 @@ export const Overview = {
       <div className="flex flex-col gap-4">
         <div className="flex flex-col gap-1">
           <H3>結構（Anatomy）</H3>
-          <Desc>edit 模式：可點擊的觸發列顯示格式化日期文字 + 日曆圖示（固定右側），點任意位置都會展開日期面板。clearable 有值時額外顯示 X 清除按鈕。readonly / disabled 模式：格式化文字 + Calendar icon（類型身份 indicator；disabled 切 fg-disabled），無 X。</Desc>
+          <Desc>edit 模式：可點擊的觸發列顯示格式化日期文字 + 日曆圖示（固定右側），點任意位置都會展開日期面板。clearable 有值時額外顯示 X 清除按鈕。readonly 模式：純格式化文字，無 Calendar icon、無 X。disabled 模式：格式化文字 + Calendar icon（類型身份 indicator，切 fg-disabled），無 X。</Desc>
         </div>
         <div className="flex gap-8">
           {/* Edit layout */}
@@ -346,7 +346,7 @@ const InspectorInner = () => {
                 { c: Z.pad, l: '左右內距' },
                 ...(isEdit ? [{ c: Z.input, l: 'trigger text' }] : [{ c: Z.input, l: 'formatted text' }]),
                 ...(showClear ? [{ c: Z.action, l: 'X clear' }] : []),
-                { c: Z.icon, l: 'Calendar' },
+                ...(mode !== 'readonly' ? [{ c: Z.icon, l: 'Calendar' }] : []),
               ].map(({ c, l }) => (
                 <span key={l} className="inline-flex items-center gap-1">
                   <span className="w-2.5 h-2.5 rounded-md" style={{ background: c.bg, border: `1px dashed ${c.border}` }} />
@@ -364,8 +364,12 @@ const InspectorInner = () => {
                     <BpZone w={44} color={Z.action} label={`${s.icon}px`} sub="clear" />
                   </>
                 )}
-                <BpZone w={32} color={Z.gap} label={s.gapToken} sub={`${s.gap}px`} />
-                <BpZone w={44} color={Z.icon} label={`${s.icon}px`} sub="Calendar" />
+                {mode !== 'readonly' && (
+                  <>
+                    <BpZone w={32} color={Z.gap} label={s.gapToken} sub={`${s.gap}px`} />
+                    <BpZone w={44} color={Z.icon} label={`${s.icon}px`} sub="Calendar" />
+                  </>
+                )}
                 <BpZone w={44} color={Z.pad} label={s.pxToken} sub={`${s.px}px`} />
               </div>
               <div className="ml-3 flex items-center" style={{ height: 52 }}>
@@ -393,7 +397,7 @@ const InspectorInner = () => {
             <PropRow label="Fill"><TokenValue value={colors.bg} /></PropRow>
             <PropRow label="Text"><TokenValue value={colors.text} /></PropRow>
             <PropRow label="Border"><TokenValue value={colors.border} /></PropRow>
-            {isEdit && (
+            {mode !== 'readonly' && (
               <PropRow label="Calendar">
                 <TokenValue value={colors.icon} />
               </PropRow>
@@ -424,7 +428,7 @@ const InspectorInner = () => {
             <PropRow label="高度" dot={Z.dim.text}><TkVal token={s.heightToken} value={s.height} /></PropRow>
             <PropRow label="左右內距" dot={Z.pad.text}><TkVal token={s.pxToken} value={`${s.px}px`} /></PropRow>
             <PropRow label="元素間距" dot={Z.gap.text}><TkVal token={s.gapToken} value={`${s.gap}px`} /></PropRow>
-            {isEdit && (
+            {mode !== 'readonly' && (
               <PropRow label="Calendar" dot={Z.icon.text}>{s.icon}px</PropRow>
             )}
             {showClear && (
@@ -686,7 +690,7 @@ export const StateBehavior = {
               <span className="text-fg-muted text-caption">→</span>
               <DatePicker mode="disabled" value="2026-04-02" className="w-56" />
             </div>
-            <span className="text-[11px] text-fg-muted">左：edit（有 X）→ 中：readonly（無 X，保留 Calendar）→ 右：disabled（無 X，Calendar 與文字切 fg-disabled）</span>
+            <span className="text-[11px] text-fg-muted">左：edit（有 X）→ 中：readonly（無 X、無 Calendar，純文字）→ 右：disabled（無 X，保留 Calendar，與文字切 fg-disabled）</span>
           </div>
         </div>
 

package/src/components/DatePicker/date-picker.spec.md

@@ -310,7 +310,7 @@ DatePicker 套 `React.forwardRef` + `displayName`;`DatePickerProps` extends `Omi
 
 ## 邊界案例
 
-- **Disabled**:Field SSOT own;resolvedMode='disabled' 走 readonly / disabled 純 wrapper 分支(無 Popover trigger、`aria-disabled`、不開 picker),文字與 Calendar icon 切 `text-fg-disabled`。顯式 `mode="display"` 永遠最優先(useResolvedFieldMode step 1,見 field-context.ts):display + disabled 同傳走 display 分支不套 disabled token;要 disabled chrome 傳 `disabled` 或 `mode="disabled"`。
+- **Disabled**:Field SSOT own;resolvedMode='disabled' 走 readonly / disabled 純 wrapper 分支(無 Popover trigger、`aria-disabled`、不開 picker),文字與 Calendar icon 切 `text-fg-disabled`。readonly 不顯示 Calendar icon(類型身份 indicator 規則,SSOT field-controls.spec.md L227);disabled 保留並切 `fg-disabled`。顯式 `mode="display"` 永遠最優先(useResolvedFieldMode step 1,見 field-context.ts):display + disabled 同傳走 display 分支不套 disabled token;要 disabled chrome 傳 `disabled` 或 `mode="disabled"`。
 - **Loading(server-rendered grid)**:DatePicker 為 sync UI 不獨立 own loading。若 consumer 場景需 async date constraint fetch(如後端 disabled-dates list),consumer 應先 disable trigger 直到 fetch 完成,或在 popover 開啟後 body 切 `<Empty icon={<CircularProgress/>}/>`(對齊 panel-body loading SSOT)。本 spec scope 內不渲 loading state。
 - **Empty(no value)**:`value=null` → trigger 顯 placeholder(預設 `YYYY/MM/DD`,showTime 時 `YYYY/MM/DD HH:MM`;consumer 可傳 `placeholder` 覆寫)。無導覽目標時鍵盤焦點停留(react-day-picker v9 內建)。
 - **Invalid date input**:Field validation 處理 `aria-invalid="true"` + error border + 下方 error message;DatePicker 本身不 own validation 規則。

package/src/components/DatePicker/date-picker.tsx

@@ -483,9 +483,9 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
               : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
             }
           </span>
-          {/* 2026-06-10 類型身份 indicator:readonly/disabled 保留(naked cell 依 showDisplayEndIcon=isEditable,
-              並修掉原「disabled cell 無視 gate 漏顯」之 2026-05-10 cell canonical 違反);disabled → fg-disabled(spec L213)*/}
-          {(variant === 'naked' ? showDisplayEndIcon : true) && (
+          {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示(純值、不可開) / disabled 保留(fg-disabled,對齊原生 <select disabled>);
+              naked cell 依 showDisplayEndIcon=isEditable(維持 2026-05-10 cell canonical「非可編欄不顯」)*/}
+          {(variant === 'naked' ? showDisplayEndIcon : resolvedMode === 'disabled') && (
             <ItemSuffix className="pointer-events-none">
               <CalendarIcon size={iconSize} className={resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted'} aria-hidden />
             </ItemSuffix>
@@ -897,9 +897,12 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
           <span className={cn('flex-1 min-w-0 truncate', !endIso && 'text-fg-muted', resolvedMode === 'disabled' && 'text-fg-disabled')}>
             {endIso ? formatDateOrDateTime(endIso, showTime, showSeconds, { formatOptions, locale }) : resolvedPlaceholder[1]}
           </span>
-          <ItemSuffix className="pointer-events-none">
-            <CalendarIcon size={iconSize} className={resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted'} aria-hidden />
-          </ItemSuffix>
+          {/* 2026-06-26 類型身份 indicator:readonly 不顯示 / disabled 保留(fg-disabled)— 對齊單一 DatePicker(:488)+ SSOT;Range 無 naked-cell 變體故 gate = resolvedMode==='disabled' */}
+          {resolvedMode === 'disabled' && (
+            <ItemSuffix className="pointer-events-none">
+              <CalendarIcon size={iconSize} className="text-fg-disabled" aria-hidden />
+            </ItemSuffix>
+          )}
         </div>
       )
     }

package/src/components/DescriptionList/description-list.tsx

@@ -123,7 +123,7 @@ DescriptionItem.displayName = 'DescriptionItem'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const descriptionListMeta = {
   component: 'DescriptionList',
-  family: null, // non-family composite / overlay / layout
+  family: 'composite', // 對齊 description-list.spec.md frontmatter family: composite(SSOT)
   variants: {
 
   },

package/src/components/Dialog/dialog.anatomy.stories.tsx

@@ -417,7 +417,7 @@ export const ColorMatrix: Story = {
     <div className="flex flex-col gap-8">
       <div>
         <H3>Density</H3>
-        <Desc>Dialog 鎖 `data-layout-space="lg"`(只鎖版面間距 tier)+ ui-size 繼承 page `data-density`(控件不被撐大)。modal 值得寬鬆呼吸 padding:body px-loose 24 / header py-tight 16 → header 56(宣告 lg tier)。reinstate c3d3b736 decouple(只鎖 layout-space,非當年連 ui-size 一起鎖撐高 header 的 density)。世界級:Material M3 / Atlassian modal padding 24。</Desc>
+        <Desc>Dialog **不自設任何 density attribute**,layout-space + ui-size 全繼承 page。md page → body px-loose 16 / header py-tight 12 → header 48;lg page → 24 / 16 → header 56,隨 page tier。modal 寬鬆呼吸由 page tier 自動滿足(lg 拿 24 = Material 級;md 16 = Polaris Modal 下限)。世界級:SAP Fiori / AWS Cloudscape 皆讓 modal 跟 page density dial 走,不釘固定 tier。</Desc>
       </div>
 
       <div>

package/src/components/DropdownMenu/dropdown-menu.spec.md

@@ -217,7 +217,7 @@ Item-level default / hover / focused / selected / disabled **色彩**由 MenuIte
 - **Disabled item**:`<DropdownMenuItem disabled>`(Radix 內建支援),視覺繼承 MenuItem SSOT(`text-fg-disabled` + `aria-disabled=true` + 鍵盤導覽 skip + 不觸發 onSelect)。
 - **Loading(async submenu / async items)**:DropdownMenu primitive 不獨立 own loading prop。async submenu 場景應由 consumer 在 `<DropdownMenuSub>` 內條件性渲 `<DropdownMenuItem disabled>` + spinner label(如「載入中...」);或 fetch options 前先 disable 整個 menu trigger。完整 loading body 替換 pattern 屬 SelectMenu scope,不在 DropdownMenu scope。
 - **Empty(no items / async fetch result empty)**:consumer 應條件性渲 `<DropdownMenuItem disabled>` 顯示「無可用動作」字樣;不渲空 menu。
-- **Dark mode / density**:走 MenuItem + Popover SSOT 自動 adapt;density 預設 lock `md`(M3 portal subtree convention)。
+- **Dark mode / density**:走 MenuItem + Popover SSOT 自動 adapt;density 繼承 page(不鎖;DropdownMenu item 高度 = field-height-{size} 隨 page density 變,鎖 md 會釘死 md-scale 對不上 lg 觸發點),SSOT 見 `tokens/density/density.spec.md`。
 
 ---
 

package/src/components/Empty/empty.tsx

@@ -15,6 +15,8 @@ import { useRowSize } from '@/design-system/patterns/element-anatomy/item-anatom
  *   desc → action = mt-6（24px）
  *   title → desc = `var(--item-gap-label-desc-reading-lg)`（reading-lg tier token,item-anatomy SSOT;bare `--item-gap-label-desc` 已 retire）
  *
+ * description 字級隨 RowSizeContext 變（sm/md → text-body 14px,lg → text-body-lg 16px）。
+ *
  * Outer padding 由 consumer 容器決定(py-12 / py-6 / py-16 等）。
  */
 

package/src/components/Field/field-controls.spec.md

@@ -58,7 +58,9 @@ components/
 
 ---
 
-## Mode — 三種模式
+## Mode — 表單三態 (display 見下方 Display 段)
+
+下表涵蓋 Form-context 三態(edit / readonly / disabled);完整 `FieldMode` 為四值(`'edit' | 'display' | 'readonly' | 'disabled'`),`display` 模式於下方 `## Display` 段記載。
 
 | Mode | 底色 | 邊框 | 文字色 | 用途 |
 |------|------|------|--------|------|
@@ -226,14 +228,15 @@ Field 內的具體套用：
 
 ## 下拉箭頭（Select / Combobox）與類型身份 indicator
 
-Select / Combobox 的 ChevronDown、DatePicker 的 Calendar、TimePicker 的 Clock = **類型身份 indicator**(「這是什麼欄位」),**「是欄位」的所有狀態都顯示**(2026-06-10 user 拍板;對齊原生 select / MUI #19833 / Carbon read-only「keep icon signifiers de-emphasized」/ Accordion M24 precedent):
+Select / Combobox 的 ChevronDown、DatePicker 的 Calendar、TimePicker 的 Clock = **類型身份 indicator**(「這是什麼欄位」)。**edit 顯示(可互動)/ readonly 不顯示 / disabled 顯示(灰示)**(2026-06-26 user 拍板;readonly = 純值顯示、不可開下拉 → 箭頭會誤導故不顯;disabled 保留對齊原生 `<select disabled>` 灰示箭頭 + MUI #19833 / Carbon read-only「keep icon signifiers de-emphasized」/ Accordion M24 precedent):
 
-- edit / readonly:`fg-muted`;**disabled:`fg-disabled`**(對齊上方 Icon 色彩原則)
+- edit:`fg-muted`;**readonly:不顯示 indicator**;**disabled:`fg-disabled`**(對齊上方 Icon 色彩原則)
 - 不可互動(`pointer-events-none`)——下拉由 select 元素本身觸發
 - **Cell(naked variant)例外**:indicator 依 `showDisplayEndIcon`(= cell 的 isEditable)——非可編欄不顯(2026-05-10 cell canonical「indicator = editable affordance」);**可編欄的 disabled cell 顯示 + fg-disabled**(同表單邏輯)
 - locked(readonly/disabled)wrapper 並設 `aria-disabled`(disabled 時)——styled-disabled 非原生元素需明告 AT inactive,亦使 axe 正確套用 WCAG 1.4.3 inactive-UI 豁免
 - clearable 有值時：clear X 在左，ChevronDown 在右
-- 右側元素(clear + chevron)水平間距對齊 Field container padding token(具體值見 `field-wrapper.tsx`),跟 Input 一致
+- **右側元素(clear / chevron / calendar / clock)右緣水平內距 = `--field-px`(12px,SSOT `tokens/uiSize/uiSize.css`),edit / readonly / disabled / display 全 mode 一致**(跟 Input 一致)。**tag 模式特例**:左側 `tagPadding` 用對稱 px-calc(≈8px)貼齊 tags、會吃掉右緣,故 tag 容器(含 readonly/disabled)**必 re-assert `paddingRight: var(--field-px)`** 對齊 edit;漏接 = chevron 右緣偏移 bug(2026-06-27 修 Select:354 / Combobox ReadonlyMultiSelect)
+- **多行(Combobox tag wrap)垂直對齊**:tags 換行、容器動態變高時,右側 chevron **鎖第一行 tag 中線**(非整體置中)——容器 `items-start` + `ItemSuffix self-start` + `style={{ height: tagHeight }}`(sm 20 / md+lg 24)。對齊 item-anatomy「suffix 永遠 `h-[1lh]` 對齊第一行」canonical;edit / readonly / disabled 全 mode 一致(2026-06-27 補 readonly/disabled wrap 漏接)
 
 ## Select 顯示模式
 
@@ -246,9 +249,9 @@ Select 支援兩種顯示模式（`display` prop）：
 
 `plain` 模式可搭配 `startIcon`(代表 value 的圖示,如狀態 icon;2026-05-01 由 `text` 改名 `plain`,rationale 見 `select.spec.md`)。
 
-`tag` 模式的 edit 用 hidden select overlay(跟 Combobox 同模式),Tag 用 `pointer-events-none`,點擊穿透到 select。右側元素水平間距對齊 Field container padding token(見 `field-wrapper.tsx`)。
+`tag` 模式的 edit 用 hidden select overlay(跟 Combobox 同模式),Tag 用 `pointer-events-none`,點擊穿透到 select。右側元素右緣 = `--field-px`(見上方「右側元素」canonical;tag 模式 readonly/disabled 必 re-assert)。
 
-tagPadding 只在有 Tag 時才套用。Placeholder/空值狀態使用 fieldWrapper 的標準 px-3 padding，確保文字與邊框有足夠間距。
+tagPadding 只在有 Tag 時才套用。Placeholder/空值狀態使用 fieldWrapper 的標準 `--field-px`(`px-[var(--field-px)]`)padding，確保文字與邊框有足夠間距。
 
 ---
 

package/src/components/Field/field-wrapper.tsx

@@ -57,9 +57,9 @@ export const fieldWrapperStyles = cva(
         naked: '',
       },
       size: {
-        sm: 'text-body h-field-sm px-3 gap-2',
-        md: 'text-body h-field-md px-3 gap-2',
-        lg: 'text-body-lg h-field-lg px-3 gap-2',
+        sm: 'text-body h-field-sm px-[var(--field-px)] gap-2',
+        md: 'text-body h-field-md px-[var(--field-px)] gap-2',
+        lg: 'text-body-lg h-field-lg px-[var(--field-px)] gap-2',
       },
     },
     // mode x variant 交叉:visual chrome 由 compoundVariants 決定
@@ -98,7 +98,7 @@ export const fieldWrapperStyles = cva(
         mode: 'display',
         variant: 'default',
         // 2026-05-13 Q3 Path Ⅰ(user 拍板 Path Ⅰ 全 zero chrome + codex V2 verdict + field-controls.spec.md (d)):
-        // default display = zero chrome — !px-0 !py-0 override size token 的 px-3,跟 Select / Combobox
+        // default display = zero chrome — !px-0 !py-0 override size token 的 px-[var(--field-px)],跟 Select / Combobox
         // / DatePicker / TimePicker / LinkInput non-D-path bare-span idiom 一致(Carbon read-only / Stripe
         // display / Notion property / Polaris readonly TextField 全 zero chrome)。
         className: 'bg-transparent border border-transparent !px-0 !py-0',

package/src/components/FileItem/file-item.principles.stories.tsx

@@ -181,6 +181,7 @@ export const StatusProgressRule: Story = {
           name="users-export.csv"
           description="1.2 MB"
           status="completed"
+          surface="upload-manager"
           mode="rich"
         />
       </Rule>

package/src/components/FileUpload/file-upload.principles.stories.tsx

@@ -93,10 +93,10 @@ export const UsageGuidance: Story = {
         note="drag-over 只用邊框顏色(border-primary,底維持 surface 不變 bg)傳達狀態。加 scale 會讓區塊在拖放瞬間晃動、使用者滑鼠與 drop target 錯位;加 shadow 和元件 elevation 體系衝突。"
       >
         <div className="flex flex-col gap-2">
-          <div className="border-2 border-dashed border-primary bg-surface rounded-md px-6 py-10 text-center text-caption text-fg-muted">
+          <div className="border-2 border-dashed border-primary bg-surface rounded-md p-[var(--layout-space-loose)] text-center text-caption text-fg-muted">
             ✓ 僅改邊框顏色(dashed primary,底維持 surface)
           </div>
-          <div className="border-2 border-dashed border-primary bg-surface rounded-md px-6 py-10 text-center text-caption text-fg-muted scale-105 shadow-[var(--elevation-200)]">
+          <div className="border-2 border-dashed border-primary bg-surface rounded-md p-[var(--layout-space-loose)] text-center text-caption text-fg-muted scale-105 shadow-[var(--elevation-200)]">
             ✗ scale + shadow — 視覺噪音,與 elevation 系統衝突
           </div>
         </div>

package/src/components/FileUpload/file-upload.spec.md

@@ -140,7 +140,7 @@ FileUpload 是**拖放 / 點擊上傳區塊**——可拖曳檔案進入或點
 
 ## A11y 預設
 
-- `role="button"` + `tabIndex=0`(disabled 時 `-1`)
+- `role="button"` + `tabIndex=0`(disabled 或 loading 時 `-1`)
 - Enter / Space 鍵觸發檔案選取浮窗(模擬 click)
 - `aria-disabled={true}` 當 disabled
 - `<input type="file">` 以 `className="hidden"`(`display:none`)隱藏 — 移出無障礙樹、不可聚焦;互動由外層 `role="button"` wrapper 承載。Accessible name 來自 wrapper 內 Empty 的 title + description 文字(name-from-content),非 input 本身

package/src/components/HoverCard/hover-card.principles.stories.tsx

@@ -193,7 +193,7 @@ export const PureBehaviorPrimitiveRule: Story = {
             <HoverCardTrigger asChild>
               <Button variant="tertiary" size="sm">深色 Tooltip 樣式</Button>
             </HoverCardTrigger>
-            <HoverCardContent className="bg-tooltip text-inverse-fg rounded-md px-3 py-2" data-theme="dark">
+            <HoverCardContent className="bg-tooltip text-on-emphasis rounded-md px-3 py-2" data-theme="dark">
               <div className="w-48 text-caption">OverflowIndicator 風格:深底 + compact</div>
             </HoverCardContent>
           </HoverCard>

package/src/components/Input/input.anatomy.stories.tsx

@@ -51,9 +51,9 @@ interface SizeSpec {
 }
 
 const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
-  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, actionHover: 18 },
-  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, actionHover: 18 },
-  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, actionHover: 22 },
+  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, actionHover: 18 },
+  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, actionHover: 18 },
+  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, actionHover: 22 },
 }
 
 const MODE_DESC: Record<ModeKey, string> = {

package/src/components/LinkInput/link-input.anatomy.stories.tsx

@@ -92,9 +92,9 @@ interface SizeSpec {
 }
 
 const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
-  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body', font: '14px', icon: 16, actionHover: 18 },
-  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body', font: '14px', icon: 16, actionHover: 18 },
-  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, actionHover: 22 },
+  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body', font: '14px', icon: 16, actionHover: 18 },
+  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body', font: '14px', icon: 16, actionHover: 18 },
+  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, actionHover: 22 },
 }
 
 /* ═══════════════════════════════════════════════════════════════════════════

package/src/components/Notice/notice.anatomy.stories.tsx

@@ -448,7 +448,7 @@ export const VariantIconMap: Story = {
         <H3>Subtle 樣式視覺</H3>
         <Desc>
           Notice 本身不設 bg / border。此處 shell 為 Alert consumer 提供的 subtle container(
-          <code className="font-mono text-footnote mx-1">bg-*-subtle + border {`{hue}-hover`}</code>
+          <code className="font-mono text-footnote mx-1">bg-*-subtle + border {`{hue}-text`}</code>
           ),展示 icon 色彩在 subtle surface 上的對比。Solid(dark bg + 白字 icon)對照請查
           <code className="font-mono text-footnote mx-1">alert.anatomy.stories.tsx</code>
           。

package/src/components/NumberInput/number-input.anatomy.stories.tsx

@@ -45,11 +45,12 @@ const TOKEN_MAP: Record<ModeKey, Record<StateKey, ColorSpec>> = {
     disabled: { bg: 'transparent',    text: '--fg-disabled',  border: 'transparent' },
   },
   readonly: {
+    // readonly cva = `bg-readonly border border-transparent`(field-wrapper.tsx:109)—— 鎖定,無 hover / focus / error bg 轉換
     default:  { bg: '--bg-readonly',  text: '--foreground',   border: 'transparent' },
-    hover:    { bg: '--bg-disabled',  text: '--foreground',   border: 'transparent' },
-    focus:    { bg: '--bg-disabled',  text: '--foreground',   border: 'transparent' },
-    error:    { bg: '--bg-disabled',  text: '--foreground',   border: 'transparent' },
-    disabled: { bg: '--bg-disabled',  text: '--foreground',   border: 'transparent' },
+    hover:    { bg: '--bg-readonly',  text: '--foreground',   border: 'transparent' },
+    focus:    { bg: '--bg-readonly',  text: '--foreground',   border: 'transparent' },
+    error:    { bg: '--bg-readonly',  text: '--foreground',   border: 'transparent' },
+    disabled: { bg: '--bg-readonly',  text: '--foreground',   border: 'transparent' },
   },
   disabled: {
     default:  { bg: '--bg-disabled',  text: '--fg-disabled',  border: 'transparent' },
@@ -70,9 +71,9 @@ interface SizeSpec {
 }
 
 const SIZE_SPECS: Record<SizeKey, SizeSpec> = {
-  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, actionHover: 18 },
-  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, actionHover: 18 },
-  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-3', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, actionHover: 22 },
+  sm: { heightToken: 'h-field-sm', height: '28px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, actionHover: 18 },
+  md: { heightToken: 'h-field-md', height: '32px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body',    font: '14px', icon: 16, actionHover: 18 },
+  lg: { heightToken: 'h-field-lg', height: '36px', pxToken: 'px-[var(--field-px)]', px: 12, gapToken: 'gap-2', gap: 8, fontToken: 'text-body-lg', font: '16px', icon: 20, actionHover: 22 },
 }
 
 /* ═══════════════════════════════════════════════════════════════════════════

package/src/components/NumberInput/number-input.spec.md

@@ -124,7 +124,7 @@ col.accessor('price', {
 
 ## A11y 預設
 
-**ARIA / Pattern**:ARIA / keyboard 機制**僅 edit mode 適用**——edit mode 渲染 native `<input>` element(預設 a11y),且把 `...props`(含 `aria-label` / `aria-describedby` 等)轉發到該 input,Field wrapper 另補 `aria-invalid` / `aria-required` / `aria-describedby` / `aria-errormessage`。`display` / `readonly` / `disabled` 三 mode 渲染的是無互動純展示文字(`<div>` + `<span>`,不轉發 `aria-*`),螢幕報讀僅得格式化後的靜態值(對齊 Carbon read-only / Stripe display 慣例)。
+**ARIA / Pattern**:ARIA / keyboard 機制**僅 edit mode 適用**——edit mode 渲染 native `<input>` element(預設 a11y),且把 `...props`(含 `aria-label` / `aria-describedby` 等)轉發到該 input;該 native input 自身消費 `fieldCtx` 設定 `aria-invalid` / `aria-required` / `aria-describedby` / `aria-errormessage`(非由 Field wrapper 注入,對齊 Select / Combobox trigger 自設機制)。`display` / `readonly` / `disabled` 三 mode 渲染的是無互動純展示文字(`<div>` + `<span>`,不轉發 `aria-*`),螢幕報讀僅得格式化後的靜態值(對齊 Carbon read-only / Stripe display 慣例)。
 
 **Keyboard 行為**:
 

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

@@ -151,7 +151,7 @@ OverflowIndicator.displayName = 'OverflowIndicator'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const overflowIndicatorMeta = {
   component: 'OverflowIndicator',
-  family: null, // non-family composite / overlay / layout
+  family: 'self-contained', // 對齊 overflow-indicator.spec.md frontmatter family: self-contained(SSOT)
   variants: {
 
   },

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

@@ -147,7 +147,7 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 
 | 共享項 | SSOT owner |
 |---|---|
-| Avatar 左 inset 距 trigger.left = 12px 固定(不隨 size/density 漂移)| 本 spec L94 + `people-picker.tsx:362` `!px-3` inject(form context)/ `!px-[var(--table-cell-px)]`(naked variant table cell)|
+| Avatar 左 inset 距 trigger.left = 12px 固定(不隨 size/density 漂移)| 本 spec L94 + `people-picker.tsx:362` `!px-[var(--field-px)]` inject(form context)/ `!px-[var(--table-cell-px)]`(naked variant table cell)|
 | Avatar+人名視覺 | `person-display.tsx:137-152` `PersonDisplay`(共享 renderer)|
 | 人名按空間 ellipsis | `person-display.tsx:150` `truncate flex-1 min-w-0` |
 | Placeholder ellipsis(inline-search active 時)| `field-wrapper.tsx:244` `bareInputStyles` 含 `truncate` |
@@ -172,7 +172,7 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 
 **改 PeoplePicker 視覺前必查本表,動 trigger render / placeholder / overflowShape / tagWrapperClassName 前先 cite 對應 row。** Hook `check_peoplepicker_ssot_drift.sh` 機械強制。
 
-**Avatar 左 inset SSOT(GitHub people picker idiom)**:single trigger / multi stack 第一個 avatar 距 trigger.left = **12px 固定**(不隨 size / density 漂移)。實作:PeoplePicker form context + 有 tag → `cn(className, '!px-3')` inject 12px override 到 Combobox Field wrapper,**覆蓋** Combobox `tagPadding[size]` density-dependent calc 公式(該公式在 default lg + 全 comfortable 共 4/6 組合漂離 12px,故報廢改固定值;推導史詳 git log 2026-05-13);`tagAreaPaddingLeftPx={undefined}` 不再 +8 magic。Cell context naked variant `!px-[var(--table-cell-px)]` 已是 12px 不 inject。對齊 GitHub picker / Material Autocomplete renderTags / Ant Select tagRender 共享 fixed-inset canonical(不 scale with size)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Avatar 左 inset SSOT(GitHub people picker idiom)**:single trigger / multi stack 第一個 avatar 距 trigger.left = **12px 固定**(不隨 size / density 漂移)。實作:PeoplePicker form context + 有 tag → `cn(className, '!px-[var(--field-px)]')` inject 12px override 到 Combobox Field wrapper,**覆蓋** Combobox `tagPadding[size]` density-dependent calc 公式(該公式在 default lg + 全 comfortable 共 4/6 組合漂離 12px,故報廢改固定值;推導史詳 git log 2026-05-13);`tagAreaPaddingLeftPx={undefined}` 不再 +8 magic。Cell context naked variant `!px-[var(--table-cell-px)]` 已是 12px 不 inject。對齊 GitHub picker / Material Autocomplete renderTags / Ant Select tagRender 共享 fixed-inset canonical(不 scale with size)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 **判準**：
 - **選人 → PeoplePicker**（不用 Select / Combobox 代替，失去 Avatar 視覺）
@@ -249,7 +249,7 @@ PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox
 
 ## 邊界案例
 
-- **Disabled**:`disabled` → `resolvedMode='disabled'`(`useResolvedFieldMode`),走獨立 static-display 分支(`people-picker.tsx`「readonly / disabled」段)——渲染靜態 `<div>` 包 `MultiPersonDisplay` / `PersonDisplay` + `ItemSuffix` ChevronDown 類型身份 indicator(2026-06-10 加;naked variant 依 `showDisplayEndIcon`),**不** wrap Select / Combobox、無 dismiss X、無 inline-search input。視覺與 readonly 等效。token 走 M24 state precedence(`text-fg-disabled`,含 chevron)。
+- **Disabled**:`disabled` → `resolvedMode='disabled'`(`useResolvedFieldMode`),走獨立 static-display 分支(`people-picker.tsx`「readonly / disabled」段)——渲染靜態 `<div>` 包 `MultiPersonDisplay` / `PersonDisplay` + `ItemSuffix` ChevronDown 類型身份 indicator(2026-06-26:disabled 保留 chevron、readonly 不顯示;naked variant 依 `showDisplayEndIcon`),**不** wrap Select / Combobox、無 dismiss X、無 inline-search input。token 走 M24 state precedence(`text-fg-disabled`,含 chevron)。
 - **Loading(async people fetch)**:目前 PeoplePicker **未暴露 `loading` prop**(`PeoplePickerProps` 無此欄位,內部也未 forward 給 wrapped Select / Combobox)。consumer 若需 loading 態,在 fetch 完成前自行控制 `people=[]`(走 emptyText 空態)。底層 Select / Combobox / SelectMenu 各有自己的 loading 機制,但尚未經 PeoplePicker API 層轉發。
 - **Empty(no search results)**:`emptyText` 預設「沒有符合的人員」(本 spec L72 已 codify);無 creatable mode(人員不可建立)。
 - **Empty(no value selected)**:single mode → trigger 顯 placeholder「請選擇人員」;multi mode `value=[]` → trigger 同 placeholder(無 avatar stack 渲);詳「Trigger display SSOT canonical table」B-D 段。

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

@@ -1,6 +1,6 @@
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 // @placeholder-vocabulary-allow: 1-cycle backward-compat — `placeholder` 已加(trigger empty SSOT),`emptyPlaceholder={emptyText}` forward 仍保留讓既有 consumer 不被 silent break;Combobox line 760 `placeholder ?? emptyPlaceholder` fallback → placeholder 永遠 takes precedence。Future cycle 移除 emptyPlaceholder forward(per field-controls.spec.md 共享 contract b)。
-// @cell-metric-escape-allow: comment describes RETIRED `tagAreaPaddingLeftPx={8}` magic — current code is surface-guarded (`surface === 'form'` only injects `!px-3`; table-cell context untouched, lets naked `!px-[var(--table-cell-px)]` SSOT take over). Hook regex grep'd the comment word, not the live code path. Per (a) fix 2026-05-13 user-approved Path a.
+// @cell-metric-escape-allow: comment describes RETIRED `tagAreaPaddingLeftPx={8}` magic — current code is surface-guarded (`surface === 'form'` only injects `!px-[var(--field-px)]`; table-cell context untouched, lets naked `!px-[var(--table-cell-px)]` SSOT take over). Hook regex grep'd the comment word, not the live code path. Per (a) fix 2026-05-13 user-approved Path a.
 import * as React from 'react'
 import { ChevronDown } from 'lucide-react'
 import { cn } from '@/lib/utils'
@@ -189,8 +189,8 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
               ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured />
               : <PersonDisplay value={value as PersonValue} size={size} />}
         </span>
-        {/* 2026-06-10 類型身份 indicator:readonly/disabled 保留 chevron(naked cell 依 showDisplayEndIcon);disabled → fg-disabled */}
-        {(resolvedVariant === 'naked' ? showDisplayEndIcon : true) && (
+        {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示 / disabled 保留(fg-disabled,對齊原生 <select disabled>);naked cell 依 showDisplayEndIcon */}
+        {(resolvedVariant === 'naked' ? showDisplayEndIcon : resolvedMode === 'disabled') && (
           <ItemSuffix className="pointer-events-none">
             <ChevronDown size={ICON_SIZE[size as 'sm' | 'md' | 'lg']} className={cn('shrink-0', resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted')} aria-hidden />
           </ItemSuffix>
@@ -363,12 +363,12 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
       // 撤掉 `tagAreaPaddingLeftPx={8}` magic — Combobox `tagPadding[size]` 是 density-dependent
       // calc 公式(`(field-height - icon-size) / 2`),只在 md size + default density 才 = 4px;
       // 其他 size/density 漂 6px / 8px → 4+8=12 spec 公式不成立。
-      // (a) fix:form context + 有 tag → 改 inject `!px-3`(固定 12px)直接 override `tagPadding[size]`,
+      // (a) fix:form context + 有 tag → 改 inject `!px-[var(--field-px)]`(固定 12px)直接 override `tagPadding[size]`,
       // 達成 GitHub PeoplePicker fixed 12px inset(對齊 cell context 同 13px from cell.left 含 1px border)。
-      // - form + 有 tag → `!px-3`(12px 固定 inset)+ tagAreaPaddingLeftPx undefined → field.padL=12 ✓
+      // - form + 有 tag → `!px-[var(--field-px)]`(12px 固定 inset)+ tagAreaPaddingLeftPx undefined → field.padL=12 ✓
       // - table-cell + 有 tag → naked variant `!px-[var(--table-cell-px)]` 已是 12px,不 inject ✓
       // - isEmpty → 不 inject,走 Combobox 預設文字 inset(`tagPadding[size]` 公式自然 vertical center)
-      className={cn(className, !isEmpty && surface === 'form' && '!px-3')}
+      className={cn(className, !isEmpty && surface === 'form' && '!px-[var(--field-px)]')}
       aria-label={ariaLabel}
       // 2026-05-15 Bug 1 fix(Claude+Codex Step 5 比稿 consensus,user verbatim「就 A」):per-length 動態
       // wrapper class — length=1 降階單人視覺需要 width constraint chain(`flex-1 min-w-0 overflow-hidden`),

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

@@ -253,7 +253,7 @@ export const VisualAlignmentRule: Story = {
     <div>
       <Rule
         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=lg(寬鬆呼吸),兩者 ui-size 都繼承 page"
+        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>
@@ -285,10 +285,10 @@ export const VisualAlignmentRule: Story = {
       </Rule>
 
       <Rule
-        title="為什麼 density 鎖 md"
-        note="頁面 density 大(lg)時,Popover 若跟著放大會失去「輕量補充 UI」的定位 — 使用者會誤以為是主 modal。鎖 md 讓 Popover 永遠比主頁面緊湊,保持「這是補充不是主流程」的視覺暗示"
+        title="為什麼 layout-space 鎖 md"
+        note="Popover 只鎖 layout-space=md(header / footer padding 永遠精簡),內部控件的 ui-size 繼承 page(對齊 trigger)。頁面 layout-space 大(lg)時,Popover 若 header / footer 跟著放大會失去「輕量補充 UI」的定位 — 使用者會誤以為是主 modal。鎖 layout-space=md 讓 Popover chrome 永遠比主頁面緊湊,保持「這是補充不是主流程」的視覺暗示"
       >
-        <Label>頁面 density = lg,Popover 內部仍是 md — 輕量感不被放大破壞</Label>
+        <Label>頁面 layout-space = lg,Popover header / footer 仍是 md(內部控件 ui-size 繼承 page)— 輕量感不被放大破壞</Label>
       </Rule>
     </div>
   ),

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

@@ -498,7 +498,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">{"詳 `profile-card.spec.md` 「A11y 預設」段。摘要:\n\n> 命名對齊 DS 設計準則(2026-05-18,per  # 命名與語言一致性 )。本節原標題「無障礙」,改「A11y 預設」與其他 spec 一致。\n\n-   Trigger 整合  :Avatar 作為 HoverCard trigger 時, onFocus  /  onBlur  與 mouseenter/leave 同時觸發由 Radix HoverCard 管理——鍵盤使用者 Tab 到 avatar 可自動顯示 card,Escape 關閉\n-   Focus 順序  :Radix  HoverCard  預設不抓取 focus 進入浮層——HoverCardContent 每次 render 把浮層內所有 tabIndex>=0 節點 set tabindex=-1(@radix-ui/react-hover-card dist index.js L217-222),刻意把 action / view more 移出 tab order。hover-integrated 路徑下鍵盤使用者 Tab 只停在 trigger(Avatar),無法 Tab 聚焦浮層內 action / view more(與 Popover 的 focus trap 截然不同)。需要鍵盤可達 action 改用 Popover / Dialog\n-   Live region 語意  :ProfileCard 是展示內容,非 announcement,不套  aria-live \n-   DL 語意  :Info Fields 使用 DescriptionList(<dl>/<dt>/<dd>),screen reader 讀「term X, description Y」(詳 description-list.spec.md「無障礙」段)\n-   CTA button aria-label  :icon-only action button 必帶  aria-label (「傳訊息給 {name}」),不只 icon 視覺\n-   色彩對比  :Status badge / Avatar status 圓點均過 WCAG AA,不依賴單一色彩載體(搭配文字標籤)"}</p>
+      <p className="whitespace-pre-line">{"詳 `profile-card.spec.md` 「A11y 預設」段。摘要:\n\n> 命名對齊 DS 設計準則(2026-05-18,per  # 命名與語言一致性 )。本節原標題「無障礙」,改「A11y 預設」與其他 spec 一致。\n\n-   Trigger 整合  :Avatar 作為 HoverCard trigger 時, onFocus  /  onBlur  與 mouseenter/leave 同時觸發由 Radix HoverCard 管理——鍵盤使用者 Tab 到 avatar 可自動顯示 card,Escape 關閉\n-   Focus 順序  :Radix  HoverCard  預設不抓取 focus 進入浮層——HoverCardContent 每次 render 把浮層內所有 tabIndex>=0 節點 set tabindex=-1(@radix-ui/react-hover-card 的 getTabbableNodes + setAttribute('tabindex','-1');dist 行號隨安裝版本浮動,不 pin),刻意把 action / view more 移出 tab order。hover-integrated 路徑下鍵盤使用者 Tab 只停在 trigger(Avatar),無法 Tab 聚焦浮層內 action / view more(與 Popover 的 focus trap 截然不同)。需要鍵盤可達 action 改用 Popover / Dialog\n-   Live region 語意  :ProfileCard 是展示內容,非 announcement,不套  aria-live \n-   DL 語意  :Info Fields 使用 DescriptionList(<dl>/<dt>/<dd>),screen reader 讀「term X, description Y」(詳 description-list.spec.md「無障礙」段)\n-   CTA button aria-label  :icon-only action button 必帶  aria-label (「傳訊息給 {name}」),不只 icon 視覺\n-   色彩對比  :Status badge / Avatar status 圓點均過 WCAG AA,不依賴單一色彩載體(搭配文字標籤)"}</p>
     </div>
   ),
 }

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

@@ -314,7 +314,7 @@ export const nameCardMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: [], // 唯讀 person-info template,無自身互動 state（hover/active/focus/disabled 屬子 Button/Avatar）
   tokens: {
     bg: ['bg-muted'],
     fg: ['text-foreground'],

package/src/components/ProgressBar/progress-bar.spec.md

@@ -72,7 +72,7 @@ ProgressBar 是**量化 linear 進度** primitive——consumer 必須能回答
 | **視覺** | 水平直線從左往右填充 | 圓弧從 12 點順時針填充 / indeterminate 整體旋轉 |
 | **典型情境** | 批次處理 / 表單 wizard / 頁面級大區塊 / quota(檔案上傳 → 走 FileItem) | Button loading / Field loading / cell 局部 / inline 小 % |
 | **可量化時機** | **必須能量化**(100% 結束可預期) | determinate 能量化 / indeterminate 不需要 |
-| **a11y** | `role="progressbar"` + `aria-valuenow` | `role="progressbar"`(有 value) / `role="status"`(無 value) |
+| **a11y** | `role="progressbar"` + `aria-valuenow` | `role="progressbar"`(有 value) / `role="status"`(無 value 且有 label/aria-label;否則 aria-hidden 交父層 aria-busy) |
 | **終止條件** | 到 100% 或 status 變 success / error | 任務完成(卸載或 aria-busy 移除) |
 | **typical 時長** | 秒級到分鐘級(值得顯示比例) | 秒級(短暫等待) / 秒到分鐘(determinate) |
 

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

@@ -124,7 +124,7 @@ const Tab = ({ active, onClick, children }: { active: boolean; onClick: () => vo
     type="button"
     onClick={onClick}
     className={`px-2.5 py-1 text-[12px] font-mono rounded-md cursor-pointer transition-colors ${
-      active ? 'bg-primary text-white font-semibold' : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
+      active ? 'bg-primary text-on-emphasis font-semibold' : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
     }`}
   >
     {children}
@@ -237,7 +237,7 @@ const InspectorInner = () => {
             <PropRow label="aria-valuemax">{readOnly || disabled ? '—' : '5'}</PropRow>
             <PropRow label="aria-valuetext">{readOnly || disabled ? '—' : `${value} of 5 stars`}</PropRow>
             <PropRow label="aria-label">{readOnly ? '必填' : 'Field 內免填 · standalone 必填'}</PropRow>
-            <PropRow label="aria-labelledby">{readOnly || disabled ? '—' : 'Field 內自動指向 FieldLabel'}</PropRow>
+            <PropRow label="aria-labelledby">Field 內自動指向 FieldLabel（所有模式,含 readonly/disabled）</PropRow>
           </div>
         </div>
       </div>

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

@@ -170,7 +170,7 @@ Star icon 渲染時明確設 `stroke="none"`(Lucide Star 預設 `stroke="current
 ## A11y 預設
 
 - **interactive**：`role="slider"` + `aria-valuenow={value}` + `aria-valuemin={0}` + `aria-valuemax={max}` + `aria-valuetext={`{value} of {max} stars`}` + `tabIndex={0}`，鍵盤 Arrow Left/Right/Up/Down ± step（precision=half 時 step=0.5，否則 step=1）；Home = 0；End = max（完整 WAI-ARIA slider keyboard pattern）
-- **readOnly**：`role="img"` + `aria-label`（**必填**），例：`aria-label="平均評分 4.7 星，共 5 星"`。無 tabIndex
+- **readOnly**：`role="img"` + accessible name。`Field` 內由 `aria-labelledby` 自動指向 `FieldLabel`（免填 `aria-label`）；standalone（無 Field）時 `aria-label` 必填，例：`aria-label="平均評分 4.7 星，共 5 星"`。無 tabIndex
 - **disabled**：`aria-disabled="true"` + `pointer-events-none`
 - **單顆星** `aria-hidden`：內部點擊目標是 `<span role="presentation" aria-hidden>`（非 interactive element，避免與外層 `role="slider"` 形成 axe nested-interactive 違規，2026-04-25 修正；含 half-precision 的兩個 hover zone）都不干擾螢幕閱讀器，父層 role 獨自表達語意
 

package/src/components/Rating/rating.tsx

@@ -17,7 +17,7 @@ import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useRes
  * ── 視覺 ──
  * 填色用 `var(--warning)`(yellow-6,世界級黃星 convention;與 warning 語意共用色相
  * 但語境不同,評分 = UX convention color 非 status)。
- * 空色用 `var(--color-neutral-4)`(灰色;與 disabled/empty 同級)。
+ * 空色用 `var(--divider)`(neutral-4 借 divider semantic alias;灰色;與 disabled/empty 同級)。
  *
  * ── 互動 ──
  * interactive(預設):hover 預覽、click 設值、keyboard Left/Right 改值