@teamix-evo/ui 0.1.1 → 0.3.0

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

@@ -1,13 +1,14 @@
 ---
 id: color-picker
 name: ColorPicker
+displayName: 颜色选择
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# ColorPicker
+# ColorPicker 颜色选择
 
 颜色选择 — antd 独有补足。**等价 antd `ColorPicker`**(v5.5+)。基于原生 `<input type="color">` + alpha 滑块 + hex 文本输入 + 预设色块,提供"触发器(色块)→ 弹出面板"的标准交互。可选透明度(8 位 hex)。
 
@@ -24,6 +25,8 @@ package: "@teamix-evo/ui"
 - 渐变 / 多色阶 → 当前不支持,需配合第三方 picker
 - HSL / RGB 各通道独立调节 → 当前仅 hex + alpha,复杂场景建议引入专业 picker
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -33,10 +36,12 @@ package: "@teamix-evo/ui"
 | `allowAlpha` | `boolean` | `false` | – | 是否允许透明度(antd `format=hex8` 类似行为) — 启用后展示 alpha 滑块,value 变为 8 位 hex。 |
 | `presets` | `string[]` | – | – | 预设色块(antd `presets` 并集) — 一组常用颜色快捷选择。 |
 | `disabled` | `boolean` | – | – | 整体禁用。 |
-| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 触发器尺寸。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 触发器尺寸。 |
 | `className` | `string` | – | – | 触发器 className。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -45,8 +50,8 @@ package: "@teamix-evo/ui"
 | 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 并集 |
+| `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 依赖
 
@@ -55,7 +60,7 @@ _无 — 本组件不依赖任何 npm 包。_
 
 ## AI 生成纪律
 
-- **value 必须是 `#RRGGBB`(6位)或 `#RRGGBBAA`(8位 + 透明度)** — 不接受 `rgb()` / `hsl()` / 命名色
+- **value 必须是 `#RRGGBB`(6 位)或 `#RRGGBBAA`(8 位 + 透明度)** — 不接受 `rgb()` / `hsl()` / 命名色
 - **`allowAlpha=true`** 时 value 自动变为 8 位 hex;关闭时即使有 alpha 也会被截断到 6 位
 - **`presets`** 应是品牌色板而非随手凑数 — 6-12 个 stable 颜色为佳,避免视觉混乱
 - **`disabled`** 是只读语义 — 配 value 展示当前选中色;**不要**用做"暂时锁定"等业务态(用 form-level 控制)

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+)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '颜色选择 —— 触发器色块 → 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;
 }
@@ -48,12 +48,13 @@ const ColorPicker = React.forwardRef<HTMLButtonElement, ColorPickerProps>(
   (
     {
       value,
+      // eslint-disable-next-line teamix-evo/no-color-literal -- ColorPicker default value is a hex literal by API contract (antd parity); not a styling decision.
       defaultValue = '#000000',
       onChange,
       allowAlpha = false,
       presets,
       disabled = false,
-      size = 'default',
+      size = 'md',
       className,
     },
     ref,
@@ -69,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>
@@ -82,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,
@@ -103,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}
@@ -116,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"
@@ -141,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,15 +2,16 @@
 id: command
 name: Command
 type: component
-category: shell
+category: feedback
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 命令面板
 ---
 
-# Command
+# 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
 
@@ -26,10 +27,14 @@ package: "@teamix-evo/ui"
 - 静态菜单 → `DropdownMenu`
 - 需要表单语义 → `Combobox`(基于本组件)
 
+## Props
+
 <!-- auto:props:begin -->
 _(no props)_
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -38,7 +43,7 @@ _(no props)_
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `dialog` | component | 模态对话框 — Radix Dialog + antd Modal 并集(组合式 Header/Footer/Title/Description) |
+| `dialog` | component | 模态对话框 — Radix Dialog + antd Modal 并集(组合式 Header/Footer/Title/Description,size sm/md/lg/xl 绑定 layout-dialog tokens,圆角 radius-dialog 16px,无 border) |
 
 ### npm 依赖
 
@@ -63,8 +68,13 @@ pnpm add cmdk@^1.0.0 lucide-react@^0.460.0
 
 ```tsx
 import {
-  Command, CommandInput, CommandList, CommandEmpty,
-  CommandGroup, CommandItem, CommandShortcut,
+  Command,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandShortcut,
 } from '@/components/ui/command';
 import { Calendar, Mail, User } from 'lucide-react';
 
@@ -74,14 +84,20 @@ import { Calendar, Mail, User } from 'lucide-react';
   <CommandList>
     <CommandEmpty>无结果。</CommandEmpty>
     <CommandGroup heading="建议">
-      <CommandItem><Calendar /> 日历 <CommandShortcut>⌘K</CommandShortcut></CommandItem>
-      <CommandItem><Mail /> 邮件</CommandItem>
+      <CommandItem>
+        <Calendar /> 日历 <CommandShortcut>⌘K</CommandShortcut>
+      </CommandItem>
+      <CommandItem>
+        <Mail /> 邮件
+      </CommandItem>
     </CommandGroup>
     <CommandGroup heading="设置">
-      <CommandItem><User /> 个人资料</CommandItem>
+      <CommandItem>
+        <User /> 个人资料
+      </CommandItem>
     </CommandGroup>
   </CommandList>
-</Command>
+</Command>;
 
 // 模态(全局 ⌘K)
 import { CommandDialog } from '@/components/ui/command';
@@ -100,5 +116,5 @@ React.useEffect(() => {
 <CommandDialog open={open} onOpenChange={setOpen}>
   <CommandInput placeholder="..." />
   <CommandList>...</CommandList>
-</CommandDialog>
+</CommandDialog>;
 ```

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 全局触发。OpenTrek tokens 适配,无 mock。',
+          '命令面板 / 下拉底座 — 全局搜索 / 命令执行（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}
@@ -60,7 +71,7 @@ const CommandList = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <CommandPrimitive.List
     ref={ref}
-    className={cn('max-h-[300px] overflow-y-auto overflow-x-hidden', className)}
+    className={cn('max-h-listbox overflow-y-auto overflow-x-hidden', 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,12 +2,13 @@
 id: context-menu
 name: ContextMenu
 type: component
-category: navigation
+category: deprecated
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 右键菜单
 ---
 
-# ContextMenu
+# ContextMenu 右键菜单
 
 右键菜单 — Radix ContextMenu 完整实现。**与 DropdownMenu 形态一致**(Item / CheckboxItem / RadioItem / Sub / Label / Separator / Shortcut),仅触发方式不同(右键 vs click)。
 shadcn 显式版,antd 用 Dropdown 模拟同样可达。
@@ -54,8 +55,6 @@ pnpm add @radix-ui/react-context-menu@^2.2.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
-> 子组件与 DropdownMenu 完全一致(只差名称前缀):`ContextMenu / Trigger / Content / Item / CheckboxItem / RadioItem / Label / Separator / Shortcut / Sub / SubTrigger / SubContent / Group / RadioGroup / Portal`。
-
 ## AI 生成纪律
 
 - **Trigger 必有可见区域**:不能是空区域,否则无右键目标 — 通常 wrap 一个文本块 / 图片 / 卡片
@@ -67,8 +66,12 @@ pnpm add @radix-ui/react-context-menu@^2.2.0 lucide-react@^0.460.0
 
 ```tsx
 import {
-  ContextMenu, ContextMenuTrigger, ContextMenuContent,
-  ContextMenuItem, ContextMenuSeparator, ContextMenuShortcut,
+  ContextMenu,
+  ContextMenuTrigger,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
 } from '@/components/ui/context-menu';
 
 <ContextMenu>
@@ -86,5 +89,5 @@ import {
       删除 <ContextMenuShortcut>⌫</ContextMenuShortcut>
     </ContextMenuItem>
   </ContextMenuContent>
-</ContextMenu>
+</ContextMenu>;
 ```

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,9 +9,17 @@ import {
 } from './context-menu';
 
 const meta: Meta<typeof ContextMenuContent> = {
-  title: '导航 · Navigation/ContextMenu',
+  title: '废弃 · Deprecated/ContextMenu',
   component: ContextMenuContent,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n右键菜单 — 右键触发的操作菜单，与 DropdownMenu 形态一致（Item / CheckboxItem / RadioItem / Sub），仅触发方式不同。Radix ContextMenu 实现，shadcn 显式版，antd 用 Dropdown 模拟同样可达。',
+      },
+    },
+  },
 };
 
 export default meta;
@@ -20,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-[8rem] 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-[8rem] 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,
     )}