@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/timeline/timeline.meta.md

@@ -1,15 +1,18 @@
 ---
 id: timeline
 name: Timeline
+displayName: 时间轴
 type: component
 category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Timeline
+# Timeline 时间轴
 
-时间轴 — antd 独有补足。**等价 antd `Timeline`**。垂直时间流(操作历史 / 物流轨迹 / 进度记录),支持 `left` / `right` / `alternate` 三种布局、5 种圆点颜色、自定义圆点节点、反向、尾部 `pending` 占位(配 Spinner 表示进行中)。
+时间轴 — antd 独有补足。**等价 antd `Timeline`**。垂直时间流(操作历史 / 物流轨迹 / 进度记录),支持 `left` / `right` / `alternate` 三种布局、5 档圆点 color、自定义圆点节点、反向、尾部 `pending` 占位(配 Spinner 表示进行中)。
+
+> **语义色 API**(见 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md)):圆点颜色用 `color`,5 档枚举 `default | primary | success | warning | destructive`(字面与 OpenTrek tokens 对齐,**不收 `info`**;如需信息色,用 `primary`)。
 
 ## When to use
 
@@ -24,6 +27,8 @@ package: "@teamix-evo/ui"
 - 数据表 → `Table` / `DataTable`
 - 不带时间属性的事件列表 → `List` / `Item` + `ItemGroup`
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -33,6 +38,8 @@ package: "@teamix-evo/ui"
 | `pending` | `React.ReactNode` | – | – | 在尾部追加一个"未结束"占位(antd `pending` 并集) — 通常配 `<Spinner>` 显示加载中。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -51,8 +58,9 @@ _无 — 本组件不依赖任何 npm 包。_
 
 - **每项必须有 `children`** — `label` 仅用于时间 / 副标签(`left` 模式下也会渲染在主标题上方)
 - **`mode="alternate"`** 适合非密集长内容,适合两栏对照("时间 ↔ 事件")
-- **`color` 是语义色**:`error` 用于真错误,`success` 用于完成态;**不要**用 `warning` 表示"普通节点"
+- **`color` 是语义色**:`destructive` 用于真错误,`success` 用于完成态;**不要**用 `warning` 表示“普通节点”
 - **自定义 `dot`**:用 lucide icon 节点,**尺寸控制在 12px(`size-3`)** 与默认圆点对齐
+- **`selected: true`** 会将默认圆点换为 45° 旋转的小方块(`size-2.5 rotate-45`)+ primary 色 — 用于标记"当前 / 选中"节点;设了 `dot` 后不生效
 - **`pending`** 配 `<Spinner size="sm" />` 是经典组合 — 表示"流程未结束,有新事件在路上"
 - **`reverse`**:数据天然按时间升序时用,**不要**先在外面 reverse 数据再传(直接用 prop 更明确)
 - **节点 > 20 个**建议折叠为分页 / Collapsible — Timeline 长得过深会失去时间感
@@ -79,14 +87,14 @@ import { CheckCircle2 } from 'lucide-react';
     { children: '订单已创建', color: 'success' },
     { children: '正在打包', color: 'primary' },
   ]}
-  pending={<><Spinner size="sm" tone="muted" /> 等待发货...</>}
+  pending={<><Spinner size="sm" color="muted" /> 等待发货...</>}
 />
 
 // 自定义 dot
 <Timeline
   items={[
     { children: '部署到 staging', dot: <CheckCircle2 className="size-3 text-emerald-500" /> },
-    { children: '回滚到 v1.2', color: 'error' },
+    { children: '回滚到 v1.2', color: 'destructive' },
   ]}
 />
 

package/src/components/timeline/timeline.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { CheckCircle2 } from 'lucide-react';
 import { Timeline } from './timeline';
 import { Spinner } from '@/components/spinner/spinner';
@@ -11,7 +11,7 @@ const meta: Meta<typeof Timeline> = {
     docs: {
       description: {
         component:
-          '时间轴 — 垂直时间流(操作历史 / 物流轨迹 / 进度记录)。3 种布局(left / right / alternate)+ 5 种圆点语义色 + 自定义 dot + pending 进行中占位。等价 antd `Timeline`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '时间轴 — 垂直时间流（操作历史 / 物流轨迹 / 进度记录）。3 种布局（left / right / alternate）+ 5 种圆点语义色(`color`，对齐 ADR 0021) + 自定义 dot + pending 进行中占位。等价 antd `Timeline`。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
       },
     },
   },
@@ -46,7 +46,7 @@ export const WithPending: Story = {
         ]}
         pending={
           <span className="inline-flex items-center gap-1">
-            <Spinner size="sm" tone="muted" />
+            <Spinner size="sm" color="muted" />
             等待发货...
           </span>
         }
@@ -61,9 +61,15 @@ export const CustomDots: Story = {
     <div className="w-96">
       <Timeline
         items={[
-          { children: '部署到 staging 成功', dot: <CheckCircle2 className="size-3 text-emerald-500" /> },
-          { children: 'staging 验证通过', dot: <CheckCircle2 className="size-3 text-emerald-500" /> },
-          { children: '回滚到 v1.2', color: 'error' },
+          {
+            children: '部署到 staging 成功',
+            dot: <CheckCircle2 className="size-3 text-emerald-500" />,
+          },
+          {
+            children: 'staging 验证通过',
+            dot: <CheckCircle2 className="size-3 text-emerald-500" />,
+          },
+          { children: '回滚到 v1.2', color: 'destructive' },
         ]}
       />
     </div>
@@ -94,7 +100,11 @@ export const Reverse: Story = {
       <Timeline
         reverse
         items={[
-          { children: '订单已创建', label: '2026-05-01 10:00', color: 'default' },
+          {
+            children: '订单已创建',
+            label: '2026-05-01 10:00',
+            color: 'default',
+          },
           { children: '已发货', label: '2026-05-02 14:30', color: 'primary' },
           { children: '已签收', label: '2026-05-04 09:15', color: 'success' },
         ]}
@@ -102,3 +112,23 @@ export const Reverse: Story = {
     </div>
   ),
 };
+
+export const Selected: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80">
+      <Timeline
+        items={[
+          { children: '订单已创建', label: '2026-05-01 10:00', color: 'default' },
+          {
+            children: '当前节点 — 选中后以方形 + primary 色区分',
+            label: '2026-05-02 14:30',
+            color: 'primary',
+            selected: true,
+          },
+          { children: '待处理', label: '2026-05-03 11:00', color: 'default' },
+        ]}
+      />
+    </div>
+  ),
+};

package/src/components/timeline/timeline.tsx

@@ -7,14 +7,14 @@ export type TimelineDotColor =
   | 'primary'
   | 'success'
   | 'warning'
-  | 'error';
+  | 'destructive';
 
 const dotColorMap: Record<TimelineDotColor, string> = {
   default: 'bg-muted-foreground',
   primary: 'bg-primary',
-  success: 'bg-emerald-500',
-  warning: 'bg-amber-500',
-  error: 'bg-destructive',
+  success: 'bg-success',
+  warning: 'bg-warning',
+  destructive: 'bg-destructive',
 };
 
 export interface TimelineItem {
@@ -23,7 +23,7 @@ export interface TimelineItem {
   /** 左侧时间 / 标签(antd `label` 并集 — 仅 `mode="alternate"` / 左侧布局时显式渲染)。 */
   label?: React.ReactNode;
   /**
-   * 圆点颜色(antd `color` 并集) — 也可传 `dot` 完全自定义。
+   * 圆点语义色(调色板) — 对齐 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md);也可传 `dot` 完全自定义。
    * @default "default"
    */
   color?: TimelineDotColor;
@@ -31,6 +31,11 @@ export interface TimelineItem {
    * 自定义圆点节点(antd `dot` 并集) — 传节点(如 icon)替换默认圆点。
    */
   dot?: React.ReactNode;
+  /**
+   * 标记该节点为选中状态 — 默认圆点会改为方形 + primary 色(不影响自定义 `dot`)。
+   * @default false
+   */
+  selected?: boolean;
 }
 
 export interface TimelineProps extends React.HTMLAttributes<HTMLOListElement> {
@@ -64,6 +69,13 @@ const Timeline = React.forwardRef<HTMLOListElement, TimelineProps>(
         <span className="flex size-3 items-center justify-center text-primary">
           {it.dot}
         </span>
+      ) : it.selected ? (
+        <span
+          className={cn(
+            'size-2.5 rotate-45 ring-2 ring-background',
+            dotColorMap[it.color ?? 'primary'],
+          )}
+        />
       ) : (
         <span
           className={cn(
@@ -81,7 +93,8 @@ const Timeline = React.forwardRef<HTMLOListElement, TimelineProps>(
       >
         {finalItems.map((it, i) => {
           const isLast = i === finalItems.length - 1 && !pending;
-          const sideRight = mode === 'right' || (mode === 'alternate' && i % 2 === 1);
+          const sideRight =
+            mode === 'right' || (mode === 'alternate' && i % 2 === 1);
           return (
             <li
               key={i}
@@ -90,13 +103,18 @@ const Timeline = React.forwardRef<HTMLOListElement, TimelineProps>(
                 mode === 'alternate'
                   ? 'grid-cols-[1fr_auto_1fr]'
                   : sideRight
-                    ? 'grid-cols-[1fr_auto]'
-                    : 'grid-cols-[auto_1fr]',
+                  ? 'grid-cols-[1fr_auto]'
+                  : 'grid-cols-[auto_1fr]',
               )}
             >
               {/* left slot */}
               {mode === 'alternate' || mode === 'right' ? (
-                <div className={cn('min-w-0 text-sm', sideRight ? '' : 'text-right')}>
+                <div
+                  className={cn(
+                    'min-w-0 text-xs',
+                    sideRight ? '' : 'text-right',
+                  )}
+                >
                   {!sideRight ? it.children : it.label}
                 </div>
               ) : null}
@@ -107,6 +125,7 @@ const Timeline = React.forwardRef<HTMLOListElement, TimelineProps>(
                 {!isLast ? (
                   <span
                     aria-hidden="true"
+                    // eslint-disable-next-line teamix-evo/no-arbitrary-tw-value -- timeline connector extends to next item; calc(100% + 1.5rem) bridges the inter-item gap, not tokenizable.
                     className="absolute top-3 h-[calc(100%+1.5rem)] w-px bg-border"
                   />
                 ) : null}
@@ -114,18 +133,20 @@ const Timeline = React.forwardRef<HTMLOListElement, TimelineProps>(
 
               {/* right slot */}
               {mode === 'alternate' ? (
-                <div className="min-w-0 text-sm">
+                <div className="min-w-0 text-xs">
                   {sideRight ? it.children : it.label}
                 </div>
               ) : mode === 'left' ? (
                 <div className="min-w-0">
                   {it.label ? (
-                    <div className="mb-0.5 text-xs text-muted-foreground">{it.label}</div>
+                    <div className="mb-0.5 text-xs text-muted-foreground">
+                      {it.label}
+                    </div>
                   ) : null}
-                  <div className="text-sm">{it.children}</div>
+                  <div className="text-xs">{it.children}</div>
                 </div>
               ) : (
-                <div className="min-w-0 text-sm">
+                <div className="min-w-0 text-xs">
                   {sideRight ? it.children : null}
                 </div>
               )}
@@ -135,7 +156,7 @@ const Timeline = React.forwardRef<HTMLOListElement, TimelineProps>(
         {pending ? (
           <li className="grid grid-cols-[auto_1fr] items-start gap-3">
             <span className="size-3 rounded-full bg-muted-foreground/50 ring-2 ring-background" />
-            <div className="text-sm text-muted-foreground">{pending}</div>
+            <div className="text-xs text-muted-foreground">{pending}</div>
           </li>
         ) : null}
       </ol>

package/src/components/toggle/toggle.meta.md

@@ -2,12 +2,13 @@
 id: toggle
 name: Toggle
 type: component
-category: form
+category: deprecated
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 切换按钮
 ---
 
-# Toggle
+# Toggle 切换按钮
 
 二元状态按钮 — Radix Toggle 包装。**shadcn-only**(antd 无独立对标,与 Switch 形态不同)。
 
@@ -33,7 +34,7 @@ package: "@teamix-evo/ui"
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
 | `variant` | `'default' \| 'outline'` | `"default"` | – | 视觉风格。 |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 尺寸。 |
 <!-- auto:props:end -->
 
 ## 依赖

package/src/components/toggle/toggle.stories.tsx

@@ -1,16 +1,16 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Bold, Italic, Underline } from 'lucide-react';
 import { Toggle } from './toggle';
 
 const meta: Meta<typeof Toggle> = {
-  title: '表单与输入 · Form/Toggle',
+  title: '废弃 · Deprecated/Toggle',
   component: Toggle,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '切换按钮 — 二状态 (开 / 关) 按钮，常用于富文本编辑器工具栏 (加粗 / 斜体 / 下划线) 等场景。Radix Toggle 实现， shadcn 专有（antd 未提供对应原子组件，antd 逻辑上以 Radio.Button + Switch 组合表达）。支持 `variant`（default / outline）与 `size`（sm / default / lg）。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n切换按钮 — 二状态 (开 / 关) 按钮，常用于富文本编辑器工具栏 (加粗 / 斜体 / 下划线) 等场景。Radix Toggle 实现， shadcn 专有（antd 未提供对应原子组件，antd 逻辑上以 Radio.Button + Switch 组合表达）。支持 `variant`（default / outline）与 `size`（sm / default / lg）。',
       },
     },
   },
@@ -51,7 +51,7 @@ export const Variants: Story = {
 export const Toolbar: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex items-center gap-1 rounded-md border p-1">
+    <div className="flex items-center gap-1 rounded-md border border-border p-1">
       <Toggle size="sm" aria-label="加粗">
         <Bold />
       </Toggle>

package/src/components/toggle/toggle.tsx

@@ -5,7 +5,7 @@ import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '@/utils/cn';
 
 const toggleVariants = cva(
-  'inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium ring-offset-background transition-colors hover:bg-muted hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+  'inline-flex cursor-pointer items-center justify-center gap-2 rounded-md text-xs font-medium ring-offset-background transition-colors hover:bg-muted hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
   {
     variants: {
       variant: {
@@ -15,11 +15,12 @@ const toggleVariants = cva(
       },
       size: {
         sm: 'h-8 px-2 min-w-8',
+        md: 'h-9 px-3 min-w-9',
         default: 'h-9 px-3 min-w-9',
         lg: 'h-10 px-4 min-w-10',
       },
     },
-    defaultVariants: { variant: 'default', size: 'default' },
+    defaultVariants: { variant: 'default', size: 'md' },
   },
 );
 
@@ -35,7 +36,7 @@ export interface ToggleProps
    * 尺寸。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
 }
 
 const Toggle = React.forwardRef<

package/src/components/toggle-group/toggle-group.meta.md

@@ -2,12 +2,13 @@
 id: toggle-group
 name: ToggleGroup
 type: component
-category: form
+category: deprecated
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 切换按钮组
 ---
 
-# ToggleGroup
+# ToggleGroup 切换按钮组
 
 切换按钮组 — Radix ToggleGroup,**单选(`type="single"`)+ 多选(`type="multiple"`)**。复用 Toggle 的 cva variants(default / outline)与 size。
 
@@ -31,7 +32,7 @@ package: "@teamix-evo/ui"
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
 | `variant` | `'default' \| 'outline'` | `"default"` | – | 视觉风格,与同源的 [`Toggle`](../toggle/toggle.tsx) 保持一致。 |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸,与同源的 [`Toggle`](../toggle/toggle.tsx) 保持一致。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 尺寸,与同源的 [`Toggle`](../toggle/toggle.tsx) 保持一致。 |
 | `className` | `string` | – | – | 容器 className,会与默认布局类合并。 |
 <!-- auto:props:end -->
 

package/src/components/toggle-group/toggle-group.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   AlignLeft,
   AlignCenter,
@@ -11,14 +11,14 @@ import {
 import { ToggleGroup, ToggleGroupItem } from './toggle-group';
 
 const meta: Meta<typeof ToggleGroup> = {
-  title: '表单与输入 · Form/ToggleGroup',
+  title: '废弃 · Deprecated/ToggleGroup',
   component: ToggleGroup,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '切换按钮组 — 一组二状态按钮的集合，可选单选 (`type="single"`) 或多选 (`type="multiple"`)，常用于对齐方式 / 字体样式等工具栏场景。Radix ToggleGroup 实现，shadcn 专有（antd 以 `Radio.Group` + `Radio.Button` 表达单选、以菜单多选表达多选）；`variant` / `size` 与 `Toggle` 保持一致。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n切换按钮组 — 一组二状态按钮的集合，可选单选 (`type="single"`) 或多选 (`type="multiple"`)，常用于对齐方式 / 字体样式等工具栏场景。Radix ToggleGroup 实现，shadcn 专有（antd 以 `Radio.Group` + `Radio.Button` 表达单选、以菜单多选表达多选）；`variant` / `size` 与 `Toggle` 保持一致。',
       },
     },
   },

package/src/components/toggle-group/toggle-group.tsx

@@ -7,7 +7,7 @@ import { toggleVariants } from '@/components/toggle/toggle';
 
 const ToggleGroupContext = React.createContext<
   VariantProps<typeof toggleVariants>
->({ size: 'default', variant: 'default' });
+>({ size: 'md', variant: 'default' });
 
 /**
  * ToggleGroup 自身的可定制属性。底层 type=`single`|`multiple` 与对应的
@@ -23,7 +23,7 @@ export interface ToggleGroupProps {
    * 尺寸,与同源的 [`Toggle`](../toggle/toggle.tsx) 保持一致。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
   /**
    * 容器 className,会与默认布局类合并。
    */

package/src/components/tooltip/tooltip.meta.md

@@ -2,18 +2,28 @@
 id: tooltip
 name: Tooltip
 type: component
-category: feedback
+category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 文字提示
 ---
 
-# Tooltip
+# Tooltip 文字提示
 
-文字提示气泡 — Radix Tooltip + antd `arrow / placement(side)` 并集。
+文字提示气泡 — Radix Tooltip + antd `arrow / placement(side)` 并集 + cloud-design Balloon 双形态(`variant: default | light`)。
 **两种用法**:`<Tooltip title="...">{trigger}</Tooltip>` 一行包装,或拆分原子组件(`TooltipRoot/Trigger/Content`)精细控制。
 
 > **必须用 `<TooltipProvider>` 包裹**(通常在应用根),或在单 Tooltip 上传 `withProvider`。
 
+## 视觉变体
+
+| variant   | 背景                          | 适用场景                                          |
+| --------- | ----------------------------- | ------------------------------------------------- |
+| `default` | 深色 + 浅色文字               | 图标按钮、列截断、工具栏 — 信息密度高、对比强     |
+| `light`   | 浅色 + 深色文字 + 边框 + 阴影 | 富文本提示、字段说明、与 Popover 调性接近的轻提示 |
+
+对应 cloud-design Balloon `type="primary"`(白色)/ `type="normal"`(深色)。
+
 ## When to use
 
 - 图标按钮的文字解释(无障碍 + 视觉提示)
@@ -36,6 +46,7 @@ package: "@teamix-evo/ui"
 | `children` | `React.ReactElement` | – | ✓ | 触发器(单个 ReactElement,asChild 透传)。 |
 | `title` | `React.ReactNode` | – | ✓ | 提示内容。 |
 | `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `"top"` | – | 弹出方向。 |
+| `variant` | `'default' \| 'light'` | `"default"` | – | 视觉变体: - `default`:深色背景 + 浅色文字(信息密度高、对比强,适合图标按钮 / 列截断提示) - `light`:浅色背景 + 深色文字 + 边框 + 阴影(视觉更轻,贴近富内容卡片调性, 对齐 cloud-design Balloon `type="primary"`) |
 | `arrow` | `boolean` | `true` | – | 是否显示三角形箭头。 |
 | `delayDuration` | `number` | – | – | 显示延迟(ms),默认沿用 Provider 的 delayDuration。 |
 | `withProvider` | `boolean` | – | – | 强制传给 Provider 的 delayDuration(便于不挂 Provider 的场景)。 |
@@ -59,7 +70,7 @@ package: "@teamix-evo/ui"
 > 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
 
 ```bash
-pnpm add @radix-ui/react-tooltip@^1.1.0
+pnpm add @radix-ui/react-tooltip@^1.1.0 class-variance-authority@^0.7.0
 ```
 <!-- auto:deps:end -->
 
@@ -72,6 +83,8 @@ pnpm add @radix-ui/react-tooltip@^1.1.0
 - **`title` ≤ 1 行**:超过 1 行换 `HoverCard`
 - **图标按钮必配 Tooltip + aria-label**:不能只靠 Tooltip 而省略 aria-label,屏幕阅读器不一定触发
 - **`side` 选 `top` 通常最稳**:避免被屏幕边缘截断;Radix 自带翻转回避能力,但标注首选语义
+- **变体选择**:默认深色(`default`)即可;只有需要承载图标 + 文字的轻提示、且周围已有大量深色元素时才选 `light`,避免与 `Popover` 视觉混淆
+- **不要为 `light` 自行覆写 `bg-white`/`text-black`**:语义色走 `bg-popover`/`text-popover-foreground`,主题切换时才能跟随
 
 ## Examples
 
@@ -96,4 +109,41 @@ import { Settings } from 'lucide-react';
 <Tooltip title="向右弹出" side="right" arrow={false}>
   <Button variant="outline">悬浮我</Button>
 </Tooltip>
+
+// 浅色变体(light)
+<Tooltip title="浅色提示" variant="light">
+  <Button variant="outline">浅色</Button>
+</Tooltip>
 ```
+
+## Balloon.Tooltip 形态 — 旧库 API → 新库映射
+
+旧库 cloud-design `Balloon.Tooltip`(以及 `Balloon triggerType="hover"`)在新库统一拆到 `Tooltip`。完整的 Balloon 拆解决策与 Props 总表见 [`popover.meta.md` "Balloon 形态” 章节](../popover/popover.meta.md);本表只列 Tooltip 主路径。
+
+### Props 映射表
+
+| 旧库 `Balloon.Tooltip` / `Balloon hover` API | 新库等价写法                                     | 备注                                                                                          |
+| -------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `trigger`                                    | `<Tooltip>{element}</Tooltip>`(asChild 自动处理) | 与 Popover 统一 trigger 协议                                                                  |
+| `children`(文本内容)                         | `title` prop                                     | 重命名为 `title`,与 antd `Tooltip` 一致                                                       |
+| `align`(12 方向)                             | `side`(4 方向,Radix 范式)                        | Tooltip 只提供 4 方向,需要 12 方位请用 `<TooltipContent side={...} align={...}>` 拆分原子组件 |
+| `type="normal"`(深色)                        | `variant="default"`(默认)                        | bg-primary + text-primary-foreground                                                          |
+| `type="primary"`(浅色)                       | `variant="light"`                                | 边框 + bg-popover + shadow                                                                    |
+| `delay`(hover 延时)                          | `delayDuration`                                  | 默认走 `TooltipProvider` 上的值                                                               |
+| `arrow=true`(默认)                           | `arrow={true}`(默认)                             | 一致                                                                                          |
+| `popupClassName` / `popupStyle`              | `<TooltipContent className/style>`(拆原子用法)   | `<Tooltip>` 包装器未透传,需拆到 TooltipContent                                                |
+
+### 不修复清单
+
+| 旧 API                                | 决策原因                                                                |
+| ------------------------------------- | ----------------------------------------------------------------------- |
+| `triggerType="click"` 在 Tooltip 混用 | hover/click 语义不同 — click 走 [`Popover`](../popover/popover.meta.md) |
+| 12 方向 prop 级支持                   | shorthand `side` 足够覆盖 90% 场景;边缘对齐拆原子组件 + `align`         |
+| `safeNode`                            | Tooltip 不需要 — hover 离开即隐藏,无 click outside 语义                 |
+| `closable`                            | Tooltip 不需要 — 鼠标离开即隐藏;需手动关闭请用 Popover                  |
+
+### Tooltip 专项 AI 生成纪律(在通用纪律之上叠加)
+
+- **不要用 Tooltip 装交互元素** — 需要点击/表单/链接 → 走 `Popover`(中量交互)/`HoverCard`(纯展示富内容)
+- **外层必挑 `<TooltipProvider delayDuration={300}>`** — 高频 demo 在应用根一次安装,不要每个 Tooltip 独立 `withProvider`(除非是独立 story / 孤零页面)
+- **`light` 变体只用于能够与 Popover 区分的轻提示** — 不要不分场景一套 light

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

@@ -1,17 +1,17 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import { Settings } from 'lucide-react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Settings, Info } from 'lucide-react';
 import { Tooltip, TooltipProvider } from './tooltip';
 import { Button } from '@/components/button/button';
 
 const meta: Meta<typeof Tooltip> = {
-  title: '反馈与浮层 · Feedback/Tooltip',
+  title: '数据展示 · Data Display/Tooltip',
   component: Tooltip,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '文字气泡提示 — 鼠标悬停或键盘聚焦元素时弹出的简短提示。Radix Tooltip 实现 + antd Tooltip 的并集能力：需 `TooltipProvider` 包裹（可设 `delayDuration`），通过 `side` / `arrow` / `title` 调整方位与尖角；适用于纯文本辅助说明，丰富交互请选 `Popover`。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '文字提示 —— 鼠标悬停或键盘聚焦元素时弹出的简短文字解释。基于 Radix Tooltip 实现 + antd `Tooltip` 并集能力:`title` 文本、`side` 四向、`arrow` 尖角、`delayDuration` 延迟、`withProvider` 内联 Provider,新增 `variant`(default 深底 / light 白底)对齐 cloud-design Balloon 双形态。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
@@ -20,10 +20,14 @@ const meta: Meta<typeof Tooltip> = {
       control: 'inline-radio',
       options: ['top', 'right', 'bottom', 'left'],
     },
+    variant: {
+      control: 'inline-radio',
+      options: ['default', 'light'],
+    },
     arrow: { control: 'boolean' },
     title: { control: 'text' },
   },
-  args: { side: 'top', arrow: true, title: '设置' },
+  args: { side: 'top', variant: 'default', arrow: true, title: '设置' },
   decorators: [
     (Story) => (
       <TooltipProvider delayDuration={200}>
@@ -61,6 +65,39 @@ export const Sides: Story = {
   ),
 };
 
+export const Variants: Story = {
+  name: 'Variants · default vs light',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-6">
+      <Tooltip title="深色 tooltip(default)" variant="default">
+        <Button variant="outline">深色</Button>
+      </Tooltip>
+      <Tooltip title="浅色 tooltip(light) · 带边框与阴影" variant="light">
+        <Button variant="outline">浅色</Button>
+      </Tooltip>
+    </div>
+  ),
+};
+
+export const LightVariant: Story = {
+  name: 'Light variant 富文本',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Tooltip
+      variant="light"
+      side="right"
+      title={
+        <span className="inline-flex items-center gap-1.5">
+          <Info className="size-3.5" /> 配额按账号每分钟计算
+        </span>
+      }
+    >
+      <Button variant="outline">规则说明</Button>
+    </Tooltip>
+  ),
+};
+
 export const NoArrow: Story = {
   parameters: { controls: { disable: true } },
   render: () => (