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

package/references/design-handoff.md

@@ -1,32 +1,136 @@
 ---
 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)`，改令牌即全局生效 |
+
+跨编辑器一致：本协议 + 模版 `design-tokens.scss` 注释 + `handoff-output.md` 字段名对齐；禁止只改文档不改令牌、或只改裸 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`** | 设计落地时**必须** `"card"` |
+| `shell.contentMargin` | `--layout-content-padding`（及桥接 `--vts-margin`） | 数字 px，如 `24`（模版出厂常为 **8**；**有 handoff 才覆盖**） |
+
+落地 `card` 时同步：`ShowModel: "card"` + `$storage.configure.showModel`（或 bump `Version` 清缓存）+ 按下表写 `--vts-tag-card-*`。
+
+### `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` |
+| `tagCardRadius` | `--vts-tag-card-radius` |
+| `tagCardGap` | `--vts-tag-card-gap` |
 
-定位：扫会话交接块、`## 设计令牌`、`: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 +138,24 @@ 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`（卡片·设计规范）。
+
+| 场景 | `ShowModel` |
+|------|-------------|
+| 模版出厂、未落地设计 | 保持项目现有值（常见 `chrome` / `smart`），**勿强行改** |
+| 设计规范 / handoff 落地 | **必须**切到 `card`（对齐设计 TDesign 卡片页签） |
+| 用户在设置面板手动切换 | 以用户选择为准 |
+
+侧栏派生（`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 +172,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：card（将写入）| 保持现有
+- 几何：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. 验证侧栏 / 主色 / 卡片页签 / 内容边距  
+6. 提醒清 `localStorage`（改了 `EpThemeColor` / `ShowModel` / `Version` 时）  
+7. 若同轮还有业务需求 → 再写/改 views（仅样式任务则到此结束）
 
-## 交接块字段
+---
+
+## 兼容：旧交接块字段
+
+无 JSON 时仍可认（可整块粘贴到会话）：
 
-```markdown
-## 前端落地交接
 - 设计来源：上游产出
-- 主题色系：<主题中文名>
-- data-theme：<模版 html[data-theme] 值>
-- 侧栏：<深色渐变|浅色>
-- 内容区默认：<亮色|暗黑>
-- 主色：<#HEX>
+- 主题色系：`<主题中文名>`
+- data-theme：`<模版 html[data-theme] 值>`
+- 侧栏：深色渐变 | 浅色
+- 内容区默认：亮色 | 暗黑
+- 主色：`#HEX`
+- ShowModel：`card`（设计落地时）| `smart` | `chrome`（未落地设计时保留模版默认）
+
+设计令牌 CSS 须含主色阶，并**建议含组件尺寸三档**：
 
-## 设计令牌（CSS）
 ```css
 :root {
   --brand-primary: #...;
@@ -85,8 +222,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: card` + `--vts-tag-card-*` | 未落地勿改 |
+| 卡片页签关闭色 | `--error-color` / `--error-6`、`--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 可引用）
+
+| 条件 | 处理 |
+|------|------|
+| 用户要求按设计落地，但未切 `ShowModel: card` | 硬失败：补写配置 |
+| 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(--…)` 再回填 |
+| 设计落地核对表（壳/色/控件/弹窗）有漏项且未标「保留出厂」 | 硬失败：补回填或回执注明 |

package/references/design-system.md

@@ -9,11 +9,20 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 
 识别规范后，在业务项目完成：令牌层（数据）+ 模版样式改写（执行）+ 硬编码冲突清理。之后业务只引令牌，禁止裸值。组件层仍是 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` | 基础与壳变量 |
+| `reset.scss` / `index.scss` | 基础与壳变量桥接 |
 | `theme.scss` / `sidebar.scss` | 侧栏/导航 |
 
 禁止另建独立「重写层」文件。
@@ -75,14 +84,14 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 
 ### Step 0 上游设计产出落地（优先于 Step 1）
 
-**触发**：会话存在设计交接块 / `【主题色系】` / 令牌 CSS（`:root` + `--primary-*` 等）产出。
+**触发**：会话 / 仓库存在 **`design-handoff/v1` JSON**，或设计交接块 / `【主题色系】` / 令牌 CSS（`:root` + `--primary-*`）。
 
 **动作**：
 
 1. 读 `references/design-handoff.md`。
-2. 从会话/附件收集交接块与令牌 CSS，按 handoff 覆盖清单落地。
+2. **优先**收集 `design-handoff/v1` JSON；无 JSON 再收集交接块与令牌 CSS。按 handoff 映射表与**全量令牌核对表（A～E）**落地，设计未给出的项回执标明「保留出厂」。
 3. 比对项目 `design-tokens.scss` / `platform-config.json` 与产出主色；不一致则先落地。
-4. 识别回执：`规范来源` = 上游产出 / 交接块；`目标规范` = `custom:<上游主题名>`。
+4. 识别回执：`规范来源` = design-handoff/v1 | 交接块 | 混合；`目标规范` = `custom:<上游主题名>`。
 5. 模版仍为出厂 `Theme: light` + `#409EFF` 且本轮要改依赖主题的页面时，同轮先完成样式覆盖清单。
 
 ### Step 1 探查现状（含命名锁定与模版版本判定）
@@ -136,17 +145,23 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
   --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: 56px;
+  --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: #ff4d4f;
+  --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;
@@ -171,7 +186,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: linear-gradient(to bottom, var(--primary-bg), var(--component-bg)); /* 弹窗/MessageBox 背景；index.scss 桥接 --vts-dialog-bg */
+  --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 生效前的首屏主色 */
@@ -229,7 +244,7 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 /* —— 按钮 —— */
 .el-button {
   height: var(--control-height);
-  padding: 0 15px;
+  padding: 0 var(--button-padding-x, 15px);
   font-size: var(--font-size-base);
   font-weight: var(--font-weight-regular);
   border-radius: var(--radius-base);
@@ -315,21 +330,21 @@ 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: var(--dialog-header-padding); margin-right: 0; }
+.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-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-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: 46px; padding: 0 var(--vts-space-md, 16px); }
+.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);
@@ -361,7 +376,7 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 
 ### Step 5 模版硬编码冲突处理（按模版版本二选一，逐条回填）
 
-- **4.A（新模版，已变量化）**：模版样式均为 `var(--x, 默认值)` 形式，Step 2 的「模版桥接令牌」段已自动接管。**逐条确认**桥接令牌齐全即可，`--vts-dialog-bg` 已变量化为 `var(--ds-dialog-bg, 原值)`，确认桥接段含 `--ds-dialog-bg: var(--el-bg-color-overlay)` 即完成接管。
+- **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（旧模版）**：按第四节冲突清单**逐条手工处理**。
 
 **无论走哪条路**，处理完必须：
@@ -390,7 +405,7 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
    | `sidebar.scss` | 侧栏执行 | 背景用 `background: var(--vts-theme-menu-bg)`（支持渐变）；激活块 `--vts-theme-menu-active-bg`；边框 `--vts-sidebar-border-color` |
    | `dark.scss` | 暗黑侧栏 | **禁止** `sidebar-container { background-color: var(--el-bg-color) }` 压盖渐变；改用 `background: var(--vts-theme-menu-bg)` |
    | `platform-config.json` | 顶栏/主题 | `EpThemeColor` = 规范 primary-5；深色侧栏时 `Theme: default`（或对应 data-theme） |
-   | `layout/components/lay-tag` | 页签栏高度 | 走 `--vts-tabs-height`（桥接 `--tabs-height`） |
+   | `layout/components/lay-tag` | 页签栏高度 / 风格 | 高度走 `--vts-tabs-height`；设计落地时 `ShowModel: 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` 第三节规则。
@@ -447,7 +462,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | 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 { padding: 5px !important }` | AntD 卡片内边距 24px | 已变量化 `var(--vts-card-padding, 5px)` | 改为 `var(--vts-card-padding) !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` 令牌 |
@@ -455,7 +470,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | 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-bar-height: 38px`、`--vts-margin: 8px` | 与规范导航高度（AntD Pro 56px）不一致 | 令牌可覆盖 | 令牌层覆盖并回归验证列表页 `calc(100vh - ...)`；默认保持不变标注差异 |
+| 14 | `index.scss` | `--vts-margin` / `--layout-content-padding` 出厂 8px | 设计 handoff 常覆盖为 24 等 | 令牌可覆盖 | 定高列表走 `%`/flex（`vts-page-card`）；禁止业务页 `100vh` 减顶栏定高 |
 | 15 | `button.scss` | `.btn/.golang/.php` 演示按钮（122×44 等） | 仅演示用，影响小 | 不处理 | 业务禁止使用这些类名 |
 
 ---
@@ -469,7 +484,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | `--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` / `#ff4d4f` | `#00b42a` / `#ff8d1a` / `#fb2323` | `#00b42a` / `#ff7d00` / `#f53f3f` | `#4caf50` / `#fb8c00` / `#f44336` | `#029e74` / `#f7ba2a` / `#e2231a` |
+| 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 |
@@ -504,9 +519,12 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 ### 7.1 产出物识别
 
-1. 会话中的设计交接块 / 令牌表 / HTML 原型
-2. 用户提供的含 `:root { --... }` 的文件或规范文档
-3. 特征：`--brand-*` / `--primary` / `colorPrimary` / design token 表
+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 令牌归一化（上游命名 ≠ 本模块标准名）
 
@@ -518,7 +536,9 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | `--brand-hover` / `--brand-active` | `--primary-hover` / `colorPrimaryHover` / 主色-悬浮 |
 | `--font-size-base` | `--font-size` / `fontSizeBase` / 基础字号 |
 | `--radius-base` | `--border-radius` / `borderRadius` / 圆角 |
-| `--control-height` | `--component-size` / `controlHeight` / 控件高度 |
+| `--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` / 页面背景 |
 
@@ -558,7 +578,8 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | 模版标准令牌（`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 |
+| `--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` |
@@ -606,8 +627,8 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 2. `index.scss`：桥接 `--vts-bar-height` / `--vts-tabs-height` / `--vts-layout-header-offset*` 仍指向源令牌  
 3. `SidebarLogo.vue`、`lay-navbar`：高度/行高仍 `var(--vts-bar-height)` 或等价引用  
 4. `sidebar.scss`：`calc(100% - var(--header-height) - var(--sidebar-collapse-bar-height))`，禁止写死 px 组合  
-5. `lay-content/index.vue`：`padding-top` 用 `--vts-layout-header-offset*`，禁止写死旧顶栏组合；**禁止**与 `$storage.configure.headerHeight` 双向联动  
-6. `lay-header`：布局/标签页变化须 `nextTick` 重测，且仅在高度变化时写回 `$storage.configure.headerHeight`  
+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 变化
 
@@ -617,7 +638,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 #### 7.5.5 查询区尺寸（core-kernel 黄金样板）
 
-列表页查询区 **`el-form` 不写 size**（default 中号，32px），查询/工具栏按钮随表单继承；**禁止**查询区单独写 `size="small"` 导致输入框与按钮档位不一致。
+列表页查询区 **`el-form` 不写 size**（default 中号 = `--control-height` / 设计 `--component-size-base`，默认 32px），查询/工具栏按钮随表单继承；**禁止**查询区单独写 `size="small"` 导致输入框与按钮变成 24px 档。
 
 #### 7.5.6 适配完成验证（Step 8 补充）
 
@@ -625,12 +646,33 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 - [ ] 主内容区 `padding-top` = 当前 `--layout-header-offset`（或桥接 `--vts-layout-header-offset`）  
 - [ ] 顶栏 / 页签 / 侧栏 / 菜单项 computed 尺寸 = 当前对应令牌值  
 - [ ] 执行层 grep 无壳层裸 px 残留（EP 菜单根上的具体 px 须与 `--el-menu-item-height` 一致）  
-- [ ] 查询区 input 与 button 高度一致（small 档）
+- [ ] 查询区 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` 与表单控件档位是两套体系，改表单令牌时不要误改表格密度全局配置（除非用户要求）。
+
 ---
 
 ## 八、反例（短）
@@ -647,4 +689,6 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | 业务页裸写控件高度 | 只引令牌 |
 | 只写令牌不改壳层执行层 | 执行 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` 或上游产出 |