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

package/SKILL.md

@@ -184,7 +184,7 @@ export function getXxxListApi(data: XxxQuery) {
 ### 列表页
 
 ```typescript
-const { content, pagination, loading, onSearch, reset, formRef, tableData, tableHeight, ... } =
+const { content, otherRef, pagination, loading, onSearch, reset, formRef, tableData, tableHeight, ... } =
   useTableSearch(formQuery, getXxxListApi, `${import.meta.env.VITE_API_BASE_URL}/console/xxx/list`);
 
 onSearch(); // 查询
@@ -197,6 +197,7 @@ reset();    // 重置（配合 formRef.resetFields）
   - `el-card ref="content"` + 固定 `height`（含 `headerHeight`），禁止只用 `minHeight` / `ref` 挂 `div`
   - 查询区 `bg-bg_color p-5` + `ReGrid` `:gap="[0, 20]"` + 表单项 `w-[100%] !mr-0`；与 `ReTableBar` 展示区分开
   - 表格绑 `tableHeight`；分页放在 `ReTableBar` 内，避免无数据时贴查询区
+  - 卡片内查询条件以外的模块（统计块/页签/提示条等）包一个根元素绑 `otherRef`，高度自动从 `tableHeight` 扣除，不绑则表格高度算错
 
 ### 路由
 
@@ -289,7 +290,7 @@ reset();    // 重置（配合 formRef.resetFields）
 **3. API** — `@/utils/http`；方法跟后端（允许 GET/POST）；封装在 `src/api/`；`VITE_API_BASE_URL`；无虚构 `/api` / 无 `crypto: true`
 **4. 安全** — 无危险 v-html；无硬编码密钥  
 **5. 业务** — `onSearch`/`reset`；提交 loading；权限；未二次 Layout  
-**5b. 列表布局** — `el-card`+`content`+固定 height；查询/展示分区；`tableHeight`；分页在 ReTableBar 内  
+**5b. 列表布局** — `el-card`+`content`+固定 height；查询/展示分区；`tableHeight`；分页在 ReTableBar 内；查询条件外的模块绑 `otherRef`  
 **5c. 设计规范遵从（命中 design-system 时必查）** — 已输出识别回执且三点一致；令牌层（唯一新增）已建立、几何重写并入 element-plus.scss、文件名未漂移；第四节硬编码冲突清单逐条处理并回填；公共区域（侧栏/导航/壳变量）已适配；存量裸值扫描已执行；业务代码无裸控件高度/内边距/字号；验证清单全过  
 **5d. 样式契约（每次生成必查）** — UnoCSS 连字符形态（`p-5`/`w-full`；无 `p5`/`w100%`）；颜色语义变量（无 `bg-[#fff] dark:bg-[#303030]`）；组件尺寸档位（查询/工具栏 `small`、表格 `:size="size"`、弹窗表单 default、整屏 `large`）；间距 4px 基数；细则见 `core-kernel`「四之二」  
 **6. 风格** — 无多余 console；`$t('中文')`；`--vts-*` / UnoCSS；图标走 `svg-icon` / `icons` 约定  

package/package.json

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

package/references/code-quality.md

@@ -46,7 +46,7 @@ tags: [code-review, quality, checklist, lint, typescript, vue3, security, perfor
 - [ ] HTTP 为 `import { http } from '@/utils/http'` + 全局 `Result<T>`
 - [ ] 业务路由未二次挂 Layout
 - [ ] 使用对应 `references/<模块>.md` 示例与约定写法
-- [ ] **查询列表布局**：`el-card ref="content"` + 固定 `height`（含 `headerHeight`）；查询区 `bg-bg_color p-5` + `ReGrid` `gap`/`cols`；表格绑 `tableHeight`；分页在 `ReTableBar` 内
+- [ ] **查询列表布局**：`el-card ref="content"` + 固定 `height`（含 `headerHeight`）；查询区 `bg-bg_color p-5` + `ReGrid` `gap`/`cols`；表格绑 `tableHeight`；分页在 `ReTableBar` 内；卡片内查询条件以外的模块包根元素绑 `otherRef`
 
 
 ## 一、TypeScript 类型检查
@@ -274,6 +274,7 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 - [ ] 折叠事件为 `@should-show-collapse`（不是 `@show-collapse`）。
 - [ ] 展示区用 `ReTableBar class="bg-bg_color"`，与查询区视觉分离。
 - [ ] 表格 `:style="{ height: \`${tableHeight}px\` }"`；`paginationRef` 在表格下方且同属 `ReTableBar` `#default`。
+- [ ] 卡片内除查询表单、表格+分页外还有其他模块（统计块/页签/提示条等）时，已包进一个根元素并绑 `ref="otherRef"`（从 `useTableSearch` 解构）；未绑则 `tableHeight` 漏减该模块高度。
 - [ ] `RePagination` 使用 `:pagination` + `@handle-current-change` / `@handle-size-change`。
 - [ ] `ReTableOperate` 使用 `:list`（不是 `:buttons`）。
 

package/references/core-kernel.md

@@ -28,7 +28,7 @@ tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
 | 8 | i18n：`$t('中文key')`，key 即中文文案 |
 | 9 | 禁止用 `v-html` 渲染不可信内容 |
 | 10 | 新三方依赖必须用户确认；已有封装须复用，选型表指定库勿擅自替换 |
-| 11 | **查询列表页布局硬约束**（见下方黄金样板）：`el-card` + `ref="content"` + **固定 `height`**（非 `minHeight`）；查询区与表格区分区；表格用 `tableHeight`；分页放在 `ReTableBar` 内 |
+| 11 | **查询列表页布局硬约束**（见下方黄金样板）：`el-card` + `ref="content"` + **固定 `height`**（非 `minHeight`）；查询区与表格区分区；表格用 `tableHeight`；分页放在 `ReTableBar` 内；查询条件以外的模块绑 `otherRef` 参与高度扣除 |
 | 11 | addon 缺失时按 `project-inventory` 第九节**精确版本**安装；禁止 `@latest` / 无版本号；Vite 插件与 `build/plugins/*` 成套核对 |
 | 12 | **样式契约**（见「四之二」）：UnoCSS 类名必须连字符形态（`p-5`/`w-full`，禁止 `p5`/`w100%`）；颜色按语义取 `--el-*`/`--vts-*` 变量（禁止 `bg-[#fff] dark:bg-[#303030]` 成对硬编码）；组件尺寸按场景档位（查询/工具栏 `small`、表格 `:size="size"`、弹窗表单 default、整屏主表单 `large`）；`design-tokens.scss` 存在时零新增硬编码裸值 |
 
@@ -131,6 +131,7 @@ ReAuth、ReDialog、ReGrid、ReGridItem、RePagination、ReTableBar、ReTableOpe
 | L5 | 操作按钮用 `suffix` | `<ReGridItem suffix>`，勿用随意 `index=99` 冒充后缀列 |
 | L6 | 表格动态高度 | `:style="{ height: \`${tableHeight}px\` }"`；分页 **必须在** `ReTableBar` 的 `#default` 内、表格下方，保证空数据时仍占满剩余高度 |
 | L7 | `RePagination` 真实 API | `:pagination="pagination"` + `@handle-current-change` / `@handle-size-change`；**禁止**虚构的 `v-model:current-page` |
+| L8 | 查询条件之外的模块必须绑 `otherRef` | 卡片内除查询表单、表格+分页外还有任何模块（统计块/页签/提示条/子面板等），外层包一个根元素并 `ref="otherRef"`；`tableHeight` 会自动减去它的高度，不绑则表格高度算错（溢出或被压扁）。多个模块合并进**一个**根容器，禁止逐个散落 |
 
 ```vue
 <script setup lang="ts">
@@ -153,6 +154,7 @@ const formQuery = reactive<CustomerQuery>({ keyword: "", status: undefined });
 
 const {
   content,
+  otherRef,
   tableHeight,
   paginationRef,
   loading,
@@ -215,7 +217,7 @@ function handleSizeChange(size: number) {
         height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`,
       }"
     >
-      <!-- L3：查询区独立背景与内边距 -->
+      <!-- L3：查询区独立背景与内边距（formRef 高度自动参与 tableHeight 计算） -->
       <div>
         <el-form
           ref="formRef"
@@ -254,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
@@ -281,13 +282,21 @@ function handleSizeChange(size: number) {
         </el-form>
       </div>
 
+      <!-- L8：查询条件以外的模块统一包一个根元素绑 otherRef（无额外模块时整段删除）；
+           tableHeight 公式会自动减去它的高度：
+           content 高 − formRef 高 − paginationRef 高 − otherRef 高 − 50；
+           模块自身间距写在内部内容上，根容器保持零高度余量 -->
+      <div ref="otherRef">
+        <!-- 统计/页签/提示等额外模块放这里 -->
+      </div>
+
       <!-- L3/L6：展示区在 ReTableBar 内；表格+分页同槽，保证空数据也撑满 -->
       <ReTableBar class="bg-bg_color" :columns="[]" @refresh="onSearch">
         <template #title>
           <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>
@@ -335,11 +344,13 @@ function handleSizeChange(size: number) {
 
 `useTableSearch(formQuery, searchFn, url)`：`searchFn` 签名为 `(query, url) => Promise<Result<T>>`，分页字段为 `pageNo` / `pageSize`，列表数据取 `data.content`，总数 `data.totalCount`。返回值中的 `content` / `tableHeight` / `paginationRef` / `formRef` 必须按样板绑定，否则动态高度失效。
 
+**动态高度真相**：`tableHeight = content.offsetHeight − formRef 高 − paginationRef 高 − otherRef 高 − 50`（ResizeObserver 实时计算）。`content` / `formRef` / `paginationRef` 是固定三件套；**页面出现查询条件以外的模块时必须解构 `otherRef` 并绑到这些模块的统一根元素上**（多个模块包进同一个根容器），高度随模块显隐/伸缩自动重算。禁止用写死像素、`calc()` 猜值或自行手写 ResizeObserver 替代该机制。
+
 ---
 
 ## 四之二、样式契约（所有生成代码必须遵循）
 
-> 本节是**生成任何页面/组件代码时的样式真相源**：尺寸、间距、边距、颜色、组件档位全部按此执行。后期设计类 Skill（如 ui-ux-pro-max / project-style-design）产出设计规范后，规范经 `design-system` 模块落到 `design-tokens.scss`；此后生成代码只准引用令牌，本节约束依然生效。
+> 本节是**生成任何页面/组件代码时的样式真相源**：尺寸、间距、边距、颜色、组件档位全部按此执行。任意上游设计类 Skill 产出规范后，经 `design-system` 模块归一化并**修改**项目 `design-tokens.scss`（默认值来自 Vue 模版，不由本 Skill 写死）；此后生成代码只准引用令牌，本节约束依然生效。
 
 ### 1. UnoCSS 类名形态（写错 = 样式静默失效）
 
@@ -367,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 / 图谱 / 连线库等**必须传具体色值字符串**的场景，用统一工具从运行时读取变量，禁止把十六进制写死在业务代码里：
 
@@ -384,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/crud-pages.md

@@ -18,7 +18,7 @@ tags: [vue3, crud, list, form, detail, table, useTableSearch, page, layout]
 ```typescript
 useTableSearch(formQuery, searchFn, url)
 // searchFn: (query: CombinedQueryData, url: string) => Promise<Result<T>>
-// 返回含：content, tableData, pagination, loading, formRef, onSearch, reset,
+// 返回含：content, otherRef, tableData, pagination, loading, formRef, onSearch, reset,
 //         tableHeight, paginationRef, gridRef, showCollapse, collapsed,
 //         collapsedToggle, upBold, downBold, multipleTableRef, ...
 ```
@@ -27,7 +27,7 @@ useTableSearch(formQuery, searchFn, url)
 - 重置：`reset()`（内部 `formRef.resetFields()`）
 - 列表：`tableData.value.tableList`（或经 computed 断言）
 - 分页：请求带 `pageNo` / `pageSize`；响应 `data.content` / `data.totalCount`
-- **高度**：`tableHeight` 由 ResizeObserver 根据 `content` / `formRef` / `paginationRef` 计算；三者必须按黄金样板绑定
+- **高度**：`tableHeight` 由 ResizeObserver 计算，公式 = `content` 高 − `formRef` 高 − `paginationRef` 高 − `otherRef` 高 − 50；`content` / `formRef` / `paginationRef` 必须按黄金样板绑定；**查询条件以外的模块（统计块/页签/提示条等）必须包进一个根元素并绑 `otherRef`**，否则表格动态高度算错
 
 ### 布局硬约束（生成列表页必须全部满足）
 
@@ -40,6 +40,7 @@ useTableSearch(formQuery, searchFn, url)
 | 查询按钮 | `<ReGridItem suffix>` + `flex flex-end` | 用 `index="99"` 冒充后缀 |
 | 展示区 | `ReTableBar class="bg-bg_color"`，与查询区分离 | 查询与表格糊成一块、无标题栏 |
 | 表格高度 | `:style="{ height: \`${tableHeight}px\` }"` | 不绑 `tableHeight`（空数据时分页贴查询区） |
+| 额外模块 | 卡片内查询条件以外的模块包一个根元素绑 `ref="otherRef"`（多个模块合进同一根容器），高度自动从 `tableHeight` 扣除 | 额外模块不绑 `otherRef`（表格溢出/被压扁）；手写固定像素或 `calc()` 猜高度 |
 | 分页 | 放在 `ReTableBar` `#default` 内、表格下方；`RePagination` + `:pagination` + `@handle-current-change` / `@handle-size-change` | 分页在卡片外；虚构 `v-model:current-page` |
 
 ### 完整列表示例
@@ -63,7 +64,7 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 ```
 
 ```typescript
-const { onSearch, reset, tableData, loading, pagination, content, tableHeight, ... } =
+const { onSearch, reset, tableData, loading, pagination, content, otherRef, tableHeight, ... } =
   useTableSearch(
     formQuery,
     getCustomerList,
@@ -160,6 +161,7 @@ async function onSubmit() {
 - 业务路由二次 Layout
 - ReSelectQuery 写成不存在的 `:api` / `label-key` API（真实 props 见 form-advanced）
 - **`ref="content"` 挂在 `div` 上**（`content.$el` 为空 → `tableHeight` 恒为 0）
+- **卡片内有查询条件以外的模块却不绑 `otherRef`**（高度公式漏减该模块 → 表格溢出卡片或底部被截）；或绑到多个散落元素（`otherRef` 只有一个，多模块需包进同一根容器）
 - 卡片只用 **`minHeight`**，不用固定 **`height`**（页面不饱满、表格高度算错）
 - 查询表单无 `p-5` / 无 `gap` / 表单项无 `w-[100%] !mr-0`（字段挤在一起）
 - 查询区与 `ReTableBar` 无分区（条件与展示糊成一块）

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` 转换）：

package/references/project-inventory.md

@@ -221,7 +221,7 @@
 | **useApp** | 全局应用状态（布局、字典、登出等） | `baseCodeGet(codeType)`、`filterValue()`、`headerHeight`、`svgLoading` |
 | **useDetail** | 详情页跳转与参数传递 | `toDetail({ id, mark, text })`、`initToDetail()`、`getParameter()` |
 | **useFormCheck** | 多表单校验聚合 | 追踪各字段校验状态，emit `form-validate` 事件 |
-| **useTableSearch** | 列表页搜索/分页/Loading/动态表高 | `content`（须绑 `el-card`）、`tableHeight`、`paginationRef`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef`、`gridRef`、`collapsed` / `showCollapse` / `collapsedToggle` |
+| **useTableSearch** | 列表页搜索/分页/Loading/动态表高 | `content`（须绑 `el-card`）、`otherRef`（查询条件外模块的统一根元素，高度自动从 `tableHeight` 扣除）、`tableHeight`、`paginationRef`、`tableData`、`pagination`、`loading`、`onSearch()`、`reset()`、`formRef`、`gridRef`、`collapsed` / `showCollapse` / `collapsedToggle` |
 | **useTags** | 多标签页管理 | 右键菜单（刷新/关闭/关闭其他/全屏） |
 | **useTheme** | 主题切换（暗色/亮色） | 主题色生成、布局预设、缓存重置 |
 | **useWebSocket** | WebSocket 通信 | `subscribe()`、`send()`、`sendRaw()`、`isConnected` |