@qilitt-mickey/vue3-temp-skill 1.1.24 → 1.1.26

package/references/design-system.md

@@ -1,718 +1,120 @@
----
-skill: design-system
-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（不换组件，只换令牌数据）。
-
-### 双轨原则（出厂默认 vs 设计落地）
-
-| 轨 | 含义 | Agent 行为 |
-|----|------|------------|
-| **出厂** | `design-tokens.scss` / `platform-config.json` 已有默认（如壳 64/208/40、主色 `#409EFF`、`ShowModel: chrome`、`--layout-content-padding: 8`） | **勿擅自改掉**以贴合设计；系统未调用设计技能时保持出厂 |
-| **设计落地** | 会话/仓库存在 `design-handoff/v1` 或用户要求按设计规范适配 | **必须**按设计规范与 JSON **全量回填**令牌；设计未提及的字段保留出厂；壳层/ReDialog/EP 几何须已是 `var(--token)`，改令牌即生效 |
-
-视觉关键尺寸（顶栏/侧栏/页签/内容边距/控件高/弹窗/卡片页签等）在模版中**一律为 CSS 变量**；文档里的 64/208 等是默认值说明，不是允许写死在组件里的常量。
-
-| 文件 | 职责 |
-|------|------|
-| `design-tokens.scss`（**唯一新增**） | 纯 `:root` 数据：主色/字体/圆角/高度 + 桥接 + `--el-*`；禁止选择器 |
-| `element-plus.scss` | EP 几何/视觉唯一出口；全部 `var()` |
-| `reset.scss` / `index.scss` | 基础与壳变量桥接 |
-| `theme.scss` / `sidebar.scss` | 侧栏/导航 |
-
-禁止另建独立「重写层」文件。
-
----
-
-## 一、触发与规范识别
-
-### 1.1 触发场景
-
-- 用户提到内置预设之一：`Ant Design` / `antd` / 蚂蚁、`Semi Design` / 字节 Semi、`Arco Design`、`Vuetify` / Material、`FindDesign` / 京东 UDC / jdd-design；或提到**任意其他设计系统 / 自定义规范**（预设非封闭集，见 1.4）
-- 用户说「按 XX 规范适配」「套设计规范」「UI 统一成 XX 风格」「重写组件样式以符合规范」
-- 上游设计产出（令牌 / 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 0 上游设计产出落地（优先于 Step 1）
-
-**触发**：会话 / 仓库存在 **`design-handoff/v1` JSON**，或设计交接块 / `【主题色系】` / 令牌 CSS（`:root` + `--primary-*`）。
-
-**动作**：
-
-1. 读 `references/design-handoff.md`。
-2. **优先**收集 `design-handoff/v1` JSON；无 JSON 再收集交接块与令牌 CSS。按 handoff 映射表与**全量令牌核对表（A～E）**落地，设计未给出的项回执标明「保留出厂」。
-3. 比对项目 `design-tokens.scss` / `platform-config.json` 与产出主色；不一致则先落地。
-4. 识别回执：`规范来源` = design-handoff/v1 | 交接块 | 混合；`目标规范` = `custom:<上游主题名>`。
-5. 模版仍为出厂 `Theme: light` + `#409EFF` 且本轮要改依赖主题的页面时，同轮先完成样式覆盖清单。
-
-### Step 1 探查现状（含命名锁定与模版版本判定）
-
-1. 读业务项目 `src/styles/index.scss` 的 `@use` 列表与 `src/styles/` 目录。
-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
-   - 出现 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`
-
-> **当前项目已有** `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;
-  /* 设计规范别名（--component-size-* ↔ EP size API，见 7.5.8） */
-  --component-size-sm: var(--control-height-sm);
-  --component-size-base: var(--control-height);
-  --component-size-lg: var(--control-height-lg);
-  --control-padding-x: 12px;
-  --card-padding: 24px;
-  --layout-bg: #f5f5f5;
-  --sidebar-width: 208px;
-  --header-height: 64px; /* 模版出厂与设计壳层一致；antd Pro 文档若写 56，以当前设计 handoff / 设计技能为准覆盖 */
-  --tabs-height: 40px;
-  --layout-content-padding: 8px; /* 出厂；设计落地常 24 → 同步 --vts-margin */
-  /* ===== 用户可自定义 ===== */
-
-  /* —— 规范语义别名（--vts-* 业务语义层，映射规范令牌） —— */
-  --vts-color-success: #52c41a;
-  --vts-color-warning: #faad14;
-  --vts-color-danger: #f5222d; /* 与 --error-color / 设计 #F5222D 一致；勿用 #ff4d4f 或 EP #F56C6C */
-  --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);
-  --ds-dialog-bg: linear-gradient(to bottom, var(--primary-bg), var(--component-bg)); /* 主题色轻渐变；index 桥接 --vts-dialog-bg；fallback 可为 overlay 但令牌本身必须是渐变 */
-
-  /* —— 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 预设**。其他规范按第五节令牌速查表替换「用户可自定义」区块与语义色。
->
-> ⚠️ `design-tokens.scss` **只允许 `:root` 变量块**：业务组件类（如 `.vts-status`、`.vts-op`）不得写入本文件，应放 `element-plus.scss` 或业务组件内。
-
-### Step 3 组件几何重写并入 `src/styles/element-plus.scss`（不另建重写层文件）
-
-几何规格（高度 / 内边距 / 字号 / 圆角）**直接追加/修改在模版既有的 `element-plus.scss` 内**，三条纪律：
-
-1. 全部引用令牌，**禁止裸值**（`var(--x, 回退)` 的回退值除外）。
-2. 每段追加规范注释：`/* —— <规范名> 几何：<组件> —— */`，让后续开发者一眼看出取值来源。
-3. 模版里同一选择器已有裸值规则（如 `.el-card__body { padding: 5px }`）→ **就地改为令牌引用**，禁止另起一条规则去压盖，避免“同属性两处定义”。
-
-标准样板（按需追加/修改，只改数据值，结构不变）：
-
-```scss
-/**
- * <规范名> → Element Plus 几何规格（追加在 element-plus.scss 内）
- * 全部引用 design-tokens.scss 令牌；业务页禁止再写裸高度/内边距。
- */
-
-/* —— 按钮 —— */
-.el-button {
-  height: var(--control-height);
-  padding: 0 var(--button-padding-x, 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(--dialog-border-radius, var(--radius-lg)); }
-/* ReDialog 消费头/底高度与 body 内边距令牌；MessageBox 用更紧凑的 message-box-* */
-.el-message-box__header { padding: var(--message-box-header-padding); margin-right: 0; }
-.el-dialog__title, .el-message-box__title { font-size: var(--font-size-lg); font-weight: var(--font-weight-semibold); }
-.el-message-box__content { padding: var(--message-box-content-padding); font-size: var(--font-size-base); line-height: var(--line-height); }
-.el-message-box__btns { padding: var(--message-box-footer-padding); }
-.el-drawer__header { padding: var(--spacing-md) var(--spacing-lg); margin-bottom: 0; font-size: var(--font-size-lg); }
-.el-drawer__body { padding: var(--spacing-md) var(--spacing-lg); }
-
-/* —— 下拉 / 弹出选项 —— */
-.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: var(--tabs-item-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 3.5 设计模式页面结构（设计 Skill 产出存在时触发）
-
-> **职责边界**：项目 Skill 只做令牌数值桥接（Step 2）和 EP 几何重写（Step 3）。页面布局结构和视觉表现**不在全局 CSS 文件中注入**，而是在**页面代码中直接实现**，遵循设计 Skill 的布局规范。
-
-触发条件：存在 `design-handoff/v1` JSON、用户指定设计规范、或命中 `design-system` 模块且设计 Skill 产出可用。
-
-模版已出厂自带 `design-visual.scss`（视觉基线）和 `design-layout.scss`（构图基线），提供默认的 CSS 钩子类。设计模式下：
-
-1. **令牌值桥接**（Step 2 已完成）：颜色 / 阴影 / 圆角 / 间距 / 字号数值写入 `design-tokens.scss`
-2. **页面结构按设计 Skill 布局规范生成**：
-   - 列表页 → 读设计 Skill 的 `list-page.md` 区域拆分，在页面代码中使用 `.vts-page-header` / `.vts-filter-area` / `.vts-action-bar` / `.vts-table-area` 结构类
-   - 详情页 → 读设计 Skill 的详情页规范，使用 `.vts-detail-container`
-   - 框架壳层 → 读设计 Skill 的 `unified-framework.md`，顶栏 / 侧栏 / 页签 / 内容区的几何和视觉按规范实现
-3. **组件视觉表现**：`design-visual.scss` 提供全局基线（hover/阴影/过渡），页面内无需重复写
-4. **设计 Skill 布局决策的直接实现**：如设计 Skill 规定顶部导航语言切换为内联文字（中/EN）而非下拉框，则在 `lay-navbar` 组件中直接实现该交互，不通过 CSS 覆盖
-
-**关键原则**：设计 Skill 的布局和视觉决策在**页面代码**中实现，不通过全局 CSS 文件注入。项目 Skill 的职责是提供令牌数值和 CSS 钩子类，让页面代码有标准化的引用点。
-
-### Step 4 接线 `src/styles/index.scss`
-
+---
+skill: design-system
+description: 项目设计系统静态说明。描述令牌体系、主题系统、暗色模式、布局框架、EP 定制规则、加载顺序和禁止清单，供 AI 查阅。落地流程见 design-handoff.md。
+scope: project
+tags: [design-system, design-tokens, element-plus, theme, css-variables, dark-mode]
+---
+
+# 项目设计系统说明
+
+项目基于 Element Plus，通过 CSS 变量令牌体系驱动视觉。不换组件库，只换令牌数据。组件层始终是 EP，样式层由令牌控制。
+
+## 双轨原则
+
+| 轨 | 含义 | Agent 行为 |
+|----|------|------------|
+| **出厂** | `design-tokens.scss` / `platform-config.json` 已有默认值（壳 64/208/40、主色 `#409EFF`、`ShowModel: chrome`、`--layout-content-padding: 8`） | 勿擅自改掉以贴合设计；未调用设计技能时保持出厂 |
+| **设计落地** | 会话存在 `design-handoff/v1` JSON 或用户要求按设计规范适配 | 必须按 JSON 全量回填令牌；设计未提及的字段保留出厂 |
+
+视觉关键尺寸（顶栏/侧栏/页签/内容边距/控件高/弹窗等）在模版中一律为 CSS 变量；文档里的 64/208 等是默认值说明，不是允许写死在组件里的常量。
+
+## 文件职责
+
+| 文件 | 职责 |
+|------|------|
+| `design-tokens.scss`（唯一新增） | 纯 `:root` 数据：主色/字体/圆角/高度 + 桥接 + `--el-*`；禁止选择器 |
+| `element-plus.scss` | EP 几何/视觉唯一出口：控件尺寸 + shadow / hover / transition / 交互态；全部 `var()` |
+| `reset.scss` / `index.scss` | 基础与壳变量桥接 |
+| `theme.scss` / `sidebar.scss` | 侧栏/导航 |
+| `dark.scss` | 暗色覆盖 |
+
+禁止另建独立「重写层」文件。
+
+## 令牌体系（design-tokens.scss 四段结构）
+
+```
+:root {
+  /* ① 用户可自定义 */ — 主色/字体/圆角/控件高度/间距/布局尺寸
+  /* ② 规范语义别名（--vts-*） */ — 业务语义层，映射规范令牌（success/warning/danger/info/表头/行变更色等）
+  /* ③ 模版桥接令牌 */ — 给模版 var(--x, 默认值) 提供适配值（--vts-card-padding / --ds-form-label-weight 等）
+  /* ④ Element Plus 映射 */ — --el-color-primary / --el-font-size-base / --el-border-radius-base 等
+}
+```
+
+- 换规范 = 只改「①用户可自定义」区块 + 「②语义别名」；「③桥接」结构不变，「④EP 映射」自动跟随。
+- `design-tokens.scss` 只允许 `:root` 变量块；业务组件类不得写入本文件。
+
+## 主题系统
+
+- `public/platform-config.json` 的 `EpThemeColor` 是运行时初始主色来源（`useApp.ts` 读取并 `setEpThemeColor()`）。
+- `Theme` 字段控制侧栏风格：`default`（深色 `#001529`）/ `light`（浅色）/ `dark-gradient` 等。
+- 主色运行时切换走 `setEpThemeColor()`（保证 chroma 色阶同步），令牌层只负责初始值。
+- **localStorage 缓存陷阱**：`epThemeColor` 优先读 `localStorage` 的 `responsive-layout`；改完 `platform-config.json` 后老访客不会自动生效，需清缓存或提升 `Version` 触发重置。
+
+## 暗色模式
+
+- `dark.scss` 内为令牌补暗色覆盖：`--vts-table-header-bg`、`--vts-message-bg`、`--vts-dialog-bg` 等。
+- 暗色侧栏禁止 `sidebar-container { background-color: var(--el-bg-color) }` 压盖渐变；改用 `background: var(--vts-theme-menu-bg)`。
+
+## 布局框架令牌
+
+壳层令牌命名纪律（违反即 bug）：
+
+| 令牌 | 只允许用于 | 禁止用于 |
+|---|---|---|
+| `--vts-bar-height` / `--header-height` | 顶栏、Logo 区、水平导航、面包屑行 | 侧栏菜单项 |
+| `--el-menu-item-height` | 侧栏/垂直菜单项、子菜单 title | 顶栏、页签栏 |
+| `--vts-tabs-height` / `--tabs-height` | 多标签页签栏 | 菜单、表单控件 |
+
+壳层令牌接线关系（值来源：上游设计产出 > 用户/预设 > 模版默认）：
+
+| 模版令牌 | 执行层消费位置 |
+|---|---|
+| `--header-height` | `index.scss` → `--vts-bar-height`；`lay-navbar`；`SidebarLogo`；`sidebar.scss` |
+| `--tabs-height` | `index.scss` → `--vts-tabs-height`；`lay-tag/index.vue` |
+| `--sidebar-width` / `--sidebar-collapsed-width` | `sidebar.scss` `$sideBarWidth`、`.sidebar-container` |
+| `--layout-header-offset*` | `index.scss` → `--vts-layout-header-offset*`；`lay-content/index.vue` `padding-top` |
+| `--ds-dialog-bg` | `index.scss` → `--vts-dialog-bg`；`.el-dialog` / `.el-message-box` background |
+
+## EP 定制规则
+
+组件尺寸 size API 归一化：
+
+| 设计语义 | 设计令牌 | 模版令牌 | EP CSS 变量 | EP 组件 API | 默认像素 |
+|----------|----------|----------|-------------|-------------|---------|
+| small | `--component-size-sm` | `--control-height-sm` | `--el-component-size-small` | `size="small"` | 24px |
+| **default** | `--component-size-base` | `--control-height` | `--el-component-size` | **不写 size** | **32px** |
+| large | `--component-size-lg` | `--control-height-lg` | `--el-component-size-large` | `size="large"` | 40px |
+
+- 缺档规则：上游只给一个高度 → 写入 `--control-height`（default）；sm/lg 保留默认或按比例派生。
+- `element-plus.scss` 中无 `--small`/`--large` 修饰的按钮/输入类选择器须引用 `var(--control-height)`。
+- 查询区 `el-form` 不写 size（default 中号）；禁止全局 `el-config-provider` 强制 `size="small"`。
+- 表格行内操作可用 `size="small"`；查询区/标准表单/弹窗表单用 default。
+
+## 加载顺序（index.scss）
+
 ```scss
-@use 'design-tokens';     // 唯一新增：纯数据令牌，必须最先
-@use 'design-visual';     // 视觉表现层：shadow / hover / transition / 交互态
-@use 'design-layout';     // 页面构图层：区域容器 / 间距节奏
+@use 'design-tokens';     // 最先：纯数据令牌
 @use 'theme';
 @use 'transition';
 @use 'button';
-@use 'element-plus';      // 模版默认覆盖 + 规范几何重写（已并入）
+@use 'element-plus';      // EP 几何 + 视觉规则（shadow / hover / transition / 交互态）
 @use 'sidebar';
 @use 'dark';
 @use 'vant';
 ```
 
-唯一顺序要求：`design-tokens` 放最前（供后续文件引用）；`design-visual` 和 `design-layout` 紧随其后，在 `element-plus` 之前，确保视觉层在 EP 几何层之前加载。几何重写已并入 `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 条）。
-
-### Step 5 模版硬编码冲突处理（按模版版本二选一，逐条回填）
-
-- **4.A（新模版，已变量化）**：模版样式均为 `var(--x, 默认值)` 形式，Step 2 的「模版桥接令牌」段已自动接管。**逐条确认**桥接令牌齐全即可：`--ds-dialog-bg` 必须为 **`linear-gradient(var(--primary-bg), var(--component-bg))`**（主题色轻渐变）；`index.scss` 中 `--vts-dialog-bg: var(--ds-dialog-bg, var(--el-bg-color-overlay))` 的 overlay **仅作 fallback**，不得把令牌本身改成纯 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. 在最终回复中**逐条回填**冲突清单处理结果（格式见 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. **公共区域（侧边栏 / 导航栏 / 内容壳）同样要按规范落地**——这些不在 EP 组件范围内，靠模版壳层变量与主题文件执行：
-
-   | 位置 | 项目 | 规范落地动作 |
-   |---|---|---|
-   | `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`；设计落地写 JSON `ShowModel`（默认 `line`；`card` 时用 `--vts-tag-card-*`） |
-   | `layout/components/lay-navbar` 等 | 顶栏内容区 | 行高/高度跟随 `--vts-bar-height`，禁止残留 `h-38` 等旧模版裸值 |
-
-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 控件裸几何 → 删除，交给 `element-plus.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` = 规范 `--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 更紧凑）
-- [ ] 侧栏：深色主题下 DevTools 检查 `.sidebar-container` computed `background` 为 **`#001529`**（`var(--sidebar-bg)`，非旧版主色纵向渐变）；激活项块色 = `--primary-color` / `brandPrimary`；Logo 区 = `--sidebar-logo-bg`
-- [ ] 第四节冲突清单全部处理完毕（逐条回填）
-- [ ] Step 7 存量扫描已执行且结果已输出
-- [ ] 设计模式页面结构（设计 Skill 产出存在时）：列表页含 `.vts-page-header`（标题+描述+操作）、`.vts-filter-area`（筛选区容器）、`.vts-table-area`（表格区）
-- [ ] 视觉基线：`design-visual.scss` 和 `design-layout.scss` 在 `index.scss` 中已加载且顺序在 `element-plus` 之前
-- [ ] 暗色覆盖：视觉层和构图层在 `dark.scss` 中有对应暗色覆盖
-- [ ] 令牌无硬编码：页面代码中引用的 CSS 钩子类值全部来自令牌变量
-
----
-
-## 三、业务代码编写规则（规范生效期全程有效）
-
-1. **禁止裸值**：业务页面/组件中不得对 EP 控件写裸 `height` / `padding` / `font-size` / `border-radius`，一律引用 `--control-*` / `--font-size-*` / `--radius-*` 令牌；布局间距用 UnoCSS `p-*` / `m-*`（4px 基数）。
-2. **禁止重复重写**：组件几何只在 `element-plus.scss` 统一改（引用令牌），业务页不得再写 `.el-input__wrapper { height: ... }` 之类的覆盖。
-3. **颜色只走变量**：`--brand-*` / `--vts-*` / `--el-*`，禁止硬编码 hex（与 `layout-theme` 规则一致）。
-4. **换规范 = 只换令牌层**：切换设计系统时只重写 `design-tokens.scss`（`element-plus.scss` 几何段已令牌化，原则上无需改动），业务代码零改动；做不到的写法说明违反了规则 1~3，必须修正。
-5. 主色运行时切换仍走 `setEpThemeColor()`（保证 chroma 色阶同步），令牌层只负责初始值与非主色令牌。
-6. **命名纪律**：适配新增文件永远只有一个 `design-tokens.scss`；禁止按规范名派生文件（如 `semi-controls.scss`、`antd-tokens.scss`），禁止再新建独立的几何重写层文件。
-
----
-
-## 四、模版自带硬编码冲突清单
-
-> 来源：当前项目 `src/styles/`。已变量化（`var(--x, 默认值)`）的项走 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` 旧裸 `5px` | AntD / 令牌卡片内边距 24px | 已 `var(--vts-card-padding, var(--card-padding, 24px))` | 禁止再把 fallback 写成 5px |
-| 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` / `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 套侧栏 `--vts-theme-*` 出厂单色 | 上游设计产出落地时需桥接 `--sidebar-*` | 模版保持出厂单色 | 按 `design-handoff.md` 动态写入 |
-| 13 | `useApp.ts` | `epThemeColor` 缺省 `#409EFF` | EP 出厂蓝 ≠ 规范主色 | 不改代码 | 改 `platform-config.json` 的 `EpThemeColor`（Step 6） |
-| 14 | `index.scss` | `--vts-margin` / `--layout-content-padding` 出厂 8px | 设计 handoff 常覆盖为 24 等 | 令牌可覆盖 | 定高列表走 `%`/flex（`vts-page-card`）；禁止业务页 `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` / `#f5222d` | `#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. `element-plus.scss` 的几何段已全部令牌化，**原则上不动**；仅当两规范存在无法令牌化的结构差异时才微调（极罕见），结构不动。
-4. 更新 `platform-config.json` 的 `EpThemeColor`，并**提醒清 localStorage**（Step 6 第 2 条）。
-5. 重跑 Step 5 grep 验证、Step 7 存量扫描、Step 8 验证清单。
-6. 业务代码应当零改动；若有改动，说明存在裸值，先修裸值再切换。
-
----
-
-## 七、与上游设计产出的衔接协议
-
-细则见 `design-handoff.md`。
-
-### 7.1 产出物识别
-
-1. **`design-handoff/v1` JSON**（会话 / `design/design-handoff.json`）——**首选**
-2. 会话中的设计交接块 / 令牌表 / HTML 原型
-3. 用户提供的含 `:root { --... }` 的文件或规范文档
-4. 特征：`$schema: design-handoff/v1` / `--brand-*` / `--primary` / `colorPrimary` / design token 表
-
-有 JSON 时字段映射见 `design-handoff.md`「JSON → 模版映射」。
-
-### 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-base` / `--component-size` / `controlHeight` / 控件高度 / **default 档** |
-| `--control-height-sm` | `--component-size-sm` / 控件高度 small / **size=small** |
-| `--control-height-lg` | `--component-size-lg` / 控件高度 large / **size=large** |
-| `--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 / 7.5.2 归一化后，**修改**项目已有 `design-tokens.scss` 对应字段（有上游则覆盖，无则保留模版默认）。
-3. 按 **7.5 壳层执行清单** grep 执行层，确认仍引用令牌、无裸 px 残留。
-4. 若上游产出含组件视觉（HTML 原型/设计稿）→ 以其为基准微调 `element-plus.scss` 几何段的差异项。
-5. 上游产出里的业务配色（状态色、图表系列）按 `layout-theme` 第八节映射为 `--vts-*` 语义变量。
-6. 原型与项目出现视觉差异时：先对比两侧令牌值是否一致（含命名映射是否漏项），再查第四节冲突清单是否漏处理，最后查 Step 7 存量裸值。
-
-### 7.4 约束
-
-- 本模块与上游技能**解耦**：上游技能更名/替换不影响本协议，只需重新定位产出物。
-- 禁止在本文档或生成代码中硬编码上游技能名作为流程前提；提及仅作举例。
-- 上游只给视觉稿没给令牌时，从稿子的 computed 样式/标注反推令牌，并在回执中注明"反推"项。
-- **默认值归属**：壳层默认像素/色值以当前项目 `src/styles/design-tokens.scss` 为准；本 Skill 不另造默认表。
-
-### 7.5 壳层执行清单（模版接线 · 值随上游动态覆盖）
-
-> **职责边界**  
-> - **当前业务项目**：`design-tokens.scss` 提供壳层令牌字段与默认值；`sidebar.scss` / `layout/**` / `index.scss` 用 `var(--token)` 接线。  
-> - **本 Skill**：读产出 → 归一化（7.2 / 7.5.2）→ 改项目已有令牌字段 → grep 执行层仍引用令牌。  
-> - **无上游产出**：保留项目默认值，或按用户口述 / 内置预设改令牌。
-
-#### 7.5.1 壳层令牌接线表（结构固定 · 值读模版或上游）
-
-适配前先 **read 业务项目** `src/styles/design-tokens.scss` 的「布局壳层」段，以文件内现有字段为准；下表只描述**接线关系**，**不含默认像素**。
-
-| 模版标准令牌（`design-tokens.scss`） | 执行层消费位置（grep 确认仍用 `var()`，勿裸 px） |
-|---|---|
-| `--ds-dialog-bg` / `--primary-bg` | `design-tokens.scss` → `index.scss` `--vts-dialog-bg` → `.el-dialog` / `.el-message-box` background |
-| `--dialog-header-height` / `--dialog-footer-height` / `--dialog-body-padding` / `--dialog-border-radius` | `ReDialog`（`.el-dialog`） |
-| `--message-box-*-padding` | `element-plus.scss` MessageBox |
-| `--header-padding-x` | `index.scss` → `--vts-header-padding-x`；`lay-navbar` `padding-inline` |
-| `--header-height` | `index.scss` → `--vts-bar-height`；`lay-navbar`；`SidebarLogo`；`ReHeaderPage`；`sidebar.scss` `.horizontal-header` |
-| `--tabs-height` | `index.scss` → `--vts-tabs-height`；`layout/components/lay-tag/index.vue` |
-| `--layout-header-offset` / `--layout-header-offset-no-tabs` | `index.scss` → `--vts-layout-header-offset*`；`lay-content/index.vue` `padding-top` |
-| `--sidebar-width` / `--sidebar-collapsed-width` | `sidebar.scss` `$sideBarWidth`、`.sidebar-container`、`.hideSidebar` |
-| `--sidebar-collapse-bar-height` | `SidebarLeftCollapse.vue`；`sidebar.scss` scroll 区 `calc(100% - …)` |
-| `--el-menu-item-height` | `sidebar.scss` `.sidebar-container .el-menu` 及菜单项（**禁止**与 `--header-height` 混用） |
-
-**值来源优先级**（写入 `design-tokens.scss` 时）：
-
-1. 上游设计技能产出 → 7.2 / 7.5.2 归一化后**覆盖**对应字段  
-2. 用户口述 / 内置预设 Step 2 → 覆盖  
-3. 以上皆无 → **保留模版文件现有值**，不在 Skill 或回复中自造默认表  
-
-**命名纪律（违反即 bug）**：
-
-| 令牌 | 只允许用于 | 禁止用于 |
-|---|---|---|
-| `--vts-bar-height` / `--header-height` | 顶栏、Logo 区、水平导航、面包屑行 | 侧栏菜单项、子菜单 title |
-| `--el-menu-item-height` | 侧栏/垂直菜单项、子菜单 title | 顶栏、页签栏 |
-| `--vts-tabs-height` / `--tabs-height` | 多标签页签栏 | 菜单、表单控件 |
-
-#### 7.5.2 布局壳层：7.2 归一化补充（上游别名 → 模版字段名）
-
-上游产出可能是 CSS 变量、JSON、规范表格或标注文字；按**语义**映射到模版已有字段，**禁止**在 Skill 里写死某套设计规范的固定数值。
-
-| 模版标准令牌 | 常见上游别名（按实际产出识别，非穷举） |
-|---|---|
-| `--primary-bg` / `--brand-primary` | 主色浅底 / primaryBg / colorPrimaryBg → 参与 `--ds-dialog-bg` 渐变顶色 |
-| `--header-padding-x` | 顶栏左右内边距 / headerPaddingX / 标注「Header padding ××px」 |
-| `--header-height` | 顶栏高度 / navbarHeight / `--layout-header-height` / 标注「Header ××px」 |
-| `--tabs-height` | 页签栏高度 / tabsHeight / multiTabHeight |
-| `--sidebar-width` | 侧栏展开宽度 / siderWidth / menuWidth |
-| `--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` | 侧栏深色底 `#001529` / 菜单激活纯色 `primary-color` |
-
-#### 7.5.3 壳层令牌变更后的连锁巡检（按令牌名，不写死像素）
-
-任一壳层令牌被上游或用户覆盖后，**grep 执行层**确认无裸值残留：
-
-1. `design-tokens.scss`：被改字段；若 `--layout-header-offset*` 依赖 header/tabs，确认仍正确派生  
-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` 用 `--vts-layout-header-offset*`；禁止写死顶栏组合；禁止 JS 测顶栏高度  
-6. `lay-header`：渲染 navbar / tag；顶栏高度由 CSS 令牌控制  
-7. DevTools：顶栏 computed = **当前** `--header-height`；菜单项 = **当前** `--el-menu-item-height`（两者须不同）
-8. 定高列表页：`--card-padding` / `--vts-card-padding` 变更后，抽查一页查询列表——内容区无外层滚动条、分页完整、`tableHeight` 随 padding 变化
-
-#### 7.5.4 EP 菜单变量纪律
-
-`.sidebar-container .el-menu` 上写 `--el-menu-item-height: <与 design-tokens 一致>`，**禁止** `--el-menu-item-height: var(--el-menu-item-height, …)` 自引用（EP 回退默认 56px）。
-
-#### 7.5.5 查询区尺寸（core-kernel 标准样板）
-
-列表页查询区 **`el-form` 不写 size**（default 中号 = `--control-height` / 设计 `--component-size-base`，默认 32px），查询/工具栏按钮随表单继承；**禁止**查询区单独写 `size="small"` 导致输入框与按钮变成 24px 档。
-
-#### 7.5.6 适配完成验证（Step 8 补充）
-
-- [ ] 已 read 项目 `design-tokens.scss`；回执区分「上游覆盖项 / 保留模版默认项」  
-- [ ] 主内容区 `padding-top` = 当前 `--layout-header-offset`（或桥接 `--vts-layout-header-offset`）  
-- [ ] 顶栏 / 页签 / 侧栏 / 菜单项 computed 尺寸 = 当前对应令牌值  
-- [ ] 执行层 grep 无壳层裸 px 残留（EP 菜单根上的具体 px 须与 `--el-menu-item-height` 一致）  
-- [ ] 查询区 input 与 button 高度一致，且均为 **default 档**（computed ≈ `--control-height`，不是 `--control-height-sm`）  
-- [ ] 三档令牌已写入：`--control-height-sm` / `--control-height` / `--control-height-lg`，并桥接 `--el-component-size*`  
-- [ ] `el-config-provider` **未**全局强制 `size="small"`（除非用户明确要求紧凑主题）
-
-#### 7.5.7 侧栏整主题适配（上游产出 · 强制）
-
-有上游设计产出且要求深色导航时，禁止只改 `--el-color-primary`。按 `design-handoff.md` 读取主色板并写入 `design-tokens` / `theme.scss` 桥接 / `platform-config.json`；`data-theme` 以交接块为准。
-
-#### 7.5.8 组件尺寸 size API 落地（设计规范 → Element Plus）
-
-> 设计侧令牌多为 `--component-size-sm|base|lg`；模版标准名为 `--control-height*`。落地时按下表归一化，并保证 **未指定 size 的 EP 控件** 使用 default 档高度（见 `element-plus.scss` 对 `.el-button` / `.el-input__wrapper` 的重写）。
-
-| 设计语义 | 设计令牌 | 模版令牌 | EP CSS 变量 | EP 组件 API | 像素默认 |
-|----------|----------|----------|-------------|-------------|---------|
-| small | `--component-size-sm` | `--control-height-sm` | `--el-component-size-small` | `size="small"` | 24px |
-| **default** | `--component-size-base` | `--control-height` | `--el-component-size` | **不写 size** / `default` | **32px** |
-| large | `--component-size-lg` | `--control-height-lg` | `--el-component-size-large` | `size="large"` | 40px |
-
-**缺档规则**（与设计规范「一点九」一致）：
-
-1. 上游给出完整三档 → 三档都写入 `design-tokens.scss`「用户可自定义」，并确认 `--el-component-size*` 桥接仍指向 `--control-height*`。
-2. 上游**只给一个高度**（如「控件 32」）→ 写入 `--control-height`（default）；`--control-height-sm` / `--control-height-lg` 保留模版默认或按比例派生；回执注明「缺档 → 回退至 default」。
-3. **必须重设 default（未指定 size）**：`element-plus.scss` 中无 `--small`/`--large` 修饰的按钮/输入类选择器须引用 `var(--control-height)`，禁止依赖 EP 出厂像素且与令牌脱节。
-4. **禁止**把设计 base(32) 映射成全局 `size="small"`；`App.vue` 的 `el-config-provider` 默认不传 `size`（或显式不设），避免全站变 24px。
-5. 表格行内操作、紧凑工具条可用 `size="small"`；查询区/标准表单/弹窗表单用 default；登录主操作可用 `large`。
-6. VXETable / 表格密度的 `size` 与表单控件档位是两套体系，改表单令牌时不要误改表格密度全局配置（除非用户要求）。
-
----
-
-## 八、反例对照表
-
-| 错误 | 正确 |
-|------|------|
-| 只改 `--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` 一致的具体值 |
-| 设计 32px 却全局/查询区用 `size="small"` | default 档不写 size；small 仅紧凑场景 |
-| 只落 `--control-height` 不落 sm/lg、也不桥接 `--el-component-size*` | 三档令牌 + EP 变量 + `element-plus.scss` 默认选择器 |
-| Skill 文档写死顶栏/侧栏默认 px | 读模版 `design-tokens.scss` 或上游产出 |
+`design-tokens` 必须最先，供后续文件引用。视觉规则（shadow/hover/transition/交互态）直接写入 `element-plus.scss`，不另建文件。
+
+## 禁止清单
+
+1. 业务页/组件中裸写 EP 控件 `height` / `padding` / `font-size` / `border-radius`，一律引用令牌
+2. 业务页中重复写 `.el-input__wrapper { height: ... }` 等覆盖，几何只在 `element-plus.scss` 统一改
+3. 颜色硬编码 hex，必须走 `--brand-*` / `--vts-*` / `--el-*` 变量
+4. 另建独立「重写层」文件或按规范名派生文件（如 `semi-controls.scss`）
+5. `design-tokens.scss` 中写选择器（只允许 `:root` 变量块）
+6. EP 菜单变量自引用 `--el-menu-item-height: var(--el-menu-item-height, …)`（EP 回退 56px）
+7. 把设计 base(32px) 映射成全局 `size="small"` 导致全站变 24px
+8. `design-tokens.scss` 或 Skill 文档中写死顶栏/侧栏默认 px；值以当前项目文件或上游产出为准
+9. 改 `EpThemeColor` 后不提醒清 localStorage 缓存
+10. 弹窗背景写死固定渐变；须用 `--ds-dialog-bg`（主题色轻渐变 `primary-bg → component-bg`）