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

package/src/components/Tabs/tabs.anatomy.stories.tsx

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/react'
-import { Users, Settings, Bell, FileText } from 'lucide-react'
+import { Users, Settings, Bell, FileText, CreditCard, Plug, Shield, KeyRound } from 'lucide-react'
 import { Tabs, TabsList, TabsTrigger, TabsContent } from './tabs'
 import { Badge } from '@/design-system/components/Badge/badge'
 import { H3, Desc, Td, Th, TokenCell } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
@@ -132,7 +132,7 @@ export const Inspector: Story = {
       description: '當前 selected tab',
     },
     withIcons: { control: 'boolean', description: 'startIcon(對應專案 / 成員 / 設定 icon)' },
-    withBadges: { control: 'boolean', description: '成員 tab 顯示 3、通知顯示 12(Badge suffix)' },
+    withBadges: { control: 'boolean', description: '成員 tab 顯示 3、設定顯示 12(Badge suffix)' },
   },
   render: (args) => {
     const { size, overflow, value, withIcons, withBadges } = args as InspectorArgs
@@ -158,12 +158,15 @@ export const Inspector: Story = {
             >
               設定
             </TabsTrigger>
+            {/* 2026-07-14 audit Dim 68:overflow 額外 triggers 也跟 withIcons 全有全無
+                (tabs.spec.md 禁止事項「同一組 Tabs 內 startIcon 全有或全無」— 原本前四個有
+                icon、後三個沒有,Inspector withIcons=true + overflow 時違反自家 spec)*/}
             {(overflow === 'scroll' || overflow === 'menu') && (
               <>
-                <TabsTrigger value="billing" startIcon={withIcons ? Bell : undefined}>計費</TabsTrigger>
-                <TabsTrigger value="integrations">整合</TabsTrigger>
-                <TabsTrigger value="security">安全性</TabsTrigger>
-                <TabsTrigger value="api">API keys</TabsTrigger>
+                <TabsTrigger value="billing" startIcon={withIcons ? CreditCard : undefined}>計費</TabsTrigger>
+                <TabsTrigger value="integrations" startIcon={withIcons ? Plug : undefined}>整合</TabsTrigger>
+                <TabsTrigger value="security" startIcon={withIcons ? Shield : undefined}>安全性</TabsTrigger>
+                <TabsTrigger value="api" startIcon={withIcons ? KeyRound : undefined}>API keys</TabsTrigger>
               </>
             )}
           </TabsList>
@@ -258,7 +261,7 @@ export const ColorMatrix: Story = {
                 <Td mono>selected</Td>
                 <Td><TokenCell token="--foreground" display="foreground" /></Td>
                 <Td>—(transparent)</Td>
-                <Td><TokenCell token="--primary-hover" display="2px primary-hover" /></Td>
+                <Td><TokenCell token="--primary" display="2px primary" /></Td>
               </tr>
               <tr>
                 <Td mono>disabled</Td>

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

@@ -211,7 +211,7 @@ DS 詞彙 **selected**（持續選中）；Radix DOM attr 為 `data-state="activ
 | 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` |
+| 未選 | `text-fg-secondary` + `font-medium`（與 selected 同 weight，差異僅文字色 + 有無底線，非 weight）、無底線；hover 時文字色轉 `text-foreground` |
 | disabled | `text-fg-disabled`；無 hover 色變化、無底線；`cursor-not-allowed`；不接受鍵盤 focus |
 | focus-visible | `ring-2 ring-ring ring-offset-1`，與 Button 一致；鍵盤導覽（左右箭頭）由 Radix 原生處理 |
 

package/src/components/Tabs/tabs.tsx

@@ -82,6 +82,25 @@ function getElementRef(element: React.ReactElement): React.Ref<HTMLElement> | un
   )
 }
 
+// 遞迴攤平 Fragment：React.Children.toArray 不展開 <>…</>(把 Fragment 當單一 element),
+// 導致 menu 模式 dropdown 漏掉被 Fragment 包起來的 trigger（如條件渲染的溢出 tabs）+ cloneElement
+// 對 Fragment 傳 ref 會噴 React warning。攤平後每個 keyless child 補 path-index key,對齊
+// React.Children.toArray 的自動 key 行為,避免 list key warning。
+function flattenTabTriggers(children: React.ReactNode, prefix = ''): React.ReactElement[] {
+  const out: React.ReactElement[] = []
+  React.Children.forEach(children, (child, i) => {
+    if (!React.isValidElement(child)) return
+    if (child.type === React.Fragment) {
+      out.push(
+        ...flattenTabTriggers((child.props as { children?: React.ReactNode }).children, `${prefix}${i}.`),
+      )
+    } else {
+      out.push(child.key != null ? child : React.cloneElement(child, { key: `tab-${prefix}${i}` }))
+    }
+  })
+  return out
+}
+
 const Tabs = React.forwardRef<
   React.ElementRef<typeof TabsPrimitive.Root>,
   TabsProps
@@ -284,8 +303,9 @@ const MenuTabsList = React.forwardRef<
     []
   )
 
+  // Fragment-safe:攤平 <>…</> 讓條件渲染的溢出 tabs 也進 dropdown / ref map(見 flattenTabTriggers）
   const items = React.useMemo(
-    () => React.Children.toArray(children).filter(React.isValidElement) as React.ReactElement[],
+    () => flattenTabTriggers(children),
     [children]
   )
 

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

@@ -205,7 +205,7 @@ export const ColorMatrix: Story = {
                 <Td>透明（zero-chrome，host context 提供邊界）</Td>
                 <Td>透明（無邊框）</Td>
                 <Td><TokenCell token="--foreground" display="foreground" /></Td>
-                <Td>—（display 無 placeholder；空值顯 — em-dash fg-muted）</Td>
+                <Td>—（display 無 placeholder；空值顯半形 -(hyphen)foreground）</Td>
               </tr>
               <tr>
                 <Td mono>readonly</Td>

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

@@ -154,7 +154,7 @@ export const NoIconRule: Story = {
     <div>
       <Rule
         title="Textarea 不支援 startIcon / endAction"
-        note="Textarea 是多行閱讀區,icon 放在框內會跟多行文字位置衝突(icon 是跟第一行對齊還是 center?)。世界級 DS(Material / Chakra / Ant)textarea 都不放內嵌 icon。需要 icon 請放 Field 外(例如 Field 的 startIcon 或標題旁)"
+        note="Textarea 是多行閱讀區,icon 放在框內會跟多行文字位置衝突(icon 是跟第一行對齊還是 center?)。世界級 DS(Material / Chakra / Ant)textarea 都不放內嵌 icon。需要 icon 請放 Textarea 外部(例如 Field 的標題 FieldLabel 旁)"
       >
         <Label warn>(型別設計)TextareaProps 不接受 startIcon / endAction,設計上就擋住</Label>
       </Rule>

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

@@ -104,11 +104,11 @@ native `<textarea>` 自帶 `value` / `defaultValue` / `onChange` triplet — Tex
 
 ### Readonly 特例
 
-不同於 Input 的 readonly（同高度、緊湊底色），`variant="default"` 的 Textarea readonly **保留 padding，並填上 `bg-readonly` 底色標示閱讀區**——多行內容需要明確的閱讀區域邊界訊號,沒有這塊填色區會無法與周圍純文字內容區分。`variant="bare"` readonly 維持透明無填色;`variant="naked"`(cell-as-input substrate)readonly 透明且 `!px-0 !py-0`——兩者的邊界訊號由 host context(toolbar / table cell)提供(`textarea.tsx` compoundVariants,intentional divergence)。
+不同於 Input 的 readonly（同高度、緊湊底色），`variant="default"` 的 Textarea readonly **保留 padding，並填上 `bg-readonly` 底色標示閱讀區**——多行內容需要明確的閱讀區域邊界訊號,沒有這塊填色區會無法與周圍純文字內容區分。`variant="naked"`(cell-as-input substrate)readonly 透明且 `!px-0 !py-0`——邊界訊號由 host context(table cell)提供(`textarea.tsx` compoundVariants,intentional divergence;`bare` variant 2026-07-09 退役)。
 
 ### 邊界案例
 
-- **空值**:edit 態顯示 placeholder;display 態 value 為空(`null` / `''`)時渲染 `—`(`EMPTY_DISPLAY`)+ `text-fg-muted`
+- **空值**:edit 態顯示 placeholder;display / readonly 態 value 為空(`null` / `''`)時渲染半形 `-`(`EMPTY_DISPLAY`)+ `text-foreground`(disabled → fg-disabled)
 - **極長文字**:edit 態高度固定於 rows / resize 結果,內容超出時 native 內部捲動;display 態 `<div>` 隨內容增高(`whitespace-pre-wrap break-words`),無截斷
 - **resize 上限**:`resize-y` 預設無上限;需限制時 consumer 傳 `max-h-*` className(native resize 受 max-height 約束)
 
@@ -120,7 +120,7 @@ native `<textarea>` 自帶 `value` / `defaultValue` / `onChange` triplet — Tex
 - ❌ Textarea 裡放 startIcon / endAction——textarea 慣例無 icon 框內
 - ❌ Textarea 啟用水平 resize（`resize-x` / `resize: both`）——破壞 form 佈局
 - ❌ 把 Textarea 當 code editor 用（無 syntax highlight / auto-complete）
-- ❌ `variant="default"` readonly 移除底色填充 + padding——多行內容需要閱讀區域邊界訊號(bare / naked 變體本就透明、邊界由 host context 提供,不在此限)
+- ❌ `variant="default"` readonly 移除底色填充 + padding——多行內容需要閱讀區域邊界訊號(naked 變體本就透明、邊界由 host context 提供,不在此限)
 
 ---
 
@@ -151,7 +151,7 @@ Textarea 是 **Field Controls family 的多行變體**,共用規則由 `../Field
 - 字母鍵 — 輸入
 - Enter — 換行（不觸發 form submit，與 Input 不同）
 
-**Focus**:DS focus-visible 邊框(`focus-visible:!border-primary`)由 `<textarea>` 自身的 cva compoundVariants 直接套用（textarea.tsx default/bare/naked edit 態），無 fieldWrapper composite——Textarea 是裸 native textarea（見「定位」L30），standalone 使用即取得 primary focus 邊框。
+**Focus**:DS focus 邊框由 `<textarea>` 自身的 cva compoundVariants 直接套用,無 fieldWrapper composite——Textarea 是裸 native textarea(見「定位」L30)。兩種 chrome 的 focus 觸發不同:**default chrome** 用 `focus-within:!border-primary`(滑鼠點擊或鍵盤聚焦皆亮主色邊框,對齊 form 場景);**naked chrome**(cell-as-input)用 `focus-visible:!border-primary`(僅鍵盤聚焦亮,滑鼠由 host cell 提供 frame)。readonly 有值態另用 ring idiom(`focus-visible:ring-2 ring-ring ring-offset-1`,鍵盤限定;見 `../Field/field-controls.spec.md`「readonly focus ring」)。standalone 使用即取得對應 focus 指示。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 

package/src/components/Textarea/textarea.tsx

@@ -2,9 +2,10 @@
 import * as React from 'react'
 import { cva, type VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
+import type { FieldMode, FieldVariant, FieldVariantInternal } from '@/design-system/components/Field/field-types'
 import { useFieldContext, useResolvedFieldSize, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
-import { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
+import { useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
+import { useControllable } from '@/design-system/hooks/use-controllable'
 
 /**
  * Textarea — 多行文字輸入
@@ -29,8 +30,8 @@ import { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
  * 預設 rows={3}。消費者可透過 rows prop 調整，或透過 min-h-* className 覆寫。
  */
 
-// Phase B1(2026-05-05):新增 chrome variant(default / bare),mode×chrome 的 chrome 規則由
-// compoundVariants 決定,鏡射 fieldWrapperStyles 對齊 canonical(Phase D 將整併進 fieldWrapperStyles)。
+// Phase B1(2026-05-05):chrome variant(default / naked;`bare` 2026-07-09 退役),mode×chrome 的
+// chrome 規則由 compoundVariants 決定,鏡射 fieldWrapperStyles 對齊 canonical(Phase D 將整併進 fieldWrapperStyles)。
 const textareaVariants = cva(
   [
     'w-full rounded-md',
@@ -51,10 +52,9 @@ const textareaVariants = cva(
         readonly: '',
         disabled: '',
       },
-      // chrome 對齊 fieldWrapperStyles.variant(default / bare / naked)。
+      // chrome 對齊 fieldWrapperStyles.variant(default / naked;2026-07-09 `bare` 退役)。
       variant: {
         default: '',
-        bare: '',
         naked: '',
       },
       size: {
@@ -89,46 +89,24 @@ const textareaVariants = cva(
       {
         mode: 'readonly',
         variant: 'default',
-        className: 'bg-readonly border border-transparent',
+        // 2026-07-13 a11y(WCAG 2.4.7):readonly 有值渲 native <textarea readOnly> 可鍵盤聚焦,base
+        //   outline-none + border-transparent 無焦點指示 → 鏡射 field-wrapper.tsx readonly ring idiom
+        //   (field-controls.spec.md「readonly focus ring」)。textarea 為裸 focusable element,直接用
+        //   focus-visible:(非 :has()),僅鍵盤聚焦顯示、滑鼠點擊不觸發。
+        className: 'bg-readonly border border-transparent focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
       },
       {
         mode: 'disabled',
         variant: 'default',
         className: 'bg-disabled border border-transparent cursor-not-allowed text-fg-disabled',
       },
-      // bare chrome × mode(對齊 fieldWrapperStyles bare 規則)
-      {
-        mode: 'edit',
-        variant: 'bare',
-        className: [
-          'bg-transparent border border-transparent',
-          'hover:border-border',
-        ],
-      },
-      { mode: 'edit', variant: 'bare', error: false, className: 'focus-within:!border-primary focus-within:hover:!border-primary' },
+      // (2026-07-09 `bare` chrome × mode compounds 退役已移除;error:true 為 variant-agnostic 保留)
       {
         mode: 'edit',
         error: true,
         className: 'border-error hover:border-error-hover focus-within:!border-error focus-within:hover:!border-error',
       },
-      {
-        mode: 'display',
-        variant: 'bare',
-        className: 'bg-transparent border border-transparent',
-      },
-      {
-        mode: 'readonly',
-        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 text-fg-disabled',
-      },
+      // (2026-07-09 display×bare / readonly×bare / disabled×bare compounds 退役已移除)
       // naked chrome × mode — cell-as-input substrate(2026-05-06 v14 revert v12)。
       //   v12 `!absolute -inset-px` autoRowHeight 不相容 → revert v9 baseline + 保留 v13.3
       //   focus !important。focus-visible 用 textarea 自身 selector(focusable element)。
@@ -176,7 +154,7 @@ export interface TextareaProps
   /**
    * Visual chrome(正交於 mode);Phase B1(2026-05-05)新增。透傳自 FieldContext.variant,per-prop override。
    * - `'default'` — 完整 chrome(form 場景)
-   * - `'bare'` — 透明 variant,hover/focus 才 reveal inner border(toolbar / inline editing)
+   * (2026-07-09 `bare` variant 退役;naked = cell-as-input substrate,@internal)
    * - `'naked'` — 完全無 chrome,cell-as-input(host cell 提供 border + focus frame,對齊 Airtable / Notion / Excel cell editing)
    */
   variant?: FieldVariant
@@ -197,6 +175,7 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
       readOnly,
       rows = 3,
       value,
+      defaultValue,
       id: idProp,
       'aria-describedby': ariaDescribedByProp,
       'aria-errormessage': ariaErrorMessageProp,
@@ -207,44 +186,84 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
     // Field context 整合：disabled / mode / chrome / invalid / size / id 都能從 context 繼承
     const fieldCtx = useFieldContext()
     // chrome 透傳:per-prop override context
-    const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+    const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     const error = useResolvedFieldInvalid(errorProp)
     const size = useResolvedFieldSize(sizeProp)
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode 統一解析(prop > 有效 disabled > fieldCtx.mode > readOnly > 'edit')
     const resolvedMode: FieldMode = useResolvedFieldMode({ mode: modeProp, disabled, readOnly })
+    const emptyDisplay = useFieldEmptyDisplay()
     const isEditable = resolvedMode === 'edit'
     const isDisplay = resolvedMode === 'display'
     const inputId = idProp ?? fieldCtx?.id
     const ariaDescribedBy = ariaDescribedByProp ?? fieldCtx?.descriptionId
     const ariaErrorMessage = ariaErrorMessageProp ?? (error ? fieldCtx?.errorId : undefined)
 
-    // ── display mode:純展示,渲染 <div> 取代 <textarea>(white-space:pre-wrap 保留多行) ──
+    // ── display mode(+ readonly 空值)純展示,渲染 <div> 取代 <textarea>(white-space:pre-wrap 保留多行) ──
     // 對齊 Carbon read-only / Cloudscape display-mode
-    if (isDisplay) {
-      const displayValue = value != null && value !== '' ? String(value) : null
+    // 2026-07-08 user 拍板:readonly 空值也走 display-div 顯 '-'(readonly **有值** 仍走下方
+    // native <textarea readOnly> 保留選取/複製語意 — field-controls.spec.md「null / undefined 值」)。
+    // 2026-07-13 fix:空值判斷需認得 uncontrolled defaultValue — readonly / display 也要顯示內容,
+    //   不可誤判為空值渲 '-'(原為靜態 value ?? defaultValue)。
+    // 2026-07-14 R2(dual-model consensus,同 Input input.tsx):resolved value 改走 useControllable
+    // 內部 SSOT(Radix idiom)。原靜態版有 typing-stale gap:uncontrolled 打字後外部切
+    // display / readonly 仍顯示 stale defaultValue。uncontrolled 時 native textarea 由
+    // value={resolved} 內部驅動(defaultValue 只作初始值,不落 DOM attribute),同時修
+    // remount-stale(切 display 再回 edit 從 defaultValue attribute 重掛)+ form.reset() stale
+    // (HTML 標準 reset 不發 input event,下方 reset bridge 修)。controlled(傳 value)時
+    // useControllable 純 passthrough,行為與原本完全一致。consumer onChange 不接進 hook
+    // (保留 native event signature),於 <textarea> onChange 另行轉發。
+    const isControlled = value !== undefined
+    const [resolved, setResolved] = useControllable<string | number | readonly string[]>({
+      value: value as string | number | readonly string[] | undefined,
+      defaultValue: defaultValue ?? '',
+    })
+    const displayValue = resolved != null && resolved !== '' ? String(resolved) : null
+    const showDisplaySpan = isDisplay || (resolvedMode === 'readonly' && displayValue == null)
+
+    // form.reset() bridge(uncontrolled only):reset 恢復 defaultValue 但不發 input event →
+    // 手動把 resolved 歸位 defaultValue。keyed on showDisplaySpan:display 分支不掛 native
+    // textarea,回 edit 重掛時 effect 重跑補掛 listener。
+    const innerRef = React.useRef<HTMLTextAreaElement | null>(null)
+    React.useEffect(() => {
+      if (isControlled || showDisplaySpan) return
+      const form = innerRef.current?.form
+      if (!form) return
+      const handleReset = () => setResolved(defaultValue ?? '')
+      form.addEventListener('reset', handleReset)
+      return () => form.removeEventListener('reset', handleReset)
+    }, [isControlled, showDisplaySpan, defaultValue, setResolved])
+    // Merge refs(LinkInput setRef idiom,link-input.tsx:138)
+    const setRef = React.useCallback((el: HTMLTextAreaElement | null) => {
+      innerRef.current = el
+      if (typeof ref === 'function') ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLTextAreaElement | null>).current = el
+    }, [ref])
+
+    if (showDisplaySpan) {
+      const spanMode = isDisplay ? 'display' : 'readonly'
       return (
         <div
           id={inputId}
-          data-field-mode="display"
+          data-field-mode={spanMode}
           aria-describedby={ariaDescribedBy}
           className={cn(
-            textareaVariants({ mode: 'display', variant: variant, size }),
+            textareaVariants({ mode: spanMode, variant: variant, size }),
             'whitespace-pre-wrap break-words',
-            displayValue == null && 'text-fg-muted',
+            displayValue == null && fieldEmptyColorClass(resolvedMode),
             className,
           )}
         >
-          {displayValue ?? EMPTY_DISPLAY}
+          {displayValue ?? emptyDisplay}
         </div>
       )
     }
 
     return (
       <textarea
-        ref={ref}
+        ref={setRef}
         id={inputId}
         rows={rows}
-        value={value as string | number | readonly string[] | undefined}
+        value={resolved}
         disabled={resolvedMode === 'disabled'}
         readOnly={resolvedMode === 'readonly'}
         aria-invalid={error || undefined}
@@ -258,6 +277,11 @@ const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
           className
         )}
         {...props}
+        // 置於 {...props} 後:寫回 resolved SSOT(controlled 時 useControllable 內部為 no-op)再轉發 consumer onChange。
+        onChange={(e) => {
+          setResolved(e.target.value)
+          props.onChange?.(e)
+        }}
       />
     )
   }
@@ -280,6 +304,8 @@ export const textareaMeta = {
   },
   // states 對齊 cva compoundVariants + anatomy ColorMatrix 真實 state 集合;
   //   text input 無 'active'(按下)視覺態(Material/Polaris/Carbon TextArea 共識)。
+  //   'focus-visible' 泛指 focus 態:default chrome 實為 focus-within(滑鼠+鍵盤皆亮),naked chrome
+  //   為 focus-visible(鍵盤限定),readonly 有值態為 focus-visible ring(見上方 compoundVariants)。
   states: ['default', 'hover', 'focus-visible', 'readonly', 'disabled', 'error'],
   tokens: {
     bg: ['bg-disabled', 'bg-readonly', 'bg-surface'], // 2026-07-04 補:readonly×default cva 實際消費(spec「Readonly 特例」主打 token)

package/src/components/TimePicker/time-columns.tsx

@@ -147,12 +147,16 @@ function TimeColumn({ values, selected, disabledSet, label, onSelect, withDivide
   //   - TimePicker:wrap in h-[216px] container(預設 ~7 items)
   //   - DatePicker showTime / Range:flex-row items-stretch + calendar 一起決定高度(自動同高)
   return (
-    <ScrollArea className={cn('flex-1 h-full', withDivider && 'border-r border-divider')}>
+    // viewportTabIndex=-1:焦點直接落 listbox(有 keydown),消除「Viewport+listbox 雙 tab stop
+    // + 焦點落 Viewport 時 ↑/↓ 觸發原生捲動非選值」a11y bug(axe 由 listbox tabIndex=0 滿足)
+    <ScrollArea viewportTabIndex={-1} className={cn('flex-1 h-full', withDivider && 'border-r border-divider')}>
       <div
         ref={listRef}
         role="listbox"
         aria-label={label}
-        aria-activedescendant={selected != null ? `${baseId}-opt-${selected}` : undefined}
+        // guard values.includes:off-step value(如 minuteStep=15 但分=07)的 option 未渲染,
+        // 指向未渲染 id = 懸空 ARIA 參照(AT 讀空);僅真實渲染的 option 才掛
+        aria-activedescendant={selected != null && values.includes(selected) ? `${baseId}-opt-${selected}` : undefined}
         tabIndex={0}
         onKeyDown={handleKeyDown}
         className="flex flex-col py-2 focus-visible:outline-2 focus-visible:outline-ring focus-visible:outline-offset-[-2px]"

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

@@ -61,7 +61,7 @@ export const UsageGuidance: Story = {
       <div className="prose prose-sm max-w-prose space-y-4">
       <p>TimePicker 只管時間,以下情境改用其他元件:</p>
       <ul className="list-disc list-inside space-y-1 text-fg-secondary">
-        <li><strong>同時選日期和時間</strong> → DatePicker + TimePicker 並列。Jira 的 due date 用 DatePicker，time 用 TimePicker</li>
+        <li><strong>同時選日期和時間</strong> → DatePicker 加 showTime prop（canonical 2026-05-02，Ant idiom；非 DatePicker + TimePicker 並列，見 DatePicker 設計原則）。Linear 的 reminder「日期 + 時間」是單一 datetime picker</li>
         <li><strong>時間範圍（from-to）</strong> → 兩個 TimePicker 並列。Google Calendar 的 event time 是兩個 picker</li>
         <li><strong>純文字時間輸入</strong> → Input + validation。開發者工具用 Input</li>
         <li><strong>倒數計時或相對時間</strong> → 自訂計時器。TimePicker 是 wall-clock time（09:30），不是 duration</li>

package/src/components/TimePicker/time-picker.spec.md

@@ -66,7 +66,7 @@ open 軸同樣只開最小 API — **uncontrolled-only**:`defaultOpen`(初始開
 
 | 場景 | 改用 | 原因 |
 |------|------|------|
-| 同時需要日期 + 時間 | **DatePicker with time** 或 `<DatePicker> + <TimePicker>` 並列 | TimePicker 本身不帶日期;需配 DatePicker 組合 |
+| 同時需要日期 + 時間 | **`<DatePicker showTime>`**(canonical 2026-05-02,Ant idiom;非獨立並列組合,見 date-picker.spec「showTime」段) | TimePicker 本身不帶日期;datetime 是單一 picker 職責 |
 | 時間範圍(from-to) | **兩個 `<TimePicker>`** 並列 + 之間 `<ArrowRight>` | TimePicker **MVP 不支援 range**,用組合達成(對齊 Ant `TimePicker.RangePicker` 的 composition 思路 — [source](https://github.com/react-component/picker/blob/master/src/PickerInput/RangePicker.tsx)) |
 | 純文字時間輸入(秒有意義的科學測量) | `<Input>` + mask / regex validation | TimePicker 的 column UX 不適合大量精確輸入 |
 | 倒數計時 / 相對時間 | 自行渲染 `MM:SS` 倒數 | TimePicker 是 wall-clock time,不是 duration |
@@ -199,7 +199,7 @@ Panel 展開後的 column picker 結構:
 詳見 `../Field/field-controls.spec.md`(共用規則)。
 
 ### Empty 值
-`value={null}` / `value=""` / `value=undefined` 都視為空,trigger 顯示 `placeholder`。Display 模式空值顯示 `—`(對齊 `EMPTY_DISPLAY`)。
+`value={null}` / `value=""` / `value=undefined` 都視為空,trigger 顯示 `placeholder`。Display 模式空值顯示半形 `-`(對齊 `EMPTY_DISPLAY`,text-foreground)。
 
 ### 驗證時機
 - **每次欄位選取(時 / 分 / 秒任一改變)當下即 commit value 給 `onChange`**(eager commit,非 OK 才送)。OK 鈕(「確定」)只負責關閉 Panel,不另行 commit。`此刻` 按鈕則一次 commit 當前時間並關閉 Panel
@@ -274,7 +274,7 @@ trigger 的互動狀態(focus / invalid / disabled / readonly)完全繼承 `../F
 
 - **Disabled**:Field SSOT own;trigger 自動 disabled(`text-fg-disabled` + 不開 picker),Display mode + disabled 維持時間格式但 token 切 disabled。
 - **Loading**:TimePicker 為 sync UI(time math 在 client),無 loading state。極端 case(後端 disabled-times list)應由 consumer 先 disable trigger 直到 fetch 完成。
-- **Empty(no value)**:`value=null` 為合法 initial state,trigger 顯 placeholder;**未傳 `placeholder` 時 default = 格式遮罩**(`HH:MM`,showSeconds=true 時 `HH:MM:SS`),非固定文案。`null` + Display mode 顯 `—`(em dash + `text-fg-muted`)對齊 Input display empty 慣例。
+- **Empty(no value)**:`value=null` 為合法 initial state,trigger 顯 placeholder;**未傳 `placeholder` 時 default = 格式遮罩**(`HH:MM`,showSeconds=true 時 `HH:MM:SS`),非固定文案。`null` + Display mode 顯半形 `-`(hyphen + `text-foreground`,disabled → fg-disabled)對齊 Input display empty 慣例。
 - **Empty(disabled all times)**:極端場景(`disabledHours` / `disabledMinutes` 覆蓋全範圍),panel column 全 disabled,鍵盤焦點停留無導覽目標。
 - **Panel 開啟中外部 value 變更**:controlled 單向資料流——欄位選中即時反映新 value,並 scroll-into-view(`behavior:'smooth'`,mount 後的變更;見「Spacing + 結構」的 Scroll-into-view 條)。
 - **Dark mode / density**:走 Field + Popover SSOT 自動 adapt;panel column item 由 MenuItem SSOT 控 density。

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

@@ -3,16 +3,15 @@ import * as React from 'react'
 import { X, Clock } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
+import type { FieldMode, FieldVariant, FieldVariantInternal } from '@/design-system/components/Field/field-types'
 import {
   fieldWrapperStyles,
   bareInputStyles,
-  EMPTY_DISPLAY,
   fieldDisplayTextClass,
 } from '@/design-system/components/Field/field-wrapper'
 import { ItemInlineAction, ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { Popover, PopoverTrigger, PopoverContent } from '@/design-system/components/Popover/popover'
-import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
+import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { Button } from '@/design-system/components/Button/button'
 import { SurfaceFooter } from '@/design-system/patterns/overlay-surface/overlay-surface'
 import {
@@ -191,7 +190,8 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
     const disabled = useResolvedFieldDisabled(disabledProp)
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="display"> 漏 cascade
     const resolvedMode = useResolvedFieldMode({ mode, disabled })
-    const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+    const emptyDisplay = useFieldEmptyDisplay()
+    const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     const isEditable = resolvedMode === 'edit'
     // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
@@ -204,7 +204,7 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
     const setOpen = React.useCallback((next: boolean) => { setOpenState(next); onOpenChange?.(next) }, [onOpenChange])
 
     const currentParts = React.useMemo(() => isoToTimeParts(value), [value])
-    // draft 僅在 panel 開啟時用來處理 commit(OK button)的暫存
+    // draft = panel 開啟期間的暫存:供 eager commit(每次欄選 commitDraft 即 commit)+ disabledTime 重算;OK 按鈕只 setOpen(false) 關 Panel,不做 commit
     const [draft, setDraft] = React.useState<TimeParts>(
       () => currentParts ?? { hours: 0, minutes: 0, seconds: 0 },
     )
@@ -260,7 +260,7 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
       if (!showDisplayEndIcon) {
         // 2026-05-14 I2 fix(spec contract (e) display typography canonical):bare span 套
         // `fieldDisplayTextClass(size)`(sm/md→text-body,lg→text-body-lg)— 對齊 Field family 統一。
-        if (!value) return <span className={cn(fieldDisplayTextClass(size), 'text-fg-muted', className)}>{EMPTY_DISPLAY}</span>
+        if (!value) return <span className={cn(fieldDisplayTextClass(size), fieldEmptyColorClass(resolvedMode), className)}>{emptyDisplay}</span>
         return <span className={cn(fieldDisplayTextClass(size), 'truncate', className)}>{formatTime(value, { formatOptions, locale })}</span>
       }
       return (
@@ -268,8 +268,8 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
           className={cn(fieldWrapperStyles({ mode: 'display', variant, size }), className)}
           data-field-mode="display"
         >
-          <span className={cn(bareInputStyles, 'flex-1 min-w-0 truncate', !value && 'text-fg-muted')}>
-            {value ? formatTime(value, { formatOptions, locale }) : EMPTY_DISPLAY}
+          <span className={cn(bareInputStyles, 'flex-1 min-w-0 truncate', !value && fieldEmptyColorClass(resolvedMode))}>
+            {value ? formatTime(value, { formatOptions, locale }) : emptyDisplay}
           </span>
           {EndIconCmp && (
             <ItemSuffix className="pointer-events-none">
@@ -297,7 +297,7 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
           >
             {value
               ? formatTime(value, { formatOptions, locale })
-              : <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+              : <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
             }
           </span>
           {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示 / disabled 保留(fg-disabled);naked cell 依 showDisplayEndIcon=isEditable(修 disabled cell 漏顯 bug)*/}
@@ -344,6 +344,10 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
             aria-expanded={open}
             onKeyDown={(e) => {
               if (disabled) return
+              // 2026-07-14 dim-10 修:內層「清除時間」ItemInlineAction button 的 Enter/Space
+              // 會 bubble 到本 handler 被 preventDefault 吞掉(按鈕 activation 被取消、panel 反而開)。
+              // trigger 鍵盤邏輯只在事件源自 trigger div 本身時執行。
+              if (e.target !== e.currentTarget) return
               // Enter / Space / ArrowDown / Alt+ArrowDown → 開 panel(APG combobox required + Select canonical)
               if (e.key === 'Enter' || e.key === ' ' || e.key === 'ArrowDown') {
                 e.preventDefault()
@@ -385,7 +389,9 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
             )}
           </div>
         </PopoverTrigger>
-        <PopoverContent className="w-auto p-0" align="start">
+        {/* a11y(2026-07-14 dim-10):Radix PopoverContent 輸出 role="dialog",無 title 需
+            accessible name(WAI-ARIA dialog required);對齊 date-picker.tsx:1040「日期區間選擇」同款 DS default。 */}
+        <PopoverContent className="w-auto p-0" align="start" aria-label="選擇時間" /* i18n-allow: DS default dialog label */>
           {/* Panel 對齊 ref/timepicker.png:2-3 個 SelectMenu 式欄位並排,分隔線分開。
               Width 依欄數由 TimeColumns 決定:2 欄 w-40 / 3 欄 w-60。
               Height 由 wrapper 控:216px 預設(扣 footer 後 list 約可見 5-6 items)。

package/src/components/Toast/toast.stories.tsx

@@ -10,26 +10,29 @@ const meta: Meta = {
 export default meta
 
 // 2026-07-04 audit:補 'info'(NoticeVariant 5 值,原漏 → 靜態雙 theme 對照未涵蓋全 variant)
+// 2026-07-14 Dim 68 修:原 warning =「訂閱 7 天後停用 + 續訂 CTA」= 持久帳務狀態 + 強制 CTA,
+// 違反 toast.spec.md「持久性系統狀態(方案過期)→ Alert」+「❌ 不把需要 user action 的內容
+// 放 Toast(action 僅限復原類非必要後手)」。改為短暫操作回饋(匯入部分完成)+ 非必要「查看」後手。
 const VARIANTS: NoticeVariant[] = ['neutral', 'info', 'success', 'warning', 'error']
 const LABELS: Record<string, string> = {
   neutral: '檔案已複製到剪貼簿',
   info: '新版本 v2.4 可用',
   success: '專案已儲存',
-  warning: '即將到期的訂閱',
+  warning: '匯入部分完成',
   error: '無法連線伺服器',
 }
 const ACTIONS: Record<string, string> = {
   neutral: '復原',
   info: '查看更新',
   success: '查看',
-  warning: '續訂',
+  warning: '查看',
   error: '重試',
 }
 const DESCRIPTIONS: Record<string, string> = {
   neutral: '「Q3 營收報表.xlsx」已加入剪貼簿',
   info: '重新整理頁面即可套用新功能',
   success: '變更已同步到所有成員',
-  warning: '7 天後將停用,請前往結算頁續訂',
+  warning: '120 筆已匯入,3 筆格式錯誤被略過',
   error: '請檢查網路後再試一次',
 }
 
@@ -120,7 +123,7 @@ export const Interactive = {
       <div className="flex flex-wrap gap-2">
         <Button variant="secondary" onClick={() => toast({ title: '檔案已複製到剪貼簿', action: { label: '復原', onClick: () => {} } })}>複製檔案</Button>
         <Button variant="secondary" onClick={() => toast({ variant: 'success', title: '專案已儲存', description: '變更已同步到所有成員', action: { label: '查看', onClick: () => {} } })}>儲存專案</Button>
-        <Button variant="secondary" onClick={() => toast({ variant: 'warning', title: '即將到期的訂閱', description: '7 天後將停用,請前往結算頁續訂', action: { label: '續訂', onClick: () => {} } })}>訂閱提醒</Button>
+        <Button variant="secondary" onClick={() => toast({ variant: 'warning', title: '匯入部分完成', description: '120 筆已匯入,3 筆格式錯誤被略過', action: { label: '查看', onClick: () => {} } })}>匯入資料</Button>
         <Button variant="secondary" onClick={() => toast({ variant: 'error', title: '無法連線伺服器', description: '請檢查網路後再試一次', action: { label: '重試', onClick: () => {} } })}>斷線示範</Button>
       </div>
       <Toaster />

package/src/components/Tooltip/tooltip.anatomy.stories.tsx

@@ -159,7 +159,7 @@ export const Overview = {
             <thead><tr><Th>零件</Th><Th>元素</Th><Th>說明</Th></tr></thead>
             <tbody>
               {[
-                ['TooltipProvider', '<TooltipPrimitive.Provider>', '全域 Provider，控制 warm-up delay 參數（全產品一個）'],
+                ['TooltipProvider', '<TooltipPrimitive.Provider>', '全域 Provider，控制 skip window 與共享暖機狀態（全產品一個）；單一 tooltip 的 delay 由 Root 預設 500ms 決定，優先於 Provider'],
                 ['Tooltip', '<TooltipPrimitive.Root>', '單一 tooltip 實例的容器'],
                 ['TooltipTrigger', '<TooltipPrimitive.Trigger>', '觸發器，搭配 asChild 套用至任意子元素'],
                 ['TooltipContent', '<TooltipPrimitive.Content>', '浮動內容區，透過 Portal 渲染'],
@@ -195,7 +195,7 @@ export const Overview = {
       {/* Warm-up pattern */}
       <div className="flex flex-col gap-3">
         <H3>Warm-up Pattern（暖機模式）</H3>
-        <Desc>全產品統一一組時間參數，不因 tooltip 類型或位置而異。其中 delayDuration（500ms）由 DS Tooltip wrapper（Root 預設值,對齊 motion token SSOT;Radix Root prop 優先於 Provider 同名設定）統一；skipDelayDuration（300ms）沿用 Radix 內建 default，由消費端 app／storybook root 顯式同步設定，DS wrapper 本身不 carry 這個值。</Desc>
+        <Desc>全產品統一一組時間參數，不因 tooltip 類型或位置而異：首次 hover 需停留 500ms 才顯示（確認是刻意停留）；顯示後 300ms 內把游標移到下一個觸發器可即時切換、不用重新等待。</Desc>
         <div className="flex flex-col gap-1.5 text-caption max-w-[600px]">
           <div className="flex items-start gap-2 py-1.5 border-b border-divider">
             <span className="text-fg-muted w-5 shrink-0 font-mono">1.</span>
@@ -338,7 +338,7 @@ export const Inspector = {
     <div className="flex flex-col gap-4">
       <div className="flex flex-col gap-1">
         <H3>元件檢閱器</H3>
-        <Desc>切換方向查看 tooltip 的 placement。右側面板列出所有 design token 及其對應值。</Desc>
+        <Desc>切換方向查看 tooltip 的 placement。右側面板列出主要 design token 及其對應值。</Desc>
       </div>
       <InspectorInner />
     </div>
@@ -407,7 +407,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">{"ARIA / Pattern:沿用 Radix tooltip 的無障礙預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/tooltip#accessibility)。\n\n  鍵盤行為:\n\n- Tab — focus 到觸發器時顯示\n- Esc — 關閉\n\n  焦點:hover / focus 浮層,非 modal——focus 開啟浮層但不鎖住焦點,焦點仍留在觸發器,按 Esc 關閉。觸發器有可見 focus ring(2px 外框)。\n\n  驗證:Storybook a11y addon 面板應 0 個 critical 違規;純鍵盤即可完整操作(無需滑鼠)。文字對比 ≥ 4.5:1、UI 元素對比 ≥ 3:1(WCAG AA)。"}</p>
+      <p className="whitespace-pre-line">{"ARIA / Pattern:沿用 Radix tooltip 的無障礙預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/tooltip#accessibility)。\n\n  鍵盤行為:\n\n- Tab — focus 到觸發器時顯示\n- Esc — 關閉\n\n  焦點:hover / focus 浮層,非 modal——focus 開啟浮層但不鎖住焦點,焦點仍留在觸發器,按 Esc 關閉。觸發器的 focus ring 由 asChild 包的可聚焦子元件提供(Tooltip 本身是透傳 Trigger、不加樣式)。\n\n  驗證:Storybook a11y addon 面板應 0 個 critical 違規;純鍵盤即可完整操作(無需滑鼠)。文字對比 ≥ 4.5:1、UI 元素對比 ≥ 3:1(WCAG AA)。"}</p>
     </div>
   ),
 }