@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/popover/popover.meta.md

@@ -4,12 +4,13 @@ name: Popover
 type: component
 category: feedback
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 气泡卡片
 ---
 
-# Popover
+# Popover 气泡卡片
 
-可交互浮层 — Radix Popover + antd `arrow` 并集。
+可交互浮层 — Radix Popover + antd `arrow` 并集,使用 `showArrow` 控制尖角(与 Tooltip / HoverCard 命名统一)。
 **与 Tooltip 区别**:Popover 内可放任意交互元素(button / form / link),触发方式为 click(默认),不是 hover。
 
 ## When to use
@@ -32,7 +33,9 @@ package: "@teamix-evo/ui"
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `arrow` | `boolean` | `false` | – | 是否显示三角形箭头(antd `arrow` 并集)。 |
+| `showArrow` | `boolean` | `false` | – | 是否显示三角形箭头(antd `arrow` 并集)。 与 Tooltip / HoverCard 统一用 `showArrow`,语义更清晰。 |
+| `arrow` | `boolean` | – | – | 向后兼容别名:与 `showArrow` 二选一,同时传入时 `showArrow` 优先。 |
+| `container` | `HTMLElement \| null` | – | – | 弹层 Portal 挂载容器 — 透传给 Radix Popover Portal。 默认挂在 `document.body`;在内层滚动容器 / Dialog 内时常需指定为该容器节点。 等价 antd `popupContainer`。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -65,6 +68,8 @@ pnpm add @radix-ui/react-popover@^1.1.0
 - **Content 必有焦点目标**:键盘可达性 — Popover 打开后第一个可聚焦元素自动获焦
 - **不嵌套 Popover**:嵌套会导致焦点陷阱混乱;改用 `Sheet` 或 `Dialog`
 - **`modal={true}` 仅用于阻断场景**:默认 modal=false,允许用户点外部关闭
+- **尖角名称用 `showArrow`**:与 Tooltip / HoverCard 保持一致;老字段 `arrow` 仅作为 deprecated 别名兼容,新代码不要再使用
+- **表单场景推荐 `showArrow`**:轻微联动视觉、用户能快速识别浮层来源;菜单类/设置面板可省略尖角以减少视觉噪点
 
 ## Examples
 
@@ -90,8 +95,60 @@ import { Button } from '@/components/ui/button';
   <PopoverTrigger asChild>
     <Button>更多</Button>
   </PopoverTrigger>
-  <PopoverContent arrow>
+  <PopoverContent showArrow>
     <p>简短说明</p>
   </PopoverContent>
 </Popover>
 ```
+
+## Balloon 形态 — 旧库 API → 新组合映射
+
+新库 **不提供独立的 `Balloon` 组件**。这是主动决策 — 旧库 cloud-design `Balloon` 是"hover 提示 + click 浮层 + closable + 多主题"一物多相,违背 P1 三层对齐。新库拆为:
+
+- **`Tooltip`**(hover) — 对应 cloud-design `Balloon.Tooltip` 和 `Balloon triggerType="hover"`,详见 [`tooltip.meta.md`](../tooltip/tooltip.meta.md)
+- **`Popover`**(click,本组件) — 对应 cloud-design `Balloon triggerType="click"`(默认)
+- **`HoverCard`**(纯展示的 hover 富内容) — 对应 `Balloon` 里放了富文本但不需交互的场景
+
+### Props 映射表(`Balloon` triggerType="click" 主路径)
+
+| 旧库 `Balloon` API                                 | 新库等价写法                                                                                                 | 备注                                                                                       |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `triggerType="click"`(默认)                        | `<Popover>`                                                                                                  | 默认即点击,无需额外配置                                                                    |
+| `triggerType="hover"`                              | `<Tooltip>` 或 `<HoverCard>`                                                                                 | hover 请拆到专门组件 — 语义不同                                                            |
+| `triggerType="focus"`                              | 暂不提供                                                                                                     | Radix Popover 默认不含 focus 触发;需要时业务侧 `onFocus={() => setOpen(true)}`             |
+| `trigger` (触发元素)                               | `<PopoverTrigger asChild>{element}</PopoverTrigger>`                                                         | asChild 透传,不多一层 wrapper                                                              |
+| `children` (浮层内容)                              | `<PopoverContent>{...}</PopoverContent>`                                                                     | 可放任意交互元素                                                                           |
+| `align`(12 方向 `tl/t/tr/lt/l/lb/rt/r/rb/bl/b/br`) | `side` + `align` 二维拆解 — 例: `tl` → `side="top" align="start"`,`t` → `side="top" align="center"`          | Radix 范式,遵循 W3C 方位语义                                                               |
+| `offset`                                           | `sideOffset` / `alignOffset`                                                                                 | 拆为两个轴,更精细                                                                          |
+| `type="normal"`(深色) / `type="primary"`(浅色)     | Popover 默认仅 light 一种 — 需深色请用 `Tooltip variant="default"` 或自带 `bg-primary` className             | 替代思路:Popover 是富内容容器,深色背景会严重限制子节点 contrast,业务需要时手动覆盖设计令牌 |
+| `closable=true`(右上角 X)                          | `<PopoverClose asChild><Button size="icon" variant="ghost" icon={<X />} aria-label="关闭" /></PopoverClose>` | 组合式 — 位置/样式/图标任意可控,见 `ClosableContent` story                                 |
+| `visible` / `defaultVisible`                       | `<Popover open={...}>` / `defaultOpen={...}`                                                                 | 受控/非受控两套                                                                            |
+| `onVisibleChange`                                  | `<Popover onOpenChange={...}>`                                                                               | —                                                                                          |
+| `onClose`                                          | `onOpenChange(open)` 里 · `if (!open) {...}`                                                                 | 统一为 `onOpenChange`,不拆 open/close 二事件                                               |
+| `safeNode`(点击该节点不关闭)                       | `onInteractOutside={(e) => { if (mySafeNode.contains(e.target as Node)) e.preventDefault(); }}`              | Radix 原生在 `onInteractOutside` callback 里自由判断,可控性更高                            |
+| `popupClassName`                                   | `<PopoverContent className="...">`                                                                           | 直接透传                                                                                   |
+| `popupStyle`                                       | `<PopoverContent style="...">`                                                                               | 直接透传                                                                                   |
+| `popupContainer`                                   | `<PopoverPrimitive.Portal container={...}>` (需手动包裹)                                                     | Radix 默认 portal 到 body                                                                  |
+| `cache`(隐藏时保留 DOM)                            | 不提供                                                                                                       | Radix Portal 是 mount/unmount 语义;需 cache 请业务侧自管 mount state                       |
+| `delay`(hover 延时)                                | 请用 `<Tooltip delayDuration={...}>`                                                                         | Popover 点击触发本就不需延时                                                               |
+| `animation` 自定义                                 | 已固化为 `animate-in/out fade+zoom+slide` 四向                                                               | 业务覆盖 → `<PopoverContent className="...">`                                              |
+| `followTrigger`                                    | 不提供                                                                                                       | Radix Portal 默认即 follow trigger,无需 prop                                               |
+
+### 不修复清单(主动不补)
+
+| 旧 API                                 | 决策原因                                                                              |
+| -------------------------------------- | ------------------------------------------------------------------------------------- |
+| 独立 `Balloon` 组件导出                | P1 三层对齐;`Tooltip`/`Popover`/`HoverCard` 三件拆解语义更明确                        |
+| `triggerType="focus"` 内置支持         | Radix Popover 不含 focus 触发;业务需要时手动 controlled `onFocus`,更可控              |
+| `cache`(隐藏时保留 DOM)                | mount/unmount 语义更准;cache 语义需业务侧明确控制                                     |
+| `safeNode` prop                        | `onInteractOutside` callback 表达力更强(可同时判断多个安全节点 + 条件逻辑)            |
+| 12 方向语言                            | 拆解为 `side` + `align` 二维 — W3C 语义,与 shadcn / Radix / antd `placement` 拆解一致 |
+| `cache` / `popupContainer` 为默认 prop | 低频场景,业务手动包 Portal container 更加明确                                         |
+
+### Balloon 专项 AI 生成纪律(在通用纪律之上叠加)
+
+- **实例化时先选语义不选品牌**:写业务代码时,口说 "加个 Balloon" → 先问 "hover 还是 click + 内部能交互吗" → 选出 Tooltip / HoverCard / Popover
+- **closable 走组合式**:不要为了"对齐 closable=true" 反向在 Popover 级加 prop — `<PopoverClose asChild>` 包 icon Button 即可(见 `ClosableContent` story)
+- **带 PopoverClose 的 X 按钮走 `variant="ghost" size="icon"`** + 主体内容 `pr-6` 避免多行文本被覆盖
+- **不要为 `safeNode` 需求抽 helper**:`onInteractOutside={(e) => isInsideRef(e.target, [refA, refB]) && e.preventDefault()}` 即足够
+- **深色背景需求请优先考虑切换到 Tooltip variant="default"** — 仅在 "深色且需交互" 的少数场景才走 Popover className 覆盖

package/src/components/popover/popover.stories.tsx

@@ -1,18 +1,24 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import { Popover, PopoverTrigger, PopoverContent } from './popover';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { X } from 'lucide-react';
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverClose,
+} from './popover';
 import { Button } from '@/components/button/button';
 import { Input } from '@/components/input/input';
 import { Label } from '@/components/label/label';
 
 const meta: Meta<typeof PopoverContent> = {
-  title: '反馈与浮层 · Feedback/Popover',
+  title: '反馈 · Feedback/Popover',
   component: PopoverContent,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '气泡卡片 — 由 trigger 触发，在 portal 中展示富内容（表单、菜单、说明等）。Radix Popover 实现 + antd Popover 的语义并集：相比 Tooltip 仅承载纯文本提示，Popover 可承载任意交互内容；通过 `side` / `align` 控制方位，`arrow` 控制是否带尖角。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '气泡卡片 —— 由 trigger 触发,在 portal 中展示富内容(表单、菜单、说明等)。基于 Radix Popover 实现 + antd `Popover` 并集能力:`side` / `align` 控制方位、`showArrow` 渲染尖角、`modal` 控制是否阻断外部交互。相比 Tooltip 仅承载纯文本提示,Popover 可承载任意交互内容。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
@@ -25,9 +31,9 @@ const meta: Meta<typeof PopoverContent> = {
       control: 'inline-radio',
       options: ['start', 'center', 'end'],
     },
-    arrow: { control: 'boolean' },
+    showArrow: { control: 'boolean' },
   },
-  args: { side: 'bottom', align: 'center', arrow: false },
+  args: { side: 'bottom', align: 'center', showArrow: false },
 };
 
 export default meta;
@@ -49,6 +55,42 @@ export const Playground: Story = {
   ),
 };
 
+export const WithArrow: Story = {
+  name: 'showArrow · 有尖角',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Popover defaultOpen>
+      <PopoverTrigger asChild>
+        <Button variant="outline">带箭头</Button>
+      </PopoverTrigger>
+      <PopoverContent showArrow>
+        <h4 className="mb-1 font-medium">导出 CSV</h4>
+        <p className="text-sm text-muted-foreground">
+          仅导出当前筛选范围内的数据。
+        </p>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
+export const WithoutArrow: Story = {
+  name: 'showArrow={false} · 无尖角',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Popover defaultOpen>
+      <PopoverTrigger asChild>
+        <Button variant="outline">无箭头</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <h4 className="mb-1 font-medium">默认形态</h4>
+        <p className="text-sm text-muted-foreground">
+          浮层与 trigger 之间留白,不带尖角。
+        </p>
+      </PopoverContent>
+    </Popover>
+  ),
+};
+
 export const InteractiveForm: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
@@ -56,7 +98,7 @@ export const InteractiveForm: Story = {
       <PopoverTrigger asChild>
         <Button>边距设置</Button>
       </PopoverTrigger>
-      <PopoverContent className="w-80">
+      <PopoverContent className="w-80" showArrow>
         <div className="grid gap-3">
           <h4 className="font-medium">边距</h4>
           <div className="grid grid-cols-3 items-center gap-3">
@@ -80,3 +122,37 @@ export const InteractiveForm: Story = {
     </Popover>
   ),
 };
+
+/**
+ * Closable 形态 — 对齐 cloud-design `Balloon closable=true`。旧库用
+ * `closable` prop 声明式控制右上角 X 按钮,新库用 `<PopoverClose asChild>`
+ * 包裹 icon Button 的组合式 — 位置/样式/图标任意可控,且与整体设计体系的
+ * Button 变体(`size="icon"` `variant="ghost"`)保持一致。
+ */
+export const ClosableContent: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Popover defaultOpen>
+      <PopoverTrigger asChild>
+        <Button variant="outline">可关闭浮层</Button>
+      </PopoverTrigger>
+      <PopoverContent className="relative w-80" showArrow>
+        <PopoverClose asChild>
+          <Button
+            size="icon"
+            variant="ghost"
+            icon={<X />}
+            aria-label="关闭浮层"
+            className="absolute right-1 top-1"
+          />
+        </PopoverClose>
+        <div className="pr-6">
+          <h4 className="mb-1 font-medium">付费提示</h4>
+          <p className="text-sm text-muted-foreground">
+            升级到专业版可解锁高级限流策略。点击右上角 × 随时关闭。
+          </p>
+        </div>
+      </PopoverContent>
+    </Popover>
+  ),
+};

package/src/components/popover/popover.tsx

@@ -4,7 +4,17 @@ import * as PopoverPrimitive from '@radix-ui/react-popover';
 import { cn } from '@/utils/cn';
 
 const Popover = PopoverPrimitive.Root;
-const PopoverTrigger = PopoverPrimitive.Trigger;
+const PopoverTrigger = React.forwardRef<
+  React.ElementRef<typeof PopoverPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Trigger>
+>(({ className, ...props }, ref) => (
+  <PopoverPrimitive.Trigger
+    ref={ref}
+    className={cn('cursor-pointer', className)}
+    {...props}
+  />
+));
+PopoverTrigger.displayName = PopoverPrimitive.Trigger.displayName;
 const PopoverAnchor = PopoverPrimitive.Anchor;
 const PopoverClose = PopoverPrimitive.Close;
 
@@ -12,44 +22,83 @@ export interface PopoverContentProps
   extends React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content> {
   /**
    * 是否显示三角形箭头(antd `arrow` 并集)。
+   * 与 Tooltip / HoverCard 统一用 `showArrow`,语义更清晰。
    * @default false
    */
+  showArrow?: boolean;
+  /**
+   * 向后兼容别名:与 `showArrow` 二选一,同时传入时 `showArrow` 优先。
+   * @deprecated 请改用 `showArrow`,后续版本会移除。
+   */
   arrow?: boolean;
+  /**
+   * 弹层 Portal 挂载容器 — 透传给 Radix Popover Portal。
+   * 默认挂在 `document.body`;在内层滚动容器 / Dialog 内时常需指定为该容器节点。
+   * 等价 antd `popupContainer`。
+   */
+  container?: HTMLElement | null;
 }
 
+/**
+ * `onCloseAutoFocus` 默认 `preventDefault` — 阻止 Radix 关闭时把焦点程序化
+ * restore 回 trigger。
+ *
+ * 原因:Chromium/Safari 把"程序化 restore 的 focus"判定为非鼠标焦点 → 触发
+ * `:focus-visible` → trigger(多数是 Button)在关闭后残留蓝色 ring,与用户
+ * "鼠标点完已经失焦了"的视觉预期冲突。与 DropdownMenu / ContextMenu 走同一
+ * 默认策略,对齐 antd `Popover` / cloud-design `Balloon` 的鼠标体感。
+ *
+ * 取舍:键盘 Esc 关闭后焦点也不会 restore 回 trigger,而是落到 body。业务侧
+ * 需要保留 restore 行为时,显式传 `onCloseAutoFocus` 即可完全覆盖默认。
+ */
 const PopoverContent = React.forwardRef<
   React.ElementRef<typeof PopoverPrimitive.Content>,
   PopoverContentProps
 >(
   (
-    { className, align = 'center', sideOffset = 4, arrow = false, children, ...props },
+    {
+      className,
+      align = 'center',
+      sideOffset = 4,
+      showArrow,
+      arrow,
+      onCloseAutoFocus,
+      container,
+      children,
+      ...props
+    },
     ref,
-  ) => (
-    <PopoverPrimitive.Portal>
-      <PopoverPrimitive.Content
-        ref={ref}
-        align={align}
-        sideOffset={sideOffset}
-        className={cn(
-          'z-50 w-72 rounded-md border bg-popover p-4 text-popover-foreground shadow-md outline-none animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
-          className,
-        )}
-        {...props}
-      >
-        {children}
-        {arrow ? (
-          <PopoverPrimitive.Arrow className="fill-popover" width={10} height={5} />
-        ) : null}
-      </PopoverPrimitive.Content>
-    </PopoverPrimitive.Portal>
-  ),
+  ) => {
+    // showArrow 优先;arrow 作为 deprecated 别名兜底,保持向后兼容
+    const renderArrow = showArrow ?? arrow ?? false;
+    return (
+      <PopoverPrimitive.Portal container={container}>
+        <PopoverPrimitive.Content
+          ref={ref}
+          align={align}
+          sideOffset={sideOffset}
+          onCloseAutoFocus={
+            onCloseAutoFocus ?? ((event) => event.preventDefault())
+          }
+          className={cn(
+            'z-50 w-72 rounded-md border border-border bg-popover p-4 text-popover-foreground shadow-md outline-none animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+            className,
+          )}
+          {...props}
+        >
+          {children}
+          {renderArrow ? (
+            <PopoverPrimitive.Arrow
+              className="fill-popover"
+              width={10}
+              height={5}
+            />
+          ) : null}
+        </PopoverPrimitive.Content>
+      </PopoverPrimitive.Portal>
+    );
+  },
 );
 PopoverContent.displayName = PopoverPrimitive.Content.displayName;
 
-export {
-  Popover,
-  PopoverTrigger,
-  PopoverContent,
-  PopoverAnchor,
-  PopoverClose,
-};
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor, PopoverClose };

package/src/components/progress/progress.meta.md

@@ -2,12 +2,13 @@
 id: progress
 name: Progress
 type: component
-category: foundation
+category: feedback
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 进度条
 ---
 
-# Progress
+# Progress 进度条
 
 进度条 — Radix Progress + antd 的 `status / showInfo / Progress.Circle` 并集。
 
@@ -33,7 +34,7 @@ package: "@teamix-evo/ui"
 | `value` | `number` | `0` | – | 当前百分比(0~100)。 |
 | `status` | `ProgressStatus` | `"normal"` | – | 状态色,自动优先级:`exception > warning > success > normal`。 |
 | `showInfo` | `boolean` | `false` | – | 是否在右侧显示百分比文字(antd showInfo 并集)。 |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 进度条尺寸。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"md"` | – | 进度条尺寸。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -58,8 +59,6 @@ pnpm add @radix-ui/react-progress@^1.1.0
 ```
 <!-- auto:deps:end -->
 
-> `ProgressCircle` 的 props 详见 [`progress.tsx`](./progress.tsx) 的 `ProgressCircleProps` interface。
-
 ## AI 生成纪律
 
 - **`status` 反映业务语义**:正常进行 `normal`、完成 `success`、警告 `warning`、失败/异常 `exception`,**不要**用颜色 prop 绕过 status 直接调色
@@ -84,3 +83,36 @@ import { Progress, ProgressCircle } from '@/components/ui/progress';
 <ProgressCircle value={100} status="success" size={120} />
 <ProgressCircle value={42} showInfo={false} size={48} />
 ```
+
+---
+
+## Progress 形态 — 旧库 API → 新映射
+
+> 旧库 `Progress`(hybridcloud,shape='line'|'circle') → 新库 `Progress`(线形) + `ProgressCircle`(环形)。
+> 新库基于 Radix Progress Primitive + SVG circle,语义色对齐 ADR 0021。
+
+### 命名 & 结构映射
+
+| 旧库                       | 新库                                      | 说明                           |
+| -------------------------- | ----------------------------------------- | ------------------------------ |
+| `Progress shape='line'`    | `Progress`                                | 线形进度条                     |
+| `Progress shape='circle'`  | `ProgressCircle`                          | 环形(独立组件)                 |
+| `percent`                  | `value`                                   | 属性重命名(0~100)              |
+| `state='normal'`           | `status='normal'`                         | state → status                 |
+| `state='error'`            | `status='exception'`                      | error → exception              |
+| `state='success'`          | `status='success'`                        | 直接映射                       |
+| —                          | `status='warning'`                        | 新增警告状态                   |
+| `size: small/medium/large` | `size: 'sm' \| 'md' \| 'default' \| 'lg'` | md = medium = default          |
+| `textRender`               | `showInfo`(布尔)                          | 自定义 → 开关;复杂文本外部组合 |
+| `progressive` (渐变色)     | 不复刻                                    | 用 status 语义色替代           |
+| `color` (任意 CSS)         | 不复刻                                    | 仅走 status 语义色             |
+| `hasBorder`                | 不复刻                                    | 新库无此选项                   |
+
+### 迁移 FAQ
+
+| 问题              | 回答                                                           |
+| ----------------- | -------------------------------------------------------------- |
+| percent → value?  | 直接改名,语义相同(0~100)                                       |
+| 环形怎么写?       | `<ProgressCircle value={75} size={80} />`;带文字 `showInfo`    |
+| 怎么做自定义文字? | 外部组合: `<div><Progress value={x} /><span>{x}%</span></div>` |
+| 失败状态怎么显示? | `status="exception"` — 自动变红色(destructive)                 |

package/src/components/progress/progress.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Progress, ProgressCircle } from './progress';
 
 const meta: Meta<typeof Progress> = {
-  title: '基础原语 · Foundation/Progress',
+  title: '反馈 · Feedback/Progress',
   component: Progress,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '进度条 — 展示一个任务的完成进度，访问友好的状态反馈。Radix Progress 实现 + antd Progress 的能力并集：除默认线形（`Progress`）外还提供环形 `ProgressCircle`，支持 `status`（normal / success / warning / exception）、`size`、`showInfo` 以及任意 `format` 提示。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '进度条 — 展示一个任务的完成进度，访问友好的状态反馈。Radix Progress 实现 + antd Progress 的能力并集：除默认线形（`Progress`）外还提供环形 `ProgressCircle`，支持 `status`（normal / success / warning / exception）、`size`、`showInfo` 以及任意 `format` 提示。',
       },
     },
   },

package/src/components/progress/progress.tsx

@@ -7,15 +7,15 @@ export type ProgressStatus = 'normal' | 'success' | 'warning' | 'exception';
 
 const statusBarColor: Record<ProgressStatus, string> = {
   normal: 'bg-primary',
-  success: 'bg-emerald-500',
-  warning: 'bg-amber-500',
+  success: 'bg-success',
+  warning: 'bg-warning',
   exception: 'bg-destructive',
 };
 
 const statusTextColor: Record<ProgressStatus, string> = {
   normal: 'text-foreground',
-  success: 'text-emerald-600',
-  warning: 'text-amber-600',
+  success: 'text-success',
+  warning: 'text-warning',
   exception: 'text-destructive',
 };
 
@@ -41,9 +41,9 @@ export interface ProgressProps
   showInfo?: boolean;
   /**
    * 进度条尺寸。
-   * @default "default"
+   * @default "md"
    */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
 }
 
 const Progress = React.forwardRef<
@@ -56,7 +56,7 @@ const Progress = React.forwardRef<
       value = 0,
       status = 'normal',
       showInfo = false,
-      size = 'default',
+      size = 'md',
       ...props
     },
     ref,
@@ -78,7 +78,11 @@ const Progress = React.forwardRef<
               'size-full flex-1 transition-all',
               statusBarColor[status],
             )}
-            style={{ transform: `translateX(-${100 - Math.min(100, Math.max(0, value))}%)` }}
+            style={{
+              transform: `translateX(-${
+                100 - Math.min(100, Math.max(0, value))
+              }%)`,
+            }}
           />
         </ProgressPrimitive.Root>
         {showInfo ? (
@@ -131,11 +135,15 @@ const ProgressCircle = React.forwardRef<HTMLDivElement, ProgressCircleProps>(
   ) => {
     const radius = (size - strokeWidth) / 2;
     const circumference = 2 * Math.PI * radius;
-    const offset = circumference * (1 - Math.min(100, Math.max(0, value)) / 100);
+    const offset =
+      circumference * (1 - Math.min(100, Math.max(0, value)) / 100);
     return (
       <div
         ref={ref}
-        className={cn('relative inline-flex items-center justify-center', className)}
+        className={cn(
+          'relative inline-flex items-center justify-center',
+          className,
+        )}
         style={{ width: size, height: size }}
         role="progressbar"
         aria-valuenow={value}
@@ -167,19 +175,19 @@ const ProgressCircle = React.forwardRef<HTMLDivElement, ProgressCircleProps>(
             className={cn(
               'fill-none transition-all',
               status === 'success'
-                ? 'stroke-emerald-500'
+                ? 'stroke-success'
                 : status === 'warning'
-                  ? 'stroke-amber-500'
-                  : status === 'exception'
-                    ? 'stroke-destructive'
-                    : 'stroke-primary',
+                ? 'stroke-warning'
+                : status === 'exception'
+                ? 'stroke-destructive'
+                : 'stroke-primary',
             )}
           />
         </svg>
         {showInfo ? (
           <span
             className={cn(
-              'absolute text-sm font-semibold tabular-nums',
+              'absolute text-xs font-semibold tabular-nums',
               statusTextColor[status],
             )}
           >