@qilitt-mickey/vue3-temp-skill 1.1.17 → 1.1.18

package/SKILL.md

@@ -13,7 +13,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
 
 - 面向由 **vue3-web-temp** 脚手架搭出的业务项目（目录名/安装路径因人而异，以当前工作区为准）
 - 业务写法以本包 `references/` 为准；壳层行为（顶部 tag / 侧栏 / keep-alive / `useDetail`）以**当前项目**已有实现为准
-- **双轨**：无设计 handoff → 保持模版出厂令牌；有设计落地 → 读 `design-handoff.md`，按设计规范回填令牌（视觉关键尺寸须为 CSS 变量）
+- **双轨**：无设计 handoff → 保持模版出厂；有设计落地 → 读 `design-handoff.md` **原子步骤**（`Theme`/`Version`/令牌整组，禁止只改主色）
 
 ## 使用方式
 

package/package.json

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

package/references/code-quality.md

@@ -103,7 +103,7 @@ lint / type-check **过了也不能放过**下列项。发现即改代码，禁
 - [ ] 规范识别回执；令牌 / `platform-config.json` / 侧栏主题一致
 - [ ] 已建 `design-tokens.scss`；`index.scss` 中其 `@use` 最前
 - [ ] 冲突清单已逐条处理（见 `design-system`）
-- [ ] 有上游设计产出时已读 `design-handoff`：JSON 优先；按**全量令牌核对表 A～E**回填或回执「保留出厂」；`ShowModel` 写 JSON 值（设计默认常 `line`）；错误色 `#F5222D`；弹窗/壳层改令牌即生效
+- [ ] 有上游设计产出时已读 `design-handoff`：JSON 优先；**原子步骤**含 `Theme=default`（深色侧栏）+ `--sidebar-*` + **`Version++`** + 主色阶；禁止只改 EpThemeColor；错误色 `#F5222D`
 - [ ] **无**设计落地时未改出厂主色 / ShowModel / 壳层 / 弹窗几何默认
 - [ ] 组件尺寸三档已落地并桥接 `--el-component-size*`；缺档落到 default；未全局强制 `size="small"`；**查询区不写 size**（三档对照表 ≠ 查询区要用 small）
 

package/references/design-handoff.md

@@ -11,11 +11,29 @@ 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)`，改令牌即全局生效 |
+| **未调用设计 / 无 handoff** | 保持模版出厂（主色 `#409EFF`、`Theme: light`=**白侧栏**、`ShowModel: chrome`、margin 8 等）。**禁止**为「看起来像设计」而改出厂 |
+| **有 design-handoff/v1 或用户要求按设计落地** | 按下文「落地原子步骤」**整组**回填；只改主色/令牌、不改 `Theme`/`Version` = **落地失败** |
 
-跨编辑器一致：设计侧 `handoff-output.md`（**JSON 字段形状**）+ 本文件（**→ 模版映射**）+ 模版 `design-tokens.scss` 注释对齐。  
-**分工**：设计师只改视觉规范正文，不维护本映射表；规范装进不了现有 JSON 时，由研发扩 `handoff-output` Schema 并同步改本文件。禁止只改文档不改令牌、或只改裸 px 不改令牌。
+跨编辑器一致：设计侧 `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` 也不会进页面。
 
 ## 触发
 
@@ -62,16 +80,14 @@ tags: [handoff, design-tokens, upstream, artifacts, 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`** | **以 JSON 为准**写入（设计当前默认 **`line`**；旧稿可能为 `card`） |
-| `shell.contentMargin` | `--layout-content-padding`（及桥接 `--vts-margin`） | 数字 px，如 `24`（模版出厂常为 **8**；**有 handoff 才覆盖**） |
+| `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 不生效 |
 
-写入 `ShowModel` 后同步 `$storage.configure.showModel`（或 bump `Version` 清缓存）。  
-- **`card`**：写 `--vts-tag-card-*`（见 geometry）  
-- **`line`**：无容器文字页签（见 `notes` / `homeTabSize` / `tagDividerWidth`）；模版若尚未实现该枚举 → 回执「待实现 line」，**禁止**静默改成 `card`；可先落令牌与配置，页签样式单开任务  
-- **`chrome` / `smart`**：仅当 JSON 明确要求时写入
+写入后：硬刷新或等 Version 失效逻辑清掉旧 `layout`/`configure`。
 
 ### `geometry` → 令牌
 
@@ -162,12 +178,23 @@ tags: [handoff, design-tokens, upstream, artifacts, json]
 | JSON=`line` 且模版无实现 | 回执待实现；勿改写成 `card` |
 | 用户在设置面板手动切换 | 以用户选择为准 |
 
-侧栏派生（`shell.sidebar === "dark-gradient"` 时）：
+侧栏派生（`shell.sidebar === "dark-gradient"` 时 **整组必写**）：
 
-> **视觉权威**：`page-templates` 规定深色侧栏底为 **`#001529` 纯色**，菜单激活为 **`--primary-color` 纯色**（禁止把激活态做成渐变）。  
-> 协议字段名仍叫 `dark-gradient`（表示「深色侧栏模式」相对 `light`）；**落地色值以 page-templates 为准**，勿再套用旧版「主色阶拼纵向渐变」公式。
+> 设计「浅色模式」= 内容浅 + 侧栏 `#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;
@@ -175,16 +202,34 @@ tags: [handoff, design-tokens, upstream, artifacts, json]
 --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-menu-active-bg: var(--primary-color);
 --sidebar-submenu-bg: color-mix(in srgb, #001529 82%, #000);
 --sidebar-active-indicator: var(--primary-color);
 ```
 
-`theme.scss`：`--vts-theme-menu-bg: var(--sidebar-bg);` 等 → `layout-theme`。
-自检：侧栏 computed 背景为 `#001529`（或 `var(--sidebar-bg)`）；激活块 = `--primary-color` / `brandPrimary`。
+`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
@@ -262,8 +307,9 @@ tags: [handoff, design-tokens, upstream, artifacts, json]
 | 侧栏宽 / 收起 | `--sidebar-width` / `--sidebar-collapsed-width` | 208 / 64 |
 | 内容区内边距 | `--layout-content-padding` → `--vts-margin` | 出厂 8；设计常 24 |
 | 页脚高 | `--layout-footer-height` | 48 |
-| 页签风格 | `ShowModel` = JSON `shell.showModel`（默认 `line`；`card` 时写 `--vts-tag-card-*`） | 未落地勿改 |
-| 页签关闭/错误色 | `--error-color` / `--error-6`；`card` 时尚有 `--vts-tag-card-close-*` | `#F5222D` |
+| 页签风格 | `ShowModel` = JSON `shell.showModel` | 未落地勿改 |
+| 侧栏（设计浅色页） | `Theme=default` + `--sidebar-bg:#001529` + **Version++** | 出厂 `Theme=light` 白侧栏；落地勿漏 |
+| 页签关闭/错误色 | `--error-color` / `--error-6` | `#F5222D` |
 
 ### B. 色板与文字
 
@@ -301,11 +347,11 @@ tags: [handoff, design-tokens, upstream, artifacts, json]
 
 ### E. 落地后自检
 
-- [ ] `platform-config`：`EpThemeColor` / `ShowModel` / `Theme` / `DarkMode` / `Version++`
-- [ ] 侧栏深色渐变时 `--sidebar-*` + `theme.scss` 桥接
+- [ ] `platform-config`：`EpThemeColor` + **`Theme=default`（深色侧栏）** + `OverallStyle` + `ShowModel` + **`Version++`**
+- [ ] `--sidebar-bg` 为 `#001529`；运行时 `data-theme=default`（不是 light）
+- [ ] 硬刷新后侧栏仍深色（证明 Version 已清缓存）
 - [ ] grep 壳层与 ReDialog：无不可覆盖裸 px
-- [ ] 列表页仍无 `100vh` 减顶栏；margin 变化后 flex 链正常
-- [ ] 回执列出「已覆盖 / 保留出厂」字段清单
+- [ ] 回执列出「已覆盖 / 保留出厂」
 
 ---
 
@@ -313,9 +359,11 @@ tags: [handoff, design-tokens, upstream, artifacts, json]
 
 | 条件 | 处理 |
 |------|------|
-| 用户要求按设计落地，但未写入 JSON 中的 `shell.showModel` | 硬失败：按 JSON 补写配置（默认常为 `line`） |
+| 设计 `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` / `--error-color` |
-| 改了 `--layout-content-padding` / `--vts-margin` 后列表仍用 `100vh` 减顶栏定高 | 硬失败：迁 flex/`vts-page-card` |
-| 设计落地后壳层/弹窗写死 px、改令牌不生效 | 硬失败：消费点改为 `var(--…)` 再回填 |
-| 设计落地核对表（壳/色/控件/弹窗）有漏项且未标「保留出厂」 | 硬失败：补回填或回执注明 |
+| 用 `#F56C6C` 或未映射的 EP danger 代替 `tokens.error` | 硬失败：改为 `#F5222D` |
+| 改了 margin 后列表仍用 `100vh` 减顶栏 | 硬失败：迁 flex/`vts-page-card` |
+| 设计落地后壳层/弹窗写死 px | 硬失败：改 `var(--…)` |
+| 核对表有漏项且未标「保留出厂」 | 硬失败 |

package/references/layout-theme.md

@@ -64,8 +64,8 @@ tags: [vue3, layout, theme, dark-mode, css-variables, design-tokens, element-plu
 
 | 主题名 | 中文名 | 说明 |
 |--------|--------|------|
-| `light` | 亮白色 | 浅色侧栏 |
-| `default` | 道奇蓝 | 深色侧栏（出厂 `#001529`） |
+| `light` | 亮白色 | **白侧栏**（模版出厂常见 `Theme`） |
+| `default` | 道奇蓝 | **深色侧栏** `#001529`（设计 handoff `sidebar=dark-gradient` 必须切到此项） |
 | `saucePurple` | 深紫罗兰 | 深色侧栏 |
 | `pink` | 深粉色 | 深色侧栏 |
 | `dusk` | 猩红色 | 深色侧栏 |
@@ -73,7 +73,8 @@ tags: [vue3, layout, theme, dark-mode, css-variables, design-tokens, element-plu
 | `mingQing` | 绿宝石 | 深色侧栏 |
 | `auroraGreen` | 酸橙绿 | 深色侧栏 |
 
-> **上游设计技能衔接**：色值与 `data-theme` 对应关系读 upstream 交接块，不在本 Skill 写死。落地时同步 `design-tokens.scss`、`theme.scss` 桥接、`platform-config.json` 的 `Theme` / `EpThemeColor`。
+> **正交**：`OverallStyle`/`DarkMode` = 内容区浅/深；`Theme` = 侧栏配色。设计「浅色模式」≠ `Theme=light`。  
+> 设计落地：`Theme=default` + `--sidebar-*` + **`Version` 自增**（见 `design-handoff`；否则 localStorage 仍白侧栏）。
 
 ### 2.1.1 侧栏扩展变量（设计技能落地后写入）
 
@@ -97,8 +98,9 @@ tags: [vue3, layout, theme, dark-mode, css-variables, design-tokens, element-plu
 
 **关键逻辑**：
 - 主色通过 `document.documentElement.style.setProperty('--el-color-primary', color)` 直接设置。
-- `light` 和 `default` 主题使用配置文件中的 `EpThemeColor`，其他主题使用预设色卡中的颜色。
-- 切换暗黑模式时，如果当前主题是 `light`，会自动切到 `default`（因为亮白色在暗黑下不协调）。
+- `light` 和 `default` 使用配置里的 `EpThemeColor`；其它主题用色卡色。
+- 整体切暗黑且当前为 `light`（白侧栏）时，自动切到 `default`。
+- 设计落地必须把 `Theme` 写成 `default` 并 **Version++**，不能只改主色。
 
 ### 2.3 自定义主题色配置