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

package/README.md

@@ -9,7 +9,7 @@ Vue 3 企业级中后台项目开发规范技能包 — 让 AI 按团队规范
 **设计要点**：
 
 - **始终加载** `core-kernel` + `project-inventory`（生成前）
-- **生成后强制闸门** `code-quality`：重读清单 → 对照落盘文件 → `pnpm type-check` → 最终回复必须含「代码质量审查」结果块（仅列入命中模块不算完成）
+- **生成后强制闸门** `code-quality`：重读清单 → 对照落盘文件 → `pnpm lint:fix` + `pnpm type-check` → 最终回复必须含「代码质量审查」结果块（仅列入命中模块不算完成）
 - **Vite / 脚本 / 入口不单独成 Skill**（工程摘要在 core-kernel）
 - **组件 / Hook 分核心与附加**，专项能力按需命中
 - 按 `references/` 内完整示例编写；复用已有封装；选型表指定库勿擅自替换（新依赖须待确认）
@@ -42,7 +42,7 @@ Vue 3 企业级中后台项目开发规范技能包 — 让 AI 按团队规范
 
 | 模块 | 覆盖 |
 |------|------|
-| code-quality | 清单自查 + `pnpm type-check` + 最终回复「代码质量审查」结果块 |
+| code-quality | 清单自查 + `pnpm lint:fix` + `pnpm type-check` + 最终回复「代码质量审查」结果块 |
 
 ### 标准业务面
 
@@ -96,7 +96,7 @@ npx @qilitt-mickey/vue3-temp-skill@latest install all
 3. **addon**：查业务 `package.json`，缺失则按 inventory 第九节精确版本征得确认后 `pnpm add`（含 `-D` 插件）  
 4. 读功能模块；仓库有 Re*/Hook/utils 则复用，页面写法用 Skill 示例  
 5. 生成落盘  
-6. **强制闸门 code-quality**：重读清单 → 自查刚改文件 → `pnpm type-check` → 修正 → 最终回复输出「代码质量审查」结果块（缺块 = 未完成）  
+6. **强制闸门 code-quality**：重读清单 → 自查刚改文件 → `pnpm lint:fix` + `pnpm type-check` → 修正 → 最终回复输出「代码质量审查」结果块（缺块 / 缺 lint:fix = 未完成）  
 
 ## 源码位置
 

package/SKILL.md

@@ -12,8 +12,8 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 > 2. **始终加载** `core-kernel` + `project-inventory`（生成前必读）
 > 3. 加载命中的功能模块详细规范（`references/`）
 > 4. **以本 Skill 内示例为准编写代码**（复用已有封装；选型表指定的库勿擅自替换）
-> 5. **生成完成后强制执行 `code-quality` 闸门**（见工作流第 6 步）：重读清单 → 对照刚改文件自查 → 跑 `pnpm type-check` → 不通过就地修正 → 最终回复必须含「代码质量审查」结果块  
-> ⚠️ 仅在「命中模块」里写出 `code-quality` **不算**执行审查；没有审查结果块 = 任务未完成
+> 5. **生成完成后强制执行 `code-quality` 闸门**（见工作流第 6 步）：重读清单 → 对照刚改文件自查 → 必跑 `pnpm lint:fix` + `pnpm type-check` → 不通过就地修正 → 最终回复必须含「代码质量审查」结果块  
+> ⚠️ 仅在「命中模块」里写出 `code-quality` **不算**执行审查；没有审查结果块 = 任务未完成；只跑 type-check 未跑 lint:fix 也不算完成
 
 ---
 
@@ -63,7 +63,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 | 模块 | 文件 | 职责 |
 |------|------|------|
-| **code-quality** | `references/code-quality.md` | **写完/改完代码之后**再执行：对照清单自查 + `pnpm type-check` + 输出审查结果块；失败则修正后重跑 |
+| **code-quality** | `references/code-quality.md` | **写完/改完代码之后**再执行：对照清单自查 + `pnpm lint:fix` + `pnpm type-check` + 输出审查结果块；失败则修正后重跑 |
 
 > `code-quality` **不要**只放进「命中模块」列表交差。它是闸门：生成前可预览清单，但**正式审查必须在落盘之后**，并在最终回复中可见。
 
@@ -77,6 +77,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 | **data-writeback** | 回显、多表单校验 | 回显、回填、useFormCheck |
 | **permission-auth** | 页面/按钮权限 | 权限、v-auth、roles、ReAuth |
 | **layout-theme** | 布局主题、CSS 变量、暗黑 | 布局、主题、暗黑、`--vts-*`、UnoCSS |
+| **design-system** | 设计规范识别与全量适配（Ant Design / Semi / Arco / Vuetify / FindDesign） | 设计规范、UI 规范、按 XX 规范适配、Ant Design、Semi、Arco、Vuetify、FindDesign、京东风格、design-tokens、组件样式重写 |
 | **icons** | 图标体系（本地 SVG / Iconify / 菜单 / Picker） | 图标、svg-icon、Iconify、ReSvgIcon、ReIconPicker、菜单图标、extraIcon、i-ep、i-ri、本地图标、离线图标 |
 | **feedback-loading** | Message / Loading | message、loading、确认框 |
 | **base-code-dict** | 字典码表 | 字典、baseCode、码表 |
@@ -125,6 +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` 就宣称已适配，禁止识别漂移  
    - 只说「自定义指令」未说明效果 → 先追问，禁止默认塞模块  
 6. **HTTP**：方法跟后端文档，**允许 GET/POST**；POST→`data`，GET→`params`；真实 URL 用 `VITE_API_BASE_URL`；`/mock` 仅本地 Fake Server；无单请求 `crypto: true`。
 
@@ -246,8 +248,8 @@ reset();    // 重置（配合 formRef.resetFields）
 
 1. **重读** `references/code-quality.md`（生成后再读一次，不要只靠记忆）。
 2. **对照刚写入/修改的文件**逐项过清单（尤其：选型、HTTP/`Result`、列表布局、权限、无多余 console）。
-3. **跑命令**（在业务项目根目录）：优先 `pnpm type-check`；若项目有 `pnpm lint` 且改动含 `.vue/.ts`，尽量一并跑。失败则修代码后重跑，直到通过或明确阻塞原因。
-4. **就地修正**：审查发现的问题必须改完再进入第 7 步；禁止带着已知规范问题收工。
+3. **跑命令**（在业务项目根目录，**两项均必跑**）：先 `pnpm lint:fix`（无则 `pnpm lint` / `pnpm exec eslint . --fix`），再 `pnpm type-check`（无则 `pnpm exec vue-tsc --noEmit`）。失败则修代码后重跑两条，直到全部通过或明确阻塞原因。禁止只跑 type-check 就收工。
+4. **就地修正**：审查发现的问题必须改完再进入第 7 步；禁止带着已知规范 / lint 问题收工。
 5. **写入最终回复的「代码质量审查」结果块**（格式见下）；无此块视为任务未完成。
 
 #### 最终回复必含结构
@@ -259,7 +261,7 @@ reset();    // 重置（配合 formRef.resetFields）
 ## 代码质量审查
 - 闸门：已执行 code-quality（生成后）
 - 清单：选型 / 类型 / 组件 / API / 安全 / 业务 / 列表布局(如适用) / 风格 → 通过 | 已修正：…
-- 命令：`pnpm type-check` → 通过 | 失败原因…
+- 命令：`pnpm lint:fix` → 通过 | 失败原因…；`pnpm type-check` → 通过 | 失败原因…
 - 待确认：…
 
 ## 变更说明
@@ -287,6 +289,7 @@ reset();    // 重置（配合 formRef.resetFields）
 **4. 安全** — 无危险 v-html；无硬编码密钥  
 **5. 业务** — `onSearch`/`reset`；提交 loading；权限；未二次 Layout  
 **5b. 列表布局** — `el-card`+`content`+固定 height；查询/展示分区；`tableHeight`；分页在 ReTableBar 内  
+**5c. 设计规范遵从（命中 design-system 时必查）** — 已输出识别回执且三点一致；令牌层/几何重写层已建立且 `@use` 顺序正确、文件名未漂移；第四节硬编码冲突清单逐条处理并回填；存量裸值扫描已执行；业务代码无裸控件高度/内边距/字号；验证清单全过  
 **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.4",
+  "version": "1.1.6",
   "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块",
   "bin": {
     "vue3-temp-skill": "./bin/cli.js"

package/references/code-quality.md

@@ -1,6 +1,6 @@
 ---
 skill: code-quality
-description: 生成后强制质量闸门。写完/改完 Vue/TS 代码后必须重读本清单、对照落盘文件自查、跑 type-check，并在最终回复输出「代码质量审查」结果块。仅把本模块列入命中模块不算完成。
+description: 生成后强制质量闸门。写完/改完 Vue/TS 代码后必须重读本清单、对照落盘文件自查、必跑 lint:fix 与 type-check，并在最终回复输出「代码质量审查」结果块。仅把本模块列入命中模块不算完成。
 scope: project
 tags: [code-review, quality, checklist, lint, typescript, vue3, security, performance, gate]
 ---
@@ -8,17 +8,18 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 # 代码质量审查清单（生成后强制闸门）
 
 > **何时执行**：任意 `/vue3-temp-skill` 任务在**文件已写入或修改之后**，结束对话前必须执行本闸门。  
-> **不算完成**：只在「命中模块」里写 `code-quality`；或只跑了 type-check 却未对照本清单；或最终回复无「代码质量审查」结果块。  
+> **不算完成**：只在「命中模块」里写 `code-quality`；或只跑了 type-check / 未跑 `lint:fix`；或未对照本清单；或最终回复无「代码质量审查」结果块。  
 > **须按** Skill 功能模块示例 + 本清单审查；不通过必须修正后再收工。
 
 ## 强制执行协议（AI 必须按序做）
 
 1. **重读本文件**（生成后再读，禁止仅凭开场记忆勾选）。
 2. **列出本轮改动文件路径**，逐文件对照下方清单相关项。
-3. **执行命令**（业务项目根目录）：
+3. **执行命令**（业务项目根目录，**两项均必跑，缺一不可**）：
+   - 必跑：`pnpm lint:fix`（自动修复可修问题；若无该脚本则用 `pnpm lint`，再无则 `pnpm exec eslint . --fix`）
    - 必跑：`pnpm type-check`（若无该脚本则用 `pnpm exec vue-tsc --noEmit`）
-   - 建议：`pnpm lint`（存在且改动含 `.vue/.ts/.tsx` 时）
-4. **失败则修代码 → 重跑命令**，直到通过或写出明确阻塞（缺依赖、环境等）。
+   - 顺序建议：先 `lint:fix`，再 `type-check`（lint 可能改写文件，须以最终落盘结果过类型检查）
+4. **失败则修代码 → 重跑上述两条命令**，直到全部通过或写出明确阻塞（缺依赖、环境等）。`lint:fix` 后仍有无法自动修复的报错，必须手改后再跑，禁止跳过。
 5. **在最终回复追加结果块**（缺此块 = 未完成）：
 
 ```markdown
@@ -27,7 +28,7 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 - 改动文件：`path/a`、`path/b`、…
 - 清单：选型 ✅ / 类型 ✅ / 组件 ✅ / API ✅ / 安全 ✅ / 业务 ✅ / 列表布局 ✅或N/A / 风格 ✅
 - 已修正：…（无则写「无」）
-- 命令：`pnpm type-check` → 通过 | 失败：…
+- 命令：`pnpm lint:fix` → 通过 | 失败：…；`pnpm type-check` → 通过 | 失败：…
 - 待确认：…
 ```
 
@@ -237,6 +238,16 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 - [ ] 侧边栏相关样式通过 `html[data-theme]` 选择器设置，不写在 `:root` 中。
 - [ ] 覆盖 Element Plus 组件的全局样式放在 `src/styles/element-plus.scss`，不在组件内写。
 
+### 设计规范遵从（命中 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-system.md` 第四节「模版硬编码冲突清单」逐条处理并在回复中逐条回填（重点：通配符 font-family、reset.scss body 字体与 `label { font-weight: 700 }`、`.el-card__body` padding 5px、弹窗渐变蓝底、表头硬编码色）。
+- [ ] 主色三态（hover/active）、字体、控件高度、圆角、卡片内边距、表单标签字重、表头视觉均符合目标规范（按第二节验证清单核验）。
+- [ ] 业务代码无裸控件高度/内边距/字号/圆角；组件几何覆盖只集中在 `design-controls.scss`；存量裸值扫描已执行。
+- [ ] `platform-config.json` 的 `EpThemeColor` 与规范主色一致，已提醒清理 localStorage 缓存；新增令牌已在 `dark.scss` 补暗色覆盖。
+
 ## 七、业务逻辑检查
 
 ### 必须通过
@@ -277,21 +288,26 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 ## 审查流程
 
 1. **生成/改码落盘之后**（不是生成前）：执行上方「强制执行协议」。
-2. **发现问题**：立即修正并重跑 `pnpm type-check`，不要带着已知问题收工。
+2. **发现问题**：立即修正并重跑 `pnpm lint:fix` + `pnpm type-check`，不要带着已知问题收工。
 3. **不确定项**：写入结果块「待确认」，必要时在代码加 `// TODO: 需要确认`。
-4. **严重问题**（安全 / 类型错误 / 列表布局硬约束违反）：必须修正后再输出最终回复。
+4. **严重问题**（安全 / 类型错误 / lint 报错 / 列表布局硬约束违反）：必须修正后再输出最终回复。
 5. **最终回复**：必须含「代码质量审查」结果块；禁止只用「命中模块含 code-quality」代替。
 
 ## 快速自检命令
 
-完成代码修改后，运行以下命令验证：
+完成代码修改后，运行以下命令验证（**均必跑**）：
 
 ```bash
+# 必跑：Lint 自动修复（优先用项目脚本）
+pnpm lint:fix
+
 # 必跑：TypeScript 类型检查（优先用项目脚本）
 pnpm type-check
 
-# 建议：全量检查
+# 无 lint:fix 时的回退
 pnpm lint
+# 或
+pnpm exec eslint . --fix
 
 # 无 type-check 脚本时的回退
 pnpm exec vue-tsc --noEmit

package/references/core-kernel.md

@@ -359,7 +359,7 @@ function handleSizeChange(size: number) {
 
 | 项 | 说明 |
 |----|------|
-| 包管理 | pnpm；脚本 `dev` / `build` / `type-check` / `lint` |
+| 包管理 | pnpm；脚本 `dev` / `build` / `type-check` / `lint` / `lint:fix`（质量闸门必跑后两者） |
 | 默认插件 | Vue/JSX、AutoImport、SVG、UnoCSS、Favicon、Mock(`VITE_USE_MOCK`)、Gzip、Visualizer、混淆、DevTools |
 | 去 console | `build/build.ts`：非 `VITE_DEBUGGER` 时 Terser `drop_console`（**无** vite-plugin-remove-console） |
 | 功能附属插件 | FileViewer → `file-management`；vConsole → `mobile-h5`；精确版本与 `pnpm` 命令见 `project-inventory` 第九节 |

package/references/design-system.md

@@ -0,0 +1,514 @@
+---
+skill: design-system
+description: 设计规范识别与全量落地机制。当用户指定设计系统（内置预设：Ant Design / Semi Design / Arco Design / Vuetify / FindDesign 京东UDC；非封闭集，支持任意自定义规范）或要求"按 XX 规范 / 设计规范 / UI 规范适配项目"时，强制执行为「识别回执 + 令牌层 + 组件几何重写层 + 模版硬编码冲突处理 + 存量回归扫描」的完整适配流程，并在 code-quality 闸门中校验规范遵从。按通用协议自动识别并衔接任意上游 UI/UX 设计技能的令牌产出（不绑定具体技能名）。
+scope: project
+tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, element-plus, theme, css-variables]
+---
+
+# 设计规范识别与全量适配机制
+
+> **本模块的职责**：识别规范后，在**业务项目**内一次性建立「令牌层 + 组件几何重写层 + 硬编码冲突清理」三层适配，之后所有生成代码只准引用令牌，禁止裸值。
+>
+---
+
+## 一、触发与规范识别
+
+### 1.1 触发场景
+
+- 用户提到内置预设之一：`Ant Design` / `antd` / 蚂蚁、`Semi Design` / 字节 Semi、`Arco Design`、`Vuetify` / Material、`FindDesign` / 京东 UDC / jdd-design；或提到**任意其他设计系统 / 自定义规范**（预设非封闭集，见 1.4）
+- 用户说「按 XX 规范适配」「套设计规范」「UI 统一成 XX 风格」「重写组件样式以符合规范」
+- **上游设计技能**（名称不限，如 project-style-design 或任何同类 UI/UX 技能）产出了设计令牌 / HTML 原型 / 规范文档，用户要求落到项目
+
+### 1.2 识别表（内置预设 · 非封闭集）
+
+| 用户输入关键词 | 规范 ID | 主色默认 | 风格特征 |
+|---|---|---|---|
+| Ant Design / antd / 蚂蚁 / AntD / Pro | `antd` | `#1677ff` | 圆角 6px、字号 14、控件 32、页面底 `#f5f5f5` |
+| Semi Design / 字节 / 抖音风 | `semi` | `#0077fa` | 圆角 6px、轻阴影描边、控件 32 |
+| Arco Design / 字节 Arco | `arco` | `#165dff` | 圆角 4px、底 `#f2f3f5`、控件 32 |
+| Vuetify / Material | `vuetify` | `#1867c0` | 圆角 4px、Roboto、Material 阴影 |
+| FindDesign / 京东 / UDC | `findesign` | `#e2231a` | 京东红、圆角 4px、电商后台 |
+
+- 用户未指定且无上游产出 → **主动询问**选哪套规范（给出上表），禁止默认套用。
+- 用户或上游技能提供了自定义令牌（如 `:root` 中的 `--brand-*`）→ **以上游令牌为准**，覆盖预设默认值；解析规则见第七节。
+- 用户提到的规范不在上表 → 按 1.3 处理，禁止强行归入最接近的预设。
+
+### 1.3 规范不在内置预设内时的处理
+
+五大预设只是**内置速查**，不是封闭集。遇到上表之外的规范（企业内部规范、其他开源设计系统、混合风格）：
+
+1. **令牌驱动优先**：能从上游产出 / 官方文档 / 用户提供的 `:root` 取到令牌 → 直接采用，跳过预设表。
+2. **缺项就近推导**：缺失的令牌取**风格最接近的预设**同位值补齐（如某企业内部规范缺圆角 → 参考视觉最接近的预设）。
+3. **回执标注推导项**：识别回执的「目标规范」写实际名称并标 `custom`，推导补齐的令牌逐项列出，请用户确认。
+4. 禁止把无法对应的规范硬套进五大预设，也禁止因"不在表里"而拒绝适配。
+
+### 1.4 识别回执（强制 · 适配类任务第一步）
+
+命中本模块后，**动手改任何文件之前**，先在回复中输出识别回执块并与用户确认（批量/明确指令场景可直接执行，但回执块仍必须输出）：
+
+```markdown
+## 规范识别回执
+- 目标规范：<antd / semi / arco / vuetify / findesign / custom:「实际规范名」>
+- 规范来源：<用户明说 / 上游设计技能「技能名/产出物」产出 / 上下文推断>
+- 主色：<#xxxxxx>（hover <#xxxxxx> / active <#xxxxxx>）
+- 项目现状：<未适配 / 已适配 <规范名>，本次为切换 / 补漏>
+- 推导补齐项（仅 custom）：<由最接近预设补齐的令牌及取值>
+```
+
+**一致性约束**：
+
+1. 一次适配任务只允许**一套**规范。回执中的规范 ID 必须贯穿令牌层注释、`platform-config.json`、侧栏主题，**三处必须同名同色**。
+2. 若「项目现状 = 已适配其他规范」（例如项目里已有 Semi 令牌但用户要 AntD），本次属于**规范切换**，走第六节流程，禁止在旧文件上打补丁造成两套令牌并存。
+
+---
+
+## 二、强制适配工作流（按序执行，缺一不可）
+
+### 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` 等）→ **必须先重命名/合并为规范名**再继续；禁止让变体与规范名并存。
+3. **模版版本判定**（决定 Step 5 走哪条清单）：
+   ```
+   grep 目标：src/styles/element-plus.scss
+   - 出现 var(--vts-card-padding / var(--ds-form-label-weight → 新模版（已变量化），走 4.A
+   - 出现 padding: 5px !important / font-weight: 700 !important 裸值 → 旧模版，走 4.B
+   ```
+4. 读 `public/platform-config.json` 的 `EpThemeColor` 当前值，与回执主色比对。
+
+### Step 2 写入令牌层 `src/styles/design-tokens.scss`
+
+结构固定为四段：用户可自定义 → 规范语义别名 → 模版桥接令牌 → Element Plus 映射。
+
+```scss
+/**
+ * Design Tokens · <规范名>
+ * 组件层为 Element Plus，视觉令牌全局映射为 <规范名> 体系。
+ * 改主题：优先改「用户可自定义」区块，或改 public/platform-config.json 的 EpThemeColor。
+ */
+:root {
+  /* ===== 用户可自定义 ===== */
+  --brand-primary: #1677ff;
+  --brand-hover: #4096ff;
+  --brand-active: #0958d9;
+  --font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC',
+    'Hiragino Sans GB', 'Microsoft YaHei', sans-serif;
+  --font-size-sm: 12px;
+  --font-size-base: 14px;
+  --font-size-lg: 16px;
+  --font-size-xl: 20px;
+  --font-size-2xl: 24px;
+  --font-weight-regular: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --line-height: 1.5715;
+  --radius-sm: 4px;
+  --radius-base: 6px;
+  --radius-lg: 8px;
+  --space-unit: 4px;
+  --control-height-sm: 24px;
+  --control-height: 32px;
+  --control-height-lg: 40px;
+  --control-padding-x: 12px;
+  --card-padding: 24px;
+  --layout-bg: #f5f5f5;
+  --sidebar-width: 208px;
+  --header-height: 56px;
+  /* ===== 用户可自定义 ===== */
+
+  /* —— 规范语义别名（--vts-* 业务语义层，映射规范令牌） —— */
+  --vts-color-success: #52c41a;
+  --vts-color-warning: #faad14;
+  --vts-color-danger: #ff4d4f;
+  --vts-color-info: #1677ff;
+  --vts-bg-color-page: var(--layout-bg);
+  --vts-border-color-cool: #d9d9d9;
+  --vts-table-header-bg: #fafafa;
+  --vts-table-header-text: rgb(0 0 0 / 88%);
+  --vts-row-added-bg: #e6f4ff;
+  --vts-row-modified-bg: #fffbe6;
+  --vts-row-deleted-bg: #f5f5f5;
+
+  /* —— 模版桥接令牌（给模版 var(--x, 默认值) 提供适配值；新模版必配，旧模版无害） —— */
+  --vts-card-padding: var(--card-padding);
+  --ds-form-label-weight: var(--font-weight-regular);
+  --ds-placeholder-color: var(--el-text-color-placeholder);
+  --vts-message-bg: var(--el-bg-color-overlay);
+  --vts-message-text: var(--el-text-color-primary);
+  --vts-collapse-header-padding: var(--vts-space-xs, 8px) var(--vts-space-md, 16px);
+  --vts-collapse-header-text: var(--el-text-color-primary);
+  --vts-collapse-header-size: var(--font-size-lg);
+  --vts-collapse-header-weight: var(--font-weight-semibold);
+  --vts-scrollbar-bg: transparent;
+  --vts-scrollbar-thumb: var(--vts-border-color-cool);
+  --vts-scrollbar-thumb-hover: var(--el-text-color-secondary);
+  --vts-autofill-bg: var(--el-bg-color);
+  --vts-autofill-text: var(--el-text-color-primary);
+
+  /* —— Element Plus 变量映射（必配，含主色兜底） —— */
+  --el-color-primary: var(--brand-primary); /* 兜底：JS 运行时 setEpThemeColor 生效前的首屏主色 */
+  --el-color-success: var(--vts-color-success);
+  --el-color-warning: var(--vts-color-warning);
+  --el-color-danger: var(--vts-color-danger);
+  --el-color-info: var(--vts-color-info);
+  --el-font-family: var(--font-family);
+  --el-font-size-base: var(--font-size-base);
+  --el-font-size-small: var(--font-size-sm);
+  --el-font-size-extra-small: var(--font-size-sm);
+  --el-font-size-medium: var(--font-size-base);
+  --el-font-size-large: var(--font-size-lg);
+  --el-font-size-extra-large: var(--font-size-xl);
+  --el-font-weight-primary: var(--font-weight-regular);
+  --el-border-radius-base: var(--radius-base);
+  --el-border-radius-small: var(--radius-sm);
+  --el-component-size: var(--control-height);
+  --el-component-size-small: var(--control-height-sm);
+  --el-component-size-large: var(--control-height-lg);
+  --el-border-color: var(--vts-border-color-cool);
+  --el-border-color-light: var(--vts-border-color-cool);
+  --el-border-color-lighter: var(--vts-border-color-cool);
+  --el-fill-color-light: var(--vts-table-header-bg);
+  --el-fill-color-blank: #fff;
+  --el-bg-color: #fff;
+  --el-bg-color-page: var(--layout-bg);
+  --el-text-color-primary: rgb(0 0 0 / 88%);
+  --el-text-color-regular: rgb(0 0 0 / 65%);
+  --el-text-color-secondary: rgb(0 0 0 / 45%);
+  --el-text-color-placeholder: rgb(0 0 0 / 25%);
+}
+```
+
+> 上面是 **Ant Design 预设**。其他规范按第五节令牌速查表替换「用户可自定义」区块与语义色。
+
+### Step 3 写入组件几何重写层 `src/styles/design-controls.scss`
+
+只重写几何规格（高度 / 内边距 / 字号 / 圆角），全部引用令牌，**禁止再写裸值**。完整黄金样板（覆盖 EP 常用控件全集，按需删减但禁止新增裸值）：
+
+```scss
+/**
+ * <规范名> → Element Plus 几何规格重写
+ * 全部引用 design-tokens.scss 令牌；业务页禁止再写裸高度/内边距。
+ */
+
+/* —— 按钮 —— */
+.el-button {
+  height: var(--control-height);
+  padding: 0 15px;
+  font-size: var(--font-size-base);
+  font-weight: var(--font-weight-regular);
+  border-radius: var(--radius-base);
+}
+.el-button--small { height: var(--control-height-sm); padding: 0 var(--vts-space-xs, 8px); font-size: var(--font-size-sm); }
+.el-button--large { height: var(--control-height-lg); padding: 0 var(--vts-space-md, 16px); font-size: var(--font-size-lg); }
+.el-button.is-circle { width: var(--control-height); padding: 0; }
+
+/* —— 输入类控件（input/select/date/cascader/input-number） —— */
+.el-input__wrapper,
+.el-select__wrapper,
+.el-cascader .el-input__wrapper,
+.el-date-editor.el-input__wrapper,
+.el-date-editor .el-input__wrapper,
+.el-input-number .el-input__wrapper {
+  min-height: var(--control-height);
+  padding: 0 var(--control-padding-x);
+  font-size: var(--font-size-base);
+  border-radius: var(--radius-base);
+}
+.el-input--small .el-input__wrapper,
+.el-select--small .el-select__wrapper { min-height: var(--control-height-sm); font-size: var(--font-size-sm); }
+.el-input--large .el-input__wrapper,
+.el-select--large .el-select__wrapper { min-height: var(--control-height-lg); font-size: var(--font-size-lg); }
+.el-input__inner, .el-select__selected-item { font-size: inherit; }
+.el-textarea__inner {
+  padding: var(--vts-space-xs, 8px) var(--control-padding-x);
+  border-radius: var(--radius-base);
+  font-size: var(--font-size-base);
+  line-height: var(--line-height);
+}
+
+/* —— 表单 —— */
+.el-form-item { margin-bottom: var(--vts-space-md, 16px); }
+.el-form-item__label {
+  height: var(--control-height);
+  line-height: var(--control-height);
+  font-size: var(--font-size-base);
+  font-weight: var(--ds-form-label-weight, var(--font-weight-regular)); /* AntD/Semi 表单标签不加粗 */
+  color: var(--el-text-color-regular);
+}
+.el-form-item__content { min-height: var(--control-height); }
+.el-checkbox__inner, .el-radio__inner { width: 16px; height: 16px; border-radius: var(--radius-sm); }
+.el-radio__inner { border-radius: 50%; }
+.el-switch__core { min-width: 36px; height: 20px; border-radius: 10px; }
+
+/* —— 表格 —— */
+.el-table {
+  font-size: var(--font-size-base);
+  .el-table__header th {
+    color: var(--vts-table-header-text);
+    background: var(--vts-table-header-bg);
+    font-weight: var(--font-weight-semibold);
+  }
+  .el-table__cell { padding: var(--vts-space-xs, 8px) 0; }
+  .el-table__row.row-added > .el-table__cell { background: var(--vts-row-added-bg); }
+  .el-table__row.row-modified > .el-table__cell { background: var(--vts-row-modified-bg); }
+  .el-table__row.row-deleted > .el-table__cell { background: var(--vts-row-deleted-bg); }
+}
+
+/* —— 卡片 —— */
+.el-card { border-radius: var(--radius-lg); }
+.el-card__header { padding: var(--vts-space-md, 16px) var(--card-padding); font-size: var(--font-size-lg); font-weight: var(--font-weight-semibold); }
+.el-card__body { padding: var(--vts-card-padding, var(--card-padding)); }
+
+/* —— 标签 / 徽章 / 提示 —— */
+.el-tag { height: 22px; padding: 0 var(--vts-space-xs, 8px); font-size: var(--font-size-sm); line-height: 20px; border-radius: var(--radius-sm); }
+.el-alert { padding: var(--vts-space-xs, 8px) var(--vts-space-md, 16px); font-size: var(--font-size-base); border-radius: var(--radius-base); }
+
+/* —— 分页 —— */
+.el-pagination {
+  --el-pagination-font-size: var(--font-size-base);
+  --el-pagination-button-width: var(--control-height);
+  --el-pagination-button-height: var(--control-height);
+  font-size: var(--font-size-base);
+}
+.el-pager li, .el-pagination button {
+  min-width: var(--control-height);
+  height: var(--control-height);
+  line-height: var(--control-height);
+  font-size: var(--font-size-base);
+  border-radius: var(--radius-base);
+}
+
+/* —— 弹窗 / 抽屉 / 消息盒 —— */
+.el-dialog, .el-message-box { padding: 0; font-size: var(--font-size-base); border-radius: var(--radius-lg); }
+.el-dialog__header, .el-message-box__header { padding: 16px 24px; margin-right: 0; }
+.el-dialog__title, .el-message-box__title { font-size: var(--font-size-lg); font-weight: var(--font-weight-semibold); }
+.el-dialog__body, .el-message-box__content { padding: 24px; font-size: var(--font-size-base); line-height: var(--line-height); }
+.el-dialog__footer, .el-message-box__btns { padding: var(--vts-space-md, 16px) 24px; }
+.el-drawer__header { padding: var(--vts-space-md, 16px) 24px; margin-bottom: 0; font-size: var(--font-size-lg); }
+.el-drawer__body { padding: var(--vts-space-md, 16px) 24px; }
+
+/* —— 下拉 / 弹出选项 —— */
+.el-dropdown-menu__item { padding: 0 var(--vts-space-md, 16px); font-size: var(--font-size-base); line-height: var(--control-height); }
+.el-select-dropdown__item { height: var(--control-height); padding: 0 var(--control-padding-x); font-size: var(--font-size-base); line-height: var(--control-height); }
+
+/* —— 导航：页签 / 菜单 / 面包屑 —— */
+.el-tabs__item { font-size: var(--font-size-base); height: 46px; padding: 0 var(--vts-space-md, 16px); }
+.el-menu-item, .el-sub-menu__title {
+  height: var(--el-menu-item-height, 40px);
+  line-height: var(--el-menu-item-height, 40px);
+  font-size: var(--font-size-base);
+}
+.el-breadcrumb { font-size: var(--font-size-base); line-height: var(--line-height); }
+```
+
+> 各规范差异项：`antd` 表头 `#fafafa` 不加边框分隔；`semi` 少阴影轻描边；`vuetify` 控件高度 Material 化（input 40px、button 36px）；按第五节表微调样板中的数值来源即可，**结构不变**。
+
+### Step 4 接线 `src/styles/index.scss`（顺序即优先级）
+
+```scss
+@use 'design-tokens';     // ① 令牌必须最先，供后续文件引用
+@use 'theme';
+@use 'transition';
+@use 'button';
+@use 'element-plus';      // ② 模版原生覆盖
+@use 'design-controls';   // ③ 规范重写必须在其后，同选择器后者优先
+@use 'sidebar';
+@use 'dark';
+@use 'vant';
+```
+
+**字体接管**：
+- 新模版：`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 条）。
+
+### Step 5 模版硬编码冲突处理（按模版版本二选一，逐条回填）
+
+- **4.A（新模版，已变量化）**：模版样式均为 `var(--x, 默认值)` 形式，Step 2 的「模版桥接令牌」段已自动接管。**逐条确认**桥接令牌齐全即可，重点核对 `--vts-dialog-bg`（仍定义在 index.scss :root，需把渐变值改为 `var(--el-bg-color-overlay)`）。
+- **4.B（旧模版）**：按第四节冲突清单**逐条手工处理**。
+
+**无论走哪条路**，处理完必须：
+
+1. 用全文检索验证：下列模式在 `src/styles/` 内**不得出现在 `var(...)` 回退值之外**（新模版里它们以 `var(--x, 原值)` 的 fallback 形式存在属合法；旧模版或裸值残留则属未处理干净）：
+
+   ```
+   Alibaba PuHuiTi（注意：不带 !important 的也要查，reset.scss body 就是一条）
+   padding: 5px、font-weight: 700、#9ca3af、#34394d、#f2f9fc、#8c8f90、
+   #e6f4ff、#fff7e6、#fffbe6、linear-gradient(to bottom, #e5f3fe、
+   background: white !important、#000000d9
+   ```
+
+2. 在最终回复中**逐条回填**冲突清单处理结果（格式见 2.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 一致）。
+4. 暗黑模式：在 `dark.scss` 内为新增令牌补暗色覆盖（`--vts-table-header-bg`、`--vts-message-bg`、`--vts-dialog-bg` 等），遵守 `layout-theme` 第三节规则。
+
+### Step 7 存量代码回归扫描（防"令牌层建好了但页面没跟上"）
+
+适配/切换完成后，对 `src/views/` 与 `src/components/` 跑一遍裸值扫描：
+
+```
+grep 目标（*.vue 的 <style> 与行内 style）：
+height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
+```
+
+- 命中的 EP 控件裸几何 → 删除，交给 `design-controls.scss` 统一管。
+- 布局类间距（容器 padding/margin）→ 允许保留 UnoCSS `p-*`/`m-*`，但颜色 hex 必须换成令牌。
+- 扫描结果与处理数量写入最终回复。
+
+### Step 8 验证清单（并入最终回复的「代码质量审查」）
+
+- [ ] 主色：按钮/链接/选中态均为规范主色（含 hover/active 三态）
+- [ ] 字体：DevTools 检查 body 与 `.el-input__inner` 的 computed font-family 为规范字体（**含 reset.scss body 一处**）
+- [ ] 控件高度：input/button 计算高度 = 规范值（24/32/40 或规范预设）
+- [ ] 圆角：input、button、card、dialog 均为规范圆角
+- [ ] 表格：表头底色/文字色/字重符合规范
+- [ ] 卡片内边距：`.el-card__body` = 规范值（AntD 24px），不再是 5px
+- [ ] 表单标签：computed font-weight 为规范值（AntD/Semi = 400，非 700）
+- [ ] 弹窗：无渐变蓝底，背景为规范底色，圆角符合规范
+- [ ] 暗黑模式下无白底黑字残留（切换 `html.dark` 验证）
+- [ ] 第四节冲突清单全部处理完毕（逐条回填）
+- [ ] Step 7 存量扫描已执行且结果已输出
+
+---
+
+## 三、业务代码编写规则（规范生效期全程有效）
+
+1. **禁止裸值**：业务页面/组件中不得对 EP 控件写裸 `height` / `padding` / `font-size` / `border-radius`，一律引用 `--control-*` / `--font-size-*` / `--radius-*` 令牌；布局间距用 UnoCSS `p-*` / `m-*`（4px 基数）。
+2. **禁止重复重写**：组件几何只在 `design-controls.scss` 统一改，业务页不得再写 `.el-input__wrapper { height: ... }` 之类的覆盖。
+3. **颜色只走变量**：`--brand-*` / `--vts-*` / `--el-*`，禁止硬编码 hex（与 `layout-theme` 规则一致）。
+4. **换规范 = 只换令牌层**：切换设计系统时只重写 `design-tokens.scss`（必要时微调 `design-controls.scss` 差异项），业务代码零改动；做不到的写法说明违反了规则 1~3，必须修正。
+5. 主色运行时切换仍走 `setEpThemeColor()`（保证 chroma 色阶同步），令牌层只负责初始值与非主色令牌。
+6. **命名纪律**：适配层文件永远叫 `design-tokens.scss` / `design-controls.scss`，禁止按规范名派生（如 `semi-controls.scss`）。
+
+---
+
+## 四、模版自带硬编码冲突清单
+
+> 来源：模版 `vue3-web-temp` 的 `src/styles/`。新模版已将下列项**变量化**（`var(--x, 默认值)`），适配时由 Step 2 桥接令牌自动接管（4.A）；旧模版生成的项目需逐条手工处理（4.B）。
+
+| # | 文件 | 硬编码内容 | 与规范的冲突 | 新模版状态 | 旧项目处理 |
+|---|------|-----------|-------------|-----------|-----------|
+| 1 | `index.scss` | `* { font-family: 'Alibaba PuHuiTi 3.0' ... !important }` | **最致命**：通配符 + !important | 已变量化 `var(--font-family, ...)` | 改为 `font-family: var(--font-family) !important` |
+| 2 | `reset.scss` | body `font-family: 'Alibaba PuHuiTi 3.0'...` | 同上 | 已变量化 | 改为 `var(--font-family)` |
+| 3 | `reset.scss` | `label { font-weight: 700 }` | AntD/Semi 表单标签为常规字重 | 已变量化 `var(--ds-form-label-weight, 700)` | 改为 `var(--ds-form-label-weight)` |
+| 4 | `reset.scss` | placeholder 色 `#9ca3af` | 不符合规范占位色阶 | 已变量化 `var(--ds-placeholder-color, ...)` | 改为 `var(--ds-placeholder-color)` |
+| 5 | `element-plus.scss` | `.el-form-item__label { font-weight: 700 !important }` | 同 #3 | 已变量化 | 改为 `var(--ds-form-label-weight) !important` |
+| 6 | `element-plus.scss` | `.el-card__body { padding: 5px !important }` | AntD 卡片内边距 24px | 已变量化 `var(--vts-card-padding, 5px)` | 改为 `var(--vts-card-padding) !important` |
+| 7 | `element-plus.scss` | `.el-collapse-item__header` 字号 16px / bold / `#34394d` | 折叠面板脱离规范 | 已变量化 | 颜色/字重/字号走 `--vts-collapse-header-*` |
+| 8 | `element-plus.scss` | `.el-table__header th` 色 `#8c8f90` + 底 `#f2f9fc` | 表头不跟随规范 | 已变量化 `--vts-table-header-*` | 改 `--vts-table-header-text/bg` |
+| 9 | `element-plus.scss` | `.row-added/#e6f4ff`、`.row-modified/#fff7e6`、`.row-deleted/#f5f5f5` | 行变更色脱离规范且无暗色适配 | 已变量化 `--vts-row-*-bg` | 改 `--vts-row-*-bg` 令牌 |
+| 10 | `element-plus.scss` | `.vts-message` 背景 `white`、文字 `#000000d9` | 暗黑/规范底失效 | 已变量化 `--vts-message-bg/text` | 改 `var(--vts-message-bg/text)` |
+| 11 | `index.scss` | `--vts-dialog-bg: linear-gradient(to bottom, #e5f3fe, #fefefe)` | **所有弹窗强制渐变蓝底** | **仍未变量化**（定义在 :root） | 令牌改为 `var(--el-bg-color-overlay)`；暗黑在 dark.scss 覆盖 |
+| 12 | `theme.scss` | 8 套侧栏配色（激活条 `#4091f7` 等） | 激活指示条非规范主色 | 主题库保留 | 追加规范匹配的 `html[data-theme]` 块覆盖 `--vts-theme-menu-active-before` |
+| 13 | `useApp.ts` | `epThemeColor` 缺省 `#409EFF` | EP 出厂蓝 ≠ 规范主色 | 不改代码 | 改 `platform-config.json` 的 `EpThemeColor`（Step 6） |
+| 14 | `index.scss` | `--vts-bar-height: 38px`、`--vts-margin: 8px` | 与规范导航高度（AntD Pro 56px）不一致 | 令牌可覆盖 | 令牌层覆盖并回归验证列表页 `calc(100vh - ...)`；默认保持不变标注差异 |
+| 15 | `button.scss` | `.btn/.golang/.php` 演示按钮（122×44 等） | 仅演示用，影响小 | 不处理 | 业务禁止使用这些类名 |
+
+---
+
+## 五、内置预设令牌速查表（替换 Step 2「用户可自定义」区块）
+
+> 仅适用于命中内置预设的场景；`custom` 规范按 1.3 直接用上游令牌，本表只用于缺项推导参考。
+
+| 令牌 | **antd**（Ant Design 5） | **semi**（Semi Design） | **arco**（Arco Design） | **vuetify**（Material） | **findesign**（京东 UDC） |
+|---|---|---|---|---|---|
+| `--brand-primary` | `#1677ff` | `#0077fa` | `#165dff` | `#1867c0` | `#e2231a` |
+| `--brand-hover` | `#4096ff` | `#1c7bff` | `#4080ff` | `#2196f3` | `#ff5148` |
+| `--brand-active` | `#0958d9` | `#0054c8` | `#0e42d2` | `#0d47a1` | `#c91623` |
+| success / warning / danger | `#52c41a` / `#faad14` / `#ff4d4f` | `#00b42a` / `#ff8d1a` / `#fb2323` | `#00b42a` / `#ff7d00` / `#f53f3f` | `#4caf50` / `#fb8c00` / `#f44336` | `#029e74` / `#f7ba2a` / `#e2231a` |
+| `--font-family` | `-apple-system..., 'PingFang SC','Microsoft YaHei'` | `'Inter', -apple-system..., 'PingFang SC'` | `-apple-system..., 'PingFang SC'` | `Roboto, 'PingFang SC', sans-serif` | `-apple-system..., 'PingFang SC'` |
+| 字号 sm/base/lg/xl | 12 / 14 / 16 / 20 | 12 / 14 / 16 / 20 | 12 / 14 / 16 / 20 | 12 / 14 / 16 / 20 | 12 / 14 / 16 / 20 |
+| `--line-height` | 1.5715 | 1.5 | 1.5715 | 1.5 | 1.5715 |
+| 圆角 sm/base/lg | 4 / 6 / 8 | 4 / 6 / 8 | 2 / 4 / 8 | 4 / 4 / 8 | 2 / 4 / 8 |
+| 控件高 sm/base/lg | 24 / 32 / 40 | 28 / 32 / 36 | 28 / 32 / 36 | 30 / 36 / 44 | 24 / 32 / 40 |
+| `--card-padding` | 24 | 20 | 16 | 16 | 16 |
+| `--layout-bg` | `#f5f5f5` | `#f7f8fa` | `#f2f3f5` | `#f5f5f5` | `#f2f3f5` |
+| 边框色 | `#d9d9d9` | `rgb(229 230 235)` | `#e5e6eb` | `rgb(0 0 0 / 12%)` | `#dcdfe6` |
+| 文字 primary/regular/secondary | `rgb(0 0 0/88%)` / 65% / 45% | `rgb(0 0 0/90%)` / 75% / 35% | `#1d2129` / `#4e5969` / `#86909c` | `rgb(0 0 0/87%)` / 60% / 38% | `#303133` / `#606266` / `#909399` |
+| 表头底 / 文字 | `#fafafa` / `rgb(0 0 0/88%)` | `#f7f8fa` / `rgb(78 89 105)` | `#f7f8fa` / `#4e5969` | `#fafafa` / `rgb(0 0 0/87%)` | `#f5f7fa` / `#606266` |
+| 侧栏建议 | Pro 深色 `#001529`（default 主题）或浅色 light | 浅色 light | 深色 `#1d2129` 或浅色 | 浅色 light | 深色 `#1f2329` 或浅色 |
+| `EpThemeColor`（platform-config.json） | `#1677FF` | `#0077FA` | `#165DFF` | `#1867C0` | `#E2231A` |
+
+> 表格给的是各规范**官方默认**；用户或上游设计技能提供自定义令牌时以自定义为准。
+
+---
+
+## 六、规范切换流程（已适配项目换另一套规范）
+
+1. 输出识别回执，「项目现状」标注为已适配的旧规范。
+2. **只重写** `design-tokens.scss` 的「用户可自定义」区块 + 语义别名 + EP 映射（按新规范速查表），桥接令牌段结构不变。
+3. `design-controls.scss` 仅在两规范几何差异处微调（如 vuetify 控件高度），结构不动。
+4. 更新 `platform-config.json` 的 `EpThemeColor`，并**提醒清 localStorage**（Step 6 第 2 条）。
+5. 重跑 Step 5 grep 验证、Step 7 存量扫描、Step 8 验证清单。
+6. 业务代码应当零改动；若有改动，说明存在裸值，先修裸值再切换。
+
+---
+
+## 七、与上游设计技能的衔接协议（通用 · 不绑定具体技能名）
+
+> 上游可能是 `project-style-design`，也可能是任何同类 UI/UX 设计技能，甚至是用户手工整理的规范文档。**只认产出物，不认技能名**：无论哪个技能，只要产出了令牌/原型/规范文档，都按本协议解析。
+
+### 7.1 产出物识别（先找到要解析什么）
+
+按以下线索定位上游产出物：
+
+1. **会话上下文**：当前/前序对话中调用过的设计类技能及其产出（单文件 HTML 原型、令牌表、规范 md）。
+2. **用户提供的文件/路径**：含 `:root { --... }` 的 HTML/CSS、设计令牌 JSON/YAML、规范文档。
+3. **特征检测**：产出物中含 `--brand-*` / `--primary` / `colorPrimary` / design token 表 / 组件视觉稿 → 即可作为衔接输入。
+
+### 7.2 令牌归一化（上游命名 ≠ 本模块标准名）
+
+不同技能/规范的令牌命名不一定与本模块 Step 2 一致，**禁止假设同名**。逐项建立映射后写入 `design-tokens.scss`：
+
+| 本模块标准令牌 | 常见上游别名（举例，按实际产出识别） |
+|---|---|
+| `--brand-primary` | `--primary` / `colorPrimary` / `--ds-primary` / 主色 |
+| `--brand-hover` / `--brand-active` | `--primary-hover` / `colorPrimaryHover` / 主色-悬浮 |
+| `--font-size-base` | `--font-size` / `fontSizeBase` / 基础字号 |
+| `--radius-base` | `--border-radius` / `borderRadius` / 圆角 |
+| `--control-height` | `--component-size` / `controlHeight` / 控件高度 |
+| `--card-padding` | `--padding-lg` / `cardPadding` / 卡片内边距 |
+| `--layout-bg` | `--bg-page` / `colorBgLayout` / 页面背景 |
+
+- 上游命名与标准名一致 → 直接采用。
+- 不一致 → 在令牌层内做别名映射（`--brand-primary: var(--primary)` 或直接赋值），**对外只暴露标准名**。
+- 上游未提供的令牌 → 按 1.3 缺项推导补齐，并在回执中列出。
+
+### 7.3 落项目流程
+
+当用户要求「把上游设计技能的稿子/令牌落到项目」：
+
+1. 先输出识别回执（规范 = 稿子所用系统；不在预设内则标 `custom`，按 1.3）。
+2. 按 7.2 归一化后，把「用户可自定义」区块的令牌值写入 `design-tokens.scss`。
+3. 若上游产出含组件视觉（HTML 原型/设计稿）→ 以其为基准微调 `design-controls.scss` 差异项。
+4. 上游产出里的业务配色（状态色、图表系列）按 `layout-theme` 第八节映射为 `--vts-*` 语义变量。
+5. 原型与项目出现视觉差异时：先对比两侧令牌值是否一致（含命名映射是否漏项），再查第四节冲突清单是否漏处理，最后查 Step 7 存量裸值。
+
+### 7.4 约束
+
+- 本模块与上游技能**解耦**：上游技能更名/替换不影响本协议，只需重新定位产出物。
+- 禁止在本文档或生成代码中硬编码上游技能名作为流程前提；提及仅作举例。
+- 上游只给视觉稿没给令牌时，从稿子的 computed 样式/标注反推令牌，并在回执中注明"反推"项。
+
+---
+
+## 八、常见反例（含实战事故）
+
+- 只把 `--el-color-primary` 改成规范主色就宣称"已适配 Ant Design"（字号/圆角/高度/内边距全未动）。
+- **识别漂移风险**：用户口述的规范与真正写入令牌层的规范不一致（如说要 AntD 却写了 `#0077fa`、`--semi-*` 别名的 Semi 令牌）——回执块与三点一致性校验就是防这个。
+- **命名漂移**：适配层建成 `tokens.scss` / `semi-controls.scss`，下次适配找不到又建一套——必须锁定 `design-tokens.scss` / `design-controls.scss`。
+- **冲突清单假完成**：声称「已全部处理」，实际 `reset.scss` 的 body 字体（不带 !important 的那条）与 `label { font-weight: 700 }` 原封未动——grep 时漏掉了不带 !important 的关键词。
+- 新建 `design-controls.scss` 但 `@use` 顺序放在 `element-plus` 之前 → 被模版覆盖层压回去。
+- 弹窗仍是渐变蓝底（忘改 `--vts-dialog-bg`）。
+- 改了 `platform-config.json` 主色但没提醒清 localStorage → 老访客看到的还是旧色。
+- 业务页面里又写 `.el-input { height: 36px }` 之类的裸值覆盖 → 换规范时需要逐页改，违反规则 1~2。
+- 换规范时连业务组件样式一起改（说明令牌层抽象失败）。
+- 暗黑模式不适配新令牌，切 dark 后表头/行变更色刺眼。
+- **固化上游技能名**：流程里写死"必须先用 project-style-design"，换个同类技能就不会衔接——正确做法是按第七节协议只认产出物。
+- **预设硬套**：把不在五大预设内的规范强行归入最接近的预设，或假设上游令牌名与本模块标准名一致而不做归一化映射。