@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/color-picker/color-picker.meta.md

@@ -3,7 +3,7 @@ id: color-picker
 name: ColorPicker
 displayName: 颜色选择
 type: component
-category: form
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -28,38 +28,34 @@ package: '@teamix-evo/ui'
 ## Props
 
 <!-- auto:props:begin -->
-
-| 名称           | 类型                        | 默认值      | 必填 | 说明                                                                                      |
-| -------------- | --------------------------- | ----------- | ---- | ----------------------------------------------------------------------------------------- |
-| `value`        | `string`                    | –           | –    | 受控值 — `#RRGGBB` 或 `#RRGGBBAA`(开 `allowAlpha` 时)。                                   |
-| `defaultValue` | `string`                    | `"#000000"` | –    | uncontrolled 初值。                                                                       |
-| `onChange`     | `(value: string) => void`   | –           | –    | 值变化回调。                                                                              |
-| `allowAlpha`   | `boolean`                   | `false`     | –    | 是否允许透明度(antd `format=hex8` 类似行为) — 启用后展示 alpha 滑块,value 变为 8 位 hex。 |
-| `presets`      | `string[]`                  | –           | –    | 预设色块(antd `presets` 并集) — 一组常用颜色快捷选择。                                    |
-| `disabled`     | `boolean`                   | –           | –    | 整体禁用。                                                                                |
-| `size`         | `'sm' \| 'default' \| 'lg'` | `"default"` | –    | 触发器尺寸。                                                                              |
-| `className`    | `string`                    | –           | –    | 触发器 className。                                                                        |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | – | – | 受控值 — `#RRGGBB` 或 `#RRGGBBAA`(开 `allowAlpha` 时)。 |
+| `defaultValue` | `string` | `"#000000"` | – | uncontrolled 初值。 |
+| `onChange` | `(value: string) => void` | – | – | 值变化回调。 |
+| `allowAlpha` | `boolean` | `false` | – | 是否允许透明度(antd `format=hex8` 类似行为) — 启用后展示 alpha 滑块,value 变为 8 位 hex。 |
+| `presets` | `string[]` | – | – | 预设色块(antd `presets` 并集) — 一组常用颜色快捷选择。 |
+| `disabled` | `boolean` | – | – | 整体禁用。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 触发器尺寸。 |
+| `className` | `string` | – | – | 触发器 className。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add color-picker` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry     | 类型      | 描述                                                                                            |
-| --------- | --------- | ----------------------------------------------------------------------------------------------- |
-| `cn`      | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                              |
-| `input`   | component | 文本输入 — shadcn 简洁基底 + antd prefix/suffix/clearable/showCount/addonBefore/addonAfter/size |
-| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集                                                    |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `input` | component | 单行文本输入 — clearable / showCount / size(sm 24 / md 32 / lg 36,与 Button 同档)/ error 四档内建能力。前缀/后缀/addon 等复合形态已拆出独立 InputGroup;多行已拆出独立 Textarea |
+| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集,使用 showArrow 控制尖角(与 Tooltip / HoverCard 命名统一) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/color-picker/color-picker.stories.tsx

@@ -1,16 +1,16 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { ColorPicker } from './color-picker';
 
 const meta: Meta<typeof ColorPicker> = {
-  title: '表单与输入 · Form/ColorPicker',
+  title: '数据录入 · Data Entry/ColorPicker',
   component: ColorPicker,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '颜色选择 — 触发器色块 → Popover 面板（原生 color input + alpha + hex 输入 + 预设色板）。可选 8 位 hex（含透明度）。等价 antd `ColorPicker`（v5.5+）。',
+          '颜色选择 —— 触发器色块 → Popover 面板,选取一个 `#RRGGBB` 或 `#RRGGBBAA` 颜色。基于原生 `<input type="color">` + Radix `Popover` + `Input` 组合,等价 antd `ColorPicker`(v5.5+):`value` / `defaultValue` / `onChange` 受控双轨、`allowAlpha` 透明度档(8 位 hex)、`presets` 预设色板、`size`(`sm`/`default`/`lg`)三档触发器、`disabled`。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
@@ -26,11 +26,27 @@ export default meta;
 type Story = StoryObj<typeof ColorPicker>;
 
 export const Playground: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '基础颜色选择 —— uncontrolled,内部维护当前色,点击触发器弹出原生 color input + hex 文本输入双通道。',
+      },
+    },
+  },
   render: (args) => <ColorPicker {...args} defaultValue="#f43f5e" />,
 };
 
 export const Controlled: Story = {
-  parameters: { controls: { disable: true } },
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '受控形态 —— `value` + `onChange` 由消费侧持有真值,常用于"主题色配置 + 实时预览"场景。',
+      },
+    },
+  },
   render: () => {
     const [c, setC] = React.useState('#3b82f6');
     return (
@@ -43,7 +59,15 @@ export const Controlled: Story = {
 };
 
 export const WithPresets: Story = {
-  parameters: { controls: { disable: true } },
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '预设色板 —— `presets` 数组渲染为面板底部色块,点击即写入 value。建议给 6~12 个品牌色,避免视觉混乱。',
+      },
+    },
+  },
   render: () => (
     <ColorPicker
       defaultValue="#3b82f6"
@@ -64,12 +88,49 @@ export const WithPresets: Story = {
 };
 
 export const WithAlpha: Story = {
-  parameters: { controls: { disable: true } },
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '透明度档 —— `allowAlpha` 启用后 value 自动变 8 位 hex,面板内多出 `Alpha` 滑块与百分比读数。',
+      },
+    },
+  },
   render: () => <ColorPicker allowAlpha defaultValue="#3b82f680" />,
 };
 
+export const HexInput: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '自定义 hex 输入 —— 面板内嵌的 `Input` 接受手动 hex(`#RRGGBB` 或 `#RRGGBBAA`),不合法字符自动剥除,长度按 `allowAlpha` 截断。',
+      },
+    },
+  },
+  render: () => {
+    const [c, setC] = React.useState('#10b981');
+    return (
+      <div className="flex items-center gap-3">
+        <ColorPicker value={c} onChange={setC} allowAlpha />
+        <code className="rounded bg-muted px-2 py-1 text-xs">{c}</code>
+      </div>
+    );
+  },
+};
+
 export const Sizes: Story = {
-  parameters: { controls: { disable: true } },
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '三档触发器尺寸 —— `sm` / `default` / `lg`,对齐其它表单控件高度档位。',
+      },
+    },
+  },
   render: () => (
     <div className="flex items-center gap-3">
       <ColorPicker size="sm" defaultValue="#ef4444" />
@@ -78,3 +139,21 @@ export const Sizes: Story = {
     </div>
   ),
 };
+
+export const Disabled: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '禁用态 —— 整组 `disabled`,点击不弹面板,触发器降透明度。仅用于只读语义,业务态锁定建议在 form 层处理。',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex items-center gap-3">
+      <ColorPicker defaultValue="#3b82f6" disabled />
+      <ColorPicker defaultValue="#10b981" allowAlpha disabled />
+    </div>
+  ),
+};

package/src/components/color-picker/color-picker.tsx

@@ -27,7 +27,7 @@ export interface ColorPickerProps {
   /** 整体禁用。 */
   disabled?: boolean;
   /** 触发器尺寸。 @default "default" */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
   /** 触发器 className。 */
   className?: string;
 }
@@ -54,7 +54,7 @@ const ColorPicker = React.forwardRef<HTMLButtonElement, ColorPickerProps>(
       allowAlpha = false,
       presets,
       disabled = false,
-      size = 'default',
+      size = 'md',
       className,
     },
     ref,
@@ -70,10 +70,12 @@ const ColorPicker = React.forwardRef<HTMLButtonElement, ColorPickerProps>(
     };
 
     const baseHex = current.slice(0, 7);
-    const alphaHex = allowAlpha && current.length >= 9 ? current.slice(7, 9) : 'ff';
+    const alphaHex =
+      allowAlpha && current.length >= 9 ? current.slice(7, 9) : 'ff';
     const alphaInt = parseInt(alphaHex, 16);
 
-    const swatchSize = size === 'sm' ? 'size-7' : size === 'lg' ? 'size-11' : 'size-9';
+    const swatchSize =
+      size === 'sm' ? 'size-7' : size === 'lg' ? 'size-11' : 'size-9';
 
     return (
       <Popover>
@@ -83,7 +85,7 @@ const ColorPicker = React.forwardRef<HTMLButtonElement, ColorPickerProps>(
             type="button"
             disabled={disabled}
             className={cn(
-              'inline-flex items-center justify-center rounded-md border border-input bg-background shadow-sm transition-colors',
+              'inline-flex cursor-pointer items-center justify-center rounded-md border border-input bg-background shadow-sm transition-colors',
               'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
               'disabled:cursor-not-allowed disabled:opacity-50',
               swatchSize,
@@ -104,12 +106,18 @@ const ColorPicker = React.forwardRef<HTMLButtonElement, ColorPickerProps>(
               type="color"
               value={baseHex}
               disabled={disabled}
-              onChange={(e) => update(allowAlpha ? `${e.target.value}${alphaHex}` : e.target.value)}
+              onChange={(e) =>
+                update(
+                  allowAlpha ? `${e.target.value}${alphaHex}` : e.target.value,
+                )
+              }
               className="h-10 w-full cursor-pointer rounded-md border border-input bg-transparent"
             />
             {allowAlpha ? (
               <div className="flex items-center gap-2">
-                <span className="w-12 text-xs text-muted-foreground">Alpha</span>
+                <span className="w-12 text-xs text-muted-foreground">
+                  Alpha
+                </span>
                 <input
                   type="range"
                   min={0}
@@ -117,7 +125,9 @@ const ColorPicker = React.forwardRef<HTMLButtonElement, ColorPickerProps>(
                   value={alphaInt}
                   disabled={disabled}
                   onChange={(e) => {
-                    const a = Number(e.target.value).toString(16).padStart(2, '0');
+                    const a = Number(e.target.value)
+                      .toString(16)
+                      .padStart(2, '0');
                     update(`${baseHex}${a}`);
                   }}
                   className="flex-1"
@@ -142,7 +152,7 @@ const ColorPicker = React.forwardRef<HTMLButtonElement, ColorPickerProps>(
                     aria-label={p}
                     onClick={() => update(p)}
                     className={cn(
-                      'size-6 rounded-sm border border-border ring-offset-background transition-all',
+                      'size-6 cursor-pointer rounded-sm border border-border ring-offset-background transition-all',
                       'hover:scale-110 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
                     )}
                     style={{ backgroundColor: p }}

package/src/components/command/command.meta.md

@@ -2,7 +2,7 @@
 id: command
 name: Command
 type: component
-category: shell
+category: feedback
 since: 0.1.0
 package: '@teamix-evo/ui'
 displayName: 命令面板
@@ -10,8 +10,8 @@ displayName: 命令面板
 
 # Command 命令面板
 
-命令面板 — 基于 [`cmdk`](https://cmdk.paco.me/),提供"按 ⌘K 打开"的全局搜索 / 命令执行体验(Linear / Raycast / Vercel 风格)。
-**shadcn-only**(antd 无对标)。是 `Combobox` 的底座(Combobox = Command + Popover)。
+命令面板 / 下拉底座 — 基于 [`cmdk`](https://cmdk.paco.me/),提供"按 ⌘K 打开"的全局搜索 / 命令执行体验(Linear / Raycast / Vercel 风格)。
+**shadcn-only**(antd 无对标)。同时作为 `Combobox` / `Select` / `AutoComplete` 的同源下拉内核(ADR 0029),提供过滤 / 键盘导航 / a11y 能力。
 
 ## When to use
 
@@ -30,23 +30,20 @@ displayName: 命令面板
 ## Props
 
 <!-- auto:props:begin -->
-
 _(no props)_
-
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add command` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry    | 类型      | 描述                                                                                |
-| -------- | --------- | ----------------------------------------------------------------------------------- |
-| `cn`     | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                  |
-| `dialog` | component | 模态对话框 — Radix Dialog + antd Modal 并集(组合式 Header/Footer/Title/Description) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `dialog` | component | 模态对话框 — Radix Dialog + antd Modal 并集(组合式 Header/Footer/Title/Description,size sm/md/lg/xl 绑定 layout-dialog tokens,圆角 radius-dialog 16px,无 border) |
 
 ### npm 依赖
 
@@ -55,7 +52,6 @@ _(no props)_
 ```bash
 pnpm add cmdk@^1.0.0 lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 > 子组件:`Command`(Root 容器)/ `CommandDialog`(模态版,内部组合 Dialog)/ `CommandInput`(自带搜索图标)/ `CommandList`(可滚动列表)/ `CommandEmpty`(无匹配空态)/ `CommandGroup`(分组,带 heading)/ `CommandItem`(选项,支持 `onSelect`)/ `CommandSeparator` / `CommandShortcut`(右对齐快捷键)。

package/src/components/command/command.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Calendar, Mail, Settings, User } from 'lucide-react';
 import {
   Command,
@@ -12,14 +12,14 @@ import {
 } from './command';
 
 const meta: Meta<typeof Command> = {
-  title: '应用壳 · Shell/Command',
+  title: '反馈 · Feedback/Command',
   component: Command,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '命令面板 — 全局搜索 / 命令执行（Linear / Raycast / Vercel 风格）。基于 cmdk，提供键盘导航、模糊搜索、分组、空态、快捷键提示；模态版用 CommandDialog 监听 ⌘K 全局触发。',
+          '命令面板 / 下拉底座 — 全局搜索 / 命令执行（Linear / Raycast / Vercel 风格）。基于 cmdk，提供键盘导航、模糊搜索、分组、空态、快捷键提示；模态版用 CommandDialog 监听 ⌘K 全局触发。同时作为 `Combobox` / `Select` / `AutoComplete` 的同源下拉内核（ADR 0029）。',
       },
     },
   },
@@ -30,7 +30,7 @@ type Story = StoryObj<typeof Command>;
 
 export const Inline: Story = {
   render: () => (
-    <Command className="w-80 rounded-lg border">
+    <Command className="w-80 rounded-lg border border-border">
       <CommandInput placeholder="输入命令或搜索..." />
       <CommandList>
         <CommandEmpty>无结果。</CommandEmpty>

package/src/components/command/command.tsx

@@ -3,7 +3,7 @@ import { Command as CommandPrimitive } from 'cmdk';
 import { Search } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
-import { Dialog, DialogContent } from '@/components/dialog/dialog';
+import { Dialog, DialogContent, DialogTitle } from '@/components/dialog/dialog';
 
 export interface CommandProps
   extends React.ComponentPropsWithoutRef<typeof CommandPrimitive> {}
@@ -24,11 +24,19 @@ const Command = React.forwardRef<
 Command.displayName = CommandPrimitive.displayName;
 
 interface CommandDialogProps
-  extends React.ComponentPropsWithoutRef<typeof Dialog> {}
+  extends React.ComponentPropsWithoutRef<typeof Dialog> {
+  /** 命令面板的可访问性标题(默认隐藏视觉)。 */
+  title?: string;
+}
 
-const CommandDialog = ({ children, ...props }: CommandDialogProps) => (
+const CommandDialog = ({
+  title = '命令面板',
+  children,
+  ...props
+}: CommandDialogProps) => (
   <Dialog {...props}>
     <DialogContent className="overflow-hidden p-0">
+      <DialogTitle className="sr-only">{title}</DialogTitle>
       <Command className="[&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:font-medium [&_[cmdk-group-heading]]:text-muted-foreground [&_[cmdk-group]:not([hidden])_~[cmdk-group]]:pt-0 [&_[cmdk-group]]:px-2 [&_[cmdk-input-wrapper]_svg]:size-5 [&_[cmdk-input]]:h-12 [&_[cmdk-item]]:px-2 [&_[cmdk-item]]:py-3 [&_[cmdk-item]_svg]:size-5">
         {children}
       </Command>
@@ -40,12 +48,15 @@ const CommandInput = React.forwardRef<
   React.ElementRef<typeof CommandPrimitive.Input>,
   React.ComponentPropsWithoutRef<typeof CommandPrimitive.Input>
 >(({ className, ...props }, ref) => (
-  <div className="flex items-center border-b px-3" cmdk-input-wrapper="">
+  <div
+    className="flex items-center border-b border-b-border px-3"
+    cmdk-input-wrapper=""
+  >
     <Search className="mr-2 size-4 shrink-0 opacity-50" />
     <CommandPrimitive.Input
       ref={ref}
       className={cn(
-        'flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50',
+        'flex h-10 w-full rounded-md bg-transparent py-3 text-xs outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50',
         className,
       )}
       {...props}
@@ -72,7 +83,7 @@ const CommandEmpty = React.forwardRef<
 >((props, ref) => (
   <CommandPrimitive.Empty
     ref={ref}
-    className="py-6 text-center text-sm text-muted-foreground"
+    className="py-6 text-center text-xs text-muted-foreground"
     {...props}
   />
 ));
@@ -112,7 +123,7 @@ const CommandItem = React.forwardRef<
   <CommandPrimitive.Item
     ref={ref}
     className={cn(
-      "relative flex cursor-default gap-2 select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none data-[disabled=true]:pointer-events-none data-[selected='true']:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+      "relative flex cursor-pointer gap-2 select-none items-center rounded-sm px-2 py-1.5 text-xs outline-none data-[disabled=true]:pointer-events-none data-[selected='true']:bg-accent data-[selected=true]:text-accent-foreground data-[disabled=true]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
       className,
     )}
     {...props}

package/src/components/context-menu/context-menu.meta.md

@@ -2,7 +2,7 @@
 id: context-menu
 name: ContextMenu
 type: component
-category: navigation
+category: deprecated
 since: 0.1.0
 package: '@teamix-evo/ui'
 displayName: 右键菜单
@@ -30,25 +30,7 @@ shadcn 显式版,antd 用 Dropdown 模拟同样可达。
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `ContextMenuContent` 的 props。
 
 <!-- auto:props:begin -->
-
-#### ContextMenuSubTrigger
-
-| 名称    | 类型      | 默认值  | 必填 | 说明                                        |
-| ------- | --------- | ------- | ---- | ------------------------------------------- |
-| `inset` | `boolean` | `false` | –    | 左侧留出 icon 宽度的缩进,对齐同级 icon 项。 |
-
-#### ContextMenuItem
-
-| 名称    | 类型      | 默认值  | 必填 | 说明                                        |
-| ------- | --------- | ------- | ---- | ------------------------------------------- |
-| `inset` | `boolean` | `false` | –    | 左侧留出 icon 宽度的缩进,对齐同级 icon 项。 |
-
-#### ContextMenuLabel
-
-| 名称    | 类型      | 默认值  | 必填 | 说明                                        |
-| ------- | --------- | ------- | ---- | ------------------------------------------- |
-| `inset` | `boolean` | `false` | –    | 左侧留出 icon 宽度的缩进,对齐同级 icon 项。 |
-
+_(组件无 `<Name>Props` interface — props 详见 [`context-menu.tsx`](./context-menu.tsx))_
 <!-- auto:props:end -->
 
 ## 依赖
@@ -56,14 +38,13 @@ shadcn 显式版,antd 用 Dropdown 模拟同样可达。
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add context-menu` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -72,7 +53,6 @@ shadcn 显式版,antd 用 Dropdown 模拟同样可达。
 ```bash
 pnpm add @radix-ui/react-context-menu@^2.2.0 lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/context-menu/context-menu.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   ContextMenu,
   ContextMenuTrigger,
@@ -9,14 +9,14 @@ import {
 } from './context-menu';
 
 const meta: Meta<typeof ContextMenuContent> = {
-  title: '导航 · Navigation/ContextMenu',
+  title: '废弃 · Deprecated/ContextMenu',
   component: ContextMenuContent,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '右键菜单 — 右键触发的操作菜单，与 DropdownMenu 形态一致（Item / CheckboxItem / RadioItem / Sub），仅触发方式不同。Radix ContextMenu 实现，shadcn 显式版，antd 用 Dropdown 模拟同样可达。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n右键菜单 — 右键触发的操作菜单，与 DropdownMenu 形态一致（Item / CheckboxItem / RadioItem / Sub），仅触发方式不同。Radix ContextMenu 实现，shadcn 显式版，antd 用 Dropdown 模拟同样可达。',
       },
     },
   },
@@ -28,7 +28,7 @@ type Story = StoryObj<typeof ContextMenuContent>;
 export const Default: Story = {
   render: () => (
     <ContextMenu>
-      <ContextMenuTrigger className="flex h-32 w-72 items-center justify-center rounded-md border border-dashed text-sm text-muted-foreground">
+      <ContextMenuTrigger className="flex h-32 w-72 items-center justify-center rounded-md border border-border border-dashed text-sm text-muted-foreground">
         在此处右键(或长按)打开菜单
       </ContextMenuTrigger>
       <ContextMenuContent className="w-56">

package/src/components/context-menu/context-menu.tsx

@@ -20,7 +20,7 @@ const ContextMenuSubTrigger = React.forwardRef<
   <ContextMenuPrimitive.SubTrigger
     ref={ref}
     className={cn(
-      'flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+      'flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-xs outline-none focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
       inset && 'pl-8',
       className,
     )}
@@ -39,7 +39,7 @@ const ContextMenuSubContent = React.forwardRef<
   <ContextMenuPrimitive.SubContent
     ref={ref}
     className={cn(
-      'z-50 min-w-menu overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+      'z-50 min-w-menu overflow-hidden rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
       className,
     )}
     {...props}
@@ -47,15 +47,28 @@ const ContextMenuSubContent = React.forwardRef<
 ));
 ContextMenuSubContent.displayName = ContextMenuPrimitive.SubContent.displayName;
 
+/**
+ * `onCloseAutoFocus` 默认 `preventDefault` — 阻止 Radix 关闭时把焦点程序化
+ * restore 回 trigger。
+ *
+ * 原因:Chromium/Safari 把"程序化 restore 的 focus"判定为非鼠标焦点 → 触发
+ * `:focus-visible` → trigger 如果是 button-like 元素会残留蓝色 ring(ContextMenu
+ * trigger 常是任意容器,常见场景不明显,但作为 popper 类一致默认策略)。
+ * 与 DropdownMenu / Popover 走同一默认,保证全库 popper 类鼠标体感一致。
+ *
+ * 取舍:键盘 Esc 关闭后焦点也不会 restore 回 trigger,而是落到 body。业务侧
+ * 需要保留 restore 行为时,显式传 `onCloseAutoFocus` 即可完全覆盖默认。
+ */
 const ContextMenuContent = React.forwardRef<
   React.ElementRef<typeof ContextMenuPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof ContextMenuPrimitive.Content>
->(({ className, ...props }, ref) => (
+>(({ className, onCloseAutoFocus, ...props }, ref) => (
   <ContextMenuPrimitive.Portal>
     <ContextMenuPrimitive.Content
       ref={ref}
+      onCloseAutoFocus={onCloseAutoFocus ?? ((event) => event.preventDefault())}
       className={cn(
-        'z-50 min-w-menu overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md animate-in fade-in-80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+        'z-50 min-w-menu overflow-hidden rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md animate-in fade-in-80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
         className,
       )}
       {...props}
@@ -73,7 +86,7 @@ const ContextMenuItem = React.forwardRef<
   <ContextMenuPrimitive.Item
     ref={ref}
     className={cn(
-      'relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
+      'relative flex cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-xs outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0',
       inset && 'pl-8',
       className,
     )}
@@ -89,7 +102,7 @@ const ContextMenuCheckboxItem = React.forwardRef<
   <ContextMenuPrimitive.CheckboxItem
     ref={ref}
     className={cn(
-      'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      'relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-xs outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
       className,
     )}
     checked={checked}
@@ -113,7 +126,7 @@ const ContextMenuRadioItem = React.forwardRef<
   <ContextMenuPrimitive.RadioItem
     ref={ref}
     className={cn(
-      'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+      'relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-xs outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
       className,
     )}
     {...props}
@@ -137,7 +150,7 @@ const ContextMenuLabel = React.forwardRef<
   <ContextMenuPrimitive.Label
     ref={ref}
     className={cn(
-      'px-2 py-1.5 text-sm font-semibold text-foreground',
+      'px-2 py-1.5 text-xs font-semibold text-foreground',
       inset && 'pl-8',
       className,
     )}