@qilitt-mickey/vue3-temp-skill 1.1.6 → 1.1.7

package/SKILL.md

@@ -126,7 +126,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
    - 「导出 Excel / 下载文件」→ `download-export`  
    - 「菜单加图标 / 换图标 / 图标选择器 / 本地 SVG 图标」→ `icons`  
    - 「粒子背景 / 登录粒子 / 粒子特效」→ `particles`  
-   - 「按 Ant Design / Semi / Arco / Vuetify / 京东 等设计规范适配」「套 UI 规范」「让项目符合 XX 规范」→ `design-system`（+ `layout-theme`）：必须完整执行其 8 步适配工作流（识别回执 + 令牌层 + 组件几何重写层 + 模版硬编码冲突逐条回填 + 存量裸值扫描）；适配层文件名锁定 `design-tokens.scss` / `design-controls.scss`；禁止只改 `--el-color-primary` 就宣称已适配，禁止识别漂移  
+   - 「按 Ant Design / Semi / Arco / Vuetify / 京东 等设计规范适配」「套 UI 规范」「让项目符合 XX 规范」→ `design-system`（+ `layout-theme`）：必须完整执行其适配工作流（识别回执 + 令牌层（唯一新增文件）+ 几何重写并入 element-plus.scss + 硬编码冲突逐条回填 + 公共区域适配 + 存量裸值扫描）；适配新增文件只允许 `design-tokens.scss`；组件层永远是 Element Plus，适配只换令牌数据不换组件；禁止只改 `--el-color-primary` 就宣称已适配，禁止识别漂移
    - 只说「自定义指令」未说明效果 → 先追问，禁止默认塞模块  
 6. **HTTP**：方法跟后端文档，**允许 GET/POST**；POST→`data`，GET→`params`；真实 URL 用 `VITE_API_BASE_URL`；`/mock` 仅本地 Fake Server；无单请求 `crypto: true`。
 
@@ -289,7 +289,7 @@ reset();    // 重置（配合 formRef.resetFields）
 **4. 安全** — 无危险 v-html；无硬编码密钥  
 **5. 业务** — `onSearch`/`reset`；提交 loading；权限；未二次 Layout  
 **5b. 列表布局** — `el-card`+`content`+固定 height；查询/展示分区；`tableHeight`；分页在 ReTableBar 内  
-**5c. 设计规范遵从（命中 design-system 时必查）** — 已输出识别回执且三点一致；令牌层/几何重写层已建立且 `@use` 顺序正确、文件名未漂移；第四节硬编码冲突清单逐条处理并回填；存量裸值扫描已执行；业务代码无裸控件高度/内边距/字号；验证清单全过  
+**5c. 设计规范遵从（命中 design-system 时必查）** — 已输出识别回执且三点一致；令牌层（唯一新增）已建立、几何重写并入 element-plus.scss、文件名未漂移；第四节硬编码冲突清单逐条处理并回填；公共区域（侧栏/导航/壳变量）已适配；存量裸值扫描已执行；业务代码无裸控件高度/内边距/字号；验证清单全过  
 **6. 风格** — 无多余 console；`$t('中文')`；`--vts-*` / UnoCSS；图标走 `svg-icon` / `icons` 约定  
 
 完整项见 `references/code-quality.md`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qilitt-mickey/vue3-temp-skill",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块",
   "bin": {
     "vue3-temp-skill": "./bin/cli.js"

package/references/code-quality.md

@@ -241,11 +241,12 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 ### 设计规范遵从（命中 design-system 时必查，细则见 `design-system.md`）
 
 - [ ] 已输出「规范识别回执」，且规范 ID / 主色在令牌层、`platform-config.json`、侧栏主题三处一致（防识别漂移）。
-- [ ] 已建立令牌层 `design-tokens.scss`（含用户可自定义区块 + 模版桥接令牌 + `--el-*` 映射）与几何重写层 `design-controls.scss`；文件名不得漂移成 `tokens.scss` / `semi-controls.scss` 等变体。
-- [ ] `index.scss` 中 `@use` 顺序：`design-tokens` 最前，`design-controls` 在 `element-plus` 之后。
+- [ ] 已建立令牌层 `design-tokens.scss`（**唯一新增文件**，纯 `:root` 数据无选择器；含用户可自定义区块 + 模版桥接令牌 + `--el-*` 映射）；组件几何重写已并入 `element-plus.scss`（令牌引用 + 规范注释）；文件名不得漂移成 `tokens.scss` 等变体，无独立重写层文件残留。
+- [ ] `index.scss` 中 `design-tokens` 位于 `@use` 最前；模版其余顺序未动。
 - [ ] `design-system.md` 第四节「模版硬编码冲突清单」逐条处理并在回复中逐条回填（重点：通配符 font-family、reset.scss body 字体与 `label { font-weight: 700 }`、`.el-card__body` padding 5px、弹窗渐变蓝底、表头硬编码色）。
 - [ ] 主色三态（hover/active）、字体、控件高度、圆角、卡片内边距、表单标签字重、表头视觉均符合目标规范（按第二节验证清单核验）。
-- [ ] 业务代码无裸控件高度/内边距/字号/圆角；组件几何覆盖只集中在 `design-controls.scss`；存量裸值扫描已执行。
+- [ ] 业务代码无裸控件高度/内边距/字号/圆角；组件几何覆盖只集中在 `element-plus.scss`；存量裸值扫描已执行。
+- [ ] 公共区域已按规范落地：`theme.scss` 侧栏配色（激活条 = 规范主色）、`index.scss` 壳变量（导航高/内容边距/弹窗底）、`HeaderHeight` 一致。
 - [ ] `platform-config.json` 的 `EpThemeColor` 与规范主色一致，已提醒清理 localStorage 缓存；新增令牌已在 `dark.scss` 补暗色覆盖。
 
 ## 七、业务逻辑检查

package/references/design-system.md

@@ -1,14 +1,29 @@
 ---
 skill: design-system
-description: 设计规范识别与全量落地机制。当用户指定设计系统（内置预设：Ant Design / Semi Design / Arco Design / Vuetify / FindDesign 京东UDC；非封闭集，支持任意自定义规范）或要求"按 XX 规范 / 设计规范 / UI 规范适配项目"时，强制执行为「识别回执 + 令牌层 + 组件几何重写层 + 模版硬编码冲突处理 + 存量回归扫描」的完整适配流程，并在 code-quality 闸门中校验规范遵从。按通用协议自动识别并衔接任意上游 UI/UX 设计技能的令牌产出（不绑定具体技能名）。
+description: 设计规范识别与全量落地机制。当用户指定设计系统（内置预设：Ant Design / Semi Design / Arco Design / Vuetify / FindDesign 京东UDC；非封闭集，支持任意自定义规范）或要求"按 XX 规范 / 设计规范 / UI 规范适配项目"时，强制执行为「识别回执 + 令牌层（唯一新增文件）+ 几何重写并入 element-plus.scss + 模版硬编码冲突处理 + 公共区域适配 + 存量回归扫描」的完整适配流程，并在 code-quality 闸门中校验规范遵从。按通用协议自动识别并衔接任意上游 UI/UX 设计技能的令牌产出（不绑定具体技能名）。
 scope: project
 tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, element-plus, theme, css-variables]
 ---
 
 # 设计规范识别与全量适配机制
 
-> **本模块的职责**：识别规范后，在**业务项目**内一次性建立「令牌层 + 组件几何重写层 + 硬编码冲突清理」三层适配，之后所有生成代码只准引用令牌，禁止裸值。
+> **本模块的职责**：识别规范后，在**业务项目**内一次性完成「令牌层（数据）+ 模版样式文件改写（执行）+ 硬编码冲突清理」的适配，之后所有生成代码只准引用令牌，禁止裸值。
 >
+> **核心理念（始终明确）**：组件层永远是 **Element Plus**——代码照旧写 `<el-button>` / `<el-table>` / `<el-dialog>`，规范适配**不换组件**，只替换驱动组件样式的**“数据”**（令牌：高度/内边距/字号/圆角/颜色）。所有样式文件只是“按令牌数据执行”，换规范 = 换一套数据。
+>
+> **架构决策（单文件）**：适配只**新增一个文件** `design-tokens.scss`（纯数据层，无选择器）；组件几何与视觉重写**直接并入模版既有的 `element-plus.scss` 等文件**（引用令牌 + 标注规范注释）。禁止另建并存的“重写层”文件——两个文件同时改 EP 组件样式会让后续开发者不知道改哪里、靠加载顺序压盖易失效。
+
+### 职责分工（适配文件 vs 模版既有文件）
+
+| 文件 | 职责 | 内容形态 |
+|------|------|---------|
+| `design-tokens.scss`（**唯一新增**） | 规范**数据源**：主色/字体/字号/圆角/控件高度/间距 + 模版桥接令牌 + `--el-*` 映射 | 纯 `:root` 变量，**禁止选择器与组件类** |
+| `element-plus.scss`（模版既有） | EP 组件几何与视觉覆盖的**唯一出口**：模版默认 + 规范重写都在这里，全部引用令牌 | 选择器 + `var()`，每段标注规范注释 |
+| `reset.scss` / `index.scss`（模版既有） | 基础样式与全局壳变量（导航高/内容边距/弹窗底） | 引用令牌 |
+| `theme.scss` / `sidebar.scss`（模版既有） | 侧边栏/导航配色与几何 | 按规范换色，引用令牌 |
+
+> 关系一句话：`design-tokens.scss` 是数据层，模版样式文件是执行层；不存在第三个“重写层”文件。
+
 ---
 
 ## 一、触发与规范识别
@@ -67,9 +82,10 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 ### Step 1 探查现状（含命名锁定与模版版本判定）
 
 1. 读业务项目 `src/styles/index.scss` 的 `@use` 列表与 `src/styles/` 目录。
-2. **命名锁定**：规范适配层**只允许**叫 `design-tokens.scss` 与 `design-controls.scss`。
-   - 已存在这两个文件 → 更新令牌值与遗漏重写，不重复建层。
-   - 发现旧命名变体（`tokens.scss`、`semi-controls.scss`、`antd-controls.scss` 等）→ **必须先重命名/合并为规范名**再继续；禁止让变体与规范名并存。
+2. **命名锁定（单文件架构）**：适配**新增文件只允许**叫 `design-tokens.scss`（纯数据层）。
+   - 已存在 → 只更新令牌值，不重复建层。
+   - 发现旧命名变体（`tokens.scss` 等）→ 必须先重命名为规范名。
+   - 发现旧版并存的几何重写层文件（`design-controls.scss` / `semi-controls.scss` / `*-controls.scss`）→ **必须把其内容合并进 `element-plus.scss`（改为令牌引用 + 规范注释）后删除原文件**；禁止重写层与 `element-plus.scss` 并存。
 3. **模版版本判定**（决定 Step 5 走哪条清单）：
    ```
    grep 目标：src/styles/element-plus.scss
@@ -181,14 +197,22 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 ```
 
 > 上面是 **Ant Design 预设**。其他规范按第五节令牌速查表替换「用户可自定义」区块与语义色。
+>
+> ⚠️ `design-tokens.scss` **只允许 `:root` 变量块**：业务组件类（如 `.vts-status`、`.vts-op`）不得写入本文件，应放 `element-plus.scss` 或业务组件内。
 
-### Step 3 写入组件几何重写层 `src/styles/design-controls.scss`
+### Step 3 组件几何重写并入 `src/styles/element-plus.scss`（不另建重写层文件）
 
-只重写几何规格（高度 / 内边距 / 字号 / 圆角），全部引用令牌，**禁止再写裸值**。完整黄金样板（覆盖 EP 常用控件全集，按需删减但禁止新增裸值）：
+几何规格（高度 / 内边距 / 字号 / 圆角）**直接追加/修改在模版既有的 `element-plus.scss` 内**，三条纪律：
+
+1. 全部引用令牌，**禁止裸值**（`var(--x, 回退)` 的回退值除外）。
+2. 每段追加规范注释：`/* —— <规范名> 几何：<组件> —— */`，让后续开发者一眼看出取值来源。
+3. 模版里同一选择器已有裸值规则（如 `.el-card__body { padding: 5px }`）→ **就地改为令牌引用**，禁止另起一条规则去压盖，避免“同属性两处定义”。
+
+黄金样板（按需追加/修改，只改数据值，结构不变）：
 
 ```scss
 /**
- * <规范名> → Element Plus 几何规格重写
+ * <规范名> → Element Plus 几何规格（追加在 element-plus.scss 内）
  * 全部引用 design-tokens.scss 令牌；业务页禁止再写裸高度/内边距。
  */
 
@@ -303,22 +327,23 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 .el-breadcrumb { font-size: var(--font-size-base); line-height: var(--line-height); }
 ```
 
-> 各规范差异项：`antd` 表头 `#fafafa` 不加边框分隔；`semi` 少阴影轻描边；`vuetify` 控件高度 Material 化（input 40px、button 36px）；按第五节表微调样板中的数值来源即可，**结构不变**。
+> 各规范差异项：`antd` 表头 `#fafafa` 不加边框分隔；`semi` 少阴影轻描边；`vuetify` 控件高度 Material 化（input 40px、button 36px）；按第五节表微调样板中的数值来源即可，**结构不变**。差异值同样只改令牌数据，不另写选择器。
 
-### Step 4 接线 `src/styles/index.scss`（顺序即优先级）
+### Step 4 接线 `src/styles/index.scss`
 
 ```scss
-@use 'design-tokens';     // ① 令牌必须最先，供后续文件引用
+@use 'design-tokens';     // 唯一新增：纯数据令牌，必须最先
 @use 'theme';
 @use 'transition';
 @use 'button';
-@use 'element-plus';      // ② 模版原生覆盖
-@use 'design-controls';   // ③ 规范重写必须在其后，同选择器后者优先
+@use 'element-plus';      // 模版默认覆盖 + 规范几何重写（已并入）
 @use 'sidebar';
 @use 'dark';
 @use 'vant';
 ```
 
+唯一顺序要求：`design-tokens` 放最前（供后续文件引用）。几何重写已并入 `element-plus.scss`，**不再存在**“重写层必须排在覆盖层之后”的顺序陷阱；模版其余 `@use` 顺序保持不动。
+
 **字体接管**：
 - 新模版：`index.scss` 已是 `font-family: var(--font-family, ...) !important`，令牌层定义 `--font-family` 即自动生效，无需改动。
 - 旧模版：把 `* { font-family: 'Alibaba PuHuiTi 3.0' ... !important }` 改为 `font-family: var(--font-family) !important`（见 4.B 第 1 条）。
@@ -339,13 +364,21 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
    background: white !important、#000000d9
    ```
 
-2. 在最终回复中**逐条回填**冲突清单处理结果（格式见 2.8 验证输出），禁止笼统写「已全部处理」。
+2. 在最终回复中**逐条回填**冲突清单处理结果（格式见 Step 8 验证输出），禁止笼统写「已全部处理」。
 
 ### Step 6 运行时主色与主题联动
 
 1. `public/platform-config.json` 的 `EpThemeColor` 改为规范主色（如 `#1677FF`）——这是 `useApp.ts` 的初始 `--el-color-primary` 来源。
 2. **localStorage 缓存陷阱（必告）**：`epThemeColor` 优先读 `localStorage` 的 `responsive-layout`，改完 `platform-config.json` 后**老访客不会自动生效**。必须在回复中提醒：清除浏览器 `responsive-layout` 缓存，或提升 `platform-config.json` 的 `Version` 触发重置。
-3. 侧边栏：在 `theme.scss` 追加/覆盖与规范匹配的 `html[data-theme]` 块。例：AntD Pro 浅色侧栏沿用 `light`，但把 `--vts-theme-menu-active-before` 覆盖为规范主色；深色侧栏用 `default`（`#001529` 与 AntD Pro 一致）。
+3. **公共区域（侧边栏 / 导航栏 / 内容壳）同样要按规范落地**——这些不在 EP 组件范围内，靠模版壳层变量与主题文件执行：
+
+   | 位置 | 项目 | 规范落地动作 |
+   |---|---|---|
+   | `theme.scss` | 侧栏配色 | 追加/覆盖与规范匹配的 `html[data-theme]` 块：`--vts-theme-menu-active-before` → 规范主色；菜单底/悬浮按规范形态（AntD Pro 浅色用 `light`，深色用 `default` `#001529`） |
+   | `index.scss` | 壳变量 | `--vts-bar-height`（导航高，AntD Pro 56px）、`--vts-margin`（内容边距）、`--vts-dialog-bg`（渐变改 `var(--el-bg-color-overlay)`）；改后回归验证列表页 `calc(100vh - ...)` |
+   | `platform-config.json` | 顶栏高度 | `HeaderHeight` 与规范一致（如 AntD Pro 56） |
+   | `sidebar.scss` | 侧栏几何 | 宽度走 `--sidebar-width`；菜单项高度走令牌层 EP 映射（`--el-menu-item-height`） |
+
 4. 暗黑模式：在 `dark.scss` 内为新增令牌补暗色覆盖（`--vts-table-header-bg`、`--vts-message-bg`、`--vts-dialog-bg` 等），遵守 `layout-theme` 第三节规则。
 
 ### Step 7 存量代码回归扫描（防"令牌层建好了但页面没跟上"）
@@ -357,7 +390,7 @@ grep 目标（*.vue 的 <style> 与行内 style）：
 height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 ```
 
-- 命中的 EP 控件裸几何 → 删除，交给 `design-controls.scss` 统一管。
+- 命中的 EP 控件裸几何 → 删除，交给 `element-plus.scss` 统一管。
 - 布局类间距（容器 padding/margin）→ 允许保留 UnoCSS `p-*`/`m-*`，但颜色 hex 必须换成令牌。
 - 扫描结果与处理数量写入最终回复。
 
@@ -380,11 +413,11 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 ## 三、业务代码编写规则（规范生效期全程有效）
 
 1. **禁止裸值**：业务页面/组件中不得对 EP 控件写裸 `height` / `padding` / `font-size` / `border-radius`，一律引用 `--control-*` / `--font-size-*` / `--radius-*` 令牌；布局间距用 UnoCSS `p-*` / `m-*`（4px 基数）。
-2. **禁止重复重写**：组件几何只在 `design-controls.scss` 统一改，业务页不得再写 `.el-input__wrapper { height: ... }` 之类的覆盖。
+2. **禁止重复重写**：组件几何只在 `element-plus.scss` 统一改（引用令牌），业务页不得再写 `.el-input__wrapper { height: ... }` 之类的覆盖。
 3. **颜色只走变量**：`--brand-*` / `--vts-*` / `--el-*`，禁止硬编码 hex（与 `layout-theme` 规则一致）。
-4. **换规范 = 只换令牌层**：切换设计系统时只重写 `design-tokens.scss`（必要时微调 `design-controls.scss` 差异项），业务代码零改动；做不到的写法说明违反了规则 1~3，必须修正。
+4. **换规范 = 只换令牌层**：切换设计系统时只重写 `design-tokens.scss`（`element-plus.scss` 几何段已令牌化，原则上无需改动），业务代码零改动；做不到的写法说明违反了规则 1~3，必须修正。
 5. 主色运行时切换仍走 `setEpThemeColor()`（保证 chroma 色阶同步），令牌层只负责初始值与非主色令牌。
-6. **命名纪律**：适配层文件永远叫 `design-tokens.scss` / `design-controls.scss`，禁止按规范名派生（如 `semi-controls.scss`）。
+6. **命名纪律**：适配新增文件永远只有一个 `design-tokens.scss`；禁止按规范名派生文件（如 `semi-controls.scss`、`antd-tokens.scss`），禁止再新建独立的几何重写层文件。
 
 ---
 
@@ -443,7 +476,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 1. 输出识别回执，「项目现状」标注为已适配的旧规范。
 2. **只重写** `design-tokens.scss` 的「用户可自定义」区块 + 语义别名 + EP 映射（按新规范速查表），桥接令牌段结构不变。
-3. `design-controls.scss` 仅在两规范几何差异处微调（如 vuetify 控件高度），结构不动。
+3. `element-plus.scss` 的几何段已全部令牌化，**原则上不动**；仅当两规范存在无法令牌化的结构差异时才微调（极罕见），结构不动。
 4. 更新 `platform-config.json` 的 `EpThemeColor`，并**提醒清 localStorage**（Step 6 第 2 条）。
 5. 重跑 Step 5 grep 验证、Step 7 存量扫描、Step 8 验证清单。
 6. 业务代码应当零改动；若有改动，说明存在裸值，先修裸值再切换。
@@ -486,7 +519,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 1. 先输出识别回执（规范 = 稿子所用系统；不在预设内则标 `custom`，按 1.3）。
 2. 按 7.2 归一化后，把「用户可自定义」区块的令牌值写入 `design-tokens.scss`。
-3. 若上游产出含组件视觉（HTML 原型/设计稿）→ 以其为基准微调 `design-controls.scss` 差异项。
+3. 若上游产出含组件视觉（HTML 原型/设计稿）→ 以其为基准微调 `element-plus.scss` 几何段的差异项。
 4. 上游产出里的业务配色（状态色、图表系列）按 `layout-theme` 第八节映射为 `--vts-*` 语义变量。
 5. 原型与项目出现视觉差异时：先对比两侧令牌值是否一致（含命名映射是否漏项），再查第四节冲突清单是否漏处理，最后查 Step 7 存量裸值。
 
@@ -502,9 +535,9 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 - 只把 `--el-color-primary` 改成规范主色就宣称"已适配 Ant Design"（字号/圆角/高度/内边距全未动）。
 - **识别漂移风险**：用户口述的规范与真正写入令牌层的规范不一致（如说要 AntD 却写了 `#0077fa`、`--semi-*` 别名的 Semi 令牌）——回执块与三点一致性校验就是防这个。
-- **命名漂移**：适配层建成 `tokens.scss` / `semi-controls.scss`，下次适配找不到又建一套——必须锁定 `design-tokens.scss` / `design-controls.scss`。
+- **命名漂移/重复建层**：适配文件建成 `tokens.scss`，或另起 `semi-controls.scss` 之类的几何重写层与 `element-plus.scss` 并存——新增文件只允许 `design-tokens.scss`，几何重写一律并入 `element-plus.scss`。
 - **冲突清单假完成**：声称「已全部处理」，实际 `reset.scss` 的 body 字体（不带 !important 的那条）与 `label { font-weight: 700 }` 原封未动——grep 时漏掉了不带 !important 的关键词。
-- 新建 `design-controls.scss` 但 `@use` 顺序放在 `element-plus` 之前 → 被模版覆盖层压回去。
+- **靠加载顺序压盖**：几何重写独立成文件、指望 `@use` 顺序盖过模版覆盖层，顺序一错样式静默失效——已改为并入 `element-plus.scss`，从根上消除顺序问题。
 - 弹窗仍是渐变蓝底（忘改 `--vts-dialog-bg`）。
 - 改了 `platform-config.json` 主色但没提醒清 localStorage → 老访客看到的还是旧色。
 - 业务页面里又写 `.el-input { height: 36px }` 之类的裸值覆盖 → 换规范时需要逐页改，违反规则 1~2。