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

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,11 @@ 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` 逐文件修改清单（含 1:1 还原要求 F1-F14 / P1-P7）
+- **双轨**：无设计 handoff → 保持模版出厂；有设计落地 → 读 `design-handoff.md` 逐文件修改清单（含 1:1 还原要求 F1-F14 / P1-P7）
 - **设计优先级**：当设计技能产出（`design-handoff/v1` JSON）存在时，视觉层面（布局/间距/圆角/阴影/色彩/组件结构）以设计技能产出为准，本技能出厂默认值按设计产出替换。详见下方「设计优先级与 handoff 强制执行」段
 
 ## 使用方式
@@ -64,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/` 等业务改动同步修改；仅用户明确要求维护文档时才改
 
 ## 完整性守则（全模块强制）
 
@@ -76,7 +78,39 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 ## 设计落地（handoff）
 
-当会话中存在 `design-handoff/v1` JSON 时，**强制加载** `references/design-handoff.md`，按 C/T/F/S/P 五步全流程执行（配置→令牌→框架→样式→页面），**任一步跳过 = 硬失败**。设计产出优先级高于本技能出厂默认值，页面保留业务逻辑、重写视觉结构。完整规则与逐项清单见 `design-handoff.md`。
+设计技能（project-ui-design）每次产出时**始终自动附加 `design-handoff/v1` JSON**。本技能检测到 JSON 后**强制加载** `references/design-handoff.md`，按 C/T/F/Co/S/P 六步全流程执行（配置→令牌→框架→共享组件→样式→页面），**任一步跳过 = 硬失败**。设计产出优先级高于本技能出厂默认值，页面保留业务逻辑、重写视觉结构。用户无需提及「JSON」或「handoff」——这是两技能间的自动协议。完整规则与逐项清单见 `design-handoff.md`。
+
+### 项目级模式 vs 单页模式
+
+通过 JSON 的 `meta.transformScope` 字段自动识别改造范围：
+
+| 模式 | 触发条件 | 执行范围 | 关键规则 |
+|------|---------|---------|---------|
+| **单页模式**（默认） | `transformScope: "single-page"` 或未设置 | C/T/F/Co/S + 单个页面 P 步骤 | 只改造当前对话涉及的页面，框架/共享组件若已改造则跳过 |
+| **项目级模式** | `transformScope: "project"` | C/T/F/Co/S（全局一次） + **全页面遍历改造** | 先扫描全部路由，构建页面清单，逐页面执行 P 步骤，全部完成后做全量校验 |
+
+**项目级模式核心规则**：
+1. 先扫描 `src/router/modules/` 所有路由文件，构建页面清单
+2. C/T/F/Co/S 是全局的，只执行一次（框架 + 共享组件）
+3. 逐页面执行 P1-P7，每页标记 `status: completed`
+4. 单次对话改不完时，输出进度 + 待改造页面清单，用户说「继续」时从断点恢复
+5. **禁止在未完成全部页面前声称任务完成**——必须明确告知进度和剩余页面
+
+### 设计概念 → 项目组件映射
+
+设计 skill 定义了"表格工具栏""操作列""导航栏"等设计概念，本技能通过映射表自动找到项目中对应的组件进行修改。映射表见 `design-handoff.md` 第八章（共享组件级落地）。共享组件在 Co 步骤（F 步骤之后、S 步骤之前）统一修改，**一处修改，全局生效**，不需要在每个页面重复处理。
+
+### ⚠️ 设计落地绝对禁止修改 docs/**
+
+设计落地场景下，`docs/` 目录为**只读**，绝对禁止修改：
+- ❌ 不得把设计产出的 HTML 保存到 `docs/`
+- ❌ 不得在 `docs/` 中生成设计规范文档
+- ❌ 不得修改 `docs/style-templates/` 的演示页
+- ✅ 设计修改只落在 `src/`、`public/`、`platform-config.json` 等业务代码中
+- ✅ 设计规范直接读取设计 skill 的 references 文件，不另存
+- ✅ 设计产出 HTML 仅在对话中作为参考对照，不写入项目
+
+违反此规则即硬失败，必须立即撤销对 docs/ 的修改。
 
 ## 模块路由表
 
@@ -93,7 +127,7 @@ 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`（项目设计系统说明） |
+| 设计交接块 / **design-handoff/v1 JSON** / 上游令牌产出落地 | `references/design-handoff.md`（逐文件修改清单）+ `design-system.md`（项目设计系统说明） |
 | **设计模式**（设计 Skill 产出存在时触发） | `crud-pages.md` 设计模式样板 + `design-handoff.md` 1:1 还原要求（F1-F14 / P1-P7） |
 
 ### 标准业务面
@@ -147,7 +181,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`
@@ -169,7 +203,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`（逐文件修改清单，含 1:1 还原 F1-F14 / P1-P7）
+   - 按 XX / UI 规范适配、设计交接块、整站风格重构 → `design-system`（项目设计系统说明）+ `layout-theme`；有令牌/交接产出时加读 `design-handoff.md`（逐文件修改清单，含 C/T/F/Co/S/P 全流程 + 共享组件映射 + 项目级模式）
    - 列表→独立详情/编辑页 → `crud-pages` + `detail-page`
    - 图表（折线/柱状/饼图） → `chart-echarts`
    - 数据大屏、看板 → `data-screen`
@@ -193,12 +227,21 @@ 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/v1 JSON 是否存在** — 若存在，强制加载 `design-handoff`（逐文件修改清单，含 C/T/F/S/P 全流程）+ `design-system.md`，并按设计产出优先级执行
-3. **依赖**：缺包按 inventory 第九节精确版本，确认后安装；**再按 `addon-enable` 对应章节改配置**
-4. **探查**：复用仓库 `Re*` / Hook / utils
-5. **生成**：可运行代码落盘；**有 handoff JSON 时，页面结构以设计输出为准，保留业务逻辑**
-6. **code-quality**：按 `references/code-quality.md` 执行；**有 handoff JSON 时，额外执行 handoff 落地完整性校验**（见 `design-handoff.md` 末尾）
-7. **输出**：变更说明（含已改配置文件列表）+ 待确认项
+2. **加载**：`core-kernel` + 命中模块；addon/缺包时加读 `project-inventory` + **`addon-enable`**；**检测 design-handoff/v1 JSON 是否存在** — 若存在，强制加载 `design-handoff`（逐文件修改清单，含 C/T/F/Co/S/P 全流程 + 共享组件映射 + 项目级模式）+ `design-system.md`，并按设计产出优先级执行
+3. **模式判断**：有 handoff JSON 时，读取 `meta.transformScope`：
+   - `project` → 进入**项目级模式**：先扫描 `src/router/modules/` 构建页面清单，输出「待改造页面清单」供用户确认
+   - `single-page` 或未设置 → 单页模式，仅处理当前页面
+4. **依赖**：缺包按 inventory 第九节精确版本，确认后安装；**再按 `addon-enable` 对应章节改配置**
+5. **探查**：复用仓库 `Re*` / Hook / utils；**项目级模式下**，探查所有共享组件（ReTableBar / ReTableOperate / RePagination 等）的当前实现
+6. **生成**：
+   - 单页模式：C/T/F/Co/S + 当前页面 P 步骤
+   - 项目级模式：C/T/F/Co/S（全局一次） + 逐页面执行 P 步骤，标记完成状态
+   - **有 handoff JSON 时，页面结构以设计输出为准，保留业务逻辑**
+   - **禁止**同步修改 `docs/**`（除非用户明确要求维护文档）
+7. **设计还原度验证**：有 handoff JSON 时必须执行，按 `design-handoff.md` 第十章逐区域逐元素对照设计规范验证，输出「设计还原度验证报告」，未通过项必须修正
+8. **功能完整性核查**：有 handoff JSON 时必须执行，按 `design-handoff.md` 第十一章逐项核查功能是否正常（框架/共享组件/页面），样式改造不得破坏原有功能，发现问题立即修正
+9. **code-quality**：按 `references/code-quality.md` 执行；**有 handoff JSON 时，额外执行 handoff 落地完整性校验**（项目级模式需校验全页面完成度 + 共享组件修改 + 设计还原度 + 功能完整性）
+10. **输出**：变更说明（含已改配置文件列表）+ 设计还原度验证报告 + 功能完整性核查报告 + 待确认项；**项目级模式未全部完成时，输出进度 + 待改造页面清单 + 「继续」指令提示**
 
 ### 最终回复结构
 

package/package.json

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

package/references/code-quality.md

@@ -49,17 +49,104 @@ 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 文字不变淡（加深为品牌色）
+- [ ] 所有视觉规则在暗色模式下有对应覆盖
+
+#### 共享组件层（10 项）
+
+- [ ] ReTableBar 工具栏按钮样式符合设计规范（刷新/密度/列设置：icon 16px、按钮 32px、分隔线 1px）
+- [ ] ReTableBar 工具栏左右布局正确（左批量操作、右工具按钮）
+- [ ] ReTableBar 标题区：设计模式下无多余「展示列表」标题文字
+- [ ] ReTableOperate 操作列：纯文字链接，无图标，按钮间有 1px×14px 竖分隔线
+- [ ] ReTableOperate「更多」按钮：带 10px 下拉箭头，下拉菜单样式正确
+- [ ] ReTableOperate 折叠阈值：limit 默认 3，列宽动态计算（`resolveOperateColumnWidth`）
+- [ ] RePagination 分页样式符合设计规范（两段式布局、可选 10/20/50 条）
+- [ ] 侧栏菜单激活态：实色品牌底 + 左侧 3px 指示条 + 白色文字（非 8% 透明底）
+- [ ] 顶栏折叠按钮：垂直居中，40×40px；设置按钮：已隐藏/删除
+- [ ] 内容区模块分割线：各区域间距与设计规范一致（标题 20px / 筛选 20px / 工具栏 20px 8px / 表格 0 20px / 分页 8px 20px 20px）
+
+#### 页面层（11 项）
+
+- [ ] 页面有标题区（`.vts-page-header`：标题 + 描述 + 操作按钮）
+- [ ] 筛选区有容器感（`.vts-filter-area`：背景 + 底部分割线）
+- [ ] 操作栏存在（`.vts-action-bar`：批量操作 + 工具按钮）
+- [ ] 表格区有包裹感（`.vts-table-area`）
+- [ ] 状态标签样式符合规范（filled/outlined/solid 按列分配）
+- [ ] 操作列统一为文字链接 + "更多"下拉（ReTableOperate）
+- [ ] 设计中未体现的元素已隐藏/移除（对照元素自查隐藏清单 4.1-4.4）
+- [ ] 所有样式值引用 CSS 变量，无裸 hex/px 值
+- [ ] 页面无「展示列表」等多余标题文字
+- [ ] 页面无「左侧按钮可以增加多个」「增加一行可编辑数据」等示例按钮
+- [ ] 操作列按钮无多余图标，仅保留文字 + 竖分隔线
+
+#### 项目级完成性（transformScope=project 时额外执行）
+
+- [ ] 已扫描全部路由模块（`src/router/modules/`），页面清单完整
+- [ ] 所有列表页均已按设计规范改造（base/tree/vxe-table 等）
+- [ ] 所有表单页均已按设计规范改造
+- [ ] 所有详情页均已按设计规范改造
+- [ ] 工作台/仪表盘/数据大屏等其他页面均已按设计规范改造
+- [ ] 共享组件（ReTableBar/ReTableOperate/RePagination）已全局修改
+- [ ] 框架组件（navbar/sidebar/tabs/app-main）已全局修改
+- [ ] 元素隐藏清单已逐项检查并处理（顶栏/侧栏/列表/共享组件 四类）
+- [ ] 无遗漏页面（对照路由清单逐一核对）
+- [ ] 所有页面的多余元素（「展示列表」「左侧按钮...」等）均已清除
+
+#### 设计还原度验证（有 handoff JSON 时必须执行）
+
+> 验证依据：设计 skill 的规范文件（design-tokens.md / unified-framework.md / list-page.md / component-spec.md）
+> 验证方法：代码级对照——读取设计规范预期值 → 检查项目代码实际值 → 比对是否一致
+> 验证顺序：框架层 → 页面层 → 共享组件层 → 细节项 → 元素清理
+
+- [ ] **框架层还原度**：顶栏高度/元素/折叠位置、侧栏宽度/背景/激活态、页签高度/激活态、内容区背景/padding，共 10 项已逐项对照
+- [ ] **页面层还原度**：卡片阴影圆角、标题区字号/padding、筛选区背景/分隔线、工具栏布局/按钮、表格表头/行高/hover、操作列样式、分页布局、模块分割线/间距，共 12 项已逐项对照
+- [ ] **共享组件还原度**：ReTableBar（按钮样式/布局/分页集成）、ReTableOperate（文字链接/分隔线/更多箭头/折叠逻辑）、RePagination（样式/布局），共 10 项已逐项对照
+- [ ] **核心组件还原度**：按钮（高度/圆角/主色三态）、输入框（高度/圆角/focus 光环）、Tag（5 种状态色）、下拉菜单、空状态，已逐项对照
+- [ ] **细节项还原度**：图标大小 16px、分隔线 #F0F0F0、hover 文字加深不变浅、行高正确、字重正确、圆角统一、阴影自然、更多按钮有箭头、操作列有竖分隔线、页签下划线居中、操作列 sticky、选择列 48px、状态标签颜色对应、卡片有阴影，共 15 项已逐项检查
+- [ ] **令牌溯源检查**：颜色/尺寸/间距均通过 CSS 变量传递，变量值与 design-tokens.md 一致，无裸 hex/px 值
+- [ ] **元素清理检查**：设置按钮、展示列表标题、示例按钮、操作列多余图标等已全部移除
+- [ ] **已输出「设计还原度验证报告」**（格式见 design-handoff.md 第十章 10.7），包含整体还原度、各层通过率、偏差项及修正方案
+- [ ] **绝对禁止**：设计落地过程中未修改 `docs/**` 下任何文件（设计产出 HTML 不写入项目，设计规范不另存文档，所有修改只在 src/ 等业务代码中）
+- [ ] **功能完整性核查**：样式改造后原有功能全部正常（框架层/共享组件层/页面层均已逐项核查，无按钮失效、事件丢失、数据绑定断裂等功能回归问题）
+- [ ] **已输出「功能完整性核查报告」**（格式见 design-handoff.md 第十一章 11.7），包含整体通过率、各层核查结果、发现的问题及修正方案
+
+> ⚠️ 硬约束：设计还原度验证未通过的项，必须修正后重新验证，直至全部通过。禁止带着未修正的偏差项进入后续环节。
 
 ## 选型与硬约束
 

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` / 自造「更多」菜单。