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

package/src/components/Tabs/tabs.spec.md

@@ -82,22 +82,11 @@ TabsList ─┬─ TabsTrigger  [startIcon?] [label] [suffix?: badge? + endIcon?
 TabsContent ← 對應被選中的 trigger
 ```
 
-**單個 Trigger 內部**：
-
-```
-[startIcon?]  [label]  [suffix?]
-  ↑            ↑         ↑
-  16/20px      plain     span(gap-1): [badge?] [endIcon?]
-               span
-  │─── gap-2 ────│─── gap-2 ──│
-```
-
-- **Trigger 三層 slot 間 gap-2**（8px），對標 **item-layout pattern** 的橫向 inline 變體
-- **suffix 內 gap-1**（4px），對標 **Button** suffix wrapper（`button.tsx` 的 `<span className="inline-flex items-center gap-1">`）
+**單個 Trigger 內部**：`[startIcon 16/20px] ─gap-2─ [label] ─gap-2─ [suffix span(gap-1): badge? endIcon?]`——slot 間 **gap-2**（8px）對標 **item-layout pattern** 橫向 inline 變體；suffix 內 **gap-1**（4px）對標 **Button** suffix wrapper（`button.tsx` 的 `<span className="inline-flex items-center gap-1">`）
 - `startIcon` 描述 tab 的內容性質（人像 icon 配「成員」、齒輪 icon 配「設定」）
 - `badge` 傳達該 tab 底下的待處理計數（「通知 3」「成員 12」）
 - `endIcon` **純視覺 indicator only**（方向 / 狀態 — ChevronDown 暗示「展開後看到子內容」、Pin / Star 狀態徽記）。**不拼 click 行為** — 點到 endIcon 跟點到 tab body 同效果（切 tab）
-- `inlineAction`（2026-05-21 加）拆分 click target：點到 inlineAction 走它自己的 handler 不切 tab；典型如「『更多 ▾』tab 後綴點開 overflow dropdown 不切 tab」（split-click pattern,對齊 GitHub「Code ▾」/ Linear "Triage..." menu / Atlassian split-tab 共識）
+- `inlineAction`（2026-05-21 加）拆分 click target：點到 inlineAction 走它自己的 handler 不切 tab；典型如「『更多 ▾』tab 後綴點開 overflow dropdown 不切 tab」（split-click pattern,對齊 GitHub「Code ▾」/ Linear "Triage..." menu / Atlassian split-tab 共識）。DOM 上 inlineAction 是 trigger 的 **sibling**（絕對定位在 trigger 以 paddingRight 預留的區域,同 SidebarMenuButton suffixNode canonical）,**非巢狀 button** — Radix trigger 是原生 `<button>`,巢 button 為 HTML 不合法 + axe nested-interactive（2026-07-05 D4 修）
 
 ### 對標對象與故意的偏離
 
@@ -116,7 +105,7 @@ Tabs trigger = **item-layout 橫向變體 + Button 高度系統**。對標 item-
 
 **Tabs 目前只有一種視覺**：底線標示型（underline indicator）。
 
-選中 trigger 底部有 2px 的 `bg-primary-hover` 底線，未選 trigger 僅文字色變化。未來若需要「填色型」或「pill 型」tabs，應先評估是否真的是 Tabs 的語意（通常是 SegmentedControl 或 Button group 的偽裝）再考慮擴充。
+選中 trigger 底部有 2px 的 `bg-primary` 底線（2026-07-06 拍板：持續選中站 base），未選 trigger 僅文字色變化。未來若需要「填色型」或「pill 型」tabs，應先評估是否真的是 Tabs 的語意（通常是 SegmentedControl 或 Button group 的偽裝）再考慮擴充。
 
 ---
 
@@ -191,17 +180,11 @@ Tabs 是 **navigation anchor**，不是 compact control：
 
 ## Underline 與 TabsList border 的視覺關係
 
-TabsList 底部有 1px gray border（`border-divider`，neutral-4），selected trigger 有 2px primary-hover 底線。**這兩條線視覺上必須是同一條**——selected 底線從 TabsList 的 gray border 位置「長出來」，不得出現雙線。
+TabsList 底部有 1px gray border（`border-divider`，neutral-4），selected trigger 有 2px primary 底線。**這兩條線視覺上必須是同一條**——selected 底線從 TabsList 的 gray border 位置「長出來」，不得出現雙線。
 
 **原則**：selected 底線必須覆蓋並延伸 TabsList 的 gray border，避免疊線。實作手法（pseudo-element 定位）見 `.tsx`。
 
-**色 token = `--divider`(neutral-4)而非 `--border`(neutral-5)**(2026-05-18 改 per user verbatim「我認為應該把 tabs 的下底線統一改成是 divider 色吧?」+「做」approval):
-- 跟 Dialog / Sheet / Popover / Sidebar header `border-b border-divider` 同色 — chrome separator 一致
-- withTabs scenario 下 tabs underline = chrome separator,色不同會視覺斷裂
-- Selected trigger 2px primary indicator overlay underlying 1px divider 對比仍清楚(primary 比 neutral-4 強得多)
-- 對齊 `color.spec.md`「T-junction connectivity 原則」段 outer-vs-divider 判準的「T-junction seamless」直覺(tabs underline 跟 header separator T 字交接)
-
-在 Dialog / Sidebar header 內特別重要——header 的 `border-b` 和 Tabs 的 `border-b` 必須感知為同一條水平線。
+**色 token = `--divider`(neutral-4)而非 `--border`(neutral-5)**(2026-05-18 改 per user verbatim「我認為應該把 tabs 的下底線統一改成是 divider 色吧?」+「做」approval):跟 Dialog / Sheet / Popover / Sidebar header `border-b border-divider` 同色——chrome separator 一致,withTabs scenario 下 underline = chrome separator,色不同會視覺斷裂;selected trigger 2px primary indicator overlay 1px divider 對比仍清楚;對齊 `color.spec.md`「T-junction connectivity 原則」(tabs underline 跟 header separator T 字交接)。在 Dialog / Sidebar header 內特別重要——header 的 `border-b` 和 Tabs 的 `border-b` 必須感知為同一條水平線。
 
 ---
 
@@ -209,13 +192,9 @@ TabsList 底部有 1px gray border（`border-divider`，neutral-4），selected
 
 Tabs 常與容器 header 的底邊 border 合併——**視覺上只有一條線**,不是 header border + tabs border 疊兩條。
 
-**做法**:Tabs 的 `TabsList` 底部 border 與 header 的 `border-b` 實際上是**同一條線**(設計上重疊、實作上不重複渲染)。**Header 退讓**(移除自己 `border-b`),**Tabs 接管**(自身 `border-b border-divider` per `TABS_LIST_BASE`,2026-05-18 fd843c25 統一 chrome separator 色)。三種 overflow mode 的 TabsList 一律跨滿父容器(none 模式 `w-full`;scroll / menu 模式 inner list `min-w-full` 保留溢出成長,見 L184;`TABS_LIST_BASE` + `overflow-y-hidden` 阻 y auto-promote,2026-05-19 c359c711 border owner 升 list 內部);chrome header 內的全寬 paint 由 `ChromeHeader` tabsSlot wrapper 以 `[&>[role=tablist]]:w-full` 強制(見 `header-canonical.spec.md`)。
+**做法**:Tabs 的 `TabsList` 底部 border 與 header 的 `border-b` 實際上是**同一條線**(設計上重疊、實作上不重複渲染)。**Header 退讓**(移除自己 `border-b`),**Tabs 接管**(自身 `border-b border-divider` per `TABS_LIST_BASE`,2026-05-18 fd843c25 統一 chrome separator 色)。三種 overflow mode 的 TabsList 一律跨滿父容器(none 模式 `w-full`;scroll / menu 模式 inner list `min-w-full` 保留溢出成長,見「寬度行為」段;`TABS_LIST_BASE` + `overflow-y-hidden` 阻 y auto-promote,2026-05-19 c359c711 border owner 升 list 內部);chrome header 內的全寬 paint 由 `ChromeHeader` tabsSlot wrapper 以 `[&>[role=tablist]]:w-full` 強制(見 `header-canonical.spec.md`)。
 
-**世界級對照(verbatim cite)**:
-- **GitHub Primer PageHeader**:「`hasBorder` defaults true,**but border NOT rendered if Navigation child contains UnderlineNav**;UnderlineNav itself provides bottom border」(`primer.style/components/page-header/react`)
-- **Ant Design Tabs**:line type 自帶 bottom border(`ant.design/components/tabs`)
-- **Mantine Tabs**:default variant 自包 bottom border(`mantine.dev/core/tabs/`)
-- **Counter-pattern(reject)**:Material UI 走「container 畫 border + tabs 不畫」(`<Box sx={{ borderBottom: 1 }}><Tabs>...</Tabs></Box>` 從 `mui.com/material-ui/react-tabs/`)— 本 DS reject,理由:tabs underline 需 1px gray base line(`tabs.spec.md:185-187`),tabs 不畫 border 會讓 2px primary indicator 浮空失去 base
+**世界級對照(verbatim cite)**:GitHub Primer PageHeader「`hasBorder` defaults true,**but border NOT rendered if Navigation child contains UnderlineNav**;UnderlineNav itself provides bottom border」(`primer.style/components/page-header/react`);Ant Tabs line type 自帶 bottom border(`ant.design/components/tabs`);Mantine Tabs default variant 自包 bottom border(`mantine.dev/core/tabs/`)。**Counter-pattern(reject)**:Material UI 走「container 畫 border + tabs 不畫」(`<Box sx={{ borderBottom: 1 }}><Tabs>` 從 `mui.com/material-ui/react-tabs/`)——本 DS reject,理由:tabs underline 需 1px gray base line(見「Underline 與 TabsList border 的視覺關係」段),tabs 不畫 border 會讓 2px primary indicator 浮空失去 base
 
 **Auto-suppress 機制(Phase 2 production code 提案)**:header primitive 加 `withTabs?: boolean` prop → true 時自動移除自身 `border-b`,免 consumer 手動忘記。對齊 GitHub Primer 的 auto-suppress 模式(免 consumer 手動 prop)。完整 cross-header canonical 詳 `patterns/header-canonical/header-canonical.spec.md` W1。
 
@@ -227,27 +206,14 @@ Size 建議:overlay / chrome header 內用 `sm`(32/40)— 對應 close X 也是
 
 ## 狀態
 
-### active
-
-選中的 trigger：
-- 文字色 `text-foreground`、`font-medium`
-- 底部 2px 底線 `bg-primary-hover`（對齊 semantic.css：選中狀態的邊框/文字統一用 `--primary-hover`）
-
-未選的 trigger：
-- 文字色 `text-fg-secondary`、一般 weight
-- 無底線
-- hover 時文字色轉 `text-foreground`
-
-### disabled
-
-- 文字色 `text-fg-disabled`
-- 無 hover 色變化、無底線
-- Cursor 變為 `not-allowed`（滑鼠移過明確告知不可點）
-- 不接受鍵盤 focus
-
-### focus-visible
+DS 詞彙 **selected**（持續選中）；Radix DOM attr 為 `data-state="active"`（primitive 命名，不改寫）。
 
-`ring-2 ring-ring ring-offset-1`，與 Button 一致。鍵盤導覽（Radix Tabs 原生支援左右箭頭）由 Radix 處理。
+| State | 視覺 |
+|---|---|
+| selected | `text-foreground` + `font-medium` + 底部 2px `bg-primary` 底線（semantic.css 選中規則；2026-07-06 拍板持續選中站 base，Ant inkBarColor = colorPrimary 同款）|
+| 未選 | `text-fg-secondary`、一般 weight、無底線；hover 時文字色轉 `text-foreground` |
+| disabled | `text-fg-disabled`；無 hover 色變化、無底線；`cursor-not-allowed`；不接受鍵盤 focus |
+| focus-visible | `ring-2 ring-ring ring-offset-1`，與 Button 一致；鍵盤導覽（左右箭頭）由 Radix 原生處理 |
 
 ---
 
@@ -292,6 +258,7 @@ Tabs anatomy 採 DS 標準結構 + 元件特有矩陣:
 - 標準 `SizeMatrix` / `ColorMatrix` / `StateBehavior`(selected / hover / disabled)—— 結構性對照,呈現 underline / selected border 與 TabsList border 的視覺關係(見「Underline 與 TabsList border 的視覺關係」段),單組合 Inspector 無法並列呈現
 - 元件特有 `OverflowMatrix`(scroll / menu / fade 三模式)—— 「tabs 放不下時怎麼處理」是設計決策題,需三方案 side-by-side 同時比較,Inspector 單組合無法呈現
 - `SpacingTokens` —— 間距 token 對照
+- `Accessibility`(`無障礙`)—— Radix tabs a11y 預設摘要 + Keyboard 行為對照(詳「A11y 預設」段)
 
 ---
 

package/src/components/Tabs/tabs.tsx

@@ -42,7 +42,7 @@ import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
  *   slot 間 gap-2，suffix 內 gap-1
  *
  * ── Selected underline ──
- *   使用 ::after 絕對定位在 bottom: -1px，2px primary-hover，
+ *   使用 ::after 絕對定位在 bottom: -1px，2px primary（2026-07-06 拍板:持續選中站 base），
  *   蓋住 TabsList 的 1px gray border（單一視覺線條，不雙線）。
  */
 
@@ -65,6 +65,23 @@ const TabsValueContext = React.createContext<{
   onValueChange?: (value: string) => void
 }>({})
 
+
+// ── getElementRef(Radix Slot idiom;鏡射 chip.tsx 同名 helper — 2026-07-05 M10 同型修)──
+// 讀 child 既有 ref 而不觸發 React 18/19 dev deprecation warning。
+function getElementRef(element: React.ReactElement): React.Ref<HTMLElement> | undefined {
+  let getter = Object.getOwnPropertyDescriptor(element.props, 'ref')?.get
+  let mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+  if (mayWarn) return (element as unknown as { ref?: React.Ref<HTMLElement> }).ref
+  getter = Object.getOwnPropertyDescriptor(element, 'ref')?.get
+  mayWarn = getter && 'isReactWarning' in getter && getter.isReactWarning
+  if (mayWarn) return (element.props as { ref?: React.Ref<HTMLElement> }).ref
+  return (
+    (element.props as { ref?: React.Ref<HTMLElement> }).ref ??
+    (element as unknown as { ref?: React.Ref<HTMLElement> }).ref ??
+    undefined
+  )
+}
+
 const Tabs = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Root>,
   TabsProps
@@ -272,12 +289,21 @@ const MenuTabsList = React.forwardRef<
     [children]
   )
 
-  const enhancedChildren = items.map((child, i) =>
-    React.cloneElement(
+  // 2026-07-05 M10 同型修(Chip MenuChipGroup 同款):原 cloneElement 直接覆寫 child ref,
+  // consumer 自有 ref 被靜默取代 → compose(registerItem + child 原 ref)。
+  const enhancedChildren = items.map((child, i) => {
+    const childRef = getElementRef(child)
+    return React.cloneElement(
       child as React.ReactElement<{ ref?: React.Ref<HTMLElement> }>,
-      { ref: registerItem(i) }
+      {
+        ref: (el: HTMLElement | null) => {
+          registerItem(i)(el)
+          if (typeof childRef === 'function') childRef(el)
+          else if (childRef) (childRef as React.MutableRefObject<HTMLElement | null>).current = el
+        },
+      }
     )
-  )
+  })
 
   // Menu 模式沒有 arrows,但仍套 fade mask (reserveArrowWidth: 0) 軟化內容硬邊
   // code-quality-allow: long-function — helper fn 結構緊密,拆 sub-fn 會跨 fn 傳 state 反而複雜
@@ -365,8 +391,8 @@ const tabsTriggerVariants = cva(
     'transition-colors duration-150',
     'cursor-pointer select-none',
     'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
-    // Trigger 無水平 padding — 寬度 = 內容寬度。triggers 間的分隔靠 TabsList 的 gap-[layout-space-loose]
-    // selected underline：::after 絕對定位在 bottom:-1px，2px primary-hover
+    // Trigger 無水平 padding — 寬度 = 內容寬度。triggers 間的分隔靠 TabsList 的 gap-[var(--layout-space-loose)]
+    // selected underline：::after 絕對定位在 bottom:-1px，2px primary（持續選中 base）
     // left-0/right-0 因為 trigger 已無 padding，底線等於內容寬度
     // 底線蓋住 TabsList 的 1px gray border，視覺單一線條
     'after:absolute after:left-0 after:right-0 after:bottom-[-1px] after:h-0.5',
@@ -375,7 +401,9 @@ const tabsTriggerVariants = cva(
     'hover:text-foreground',
     // selected
     'data-[state=active]:text-foreground data-[state=active]:font-medium',
-    'data-[state=active]:after:bg-primary-hover',
+    // 2026-07-06 user 拍板:選中底線 hover 階 → primary base(持續選中站 base;
+    // Ant inkBarColor = colorPrimary / Material 3 active indicator = primary 同款)
+    'data-[state=active]:after:bg-primary',
     // disabled：cursor-not-allowed + 不吃 hover 色
     // 不用 pointer-events-none，否則 cursor 不會改變；button[disabled] 本身就擋 click
     'disabled:cursor-not-allowed disabled:text-fg-disabled',
@@ -416,8 +444,11 @@ interface TabsTriggerProps
    * Inline action slot(2026-05-21 v3 加,per user「圖一 後綴應該是 inline action」+「點擊
    * 該 tab 的 inline action 跟其他地方應該不同反應」directive):
    * 提供 `<ItemInlineAction>` / `<DropdownMenuTrigger asChild><ItemInlineAction ... /></DropdownMenuTrigger>`
-   * 等獨立 click target。**TabsTrigger 自動 stopPropagation**,inline action 點擊不冒泡到 tab body,
-   * 達成 split-click 行為(對齊 GitHub「Code ▾」/ Linear "Triage..." menu / Atlassian split-tab 共識)。
+   * 等獨立 click target。**DOM 上是 trigger 的 sibling(絕對定位),非巢狀 button**
+   * (2026-07-05 D4 修:Radix TabsTrigger 是原生 `<button>`,巢 button = HTML 不合法 +
+   * axe nested-interactive;同 SidebarMenuButton suffixNode canonical),inline action
+   * 點擊天然不落在 tab body,達成 split-click 行為(對齊 GitHub「Code ▾」/
+   * Linear "Triage..." menu / Atlassian split-tab 共識)。
    *
    * 跟 endIcon 區別:endIcon = 純視覺 indicator(無獨立行為,連同 tab 一起 click),
    * inlineAction = 獨立 click target(自己的 handler,不切 tab)。語意分家明確。
@@ -432,12 +463,23 @@ const TabsTrigger = React.forwardRef<
   const { size } = React.useContext(TabsContext)
   // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
-  const hasSuffix = badge != null || EndIcon !== undefined || inlineAction != null
+  const hasSuffix = badge != null || EndIcon !== undefined
+  // 2026-07-05 D4 修(deep-audit「Tabs:inlineAction slot 造成 button 巢 button」):
+  // Radix TabsTrigger render 原生 <button>,inlineAction(ItemInlineActionButton)也是原生
+  // <button> — 巢狀 interactive = HTML 不合法 + axe nested-interactive(serious)+ tab 的
+  // accessible name 混入 action 內容。改 sibling 佈局(同 SidebarMenuButton suffixNode
+  // canonical,sidebar.tsx):wrapper span(relative)內 trigger + 絕對定位 action;trigger 以
+  // paddingRight 預留 action 空間 — icon 寬 + 原 gap(有 badge/endIcon 時 4px = suffix 內
+  // gap-1;僅 action 時 8px = slot 間 gap-2),幾何與巢狀版一致。click 天然分流(action 不在
+  // trigger 子樹,不冒泡),原 stopPropagation 五連發不再需要。
+  const hasAction = inlineAction != null
+  const actionPaddingRight = hasAction ? iconSize + (hasSuffix ? 4 : 8) : undefined
 
-  return (
+  const trigger = (
     <TabsPrimitive.Trigger
       ref={ref}
       className={cn(tabsTriggerVariants({ size }), className)}
+      style={hasAction ? { paddingRight: actionPaddingRight } : undefined}
       {...props}
     >
       {StartIcon && <StartIcon size={iconSize} aria-hidden />}
@@ -446,30 +488,23 @@ const TabsTrigger = React.forwardRef<
         <span className="inline-flex items-center gap-1">
           {badge}
           {EndIcon && <EndIcon size={iconSize} aria-hidden />}
-          {inlineAction != null && (
-            // 2026-05-21 split-click invariant:inlineAction 點擊不冒泡到 TabsPrimitive.Trigger。
-            // Radix Tabs 在 3 個 channel 觸發 tab 切換,全部 stopPropagation:
-            //   - onMouseDown(primary, Radix Tabs source code main switch trigger)
-            //   - onFocus(activationMode='automatic' default,focus 落內部按鈕也算「focused」)
-            //   - onKeyDown Enter/Space(鍵盤啟動)
-            // 加 onPointerDown / onClick 防禦其他 framework 慣例。
-            // 對齊 GitHub「Code ▾」/ Linear "Triage..." split-tab 共識。
-            <span
-              onPointerDown={(e) => e.stopPropagation()}
-              onMouseDown={(e) => e.stopPropagation()}
-              onClick={(e) => e.stopPropagation()}
-              onFocus={(e) => e.stopPropagation()}
-              onKeyDown={(e) => {
-                if (e.key === 'Enter' || e.key === ' ') e.stopPropagation()
-              }}
-            >
-              {inlineAction}
-            </span>
-          )}
         </span>
       )}
     </TabsPrimitive.Trigger>
   )
+
+  if (!hasAction) return trigger
+
+  return (
+    // sibling 佈局 wrapper:span(relative)內 trigger + 絕對定位 action。
+    // Radix roving focus 用 collection context 收 trigger,不要求 trigger 是 List 直接子層。
+    <span className="relative inline-flex">
+      {trigger}
+      <span className="absolute top-1/2 -translate-y-1/2 right-0 inline-flex items-center">
+        {inlineAction}
+      </span>
+    </span>
+  )
 })
 TabsTrigger.displayName = 'TabsTrigger'
 
@@ -509,9 +544,10 @@ export const tabsMeta = {
     md: { fieldHeight: 40, iconSize: 16, typography: 'body' },
     lg: { fieldHeight: 48, iconSize: 20, typography: 'body-lg' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = 選中 tab(Radix DOM attr 為 data-state="active",meta 詞彙統一用 'selected' 避免與「按壓 active」混用;2026-07-07)
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-primary-hover', 'bg-transparent'],
+    bg: ['bg-primary', 'bg-transparent'],
     fg: ['text-fg-disabled', 'text-fg-secondary', 'text-foreground'],
     ring: ['ring-ring'],
   },

package/src/components/Tag/tag.principles.stories.tsx

@@ -32,7 +32,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>
 )
@@ -261,7 +261,7 @@ export const IconRule: Story = {
 
       <Rule
         title="❌ icon + avatar 同時用(互斥)"
-        note="icon 和 avatar 都是 prefix slot,設計慣例上互斥(由 consumer 自律,非型別強制)。若同時傳,icon 與 avatar 會並列渲染,破壞 Tag 內部結構"
+        note="icon 和 avatar 都是 prefix slot,設計慣例上互斥(非型別強制;dev mode 同時傳會 console.warn 提醒 — 對齊 Button overlayBadge dev-warn 先例)。若同時傳,icon 與 avatar 仍會並列渲染,破壞 Tag 內部結構"
       >
         <Label warn>(範例省略)設計慣例上互斥——同時傳會並列渲染,請只擇一</Label>
       </Rule>

package/src/components/Tag/tag.spec.md

@@ -125,15 +125,11 @@ Tag 是 inline label，用於分類標籤、狀態標記、多選已選值。不
 | `purple` | `--color-purple-*` |
 | `magenta` | `--color-magenta-*` |
 
-所有有色 variant 直接使用 primitive token（`--color-blue-*` 等），不使用 semantic token（`--primary`、`--error`）。Tag 的「blue」代表藍色本身，不代表「主要操作」語義；「red」代表紅色（品牌紅 hue 25），**不代表 `--error`**。
-
-**注意**：`red` 與語意 `--error` 完全無關 —— `--error` = `--color-deep-orange-6`（hue 38），而 `red` variant = `--color-red-*`（品牌紅 hue 25）。三者（`red` / `deep-orange` / `--error`）是各自獨立的色相 / 語意 token，**無映射關係**。2026-06-04 修正原「red variant 接 deep-orange」offset。
+所有有色 variant 直接使用 primitive token（`--color-blue-*` 等），不使用 semantic token（`--primary`、`--error`）。Tag 的「blue」代表藍色本身，不代表「主要操作」語義；`red` = 品牌紅 hue 25，與語意 `--error`（= `--color-deep-orange-6`，hue 38）**完全無關**——`red` / `deep-orange` / `--error` 是各自獨立的色相 / 語意 token，**無映射關係**（2026-06-04 修正原「red variant 接 deep-orange」offset）。
 
 ### 文字色
 
-所有有色 variant 的文字一律使用 primitive step-7（`--color-{hue}-7`），優先辨識度。Primitives 的相對色階公式在 dark mode 自動把 step-7 解析為高對比方向，確保文字在 subtle 底色上始終可讀。Tag 以呈現資訊為主，小面積色塊文字需要更高對比才能舒適閱讀。neutral variant 用 `text-foreground`（不適用此規則）。
-
-見 `color.spec.md` 的「文字色 Step 原則」。
+所有有色 variant 文字一律 primitive step-7（`--color-{hue}-7`）——小面積色塊文字需高對比才可讀，primitives 相對色階公式在 dark mode 自動把 step-7 解析為高對比方向。neutral variant 用 `text-foreground`（不適用此規則）。見 `color.spec.md`「文字色 Step 原則」。
 
 ---
 
@@ -184,24 +180,11 @@ Dismiss 是 Inline Action，但 icon 色繼承 Tag 文字色（非 `fg-muted`）
 
 #### 為什麼 Tag 同時用 primitive（靜態色）和 semantic（互動色）
 
-這是 **有意的職責分離**，非 code smell：
-
-| 概念 | 為什麼住這層 |
-|------|------------|
-| 靜態色（subtle bg、text、solid bg）→ **primitive** | 不需要 mode 翻轉知識——primitives 公式翻轉已自動處理 step-1 alpha、step-7 對比方向 |
-| 互動色（hover、active）→ **semantic `--{hue}-hover/active`** | 需要保證「hover 永遠較亮、active 永遠較暗」，dark mode swap 必須住 semantic 層 |
-
-兩個概念本來就不該綁同一層。Tailwind 也是同樣分離：`bg-blue-500`（靜態 scale step）vs `hover:bg-blue-600 dark:hover:bg-blue-400`（互動需 consumer 處理 mode）。差別只在於我們把 mode swap 封裝進 token，consumer 不需自己寫 dark variant。
-
-詳細流派討論見 `color.spec.md` 的「架構流派定位」段落。
+**有意的職責分離**，非 code smell：靜態色（subtle bg、text、solid bg）住 **primitive**——primitives 公式已自動處理 dark mode 翻轉（step-1 alpha、step-7 對比方向）；互動色（hover、active）住 **semantic `--{hue}-hover/active`**——「hover 永遠較亮、active 永遠較暗」的 mode swap 必須住 semantic 層。Tailwind 同款分離（`bg-blue-500` 靜態 vs `hover:bg-blue-600 dark:hover:bg-blue-400` 互動），差別在我們把 mode swap 封裝進 token，consumer 不需自寫 dark variant。詳細流派討論見 `color.spec.md`「架構流派定位」。
 
 #### `--{hue}-hover/active` 的定位
 
-Semantic 互動 token，從 brand color (`--primary-hover`) 延伸到所有作為 bg 的色相。**刻意只有 hover/active 兩個 token**——base/subtle/text 用 primitive。沒有 `--blue` base 或 `--blue-subtle`，避免重新引入完整 categorical 層。
-
-#### Neutral 例外
-
-neutral solid 的 bg 是 `--color-neutral-9`，在 dark mode 反轉（近黑 → 近白），bg 本身會跨 mode 變色。所以 overlay 不能用 `--{hue}-hover/active`（這些針對「bg 不變」的飽和色），改用 `--inverse-neutral-hover` / `--inverse-neutral-active`（內部處理 mode 鏡射 swap）。
+Semantic 互動 token，從 brand color (`--primary-hover`) 延伸到所有作為 bg 的色相。**刻意只有 hover/active 兩個 token**——base/subtle/text 用 primitive，沒有 `--blue` base 或 `--blue-subtle`，避免重新引入完整 categorical 層。**Neutral 例外**：neutral solid bg = `--color-neutral-9`，dark mode 反轉（近黑 → 近白）bg 本身跨 mode 變色，不能用針對「bg 不變」飽和色的 `--{hue}-hover/active`，改用 `--inverse-neutral-hover` / `--inverse-neutral-active`（內部處理 mode 鏡射 swap）。
 
 Inline Action 的其他規則（尺寸、hover 背景 pattern）不變。
 
@@ -240,27 +223,17 @@ Inline Action 的其他規則（尺寸、hover 背景 pattern）不變。
 | `solid` | `boolean` | 深底配對前景模式（step-6 背景；yellow/amber/orange/lime 用深字，其餘白字），預設 false |
 | `unbounded` | `boolean` | 預設 false = 寬度 cap 160px;true = 寬度交給 parent constrain（cell-as-input narrow cell 場景），詳「邊界案例」 |
 
-## 圓角
-
-統一 `rounded-md`（4px）。
+## 圓角與間距
 
-## Tag 間距
-
-tag 與 tag 之間：`gap-1`（4px）。
-
-## 包含 Tag 的 Field
-
-Field 內包含 Tag 時，Field 的 padding 改為 `(field-height - tag-height) / 2`，確保 tag 四邊等距。
+- 圓角：統一 `rounded-md`（4px）
+- Tag 與 Tag 之間：`gap-1`（4px）
+- Field 內包含 Tag 時，Field 的 padding 改為 `(field-height - tag-height) / 2`，確保 tag 四邊等距
 
 ---
 
 ## Dismiss（Inline Action）
 
-傳入 `onRemove` callback 時，Tag 自動渲染 remove 按鈕。消費端不需要自行建構 remove 按鈕或知道 inline action 的尺寸規格。
-
-尺寸 / 互動規則共用 SSOT 見 `../../patterns/element-anatomy/inline-action.spec.md`(獨立 SSOT,2026-04-24 自 item-anatomy 抽出)。
-
-**Icon 色彩特例（colored host)**：Tag dismiss icon **繼承 Tag 文字色**（非 `fg-muted`）— Tag 屬「colored host」分類。完整兩支規則（neutral host vs colored host）見上述 item-anatomy.spec.md SSOT。詳細每 variant 的 icon 色 + hover 背景見上面「Dismiss 行為（Inline Action 客製）」段。
+傳入 `onRemove` callback 時，Tag 自動渲染 remove 按鈕，消費端不需自行建構或知道 inline action 尺寸規格。尺寸 / 互動規則 SSOT 見 `../../patterns/element-anatomy/inline-action.spec.md`（含 neutral host vs colored host 兩支規則；Tag 屬 colored host——dismiss icon 繼承 Tag 文字色而非 `fg-muted`）；每 variant 的 icon 色 + hover 背景見上「Dismiss 行為（Inline Action 客製）」段。
 
 | Tag size | Icon | Hover 背景 | 上下呼吸空間 |
 |---|---|---|---|
@@ -289,12 +262,7 @@ Field 內包含 Tag 時，Field 的 padding 改為 `(field-height - tag-height)
 
 ## 為何無 StateBehavior
 
-Tag 是**純顯示 indicator**(非互動 — 見「與 Button 的差異」段),本身**無互動狀態**:
-
-- 無 hover / focus / active / selected / disabled——Tag 是 Family 3 indicator variant(非 Pill button)。若要 hover / selected 語意,改用 `Chip`(可互動版本)。
-- 僅有的「行為」是 remove(`onRemove` callback 觸發,Tag 本身不管 remove 動畫),close icon 的 hover 狀態屬 Inline Action pattern(`inline-action.spec.md` 獨立 SSOT),非 Tag 自有。
-
-對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(variant solid/subtle) + `SizeMatrix`。互動狀態 → 改用 Chip(見「與 Button 的差異」段)。
+Tag 是**純顯示 indicator**(Family 3 indicator variant,見「與 Button 的差異」段),無 hover / focus / active / selected / disabled 互動狀態——要互動語意改用 `Chip`。僅有的「行為」是 remove(`onRemove` callback,Tag 不管 remove 動畫),close icon 的 hover 屬 Inline Action pattern(`inline-action.spec.md` SSOT),非 Tag 自有。對應 anatomy story:`Overview` + `Inspector` + `ColorMatrix`(solid/subtle)+ `SizeMatrix`,無 StateBehavior。
 
 ---
 
@@ -304,7 +272,7 @@ Tag 是**純視覺 indicator**(非互動 control,互動版本是 Chip),預設 AR
 
 - **靜態 Tag**(無 `onRemove`):render 為 `<div data-tag-root>`(無 role、`inline-flex`,SR 等價於無語意 generic container,視覺上為 inline-level 跟隨 inline flow)。若 Tag 表達狀態語意(「進行中」「已逾期」),consumer 應在父 region 用 `aria-label` 或視覺 prefix(icon)讓 SR 理解 context
 - **Removable Tag**(`onRemove` 存在):inline X close 走 `<ItemInlineActionButton icon={X} size="md" aria-label="移除 {tagLabel}" />`(item-anatomy SSOT 的原生 `<button>`,非 `Button` 元件)— 對齊 inline-action canonical(`patterns/element-anatomy/inline-action.spec.md`)
-- **Keyboard**:靜態 Tag 不取得 focus(無互動);dismissible 的 X 走原生 button 鍵盤(Tab → focus → Enter/Space → dismiss)
+- **Keyboard**:靜態 Tag 不取得 focus(無互動);**例外:截斷時條件性 `tabIndex=0`**(2026-07-06 拍板)——全文 tooltip 需鍵盤可達,APG Tooltip pattern 原文「popup 在元素收到鍵盤焦點或 hover 時顯示」= trigger 可 focus 是 W3C 官方前提;Radix Tooltip focus-open 自動生效,未截斷不入 tab 序。dismissible 的 X 走原生 button 鍵盤(Tab → focus → Enter/Space → dismiss)
 - **Color-only 語意警告**:Tag 用色相區分狀態時必有文字 label 或 prefix icon(色盲 user 友好);對齊 WCAG 1.4.1「不僅靠顏色傳達」
 - **驗證**:Storybook a11y addon panel 0 critical violation;WCAG AA contrast ≥ 4.5:1(text)/ 3:1(icon)
 

package/src/components/Tag/tag.tsx

@@ -154,6 +154,17 @@ function TagInner(
 
   const label = typeof children === 'string' ? children : ''
 
+  // ── Dev-mode warning:icon 與 avatar 互斥 ──
+  // 兩者同為 prefix slot(tag.spec.md Props 表「與 avatar 互斥」),同時傳會並列渲染破壞 Tag
+  // 內部結構;原僅 jsdoc/spec 約束會靜默通過 → 2026-07-05 對齊 Button overlayBadge dev-warn
+  // 先例(button.tsx「Dev-mode warning」段)補齊家族一致 runtime 防線。
+  if (process.env.NODE_ENV !== 'production' && Icon && avatar) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      '[DS Tag] `icon` 與 `avatar` 互斥(同為 prefix slot),同時傳會並列渲染破壞 Tag 內部結構,請只擇一。SSOT:tag.spec.md Props 表 + tag.principles.stories.tsx IconRule。'
+    )
+  }
+
   const tag = (
     <div
       ref={(el) => {
@@ -162,7 +173,18 @@ function TagInner(
         else if (forwardedRef) (forwardedRef as React.MutableRefObject<HTMLDivElement | null>).current = el
       }}
       data-tag-root=""
-      className={cn(tagVariants({ color, size }), solidClass, 'w-fit min-w-0 overflow-hidden', className)}
+      // 截斷時條件性可 focus(2026-07-06 user 拍板「確認世界級有這樣做就做」——APG Tooltip
+      // pattern 原文:tooltip 在元素「收到鍵盤焦點」或 hover 時顯示,trigger 可 focus 是
+      // W3C 官方 pattern 前提;Radix Tooltip focus-open 自動生效 → 鍵盤 Tab 到即見全文。
+      // 未截斷不入 tab 序(維持 tag.spec「靜態 Tag 不取得 focus」預設,不汙染 tab order)。
+      tabIndex={isTruncated ? 0 : undefined}
+      className={cn(
+        tagVariants({ color, size }),
+        solidClass,
+        'w-fit min-w-0 overflow-hidden',
+        isTruncated && 'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
+        className,
+      )}
       // 2026-05-18 Round 5 fix(per Codex M31 Round 5 verdict + user 拍板「那就開始做」):
       // 用 CSS var `--combobox-tag-area-inline-size`(由 Combobox useOverflowCount JS-injected)取代
       // `min(100%, 10rem)` cyclic percentage。CSS Sizing 3 §5.2.1:percentage 在 indefinite containing
@@ -222,17 +244,21 @@ export const tagMeta = {
     magenta: { purpose: 'categorical 色相(--color-magenta-*)' },
   },
   sizes: {
-    // Tag 尺寸不引用 field-height token（spec.md:180/241——Tag 與 Field 尺寸獨立）。
+    // Tag 尺寸不引用 field-height token（spec「尺寸」段——Tag 與 Field 尺寸獨立;段名指法免行號漂移）。
     // height = Tag 自身高度（cva h-5/h-6/h-6 = 20/24/24，lg = md alias）。
-    // iconSize 全尺寸統一 16（tag.tsx:195 硬寫 size={16}）。
+    // iconSize 全尺寸統一 16（本檔 CAT icon render 硬寫 size={16}）。
     sm: { height: 20, iconSize: 16, typography: 'caption' },
     md: { height: 24, iconSize: 16, typography: 'body' },
     lg: { height: 24, iconSize: 16, typography: 'body' },
   },
-  // Tag 為純展示 indicator，無互動 state（spec.md:249-256「為何無 StateBehavior」）。
+  // Tag 為純展示 indicator，無互動 state（spec「為何無 StateBehavior」段;段名指法免行號漂移）。
   // 唯一行為 dismiss 屬 Inline Action pattern，非 Tag 自有 state。
   states: ['default'],
   tokens: {
+    // 2026-07-04 audit 註記:另有動態色相家族不逐一列 — CAT_SUBTLE 12 色相
+    // bg-[var(--color-{hue}-1)] + step-7 深字、CAT_SOLID step-6 底 + --on-emphasis(-dark) 配字、
+    // neutral solid bg-[var(--color-neutral-9)] — 全由 categorical-color.ts SSOT 衍生
+    //(anatomy TOKEN_MAP 以 stripVar 機械衍生,零漂移)。
     bg: ['bg-neutral-active', 'bg-neutral-hover', 'bg-secondary', 'bg-transparent'],
     fg: ['text-foreground', 'text-inverse-fg'],
     ring: [],

package/src/components/Textarea/textarea.principles.stories.tsx

@@ -4,6 +4,7 @@ import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'
 import { Textarea } from './textarea'
 import { Input } from '@/design-system/components/Input/input'
+import { Button } from '@/design-system/components/Button/button'
 
 const meta: Meta = {
   title: 'Design System/Components/Textarea/設計原則',
@@ -165,7 +166,7 @@ export const NoIconRule: Story = {
         <div className="flex flex-col gap-2">
           <Textarea placeholder="留下你的評論..." rows={3} />
           <div className="flex justify-end">
-            <button className="px-4 py-2 text-body bg-primary text-inverse-fg rounded-md">送出</button>
+            <Button variant="primary" size="sm">送出</Button>
           </div>
         </div>
         <Label>↑ 按鈕在 Textarea 下方,不塞進框內</Label>

package/src/components/Textarea/textarea.spec.md

@@ -71,6 +71,7 @@ Textarea 是**多行文字**的輸入與顯示元件——Input 的多行版本
 
 - **`rows` prop**：預設 `3`，控制初始可見行數
 - **`resize-y`**：使用者可手動拖拉下邊緣垂直 resize
+- **`variant="naked"` 例外**：cell-as-input substrate（DataTable cell）四 mode 一律 `!resize-none` 覆蓋 `resize-y`，並以 `!h-full` 撐滿 cell——cell 內手動 resize 會破壞表格佈局（`textarea.tsx` naked compoundVariants，intentional divergence）
 - **`min-h-*` className**：消費者可透過 Tailwind utility 覆寫最小高度
 - **禁止 `resize: horizontal` 或 `both`**：水平 resize 破壞 form 佈局
 
@@ -87,7 +88,7 @@ sm 與 md 視覺相同（純命名 mapping，對齊 Field family）。
 
 ### 為什麼不完全對齊 `--field-height-*`
 
-- **現況**:Textarea 高度由 `rows` + `resize-y` 決定,**不綁 `--field-height-*`**;`size` 只控字體(sm/md = text-body 14px / lg = text-body-lg 16px)與 padding 風格,**不控高度**
+- **現況**:Textarea 高度由 `rows` + `resize-y` 決定,**不綁 `--field-height-*`**;`size` 只控字體(sm/md = text-body 14px / lg = text-body-lg 16px),**不控高度也不控 padding**(padding 為固定 `px-[var(--field-px)] py-2`,三 size 相同)
 - **Rationale**:Textarea 是**多行輸入**,高度由內容 / rows 決定是本質特徵——若硬綁 field-height 只有單行高度,multi-line 場景無法表達。字體 tier 仍對齊 Field family(sm/md 共 text-body、lg 切 text-body-lg),確保並排單行 Input 的視覺 rhythm 一致
 - **世界級對照**:Ant Design `<Input.TextArea>` rows 決定高度、autoSize object 配置 min/max / Material MUI `<TextField multiline>` 用 minRows/maxRows / Polaris `<TextField multiline>` 同流派——全部 textarea 的 container 高度獨立於 field-height,只繼承字體 / padding / border token <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 

package/src/components/Textarea/textarea.tsx

@@ -62,6 +62,11 @@ const textareaVariants = cva(
         md: 'text-body',
         lg: 'text-body-lg',
       },
+      // error(2026-07-04 Q1,鏡射 fieldWrapperStyles error variant;Phase D 整併時一起收)
+      error: {
+        true: '',
+        false: '',
+      },
     },
     compoundVariants: [
       // default chrome × mode
@@ -71,9 +76,9 @@ const textareaVariants = cva(
         className: [
           'bg-surface border border-border',
           'hover:border-border-hover',
-          'focus-visible:!border-primary focus-visible:hover:!border-primary',
         ],
       },
+      { mode: 'edit', variant: 'default', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },
       {
         mode: 'display',
         variant: 'default',
@@ -98,9 +103,14 @@ const textareaVariants = cva(
         className: [
           'bg-transparent border border-transparent',
           'hover:border-border',
-          'focus-visible:!border-primary focus-visible:hover:!border-primary',
         ],
       },
+      { mode: 'edit', variant: 'bare', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },
+      {
+        mode: 'edit',
+        error: true,
+        className: 'border-error hover:border-error-hover focus-within:!border-error focus-within:hover:!border-error',
+      },
       {
         mode: 'display',
         variant: 'bare',
@@ -111,10 +121,13 @@ const textareaVariants = cva(
         variant: 'bare',
         className: 'bg-transparent border border-transparent',
       },
+      // 2026-07-05 fix(deep-audit A.1b,鏡射下方 naked 2026-05-13 codex V2 fix):移除 bare×disabled
+      //   的 `opacity-disabled` blanket — 同 class 已用具體 `text-fg-disabled` token swap,兩策略同時
+      //   套用違 opacity.spec.md「不可混用」canonical(0.45 × token 疊加 = 過度褪色)。
       {
         mode: 'disabled',
         variant: 'bare',
-        className: 'bg-transparent border border-transparent cursor-not-allowed opacity-disabled text-fg-disabled',
+        className: 'bg-transparent border border-transparent cursor-not-allowed text-fg-disabled',
       },
       // naked chrome × mode — cell-as-input substrate(2026-05-06 v14 revert v12)。
       //   v12 `!absolute -inset-px` autoRowHeight 不相容 → revert v9 baseline + 保留 v13.3
@@ -127,13 +140,13 @@ const textareaVariants = cva(
           '!px-[var(--table-cell-px)] !py-[var(--table-cell-py)]',
           'border border-border',
           'hover:border-border-hover',
-          'focus-visible:!border-primary focus-visible:hover:!border-primary',
           // textarea UA stylesheet 預設 line-height: normal(1.2-1.5 不定),會跟 display
           // `<div>` text-body line-height: 1.5(21px @ 14px)不一致 → cell 進 edit 後 height
           // shift。顯式 leading 對齊 div 行為。
           '!leading-[1.5]',
         ],
       },
+      { mode: 'edit', variant: 'naked', error: false, className: 'focus-visible:!border-primary focus-visible:hover:!border-primary' },
       // 2026-05-13 Q1 R4 verify(per codex Q1 verdict 補 Textarea nuance):
       // Textarea naked display/readonly/disabled 用 `!h-full`,**不**對齊 Field wrapper 的 `!h-auto`。
       // Why divergence:textarea 是 native form element 帶 intrinsic rows-based height,且 cell 內
@@ -150,6 +163,7 @@ const textareaVariants = cva(
       mode: 'edit',
       variant: 'default',
       size: 'md',
+      error: false,
     },
   }
 )
@@ -240,11 +254,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
         data-field-mode={resolvedMode}
         data-error={isEditable && error ? '' : undefined}
         className={cn(
-          textareaVariants({ mode: resolvedMode, variant: variant, size }),
-          isEditable && error && [
-            'border-error hover:border-error-hover',
-            'focus-visible:border-error focus-visible:hover:border-error',
-          ],
+          textareaVariants({ mode: resolvedMode, variant: variant, size, error }),
           className
         )}
         {...props}
@@ -272,7 +282,7 @@ export const textareaMeta = {
   //   text input 無 'active'(按下)視覺態(Material/Polaris/Carbon TextArea 共識)。
   states: ['default', 'hover', 'focus-visible', 'readonly', 'disabled', 'error'],
   tokens: {
-    bg: ['bg-disabled', 'bg-surface'],
+    bg: ['bg-disabled', 'bg-readonly', 'bg-surface'], // 2026-07-04 補:readonly×default cva 實際消費(spec「Readonly 特例」主打 token)
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-foreground'],
     ring: [],
   },

package/src/components/TimePicker/time-picker.anatomy.stories.tsx

@@ -12,7 +12,8 @@ import type { Meta, StoryObj } from '@storybook/react'
 import { TimePicker } from './time-picker'
 
 /**
- * TimePicker 設計規格 — 完整技術規格。anatomy 5-story 最小版本。
+ * TimePicker 設計規格 — 完整技術規格。anatomy 7 story(6-canonical 去 StateBehavior,
+ * 加元件特有 ModeMatrix / PrecisionMatrix;見 spec「為何無 StateBehavior」)。
  * 深度規格見 `time-picker.spec.md`。
  */