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

package/README.md

@@ -73,3 +73,4 @@ npx @qilitt-mickey/vue3-temp-skill@latest install all
 - **标准样板**：在本包 `references/`，不在模板 `views/`
 - 壳层以当前项目源码为准；规范与安装表以本包为准
 - HTTP：`axios@1.19.0` 固定版本，仅经 `@/utils/http`
+- **`docs/` 只读**：模板 `docs/**`（如风格演示页）为静态文档说明，**不随业务代码同步修改**；仅用户明确要求维护文档时才改动

package/SKILL.md

@@ -7,24 +7,24 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 # Vue 3 项目开发规范技能包
 
-执行顺序：运行 `python scripts/match.py "<需求>"` 获取精确匹配 → 按 `load_files` 读参考文件 → 生成 → 按 `quality_gates` 检查 → 执行 `code-quality` → 回复含审查结果块。
-
-> **模块路由优先用脚本**：`python scripts/match.py "需求描述"` 输出 JSON，含命中模块、同批加载、闸门项、加载文件清单。AI 按此结果加载文件，不自行推理匹配。无 Python 环境时回退至下方路由表手动匹配。
-
-### 脚本工具
-
-| 命令 | 用途 |
-|------|------|
-| `python scripts/match.py "<需求>"` | **运行时匹配器**（AI 调用）：输出命中模块、同批加载、闸门项、文件清单 |
-| `python scripts/match.py --batch` | 批量测试 15 个典型场景 |
-| `npm run check` | **发布前全量检查**（5 项任一失败即中断） |
-| `npm run validate` | 结构校验：frontmatter、路由表一致性、孤立模块、交叉引用 |
-| `npm run audit` | 命中精度审计：关键词重叠、盲区、模块评分、边界冲突 |
-| `npm run content` | 内容可用性审计：样板完整性、Must-do 清单 |
-| `npm run deps` | 依赖图分析：断链、循环依赖、引用热度 |
-| `npm run match:batch` | 批量测试（npm 封装） |
-| `node scripts/cli.mjs --list` | 列出所有可用命令 |
-
+执行顺序：运行 `python scripts/match.py "<需求>"` 获取精确匹配 → 按 `load_files` 读参考文件 → 生成 → 按 `quality_gates` 检查 → 执行 `code-quality` → 回复含审查结果块。
+
+> **模块路由优先用脚本**：`python scripts/match.py "需求描述"` 输出 JSON，含命中模块、同批加载、闸门项、加载文件清单。AI 按此结果加载文件，不自行推理匹配。无 Python 环境时回退至下方路由表手动匹配。
+
+### 脚本工具
+
+| 命令 | 用途 |
+|------|------|
+| `python scripts/match.py "<需求>"` | **运行时匹配器**（AI 调用）：输出命中模块、同批加载、闸门项、文件清单 |
+| `python scripts/match.py --batch` | 批量测试 15 个典型场景 |
+| `npm run check` | **发布前全量检查**（5 项任一失败即中断） |
+| `npm run validate` | 结构校验：frontmatter、路由表一致性、孤立模块、交叉引用 |
+| `npm run audit` | 命中精度审计：关键词重叠、盲区、模块评分、边界冲突 |
+| `npm run content` | 内容可用性审计：样板完整性、Must-do 清单 |
+| `npm run deps` | 依赖图分析：断链、循环依赖、引用热度 |
+| `npm run match:batch` | 批量测试（npm 封装） |
+| `node scripts/cli.mjs --list` | 列出所有可用命令 |
+
 > `npm run release` 会自动先执行全量检查，通过后才升版本、提交、发布。
 
 ## 术语约定
@@ -44,10 +44,12 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 - 面向由 **vue3-web-temp** 脚手架搭出的业务项目（目录名/安装路径因人而异，以当前工作区为准）
 - **文档分工**：人类读模板 `README.md`；AI 读模板 `AGENTS.md` + 本 Skill；样板与细则在本包 `references/`
+- **`docs/` 只读边界**：模板仓库 `docs/**`（如 `docs/style-templates/`）为**静态文档/演示说明**，仅供人类预览与沟通参考；**禁止**在业务开发、设计落地、重构、联调等场景中同步修改其中的文件。`docs/` 内示例代码**不跟随** `src/` 等业务代码联动更新；仅当用户**明确要求**维护文档本身时方可改动
 - **精简出厂**：模板 `views/` 仅保留登录/首页等壳页面；**业务标准样板**在本包 `references/`（如 `crud-pages`、`detail-page`）
 - **依赖分层**：`package.json` 仅 **core**；**addon** 默认不装；缺包时装依赖后须按 `addon-enable.md` **逐文件恢复配置**（非自动）
 - 壳层行为（顶部 tag / 侧栏 / keep-alive / `useDetail`）以**当前项目**已有实现为准
-- **双轨**：无设计 handoff → 保持模版出厂；有设计落地 → 读 `design-handoff.md` 逐文件修改清单 + 设计 Skill `project-implementation-protocol.md`
+- **双轨**：无设计 handoff → 保持模版出厂；有设计落地 → 读 `design-handoff.md` 逐文件修改清单（含 1:1 还原要求 F1-F14 / P1-P7）
+- **设计优先级**：当设计技能产出（`design-handoff/v1` JSON）存在时，视觉层面（布局/间距/圆角/阴影/色彩/组件结构）以设计技能产出为准，本技能出厂默认值按设计产出替换。详见下方「设计优先级与 handoff 强制执行」段
 
 ## 使用方式
 
@@ -63,6 +65,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 4. 无对应能力 → 标注「待确认」，未经同意不引入新依赖
 5. 权威性优先级：`仓库已有封装` > `本 Skill 示例` > 通用 Vue 习惯
 6. 命中 addon / 缺依赖：读 `project-inventory` 第九/十节 + **`addon-enable.md`**（逐文件恢复代码）；精确版本安装，禁止 `@latest`
+7. **`docs/**` 不参与业务落盘**：模板 `docs/` 为静态文档/演示说明，禁止随 `src/` 等业务改动同步修改；仅用户明确要求维护文档时才改
 
 ## 完整性守则（全模块强制）
 
@@ -73,6 +76,10 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 3. **Hook ≠ 壳层自动**：`toDetail` 写 tag；侧栏高亮 / keepAlive 靠路由 meta；`http` 加解密靠环境开关，不靠单请求配置
 4. **大范围交付仍须逐模块核对硬失败表**，禁止以 lint 通过代替硬失败表逐项核对
 
+## 设计落地（handoff）
+
+设计技能（project-ui-design）每次产出时**始终自动附加 `design-handoff/v1` JSON**。本技能检测到 JSON 后**强制加载** `references/design-handoff.md`，按 C/T/F/S/P 五步全流程执行（配置→令牌→框架→样式→页面），**任一步跳过 = 硬失败**。设计产出优先级高于本技能出厂默认值，页面保留业务逻辑、重写视觉结构。用户无需提及「JSON」或「handoff」——这是两技能间的自动协议。完整规则与逐项清单见 `design-handoff.md`。
+
 ## 模块路由表
 
 ### 始终加载
@@ -88,8 +95,8 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 | addon / 查 Re* 名 / 装依赖 | `references/project-inventory.md` |
 | **启用精简模板已删的 addon（装包 + 改配置）** | `references/addon-enable.md`（与功能模块同读） |
 | 写完代码后（闸门，非功能命中） | `references/code-quality.md` |
-| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md`（逐文件修改清单）+ `design-system.md`（项目设计系统说明） |
-| **设计模式**（设计 Skill 产出存在时触发） | `crud-pages.md` 设计模式样板 + 设计 Skill `project-implementation-protocol.md`（1:1 还原协议） |
+| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md`（逐文件修改清单）+ `design-system.md`（项目设计系统说明） |
+| **设计模式**（设计 Skill 产出存在时触发） | `crud-pages.md` 设计模式样板 + `design-handoff.md` 1:1 还原要求（F1-F14 / P1-P7） |
 
 ### 标准业务面
 
@@ -142,7 +149,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 1. 单模块 → 该模块 + `core-kernel`；结束后执行 `code-quality`
 2. 多模块 → 同时加载（例：客户列表 = `crud-pages` + `permission-auth` + `http-api`）
 3. 未命中模块 → 仅 `core-kernel`，向用户确认是否专项
-4. 默认不改 `vite.config.ts` / `build/**`；**例外**：按 `addon-enable.md` 恢复 FileViewer / VantResolver / Vconsole 等占位插件时允许改 `build/plugins/*`
+4. 默认不改 `vite.config.ts` / `build/**` / **`docs/**`**；**例外**：按 `addon-enable.md` 恢复 FileViewer / VantResolver / Vconsole 等占位插件时允许改 `build/plugins/*`；`docs/**` 无例外，须用户明确要求才改
 5. 效果匹配：
    - 启用 echarts / vant / file-viewer / 富文本等已删 addon → 功能模块 + **`addon-enable`**
    - 弹窗、对话框、抽屉 → `form-advanced`
@@ -164,7 +171,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
    - 批量操作、表格排序 → `crud-pages`
    - 趋势图、地图、甘特图 → `chart-echarts`
    - 附件上传、断点续传 → `file-management`
-   - 按 XX / UI 规范适配、设计交接块、整站风格重构 → `design-system`（项目设计系统说明）+ `layout-theme`；有令牌/交接产出时加读 `design-handoff.md`（逐文件修改清单）+ 设计 Skill `project-implementation-protocol.md`
+   - 按 XX / UI 规范适配、设计交接块、整站风格重构 → `design-system`（项目设计系统说明）+ `layout-theme`；有令牌/交接产出时加读 `design-handoff.md`（逐文件修改清单，含 1:1 还原 F1-F14 / P1-P7）
    - 列表→独立详情/编辑页 → `crud-pages` + `detail-page`
    - 图表（折线/柱状/饼图） → `chart-echarts`
    - 数据大屏、看板 → `data-screen`
@@ -188,11 +195,11 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 ## 工作流
 
 1. **需求分析**：列出功能模块 ID（不含 `code-quality`）
-2. **加载**：`core-kernel` + 命中模块；addon/缺包时加读 `project-inventory` + **`addon-enable`**；设计规范/交接产出时加读 `design-handoff`（逐文件修改清单）+ 设计 Skill `project-implementation-protocol.md`
+2. **加载**：`core-kernel` + 命中模块；addon/缺包时加读 `project-inventory` + **`addon-enable`**；**检测 design-handoff/v1 JSON 是否存在** — 若存在，强制加载 `design-handoff`（逐文件修改清单，含 C/T/F/S/P 全流程）+ `design-system.md`，并按设计产出优先级执行
 3. **依赖**：缺包按 inventory 第九节精确版本，确认后安装；**再按 `addon-enable` 对应章节改配置**
 4. **探查**：复用仓库 `Re*` / Hook / utils
-5. **生成**：可运行代码落盘
-6. **code-quality**：按 `references/code-quality.md` 执行
+5. **生成**：可运行代码落盘至 `src/` 等业务目录；**禁止**同步修改 `docs/**`（除非用户明确要求维护文档）；**有 handoff JSON 时，页面结构以设计输出为准，保留业务逻辑**
+6. **code-quality**：按 `references/code-quality.md` 执行；**有 handoff JSON 时，额外执行 handoff 落地完整性校验**（见 `design-handoff.md` 末尾）
 7. **输出**：变更说明（含已改配置文件列表）+ 待确认项
 
 ### 最终回复结构
@@ -205,11 +212,13 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 - 闸门：已执行 code-quality（生成后）
 - 清单：选型 / 类型 / 组件 / API / 安全 / 业务 / 列表→详情(如适用) / 列表布局(如适用) / 风格 / addon启用(如适用) → 通过 | 已修正：…
 - 硬失败：无 | 已拦截并修正：…
+- handoff 落地（如有 JSON）：C/T/F/S/P 全流程已执行 → 通过 | 未完成项：…（硬失败）
 - 命令：`pnpm lint:fix` → …；`pnpm type-check` → …
 - 待确认：…
 
 ## 变更说明
 - …
+- 移除/新增元素（如有 handoff）：按设计输出移除了…/新增了…（供用户确认）
 ```
 
 ## 文件索引

package/package.json

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

package/references/code-quality.md

@@ -49,17 +49,55 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 | `element-plus.scss` 内视觉规则（shadow/hover/transition） | 出现非令牌引用的裸 hex / px / rgba 值 | 全部改为 `var()` 引用令牌 |
 | 视觉规则新增 | `dark.scss` 缺少对应暗色覆盖 | 每条新规则在 `html.dark` 内有对应覆盖 |
 
-### 设计模式专项检查（设计 Skill 产出存在时）
-
-设计还原的完整检查清单见设计 Skill 的 `project-implementation-protocol.md`。本闸门只检查项目侧落地结果：
-
-| 检查项 | 失败条件 | 修复 |
-|--------|---------|------|
-| 页面区域结构 | JSON `structureRequirements.pageRegions` 指定的区域在页面中缺失 | 按 `crud-pages.md` 设计模式样板 D1-D8 补充 |
-| 框架壳层 | JSON `structureRequirements.frameworkShell` 指定的壳层配置未落地 | 按 `design-handoff.md` 配置文件修改清单 C1-C8 执行 |
-| 交互行为 | JSON `interactionSpecs` 指定的交互未实现 | 按 `project-implementation-protocol.md` 交互保真要求实现 |
-| 令牌引用 | 页面代码中 CSS 钩子类对应的值非令牌引用 | 值来自 `design-tokens.scss` 令牌变量 |
-| 逐文件修改清单 | `design-handoff.md` 清单中有未执行项 | 补齐遗漏项 |
+### 设计模式专项检查（设计 Skill 产出或指定设计规范时强制执行）
+
+> 任一项未通过 = 硬失败，必须修正后重新生成。
+> 对照 `design-handoff.md` 硬失败表 + 元素自查隐藏清单逐项核查。
+
+#### 配置层（4 项）
+
+- [ ] `platform-config.json` 的 `EpThemeColor` 与设计主色一致
+- [ ] `Theme` 与侧栏风格对应（`dark-gradient` → `default`）
+- [ ] `ShowModel` 与页签风格一致
+- [ ] `Version` 已自增
+
+#### 令牌层（5 项）
+
+- [ ] `--primary-0` ~ `--primary-9` 完整 10 级色阶
+- [ ] 几何尺寸令牌与设计一致（header/tabs/sidebar/margin）
+- [ ] 控件高度令牌与设计一致（`--control-height*`）
+- [ ] 视觉令牌完整（shadow/transition/transform）
+- [ ] 无硬编码 hex 值出现在令牌以外的位置
+
+#### 框架层（7 项）
+
+- [ ] 顶栏元素组成与设计一致（不多不少：设置/通知/全屏/搜索/面包屑）
+- [ ] 语言切换为内联文字（非下拉框）
+- [ ] 侧栏底部折叠按钮设计无则已隐藏（折叠按钮移至顶部）
+- [ ] 菜单 hover 折叠功能设计无则已禁用
+- [ ] 菜单激活态：品牌色极浅底 + 右侧强调条（非纯蓝底白字）
+- [ ] 页签横线居中，关闭按钮行为正确
+- [ ] Logo 区：品牌色方块 + 白字首字（非默认彩色图标）
+
+#### 样式层（6 项）
+
+- [ ] 卡片 hover 有浮起效果（transform + shadow）
+- [ ] 按钮 hover 有上浮效果（位移 + 阴影）
+- [ ] 输入框聚焦有光环（品牌色边框 + 外阴影）
+- [ ] 表格行 hover 有品牌色底
+- [ ] 展开收起按钮 hover 文字不变淡（加深为品牌色）
+- [ ] 所有视觉规则在暗色模式下有对应覆盖
+
+#### 页面层（8 项）
+
+- [ ] 页面有标题区（`.vts-page-header`：标题 + 描述 + 操作按钮）
+- [ ] 筛选区有容器感（`.vts-filter-area`：背景 + 底部分割线）
+- [ ] 操作栏存在（`.vts-action-bar`：批量操作 + 工具按钮）
+- [ ] 表格区有包裹感（`.vts-table-area`）
+- [ ] 状态标签样式符合规范（filled/outlined/solid 按列分配）
+- [ ] 操作列统一为文字链接 + "更多"下拉（ReTableOperate）
+- [ ] 设计中未体现的元素已隐藏/移除（对照元素自查隐藏清单）
+- [ ] 所有样式值引用 CSS 变量，无裸 hex/px 值
 
 ## 选型与硬约束
 

package/references/core-kernel.md

@@ -27,6 +27,7 @@ tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
 | 12 | 列表布局按 **`crud-pages` 标准样板**（`el-card.vts-page-card`+`content`、无 `100vh` 减顶栏定高、`tableHeight`、`otherRef`、分页在 ReTableBar 内；仅表格体内滚动） |
 | 13 | addon 按 `project-inventory` 第九节精确版本安装；禁止 `@latest` |
 | 14 | 样式契约见下文「样式契约」 |
+| 15 | **`docs/**` 禁止随业务改动**：模板 `docs/` 为静态文档/演示（如 `style-templates/`），不参与业务落盘；除非用户明确要求维护文档，否则不得修改、同步或「对齐」其中文件 |
 
 ## 二、应用壳
 
@@ -156,7 +157,16 @@ export function getCustomerList(data: CustomerQuery, url: string) {
 | addon 构建 | FileViewer / vConsole 等在精简模板中为占位；安装后按对应模块恢复 `build/plugins/*` |
 | addon 类型检查 | 未装 addon 时相关路径在 `tsconfig exclude`；**装包后须手动移除**对应项 → 见 `project-inventory` **第十节**（非自动） |
 
-非用户要求不改 `vite.config.ts` / `build/**`。
+非用户要求不改 `vite.config.ts` / `build/**` / **`docs/**`**。
+
+### docs/ 目录（只读）
+
+| 项 | 说明 |
+|----|------|
+| 用途 | 人类可读文档、UI 风格演示页（`docs/style-templates/`）等 |
+| 与业务关系 | **不参与**业务开发落盘；其中示例代码**不跟随** `src/` 等业务实现同步修改 |
+| AI 行为 | 默认**不读、不改、不引用为落盘目标**；仅用户明确要求更新文档本身时可改 |
+| 参考方式 | 风格选型可**只读浏览**演示页后与用户沟通；中后台功能页仍按 Skill 标准样板在 `src/` 实现 |
 
 ## 八、环境变量
 

package/references/crud-pages.md

@@ -492,18 +492,54 @@ function handleSizeChange(size: number) {
 </template>
 ```
 
-**设计模式与出厂模式的关键差异**：
-
-| 差异点 | 出厂模式 | 设计模式 | JSON 来源 |
-|--------|---------|---------|-----------|
-| 页面标题 | 无 | `.vts-page-header` 含标题+描述+操作 | `structureRequirements.pageRegions.header` |
-| 筛选区 | `bg-bg_color p-5` | `.vts-filter-area`（容器感+分隔线） | `structureRequirements.pageRegions.filter` |
-| 主操作按钮位置 | `ReTableBar #buttons` | `.vts-page-header__actions` | `structureRequirements.pageRegions.header.actions` |
-| 表格区 | 无包裹 | `.vts-table-area`（圆角边框） | `structureRequirements.pageRegions.table` |
-| 表头底色 | EP 默认浅灰 | 由 `element-plus.scss` 全局提供品牌色浅底+强调线 | `visual.tableHeader` |
-| 行 hover | EP 默认灰色 | 由 `element-plus.scss` 全局提供品牌色极浅底 | `visual.rowHover` |
+**设计模式与出厂模式的关键差异**：
+
+| 差异点 | 出厂模式 | 设计模式 | JSON 来源 |
+|--------|---------|---------|-----------|
+| 页面标题 | 无 | `.vts-page-header` 含标题+描述+操作 | `structureRequirements.pageRegions.header` |
+| 筛选区 | `bg-bg_color p-5` | `.vts-filter-area`（容器感+分隔线） | `structureRequirements.pageRegions.filter` |
+| 主操作按钮位置 | `ReTableBar #buttons` | `.vts-page-header__actions` | `structureRequirements.pageRegions.header.actions` |
+| 操作栏 | 无独立操作栏 | `.vts-action-bar`（批量操作 + 工具按钮） | `structureRequirements.pageRegions.actionBar` |
+| 表格区 | 无包裹 | `.vts-table-area`（圆角边框） | `structureRequirements.pageRegions.table` |
+| 表头底色 | EP 默认浅灰 | 品牌色浅底 + 强调线（element-plus.scss 全局） | `visual.tableHeader` |
+| 行 hover | EP 默认灰色 | 品牌色极浅底（element-plus.scss 全局） | `visual.rowHover` |
+| 状态标签 | 无规范 | filled/outlined/solid 按列分配 | `component-spec.md` Tag 规范 |
 | 交互行为 | EP 默认 | 按 JSON `interactionSpecs` 实现 | `interactionSpecs` |
 
+### 设计模式 CSS 类速查
+
+| CSS 类 | 作用 | 对应令牌 |
+|--------|------|---------|
+| `.vts-page-header` | 页面标题区容器 | `--page-header-padding-y/x` |
+| `.vts-page-header__title-text` | 标题文字 | `--page-header-title-size` / `--page-header-title-weight` |
+| `.vts-page-header__subtitle` | 副标题文字 | `--page-header-subtitle-size` / `--page-header-subtitle-color` |
+| `.vts-page-header__actions` | 标题区右侧操作按钮组 | — |
+| `.vts-filter-area` | 筛选区容器（带底部分割线） | `--filter-area-padding` / `--filter-area-border-bottom` |
+| `.vts-action-bar` | 操作栏容器（批量 + 工具按钮） | `--action-bar-padding-y/x` |
+| `.vts-table-area` | 表格区包裹 | `--table-area-border-radius` / `--table-area-border` |
+| `.vts-thumb-circle` | 缩略图圆形首字 | `--thumb-size` / `--thumb-bg` / `--thumb-color` |
+| `.vts-collapse-btn` | 展开收起按钮 | 文字色 + 箭头色 hover 时**加深为品牌色，禁止变淡** |
+
+### 设计模式状态标签规范
+
+- 状态列默认使用 **filled** 变体（浅色背景 + 语义色文字 + 浅边框）
+- 分类/类型列使用 **outlined** 变体（透明背景 + 语义色边框 + 语义色文字）
+- 关键标记列使用 **solid** 变体（纯色填充 + 白字）
+- **≥3 个 Tag 列时**：四选二（filled + outlined 为推荐搭配），同一列内样式一致
+- 完整规则见 `component-spec.md` 7.9 节 + `list-page.md` 第 7-8 节
+
+### 设计模式缩略图列
+
+- 商品/用户/文件等有标识的列表首列使用圆形首字缩略图
+- 尺寸：32×32px，`border-radius: 50%`，品牌色浅底 + 品牌色文字
+- 文字：名称首字（中文取首字，英文取首字母大写）
+
+### 展开收起按钮 hover 强制规则
+
+⚠️ **展开收起按钮 hover 时文字色必须加深（品牌色），禁止变淡/变透明/变浅灰。**
+- 使用自定义 `.vts-collapse-btn` 类，不依赖 `el-button link`（EP link 按钮 hover 会变淡）
+- 箭头图标同步变品牌色，旋转过渡 `0.2s`
+
 ## 操作列按钮过多（ReTableOperate · 强制）
 
 落点：`src/components/ReTableOperate`。列表行操作**必须**用本组件，禁止手写一排 `el-button` / 自造「更多」菜单。

package/references/design-handoff.md

@@ -11,7 +11,7 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 > 每一项标注：JSON 来源 → 项目文件 → 修改内容 → 验证点。
 > 模板源码保持出厂状态，所有修改在 AI 生成/修改代码时完成。
 >
-> 1:1 还原要求见设计 Skill 的 `project-implementation-protocol.md`。
+> 1:1 还原要求见下方 F1-F27（框架组件）和 P1-P7（页面代码）步骤。
 
 ## 双轨
 
@@ -20,11 +20,38 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 | **未调用设计 / 无 handoff** | 保持模板出厂（主色 `#409EFF`、`Theme: light`=白侧栏、`ShowModel: chrome`、margin 8） |
 | **有 design-handoff/v1 JSON** | 按本清单 5 步 51 项逐项执行；只改主色不改 Theme/Version = **落地失败** |
 
-## 触发
+## 两种调用场景
 
-- 会话 / 附件 / 仓库中有 `design-handoff/v1` JSON（`$schema` 字段识别）
-- 用户要求按设计稿 / 规范适配或重构整站风格
-- 命中 `design-system` 模块且设计 Skill 产出可用
+> 以下「设计技能」泛指任何能输出 `design-handoff/v1` JSON 的设计类技能，不限定具体技能名称。
+
+| 场景 | 触发时机 | 执行范围 | 关键规则 |
+|------|---------|---------|---------|
+| **先开发 → 后调设计** | 业务页面已用 vue3-temp-skill 开发完成，用户不满意效果，调设计技能输出 handoff JSON | C/T/F/S/P **全 5 步** | 页面组件保留业务逻辑（API/路由/状态/事件），**重写 `<template>` 和样式**，使页面结构与设计输出一致 |
+| **先设计 → 后开发** | 新项目先调设计技能输出 handoff JSON，再调 vue3-temp-skill | 先执行 C/T/F/S（配置/令牌/框架/样式），后续业务开发时 P 步骤随页面生成同步落地 | 后续每个新页面开发都须遵循已落地设计规范，不以出厂样板覆盖设计输出 |
+
+**两种场景均须执行完整 C/T/F/S/P 流程，不可跳步。**
+
+## 设计为准原则
+
+> 设计输出是页面结构和功能元素的**唯一视觉基准**，不是仅调整配色。
+
+1. **设计输出中未体现的元素 → 隐藏或移除**（如模板有设置按钮但设计中没有 → 去掉）
+2. **设计输出中有但模板没有的元素 → 新增**（如设计有页面标题区但模板没有 → 补上）
+3. **设计输出覆盖的区域 → 严格按设计结构重写**，布局/元素/交互以设计为准
+4. **设计输出未覆盖的区域 → 保持项目已有实现**，仅同步令牌（色彩/字体/圆角等）
+5. **隐藏/移除功能性元素时**：在回复中明确列出被移除的元素，供用户确认是否需要补回
+
+## 触发（自动，无需用户提及 JSON）
+
+> 设计技能（project-ui-design）每次产出时**始终自动附加 `design-handoff/v1` JSON**。
+> 本技能检测到 JSON 存在 → 自动触发完整 C/T/F/S/P 流程，用户无需提及「JSON」「handoff」「桥接」等技术词。
+
+**触发条件**（满足任一）：
+
+1. 会话中存在 `design-handoff/v1` JSON（设计技能自动产出）
+2. 会话中存在设计技能的 HTML 产出 + 用户要求按设计结果适配工程代码
+
+⚠️ 触发后 **必须执行完整 C/T/F/S/P 五步**，禁止只改主色或只改令牌。
 
 ## 规范识别回执（动手前必出）
 
@@ -47,14 +74,14 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 | # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
 |---|---------|---------|---------|------|
-| C1 | `shell.sidebar` | `platform-config.json` → `Theme` | `dark-gradient` → `default`（深色侧栏）；仅明确要白菜单时 `light` | 侧栏背景为 `#001529` |
+| C1 | `shell.sidebar` | `platform-config.json` → `Theme` | `dark-gradient` → `default`（深色侧栏）；仅明确要白菜单时 `light` | 侧栏背景为深色 |
 | C2 | `shell.showModel` | `platform-config.json` → `ShowModel` | 设为 JSON 值（`line`/`card`/`chrome`/`smart`） | 页签风格与设计一致 |
 | C3 | `shell.darkMode` | `platform-config.json` → `DarkMode` | `true`/`false` | 暗色模式开关 |
 | C4 | `shell.contentMode` | `platform-config.json` → `OverallStyle` | `vertical`/`horizontal`/`mix` | 布局模式 |
-| C5 | `shell.contentMargin` | `platform-config.json` → `contentMargin` | 数值（如 24） | 内容区间距 |
-| C6 | `tokens.brandPrimary` | `platform-config.json` → `EpThemeColor` | HEX 值 | 主色全局生效 |
-| C7 | `shell.dataTheme` | `platform-config.json` → `dataTheme` | 主题标识（如 `default`） | 侧栏主题色 |
-| C8 | — | `platform-config.json` → `Version` | **必须自增**（如 `0.0.5` → `0.0.6`） | 否则 localStorage 缓存不刷新 |
+| C5 | `shell.contentMargin` | `platform-config.json` → `contentMargin` | 按 JSON 值 | 内容区间距 |
+| C6 | `tokens.brandPrimary` + `tokens.primaryScale` | `platform-config.json` → `EpThemeColor` + `PrimaryScale` | HEX 值 + 10 级色阶数组 | 主色全局生效；运行时优先用 PrimaryScale 精确色阶，不再走 chroma 计算 |
+| C7 | `shell.dataTheme` | `platform-config.json` → `dataTheme` | 按 JSON 值 | 侧栏主题色 |
+| C8 | — | `platform-config.json` → `Version` | **必须自增** | 否则 localStorage 缓存不刷新 |
 
 **禁止**：把设计「浅色内容」写成 `Theme=light`。`contentMode=light` 与 `Theme=light` 不是一回事。深色侧栏 = `Theme=default`。
 
@@ -79,24 +106,14 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 | T11 | `componentSize` | 控件段 | `--control-height-sm` / `--control-height` / `--control-height-lg` | 值与 JSON 一致 |
 | T12 | `dataViz` | 可视化段 | `--chart-categorical-*` / `--chart-success` / `--chart-warning` 等 | 值与 JSON 一致 |
 
-侧栏深色（`shell.sidebar === "dark-gradient"`）时追加写入 `design-tokens.scss`：
-
-```scss
---sidebar-bg: #001529;
---sidebar-logo-bg: #002140;
---sidebar-border-color: transparent;
---sidebar-menu-text: rgb(255 255 255 / 65%);
---sidebar-menu-text-hover: #fff;
---sidebar-menu-active-text: #fff;
---sidebar-menu-hover-bg: rgb(255 255 255 / 8%);
---sidebar-menu-active-bg: var(--primary-color);
---sidebar-submenu-bg: color-mix(in srgb, #001529 82%, #000);
---sidebar-active-indicator: var(--primary-color);
-```
+侧栏深色（`shell.sidebar === "dark-gradient"`）时追加写入 `design-tokens.scss` 的侧栏令牌段：
+
+> 令牌变量名固定（`--sidebar-bg` / `--sidebar-logo-bg` / `--sidebar-menu-text` 等），**值来自 JSON `tokens` 或 `design-tokens.md` 侧栏令牌段**。
+> 核心令牌：`--sidebar-bg`、`--sidebar-logo-bg`、`--sidebar-menu-text`、`--sidebar-menu-text-hover`、`--sidebar-menu-active-text`、`--sidebar-menu-hover-bg`、`--sidebar-menu-active-bg`（引用 `var(--primary-color)`）、`--sidebar-submenu-bg`、`--sidebar-active-indicator`（引用 `var(--primary-color)`）。
 
 ---
 
-## 三、框架组件修改（F1-F14 · 1:1 还原核心）
+## 三、框架组件修改（F1-F27 · 1:1 还原核心）
 
 > 此节实现 `structureRequirements` 和 `interactionSpecs` 的要求。
 > 模板源码保持出厂，AI 获取 JSON 后逐项修改组件代码。
@@ -105,60 +122,150 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 | # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
 |---|---------|---------|---------|------|
-| F1 | `structureRequirements.frameworkShell.header` | `src/layout/components/navbar/index.vue` | 顶栏组成：折叠按钮（左）+ 语言切换 + 功能图标组 + 分割线 + 欢迎区 + 头像（右） | 元素完整 |
+| F1 | `structureRequirements.frameworkShell.header` | `src/layout/components/navbar/index.vue` | 顶栏组成：折叠按钮（左）+ 语言切换 + 功能图标组 + 分割线 + 欢迎区 + 头像（右）。**设计中未体现的元素必须移除**（设置/通知/全屏/搜索/面包屑等） | 元素与设计完全一致，不多不少 |
 | F2 | `interactionSpecs.languageSwitch` | navbar/ 语言切换组件 | **改为内联文字**（中 / EN），竖线分隔。激活态品牌色文字，非激活次要色。**禁止下拉框** | 语言切换为内联文字 |
 | F3 | `structureRequirements.frameworkShell.headerLayout` | navbar/index.vue | flex 两端对齐：左侧折叠按钮，右侧功能组 | 布局与设计一致 |
 | F4 | `interactionSpecs.menuActive` → 头像区 | navbar/ 欢迎区 | 悬停态：头像微浮起 + 欢迎文字变品牌色 | hover 效果与设计一致 |
+| F5 | `frameworkShell.header` 元素清单 | navbar/index.vue | **设置按钮**：设计无则 `display:none` 或删除组件引用 | 设置按钮不出现 |
+| F6 | `frameworkShell.header` 元素清单 | navbar/index.vue | **通知/消息按钮**：设计无则隐藏 | 通知图标不出现 |
+| F7 | `frameworkShell.header` 元素清单 | navbar/index.vue | **全屏按钮**：设计无则隐藏 | 全屏图标不出现 |
+| F8 | `frameworkShell.header` 元素清单 | navbar/index.vue | **面包屑**：设计无则隐藏（统一框架默认无面包屑） | 顶栏无面包屑 |
+| F9 | `frameworkShell.header` 元素清单 | navbar/index.vue | **搜索框**：设计无则隐藏（统一框架默认无搜索框） | 顶栏无搜索框 |
 
 ### 3.2 侧栏 sidebar
 
 | # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
 |---|---------|---------|---------|------|
-| F5 | `structureRequirements.frameworkShell.sidebar.logoArea` | `src/layout/components/sidebar/` | Logo 区：品牌色方块 + 白字（按设计），非默认彩色图标 | Logo 风格统一 |
-| F6 | `structureRequirements.frameworkShell.sidebar.menuItemHeight` | sidebar/ + `element-plus.scss` | 菜单项高度设为设计值（如 40px） | 间距有呼吸感 |
-| F7 | `interactionSpecs.menuActive` | sidebar/ + `element-plus.scss` | **菜单激活态**：品牌色极浅底 + 右侧 3px 强调条 + 品牌色文字 | 激活态视觉锚点清晰 |
-| F8 | `structureRequirements.frameworkShell.sidebar.collapsed` | sidebar/ 折叠态 | 仅图标，宽度按 `geometry.siderCollapsedWidth` | 折叠宽度与设计一致 |
-| F9 | `shell.sidebar` → 深色侧栏 | `theme.scss` / `sidebar.scss` | 侧栏背景色 `#001529`（深色），非出厂白色 | 侧栏深色 |
+| F10 | `structureRequirements.frameworkShell.sidebar.logoArea` | `src/layout/components/sidebar/` | Logo 区：品牌色方块 + 白字首字（尺寸/圆角按 JSON 值），非默认彩色图标 | Logo 风格统一 |
+| F11 | `structureRequirements.frameworkShell.sidebar.menuItemHeight` | sidebar/ + `element-plus.scss` | 菜单项高度按 JSON 值 | 间距有呼吸感 |
+| F12 | `interactionSpecs.menuActive` | sidebar/ + `element-plus.scss` | **菜单激活态**：品牌色极浅底 + 右侧强调条 + 品牌色文字。**禁止纯蓝底白字** | 激活态视觉锚点清晰 |
+| F13 | `structureRequirements.frameworkShell.sidebar.collapsed` | sidebar/ 折叠态 | 仅图标，宽度按 `geometry.siderCollapsedWidth` | 折叠宽度与设计一致 |
+| F14 | `shell.sidebar` → 深色侧栏 | `theme.scss` / `sidebar.scss` | 侧栏背景色按 JSON/令牌库值（深色），非出厂白色 | 侧栏深色 |
+| F15 | `frameworkShell.sidebar.collapseButtonPosition` | sidebar/ | **折叠按钮位置**：设计在顶部则放 Logo 区；设计在底部则放侧栏底部 | 折叠按钮位置与设计一致 |
+| F16 | `frameworkShell.sidebar.bottomCollapse` | sidebar/ | **底部折叠按钮**：设计无则 **必须隐藏**（`display:none` 或删除底部触发器），折叠功能移至顶部 | 侧栏底部无折叠按钮 |
+| F17 | `frameworkShell.sidebar.hoverCollapse` | sidebar/ | **菜单 hover 折叠功能**：设计无则 **必须禁用**（删除 `show-collapse-on-hover` 或等效逻辑） | 菜单 hover 不出现折叠提示 |
+| F18 | `frameworkShell.sidebar.groupTitle` | sidebar/ | 菜单分组标题：设计无分组则移除分组标题 | 分组标题与设计一致 |
 
 ### 3.3 页签 tabs
 
 | # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
 |---|---------|---------|---------|------|
-| F10 | `shell.showModel` | `src/layout/components/tabs/` + `element-plus.scss` | 页签风格按设计值实现（line: 底部强调线；card: 卡片式；chrome: 谷歌式） | 风格与设计一致 |
-| F11 | `structureRequirements.frameworkShell.tabs.homeTab` | tabs/ | 首页页签固定左侧，不可关闭 | 首页页签行为正确 |
-| F12 | `interactionSpecs.tabsActive` | `element-plus.scss` | 激活页签：品牌色文字 + 底部强调线（line 风格） | 激活态视觉与设计一致 |
+| F19 | `shell.showModel` | `src/layout/components/tabs/` + `element-plus.scss` | 页签风格按设计值实现（line: 底部强调线；card: 卡片式；chrome: 谷歌式） | 风格与设计一致 |
+| F20 | `structureRequirements.frameworkShell.tabs.homeTab` | tabs/ | 首页页签固定左侧，**不可关闭** | 首页页签行为正确 |
+| F21 | `interactionSpecs.tabsActive` | `element-plus.scss` | 激活页签：品牌色文字 + 底部强调线（line 风格） | 激活态视觉与设计一致 |
+| F22 | `interactionSpecs.tabsUnderline` | `element-plus.scss` | **页签下划线居中**：`line` 模式下激活下划线与文字等宽、严格居中，禁止偏左/偏右 | 横线视觉居中 |
+| F23 | `frameworkShell.tabs.height` | tabs/ + `design-tokens.scss` | 页签高度严格按 `--tabs-height`，内部 flex 垂直居中 | 文字垂直居中 |
+| F24 | `interactionSpecs.tabsClose` | `element-plus.scss` | 关闭按钮始终可见，hover 变色（按 JSON `interactionSpecs.tabsClose` 值） | 关闭按钮行为正确 |
+| F25 | `frameworkShell.tabs.contextMenu` | tabs/ | 右键菜单：刷新/关闭/关闭其他/关闭左侧/关闭右侧/全部关闭 | 右键菜单项与设计一致 |
 
 ### 3.4 内容区 app-main
 
 | # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
 |---|---------|---------|---------|------|
-| F13 | `geometry.contentPadding` | `src/layout/components/app-main/` + `design-tokens.scss` | 内容区内边距设为设计值（如 24px），非出厂 8px | 间距有呼吸感 |
-| F14 | `tokens.layoutBg` | app-main/ + `design-tokens.scss` | 内容区背景色设为设计值（如 `#F5F5F5`） | 背景层次分明 |
+| F26 | `geometry.contentPadding` | `src/layout/components/app-main/` + `design-tokens.scss` | 内容区内边距按 JSON `geometry.contentPadding` 值，非出厂默认 | 间距有呼吸感 |
+| F27 | `tokens.layoutBg` | app-main/ + `design-tokens.scss` | 内容区背景色按 JSON `tokens.layoutBg` 值 | 背景层次分明 |
 
 ---
 
-## 四、样式文件修改（S1-S10）
+## 四、元素自查隐藏清单（设计没有 → 必删）
 
-写入 `src/styles/element-plus.scss`（在既有规则基础上追加视觉规则段，引用令牌变量）。
+> 设计输出（JSON `structureRequirements` 或设计稿图）中没有的元素，必须隐藏或移除。
+> 以下为高频检查项，**逐项对照**，设计中没有的一律处理。
+> 隐藏/移除功能性元素时，在最终回复的「设计落地」结果块中列出被移除项。
 
-| # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
-|---|---------|---------|---------|------|
-| S1 | `visual.shadowCardRest` | `element-plus.scss` → `.el-card` | 静态阴影值 | 卡片有微妙投影 |
-| S2 | `visual.shadowCardHover` + `interactionSpecs.cardHover` | `element-plus.scss` → `.el-card:hover` | 浮起阴影 + 边框变品牌色 + 过渡 | 卡片 hover 有浮起感 |
-| S3 | `interactionSpecs.buttonHover` | `element-plus.scss` → `.el-button:hover` | `translateY(-1px)` + 品牌色阴影 + 过渡 | 按钮 hover 有上浮感 |
-| S4 | `interactionSpecs.inputFocus` | `element-plus.scss` → `.el-input__wrapper:focus` | 品牌色边框 + 3px 外光环 + 过渡 | 输入框聚焦有光环 |
-| S5 | `interactionSpecs.tableRowHover` | `element-plus.scss` → `.el-table tbody tr:hover` | 品牌色极浅底 + 过渡 | 行 hover 有品牌色感 |
-| S6 | `visual.tableHeaderBorderBottom` | `element-plus.scss` → `.el-table thead th` | 表头底色 + 字重 + 底部强调线 | 表头有层次感 |
-| S7 | `visual.menuActiveBorderRight` | `element-plus.scss` → `.el-menu-item.is-active` | 右侧 3px 强调条 | 菜单激活有锚点 |
-| S8 | `interactionSpecs.paginationActive` | `element-plus.scss` → `.el-pagination .is-active` | 品牌色底 + 白字 + 圆角 | 分页激活页有品牌色 |
-| S9 | `visual.transitionBase` | `element-plus.scss` → 全局过渡 | 过渡时长 + 缓动曲线 | 交互有平滑感 |
-| S10 | — | `src/styles/dark.scss` | 以上所有视觉规则在暗色模式下有覆盖 | 暗色模式完整 |
-
-> 视觉规则直接写入 `element-plus.scss`，引用令牌变量。设计落地时令牌值变化即生效，规则结构不动。
+### 4.1 顶栏元素
+
+| 元素 | 组件位置 | 默认状态 | 设计无则 |
+|------|---------|---------|---------|
+| 设置按钮 | navbar 右侧 | 显示 | `display:none` 或删除组件引用 |
+| 通知/消息按钮 | navbar 右侧 | 显示 | 同上 |
+| 全屏按钮 | navbar 右侧 | 显示 | 同上 |
+| 搜索框 | navbar 左侧或中部 | 不显示 | 确认不显示 |
+| 面包屑 | navbar 下方或内 | 不显示 | 确认不显示 |
+| 语言切换下拉 | navbar 右侧 | 内联文字 | 确认是内联文字，非下拉框 |
+
+### 4.2 侧栏元素
+
+| 元素 | 组件位置 | 默认状态 | 设计无则 |
+|------|---------|---------|---------|
+| 底部折叠按钮 | sidebar 底部 | 显示 | 隐藏，折叠按钮移至顶部 Logo 区 |
+| 菜单 hover 折叠提示 | sidebar 菜单 hover 时 | 显示 | 禁用（删 `show-collapse-on-hover` 或等效逻辑） |
+| 菜单分组标题 | sidebar 菜单中 | 大写字母 | 设计无分组则移除 |
+| 子菜单展开箭头 | sidebar 子菜单 | 显示 | 确认样式与设计一致 |
+
+### 4.3 列表页元素
+
+| 元素 | 组件位置 | 默认状态 | 设计无则 |
+|------|---------|---------|---------|
+| 密度切换按钮 | 表格工具栏 | 显示 | 设计无则隐藏 |
+| 列设置按钮 | 表格工具栏 | 显示 | 设计无则隐藏 |
+| 刷新按钮 | 表格工具栏 | 显示 | 设计无则隐藏 |
+| 搜索框（表格内） | 表格头部 | 不显示 | 确认不显示 |
+| 序号列 | 表格第一列 | 不显示 | 设计无则不加 |
+| 展开行按钮 | 表格行首 | 不显示 | 设计无则不加 |
+
+### 4.4 移除后告知格式
+
+隐藏/移除以上功能性元素时，在最终回复中追加：
+
+```markdown
+## 设计落地 — 已移除元素（设计中未体现）
+
+- 顶栏设置按钮
+- 侧栏底部折叠按钮（已移至 Logo 区）
+- 表格密度切换按钮
+- ...
+```
 
 ---
 
-## 五、页面代码修改（P1-P7）
+## 五、样式文件修改（S1 · 机制 + 区域映射）
+
+### 5.1 机制
+
+1. 读取 JSON 的 `visual` + `interactionSpecs` 字段
+2. 按「区域映射表」逐项将 JSON 值写入 `element-plus.scss` 对应 CSS 选择器
+3. **所有值引用 `design-tokens.scss` 令牌变量**，不硬编码
+4. JSON 无值时回退 `design-tokens.md` 默认值（设计技能令牌库）
+5. `dark.scss` 对以上规则逐条提供暗色覆盖
+
+### 5.2 原则（硬约束，不随设计变化而失效）
+
+⚠️ **hover 禁止变淡**：所有 hover 状态的文字色必须加深或变色，禁止变淡/变透明/变浅灰。
+⚠️ **下划线居中**：line 风格页签激活下划线与文字等宽、严格居中，禁止偏左偏右。
+⚠️ **值不硬编码**：本表不指定具体 hex/px/时长值，一切值来自 JSON 或令牌库。
+
+### 5.3 区域映射表（JSON 字段 → CSS 选择器）
+
+> 本表只映射「哪个 JSON 字段 → 哪个 CSS 选择器 → 验证什么」，**不硬编码值**。
+> 具体值由 JSON `visual` / `interactionSpecs` 驱动，令牌变量承载。
+
+| 区域 | JSON 来源 | CSS 选择器 | 验证 |
+|------|---------|-----------|------|
+| 卡片静态 | `visual.shadowCardRest` | `.el-card` | 卡片有投影 |
+| 卡片 hover | `visual.shadowCardHover` + `interactionSpecs.cardHover` | `.el-card:hover` | 卡片 hover 有浮起感 |
+| 按钮 hover | `interactionSpecs.buttonHover` | `.el-button:hover` | 按钮 hover 有上浮感 |
+| 输入框聚焦 | `interactionSpecs.inputFocus` | `.el-input__wrapper:focus-within` | 输入框聚焦有光环 |
+| 表格行 hover | `interactionSpecs.tableRowHover` | `.el-table tbody tr:hover` | 行 hover 有品牌色感 |
+| 表头 | `visual.tableHeaderBorderBottom` | `.el-table thead th` | 表头有层次感 |
+| 菜单激活 | `visual.menuActiveBorderRight` | `.el-menu-item.is-active` | 菜单激活有锚点 |
+| 分页激活 | `interactionSpecs.paginationActive` | `.el-pagination .is-active` | 分页激活页有品牌色 |
+| 全局过渡 | `visual.transitionBase` | `*` (transition) | 交互有平滑感 |
+| 暗色覆盖 | — | `html.dark` 下以上选择器 | 暗色模式完整 |
+| 展开收起 hover | `interactionSpecs.collapseBtnHover` | `.vts-collapse-btn:hover` | hover 文字不变浅 |
+| 操作列 hover | `interactionSpecs.actionBtnHover` | `.vts-table-area .el-button--text:hover` | 操作列 hover 文字加深 |
+| 页签关闭 hover | `interactionSpecs.tabsCloseHover` | `.el-tabs__item .el-icon-close:hover` | 关闭按钮 hover 有反馈 |
+| 页签下划线 | `interactionSpecs.tabsUnderline` | `.el-tabs__active-bar` | 横线居中 |
+| 下拉选项 hover | `interactionSpecs.selectOptionHover` | `.el-select-dropdown__item.hover` | 下拉项 hover 有品牌色感 |
+| 复选框 hover | `interactionSpecs.checkboxHover` | `.el-checkbox__inner:hover` | 复选框 hover 有反馈 |
+| 开关过渡 | `interactionSpecs.switchTransition` | `.el-switch` | 开关切换有动画 |
+| Tag hover | `interactionSpecs.tagHover` | `.el-tag:hover` | Tag hover 有反馈 |
+
+> 设计技能输出更新时，JSON 值变化 → 令牌变量变化 → CSS 规则自动生效，**本表结构不动**。
+
+---
+
+## 六、页面代码修改（P1-P7）
 
 | # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
 |---|---------|---------|---------|------|
@@ -183,28 +290,88 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 
 ---
 
-## 六、执行顺序
+## 七、执行顺序
 
 1. **配置修改**（C1-C8）→ `platform-config.json`
 2. **令牌写入**（T1-T12）→ `design-tokens.scss`
-3. **框架组件修改**（F1-F14）→ navbar / sidebar / tabs / app-main
-4. **样式修改**（S1-S10）→ `element-plus.scss` + `dark.scss`
-5. **页面代码生成**（P1-P7）→ 业务页面 .vue
+3. **框架组件修改**（F1-F27）→ navbar / sidebar / tabs / app-main
+4. **元素自查隐藏**（第四章清单）→ 逐项对照，设计无则删
+5. **样式修改**（S1 区域映射）→ `element-plus.scss` + `dark.scss`
+6. **页面代码生成**（P1-P7）→ 业务页面 .vue
 
 ---
 
-## 硬失败
+## 八、硬失败（任一项命中 = 落地失败，必须修正）
+
+| 类别 | 条件 | 处理 |
+|------|------|------|
+| 配置 | 只改主色/tokens，未改 Theme / Version | 硬失败：补全 C1-C8 |
+| 配置 | 设计 `sidebar=dark-gradient` 但 `Theme` 仍为 `light` | 硬失败：改为 `default` 并 `Version++` |
+| 配置 | 未写入 `shell.showModel` | 硬失败：按 JSON 补写 |
+| 配置 | `primaryScale` 未写入 `--primary-0..9` | 硬失败：补全 10 级色阶 |
+| 令牌 | 用 EP 默认错误色 `#F56C6C` 而非令牌引用 | 硬失败：改为 `var(--error-color)` 或对应令牌值 |
+| 令牌 | 壳层/弹窗写死 px | 硬失败：改 `var(--…)` |
+| 令牌 | 改了 margin 后列表仍用 `100vh` 减顶栏 | 硬失败：迁 flex / `vts-page-card` |
+| 框架-顶栏 | 顶栏元素与设计不一致（多了或少了） | 硬失败：按 `frameworkShell.header` 逐项对齐 |
+| 框架-顶栏 | 语言切换为下拉框（非内联文字） | 硬失败：改为内联文字 |
+| 框架-顶栏 | 设置按钮设计无但代码中还在 | 硬失败：删除或 `display:none` |
+| 框架-侧栏 | 侧栏底部折叠按钮设计无但还在 | 硬失败：隐藏，折叠按钮移至顶部 |
+| 框架-侧栏 | 菜单 hover 出现折叠功能设计无但还在 | 硬失败：禁用该功能 |
+| 框架-侧栏 | 菜单激活态无品牌色底+强调条 | 硬失败：按 `interactionSpecs.menuActive` 补充 |
+| 框架-页签 | 页签横线不居中 | 硬失败：调整下划线位置，确保与文字等宽居中 |
+| 框架-页签 | 首页页签可关闭 | 硬失败：设为不可关闭 |
+| 样式 | 展开收起按钮 hover 文字变浅 | 硬失败：hover 文字色加深或变色，**禁止变淡** |
+| 样式 | 表格行 hover 无品牌色底 | 硬失败：补充 hover 背景色 |
+| 样式 | 卡片/按钮 hover 无浮起效果 | 硬失败：补充 transform + shadow |
+| 样式 | 输入框聚焦无光环 | 硬失败：补充 focus 阴影 |
+| 页面 | 页面无标题区 / 筛选区无容器感 | 硬失败：按 `moduleComposition` 补充 |
+| 页面 | 状态标签样式与设计规范不一致 | 硬失败：按 `component-spec.md` Tag 规范修正 |
+| 页面 | 操作列按钮样式混乱（混用 button/文字链接） | 硬失败：统一为文字链接 + "更多"下拉 |
+| 页面 | 设计中未体现的元素未隐藏 | 硬失败：按元素自查隐藏清单逐项处理 |
+| 页面 | `structureRequirements` 或 `interactionSpecs` 段未实现 | 硬失败：按 F1-F27 / P1-P7 补充 |
 
-| 条件 | 处理 |
-|------|------|
-| 设计 `sidebar=dark-gradient` 但 `Theme` 仍为 `light` | **硬失败**：改为 `default` 并 `Version++` |
-| 只改主色/tokens，未改 Theme / Version | **硬失败**：补全 C1-C8 |
-| 未写入 `shell.showModel` | 硬失败：按 JSON 补写 |
-| `primaryScale` 未写入 `--primary-0..9` | 硬失败 |
-| 用 `#F56C6C` 代替 `tokens.error` | 硬失败：改为 `#F5222D` |
-| 改了 margin 后列表仍用 `100vh` 减顶栏 | 硬失败：迁 flex / `vts-page-card` |
-| 壳层/弹窗写死 px | 硬失败：改 `var(--…)` |
-| 语言切换为下拉框（非内联文字） | 硬失败：改为内联文字 |
-| 菜单激活态无品牌色底+强调条 | 硬失败：按 `interactionSpecs.menuActive` 补充 |
-| 页面无标题区 / 筛选区无容器感 | 硬失败：按 `structureRequirements.moduleComposition` 补充 |
-| `structureRequirements` 或 `interactionSpecs` 段未实现 | 硬失败：按 `project-implementation-protocol.md` 补充 |
+---
+
+## 九、落地完整性校验（code-quality 额外执行）
+
+> 当 `design-handoff/v1` JSON 存在时，`code-quality` 必须额外执行以下校验。
+> 任一项未通过 = 硬失败，必须修正后重新生成。
+
+### 配置层
+
+- [ ] `platform-config.json` 的 `EpThemeColor` 与 JSON `tokens.brandPrimary` 一致
+- [ ] `Theme` 与 `shell.sidebar` 对应（`dark-gradient` → `default`）
+- [ ] `ShowModel` 与 `shell.showModel` 一致
+- [ ] `Version` 已自增
+
+### 令牌层
+
+- [ ] `design-tokens.scss` 的 `--primary-0` ~ `--primary-9` 全部写入
+- [ ] `--primary-5` === `--brand-primary` === `brandPrimary`
+- [ ] `--header-height` / `--tabs-height` / `--sidebar-width` / `--layout-content-padding` 与 JSON `geometry` 一致
+- [ ] `--control-height*` 与 JSON `componentSize` 一致
+- [ ] 无硬编码 hex 值出现在令牌以外的位置
+
+### 框架层
+
+- [ ] navbar 顶栏组成与 `structureRequirements.frameworkShell.header` 一致
+- [ ] 语言切换为内联文字（非下拉框）
+- [ ] sidebar Logo 区为品牌色方块 + 白字
+- [ ] 菜单激活态有品牌色极浅底 + 右侧强调条
+- [ ] 页签风格与 `shell.showModel` 一致
+- [ ] 内容区内边距与 `geometry.contentPadding` 一致
+
+### 样式层
+
+- [ ] `element-plus.scss` 视觉规则按 S1 区域映射表逐项写入，值来自 JSON `visual` / `interactionSpecs`
+- [ ] `dark.scss` 对以上视觉规则有暗色覆盖
+
+### 页面层
+
+- [ ] 业务页面区域结构与 JSON `pageStructure.regions` 一致
+- [ ] 页面有标题区（`.vts-page-header`）：标题 + 描述 + 操作按钮
+- [ ] 筛选区有容器感（`.vts-filter-area`）：背景 + 圆角 + 底部分隔线
+- [ ] 表格区有包裹感（`.vts-table-area`）：圆角 + 边框
+- [ ] 页面内交互行为按 `interactionSpecs` 实现
+- [ ] 所有样式值引用 CSS 变量，无裸值
+- [ ] **未用出厂 CRUD 样板结构覆盖设计输出的页面结构**

package/references/design-system.md

@@ -9,12 +9,9 @@ tags: [design-system, design-tokens, element-plus, theme, css-variables, dark-mo
 
 项目基于 Element Plus，通过 CSS 变量令牌体系驱动视觉。不换组件库，只换令牌数据。组件层始终是 EP，样式层由令牌控制。
 
-## 双轨原则
-
-| 轨 | 含义 | Agent 行为 |
-|----|------|------------|
-| **出厂** | `design-tokens.scss` / `platform-config.json` 已有默认值（壳 64/208/40、主色 `#409EFF`、`ShowModel: chrome`、`--layout-content-padding: 8`） | 勿擅自改掉以贴合设计；未调用设计技能时保持出厂 |
-| **设计落地** | 会话存在 `design-handoff/v1` JSON 或用户要求按设计规范适配 | 必须按 JSON 全量回填令牌；设计未提及的字段保留出厂 |
+> **落地流程与优先级**：有 `design-handoff/v1` JSON 时，设计产出 > 本文档桥接规则 > 出厂默认值。完整执行流程、双轨原则、冲突处理见 `design-handoff.md`。
+>
+> **职责边界**：设计技能定义「设计应该是什么样」；本文档定义「如何把设计落地到 EP」（令牌桥接/CSS 变量映射/EP 几何适配）；各功能模块定义业务功能怎么写。
 
 视觉关键尺寸（顶栏/侧栏/页签/内容边距/控件高/弹窗等）在模版中一律为 CSS 变量；文档里的 64/208 等是默认值说明，不是允许写死在组件里的常量。
 
@@ -48,7 +45,7 @@ tags: [design-system, design-tokens, element-plus, theme, css-variables, dark-mo
 
 - `public/platform-config.json` 的 `EpThemeColor` 是运行时初始主色来源（`useApp.ts` 读取并 `setEpThemeColor()`）。
 - `Theme` 字段控制侧栏风格：`default`（深色 `#001529`）/ `light`（浅色）/ `dark-gradient` 等。
-- 主色运行时切换走 `setEpThemeColor()`（保证 chroma 色阶同步），令牌层只负责初始值。
+- 主色运行时切换走 `setEpThemeColor()`；若 `platform-config.json` 含 `PrimaryScale` 数组，运行时优先使用精确色阶值（与设计技能 `primaryScale` 一致），否则回退 chroma 计算色阶。令牌层只负责初始值。
 - **localStorage 缓存陷阱**：`epThemeColor` 优先读 `localStorage` 的 `responsive-layout`；改完 `platform-config.json` 后老访客不会自动生效，需清缓存或提升 `Version` 触发重置。
 
 ## 暗色模式