@qilitt-mickey/vue3-temp-skill 1.1.14 → 1.1.16

package/SKILL.md

@@ -13,6 +13,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 - 面向由 **vue3-web-temp** 脚手架搭出的业务项目（目录名/安装路径因人而异，以当前工作区为准）
 - 业务写法以本包 `references/` 为准；壳层行为（顶部 tag / 侧栏 / keep-alive / `useDetail`）以**当前项目**已有实现为准
+- **双轨**：无设计 handoff → 保持模版出厂令牌；有设计落地 → 读 `design-handoff.md`，按设计规范回填令牌（视觉关键尺寸须为 CSS 变量）
 
 ## 使用方式
 
@@ -52,7 +53,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 |------|------|
 | addon / 查 Re* 名 / 装依赖 | `references/project-inventory.md` |
 | 写完代码后（闸门，非功能命中） | `references/code-quality.md` |
-| 设计交接块 / 上游令牌产出落地 | `references/design-handoff.md`（+ `design-system`） |
+| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md`（+ `design-system`） |
 
 ### 标准业务面
 
@@ -69,7 +70,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 | **feedback-loading** | message、loading、确认框 |
 | **base-code-dict** | 字典、baseCode、码表 |
 | **api-check** | 联调、mock、契约、对接后端 |
-| **ui-components** | Re组件、公共组件、type.ts |
+| **ui-components** | 新建 Re*、type.ts、组件目录；**用法见各功能模块**（本文件仅索引） |
 
 ### 专项能力包
 

package/package.json

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

package/references/code-quality.md

@@ -37,13 +37,14 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 | `toDetail` / 独立 `*Detail` 路由 | 路由无 `activePath`，或 `showLink` 非 `false` | `detail-page` 三件套 |
 | 同上 | 默认场景缺 `keepAlive`/`moreTags`（业务未声明不要缓存） | 样板默认写出；不要缓存再删 |
 | 同上 | 详情页无 `initToDetail`，或 `name` 与路由不一致 | 对齐 `defineOptions` |
-| 列表页 | 无 `el-card.vts-page-card` / 无 `tableHeight` / 分页在 ReTableBar 外 | `crud-pages` L1–L8 |
+| 列表页 | 无 `el-card.vts-page-card` / `100vh` 减顶栏定高 / 无 `tableHeight` / 分页在 ReTableBar 外 / 操作列手写多按钮未用 `ReTableOperate` | `crud-pages` L1–L9 |
 | `src/api/**` | 绕过 `@/utils/http`，或虚构 `/api` 前缀，或响应当 `success`/`code` | `http-api` |
 | 下载/导出 API | 无 `responseType: "blob"` | `http-api` / `download-export` |
 | 删除/危险操作 | 无确认框 | `feedback-loading` |
 | 编辑回显 | 整表 `formData = res.data` 破坏响应式 | `Object.assign`（`data-writeback`） |
 | 按钮权限需求 | 裸 `v-if` 角色判断，未用 `v-auth`/`ReAuth` | `permission-auth` |
 | 新菜单路由 | 父级无 `icon` 或业务页二次挂 `Layout` | `icons` + `core-kernel` |
+| 列表查询区 `el-form` / 查询按钮 | 写了 `size="small"`（紧凑主题用户未要求） | 不写 size，用 default=`--control-height` |
 
 ## 选型与硬约束
 
@@ -53,7 +54,8 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 - [ ] 列表方法名 `onSearch` / `reset`；HTTP 用 `@/utils/http` + `Result<T>`
 - [ ] 业务路由未二次挂 Layout
 - [ ] 独立详情：对照路由文件确认 `showLink:false` + `activePath` + `keepAlive`/`moreTags`（默认）+ `toDetail` + `initToDetail`
-- [ ] 列表布局按 `crud-pages` 黄金样板（`el-card.vts-page-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内；内容区无外层滚动条）
+- [ ] 列表布局按 `crud-pages` 黄金样板（`el-card.vts-page-card`+`content`、无 `100vh` 减顶栏、`tableHeight`、`otherRef`、分页在 ReTableBar 内；内容区无外层滚动条）
+- [ ] 顶栏高度仅 `--header-height` 等 CSS 令牌；禁止 JS 测顶栏 / `platform-config` 顶栏像素字段 / `useApp` 导出顶栏高度
 
 ## TypeScript
 
@@ -91,7 +93,7 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 ## 样式
 
 - [ ] `scoped`；色用 CSS 变量；优先 UnoCSS 连字符类（`p-5` 非 `p5`）
-- [ ] 语义色 `bg-bg_color` / `--el-*`；尺寸档位见 `core-kernel` 样式契约
+- [ ] 语义色 `bg-bg_color` / `--el-*`；尺寸档位见 `core-kernel` 样式契约（查询区 default 32，禁止误用 small 24）
 - [ ] 图标见 `icons`；忌滥 `!important`；选择器 ≤3 层
 - [ ] 全局 EP 覆盖在 `element-plus.scss`；侧栏色用 `html[data-theme]`
 - [ ] 主色经 `setEpThemeColor()`；颜色处理用 `chroma-js`
@@ -101,7 +103,9 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 - [ ] 规范识别回执；令牌 / `platform-config.json` / 侧栏主题一致
 - [ ] 已建 `design-tokens.scss`；`index.scss` 中其 `@use` 最前
 - [ ] 冲突清单已逐条处理（见 `design-system`）
-- [ ] 有上游设计产出时已读 `design-handoff`；`EpThemeColor`/`Theme`/侧栏桥接/`Version` 一致
+- [ ] 有上游设计产出时已读 `design-handoff`：JSON 优先；按**全量令牌核对表 A～E**回填或回执「保留出厂」；`ShowModel` 写 JSON 值（设计默认常 `line`）；错误色 `#F5222D`；弹窗/壳层改令牌即生效
+- [ ] **无**设计落地时未改出厂主色 / ShowModel / 壳层 / 弹窗几何默认
+- [ ] 组件尺寸三档已落地并桥接 `--el-component-size*`；缺档落到 default；未全局强制 `size="small"`；**查询区不写 size**（三档对照表 ≠ 查询区要用 small）
 
 ## 业务
 

package/references/core-kernel.md

@@ -24,7 +24,7 @@ tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
 | 9 | i18n：`$t('中文key')` |
 | 10 | 禁止用 `v-html` 渲染不可信内容 |
 | 11 | 新依赖须用户确认；已有封装须复用；选型表指定库勿擅自替换 |
-| 12 | 列表布局按 **`crud-pages` 黄金样板**（`el-card.vts-page-card`+`content`+固定 height、`tableHeight`、`otherRef`、分页在 ReTableBar 内；仅表格体内滚动） |
+| 12 | 列表布局按 **`crud-pages` 黄金样板**（`el-card.vts-page-card`+`content`、无 `100vh` 减顶栏定高、`tableHeight`、`otherRef`、分页在 ReTableBar 内；仅表格体内滚动） |
 | 13 | addon 按 `project-inventory` 第九节精确版本安装；禁止 `@latest` |
 | 14 | 样式契约见下文「样式契约」 |
 
@@ -82,7 +82,7 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 
 | Hook | 用途 | 详例 |
 |------|------|------|
-| `useApp` | headerHeight、字典、svgLoading | — |
+| `useApp` | 字典、svgLoading | — |
 | `useTableSearch` | 列表查询分页 | `crud-pages` |
 | `useDetail` | 详情跳转与顶部 tag | `detail-page` |
 | `useFormCheck` | 多表单校验 | `data-writeback` |
@@ -111,28 +111,27 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 
 ### 组件尺寸
 
-| 场景 | 档位 |
-|------|------|
-| 查询区表单/按钮、工具栏按钮 | default（不写 size） |
-| 表格 / 分页 | `:size="size"`（ReTableBar 透出） |
-| 弹窗内表单 | default |
-| 登录/整屏主表单 | `large` |
-| 移动端 Vant | 见 `mobile-h5` |
+| 场景 | 档位 | 像素（令牌） |
+|------|------|--------------|
+| 查询区表单/按钮、工具栏按钮、弹窗内表单 | **default（不写 size）** | `--control-height`（设计 `--component-size-base`，默认 32px） |
+| 表格 / 分页 | `:size="size"`（ReTableBar 透出） | 随密度切换，与表单档位独立 |
+| 表格行内操作、紧凑工具条 | `small` | `--control-height-sm`（24px） |
+| 登录/整屏主表单主按钮 | `large` | `--control-height-lg`（40px） |
+| 移动端 Vant | 见 `mobile-h5` | — |
 
-存在 `design-tokens.scss` 时：零新增硬编码裸值；适配流程见 `design-system`。
+- **禁止**查询区 / 标准业务表单写 `size="small"`，也**禁止** `el-config-provider` 全局强制 `small`（除非用户明确要求紧凑主题）。
+- 存在 `design-tokens.scss` 时：零新增硬编码裸值；三档桥接与 EP 映射见 `design-system` 7.5.8。
+- 适配流程见 `design-system`。
 
 ### 独立功能页容器
 
-定高且内部滚动（与列表卡同类场景）：
+定高且内部滚动（与列表卡同类场景）——优先 `el-card.vts-page-card`；非 Card 根节点用 `vts-page-fill`：
 
 ```vue
-<div
-  :style="{ height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)` }"
-  class="pos-relative bg-bg_color p-5 overflow-hidden"
->
+<div class="vts-page-fill h-full pos-relative bg-bg_color p-5 overflow-hidden">
 ```
 
-查询列表定高卡 → `crud-pages`（`el-card.vts-page-card` + `tableHeight`）。
+查询列表定高卡 → `crud-pages`（`el-card.vts-page-card` + `tableHeight`，禁止 `100vh` 减顶栏定高）。
 ## 六、资产分层
 
 附加 Hook/组件按功能模块加载（WebSocket、微信、附件、图表等）→ 见各专项与 `project-inventory`。

package/references/crud-pages.md

@@ -29,23 +29,27 @@ useTableSearch(formQuery, searchFn, url)
 
 | 场景 | 做法 |
 |------|------|
-| 查询列表（定高） | `el-card.vts-page-card` + 固定 `height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`；表格绑 `tableHeight`；**仅表格体内滚动**；分页在表格下方；整页无外层滚动条 |
+| 查询列表（定高） | `el-card.vts-page-card`（禁止 `100vh` 减顶栏定高）；表格绑 `tableHeight`；仅表格体内滚动；分页在表格下方；整页无外层滚动条 |
 | 树 + 表分栏 | 同上；左侧树、右侧表共用定高卡，高度仍走 `useTableSearch` 几何实测 |
-| 长表单 / 详情 / 说明类 | 可用 `minHeight` 同公式；内容超出时由 `.app-main` 内 `el-scrollbar` 滚动 |
-| Card 内边距 | 一律走 `--vts-card-padding`（桥接 `--card-padding`）；换规范只改令牌，列表高度由 Hook 跟随 |
+| 长表单 / 详情 / 说明类 | 根节点 `min-height: 100%`（或 `:style="{ minHeight: '100%' }"`）；超出由 `.app-main` 内 `el-scrollbar` 滚动 |
+| 非 Card 整页填满 | 根节点加 `class="vts-page-fill"` + `height: 100%` / `h-full` |
+| Card 内边距 | 一律走 `--vts-card-padding`（桥接 `--card-padding`）；换规范 / `--vts-margin` 变化由壳层 flex 链 + Hook 自动跟随 |
+
+> **壳层原理**（`lay-content`）：`.main-content` 用 `padding: var(--vts-margin)`（不用 margin）；定高页 `.main-content:has(.vts-page-card)` / `.vts-page-fill` 为 `height: 100%`；`.vts-page-card` 填满。`html/body/#app/.app-wrapper/.main-container/.app-main` 均为 `height:100%; overflow:hidden`。禁止业务页 `100vh` 减顶栏定高。
 
 ## 列表黄金样板（唯一完整示例）
 
 | # | 必须 |
 |---|------|
 | L1 | `el-card` + `class="vts-page-card"` + `ref="content"`（禁止挂 `div`） |
-| L2 | 固定 `height: calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`（禁止只用 `minHeight`） |
+| L2 | 不要写 `height: calc(100vh - …)` / 不要用 JS 测顶栏定高（壳层 + `.vts-page-card` 已填满） |
 | L3 | 查询区 `bg-bg_color p-5`；展示区 `ReTableBar class="bg-bg_color"` |
 | L4 | `ReGrid` `:gap="[0,20]"` + cols；表单项 `w-[100%] !mr-0`；`@should-show-collapse` |
-| L5 | 操作列 `<ReGridItem suffix>` |
+| L5 | 查询区 `<ReGridItem suffix>`（查询 / 重置 / 展开收起） |
 | L6 | 表格绑 `ref="multipleTableRef"` + `tableHeight`；分页在 `ReTableBar` `#default` 内、表格下方 |
 | L7 | `RePagination`：`:pagination` + `@handle-current-change` / `@handle-size-change` |
 | L8 | 查询与表之间的额外模块包一根元素绑 `otherRef`（须在表格上方，高度计入 `tableTop`） |
+| L9 | 表格操作列 `ReTableOperate :list`；按钮过多用 `limit`（默认 **3**）自动「更多」下拉，见下文专节 |
 
 ```vue
 <script setup lang="ts">
@@ -63,7 +67,7 @@ import { message } from "@/utils/message";
 
 defineOptions({ name: "CustomerList" });
 
-const { headerHeight, svgLoading } = useApp();
+const { svgLoading } = useApp();
 const formQuery = reactive<CustomerQuery>({ keyword: "", status: undefined });
 
 const {
@@ -125,9 +129,6 @@ function handleSizeChange(size: number) {
       ref="content"
       class="vts-page-card"
       shadow="never"
-      :style="{
-        height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`,
-      }"
     >
       <div>
         <el-form
@@ -236,7 +237,35 @@ function handleSizeChange(size: number) {
 </template>
 ```
 
-补充：`ReTableOperate` 用 `:list`；`defineOptions.name` === 路由 `name`；`headerHeight` / `svgLoading` 来自 `useApp()`。
+补充：`ReTableOperate` 用 `:list`；`defineOptions.name` === 路由 `name`；`svgLoading` 来自 `useApp()`；列表定高走壳层令牌 + `vts-page-card`。
+
+## 操作列按钮过多（ReTableOperate · 强制）
+
+落点：`src/components/ReTableOperate`。列表行操作**必须**用本组件，禁止手写一排 `el-button` / 自造「更多」菜单。
+
+### 行为（与模版一致）
+
+| 项 | 约定 |
+|----|------|
+| `limit` | 默认 **`3`**：可见按钮总数阈值（含「更多」槽位） |
+| ≤ `limit` | 全部以文字按钮平铺 |
+| > `limit` | 前 **`limit - 1`** 个平铺，其余进 **「更多」** `el-dropdown` |
+| 过滤顺序 | 先 `auth`（`hasAuth`）→ 再 `show(row)` → 再按 `limit` 折叠 |
+| `size` | 组件默认 `small`（行内紧凑）；可按列改 |
+
+示例：`limit=3` 且有 5 个可见按钮 → 平铺 2 个 +「更多」（内含后 3 个）。
+
+```vue
+<!-- 默认折叠阈值 3 -->
+<ReTableOperate :list="operateButtons" :row="row" :index="$index" />
+
+<!-- 需要多露几个时再改，勿低于 2（否则「更多」几乎占满） -->
+<ReTableOperate :list="operateButtons" :row="row" :index="$index" :limit="4" />
+```
+
+`OperateButton` 常用字段：`label`、`type`、`icon`、`auth`、`show`、`disabled`、`onClick`（见组件 `type.ts`）。危险操作用 `type: 'danger'`；权限写 `auth`，勿在列模板里 `v-if` 角色。
+
+操作列 `width`：按钮多时适当加宽（如 160～220），仍依赖 `limit` 折叠，禁止无限加宽硬塞。
 
 ## 列表 → 详情/编辑
 
@@ -343,10 +372,11 @@ async function onSubmit() {
 | 错误 | 正确 |
 |------|------|
 | `handleSearch` / 手写分页 | `onSearch` / `useTableSearch` |
-| `ref="content"` 挂 div / 只用 minHeight / 缺 `vts-page-card` | `el-card.vts-page-card` + 固定 height |
+| `ref="content"` 挂 div / `100vh` 减顶栏定高 / 缺 `vts-page-card` | `el-card.vts-page-card`（高度交给壳层） |
 | 不绑 `tableHeight` / 分页在卡片外 / 手写魔法数扣高度 | 样板 L6/L7；高度交给 `useTableSearch` |
 | 额外模块不绑 `otherRef` | L8 |
 | 只写 `toDetail`、详情路由缺 `activePath` | 三件套整段落盘（见 detail-page） |
 | 裸 `router.push` 开详情 | `toDetail` + meta（见 detail-page） |
 | `ReTableOperate :buttons` | `:list` |
+| 操作列手写多颗 `el-button` / 自造更多菜单 | `ReTableOperate`；过多靠 `limit`（默认 3）进「更多」 |
 | `@show-collapse` | `@should-show-collapse` |

package/references/design-handoff.md

@@ -1,32 +1,142 @@
 ---
 skill: design-handoff
-description: 设计产出物 → 业务项目样式落地。从会话/附件取交接块与令牌 CSS，按覆盖清单写入模版样式与配置。
+description: 设计产出物 → 业务项目样式落地。优先认 design-handoff/v1 JSON；兼容旧交接块与令牌 CSS。
 scope: project
-tags: [handoff, design-tokens, upstream, artifacts]
+tags: [handoff, design-tokens, upstream, artifacts, json]
 ---
 
 # 设计产出 → 模板落地
 
+## 双轨（必读）
+
+| 场景 | 行为 |
+|------|------|
+| **未调用设计 / 无 handoff** | 保持模版出厂令牌与 `platform-config`（主色 `#409EFF`、壳 64/208/40、margin 8、`ShowModel: chrome` 等）。**禁止**为「看起来像设计」而改出厂 |
+| **有 design-handoff/v1 或用户要求按设计落地** | 以**设计规范**为准全量回填 `design-tokens` + 配置；设计 JSON/规范未给出的字段**保留出厂**；代码层须已消费 `var(--token)`，改令牌即全局生效 |
+
+跨编辑器一致：设计侧 `handoff-output.md`（**JSON 字段形状**）+ 本文件（**→ 模版映射**）+ 模版 `design-tokens.scss` 注释对齐。  
+**分工**：设计师只改视觉规范正文，不维护本映射表；规范装进不了现有 JSON 时，由研发扩 `handoff-output` Schema 并同步改本文件。禁止只改文档不改令牌、或只改裸 px 不改令牌。
+
 ## 触发
 
 出现以下任一情况时执行本协议（与业务开发的先后跟用户需求：可先定风格再写业务，也可在已有业务上全量重构样式）：
 
-- 会话有「前端落地交接」块 / `【主题色系】` / `:root` 令牌 CSS
+- 会话 / 附件 / 仓库中有 **`design-handoff/v1` JSON**（优先）
+- 会话有「前端落地交接」块 / `【主题色系】` / `:root` 令牌 CSS（兼容）
 - 用户要求按设计稿 / 规范适配或重构整站风格
 - 用户附带色板、规范或 HTML 原型
 
-## 收集产出（会话 / 附件）
+动手改文件前先输出**规范识别回执**（见下文）。
+
+## 收集产出（优先级）
 
 | 优先 | 形态 | 用途 |
 |------|------|------|
-| 1 | 前端落地交接块 | `data-theme` / 侧栏 / DarkMode / 主色 |
-| 2 | 令牌 CSS（`--brand-*` / `--primary-*` 等） | 写入 `design-tokens.scss` |
-| 3 | 几何/间距数值 | 覆盖桥接令牌；缺则保留模版默认 |
-| 4 | HTML/CSS 原型 | 微调 `element-plus.scss` |
-| 5 | 项目已有 `design-tokens.scss` | 读现状 |
+| **1** | **`design-handoff/v1` JSON** | 结构化写入 tokens / 几何 / `ShowModel`（**首选**） |
+| 2 | 前端落地交接块 | `data-theme` / 侧栏 / DarkMode / 主色 |
+| 3 | 令牌 CSS（`--brand-*` / `--primary-*` 等） | 写入 `design-tokens.scss` |
+| 4 | 几何/间距数值 | 覆盖桥接令牌；缺则保留模版默认 |
+| 5 | HTML/CSS 原型 | 微调 `element-plus.scss` |
+| 6 | 项目已有 `design-tokens.scss` | 读现状 |
+
+定位 JSON：
+
+1. 会话中的 ` ```json ` 且含 `"$schema": "design-handoff/v1"`
+2. 仓库 `design/design-handoff.json`（或用户指定路径）
+3. 附件同名文件
+
+有 JSON 时：**以 JSON 为准**；交接块 / 零散 CSS 仅补 JSON 未覆盖字段。  
+无 JSON 时：回退优先 2～5（旧协议），并在回执中注明「建议补齐 design-handoff/v1」。
+
+缺主色阶 →「待确认」；有 `brandPrimary` 则可先落主色与壳桥接，不臆造 `primaryScale`。
+
+---
+
+## JSON → 模版映射（`design-handoff/v1`）
+
+设计侧 schema 见上游 `handoff-output.md`（字段名以下表为准）。
+
+### `meta` / `shell` → 配置
+
+| JSON 字段 | 落点 | 写入 |
+|-----------|------|------|
+| `tokens.brandPrimary` | `platform-config.json` → `EpThemeColor` | HEX；并 bump `Version` |
+| `shell.darkMode` | `platform-config.json` → `DarkMode` | boolean |
+| `shell.sidebar` | `platform-config.json` → `Theme` + 侧栏令牌 | `dark-gradient` → 深色侧栏主题（如 `default`）+ 写入 `--sidebar-*`；`light` → 浅色侧栏，勿套深色渐变 |
+| `shell.dataTheme` | `html[data-theme]` / 配置 | 有则用；无则按 sidebar/contentMode 推断，写回执 |
+| `shell.contentMode` | 内容区默认亮暗 | 与 DarkMode / 用户确认对齐 |
+| `shell.showModel` | `platform-config.json` → **`ShowModel`** | **以 JSON 为准**写入（设计当前默认 **`line`**；旧稿可能为 `card`） |
+| `shell.contentMargin` | `--layout-content-padding`（及桥接 `--vts-margin`） | 数字 px，如 `24`（模版出厂常为 **8**；**有 handoff 才覆盖**） |
+
+写入 `ShowModel` 后同步 `$storage.configure.showModel`（或 bump `Version` 清缓存）。  
+- **`card`**：写 `--vts-tag-card-*`（见 geometry）  
+- **`line`**：无容器文字页签（见 `notes` / `homeTabSize` / `tagDividerWidth`）；模版若尚未实现该枚举 → 回执「待实现 line」，**禁止**静默改成 `card`；可先落令牌与配置，页签样式单开任务  
+- **`chrome` / `smart`**：仅当 JSON 明确要求时写入
+
+### `geometry` → 令牌
+
+| JSON 字段 | CSS 变量（`design-tokens.scss` / 桥接） |
+|-----------|----------------------------------------|
+| `headerHeight`（JSON geometry） | `--header-height` / `--layout-header-height` |
+| `tabsHeight` | `--tabs-height`（壳层多标签栏；**不是** `--tabs-item-height`） |
+| `siderWidth` | `--sidebar-width` / `--layout-sider-width` |
+| `siderCollapsedWidth` | `--sidebar-collapsed-width` / `--layout-sider-collapsed-width` |
+| `contentPadding` / `shell.contentMargin` | `--layout-content-padding` → `--vts-margin`（不一致时以 `contentMargin` 为准并回执） |
+| `tagCardHeight` | `--vts-tag-card-height`（`showModel=card`） |
+| `tagCardRadius` | `--vts-tag-card-radius`（`showModel=card`） |
+| `tagCardGap` | `--vts-tag-card-gap`（`showModel=card`） |
+| `homeTabSize` | 首页纯图标页签边长（`showModel=line`，常见 40） |
+| `tagDividerWidth` | 页签间竖分割线宽（`showModel=line`，常见 1） |
 
-定位：扫会话交接块、`## 设计令牌`、`:root {`、附件中的 `--primary-` / 主色表。  
-缺项 →「待确认」；有主色则先落主色与壳桥接，不臆造色阶。
+可选（设计组件规范提及或 handoff.notes 给出时写入）：
+
+| 语义 | CSS 变量 | 出厂参考 |
+|------|----------|----------|
+| EP 内容 Tabs 项高 | `--tabs-item-height` | 46 |
+| 弹窗头/底高 | `--dialog-header-height` / `--dialog-footer-height` | 38 |
+| 弹窗 body 内边距 | `--dialog-body-padding` | 15 |
+| 弹窗圆角 | `--dialog-border-radius` | 10（设计落地可改 `--radius-lg`） |
+| 按钮水平 padding | `--button-padding-x` | 15 |
+| Switch | `--switch-min-width` / `--switch-height` / `--switch-border-radius` | 36 / 20 / 10 |
+| 页脚高 | `--layout-footer-height` | 48 |
+
+改几何后：**不要**让业务页重写 `100vh`；定高列表走 `%` / flex（`vts-page-card`）。
+
+**硬要求**：落地前 grep `src/layout`、`ReDialog`、`element-plus.scss` 壳层几何，确认消费的是 `var(--…)`；若仍有不可覆盖裸 px，**先改代码再写令牌**。
+
+### `tokens` → `design-tokens.scss`
+
+| JSON 字段 | CSS 变量 |
+|-----------|----------|
+| `brandPrimary` | `--brand-primary`；`--primary-5` / `--primary-color`；`--el-color-primary` 桥接保持 `var(--brand-primary)` |
+| `brandHover` | `--brand-hover` |
+| `brandActive` | `--brand-active` |
+| `primaryScale[0..9]` | `--primary-0` … `--primary-9`；并设 `--primary-hover` = scale[6]，`--primary-active` = scale[7]，`--primary-bg` = scale[0]（或设计指定），`--primary-bg-hover` = scale[1] |
+| `success` | `--success-color` |
+| `warning` | `--warning-color` |
+| `error` | `--error-color` 与 **`--error-6`**（同值） |
+| `errorBg` | `--error-bg`（有则写） |
+| `layoutBg` | `--layout-bg` |
+| `componentBg` | `--component-bg` |
+
+校验：`primaryScale.length === 10` 且 `primaryScale[5] === brandPrimary`；否则回执「待确认」并先写 brand，不瞎补色阶。
+
+### `componentSize` → 控件高度
+
+| JSON | 令牌 |
+|------|------|
+| `sm` | `--control-height-sm` / `--component-size-sm` / `--el-component-size-small` |
+| `base` | `--control-height` / `--component-size-base` / `--el-component-size` |
+| `lg` | `--control-height-lg` / `--component-size-lg` / `--el-component-size-large` |
+
+细则见 `design-system` 7.5.8。缺档 → 落到 default（base），回执注明。
+
+### 卡片页签关闭色（设计约束）
+
+- 关闭 hover：圆形底 `--layout-bg`（=`tokens.layoutBg`）+ 图标 `--error-6` / `tokens.error`（`#F5222D`）
+- **禁止**用 Element Plus 默认 danger `#F56C6C` 冒充错误色
+
+---
 
 ## 覆盖清单
 
@@ -34,13 +144,25 @@ tags: [handoff, design-tokens, upstream, artifacts]
 |---|------|------|
 | A | `src/styles/design-tokens.scss` | 令牌 CSS；深色侧栏时追加 `--sidebar-*` |
 | B | `theme.scss` 当前 `html[data-theme]` | `--vts-theme-*` → `--sidebar-*` |
-| C | `public/platform-config.json` | `EpThemeColor` / `Theme` / `DarkMode`；`Version` 自增 |
-| D | `index.scss` | `design-tokens` 的 `@use` 最前 |
-| E | `dark.scss` / 语义色 | 跟 `--primary-*` |
+| C | `public/platform-config.json` | `EpThemeColor` / `Theme` / `DarkMode` / **`ShowModel`**；`Version` 自增 |
+| D | `index.scss` | `design-tokens` 的 `@use` 最前；按需 `--vts-margin` / `--vts-tag-card-*` |
+| E | `dark.scss` / 语义色 | 跟 `--primary-*` / `--error-*` |
 | F | 冲突清单 | `design-system` 第四节 |
 | G | 规范识别回执 | 动手改文件前输出 |
+| H | （可选）`design/design-handoff.json` | 若用户要求落盘，写入校验后的 JSON 副本 |
 
-侧栏派生（交接为深色渐变时）：
+### 页签风格（ShowModel）
+
+模版出厂常见：`smart` / `chrome` / `card`。设计 handoff 当前默认 **`line`**（无容器文字页签，见上游 `handoff-output.md`）。
+
+| 场景 | `ShowModel` |
+|------|-------------|
+| 模版出厂、未落地设计 | 保持项目现有值，**勿强行改** |
+| 设计 handoff 落地 | **写入 JSON 的 `shell.showModel`**（默认 `line`；旧 JSON 可能为 `card`） |
+| JSON=`line` 且模版无实现 | 回执待实现；勿改写成 `card` |
+| 用户在设置面板手动切换 | 以用户选择为准 |
+
+侧栏派生（`shell.sidebar === "dark-gradient"` 时）：
 
 ```scss
 --sidebar-bg: linear-gradient(180deg, color-mix(in srgb, var(--primary-8) 88%, var(--primary-7)) 0%, var(--primary-9) 52%, color-mix(in srgb, var(--primary-9) 90%, #000) 100%);
@@ -57,27 +179,49 @@ tags: [handoff, design-tokens, upstream, artifacts]
 
 `theme.scss`：`--vts-theme-menu-bg: var(--sidebar-bg);` 等 → `layout-theme`。
 
+---
+
+## 规范识别回执（动手前必出）
+
+```markdown
+## 规范识别回执
+- 来源形态：design-handoff/v1 JSON | 交接块 | 令牌 CSS | 混合
+- 主题：{themeName} / {themeId} / 主色 {brandPrimary}
+- ShowModel：{json.showModel，如 line/card}（将写入）| 保持现有 | line 待实现
+- 几何：header {n} / tabs {n} / margin {n}
+- 主色阶：完整 10 级 | 仅 brand（待确认色阶）
+- 侧栏：dark-gradient | light
+- 将改文件：design-tokens.scss / platform-config.json / index.scss / …
+```
+
+---
+
 ## 顺序
 
-1. 收集产出 1～4  
+1. 收集产出（JSON 优先）  
 2. 规范识别回执  
-3. A→E  
-4. F  
-5. 验证侧栏/主色  
-6. 若同轮还有业务需求 → 再写/改 views（仅样式任务则到此结束）  
+3. A→E（按映射表写）  
+4. F 冲突核对  
+5. 验证侧栏 / 主色 / 页签（按 JSON `showModel`）/ 内容边距  
+6. 提醒清 `localStorage`（改了 `EpThemeColor` / `ShowModel` / `Version` 时）  
+7. 若同轮还有业务需求 → 再写/改 views（仅样式任务则到此结束）
 
-## 交接块字段
+---
+
+## 兼容：旧交接块字段
+
+无 JSON 时仍可认（可整块粘贴到会话）：
 
-```markdown
-## 前端落地交接
 - 设计来源：上游产出
-- 主题色系：<主题中文名>
-- data-theme：<模版 html[data-theme] 值>
-- 侧栏：<深色渐变|浅色>
-- 内容区默认：<亮色|暗黑>
-- 主色：<#HEX>
+- 主题色系：`<主题中文名>`
+- data-theme：`<模版 html[data-theme] 值>`
+- 侧栏：深色渐变 | 浅色
+- 内容区默认：亮色 | 暗黑
+- 主色：`#HEX`
+- ShowModel：以设计为准（当前规范默认 `line`；旧稿 `card`）| `smart` | `chrome`（未落地设计时保留模版默认）
+
+设计令牌 CSS 须含主色阶，并**建议含组件尺寸三档**：
 
-## 设计令牌（CSS）
 ```css
 :root {
   --brand-primary: #...;
@@ -85,8 +229,89 @@ tags: [handoff, design-tokens, upstream, artifacts]
   --brand-active: #...;
   --primary-0: #...;
   /* --primary-1 … --primary-9 */
+  --component-size-sm: 24px;
+  --component-size-base: 32px;
+  --component-size-lg: 40px;
 }
 ```
-```
+
+| 档位 | 像素 | EP / 通用 API | 模版令牌 |
+|------|------|---------------|----------|
+| small | 24px | `size="small"` | `--control-height-sm` / `--el-component-size-small` |
+| default | 32px | 不写 size | `--control-height` / `--el-component-size`【全站默认】 |
+| large | 40px | `size="large"` | `--control-height-lg` / `--el-component-size-large` |
 
 仅有交接块无令牌 CSS：写 `--brand-primary` + `EpThemeColor`，待确认注明缺色阶。
+
+---
+
+## 设计落地 · 全量令牌核对表（强制）
+
+> **出厂默认保留**；仅在有设计 handoff /「按设计规范适配」时执行。设计未给出的项勾「保留出厂」。漏项 = 硬失败风险。
+
+### A. 壳层与页签
+
+| 设计语义 | 写入令牌 | 缺省 |
+|----------|----------|------|
+| 顶栏高 | `--header-height` / `--layout-header-height` | 出厂 64 |
+| 多标签栏高 | `--tabs-height` | 40 |
+| 侧栏宽 / 收起 | `--sidebar-width` / `--sidebar-collapsed-width` | 208 / 64 |
+| 内容区内边距 | `--layout-content-padding` → `--vts-margin` | 出厂 8；设计常 24 |
+| 页脚高 | `--layout-footer-height` | 48 |
+| 页签风格 | `ShowModel` = JSON `shell.showModel`（默认 `line`；`card` 时写 `--vts-tag-card-*`） | 未落地勿改 |
+| 页签关闭/错误色 | `--error-color` / `--error-6`；`card` 时尚有 `--vts-tag-card-close-*` | `#F5222D` |
+
+### B. 色板与文字
+
+| 设计语义 | 写入令牌 | 缺省 |
+|----------|----------|------|
+| 主色 / hover / active | `--brand-*` + `EpThemeColor` | 出厂 `#409EFF` |
+| 主色 10 阶 | `--primary-0`…`--primary-9`、`--primary-5` | 无阶则待确认，至少 `--primary-5=brand` |
+| 成功/警告/错误 | `--success-color` / `--warning-color` / `--error-color` | 设计功能色 |
+| 中性文字/边框/底 | `--text-*` / `--border-*` / `--layout-bg` / `--component-bg` | 出厂 |
+| 弹窗渐变顶色 | `--primary-bg`、`--ds-dialog-bg` | 随 brand 浅混 |
+
+### C. 控件与反馈几何
+
+| 设计语义 | 写入令牌 | 缺省 |
+|----------|----------|------|
+| 控件三档 | `--control-height*` / `--component-size-*` / `--el-component-size*` | 24/32/40 |
+| 按钮水平 padding | `--button-padding-x` | 15 |
+| 圆角 | `--radius-sm/base/lg` | 4/6/8 |
+| Card 内边距 | `--card-padding` / `--vts-card-padding` | 24 |
+| Switch | `--switch-min-width/height/border-radius` | 出厂 36/20/10；设计若写 44×22 则覆盖 |
+| Tag | `--tag-height` / `--tag-line-height` | 22/20 |
+| EP 内容 Tabs 项高 | `--tabs-item-height` | 46（≠ 壳层 tabs） |
+| 菜单项高 | `--el-menu-item-height` | 40 |
+
+### D. 弹窗（出厂可保留；设计 Modal 规范出现则必须回填）
+
+| 设计语义（component-spec Modal 等） | 写入令牌 | 出厂（未设计时） |
+|----------|----------|------------------|
+| 弹窗圆角（设计常 8） | `--dialog-border-radius` | 10 |
+| 头/底高度或 padding | `--dialog-header-height` / `--dialog-footer-height` / padding 令牌 | 38 / 38 |
+| 内容区内边距 | `--dialog-body-padding` | 15 |
+| MessageBox 更紧凑 padding | `--message-box-*-padding` | 8×16 |
+
+回填后确认 `ReDialog` / MessageBox 已 `var(--…)` 消费（改令牌即变，无需改业务页）。
+
+### E. 落地后自检
+
+- [ ] `platform-config`：`EpThemeColor` / `ShowModel` / `Theme` / `DarkMode` / `Version++`
+- [ ] 侧栏深色渐变时 `--sidebar-*` + `theme.scss` 桥接
+- [ ] grep 壳层与 ReDialog：无不可覆盖裸 px
+- [ ] 列表页仍无 `100vh` 减顶栏；margin 变化后 flex 链正常
+- [ ] 回执列出「已覆盖 / 保留出厂」字段清单
+
+---
+
+## 硬失败（code-quality 可引用）
+
+| 条件 | 处理 |
+|------|------|
+| 用户要求按设计落地，但未写入 JSON 中的 `shell.showModel` | 硬失败：按 JSON 补写配置（默认常为 `line`） |
+| JSON 有 `primaryScale` 但未写入 `--primary-0..9` | 硬失败 |
+| 用 `#F56C6C` 或未映射的 EP danger 代替 `tokens.error` | 硬失败：改为 `#F5222D` / `--error-color` |
+| 改了 `--layout-content-padding` / `--vts-margin` 后列表仍用 `100vh` 减顶栏定高 | 硬失败：迁 flex/`vts-page-card` |
+| 设计落地后壳层/弹窗写死 px、改令牌不生效 | 硬失败：消费点改为 `var(--…)` 再回填 |
+| 设计落地核对表（壳/色/控件/弹窗）有漏项且未标「保留出厂」 | 硬失败：补回填或回执注明 |