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

package/references/design-handoff.md

@@ -1,403 +1,210 @@
----
-skill: design-handoff
-description: 设计产出物 → 业务项目样式落地。优先认 design-handoff/v1 JSON；兼容旧交接块与令牌 CSS。
-scope: project
-tags: [handoff, design-tokens, upstream, artifacts, json]
----
-
-# 设计产出 → 模板落地
-
-## 双轨（必读）
-
-| 场景 | 行为 |
-|------|------|
-| **未调用设计 / 无 handoff** | 保持模版出厂（主色 `#409EFF`、`Theme: light`=**白侧栏**、`ShowModel: chrome`、margin 8 等）。**禁止**为贴合视觉印象而擅自修改出厂值 |
-| **有 design-handoff/v1 或用户要求按设计落地** | 按下文「落地原子步骤」**整组**回填；只改主色/令牌、不改 `Theme`/`Version` = **落地失败** |
-
-跨编辑器一致：设计侧 `handoff-output.md`（JSON 形状）+ 本文件（→ 模版映射）+ 模版令牌。  
-**分工**：设计师改视觉正文；本文件规定 Agent 如何落到模版。禁止只改文档不改令牌。
-
-### 出厂 vs 设计：侧栏两套开关（高频错误）
-
-| 概念 | 出厂 | 设计 page-templates「浅色模式」 |
-|------|------|--------------------------------|
-| 内容区 | OverallStyle=light | OverallStyle=light / contentMode=light |
-| 侧栏 | **`Theme=light` → 白菜单** | **`Theme=default` + `--sidebar-bg:#001529`** |
-| 主色 | EpThemeColor `#409EFF` | `tokens.brandPrimary`（如钴蓝 `#1B4FE0`） |
-
-**禁止**：把设计「浅色」写成 `Theme=light`。`contentMode/OverallStyle=light` 与 `Theme=light` 不是一回事。
-
-### `Version` 必须生效（落地核心）
-
-模版 `layout` / `configure` **优先读 localStorage**。只改 `platform-config.json` 而浏览器仍缓存 `Theme=light` → 侧栏一直白。
-
-模版已在 `injectResponsiveStorage`：当 **`Version` 与上次不同** 时删除 `layout`+`configure` 并按新配置重灌。
-
-因此设计落地时：**`Version` 必须自增**（如 `0.0.5` → `0.0.6`），否则 handoff 写了 `Theme=default` 也不会进页面。
-
-## 触发
-
-出现以下任一情况时执行本协议（与业务开发的先后跟用户需求：可先定风格再写业务，也可在已有业务上全量重构样式）：
-
-- 会话 / 附件 / 仓库中有 **`design-handoff/v1` JSON**（优先）
-- 会话有「前端落地交接」块 / `【主题色系】` / `:root` 令牌 CSS（兼容）
-- 用户要求按设计稿 / 规范适配或重构整站风格
-- 用户附带色板、规范或 HTML 原型
-
-动手改文件前先输出**规范识别回执**（见下文）。
-
-## 收集产出（优先级）
-
-| 优先 | 形态 | 用途 |
-|------|------|------|
-| **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`** + `--sidebar-*` | **`dark-gradient`（设计默认）→ `Theme: "default"`**（深色侧栏）；仅当设计明确要白菜单才 `"light"`。**禁止**因 contentMode=light 写成 Theme=light |
-| `shell.contentMode` / `darkMode` | `OverallStyle` / `DarkMode` | 设计浅色内容：`OverallStyle: "light"` + `DarkMode: false` |
-| `shell.dataTheme` | 可选；缺省时 `dark-gradient` → 运行时 `data-theme=default` | 与 Theme 一致 |
-| `shell.showModel` | `ShowModel` | 以 JSON 为准（设计常 `line`） |
-| `shell.contentMargin` | `--layout-content-padding` / `--vts-margin` | 如 `24`；有 handoff 才覆盖出厂 8 |
-| （整次落地） | **`Version` 自增** | **必做**；否则 localStorage 不重灌，Theme/ShowModel 不生效 |
-
-写入后：硬刷新或等 Version 失效逻辑清掉旧 `layout`/`configure`。
-
-### `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） |
-
-可选（设计组件规范提及或 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），回执注明。
-
-### `visual` → 视觉表现令牌（`design-tokens.scss` 视觉段 + `design-visual.scss`）
-
-有 `visual` 字段时写入 `design-tokens.scss` 的「视觉表现令牌」段；`design-visual.scss` 规则结构不动，只通过令牌值变化生效。
-
-| JSON 字段 | CSS 变量 | 用途 |
-|-----------|----------|------|
-| `visual.shadowCardRest` | `--shadow-card-rest` | 卡片静态阴影 |
-| `visual.shadowCardHover` | `--shadow-card-hover` | 卡片悬停阴影 |
-| `visual.shadowButtonHover` | `--shadow-button-hover` | 按钮悬停阴影 |
-| `visual.shadowInputFocus` | `--shadow-input-focus` | 输入框聚焦光环 |
-| `visual.shadowDialog` | `--shadow-dialog` | 弹窗阴影 |
-| `visual.transitionBase` | `--transition-base` | 基础过渡曲线 |
-| `visual.buttonHoverTransform` | `--transform-button-hover` | 按钮 hover 变换 |
-| `visual.tableHeaderBorderBottom` | `--table-header-border-bottom` | 表头强调底线 |
-| `visual.menuActiveBorderRight` | `--menu-active-border-right` | 菜单激活强调条 |
-
-缺项 → 保留出厂默认值，回执标明。
-
-### `layout` → 页面构图令牌（`design-tokens.scss` 构图段 + `design-layout.scss`）
-
-有 `layout` 字段时写入 `design-tokens.scss` 的「页面构图令牌」段；`design-layout.scss` 规则结构不动。
-
-| JSON 字段 | CSS 变量 | 用途 |
-|-----------|----------|------|
-| `layout.pageHeaderMargin` | `--page-header-margin` | 标题区下边距 |
-| `layout.filterAreaRadius` | `--filter-area-radius` | 筛选区圆角 |
-| `layout.filterAreaPaddingY` | `--filter-area-padding-y` | 筛选区上下内边距 |
-| `layout.filterAreaPaddingX` | `--filter-area-padding-x` | 筛选区左右内边距 |
-| `layout.actionBarGap` | `--action-bar-gap` | 操作栏按钮间距 |
-| `layout.tableAreaBorderRadius` | `--table-area-border-radius` | 表格区圆角 |
-| `layout.emptyStatePadding` | `--empty-state-padding` | 空状态间距 |
-
-缺项 → 保留出厂默认值，回执标明。
-
-### 卡片页签关闭色（设计约束）
-
-- 关闭 hover：圆形底 `--layout-bg`（=`tokens.layoutBg`）+ 图标 `--error-6` / `tokens.error`（`#F5222D`）
-- **禁止**用 Element Plus 默认 danger `#F56C6C` 冒充错误色
-
----
-
-## 覆盖清单
-
-| # | 落点 | 写入 |
-|---|------|------|
-| A | `src/styles/design-tokens.scss` | 令牌 CSS；深色侧栏时追加 `--sidebar-*`；`visual` / `layout` 段 |
-| B | `theme.scss` 当前 `html[data-theme]` | `--vts-theme-*` → `--sidebar-*` |
-| C | `public/platform-config.json` | `EpThemeColor` / `Theme` / `DarkMode` / **`ShowModel`**；`Version` 自增 |
-| D | `index.scss` | `design-tokens` → `design-visual` → `design-layout` 最先；按需 `--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"` 时 **整组必写**）：
-
-> 设计「浅色模式」= 内容浅 + 侧栏 `#001529`。落地时：
-
-```json
-// platform-config.json（示例片段）
-{
-  "Version": "<原值+1>",
-  "Theme": "default",
-  "OverallStyle": "light",
-  "DarkMode": false,
-  "EpThemeColor": "<brandPrimary>"
-}
-```
-
-```scss
-/* design-tokens.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);
-```
-
-`theme.scss` 中 `html[data-theme='default']` 已桥接 `--sidebar-*`。  
-自检：DevTools 中 `html` 的 `data-theme="default"`，`.sidebar-container` 背景为 `#001529`（非 `#fff`）。
-
----
-
-## 落地原子步骤（Agent 必按序；缺一步=失败）
-
-有 `design-handoff/v1` 时，**同一轮**完成：
-
-1. 回执（规范识别）  
-2. 写 `design-tokens.scss`：`brand*` / `primaryScale` / 几何 / **`--sidebar-*`（dark-gradient）** / contentMargin  
-3. 写 `platform-config.json`（**整组**）：  
-   - `EpThemeColor` = brandPrimary  
-   - `Theme` = **`default`**（若 `shell.sidebar=dark-gradient`）  
-   - `OverallStyle` = `light`（若 contentMode=light）  
-   - `DarkMode` = shell.darkMode  
-   - `ShowModel` = shell.showModel  
-   - **`Version` 自增**（字符串或数字均可，须与上次不同）  
-4. 核对表 A～E；硬失败项见下  
-5. 回执「已覆盖 / 保留出厂」；提醒用户**硬刷新**一次（Version 会清 layout 缓存）
-
-**反例（禁止）**：只改 `EpThemeColor` / `:root` 主色 → 侧栏仍白、未达完整落地效果。
-
-## 规范识别回执（动手前必出）
-
-```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. 收集产出（JSON 优先）  
-2. 规范识别回执  
-3. A→E（按映射表写）  
-4. F 冲突核对  
-5. 验证侧栏 / 主色 / 页签（按 JSON `showModel`）/ 内容边距  
-6. 提醒清 `localStorage`（改了 `EpThemeColor` / `ShowModel` / `Version` 时）  
-7. 若同轮还有业务需求 → 再写/改 views（仅样式任务则到此结束）
-
----
-
-## 兼容：旧交接块字段
-
-无 JSON 时仍可认（可整块粘贴到会话）：
-
-- 设计来源：上游产出
-- 主题色系：`<主题中文名>`
-- data-theme：`<模版 html[data-theme] 值>`
-- 侧栏：深色渐变 | 浅色
-- 内容区默认：亮色 | 暗黑
-- 主色：`#HEX`
-- ShowModel：以设计为准（当前规范默认 `line`；旧稿 `card`）| `smart` | `chrome`（未落地设计时保留模版默认）
-
-设计令牌 CSS 须含主色阶，并**建议含组件尺寸三档**：
-
-```css
-:root {
-  --brand-primary: #...;
-  --brand-hover: #...;
-  --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` | 未落地勿改 |
-| 侧栏（设计浅色页） | `Theme=default` + `--sidebar-bg:#001529` + **Version++** | 出厂 `Theme=light` 白侧栏；落地勿漏 |
-| 页签关闭/错误色 | `--error-color` / `--error-6` | `#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` + **`Theme=default`（深色侧栏）** + `OverallStyle` + `ShowModel` + **`Version++`**
-- [ ] `--sidebar-bg` 为 `#001529`；运行时 `data-theme=default`（不是 light）
-- [ ] 硬刷新后侧栏仍深色（证明 Version 已清缓存）
-- [ ] grep 壳层与 ReDialog：无不可覆盖裸 px
-- [ ] 回执列出「已覆盖 / 保留出厂」
-
----
-
-## 硬失败（code-quality 可引用）
-
-| 条件 | 处理 |
-|------|------|
-| 设计 `sidebar=dark-gradient` 但 `Theme` 仍为 `light`（或未改） | **硬失败**：改为 `default` 并 Version++ |
-| 设计落地只改了主色/tokens，未改 Theme / Version | **硬失败**：补全原子步骤 |
-| 用户要求按设计落地，但未写入 JSON 中的 `shell.showModel` | 硬失败：按 JSON 补写 |
-| JSON 有 `primaryScale` 但未写入 `--primary-0..9` | 硬失败 |
-| 用 `#F56C6C` 或未映射的 EP danger 代替 `tokens.error` | 硬失败：改为 `#F5222D` |
-| 改了 margin 后列表仍用 `100vh` 减顶栏 | 硬失败：迁 flex/`vts-page-card` |
-| 设计落地后壳层/弹窗写死 px | 硬失败：改 `var(--…)` |
-| 核对表有漏项且未标「保留出厂」 | 硬失败 |
+---
+skill: design-handoff
+description: 收到 design-handoff/v1 JSON 后，按逐文件修改清单执行。配置→令牌→框架组件→样式→页面代码，5 步 51 项。
+scope: project
+tags: [handoff, design-tokens, upstream, artifacts, json, modification-checklist]
+---
+
+# 设计落地修改清单
+
+> 收到 `design-handoff/v1` JSON 后，AI 按本清单逐项执行修改。
+> 每一项标注：JSON 来源 → 项目文件 → 修改内容 → 验证点。
+> 模板源码保持出厂状态，所有修改在 AI 生成/修改代码时完成。
+>
+> 1:1 还原要求见设计 Skill 的 `project-implementation-protocol.md`。
+
+## 双轨
+
+| 场景 | 行为 |
+|------|------|
+| **未调用设计 / 无 handoff** | 保持模板出厂（主色 `#409EFF`、`Theme: light`=白侧栏、`ShowModel: chrome`、margin 8） |
+| **有 design-handoff/v1 JSON** | 按本清单 5 步 51 项逐项执行；只改主色不改 Theme/Version = **落地失败** |
+
+## 触发
+
+- 会话 / 附件 / 仓库中有 `design-handoff/v1` JSON（`$schema` 字段识别）
+- 用户要求按设计稿 / 规范适配或重构整站风格
+- 命中 `design-system` 模块且设计 Skill 产出可用
+
+## 规范识别回执（动手前必出）
+
+```markdown
+## 规范识别回执
+- 来源形态：design-handoff/v1 JSON
+- 主题：{themeName} / {themeId} / 主色 {brandPrimary}
+- ShowModel：{shell.showModel}
+- 几何：header {n} / tabs {n} / margin {n}
+- 主色阶：完整 10 级
+- 侧栏：{shell.sidebar}
+- 结构要求：{structureRequirements.frameworkShell.header.length} 项
+- 交互要求：{Object.keys(interactionSpecs).length} 类
+- 将改文件：platform-config.json / design-tokens.scss / navbar / sidebar / tabs / app-main / element-plus.scss / dark.scss / 业务页面
+```
+
+---
+
+## 一、配置文件修改（C1-C8）
+
+| # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
+|---|---------|---------|---------|------|
+| C1 | `shell.sidebar` | `platform-config.json` → `Theme` | `dark-gradient` → `default`（深色侧栏）；仅明确要白菜单时 `light` | 侧栏背景为 `#001529` |
+| 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 缓存不刷新 |
+
+**禁止**：把设计「浅色内容」写成 `Theme=light`。`contentMode=light` 与 `Theme=light` 不是一回事。深色侧栏 = `Theme=default`。
+
+---
+
+## 二、令牌文件修改（T1-T12）
+
+写入 `src/styles/design-tokens.scss`，只改值，不改结构。
+
+| # | JSON 段 | 令牌段 | 修改内容 | 验证 |
+|---|---------|--------|---------|------|
+| T1 | `tokens` | 颜色段 | `--brand-primary` / `--primary-0..9` / `--success-color` / `--warning-color` / `--error-color` / `--layout-bg` / `--component-bg` | 值与 JSON 一致；`primaryScale[5] === brandPrimary` |
+| T2 | `typography` | 字体段 | `--font-family` / `--font-size-*` / `--font-weight-*` / `--line-height-*` | 值与 JSON 一致 |
+| T3 | `spacing` | 间距段 | `--spacing-base` / `--spacing-xs..2xl` | 值与 JSON 一致 |
+| T4 | `radius` | 圆角段 | `--radius-none..full` | 值与 JSON 一致 |
+| T5 | `border` | 边框段 | `--border-width` / `--border-color` / `--border-color-light` / `--border-color-dark` / `--split-color` | 值与 JSON 一致 |
+| T6 | `zIndex` | 层级段 | `--z-content` / `--z-header` / `--z-sider` / `--z-tabs` / `--z-dropdown` / `--z-modal` 等 | 值与 JSON 一致 |
+| T7 | `responsive` | 响应式段 | `--breakpoint-xs..2xl` | 值与 JSON 一致 |
+| T8 | `visual` | 视觉段 | `--shadow-card-rest` / `--shadow-card-hover` / `--shadow-button-hover` / `--shadow-input-focus` / `--shadow-dialog` / `--transition-base` / `--transform-button-hover` / `--table-header-border-bottom` / `--menu-active-border-right` | 值与 JSON 一致 |
+| T9 | `layout` | 构图段 | `--page-header-margin` / `--filter-area-radius` / `--filter-area-padding-y/x` / `--action-bar-gap` / `--table-area-border-radius` / `--empty-state-padding` | 值与 JSON 一致 |
+| T10 | `geometry` | 框架段 | `--header-height` / `--tabs-height` / `--sidebar-width` / `--sidebar-collapsed-width` / `--layout-content-padding` | 值与 JSON 一致 |
+| 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);
+```
+
+---
+
+## 三、框架组件修改（F1-F14 · 1:1 还原核心）
+
+> 此节实现 `structureRequirements` 和 `interactionSpecs` 的要求。
+> 模板源码保持出厂，AI 获取 JSON 后逐项修改组件代码。
+
+### 3.1 顶栏 navbar
+
+| # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
+|---|---------|---------|---------|------|
+| 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 效果与设计一致 |
+
+### 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`（深色），非出厂白色 | 侧栏深色 |
+
+### 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 风格） | 激活态视觉与设计一致 |
+
+### 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`） | 背景层次分明 |
+
+---
+
+## 四、样式文件修改（S1-S10）
+
+写入 `src/styles/element-plus.scss`（在既有规则基础上追加视觉规则段，引用令牌变量）。
+
+| # | 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`，引用令牌变量。设计落地时令牌值变化即生效，规则结构不动。
+
+---
+
+## 五、页面代码修改（P1-P7）
+
+| # | JSON 来源 | 项目文件 | 修改内容 | 验证 |
+|---|---------|---------|---------|------|
+| P1 | `pageStructure.regions` | 页面 .vue 文件 | 按 JSON 的 regions 列表实现页面区域，**不照抄 crud-pages 样板**，以 JSON 结构为准 | 区域完整且顺序正确 |
+| P2 | `structureRequirements.moduleComposition.pageHeader` | 页面 .vue → `.vts-page-header` | 标题 + 描述 + 操作按钮，flex 两端对齐 | 有页面标题区 |
+| P3 | `structureRequirements.moduleComposition.filterArea` | 页面 .vue → `.vts-filter-area` | 独立容器：背景 + 圆角 + 底部分隔线 | 筛选区有容器感 |
+| P4 | `structureRequirements.moduleComposition.tableArea` | 页面 .vue → `.vts-table-area` | 圆角 + 边框包裹 | 表格区有包裹感 |
+| P5 | `structureRequirements.moduleComposition.actionBar` | 页面 .vue → `.vts-action-bar` | 左侧批量操作 + 右侧工具按钮 | 操作栏布局正确 |
+| P6 | `interactionSpecs.*` | 页面 .vue | 页面内交互行为按 interactionSpecs 实现 | 交互完整 |
+| P7 | `tokens.*` | 页面 .vue | 所有值引用 CSS 变量，无硬编码 | 无裸值 |
+
+### crud-pages.md 设计模式样板的使用方式
+
+`crud-pages.md` 的设计模式样板是**起始模板**，不是最终代码。AI 使用时必须：
+
+1. 以样板为基础结构
+2. 读 JSON 的 `pageStructure.regions`，按实际区域调整（增/减/改顺序）
+3. 读 JSON 的 `structureRequirements.moduleComposition`，按实际布局调整区域内部结构
+4. 读 JSON 的 `interactionSpecs`，在页面代码中实现交互行为
+5. Re* 组件（ReTableBar / RePagination / ReTableOperate / ReGrid）的使用方式不变
+6. CSS 钩子类（`.vts-page-header` / `.vts-filter-area` / `.vts-table-area`）按 JSON `structureRequirements` 调整
+
+---
+
+## 六、执行顺序
+
+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
+
+---
+
+## 硬失败
+
+| 条件 | 处理 |
+|------|------|
+| 设计 `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` 补充 |