@qilitt-mickey/vue3-temp-skill 1.1.6 → 1.1.8

package/SKILL.md

@@ -126,7 +126,7 @@ tags: [vue3, typescript, element-plus, vant, pinia, vite, unocss, crud, componen
    - 「导出 Excel / 下载文件」→ `download-export`  
    - 「菜单加图标 / 换图标 / 图标选择器 / 本地 SVG 图标」→ `icons`  
    - 「粒子背景 / 登录粒子 / 粒子特效」→ `particles`  
-   - 「按 Ant Design / Semi / Arco / Vuetify / 京东 等设计规范适配」「套 UI 规范」「让项目符合 XX 规范」→ `design-system`（+ `layout-theme`）：必须完整执行其 8 步适配工作流（识别回执 + 令牌层 + 组件几何重写层 + 模版硬编码冲突逐条回填 + 存量裸值扫描）；适配层文件名锁定 `design-tokens.scss` / `design-controls.scss`；禁止只改 `--el-color-primary` 就宣称已适配，禁止识别漂移  
+   - 「按 Ant Design / Semi / Arco / Vuetify / 京东 等设计规范适配」「套 UI 规范」「让项目符合 XX 规范」→ `design-system`（+ `layout-theme`）：必须完整执行其适配工作流（识别回执 + 令牌层（唯一新增文件）+ 几何重写并入 element-plus.scss + 硬编码冲突逐条回填 + 公共区域适配 + 存量裸值扫描）；适配新增文件只允许 `design-tokens.scss`；组件层永远是 Element Plus，适配只换令牌数据不换组件；禁止只改 `--el-color-primary` 就宣称已适配，禁止识别漂移
    - 只说「自定义指令」未说明效果 → 先追问，禁止默认塞模块  
 6. **HTTP**：方法跟后端文档，**允许 GET/POST**；POST→`data`，GET→`params`；真实 URL 用 `VITE_API_BASE_URL`；`/mock` 仅本地 Fake Server；无单请求 `crypto: true`。
 
@@ -208,6 +208,7 @@ reset();    // 重置（配合 formRef.resetFields）
 - `<script setup lang="ts">` + `defineOptions({ name })`
 - Re*：`type.ts` + 显式 import
 - `$t('中文key')`；`import.meta.env.VITE_*`；禁止不可信 `v-html`
+- **样式契约**：UnoCSS 连字符类名（`p-5`/`w-full`，禁 `p5`/`w100%`）+ 语义色变量（`bg-bg_color`，禁 `bg-[#fff] dark:bg-[#303030]`）+ 尺寸档位（查询/工具栏 `small`、表格 `:size="size"`、弹窗表单 default、整屏 `large`）；详见 `core-kernel`「四之二、样式契约」
 
 ---
 
@@ -289,7 +290,8 @@ reset();    // 重置（配合 formRef.resetFields）
 **4. 安全** — 无危险 v-html；无硬编码密钥  
 **5. 业务** — `onSearch`/`reset`；提交 loading；权限；未二次 Layout  
 **5b. 列表布局** — `el-card`+`content`+固定 height；查询/展示分区；`tableHeight`；分页在 ReTableBar 内  
-**5c. 设计规范遵从（命中 design-system 时必查）** — 已输出识别回执且三点一致；令牌层/几何重写层已建立且 `@use` 顺序正确、文件名未漂移；第四节硬编码冲突清单逐条处理并回填；存量裸值扫描已执行；业务代码无裸控件高度/内边距/字号；验证清单全过  
+**5c. 设计规范遵从（命中 design-system 时必查）** — 已输出识别回执且三点一致；令牌层（唯一新增）已建立、几何重写并入 element-plus.scss、文件名未漂移；第四节硬编码冲突清单逐条处理并回填；公共区域（侧栏/导航/壳变量）已适配；存量裸值扫描已执行；业务代码无裸控件高度/内边距/字号；验证清单全过  
+**5d. 样式契约（每次生成必查）** — UnoCSS 连字符形态（`p-5`/`w-full`；无 `p5`/`w100%`）；颜色语义变量（无 `bg-[#fff] dark:bg-[#303030]`）；组件尺寸档位（查询/工具栏 `small`、表格 `:size="size"`、弹窗表单 default、整屏 `large`）；间距 4px 基数；细则见 `core-kernel`「四之二」  
 **6. 风格** — 无多余 console；`$t('中文')`；`--vts-*` / UnoCSS；图标走 `svg-icon` / `icons` 约定  
 
 完整项见 `references/code-quality.md`。

package/package.json

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

package/references/code-quality.md

@@ -228,6 +228,9 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 - [ ] 样式使用 `scoped`，不会污染全局。
 - [ ] 颜色使用 CSS 变量（`var(--el-color-primary)`），不硬编码。
 - [ ] 优先使用 UnoCSS 原子类（`flex-center`、`mb-4`）。
+- [ ] UnoCSS 类名为连字符形态：`p-5` / `w-full` / `px-5` / `gap-10`；禁止 `p5` / `w100%` / `px5` / `gap10`（无 CSS 产出，样式静默失效）。
+- [ ] 背景/文字色按语义取变量：`bg-bg_color` / `var(--el-text-color-*)`；禁止 `bg-[#fff]` + `dark:bg-[#303030]` 成对硬编码。
+- [ ] 组件尺寸按场景档位：查询区与 `ReTableBar` 工具栏按钮 `size="small"`；表格 `:size="size"`（禁写死）；弹窗表单 default；整屏主表单 `large`（细则见 `core-kernel`「四之二、样式契约」）。
 - [ ] 业务图标优先 `<svg-icon name="..." />`（本地无冒号 / Iconify 含 `:`）；菜单 `meta.icon` 为 string；细则见 `icons`。
 - [ ] 不使用 `!important`，除非覆盖第三方组件样式且有注释说明。
 - [ ] 不使用深层嵌套选择器（不超过 3 层）。
@@ -241,11 +244,12 @@ const fullName = computed(() => `${user.firstName} ${user.lastName}`);
 ### 设计规范遵从（命中 design-system 时必查，细则见 `design-system.md`）
 
 - [ ] 已输出「规范识别回执」，且规范 ID / 主色在令牌层、`platform-config.json`、侧栏主题三处一致（防识别漂移）。
-- [ ] 已建立令牌层 `design-tokens.scss`（含用户可自定义区块 + 模版桥接令牌 + `--el-*` 映射）与几何重写层 `design-controls.scss`；文件名不得漂移成 `tokens.scss` / `semi-controls.scss` 等变体。
-- [ ] `index.scss` 中 `@use` 顺序：`design-tokens` 最前，`design-controls` 在 `element-plus` 之后。
+- [ ] 已建立令牌层 `design-tokens.scss`（**唯一新增文件**，纯 `:root` 数据无选择器；含用户可自定义区块 + 模版桥接令牌 + `--el-*` 映射）；组件几何重写已并入 `element-plus.scss`（令牌引用 + 规范注释）；文件名不得漂移成 `tokens.scss` 等变体，无独立重写层文件残留。
+- [ ] `index.scss` 中 `design-tokens` 位于 `@use` 最前；模版其余顺序未动。
 - [ ] `design-system.md` 第四节「模版硬编码冲突清单」逐条处理并在回复中逐条回填（重点：通配符 font-family、reset.scss body 字体与 `label { font-weight: 700 }`、`.el-card__body` padding 5px、弹窗渐变蓝底、表头硬编码色）。
 - [ ] 主色三态（hover/active）、字体、控件高度、圆角、卡片内边距、表单标签字重、表头视觉均符合目标规范（按第二节验证清单核验）。
-- [ ] 业务代码无裸控件高度/内边距/字号/圆角；组件几何覆盖只集中在 `design-controls.scss`；存量裸值扫描已执行。
+- [ ] 业务代码无裸控件高度/内边距/字号/圆角；组件几何覆盖只集中在 `element-plus.scss`；存量裸值扫描已执行。
+- [ ] 公共区域已按规范落地：`theme.scss` 侧栏配色（激活条 = 规范主色）、`index.scss` 壳变量（导航高/内容边距/弹窗底）、`HeaderHeight` 一致。
 - [ ] `platform-config.json` 的 `EpThemeColor` 与规范主色一致，已提醒清理 localStorage 缓存；新增令牌已在 `dark.scss` 补暗色覆盖。
 
 ## 七、业务逻辑检查

package/references/core-kernel.md

@@ -30,6 +30,7 @@ tags: [vue3, kernel, conventions, layout, router, http, crud, inventory]
 | 10 | 新三方依赖必须用户确认；已有封装须复用，选型表指定库勿擅自替换 |
 | 11 | **查询列表页布局硬约束**（见下方黄金样板）：`el-card` + `ref="content"` + **固定 `height`**（非 `minHeight`）；查询区与表格区分区；表格用 `tableHeight`；分页放在 `ReTableBar` 内 |
 | 11 | addon 缺失时按 `project-inventory` 第九节**精确版本**安装；禁止 `@latest` / 无版本号；Vite 插件与 `build/plugins/*` 成套核对 |
+| 12 | **样式契约**（见「四之二」）：UnoCSS 类名必须连字符形态（`p-5`/`w-full`，禁止 `p5`/`w100%`）；颜色按语义取 `--el-*`/`--vts-*` 变量（禁止 `bg-[#fff] dark:bg-[#303030]` 成对硬编码）；组件尺寸按场景档位（查询/工具栏 `small`、表格 `:size="size"`、弹窗表单 default、整屏主表单 `large`）；`design-tokens.scss` 存在时零新增硬编码裸值 |
 
 ---
 
@@ -336,6 +337,85 @@ function handleSizeChange(size: number) {
 
 ---
 
+## 四之二、样式契约（所有生成代码必须遵循）
+
+> 本节是**生成任何页面/组件代码时的样式真相源**：尺寸、间距、边距、颜色、组件档位全部按此执行。后期设计类 Skill（如 ui-ux-pro-max / project-style-design）产出设计规范后，规范经 `design-system` 模块落到 `design-tokens.scss`；此后生成代码只准引用令牌，本节约束依然生效。
+
+### 1. UnoCSS 类名形态（写错 = 样式静默失效）
+
+项目 `presetRemToPx({ baseFontSize: 4 })`：**间距数字即像素**（`p-5` = 5px）。类名**必须带连字符**，无连字符写法不会产出任何 CSS（已用 dist 产物实证）：
+
+| ❌ 无效（无 CSS 产出） | ✅ 有效 | 说明 |
+|---|---|---|
+| `p5` / `p10` / `p20` / `m10` / `mt20` / `px5` / `gap10` | `p-5` / `p-10` / `p-20` / `m-10` / `mt-20` / `px-5` / `gap-10` | 间距类必须带连字符 |
+| `w100%` / `h100%` / `w-100%` / `h-[100%]` | `w-full` / `h-full` | 满宽满高统一 `full` |
+| `p-b-16` | `pb-16` | 方向前缀连写 |
+| `bg-[#fff]` + `dark:bg-[#303030]` | `bg-bg_color` | 背景按语义取变量，自动适配暗黑 |
+
+- 间距取 **4px 基数**（4/8/12/16/20）；`p-5`（查询区内边距）等模版既有值保持原样。
+- shortcuts 白名单：`flex-center` / `flex-end` / `flex-middle` / `flex-between` / `flex-col-center` / `break-word` / `ellipsis`，布局优先用它们。
+- 字号用显式 px 档位：`text-xs`=12 / `text-sm`=14 / `text-base`=16 / `text-lg`=18 / `text-xl`=20 / `text-2xl`=24 / `text-3xl`=30。
+
+### 2. 颜色纪律（按语义取变量，禁止成对硬编码）
+
+| 语义 | 用法 |
+|---|---|
+| 页面/卡片背景 | `bg-bg_color`（桥接 `--el-bg-color`）；布局底 `--el-bg-color-page`；浮层 `--el-bg-color-overlay` |
+| 文字 | `--el-text-color-primary` / `regular` / `secondary` / `placeholder` |
+| 边框 | `--el-border-color`（及 `-light` / `-lighter` / `-dark`） |
+| 浅填充（表头/hover 底） | `--el-fill-color-light` |
+| 主色与梯度 | `--el-color-primary`（及 `-light-3/5/7/9`、`-dark-2`） |
+| 状态色 | `--el-color-success` / `warning` / `danger` / `info` |
+| 表格表头 | `--vts-table-header-bg` / `--vts-table-header-text`（el-table 与 vxe 共用） |
+| 弹窗背景 | `--vts-dialog-bg`（支持 `--ds-dialog-bg` 覆写） |
+
+Canvas / 图谱 / 连线库等**必须传具体色值字符串**的场景，用统一工具从运行时读取变量，禁止把十六进制写死在业务代码里：
+
+```typescript
+/** 读取 CSS 变量（canvas/G6/jsPlumb 等需要具体色值时使用） */
+const getCssVar = (name: string, fallback = "") =>
+  getComputedStyle(document.documentElement).getPropertyValue(name).trim() || fallback;
+
+// 示例：G6 边样式
+edge: { type: "line", style: { stroke: getCssVar("--el-color-primary-light-5", "#9DC5EA") } }
+```
+
+### 3. 组件尺寸纪律（small / default / large 按场景定档）
+
+| 场景 | 档位 | 说明 |
+|---|---|---|
+| 查询区按钮（查询/重置/展开收起） | `size="small"` | 与 inline 查询区配套 |
+| `ReTableBar` 工具栏按钮（新增/导入/导出/删除） | `size="small"` | 列表页工具栏统一 small |
+| 表格 | `:size="size"`（`ReTableBar` 插槽透出） | **禁止写死**，密度切换由用户控制 |
+| 分页 | `RePagination :size="size"` | 跟随表格密度 |
+| 弹窗内表单 | default（不写 size）+ `label-width="96px"` | `ReDialog` / `ReDialogResize` 内表单 |
+| 登录页 / 整屏主表单 | `size="large"` | 低频全屏操作放大档位 |
+| 移动端 Vant | 独立尺寸体系 | 不与 EP 档位混用，见 `mobile-h5` |
+
+设计规范生效期（`design-tokens.scss` 存在）：档位高度由令牌驱动——`small ↔ --ds-control-height-sm`、`default ↔ --ds-control-height`、`large ↔ --ds-control-height-lg`（经 `--el-component-size*` 映射）。**禁止**在业务代码里写裸控件高度（如 `.el-input { height: 36px }`）绕过档位。
+
+### 4. 页面容器黄金形态
+
+```vue
+<!-- 独立功能页（图谱/流程图等常规页） -->
+<div
+  :style="{ height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)` }"
+  class="pos-relative bg-bg_color p-5 overflow-hidden"
+>
+```
+
+- 高度公式固定：`calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)`（`headerHeight` 来自 `useApp()`）。
+- 容器内边距默认 `p-5`；区块之间用 `mb-10` / `gap-10` 等 4 基数间距。
+
+### 5. 设计规范生效期（design-tokens.scss 存在时）
+
+1. 生成代码前先确认 `src/styles/design-tokens.scss` 是否存在；存在则进入「规范期」。
+2. 规范期**零新增硬编码**：颜色/控件高度/内边距/圆角/字号一律引用令牌或语义变量；设计稿与令牌冲突时回填令牌层，不在页面里写裸值。
+3. 间距/边距仍按 4px 基数，优先对齐令牌 `--space-unit` 的倍数。
+4. 命中 `design-system` 时按其工作流执行适配与存量扫描，本节约束与其一致不冲突。
+
+---
+
 ## 五、资产分层（核心 vs 附加）
 
 ### 附加 Hook（按功能模块加载，勿塞进每个 CRUD）
@@ -383,4 +463,5 @@ function handleSizeChange(size: number) {
 - 完整 CRUD 变体、表单页 → `crud-pages`
 - 详情跳转 → `detail-page`
 - 主题布局深挖 → `layout-theme`
+- 设计规范适配 / 项目存在 `design-tokens.scss` → `design-system`（样式契约随之进入「规范期」，见四之二第 5 节）
 - 选型对照与全量组件表 → `project-inventory.md`

package/references/data-mapping.md

@@ -49,15 +49,19 @@ let jsPlumbInstance: any = null
 ## 初始化 jsPlumb
 
 ```typescript
+/** 读取 CSS 变量（jsPlumb 需要具体色值；设计规范生效期自动跟随令牌，见 core-kernel「四之二」） */
+const getCssVar = (name: string, fallback = '') =>
+  getComputedStyle(document.documentElement).getPropertyValue(name).trim() || fallback
+
 const initJsPlumb = () => {
   jsPlumbInstance = jsPlumb.getInstance({
     // 连接线：Straight(直线) / Bezier(贝塞尔) / Flowchart(折线) / StateMachine(状态机)
     Connector: ['Straight', { stub: 0, gap: 1 }],
-    PaintStyle: { stroke: '#409eff', strokeWidth: 2 },
-    HoverPaintStyle: { stroke: '#66b1ff', strokeWidth: 3 },
+    PaintStyle: { stroke: getCssVar('--el-color-primary', '#409eff'), strokeWidth: 2 },
+    HoverPaintStyle: { stroke: getCssVar('--el-color-primary-light-3', '#66b1ff'), strokeWidth: 3 },
     Endpoint: ['Dot', { radius: 6 }],
     EndpointStyle: { fill: 'transparent', stroke: 'transparent' },
-    EndpointHoverStyle: { fill: '#fff', stroke: '#66b1ff' },
+    EndpointHoverStyle: { fill: getCssVar('--el-bg-color', '#fff'), stroke: getCssVar('--el-color-primary-light-3', '#66b1ff') },
     Container: 'mapping-container', // 必须指定容器 ID
     ConnectionOverlays: [
       ['Arrow', {
@@ -141,11 +145,11 @@ const getMappingResult = () => {
     </el-card>
 
     <!-- 映射区域 -->
-    <div id="mapping-container" class="flex-1 relative flex justify-between bg-white p-8">
+    <div id="mapping-container" class="flex-1 relative flex justify-between bg-bg_color p-8">
       <!-- 左侧源字段 -->
       <div class="w-[40%] flex flex-col border rounded">
         <div v-for="item in sourceFields" :id="item.id" :key="item.id"
-          class="field-item flex border-b hover:bg-gray-50 cursor-pointer relative">
+          class="field-item flex border-b hover:bg-[var(--el-fill-color-light)] cursor-pointer relative">
           <div class="flex-1 p-2">{{ item.name }}</div>
           <div class="w-[80px] p-2 text-center">{{ item.type }}</div>
           <!-- 连接点 -->
@@ -160,7 +164,7 @@ const getMappingResult = () => {
       <!-- 右侧目标字段 -->
       <div class="w-[40%] flex flex-col border rounded">
         <div v-for="item in targetFields" :id="item.id" :key="item.id"
-          class="field-item flex border-b hover:bg-gray-50 cursor-pointer relative">
+          class="field-item flex border-b hover:bg-[var(--el-fill-color-light)] cursor-pointer relative">
           <div :id="`handle-${item.id}`"
             class="connector-handle-left absolute left-0 top-1/2 -mt-[6px] -translate-x-1/2" />
           <div class="flex-1 p-2">{{ item.name }}</div>
@@ -180,14 +184,14 @@ const getMappingResult = () => {
   z-index: 10;
   width: 12px;
   height: 12px;
-  background-color: #fff;
-  border: 1px solid #409eff;
+  background-color: var(--el-bg-color);
+  border: 1px solid var(--el-color-primary);
   border-radius: 50%;
 }
 .connector-handle-right:hover,
 .connector-handle-left:hover {
-  background-color: #e6f7ff;
-  border-color: #1890ff;
+  background-color: var(--el-color-primary-light-9);
+  border-color: var(--el-color-primary-light-3);
 }
 :deep(.jtk-endpoint) { z-index: 20; }
 :deep(.jtk-connector) { z-index: 10; }

package/references/data-screen.md

@@ -72,6 +72,7 @@ function getScale(width = 1920, height = 1080) {
   width: 100vw;
   height: 100vh;
   overflow: hidden;
+  /* 大屏深色画布底：属大屏设计产物；设计规范提供大屏背景令牌时替换为对应 var() */
   background: #000;
 }
 

package/references/design-system.md

@@ -1,14 +1,29 @@
 ---
 skill: design-system
-description: 设计规范识别与全量落地机制。当用户指定设计系统（内置预设：Ant Design / Semi Design / Arco Design / Vuetify / FindDesign 京东UDC；非封闭集，支持任意自定义规范）或要求"按 XX 规范 / 设计规范 / UI 规范适配项目"时，强制执行为「识别回执 + 令牌层 + 组件几何重写层 + 模版硬编码冲突处理 + 存量回归扫描」的完整适配流程，并在 code-quality 闸门中校验规范遵从。按通用协议自动识别并衔接任意上游 UI/UX 设计技能的令牌产出（不绑定具体技能名）。
+description: 设计规范识别与全量落地机制。当用户指定设计系统（内置预设：Ant Design / Semi Design / Arco Design / Vuetify / FindDesign 京东UDC；非封闭集，支持任意自定义规范）或要求"按 XX 规范 / 设计规范 / UI 规范适配项目"时，强制执行为「识别回执 + 令牌层（唯一新增文件）+ 几何重写并入 element-plus.scss + 模版硬编码冲突处理 + 公共区域适配 + 存量回归扫描」的完整适配流程，并在 code-quality 闸门中校验规范遵从。按通用协议自动识别并衔接任意上游 UI/UX 设计技能的令牌产出（不绑定具体技能名）。
 scope: project
 tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, element-plus, theme, css-variables]
 ---
 
 # 设计规范识别与全量适配机制
 
-> **本模块的职责**：识别规范后，在**业务项目**内一次性建立「令牌层 + 组件几何重写层 + 硬编码冲突清理」三层适配，之后所有生成代码只准引用令牌，禁止裸值。
+> **本模块的职责**：识别规范后，在**业务项目**内一次性完成「令牌层（数据）+ 模版样式文件改写（执行）+ 硬编码冲突清理」的适配，之后所有生成代码只准引用令牌，禁止裸值。
 >
+> **核心理念（始终明确）**：组件层永远是 **Element Plus**——代码照旧写 `<el-button>` / `<el-table>` / `<el-dialog>`，规范适配**不换组件**，只替换驱动组件样式的**“数据”**（令牌：高度/内边距/字号/圆角/颜色）。所有样式文件只是“按令牌数据执行”，换规范 = 换一套数据。
+>
+> **架构决策（单文件）**：适配只**新增一个文件** `design-tokens.scss`（纯数据层，无选择器）；组件几何与视觉重写**直接并入模版既有的 `element-plus.scss` 等文件**（引用令牌 + 标注规范注释）。禁止另建并存的“重写层”文件——两个文件同时改 EP 组件样式会让后续开发者不知道改哪里、靠加载顺序压盖易失效。
+
+### 职责分工（适配文件 vs 模版既有文件）
+
+| 文件 | 职责 | 内容形态 |
+|------|------|---------|
+| `design-tokens.scss`（**唯一新增**） | 规范**数据源**：主色/字体/字号/圆角/控件高度/间距 + 模版桥接令牌 + `--el-*` 映射 | 纯 `:root` 变量，**禁止选择器与组件类** |
+| `element-plus.scss`（模版既有） | EP 组件几何与视觉覆盖的**唯一出口**：模版默认 + 规范重写都在这里，全部引用令牌 | 选择器 + `var()`，每段标注规范注释 |
+| `reset.scss` / `index.scss`（模版既有） | 基础样式与全局壳变量（导航高/内容边距/弹窗底） | 引用令牌 |
+| `theme.scss` / `sidebar.scss`（模版既有） | 侧边栏/导航配色与几何 | 按规范换色，引用令牌 |
+
+> 关系一句话：`design-tokens.scss` 是数据层，模版样式文件是执行层；不存在第三个“重写层”文件。
+
 ---
 
 ## 一、触发与规范识别
@@ -67,9 +82,10 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 ### Step 1 探查现状（含命名锁定与模版版本判定）
 
 1. 读业务项目 `src/styles/index.scss` 的 `@use` 列表与 `src/styles/` 目录。
-2. **命名锁定**：规范适配层**只允许**叫 `design-tokens.scss` 与 `design-controls.scss`。
-   - 已存在这两个文件 → 更新令牌值与遗漏重写，不重复建层。
-   - 发现旧命名变体（`tokens.scss`、`semi-controls.scss`、`antd-controls.scss` 等）→ **必须先重命名/合并为规范名**再继续；禁止让变体与规范名并存。
+2. **命名锁定（单文件架构）**：适配**新增文件只允许**叫 `design-tokens.scss`（纯数据层）。
+   - 已存在 → 只更新令牌值，不重复建层。
+   - 发现旧命名变体（`tokens.scss` 等）→ 必须先重命名为规范名。
+   - 发现旧版并存的几何重写层文件（`design-controls.scss` / `semi-controls.scss` / `*-controls.scss`）→ **必须把其内容合并进 `element-plus.scss`（改为令牌引用 + 规范注释）后删除原文件**；禁止重写层与 `element-plus.scss` 并存。
 3. **模版版本判定**（决定 Step 5 走哪条清单）：
    ```
    grep 目标：src/styles/element-plus.scss
@@ -146,6 +162,7 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
   --vts-scrollbar-thumb-hover: var(--el-text-color-secondary);
   --vts-autofill-bg: var(--el-bg-color);
   --vts-autofill-text: var(--el-text-color-primary);
+  --ds-dialog-bg: var(--el-bg-color-overlay); /* 接管 --vts-dialog-bg：弹窗背景按规范走浮层色 */
 
   /* —— Element Plus 变量映射（必配，含主色兜底） —— */
   --el-color-primary: var(--brand-primary); /* 兜底：JS 运行时 setEpThemeColor 生效前的首屏主色 */
@@ -181,14 +198,22 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 ```
 
 > 上面是 **Ant Design 预设**。其他规范按第五节令牌速查表替换「用户可自定义」区块与语义色。
+>
+> ⚠️ `design-tokens.scss` **只允许 `:root` 变量块**：业务组件类（如 `.vts-status`、`.vts-op`）不得写入本文件，应放 `element-plus.scss` 或业务组件内。
 
-### Step 3 写入组件几何重写层 `src/styles/design-controls.scss`
+### Step 3 组件几何重写并入 `src/styles/element-plus.scss`（不另建重写层文件）
 
-只重写几何规格（高度 / 内边距 / 字号 / 圆角），全部引用令牌，**禁止再写裸值**。完整黄金样板（覆盖 EP 常用控件全集，按需删减但禁止新增裸值）：
+几何规格（高度 / 内边距 / 字号 / 圆角）**直接追加/修改在模版既有的 `element-plus.scss` 内**，三条纪律：
+
+1. 全部引用令牌，**禁止裸值**（`var(--x, 回退)` 的回退值除外）。
+2. 每段追加规范注释：`/* —— <规范名> 几何：<组件> —— */`，让后续开发者一眼看出取值来源。
+3. 模版里同一选择器已有裸值规则（如 `.el-card__body { padding: 5px }`）→ **就地改为令牌引用**，禁止另起一条规则去压盖，避免“同属性两处定义”。
+
+黄金样板（按需追加/修改，只改数据值，结构不变）：
 
 ```scss
 /**
- * <规范名> → Element Plus 几何规格重写
+ * <规范名> → Element Plus 几何规格（追加在 element-plus.scss 内）
  * 全部引用 design-tokens.scss 令牌；业务页禁止再写裸高度/内边距。
  */
 
@@ -303,29 +328,30 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
 .el-breadcrumb { font-size: var(--font-size-base); line-height: var(--line-height); }
 ```
 
-> 各规范差异项：`antd` 表头 `#fafafa` 不加边框分隔；`semi` 少阴影轻描边；`vuetify` 控件高度 Material 化（input 40px、button 36px）；按第五节表微调样板中的数值来源即可，**结构不变**。
+> 各规范差异项：`antd` 表头 `#fafafa` 不加边框分隔；`semi` 少阴影轻描边；`vuetify` 控件高度 Material 化（input 40px、button 36px）；按第五节表微调样板中的数值来源即可，**结构不变**。差异值同样只改令牌数据，不另写选择器。
 
-### Step 4 接线 `src/styles/index.scss`（顺序即优先级）
+### Step 4 接线 `src/styles/index.scss`
 
 ```scss
-@use 'design-tokens';     // ① 令牌必须最先，供后续文件引用
+@use 'design-tokens';     // 唯一新增：纯数据令牌，必须最先
 @use 'theme';
 @use 'transition';
 @use 'button';
-@use 'element-plus';      // ② 模版原生覆盖
-@use 'design-controls';   // ③ 规范重写必须在其后，同选择器后者优先
+@use 'element-plus';      // 模版默认覆盖 + 规范几何重写（已并入）
 @use 'sidebar';
 @use 'dark';
 @use 'vant';
 ```
 
+唯一顺序要求：`design-tokens` 放最前（供后续文件引用）。几何重写已并入 `element-plus.scss`，**不再存在**“重写层必须排在覆盖层之后”的顺序陷阱；模版其余 `@use` 顺序保持不动。
+
 **字体接管**：
 - 新模版：`index.scss` 已是 `font-family: var(--font-family, ...) !important`，令牌层定义 `--font-family` 即自动生效，无需改动。
 - 旧模版：把 `* { font-family: 'Alibaba PuHuiTi 3.0' ... !important }` 改为 `font-family: var(--font-family) !important`（见 4.B 第 1 条）。
 
 ### Step 5 模版硬编码冲突处理（按模版版本二选一，逐条回填）
 
-- **4.A（新模版，已变量化）**：模版样式均为 `var(--x, 默认值)` 形式，Step 2 的「模版桥接令牌」段已自动接管。**逐条确认**桥接令牌齐全即可，重点核对 `--vts-dialog-bg`（仍定义在 index.scss :root，需把渐变值改为 `var(--el-bg-color-overlay)`）。
+- **4.A（新模版，已变量化）**：模版样式均为 `var(--x, 默认值)` 形式，Step 2 的「模版桥接令牌」段已自动接管。**逐条确认**桥接令牌齐全即可，`--vts-dialog-bg` 已变量化为 `var(--ds-dialog-bg, 原值)`，确认桥接段含 `--ds-dialog-bg: var(--el-bg-color-overlay)` 即完成接管。
 - **4.B（旧模版）**：按第四节冲突清单**逐条手工处理**。
 
 **无论走哪条路**，处理完必须：
@@ -339,13 +365,21 @@ tags: [design-system, design-tokens, antd, semi, arco, vuetify, findesign, eleme
    background: white !important、#000000d9
    ```
 
-2. 在最终回复中**逐条回填**冲突清单处理结果（格式见 2.8 验证输出），禁止笼统写「已全部处理」。
+2. 在最终回复中**逐条回填**冲突清单处理结果（格式见 Step 8 验证输出），禁止笼统写「已全部处理」。
 
 ### Step 6 运行时主色与主题联动
 
 1. `public/platform-config.json` 的 `EpThemeColor` 改为规范主色（如 `#1677FF`）——这是 `useApp.ts` 的初始 `--el-color-primary` 来源。
 2. **localStorage 缓存陷阱（必告）**：`epThemeColor` 优先读 `localStorage` 的 `responsive-layout`，改完 `platform-config.json` 后**老访客不会自动生效**。必须在回复中提醒：清除浏览器 `responsive-layout` 缓存，或提升 `platform-config.json` 的 `Version` 触发重置。
-3. 侧边栏：在 `theme.scss` 追加/覆盖与规范匹配的 `html[data-theme]` 块。例：AntD Pro 浅色侧栏沿用 `light`，但把 `--vts-theme-menu-active-before` 覆盖为规范主色；深色侧栏用 `default`（`#001529` 与 AntD Pro 一致）。
+3. **公共区域（侧边栏 / 导航栏 / 内容壳）同样要按规范落地**——这些不在 EP 组件范围内，靠模版壳层变量与主题文件执行：
+
+   | 位置 | 项目 | 规范落地动作 |
+   |---|---|---|
+   | `theme.scss` | 侧栏配色 | 追加/覆盖与规范匹配的 `html[data-theme]` 块：`--vts-theme-menu-active-before` → 规范主色；菜单底/悬浮按规范形态（AntD Pro 浅色用 `light`，深色用 `default` `#001529`） |
+   | `index.scss` | 壳变量 | `--vts-bar-height`（导航高，AntD Pro 56px）、`--vts-margin`（内容边距）、`--vts-dialog-bg`（已变量化，由桥接令牌 `--ds-dialog-bg` 接管）；改后回归验证列表页 `calc(100vh - ...)` |
+   | `platform-config.json` | 顶栏高度 | `HeaderHeight` 与规范一致（如 AntD Pro 56） |
+   | `sidebar.scss` | 侧栏几何 | 宽度走 `--sidebar-width`；菜单项高度走令牌层 EP 映射（`--el-menu-item-height`） |
+
 4. 暗黑模式：在 `dark.scss` 内为新增令牌补暗色覆盖（`--vts-table-header-bg`、`--vts-message-bg`、`--vts-dialog-bg` 等），遵守 `layout-theme` 第三节规则。
 
 ### Step 7 存量代码回归扫描（防"令牌层建好了但页面没跟上"）
@@ -357,7 +391,7 @@ grep 目标（*.vue 的 <style> 与行内 style）：
 height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 ```
 
-- 命中的 EP 控件裸几何 → 删除，交给 `design-controls.scss` 统一管。
+- 命中的 EP 控件裸几何 → 删除，交给 `element-plus.scss` 统一管。
 - 布局类间距（容器 padding/margin）→ 允许保留 UnoCSS `p-*`/`m-*`，但颜色 hex 必须换成令牌。
 - 扫描结果与处理数量写入最终回复。
 
@@ -380,11 +414,11 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 ## 三、业务代码编写规则（规范生效期全程有效）
 
 1. **禁止裸值**：业务页面/组件中不得对 EP 控件写裸 `height` / `padding` / `font-size` / `border-radius`，一律引用 `--control-*` / `--font-size-*` / `--radius-*` 令牌；布局间距用 UnoCSS `p-*` / `m-*`（4px 基数）。
-2. **禁止重复重写**：组件几何只在 `design-controls.scss` 统一改，业务页不得再写 `.el-input__wrapper { height: ... }` 之类的覆盖。
+2. **禁止重复重写**：组件几何只在 `element-plus.scss` 统一改（引用令牌），业务页不得再写 `.el-input__wrapper { height: ... }` 之类的覆盖。
 3. **颜色只走变量**：`--brand-*` / `--vts-*` / `--el-*`，禁止硬编码 hex（与 `layout-theme` 规则一致）。
-4. **换规范 = 只换令牌层**：切换设计系统时只重写 `design-tokens.scss`（必要时微调 `design-controls.scss` 差异项），业务代码零改动；做不到的写法说明违反了规则 1~3，必须修正。
+4. **换规范 = 只换令牌层**：切换设计系统时只重写 `design-tokens.scss`（`element-plus.scss` 几何段已令牌化，原则上无需改动），业务代码零改动；做不到的写法说明违反了规则 1~3，必须修正。
 5. 主色运行时切换仍走 `setEpThemeColor()`（保证 chroma 色阶同步），令牌层只负责初始值与非主色令牌。
-6. **命名纪律**：适配层文件永远叫 `design-tokens.scss` / `design-controls.scss`，禁止按规范名派生（如 `semi-controls.scss`）。
+6. **命名纪律**：适配新增文件永远只有一个 `design-tokens.scss`；禁止按规范名派生文件（如 `semi-controls.scss`、`antd-tokens.scss`），禁止再新建独立的几何重写层文件。
 
 ---
 
@@ -404,7 +438,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 | 8 | `element-plus.scss` | `.el-table__header th` 色 `#8c8f90` + 底 `#f2f9fc` | 表头不跟随规范 | 已变量化 `--vts-table-header-*` | 改 `--vts-table-header-text/bg` |
 | 9 | `element-plus.scss` | `.row-added/#e6f4ff`、`.row-modified/#fff7e6`、`.row-deleted/#f5f5f5` | 行变更色脱离规范且无暗色适配 | 已变量化 `--vts-row-*-bg` | 改 `--vts-row-*-bg` 令牌 |
 | 10 | `element-plus.scss` | `.vts-message` 背景 `white`、文字 `#000000d9` | 暗黑/规范底失效 | 已变量化 `--vts-message-bg/text` | 改 `var(--vts-message-bg/text)` |
-| 11 | `index.scss` | `--vts-dialog-bg: linear-gradient(to bottom, #e5f3fe, #fefefe)` | **所有弹窗强制渐变蓝底** | **仍未变量化**（定义在 :root） | 令牌改为 `var(--el-bg-color-overlay)`；暗黑在 dark.scss 覆盖 |
+| 11 | `index.scss` / `dark.scss` | `--vts-dialog-bg: linear-gradient(to bottom, #e5f3fe, #fefefe)`（dark: `rgb(36 37 37)`） | **所有弹窗强制渐变蓝底** | 已变量化 `var(--ds-dialog-bg, 原值)`，桥接令牌 `--ds-dialog-bg` 自动接管 | 旧项目把亮/暗两处定义改为 `var(--ds-dialog-bg, 原值)` |
 | 12 | `theme.scss` | 8 套侧栏配色（激活条 `#4091f7` 等） | 激活指示条非规范主色 | 主题库保留 | 追加规范匹配的 `html[data-theme]` 块覆盖 `--vts-theme-menu-active-before` |
 | 13 | `useApp.ts` | `epThemeColor` 缺省 `#409EFF` | EP 出厂蓝 ≠ 规范主色 | 不改代码 | 改 `platform-config.json` 的 `EpThemeColor`（Step 6） |
 | 14 | `index.scss` | `--vts-bar-height: 38px`、`--vts-margin: 8px` | 与规范导航高度（AntD Pro 56px）不一致 | 令牌可覆盖 | 令牌层覆盖并回归验证列表页 `calc(100vh - ...)`；默认保持不变标注差异 |
@@ -443,7 +477,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 1. 输出识别回执，「项目现状」标注为已适配的旧规范。
 2. **只重写** `design-tokens.scss` 的「用户可自定义」区块 + 语义别名 + EP 映射（按新规范速查表），桥接令牌段结构不变。
-3. `design-controls.scss` 仅在两规范几何差异处微调（如 vuetify 控件高度），结构不动。
+3. `element-plus.scss` 的几何段已全部令牌化，**原则上不动**；仅当两规范存在无法令牌化的结构差异时才微调（极罕见），结构不动。
 4. 更新 `platform-config.json` 的 `EpThemeColor`，并**提醒清 localStorage**（Step 6 第 2 条）。
 5. 重跑 Step 5 grep 验证、Step 7 存量扫描、Step 8 验证清单。
 6. 业务代码应当零改动；若有改动，说明存在裸值，先修裸值再切换。
@@ -486,7 +520,7 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 1. 先输出识别回执（规范 = 稿子所用系统；不在预设内则标 `custom`，按 1.3）。
 2. 按 7.2 归一化后，把「用户可自定义」区块的令牌值写入 `design-tokens.scss`。
-3. 若上游产出含组件视觉（HTML 原型/设计稿）→ 以其为基准微调 `design-controls.scss` 差异项。
+3. 若上游产出含组件视觉（HTML 原型/设计稿）→ 以其为基准微调 `element-plus.scss` 几何段的差异项。
 4. 上游产出里的业务配色（状态色、图表系列）按 `layout-theme` 第八节映射为 `--vts-*` 语义变量。
 5. 原型与项目出现视觉差异时：先对比两侧令牌值是否一致（含命名映射是否漏项），再查第四节冲突清单是否漏处理，最后查 Step 7 存量裸值。
 
@@ -502,9 +536,9 @@ height: \d+px、padding: \d+px、font-size: \d+px、行内 style="...颜色 hex"
 
 - 只把 `--el-color-primary` 改成规范主色就宣称"已适配 Ant Design"（字号/圆角/高度/内边距全未动）。
 - **识别漂移风险**：用户口述的规范与真正写入令牌层的规范不一致（如说要 AntD 却写了 `#0077fa`、`--semi-*` 别名的 Semi 令牌）——回执块与三点一致性校验就是防这个。
-- **命名漂移**：适配层建成 `tokens.scss` / `semi-controls.scss`，下次适配找不到又建一套——必须锁定 `design-tokens.scss` / `design-controls.scss`。
+- **命名漂移/重复建层**：适配文件建成 `tokens.scss`，或另起 `semi-controls.scss` 之类的几何重写层与 `element-plus.scss` 并存——新增文件只允许 `design-tokens.scss`，几何重写一律并入 `element-plus.scss`。
 - **冲突清单假完成**：声称「已全部处理」，实际 `reset.scss` 的 body 字体（不带 !important 的那条）与 `label { font-weight: 700 }` 原封未动——grep 时漏掉了不带 !important 的关键词。
-- 新建 `design-controls.scss` 但 `@use` 顺序放在 `element-plus` 之前 → 被模版覆盖层压回去。
+- **靠加载顺序压盖**：几何重写独立成文件、指望 `@use` 顺序盖过模版覆盖层，顺序一错样式静默失效——已改为并入 `element-plus.scss`，从根上消除顺序问题。
 - 弹窗仍是渐变蓝底（忘改 `--vts-dialog-bg`）。
 - 改了 `platform-config.json` 主色但没提醒清 localStorage → 老访客看到的还是旧色。
 - 业务页面里又写 `.el-input { height: 36px }` 之类的裸值覆盖 → 换规范时需要逐页改，违反规则 1~2。

package/references/feedback-ui.md

@@ -32,8 +32,8 @@ const NoticeBar = defineAsyncComponent(
     text="系统将于今晚 22:00 进行维护"
     left-icon="notice"
     right-icon="arrowRight"
-    background="#ecf5ff"
-    color="#409eff"
+    background="var(--el-color-primary-light-9)"
+    color="var(--el-color-primary)"
   />
 </template>
 ```

package/references/flowchart-g6.md

@@ -62,6 +62,10 @@ const initGraph = async () => {
   const { Graph } = await import('@antv/g6')
   register(ExtensionCategory.NODE, 'vue-node', VueNode)
 
+  /** 读取 CSS 变量（canvas 需要具体色值；设计规范生效期自动跟随令牌，见 core-kernel「四之二」） */
+  const getCssVar = (name: string, fallback = '') =>
+    getComputedStyle(document.documentElement).getPropertyValue(name).trim() || fallback
+
   // 定义 Vue 节点组件
   const FlowNodeComp = defineComponent({
     name: 'FlowNodeComp',
@@ -96,16 +100,17 @@ const initGraph = async () => {
       return () => (
         <div style={{
           width: `${props.nodeWidth}px`, height: `${props.nodeHeight}px`,
-          border: '2px solid', borderColor: isSelected.value ? 'red' : '#9DC5EA',
-          borderRadius: '8px', background: '#EAF4FF', cursor: 'pointer',
+          border: '2px solid',
+          borderColor: isSelected.value ? getCssVar('--el-color-danger', 'red') : getCssVar('--el-color-primary-light-5', '#9DC5EA'),
+          borderRadius: '8px', background: getCssVar('--el-color-primary-light-9', '#EAF4FF'), cursor: 'pointer',
         }} onClick={handleNodeClick}>
-          <div style={{ background: '#CFE7FF', padding: '8px', fontWeight: 600 }}>
+          <div style={{ background: getCssVar('--el-color-primary-light-8', '#CFE7FF'), padding: '8px', fontWeight: 600 }}>
             {nodeData.value?.title ?? ''}
           </div>
           <div style={{ padding: '8px' }}>
             <div>业务号：{nodeData.value?.caseNo ?? ''}</div>
             <div>{nodeData.value?.handler ?? ''}</div>
-            <div style={{ color: '#409eff' }}>状态：{nodeData.value?.status ?? ''}</div>
+            <div style={{ color: getCssVar('--el-color-primary', '#409eff') }}>状态：{nodeData.value?.status ?? ''}</div>
           </div>
         </div>
       )
@@ -131,7 +136,7 @@ const initGraph = async () => {
       },
       animation: { enter: false },
     },
-    edge: { type: 'line', style: { stroke: '#9DC5EA' }, animation: { enter: false } },
+    edge: { type: 'line', style: { stroke: getCssVar('--el-color-primary-light-5', '#9DC5EA') }, animation: { enter: false } },
     layout: {
       type: 'compact-box',
       direction: 'TB',
@@ -227,7 +232,7 @@ defineExpose({ getInstance: () => graph })
 <!-- g6 页面示例 -->
 <template>
   <div :style="{ height: `calc(100vh - 2 * var(--vts-margin) - ${headerHeight}px)` }"
-    class="pos-relative bg-[#fff] p-5 overflow-hidden">
+    class="pos-relative bg-bg_color p-5 overflow-hidden">
     <div class="toolbar">
       <el-alert title="antv/g6流程图展示" type="info" :closable="false" />
     </div>

package/references/graph-relation.md

@@ -113,13 +113,20 @@ const transformNodes = (nodesData): GraphNode[] => {
   }))
 }
 
+// 图谱业务色板（集中声明、全篇引用；设计规范生效期改为从设计令牌读取的值，见 core-kernel「四之二」）
+const GRAPH_PALETTE = {
+  enterprise: '#4F9DF8', // 企业客户
+  personal: '#FF8234',   // 个人客户
+  self: '#675bf6',       // 当前客户
+}
+
 // 连线转换 — 可根据目标节点类型设置颜色
 const transformLines = (linesData): GraphLine[] => {
   return linesData.map((line) => {
     const targetNode = nodes.value.find(n => n.id === line.source)
     let color = ''
-    if (targetNode?.data.customerType === '2') color = '#4F9DF8'
-    else if (targetNode?.data.customerType === '1') color = '#FF8234'
+    if (targetNode?.data.customerType === '2') color = GRAPH_PALETTE.enterprise
+    else if (targetNode?.data.customerType === '1') color = GRAPH_PALETTE.personal
     return { from: line.source, to: line.target, text: line.category, opacity: 1, color, textOffset_y: 15 }
   })
 }
@@ -190,7 +197,7 @@ const onCanvasClick = ($event) => {
         @canvas-click="onCanvasClick" @node-click="onNodeClick" @line-click="onLineClick">
         <template #node="{ node }">
           <div :data-node-id="node.id" class="my-node-style"
-            :class="{ 'bg-[#4F9DF8]': node.data.customerType === '2' }"
+            :style="{ background: node.data.customerType === '2' ? GRAPH_PALETTE.enterprise : '' }"
             @mouseenter="showNodeTips(node)" @mouseleave="hideNodeTips">
             <div class="c-node-name">{{ node.text }}</div>
           </div>
@@ -243,9 +250,9 @@ onMounted(async () => {
 
 ```typescript
 const legendConfig = ref([
-  { type: 'self', label: '当前客户', color: '#675bf6', borderColor: '#9f93da', borderStyle: 'dashed' },
-  { type: 'personal', label: '个人客户', color: '#FF8234', borderColor: '#FF8234' },
-  { type: 'enterprise', label: '企业客户', color: '#4F9DF8', borderColor: '#4F9DF8' },
+  { type: 'self', label: '当前客户', color: GRAPH_PALETTE.self, borderColor: '#9f93da', borderStyle: 'dashed' },
+  { type: 'personal', label: '个人客户', color: GRAPH_PALETTE.personal, borderColor: GRAPH_PALETTE.personal },
+  { type: 'enterprise', label: '企业客户', color: GRAPH_PALETTE.enterprise, borderColor: GRAPH_PALETTE.enterprise },
 ])
 ```
 

package/references/layout-theme.md

@@ -125,7 +125,7 @@ html.dark {
   // === 必须覆盖的全局变量 ===
   --vts-border-color: rgb(253 253 253 / 12%);    // 亮色: rgb(5 5 5 / 6%)
   --vts-switch-off-color: #ffffff3f;              // 亮色: #a6a6a6
-  --vts-dialog-bg: rgb(36 37 37);                 // 亮色: linear-gradient(...)
+  --vts-dialog-bg: var(--ds-dialog-bg, rgb(36 37 37)); // 亮色: var(--ds-dialog-bg, linear-gradient(...))
 
   // === 布局区域背景 ===
   .navbar, .tags-view, .sidebar-container,
@@ -158,13 +158,13 @@ html.dark {
 
 | 位置 | 硬编码值 | 用途 | 建议 |
 |------|---------|------|------|
-| `.el-table__header th` | `#f2f9fc` | 表头背景 | 应使用 `var(--el-fill-color-light)` |
-| `.el-table__header th` | `#8c8f90` | 表头文字 | 应使用 `var(--el-text-color-secondary)` |
+| `.el-table__header th` | `#f2f9fc` | 表头背景 | 已变量化 `var(--vts-table-header-bg, #f2f9fc)`，设计系统可覆写 |
+| `.el-table__header th` | `#8c8f90` | 表头文字 | 已变量化 `var(--vts-table-header-text, #8c8f90)`，设计系统可覆写 |
 | `.row-added` | `#e6f4ff` | 新增行背景 | 需添加暗黑覆盖 |
 | `.row-modified` | `#fff7e6` | 修改行背景 | 需添加暗黑覆盖 |
 | `.row-deleted` | `#f5f5f5` | 删除行背景 | 需添加暗黑覆盖 |
 | `.el-collapse-item__header` | `#34394d` | 折叠面板文字 | 应使用 `var(--el-text-color-primary)` |
-| `.vxe-header--row` | `#f2f9fc` / `#8c8f90` | VXE 表头 | 同上 |
+| `.vxe-header--row` | `#f2f9fc` / `#8c8f90` | VXE 表头 | 已变量化，与 el-table 表头共用 `--vts-table-header-*` |
 | 滚动条 | `#f9fafb` / `#e5e5e5` | 滚动条样式 | 需添加暗黑覆盖 |
 | autofill | `white` / `#333` | 输入框自动填充 | 需添加暗黑覆盖 |
 

package/references/qrcode-barcode.md

@@ -104,4 +104,5 @@ const options = reactive({
 
 1. 二维码内容为空时不渲染，需配合 `v-if` 或默认值处理。
 2. logo 图片需考虑跨域；本地图片建议通过 `import` 引入。
+3. 码色值（`color.dark/light`、JsBarcode `lineColor`）在库层需要具体色值：设计规范生效期用 `getComputedStyle` 从令牌读取（写法见 `core-kernel`「四之二」getCssVar），勿把品牌色写死在业务代码。
 3. 条形码 `type` 与 `options.format` 同时存在时，`type` 优先级更高。

package/references/workflow-bpmn.md

@@ -148,17 +148,17 @@ onBeforeUnmount(() => {
 </template>
 
 <style>
-/* BPMN 高亮样式（全局，不加 scoped） */
+/* BPMN 高亮样式（全局，不加 scoped）；色值走语义变量，设计规范生效期由令牌自动覆写 */
 :deep(.bpmn-active) .djs-visual > :nth-child(1) {
-  fill: #409eff !important;
-  stroke: #409eff !important;
+  fill: var(--el-color-primary) !important;
+  stroke: var(--el-color-primary) !important;
 }
 :deep(.bpmn-finished) .djs-visual > :nth-child(1) {
-  fill: #67c23a !important;
-  stroke: #67c23a !important;
+  fill: var(--el-color-success) !important;
+  stroke: var(--el-color-success) !important;
 }
 :deep(.bpmn-flow-finished) .djs-visual > :nth-child(1) {
-  stroke: #67c23a !important;
+  stroke: var(--el-color-success) !important;
 }
 </style>
 ```