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

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

@@ -35,6 +35,20 @@ export interface DateFormatOptions {
  * (跟 ISO date 視覺對不上,跟 sort 順序也對不上)。Ant / Material X / Apple HIG
  * 一致 year-first。Consumer 想自訂可傳 `formatOptions` + `locale`。
  */
+// 2026-07-06 D3 perf:formatOptions/locale 顯式傳入時走 Intl.DateTimeFormat(貴 constructor)。
+// DataTable date 欄轉發此 config → 每 cell × 每次表格 re-render 重建。module-level cache 重用實例
+// (無狀態可安全重用),key = locale|JSON.stringify(options)。行為 Δ=0。
+const dtfCache = new Map<string, Intl.DateTimeFormat>()
+function getDateTimeFormatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  const key = locale + '|' + JSON.stringify(options)
+  let fmt = dtfCache.get(key)
+  if (!fmt) {
+    fmt = new Intl.DateTimeFormat(locale, options)
+    dtfCache.set(key, fmt)
+  }
+  return fmt
+}
+
 function formatDate(
   value: string | number | Date,
   options: DateFormatOptions = {},
@@ -43,7 +57,7 @@ function formatDate(
   if (Number.isNaN(date.getTime())) return String(value)
   // 若 consumer 顯式傳 formatOptions / locale → 走 Intl.DateTimeFormat
   if (options.formatOptions || options.locale) {
-    return new Intl.DateTimeFormat(options.locale ?? 'en-US', options.formatOptions ?? { year: 'numeric', month: '2-digit', day: '2-digit' }).format(date)
+    return getDateTimeFormatter(options.locale ?? 'en-US', options.formatOptions ?? { year: 'numeric', month: '2-digit', day: '2-digit' }).format(date)
   }
   // 預設:YYYY/MM/DD(直接組,locale-independent + 視覺穩定)
   const y = date.getFullYear()
@@ -537,13 +551,9 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
               if (e.key === 'Escape') setOpen(false)
             }}
             className={cn(
-              fieldWrapperStyles({ mode: 'edit', variant: variant, size }),
+              fieldWrapperStyles({ mode: 'edit', variant: variant, size, error }),
               'text-left cursor-pointer',
               'focus-visible:outline-none',
-              error && [
-                'border-error hover:border-error-hover',
-                'focus-within:border-error focus-within:hover:border-error',
-              ],
               className,
             )}
             {...props}
@@ -640,10 +650,13 @@ const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>(
                 }
               />
             </div>
-            {showTime && (
+            {(showTime || needConfirm) && (
               // Footer:消費 SurfaceFooter SSOT(border-t + canonical px-loose py-tight padding,
               // 不再 hand-coded p-2 / Separator / ml-auto wrapper 三層垃圾)。
               // 「此刻」加 mr-auto 把後面 button 推右(對齊 Ant `marginInlineStart: auto` on OK)。
+              // 2026-07-05 D4:gate 由 `showTime` 改 `(showTime || needConfirm)` 對齊 Range(:1068)—
+              // date-only `needConfirm` 時 onSelect 只寫 draft 且不關 popover,footer「確定」是唯一
+              // commit 路徑,原 gate 漏渲 footer = draft 永遠無法 commit 的死路。
               <SurfaceFooter>
                 <Button variant="tertiary" size="sm" onClick={handleNow} className="mr-auto">此刻</Button>
                 {needConfirm ? (
@@ -756,6 +769,15 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
     const [draft, setDraft] = React.useState<[string | null, string | null]>(value ?? [null, null])
     const [activeEnd, setActiveEnd] = React.useState<'start' | 'end'>('start')
 
+    // 2026-07-05 D4 focus 回復:Range 只用 PopoverAnchor(start/end button 自行 onClick 開啟),
+    // Radix triggerRef 恆 null → 內建 onCloseAutoFocus 的 triggerRef.focus() no-op 後又
+    // preventDefault 掉 FocusScope fallback → Esc/確定/選完自動關閉後焦點掉到 document.body
+    // (WCAG 2.4.3)。手動回焦 active 端 button(對齊 Ant RangePicker);outside-click 關閉
+    // 依 Radix non-modal 慣例不搶焦(hasInteractedOutside 鏡射 Radix 自家 guard)。
+    const startBtnRef = React.useRef<HTMLButtonElement>(null)
+    const endBtnRef = React.useRef<HTMLButtonElement>(null)
+    const hasInteractedOutsideRef = React.useRef(false)
+
     // Sync draft from value ONLY on open false→true(canonical 2026-05-02 v3):
     // 之前用 `[value, open]` 雙 dep,popover 開啟期間 value 任何 reference 變更 → useEffect
     // 觸發 → 直接 clobber user 的 draft 編輯。改成只在 open 從 false→true 同步。
@@ -921,18 +943,15 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
             data-error={error ? '' : undefined}
             data-state={open ? 'open' : 'closed'}
             className={cn(
-              fieldWrapperStyles({ mode: 'edit', size }),
+              fieldWrapperStyles({ mode: 'edit', size, error }),
               'cursor-text',
-              error && [
-                'border-error hover:border-error-hover',
-                'focus-within:border-error focus-within:hover:border-error',
-              ],
               className,
             )}
             {...props}
           >
             <button
               type="button"
+              ref={startBtnRef}
               onClick={() => openWithActive('start')}
               data-active-end={open && activeEnd === 'start' ? 'true' : undefined}
               aria-label={resolvedPlaceholder[0]}
@@ -950,6 +969,7 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
             <ArrowRight size={iconSize} className="shrink-0 text-fg-muted mx-2" aria-hidden />
             <button
               type="button"
+              ref={endBtnRef}
               onClick={() => openWithActive('end')}
               data-active-end={open && activeEnd === 'end' ? 'true' : undefined}
               aria-label={resolvedPlaceholder[1]}
@@ -979,7 +999,22 @@ const DatePickerRange = React.forwardRef<HTMLDivElement, DatePickerRangeProps>(
             </ItemSuffix>
           </div>
         </PopoverAnchor>
-        <PopoverContent className="w-auto p-0" align="start">
+        <PopoverContent
+          className="w-auto p-0"
+          align="start"
+          // 2026-07-05 D4 focus 回復(機制詳 :758 comment):outside-click 標記不搶焦(鏡射
+          // Radix non-modal 自家 hasInteractedOutside guard);其餘關閉路徑(Esc / 確定 /
+          // 選完自動關)preventDefault 掉內建 triggerRef.focus()(Anchor-only 恆 null no-op)
+          // 後手動回焦 active 端 button — 對齊 Ant RangePicker 關閉後焦點回 active 端輸入格。
+          onInteractOutside={() => { hasInteractedOutsideRef.current = true }}
+          onCloseAutoFocus={(e) => {
+            e.preventDefault()
+            if (!hasInteractedOutsideRef.current) {
+              ;(activeEnd === 'start' ? startBtnRef : endBtnRef).current?.focus()
+            }
+            hasInteractedOutsideRef.current = false
+          }}
+        >
           {/* 2026-05-06 v9.1 M25 chain — 同 single DatePicker 修法,viewport 壓縮 calendar 內滾 + footer 永遠 in-view */}
           <div role="dialog" aria-label="日期區間選擇" className="flex flex-col flex-1 min-h-0">
             <div className="flex-1 min-h-0 overflow-y-auto">
@@ -1123,9 +1158,11 @@ export const datePickerMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = range 帶持續選中(before:bg-neutral-selected,本檔自有);'active' 移除 — 全檔無按壓
+  // 視覺(data-active-end 是定位 attr 非按壓 token;2026-07-07 詞彙統一 DS-wide 交叉掃補修)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: [],
+    bg: ['bg-neutral-selected'],
     fg: ['text-fg-disabled', 'text-fg-muted'],
     ring: [],
   },

package/src/components/DescriptionList/description-list.spec.md

@@ -194,7 +194,7 @@ DescriptionList 是**唯讀 label / value 資料呈現**(非互動 / 非 variant
 
 ## 邊界案例
 
-- **Disabled(action cell)**:DescriptionList 主體為唯讀資料呈現,本身無 disabled state;若 `<dd>` 內 consumer 嵌入 inline action(Button / Link),該 action 自行 own disabled,DL 不干預(token 走 Button SSOT)。
+- **Disabled(action cell)**:DescriptionList 主體為唯讀資料呈現,本身無 disabled state。**dd 內互動內容 canonical(2026-07-04 Q9 拍板,三處立場收斂)**:操作型互動(Button / Input)**禁止**(見「禁止事項」— 需要動作 → Field read-only / inline-edit / action row / 卡片 header action);展示 / 導覽型 ReactNode(Tag / Badge / **Link**)**允許**,Link 自行 own disabled,DL 不干預。對齊 Polaris(ReactNode 型別 + 純敘述範例)/ Ant(action 放 extra 不放 dd)/ Carbon(read-only default)三家共識。
 - **Loading**:DL 非 async surface,無 loading prop。若 page-level data 載入中,consumer 應在 DL 外層用 `<Skeleton>`(每組 dt/dd 對應一條 skeleton line)取代;DL 本體不渲染 loading state。
 - **Empty(no items / empty value)**:no items → consumer 應 conditional 渲 `<Empty>` 取代 DL,不渲空 `<dl>`(SR 會讀「empty list」造成混淆);individual value 空 → consumer 應自行傳入 `—`(em dash,包 `text-fg-muted`;元件不自動 normalize,已在「無障礙」段 codify)。
 - **長 label / 長值**:horizontal 模式 label(`dt`)`shrink-0` 不收縮、不截斷,value(`dd`)`break-all min-w-0` 斷行吸收擠壓;vertical 模式兩者佔滿欄寬自然換行。無空白長字串(URL / ID)詳「無障礙」段「長值換行」。

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

@@ -112,7 +112,9 @@ const DescriptionItem = React.forwardRef<HTMLDivElement, DescriptionItemProps>(
     return (
       <div ref={ref} className={cn('flex flex-col', className)} {...props}>
         <dt className="text-body text-fg-secondary">{label}</dt>
-        <dd className="text-body mt-[var(--item-gap-label-desc-reading)]">{children}</dd>
+        {/* text-foreground 顯式宣告(2026-07-05 fix):與 horizontal 分支一致,不靠容器繼承 —
+            spec Typography 段 / tsx docblock / anatomy Overview 三處 canonical 皆宣稱 dd = text-foreground */}
+        <dd className="text-body text-foreground mt-[var(--item-gap-label-desc-reading)]">{children}</dd>
       </div>
     )
   },

package/src/components/Dialog/dialog.spec.md

@@ -103,7 +103,7 @@ Modal 與 viewport 四邊保持 `--layout-space-bottom`（48px）最小間距。
 - Header 只有 title + close X → max layout = 24 → header = 24 + 2×`py-tight`(隨 page:md 12 / lg 16)= **48 md / 56 lg**(= `--chrome-header-height` 同 tier 對齊)✓
 - Header 塞 bounded primary(無 `data-unbounded`)→ header 自然長高
 
-**Canonical 來源**:Dialog 是 overlay chrome，corner close X 屬 action group region，必用 Button(非 Inline Action / 非自刻 button)。詳見 `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss canonical」+ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
+**Canonical 來源**:Dialog 是 overlay chrome，corner close X 屬 action group region，必用 Button(非 Inline Action / 非自刻 button)。詳見 `patterns/element-anatomy/inline-action.spec.md`「Dismiss canonical — X close only」+ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
 
 ## Title
 

package/src/components/Dialog/dialog.tsx

@@ -244,7 +244,8 @@ export const dialogMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 2026-07-04 audit 對齊:容器無 hover/active/disabled 態(spec「狀態處理的職責邊界」明文;對齊 popover meta 已修 pattern)
+  states: ['default'],
   tokens: {
     bg: ['bg-surface-raised'],
     fg: ['text-fg-secondary'],

package/src/components/DropdownMenu/dropdown-menu.anatomy.stories.tsx

@@ -253,6 +253,7 @@ export const Overview = {
                 ['SubTrigger', 'badge', 'ReactNode', '—', '子選單狀態 badge'],
                 ['CheckboxItem', 'checked', 'boolean', '—', '勾選狀態'],
                 ['CheckboxItem', 'startIcon', 'LucideIcon', '—', '左側 icon'],
+                ['CheckboxItem', 'description', 'ReactNode', '—', '次要說明文字'],
               ].map(([comp, p, t, d, desc], i) => (
                 <tr key={i}><Td>{comp}</Td><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
               ))}
@@ -647,7 +648,8 @@ export const ColorMatrix = {
                 ['suffix icon (direction)', '--fg-muted', 'ChevronRight, ExternalLink — via endIcon prop'],
                 ['suffix value text', '--fg-muted', '"深色", "已啟用"'],
                 ['shortcut text', '--fg-muted', '⌘C, ⌘E — via shortcut prop'],
-                ['all icons (disabled)', '--fg-disabled', 'unified'],
+                ['prefix icon / label (disabled)', '--fg-disabled', 'startIcon 與 label 同步切 disabled'],
+                ['suffix icon / shortcut (disabled)', '--fg-muted', '容器套 opacity-disabled 減淡,非 fg-disabled(menu-item.spec.md「狀態」)'],
               ].map(([role, token, ex], i) => (
                 <tr key={i}>
                   <Td>{role}</Td>

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

@@ -162,12 +162,14 @@ SubContent 使用相同規格，包括 sideOffset。
 
 透過 `DropdownMenuContent` 的 `size` prop 設定，經 SizeContext 向下傳遞，所有子項目自動套用。
 
-| Size | Label | Icon | Checkbox/Radio 控件 |
+| Size | Label | Icon | Checkbox 控件 |
 |---|---|---|---|
 | sm | `text-body leading-compact` (14px, 1.3) | 16px | 16px |
 | md | `text-body leading-compact` (14px, 1.3) | 16px | 16px |
 | lg | `text-body-lg leading-compact` (16px, 1.3) | 20px | 20px |
 
+RadioItem 不渲染 radio 控件——選中以 `bg-neutral-selected` 背景高亮(見 `../Menu/menu-item.spec.md`「選中指示器」),故控件尺寸欄僅適用 CheckboxItem。
+
 DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使用 `leading-compact`。
 
 ---
@@ -180,7 +182,7 @@ DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使
 |---|---|
 | `↑` `↓` | 移動焦點 |
 | `Home` / `End` | 跳到第一／最後一個 item（`PageUp` / `PageDown` 同） |
-| 首字 typeahead | 打字元自動跳到符合的 item |
+| 首字 typeahead | 打字元自動跳到 **label 符合**的 item——children 為字串時元件自動 forward `textValue`,description / badge / shortcut 不進比對;複雜 children(非純字串)由 consumer 顯式給 `textValue` |
 | `Enter` / `Space` | 執行目前焦點的動作 |
 | `Escape` | 關閉整個選單（含所有展開子層；Radix root close）。逐層收合用 `←` |
 | `→` | 展開子選單 |
@@ -207,7 +209,7 @@ DropdownMenu 是掃描模式——使用者快速瀏覽選項，所有尺寸使
 
 ## StateBehavior(DropdownMenu 層級特有)
 
-Item-level default / hover / focused / selected / disabled **色彩**由 MenuItem primitive SSOT 擁有(`patterns/element-anatomy/item-anatomy.spec.md`「選擇 / 狀態視覺規則」),在本元件 `ColorMatrix` story 承載並直接引用 MenuItem token。DropdownMenu 的 `StateBehavior` story 展示**浮層層級特有的動態行為**:open / close 動畫(Radix `data-state` 驅動)、Submenu 展開 / 收起、CheckboxItem toggle(多選不 close)——這些是 item primitive 沒有的維度。
+Item-level default / hover / focused / selected / disabled **色彩**由 MenuItem primitive SSOT 擁有(`patterns/element-anatomy/item-anatomy.spec.md`「選擇 / 狀態視覺規則」),在本元件 `ColorMatrix` story 承載並直接引用 MenuItem token。**selected × highlighted 疊加(2026-07-04 Q2 拍板)**:selected bg 勝 Radix `data-[highlighted]`(hover + keyboard cursor)— 對齊 MenuItem「selected 勝 hover」canonical(menu-item.spec.md 狀態表),`selected && 'data-[highlighted]:bg-neutral-selected'` override;CheckboxItem/RadioItem checked 同規則。DropdownMenu 的 `StateBehavior` story 展示**浮層層級特有的動態行為**:open / close 動畫(Radix `data-state` 驅動)、Submenu 展開 / 收起、CheckboxItem toggle(多選不 close)——這些是 item primitive 沒有的維度。
 
 ---
 
@@ -218,6 +220,7 @@ Item-level default / hover / focused / selected / disabled **色彩**由 MenuIte
 - **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 繼承 page(不鎖;DropdownMenu item 高度 = field-height-{size} 隨 page density 變,鎖 md 會釘死 md-scale 對不上 lg 觸發點),SSOT 見 `tokens/density/density.spec.md`。
+- **大量 item(> 100)**:建議上游分頁 / 搜尋收斂或考慮 windowing(對齊 Ant Select / MUI Autocomplete 慣例);本元件無虛擬化——action menu 本不該長到這個量級,超過先重想資訊架構(選值場景改用 SelectMenu 系 + searchable)。
 
 ---
 
@@ -237,11 +240,11 @@ Item-level default / hover / focused / selected / disabled **色彩**由 MenuIte
 - Tab — focus trigger
 - Enter / Space / ↓ — 開啟
 - ↑/↓ — 導覽 items（Home/End 跳首尾項，PageUp/PageDown 同）
-- 首字 typeahead — 打字元自動跳到符合的 item
+- 首字 typeahead — 打字元自動跳到 label 符合的 item(比對 `textValue`,見「鍵盤操作」表)
 - Enter / Space — 選擇目前焦點的選項
 - Esc — 關閉
 
-**Focus**:Radix primitive 自管 focus trap / restoration。鍵盤導覽到的項目以 highlight **底色**標示(Radix `data-[highlighted]:bg-neutral-hover`,本元件刻意採 `data-highlighted` 而非 `:focus-visible` outline ring,跨瀏覽器一致 — 見 dropdown-menu.tsx docblock「Hover / highlight canonical」),不畫 `outline: 2px solid var(--ring)` 外框。
+**Focus**:Radix primitive 自管 focus trap / restoration。鍵盤導覽到的項目以 highlight **底色**標示(Radix `data-[highlighted]:bg-neutral-hover`,本元件刻意採 `data-highlighted` 而非 `:focus-visible` outline ring,跨瀏覽器一致 — 見 dropdown-menu.tsx docblock「Hover / highlight canonical」),不畫 `outline: 2px solid var(--ring)` 外框。**Trigger focus 指示**:非 asChild 裸用的 Trigger 顯示 Button focus canonical ring(`focus-visible:ring-2 ring-ring ring-offset-1`,SSOT = button.tsx);asChild 場景由子元件(通常 Button)自帶同款 ring。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 

package/src/components/DropdownMenu/dropdown-menu.tsx

@@ -71,7 +71,13 @@ const DropdownMenuTrigger = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <DropdownMenuPrimitive.Trigger
     ref={ref}
-    className={cn('outline-none', className)}
+    // 2026-07-05:非 asChild 裸用需可見 focus 指示(WCAG 2.4.7)——原 `outline-none` 讓裸 Trigger
+    // 完全無 focus ring。消費 Button focus canonical(button.tsx buttonVariants base)。
+    // asChild+Button 場景同名 class 重複,無影響。
+    className={cn(
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+      className,
+    )}
     {...props}
   />
 ))
@@ -243,9 +249,20 @@ const DropdownMenuItem = React.forwardRef<
     <DropdownMenuPrimitive.Item
       ref={ref}
       disabled={disabled}
+      // 2026-07-05:typeahead 只比對 label——children 為字串時 auto-forward textValue,避免 Radix
+      // fallback 拿整段 textContent(label+description+badge+shortcut 串接)比對。consumer 顯式
+      // textValue 在 {...props} 較後 spread,仍優先。
+      textValue={typeof children === 'string' ? children : undefined}
       className={cn(
         radixItemClass,
-        selected && 'bg-neutral-selected',
+        // 2026-07-04 Q2 拍板:selected bg 勝 hover/highlighted(bg 是唯一選中指示器,被 hover 洗掉
+        // = 選中資訊消失)。對齊 MenuItem(menu-item.tsx selected 時關 hover bg)+ Ant Menu
+        // `:not(-item-selected)` + VS Code list `:hover:not(.selected)`;Radix highlighted 同時是
+        // keyboard cursor,selected 項停留時維持 selected bg(DS bg 通道單一職責)。
+        // 2026-07-05 D4 補完 Q2 附帶條件:selected×highlighted(鍵盤 cursor 停留)用加深一階
+        // bg-neutral-selected-active(neutral-3;M23 nearest canonical = Button toggle active 同
+        // family)— 深化而非洗掉 selection,cursor 可感知(WCAG 2.4.7),對齊 MUI selectedOpacity+hover idiom。
+        selected && 'bg-neutral-selected data-[highlighted]:bg-neutral-selected-active',
         className,
       )}
       {...props}
@@ -300,6 +317,8 @@ const DropdownMenuSubTrigger = React.forwardRef<
   return (
     <DropdownMenuPrimitive.SubTrigger
       ref={ref}
+      // 2026-07-05:同 DropdownMenuItem——typeahead 只比對 label(endContent 的 value/badge 不進比對)。
+      textValue={typeof children === 'string' ? children : undefined}
       className={cn(
         radixItemClass,
         'data-[state=open]:bg-neutral-hover',
@@ -342,6 +361,8 @@ const DropdownMenuCheckboxItem = React.forwardRef<
       ref={ref}
       checked={checked}
       disabled={disabled}
+      // 2026-07-05:同 DropdownMenuItem——typeahead 只比對 label(M10 同 pattern:帶 description)。
+      textValue={typeof children === 'string' ? children : undefined}
       onSelect={(e) => e.preventDefault()}
       className={cn(radixItemClass, className)}
       {...props}
@@ -421,11 +442,14 @@ const DropdownMenuRadioItem = React.forwardRef<
     <DropdownMenuPrimitive.RadioItem
       ref={ref}
       disabled={disabled}
+      // 2026-07-05:同 DropdownMenuItem——typeahead 只比對 label(M10 同 pattern:帶 description)。
+      textValue={typeof children === 'string' ? children : undefined}
       onSelect={(e) => e.preventDefault()}
       // 2026-05-31 #10:selected 底色套在外層 Radix RadioItem 本身(非 `[&>*]` 子 MenuItem),
       // 因內層 MenuItem 自帶 `!bg-transparent` 會蓋掉子層 bg → 選中底色從不顯示。
       // 改 parent-bg pattern(對齊 DropdownMenuItem selected):RadioItem 上底色,MenuItem 透明讓它透出。
-      className={cn(radixItemClass, 'data-[state=checked]:bg-neutral-selected', className)}
+      // 2026-07-04 Q2:checked 亦勝 highlighted(同 DropdownMenuItem selected 規則)
+      className={cn(radixItemClass, 'data-[state=checked]:bg-neutral-selected data-[state=checked]:data-[highlighted]:bg-neutral-selected-active', className)}
       {...props}
     >
       <MenuItem
@@ -461,18 +485,20 @@ DropdownMenuShortcut.displayName = 'DropdownMenuShortcut'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const dropdownMenuMeta = {
   component: 'DropdownMenu',
-  family: null, // non-family composite / overlay / layout
+  family: 1, // 對齊 dropdown-menu.spec.md frontmatter L3(Family 1 消費者;DS 慣例 = meta 對齊 spec frontmatter,原 null 是 Phase 1 boilerplate 殘留)
   variants: {
 
   },
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = 單選/checked item 持續選中(bg-neutral-selected);'active' 保留 — highlight-on-selected
+  // 走 bg-neutral-selected-active(active 階 token,M23 nearest canonical;2026-07-07 詞彙統一補修)。
+  states: ['default', 'hover', 'active', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-surface-raised', 'bg-transparent'],
+    bg: ['bg-neutral-hover', 'bg-neutral-selected', 'bg-neutral-selected-active', 'bg-surface-raised', 'bg-transparent'],
     fg: ['text-fg-disabled', 'text-fg-muted'],
-    ring: [],
+    ring: ['ring-ring'], // 2026-07-05:Trigger focus canonical ring(對齊 Checkbox/Tabs 等 meta 慣例)
   },
 } as const
 

package/src/components/Empty/empty.anatomy.stories.tsx

@@ -81,7 +81,7 @@ export const Overview: Story = {
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
               {[
-                ['icon', 'LucideIcon', '—', 'Avatar 48px 內的 icon'],
+                ['icon', 'LucideIcon | ReactElement', '—', 'LucideIcon 自動包 Avatar 48px;ReactElement 原樣渲染(自訂 Avatar / img / CircularProgress)'],
                 ['title', 'string', '—', '主要標題(16px medium)'],
                 ['description', 'string', '必填(預設唯一 slot)', '說明文字(14px;lg RowSizeContext 子樹內 16px · fg-secondary)'],
                 ['action', 'ReactNode', '—', 'CTA button / 操作區'],

package/src/components/Empty/empty.spec.md

@@ -32,6 +32,7 @@ benchmark:
 - **SelectMenu / Combobox 下拉空**：「無選項」「找不到符合的項目」
 - **Page section 無內容**：dashboard widget 暫無資料、設定頁未建立任何項目
 - **初次引導**：讓使用者首次使用時知道「這裡會放什麼」+ 有 CTA 建立
+- **容器級無權限提示**（2026-07-04 Q7 拍板）：卡片 / 區塊 / 面板內容因權限不可見 — **必附 request-access 類 action**（對齊 Atlassian「Request access」empty state 官方範例 + Carbon error-management scenario）；整頁級 403 / 404 仍禁用（→ 專屬錯誤頁面，見「何時不用」）
 
 ## 何時不用
 
@@ -113,7 +114,7 @@ Empty 是 **non-interactive layout primitive**——本身無 ARIA role(讓 cons
 | Page section 暫無內容 | `<section aria-labelledby={titleId}>` + `<h2>` 包 title slot | 對齊 WCAG 2.1 SC 2.4.6 標題明確語意 |
 | 初次引導(有 CTA) | Action Button 自帶 a11y;無需 Empty 層額外 ARIA | CTA 是真實互動 element,自己的 a11y 足夠 |
 
-**Title slot heading level**:Empty 不渲染 heading tag(`<h1>` / `<h2>`),只 `<div>` + 視覺 typography。Consumer 若需 heading semantic,在外層自包 `<h2>{title}</h2>` + 不傳 Empty 的 title prop(避免重複)。
+**Title slot heading level**:Empty 不渲染 heading tag(`<h1>` / `<h2>`),只 `<span>` + 視覺 typography。Consumer 若需 heading semantic,在外層自包 `<h2>{title}</h2>` + 不傳 Empty 的 title prop(避免重複)。
 
 **Icon slot**:LucideIcon 自動渲染 `aria-hidden="true"`(decorative);ReactElement(自帶 Avatar / Illustration)由 consumer 控制 `aria-hidden` / `alt`(若是 `<img>` 必傳 `alt=""` 表示 decorative)。
 
@@ -210,7 +211,6 @@ Empty 是 **pure layout primitive**(排列 icon / title / description / action
 - `file-upload.spec.md`
 - `file-viewer.spec.md`
 - `select-menu.spec.md`
-- `select.spec.md`
 - `sheet.spec.md`
 - `skeleton.spec.md`
 - `tree-view.spec.md`

package/src/components/Empty/empty.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react'
-import { SearchX, WifiOff, Lock, Inbox } from 'lucide-react'
+import { SearchX, Lock, Inbox } from 'lucide-react'
 import { Empty } from './empty'
 import { Button } from '@/design-system/components/Button/button'
 
@@ -49,20 +49,9 @@ export const NoTasks: Story = {
   ),
 }
 
-/* ── 錯誤無法載入(action-oriented)────────────────────────────────── */
-export const LoadFailure: Story = {
-  name: '錯誤無法載入',
-  render: () => (
-    <div className="border border-border rounded-lg p-8 max-w-md">
-      <Empty
-        icon={WifiOff}
-        title="連線中斷,無法載入資料"
-        description="請檢查網路連線後重試"
-        action={<Button variant="secondary">重新載入</Button>}
-      />
-    </div>
-  ),
-}
+// Retired 2026-07-04 audit(Q 拍板):原 LoadFailure story 正面示範 spec 明文禁止的 error-state
+// 用法(empty.spec.md「何時不用」+ 禁止事項「錯誤/失敗狀態 → 改用 Alert」)— showcase 不得把
+// 反例當正例教。錯誤示範保留在 principles 的 ❌ 反例(empty.principles.stories.tsx)。
 
 /* ── 權限不足 ─────────────────────────────────────────────────────── */
 export const NoPermission: Story = {

package/src/components/Empty/empty.tsx

@@ -50,7 +50,10 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
     let iconElement: React.ReactNode = null
     if (icon) {
       if (React.isValidElement(icon)) {
-        iconElement = icon
+        // disabled:自訂 element 同樣變淡(2026-07-07 補漏 — docblock/spec 無條件宣稱「icon glyph →
+        // fg-disabled」但原僅 LucideIcon 分支生效)。`contents` wrapper 不進 layout,[&_svg] token swap
+        // 只染 svg 系自訂 icon;非 svg(img 照片)不強制染色。
+        iconElement = disabled ? <span className="contents [&_svg]:!text-fg-disabled">{icon}</span> : icon
       } else {
         const Icon = icon as LucideIcon
         // disabled:glyph → fg-disabled([&_svg]:!… 蓋過 Avatar 內聯 color;circle bg 維持 muted)。icon 是文字一環,隨 disabled 變淡。

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

@@ -267,7 +267,7 @@ tagPadding 只在有 Tag 時才套用。Placeholder/空值狀態使用 fieldWrap
 
 Field 內部用 `<ItemInlineAction>`(`patterns/element-anatomy/item-anatomy.tsx` 共用元件)渲染 — 跟 Sidebar / TreeView / DropdownMenu 的 inline action **完全同一套** canonical 實作,不再有「每個 host 自己複製 18 行 button JSX」的漂移。
 
-- 共用規則見 `patterns/element-anatomy/item-anatomy.spec.md`「Inline Action 設計規格」節
+- 共用規則見 `patterns/element-anatomy/inline-action.spec.md`(canonical SSOT,2026-04-24 自 item-anatomy 抽出;Field endAction 屬 neutral host 支)
 - Helper 規格與 API 見 `item-anatomy.spec.md` 的「Inline action 共用元件」節
 - Field host 必須傳 `size={size}` 給 `<ItemInlineAction>`(field 不在 `RowSizeContext` 內,需明確覆寫)
 
@@ -380,3 +380,4 @@ col.accessor('status', {
 - `switch.spec.md`
 - `textarea.spec.md`
 - `time-picker.spec.md`
+- `uiSize.spec.md`

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

@@ -61,6 +61,16 @@ export const fieldWrapperStyles = cva(
         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',
       },
+      // error(2026-07-04 Q1 拍板,SSOT 集中):原散在各控件的 error border classes 因
+      // focus-within:!border-primary(!important)被蓋 = dead code(聚焦永遠藍)。
+      // Benchmark 實查證偽舊宣稱:MUI(紅框加粗)/ Ant(紅框紅 glow)/ Polaris(紅 border
+      // + 獨立藍 focus ring)聚焦時 error 紅皆保留;唯一切藍的 Carbon 靠 in-field 紅 icon 補償。
+      // DS 邊框是唯一 error 載體 → error 勝 focus 的「顏色」通道。錯誤清除(edit-clears-error,
+      // useFormValidation)後自然回 focus 藍。
+      error: {
+        true: '',
+        false: '',
+      },
     },
     // mode x variant 交叉:visual chrome 由 compoundVariants 決定
     //
@@ -90,10 +100,13 @@ export const fieldWrapperStyles = cva(
           // 副作用 — Ant 風「選後藍 / 取消灰」自動達成:
           //   - 選 option close popover → Radix focus return to trigger → focus-within fires → 藍
           //   - 點外取消 close popover → focus 移外 → focus-within 不 fire → 灰
-          'focus-within:!border-primary focus-within:hover:!border-primary',
+          //
+          // 2026-07-04 Q1 拍板修訂:「focus dominates everything」對 error 讓位(見 error variant
+          // 註解)— focus 藍只在 error:false compound(下方),error:true 走 error compound 紅。
           'data-[state=open]:border-border-hover',
         ],
       },
+      { mode: 'edit', variant: 'default', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },
       {
         mode: 'display',
         variant: 'default',
@@ -125,10 +138,17 @@ export const fieldWrapperStyles = cva(
           'bg-transparent border border-transparent',
           'hover:border-border',
           // 同 default chrome v13.3 SSOT:focus-within !important 強制勝過 data-state
-          'focus-within:!border-primary focus-within:hover:!border-primary',
+          //(2026-07-04 Q1:同 default,focus 藍移到 error:false compound)
           'data-[state=open]:border-border',
         ],
       },
+      { mode: 'edit', variant: 'bare', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },
+      // error chrome(mode=edit 限定,variant 不分 — naked cell 內 error 同樣紅框,保留既有控件層行為):
+      {
+        mode: 'edit',
+        error: true,
+        className: 'border-error hover:border-error-hover focus-within:!border-error focus-within:hover:!border-error',
+      },
       {
         mode: 'display',
         variant: 'bare',
@@ -173,12 +193,13 @@ export const fieldWrapperStyles = cva(
           '!px-[var(--table-cell-px)] !py-[var(--table-cell-py)]',
           'border border-border',
           'hover:border-border-hover',
-          // v13.3 SSOT canonical:focus-within !important(同 default + bare)
-          'focus-within:!border-primary focus-within:hover:!border-primary',
+          // v13.3 SSOT canonical:focus-within !important(同 default + bare;
+          // 2026-07-04 Q1:focus 藍移到 error:false compound,error:true 走共用 error compound)
           'data-[state=open]:border-border-hover',
           'group-data-[row-mode=auto]/cell:!items-start',
         ],
       },
+      { mode: 'edit', variant: 'naked', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },
       {
         // 2026-05-12 fix v2(M32 root invariant audit):
         //   Q1 root invariant?:cell-as-input display 視覺位置 = `cell.items-{X}` × `Field.height`
@@ -215,8 +236,6 @@ export const fieldWrapperStyles = cva(
         // 移除 `opacity-disabled` blanket — naked wrapper 只負責 substrate(透明 border + 抑制 cursor),
         // 內部 content(text / icon / avatar)各自 disabled context 處理(text-fg-disabled / Avatar opacity 等具體 token)。
         // 對齊 DataTable cell-disabled TD 加 `bg-disabled` 表達 cell-level disabled state 的 SSOT 分權。
-        // **default/bare disabled variant(line 107, 135)deferred R3.5** — 仍依賴 wrapper opacity-disabled
-        // for Avatar dim(Avatar 尚未 fieldCtx-aware self-dim);Avatar self-dim 實作後再連帶移除。
         mode: 'disabled',
         variant: 'naked',
         className: [
@@ -229,6 +248,7 @@ export const fieldWrapperStyles = cva(
       mode: 'edit',
       variant: 'default',
       size: 'md',
+      error: false,
     },
   }
 )
@@ -274,8 +294,8 @@ export const bareInputStyles = [
 //   - Material X-Grid `gridClasses.cell` wrapper 不允許 cell content override alignment
 //   - Notion / Airtable cell content 從 host 繼承,不 hardcode self alignment
 //
-// Hook:`check_naked_row_mode_propagation.sh`(write-time BLOCKER)
-// Audit:design-system-audit Group N M27(periodic batch verify)
+// Hook:`check_field_family_invariants.sh` A.1(原 check_naked_row_mode_propagation.sh 已 folded,write-time BLOCKER)
+// Audit:design-system-audit Group N(periodic batch verify)
 export const nakedCellRowModeAlign = 'group-data-[row-mode=auto]/cell:items-start'
 
 // ── Cell-as-input Display Hover Ring(2026-05-05 v9 — sole remaining ring const)─

package/src/components/Field/field.anatomy.stories.tsx

@@ -151,8 +151,8 @@ export const Inspector: Story = {
       options: ['edit', 'display', 'readonly', 'disabled'],
       description: 'Context 傳給控制元件:edit 可編輯 / display 純展示 / readonly 鎖定但保留輸入外觀 / disabled 停用',
     },
-    required: { control: 'boolean', description: 'label 後加 * + aria-required' },
-    invalid: { control: 'boolean', description: '觸發 error border + FieldError 取代 FieldDescription' },
+    required: { control: 'boolean', description: 'label 文字前加 * + aria-required' },
+    invalid: { control: 'boolean', description: '觸發 error border + aria-invalid;本例以 FieldError 條件替換 FieldDescription(consumer 慣例,非元件行為)' },
     disabled: { control: 'boolean', description: 'Field disabled context 傳給 control' },
     labelWidth: {
       control: 'select',
@@ -264,7 +264,7 @@ export const SizeMatrix: Story = {
     <div className="flex flex-col gap-10">
       <div>
         <H3>三種 Size — 對齊 field-height 系統</H3>
-        <Desc>Field 的 size 透過 context 傳遞給 input-class control(Input / NumberInput / Select / Combobox / DatePicker / TimePicker / PeoplePicker 等,皆經 useResolvedFieldSize 解析),控制其內部高度對齊 `--field-height-*` tier(見 uiSize.spec.md)。Slider / Switch / Checkbox 等 primitive 維持原生尺寸不讀 context size(見 field.spec.md「為什麼 primitive 不自己變高」),其行高節奏改由 Field control-area 的 min-h-field-{'{size}'} 提供——同一 Field 內所有 control 因此自動對齊高度。</Desc>
+        <Desc>Field 的 size 透過 context 傳遞給 input-class control(Input / NumberInput / Select / Combobox / DatePicker / TimePicker / PeoplePicker 等,皆經 useResolvedFieldSize 解析),控制其內部高度對齊 `--field-height-*` tier(見 uiSize.spec.md)。Slider / Switch / Checkbox 等 primitive 的 edit 態維持原生尺寸、不隨 Field size 變高(Switch / Checkbox 仍經 useResolvedFieldSize 解析 size,僅用於 readonly 灰框 chrome;Slider 完全不讀 context size。見 field.spec.md「為什麼 primitive 不自己變高」),其行高節奏改由 Field control-area 的 min-h-field-{'{size}'} 提供——同一 Field 內所有 control 因此自動對齊高度。</Desc>
         <div className="grid grid-cols-3 gap-6">
           {(['sm', 'md', 'lg'] as const).map(size => (
             <div key={size} className="border border-dashed border-divider rounded-md p-4">
@@ -300,7 +300,7 @@ export const StateBehavior: Story = {
   render: () => (
     <div className="flex flex-col gap-10">
       <div>
-        <H3>Required — label 後加 * 星號</H3>
+        <H3>Required — label 前加 * 星號</H3>
         <Desc>Field 的 required 透過 context 傳遞,FieldLabel 自動在文字前加上星號(僅視覺,對讀屏隱藏);aria-required 由內部的輸入控件(如 Input)負責設定。</Desc>
         <div className="border border-dashed border-divider rounded-md p-4 max-w-md">
           <Field required>
@@ -313,7 +313,7 @@ export const StateBehavior: Story = {
 
       <div>
         <H3>Invalid — 觸發 error 視覺 + FieldError 顯示</H3>
-        <Desc>Field invalid 傳 context(觸發 aria-invalid + error border),FieldError 取代 FieldDescription 顯示。</Desc>
+        <Desc>Field invalid 傳 context(觸發 aria-invalid + error border),FieldError 顯示錯誤訊息(若與 FieldDescription 並存則兩者並列渲染;條件替換屬 consumer 慣例,非元件行為)。</Desc>
         <div className="border border-dashed border-divider rounded-md p-4 max-w-md">
           <Field invalid>
             <FieldLabel>Email</FieldLabel>
@@ -406,7 +406,7 @@ export const ColorMatrix: Story = {
               <tr>
                 <Td mono>FieldDescription</Td>
                 <Td><TokenCell token="--fg-secondary" display="fg-secondary" /></Td>
-                <Td>—(隱藏,被 FieldError 取代)</Td>
+                <Td>fg-secondary(不變;元件不自動隱藏——本例以 FieldError 條件替換屬 consumer 慣例)</Td>
                 <Td><TokenCell token="--fg-disabled" display="fg-disabled" /></Td>
               </tr>
               <tr>
@@ -453,7 +453,7 @@ export const ColorMatrix: Story = {
             <Field required>
               <FieldLabel>姓名</FieldLabel>
               <Input placeholder="請輸入姓名" />
-              <FieldDescription>本欄位為必填(label 後有星號 *)</FieldDescription>
+              <FieldDescription>本欄位為必填(label 前有星號 *)</FieldDescription>
             </Field>
           </div>
           <div>

package/src/components/Field/field.principles.stories.tsx

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