@teamix-evo/ui 0.1.1

package/src/components/toggle-group/toggle-group.meta.md

@@ -0,0 +1,90 @@
+---
+id: toggle-group
+name: ToggleGroup
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# ToggleGroup
+
+切换按钮组 — Radix ToggleGroup,**单选(`type="single"`)+ 多选(`type="multiple"`)**。复用 Toggle 的 cva variants(default / outline)与 size。
+
+## When to use
+
+- 工具栏(Bold / Italic / Underline)— `type="multiple"`
+- 视图切换(Grid / List / Card)— `type="single"`
+- 段落对齐(Left / Center / Right / Justify)— `type="single"`
+
+## When NOT to use
+
+- 表单选择 → `RadioGroup`(单选)/ `Checkbox`(多选)
+- 选项数 > 5 → `Select` / `Combobox`
+- 单个二元开关 → `Switch` / `Toggle`
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `'default' \| 'outline'` | `"default"` | – | 视觉风格,与同源的 [`Toggle`](../toggle/toggle.tsx) 保持一致。 |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸,与同源的 [`Toggle`](../toggle/toggle.tsx) 保持一致。 |
+| `className` | `string` | – | – | 容器 className,会与默认布局类合并。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add toggle-group` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `toggle` | component | 二元状态按钮 — Radix Toggle 包装,工具栏图标级开关 |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add @radix-ui/react-toggle-group@^1.1.0 class-variance-authority@^0.7.0
+```
+<!-- auto:deps:end -->
+
+> 透传 Radix ToggleGroup.Root 所有 props(`type` / `value` / `defaultValue` / `onValueChange` / `disabled` / `loop` / `orientation` 等)。
+> `ToggleGroupItem` 接受 `value` 等 Radix 标准 props。
+
+## AI 生成纪律
+
+- **`type` 必传**:`type="single"` 与 `type="multiple"` value 类型不同(string vs string[])
+- **每项 value 唯一**:不要用 index
+- **`size` / `variant` 在 Group 上设置**:Item 自动继承,不要逐项设置
+- **图标按钮配 `aria-label`**
+
+## Examples
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group';
+import { AlignLeft, AlignCenter, AlignRight } from 'lucide-react';
+
+// 单选(对齐方式)
+<ToggleGroup type="single" defaultValue="left">
+  <ToggleGroupItem value="left" aria-label="左对齐"><AlignLeft /></ToggleGroupItem>
+  <ToggleGroupItem value="center" aria-label="居中"><AlignCenter /></ToggleGroupItem>
+  <ToggleGroupItem value="right" aria-label="右对齐"><AlignRight /></ToggleGroupItem>
+</ToggleGroup>
+
+// 多选(文本格式)
+<ToggleGroup type="multiple" variant="outline">
+  <ToggleGroupItem value="bold">B</ToggleGroupItem>
+  <ToggleGroupItem value="italic">I</ToggleGroupItem>
+  <ToggleGroupItem value="underline">U</ToggleGroupItem>
+</ToggleGroup>
+```

package/src/components/toggle-group/toggle-group.stories.tsx

@@ -0,0 +1,83 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  AlignLeft,
+  AlignCenter,
+  AlignRight,
+  AlignJustify,
+  Bold,
+  Italic,
+  Underline,
+} from 'lucide-react';
+import { ToggleGroup, ToggleGroupItem } from './toggle-group';
+
+const meta: Meta<typeof ToggleGroup> = {
+  title: '表单与输入 · Form/ToggleGroup',
+  component: ToggleGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '切换按钮组 — 一组二状态按钮的集合，可选单选 (`type="single"`) 或多选 (`type="multiple"`)，常用于对齐方式 / 字体样式等工具栏场景。Radix ToggleGroup 实现，shadcn 专有（antd 以 `Radio.Group` + `Radio.Button` 表达单选、以菜单多选表达多选）；`variant` / `size` 与 `Toggle` 保持一致。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    variant: { control: 'inline-radio', options: ['default', 'outline'] },
+    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
+    disabled: { control: 'boolean' },
+  },
+  args: { variant: 'default', size: 'default' },
+};
+
+export default meta;
+type Story = StoryObj<typeof ToggleGroup>;
+
+export const SingleAlign: Story = {
+  args: { type: 'single', defaultValue: 'left' },
+  render: (args) => (
+    <ToggleGroup {...args}>
+      <ToggleGroupItem value="left" aria-label="左对齐">
+        <AlignLeft />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="center" aria-label="居中">
+        <AlignCenter />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="right" aria-label="右对齐">
+        <AlignRight />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="justify" aria-label="两端对齐">
+        <AlignJustify />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  ),
+};
+
+export const MultipleFormat: Story = {
+  args: { type: 'multiple', variant: 'outline' },
+  parameters: { controls: { disable: true } },
+  render: (args) => (
+    <ToggleGroup {...args}>
+      <ToggleGroupItem value="bold" aria-label="加粗">
+        <Bold />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="italic" aria-label="斜体">
+        <Italic />
+      </ToggleGroupItem>
+      <ToggleGroupItem value="underline" aria-label="下划线">
+        <Underline />
+      </ToggleGroupItem>
+    </ToggleGroup>
+  ),
+};
+
+export const TextItems: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <ToggleGroup type="single" defaultValue="grid" variant="outline">
+      <ToggleGroupItem value="grid">网格</ToggleGroupItem>
+      <ToggleGroupItem value="list">列表</ToggleGroupItem>
+      <ToggleGroupItem value="card">卡片</ToggleGroupItem>
+    </ToggleGroup>
+  ),
+};

package/src/components/toggle-group/toggle-group.tsx

@@ -0,0 +1,78 @@
+import * as React from 'react';
+import * as ToggleGroupPrimitive from '@radix-ui/react-toggle-group';
+import { type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/utils/cn';
+import { toggleVariants } from '@/components/toggle/toggle';
+
+const ToggleGroupContext = React.createContext<
+  VariantProps<typeof toggleVariants>
+>({ size: 'default', variant: 'default' });
+
+/**
+ * ToggleGroup 自身的可定制属性。底层 type=`single`|`multiple` 与对应的
+ * `value` / `onValueChange` 等由 Radix 的 union props 透传。
+ */
+export interface ToggleGroupProps {
+  /**
+   * 视觉风格,与同源的 [`Toggle`](../toggle/toggle.tsx) 保持一致。
+   * @default "default"
+   */
+  variant?: 'default' | 'outline';
+  /**
+   * 尺寸,与同源的 [`Toggle`](../toggle/toggle.tsx) 保持一致。
+   * @default "default"
+   */
+  size?: 'sm' | 'default' | 'lg';
+  /**
+   * 容器 className,会与默认布局类合并。
+   */
+  className?: string;
+}
+
+function ToggleGroup({
+  className,
+  variant,
+  size,
+  children,
+  ...props
+}: ToggleGroupProps &
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>) {
+  return (
+    <ToggleGroupPrimitive.Root
+      className={cn('flex items-center justify-center gap-1', className)}
+      {...props}
+    >
+      <ToggleGroupContext.Provider value={{ variant, size }}>
+        {children}
+      </ToggleGroupContext.Provider>
+    </ToggleGroupPrimitive.Root>
+  );
+}
+ToggleGroup.displayName = ToggleGroupPrimitive.Root.displayName;
+
+const ToggleGroupItem = React.forwardRef<
+  React.ElementRef<typeof ToggleGroupPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> &
+    VariantProps<typeof toggleVariants>
+>(({ className, children, variant, size, ...props }, ref) => {
+  const ctx = React.useContext(ToggleGroupContext);
+  return (
+    <ToggleGroupPrimitive.Item
+      ref={ref}
+      className={cn(
+        toggleVariants({
+          variant: ctx.variant ?? variant,
+          size: ctx.size ?? size,
+        }),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </ToggleGroupPrimitive.Item>
+  );
+});
+ToggleGroupItem.displayName = ToggleGroupPrimitive.Item.displayName;
+
+export { ToggleGroup, ToggleGroupItem };

package/src/components/tooltip/tooltip.meta.md

@@ -0,0 +1,99 @@
+---
+id: tooltip
+name: Tooltip
+type: component
+category: feedback
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Tooltip
+
+文字提示气泡 — Radix Tooltip + antd `arrow / placement(side)` 并集。
+**两种用法**:`<Tooltip title="...">{trigger}</Tooltip>` 一行包装,或拆分原子组件(`TooltipRoot/Trigger/Content`)精细控制。
+
+> **必须用 `<TooltipProvider>` 包裹**(通常在应用根),或在单 Tooltip 上传 `withProvider`。
+
+## When to use
+
+- 图标按钮的文字解释(无障碍 + 视觉提示)
+- 表单字段的辅助说明(替代占空间的描述文字)
+- 数据列的列宽不足导致截断时的完整内容
+
+## When NOT to use
+
+- 包含交互的内容 → 用 `Popover` 或 `HoverCard`
+- 长文本(超过 1 行)→ 用 `HoverCard` 或对话框
+- 移动端首要功能 → 触屏不易触发 hover,改用按钮 + 弹窗
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `children` | `React.ReactElement` | – | ✓ | 触发器(单个 ReactElement,asChild 透传)。 |
+| `title` | `React.ReactNode` | – | ✓ | 提示内容。 |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `"top"` | – | 弹出方向。 |
+| `arrow` | `boolean` | `true` | – | 是否显示三角形箭头。 |
+| `delayDuration` | `number` | – | – | 显示延迟(ms),默认沿用 Provider 的 delayDuration。 |
+| `withProvider` | `boolean` | – | – | 强制传给 Provider 的 delayDuration(便于不挂 Provider 的场景)。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add tooltip` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add @radix-ui/react-tooltip@^1.1.0
+```
+<!-- auto:deps:end -->
+
+> 子组件 `TooltipProvider / TooltipRoot / TooltipTrigger / TooltipContent` 用于精细控制,见 [`tooltip.tsx`](./tooltip.tsx)。
+
+## AI 生成纪律
+
+- **必有 Provider**:不挂 Provider 直接用 Tooltip 会报错或不工作。**应用根**统一挂 `<TooltipProvider delayDuration={300}>`
+- **`title` 用文本不放交互**:Tooltip 内放 button / link 在键盘焦点流转上是反模式
+- **`title` ≤ 1 行**:超过 1 行换 `HoverCard`
+- **图标按钮必配 Tooltip + aria-label**:不能只靠 Tooltip 而省略 aria-label,屏幕阅读器不一定触发
+- **`side` 选 `top` 通常最稳**:避免被屏幕边缘截断;Radix 自带翻转回避能力,但标注首选语义
+
+## Examples
+
+```tsx
+import { Tooltip, TooltipProvider } from '@/components/ui/tooltip';
+import { Button } from '@/components/ui/button';
+import { Settings } from 'lucide-react';
+
+// 应用根挂 Provider
+<TooltipProvider delayDuration={300}>
+  <App />
+</TooltipProvider>
+
+// 简洁用法
+<Tooltip title="设置">
+  <Button size="icon" variant="ghost" aria-label="设置">
+    <Settings />
+  </Button>
+</Tooltip>
+
+// 自定义方向 + 无箭头
+<Tooltip title="向右弹出" side="right" arrow={false}>
+  <Button variant="outline">悬浮我</Button>
+</Tooltip>
+```

package/src/components/tooltip/tooltip.stories.tsx

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Settings } from 'lucide-react';
+import { Tooltip, TooltipProvider } from './tooltip';
+import { Button } from '@/components/button/button';
+
+const meta: Meta<typeof Tooltip> = {
+  title: '反馈与浮层 · Feedback/Tooltip',
+  component: Tooltip,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '文字气泡提示 — 鼠标悬停或键盘聚焦元素时弹出的简短提示。Radix Tooltip 实现 + antd Tooltip 的并集能力：需 `TooltipProvider` 包裹（可设 `delayDuration`），通过 `side` / `arrow` / `title` 调整方位与尖角；适用于纯文本辅助说明，丰富交互请选 `Popover`。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    side: {
+      control: 'inline-radio',
+      options: ['top', 'right', 'bottom', 'left'],
+    },
+    arrow: { control: 'boolean' },
+    title: { control: 'text' },
+  },
+  args: { side: 'top', arrow: true, title: '设置' },
+  decorators: [
+    (Story) => (
+      <TooltipProvider delayDuration={200}>
+        <div className="flex h-32 items-center justify-center">
+          <Story />
+        </div>
+      </TooltipProvider>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Tooltip>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <Tooltip {...args}>
+      <Button size="icon" variant="ghost" aria-label="设置">
+        <Settings />
+      </Button>
+    </Tooltip>
+  ),
+};
+
+export const Sides: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex items-center gap-3">
+      {(['top', 'right', 'bottom', 'left'] as const).map((s) => (
+        <Tooltip key={s} title={s} side={s}>
+          <Button variant="outline">{s}</Button>
+        </Tooltip>
+      ))}
+    </div>
+  ),
+};
+
+export const NoArrow: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Tooltip title="无箭头" arrow={false}>
+      <Button variant="outline">悬浮</Button>
+    </Tooltip>
+  ),
+};

package/src/components/tooltip/tooltip.tsx

@@ -0,0 +1,93 @@
+import * as React from 'react';
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+
+import { cn } from '@/utils/cn';
+
+const TooltipProvider = TooltipPrimitive.Provider;
+const TooltipRoot = TooltipPrimitive.Root;
+const TooltipTrigger = TooltipPrimitive.Trigger;
+
+export interface TooltipContentProps
+  extends React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content> {
+  /**
+   * 是否显示三角形箭头(antd `arrow` 并集)。
+   * @default true
+   */
+  arrow?: boolean;
+}
+
+const TooltipContent = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Content>,
+  TooltipContentProps
+>(({ className, sideOffset = 4, arrow = true, children, ...props }, ref) => (
+  <TooltipPrimitive.Portal>
+    <TooltipPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(
+        'z-50 overflow-hidden rounded-md bg-primary px-3 py-1.5 text-xs text-primary-foreground shadow-md animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      {arrow ? (
+        <TooltipPrimitive.Arrow className="fill-primary" width={8} height={4} />
+      ) : null}
+    </TooltipPrimitive.Content>
+  </TooltipPrimitive.Portal>
+));
+TooltipContent.displayName = TooltipPrimitive.Content.displayName;
+
+// ─── Convenience wrapper(antd-style 一行调用)──────────────────────────────
+
+export interface TooltipProps
+  extends Omit<
+    React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Root>,
+    'children'
+  > {
+  /** 触发器(单个 ReactElement,asChild 透传)。 */
+  children: React.ReactElement;
+  /** 提示内容。 */
+  title: React.ReactNode;
+  /** 弹出方向。 @default "top" */
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  /** 是否显示三角形箭头。 @default true */
+  arrow?: boolean;
+  /** 显示延迟(ms),默认沿用 Provider 的 delayDuration。 */
+  delayDuration?: number;
+  /** 强制传给 Provider 的 delayDuration(便于不挂 Provider 的场景)。 */
+  withProvider?: boolean;
+}
+
+const Tooltip: React.FC<TooltipProps> = ({
+  children,
+  title,
+  side = 'top',
+  arrow = true,
+  delayDuration,
+  withProvider = false,
+  ...rootProps
+}) => {
+  const inner = (
+    <TooltipRoot delayDuration={delayDuration} {...rootProps}>
+      <TooltipTrigger asChild>{children}</TooltipTrigger>
+      <TooltipContent side={side} arrow={arrow}>
+        {title}
+      </TooltipContent>
+    </TooltipRoot>
+  );
+  return withProvider ? (
+    <TooltipProvider delayDuration={delayDuration}>{inner}</TooltipProvider>
+  ) : (
+    inner
+  );
+};
+
+export {
+  Tooltip,
+  TooltipProvider,
+  TooltipRoot,
+  TooltipTrigger,
+  TooltipContent,
+};

package/src/components/tour/tour.meta.md

@@ -0,0 +1,116 @@
+---
+id: tour
+name: Tour
+type: component
+category: feedback
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Tour
+
+新手引导 — antd 独有补足。**等价 antd `Tour`**(v5.0+)。多步骤引导(spotlight + 卡片 + 步进按钮 + 可关闭),帮助新用户首次进入页面时了解关键功能位置。
+
+## When to use
+
+- 首次进入新功能页(关键功能位置说明)
+- 重大改版后的迁移引导(指出新位置)
+- 工具型应用的快速入门(画板 / 编辑器)
+
+## When NOT to use
+
+- 静态帮助文档 → 用 Anchor + 长文档
+- 单一提示 → `Tooltip` / `Popover`
+- 表单字段说明 → `FieldDescription`
+- 错误反馈 → `Alert` / `notification`
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `steps` | `TourStep[]` | – | ✓ | 步骤列表(antd `steps` 并集)。 |
+| `open` | `boolean` | – | – | 受控 open 状态。 |
+| `defaultOpen` | `boolean` | `false` | – | uncontrolled 初值。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | open 变化回调。 |
+| `current` | `number` | – | – | 当前步骤索引(受控)。 |
+| `onChange` | `(current: number) => void` | – | – | 步骤变化回调。 |
+| `onFinish` | `() => void` | – | – | 完成时回调(走到最后一步且点击"完成")。 |
+| `onClose` | `() => void` | – | – | 关闭回调(任意时刻点 X / mask)。 |
+| `mask` | `boolean` | `true` | – | 是否显示遮罩(antd `mask` 并集)。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add tour` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **业务侧自管"是否首次访问"** — 通常配 localStorage `tour:onboarding` 标记;**不要**期望本组件持久化
+- **`target` 必须是已挂载的元素**:用 `useRef` 绑定到 DOM 节点;Tour 用 `getBoundingClientRect()` 定位 spotlight
+- **`target` 不传 = 居中无 spotlight 模式**:用于"欢迎语" / "总结结束语"等无指向步骤
+- **步骤 ≤ 5**:再多用户会跳过 — 太长的引导改用文档 / 视频
+- **`onFinish` 应同时 set localStorage** 标记完成,避免再次弹出
+- **不要在 Tour 内放复杂表单 / 长文本** — 它是定位提示,不是阅读容器
+- **`mask=false`** 仅在用户需要边引导边操作时关闭;默认遮罩聚焦更强
+
+## Examples
+
+```tsx
+import { Tour } from '@/components/ui/tour';
+import * as React from 'react';
+
+function Page() {
+  const newBtnRef = React.useRef<HTMLButtonElement>(null);
+  const settingsRef = React.useRef<HTMLDivElement>(null);
+  const [open, setOpen] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!localStorage.getItem('tour:v1')) setOpen(true);
+  }, []);
+
+  return (
+    <>
+      <button ref={newBtnRef}>新建</button>
+      <div ref={settingsRef}>设置</div>
+
+      <Tour
+        open={open}
+        onOpenChange={setOpen}
+        onFinish={() => localStorage.setItem('tour:v1', '1')}
+        steps={[
+          {
+            target: newBtnRef,
+            title: '从这里新建',
+            description: '点击「新建」按钮即可创建新的项目',
+            placement: 'bottom',
+          },
+          {
+            target: settingsRef,
+            title: '个性化设置',
+            description: '在此处调整主题 / 通知偏好',
+            placement: 'left',
+          },
+          {
+            title: '完成!',
+            description: '开始使用吧 🎉',
+          },
+        ]}
+      />
+    </>
+  );
+}
+```