@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

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

@@ -0,0 +1,422 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+// @anatomy-rationale:
+//   ColorMatrix N/A — Tooltip 色彩固定(--tooltip bg + white text,內部 wrapper
+//     強制 data-theme="dark"),無 variant × state 色彩矩陣。所有色彩 token 已
+//     於 Inspector「Token Details」面板列出。
+//   SizeMatrix N/A — Tooltip 不提供 size prop;尺寸固定 text-body(14px)+
+//     px-3 py-2 + max-w-[280px],對齊 Polaris / Material / Atlassian「tooltip
+//     是 micro UI、不縮放」共識。
+//   StateBehavior represented as PlacementReference + Inspector — Tooltip 無
+//     hover / focus / active(自身就是 hover affordance);實際行為差異在
+//     placement(top / right / bottom / left + 動畫方向)由 PlacementReference(3.)
+//     涵蓋,warm-up timing 由 Overview 段落涵蓋。
+import type { Meta } from '@storybook/react'
+import { useState } from 'react'
+import { Info, Settings } from 'lucide-react'
+import { Tooltip, TooltipContent, TooltipTrigger } from './tooltip'
+import { Button } from '../Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/Tooltip/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Shared UI Components
+
+   NOTE: Kept local (not imported from `_anatomy/anatomy-utils`) because the
+   Button-family inspector layout diverges visually from the 通用 helpers:
+   H3 `text-h6 font-semibold` (not `text-body font-bold mb-2`), Desc has no
+   bottom margin, Th/Td use `p-2 border-b border-divider` row style, and
+   Swatch defaults to `size="md"` for inline token chips.
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+const H3 = ({ children }: { children: React.ReactNode }) => (
+  <h3 className="text-h6 font-semibold text-foreground">{children}</h3>
+)
+const Desc = ({ children }: { children: React.ReactNode }) => (
+  <p className="text-caption text-fg-muted max-w-[720px]">{children}</p>
+)
+const Th = ({ children }: { children: React.ReactNode }) => (
+  <th className="text-left p-2 border-b border-divider text-fg-muted font-medium text-caption whitespace-nowrap">{children}</th>
+)
+const Td = ({ children, mono }: { children: React.ReactNode; mono?: boolean }) => (
+  <td className={`p-2 border-b border-divider align-top whitespace-nowrap text-caption ${mono ? 'font-mono' : ''}`}>{children}</td>
+)
+
+/** Token name (primary) + resolved value (secondary) */
+const TkVal = ({ token, value }: { token: string; value?: string }) => (
+  <div className="flex flex-col gap-0.5">
+    <span className="font-mono text-[12px] text-fg-secondary">{token}</span>
+    {value && <span className="font-mono text-[10px] text-fg-muted">{value}</span>}
+  </div>
+)
+
+const Swatch = ({ value, size = 'md' }: { value: string; size?: 'sm' | 'md' }) => {
+  const s = size === 'sm' ? 'w-3 h-3' : 'w-4 h-4'
+  if (value === 'transparent') {
+    return <span className={`${s} rounded-md shrink-0 border border-border`}
+      style={{ backgroundImage: 'linear-gradient(45deg,#ddd 25%,transparent 25%,transparent 75%,#ddd 75%),linear-gradient(45deg,#ddd 25%,transparent 25%,transparent 75%,#ddd 75%)', backgroundSize: '6px 6px', backgroundPosition: '0 0,3px 3px' }} />
+  }
+  return <span className={`${s} rounded-md shrink-0 border border-black/10`} style={{ backgroundColor: `var(${value})` }} />
+}
+
+const Tab = ({ active, onClick, children }: { active: boolean; onClick: () => void; children: React.ReactNode }) => (
+  <button type="button" onClick={onClick}
+    className={`px-2.5 py-1 text-[12px] font-mono rounded-md cursor-pointer transition-colors ${
+      active ? 'bg-primary text-white font-semibold' : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
+    }`}>
+    {children}
+  </button>
+)
+
+const PropRow = ({ label, dot, children }: { label: string; dot?: string; children: React.ReactNode }) => (
+  <div className="flex items-start gap-3 py-2 border-b border-divider last:border-b-0">
+    <span className="text-[11px] text-fg-muted font-medium w-[72px] shrink-0 pt-0.5 flex items-center gap-1.5">
+      {dot && <span className="w-2 h-2 rounded-full shrink-0" style={{ backgroundColor: dot }} />}
+      {label}
+    </span>
+    <div className="flex-1 text-[12px] font-mono text-fg-secondary">{children}</div>
+  </div>
+)
+
+/* Zone colors for blueprint */
+const Z = {
+  pad:     { bg: 'rgba(194,225,154,0.6)', border: 'rgba(139,179,91,0.9)', text: '#5a7a2e' },
+  content: { bg: 'rgba(199,178,230,0.6)', border: 'rgba(138,103,190,0.9)', text: '#6035a8' },
+  gap:     { bg: 'rgba(253,218,158,0.6)', border: 'rgba(218,165,60,0.9)', text: '#8a6010' },
+  trigger: { bg: 'rgba(166,208,245,0.6)', border: 'rgba(80,145,210,0.9)', text: '#2d6a9f' },
+  dim:     { text: '#d04040' },
+}
+
+const BpZone = ({ w, h, color, label, sub }: { w: number; h?: number; color: typeof Z.pad; label: string; sub?: string }) => (
+  <div className="flex flex-col items-center justify-center shrink-0 gap-0.5"
+    style={{ width: w, height: h ?? '100%', background: color.bg, borderLeft: `1.5px dashed ${color.border}`, borderRight: `1.5px dashed ${color.border}` }}>
+    <span className="text-[11px] font-mono font-bold leading-none" style={{ color: color.text }}>{label}</span>
+    {sub && <span className="text-[9px] font-mono leading-none opacity-70" style={{ color: color.text }}>{sub}</span>}
+  </div>
+)
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   1. 元件總覽
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const Overview = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      {/* Anatomy */}
+      <div className="flex flex-col gap-4">
+        <div className="flex flex-col gap-1">
+          <H3>結構（Anatomy）</H3>
+          <Desc>Tooltip 由三個部分組成：觸發器（Trigger）、浮動內容區（Content）、以及連接兩者的間距（sideOffset）。Content 內有 data-theme="dark" wrapper，子元素自動適配深色背景。</Desc>
+        </div>
+        <div className="flex gap-8 items-start">
+          {/* Anatomy diagram */}
+          <div className="flex flex-col items-center gap-0">
+            {/* Content */}
+            <div className="inline-flex items-center border-2 border-dashed border-primary/30 rounded-md px-3 py-2">
+              {[
+                { name: 'Content', color: 'info' },
+              ].map((s) => (
+                <span key={s.name} className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
+                  style={{ borderColor: `var(--${s.color})`, backgroundColor: `var(--${s.color}-subtle)`, color: `var(--${s.color})` }}>{s.name}</span>
+              ))}
+            </div>
+            {/* sideOffset */}
+            <div className="flex flex-col items-center py-1">
+              <span className="text-[10px] font-mono text-fg-muted">sideOffset 8px</span>
+              <div className="w-px h-3 bg-divider" />
+            </div>
+            {/* Trigger */}
+            <div className="inline-flex items-center border-2 border-dashed rounded-md px-3 py-2"
+              style={{ borderColor: 'var(--success)' }}>
+              <span className="rounded px-2 py-1 text-[11px] font-mono border border-dashed"
+                style={{ borderColor: 'var(--success)', backgroundColor: 'var(--success-subtle)', color: 'var(--success)' }}>Trigger</span>
+            </div>
+            <span className="text-[10px] text-fg-muted font-mono mt-1">asChild — 套用至子元件</span>
+          </div>
+
+          {/* Live example */}
+          <div className="flex flex-col gap-2 items-start">
+            <span className="text-[11px] text-fg-muted font-medium">Live 範例</span>
+            <Tooltip defaultOpen>
+              <TooltipTrigger asChild>
+                <Button variant="secondary" startIcon={Info} size="sm">付款狀態</Button>
+              </TooltipTrigger>
+              <TooltipContent side="top">款項已於 2024/12/01 撥款至銀行帳戶</TooltipContent>
+            </Tooltip>
+          </div>
+        </div>
+      </div>
+
+      {/* Composition parts */}
+      <div className="flex flex-col gap-3">
+        <H3>組合零件</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>零件</Th><Th>元素</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              {[
+                ['TooltipProvider', '<TooltipPrimitive.Provider>', '全域 Provider，控制 skip window 與共享暖機狀態（全產品一個）；單一 tooltip 的 delay 由 Root 預設 500ms 決定，優先於 Provider'],
+                ['Tooltip', '<TooltipPrimitive.Root>', '單一 tooltip 實例的容器'],
+                ['TooltipTrigger', '<TooltipPrimitive.Trigger>', '觸發器，搭配 asChild 套用至任意子元素'],
+                ['TooltipContent', '<TooltipPrimitive.Content>', '浮動內容區，透過 Portal 渲染'],
+              ].map(([part, el, desc]) => (
+                <tr key={part}><Td mono>{part}</Td><Td mono>{el}</Td><Td>{desc}</Td></tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      {/* Props */}
+      <div className="flex flex-col gap-3">
+        <H3>Props（TooltipContent）</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              {[
+                ['side', "'top'|'right'|'bottom'|'left'", "'top'", '浮動方向'],
+                ['sideOffset', 'number', '8', '與觸發器的間距（px）'],
+                ['align', "'start'|'center'|'end'", "'center'", '沿 side 軸的對齊'],
+                ['className', 'string', '—', '額外 CSS class'],
+                ['children', 'ReactNode', '—', '提示文字內容'],
+              ].map(([p, t, d, desc]) => (
+                <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      {/* Warm-up pattern */}
+      <div className="flex flex-col gap-3">
+        <H3>Warm-up Pattern（暖機模式）</H3>
+        <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>
+            <span>首次 hover → 等待 <span className="font-mono text-fg-secondary">delayDuration={500}</span><span className="text-fg-muted"> (500ms)</span>，確認是刻意停留</span>
+          </div>
+          <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">2.</span>
+            <span>出現後移到下一個觸發器 → 在 <span className="font-mono text-fg-secondary">skipDelayDuration={300}</span><span className="text-fg-muted"> (300ms)</span> 窗口內即時切換</span>
+          </div>
+          <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">3.</span>
+            <span>離開所有觸發器超過 300ms → 冷卻，下次 hover 重新等待 500ms</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   2. 元件檢閱器
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+type SideKey = 'top' | 'right' | 'bottom' | 'left'
+
+const InspectorInner = () => {
+  const [side, setSide] = useState<SideKey>('top')
+
+  return (
+    <div className="flex flex-col gap-6">
+      {/* Controls */}
+      <div className="flex flex-col gap-2.5">
+        <div className="flex items-center gap-2">
+          <span className="text-[11px] text-fg-muted w-16 shrink-0">Side</span>
+          <div className="flex gap-1.5">
+            {(['top', 'right', 'bottom', 'left'] as const).map((s) => (
+              <Tab key={s} active={side === s} onClick={() => setSide(s)}>{s}</Tab>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      {/* Preview + Panel */}
+      <div className="flex gap-8 items-start">
+        {/* Left: live preview */}
+        <div className="flex flex-col gap-5 min-w-[340px]">
+          <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>
+              </TooltipTrigger>
+              <TooltipContent side={side}>調整資料表的欄位顯示與排序</TooltipContent>
+            </Tooltip>
+          </div>
+
+          {/* Blueprint: Content internal structure */}
+          <div className="flex flex-col gap-2">
+            <span className="text-[11px] text-fg-muted font-medium">Content 內部結構</span>
+            <div className="flex items-center gap-4 text-[10px]">
+              {[{ c: Z.pad, l: '水平內距' }, { c: Z.content, l: '文字' }, { c: Z.gap, l: '垂直內距' }].map(({ c, l }) => (
+                <span key={l} className="inline-flex items-center gap-1">
+                  <span className="w-2.5 h-2.5 rounded-md" style={{ background: c.bg, border: `1px dashed ${c.border}` }} />
+                  <span className="font-medium" style={{ color: c.text }}>{l}</span>
+                </span>
+              ))}
+            </div>
+            <div className="flex items-center">
+              <div className="flex items-center rounded-md overflow-hidden" style={{ height: 44, outline: `2px solid ${Z.dim.text}22` }}>
+                <BpZone w={44} color={Z.pad} label="px-3" sub="12px" />
+                <BpZone w={80} color={Z.content} label="text-body" sub="14px" />
+                <BpZone w={44} color={Z.pad} label="px-3" sub="12px" />
+              </div>
+              <div className="ml-3 flex items-center" style={{ height: 44 }}>
+                <svg width="10" height="44" className="shrink-0">
+                  <line x1="5" y1="2" x2="5" y2="42" stroke={Z.dim.text} strokeWidth="1" />
+                  <line x1="1" y1="2" x2="9" y2="2" stroke={Z.dim.text} strokeWidth="1.5" />
+                  <line x1="1" y1="42" x2="9" y2="42" stroke={Z.dim.text} strokeWidth="1.5" />
+                </svg>
+                <div className="ml-1.5"><TkVal token="py-2" value="8px top + 8px bottom" /></div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* Right: token panel */}
+        <div className="flex flex-col gap-0 min-w-[260px] border border-divider rounded-lg overflow-hidden">
+          <div className="px-3 py-2 bg-surface-raised border-b border-divider">
+            <span className="text-[12px] font-semibold text-fg-secondary">Token Details</span>
+          </div>
+
+          <div className="px-3 py-1">
+            <PropRow label="bg" dot="var(--tooltip)">
+              <span className="inline-flex items-center gap-2">
+                <Swatch value="--tooltip" />
+                <span>--tooltip</span>
+              </span>
+              <div className="text-[10px] text-fg-muted mt-0.5">light: --color-neutral-9-opaque</div>
+              <div className="text-[10px] text-fg-muted">dark: --color-neutral-5-opaque</div>
+            </PropRow>
+            <PropRow label="text">
+              <TkVal token="text-on-emphasis" value="白色（深底反白文字）" />
+            </PropRow>
+            <PropRow label="font">
+              <TkVal token="text-body" value="14px / font-normal" />
+            </PropRow>
+            <PropRow label="padding-x">
+              <TkVal token="px-3" value="12px" />
+            </PropRow>
+            <PropRow label="padding-y">
+              <TkVal token="py-2" value="8px" />
+            </PropRow>
+            <PropRow label="radius">
+              <TkVal token="rounded-md" value="4px (--radius-md)" />
+            </PropRow>
+            <PropRow label="max-width">
+              <TkVal token="max-w-[280px]" value="280px" />
+            </PropRow>
+            <PropRow label="sideOffset">
+              <TkVal token="sideOffset={8}" value="8px" />
+            </PropRow>
+            <PropRow label="shadow">
+              <TkVal token="--elevation-200" />
+            </PropRow>
+            <PropRow label="z-index">
+              <TkVal token="z-50" value="50" />
+            </PropRow>
+            <PropRow label="theme">
+              <span>data-theme="dark" (inner wrapper)</span>
+            </PropRow>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export const Inspector = {
+  name: '元件檢閱器',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-col gap-1">
+        <H3>元件檢閱器</H3>
+        <Desc>切換方向查看 tooltip 的 placement。右側面板列出主要 design token 及其對應值。</Desc>
+      </div>
+      <InspectorInner />
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   3. 方向與間距
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const PlacementReference = {
+  name: '方向與間距',
+  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>
+        <Desc>side 決定浮動方向，sideOffset 控制與觸發器的間距。Radix 自動處理碰撞偵測——空間不足時翻轉到對面。</Desc>
+      </div>
+
+      <div className="grid grid-cols-2 gap-6 max-w-[600px]">
+        {(['top', 'right', 'bottom', 'left'] as const).map((s) => (
+          <div key={s} className="flex flex-col gap-2 items-start">
+            <span className="text-[11px] font-mono text-fg-muted font-medium">side="{s}"</span>
+            <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">{placementDemo[s].label}</Button>
+                </TooltipTrigger>
+                <TooltipContent side={s}>{placementDemo[s].tip}</TooltipContent>
+              </Tooltip>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {/* Animation */}
+      <div className="flex flex-col gap-3">
+        <H3>動畫</H3>
+        <Desc>Content 使用 Tailwind animate utilities，根據 side 從對應方向滑入。</Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Side</Th><Th>進場動畫</Th><Th>出場動畫</Th></tr></thead>
+            <tbody>
+              {[
+                ['top', 'slide-in-from-bottom-2', 'fade-out + zoom-out-95'],
+                ['right', 'slide-in-from-left-2', 'fade-out + zoom-out-95'],
+                ['bottom', 'slide-in-from-top-2', 'fade-out + zoom-out-95'],
+                ['left', 'slide-in-from-right-2', 'fade-out + zoom-out-95'],
+              ].map(([side, enter, exit]) => (
+                <tr key={side}><Td mono>{side}</Td><Td mono>{enter}</Td><Td mono>{exit}</Td></tr>
+              ))}
+              <tr><Td mono>共通</Td><Td mono>fade-in-0 + zoom-in-95</Td><Td mono>fade-out-0 + zoom-out-95</Td></tr>
+            </tbody>
+          </table>
+        </div>
+        <Desc>transform-origin 使用 --radix-tooltip-content-transform-origin，zoom 效果從觸發器方向展開。</Desc>
+      </div>
+    </div>
+    )
+  },
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  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 由 asChild 包的可聚焦子元件提供(Tooltip 本身是透傳 Trigger、不加樣式)。\n\n  驗證:Storybook a11y addon 面板應 0 個 critical 違規;純鍵盤即可完整操作(無需滑鼠)。文字對比 ≥ 4.5:1、UI 元素對比 ≥ 3:1(WCAG AA)。"}</p>
+    </div>
+  ),
+}

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

@@ -0,0 +1,204 @@
+// @principles-rationale: Merged WhenToUse + VsHoverCardRule + NotForEssentialInfoRule
+// into a single `UsageGuidance` story (3 sections) per 2026-04-26 user mandate to
+// consolidate decision-related stories. NeedsTooltipRule kept as separate principle.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Settings, Save, Info, AlertCircle } from 'lucide-react'
+import { Tooltip, TooltipTrigger, TooltipContent } from './tooltip'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Components/Tooltip/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-body-lg font-semibold text-foreground mb-3 pb-1 border-b border-divider">{title}</h2>
+    <div>{children}</div>
+  </section>
+)
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-md">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── UsageGuidance — 使用指引(何時用 / 何時不用 + 替代 / vs 近親) ──
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose">
+          <p>適合 Tooltip 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li>
+              <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>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Components/Tooltip/展示" name="長文字"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">長文字</span></LinkTo>
+            </li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:回到「畫面上的資訊是否已足夠」這個核心問題;若提示需要被點擊或停留互動,改用近親元件(見下方「vs 近親」)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代">
+        <Rule
+          title="❌ 不把關鍵資訊只放在 tooltip"
+          note="Tooltip 需要 hover 才能看到——觸控裝置(手機 / 平板)根本無法觸發。關鍵資訊(錯誤、必填標示、操作後果)如果只靠 tooltip,觸控使用者會完全看不到"
+        >
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="primary" danger>刪除帳號</Button>
+            </TooltipTrigger>
+            <TooltipContent>此動作會永久刪除所有資料且無法復原</TooltipContent>
+          </Tooltip>
+          <Label warn>↑「永久刪除無法復原」是必要警告 → 必須顯示在畫面上(例如 Dialog 確認時),不能只靠 tooltip hover 才看到</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 欄位驗證錯誤不放 tooltip"
+          note="錯誤訊息必須 persistent 顯示——使用者不應該 hover 才知道哪裡填錯。用 Field 的 inline error message(Field 下方)"
+        >
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <div className="w-full px-3 py-1.5 border border-error rounded-md">invalid@email</div>
+            </TooltipTrigger>
+            <TooltipContent>Email 格式不正確</TooltipContent>
+          </Tooltip>
+          <Label warn>↑ 錯誤訊息用 tooltip → 使用者需要 hover 才看到;應該直接顯示在 Field 下方</Label>
+        </Rule>
+
+        <Rule
+          title="✅ 補充資訊可以用 tooltip(錯過也不影響主流程)"
+          note="「這個設定是什麼意思」「shortcut key 是什麼」等對主流程非必要的補充可以用 tooltip——看到更好,沒看到也無傷大雅"
+        >
+          <div className="flex items-center gap-2">
+            <span>密度設定</span>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button variant="text" size="sm" iconOnly startIcon={Info} aria-label="密度說明" />
+              </TooltipTrigger>
+              <TooltipContent>影響 Button / Input / row 的垂直空間</TooltipContent>
+            </Tooltip>
+          </div>
+          <Label>↑ info icon 的補充說明,錯過不影響使用</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親 — Tooltip vs HoverCard">
+        <Rule
+          title="Tooltip — 純文字、語意為描述、不放互動元素"
+          note="適合一句話的提示。語意是純描述（role=tooltip / aria-describedby），不該放可點擊元素。離開 trigger 往浮層移動時，靠 Radix 的 grace 區維持開啟（讓滑鼠可移入），非計時延遲。"
+        >
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="tertiary" size="sm" iconOnly startIcon={Info} aria-label="說明" />
+            </TooltipTrigger>
+            <TooltipContent>這個設定會影響所有專案的預設值</TooltipContent>
+          </Tooltip>
+          <Label>↑ 純文字說明；滑鼠離開觸發器即關閉（移入浮層內容則保持開啟）</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 需要放互動元素(按鈕 / 連結):用 HoverCard"
+          note="Tooltip 語意是純描述（role=tooltip）,不該包含可點擊元素——即使 Radix 浮層技術上可 hover,語意上互動內容（人物名片、連結預覽、操作按鈕）屬 HoverCard。需要互動內容必須改用 HoverCard。"
+        >
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button variant="tertiary" size="sm">Ada Chen</Button>
+            </TooltipTrigger>
+            <TooltipContent>
+              <div className="flex flex-col gap-1">
+                <span>Ada Chen</span>
+                <button className="text-primary">→ 查看 profile</button>
+              </div>
+            </TooltipContent>
+          </Tooltip>
+          <Label warn>↑ tooltip 裡放「查看 profile」按鈕 → 語意是純描述（role=tooltip）不該含可點擊元素 → 改用 HoverCard</Label>
+        </Rule>
+
+        <Rule
+          title="判斷法:「使用者會想移到浮層上做事嗎?」"
+          note="需要 → HoverCard(停留行為可互動);不需要,純看一句話 → Tooltip"
+        >
+          <Label>完整對照見 HoverCard 的「與 Tooltip 的分界」說明</Label>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const NeedsTooltipRule: Story = {
+  name: '何時需要工具提示',
+  render: () => (
+    <div>
+      <Rule
+        title="判斷核心:畫面上的資訊是否已足夠?"
+        note="Tooltip 是「補救機制」——當使用者看畫面還不夠理解時才補上。不夠 → 加 tooltip;已足夠 → 不加 tooltip(重複資訊是雜訊)"
+      >
+        <Label>公式:畫面已清楚 → 不用 / 畫面不清楚 → 補 tooltip</Label>
+      </Rule>
+
+      <Rule
+        title="✅ Icon-only button 必有 tooltip(icon 沒 label)"
+        note="純 icon 按鈕的視覺完全不傳達「做什麼」,hover 需要 tooltip 補 label。Button 的 iconOnly 模式內建自動 tooltip(aria-label 驅動),不需要手動包 Tooltip"
+      >
+        <div className="flex items-center gap-2">
+          <Button variant="tertiary" size="sm" iconOnly startIcon={Settings} aria-label="設定" />
+          <Button variant="tertiary" size="sm" iconOnly startIcon={Save} aria-label="儲存" />
+          <Button variant="tertiary" size="sm" iconOnly startIcon={AlertCircle} aria-label="警告" />
+        </div>
+        <Label>↑ hover 每顆會跳出 aria-label 對應的 tooltip(自動,不需手動包)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 已有完整 label 的按鈕加 tooltip 重複文字"
+        note="Button 上已有「儲存」文字 label,再加一個 tooltip 寫「儲存」是重複無價值。Tooltip 重複時完全沒有資訊增量"
+      >
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button variant="primary">儲存</Button>
+          </TooltipTrigger>
+          <TooltipContent>儲存</TooltipContent>
+        </Tooltip>
+        <Label warn>↑ label 已寫「儲存」,tooltip 又寫「儲存」→ 重複,去掉 tooltip</Label>
+      </Rule>
+
+      <Rule
+        title="✅ 截斷文字用 tooltip 顯示完整內容(僅當實際被截斷時)"
+        note="Tooltip 是資訊補救 — 文字被 truncate 時才顯示完整內容。沒被截斷就不該顯示 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>2026 亞洲市場品牌改版與官網重構</TooltipContent>
+        </Tooltip>
+        <Label>↑ 模式示意（此靜態範例恆顯示；實務上應偵測文字真被截斷 `scrollWidth &gt; clientWidth` 時才掛 tooltip）</Label>
+      </Rule>
+    </div>
+  ),
+}