@qilitt-mickey/vue3-temp-skill 1.1.76 → 1.2.2

package/references/design-apply.md

@@ -1,167 +1,304 @@
 ---
 name: design-apply
-description: 设计变更集落地执行协议。接收 project-ui-design 输出的语义 ID 变更集 JSON，经 parser 三级匹配翻译为施工坐标，按"先结构后样式"顺序落地到目标项目，并过变更集合规闸门。
+description: 视觉契约落地协议。接收设计侧产出的视觉契约 JSON（ui.visual-contract/1.0），照抄生成三份样式文件（令牌 / 角色 / 布局）。AI 在本协议中的工作是翻译，不是判断。
 scope: project
-tags: [design-apply, changeset, semantic-id, mapping, parser, theme, layout]
+tags: [design-apply, visual-contract, design-tokens, role, layout]
 ---
 
-# 设计变更集落地（design-apply）
+# 视觉契约落地（design-apply）
 
 ## 定位
 
-本能力组是**双 Skill 链路的项目侧执行端**：统一获取上游设计技能产出的「语义 ID 变更集」JSON（`design.changeset/1.0`，协议技术栈中立），由本 Skill 负责翻译并落地到目标项目（vue3-web-temp 及派生项目）。上游设计技能为 **project-ui-design**，协议文档见其 `references/changeset-schema.md`。
+把设计侧的视觉契约翻译成项目样式。**唯一输入是一份契约 JSON，唯一输出是三份 CSS。**
 
-**变更集落点唯一化（强制）**：变更集一律落在 `<落地项目>/.design/changeset-<场景>-<页型>-<主题>.json`，与交付台账 `ledger.json` 同目录；多份并存时无法判定「本轮交付物」（`design-audit.mjs` 会告警）。**落地台账**（`ledger.json`，由审计闸自动维护）记录每轮的 `covered/applicable`、设计层行数与已落地语义 ID 集合——它既是**回退检测**的依据，也是**断点续传**的入口：跨轮「继续」时按 `applicable − 已落地点数` 取剩余工作项，禁止把「继续」当成重跑一次同样的开头。
+```
+契约 JSON（技术栈中立）
+   ↓  ① 展开令牌引用  ② 角色 → .role-<name>  ③ 布局 → .ui-page 网格
+src/styles/ui-tokens.css     :root 变量
+src/styles/ui-roles.css      角色规则
+src/styles/ui-layout.css     区域网格
+```
+
+**分工**：契约负责精确（写什么值、放哪一层），本协议负责翻译（怎么变成 CSS），组件库差异由 adapter 承担。
+
+---
+
+## 边界与约束（不可越）
+
+本能力组只处理视觉落地，与 AI 工具无关；**只服务 Vue 3 项目**。
+
+| 约束 | 说明 |
+|---|---|
+| **契约是唯一输入** | 不引入其他协议、不解析其他格式 |
+| **契约里没有技术栈信息** | 只有 CSS 属性、令牌引用、区域与角色——因此不需要理解组件内部实现也能生成样式 |
+| **路径约定用通用目录** | 读契约：`<项目根>/.design/visual-contract-*.json`；写样式：`src/styles/ui-*.css`。两者都是通用项目目录 |
+| **组件库差异只在 adapter** | 深度选择器语法、组件库前缀、布局占位挂载点——adapter 的全部职责，adapter 只覆盖 Vue 组件库 |
+
+---
+
+## 执行流程（六步）
+
+### 第 0 步 · 落地自检（先跑，断在哪一目了然）
+
+```bash
+node <技能>/scripts/check-landing.mjs --project <项目根>
+```
+
+**六项检查，逐项给修复动作，exit 1 表示链路有断点：**
+
+| # | 检查项 | 断点含义 |
+|---|---|---|
+| 1 | `contract-found` | `.design/visual-contract-*.json` 不存在 → 设计侧没落盘 |
+| 2 | `contract-valid` | 契约字段缺失（`meta.scene` / `tokens.color` / `roles` / `layout.areas`） |
+| 3 | `css-generated` | 三份 CSS 未生成 → 第 3/4/5 步没执行 |
+| 4 | `css-imported` | **生成了但没被 import** → 浏览器根本不加载 |
+| 5 | `roles-mounted` | **CSS 有规则但模板没挂类** → 死样式，视觉不变 |
+| 6 | `layout-mounted` | 模板没出现 `.ui-page` → 骨架仍是项目原样 |
+
+**六项全过是交付前置条件。** 不过就修断点，**不要直接目视猜问题在哪**。
+
+### 第 1 步 · 读契约（只读一次）
+
+读取 `<项目根>/.design/visual-contract-*.json`。多份契约（多页型）逐份独立施工。
+
+**读之前先确认 `meta`**：场景、页型、值来源。契约里已声明这三项，**不从项目源码反推、不自行猜测**。
+
+契约是项目的完整视觉事实源——**不读项目现有样式来决定怎么落地**。项目现有样式与契约冲突时，以契约为准。
+
+### 第 2 步 · 选 adapter（按项目事实判定）
+
+读 `package.json` 判定所用组件库，选取对应 adapter：
+
+| 项目依赖 | adapter |
+|---|---|
+| `element-plus` | `adapters/vue-element-plus.md` |
+| `ant-design-vue` | `adapters/vue-antdv.md` |
+| 其他 / 暂无 | 按 `adapters/_new-adapter.md` 模板补一份 Vue 组件库 adapter |
+
+**本技能只服务 Vue 3 项目**，因此 adapter 只覆盖 Vue 组件库。需要支持其他前端框架时，由对应框架的项目技能自带 adapter——契约格式不变，改的只是落地那一侧的 adapter。
+
+**adapter 只回答三件事**：① 深度选择器语法 ② 组件库穿透前缀 ③ 三份 CSS 的落点文件与引入方式。
+
+**adapter 不定义设计意图、不定义风格、不改写契约值。**
+
+### 第 3 步 · 写令牌 → `src/styles/ui-tokens.css`
+
+契约 `tokens` 逐条转 CSS 变量：
+
+```css
+:root {
+  --color-brand: #2B5AED;
+  --color-brand-hover: #1F4FD8;
+  --color-text-primary: #1F2329;
+  --space-4: 16px;
+  --radius-md: 6px;
+  --size-control-height: 32px;
+}
+```
+
+**命名规则**：`tokens` 的 `<族>.<名>` → `--<族>-<名>`，点号转连字符（`space.4` → `--space-4`，`control.height` → `--control-height`）。
+
+**值原样抄**：契约里是实值就写实值，是 `{令牌引用}` 就先完成替换。**不重新取色、不换算、不四舍五入。**
 
+### 第 4 步 · 写角色 → `src/styles/ui-roles.css`
+
+契约 `roles` 逐条转类规则。**这是纯粹的翻译，每个角色一段：**
+
+```css
+/* 角色：table.headerCell */
+.role-table-header-cell { background-color: #FAFAFA; height: 48px; padding: 16px; border-bottom: 1px solid var(--color-border-base); }
+.role-table-header-cell :deep(span) { font-size: var(--font-size-md); font-weight: 500; color: var(--color-text-primary); text-align: left; white-space: nowrap; }
 ```
-设计变更集 JSON（设计技能产出，中立协议）
-        ↓ 项目侧统一获取（设计技能不感知下游）
-parser match（确定性翻译）→ 施工坐标 → AI 按坐标改代码 → 合规闸门
+
+**翻译规则表**：
+
+| 契约结构 | 生成 |
+|---|---|
+| `roles.<名>.host[]` | `.role-<名转连字符> { … }` |
+| `roles.<名>.inner[]` | 同类名 + adapter 的内层穿透语法（`:deep()` / `>>>` / 属性选择器） |
+| `roles.<名>.states.hover.host[]` | `.role-<名>:hover { … }` |
+| `roles.<名>.states.disabled.inner[]` | `.role-<名>:disabled { … }`（或 adapter 的 disabled 通道） |
+| 声明值 `{令牌}` | 替换为 `var(--令牌)` |
+
+**角色名转换**：`table.headerCell` → 类名 `.role-table-header-cell`（点号转连字符 + `role-` 前缀，避免与组件库类名冲突）。
+
+**AI 在这一步不做的事**：
+
+| 不做 | 为什么 |
+|---|---|
+| 判断某属性落 host 还是 inner | 契约已用两个数组物理二分，照抄 |
+| 判断该不该加 `!important` | 契约禁止；层叠由 adapter 统一处理 |
+| 判断该不该提权覆盖组件库 | 角色是独立类 + 独立文件，天然不与组件库同类规则竞争；确有冲突时由 adapter 的唯一提权通道处理 |
+| 补角色库没有的角色 | 图上没有的角色不写进契约，契约里没有就不生成 |
+| 合并 / 简化声明 | 一条声明一个属性，原样生成 |
+
+### 第 5 步 · 写布局 → `src/styles/ui-layout.css`
+
+契约 `layout` 转网格。**这是布局差异的落点——设计布局与项目布局不一致时，差异只体现在这份文件的取值上。**
+
+```css
+.ui-page {
+  display: grid;
+  grid-template-columns: 208px 1fr;
+  grid-template-rows: 54px 40px 1fr;
+  grid-template-areas: "side head" "side tabs" "side body";
+}
+.ui-region-sidebar { grid-area: side; background-color: var(--color-shell-bg); width: 208px; }
+.ui-region-header  { grid-area: head; height: 54px; background-color: var(--color-surface); padding: 0 20px; }
+.ui-region-tabs    { grid-area: tabs; height: 40px; background-color: var(--color-surface); }
+.ui-region-content { grid-area: body; padding: 24px; background-color: var(--color-page-bg); gap: 20px; }
 ```
 
-分工原则：**词典（mapping/）负责精确，parser 负责翻译，AI 负责施工**。AI 不自行猜测任何点位定位或变量映射。
+**翻译规则**：
+
+| 契约字段 | 生成 |
+|---|---|
+| `layout.grid` | `grid-template-columns` |
+| `layout.rows` | `grid-template-rows` |
+| `layout.areas[]` | `grid-template-areas`（由各区域的 `area` 值排布）+ `.ui-region-<名> { grid-area: <area> }` |
+| `layout.regions.<名>` 几何键 | `width` / `height` / `min-height` / `padding` / `gap` |
+| `layout.regions.<名>` 排布键 | `display` / `flex-direction` / `justify-content` / `align-items` / `flex-wrap` |
+| `layout.regions.<名>` 定位键 | `position` + `top/right/bottom/left`（`offset` 的键）/ `z-index` |
+| `layout.regions.<名>` `bleed` | 负 margin 抵消父容器内边距 + 自身宽度撑回 |
+| 未写入 `areas` 的区域 | **不生成规则**（即为不渲染）——不需要单独的显隐声明 |
+
+**`bleed` 的生成示例**（页签栏在内容区内但要通栏）：
+
+```css
+/* 契约：tabs 区域 bleed: { top: true, left: true, right: true }，内容区 padding: 24px */
+.ui-region-tabs {
+  margin: -24px -24px 16px;      /* 抵消父内边距 */
+  padding-left: 24px;            /* 自身内容补回 */
+}
+```
+
+**关键**：项目现有的布局组件退化为**占位容器**（保留业务插槽，不参与布局决策）。页面骨架由本步生成的 `.ui-page` 网格决定。
+
+### 第 5b 步 · 生成角色的几何与排布
+
+角色除视觉声明外还带结构键，**这些键决定元素「为什么在这个位置」**：
 
-**方向约定**：设计技能只做产出，不知道对接方是谁；本 Skill 是变更集的统一获取与执行方。变更集来源不限（project-ui-design 或任何按协议输出的设计工具/人工）。
+| 契约结构 | 生成 |
+|---|---|
+| `roles.<名>.box` | `width` / `min-width` / `max-width` / `height` |
+| `roles.<名>.flow` | `display` / `align-items` / `gap` / `flex` / `min-width` |
+| `roles.<名>.align` | `text-align` / `vertical-align` |
+| `roles.<名>.span` | `flex` / `flex-shrink` / `min-width` |
+| `roles.<名>.sticky` | `position: sticky` + 对应方位的 `top/right/bottom/left` |
+| `pages.<页型>.nodes[].box` | 该节点绑定的几何约束（覆盖角色默认） |
+| `pages.<页型>.nodes[].sticky` | 该节点绑定的吸附方位 |
 
-## 变更集获取与词汇约束下发
+**三条必须落实的派生规则**：
 
-变更集输入有两条来路，处理方式相同：
+| 规则 | 生成什么 |
+|---|---|
+| **弹性收缩配 `min-width: 0`** | 契约给了 `span: { flex: "1" }` 就必须同时生成 `min-width: 0`，否则长内容撑破容器 |
+| **宽度三态照抄** | 契约写 `minWidth` 就生成 `min-width`，不擅自补 `width` |
+| **吸附列补底色** | `sticky` 存在时必须给 `background`（否则滚动时透出下层内容） |
 
-1. **直接输入**：用户/上游直接给出变更集 JSON 文件或内容。
-2. **设计技能产出**：用户在设计会话产出变更集后转来落地。若用户尚未产出，可先**下发词汇约束**提升命中率——把 `node parser/index.js list --verbose` 的点位清单（ID + 字段 + 形态枚举）一并提供给设计侧（`mapping_version` 恒为 `1.0.0`，设计侧无需查询版本），设计侧按约束输出（约束外意图走其 pending 通道，落地时按 L3 处理）。
+### 第 5c 步 · 处理跨元素联动
 
-无论哪条来路，落地流程一律走下文「执行流程」。
+契约 `pages.<页型>.nodes[].when` 声明的联动，由 adapter 提供实现方式：
 
-**阅读纪律（防上下文溢出，与流程红线同级）**：
+| `when` | adapter 的实现方式 |
+|---|---|
+| `rowHover` | 用行状态的 class 覆盖绑定元素底色 |
+| `rowSelected` | 用选中态 class 覆盖绑定元素底色 |
+| `colSticky` | 吸附列底色跟随所在行——**必须实现**，否则滚动时露底 |
+| `groupHover` | 用分组 hover 的 class 覆盖 |
 
-1. **词典走 parser，禁直读全文**：`mapping/` 下 JSON 是 parser 的事实源，不是给人（AI）通读的——查点位用 `parser query <id>`、查清单用 `parser list`，**禁止整文件读入 `mapping/scenes/*.json` / `mapping/basic/*.json`**（仅 validator/regression 维护场景或 parser 明确报错需要人工核对单条时，用 `Grep` 精确抽取相关条目，不整读）。
-2. **落地会话禁读设计侧规范库**：设计技能的 `page-specs/`（规范/令牌/效果图）不属于项目侧视野——项目侧消费的是**变更集 + oracle.json + 登记表**三个交付物；`oracle.mockup` 指向的效果图由 `resolveFirstExisting` 跨库解析给 parser 使用，但人（AI）**不打开、不阅读设计侧效果图与规范文件**。
-3. **效果图只读一次**：期望值优先直接消费设计侧交付的 `oracle.json`；确需现场抽取时（无产物降级路径），抽取完成后值落盘，**后续轮次禁止反复打开效果图 HTML/JPG**。
-4. **做到哪一步读哪一份**：各步骤细节在 `steps/` 子文件（见下方索引），按当前阶段加载，禁止一次全部通读。
+**实现方式二选一**：能挂 class 就挂 class（简单可靠）；挂不上就用组件的 `row-class-name` 回调。**由 adapter 决定，不由落地端临时发明。**
 
-## 出厂中性 · 变更集驱动（架构红线，违反即返工）
+### 第 6 步 · 挂载 + 覆盖验证
 
-**同一份模板源码，换一份变更集 = 换一套外观。** 任何「本次设计的结论」都不许固化进源码：
+1. 在样式入口引入三份文件（一次性，入口位置按项目现状）
+2. 页面根节点挂 `.ui-page`，各区域挂 `.ui-region-<名>`
+3. 按 adapter 的「角色类挂载方式」给组件挂 `.role-*`（**表格走插槽，不是在 `<el-table>` 上加类**）
+4. **重跑第 0 步的落地自检，六项全过才算挂载完成**
+5. 目视对照：打开页面与契约 `meta.source.mockup` 指向的效果图并排看
 
-| | 允许 | 禁止 |
+| 现象 | 根因 | 修正动作 |
 |---|---|---|
-| 模板源码 | 只提供**能力通道**：CSS 变量的消费者挂载点、form 枚举、DOM/属性钩子、正确的层叠优先级 | 预置**设计结论**：某个具体颜色、某句问候语、某个方位的指示条、某个硬编码尺寸 |
-| 设计产出 | AI 按本协议写入**设计层文件 / 页面级 scoped 样式 / DOM 属性与配置** | 为表达某张效果图而改写出厂样式文件与出厂组件（换设计即失效，且污染模板） |
+| 页面完全没变化 | 三份 CSS 没被 import | 在样式入口 import 一次 |
+| 只有个别地方变了 | 角色类挂载覆盖率低 | 按 adapter 挂法补齐，重跑自检 |
+| 布局还是项目原样 | 没挂 `.ui-page` / `.ui-region-*` | 布局组件加类 |
+| 有差异 | 契约值或落点层不对 | **改契约 → 重新生成 CSS** |
+| 颜色不对 | 令牌值抄错 | 改 `tokens` → 重新生成 |
+| 字号 / 字重不对 | 落错层（该进 `inner[]` 进了 `host[]`） | 改契约的数组归属 → 重新生成 |
+| 表头竖排换行 | `white-space` 没进 `inner[]` | 同上 |
+| 组件库样式盖住角色 | adapter 的穿透前缀不对 | 改 adapter 的穿透目标 |
+| 布局位置不对 | `areas` 排布或 `regions` 取值不对 | 改 `layout` → 重新生成 |
+| 某角色完全没生效 | 该角色没写进契约 | **回设计侧补抽**，不是项目侧猜 |
 
-**判据（一句话）**：换一张效果图只需要换变更集、不需要改源码 ⇒ 架构正确；需要改源码才能换 ⇒ 设计结论被烧进了源码，必须回退为通道。
+### 修正的唯一定向（不可破）
 
-- ❌ 反例：把「菜单激活指示条 = 左侧 3px」写死进 `sidebar.scss` / `element-plus.scss`；把问候语 DOM 直接加进 `lay-navbar/index.vue`；出厂 `<component>` 上硬编码 `data-content-mode="scroll"`。
-- ✅ 正例：`admin.layout.sidebar.menu` 暴露 `forms`（pill/indicator_left/indicator_right/indicator_underline/none）+ 几何字段，方位与粗细由变更集驱动；高度模式出厂不带任何属性，由页面根节点按变更集声明。
+**只改契约或改 adapter，永远不直接改生成出来的 CSS。**
 
-**落地三落点判据**（每个变更字段先判落点再动手）：
+直接改 CSS 会在下次重新生成时被覆盖，且这份覆盖不会留下痕迹——同类问题会在下一轮以另一种形态复发。改契约的成本远低于改代码，因为契约是结构化的、可定位的、可重放的。
 
-1. **有非样式通道**（DOM 属性 / 组件配置 / `platform-config.json`）→ 必须走该通道（form=scroll/fixed → 页面根节点 `data-content-mode`；form=card → `ShowModel`）。降级写成 SCSS = 未施工。
-2. **无通道且需改 DOM**（新增节点，如问候语欢迎区）→ 结构增量施工（AI 在组件模板内按 `form` 插入，保形插入、不删原代码）。
-3. **纯视觉表达**（颜色/圆角/间距/指示条几何）→ 设计层文件（见第 3 步）。
+**不做**：不建期望值文件、不建采集脚本、不跑回归、不写逐点 diff 报告。
 
-**出厂文件仅在「通道缺失」时才可改动**，且须同时满足：① 补的是能力不是结论（补变量消费者、补 form 枚举、修层叠优先级）；② 在交付说明中单列「补通道」条目写明缺失点与修复内容。
+---
 
-**模板源码注释保持中性（防污染）**：源码注释只写「这段代码做什么」——给后续维护者看。**禁止把面向 AI 的规范写进模板源码**：语义 ID、变更条目、本协议步骤号、缺口 / 自举 / 申报 / 「设计还原禁止改写本段」这类纪律条款，一律留在技能侧（`crud-pages.md` 结构通道 / `code-quality.md` 清单 / 本节），不得写进 `lay-*.vue`、`element-plus.scss`、`sidebar.scss`、`index.scss`、`design-shell.scss` 等模板文件。判据：**技能侧改了内容不需要动模板 ⇒ 正确**；改一条纪律还要去改模板注释 ⇒ 放错层。落地时技能侧只承诺「这四类通道的能力」（`data-content-mode` / `data-fill` / `design-shell.scss` 落点 / 构图钩子），具体契约与纪律全部由技能文档承载。
+## 三列变量映射表
 
-## 输入契约（变更集 Schema v1.0）
+`mapping/<场景>.json` 是项目现状与契约区域名的对照表，**只有三列**：
 
-```jsonc
+```json
 {
-  "schema": "design.changeset/1.0",       // 协议版本（parser 兼容历史值 design-changeset/v1，新输出一律用 1.0）
-  "changeset_version": "1.0.0",           // 恒填 "1.0.0"
-  "mapping_version": "1.0.0",             // 恒填 "1.0.0"：版本由双侧 SKILL.md 体系版本统一管理，词典不单独演进。parser 校验口径 = 变更集值 ∈ 词典版本集合（恒通过）；仅协议破坏性升级时双侧同步升版
-  "scene": "admin",              // 场景前缀，须与 mapping 场景域一致
-  "scheme": "default",           // 方案标识（mode=restore 时必填）：取设计侧 page-specs/styles/registry.json 的方案 id；与 scene 共同定位「方案 × 场景」的清单/登记表
-  "mode": "restore",             // 交付模式（G8 模式闸）：restore=场景还原（scheme + oracle.mockup + coverage.registry 强制必填）；design=显式声明的轻量微调；缺省 design
-  "layout_type": "vertical",    // 标准布局枚举：vertical / horizontal / mix（字段名固定 layout_type，非 layout）
-  "page_bindings": [             // 页面映射（G13 页面绑定闸）：效果图页面 → 项目页面的身份声明；缺省 = 全部映射已有页面。效果图页面默认是设计角色坐标系，不是页面增量——未显式 target:"new" 时禁止新增页面/路由/菜单
-    { "mockup": "后台管理端.html", "target": "<项目已有列表页路由名/路径>", "note": "效果图标题是设计角色坐标系 = 已有页面换肤基线，非新增业务" }
-  ],
-  "global": { "brand_primary": "钴蓝-5" },  // 可选：全局令牌通道（整套主题切换优先走此节点；值 = 语义名或临时主题 hex）
-  "changes": [
-    {
-      "id": "admin.layout.sidebar.menu",     // 语义 ID（词典 key）
-      "visible": true,                       // 可选：隐藏用 false（v-if/display，不删代码）
-      "position": "right",                   // 可选：相对方位（left/right/top/bottom）
-      "form": "card",                        // 可选：形态切换（见条目 forms 枚举）
-      "style": { "menu_bg": "钴蓝-9" },      // 可选：抽象样式字段（词典 css_vars/custom_style_map key；值 = 语义名或 hex）
-      "apply_via": "admin.layout.sidebar.menu",   //  可选：本声明引用的锚点来源条目（缺省 = 自身；值 = 语义 ID，不是选择器）
-      "layer": { "menu_text": "host" },      //  可选：落点层级（host 宿主盒 / inner 内层文本盒）；可为字符串（整条生效）或「字段 → 层级」对象
-      "structure_ops": [                     //  可选：结构施工声明（数据 / 结构驱动点位必须给，只写 CSS = 无效声明）
-        { "op": "render_branch", "node": "status_tag", "source": "row.status" }
-      ]
-    }
-  ],
-  "pending": [                     // 新增 ID 通道：parser 解析 function/parent 供 L3 施工
-    { "proposed_id": "portal.content.banner.carousel", "function": "门户首页轮播横幅", "parent": "portal.content.banner" }
-  ]
+  "schema": "ui.var-map/1.0",
+  "stack": "vue3 + element-plus",
+  "adapter": "vue-element-plus",
+  "layoutHost": "src/layout/lay-admin/index.vue",
+  "regions": {
+    "sidebar": { "scope": ".lay-sidebar", "var": "--ui-sidebar-w", "fallback": "208px" },
+    "header":  { "scope": ".lay-header",  "var": "--ui-header-h", "fallback": "54px" },
+    "tabs":    { "scope": ".lay-tabs",    "var": "--ui-tabs-h",   "fallback": "40px" },
+    "content": { "scope": ".lay-content", "var": "--ui-content-p","fallback": "24px" }
+  }
 }
 ```
 
-** 三个声明维度**（补齐「由哪个通道落地 / 被压时怎么赢 / 需要改结构时落在哪」）：
+| 字段 | 作用 |
+|---|---|
+| `scope` | 项目里承载该区域的现有类名（供 adapter 定位，生成 CSS 时不必写死） |
+| `var` | 项目侧可选的尺寸变量名（项目已有则复用，没有则用契约值直接写） |
+| `fallback` | 项目缺该区域时的占位值 |
+| `layoutHost` | 布局占位容器路径（保留业务插槽，不参与布局决策） |
 
-| 字段 | 作用 | 值域 |
-|---|---|---|
-| `apply_via` | 指认本声明使用的**锚点来源条目**（在哪条词条的 `anchors` 上落地） | 语义 ID 字符串（2~4 段小写下划线）；不是选择器 / 变量名 |
-| `layer` | 指认样式落在**宿主盒**还是**内层文本盒** | `"host"` / `"inner"`；或 `{ "<style字段>": "host"｜"inner" }` |
-| `structure_ops[]` | 需要**结构施工**时声明「改哪个语义节点 / 数据源、怎么改」 | `op` ∈ `add_node` / `remove_node` / `move_node` / `render_branch` / `bind_source`；`node` / `source` / `from` / `to` 为语义名 |
-
-硬约束：
-- 变更集**只含变更点位**——未提到的点位一律不动。
-- `style` 字段为**抽象视觉语义**（`menu_bg`、`radius`），不得出现 CSS 变量名、选择器、`!important`、技术栈词汇。值口径：官方 5 套主题用语义名（`钴蓝-5`，译表见 `mapping/basic/semantic-values.json`）；库外临时主题直接 hex + `notes` 申报派生口径。
-- `position` 用相对方位词，不用像素坐标。
-- `visible: false` 只做隐藏，**永不删除代码**。
-- `apply_via` / `layer` / `structure_ops` 与 `style` 同属**语义声明**，同样不得出现选择器、CSS 变量名、DOM 词、技术栈词：`apply_via` 必须是语义 ID（锚点名）、`layer` 只能取 `host` / `inner`、`structure_ops[].op` 只能取五枚举。
-- `pending` 数组声明的是设计侧新点位，直接归入 L3 处理（不是错误）。**注意：pending 不是施工指令**——L3 施工的内容以 `changes[]` 中同 ID 新条目声明的意图为准；设计侧只登记 pending、未在 changes[] 声明意图的点位，落地时按出厂现状处理并在缺口清单中反馈「该点位设计意图缺失」。
-- parser 校验已实现：schema 硬校验、mapping_version 缺失/不匹配拒绝、禁词与 hex 位置校验、语义 ID 命名校验、`layer` / `apply_via` / `structure_ops` 结构校验。
-
-各步骤**子文件按需加载**（做到哪一步读哪一份，禁止一次全部通读）：
-
-| 步骤 | 子文件 | 内容 | 加载时机 |
-|---|---|---|---|
-| 第 0 步 | [`step0-preflight.md`](steps/step0-preflight.md) | 第 0 步 · 版本与场景检查 · 对接匹配（适配前置）· 运行时清场 | 每次落地开工前（版本/场景/对接匹配/运行时清场三件套） |
-| 第 1 步 | [`step1-match.md`](steps/step1-match.md) | 第 1 步 · parser 确定性匹配（含词典硬闸 G8-G11/G1/G5） | match 执行与闸门判读 |
-| 第 1 步附加 | [`step1b-audit.md`](steps/step1b-audit.md) | 第 1 步附加 · 挂载点审计（audit · 静态查三类隐性缺口） | match 通过后、施工前 |
-| 第 1 步附加（之二） | [`step1c-registry.md`](steps/step1c-registry.md) | 登记表覆盖率（子项级细闸） | 变更集带 coverage.registry / --registry 时 |
-| 第 2 步 | [`step2-structure.md`](steps/step2-structure.md) | 第 2 步 · 结构先行（visible / position / form · structure_ops · layer · suppress · priority 消费） | 进入施工时（先于一切样式） |
-| 第 3 步 | [`step3-style.md`](steps/step3-style.md) | 第 3 步 · 样式落地（两层转换 + 语义值译表） | 结构完成后 |
-| 第 3 步附加 | [`step3b-shell.md`](steps/step3b-shell.md) | 第 3 步附加 · 设计层落点文件 design-shell.scss（强制 · 覆写定律 · 自举） | 写任何新 CSS 规则前 |
-| 第 3 步附加（之二） | [`step3c-priority.md`](steps/step3c-priority.md) | 覆写优先级消费（硬步骤） | 与 step3b 配套，落规则前逐条判定 |
-| 第 4 步 | [`step4-l3.md`](steps/step4-l3.md) | 第 4 步 · L3 新模块处理（分级布局） | 存在未命中点位 / 新页面生成时 |
-| 第 5 步 | [`step5-gates.md`](steps/step5-gates.md) | 第 5 步 · 合规闸门（变更集专属检查清单） | 施工完成后、验收前 |
-| 第 6 步 | [`step6-verify.md`](steps/step6-verify.md) | 第 6 步 · 渲染态验收（oracle 逐点 diff · 快照回归 · 残差豁免） | 变更集含 oracle 时强制 |
-| 维护 | [`maintenance.md`](steps/maintenance.md) | 词典维护纪律 · 出厂状态漂移排查 | 改 mapping / 排查词典假前提时 |
-| 回归 | [`regression.md`](steps/regression.md) | 端到端回归 A-V · 配套工具 | 改 parser/mapping 后必跑 |
-
-**红线摘要（全文适用，细节在各步子文件）**：出厂中性 · 变更集驱动（上文）；先结构后样式（第 2 步先于第 3 步）；缺口只分「能力缺口（当场落地）」与「意图缺口（回流设计侧）」两类；**效果图/大文件只读一次**——期望值落盘 `oracle.json` 后，后续环节一律消费落盘产物，禁止反复重读。环境无 Node 时按「环境备注」（见 maintenance.md）人工执行。
-
-## 施工标记规范（G3：@sid / @closed，design-audit E15 机检）
-
-结构性声明（`form` / `suppress` / `suppress_inner` / `structure_ops` / `text_visible:none` / `visible:false`）**必须在设计层留机读标记**——声明了不等于落地了，没有标记就没有对账凭证（悬空声明例：`collapse_trigger.form=header_inline` 声明后壳层零规则，落地端静默无效）：
-
-| 标记 | 写法 | 作用 |
-|---|---|---|
-| `@sid` | 规则上方 `/* @sid: <语义ID> */` | 「变更集 ↔ 设计层」逐条落点对账（@sid 强制） |
-| `@closed` | 收口规则上方 `/* @closed: <通道名> */` | suppress 收口兑现证据（通道名 = 词典 forms/css_vars/custom_style_map 的键） |
+**三列取代了原有的八件套词典**（`selector` / `css_vars` / `custom_style_map` / `style_scope` / `anchors` / `preconditions` / `priority` / `forms`）——落点层级由契约的 `host`/`inner` 二分承载，优先级由 adapter 统一，形态由契约声明本身承载。
 
-补充证据通道：通道为 `css_vars` 键时，设计层对该 var 写关闭值（`transparent` / `none` / `0`）即视为兑现，可免 `@closed` 标记；`visible:false` 的 `display:none` 规则按 E6 口径取证。**双向对账（E15）**：设计层 `@closed` 了变更集未声明的通道 → WARN（台账失真，收口记录进不了 D13 继承链）；声明了词典不认识的 form 值 / 通道名 → ERROR（悬空声明 = 无规则可挂）；结构性声明在设计层零证据 → ERROR。
+---
 
-## 会话结束条件（终态硬闸，违反 = 交付未完成）
+## 与项目其他能力的关系
 
-**落地会话不许「做一批、停下来等用户说继续」。** 「继续」只是异常中断后的恢复手段，不是交付形态——把恢复手段当成默认流程 = 把 1:1 还原降级为多次半成品。本轮做完一批点位后，**必须自动进入下一批**，直到同时满足以下三条才允许结束会话：
+本能力组只管视觉落地。项目开发主流程（列表页、表单、API、权限等）见 `SKILL.md` 的能力组路由。
 
-| # | 结束条件 | 判定方式 |
+**两条链路的边界**：
+
+| 场景 | 入口 | 产物 |
 |---|---|---|
-| 1 | **施工对账清零**：变更集全部已声明点位（`changes[]` ∪ `visible:false` ∪ `pending` 兑现项）全部落地 | 对照 `.design/ledger.json` 台账与 parser match 输出逐条核销；剩余 >0 → 继续施工 |
-| 2 | **静态闸清零**：`parser audit` 与 `scripts/design-audit.mjs` 的 ERROR = 0 | 两闸任一 ERROR 即返工，不得带错收尾 |
-| 3 | **验收闭环**：变更集含 oracle 时跑第 6 步 verify（本环境无浏览器 → 渲染态抽取显式移交用户执行，并说明移交项） | verify 全绿或移交说明已给出 |
-| 4 | **终态机读凭证**：跑通 `node <技能>/scripts/apply-final-gate.mjs --project <项目根> --container-width <内容区宽>`，取得 `FINAL-GATE: PASS` | 该命令串联四闸（changeset-selfcheck → parser match → parser audit → design-audit），任何一步非零即 `FAIL`，会话**不得以完成态结尾**；PASS 凭证自动写入 `.design/ledger.json` 的 `finalGate` 字段——终态判定以凭证为准，不以会话自述为准。**mode 唯一合法值 restore**：缺 mode / 写 design / 基线命中却缺三件套，均在此拦截 |
+| 常规开发 | 能力组路由（`crud-pages` / `form-advanced` / `http-api` …） | 业务代码 |
+| **设计契约落地** | 本协议 | `ui-tokens.css` / `ui-roles.css` / `ui-layout.css` |
+
+常规开发**不受本协议约束**——它写自己的页面样式，不生成角色类。两条链路的样式互不干扰：角色类是独立命名空间（`role-` 前缀），布局类是独立命名空间（`ui-` 前缀）。
+
+---
 
-> 条件 4 是 1–3 的机器汇总，不替代前三条的人读核对；前 3 条满足而凭证 FAIL = 仍有静态闸未清零，按 FAIL 输出逐项修复。
+## 红线
+
+1. **契约是唯一事实源**——不读项目现有样式来决定怎么落地；冲突时以契约为准。
+2. **照抄不判断**——不判断落点层级、不合并声明、不补角色库没有的角色、不改契约值。
+3. **禁止 `!important`**——角色类是独立命名空间，天然不竞争；确有冲突走 adapter 的唯一提权通道。
+4. **不改项目布局组件的布局决策**——它退化为占位容器；改它等于把设计结论烧进源码。
+5. **工具中立**——协议内容不出现任何 AI 工具的专有概念；路径只用通用项目目录。
+
+---
 
-**禁止的收尾话术（出现即判定为本轮交付失败，必须继续）**：
-- 「全量覆盖是迭代项 / 随迭代补齐 / 后续迭代再补其余细项 / 不阻塞已落地代码」——**覆盖率欠账 = 交付未完成**，不是迭代计划；设计侧变更集 `coverage.note` 出现同类表述同样视为交付失败（设计侧闸 D4/D9 会先拦，话术绕过闸的在这里兜底）。
-- 「核心点位已落地，其余点位影响不大」——影响大小不由落地端裁定，范围只由变更集 `coverage` 与登记表裁定。
-- 「已落地主题色与关键视觉，还原度已达 X%」——还原度以 verify / 登记表对账为准，不得以点位抽样自评。
+## 子文件（按需加载）
 
-**环境能力边界**：无浏览器只豁免「渲染态抽取与 verify」，**不豁免逐点施工**——静态可落地的 190 子项必须在会话内全部落地，施工不需要浏览器。
+| 文件 | 加载时机 |
+|---|---|
+| `adapters/vue-element-plus.md` | 项目用 Element Plus |
+| `adapters/vue-antdv.md` | 项目用 Ant Design Vue |
+| `adapters/_new-adapter.md` | 项目用其他 Vue 组件库，需要补一份适配 |