project-tiny-context-harness 0.2.54 → 0.2.56

package/assets/skills/context_product_plan/SKILL.md

@@ -1,25 +1,27 @@
----
-name: context_product_plan
-description: Use when the user explicitly asks for 产品方案, 产品经理, 产品专家, 需求方案, 功能方案, 业务规则方案, 用户故事方案, 验收标准方案, 产品规划方案, product plan, product manager, product expert, product spec, or PM spec in a Minimal Context Harness project. Do not trigger for ordinary coding, debugging, package work, or generic mentions of 产品, product, or requirements.
----
-
-# Context Product Plan
-
-## Package-Managed Boundary
-
-This Skill is generated by `sdlc-harness sync` and owned by the Harness package. Do not edit the generated `context_product_plan` Skill directly.
-
-Project-specific product planning rules belong in a separate project-local Skill under `<harnessRoot>/skills/product_plan/SKILL.md`. When a project-local Skill and this package-managed Skill both apply, use the more specific project-local Skill as the primary instruction source while keeping durable conclusions in `project_context/**`. Keep the project-local Skill front matter `description` trigger keywords aligned with this package-managed Skill and the project `AGENTS.md` role-trigger rule; if the project adds or narrows trigger terms, update both places together so agent activation and SDLC guidance do not drift apart.
-
-## 目标
-
-帮助 agent 把产品方案收敛成可恢复的 Minimal Context。
-
-## 工作方式
-
-1. 先读取 `project_context/global.md` 和 `project_context/context.toml`，按 default area、triggers、read_when 选择相关 context。
-2. 和用户澄清或整理：目标用户、产品/页面定位、核心问题、用户需要什么、产品需要提供的内容/能力/反馈、主要流程、验收信号、非目标、约束、风险和受影响模块。
-3. 涉及 Web 页面、前端布局、UI/UX、产品模块边界或信息放置时，把页面产品定位检查作为前置动作：用户在页面要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、下游消费层/运维层/详情层/其他页面归属、布局和信息密度是否匹配页面任务。多页面或多模块归属不清时，先读取相关 Context 并搜索页面入口，做全站或相关页面的信息架构 sweep，再收窄到具体实现。该检查是下一步变更分类的输入；只有形成长期产品归属、页面职责、信息架构或模块边界结论时才更新 Context。
+---
+name: context_product_plan
+description: Use when the user explicitly asks for 产品方案, 产品经理, 产品专家, 需求方案, 功能方案, 业务规则方案, 用户故事方案, 验收标准方案, 产品规划方案, product plan, product manager, product expert, product spec, or PM spec in a Minimal Context Harness project. Do not trigger for ordinary coding, debugging, package work, or generic mentions of 产品, product, or requirements.
+---
+
+# Context Product Plan
+
+## Package-Managed Boundary
+
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_product_plan` Skill directly.
+
+Project-specific product planning rules belong in a separate project-local Skill under `<harnessRoot>/skills/product_plan/SKILL.md`. When a project-local Skill and this package-managed Skill both apply, use the more specific project-local Skill as the primary instruction source while keeping durable conclusions in `project_context/**`. Keep the project-local Skill front matter `description` trigger keywords aligned with this package-managed Skill and the project `AGENTS.md` role-trigger rule; if the project adds or narrows trigger terms, update both places together so agent activation and Tiny Context guidance do not drift apart.
+
+## 目标
+
+帮助 agent 把产品方案收敛成可恢复的 Minimal Context。
+
+## 工作方式
+
+1. 先读取 `project_context/global.md` 和 `project_context/context.toml`，按 default area、triggers、read_when 选择相关 context。
+2. 和用户澄清或整理：目标用户、产品/页面定位、核心问题、用户需要什么、产品需要提供的内容/能力/反馈、主要流程、验收信号、非目标、约束、风险和受影响模块。
+3. 涉及 Product Surface（Web 页面、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息放置时，把产品/页面定位检查作为前置动作：用户在这个 surface 要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、主层/下钻/运维/诊断/详情归属、布局和信息密度是否匹配任务。多 surface、多平台或多模块归属不清时，先读取相关 Context 并搜索入口，必要时使用 `context_surface_contract` 做 Surface Contract Audit，再收窄到具体实现。该检查是下一步变更分类的输入；只有形成长期产品归属、surface 职责、信息架构或模块边界结论时才更新 Context。
+   - 若存在 Product Surface Contract，读取并对齐 primary user question、main allows/forbids、drilldown ownership、long-task state 和 verification。
+   - 若缺失且本任务改变 durable surface responsibility，输出 `Surface Contract Delta: required`，把具体答案写入 `project_context/**`，跨 surface 或跨 area 使用现有 `contract` role，不新增 surface-specific role。
 4. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件任务框架”重新理解用户任务和产品反馈；这只是通用判断框架，不是业务处方库。
 5. 当一个产品对象、能力或接口的增删改需要跨多个页面、模块、Context 或产品域同步调整时，将该影响范围视为产品边界复核信号；先判断它是否应沉淀为独立能力、subdomain 或 area，并明确对外契约、所有权和消费方边界，避免通过手工清单长期维护各消费面的重复映射。
 6. 产品意图、模块职责、边界和验收口径以 `project_context/**` 为准；代码和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码揭示“现在是什么”，代码不能静默重定义 Context。
@@ -36,51 +38,52 @@ Project-specific product planning rules belong in a separate project-local Skill
 12. Context 只能声明验证 / 部署关键路径或验收信号，不能伪造“测试已通过”或“部署已成功”。
 13. Verification / Deployment Role Context 只记录长期可复用的重复执行路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id 或 raw payload。
 14. 收尾时做 `Contract Conformance` 和 Context drift check，只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和验证入口；一次性证据、测试日志、截图结果、任务契约和实现摘要不写入 Context。
-
-## 任务契约编译
-
-- 任务契约是当前任务的编译产物，不是事实源、PRD、ADR 或长期文档；默认留在方案、交付说明或 PR 文本中。
-- `Context Delta` 必须先出现，取值为 `none` 或 `required`：
-  - `none`：本次只是按既有 Context / 原则落地，不新增长期事实。
-  - `required`：说明长期事实类型、应写入的 Context / role、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
-- `Task Contract` 用短列表说明本次产品实现必须满足的目标、用户任务、信息 / 动作 / 状态 / 反馈、边界、非目标和验收信号。
-- 对长任务、多模块、多 agent、容易发生 `Context Delta` 调头或多轮验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
-- `plan.md` 中出现的长期事实必须提炼回 `project_context/**`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
-- `Context Delta: required` 时先更新 `project_context/**`，再继续实现；`none` 时直接按 Task Contract 实现。
-- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。
-- 不为普通 bug fix、局部样式、小重构、局部实现漂移、测试修复或探索性 spike 强制编译任务契约。
-
-## 产品体验校准
-
-- 做页面、模块或入口规划时，先回答产品或页面定位是什么、要解决什么问题、需要提供什么给用户；再回答放什么、放哪里、为什么。这是页面变更前置判断，不是实现后的视觉润色。优先保留能帮助目标用户判断状态、采取行动、定位下一步或理解风险的信息。
-- 信息归属按使用场景决定：高频且跨页面的动作优先考虑系统级区域；模块动作放模块内部；运维、连接、缓存、后台任务等内部状态只有在影响用户判断或行动时才进入主界面，否则放运维/详情区域；低频解释放 Context、文档、帮助或详情，不默认占据主界面。
-- 首页、总览或入口页应服务产品定位下的核心使用路径和核心判断，不要为了证明系统层级完整而重复导航、堆叠入口、保留空指标槽或展示实现来源说明。
-- 产品文案面向真实用户，直白、行动优先；除产品名、协议、字段名、ID、调试 JSON 等必要专有名词外，普通按钮、筛选、状态、空态、警告和说明优先使用用户熟悉的语言。
-- 空态和数据要求真实：没有数据就显示真正空态，筛选无结果与系统无数据要区分，API/连接失败用用户能理解的状态表达，技术细节放到运维或详情里。
-
-## 控件任务框架
-
-- 当产品界面涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或状态反馈时，先把控件还原成用户任务：用户要判断什么、选择什么、提交什么或规避什么风险。
-- 先判断数据语义，再选交互：自由文本、枚举、实体选择、时间/区间、数量/预算、规则配置和内部开关对应不同的理解成本、错误成本和验证需求。
-- 明确用户确认自己“选对了/填对了/可以继续”的反馈：加载中、无结果、无数据、连接失败、校验失败、保存成功和风险提示要能被用户区分。
-- 对数量、预算、配额、限流、调度和时间类字段，判断是否需要单位、范围、默认值、示例、推荐值、成本/风险/影响说明；只记录稳定业务结论，不把一次性解释写进 Context。
-- 检查用户可见语言是否面向任务，而不是后端字段名、数据库列或内部枚举直出；必要技术细节放到详情、帮助、运维或调试视图。
-- 如果选择自由输入，必须判断错误成本、校验反馈和恢复路径是否可接受；如果不可接受，应形成更明确的输入约束或控件契约。
-- 这些问题是通用产品判断，不是固定控件处方。业务特定答案进入项目 Context 或项目本地 Skill；本次实现如何满足既有约束只写在交付说明。
-
-## 输出边界
-
-- 不默认创建 `.work_products/**`、PRD、tech plan、ADR、implementation doc、review/test/release 文档。
-- 不要求 lifecycle phase、plan task、phase gate 或阶段 Skill。
-- 如果用户明确要求独立方案文档，可以临时生成；长期事实仍要提炼回 `project_context/**`。
-- 如果用户只是要求实现功能、修 bug、调整代码、处理 package/release，或只是泛泛提到“产品 / product / requirements”，不需要触发本 Skill；只有明确角色名或强相关产物名指向产品判断、需求整理、验收口径或长期产品事实沉淀时才使用。
-
-## 建议沉淀位置
-
-- `global.md#Product / Delivery Brief`：项目级产品目标、用户、核心流程和非目标。
-- `global.md#Design Rationale`：长期产品取舍。
-- `areas/*.md#User / System Contract`：产品域可见行为、API、CLI、UI 或数据契约。
-- `areas/*.md#Key Constraints`：业务规则、边界、风险和不易从代码看出的约束。
-- `areas/*/verification.md` 或 role=`verification` Context：关键测试、smoke、CI、probe 或验证重复执行路径。
-- `areas/*/deployment.md` 或 role=`deployment` Context：关键部署、云端初始化、运行拓扑、健康检查或回滚重复执行路径。
-- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。
+
+## 任务契约编译
+
+- 任务契约是当前任务的编译产物，不是事实源、PRD、ADR 或长期文档；默认留在方案、交付说明或 PR 文本中。
+- `Context Delta` 必须先出现，取值为 `none` 或 `required`：
+  - `none`：本次只是按既有 Context / 原则落地，不新增长期事实。
+  - `required`：说明长期事实类型、应写入的 Context / role、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
+- `Task Contract` 用短列表说明本次产品实现必须满足的目标、用户任务、信息 / 动作 / 状态 / 反馈、边界、非目标和验收信号。
+- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement 和 verification；业务特定答案进入项目 Context 或项目本地 Skill，不写进 package-managed Skill。
+- 对长任务、多模块、多 agent、容易发生 `Context Delta` 调头或多轮验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
+- `plan.md` 中出现的长期事实必须提炼回 `project_context/**`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
+- `Context Delta: required` 时先更新 `project_context/**`，再继续实现；`none` 时直接按 Task Contract 实现。
+- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context。
+- 不为普通 bug fix、局部样式、小重构、局部实现漂移、测试修复或探索性 spike 强制编译任务契约。
+
+## 产品体验校准
+
+- 做页面、模块或入口规划时，先回答产品或页面定位是什么、要解决什么问题、需要提供什么给用户；再回答放什么、放哪里、为什么。这是页面变更前置判断，不是实现后的视觉润色。优先保留能帮助目标用户判断状态、采取行动、定位下一步或理解风险的信息。
+- 信息归属按使用场景决定：高频且跨页面的动作优先考虑系统级区域；模块动作放模块内部；运维、连接、缓存、后台任务等内部状态只有在影响用户判断或行动时才进入主界面，否则放运维/详情区域；低频解释放 Context、文档、帮助或详情，不默认占据主界面。
+- 首页、总览或入口页应服务产品定位下的核心使用路径和核心判断，不要为了证明系统层级完整而重复导航、堆叠入口、保留空指标槽或展示实现来源说明。
+- 产品文案面向真实用户，直白、行动优先；除产品名、协议、字段名、ID、调试 JSON 等必要专有名词外，普通按钮、筛选、状态、空态、警告和说明优先使用用户熟悉的语言。
+- 空态和数据要求真实：没有数据就显示真正空态，筛选无结果与系统无数据要区分，API/连接失败用用户能理解的状态表达，技术细节放到运维或详情里。
+
+## 控件任务框架
+
+- 当产品界面涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或状态反馈时，先把控件还原成用户任务：用户要判断什么、选择什么、提交什么或规避什么风险。
+- 先判断数据语义，再选交互：自由文本、枚举、实体选择、时间/区间、数量/预算、规则配置和内部开关对应不同的理解成本、错误成本和验证需求。
+- 明确用户确认自己“选对了/填对了/可以继续”的反馈：加载中、无结果、无数据、连接失败、校验失败、保存成功和风险提示要能被用户区分。
+- 对数量、预算、配额、限流、调度和时间类字段，判断是否需要单位、范围、默认值、示例、推荐值、成本/风险/影响说明；只记录稳定业务结论，不把一次性解释写进 Context。
+- 检查用户可见语言是否面向任务，而不是后端字段名、数据库列或内部枚举直出；必要技术细节放到详情、帮助、运维或调试视图。
+- 如果选择自由输入，必须判断错误成本、校验反馈和恢复路径是否可接受；如果不可接受，应形成更明确的输入约束或控件契约。
+- 这些问题是通用产品判断，不是固定控件处方。业务特定答案进入项目 Context 或项目本地 Skill；本次实现如何满足既有约束只写在交付说明。
+
+## 输出边界
+
+- 不默认创建 `.work_products/**`、PRD、tech plan、ADR、implementation doc、review/test/release 文档。
+- 不要求 lifecycle phase、plan task、phase gate 或阶段 Skill。
+- 如果用户明确要求独立方案文档，可以临时生成；长期事实仍要提炼回 `project_context/**`。
+- 如果用户只是要求实现功能、修 bug、调整代码、处理 package/release，或只是泛泛提到“产品 / product / requirements”，不需要触发本 Skill；只有明确角色名或强相关产物名指向产品判断、需求整理、验收口径或长期产品事实沉淀时才使用。
+
+## 建议沉淀位置
+
+- `global.md#Product / Delivery Brief`：项目级产品目标、用户、核心流程和非目标。
+- `global.md#Design Rationale`：长期产品取舍。
+- `areas/*.md#User / System Contract`：产品域可见行为、API、CLI、UI 或数据契约。
+- `areas/*.md#Key Constraints`：业务规则、边界、风险和不易从代码看出的约束。
+- `areas/*/verification.md` 或 role=`verification` Context：关键测试、smoke、CI、probe 或验证重复执行路径。
+- `areas/*/deployment.md` 或 role=`deployment` Context：关键部署、云端初始化、运行拓扑、健康检查或回滚重复执行路径。
+- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。

package/assets/skills/context_surface_contract/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: context_surface_contract
+description: Use when the user asks for Product Surface Contract, Surface Contract, Screen Contract, product surface responsibility, surface responsibility audit, information architecture governance, main/drilldown ownership, UI product boundary, product surface compiler, 产品界面职责治理, 产品接触面, 用户接触面, 页面职责契约, 界面责任契约, 主层/下钻归属, or asks to turn broad UI/product principles into project Context in a Minimal Context Harness project. Do not trigger for ordinary CSS tweaks, one-off UI bug fixes, copy edits, or implementation-only tasks unless the user explicitly asks to define or repair durable product-surface responsibility or information architecture contracts.
+---
+
+# Context Surface Contract
+
+## Package-Managed Boundary
+
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_surface_contract` Skill directly.
+
+Project-specific Product Surface responsibilities belong in `project_context/**` and optional project-local Skills such as `<harnessRoot>/skills/product_plan/SKILL.md`, `<harnessRoot>/skills/uiux_design/SKILL.md`, `<harnessRoot>/skills/development_engineer/SKILL.md` or `<harnessRoot>/skills/surface_contract/SKILL.md`. The package-managed Skill teaches the compiler workflow only; it must not contain business-specific page duties, provider facts, project names, raw payload schemas or product examples.
+
+## Purpose
+
+Help agents turn broad product/UI principles into concrete, project-owned Product Surface Contracts while keeping Minimal Context small.
+
+A Product Surface is any user-facing interface where users make judgments, take actions and receive feedback. Covered platforms include Web apps, dashboards, admin or operations UI, mobile screens, desktop windows, game UI/HUD/menu scenes, CLI/TUI output, browser extension or plugin UI, and embedded, kiosk or device UI.
+
+## Context Roles
+
+Do not add a new `context_role`.
+
+Use existing roles:
+
+- `contract` for cross-surface, cross-area or project-level Product Surface Contracts.
+- `area` or `subdomain` for owning product-domain Screen Contracts.
+- `verification` for repeatable UI, CLI, app or product-surface validation paths.
+- `decision-rationale` for stable product-surface tradeoff reasons.
+- `implementation-index` for code navigation only.
+
+Forbidden roles include `surface-contract`, `product-surface`, `web-contract`, `app-contract` and `game-surface`.
+
+## Mode Selection
+
+Use the narrowest mode that matches the request:
+
+- Audit Mode: inspect whether existing surfaces have clear responsibility.
+- Compile Mode: turn audit findings or user decisions into Context candidates.
+- Apply Mode: write durable Context only when the user explicitly allows durable writes.
+- Conformance Mode: check implementation against an existing Product Surface Contract.
+
+Do not run implementation, long validation, browser smoke, app smoke or CLI smoke unless the user explicitly asks for execution.
+
+## Audit Mode
+
+Use when the user asks to inspect, review or audit surface responsibility.
+
+Output only:
+
+- Surface list.
+- Surface platform.
+- Code, screenshot, CLI or app evidence inspected.
+- Existing Context expectation.
+- Drift, missing contract or backend complexity exposure.
+- Candidate `Context Delta`.
+- Suggested durable placement.
+- Optional temporary audit path under `tmp/**` when useful.
+
+Do not edit durable Context by default. Code, screenshots and CLI output are evidence of current implementation, not authority for product responsibility.
+
+## Compile Mode
+
+Use when turning audit findings or user decisions into Context candidates.
+
+Output:
+
+- Project-level Product Surface Contract candidate when responsibilities cross surfaces or areas.
+- Area-level Screen Contract candidate when ownership belongs inside one domain.
+- `context.toml` candidate registration with `role = "contract"` when durable registration is needed.
+- `global.md#Context Index` candidate entry when a new Context file is added.
+- Verification candidate for repeatable surface checks.
+- Repo-local Skill task-block candidate when the user wants project-specific enforcement.
+
+Do not assume business responsibilities from current code shape alone. Ask for confirmation if the candidate would silently choose between competing product or information-architecture meanings.
+
+## Apply Mode
+
+Use only when the user explicitly allows durable writes.
+
+Allowed writes:
+
+- `project_context/**`.
+- `project_context/context.toml`.
+- `project_context/global.md#Context Index`.
+- Optional `verification` role Context.
+- Optional separate project-local Skill files when the user explicitly wants project-local enforcement.
+
+Forbidden writes:
+
+- Package-managed generated Skills in a consumer project.
+- `<harnessRoot>/ty-context-managed/**` in a consumer project.
+- Business code unless the user also requested implementation.
+- Generated files.
+- `DESIGN.md`, except visual tokens or visual rationale that do not belong in a Product Surface Contract.
+
+If `Surface Contract Hit` is `none` and the task creates durable surface responsibility, set `Context Delta: required` and update project Context before implementation alignment.
+
+## Conformance Mode
+
+Use after implementation or during review.
+
+Output:
+
+- Surface Contract Conformance.
+- Remaining Drift.
+- Missing Context.
+- Implementation Drift.
+- Verification run / not_run / failed.
+
+Do not store one-off evidence, screenshots, logs, raw outputs or implementation summaries in Context.
+
+## Compiler Questions
+
+For each touched surface, answer only what is relevant:
+
+- What surface is being touched?
+- What platform shape does it have?
+- What primary user question does it answer?
+- What belongs on the main surface?
+- What must move to drilldown, diagnostics, operations, evidence or technical detail?
+- Which long-running or mutating actions require task id, progress, retry, import, recovery or history?
+- Which empty, loading, stale, unavailable, fixture or fallback states matter?
+- What validation path can prove conformance?
+
+## Repo-Local Task Block Candidate
+
+When the user wants project-local enforcement, propose a separate project-local Skill block like this and tailor only the project-specific answers:
+
+```markdown
+## Surface Contract Task Block
+
+For any task touching user-facing surfaces, information placement, forms, filters, search, long-running UI actions, diagnostics, evidence, CLI/TUI output or main/drilldown ownership, answer before implementation:
+
+- Surface Contract Hit: `<context file / none>`
+- Surface: `<route / screen / window / panel / command / HUD / menu>`
+- Surface Platform: `<web | mobile | desktop | game | cli-tui | extension | embedded | mixed>`
+- Owning Product Domain: `<area / subdomain>`
+- Primary User Question: `<one concrete user judgment>`
+- Main Surface Allows: `<durable visible information and actions>`
+- Main Surface Forbids: `<backend fields, raw payloads, diagnostics, debug ids, fake states, etc.>`
+- Drilldown Ownership: `<details / evidence / operations / diagnostics / technical details>`
+- Long Task State Requirement: `<run id, progress, retry, recovery, import, history, or none>`
+- Context Delta: `<none | required>`
+- Verification: `<view-model test / component test / browser smoke / CLI smoke / manual check>`
+```
+
+Do not add this task block to package-managed default Skills as a universal gate. Projects opt in through separate project-local Skills.
+
+## Implementation Alignment
+
+When implementation is also requested, align code with the Product Surface Contract:
+
+- View-models or presenters should expose user-facing states instead of raw backend payloads when that contract exists.
+- Components or commands should render main-surface facts and move technical details to the owning drilldown.
+- Long-running actions should persist or recover the required operation state.
+- Tests should assert user-facing state semantics, not only backend field plumbing.
+- Browser, app, CLI or game smoke checks should validate actual surface behavior when feasible.
+
+Final handoff should include concise `Surface Contract Conformance`: contract source, implementation alignment, remaining drift and verification status.
+
+## Output Boundaries
+
+- Do not create PRDs, UI/UX handoff docs, ADRs, stage artifacts, lifecycle state or phase gates.
+- Do not update Context for ordinary CSS tweaks, copy edits or one-off UI bug fixes unless durable surface responsibility changes.
+- Do not treat current backend fields, enums, JSON, screenshots or terminal output as product intent.
+- Do not add a validator, edit-order gate or package-level mandatory Surface Contract gate.
+- Do not include business-domain examples in this package-managed Skill.

package/assets/skills/context_uiux_design/SKILL.md

@@ -1,110 +1,113 @@
----
-name: context_uiux_design
-description: Use when the user explicitly asks for 设计稿, 重做设计, UI/UX 设计方案, UI 设计师, UX 设计师, 视觉设计方案, 视觉专家, 交互设计方案, 界面设计方案, 页面设计方案, 原型设计, 线框图方案, 视觉规范, 设计系统方案, DESIGN.md, Impeccable review, UX designer, UI designer, frontend redesign, visual polish, or design system spec in a Minimal Context Harness project. Do not trigger for ordinary UI implementation, CSS tweaks, bug fixes, or generic mentions of 设计, design, or user experience.
----
-
-# Context UIUX Design
-
-## Package-Managed Boundary
-
-This Skill is generated by `sdlc-harness sync` and owned by the Harness package. Do not edit the generated `context_uiux_design` Skill directly.
-
-Project-specific UI/UX and visual design rules belong in a separate project-local Skill under `<harnessRoot>/skills/uiux_design/SKILL.md`. When a project-local Skill and this package-managed Skill both apply, use the more specific project-local Skill as the primary instruction source while keeping durable conclusions in `project_context/**` and `DESIGN.md`. Keep the project-local Skill front matter `description` trigger keywords aligned with this package-managed Skill and the project `AGENTS.md` role-trigger rule; if the project adds or narrows trigger terms, update both places together so agent activation and SDLC guidance do not drift apart.
-
-## 目标
-
-帮助 agent 把界面、交互和视觉设计结论沉淀成可恢复的 Minimal Context 和 `DESIGN.md`。
-
-## 工作方式
-
-1. 先读取 `project_context/global.md` 和 `project_context/context.toml`，按 default area、triggers、read_when 选择相关 context。
-2. 如果项目存在 `DESIGN.md`，先读取它；如果用户要求视觉体系、设计稿或界面风格，按 Google `@google/design.md` 的 DESIGN.md 格式创建或更新根目录 `DESIGN.md`。
-3. 整理或生成：用户流程、页面/组件清单、关键状态、交互反馈、响应式边界、a11y 要求、视觉约束和设计 token。
-4. 涉及 Web 页面、前端布局、UI/UX、产品模块边界或信息放置时，把页面产品定位检查作为前置动作：用户在页面要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、下游消费层/运维层/详情层/其他页面归属、布局和信息密度是否匹配页面任务。多页面或多模块归属不清时，先读取相关 Context、搜索页面入口并结合已有 UI 代码/截图做全站或相关页面的信息架构 sweep，再收窄到具体视觉或交互实现。该检查是下一步变更分类的输入；只有形成长期页面职责、信息架构、交互契约或模块边界结论时才更新 Context 或 `DESIGN.md`。
-5. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件交互框架”检查控件语义、反馈状态、校验、错误预防、可供性和信息密度；这只是通用判断框架，不是固定控件处方。
-6. 界面职责、流程归属和长期交互契约以 `project_context/**` 为准；`DESIGN.md` 负责视觉 token 和视觉 rationale；代码、截图和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码和截图揭示“现在是什么”，代码不能静默重定义 Context。
-7. 设计判断或第一处实现编辑前，若任务涉及页面职责、流程边界、信息架构、交互契约、状态或调度语义、可访问性约束、设计验证关键路径或部署关键路径，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`。
-8. 普通 UI bug、局部样式或 CSS 修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期交互或视觉结论，继续对齐或交付前必须回写 Context 或 `DESIGN.md`。不要把 Context 机械补成代码改动摘要。
-9. 如果二者冲突，显式标记为实现漂移、缺失工作或 Context 过期。
-10. 如果涉及已有 UI，优先结合代码入口、运行截图或用户提供的参考图来描述差异。
-11. 当任务涉及设计稿、重做设计、视觉方案、设计系统、visual polish、frontend redesign 或 frontend styling，且存在可扫描的 UI 代码、页面文件、构建产物目录或本地/远程 URL 时，默认运行 `npx impeccable detect <target>`；实现前可用于识别既有视觉问题，实现后或交付前用于审查结果。没有可扫描目标、命令不可用或扫描失败时，说明原因并继续。
-12. 需要长期沉淀时：
-   - 项目级体验原则和屏幕清单写入 `global.md`。
-   - 模块级 screen contract、state、interaction 和视觉约束写入对应 area / subdomain Context。
-   - 颜色、字体、间距、圆角、组件视觉 token 和视觉 rationale 写入 `DESIGN.md`。
-   - 新 UI context unit 可新增 `project_context/areas/<unit>.md`，并更新 `global.md#Context Index`；复杂项目同时更新 `project_context/context.toml`。
-   - 如果 `upgrade` 自动把深层 `.md` 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。
-13. Context 只能声明设计验收入口或 smoke 入口，不能伪造“已验证通过”。
-14. Verification / Deployment Role Context 只记录长期可复用的设计验证、smoke、部署或运行初始化路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id、raw payload 或完整截图报告。
-15. 收尾时做 `Contract Conformance` 和 Context drift check，只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和截图 / 手动检查入口；一次性证据、截图结果、测试日志、任务契约和实现摘要不写入 Context。
-
-## 任务契约编译
-
-- 任务契约是当前界面任务的编译产物，不是事实源、设计稿文档链、handoff matrix 或长期 Context；默认留在方案、交付说明或 PR 文本中。
-- `Context Delta` 必须先出现，取值为 `none` 或 `required`：
-  - `none`：本次只是按既有 Context / `DESIGN.md` / 设计原则落地，不新增长期事实。
-  - `required`：说明长期事实类型、应写入的 Context / role 或 `DESIGN.md` 位置、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
-- `Task Contract` 用短列表说明页面 / 组件任务、用户判断、主信息和辅助信息归属、动作层级、输入语义、loading / empty / no results / stale / error / degraded / success 状态、布局稳定性、非目标和验收入口。
-- 对长任务、多页面/组件、多 agent、容易发生 `Context Delta` 调头或多轮截图 / 手动验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
-- `plan.md` 中出现的长期界面、交互或视觉事实必须提炼回 `project_context/**` 或 `DESIGN.md`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
-- `Context Delta: required` 时先更新 `project_context/**` 或 `DESIGN.md`，再继续实现；`none` 时直接按 Task Contract 实现。
-- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context / `DESIGN.md`。
-- 不为普通 UI bug、局部 CSS 修复、小重构、测试修复或探索性 spike 强制编译任务契约。
-
-## 信息呈现校准
-
-- 页面设计先回答：产品/页面定位是什么、要解决什么问题、用户需要什么、页面需要提供什么内容/能力/反馈；再决定元素放什么、放哪里、为什么。这是页面变更前置判断，不是实现后的视觉润色。常驻元素应证明它比位置、图标、状态、数据或交互提示更能省注意力。
-- 追求有效信息密度，而不是塞满页面。判断标准是更少无效 chrome、更少解释、更靠近真实内容和可执行动作；警惕用大标题、大容器、空卡片、假摘要或装饰区块制造仪式感。
-- 对返回、刷新、同步、关闭、搜索、展开/收起等熟悉动作，比较 icon-only、紧凑控件、文字按钮和图标+文字哪种最省注意力；如果使用 icon-only，必须保留 `aria-label`、`title`、tooltip 或 hover/focus 说明。动作不熟悉、风险高或需要区分多个相近命令时，文字通常更合适。
-- 常驻文字要克制。用户已经知道且不帮助行动的页面标题、面包屑、说明句或分区名，先判断是否可以删除，而不是先润色；必要解释可进入 tooltip、hover/focus 展开层、空态、详情页、帮助或 Context。
-- 空间应由内容价值支撑。内容少时布局可以收缩到内容附近；警惕保留一整行只有几个字的 header、空指标槽、空列表容器或没有真实数据支撑的摘要。
-- 信息架构按归属放置：真正跨页面的动作可放系统级 chrome，模块动作放模块内部，运维/连接/缓存/后台任务状态只在影响用户判断或行动时进入主工作面，低频系统解释放详情、日志、调试视图或文档。
-- 空态、加载态和错误态必须真实。不要用 fixture、看似真实的 fallback 行或“这里不展示示例数据”这类元说明遮住没有数据；筛选无结果、系统无数据和连接失败要视觉上可区分。
-- 页面稳定性是 UX 合同。滚动条出现、列表加载、tab 切换、虚拟列表高度变化、面板展开收起都不应导致布局跳动；需要时预留 `scrollbar-gutter`、稳定容器尺寸、固定关键控件尺寸和可预测的 loading skeleton。
-- 文案服务任务，不解释设计。主界面避免内部黑话、实现边界说明、生产/示例数据规则和后端来源说明；必要技术细节放到详情、日志、调试视图或运维区域。
-
-## 控件交互框架
-
-- 当界面涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或状态反馈时，先判断控件承载的交互语义，而不是直接沿用后端字段形态。
-- 判断输入数据是自由文本、枚举、实体选择、时间/区间、数量/预算还是规则配置；不同语义需要不同的可供性、约束、校验和错误恢复。
-- 明确用户完成动作前后需要的反馈状态：loading、empty、no results、error、disabled、saving、success 和 validation feedback 应该支持用户判断下一步。
-- 检查控件是否给足单位、范围、默认值、示例、推荐值、风险/成本/影响提示；解释应靠近决策点，低频细节可以进 tooltip、详情或帮助。
-- 检查可见标签、helper text、错误文案和状态文案是否是用户语言，而不是内部字段、接口名或枚举名。
-- 自由输入不是禁用项，但要和错误成本匹配：当格式固定、错误代价高或反馈复杂时，应考虑更明确的约束、选择机制或校验反馈。
-- 不把本框架读成固定控件清单：搜索是否自动触发、时间是否用 picker、预算是否用 stepper，都应由数据规模、API 成本、用户任务、错误成本和项目组件体系决定。
-
-## 视觉质量校准
-
-- 先判断界面 register：品牌页、营销页、作品集等让设计承载表达；产品工具、后台、dashboard、表单等让设计服务任务。品牌界面可以更强烈地使用图像、色彩和编排；产品界面优先可扫读、稳定组件、熟悉交互和任务效率。
-- 已有 UI 优先保持身份连续性：先找现有 token、组件库、全局 CSS、Tailwind config、截图或代表性页面；除非用户明确要求重设计，不要推翻已建立的字体、颜色、组件语言。
-- 绿色地设计视觉体系时，先说明场景和色彩策略，再选 token：谁在什么环境下使用、界面应该 restrained / committed / full palette / drenched 到什么程度。不要按品类套默认审美。
-- 做设计方案或视觉规范时，显式检查：文字对比度、65-75ch 正文行长、清晰字号层级、响应式边界、44px 触控目标、焦点态、hover/active/disabled/loading/error/success 状态、空态/错误态/长文本、reduced motion 和文本不溢出。
-- 避免常见 AI 视觉反模式：嵌套卡片、无意义玻璃拟态、紫蓝渐变或渐变文字、灰字压在彩色背景上、默认米色/奶油色大背景、过度圆角、边框加大模糊阴影的幽灵卡片、每段一个圆角 icon tile、每节重复小号全大写 eyebrow 或 `01 / 02 / 03` 标记、bounce/elastic easing、空泛营销 buzzword。
-- 视觉审查时先分清问题类型：a11y / responsive / theming / interaction / copy / performance / anti-pattern。把真正影响用户理解、操作或品牌信任的问题列为高优先级；少量纯审美偏好不要淹没关键问题。
-- Harness 默认携带 Impeccable CLI 能力；做设计稿、重做设计、视觉设计方案、设计系统方案、frontend redesign、visual polish 或既有 UI 视觉审查时，默认尝试运行 `npx impeccable detect <target>` 作为辅助证据，不必等待用户点名。其输出只能作为设计缺陷线索，不是 Harness gate，也不能替代人工截图检查、项目测试或 `validate-context`。
-
-## 输出边界
-
-- 不默认创建 `.work_products/**`、UI/UX 独立文档、handoff matrix、review/test/release 文档。
-- 不要求 lifecycle phase、plan task、phase gate 或阶段 Skill。
-- 如果用户明确要求独立设计稿、mock 或页面说明，可以临时生成；长期事实仍要提炼回 `project_context/**` 和 `DESIGN.md`。
-- `DESIGN.md` 是视觉设计系统事实源；项目流程、模块契约和下一步动作仍以 `project_context/**` 为准。
-- 如果用户只是要求实现页面、修复 UI bug、局部改 CSS、换颜色，或只是泛泛提到“设计 / design / user experience”，不需要触发本 Skill；只有明确角色名或强相关产物名指向设计方向、界面方案、视觉体系、交互规则或长期设计事实沉淀时才使用。
-
-## DESIGN.md 使用规则
-
-- 使用 Google `@google/design.md` 格式：YAML front matter 存 tokens，Markdown body 存设计理由。
-- 优先包含 `name`、`colors`、`typography`、`spacing`、`rounded` 和必要 `components` token。
-- Markdown section 顺序优先为：`Overview`、`Colors`、`Typography`、`Layout`、`Elevation & Depth`、`Shapes`、`Components`、`Do's and Don'ts`。
-- 写入或修改后，如本地可用，运行 `npx @google/design.md lint DESIGN.md` 检查结构；不要把 lint 结果写成“已通过”除非本轮真实执行。
-- 需要给工程消费 token 时，可用 `npx @google/design.md export --format css-tailwind DESIGN.md` 或 `json-tailwind` 生成临时输出。
-
-## 建议沉淀位置
-
-- `global.md#UX / Screen Brief`：全局体验原则、主要屏幕、跨模块流程。
-- `areas/*.md#User / System Contract`：页面、组件、状态、交互和数据展示契约。
-- `areas/*.md#Key Constraints`：responsive、a11y、品牌/视觉边界、加载/空态/错误态约束。
-- `areas/*/verification.md` 或 role=`verification` Context：UI smoke、截图验收、可访问性检查或项目自己的关键验证重复执行路径。
-- `areas/*/deployment.md` 或 role=`deployment` Context：前端部署、预览环境、运行拓扑或健康检查重复执行路径。
-- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。
-- `DESIGN.md`：视觉 identity、design tokens、组件视觉规则和 do/don't。
+---
+name: context_uiux_design
+description: Use when the user explicitly asks for 设计稿, 重做设计, UI/UX 设计方案, UI 设计师, UX 设计师, 视觉设计方案, 视觉专家, 交互设计方案, 界面设计方案, 页面设计方案, 原型设计, 线框图方案, 视觉规范, 设计系统方案, DESIGN.md, Impeccable review, UX designer, UI designer, frontend redesign, visual polish, or design system spec in a Minimal Context Harness project. Do not trigger for ordinary UI implementation, CSS tweaks, bug fixes, or generic mentions of 设计, design, or user experience.
+---
+
+# Context UIUX Design
+
+## Package-Managed Boundary
+
+This Skill is generated by `ty-context sync` and owned by the Harness package. Do not edit the generated `context_uiux_design` Skill directly.
+
+Project-specific UI/UX and visual design rules belong in a separate project-local Skill under `<harnessRoot>/skills/uiux_design/SKILL.md`. When a project-local Skill and this package-managed Skill both apply, use the more specific project-local Skill as the primary instruction source while keeping durable conclusions in `project_context/**` and `DESIGN.md`. Keep the project-local Skill front matter `description` trigger keywords aligned with this package-managed Skill and the project `AGENTS.md` role-trigger rule; if the project adds or narrows trigger terms, update both places together so agent activation and Tiny Context guidance do not drift apart.
+
+## 目标
+
+帮助 agent 把界面、交互和视觉设计结论沉淀成可恢复的 Minimal Context 和 `DESIGN.md`。
+
+## 工作方式
+
+1. 先读取 `project_context/global.md` 和 `project_context/context.toml`，按 default area、triggers、read_when 选择相关 context。
+2. 如果项目存在 `DESIGN.md`，先读取它；如果用户要求视觉体系、设计稿或界面风格，按 Google `@google/design.md` 的 DESIGN.md 格式创建或更新根目录 `DESIGN.md`。
+3. 整理或生成：用户流程、页面/组件清单、关键状态、交互反馈、响应式边界、a11y 要求、视觉约束和设计 token。
+4. 涉及 Product Surface（Web 页面、移动/桌面屏幕、游戏 UI/HUD/菜单、CLI/TUI 输出、扩展或设备界面）、前端布局、UI/UX、产品模块边界或信息放置时，把产品/页面定位检查作为前置动作：用户在这个 surface 要完成的判断、产品必须提供的信息/动作/反馈、不应常驻的信息、主层/下钻/运维/诊断/详情归属、布局和信息密度是否匹配任务。多 surface、多平台或多模块归属不清时，先读取相关 Context、搜索入口并结合已有 UI 代码/截图做信息架构 sweep，必要时使用 `context_surface_contract` 做 Surface Contract Check，再收窄到具体视觉或交互实现。该检查是下一步变更分类的输入；只有形成长期 surface 职责、信息架构、交互契约或模块边界结论时才更新 Context 或 `DESIGN.md`。
+   - 若存在 Product Surface Contract，读取并对齐 primary user question、main allows/forbids、drilldown ownership、long-task state 和 verification。
+   - 若缺失且本任务改变 durable surface responsibility，输出 `Surface Contract Delta: required`，把界面职责写入 `project_context/**`；视觉 token、颜色、字体、间距、圆角和视觉 rationale 仍写入 `DESIGN.md`。
+5. 涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或加载/空态/错误态等 UI 控件时，用“控件交互框架”检查控件语义、反馈状态、校验、错误预防、可供性和信息密度；这只是通用判断框架，不是固定控件处方。
+6. 界面职责、流程归属和长期交互契约以 `project_context/**` 为准；`DESIGN.md` 负责视觉 token 和视觉 rationale；代码、截图和搜索结果只说明当前实现状态。Context 决定“应该是什么”，代码和截图揭示“现在是什么”，代码不能静默重定义 Context。
+7. 设计判断或第一处实现编辑前，若任务涉及页面职责、流程边界、信息架构、交互契约、状态或调度语义、可访问性约束、设计验证关键路径或部署关键路径，先编译当前任务契约；契约第一段用 `Context Delta: none|required` 完成唯一正式长期事实判断，再写本次 `Task Contract`。
+8. 普通 UI bug、局部样式或 CSS 修复、测试修复或探索性 spike 不更新 Context，可先改代码；一旦形成长期交互或视觉结论，继续对齐或交付前必须回写 Context 或 `DESIGN.md`。不要把 Context 机械补成代码改动摘要。
+9. 如果二者冲突，显式标记为实现漂移、缺失工作或 Context 过期。
+10. 如果涉及已有 UI，优先结合代码入口、运行截图或用户提供的参考图来描述差异。
+11. 当任务涉及设计稿、重做设计、视觉方案、设计系统、visual polish、frontend redesign 或 frontend styling，且存在可扫描的 UI 代码、页面文件、构建产物目录或本地/远程 URL 时，默认运行 `npx impeccable detect <target>`；实现前可用于识别既有视觉问题，实现后或交付前用于审查结果。没有可扫描目标、命令不可用或扫描失败时，说明原因并继续。
+12. 需要长期沉淀时：
+   - 项目级体验原则和屏幕清单写入 `global.md`。
+   - 模块级 screen contract、state、interaction 和视觉约束写入对应 area / subdomain Context。
+   - 颜色、字体、间距、圆角、组件视觉 token 和视觉 rationale 写入 `DESIGN.md`。
+   - 新 UI context unit 可新增 `project_context/areas/<unit>.md`，并更新 `global.md#Context Index`；复杂项目同时更新 `project_context/context.toml`。
+   - 如果 `upgrade` 自动把深层 `.md` 注册成 area，但语义上更像 foundation / contract / archive，后续应显式调整 manifest role；不要依赖自动迁移判断语义。
+13. Context 只能声明设计验收入口或 smoke 入口，不能伪造“已验证通过”。
+14. Verification / Deployment Role Context 只记录长期可复用的设计验证、smoke、部署或运行初始化路径事实：特殊准备、最短命令或路径、预期阶段 / 信号、可接受 warning、已排除的重复探索点。不要记录一次性测试日志、完整输出、临时 JSON、CI artifact、测试报告、release ledger、secret、token、cookie、device id、raw payload 或完整截图报告。
+15. 收尾时做 `Contract Conformance` 和 Context drift check，只报告轻量状态：`Context: 已更新 ...` 或 `Context: 本次无长期事实变化`。Conformance 说明本次契约满足情况、未满足或延期项和截图 / 手动检查入口；一次性证据、截图结果、测试日志、任务契约和实现摘要不写入 Context。
+
+## 任务契约编译
+
+- 任务契约是当前界面任务的编译产物，不是事实源、设计稿文档链、handoff matrix 或长期 Context；默认留在方案、交付说明或 PR 文本中。
+- `Context Delta` 必须先出现，取值为 `none` 或 `required`：
+  - `none`：本次只是按既有 Context / `DESIGN.md` / 设计原则落地，不新增长期事实。
+  - `required`：说明长期事实类型、应写入的 Context / role 或 `DESIGN.md` 位置、需要沉淀的事实，以及明确不写入 Context 的一次性内容。
+- `Task Contract` 用短列表说明页面 / 组件任务、用户判断、主信息和辅助信息归属、动作层级、输入语义、loading / empty / no results / stale / error / degraded / success 状态、布局稳定性、非目标和验收入口。
+- 触及 Product Surface 时，`Task Contract` 同时说明 surface platform、primary user question、main allows/forbids、drilldown ownership、long-task state requirement 和 verification；代码字段、枚举、JSON 或截图只是实现证据，不是产品职责来源。
+- 对长任务、多页面/组件、多 agent、容易发生 `Context Delta` 调头或多轮截图 / 手动验证的任务，可以用 `plan.md` 或等价临时计划面暂存 `Context Delta`、`Task Contract`、`Implementation Steps` 和 `Contract Conformance`；它只是临时执行缓存。
+- `plan.md` 中出现的长期界面、交互或视觉事实必须提炼回 `project_context/**` 或 `DESIGN.md`；否则不要把临时计划当作事实源、交付产物或后续引用依据。
+- `Context Delta: required` 时先更新 `project_context/**` 或 `DESIGN.md`，再继续实现；`none` 时直接按 Task Contract 实现。
+- `Contract Conformance` 是交付前的软检查：实现偏差修实现，契约遗漏回 Task Contract，长期事实缺失回 `Context Delta` 并先更新 Context / `DESIGN.md`。
+- 不为普通 UI bug、局部 CSS 修复、小重构、测试修复或探索性 spike 强制编译任务契约。
+
+## 信息呈现校准
+
+- 页面设计先回答：产品/页面定位是什么、要解决什么问题、用户需要什么、页面需要提供什么内容/能力/反馈；再决定元素放什么、放哪里、为什么。这是页面变更前置判断，不是实现后的视觉润色。常驻元素应证明它比位置、图标、状态、数据或交互提示更能省注意力。
+- 追求有效信息密度，而不是塞满页面。判断标准是更少无效 chrome、更少解释、更靠近真实内容和可执行动作；警惕用大标题、大容器、空卡片、假摘要或装饰区块制造仪式感。
+- 对返回、刷新、同步、关闭、搜索、展开/收起等熟悉动作，比较 icon-only、紧凑控件、文字按钮和图标+文字哪种最省注意力；如果使用 icon-only，必须保留 `aria-label`、`title`、tooltip 或 hover/focus 说明。动作不熟悉、风险高或需要区分多个相近命令时，文字通常更合适。
+- 常驻文字要克制。用户已经知道且不帮助行动的页面标题、面包屑、说明句或分区名，先判断是否可以删除，而不是先润色；必要解释可进入 tooltip、hover/focus 展开层、空态、详情页、帮助或 Context。
+- 空间应由内容价值支撑。内容少时布局可以收缩到内容附近；警惕保留一整行只有几个字的 header、空指标槽、空列表容器或没有真实数据支撑的摘要。
+- 信息架构按归属放置：真正跨页面的动作可放系统级 chrome，模块动作放模块内部，运维/连接/缓存/后台任务状态只在影响用户判断或行动时进入主工作面，低频系统解释放详情、日志、调试视图或文档。
+- 空态、加载态和错误态必须真实。不要用 fixture、看似真实的 fallback 行或“这里不展示示例数据”这类元说明遮住没有数据；筛选无结果、系统无数据和连接失败要视觉上可区分。
+- 页面稳定性是 UX 合同。滚动条出现、列表加载、tab 切换、虚拟列表高度变化、面板展开收起都不应导致布局跳动；需要时预留 `scrollbar-gutter`、稳定容器尺寸、固定关键控件尺寸和可预测的 loading skeleton。
+- 文案服务任务，不解释设计。主界面避免内部黑话、实现边界说明、生产/示例数据规则和后端来源说明；必要技术细节放到详情、日志、调试视图或运维区域。
+
+## 控件交互框架
+
+- 当界面涉及输入、选择、搜索、筛选、表单/配置、调度/时间窗口、预算/配额/限流或状态反馈时，先判断控件承载的交互语义，而不是直接沿用后端字段形态。
+- 判断输入数据是自由文本、枚举、实体选择、时间/区间、数量/预算还是规则配置；不同语义需要不同的可供性、约束、校验和错误恢复。
+- 明确用户完成动作前后需要的反馈状态：loading、empty、no results、error、disabled、saving、success 和 validation feedback 应该支持用户判断下一步。
+- 检查控件是否给足单位、范围、默认值、示例、推荐值、风险/成本/影响提示；解释应靠近决策点，低频细节可以进 tooltip、详情或帮助。
+- 检查可见标签、helper text、错误文案和状态文案是否是用户语言，而不是内部字段、接口名或枚举名。
+- 自由输入不是禁用项，但要和错误成本匹配：当格式固定、错误代价高或反馈复杂时，应考虑更明确的约束、选择机制或校验反馈。
+- 不把本框架读成固定控件清单：搜索是否自动触发、时间是否用 picker、预算是否用 stepper，都应由数据规模、API 成本、用户任务、错误成本和项目组件体系决定。
+
+## 视觉质量校准
+
+- 先判断界面 register：品牌页、营销页、作品集等让设计承载表达；产品工具、后台、dashboard、表单等让设计服务任务。品牌界面可以更强烈地使用图像、色彩和编排；产品界面优先可扫读、稳定组件、熟悉交互和任务效率。
+- 已有 UI 优先保持身份连续性：先找现有 token、组件库、全局 CSS、Tailwind config、截图或代表性页面；除非用户明确要求重设计，不要推翻已建立的字体、颜色、组件语言。
+- 绿色地设计视觉体系时，先说明场景和色彩策略，再选 token：谁在什么环境下使用、界面应该 restrained / committed / full palette / drenched 到什么程度。不要按品类套默认审美。
+- 做设计方案或视觉规范时，显式检查：文字对比度、65-75ch 正文行长、清晰字号层级、响应式边界、44px 触控目标、焦点态、hover/active/disabled/loading/error/success 状态、空态/错误态/长文本、reduced motion 和文本不溢出。
+- 避免常见 AI 视觉反模式：嵌套卡片、无意义玻璃拟态、紫蓝渐变或渐变文字、灰字压在彩色背景上、默认米色/奶油色大背景、过度圆角、边框加大模糊阴影的幽灵卡片、每段一个圆角 icon tile、每节重复小号全大写 eyebrow 或 `01 / 02 / 03` 标记、bounce/elastic easing、空泛营销 buzzword。
+- 视觉审查时先分清问题类型：a11y / responsive / theming / interaction / copy / performance / anti-pattern。把真正影响用户理解、操作或品牌信任的问题列为高优先级；少量纯审美偏好不要淹没关键问题。
+- Harness 默认携带 Impeccable CLI 能力；做设计稿、重做设计、视觉设计方案、设计系统方案、frontend redesign、visual polish 或既有 UI 视觉审查时，默认尝试运行 `npx impeccable detect <target>` 作为辅助证据，不必等待用户点名。其输出只能作为设计缺陷线索，不是 Harness gate，也不能替代人工截图检查、项目测试或 `validate-context`。
+
+## 输出边界
+
+- 不默认创建 `.work_products/**`、UI/UX 独立文档、handoff matrix、review/test/release 文档。
+- 不要求 lifecycle phase、plan task、phase gate 或阶段 Skill。
+- 如果用户明确要求独立设计稿、mock 或页面说明，可以临时生成；长期事实仍要提炼回 `project_context/**` 和 `DESIGN.md`。
+- `DESIGN.md` 是视觉设计系统事实源；项目流程、模块契约和下一步动作仍以 `project_context/**` 为准。
+- 如果用户只是要求实现页面、修复 UI bug、局部改 CSS、换颜色，或只是泛泛提到“设计 / design / user experience”，不需要触发本 Skill；只有明确角色名或强相关产物名指向设计方向、界面方案、视觉体系、交互规则或长期设计事实沉淀时才使用。
+
+## DESIGN.md 使用规则
+
+- 使用 Google `@google/design.md` 格式：YAML front matter 存 tokens，Markdown body 存设计理由。
+- 优先包含 `name`、`colors`、`typography`、`spacing`、`rounded` 和必要 `components` token。
+- Markdown section 顺序优先为：`Overview`、`Colors`、`Typography`、`Layout`、`Elevation & Depth`、`Shapes`、`Components`、`Do's and Don'ts`。
+- 写入或修改后，如本地可用，运行 `npx @google/design.md lint DESIGN.md` 检查结构；不要把 lint 结果写成“已通过”除非本轮真实执行。
+- 需要给工程消费 token 时，可用 `npx @google/design.md export --format css-tailwind DESIGN.md` 或 `json-tailwind` 生成临时输出。
+
+## 建议沉淀位置
+
+- `global.md#UX / Screen Brief`：全局体验原则、主要屏幕、跨模块流程。
+- `areas/*.md#User / System Contract`：页面、组件、状态、交互和数据展示契约。
+- `areas/*.md#Key Constraints`：responsive、a11y、品牌/视觉边界、加载/空态/错误态约束。
+- `areas/*/verification.md` 或 role=`verification` Context：UI smoke、截图验收、可访问性检查或项目自己的关键验证重复执行路径。
+- `areas/*/deployment.md` 或 role=`deployment` Context：前端部署、预览环境、运行拓扑或健康检查重复执行路径。
+- `project_context/context.toml`：复杂项目的产品域 area/context_unit、role、触发词、按需读取策略和可选边界规则。
+- `DESIGN.md`：视觉 identity、design tokens、组件视觉规则和 do/don't。