@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/menubar/menubar.tsx

@@ -21,7 +21,7 @@ const Menubar = React.forwardRef<
   <MenubarPrimitive.Root
     ref={ref}
     className={cn(
-      'flex h-9 items-center gap-1 rounded-md border bg-background p-1 shadow-sm',
+      'flex h-9 items-center gap-1 rounded-md border border-border bg-background p-1 shadow-sm',
       className,
     )}
     {...props}
@@ -36,7 +36,7 @@ const MenubarTrigger = React.forwardRef<
   <MenubarPrimitive.Trigger
     ref={ref}
     className={cn(
-      'flex cursor-default select-none items-center rounded-sm px-3 py-1 text-sm font-medium outline-none focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground',
+      'flex cursor-pointer select-none items-center rounded-sm px-3 py-1 text-xs font-medium outline-none focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground',
       className,
     )}
     {...props}
@@ -53,7 +53,7 @@ const MenubarSubTrigger = React.forwardRef<
   <MenubarPrimitive.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',
+      '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',
       inset && 'pl-8',
       className,
     )}
@@ -72,7 +72,7 @@ const MenubarSubContent = React.forwardRef<
   <MenubarPrimitive.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}
@@ -95,7 +95,7 @@ const MenubarContent = React.forwardRef<
         alignOffset={alignOffset}
         sideOffset={sideOffset}
         className={cn(
-          'z-50 min-w-menu-md overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md data-[state=open]:animate-in 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-md overflow-hidden rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md data-[state=open]:animate-in 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}
@@ -114,7 +114,7 @@ const MenubarItem = React.forwardRef<
   <MenubarPrimitive.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',
+      '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',
       inset && 'pl-8',
       className,
     )}
@@ -130,7 +130,7 @@ const MenubarCheckboxItem = React.forwardRef<
   <MenubarPrimitive.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}
@@ -153,7 +153,7 @@ const MenubarRadioItem = React.forwardRef<
   <MenubarPrimitive.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}
@@ -177,7 +177,7 @@ const MenubarLabel = React.forwardRef<
   <MenubarPrimitive.Label
     ref={ref}
     className={cn(
-      'px-2 py-1.5 text-sm font-semibold',
+      'px-2 py-1.5 text-xs font-semibold',
       inset && 'pl-8',
       className,
     )}

package/src/components/native-select/native-select.meta.md

@@ -2,7 +2,7 @@
 id: native-select
 name: NativeSelect
 type: component
-category: form
+category: deprecated
 since: 0.1.0
 package: '@teamix-evo/ui'
 displayName: 原生下拉
@@ -27,24 +27,21 @@ displayName: 原生下拉
 ## Props
 
 <!-- auto:props:begin -->
-
-| 名称               | 类型     | 默认值 | 必填 | 说明                                                      |
-| ------------------ | -------- | ------ | ---- | --------------------------------------------------------- |
-| `wrapperClassName` | `string` | –      | –    | 容器额外 className(给外层 wrapper,而非 `<select>` 本身)。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `wrapperClassName` | `string` | – | – | 容器额外 className(给外层 wrapper,而非 `<select>` 本身)。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add native-select` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -53,7 +50,6 @@ displayName: 原生下拉
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/native-select/native-select.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { NativeSelect } from './native-select';
 
 const meta: Meta<typeof NativeSelect> = {
-  title: '表单与输入 · Form/NativeSelect',
+  title: '废弃 · Deprecated/NativeSelect',
   component: NativeSelect,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '原生下拉选择 — 原生 `<select>` 元素的样式封装，零 JS 开销，移动端弹起系统 picker，直接参与 form submit。与 Radix `Select` 互为补充：NativeSelect 面向原生 / 移动端友好，Radix Select 面向自定义项 UI / 受控复杂表单。shadcn 2025-10 新增。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n原生下拉选择 — 原生 `<select>` 元素的样式封装，零 JS 开销，移动端弹起系统 picker，直接参与 form submit。与 Radix `Select` 互为补充：NativeSelect 面向原生 / 移动端友好，Radix Select 面向自定义项 UI / 受控复杂表单。shadcn 2025-10 新增。',
       },
     },
   },
@@ -74,7 +74,7 @@ export const InForm: Story = {
       </NativeSelect>
       <button
         type="submit"
-        className="rounded-md border px-3 py-1 text-sm hover:bg-accent"
+        className="rounded-md border border-border px-3 py-1 text-sm hover:bg-accent"
       >
         提交
       </button>

package/src/components/native-select/native-select.tsx

@@ -33,7 +33,7 @@ const NativeSelect = React.forwardRef<HTMLSelectElement, NativeSelectProps>(
         ref={ref}
         disabled={disabled}
         className={cn(
-          'flex h-9 w-full appearance-none rounded-md border border-input bg-background py-1 pl-3 pr-8 text-sm shadow-sm',
+          'flex h-9 w-full appearance-none rounded-md border border-input bg-background py-1 pl-3 pr-8 text-xs shadow-sm',
           'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
           'disabled:cursor-not-allowed disabled:opacity-50',
           className,

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

@@ -2,7 +2,7 @@
 id: navigation-menu
 name: NavigationMenu
 type: component
-category: navigation
+category: deprecated
 since: 0.1.0
 package: '@teamix-evo/ui'
 displayName: 导航菜单
@@ -30,9 +30,7 @@ displayName: 导航菜单
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `NavigationMenu`(Root) 的 props。
 
 <!-- auto:props:begin -->
-
 _(组件无 `<Name>Props` interface — props 详见 [`navigation-menu.tsx`](./navigation-menu.tsx))_
-
 <!-- auto:props:end -->
 
 ## 依赖
@@ -40,14 +38,13 @@ _(组件无 `<Name>Props` interface — props 详见 [`navigation-menu.tsx`](./n
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add navigation-menu` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -56,7 +53,6 @@ _(组件无 `<Name>Props` interface — props 详见 [`navigation-menu.tsx`](./n
 ```bash
 pnpm add @radix-ui/react-navigation-menu@^1.2.0 class-variance-authority@^0.7.0 lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 > 完整子组件:`NavigationMenu` / `NavigationMenuList` / `NavigationMenuItem` / `NavigationMenuTrigger` / `NavigationMenuContent` / `NavigationMenuLink` / `NavigationMenuIndicator` / `NavigationMenuViewport` + `navigationMenuTriggerStyle`(给独立 Link 复用 trigger 视觉)。

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

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   NavigationMenu,
   NavigationMenuList,
@@ -8,16 +8,17 @@ import {
   NavigationMenuLink,
   navigationMenuTriggerStyle,
 } from './navigation-menu';
+import { cn } from '@/utils/cn';
 
 const meta: Meta<typeof NavigationMenu> = {
-  title: '导航 · Navigation/NavigationMenu',
+  title: '废弃 · Deprecated/NavigationMenu',
   component: NavigationMenu,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '导航菜单 — 网站 / 营销页 / 应用顶部主导航（产品 / 文档 / 定价），每项可有富 Content 面板展示子页面预览。Radix NavigationMenu 实现，shadcn 显式版，与 Menubar（应用级菜单）互补。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\nNavigationMenu 导航菜单 —— 在网站、营销页或应用顶部承载主导航，每项可展开富面板预览子页面。Radix `NavigationMenu` 内核 + shadcn 原子，**对齐 antd `Menu mode="horizontal"`** 的水平主导航能力，对齐 shadcn `NavigationMenu` 的 `NavigationMenuTrigger` / `NavigationMenuContent` / `NavigationMenuLink` / `navigationMenuTriggerStyle`，并补足 antd 的 `disabled` 项与简单链接形态。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/tokens`，无 mock。',
       },
     },
   },
@@ -106,6 +107,108 @@ export const Default: Story = {
             </a>
           </NavigationMenuLink>
         </NavigationMenuItem>
+        <NavigationMenuItem>
+          <NavigationMenuLink
+            asChild
+            className={cn(
+              navigationMenuTriggerStyle(),
+              'pointer-events-none opacity-50',
+            )}
+            aria-disabled
+          >
+            <span>企业版（即将上线）</span>
+          </NavigationMenuLink>
+        </NavigationMenuItem>
+      </NavigationMenuList>
+    </NavigationMenu>
+  ),
+};
+
+export const SimpleLinks: Story = {
+  parameters: { layout: 'centered' },
+  render: () => (
+    <NavigationMenu>
+      <NavigationMenuList>
+        {['首页', '产品', '文档', '社区', '联系我们'].map((label) => (
+          <NavigationMenuItem key={label}>
+            <NavigationMenuLink
+              asChild
+              className={navigationMenuTriggerStyle()}
+            >
+              <a href={`#${label}`} onClick={(e) => e.preventDefault()}>
+                {label}
+              </a>
+            </NavigationMenuLink>
+          </NavigationMenuItem>
+        ))}
+      </NavigationMenuList>
+    </NavigationMenu>
+  ),
+};
+
+export const DisabledItem: Story = {
+  parameters: { layout: 'centered' },
+  render: () => (
+    <NavigationMenu>
+      <NavigationMenuList>
+        <NavigationMenuItem>
+          <NavigationMenuLink asChild className={navigationMenuTriggerStyle()}>
+            <a href="#docs" onClick={(e) => e.preventDefault()}>
+              文档
+            </a>
+          </NavigationMenuLink>
+        </NavigationMenuItem>
+        <NavigationMenuItem>
+          <NavigationMenuLink
+            asChild
+            aria-disabled
+            className={cn(
+              navigationMenuTriggerStyle(),
+              'pointer-events-none opacity-50',
+            )}
+          >
+            <span>API（内部预览）</span>
+          </NavigationMenuLink>
+        </NavigationMenuItem>
+        <NavigationMenuItem>
+          <NavigationMenuLink asChild className={navigationMenuTriggerStyle()}>
+            <a href="#blog" onClick={(e) => e.preventDefault()}>
+              博客
+            </a>
+          </NavigationMenuLink>
+        </NavigationMenuItem>
+      </NavigationMenuList>
+    </NavigationMenu>
+  ),
+};
+
+/**
+ * “纵向”其实是侧边列表形态的导航。Radix `NavigationMenu` 主要面向水平、
+ * 可开富面板的主导航；需要侧边导航选 `Sidebar`。下面是将 NavigationMenu
+ * `orientation="vertical"` 下的简样实例（供对齐 antd `Menu mode="vertical"` 的过度能力）。
+ */
+export const Vertical: Story = {
+  parameters: { layout: 'centered' },
+  render: () => (
+    <NavigationMenu orientation="vertical" className="w-56 max-w-none flex-col items-stretch">
+      <NavigationMenuList className="w-full flex-col items-stretch gap-0">
+        {[
+          { label: '仪表盘', href: '#dashboard' },
+          { label: '项目', href: '#projects' },
+          { label: '任务', href: '#tasks' },
+          { label: '设置', href: '#settings' },
+        ].map((it) => (
+          <NavigationMenuItem key={it.label} className="w-full">
+            <NavigationMenuLink
+              asChild
+              className={cn(navigationMenuTriggerStyle(), 'w-full justify-start')}
+            >
+              <a href={it.href} onClick={(e) => e.preventDefault()}>
+                {it.label}
+              </a>
+            </NavigationMenuLink>
+          </NavigationMenuItem>
+        ))}
       </NavigationMenuList>
     </NavigationMenu>
   ),

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

@@ -11,7 +11,10 @@ const NavigationMenu = React.forwardRef<
 >(({ className, children, ...props }, ref) => (
   <NavigationMenuPrimitive.Root
     ref={ref}
-    className={cn('relative z-10 flex max-w-max flex-1 items-center justify-center', className)}
+    className={cn(
+      'relative z-10 flex max-w-max flex-1 items-center justify-center',
+      className,
+    )}
     {...props}
   >
     {children}
@@ -38,7 +41,7 @@ NavigationMenuList.displayName = NavigationMenuPrimitive.List.displayName;
 const NavigationMenuItem = NavigationMenuPrimitive.Item;
 
 const navigationMenuTriggerStyle = cva(
-  'group inline-flex h-9 w-max items-center justify-center rounded-md bg-background px-4 py-2 text-sm font-medium transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus:outline-none disabled:pointer-events-none disabled:opacity-50 data-[active]:bg-accent/50 data-[state=open]:bg-accent/50',
+  'group inline-flex h-9 w-max cursor-pointer items-center justify-center rounded-md bg-background px-4 py-2 text-xs font-medium transition-colors hover:bg-accent hover:text-accent-foreground focus:bg-accent focus:text-accent-foreground focus:outline-none disabled:pointer-events-none disabled:opacity-50 data-[active]:bg-accent/50 data-[state=open]:bg-accent/50',
 );
 
 const NavigationMenuTrigger = React.forwardRef<
@@ -84,7 +87,7 @@ const NavigationMenuViewport = React.forwardRef<
     <NavigationMenuPrimitive.Viewport
       ref={ref}
       className={cn(
-        'origin-top-center relative mt-1.5 h-radix-nav-viewport w-full overflow-hidden rounded-md border bg-popover text-popover-foreground shadow data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-90 md:w-radix-nav-viewport',
+        'origin-top-center relative mt-1.5 h-radix-nav-viewport w-full overflow-hidden rounded-md border border-border bg-popover text-popover-foreground shadow data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-90 md:w-radix-nav-viewport',
         className,
       )}
       {...props}

package/src/components/notification/notification.meta.md

@@ -10,7 +10,7 @@ displayName: 通知
 
 # Notification 通知
 
-卡片式通知 — antd 独有补足。**等价 antd `Notification`**(右上角 title + description 卡片),与 sonner 同一渲染栈。基于 sonner `toast.custom` 二次封装,业务侧**只需要挂载一次 `<Toaster />`**,后续在任意地方调 `notification.success(...)` / `notification.error(...)` 等触发。
+卡片式通知 — antd 独有补足。**等价 antd `Notification`**(右上角 title + description 卡片),与 sonner 同一渲染栈。基于 sonner `toast.custom` 二次封装,业务侧**只需要挂载一次 `<Toaster />`**,后续在任意地方调 `notification.success(...)` / `notification.destructive(...)` 等触发。4 档语义色对齐 [ADR 0021](../../../../docs/adr/0021-semantic-color-api-unification.md):`primary / success / warning / destructive`。
 
 ## When to use
 
@@ -40,10 +40,10 @@ _(组件无 `<Name>Props` interface — props 详见 [`notification.tsx`](./noti
 
 > `teamix-evo ui add notification` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry    | 类型      | 描述                                                                                              |
-| -------- | --------- | ------------------------------------------------------------------------------------------------- |
-| `cn`     | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                                |
-| `sonner` | component | Toast 通知 — sonner 包装,等价 antd message + notification 并集(toast() 函数式 API + Toaster 容器) |
+| Entry    | 类型      | 描述                                                                                                                       |
+| -------- | --------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `cn`     | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                                                         |
+| `sonner` | component | Toast 通知 — sonner 包装,等价 antd message + notification 并集(toast() 函数式 API + Toaster 容器,面性 5 状态图标 + 无边框) |
 
 ### npm 依赖
 
@@ -60,7 +60,7 @@ pnpm add sonner@^1.5.0 lucide-react@^0.460.0
 - **业务侧必须挂载 `<Toaster />`** —— Notification 与 toast 共用同一容器,通常挂在 root layout
 - **`title` 用动词或事件名**:"部署成功"/"订单已创建";**不要**写"提示"等空话
 - **`description` 解释后果或下一步**:"用户可在 1 分钟内访问新版本"/"详情请查看订单页";**不要**重复 title
-- **类型语义不要混淆**:`success` 用于成功完成,`warning` 用于风险提示但操作未失败,`error` 用于真正失败 — 与 `Alert` / `Toast` 的语义一致
+- **语义不要混淆**:`success` 用于成功完成,`warning` 用于风险提示但操作未失败,`destructive` 用于真正失败 — 与 `Alert` / `Toast` 的语义一致(对齐 ADR 0021,不再使用 `info` / `error` 字面)
 - **不要在 onConfirm 里同时调 toast 和 notification** — 单次反馈选一种,避免视觉噪音
 - **`destroy(id)` 主动关闭**:用于"自动重试成功"等场景,把之前的 error notification 替换掉
 
@@ -80,14 +80,14 @@ notification.warning({
   description: '请在 3 天内续费,否则服务将暂停',
 });
 
-notification.error({
+notification.destructive({
   title: '上传失败',
   description: '请检查网络连接后重试',
 });
 
 // 自定义 + 操作按钮(action 透传 sonner)
 const id = notification.open({
-  type: 'info',
+  color: 'primary',
   title: '新版本可用',
   description: 'v2.5 已发布,刷新页面以应用更新',
   action: { label: '刷新', onClick: () => location.reload() },
@@ -98,3 +98,36 @@ notification.destroy(id);
 ```
 
 > 应用根组件需要挂载一次 `<Toaster />`(来自 `sonner` entry),Notification 与 toast 共用此容器。
+
+---
+
+## Notification 形态 — 旧库 API → 新映射
+
+> 旧库 `Notification`(hybridcloud,含 open/success/error/warning 命令式) → 新库 `notification`(小写对象)。
+> 新库基于 sonner `toast.custom` 封装,共用 `<Toaster />` 容器。
+
+### 命名 & 结构映射
+
+| 旧库                                 | 新库                                      | 说明                          |
+| ------------------------------------ | ----------------------------------------- | ----------------------------- |
+| `Notification` (类)                  | `notification` (对象)                     | 大小写变更                    |
+| `Notification.success()`             | `notification.success()`                  | 直接映射                      |
+| `Notification.error()`               | `notification.destructive()`              | error → destructive(ADR 0021) |
+| `Notification.warning()`             | `notification.warning()`                  | 直接映射                      |
+| `Notification.notice()`              | `notification.open({ color: 'primary' })` | notice → primary              |
+| `options.content`                    | `options.description`                     | 字段重命名                    |
+| `options.type`                       | `options.color`                           | type → color(4 档语义色)      |
+| `Notification.close(key)`            | `notification.destroy(id)`                | 主动关闭                      |
+| `Notification.config({ placement })` | `<Toaster position="..." />`              | 声明式配置                    |
+| `size: large/medium`                 | 不复刻                                    | 固定尺寸                      |
+| `icon` 自定义                        | 不复刻                                    | 固定语义图标(规范化)          |
+| `type='help'`                        | `notification.open({ color: 'primary' })` | 合并到 primary                |
+
+### 迁移 FAQ
+
+| 问题                          | 回答                                                                |
+| ----------------------------- | ------------------------------------------------------------------- |
+| error 为什么变成 destructive? | 对齐 ADR 0021 语义色规范,统一用 destructive 表示错误/危险           |
+| Notification 和 toast 的关系? | 共用 Toaster 容器;简短提示用 toast,带标题+描述的卡片用 notification |
+| 怎么控制位置?                 | `<Toaster position="top-right" />`(默认右上)                        |
+| 怎么加 action 按钮?           | `notification.open({ ..., action: { label, onClick } })`            |

package/src/components/notification/notification.stories.tsx

@@ -1,16 +1,16 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Toaster } from '@/components/sonner/sonner';
 import { notification } from './notification';
 import { Button } from '@/components/button/button';
 
 const meta: Meta = {
-  title: '反馈与浮层 · Feedback/Notification',
+  title: '反馈 · Feedback/Notification',
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '卡片式通知 — 右上角 title + description 卡片（部署成功 / 配额提醒）。基于 sonner toast.custom，业务侧只需挂载一次 `<Toaster />`，后续在任意地方 imperative 触发。等价 antd `Notification`，与 toast(message)互补。',
+          '卡片式通知 — 右上角 title + description 卡片（部署成功 / 配额提醒）。基于 sonner toast.custom，业务侧只需挂载一次 `<Toaster />`，后续在任意地方 imperative 触发。4 档语义色(primary / success / warning / destructive)对齐 ADR 0021，与 toast(message)互补。',
       },
     },
   },
@@ -27,13 +27,13 @@ export const Playground: Story = {
         <Button
           variant="outline"
           onClick={() =>
-            notification.info({
+            notification.primary({
               title: '提示',
-              description: '这是一条 info 通知',
+              description: '这是一条 primary 通知',
             })
           }
         >
-          Info
+          Primary
         </Button>
         <Button
           onClick={() =>
@@ -59,13 +59,13 @@ export const Playground: Story = {
         <Button
           variant="destructive"
           onClick={() =>
-            notification.error({
+            notification.destructive({
               title: '上传失败',
               description: '请检查网络连接后重试',
             })
           }
         >
-          Error
+          Destructive
         </Button>
       </div>
     </div>
@@ -79,7 +79,7 @@ export const WithAction: Story = {
       <Button
         onClick={() =>
           notification.open({
-            type: 'info',
+            color: 'primary',
             title: '新版本可用',
             description: 'v2.5 已发布,刷新页面以应用更新',
             action: {

package/src/components/notification/notification.tsx

@@ -14,40 +14,54 @@ import { cn } from '@/utils/cn';
  *   - `notification.open()` 是 **title + description 卡片**(对应 antd `notification`)
  */
 
-export type NotificationType = 'info' | 'success' | 'warning' | 'error';
+export type NotificationColor =
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'destructive';
 
-export interface NotificationOptions extends Omit<ExternalToast, 'description' | 'icon'> {
+export interface NotificationOptions
+  extends Omit<ExternalToast, 'description' | 'icon'> {
   /** 标题(antd `message` 并集,但 antd 这里命名为 message,易混淆 — 我们用更准确的 `title`)。 */
   title: React.ReactNode;
   /** 描述(antd `description` 并集)。 */
   description?: React.ReactNode;
   /**
-   * 状态 — 决定左侧 icon 颜色;`open()` 默认 `info`。
-   * `success` / `warning` / `error` 也可用对应快捷方法。
+   * 语义色(对齐 ADR 0021)— 决定左侧 icon 颜色;`open()` 默认 `primary`。
+   * `success` / `warning` / `destructive` 也可用对应快捷方法。
    */
-  type?: NotificationType;
+  color?: NotificationColor;
+  /**
+   * 自定义左侧 icon — 覆盖默认按 `color` 映射的 lucide icon。
+   * 传 `null` 显式隐藏 icon(只展示文字内容)。
+   * @example
+   *   notification.open({ icon: <UserPlus className="size-5 text-primary" />, title: '新用户加入' })
+   */
+  icon?: React.ReactNode | null;
 }
 
-const iconMap: Record<NotificationType, React.ReactNode> = {
-  info: <Info className="size-5 text-primary" />,
+const iconMap: Record<NotificationColor, React.ReactNode> = {
+  primary: <Info className="size-5 text-primary" />,
   success: <CheckCircle2 className="size-5 text-success" />,
   warning: <AlertCircle className="size-5 text-warning" />,
-  error: <XCircle className="size-5 text-destructive" />,
+  destructive: <XCircle className="size-5 text-destructive" />,
 };
 
 function fire(
-  type: NotificationType,
-  { title, description, ...rest }: NotificationOptions,
+  color: NotificationColor,
+  { title, description, icon, ...rest }: NotificationOptions,
 ) {
+  // icon: undefined → 默认按 color 映射;null → 显式隐藏 icon;其他 ReactNode → 自定义
+  const iconNode = icon === undefined ? iconMap[color] : icon;
   return toast.custom(
     (id) => (
       <div
         role="alert"
         className={cn(
-          'flex w-notification gap-3 rounded-md border bg-background p-4 text-sm shadow-lg',
+          'flex w-notification gap-3 rounded-md border border-border bg-background p-4 text-xs shadow-lg',
         )}
       >
-        <span className="mt-0.5 shrink-0">{iconMap[type]}</span>
+        {iconNode ? <span className="mt-0.5 shrink-0">{iconNode}</span> : null}
         <div className="min-w-0 flex-1">
           <div className="font-semibold leading-tight">{title}</div>
           {description ? (
@@ -58,7 +72,7 @@ function fire(
           type="button"
           aria-label="关闭"
           onClick={() => toast.dismiss(id)}
-          className="text-muted-foreground transition-colors hover:text-foreground"
+          className="cursor-pointer text-muted-foreground transition-colors hover:text-foreground"
         >
           ×
         </button>
@@ -70,13 +84,14 @@ function fire(
 
 const notification = {
   /**
-   * 通用打开 — 通过 `type` 区分状态;若只传 title,样式同 `info`。
+   * 通用打开 — 通过 `color` 区分状态;若只传 title,样式同 `primary`。
    */
-  open: (opts: NotificationOptions) => fire(opts.type ?? 'info', opts),
-  info: (opts: Omit<NotificationOptions, 'type'>) => fire('info', opts),
-  success: (opts: Omit<NotificationOptions, 'type'>) => fire('success', opts),
-  warning: (opts: Omit<NotificationOptions, 'type'>) => fire('warning', opts),
-  error: (opts: Omit<NotificationOptions, 'type'>) => fire('error', opts),
+  open: (opts: NotificationOptions) => fire(opts.color ?? 'primary', opts),
+  primary: (opts: Omit<NotificationOptions, 'color'>) => fire('primary', opts),
+  success: (opts: Omit<NotificationOptions, 'color'>) => fire('success', opts),
+  warning: (opts: Omit<NotificationOptions, 'color'>) => fire('warning', opts),
+  destructive: (opts: Omit<NotificationOptions, 'color'>) =>
+    fire('destructive', opts),
   /** 主动关闭某条(传 `id`)/ 全部(不传)。 */
   destroy: (id?: string | number) => toast.dismiss(id),
 };