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

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

@@ -74,64 +74,57 @@ export const UsageGuidance: Story = {
 export const RuleMinuteStepForMeetings: Story = {
   name: '會議時段用 15 分鐘間隔',
   render: () => (
-    <div className="flex gap-8">
-      <div className="flex flex-col gap-1.5">
-        <h3 className="text-caption font-medium text-foreground">✅ minuteStep=15</h3>
-        <Field>
-          <FieldLabel>專案週會時間</FieldLabel>
-          <TimePicker value="09:15" onChange={() => {}} minuteStep={15} />
-        </Field>
-      </div>
-      <div className="flex flex-col gap-1.5">
-        <h3 className="text-caption font-medium text-fg-muted">❌ 預設 minuteStep=1(會議排程無意義)</h3>
-        <Field>
-          <FieldLabel>專案週會時間</FieldLabel>
-          <TimePicker value="09:07" onChange={() => {}} />
-        </Field>
+    <div className="flex flex-col gap-4">
+      <p className="text-caption text-fg-secondary max-w-prose">
+        會議排程以 15 分鐘為粒度是世界級慣例(Google Calendar / Outlook / Notion Calendar
+        的時間選單預設都是 15)。用預設 minuteStep=1 會讓使用者困在挑「9:07 還是 9:08」,
+        失去會議排程的本質——這類情境一律設 minuteStep=15。
+      </p>
+      <div className="flex gap-8">
+        <div className="flex flex-col gap-1.5">
+          <h3 className="text-caption font-medium text-foreground">✅ minuteStep=15</h3>
+          <Field>
+            <FieldLabel>專案週會時間</FieldLabel>
+            <TimePicker value="09:15" onChange={() => {}} minuteStep={15} />
+          </Field>
+        </div>
+        <div className="flex flex-col gap-1.5">
+          <h3 className="text-caption font-medium text-fg-muted">❌ 預設 minuteStep=1(會議排程無意義)</h3>
+          <Field>
+            <FieldLabel>專案週會時間</FieldLabel>
+            <TimePicker value="09:07" onChange={() => {}} />
+          </Field>
+        </div>
       </div>
     </div>
   ),
 }
 
-/**
- * Rule:Range 語意用兩個 TimePicker 組合
- * TimePicker MVP 不內建 Range(見 spec「為何無 Range」)——對齊 Ant composition 思路,
- * consumer 用兩個 TimePicker + arrow 達成營業時段 / 會議時段等 range 場景。
- */
-export const RuleRangeComposition: Story = {
-  name: '時間範圍用兩個 TimePicker 組合,不內建',
-  render: () => {
-    const [open, setOpen] = React.useState('10:00')
-    const [close, setClose] = React.useState('22:00')
-    return (
-      <Field>
-        <FieldLabel>營業時段(兩個 TimePicker + →)</FieldLabel>
-        <div className="flex items-center gap-2">
-          <TimePicker value={open} onChange={setOpen} />
-          <span className="text-fg-muted">→</span>
-          <TimePicker value={close} onChange={setClose} />
-        </div>
-      </Field>
-    )
-  },
-}
+// Dim 24 retire(2026-07-16):原 RuleRangeComposition(營業時段雙 TimePicker + →)與「展示」層
+// 的「店家營業時間」(ShopBusinessHours)near-identical(同值 10:00/22:00、同結構),且其規則
+// (TimePicker 不內建 Range,用兩個並列組合)已由本頁 UsageGuidance「何時不用」條目文字說明。
+// 重複範例退役;範圍組合的 live demo 見「展示 → 店家營業時間」(UsageGuidance 已 LinkTo 指向)。
 
 /**
  * 規則:清除用 X 行內動作,不要用文字按鈕
- * 設定 clearable 後,TimePicker 會自動在欄位尾端渲染一個 X 行內動作來清空值,
- * 點擊即清空。不要自己擺一顆「清除」文字按鈕——統一用 X 圖示符合全站慣例。
  */
 export const RuleClearNoLabelButton: Story = {
   name: '清除用 X 行內動作,不用文字按鈕',
   render: () => {
     const [t, setT] = React.useState<string>('14:30')
     return (
-      <div className="flex flex-col gap-1.5">
-        <h3 className="text-caption font-medium text-foreground">✅ clearable=true(自動渲染 X 行內動作)</h3>
-        <Field>
-          <FieldLabel>提醒時間</FieldLabel>
-          <TimePicker value={t} onChange={setT} clearable />
-        </Field>
+      <div className="flex flex-col gap-4">
+        <p className="text-caption text-fg-secondary max-w-prose">
+          設定 clearable 後,TimePicker 會自動在欄位尾端渲染一個 X 行內動作來清空值,點擊即清空。
+          不要自己擺一顆「清除」文字按鈕——全站統一用 X 圖示表達「移除已填內容」,與其他欄位的清除慣例一致。
+        </p>
+        <div className="flex flex-col gap-1.5">
+          <h3 className="text-caption font-medium text-foreground">✅ clearable=true(自動渲染 X 行內動作)</h3>
+          <Field>
+            <FieldLabel>提醒時間</FieldLabel>
+            <TimePicker value={t} onChange={setT} clearable />
+          </Field>
+        </div>
       </div>
     )
   },

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

@@ -80,7 +80,7 @@ open 軸同樣只開最小 API — **uncontrolled-only**:`defaultOpen`(初始開
   value={time}                   // ISO "HH:mm" or "HH:mm:ss" | null
   onChange={setTime}
   size="sm" | "md" | "lg"        // 對齊 field-height family,default md
-  mode="edit" | "display" | "readonly" | "disabled"   // display = 純展示(DataTable cell 用)
+  mode="edit" | "view" | "readonly" | "disabled"   // view = 純展示值(DataTable cell 用)
   disabled={boolean}
   error={boolean}
   clearable={boolean}
@@ -105,7 +105,7 @@ open 軸同樣只開最小 API — **uncontrolled-only**:`defaultOpen`(初始開
 
 ### 顯示格式化
 
-**Display 走 `Intl.DateTimeFormat`**(跨 locale 統一、12h/24h 支援)。`formatOptions` 透傳進去。
+**View 走 `Intl.DateTimeFormat`**(跨 locale 統一、12h/24h 支援)。`formatOptions` 透傳進去。
 
 ---
 
@@ -199,7 +199,7 @@ Panel 展開後的 column picker 結構:
 詳見 `../Field/field-controls.spec.md`(共用規則)。
 
 ### Empty 值
-`value={null}` / `value=""` / `value=undefined` 都視為空,trigger 顯示 `placeholder`。Display 模式空值顯示半形 `-`(對齊 `EMPTY_DISPLAY`,text-foreground)。
+`value={null}` / `value=""` / `value=undefined` 都視為空,trigger 顯示 `placeholder`。View 模式空值顯示半形 `-`(對齊 `EMPTY_DISPLAY`,text-foreground)。
 
 ### 驗證時機
 - **每次欄位選取(時 / 分 / 秒任一改變)當下即 commit value 給 `onChange`**(eager commit,非 OK 才送)。OK 鈕(「確定」)只負責關閉 Panel,不另行 commit。`此刻` 按鈕則一次 commit 當前時間並關閉 Panel
@@ -214,6 +214,7 @@ N/A — TimePicker 是純同步輸入,無 async 狀態。
 ## A11y 預設
 
 - trigger `role="combobox"`,在 `<Field>` 內時以 `aria-labelledby` 指向 field label(`fieldCtx.labelId`)
+- **Standalone(無 `<Field>` 包裹)accessible name**:trigger 無預設 `aria-label`,`<Field>` 外使用時 consumer **必須**自帶 `aria-label` 或 `aria-labelledby`,否則 `role="combobox"` 成為無名稱控件(對齊 Select / Combobox / DatePicker 同家族 standalone 約定)。DS 不為 trigger 塞泛用 fallback name(如「時間」),避免遮蔽 consumer 的具體語意(如「會議開始時間」);Field 內則自動接線無需 consumer 介入。Panel 本體(Popover dialog)另有本 DS 提供的 `aria-label="選擇時間"`,與 trigger name 職責分離
 - Panel 開啟時 trigger `aria-expanded="true"` + `aria-haspopup="dialog"`
 - 每欄 `role="listbox"`(`aria-label` 為 `hours` / `minutes` / `seconds`),item `role="option" aria-selected`
 - Screen reader 經 trigger 的 label + 內層可見值文字朗讀目前選取時間(目前值以可見 `<span>` 呈現,無額外 `aria-valuetext`)
@@ -272,9 +273,9 @@ trigger 的互動狀態(focus / invalid / disabled / readonly)完全繼承 `../F
 
 ## 邊界案例
 
-- **Disabled**:Field SSOT own;trigger 自動 disabled(`text-fg-disabled` + 不開 picker),Display mode + disabled 維持時間格式但 token 切 disabled。
+- **Disabled**:Field SSOT own;trigger 自動 disabled(`text-fg-disabled` + 不開 picker)。顯式 `mode` 優先於 `disabled` prop(`useResolvedFieldMode` prop > disabled),view 分支無 disabled token 邏輯——要 disabled 視覺走 `mode="disabled"`(readonly/disabled 分支 `text-fg-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 顯半形 `-`(hyphen + `text-foreground`,disabled → fg-disabled)對齊 Input display empty 慣例。
+- **Empty(no value)**:`value=null` 為合法 initial state,trigger 顯 placeholder;**未傳 `placeholder` 時 default = 格式遮罩**(`HH:MM`,showSeconds=true 時 `HH:MM:SS`),非固定文案。`null` + view mode 顯半形 `-`(hyphen + `text-foreground`;`mode="disabled"` → fg-disabled)對齊 Input view 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.stories.tsx

@@ -27,7 +27,7 @@ export default meta
 
 type Story = StoryObj<typeof TimePicker>
 
-// @story-trait-rationale: pre-existing trait gaps tracked separately; this PR scope = add Modes story with display card.
+// @story-trait-rationale: pre-existing trait gaps tracked separately; this PR scope = add Modes story with view card.
 /* ── 四模式 ── */
 export const Modes: Story = {
   name: '四模式',
@@ -38,8 +38,8 @@ export const Modes: Story = {
         <TimePicker value="14:30" onChange={() => {}} aria-label="會議時段(edit mode demo)" />
       </div>
       <div>
-        <h3 className="text-body font-bold text-foreground mb-2">display</h3>
-        <TimePicker mode="display" value="14:30" aria-label="會議時段(display mode demo)" />
+        <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+        <TimePicker mode="view" value="14:30" aria-label="會議時段(view 模式示範)" />
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>

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

@@ -63,7 +63,7 @@ export interface TimeFormatOptions {
 }
 
 // 2026-07-06 D3 perf:Intl.DateTimeFormat 是標準庫最貴 constructor 之一(locale data
-// resolution)。formatTime 無 cheap path,display/readonly/edit 每 render 必建;DataTable time 欄
+// resolution)。formatTime 無 cheap path,view/readonly/edit 每 render 必建;DataTable time 欄
 // 轉發 config 時每 cell × 每次表格 re-render 重建。module-level cache 重用實例(DateTimeFormat
 // 無狀態可安全重用),key = locale|JSON.stringify(options)。行為 Δ=0。
 const dtfCache = new Map<string, Intl.DateTimeFormat>()
@@ -109,7 +109,10 @@ export interface TimePickerProps
   extends TimeFormatOptions,
     Omit<
       React.HTMLAttributes<HTMLDivElement>,
-      'onChange' | 'placeholder'
+      // 'defaultValue' 明確排除:本元件 controlled-only(time-picker.spec.md「Controlled-only
+      // rationale」),不支援 uncontrolled 初始值 — 若不 Omit,HTMLAttributes 會讓 defaultValue
+      // 通過型別卻靜默無效(不初始化 draft),與 spec contract 矛盾。
+      'onChange' | 'placeholder' | 'defaultValue'
     > {
   mode?: FieldMode
   /** Field chrome variant. Default = context.variant ?? 'default'. Per-prop override. */
@@ -141,9 +144,9 @@ export interface TimePickerProps
    */
   endIcon?: LucideIcon | null
   /**
-   * Display 是否渲 endIcon + Field naked wrapper(D-path opt-in,2026-05-08)
-   * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 span,backward compat)。
-   * 設 true 時 display 也走 fieldWrapperStyles(naked variant)+ ItemSuffix Clock,
+   * View 態是否渲 endIcon + Field naked wrapper(D-path opt-in,2026-05-08)
+   * — DataTable cell view↔edit 像素級對齊用。預設 false(裸 span,backward compat)。
+   * 設 true 時 view 也走 fieldWrapperStyles(naked variant)+ ItemSuffix Clock,
    * 與 edit 同 DOM 結構,消除 Layer-B padding mismatch。
    */
   showDisplayEndIcon?: boolean
@@ -188,7 +191,7 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
     const size = useResolvedFieldSize(sizeProp)  // B 組 cascade fix
     const error = useResolvedFieldInvalid(errorProp)
     const disabled = useResolvedFieldDisabled(disabledProp)
-    // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="display"> 漏 cascade
+    // 2026-06-08 SSOT:mode 經 useResolvedFieldMode;修 <Field mode="view"> 漏 cascade
     const resolvedMode = useResolvedFieldMode({ mode, disabled })
     const emptyDisplay = useFieldEmptyDisplay()
     const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
@@ -252,21 +255,25 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
       setOpen(false)
     }
 
-    // mode='display'(Phase B2 2026-05-05):純內容輸出 — 對齊原 TimePickerDisplay sub-component(retired)。
+    // mode='view'(Phase B2 2026-05-05):純內容輸出 — 對齊原 TimePickerDisplay sub-component(retired)。
     //   Default(showDisplayEndIcon=false):無 Field wrapper / 無 Clock icon — backward compat 裸 span。
     //   Opt-in(showDisplayEndIcon=true,2026-05-08 D-path):Field naked wrapper + ItemSuffix Clock,
-    //   與 edit 同結構消除 cell display↔edit 像素偏移(Layer-B padding mismatch)。
-    if (resolvedMode === 'display') {
+    //   與 edit 同結構消除 cell view↔edit 像素偏移(Layer-B padding mismatch)。
+    if (resolvedMode === 'view') {
+      // 2026-07-16 DA3 fix:view 分支補 {...props} spread(aria-label 等 DOM attr 原本靜默丟失;
+      // Switch 同型 2026-07-04 已修,本檔漏 — M10 同型)。
       if (!showDisplayEndIcon) {
-        // 2026-05-14 I2 fix(spec contract (e) display typography canonical):bare span 套
+        // 2026-05-14 I2 fix(spec contract (e) view typography canonical):bare span 套
         // `fieldDisplayTextClass(size)`(sm/md→text-body,lg→text-body-lg)— 對齊 Field family 統一。
-        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>
+        if (!value) return <span {...props} ref={ref as React.Ref<HTMLSpanElement>} className={cn(fieldDisplayTextClass(size), fieldEmptyColorClass(resolvedMode), className)}>{emptyDisplay}</span>
+        return <span {...props} ref={ref as React.Ref<HTMLSpanElement>} className={cn(fieldDisplayTextClass(size), 'truncate', className)}>{formatTime(value, { formatOptions, locale })}</span>
       }
       return (
         <div
-          className={cn(fieldWrapperStyles({ mode: 'display', variant, size }), className)}
-          data-field-mode="display"
+          ref={ref}
+          {...props}
+          className={cn(fieldWrapperStyles({ mode: 'view', variant, size }), className)}
+          data-field-mode="view"
         >
           <span className={cn(bareInputStyles, 'flex-1 min-w-0 truncate', !value && fieldEmptyColorClass(resolvedMode))}>
             {value ? formatTime(value, { formatOptions, locale }) : emptyDisplay}
@@ -284,6 +291,9 @@ const TimePicker = React.forwardRef<HTMLDivElement, TimePickerProps>(
     if (!isEditable) {
       return (
         <div
+          // 2026-07-16 DA3 fix:非-edit 分支補 ref 轉發(forwardRef<HTMLDivElement> 原本只有 edit
+          // 與 bare-span view 接 ref,readonly/disabled 及 endIcon-view div 靜默丟失 — 同 view props 漏接)。
+          ref={ref}
           className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: variant, size }), className)}
           data-field-mode={resolvedMode}
           aria-disabled={resolvedMode === 'disabled' ? true : undefined}

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

@@ -45,7 +45,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Components/Toast/展示" name="有標題與描述"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">有 Title + Description</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Components/Toast/展示" name="互動測試"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">互動測試</span></LinkTo>
+          <LinkTo kind="Design System/Components/Toast/展示" name="點擊觸發通知"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">點擊觸發通知</span></LinkTo>
         </li>
       </ul>
       <p className="text-fg-muted mt-3">判斷不確定時:先看下方「何時用 / 何時不用」的對照;若訊息重要到使用者必須看到、或需要使用者確認,就不該用 Toast,改用 Alert(持久顯示)或 Dialog(阻斷確認)。</p>

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

@@ -116,7 +116,7 @@ export const WithDescription = {
 }
 
 export const Interactive = {
-  name: '互動測試',
+  name: '點擊觸發通知',
   render: () => (
     <div className="flex flex-col gap-4">
       <span className="text-caption text-fg-muted">點按鈕觸發 Toast</span>

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

@@ -245,9 +245,9 @@ const InspectorInner = () => {
           <div className="px-16 py-16 rounded-lg bg-canvas border border-divider flex items-center justify-center">
             <Tooltip defaultOpen>
               <TooltipTrigger asChild>
-                <Button variant="secondary" startIcon={Settings} size="sm">觸發器</Button>
+                <Button variant="secondary" startIcon={Settings} size="sm">欄位設定</Button>
               </TooltipTrigger>
-              <TooltipContent side={side}>提示文字</TooltipContent>
+              <TooltipContent side={side}>調整資料表的欄位顯示與排序</TooltipContent>
             </Tooltip>
           </div>
 
@@ -351,7 +351,15 @@ export const Inspector = {
 
 export const PlacementReference = {
   name: '方向與間距',
-  render: () => (
+  render: () => {
+    // 四方向以工具列常見操作示範,方位由外部 mono 標籤標示,Tooltip 提供對應說明。
+    const placementDemo: Record<SideKey, { label: string; tip: string }> = {
+      top: { label: '複製連結', tip: '複製此頁面的公開分享連結' },
+      right: { label: '封存專案', tip: '封存後移至封存區，隨時可還原' },
+      bottom: { label: '重新整理', tip: '重新載入最新資料' },
+      left: { label: '更多操作', tip: '檢視全部可用的操作' },
+    }
+    return (
     <div className="flex flex-col gap-8">
       <div className="flex flex-col gap-1">
         <H3>四方向 Placement</H3>
@@ -365,9 +373,9 @@ export const PlacementReference = {
             <div className="px-8 py-8 rounded-lg bg-canvas border border-divider flex items-center justify-center w-full">
               <Tooltip defaultOpen>
                 <TooltipTrigger asChild>
-                  <Button variant="tertiary" size="sm">{s}</Button>
+                  <Button variant="tertiary" size="sm">{placementDemo[s].label}</Button>
                 </TooltipTrigger>
-                <TooltipContent side={s}>提示文字</TooltipContent>
+                <TooltipContent side={s}>{placementDemo[s].tip}</TooltipContent>
               </Tooltip>
             </div>
           </div>
@@ -397,7 +405,8 @@ export const PlacementReference = {
         <Desc>transform-origin 使用 --radix-tooltip-content-transform-origin，zoom 效果從觸發器方向展開。</Desc>
       </div>
     </div>
-  ),
+    )
+  },
 }
 
 // ── Accessibility ─────────────────────────────────────────────────────────

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

@@ -52,7 +52,7 @@ export const UsageGuidance: Story = {
               <LinkTo kind="Design System/Components/Tooltip/展示" name="非 Button 元素"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">非 Button 元素</span></LinkTo>
             </li>
             <li>
-              <LinkTo kind="Design System/Components/Tooltip/展示" name="方向"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">方向</span></LinkTo>
+              <LinkTo kind="Design System/Components/Tooltip/展示" name="基本用法"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">基本用法</span></LinkTo>
             </li>
             <li>
               <LinkTo kind="Design System/Components/Tooltip/展示" name="長文字"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">長文字</span></LinkTo>
@@ -189,13 +189,13 @@ export const NeedsTooltipRule: Story = {
         title="✅ 截斷文字用 tooltip 顯示完整內容(僅當實際被截斷時)"
         note="Tooltip 是資訊補救 — 文字被 truncate 時才顯示完整內容。沒被截斷就不該顯示 tooltip(避免過度互動)"
       >
-        <Tooltip>
+        <Tooltip defaultOpen>
           <TooltipTrigger asChild>
             <div className="w-32 truncate px-3 py-1 border border-border rounded-md cursor-default">
-              非常長的專案名稱會被截斷
+              2026 亞洲市場品牌改版與官網重構
             </div>
           </TooltipTrigger>
-          <TooltipContent>非常長的專案名稱會被截斷顯示完整版</TooltipContent>
+          <TooltipContent>2026 亞洲市場品牌改版與官網重構</TooltipContent>
         </Tooltip>
         <Label>↑ 模式示意（此靜態範例恆顯示；實務上應偵測文字真被截斷 `scrollWidth &gt; clientWidth` 時才掛 tooltip）</Label>
       </Rule>

package/src/components/Tooltip/tooltip.spec.md

@@ -55,7 +55,11 @@ Tooltip 的判斷標準是：**畫面上的資訊是否已經足夠讓使用者
 
 ## 與 Button icon-only 的關係
 
-Button 的 `iconOnly` 模式已內建自動 tooltip（以 `aria-label` 驅動），開發者不需要額外包 `<Tooltip>`。只有在非 Button 元素需要 tooltip 時，才手動使用 Tooltip 元件。
+Button 的 `iconOnly` 模式已內建自動 tooltip（以 `aria-label` 驅動），開發者不需要額外包 `<Tooltip>`。
+
+**例外——`iconOnly` + `asChild`**：當 `iconOnly` 同時搭配 `asChild` 時，內建 tooltip wrapper **不啟動**（Radix Slot 只接受單一 child，Button 主動補 tooltip 會破壞單 child 規則）。此時 consumer 必須**自行傳入 child 的 `aria-label`** 給螢幕閱讀器，並視需要自行包 `<Tooltip>`（見 `../Button/button.spec.md` 與 `button.tsx` 的 asChild 警告）。
+
+只有在非 Button 元素需要 tooltip 時，才手動使用 Tooltip 元件。
 
 ## 內容完整性
 
@@ -90,6 +94,7 @@ Tooltip 最大寬度 **280px**（見 `.tsx` 的 `max-w-[280px]`）——超過
 - **觸控裝置**:無 hover,tooltip 無法觸發——必要資訊不可只靠 tooltip 承載(見「何時不用」「禁止事項」)
 - **長文字**:超過 max-width 280px 自動換行、完整呈現不截斷(見「最大寬度」「內容完整性」)
 - **貼近 viewport 邊**:Radix 自動翻邊 + `collisionPadding` 8px 呼吸距離(見「Edge collision」)
+- **空內容**:`TooltipContent` 的 `children` 為 `null` / `undefined` / `false` / 空字串時**不掛浮層**——不渲染帶 padding 的空 `role="tooltip"` 殼,trigger 原樣保留。Tooltip 是資訊補救機制(見「何時用」),沒有補充內容就不該出現。實作於 `tooltip.tsx` 的 `TooltipContent` 以空值 guard 提早 return null 落地
 
 ## 禁止事項
 
@@ -98,6 +103,7 @@ Tooltip 最大寬度 **280px**（見 `.tsx` 的 `max-w-[280px]`）——超過
 - ❌ 不要把 tooltip 當作必要資訊的唯一載體——tooltip 需要 hover 才能看到，觸控裝置無法觸發
 - ❌ 不要為個別 tooltip 設定不同的延遲時間——全產品統一一組參數
 - ❌ 不要在 tooltip 內截斷資訊——tooltip 是資訊終點，內容必須完整
+- ❌ 不要對 `TooltipContent` 傳空內容——空 tooltip 是無意義的視覺雜訊(空值時元件不掛浮層,見「邊界狀態」)
 
 ---
 
@@ -105,11 +111,11 @@ Tooltip 最大寬度 **280px**（見 `.tsx` 的 `max-w-[280px]`）——超過
 
 Tooltip 是**單一職責 hover 提示 primitive**(一句話補充),刻意無變體:
 
-- **無 ColorMatrix**:Tooltip 固定一種視覺(dark surface + white text,跟頁面主題反轉),無 variant / severity / hue。若需要有色 hint,那是 Popover / HoverCard 的職責。Dark mode 自動由 inverse theme 處理。故無 color matrix。
+- **無 ColorMatrix**:Tooltip 固定一種視覺(`--tooltip` bg + white text,內部 wrapper 強制 `data-theme="dark"`——不隨頁面主題反轉,dark mode 下 `--tooltip` 有自己的深色值),無 variant / severity / hue。若需要有色 hint,那是 Popover / HoverCard 的職責。故無 color matrix。
 - **無 SizeMatrix**:Tooltip 無 size prop,尺寸由內容 + max-width 常數決定(本 spec「最大寬度」段)。不提供 sm/md/lg tier——短文字 hint 不需要尺寸變體。
 - **無 StateBehavior**:Tooltip 是 passive 出現 / 消失(hover / focus 觸發,見「出現時機」段),無 hover / selected / active / disabled 這類互動元件 state。開 / 關行為由 Radix primitive 處理,寫在 `Overview` 的 usage 說明已足夠。
 
-對應 anatomy story:保留 `Overview` + `Inspector`(delay / placement 互動試玩) + 元件特有 `PlacementReference`(4 種 side 方向對照 + side-aware 動畫表;Tooltip 走 `align="center"` 輕量浮層例外,見「Align 對齊」段,無 align 軸矩陣)。
+對應 anatomy story:保留 `Overview` + `Inspector`(side 切換 + token 對照) + 元件特有 `PlacementReference`(4 種 side 方向對照 + side-aware 動畫表;Tooltip 走 `align="center"` 輕量浮層例外,見「Align 對齊」段,無 align 軸矩陣)。
 
 ---
 

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

@@ -70,7 +70,7 @@ export const LongText: Story = {
     <Tooltip defaultOpen>
       <TooltipTrigger asChild>
         <Button variant="secondary" startIcon={Info}>
-          長文字提示
+          API 金鑰安全說明
         </Button>
       </TooltipTrigger>
       <TooltipContent>

package/src/components/Tooltip/tooltip.tsx

@@ -23,7 +23,16 @@ const TooltipTrigger = TooltipPrimitive.Trigger
 const TooltipContent = React.forwardRef<
   React.ElementRef<typeof TooltipPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
->(({ className, sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = OVERLAY_COLLISION_PADDING, style, children, ...props }, ref) => (
+>(({ className, sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = OVERLAY_COLLISION_PADDING, style, children, ...props }, ref) => {
+  // 空內容不掛浮層:children 為 null / undefined / false / 空字串時不渲染帶 padding 的空
+  // role="tooltip" 殼(見 spec「邊界狀態」)。Tooltip 是資訊補救機制,無補充內容即不出現,
+  // trigger 由 TooltipTrigger 原樣保留。
+  const isEmptyContent =
+    children == null ||
+    children === false ||
+    (typeof children === 'string' && children.trim() === '')
+  if (isEmptyContent) return null
+  return (
   // collisionPadding default 8px:避免 tooltip 貼 viewport 邊(Radix avoidCollisions 預設 true 但 padding 0 會貼邊)
   // 消費 OVERLAY_COLLISION_PADDING overlay 家族 canonical(與 Popover 一致;HoverCard 特例 12 補 rounding)避免 viewport edge clipping
   <TooltipPrimitive.Portal>
@@ -48,7 +57,8 @@ const TooltipContent = React.forwardRef<
       <div data-theme="dark" className="contents">{children}</div>
     </TooltipPrimitive.Content>
   </TooltipPrimitive.Portal>
-))
+  )
+})
 TooltipContent.displayName = TooltipPrimitive.Content.displayName
 
 // Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)

package/src/components/TreeView/tree-view.anatomy.stories.tsx

@@ -283,11 +283,11 @@ export const ColorMatrix: Story = {
           <H3>Hover + Selected 並存的實際渲染</H3>
           <Desc>以下 `Documents/Photos/beach.jpg` 為 selected row,可 hover 任一其他 row 觀察 neutral-hover。</Desc>
           <div className="border border-border rounded-lg p-4 max-w-md">
-            <TreeView selectedIds={selected} onSelectedChange={setSelected} defaultExpandedIds={['docs', 'photos']}>
-              <TreeItem id="docs" label="Documents(hover 試試)" icon={Folder}>
+            <TreeView aria-label="色彩狀態範例檔案樹" selectedIds={selected} onSelectedChange={setSelected} defaultExpandedIds={['docs', 'photos']}>
+              <TreeItem id="docs" label="Documents" icon={Folder}>
                 <TreeItem id="resume" label="Resume.pdf" icon={FileText} />
                 <TreeItem id="photos" label="Photos" icon={Folder}>
-                  <TreeItem id="beach" label="beach.jpg(selected)" icon={Image} />
+                  <TreeItem id="beach" label="beach.jpg" icon={Image} />
                   <TreeItem id="trip" label="trip.jpg" icon={Image} />
                 </TreeItem>
               </TreeItem>
@@ -307,11 +307,11 @@ export const IndentMatrix: Story = {
         <H3>indentStep = chevronSize + gap-2</H3>
         <Desc>每層 indent 剛好是 chevron(16 / 20px)+ gap-2(8px)的距離——跟 item-layout 的 prefix-content gap 一致。讓 tree indent 視覺跟 item-layout 融為一體,不是獨立數字系統。</Desc>
         <div className="border border-border rounded-lg p-4 max-w-md">
-          <TreeView defaultExpandedIds={['l1', 'l2', 'l3']}>
-            <TreeItem id="l1" label="L1 (depth 0)" icon={Folder}>
-              <TreeItem id="l2" label="L2 (depth 1)" icon={Folder}>
-                <TreeItem id="l3" label="L3 (depth 2)" icon={Folder}>
-                  <TreeItem id="l4" label="L4 (depth 3)" icon={FileText} />
+          <TreeView aria-label="品牌資產資料夾樹" defaultExpandedIds={['brand', 'website', 'images']}>
+            <TreeItem id="brand" label="品牌資產" icon={Folder}>
+              <TreeItem id="website" label="網站" icon={Folder}>
+                <TreeItem id="images" label="圖片" icon={Folder}>
+                  <TreeItem id="hero" label="首頁橫幅.png" icon={Image} />
                 </TreeItem>
               </TreeItem>
             </TreeItem>
@@ -323,15 +323,17 @@ export const IndentMatrix: Story = {
         <H3>葉節點 chevron placeholder</H3>
         <Desc>同層有展開 icon、有的沒有 → label 不會對齊。TreeView 自動給葉節點留透明 chevron placeholder,label 永遠對齊 column。</Desc>
         <div className="border border-border rounded-lg p-4 max-w-md">
-          <TreeView defaultExpandedIds={['folder']}>
-            <TreeItem id="folder" label="Folder(可展開)" icon={Folder}>
-              <TreeItem id="leaf-1" label="Leaf 1(無 children)" icon={FileText} />
-              <TreeItem id="folder-2" label="Folder 2(可展開)" icon={Folder} />
-              <TreeItem id="leaf-3" label="Leaf 3(無 children)" icon={FileText} />
+          <TreeView aria-label="設計交付資料夾樹" defaultExpandedIds={['delivery']}>
+            <TreeItem id="delivery" label="設計交付" icon={Folder}>
+              <TreeItem id="spec" label="元件規格.pdf" icon={FileText} />
+              <TreeItem id="assets" label="切版素材" icon={Folder}>
+                <TreeItem id="icons" label="圖示集.svg" icon={Image} />
+              </TreeItem>
+              <TreeItem id="checklist" label="交付清單.md" icon={FileText} />
             </TreeItem>
           </TreeView>
         </div>
-        <p className="text-footnote text-fg-muted mt-3">↑ 葉 / 資料夾 label 左側對齊 — 不會因有無 chevron 位移</p>
+        <p className="text-footnote text-fg-muted mt-3">↑ 葉節點(元件規格.pdf / 交付清單.md)與可展開資料夾(切版素材)label 左側對齊 — 不因有無 chevron 位移</p>
       </div>
     </div>
   ),

package/src/components/TreeView/tree-view.principles.stories.tsx

@@ -78,9 +78,24 @@ export const UsageGuidance: Story = {
       <Section title="何時不用 + 替代方案">
         <Rule
           title='❌ 互斥展開(同時只開一個):用 Accordion type="single"'
-          note="TreeView 預設允許任意多個節點同時展開。若需要「選一個展開其他自動收」的互斥語意,用 Accordion(非 TreeView)"
+          note='TreeView 預設允許任意多個節點同時展開。平面設定分段若需要「展開一個、其他自動收合」的互斥語意,用 Accordion type="single"(非 TreeView)'
         >
-          <Label warn>(範例省略)TreeView 是多展開,Accordion 是單展開,語意不同</Label>
+          <div className="border border-border rounded-lg p-3 w-80">
+            <TreeView aria-label="帳號設定分段" selectionMode="none" defaultExpandedIds={['account', 'notify', 'privacy']}>
+              <TreeItem id="account" label="帳號設定">
+                <TreeItem id="account-email" label="電子郵件" />
+                <TreeItem id="account-password" label="密碼" />
+              </TreeItem>
+              <TreeItem id="notify" label="通知偏好">
+                <TreeItem id="notify-email" label="信件通知" />
+                <TreeItem id="notify-push" label="推播通知" />
+              </TreeItem>
+              <TreeItem id="privacy" label="隱私與安全">
+                <TreeItem id="privacy-2fa" label="兩步驟驗證" />
+              </TreeItem>
+            </TreeView>
+          </div>
+          <Label warn>↑ 三個設定分段在 TreeView 裡可同時展開;要「展開一個自動收其他」的互斥手風琴,用 Accordion type="single"</Label>
         </Rule>
       </Section>
 
@@ -101,10 +116,10 @@ export const UsageGuidance: Story = {
         </Rule>
 
         <Rule
-          title="❌ Sidebar 的簡單 2 層 nav:用 Sidebar 內建結構"
-          note="Sidebar 的 SidebarMenuSub 已處理「主項目 + 子項目」2 層結構。只有深度 ≥ 3 層或 user data 樹才用 TreeView"
+          title="❌ 純視覺分段(設計時可列舉的固定選單):用 SidebarGroup 不用 TreeView"
+          note="Sidebar 主選單只接受 1 層可列舉項目——設計時就固定死、不會 runtime 新增的分段,用 SidebarGroup 純視覺分段即可。真階層 user data(專案 / 子專案、部門樹,即使只有 2 層、未來會長)才用 TreeView(見 sidebar.spec.md「判斷規則」)"
         >
-          <Label warn>2 層 nav 用 Sidebar 的 Sub Menu 足夠,不需要 TreeView 的遞迴 overhead</Label>
+          <Label warn>固定分段用 SidebarGroup 就夠,不需要 TreeView 的遞迴 overhead;user data 樹則一律 TreeView</Label>
         </Rule>
       </Section>
     </div>
@@ -174,16 +189,34 @@ export const IndentRule: Story = {
         note="同層 siblings 有展開 icon、有的沒有 → label 不對齊。TreeView 自動給葉節點留 chevron 位置(透明 placeholder),consumer 不需介入"
       >
         <div className="border border-border rounded-lg p-3 w-80">
-          <TreeView defaultExpandedIds={['fa', 'sub']}>
-            <TreeItem id="fa" label="資料夾 A" icon={Folder}>
-              <TreeItem id="file-a" label="檔案 a.txt" icon={FileText} />
-              <TreeItem id="sub" label="子資料夾" icon={Folder}>
-                <TreeItem id="file-b" label="檔案 b.txt" icon={FileText} />
+          <TreeView aria-label="行銷素材資料夾樹" defaultExpandedIds={['assets', 'social']}>
+            <TreeItem id="assets" label="行銷素材" icon={Folder}>
+              <TreeItem id="hero" label="活動主視覺.png" icon={Image} />
+              <TreeItem id="social" label="社群貼文" icon={Folder}>
+                <TreeItem id="story" label="限動範本.psd" icon={FileText} />
               </TreeItem>
             </TreeItem>
           </TreeView>
         </div>
-        <Label>↑ 「檔案 a.txt」是葉,「子資料夾」可展開——兩者 label 依然垂直對齊</Label>
+        <Label>↑ 「活動主視覺.png」是葉,「社群貼文」可展開——兩者 label 依然垂直對齊</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 混用有 icon / 無 icon 的節點"
+        note="Chevron 有自動佔位(leaf 也留等寬空白),但 icon 無自動佔位——同層有些節點傳 icon、有些沒傳,label 起點會直接錯開。要嘛全傳 icon,要嘛全不傳(見 spec「Icon 一致性原則」)"
+      >
+        <div className="border border-border rounded-lg p-3 w-80">
+          <TreeView aria-label="icon 混用反例檔案樹" defaultExpandedIds={['src', 'public']}>
+            <TreeItem id="src" label="src" icon={Folder}>
+              <TreeItem id="app" label="App.tsx" icon={FileText} />
+              <TreeItem id="readme" label="README.md" />
+            </TreeItem>
+            <TreeItem id="public" label="public">
+              <TreeItem id="favicon" label="favicon.ico" icon={Image} />
+            </TreeItem>
+          </TreeView>
+        </div>
+        <Label warn>↑ 「README.md」「public」沒傳 icon → label 起點比有 icon 的節點前移,視覺節奏錯開</Label>
       </Rule>
     </div>
   ),