@qilitt-mickey/vue3-temp-skill 1.1.11 → 1.1.13

package/references/design-system.md

@@ -1,28 +1,22 @@
 ---
 skill: design-system
-description: 设计规范识别与全量落地机制。当用户指定设计系统（内置预设：Ant Design / Semi Design / Arco Design / Vuetify / FindDesign 京东UDC；非封闭集，支持任意自定义规范）或要求"按 XX 规范 / 设计规范 / UI 规范适配项目"时，强制执行为「识别回执 + 令牌层（唯一新增文件）+ 几何重写并入 element-plus.scss + 模版硬编码冲突处理 + 公共区域适配 + 存量回归扫描」的完整适配流程，并在 code-quality 闸门中校验规范遵从。按通用协议自动识别并衔接任意上游 UI/UX 设计技能的令牌产出（不绑定具体技能名）。
+description: 设计规范识别与全量落地。命中「按 XX / UI 规范适配」时执行：识别回执 + design-tokens.scss + 几何并入 element-plus.scss + 冲突清单 + 公共区域。有上游设计产出时先走 design-handoff Step 0。
 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 模版既有文件）
+识别规范后，在业务项目完成：令牌层（数据）+ 模版样式改写（执行）+ 硬编码冲突清理。之后业务只引令牌，禁止裸值。组件层仍是 Element Plus（不换组件，只换令牌数据）。
 
-| 文件 | 职责 | 内容形态 |
-|------|------|---------|
-| `design-tokens.scss`（**唯一新增**） | 规范**数据源**：主色/字体/字号/圆角/控件高度/间距 + 模版桥接令牌 + `--el-*` 映射 | 纯 `:root` 变量，**禁止选择器与组件类** |
-| `element-plus.scss`（模版既有） | EP 组件几何与视觉覆盖的**唯一出口**：模版默认 + 规范重写都在这里，全部引用令牌 | 选择器 + `var()`，每段标注规范注释 |
-| `reset.scss` / `index.scss`（模版既有） | 基础样式与全局壳变量（导航高/内容边距/弹窗底） | 引用令牌 |
-| `theme.scss` / `sidebar.scss`（模版既有） | 侧边栏/导航配色与几何 | 按规范换色，引用令牌 |
+| 文件 | 职责 |
+|------|------|
+| `design-tokens.scss`（**唯一新增**） | 纯 `:root` 数据：主色/字体/圆角/高度 + 桥接 + `--el-*`；禁止选择器 |
+| `element-plus.scss` | EP 几何/视觉唯一出口；全部 `var()` |
+| `reset.scss` / `index.scss` | 基础与壳变量 |
+| `theme.scss` / `sidebar.scss` | 侧栏/导航 |
 
-> 关系一句话：`design-tokens.scss` 是数据层，模版样式文件是执行层；不存在第三个“重写层”文件。
+禁止另建独立「重写层」文件。
 
 ---
 
@@ -32,7 +26,7 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 
 - 用户提到内置预设之一：`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 原型 / 规范文档，用户要求落到项目
+- 上游设计产出（令牌 / HTML 原型 / 规范文档 / 交接块）要求落到项目
 
 ### 1.2 识别表（内置预设 · 非封闭集）
 
@@ -79,6 +73,18 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 
 ## 二、强制适配工作流（按序执行，缺一不可）
 
+### Step 0 上游设计产出落地（优先于 Step 1）
+
+**触发**：会话存在设计交接块 / `【主题色系】` / 令牌 CSS（`:root` + `--primary-*` 等）产出。
+
+**动作**：
+
+1. 读 `references/design-handoff.md`。
+2. 从会话/附件收集交接块与令牌 CSS，按 handoff 覆盖清单落地。
+3. 比对项目 `design-tokens.scss` / `platform-config.json` 与产出主色；不一致则先落地。
+4. 识别回执：`规范来源` = 上游产出 / 交接块；`目标规范` = `custom:<上游主题名>`。
+5. 模版仍为出厂 `Theme: light` + `#409EFF` 且本轮要改依赖主题的页面时，同轮先完成样式覆盖清单。
+
 ### Step 1 探查现状（含命名锁定与模版版本判定）
 
 1. 读业务项目 `src/styles/index.scss` 的 `@use` 列表与 `src/styles/` 目录。
@@ -96,9 +102,8 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 
 ### Step 2 修改/写入令牌层 `src/styles/design-tokens.scss`
 
-> **新模版（vue3-web-temp ≥ 已内置令牌文件）**：`design-tokens.scss` **已存在** → **只修改令牌值**（四段结构保持不动），**禁止**整文件覆盖重写或从空项目「生成」一份新的。适配流程 = **改数据 + 改执行层**，不是「新建令牌文件」。
->
-> **旧项目/无该文件**：才允许按下方结构**新建**唯一一份 `design-tokens.scss`。
+> **当前项目已有** `design-tokens.scss` → 只改令牌值（四段结构不动），不整文件覆盖、不另建一份。适配 = 改数据 + 改执行层。  
+> **当前项目没有该文件** → 按下方结构新建唯一一份。
 
 结构固定为四段：用户可自定义 → 规范语义别名 → 模版桥接令牌 → Element Plus 映射。
 
@@ -380,10 +385,11 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 
    | 位置 | 项目 | 规范落地动作 |
    |---|---|---|
-   | `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`（已变量化，由桥接令牌 `--ds-dialog-bg` 接管）；改后回归验证列表页 `calc(100vh - ...)` |
-   | `platform-config.json` | 顶栏高度 | `HeaderHeight` 与规范一致（如 AntD Pro 56） |
-   | `sidebar.scss` | 侧栏几何 | 宽度走 `--sidebar-width` / `--sidebar-collapsed-width`；菜单项高度走 `--el-menu-item-height`（**禁止**用 `--vts-bar-height`）；Logo 区 scroll 高度随 `--header-height` + `--sidebar-collapse-bar-height` 重算 |
+   | `theme.scss` | 侧栏配色 | 将 `--vts-theme-*` 桥接到 upstream 派生的 `--sidebar-*`；`Theme` 取交接块 `data-theme` |
+   | `index.scss` | 壳变量 | `--vts-theme-menu-active-bg`、`--vts-sidebar-border-color` 桥接；`--vts-bar-height` 等照旧 |
+   | `sidebar.scss` | 侧栏执行 | 背景用 `background: var(--vts-theme-menu-bg)`（支持渐变）；激活块 `--vts-theme-menu-active-bg`；边框 `--vts-sidebar-border-color` |
+   | `dark.scss` | 暗黑侧栏 | **禁止** `sidebar-container { background-color: var(--el-bg-color) }` 压盖渐变；改用 `background: var(--vts-theme-menu-bg)` |
+   | `platform-config.json` | 顶栏/主题 | `EpThemeColor` = 规范 primary-5；深色侧栏时 `Theme: default`（或对应 data-theme） |
    | `layout/components/lay-tag` | 页签栏高度 | 走 `--vts-tabs-height`（桥接 `--tabs-height`） |
    | `layout/components/lay-navbar` 等 | 顶栏内容区 | 行高/高度跟随 `--vts-bar-height`，禁止残留 `h-38` 等旧模版裸值 |
 
@@ -409,10 +415,11 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 - [ ] 控件高度：input/button 计算高度 = 规范值（24/32/40 或规范预设）
 - [ ] 圆角：input、button、card、dialog 均为规范圆角
 - [ ] 表格：表头底色/文字色/字重符合规范
-- [ ] 卡片内边距：`.el-card__body` = 规范值（AntD 24px），不再是 5px
+- [ ] 卡片内边距：`.el-card__body` = 规范 `--vts-card-padding`（桥接 `--card-padding`）
+- [ ] 定高列表页：`el-card.vts-page-card` + `useTableSearch` 的 `tableHeight`；换 `--card-padding` 后列表仍无外层滚动条、分页完整、仅表格体内滚动
 - [ ] 表单标签：computed font-weight 为规范值（AntD/Semi = 400，非 700）
 - [ ] 弹窗：`--ds-dialog-bg` 为 **主题色轻渐变**（`primary-bg → component-bg`），非写死蓝渐变；`ElMessageBox` 内容区用 `--message-box-content-padding`（比 `el-dialog` body 更紧凑）
-- [ ] 暗黑模式下无白底黑字残留（切换 `html.dark` 验证）
+- [ ] 侧栏：深色主题下 DevTools 检查 `.sidebar-container` computed `background` 为 **渐变**（非单色 `#001529`）；激活项块色 = `--primary-6`；Logo 区 = `--sidebar-logo-bg`
 - [ ] 第四节冲突清单全部处理完毕（逐条回填）
 - [ ] Step 7 存量扫描已执行且结果已输出
 
@@ -431,7 +438,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 ## 四、模版自带硬编码冲突清单
 
-> 来源：模版 `vue3-web-temp` 的 `src/styles/`。新模版已将下列项**变量化**（`var(--x, 默认值)`），适配时由 Step 2 桥接令牌自动接管（4.A）；旧模版生成的项目需逐条手工处理（4.B）。
+> 来源：当前项目 `src/styles/`。已变量化（`var(--x, 默认值)`）的项走 4.A（桥接令牌接管）；仍为裸硬编码的走 4.B（逐条改）。
 
 | # | 文件 | 硬编码内容 | 与规范的冲突 | 新模版状态 | 旧项目处理 |
 |---|------|-----------|-------------|-----------|-----------|
@@ -446,7 +453,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | 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` / `dark.scss` | 旧默认 `--vts-dialog-bg: linear-gradient(#e5f3fe, #fefefe)`（写死蓝） | 弹窗背景应**跟随主题主色** | 已变量化：`--ds-dialog-bg: linear-gradient(var(--primary-bg), var(--component-bg))`；上游有 `--primary-bg` 则直接映射 | 旧项目改 `design-tokens` 的 `--ds-dialog-bg`，勿再写死 hex 渐变 |
-| 12 | `theme.scss` | 8 套侧栏配色（激活条 `#4091f7` 等） | 激活指示条非规范主色 | 主题库保留 | 追加规范匹配的 `html[data-theme]` 块覆盖 `--vts-theme-menu-active-before` |
+| 12 | `theme.scss` | 8 套侧栏 `--vts-theme-*` 出厂单色 | 上游设计产出落地时需桥接 `--sidebar-*` | 模版保持出厂单色 | 按 `design-handoff.md` 动态写入 |
 | 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 等） | 仅演示用，影响小 | 不处理 | 业务禁止使用这些类名 |
@@ -491,17 +498,15 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 ---
 
-## 七、与上游设计技能的衔接协议（通用 · 不绑定具体技能名）
-
-> 上游可能是 `project-style-design`，也可能是任何同类 UI/UX 设计技能，甚至是用户手工整理的规范文档。**只认产出物，不认技能名**：无论哪个技能，只要产出了令牌/原型/规范文档，都按本协议解析。
+## 七、与上游设计产出的衔接协议
 
-### 7.1 产出物识别（先找到要解析什么）
+细则见 `design-handoff.md`。
 
-按以下线索定位上游产出物：
+### 7.1 产出物识别
 
-1. **会话上下文**：当前/前序对话中调用过的设计类技能及其产出（单文件 HTML 原型、令牌表、规范 md）。
-2. **用户提供的文件/路径**：含 `:root { --... }` 的 HTML/CSS、设计令牌 JSON/YAML、规范文档。
-3. **特征检测**：产出物中含 `--brand-*` / `--primary` / `colorPrimary` / design token 表 / 组件视觉稿 → 即可作为衔接输入。
+1. 会话中的设计交接块 / 令牌表 / HTML 原型
+2. 用户提供的含 `:root { --... }` 的文件或规范文档
+3. 特征：`--brand-*` / `--primary` / `colorPrimary` / design token 表
 
 ### 7.2 令牌归一化（上游命名 ≠ 本模块标准名）
 
@@ -523,7 +528,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 ### 7.3 落项目流程
 
-当用户要求「把上游设计技能的稿子/令牌落到项目」：
+当用户要求「把上游设计产出落到项目」：
 
 1. 先输出识别回执（规范 = 稿子所用系统；不在预设内则标 `custom`，按 1.3）。
 2. 按 7.2 / 7.5.2 归一化后，**修改**项目已有 `design-tokens.scss` 对应字段（有上游则覆盖，无则保留模版默认）。
@@ -537,14 +542,14 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 - 本模块与上游技能**解耦**：上游技能更名/替换不影响本协议，只需重新定位产出物。
 - 禁止在本文档或生成代码中硬编码上游技能名作为流程前提；提及仅作举例。
 - 上游只给视觉稿没给令牌时，从稿子的 computed 样式/标注反推令牌，并在回执中注明"反推"项。
-- **默认值归属**：布局壳层的默认像素/色值由 **Vue 模版项目** `src/styles/design-tokens.scss` 定义；本 Skill **不得**自造一套「规范默认表」写进文档或代码。
+- **默认值归属**：壳层默认像素/色值以当前项目 `src/styles/design-tokens.scss` 为准；本 Skill 不另造默认表。
 
 ### 7.5 壳层执行清单（模版接线 · 值随上游动态覆盖）
 
 > **职责边界**  
-> - **Vue 模版**（`vue3-web-temp`）：在 `design-tokens.scss` 提供壳层令牌**字段与默认值**；`sidebar.scss` / `layout/**` / `index.scss` 用 `var(--token)` **接线**。  
-> - **本 Skill**：不写死任何上游设计技能的像素/色值；流程 = **读上游产出（7.1）→ 归一化（7.2 / 7.5.2）→ 修改项目已有 `design-tokens.scss` 对应字段 → grep 执行层确认仍引用令牌**。  
-> - **无上游产出**：保留模版默认值，或仅按用户口述 / 内置预设改令牌；禁止 Skill 文档里另写默认表替代模版。
+> - **当前业务项目**：`design-tokens.scss` 提供壳层令牌字段与默认值；`sidebar.scss` / `layout/**` / `index.scss` 用 `var(--token)` 接线。  
+> - **本 Skill**：读产出 → 归一化（7.2 / 7.5.2）→ 改项目已有令牌字段 → grep 执行层仍引用令牌。  
+> - **无上游产出**：保留项目默认值，或按用户口述 / 内置预设改令牌。
 
 #### 7.5.1 壳层令牌接线表（结构固定 · 值读模版或上游）
 
@@ -590,6 +595,8 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | `--sidebar-collapsed-width` | 侧栏收起宽度 / collapsedWidth |
 | `--el-menu-item-height` | 菜单项行高 / menuItemHeight / navItemHeight |
 | `--sidebar-collapse-bar-height` | 侧栏折叠条高度 / collapseTriggerHeight |
+| `--primary-0`~`--primary-9` | 会话令牌 CSS 块 / primaryScale / 10 级主色 |
+| `--sidebar-bg` / `--sidebar-menu-active-bg` | 侧栏渐变底 / menuActiveBg / siderBackground |
 
 #### 7.5.3 壳层令牌变更后的连锁巡检（按令牌名，不写死像素）
 
@@ -599,8 +606,10 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 2. `index.scss`：桥接 `--vts-bar-height` / `--vts-tabs-height` / `--vts-layout-header-offset*` 仍指向源令牌  
 3. `SidebarLogo.vue`、`lay-navbar`：高度/行高仍 `var(--vts-bar-height)` 或等价引用  
 4. `sidebar.scss`：`calc(100% - var(--header-height) - var(--sidebar-collapse-bar-height))`，禁止写死 px 组合  
-5. `lay-content/index.vue`：`padding-top: var(--vts-layout-header-offset)`，禁止写死旧顶栏组合  
-6. DevTools：顶栏 computed = **当前** `--header-height`；菜单项 = **当前** `--el-menu-item-height`（两者须不同）
+5. `lay-content/index.vue`：`padding-top` 用 `--vts-layout-header-offset*`，禁止写死旧顶栏组合；**禁止**与 `$storage.configure.headerHeight` 双向联动  
+6. `lay-header`：布局/标签页变化须 `nextTick` 重测，且仅在高度变化时写回 `$storage.configure.headerHeight`  
+7. DevTools：顶栏 computed = **当前** `--header-height`；菜单项 = **当前** `--el-menu-item-height`（两者须不同）
+8. 定高列表页：`--card-padding` / `--vts-card-padding` 变更后，抽查一页查询列表——内容区无外层滚动条、分页完整、`tableHeight` 随 padding 变化
 
 #### 7.5.4 EP 菜单变量纪律
 
@@ -618,23 +627,24 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 - [ ] 执行层 grep 无壳层裸 px 残留（EP 菜单根上的具体 px 须与 `--el-menu-item-height` 一致）  
 - [ ] 查询区 input 与 button 高度一致（small 档）
 
+#### 7.5.7 侧栏整主题适配（上游产出 · 强制）
+
+有上游设计产出且要求深色导航时，禁止只改 `--el-color-primary`。按 `design-handoff.md` 读取主色板并写入 `design-tokens` / `theme.scss` 桥接 / `platform-config.json`；`data-theme` 以交接块为准。
+
 ---
 
-## 八、常见反例（含实战事故）
-
-- 只把 `--el-color-primary` 改成规范主色就宣称"已适配 Ant Design"（字号/圆角/高度/内边距全未动）。
-- **识别漂移风险**：用户口述的规范与真正写入令牌层的规范不一致（如说要 AntD 却写了 `#0077fa`、`--semi-*` 别名的 Semi 令牌）——回执块与三点一致性校验就是防这个。
-- **命名漂移/重复建层**：适配文件建成 `tokens.scss`，或另起 `semi-controls.scss` 之类的几何重写层与 `element-plus.scss` 并存——新增文件只允许 `design-tokens.scss`，几何重写一律并入 `element-plus.scss`。
-- **冲突清单假完成**：声称「已全部处理」，实际 `reset.scss` 的 body 字体（不带 !important 的那条）与 `label { font-weight: 700 }` 原封未动——grep 时漏掉了不带 !important 的关键词。
-- **靠加载顺序压盖**：几何重写独立成文件、指望 `@use` 顺序盖过模版覆盖层，顺序一错样式静默失效——已改为并入 `element-plus.scss`，从根上消除顺序问题。
-- 弹窗仍是**写死蓝渐变**或纯白底（未设 `--ds-dialog-bg` / `--primary-bg` 主题渐变链）。
-- 把 `ElMessageBox` 与 `el-dialog` 共用 `--dialog-body-padding`（24px）导致确认框空白过大——须用 `--message-box-content-padding`（16px 24px）。
-- 改了 `platform-config.json` 主色但没提醒清 localStorage → 老访客看到的还是旧色。
-- 业务页面里又写 `.el-input { height: 36px }` 之类的裸值覆盖 → 换规范时需要逐页改，违反规则 1~2。
-- 换规范时连业务组件样式一起改（说明令牌层抽象失败）。
-- 暗黑模式不适配新令牌，切 dark 后表头/行变更色刺眼。
-- **固化上游技能名**：流程里写死某设计技能名或把其规范表抄进 Skill 文档——正确做法是 7.1 只认产出物、7.5 只认模版接线表。
-- **Skill 自造默认值**：在 Skill 文档或适配回复里写「顶栏 64px / 侧栏 208px」等默认表，替代 read 模版 `design-tokens.scss`——默认值只能来自模版文件或上游产出。
-- **预设硬套**：把不在五大预设内的规范强行归入最接近的预设，或假设上游令牌名与本模块标准名一致而不做归一化映射。
-- **只写令牌层、不执行壳层（最常见结合事故）**：改了 `--header-height` 等壳层令牌，但 `sidebar.scss` / `layout/` 仍用旧裸值或**误把 `--vts-bar-height` 套到菜单项** → 侧栏行高暴涨、折叠错位。见 **7.5 壳层执行清单**。
-- **EP 菜单变量自引用**：`.el-menu { --el-menu-item-height: var(--el-menu-item-height, 40px) }` → 无效值，EP 回退默认 56px。须在 `.sidebar-container .el-menu` 写与 `--el-menu-item-height` 一致的具体值。
+## 八、反例（短）
+
+| 错误 | 正确 |
+|------|------|
+| 只改 `--el-color-primary` | 令牌层 + 几何 + 冲突清单全做 |
+| 回执规范 ≠ 令牌/config/侧栏 | 三处同名同色 |
+| 新建 `tokens.scss` 或独立重写层 | 仅 `design-tokens.scss`；几何并入 `element-plus.scss` |
+| 冲突清单漏改 `reset.scss` body 字体 / `label { font-weight: 700 }` | 第四节逐条 grep（含无 `!important` 行） |
+| 弹窗写死蓝渐变 | `--ds-dialog-bg` / `--primary-bg` |
+| MessageBox 与 Dialog 共用同一 padding 令牌 | MessageBox 用 `--message-box-content-padding` |
+| 改 `EpThemeColor` 未提醒清 localStorage | Step 6 提醒 |
+| 业务页裸写控件高度 | 只引令牌 |
+| 只写令牌不改壳层执行层 | 执行 7.5 |
+| EP 菜单变量自引用 | 写与 `--el-menu-item-height` 一致的具体值 |
+| Skill 文档写死顶栏/侧栏默认 px | 读模版 `design-tokens.scss` 或上游产出 |

package/references/detail-page.md

@@ -1,100 +1,83 @@
-# 详情页开发
+---
+skill: detail-page
+description: 列表→独立路由详情/编辑/查看。路由 meta、toDetail 写顶部 tag、activePath 保侧栏高亮、initToDetail。
+scope: project
+tags: [vue3, detail, toDetail, useDetail, activePath, showLink, multiTags, keepAlive]
+---
 
-> 按本文件示例编写，复用 `useDetail` 等已有详情跳转约定，勿另起一套传参/回显方式。
+# 详情页 / 编辑页跳转
 
-## useDetail Hook
+真相源：模版 `useDetail.ts`、`multiTags`、侧栏 `NavVertical`。列表打开独立路由页时按本文件落地。
 
-用于列表→详情/新增/编辑页的跳转和参数传递。
+## 概念
 
-```typescript
-import { useDetail } from '@/hooks/useDetail'
+| 能力 | 字段 / API |
+|------|------------|
+| 不进左侧菜单 | 路由 `meta.showLink: false` |
+| 顶部 tag（multiTags） | `useDetail().toDetail` → `handleTags('push')` |
+| 侧栏高亮 | 路由 `meta.activePath` = 列表 path |
+| 页面缓存 | `meta.keepAlive`；多开 tag 再加 `moreTags: true` |
 
-const { toDetail, initToDetail, getParameter } = useDetail()
-```
+`showLink` 只管侧栏是否显示，不控制顶部 tag。详情不在菜单里 → 必须用 `toDetail` 写 tag；裸 `router.push` 只换路由。
 
-## 跳转
+## 路由（与列表兄弟）
 
 ```typescript
-// 从列表跳详情/编辑/新增
-toDetail('QueryDetail', { id: row.id, mark: 'view', text: row.name })
-toDetail('QueryDetail', { id: row.id, mark: 'edit', text: row.name })
-toDetail('QueryDetail', { mark: 'create', text: '新增数据' })
+{
+  path: "/customer/detail",
+  name: "CustomerDetail",
+  component: () => import("@/views/customer/detail/index.vue"),
+  meta: {
+    title: "客户详情",
+    showLink: false,
+    activePath: "/customer/list",
+    // keepAlive: true,
+    // moreTags: true,
+  },
+},
 ```
 
-### 参数说明
-
-| 参数 | 说明 |
+| 字段 | 要求 |
 |------|------|
-| `routeName` | 目标路由 `name`（必须与路由配置一致） |
-| `params.id` | 数据唯一标识 |
-| `params.mark` | 状态标识：`edit` / `view` / `create` 或自定义 |
-| `params.text` | 用于拼接标签页标题的文本 |
+| `title` | 非空 |
+| `showLink: false` | 必填 |
+| `activePath` | = 列表 path |
+| `name` | = `defineOptions({ name })` |
 
-> 数字类型参数跳转前需 `toString()`，因为 `vue-router` 解析后全为字符串。
+## 列表打开
 
-## 详情页初始化
-
-```vue
-<script setup lang="ts">
-import { useDetail } from '@/hooks/useDetail'
-
-defineOptions({ name: 'QueryDetail' }) // 必须与路由 name 一致
-
-const { initToDetail, getParameter } = useDetail()
-initToDetail('QueryDetail')
+```typescript
+import { useDetail } from "@/hooks/useDetail";
+const { toDetail } = useDetail();
 
-// 获取参数
-const { id, mark, text } = getParameter.value
-</script>
+toDetail("CustomerDetail", { webId: "0" }, "(新增)");
+toDetail("CustomerDetail", { id: row.id, text: row.name, mark: "edit" }, `(编辑)【${row.name}】`);
 ```
 
-### 标签页标题自动生成
-
-`initToDetail` 会根据参数自动生成多标签页标题：
-
-| 条件 | 标题 |
-|------|------|
-| 无 `id` | `新增` |
-| `mark === 'edit'` | `编辑【xxx】` |
-| `mark === 'view'` | `查看【xxx】` |
-
-## 数据回显
-
 ```typescript
-async function getDetail() {
-  const { id } = getParameter.value
-  if (!id) return
-  const res = await getDetailApi({ id })
-  Object.assign(formData, res.data)
-}
-
-onMounted(() => {
-  getDetail()
-})
+toDetail(name, parameter, title?, model = "query") // model: "query" | "params"
 ```
 
-## 非多标签页场景
+写入 tag 时不要把路由上的 `showLink: false` 原样塞进 `handleTags` 的 meta。
 
-普通详情页直接使用 `getParameter` 获取路由参数：
+## 详情页
 
 ```vue
 <script setup lang="ts">
-import { useDetail } from '@/hooks/useDetail'
-
-const { getParameter } = useDetail()
-const route = useRoute()
-const id = route.query.id
+import { useDetail } from "@/hooks/useDetail";
+defineOptions({ name: "CustomerDetail" });
+const { initToDetail, getParameter } = useDetail();
+initToDetail("CustomerDetail");
+const { id, mark } = getParameter as DetailParameter;
 </script>
 ```
 
-## 关键约定
-
-1. 详情页组件 `name` 必须与路由 `name` 一致，否则标签页标题功能异常。
-2. 通过 `getParameter` 获取 `query` 或 `params` 参数，不要直接用 `useRoute()`。
-3. 表单详情页回显：进入页面后调详情接口，用 `Object.assign(formData, data)` 赋值。
-4. `mark` 字段控制页面编辑态：`view` 禁用表单，`edit` 可编辑，`create` 新增。
-5. 选择类组件回填需同时维护 code 与 name（详见 data-writeback 模块）。
+`initToDetail` 标题：无 id → `(新增)`；`mark===edit'` → `(编辑)【text】`；`view` → `(查看)【text】`。
 
-## 关联文件
+## Must-do
 
-- [src/hooks/useDetail.ts](file:///e:/work/vue3-web-temp/src/hooks/useDetail.ts)
+1. 兄弟路由 + `showLink: false` + `activePath` + 非空 `title`
+2. 列表只用 `toDetail`，禁止裸 `router.push`
+3. 详情页必调 `initToDetail`；`name` 对齐
+4. 参数用 `getParameter`
+5. 需缓存 / 多开时配 `keepAlive` / `moreTags`

package/references/form-advanced.md

@@ -202,8 +202,7 @@ function parseAddress(text: string) {
 
 ## ReDialog 通用弹窗（必用）
 
-> 落点：`src/components/ReDialog`。基于 `el-dialog` 封装：居中、可拖拽、`destroy-on-close`、默认禁止点遮罩关闭、可选全屏切换、内容区 `el-scrollbar`。  
-> 写法以**本模块下方黄金样板**为准（技能自包含，勿依赖仓库 views 演示页）。
+> 落点：`src/components/ReDialog`。基于 `el-dialog`：居中、可拖拽、`destroy-on-close`、默认禁点遮罩关闭、可选全屏、内容区 `el-scrollbar`。写法见下方样板。
 
 ### Props / 插槽