@reglow/reui-mcp 0.3.9 → 0.3.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json
CHANGED
|
@@ -17,15 +17,16 @@ description: ReUI（@reglow/reui）Vue 3 组件库的检索、选型、用法示
|
|
|
17
17
|
|
|
18
18
|
## 2. 触发场景
|
|
19
19
|
|
|
20
|
-
| 用户意图
|
|
21
|
-
|
|
|
22
|
-
| 「有没有 XX 组件 / 该用哪个组件」
|
|
23
|
-
| 「XX 组件怎么用 / 有哪些 props」
|
|
24
|
-
| 「给我一段可复制的示例代码」
|
|
25
|
-
| 「这个组件内部怎么实现的」
|
|
26
|
-
| 「哪里用到了 XX / 关键词排查」
|
|
27
|
-
| 安装、主题、i18n、Nuxt 接入、构建、项目约定
|
|
28
|
-
| 业务代码里引入组件、切主题、切语言
|
|
20
|
+
| 用户意图 | 走哪里 |
|
|
21
|
+
| ---------------------------------------------- | ---------------------------------------------------------------------- |
|
|
22
|
+
| 「有没有 XX 组件 / 该用哪个组件」 | `get_reui_document`（不传 `component` 得总览）、本目录 `COMPONENTS.md` |
|
|
23
|
+
| 「XX 组件怎么用 / 有哪些 props」 | `get_reui_document` + `get_reui_code_examples` |
|
|
24
|
+
| 「给我一段可复制的示例代码」 | `get_reui_code_examples` |
|
|
25
|
+
| 「这个组件内部怎么实现的」 | `list_component_files` → `get_file_code` → `get_function_code` |
|
|
26
|
+
| 「哪里用到了 XX / 关键词排查」 | `search_reui_docs` |
|
|
27
|
+
| 安装、主题、i18n、Nuxt 接入、构建、项目约定 | `get_reui_guide` |
|
|
28
|
+
| 业务代码里引入组件、切主题、切语言 | 本目录 `BEST_PRACTICES.md` |
|
|
29
|
+
| 页面布局、配色、间距、层级、暗色模式等 UI 规范 | 本目录 `UI_DESIGN_RULES.md` |
|
|
29
30
|
|
|
30
31
|
## 3. 核心工作流（配合 reui-mcp）
|
|
31
32
|
|
|
@@ -137,11 +138,12 @@ export default defineNuxtConfig({
|
|
|
137
138
|
|
|
138
139
|
## 5. 文件导航（同目录）
|
|
139
140
|
|
|
140
|
-
| 文件
|
|
141
|
-
|
|
|
142
|
-
| `WORKFLOWS.md`
|
|
143
|
-
| `BEST_PRACTICES.md`
|
|
144
|
-
| `
|
|
141
|
+
| 文件 | 内容 | 何时读 |
|
|
142
|
+
| -------------------- | ------------------------------------------------------------------------------------------- | -------------------------- |
|
|
143
|
+
| `WORKFLOWS.md` | reui-mcp 工具概览 + 四步查询流程 + 5 个完整任务示例（含参数与判断标准） | 需要查文档/示例代码前 |
|
|
144
|
+
| `BEST_PRACTICES.md` | 安装、样式、Tailwind `@source`、主题、i18n、Nuxt 的实践与陷阱 | 写业务代码前后对照 |
|
|
145
|
+
| `UI_DESIGN_RULES.md` | 色彩/圆角/间距/字号 token、z-index 层级、列表页/表单页/指标卡骨架、交互与可访问性、常见陷阱 | 设计页面结构、定样式规范时 |
|
|
146
|
+
| `COMPONENTS.md` | 按分类的组件选型清单（说明 + 导入名 + 文档链接） | 组件选型、确认组件是否存在 |
|
|
145
147
|
|
|
146
148
|
## 6. 在 Trae / CodeBuddy / Qoder 中启用（MCP + Skills）
|
|
147
149
|
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# ReUI UI 设计规则与页面实践（UI_DESIGN_RULES）
|
|
2
|
+
|
|
3
|
+
> 面向「用 ReUI 搭建后台页面」的设计与实现。把 `reglow-design` 基座在长期业务中沉淀的 UI 规则整理成可执行清单，每条标注来源文件。
|
|
4
|
+
> 核心来源：`reglow-design/src/assets/css/main.css`、`reglow-design/README.md`、`reglow-design/src/lib/theme.ts`、`reglow-design/src/components/common/StatCard.vue`、`reglow-design/src/components/common/ListPageSkeleton.vue`、`reglow-design/src/components/common/FormSkeleton.vue`、`reglow-design/src/components/ui/input`。
|
|
5
|
+
|
|
6
|
+
## 0. 使用顺序（先规则、后组件）
|
|
7
|
+
|
|
8
|
+
1. 先按本文确定**页面骨架与主题变量**（布局 / 间距 / 色彩 / 层级）。
|
|
9
|
+
2. 再用 `COMPONENTS.md` 选组件、`get_reui_document` + `get_reui_code_examples` 取真实 API。
|
|
10
|
+
3. 落地时对照 `BEST_PRACTICES.md` 检查引入方式与陷阱。
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 1. 色彩与主题（Design Tokens）
|
|
15
|
+
|
|
16
|
+
- **只用语义 token，不写死颜色**：`bg-background` / `text-foreground` / `bg-card` / `text-muted-foreground` / `bg-muted` / `border-border` / `text-primary` / `bg-primary` / `text-destructive` / `ring-ring`。来源：`main.css` 的 `@theme inline`（`--color-*` 映射到 CSS 变量）。
|
|
17
|
+
- **颜色值用 oklch**：主题由 `applyTheme()` 注入 CSS 变量覆盖 `:root` 默认值（默认 Zinc 基础 + Blue 主色）。来源：`main.css` 默认主题块、`theme.ts` `PRIMARY_PALETTE`。
|
|
18
|
+
- **暗色只走 `.dark` 类**：`main.css` 用 `@custom-variant dark (&:where(.dark, .dark *))`，与应用主题开关（`applyTheme`）保持一致，禁止依赖系统 `prefers-color-scheme` 直接切色。来源：`main.css`。
|
|
19
|
+
- **主题配置字段**（`ThemeConfig`）：`mode`(light/dark/auto)、`baseColor`(7 种)、`primaryColor`(18 种)、`radius`("0"|"0.3"|"0.5"|"0.75"|"1.0")、`style`(7 种)、`skin`(7 套)、`headingFont`/`bodyFont`(9 种)、`showTabBar`/`showBreadcrumb`。来源：`theme.ts`。
|
|
20
|
+
- **首选 `ConfigProvider` 或 `applyTheme`**，不要手改 `:root` 变量。来源：`BEST_PRACTICES.md` §5。
|
|
21
|
+
|
|
22
|
+
## 2. 圆角、间距与字号
|
|
23
|
+
|
|
24
|
+
- **圆角用语义档位**：`rounded-sm` / `rounded-md` / `rounded-lg` / `rounded-xl`（由 `--radius` 推导：`calc(var(--radius) ± npx)`）。来源：`main.css` `--radius-*`。
|
|
25
|
+
- **卡片/容器统一 `rounded-lg border border-border bg-card shadow`**；卡片内边距 `p-5`。来源：`StatCard.vue`。
|
|
26
|
+
- **间距节奏**：区块间 `gap-3`/`gap-4`，表单行内 `gap-2`，页面垂直 `space-y-4` 级别的 4/8 网格。来源：`StatCard.vue`、`ListPageSkeleton.vue`。
|
|
27
|
+
- **字号层级**：页面标题 `text-lg`/`text-xl`；指标值 `text-2xl font-semibold leading-tight tracking-tight tabular-nums`；正文/标签 `text-sm`；辅助说明 `text-xs text-muted-foreground`。来源：`StatCard.vue`、`ListPageSkeleton.vue`。
|
|
28
|
+
- **数字对齐**：所有数值/金额/统计使用 `tabular-nums`，避免跳宽。来源：`StatCard.vue`。
|
|
29
|
+
- **禁止魔法色值**（如 `#fff`、`rgb(...)`）与任意 `z-[9999]`，统一走 token 与层级变量。
|
|
30
|
+
|
|
31
|
+
## 3. 层级（z-index）规范
|
|
32
|
+
|
|
33
|
+
统一由 CSS 变量管理，**不要自定义 z-index 数字**。来源：`main.css` 全局层级体系。
|
|
34
|
+
|
|
35
|
+
| 变量 | 值 | 用途 |
|
|
36
|
+
| --- | --- | --- |
|
|
37
|
+
| `--z-overlay-base` | 1000 | Dialog / Drawer 遮罩起点（每开一个 +10） |
|
|
38
|
+
| `--z-flyout` | 1200 | Portal 浮层：Select / Popover / Dropdown |
|
|
39
|
+
| `--z-tooltip` | 1400 | Tooltip |
|
|
40
|
+
| `--z-toast` | 10000 | Toast |
|
|
41
|
+
|
|
42
|
+
规则：浮层始终高于任何已打开 Modal；新增浮层优先复用组件库 Portal 实现，不要手写挂 body 的绝对定位层。
|
|
43
|
+
|
|
44
|
+
## 4. 页面骨架
|
|
45
|
+
|
|
46
|
+
### 4.1 列表页（List Page）
|
|
47
|
+
|
|
48
|
+
标准结构：**标题栏 → 搜索/操作栏 → 表格卡片（分页）**。来源：`ListPageSkeleton.vue`。
|
|
49
|
+
|
|
50
|
+
- 标题栏：标题 + 竖线分隔 + 计数/描述，`flex items-center gap-3`。
|
|
51
|
+
- 搜索栏：搜索框（`h-9`）+ 主操作按钮 + `flex-1` 占位 + 右侧圆形图标按钮（`size-9 rounded-full`）。
|
|
52
|
+
- 表格：`Card > CardContent(class="p-0") > Table`，表格区 `overflow-hidden flex-auto min-h-0`。
|
|
53
|
+
- 加载态用 `ListPageSkeleton`，不要空白闪烁。
|
|
54
|
+
- 表格用 `PageTable`（服务端分页/排序），列的 `accessorKey` 必须与后端字段名（snake_case）一致；单列排序默认，需要多列时加 `multi-sort`（Shift 点击，最多 3 列）。来源：`reglow-design/README.md`。
|
|
55
|
+
- 行操作按钮右对齐、次级样式；危险操作走 `text-destructive` 并要求二次确认（AlertDialog）。
|
|
56
|
+
|
|
57
|
+
### 4.2 表单页 / 弹窗（Form）
|
|
58
|
+
|
|
59
|
+
- 加载态用 `FormSkeleton`（骨架占位），字段分组用 `Card`/`Separator` 分隔。
|
|
60
|
+
- 表单控件尺寸统一（`Input`/`Select`/`Button` 高度一致：small 32 / medium 36 / large 44 px）。
|
|
61
|
+
- 全站输入框默认开启一键清除（`components/ui/input` 包装，`:allow-clear="false"` 关闭）。来源：`reglow-design/README.md`。
|
|
62
|
+
- 校验错误文案放在字段下方 `text-xs text-destructive`，按钮区右对齐（取消在左、主操作在右）。
|
|
63
|
+
|
|
64
|
+
### 4.3 指标卡（StatCard）
|
|
65
|
+
|
|
66
|
+
复用 `StatCard` 结构：卡片 `rounded-lg border bg-card p-5 shadow`，左列 `label(text-sm muted)` + `value(text-2xl font-semibold tabular-nums)` + `hint(text-xs muted)`，右侧 `size-9 rounded-xl bg-muted` 图标容器，hover 时 `bg-primary/10 text-primary`。来源：`StatCard.vue`。
|
|
67
|
+
|
|
68
|
+
## 5. 样式接入（Tailwind 消费方必读）
|
|
69
|
+
|
|
70
|
+
- 应用入口引一次样式：完整 `import "@reglow/reui/style.css"`；宿主已有 Tailwind/主题变量时用 `import "@reglow/reui/components.css"` 避免 reset 冲突。来源：`BEST_PRACTICES.md` §2。
|
|
71
|
+
- **消费方自己跑 Tailwind 时，必须 `@source` 扫描库产物**，否则响应式类丢失（如 PageTable 搜索栏/分页栏恒为 `flex-direction: column`）：
|
|
72
|
+
|
|
73
|
+
```css
|
|
74
|
+
@import "tailwindcss";
|
|
75
|
+
@import "@reglow/reui/components.css";
|
|
76
|
+
@source "../../../node_modules/@reglow/reui/dist/components";
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
来源：`reglow-design/src/assets/css/main.css`、`README.md`「样式接入」。
|
|
80
|
+
- 样式只引一次；不要在每个组件里重复 import。
|
|
81
|
+
|
|
82
|
+
## 6. 交互与可访问性
|
|
83
|
+
|
|
84
|
+
- **状态齐全**：每个数据区块提供 加载(skeleton) / 空态 / 错误(ErrorBoundary) 三态。
|
|
85
|
+
- **焦点可见**：交互元素依赖 `ring-ring` 焦点环，不要 `outline-none` 而不补 ring。
|
|
86
|
+
- **键盘可达**：浮层/菜单/表格排序优先用组件库内置可访问实现，不自己造轮子。
|
|
87
|
+
- **危险操作**：删除/不可逆操作使用 `AlertDialog` 二次确认，按钮用 `destructive` 语义色。
|
|
88
|
+
- **长列表**：大表格/长列表启用虚拟滚动（`VirtualScrollbar` / 表格虚拟化），避免一次渲染上千行。
|
|
89
|
+
|
|
90
|
+
## 7. 常见陷阱速查
|
|
91
|
+
|
|
92
|
+
| 陷阱 | 正确做法 | 来源 |
|
|
93
|
+
| --- | --- | --- |
|
|
94
|
+
| 引了 `style.css` 就不加 `@source` | 消费方跑 Tailwind 时必须 `@source` 库产物 | `README.md` |
|
|
95
|
+
| 手写颜色 / z-index | 用语义 token 与 `--z-*` 变量 | `main.css` |
|
|
96
|
+
| 依赖系统深色模式 | 用 `.dark` 类与 `applyTheme` | `main.css` |
|
|
97
|
+
| 表格列名与后端不一致 | `accessorKey` 用后端 snake_case 字段名 | `README.md` |
|
|
98
|
+
| 列表页无加载骨架 | 用 `ListPageSkeleton` / `FormSkeleton` | 组件文件 |
|
|
99
|
+
| 数字宽度跳动 | 统计值加 `tabular-nums` | `StatCard.vue` |
|
|
100
|
+
| 多个 Modal 叠层错乱 | 复用 `--z-overlay-base` 递增与 `--z-flyout` | `main.css` |
|
|
101
|
+
|
|
102
|
+
---
|
|
103
|
+
|
|
104
|
+
> 本文只收录在 `reglow-design` 仓库中可核实的做法；未核实的「经验」不写入。组件 API 仍以 `get_reui_document` / 源码为准。
|
package/skills.mjs
CHANGED