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

package/package.json

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

package/references/core-kernel.md

@@ -256,13 +256,12 @@ function handleSizeChange(size: number) {
               <div class="flex flex-end">
                 <el-button
                   type="primary"
-                  size="small"
                   :loading="loading"
                   @click="pagination.currentPage = 1; pagination.pageSize = 10; onSearch()"
                 >
                   {{ $t("查询") }}
                 </el-button>
-                <el-button size="small" @click="reset">
+                <el-button @click="reset">
                   {{ $t("重置") }}
                 </el-button>
                 <el-button
@@ -297,7 +296,7 @@ function handleSizeChange(size: number) {
           <span class="truncate font-size-16 font-bold">{{ $t("展示列表") }}</span>
         </template>
         <template #buttons>
-          <el-button type="primary" size="small" v-auth="['admin']">
+          <el-button type="primary" v-auth="['admin']">
             {{ $t("新增") }}
           </el-button>
         </template>
@@ -351,7 +350,7 @@ function handleSizeChange(size: number) {
 
 ## 四之二、样式契约（所有生成代码必须遵循）
 
-> 本节是**生成任何页面/组件代码时的样式真相源**：尺寸、间距、边距、颜色、组件档位全部按此执行。后期设计类 Skill（如 ui-ux-pro-max / project-style-design）产出设计规范后，规范经 `design-system` 模块落到 `design-tokens.scss`；此后生成代码只准引用令牌，本节约束依然生效。
+> 本节是**生成任何页面/组件代码时的样式真相源**：尺寸、间距、边距、颜色、组件档位全部按此执行。任意上游设计类 Skill 产出规范后，经 `design-system` 模块归一化并**修改**项目 `design-tokens.scss`（默认值来自 Vue 模版，不由本 Skill 写死）；此后生成代码只准引用令牌，本节约束依然生效。
 
 ### 1. UnoCSS 类名形态（写错 = 样式静默失效）
 
@@ -379,7 +378,8 @@ function handleSizeChange(size: number) {
 | 主色与梯度 | `--el-color-primary`（及 `-light-3/5/7/9`、`-dark-2`） |
 | 状态色 | `--el-color-success` / `warning` / `danger` / `info` |
 | 表格表头 | `--vts-table-header-bg` / `--vts-table-header-text`（el-table 与 vxe 共用） |
-| 弹窗背景 | `--vts-dialog-bg`（支持 `--ds-dialog-bg` 覆写） |
+| 弹窗背景 | `--vts-dialog-bg` ← `--ds-dialog-bg`（主题渐变：`primary-bg → component-bg`） |
+| 弹窗内边距 | `--dialog-header-padding` / `--dialog-body-padding` / `--message-box-content-padding` / `--dialog-footer-padding` |
 
 Canvas / 图谱 / 连线库等**必须传具体色值字符串**的场景，用统一工具从运行时读取变量，禁止把十六进制写死在业务代码里：
 
@@ -396,8 +396,9 @@ edge: { type: "line", style: { stroke: getCssVar("--el-color-primary-light-5", "
 
 | 场景 | 档位 | 说明 |
 |---|---|---|
-| 查询区按钮（查询/重置/展开收起） | `size="small"` | 与 inline 查询区配套 |
-| `ReTableBar` 工具栏按钮（新增/导入/导出/删除） | `size="small"` | 列表页工具栏统一 small |
+| **查询区 `el-form`（含输入/选择/按钮）** | **default（不写 size）** | 中号 32px，与 `--control-height` / `--el-component-size` 一致；**禁止**只给按钮写 `small` 而表单走 default |
+| 查询区按钮（查询/重置/展开收起） | 随 `el-form` 继承 | **禁止**单独写 `size="small"` 导致与输入框档位不一致 |
+| `ReTableBar` 工具栏按钮（新增/导入/导出/删除） | default（不写 size） | 列表页工具栏与查询区同档（中号） |
 | 表格 | `:size="size"`（`ReTableBar` 插槽透出） | **禁止写死**，密度切换由用户控制 |
 | 分页 | `RePagination :size="size"` | 跟随表格密度 |
 | 弹窗内表单 | default（不写 size）+ `label-width="96px"` | `ReDialog` / `ReDialogResize` 内表单 |

package/references/design-system.md

@@ -94,7 +94,11 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
    ```
 4. 读 `public/platform-config.json` 的 `EpThemeColor` 当前值，与回执主色比对。
 
-### Step 2 写入令牌层 `src/styles/design-tokens.scss`
+### Step 2 修改/写入令牌层 `src/styles/design-tokens.scss`
+
+> **新模版（vue3-web-temp ≥ 已内置令牌文件）**：`design-tokens.scss` **已存在** → **只修改令牌值**（四段结构保持不动），**禁止**整文件覆盖重写或从空项目「生成」一份新的。适配流程 = **改数据 + 改执行层**，不是「新建令牌文件」。
+>
+> **旧项目/无该文件**：才允许按下方结构**新建**唯一一份 `design-tokens.scss`。
 
 结构固定为四段：用户可自定义 → 规范语义别名 → 模版桥接令牌 → Element Plus 映射。
 
@@ -162,7 +166,7 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
   --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: var(--el-bg-color-overlay); /* 接管 --vts-dialog-bg：弹窗背景按规范走浮层色 */
+  --ds-dialog-bg: linear-gradient(to bottom, var(--primary-bg), var(--component-bg)); /* 弹窗/MessageBox 背景；index.scss 桥接 --vts-dialog-bg */
 
   /* —— Element Plus 变量映射（必配，含主色兜底） —— */
   --el-color-primary: var(--brand-primary); /* 兜底：JS 运行时 setEpThemeColor 生效前的首屏主色 */
@@ -307,12 +311,13 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 
 /* —— 弹窗 / 抽屉 / 消息盒 —— */
 .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__header, .el-message-box__header { padding: var(--dialog-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-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-dialog__body { padding: var(--dialog-body-padding); font-size: var(--font-size-base); line-height: var(--line-height); }
+.el-message-box__content { padding: var(--message-box-content-padding); font-size: var(--font-size-base); line-height: var(--line-height); }
+.el-dialog__footer, .el-message-box__btns { padding: var(--dialog-footer-padding); }
+.el-drawer__header { padding: var(--dialog-header-padding); margin-bottom: 0; font-size: var(--font-size-lg); }
+.el-drawer__body { padding: var(--dialog-footer-padding); }
 
 /* —— 下拉 / 弹出选项 —— */
 .el-dropdown-menu__item { padding: 0 var(--vts-space-md, 16px); font-size: var(--font-size-base); line-height: var(--control-height); }
@@ -378,7 +383,9 @@ 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`；菜单项高度走令牌层 EP 映射（`--el-menu-item-height`） |
+   | `sidebar.scss` | 侧栏几何 | 宽度走 `--sidebar-width` / `--sidebar-collapsed-width`；菜单项高度走 `--el-menu-item-height`（**禁止**用 `--vts-bar-height`）；Logo 区 scroll 高度随 `--header-height` + `--sidebar-collapse-bar-height` 重算 |
+   | `layout/components/lay-tag` | 页签栏高度 | 走 `--vts-tabs-height`（桥接 `--tabs-height`） |
+   | `layout/components/lay-navbar` 等 | 顶栏内容区 | 行高/高度跟随 `--vts-bar-height`，禁止残留 `h-38` 等旧模版裸值 |
 
 4. 暗黑模式：在 `dark.scss` 内为新增令牌补暗色覆盖（`--vts-table-header-bg`、`--vts-message-bg`、`--vts-dialog-bg` 等），遵守 `layout-theme` 第三节规则。
 
@@ -404,7 +411,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 - [ ] 表格：表头底色/文字色/字重符合规范
 - [ ] 卡片内边距：`.el-card__body` = 规范值（AntD 24px），不再是 5px
 - [ ] 表单标签：computed font-weight 为规范值（AntD/Semi = 400，非 700）
-- [ ] 弹窗：无渐变蓝底，背景为规范底色，圆角符合规范
+- [ ] 弹窗：`--ds-dialog-bg` 为 **主题色轻渐变**（`primary-bg → component-bg`），非写死蓝渐变；`ElMessageBox` 内容区用 `--message-box-content-padding`（比 `el-dialog` body 更紧凑）
 - [ ] 暗黑模式下无白底黑字残留（切换 `html.dark` 验证）
 - [ ] 第四节冲突清单全部处理完毕（逐条回填）
 - [ ] Step 7 存量扫描已执行且结果已输出
@@ -438,7 +445,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | 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(to bottom, #e5f3fe, #fefefe)`（dark: `rgb(36 37 37)`） | **所有弹窗强制渐变蓝底** | 已变量化 `var(--ds-dialog-bg, 原值)`，桥接令牌 `--ds-dialog-bg` 自动接管 | 旧项目把亮/暗两处定义改为 `var(--ds-dialog-bg, 原值)` |
+| 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` |
 | 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 - ...)`；默认保持不变标注差异 |
@@ -519,16 +526,97 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 当用户要求「把上游设计技能的稿子/令牌落到项目」：
 
 1. 先输出识别回执（规范 = 稿子所用系统；不在预设内则标 `custom`，按 1.3）。
-2. 按 7.2 归一化后，把「用户可自定义」区块的令牌值写入 `design-tokens.scss`。
-3. 若上游产出含组件视觉（HTML 原型/设计稿）→ 以其为基准微调 `element-plus.scss` 几何段的差异项。
-4. 上游产出里的业务配色（状态色、图表系列）按 `layout-theme` 第八节映射为 `--vts-*` 语义变量。
-5. 原型与项目出现视觉差异时：先对比两侧令牌值是否一致（含命名映射是否漏项），再查第四节冲突清单是否漏处理，最后查 Step 7 存量裸值。
+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 样式/标注反推令牌，并在回执中注明"反推"项。
+- **默认值归属**：布局壳层的默认像素/色值由 **Vue 模版项目** `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 文档里另写默认表替代模版。
+
+#### 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-padding` / `--dialog-body-padding` / `--message-box-content-padding` / `--dialog-footer-padding` | `element-plus.scss` 弹窗/MessageBox 各区块 padding |
+| `--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 |
+
+#### 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: var(--vts-layout-header-offset)`，禁止写死旧顶栏组合  
+6. DevTools：顶栏 computed = **当前** `--header-height`；菜单项 = **当前** `--el-menu-item-height`（两者须不同）
+
+#### 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 中号，32px），查询/工具栏按钮随表单继承；**禁止**查询区单独写 `size="small"` 导致输入框与按钮档位不一致。
+
+#### 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 高度一致（small 档）
 
 ---
 
@@ -539,10 +627,14 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 - **命名漂移/重复建层**：适配文件建成 `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`，从根上消除顺序问题。
-- 弹窗仍是渐变蓝底（忘改 `--vts-dialog-bg`）。
+- 弹窗仍是**写死蓝渐变**或纯白底（未设 `--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 后表头/行变更色刺眼。
-- **固化上游技能名**：流程里写死"必须先用 project-style-design"，换个同类技能就不会衔接——正确做法是按第七节协议只认产出物。
+- **固化上游技能名**：流程里写死某设计技能名或把其规范表抄进 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` 一致的具体值。

package/references/layout-theme.md

@@ -21,7 +21,8 @@ tags: [vue3, layout, theme, dark-mode, css-variables, design-tokens, element-plu
 │  --vts-switch-off-color     Switch 关闭态颜色              │
 │  --vts-bar-height           导航条高度                     │
 │  --vts-margin               内容区边距                     │
-│  --vts-dialog-bg            弹窗背景（支持渐变）             │
+│  --vts-dialog-bg            弹窗背景（`--ds-dialog-bg` 主题渐变，index.scss 桥接）   │
+│  --dialog-*-padding        弹窗/MessageBox 分区内边距（design-tokens 定义）         │
 ├─────────────────────────────────────────────────────────┤
 │  第二层：侧边栏主题变量（html[data-theme]）                  │
 │  --vts-theme-menu-bg               菜单背景色              │
@@ -188,6 +189,19 @@ html.dark {
 | `p-16` / `m-16` | 16px | 大间距 |
 | `p-20` / `m-20` | 20px | 区块间距 |
 
+### 4.1.1 弹窗 / MessageBox（design-tokens 定义 · element-plus.scss 执行）
+
+| 令牌 | 默认语义 | 消费位置 |
+|------|---------|---------|
+| `--dialog-header-padding` | 16px 24px | `.el-dialog__header` / `.el-message-box__header` |
+| `--dialog-body-padding` | 24px | `.el-dialog__body`（表单弹窗） |
+| `--message-box-content-padding` | 16px 24px | `.el-message-box__content`（确认框，**比 dialog body 更紧凑**） |
+| `--dialog-footer-padding` | 16px 24px | `.el-dialog__footer` / `.el-message-box__btns` |
+| `--primary-bg` | 主色浅底（上游设计技能常提供） | 渐变顶色 |
+| `--ds-dialog-bg` | `linear-gradient(primary-bg → component-bg)` | `index.scss` → `--vts-dialog-bg` → `.el-dialog` / `.el-message-box` |
+
+> **禁止**写死 `#e5f3fe → #fefefe` 蓝渐变；换主题时只改 `--primary-bg` / `--brand-primary`，渐变自动跟随。暗黑模式在 `dark.scss` 用 `color-mix` 覆写 `--primary-bg` 后同样生效。
+
 ### 4.2 字号
 
 UnoCSS `theme.fontSize` 已显式定义为 px 值（避免被 `presetRemToPx` 转换）：