@teamix-evo/ui 0.1.1

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

@@ -0,0 +1,88 @@
+---
+id: native-select
+name: NativeSelect
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# NativeSelect
+
+原生下拉选择 — shadcn 2025-10 新增。**原生 `<select>` 元素**的样式封装,零 JS 开销,移动端弹起系统 picker,直接参与 form `submit`。与 `Select`(Radix)互为补充,分别面向"原生友好"与"可定制项 UI"两种诉求。
+
+## When to use
+
+- 移动端表单(系统原生 picker 更熟悉,触屏体验更好)
+- 无 JS / SSR-first 场景
+- 不需要自定义选项 UI 的简单下拉(国家、省份、单位等)
+- 表单数据靠原生 `submit` 收集,不想引入受控状态
+
+## When NOT to use
+
+- 需要搜索 / 虚拟列表 / 自定义选项渲染 → `Select`(Radix)/ `Combobox`
+- 多选 → `Select multiple`(原生 multi 体验差)→ 用 Radix 版
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `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) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **用 children `<option>`** 而非 `options` 数组 — 保留原生 `<optgroup>` / `disabled` / `selected` 表达力
+- **`appearance-none`** 已禁掉浏览器默认箭头,我们用 lucide ChevronDown 替代 — **不要**自己再加箭头
+- **不要做受控** — 原生 select 在受控时不流畅(光标位置 / 滚动会跳);需要受控时直接用 Radix `Select`
+- **可访问性**:本组件无需额外 aria,原生 `<select>` 是最 accessible 的下拉之一
+- **移动端**:不要给 `<select>` 加自定义 `onTouchStart` / `onClick`,会破坏系统 picker
+
+## Examples
+
+```tsx
+import { NativeSelect } from '@/components/ui/native-select';
+
+// 基础
+<NativeSelect defaultValue="apple">
+  <option value="apple">苹果</option>
+  <option value="banana">香蕉</option>
+  <option value="cherry">樱桃</option>
+</NativeSelect>
+
+// 分组
+<NativeSelect>
+  <optgroup label="水果">
+    <option value="apple">苹果</option>
+    <option value="banana">香蕉</option>
+  </optgroup>
+  <optgroup label="蔬菜">
+    <option value="carrot">胡萝卜</option>
+  </optgroup>
+</NativeSelect>
+
+// 表单 submit
+<form action="/api/sort">
+  <NativeSelect name="sort" defaultValue="date">
+    <option value="date">按日期</option>
+    <option value="name">按名称</option>
+  </NativeSelect>
+</form>
+```

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

@@ -0,0 +1,80 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { NativeSelect } from './native-select';
+
+const meta: Meta<typeof NativeSelect> = {
+  title: '表单与输入 · Form/NativeSelect',
+  component: NativeSelect,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '原生下拉选择 — 原生 `<select>` 元素的样式封装,零 JS 开销,移动端弹起系统 picker,直接参与 form submit。与 Radix `Select` 互为补充:NativeSelect 面向原生 / 移动端友好,Radix Select 面向自定义项 UI / 受控复杂表单。shadcn 2025-10 新增,等价 antd 体系中无直接对应(antd Select 全用 popup)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    disabled: { control: 'boolean' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof NativeSelect>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <NativeSelect {...args} defaultValue="apple" wrapperClassName="w-48">
+      <option value="apple">苹果</option>
+      <option value="banana">香蕉</option>
+      <option value="cherry">樱桃</option>
+    </NativeSelect>
+  ),
+};
+
+export const Grouped: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <NativeSelect defaultValue="apple" wrapperClassName="w-48">
+      <optgroup label="水果">
+        <option value="apple">苹果</option>
+        <option value="banana">香蕉</option>
+      </optgroup>
+      <optgroup label="蔬菜">
+        <option value="carrot">胡萝卜</option>
+        <option value="celery">芹菜</option>
+      </optgroup>
+    </NativeSelect>
+  ),
+};
+
+export const Disabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <NativeSelect disabled defaultValue="apple" wrapperClassName="w-48">
+      <option value="apple">不可改</option>
+    </NativeSelect>
+  ),
+};
+
+export const InForm: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        const fd = new FormData(e.currentTarget);
+        // eslint-disable-next-line no-alert
+        alert(`提交: sort=${fd.get('sort')}`);
+      }}
+      className="flex items-center gap-2"
+    >
+      <NativeSelect name="sort" defaultValue="date" wrapperClassName="w-40">
+        <option value="date">按日期</option>
+        <option value="name">按名称</option>
+      </NativeSelect>
+      <button type="submit" className="rounded-md border px-3 py-1 text-sm hover:bg-accent">
+        提交
+      </button>
+    </form>
+  ),
+};

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

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { ChevronDown } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+export interface NativeSelectProps
+  extends React.SelectHTMLAttributes<HTMLSelectElement> {
+  /**
+   * 容器额外 className(给外层 wrapper,而非 `<select>` 本身)。
+   */
+  wrapperClassName?: string;
+}
+
+/**
+ * 原生 `<select>` 包装 — shadcn 2025-10 新增。
+ * 与 Radix `Select` 的区别:
+ *   - **零 JS 开销**,移动端弹起系统原生 picker(更熟悉)
+ *   - 表单 `submit` 直接带 value,不需要受控
+ *   - 不支持自定义选项渲染(那是 Radix Select 的活)
+ *
+ * 用 `<NativeSelect><option>...</option></NativeSelect>` 而非 `options` 数组,
+ * 保留原生标签的灵活性(`<optgroup>` 嵌套、disabled / selected 属性等)。
+ */
+const NativeSelect = React.forwardRef<HTMLSelectElement, NativeSelectProps>(
+  ({ className, wrapperClassName, children, disabled, ...props }, ref) => (
+    <div
+      className={cn(
+        'relative inline-flex w-full items-center',
+        wrapperClassName,
+      )}
+    >
+      <select
+        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',
+          'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+          'disabled:cursor-not-allowed disabled:opacity-50',
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </select>
+      <ChevronDown
+        aria-hidden="true"
+        className="pointer-events-none absolute right-2 size-4 text-muted-foreground"
+      />
+    </div>
+  ),
+);
+NativeSelect.displayName = 'NativeSelect';
+
+export { NativeSelect };

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

@@ -0,0 +1,108 @@
+---
+id: navigation-menu
+name: NavigationMenu
+type: component
+category: navigation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# NavigationMenu
+
+主导航菜单 — Radix NavigationMenu。**用于网站 / 营销页 / 应用顶部主导航**(产品 / 文档 / 定价 / 关于)。
+**与 Menubar 区别**:NavigationMenu 是**网页级横向导航**(每项可有富 Content 面板,展示子页面预览);Menubar 是**应用级菜单**(文件 / 编辑等)。
+
+## When to use
+
+- 网站顶部主导航(产品 / 解决方案 / 资源 / 公司)
+- 后台应用顶栏页面级跳转
+- 多产品矩阵的入口面板
+
+## When NOT to use
+
+- 应用功能菜单 → `Menubar`
+- 单按钮下拉 → `DropdownMenu`
+- 侧边导航 → `Sidebar`
+
+## Props
+
+> 以下表格由 `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 -->
+
+## 依赖
+
+> 以下表格由 `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) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```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 视觉)。
+
+## AI 生成纪律
+
+- **`<NavigationMenuLink asChild>` 配 router**:Next.js / React Router 的 Link 嵌入,asChild 透传
+- **Content 面板内容富但克制**:常见结构是 grid + 条目卡片,**不要**塞表单 / 长文本
+- **Triger 文字 ≤ 4 字**:主导航文案极简
+- **不嵌套 NavigationMenu**:嵌套主导航是反模式
+
+## Examples
+
+```tsx
+import * as React from 'react';
+import {
+  NavigationMenu, NavigationMenuList, NavigationMenuItem,
+  NavigationMenuTrigger, NavigationMenuContent,
+  NavigationMenuLink, navigationMenuTriggerStyle,
+} from '@/components/ui/navigation-menu';
+
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>产品</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <ul className="grid w-[400px] gap-3 p-4 md:w-[500px] md:grid-cols-2">
+          <li>
+            <NavigationMenuLink asChild>
+              <a href="/design" className="block rounded-md p-3 hover:bg-accent">
+                <div className="text-sm font-medium">Design</div>
+                <p className="text-xs text-muted-foreground">设计体系与 tokens</p>
+              </a>
+            </NavigationMenuLink>
+          </li>
+          <li>
+            <NavigationMenuLink asChild>
+              <a href="/ui" className="block rounded-md p-3 hover:bg-accent">
+                <div className="text-sm font-medium">UI</div>
+                <p className="text-xs text-muted-foreground">源码注入式组件</p>
+              </a>
+            </NavigationMenuLink>
+          </li>
+        </ul>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+    <NavigationMenuItem>
+      <NavigationMenuLink asChild className={navigationMenuTriggerStyle()}>
+        <a href="/docs">文档</a>
+      </NavigationMenuLink>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```

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

@@ -0,0 +1,112 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  NavigationMenu,
+  NavigationMenuList,
+  NavigationMenuItem,
+  NavigationMenuTrigger,
+  NavigationMenuContent,
+  NavigationMenuLink,
+  navigationMenuTriggerStyle,
+} from './navigation-menu';
+
+const meta: Meta<typeof NavigationMenu> = {
+  title: '导航 · Navigation/NavigationMenu',
+  component: NavigationMenu,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof NavigationMenu>;
+
+export const Default: Story = {
+  parameters: { layout: 'centered' },
+  render: () => (
+    <NavigationMenu>
+      <NavigationMenuList>
+        <NavigationMenuItem>
+          <NavigationMenuTrigger>产品</NavigationMenuTrigger>
+          <NavigationMenuContent>
+            <ul className="grid w-[420px] gap-3 p-4 md:w-[520px] md:grid-cols-2">
+              <li>
+                <NavigationMenuLink asChild>
+                  <a
+                    href="#design"
+                    onClick={(e) => e.preventDefault()}
+                    className="block rounded-md p-3 hover:bg-accent"
+                  >
+                    <div className="text-sm font-medium">Design</div>
+                    <p className="text-xs text-muted-foreground">
+                      设计体系与 tokens
+                    </p>
+                  </a>
+                </NavigationMenuLink>
+              </li>
+              <li>
+                <NavigationMenuLink asChild>
+                  <a
+                    href="#ui"
+                    onClick={(e) => e.preventDefault()}
+                    className="block rounded-md p-3 hover:bg-accent"
+                  >
+                    <div className="text-sm font-medium">UI</div>
+                    <p className="text-xs text-muted-foreground">
+                      源码注入式组件
+                    </p>
+                  </a>
+                </NavigationMenuLink>
+              </li>
+              <li>
+                <NavigationMenuLink asChild>
+                  <a
+                    href="#cli"
+                    onClick={(e) => e.preventDefault()}
+                    className="block rounded-md p-3 hover:bg-accent"
+                  >
+                    <div className="text-sm font-medium">CLI</div>
+                    <p className="text-xs text-muted-foreground">
+                      teamix-evo 命令行
+                    </p>
+                  </a>
+                </NavigationMenuLink>
+              </li>
+              <li>
+                <NavigationMenuLink asChild>
+                  <a
+                    href="#skills"
+                    onClick={(e) => e.preventDefault()}
+                    className="block rounded-md p-3 hover:bg-accent"
+                  >
+                    <div className="text-sm font-medium">Skills</div>
+                    <p className="text-xs text-muted-foreground">
+                      AI IDE 技能
+                    </p>
+                  </a>
+                </NavigationMenuLink>
+              </li>
+            </ul>
+          </NavigationMenuContent>
+        </NavigationMenuItem>
+        <NavigationMenuItem>
+          <NavigationMenuLink
+            asChild
+            className={navigationMenuTriggerStyle()}
+          >
+            <a href="#docs" onClick={(e) => e.preventDefault()}>
+              文档
+            </a>
+          </NavigationMenuLink>
+        </NavigationMenuItem>
+        <NavigationMenuItem>
+          <NavigationMenuLink
+            asChild
+            className={navigationMenuTriggerStyle()}
+          >
+            <a href="#pricing" onClick={(e) => e.preventDefault()}>
+              定价
+            </a>
+          </NavigationMenuLink>
+        </NavigationMenuItem>
+      </NavigationMenuList>
+    </NavigationMenu>
+  ),
+};

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

@@ -0,0 +1,125 @@
+import * as React from 'react';
+import * as NavigationMenuPrimitive from '@radix-ui/react-navigation-menu';
+import { cva } from 'class-variance-authority';
+import { ChevronDown } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+const NavigationMenu = React.forwardRef<
+  React.ElementRef<typeof NavigationMenuPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Root>
+>(({ className, children, ...props }, ref) => (
+  <NavigationMenuPrimitive.Root
+    ref={ref}
+    className={cn('relative z-10 flex max-w-max flex-1 items-center justify-center', className)}
+    {...props}
+  >
+    {children}
+    <NavigationMenuViewport />
+  </NavigationMenuPrimitive.Root>
+));
+NavigationMenu.displayName = NavigationMenuPrimitive.Root.displayName;
+
+const NavigationMenuList = React.forwardRef<
+  React.ElementRef<typeof NavigationMenuPrimitive.List>,
+  React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.List>
+>(({ className, ...props }, ref) => (
+  <NavigationMenuPrimitive.List
+    ref={ref}
+    className={cn(
+      'group flex flex-1 list-none items-center justify-center gap-1',
+      className,
+    )}
+    {...props}
+  />
+));
+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',
+);
+
+const NavigationMenuTrigger = React.forwardRef<
+  React.ElementRef<typeof NavigationMenuPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Trigger>
+>(({ className, children, ...props }, ref) => (
+  <NavigationMenuPrimitive.Trigger
+    ref={ref}
+    className={cn(navigationMenuTriggerStyle(), 'group', className)}
+    {...props}
+  >
+    {children}{' '}
+    <ChevronDown
+      className="relative top-px ml-1 size-3 transition duration-200 group-data-[state=open]:rotate-180"
+      aria-hidden="true"
+    />
+  </NavigationMenuPrimitive.Trigger>
+));
+NavigationMenuTrigger.displayName = NavigationMenuPrimitive.Trigger.displayName;
+
+const NavigationMenuContent = React.forwardRef<
+  React.ElementRef<typeof NavigationMenuPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Content>
+>(({ className, ...props }, ref) => (
+  <NavigationMenuPrimitive.Content
+    ref={ref}
+    className={cn(
+      'left-0 top-0 w-full data-[motion^=from-]:animate-in data-[motion^=to-]:animate-out data-[motion^=from-]:fade-in data-[motion^=to-]:fade-out data-[motion=from-end]:slide-in-from-right-52 data-[motion=from-start]:slide-in-from-left-52 data-[motion=to-end]:slide-out-to-right-52 data-[motion=to-start]:slide-out-to-left-52 md:absolute md:w-auto',
+      className,
+    )}
+    {...props}
+  />
+));
+NavigationMenuContent.displayName = NavigationMenuPrimitive.Content.displayName;
+
+const NavigationMenuLink = NavigationMenuPrimitive.Link;
+
+const NavigationMenuViewport = React.forwardRef<
+  React.ElementRef<typeof NavigationMenuPrimitive.Viewport>,
+  React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Viewport>
+>(({ className, ...props }, ref) => (
+  <div className={cn('absolute left-0 top-full flex justify-center')}>
+    <NavigationMenuPrimitive.Viewport
+      ref={ref}
+      className={cn(
+        'origin-top-center relative mt-1.5 h-[var(--radix-navigation-menu-viewport-height)] 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-[var(--radix-navigation-menu-viewport-width)]',
+        className,
+      )}
+      {...props}
+    />
+  </div>
+));
+NavigationMenuViewport.displayName =
+  NavigationMenuPrimitive.Viewport.displayName;
+
+const NavigationMenuIndicator = React.forwardRef<
+  React.ElementRef<typeof NavigationMenuPrimitive.Indicator>,
+  React.ComponentPropsWithoutRef<typeof NavigationMenuPrimitive.Indicator>
+>(({ className, ...props }, ref) => (
+  <NavigationMenuPrimitive.Indicator
+    ref={ref}
+    className={cn(
+      'top-full z-[1] flex h-1.5 items-end justify-center overflow-hidden data-[state=visible]:animate-in data-[state=hidden]:animate-out data-[state=hidden]:fade-out data-[state=visible]:fade-in',
+      className,
+    )}
+    {...props}
+  >
+    <div className="relative top-[60%] size-2 rotate-45 rounded-tl-sm bg-border shadow-md" />
+  </NavigationMenuPrimitive.Indicator>
+));
+NavigationMenuIndicator.displayName =
+  NavigationMenuPrimitive.Indicator.displayName;
+
+export {
+  navigationMenuTriggerStyle,
+  NavigationMenu,
+  NavigationMenuList,
+  NavigationMenuItem,
+  NavigationMenuContent,
+  NavigationMenuTrigger,
+  NavigationMenuLink,
+  NavigationMenuIndicator,
+  NavigationMenuViewport,
+};

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

@@ -0,0 +1,91 @@
+---
+id: notification
+name: notification
+type: component
+category: feedback
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Notification
+
+卡片式通知 — antd 独有补足。**等价 antd `Notification`**(右上角 title + description 卡片),与 sonner 同一渲染栈。基于 sonner `toast.custom` 二次封装,业务侧**只需要挂载一次 `<Toaster />`**,后续在任意地方调 `notification.success(...)` / `notification.error(...)` 等触发。
+
+## When to use
+
+- 操作完成的"带描述卡片"反馈(部署成功、文件已上传、订单已生成)
+- 异步流程的最终结果通知(配 description 解释下一步)
+- 系统级提醒(订阅到期、新版本可用)
+
+## When NOT to use
+
+- 短文字提示("已保存") → `toast()`(对应 antd `message`)
+- 阻塞式确认 → `Dialog` / `AlertDialog` / `Popconfirm`
+- 表单字段错误 → `FieldError`(就近显示)
+
+<!-- auto:props:begin -->
+_(组件无 `<Name>Props` interface — props 详见 [`notification.tsx`](./notification.tsx))_
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `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 容器) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add sonner@^1.5.0 lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **业务侧必须挂载 `<Toaster />`** —— Notification 与 toast 共用同一容器,通常挂在 root layout
+- **`title` 用动词或事件名**:"部署成功"/"订单已创建";**不要**写"提示"等空话
+- **`description` 解释后果或下一步**:"用户可在 1 分钟内访问新版本"/"详情请查看订单页";**不要**重复 title
+- **类型语义不要混淆**:`success` 用于成功完成,`warning` 用于风险提示但操作未失败,`error` 用于真正失败 — 与 `Alert` / `Toast` 的语义一致
+- **不要在 onConfirm 里同时调 toast 和 notification** — 单次反馈选一种,避免视觉噪音
+- **`destroy(id)` 主动关闭**:用于"自动重试成功"等场景,把之前的 error notification 替换掉
+
+## Examples
+
+```tsx
+import { notification } from '@/components/ui/notification';
+
+// 各类型快捷方法
+notification.success({
+  title: '部署成功',
+  description: '用户可在 1 分钟内访问新版本',
+});
+
+notification.warning({
+  title: '配额即将到期',
+  description: '请在 3 天内续费,否则服务将暂停',
+});
+
+notification.error({
+  title: '上传失败',
+  description: '请检查网络连接后重试',
+});
+
+// 自定义 + 操作按钮(action 透传 sonner)
+const id = notification.open({
+  type: 'info',
+  title: '新版本可用',
+  description: 'v2.5 已发布,刷新页面以应用更新',
+  action: { label: '刷新', onClick: () => location.reload() },
+});
+
+// 主动关闭
+notification.destroy(id);
+```
+
+> 应用根组件需要挂载一次 `<Toaster />`(来自 `sonner` entry),Notification 与 toast 共用此容器。