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

package/SKILL.md

@@ -47,7 +47,8 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 - **精简出厂**：模板 `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 强制执行」段
 
 ## 使用方式
 
@@ -73,6 +74,10 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 3. **Hook ≠ 壳层自动**：`toDetail` 写 tag；侧栏高亮 / keepAlive 靠路由 meta；`http` 加解密靠环境开关，不靠单请求配置
 4. **大范围交付仍须逐模块核对硬失败表**，禁止以 lint 通过代替硬失败表逐项核对
 
+## 设计落地（handoff）
+
+当会话中存在 `design-handoff/v1` JSON 时，**强制加载** `references/design-handoff.md`，按 C/T/F/S/P 五步全流程执行（配置→令牌→框架→样式→页面），**任一步跳过 = 硬失败**。设计产出优先级高于本技能出厂默认值，页面保留业务逻辑、重写视觉结构。完整规则与逐项清单见 `design-handoff.md`。
+
 ## 模块路由表
 
 ### 始终加载
@@ -89,7 +94,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 | **启用精简模板已删的 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 还原协议） |
+| **设计模式**（设计 Skill 产出存在时触发） | `crud-pages.md` 设计模式样板 + `design-handoff.md` 1:1 还原要求（F1-F14 / P1-P7） |
 
 ### 标准业务面
 
@@ -164,7 +169,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 +193,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. **生成**：可运行代码落盘；**有 handoff JSON 时，页面结构以设计输出为准，保留业务逻辑**
+6. **code-quality**：按 `references/code-quality.md` 执行；**有 handoff JSON 时，额外执行 handoff 落地完整性校验**（见 `design-handoff.md` 末尾）
 7. **输出**：变更说明（含已改配置文件列表）+ 待确认项
 
 ### 最终回复结构
@@ -205,11 +210,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.27",
   "description": "Vue 3 企业级中后台项目开发规范技能包 — core-kernel 架构、按需功能模块",
   "bin": {
     "vue3-temp-skill": "./bin/cli.js"

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-F14（框架组件）和 P1-P7（页面代码）步骤。
 
 ## 双轨
 
@@ -20,6 +20,27 @@ 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 的设计类技能，不限定具体技能名称。
+
+| 场景 | 触发时机 | 执行范围 | 关键规则 |
+|------|---------|---------|---------|
+| **先开发 → 后调设计** | 业务页面已用 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. **隐藏/移除功能性元素时**：在回复中明确列出被移除的元素，供用户确认是否需要补回
+
 ## 触发
 
 - 会话 / 附件 / 仓库中有 `design-handoff/v1` JSON（`$schema` 字段识别）
@@ -52,7 +73,7 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 | 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 值 | 主色全局生效 |
+| C6 | `tokens.brandPrimary` + `tokens.primaryScale` | `platform-config.json` → `EpThemeColor` + `PrimaryScale` | HEX 值 + 10 级色阶数组 | 主色全局生效；运行时优先用 PrimaryScale 精确色阶，不再走 chroma 计算 |
 | C7 | `shell.dataTheme` | `platform-config.json` → `dataTheme` | 主题标识（如 `default`） | 侧栏主题色 |
 | C8 | — | `platform-config.json` → `Version` | **必须自增**（如 `0.0.5` → `0.0.6`） | 否则 localStorage 缓存不刷新 |
 
@@ -207,4 +228,50 @@ tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist
 | 语言切换为下拉框（非内联文字） | 硬失败：改为内联文字 |
 | 菜单激活态无品牌色底+强调条 | 硬失败：按 `interactionSpecs.menuActive` 补充 |
 | 页面无标题区 / 筛选区无容器感 | 硬失败：按 `structureRequirements.moduleComposition` 补充 |
-| `structureRequirements` 或 `interactionSpecs` 段未实现 | 硬失败：按 `project-implementation-protocol.md` 补充 |
+| `structureRequirements` 或 `interactionSpecs` 段未实现 | 硬失败：按 `design-handoff.md` F1-F14 / P1-P7 补充 |
+
+---
+
+## 七、落地完整性校验（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 区为品牌色方块 + 白字
+- [ ] 菜单激活态有品牌色极浅底 + 右侧 3px 强调条
+- [ ] 页签风格与 `shell.showModel` 一致
+- [ ] 内容区内边距与 `geometry.contentPadding` 一致
+
+### 样式层
+
+- [ ] `element-plus.scss` 视觉规则段（S1-S10）值与 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` 触发重置。
 
 ## 暗色模式