create-dwy 0.5.1 → 0.6.0

package/templates/claude-global/skills/dwy-eui/references/eui-design-guide.md

@@ -0,0 +1,257 @@
+# EUI 页面设计风格规范
+
+> AI 使用 @dwydev/eui 编写 UI 页面时必须遵循此规范。
+
+## 一、设计风格定位
+
+**shadcn 风格 + 中后台场景**：干净、克制、功能优先。不追求视觉冲击力，追求信息密度和操作效率。
+
+| 维度 | 规范 |
+|------|------|
+| 风格 | 扁平、无装饰、留白适度 |
+| 色彩 | 中性灰为主，主色点缀，不超过 3 种颜色 |
+| 圆角 | 统一 `rounded-md`（0.625rem），不混用不同圆角 |
+| 阴影 | 仅 `shadow-xs` / `shadow-sm`，不用 `shadow-lg` 及以上 |
+| 边框 | 1px `border-border`，不用粗边框 |
+| 图标 | 只用 `lucide-vue-next`，不用 emoji、不用其他图标库 |
+| 字体 | 系统字体栈（不引入额外字体），依赖 Tailwind 默认 |
+
+## 二、颜色系统
+
+### 语义色（直接使用，不写具体色值）
+
+| 用途 | Tailwind class | 说明 |
+|------|---------------|------|
+| 页面背景 | `bg-background` | 浅色/深色自动切换 |
+| 主文本 | `text-foreground` | 最高对比度 |
+| 次要文本 | `text-muted-foreground` | 描述、辅助信息 |
+| 主色按钮/强调 | `bg-primary text-primary-foreground` | 主操作 |
+| 次要按钮 | `bg-secondary text-secondary-foreground` | 次要操作 |
+| 卡片背景 | `bg-card text-card-foreground` | 卡片容器 |
+| 危险/错误 | `text-destructive` / `bg-destructive` | 删除、错误 |
+| 边框 | `border-border` | 统一边框色 |
+| 输入框边框 | `border-input` | 表单控件 |
+| 聚焦环 | `ring-ring` | focus 状态 |
+
+### 禁止
+
+- **禁止**写死色值（如 `bg-[#3B82F6]`），必须用语义 token
+- **禁止**用 `bg-blue-500` 等 Tailwind 原始色（除了 chart 场景）
+- **禁止**超过 3 种颜色混用
+
+### 主题色
+
+EUI 支持 7 种主题色，通过 `<html class="theme-blue">` 切换，代码中不需要关心具体色值：
+
+neutral（默认）| blue | green | rose | orange | violet | slate
+
+## 三、暗色模式
+
+- 所有页面必须同时支持亮色和暗色
+- 使用语义色 token 自动适配，不需要手写 `dark:` 前缀
+- 特殊场景需要区分时使用 `dark:` 变体
+- 背景层级：`bg-background` > `bg-card` > `bg-muted`
+- 暗色模式下避免纯白文字，用 `text-foreground` 自动适配
+
+## 四、布局规范
+
+### 页面结构
+
+```vue
+<!-- 标准中后台页面 -->
+<div class="flex flex-col gap-6 p-6">
+  <!-- 页头：标题 + 操作 -->
+  <div class="flex items-center justify-between">
+    <div>
+      <h1 class="text-2xl font-semibold">页面标题</h1>
+      <p class="text-sm text-muted-foreground">页面描述</p>
+    </div>
+    <div class="flex gap-2">
+      <EButton variant="outline">次要操作</EButton>
+      <EButton>主操作</EButton>
+    </div>
+  </div>
+
+  <!-- 内容区 -->
+  <div>...</div>
+</div>
+```
+
+### 间距规则
+
+| 场景 | 间距 | 说明 |
+|------|------|------|
+| 页面内边距 | `p-6` | 24px |
+| 区块间距 | `gap-6` | 24px |
+| 卡片内边距 | `p-4` 或 `p-6` | 16px 或 24px |
+| 表单项间距 | `space-y-4` | 16px |
+| 按钮间距 | `gap-2` | 8px |
+| 紧凑元素间距 | `gap-1` | 4px |
+
+### 按钮放置
+
+- 表单/弹窗的操作按钮**右对齐**：`flex justify-end gap-2`
+- 次要操作在前（左），主操作在后（右）
+- 危险操作用 `variant="destructive"`，放最右
+
+## 五、组件使用规范
+
+### 优先级
+
+使用 EUI 组件的优先级：**EUI 组件 > 组合组件 > 原生 HTML**
+
+| 需求 | 使用 | 不使用 |
+|------|------|--------|
+| 按钮 | `<EButton>` | `<button>` |
+| 输入框 | `<EInput>` | `<input>` |
+| 下拉选择 | `<ESelect>` | `<select>` |
+| 开关 | `<ESwitch>` | `<input type="checkbox">` |
+| 表格 | `<ETable>` | `<table>` |
+| 弹窗 | `<EDialog>` | 自定义 modal |
+| 轻提示 | `useMessage()` / `toast()` | `alert()` |
+| 表单 | `<EForm>` | `<form>` |
+| 确认框 | `<EConfirmDialog>` | `confirm()` |
+
+### 表单
+
+> **禁止使用原生 `<form>` 标签。** 所有表单必须使用 `<EForm>` 组件，EForm 内置 vee-validate 校验、provide/inject 上下文传递、统一的 label 布局和 reset/validate API，原生 `<form>` 无法与 EUI 表单体系集成。
+
+```vue
+<!-- 标准表单 -->
+<EForm ref="formRef" :model="model" :rules="rules" label-width="80px">
+  <EFormItem label="名称" prop="name">
+    <EInput v-model="model.name" placeholder="请输入" />
+  </EFormItem>
+  <EFormItem>
+    <div class="flex justify-end gap-2">
+      <EButton variant="outline" @click="handleReset">重置</EButton>
+      <EButton @click="handleSubmit">提交</EButton>
+    </div>
+  </EFormItem>
+</EForm>
+```
+
+### 表格页
+
+```vue
+<!-- 标准 CRUD 列表页 -->
+<div class="flex flex-col gap-6 p-6">
+  <!-- 筛选栏 -->
+  <EForm inline :model="filters">
+    <EFormItem label="关键词">
+      <EInput v-model="filters.keyword" placeholder="搜索..." />
+    </EFormItem>
+    <EFormItem>
+      <EButton @click="search">搜索</EButton>
+    </EFormItem>
+  </EForm>
+
+  <!-- 表格 -->
+  <ETable :data="list" :columns="columns" :loading="loading" />
+
+  <!-- 分页 -->
+  <EPagination
+    v-model="page"
+    :total="total"
+    v-model:pageSize="pageSize"
+    showSizeChanger
+    showTotal
+  />
+</div>
+```
+
+### 弹窗
+
+- 表单弹窗用 `<EFormDialog>` 或 `<EDialog>` + 表单
+- 确认操作用 `<EConfirmDialog>`
+- Dialog 内容超长时自动滚动（body 区域），header/footer 固定
+- `maxWidth` 控制宽度：表单弹窗 `500px`，详情弹窗 `600px`
+
+## 六、排版规范
+
+| 元素 | class | 场景 |
+|------|-------|------|
+| 页面标题 | `text-2xl font-semibold` | h1 |
+| 区块标题 | `text-lg font-semibold` | h2 |
+| 卡片标题 | `text-base font-medium` | h3 |
+| 正文 | `text-sm` | 默认文本 |
+| 辅助文字 | `text-sm text-muted-foreground` | 描述、提示 |
+| 小字 | `text-xs text-muted-foreground` | 时间戳、标签 |
+
+### 禁止
+
+- **禁止**超过 `text-3xl` 的字号（中后台不需要）
+- **禁止**用 `font-bold`（用 `font-semibold` 或 `font-medium`）
+- **禁止**正文用 `text-xs`（太小）
+
+## 七、交互规范
+
+### 状态反馈
+
+| 操作 | 反馈方式 |
+|------|---------|
+| 表单提交成功 | `toast.success('保存成功')` 或 `useMessage().success()` |
+| 表单提交失败 | 字段级错误提示（EForm 自动处理） |
+| 删除确认 | `<EConfirmDialog type="warning">` |
+| 异步加载 | `<ETable :loading="true">` 或 `<ESkeleton>` |
+| 空数据 | `<EEmpty>` |
+
+### 过渡动画
+
+- 弹窗/抽屉：EUI 组件内置，不需要额外处理
+- 列表切换：`<Transition>` + `duration-200`
+- 加载态：`<ESkeleton>` 占位，不用空白闪烁
+- **禁止**花哨动画（弹跳、旋转入场等）
+
+### 响应式
+
+| 断点 | 宽度 | 场景 |
+|------|------|------|
+| sm | 640px | 手机横屏 |
+| md | 768px | 平板 |
+| lg | 1024px | 小桌面 |
+| xl | 1280px | 标准桌面 |
+
+中后台页面最小支持 `md`（768px），不强求手机适配。
+
+## 八、ESelect 特殊约束
+
+- `option.value` **不能为空字符串**（reka-ui 不支持）
+- 需要"全部"选项时 value 用 `'all'`，不用 `''`
+
+## 九、卡片/面板规范
+
+```vue
+<!-- 标准卡片 -->
+<div class="rounded-lg border bg-card p-6">
+  <h3 class="text-base font-medium mb-4">卡片标题</h3>
+  <!-- 内容 -->
+</div>
+
+<!-- 统计卡片 -->
+<div class="rounded-lg border bg-card p-4">
+  <p class="text-sm text-muted-foreground">指标名称</p>
+  <p class="text-2xl font-semibold mt-1">1,234</p>
+</div>
+```
+
+- 卡片用 `rounded-lg border bg-card`，不加阴影
+- 卡片标题和内容间距 `mb-4`
+- 统计卡片用紧凑内边距 `p-4`
+
+## 十、代码自检清单
+
+AI 生成页面代码后，逐条验证：
+
+| # | 检查项 |
+|---|--------|
+| 1 | 颜色只用语义 token（bg-primary/text-foreground 等），不写死色值 |
+| 2 | 图标只用 lucide-vue-next，无 emoji |
+| 3 | 表单必须用 EForm，表单控件用 EUI 组件，禁止原生 `<form>` 和原生 HTML 控件 |
+| 4 | 按钮操作区右对齐，次要在前主要在后 |
+| 5 | 弹窗指定 maxWidth，不让内容无限撑开 |
+| 6 | 可交互元素有 hover 反馈和 cursor-pointer |
+| 7 | 文本层级清晰：标题 semibold、正文 sm、辅助 muted-foreground |
+| 8 | 暗色模式下所有元素可见可读 |
+| 9 | 空状态用 EEmpty，加载态用 loading prop 或 ESkeleton |
+| 10 | ESelect 选项 value 不为空字符串 |

package/templates/claude-global/skills/dwy-eui/references/eui-integration-guide.md

@@ -0,0 +1,302 @@
+# @dwydev/eui 集成指南
+
+在你的 Vue 3 项目中集成 @dwydev/eui 组件库。
+
+## 1. 安装依赖
+
+### 安装组件库
+
+```bash
+pnpm add @dwydev/eui
+```
+
+### 安装 Peer Dependencies
+
+```bash
+pnpm add -D tailwindcss @tailwindcss/vite tw-animate-css
+```
+
+| 包名 | 版本要求 | 说明 |
+|------|---------|------|
+| `tailwindcss` | `^4.0.0` | CSS 框架 |
+| `@tailwindcss/vite` | `^4.0.0` | Vite 插件 |
+| `tw-animate-css` | `^1.0.0` | 动画工具类 |
+
+### 已知问题：vue-sonner 需手动安装
+
+`vue-sonner` 已声明在 EUI 的 `dependencies` 中，但 pnpm 的严格依赖提升策略可能导致它无法被项目正确解析。如果使用 Toast 组件时遇到模块找不到的错误，需手动安装：
+
+```bash
+pnpm add vue-sonner
+```
+
+## 2. 配置 Vite
+
+```ts
+// vite.config.ts
+import tailwindcss from '@tailwindcss/vite'
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [vue(), tailwindcss()],
+})
+```
+
+## 3. 引入样式
+
+```css
+/* src/style.css */
+@import "@dwydev/eui/theme";
+```
+
+> 主题 CSS 已内置 `@source` 指令，Tailwind 会自动扫描组件使用的工具类，无需手动配置。
+
+### 可选：按需引入主题
+
+```css
+/* 完整主题（推荐） */
+@import "@dwydev/eui/theme";
+
+/* 或分别引入 */
+@import "@dwydev/eui/theme/tokens";  /* 基础变量 + Tailwind */
+@import "@dwydev/eui/theme/dark";    /* 暗色模式 */
+```
+
+## 4. 注册组件
+
+### 全局注册（推荐）
+
+```ts
+// main.ts
+import './style.css'
+import { createApp } from 'vue'
+import EUI from '@dwydev/eui'
+import App from './App.vue'
+
+const app = createApp(App)
+app.use(EUI)
+app.mount('#app')
+```
+
+注册后所有组件全局可用，无需逐个导入。
+
+### 按需导入
+
+```ts
+// 在组件中按需导入
+import { EButton, EInput, ETable } from '@dwydev/eui'
+```
+
+适合对打包体积敏感的场景，支持 Tree-shaking。
+
+## 5. 全局配置 EConfigProvider（必须）
+
+**EConfigProvider 是使用 EUI 的前置条件。** 必须在 App 根组件用 `<EConfigProvider>` 包裹整个应用，否则以下功能不生效：
+
+- **国际化** — 日期选择器、日历等组件将显示英文而非中文
+- **全局尺寸** — 无法统一控制所有组件的尺寸
+- **弹层层级** — Dialog/Drawer/Popover 等弹层 z-index 无法统一管理
+- **UI 文案** — 确定/取消/暂无数据等通用文案无法全局配置
+
+### 基础用法
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { EConfigProvider } from '@dwydev/eui'
+</script>
+
+<template>
+  <EConfigProvider>
+    <RouterView />
+  </EConfigProvider>
+</template>
+```
+
+使用默认配置即可满足中文项目需求，无需传任何 props。
+
+### Props
+
+| Prop | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| size | `'sm' \| 'default' \| 'lg'` | `'default'` | 所有组件的全局尺寸 |
+| zIndex | `number` | `2000` | 弹层组件的基准 z-index |
+| locale | `Record<string, string>` | 见下方 | 国际化配置 |
+
+### locale 配置
+
+locale 是一个扁平的键值对象，`name` 字段为 BCP 47 语言标签，控制日期类组件的本地化显示；其余字段为 UI 通用文案。
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| name | `'zh-CN'` | BCP 47 语言标签，控制 EDatePicker、ECalendar 等组件的月份名、星期名、年份格式 |
+| confirm | `'确定'` | 确认按钮文案 |
+| cancel | `'取消'` | 取消按钮文案 |
+| close | `'关闭'` | 关闭按钮文案 |
+| loading | `'加载中...'` | 加载状态文案 |
+| empty | `'暂无数据'` | 空状态文案 |
+| search | `'搜索'` | 搜索占位文案 |
+| selectPlaceholder | `'请选择'` | 选择器默认占位文案 |
+| inputPlaceholder | `'请输入'` | 输入框默认占位文案 |
+
+### 自定义配置示例
+
+```vue
+<EConfigProvider
+  size="sm"
+  :z-index="3000"
+  :locale="{
+    name: 'en-US',
+    confirm: 'OK',
+    cancel: 'Cancel',
+    close: 'Close',
+    loading: 'Loading...',
+    empty: 'No data',
+    search: 'Search',
+    selectPlaceholder: 'Please select',
+    inputPlaceholder: 'Please input',
+  }"
+>
+  <RouterView />
+</EConfigProvider>
+```
+
+### 嵌套覆盖
+
+EConfigProvider 支持嵌套，内层配置覆盖外层，适用于局部区域需要不同配置的场景：
+
+```vue
+<EConfigProvider>                                          <!-- 全局中文 -->
+  <EConfigProvider :locale="{ name: 'en-US', ... }">      <!-- 局部英文 -->
+    <EDatePicker type="month" />                           <!-- 显示英文月份 -->
+  </EConfigProvider>
+</EConfigProvider>
+```
+
+## 6. 主题配置（可选）
+
+### 暗色模式 + 主题切换
+
+```vue
+<script setup lang="ts">
+import { useTheme } from '@dwydev/eui'
+
+const { isDark, toggleDark, colorTheme, setColorTheme } = useTheme()
+</script>
+
+<template>
+  <EButton @click="toggleDark">
+    {{ isDark ? '切换亮色' : '切换暗色' }}
+  </EButton>
+
+  <EButton @click="setColorTheme('blue')">
+    蓝色主题
+  </EButton>
+</template>
+```
+
+### 内置 7 种颜色主题
+
+| 主题名 | 说明 |
+|--------|------|
+| `neutral` | 默认主题 |
+| `blue` | 蓝色 |
+| `green` | 绿色 |
+| `rose` | 玫红 |
+| `orange` | 橙色 |
+| `violet` | 紫色 |
+| `slate` | 石板灰 |
+
+## 7. Composables
+
+### useToast
+
+轻量 toast 通知。需要在根组件挂载 `<EToast />` 容器：
+
+```vue
+<!-- App.vue -->
+<template>
+  <router-view />
+  <EToast rich-colors />
+</template>
+```
+
+使用：
+
+```ts
+import { useToast } from '@dwydev/eui'
+
+const toast = useToast()
+
+toast.success('操作成功')
+toast.error('操作失败')
+toast.warning('警告信息')
+toast.info('提示信息')
+
+// 带描述
+toast.success('保存成功', { description: '数据已持久化' })
+
+// 自定义时长（毫秒）
+toast.info('处理中...', { duration: 5000 })
+```
+
+### useMessage
+
+```ts
+import { useMessage } from '@dwydev/eui'
+
+const message = useMessage()
+
+message.success('操作成功')
+message.error('操作失败')
+message.warning('警告信息')
+message.info('提示信息')
+```
+
+### useNotification
+
+```ts
+import { useNotification } from '@dwydev/eui'
+
+const notification = useNotification()
+
+notification.success({
+  title: '操作成功',
+  message: '数据已保存',
+})
+```
+
+## 完整示例
+
+### 最小项目结构
+
+```
+my-app/
+├── src/
+│   ├── style.css          # @import "@dwydev/eui/theme"
+│   ├── main.ts            # app.use(EUI)
+│   └── App.vue
+├── index.html
+├── vite.config.ts         # tailwindcss 插件
+├── tsconfig.json
+└── package.json
+```
+
+### package.json 依赖
+
+```json
+{
+  "dependencies": {
+    "@dwydev/eui": "^1.2.0",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@vitejs/plugin-vue": "^6.0.0",
+    "tailwindcss": "^4.0.0",
+    "tw-animate-css": "^1.0.0",
+    "vite": "^8.0.0"
+  }
+}
+```