design-spec

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会改写旧版 Claude /skill-name 引用。
• 任务跟踪要求：执行任何工作流或技能步骤之前，必须为所有步骤创建或更新任务跟踪，并随着进度变化保持同步。
• 用户提问提示表示应在 Codex 中直接询问用户。
• 出现 Claude 专属的模式切换指令时，请忽略。
• 严格执行约定：用户明确调用某项技能时，必须按原样执行该技能协议。
• 子 Agent 授权：用户调用或 AI 检测到某项技能，且该技能协议要求使用子 Agent 时，该技能的启用即授权为该任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，必须明确执行每个列出的子技能步骤，并逐步报告证据。
• 如果此环境中无法运行某个必需步骤或工具，请停止并在调整方案前询问用户。

Codex 项目参考资料加载（无钩子）

Codex 使用静态项目参考资料加载，而非运行时注入项目文档。 编码、规划、调试、测试或审查时，请按以下路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块以及工作流/测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录的路由）
• docs/project-reference/lessons.md（始终适用的防护措施和反模式）

上下文缺失或过时时的处理路径： 如果 docs/project-config.json、文档索引、lessons.md、CLAUDE.md、AGENTS.md 或任务所需的任何参考文档缺失或过时，请在常规项目工作之前自动运行 $project-init 或范围更窄的设置路径（$project-config、$docs-init、$scan-all、$scan --target=<key>、$claude-md-init）。如果 Codex 镜像或 AGENTS.md 缺失或过时，请让用户运行 $sync-codex；不要自动运行。

按场景查阅文档：

• 项目结构/架构/技术栈/部署/设置（任何层级——后端、前端或基础设施）：project-structure-reference.md
• 后端/CQRS/API/领域/实体变更：backend-patterns-reference.md、domain-entities-reference.md
• 前端/UI/样式/设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规范编写、docs/specs/ 路径或 TC 格式：feature-spec-reference.md、spec-system-reference.md、spec-principles.md
• 行为/公共契约变更或规范-测试-代码同步：workflow-spec-test-code-cycle-reference.md 以及上述规范文档
• 衍生规范索引/ERD/重实现指南：spec-system-reference.md 和 docs/specs/ 下的源 Feature Specs
• 集成测试实现/审查：integration-test-reference.md
• E2E 测试实现/审查：e2e-test-reference.md
• 代码审查/审计工作：code-review-rules.md，以及根据变更文件确定的领域文档

不要不加区分地阅读所有文档。从 docs-index-reference.md 开始，然后只打开与任务相关的文件。

[BLOCKING] 按声明顺序执行技能步骤。未经用户明确批准，绝不跳过、重排或合并步骤。 [BLOCKING] 每个步骤或子技能调用之前，都要更新任务跟踪：步骤开始时设为 in_progress，结束时设为 completed。 [BLOCKING] 每个已完成或已跳过的步骤都必须附上简短证据或明确的跳过原因。 [BLOCKING] 如果任务工具不可用，请创建并维护等效的逐步计划跟踪，并使用相同的状态转换。

快速摘要

目标： 根据需求/PBI/故事/线框图，生成结构化、与技术栈无关的 UI/UX 设计规范，让开发者能在任意技术栈上重建 UI——记录每个组件、状态、设计令牌、响应式规则和无障碍需求，并将其关联回对应的功能规范。

摘要（如果只读一部分，请读这里——目的 + 每个主要步骤）：

• 目的 — 将需求转化为开发者可直接使用的 UI/UX 规范（组件清单、状态、设计令牌、响应式行为、无障碍），且与技术栈无关：按 UX 角色命名组件，绝不使用框架/库类名。
• 步骤 0–0b — 先调研： 清点现有的相关界面/组件，并梳理相互关联的流程；记录在 §1 中，确保规范与当前 UI 系统一致；如果存在对应的功能规范，则以其 §6 交互界面为基础，并原样复用其中的视图和可观察状态词汇。——原因：词汇不一致会破坏规范↔设计中心的导航。
• 步骤 1–2 — 读取并判定输入类型，确定复杂度： Figma URL → $figma-design；图像/屏幕截图 → 视觉分析工具；线框图/草图 → --mode=wireframe；PBI/文本 → 提取需求。选择快速规范（§1–4）或完整规范（§1–7，多页面时另附流程图）。
• 步骤 3–6 — 编写正文： 建立组件清单（区分新增与现有组件），定义全部 7 种状态及交互，提取设计令牌（复用设计系统），记录响应式断点（移动端 320–767 / 平板 768–1023 / 桌面端 1024+）。
• 步骤 7–8 — 保存并关联回去： 将产物写入 team-artifacts/design-specs/，然后在对应功能规范的 frontmatter 中设置 design_spec:/mockup:，指向已保存的路径——仅限 frontmatter，绝不能修改 §1–8 正文。——原因：如果未记录该路径，artifact-review --type=design 就会失败。

工作流：

1. 读取来源 — 从 PBI、故事或 Figma URL 中提取 UI 需求
2. 确定复杂度 — 快速规范（第 1–4 节）还是完整规范（全部 7 节）
3. 建立组件清单 — 列出新增与现有组件
4. 定义状态与令牌 — 交互、设计令牌、响应式断点
5. 保存产物 — 输出到 team-artifacts/design-specs/

关键规则：

• 如果提供了 Figma URL → 自动转交给 $figma-design 进行上下文提取
• 如果提供了线框图像（手绘/数字绘制/工具导出）→ 通过 --mode=wireframe 在内部处理（参见下方“模式：wireframe”）
• 如果提供了屏幕截图 → 使用 visual analysis tooling 提取设计信息
• 引用 docs/project-reference/design-system/ 中现有的设计系统令牌
• 组件模式：docs/project-reference/frontend-patterns-reference.md
• 包含无障碍要求（键盘导航、ARIA 标签、对比度）
• [BLOCKING] 与技术栈无关的输出： 规范正文/标题遵循 docs/project-reference/spec-principles.md §3——按 UX 角色描述组件，而非使用框架/库名称；源路径和类名只能出现在证据字段（**Evidence**、[Source:]）、frontmatter 和 Mermaid 中。

保持质疑，运用批判性思维和顺序思维。每项陈述都必须有可追溯的证据，并标注置信度百分比（Idea 应高于 80%）。

设计规范

根据需求或 PBI 创建结构化的 UI/UX 设计规范文档，以便交接给开发者。

适用场景

• PBI 或用户故事在实现前需要设计规范
• 将需求转化为具体的 UI 布局、状态和令牌
• 记录组件清单和交互模式
• 创建响应式断点规范

不适用场景

• 此技能会自动将 Figma URL 转交给 $figma-design；线框图在内部通过 --mode=wireframe 处理——无需调用单独的技能
• 构建实际 UI——营销/创意类请使用 design --lane=marketing，产品 UI 请使用 design --lane=product
• 审查现有 UI 代码——请使用 web-design-guidelines

前提条件

执行前请阅读：

• 源 PBI、用户故事或需求文档
• docs/project-reference/design-system/ —— 项目设计令牌（如适用）
• team-artifacts/design-specs/ 中现有的设计规范，以保持格式一致

前端 / UI 上下文

当此任务涉及前端或 UI 更改时，

• 前端模式：docs/project-reference/frontend-patterns-reference.md
• 样式 / BEM 指南：docs/project-reference/scss-styling-guide.md
• 设计系统令牌：docs/project-reference/design-system/README.md

工作流

[BLOCKING] 步骤 0 — 梳理现有 UI，并映射关联流程（遵循此技能所包含的 SYNC:existing-ui-research 协议）。在编写规范前，梳理现有的相关屏幕 / 组件 / 页面，找出已服务于此功能或领域的内容，并映射所有与新屏幕关联的功能流程，包括链接到新屏幕、嵌入新屏幕或从新屏幕导航到其他位置的流程。在 §1 概述中记录匹配的屏幕和流程，使规范忠实反映当前的 UI 系统。仅后端工作可跳过此步骤（并明确说明）。

[BLOCKING] 步骤 0b — 以主导 Feature Spec 的 §6 交互界面为起点（如有）。 检查是否已有规范功能的 Feature Spec（在 docs/specs/** 中查找涵盖相同能力的规范）。如果存在，请阅读其 §6 流程与交互界面，包括 视图清单（§6.2）、导航图（§6.3）、关键 UI 状态（§6.4）和 逐用户故事交互流程（§6.5），并以此作为本设计规范的起始框架：

• 逐字沿用该规范的术语——沿用 §6.2 中相同的 UX 角色视图名称，以及 §6.4 中相同的可观测状态名称（本技能“可观测状态定义”表中的 Default / Loading / Disabled / Error / Empty / Success 术语为通用语言）。绝不能重命名或重新划分规范中已有的内容——这两份文档必须使用相同语言，否则可导航的中心就会失效。
• 深化，不偏离或矛盾。 规范保持技术无关；本设计规范是其配套文档，在规范意图之上补充视觉细节（布局、令牌、像素级细节）。将每个 §6.5 步骤和每个 §6.4 状态映射为具体的视觉处理，同时保留规范已有的 US-/OP-/BR- 逻辑 ID 交叉引用。
• 此耦合关系是下文所含的 SYNC:ui-intent-layer 契约——完整规则见该区块；此处不要重述。

仅在不存在主导 Feature Spec 时才可跳过（此时应根据源 PBI / 用户故事编写交互框架），并说明适用的是哪种情况。

1. 读取源输入并按类型路由

   检测到的输入	检测方式	操作
   Figma URL	文本中包含 figma.com/design 或 figma.com/file	启用 $figma-design 提取上下文，然后继续
   图片 / 截图	提示中附有图片文件	使用 visual analysis tooling 提取设计指南，然后继续
   手绘线框图	图片 + “wireframe”/“sketch” 关键词	运行 --mode=wireframe（内部模式——参见“模式：wireframe”部分）
   PBI / 用户故事文本	存在验收标准	从文本中提取 UI 需求，然后继续
   口头 / 文本需求	没有图片、URL 或 PBI	向用户澄清，然后继续

对于任何视觉输入：先提取设计上下文，再生成规范。

2. 确定规范复杂度

   IF 单个表单或简单组件 → Quick Spec（仅第 1–4 节）
   IF 完整页面或多组件视图 → Full Spec（全部 7 节）
   IF 多页面流程 → Full Spec + 流程图
   

3. 构建组件清单

   • 列出所需的所有 UI 组件
   • 区分可复用组件与特定功能的组件
   • 注明共享组件库或设计系统中的现有组件

4. 定义状态和交互

   • 默认、悬停、活动、禁用、错误、加载、空状态
   • 用户交互（点击、拖动、键盘快捷键）
   • 转场和动画

5. 提取设计令牌

   • 颜色、字体排版、间距、阴影、圆角
   • 尽可能引用现有设计系统令牌

6. 记录响应式行为

   • 移动设备（320-767px）、平板电脑（768-1023px）、桌面设备（1024px+）
   • 说明各断点的变化（布局、可见性、尺寸）
   • 小屏幕最低要求（明确写入规格）： 布局在移动设备上必须保持可用。优先采用重排（行 flex-wrap / row → column，网格收缩为单列）。对于确实无法重排的组件（数据表、画布、宽网格），请指定 min-width/min-height + overflow: auto 滚动作为可接受的后备方案——允许滚动。硬性要求是不能出现内容/控件损坏的情况（不得被裁切、截断或无法访问）。如果组件需要大幅重新设计才能适配移动设备，请标记出来交由用户处理，而不是自行假设要重写。

7. 保存产物 — 根据产物类型选择文件名格式：

   • 设计规格：team-artifacts/design-specs/{YYMMDD}-designspec-{feature-slug}.md
   • 无障碍审计：team-artifacts/design-specs/{YYMMDD}-ux-audit-{feature-slug}.md
   • 单组件文档：team-artifacts/design-specs/{YYMMDD}-ux-component-{component-name}.md

8. 链接回所属的 Feature Spec（如果存在）。 保存产物后，确保该规格文档仍是可导航的中心：打开 docs/specs/** 下所属的 Feature Spec，并将其 frontmatter 中的 design_spec: 键设为已保存的设计规格文件路径（如果缺少该键，则添加；如果路径已过时，则更新）。如果也生成了模型图（例如通过 $pbi-mockup），则以相同方式设置 mockup: 键。仅编辑 frontmatter——切勿改动第 1–8 节规格正文。这样可满足 artifact-review --type=design 链接回溯检查：如果存在设计规格，但其路径未记录在规格的 design_spec: frontmatter 中，检查就会失败。仅当不存在所属的 Feature Spec（设计规格为独立文档）时才跳过——并注明这一点。

角色上下文和产物路径（规范）

适用于写入 team-artifacts/design-specs/ 的内容。

• 当前角色： ui-ux-designer · 技能： design-spec
• 路径： team-artifacts/design-specs/ · 类型： designspec · 角色令牌： ux
• 模板： .claude/docs/team-artifacts/templates/design-spec-template.md
• 命名： {YYMMDD}-ux-{type}-{slug}.md（通用产物路径格式：{YYMMDD}-{role}-{type}-{slug}.md）
• 上下文： 设计规格——包含组件状态、设计令牌、无障碍要求。
• 质量检查清单： - [ ] 已记录所有状态 · - [ ] 已指定设计令牌 · - [ ] 已包含无障碍说明 · - [ ] 已定义响应式断点

模式：wireframe（图片 → 规格）

使用 --mode=wireframe 调用（或当输入为手绘线框图、数字线框图或 UI 草图时调用）。此模式是一个输入适配器：它会分析图片，然后进入常规规格章节（输出格式）以及 M1-M5/M7 合规检查。design-spec 是线框图转规格的规范负责人。

输入路由（线框图）

输入	检测方式	操作
手绘草图照片	图像中有粗略／自然的线条	使用线框图提示词进行分析（此模式）
数字线框图	图像中有清晰的线条／形状	使用线框图提示词进行分析（此模式）
线框图工具导出图像	来自 Excalidraw/Balsamiq/MockFlow 的图像	使用线框图提示词进行分析（此模式）
Figma URL	文本中包含 figma.com	改为路由至 $figma-design
应用截图	精致的 UI，包含真实数据	改为路由至 $design --mode=screenshot

线框图分析

使用 visual analysis tooling 和以下提示词：

提示词 1：布局提取 — “分析这张线框图图像。识别：(1) 页面布局区域（页眉、侧边栏、主体、页脚）；(2) 所有 UI 元素及其大致位置和类型（按钮、输入框、表格、卡片、下拉菜单、模态框、标签页）；(3) 内容层级（主要内容与次要内容）；(4) 交互元素；(5) 所有文本标签或注释；(6) 导航模式。”

提示词 2：组件识别 — “列出线框图中的所有不同 UI 组件。对每个组件：用描述性名称命名，按复杂度分类（基础＝单个元素，复合＝分组元素，区域＝页面区域），并说明其用途。”

线框图输出生成

图像分析后，按以下内容生成（遵循下方的 SYNC:ui-wireframe-protocol 块）：

1. ASCII 线框图 — 使用制表字符重现布局
2. 组件清单 — 按层级分类（通用／领域共享／页面）
3. 状态表 — 每个视图包含默认、加载中、空、错误状态
4. 组件分解树 — 详情级别需要时提供（完善／故事）
5. 响应式建议 — 根据布局复杂度给出

对所有基于线框图的文案应用 UI 规格的 M1-M5/M7 合规性关卡：组件名称采用业务层级，不引用代码属性，按逻辑 ID 映射到功能逻辑，状态转换可观察，可根据规格重建，主题内容对业务可见。

基于线框图的规格还必须遵守相同的 设计原则义务（见下文）：先编写状态表（第 3 项）中的空、加载中、错误状态（UI-1.5），并覆盖每个交互元素的全部 5 种交互状态（UI-5.2）；响应式建议（第 5 项）应依据内容发生变化的位置断点，而不是设备名称（UI-4.4）；如果草图未说明字体比例、间距单位或对比度（UI-2.5、UI-4.1、UI-3.1），应在 §4 中记录为 [UNVERIFIED — needs design-system mapping]，不要根据图纸测量值臆造一次性取值。

映射的业务操作

输出此表，将每个交互组件与其驱动的功能操作／规则关联起来（逻辑 ID 是主要依据；如果仅凭线框图无法确定，则标记为 [UNVERIFIED — needs feature-spec mapping]）：

交互组件	交互（可观察）	功能操作／规则（逻辑 ID）	备注
主按钮	点击 → 提交表单	OP-XX	触发创建／更新操作
筛选下拉菜单	选择 → 重新加载列表	OP-XX	驱动查询／搜索操作
行操作菜单	点击 → 确认对话框	BR-XX	受授权规则保护

线框图输出格式

• 格式 A：PBI 部分（默认） — 输出一个独立的 ## UI Layout 部分，与 PBI/故事模板兼容（由 $pbi-mockup 使用）。
• 格式 B：独立规范 — 输出到 team-artifacts/design-specs/{YYMMDD}-wireframe-spec-{slug}.md。

置信度与审查（线框图）

• 解读线框图时始终显示置信度（准确率为 70-80%）。
• 实施前始终建议进行人工审查。
• 如果置信度 <70%：直接向用户询问有关模糊元素的澄清问题。

输出格式

# Design Spec: {Feature Name}

**Source:** {PBI/story reference}
**Date:** {YYMMDD}
**Status:** Draft | Review | Approved

## 1. Overview

{1-2 sentence summary of what this UI does}

## 2. Component Inventory

| Component | Type     | Source           | Notes                       |
| --------- | -------- | ---------------- | --------------------------- |
| UserCard  | New      | Feature-specific | Displays user avatar + name |
| DataTable | Existing | shared library   | Reuse with custom columns   |

## 3. Layout

{Description or ASCII wireframe of layout structure}

- Desktop: {layout description}
- Tablet: {layout changes}
- Mobile: {layout changes}

## 4. Design Tokens

| Token      | Value          | Usage                 |
| ---------- | -------------- | --------------------- |
| $primary   | #1976D2        | Action buttons, links |
| $text-body | 14px/1.5 Inter | Body text             |
| $gap-md    | 16px           | Section spacing       |

## 5. States & Interactions

| Element  | Default    | Hover      | Active     | Disabled         | Error |
| -------- | ---------- | ---------- | ---------- | ---------------- | ----- |
| Save btn | Blue/white | Darken 10% | Scale 0.98 | Gray/50% opacity | --    |

## 6. Accessibility

- Keyboard navigation order
- ARIA labels for interactive elements
- Color contrast compliance notes

## 7. Open Questions

- {Any unresolved design decisions}

设计原则义务（按规范部分）

规范是 40 条 UI/UX 设计原则（UI-1.1–UI-9.4，下方的 SYNC:ui-ux-design-principles 区块）变为可继承内容的载体——下游实施者会按照规范所述内容构建，因此未写明的条款就不会被实现。本技能生成的每份规范都 MUST 在指定的输出格式部分中包含这些义务。项目设计系统文档的优先级高于这些条款；如有真实冲突，必须向用户说明双方的内容，绝 NEVER 默默做出取舍。

规范章节	该章节必须包含的条款要求
§1 概述	指明屏幕的唯一焦点（UI-1.1），并说明适用范围（Web／移动端／两者），以明确移动端条款（UI-8.1–UI-8.4）是必须遵守还是明确跳过。
§3 布局	按邻近关系和对齐边缘分组，绝不能按嵌套边框分组（UI-1.3、UI-1.4）；说明每个断点的依据应是内容何时无法正常工作，而不是设备名称（UI-4.4）。
§4 设计令牌	将字体尺寸比例声明为 6 个命名级别，不得使用一次性尺寸（UI-2.5）：正文 Web 端为 16px／移动端为 17px，且绝不能低于 14px（UI-2.2）；每行 45–75 个字符（UI-2.3）；正文行高为 1.5，展示文字行高为 1.1–1.2（UI-2.4）；最多 2 种字体 × 3 种字重（UI-2.1）。声明一个间距单位——以 4px 或 8px 为基准，所有间距均为其倍数（UI-4.1）；由容器通过 gap 属性控制间距（UI-4.2）；内边距应小于与下一组之间的间距（UI-4.3）。如果只列出临时值的令牌表，而未声明比例，则无法通过此项检查。
§4 设计令牌（颜色）	针对每一对令牌，说明对比度目标和实测值——文本为 4.5:1，UI 边缘为 3:1（UI-3.1），必须实际测量，绝不能凭肉眼估算。一个强调色只承担一种用途（UI-3.2）；深色模式应采用提亮表面颜色并柔化白色文本的方式，绝不能简单反转颜色（UI-3.4）。
§5 状态与交互	先编写空状态、加载状态和错误状态，再编写已填充状态（UI-1.5）。 列出每个交互元素的全部 5 种交互状态——默认、悬停、焦点、激活、禁用——并在适用时列出加载状态（UI-5.2，与下方的 7 状态组件状态检查清单保持一致）。即使结果需要更长时间，也须在 100ms 内响应（UI-5.1）；动效时长为 150–250ms，采用 ease-out，并遵循减少动态效果设置（UI-5.4）；优先提供撤销，而非确认；仅对不可逆操作要求确认（UI-5.3）。表单：标签始终可见，占位符仅作提示，绝不能充当标签（UI-7.2）；在失去焦点时进行验证，并在字段旁提供修正提示（UI-7.3）；发生错误、导航或刷新时，绝不能丢失已输入的数据（UI-7.5）。
§6 无障碍	焦点环必须保持可见——若与设计冲突，应重新设计其样式，绝不能移除（UI-5.5）；绝不能只用颜色传达含义（UI-3.3）；在任何移动端／触控界面上，点击目标尺寸须 ≥44×44pt，间距须为 8px（UI-8.1）；主要操作应位于屏幕下方三分之一处（UI-8.2）；手势绝不能成为唯一的操作方式（UI-8.3）；须考虑安全区域和屏幕键盘（UI-8.4）。
§7 未决问题	列出每一项有意偏离的条款，并注明授权该偏离的项目文档或用户决策——未记录的偏离属于规范缺陷，而非风格选择。
保持每项条款义务都以可观察的 UX 语言撰写，使其能通过下方的 M1-M5/M7 门槛——说明可见结果，绝不使用 CSS 属性或框架属性。

仅当该功能没有面向用户的界面时才跳过——必须明确说明原因，以便审计跳过是否合理，而不是将其误认为遗漏。

UI 规格的 M1-M5/M7 合规要求

有关阻断性标准，请参阅 .claude/skills/shared/sdd-artifact-contract.md → “AI-SDD Mandates (M1-M7)”。UI 规格在交接前 MUST 满足以下要求：

• M1 — 使用业务级组件名称。 根据 UX 角色为每个组件命名——主按钮、次按钮、模态对话框、数据表格、下拉菜单、Toast——绝不能使用框架组件类名或库导入名称。出现技术术语表述即判定为 FAIL。
• M2 — 正文中不得引用代码属性。 使用通俗的 UX 语言描述行为和外观。正文中绝不能引用组件状态属性、CSS 类名、框架指令或选择器。这些内容只能出现在 **Evidence**/[Source:] 载体、frontmatter 和 Mermaid 中。
• M3 — 使用逻辑 ID 交叉引用。 对于由功能逻辑驱动的每项行为，都要引用对应驱动操作或规则的逻辑 ID（OP-/BR-/FR-）——将 UI 行为关联回功能规格，而不是处理程序代码。任何 [Source: namespace/service/id] 抽象锚点都必须严格放在 Evidence 载体中——绝不能使用物理代码坐标或仓库根路径。
• M4 — 行为必须可测试且含义明确。 每种状态和交互都 MUST 只有一种有效解读，并具有可观察的完成标记。将含糊表述（“适当处理”“显示反馈”）改为具体、可观察的结果。
• M5 — 可依据规格重建。 即使读者对代码库一无所知，也 MUST 能够仅凭规格在 ANY 框架上重建此 UI。如果某个标记只有通过阅读源代码才能确定，则不满足 M5——应将其改写为可观察的视觉或文本内容。
• M7 — 业务可见性。 UI 规格属于业务树工件，因此要对每种情况的 BODY 应用演示测试：“利益相关者会看到什么变化？”——没有答案 → 判定为 FAIL，归类为仅技术内容。每个 Given 都必须是用户能够设置的状态；每个 When 都必须是用户能够执行的操作；每个 Then 都必须是用户能够看到的结果。若 When 是调用行为（处理程序运行、消费者收到消息、任务触发、数据同步），或 Then 断言架构、类型、可空性或调用次数，则判定为 FAIL。只评判 BODY，绝不评判标题或 ID。⚠️ 用户能够看到的 UI 状态属于业务内容，符合 M7——加载旋转图标、空状态占位内容、错误边框、禁用控件都属于可演示的结果，而非技术案例。只有调用形式或架构断言的案例才会失败。

M1 与 M7 并非同一道门槛。 M1 管控词汇；M7 管控主题内容。即使某个技术案例采用了无可挑剔的无技术术语表述，也只是满足 M1，同时违反 M7——“视图正确反映已同步的记录” 没有提及任何框架，符合 M1，但仍是披着业务外衣的技术案例。这正是业务规格最常见的腐化方式。要问用户能够看到什么，而不是用了哪些词。

可观察状态定义

每种状态都应根据用户可见的内容（颜色、图标、位置、文本）、业务含义，以及触发它的操作／规则来定义——绝不能依据 CSS 类或组件状态属性：

状态	可观察的视觉标记	业务含义	触发操作／规则（逻辑 ID）
默认	主填充色、启用状态的标签、无旋转加载图标	操作者可以执行此操作	OP-XX（进入状态）
加载中	旋转加载图标替代标签，控件不可交互	操作进行中，等待结果	OP-XX（已提交请求）
已禁用	柔和／灰色填充、标签变暗、无指针交互提示	未满足前置条件／操作者无权限	BR-XX（授权或防护规则）
错误	错误色边框、内联消息文本、警告图标	操作遭拒或验证失败	BR-XX（验证规则）
空状态	占位插图和引导文本，无数据行	当前视图中没有记录	OP-XX（查询返回零条结果）
成功	确认提示条／对勾，已更新的可见数据	操作已完成并持久化	OP-XX（操作成功）

组件状态检查清单

每个交互式组件都必须记录全部 7 种状态的可观察外观和业务含义——绝不能依据 CSS 类或框架属性（参见 M2）：

• 默认 — 静止状态的外观；操作者可以执行此操作
• 悬停 — 指针悬停时的交互提示变化（光标／阴影高度／颜色变化）
• 激活 — 交互过程中的按下／接合反馈
• 焦点 — 供无障碍访问（a11y）遍历的键盘焦点指示器（可见的环形／轮廓）
• 已禁用 — 柔和／不可交互；未满足前置条件或权限要求
• 错误 — 验证／操作失败，带内联消息和警告提示
• 加载中 — 进行中的指示器（旋转加载图标／骨架屏）；控件不可交互

无障碍审计（WCAG 2.1 AA）

对于无障碍审计交付物，请生成此检查清单报告，并将其保存为 {YYMMDD}-ux-audit-{feature-slug}.md：

## Accessibility Audit: {Feature}

**Date:** {Date}
**Auditor:** {Name}
**Standard:** WCAG 2.1 AA

### Criteria Checklist

#### Perceivable

- [ ] 1.1.1 Non-text Content: Alt text for images
- [ ] 1.3.1 Info and Relationships: Semantic HTML
- [ ] 1.3.2 Meaningful Sequence: Logical reading order
- [ ] 1.4.1 Use of Color: Not sole means of conveying info
- [ ] 1.4.3 Contrast (Minimum): 4.5:1 text, 3:1 large text
- [ ] 1.4.4 Resize Text: Readable at 200% zoom
- [ ] 1.4.11 Non-text Contrast: 3:1 for UI components

#### Operable

- [ ] 2.1.1 Keyboard: All functions keyboard accessible
- [ ] 2.1.2 No Keyboard Trap: Can navigate away
- [ ] 2.4.1 Bypass Blocks: Skip navigation available
- [ ] 2.4.3 Focus Order: Logical tab sequence
- [ ] 2.4.4 Link Purpose: Clear from link text
- [ ] 2.4.6 Headings and Labels: Descriptive
- [ ] 2.4.7 Focus Visible: Clear focus indicator

#### Understandable

- [ ] 3.1.1 Language of Page: lang attribute set
- [ ] 3.2.1 On Focus: No unexpected context change
- [ ] 3.2.2 On Input: No unexpected context change
- [ ] 3.3.1 Error Identification: Clear error messages
- [ ] 3.3.2 Labels or Instructions: Form labels present

#### Robust

- [ ] 4.1.1 Parsing: Valid HTML
- [ ] 4.1.2 Name, Role, Value: ARIA where needed

### Issues Found

| #   | Criterion | Issue | Severity | Recommendation |
| --- | --------- | ----- | -------- | -------------- |
| 1   |           |       | P1/P2/P3 |                |

### Audit Status: PASS / FAIL / CONDITIONAL

**Remediation Priority:**
{List items by severity}

示例

示例 1：简单表单规格

输入：“客户入门表单的设计规格”

**输出：**快速规格，包含第 1 至 4 节，涵盖表单字段（姓名、电子邮件、公司名称、套餐等级下拉菜单）、验证规则、提交／取消操作，以及移动端堆叠行为。

示例 2：复杂仪表板规格

输入：“带拖放列的订单流程仪表板设计规格”

**输出：**完整规格，涵盖看板布局、订单卡片（组件清单）、拖放交互、列状态（空、已填充、超出限制）、筛选栏、移动端响应式折叠为列表视图，以及键盘拖动操作的无障碍支持。

相关技能

技能	适用场景
figma-design	从 Figma 设计中提取规格
design --lane=marketing	构建营销／创意 UI
design --lane=product	构建产品 UI（仪表板、应用）
web-design-guidelines	审查现有 UI 是否符合规范

---

工作流建议

必须遵守的重要要求——绝无例外： 如果你当前尚未处于某个工作流中，必须先询问用户。不要判断任务是否简单，也不要自行决定“简单到可以跳过”——是否使用工作流由用户决定，而不是你：

1. 运行设计流程（推荐）——$design-spec → $design --lane=product（产品 UI）或 $design --lane=marketing（营销／创意）→ $workflow-review-changes
2. 直接执行 $design-spec——独立运行此技能

---

[IMPORTANT] 开始之前，使用任务跟踪将所有工作拆分为小任务——包括读取每个文件的任务。这样可以避免因长文件而丢失上下文。对于简单任务，AI 必须询问用户是否跳过。

[BLOCKING] 在设计或编写新屏幕／更新屏幕的规格之前，先了解现有 UI。 在制作任何线框图、模型图、屏幕设计或 UI 规格之前：

1. 盘点现有的相关 UI——在项目中搜索已用于此功能或其所属领域的屏幕、页面和组件（查阅设计系统文档及实际组件清单）。
2. 梳理关联流程——找出所有链接到、嵌入、包含新屏幕，或可导航至／离开新屏幕的功能；追踪其进入和退出流程，确保新屏幕与这些流程相契合。
3. 优先复用，而非另行设计——优先采用现有组件、模式和布局惯例；如需新增组件，应说明其相较现有组件的必要性。
4. 记录发现——在交付物中记录匹配的现有屏幕／组件及关联流程，让后续设计忠实遵循当前 UI 系统。

仅当该功能仅涉及后端（无 UI）时才可跳过——并明确说明这一点。

[BLOCKING] 在每份包含 UI 的规格中，纳入与技术无关的 UI／UX 意图层——读者无需了解任何技术，就必须能想象出该功能如何运作。 当功能包含用户界面时，规格必须包含交互界面部分，以便应用本身（而不只是其 API）能够在任何技术栈上重建：

1. 视图清单——按 UX 角色和用途列出每个视图／屏幕（例如“项目列表”“项目编辑器”“确认步骤”），并说明展示的信息。只描述角色，绝不要使用实现名称。
2. 导航图——说明用户如何在各视图之间移动：入口、转换和出口。追踪此界面与系统中相邻功能的连接方式。
3. 关键可观察 UI 状态——列出用户在各视图中能够感知到的不同状态（空、加载中、有内容、错误、成功、权限被拒绝等）；描述用户看到或感受到的状态，而非其呈现方式。
4. 每个故事的交互流程——针对每个用户故事，按步骤说明从意图到结果的点击／操作路径，并关联规格已有的逻辑 ID（US-／OP-／BR-）。
5. 关联配套设计交付物——将详细的视觉还原度（布局、设计令牌、像素细节）保留在规格之外，放在关联的 design-spec／模型图中。在规格的 frontmatter 中记录该配套交付物的路径，使规格仍是便于导航的中心。

M1-clean（不可妥协）： 正文中不得出现任何框架、路由／URL、CSS 或组件类名称——只能描述角色、信息、状态和流程。技术细节应放在配套设计交付物中，绝不能写在这里。

仅当该功能仅涉及后端（无 UI）时才可跳过——并在此部分明确说明原因。 AI 错误预防 — 每项任务都应避免的失误模式：

上下文变化后重新阅读文件。 上下文压缩、恢复或长时间运行的工作可能导致记忆过时；采取行动前先核实当前文件。 根据源证据核实生成的内容。 AI 会捏造 API、名称、主张和文档事实。记录或引用之前，先检查相关源文件。 删除或重命名之前检查下游引用。 移除某项内容可能导致文档、生成的镜像、配置和调用方引用失效；先梳理引用。 编辑后追踪完整的影响链。 修改定义可能遗漏派生输出和使用方。宣布完成前，沿着受影响链逐一检查。 核实所有受影响的输出，而不只是第一个。 一项检查通过不代表所有检查都通过；验证变更可能影响的每个输出界面。 假定现有值是有意设置的——更改或将其标记为缺陷之前先问清原因。 更改或报告常量、限制、标志、阈值、措辞或模式之前，先阅读相邻上下文和历史记录、调用方的排序方式，以及至少 2 个采用相同约定的同类调用点。文档说明了“是什么”却没说明“为什么”，这意味着缺少依据，而不能证明缺少防护。 先指出歧义再行动——不要默默自行选择。 存在多种合理解释时，必须明确提问，或说明假设及其风险。 断言系统负责的最终结果，而非基础设施负责的中间状态。 验证异步工作时，应断言最终业务状态，绝不能检查由共享基础设施维护的投递或重试记录，因为任何同时运行的进程都可能写入这些记录。这种检查单独运行时会通过，一旦有其他进程共享该基础设施，就会变得不稳定。 让共享指南与接收方角色相关。 通用指南必须对每个接收该指南的技能或 Agent 都有帮助；特定于代码的要求只应放在代码专用协议中。

UI 系统上下文 — 对于涉及 .ts、.html、.scss 或 .css 文件的任何任务：

实现前必须认真阅读：

1. docs/project-reference/frontend-patterns-reference.md — 组件基类、存储、表单
2. docs/project-reference/scss-styling-guide.md — BEM 方法、SCSS 变量、混入、响应式设计
3. docs/project-reference/design-system/README.md — 设计令牌、组件清单、图标

项目特定路径请参阅 docs/project-config.json。 UI/UX 设计原则（修订版 1.0 — 40 条，Web + 移动端） — 适用于任何设计、规划、实现或审查用户界面的任务的工作规则集。除非某条明确指定平台（§8 适用于移动端／触控），否则同时适用于两个平台。引用条款时使用 ID：UI-3.1、UI-8.2。

**优先级：**项目设计系统／SCSS／前端模式文档的优先级高于这些条款；这些条款的优先级高于一般审美偏好。出现实际冲突时，必须向用户说明双方依据，绝不能悄然自行裁决。——原因：项目自身记录的决策具有权威性；项目未明确规定时，这些条款作为默认依据。

1.0 视觉层级与布局

• UI-1.1 每个屏幕只有一个焦点。若两个元素都争夺首要注意力，就弱化其中一个。
• UI-1.2 信号顺序：尺寸 → 字重 → 颜色 → 位置。优先采用足以奏效的最简信号，再添加其他信号。
• UI-1.3 通过距离分组，绝不要依靠边框。留白能清晰地区分内容；框中套框则不能。
• UI-1.4 对齐到共同边缘。每个没有明确原因的缩进看起来都像是意外造成的。
• UI-1.5 首先设计空状态、加载状态和错误状态。完整状态最容易处理。

2.0 字体排版

• UI-2.1 最多使用 2 种字体系列，每种最多 3 种字重。更多变化看起来像是不一致，而非丰富。
• UI-2.2 正文在 Web 上为 16px，在移动端为 17px。任何用户必须阅读的内容都绝不能小于 14px。
• UI-2.3 行长为 45–75 个字符。限制行宽，而非容器宽度。
• UI-2.4 行高随字号增大而减小：正文为 1.5，展示文字为 1.1–1.2。
• UI-2.5 使用固定的字号比例尺——与工程团队共享 6 个命名级别。绝不使用一次性的字号。

3.0 颜色与对比度

• UI-3.1 对比度：文本为 4.5:1，UI 边缘为 3:1。使用工具测量——绝不要在明亮屏幕上凭肉眼判断。
• UI-3.2 一种强调色只承担一种用途。无处不在的强调色就无法突出任何内容。
• UI-3.3 颜色绝不能单独承载含义——应搭配图标、标签或位置。
• UI-3.4 深色模式不是反转后的浅色模式。提高表面亮度以体现层级；弱化纯白色文本。

4.0 间距与网格

• UI-4.1 使用一个间距单位并以其倍数递增——基础值为 4px 或 8px；所有间距都是它的倍数。
• UI-4.2 间距属于容器，而非子元素。使用 gap；仅在特殊情况下使用外边距。
• UI-4.3 内部紧凑，组间宽松——内部填充始终小于与下一组之间的间距。
• UI-4.4 断点应根据内容决定，而非设备。布局无法正常工作时就设置断点。

5.0 交互与反馈

• UI-5.1 每个操作都要在 100ms 内得到响应，即使结果需要更长时间才能完成。
• UI-5.2 指定全部 5 种状态——默认、悬停、焦点、激活、禁用——并在适用时添加加载状态。
• UI-5.3 优先提供撤销，而非确认。只有无法撤销的操作才要求确认。
• UI-5.4 动效应阐明因果关系：时长 150–250ms，使用 ease-out，并遵循减少动态效果设置。
• UI-5.5 保留可见的焦点环。若与设计冲突，可以调整样式，但绝不能移除。

6.0 导航与信息架构

• UI-6.1 每个屏幕都应回答：我在哪里、这里有什么、接下来去哪里。
• UI-6.2 顶层目的地最多 5 个。合理的层级结构胜过拥挤的首层导航。
• UI-6.3 使用用户的用词作为标签，而非内部术语。团队词汇不等于分类体系。
• UI-6.4 每种状态都应有对应的 URL 或返回路径。深层链接和硬件返回操作都必须能到达合理的位置。

7.0 表单与输入

• UI-7.1 尽量少问。每个字段都必须有当前存在的理由。
• UI-7.2 标签始终可见。占位符是提示，绝不是标签。
• UI-7.3 在失焦时验证，而非每次按键时验证。错误提示应紧邻字段，并说明如何修正。
• UI-7.4 根据数据类型匹配键盘——每个字段都应设置正确的输入类型、自动完成和自动大写选项。
• UI-7.5 绝不能丢失已输入的数据。发生错误、导航或刷新时都要保留输入。

8.0 移动端与触控 (移动端／触控界面)

• UI-8.1 点击目标至少为 44×44pt，彼此间距为 8px。点击目标可以大于可见图标。
• UI-8.2 主要操作应放在底部三分之一处——拇指通常位于此处。
• UI-8.3 手势是快捷方式，绝不能是唯一操作途径。任何可滑动的内容也必须可点击。
• UI-8.4 兼顾安全区域和键盘。刘海、主屏幕指示条和屏幕键盘都会占用空间。

9.0 速度与感知速度

• UI-9.1 先显示结构，再显示数据——布局已知时使用骨架屏；只有等待情况未知时才使用加载指示器。
• UI-9.2 乐观地假设操作成功。先更新 UI，再进行结果校验；失败时要明显回滚。
• UI-9.3 为所有加载内容预留空间。图片、广告和字体绝不能导致布局偏移。
• UI-9.4 针对慢速连接进行设计。离线、超时和重试都是状态，而非边缘情况。

按角色应用——这些条款构成同一套规则；根据任务采取的行动会有所不同：

角色	义务
设计／规划界面	条款决定交付内容：首先明确空状态／加载状态／错误状态（UI-1.5），列出全部 5 种状态（UI-5.2），声明字号比例尺和间距单位（UI-2.5、UI-4.1）
实现组件	完成前检查关卡：状态 · 令牌 · 对比度 · 焦点环 · 点击目标 · 预留空间（UI-5.2、UI-2.5／UI-4.1、UI-3.1、UI-5.5、UI-8.1、UI-9.3）
审查 UI 代码或设计稿	每条款都是判定失败的条件；每项问题都要注明 UI-<clause>、file:line 和严重性。绝不能逐项勾选检查——每个部分进行一次有重点的检查
扫描／记录 UI 系统	记录项目有意偏离这些条款之处，使起优先作用的文档成为有据可查的权威依据

仅当变更没有面向用户的界面（仅后端、工具或文档）时才可跳过——须明确说明，以便跳过行为可审计，而非看起来像遗漏。 UI 线框协议 — 从线框到实现的流程：（1）处理设计输入（通过视觉分析工具分析 Figma／截图／草图）。（2）使用制表框线字符创建 ASCII 线框。（3）构建组件清单并划分层级（通用／领域共享／页面）。（4）记录状态（默认／加载中／空／错误）。（5）映射到设计令牌。（6）定义响应式断点。创建新组件前，先搜索现有组件库。根据技能水平逐步增加细节（想法 = 草图；故事 = 完整树形结构 + 规范）。

批判性思维 — 运用批判性思维和序贯思维。每个论断都需要可追溯的证据，置信度 >80% 才能采取行动。 防止幻觉： 切勿将猜测说成事实——每个论断都要引用来源，坦诚承认不确定性，自查输出中的错误，独立交叉核验，并对自己的信心保持怀疑——没有证据的确信是所有幻觉的根源。

• 强制要求，重要，必须注意： 进行任何 UI 更改前，阅读 frontend-patterns-reference、scss-styling-guide、design-system/README。

• 必须注意： 对任何面向用户的界面应用 40 条 UI/UX 设计原则（UI-1.1–UI-9.4）：一个焦点、按邻近关系分组，优先设计空／加载中／错误状态（§1）· ≤2 种字体系列，网页正文 16px／移动端正文 17px，不得小于 14px，45–75ch，固定的 6 级比例（§2）· 实测文字对比度 4.5:1／边缘对比度 3:1，一个强调色，不能只靠颜色传达信息，深色模式 ≠ 反色（§3）· 使用统一的 4/8px 间距单位，gap 优先于外边距，内部间距更紧、区域间距更宽松，断点由内容决定（§4）· 响应时间 <100ms，覆盖全部 5 种状态，优先撤销而非确认，使用 150–250ms 的缓出动画并遵循减少动态效果设置，显示可见的焦点环（§5）· 用户知道身在何处／这里有什么／接下来去哪，顶层目的地 ≤5 个，使用用户熟悉的措辞，提供 URL 或返回路径（§6）· 减少字段，标签始终可见，在失焦时验证，键盘交互一致，绝不丢失输入（§7）· 可点击目标 ≥44×44pt，间距 8px，主要操作放在屏幕下三分之一区域，手势不能成为唯一操作方式，考虑安全区域（§8）· 先呈现结构，再加载数据，乐观更新时要显示回滚方式，预留空间，设计慢速连接状态（§9）。项目的 design-system 文档优先级高于这些条款——如有实质冲突，应交由用户决定，绝不默默自行处理。每项发现都要引用 UI-<clause> + file:line。仅当更改不涉及任何面向用户的界面时，才可跳过，并明确说明。

重要，必须注意： 遵循线框协议：ASCII 线框、带层级的组件清单、状态表、设计令牌、响应式断点。

• 强制要求： 对包含 UI 的规格说明，编写／维护与技术无关的交互界面层（视图清单 + 导航图 + 可观察的 UI 状态 + 每个故事中追溯至 US-/OP-/BR- 的流程）；将深入的视觉保真度放在 frontmatter 中记录的关联 design-spec／mockup 中；不得命名任何框架／路由／CSS／组件类。仅当功能完全属于后端时才可跳过，并须说明理由。

必须注意： 运用批判性思维和序贯思维——每个论断都需要适当且可追溯的证据（代码库／代码相关论断使用 file:line；研究、产品、内容和文档相关论断使用来源 URL 或产物章节）；置信度 >80% 才能采取行动，<60% 时不得提出建议。防止幻觉：切勿将猜测说成事实，坦诚承认不确定性，独立交叉核验，并对自己的信心保持怀疑。

必须注意： 采取措施防止 AI 出错——依据证据核验生成内容，删除或重命名前追溯下游引用，核验所有受影响的输出，丢失上下文后重新阅读文件，并在采取行动前指出歧义。

提示词增强收尾提醒

重要，务必注意：遵循此技能声明的步骤顺序；未经用户明确批准，绝不跳过、重新排序或合并步骤。 重要，务必注意：对于每个步骤／子技能调用：执行前设为 in_progress，执行后设为 completed。 重要，务必注意：每个跳过的步骤都必须附上明确理由；每个已完成的步骤都必须附上简洁的证据。 重要，务必注意：如果 Task 工具不可用，则维护一个状态同步的等效逐步计划跟踪器。

项目协议叠加规则 — 执行此技能前，先解析叠加在其上的任何项目级规则：将此技能名称与项目技能协议索引的 Target 列匹配（默认位于 docs/project-reference/skill-protocols-reference.md；docs/project-config.json 中的 referenceDocs 条目可覆盖此路径），且只采用最具体的匹配层级——精确名称 > glob > *。**此优先级只决定叠加规则彼此之间的顺序，绝不影响此技能自身规则的优先级。**只读取匹配条目对应的正文，正文路径解析为 <protocols-dir>/<Name>.md；行中的 Body 链接仅为显示文本，绝不是读取路径。匹配到的正文缺失或格式不正确时，必须报告并跳过——绝不能根据索引中的 Description 重建。没有索引或没有匹配项 -> 不使用叠加规则，静默继续。完整约定：.claude/skills/project-skill-protocol/references/registry.md。

叠加规则只能添加内容：它们只能在此技能自身协议之上增加规则，绝不能替换、覆盖、禁用或重新解释其中已有的规则——移除所有叠加规则后，此技能的行为必须与文档中描述的完全一致。叠加规则是简要补充，不是权限升级：绝不能豁免工作流关卡、Git 规范、审查关卡或用户确认关卡。若叠加规则与技能规则确实冲突，或两个同等具体的叠加规则直接矛盾，必须告知用户双方内容；绝不能静默裁定。

务必注意：执行前，必须为此技能解析项目协议叠加规则——只采用最具体的匹配层级（精确名称 > glob > *；该顺序只决定叠加规则彼此之间的优先级，绝不影响此技能自身规则的优先级），且只读取 <protocols-dir>/<Name>.md 中匹配的正文；正文缺失或格式不正确时必须报告，绝不能重建。叠加规则只能添加内容（绝不替换此技能自身规则），且只是简要补充，绝不是权限升级；同等具体的规则若彼此矛盾，必须交由用户处理。

收尾提醒

重要，务必注意目标：根据需求／PBI／用户故事／线框图，产出结构化、与技术栈无关的 UI/UX 设计规范，让开发者能在任何技术栈上重建 UI——记录每个组件、状态、设计令牌、响应式规则和无障碍需求，并关联到起支配作用的 Feature Spec。

重要，务必注意主要步骤（不要遗漏）：

• 首先执行步骤 0–0b — 清点现有相关 UI 并梳理关联流程（记录在 §1 中）；以起支配作用的 Feature Spec 的 §6 为依据，并原样复用其中的视图／状态词汇——原因：重复发明已有内容或重命名规范术语，会破坏可导航的信息枢纽。

• 步骤 1–2 — 根据输入类型选择处理方式（Figma → $figma-design，图像 → 视觉分析，线框图 → --mode=wireframe，PBI／文本 → 提取），然后确定复杂度为 Quick（§1–4）还是 Full（§1–7）。

• 步骤 3–6 — 编写组件清单（区分新增与现有组件）、完整记录 7 种状态及交互、设计令牌（复用设计系统）、响应式断点。

• 步骤 7–8 — 保存到 team-artifacts/design-specs/，然后将起支配作用的 Feature Spec 的 design_spec:／mockup: frontmatter 设置为保存的路径（仅修改 frontmatter）——原因：没有此操作，回链关卡将无法通过。

• M1–M5 关卡（阻断性） — 使用业务层级的组件名称，正文中不得引用代码属性，行为交叉引用使用逻辑 ID（OP-／BR-／FR-），每个状态仅提供一种可测试的解释，并确保仅凭规范即可重建——原因：泄露技术细节的规范无法在另一种技术栈上重建。 现行协议（本技能所携带的 SYNC/共享区块简明摘要）：

• **AI 错误预防：**根据证据核验生成的内容，追踪下游引用，核验所有受影响的输出，丢失上下文后重新阅读，并明确指出歧义。

• **UI 系统上下文：**进行任何 UI 更改前，先阅读 frontend-patterns、scss-styling、design-system。

• **UI 线框图：**ASCII 线框图、分层组件清单、状态表、设计令牌、响应式断点。

• **批判性思维：**每项主张都要提供可追溯的 file:line 证据；置信度 >80% 才能采取行动。

• 强制重要务必注意：开始前使用任务跟踪将工作拆分为小型待办任务

• 强制重要务必注意：编写新代码前，在代码库中搜索 3 个或更多相似模式

• 强制重要务必注意：每项主张都要引用 file:line 证据（置信度 >80% 才能采取行动）

• 强制重要务必注意：添加最终审查待办任务，以核验工作质量

• 强制重要务必注意：将 40 条 UI/UX 设计原则（UI-1.1–UI-9.4）纳入规范章节，确保实现者继承这些原则：§5 优先编写空白、加载和错误状态（UI-1.5），并列出每个交互元素的全部 5 种交互状态（UI-5.2）；§4 声明 6 级字体比例（UI-2.5）和唯一的 4/8px 间距单位（UI-4.1），而不是使用一次性数值；明确注明测量的对比度目标（文本 4.5:1／边缘 3:1，UI-3.1）；§6 保持焦点环可见（UI-5.5）、颜色绝不能作为唯一提示（UI-3.3），并确保触控界面上的目标区域 ≥44×44pt，主要操作位于屏幕下三分之一处（UI-8.1、UI-8.2）；§7 记录每一项有意偏离及其原因——规范离开本技能后，未写明的条款就等于未实现的条款

反合理化：

逃避说法	反驳
“我会跳过现有 UI 清单，直接设计”	步骤 0 是阻断项——先盘点现有屏幕／流程，否则规范就会与当前 UI 相矛盾。
“命名框架组件更清楚”	M1/M2 不通过——按 UX 角色命名；框架／CSS 名称只能出现在 Evidence／frontmatter／Mermaid 中。
“规范已经列出视图了——我会重新划分”	原样复用 §6 的视图和状态词汇；重命名会破坏规范↔设计枢纽的可导航性。
“文件已保存——完成了”	必须执行步骤 8 的回链；设置规范的 design_spec: frontmatter，否则 artifact-review 会失败。
“‘显示反馈’描述了错误状态”	M4 不通过——每种状态都需要一个可观察的完成标记，而不是含糊的说法。

[TASK-PLANNING] 开始前，分析任务范围，并使用任务跟踪系统地将任务拆分为小型待办任务和子任务。

[IMPORTANT] 开始前，分析任务规模并系统地将其拆分为多个小型待办任务——这非常重要。

无钩子提示词协议镜像（自动同步）

来源：.claude/.ck.json + .claude/skills/shared/sync-inline-versions.md（:full 区块）+ .claude/scripts/lib/hookless-prompt-protocol.cjs

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制要求，重要，必须执行，关键。任何情况下都不得跳过。

**通用可移植性边界：**可复用技能和协议文本应保持项目中立；从 docs/project-config.json 和 docs/project-reference/ 中了解项目特定约定。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。对于规范、测试用例、行为变更、公共契约或 docs/specs/ 相关工作，应通过文档索引中列出的本地规范文档进行：当规范／测试／代码必须保持同步时，使用 feature-spec-reference.md、spec-system-reference.md、spec-principles.md 和 workflow-spec-test-code-cycle-reference.md。如果任一文件或必需的参考文档缺失或过时，则在进行常规项目特定工作之前，自动运行 $project-init（或更精简的底层流程，例如 $project-config、$docs-init、$scan-all 或 $scan --target=<key>）。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. **检测：**如果提示以明确的斜杠技能／工作流命令开头，则直接执行。否则，根据工作流目录和技能列表匹配提示。
2. **分析：**选择最佳方案：直接执行、调用技能、启动标准工作流，或组合自定义步骤。
3. **自动选择：**自行选择最佳方案。不要让用户在直接执行、技能、标准工作流或自定义工作流之间做选择。
4. **启动：**对于选定的工作流，调用 $start-workflow <workflowId>；对于选定的技能，调用该技能；对于自定义工作流，直接按顺序执行自定义步骤；对于直接执行，继续处理任务。
5. **创建任务：**如果选定路径包含多个步骤，则在执行前为所有工作流／技能／自定义步骤创建任务跟踪。
6. **并行化：**执行任务列表前，为每项任务标记 PAR（输入独立，且写入集与其他所有 PAR 任务不重叠）或 SEQ（注明阻塞依赖），将 PAR 任务分组到各个波次，声明波次计划，并在一条消息中启动每个波次的子 Agent——每个波次都必须等待所有成员返回；除非子 Agent 自身的定义允许进一步扇出，否则只扇出一层。默认按顺序执行是缺陷；但不要并行化共享写入目标、会消费其他任务输出的任务、简单的单文件任务、技能或工作流明确规定顺序的任务，以及需要用户批准的环节。
7. **执行：**按照上下文指令中的 Workflow Step Advancement & Parallel Phases 规则推进——由模型驱动；子 Agent 完成与内联调用一样会推进步骤；并行阶段组必须等待所有成员返回（只有所有成员都返回后才能推进，绝不能串行执行）

共享 AI-SDD 协议标记

来源：.claude/skills/shared/sync-inline-versions.md

SYNC:ai-sdd-artifact-contract

AI-SDD 工件契约 — 共享的规范驱动开发规则应保持可移植，并由源文件管理。

1. 将可复用的 AI-SDD 原则保存在 .claude 中；将特定于仓库的路径、命令、负责人、产品和格式放在项目配置／参考文档中。
2. 保持以下周期：spec -> plan -> tasks -> implement -> verify -> update spec/docs。
3. 通过决策、任务、TC／测试、源证据以及文档／规范更新，追踪每项要求或不变量。
4. 将从代码提取规范的内容仅视为参考，直到规范的权威负责人接受为止。
5. 任何受支持的 AI 工具都可基于同步的上下文进行规划、实现、审查或验证；使用多个工具是可选的。
6. 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。— 原因：镜像是生成的工件；下次同步时，手动修改会被覆盖
7. 如果 docs/project-config.json、根目录指令文件或必需的项目参考文档缺失或过时，则在进行常规项目特定工作之前，自动运行 $project-init 或范围更窄的底层流程。

当前参考文档： 当前技能根目录中的 shared/sdd-artifact-contract.md。

---

SYNC:ai-sdd-artifact-contract:reminder

• MANDATORY 应用 shared/sdd-artifact-contract.md；将可复用的 AI-SDD 保存在 .claude 中，并将本地规则保存在项目文档中。
• MANDATORY 从代码提取的规范仅供参考，直到权威规范获批；任何受支持的 AI 工具都可基于同步的上下文执行工作。
• MANDATORY 先更新 .claude 源文件，再同步生成的镜像；不要手动编辑 .agents、.codex 或 AGENTS.md。
• MANDATORY 如果项目配置、根目录指令文件或必需的参考文档缺失或过时，则应自动通过 $project-init 或范围更窄的设置流程来处理项目特定工作。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；之后随着各步骤开始／完成，持续同步更新任务跟踪。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — MANDATORY。不得跳过。

开始前将工作拆分为小任务（任务跟踪）。添加最终任务：“分析 AI 错误与经验教训”。

提取经验教训——仅关注根本原因，而非修复表象：

1. 指明失败模式（推理／假设失误），而非表面症状——“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，则再向上抽象一层。
3. 写成通用规则——去除特定于项目的名称／路径／类。规则应适用于任何代码库。
4. 合并：多个错误若属于同一种失败模式，则合并为一条经验教训。
5. 复发门槛：“如果没有这条提醒，未来会话中是否会再次出现此问题？”——不会 → 跳过 $learn。
6. 自动修复门槛：“$code-review／$code-simplifier／$security-review／$lint 能否发现此问题？”——能 → 改进审查技能。
7. 两个门槛都通过 → 请用户运行 $learn。 [CRITICAL-THINKING-MINDSET] 运用批判性思维和序贯思维。每项断言都需要可追溯的证据；采取行动前，置信度须 >80%。 **反幻觉原则：**绝不将猜测当作事实——为每项断言引用来源，坦诚承认不确定性，自行检查输出错误，独立交叉核对，并对自己的信心保持怀疑——缺乏证据的确信是所有幻觉的根源。 **AI 注意力原则（首因－近因效应）：**在较长提示词／协议的开头和结尾都放置最关键的 3 条规则，以确保指令在较长的上下文窗口中仍能得到遵循。 **目标驱动执行：**先定义成功标准，持续循环直至验证完成；仅当可观察的检查均通过后才停止。 **测试验证意图：**测试必须保护业务规则／不变量，并在受保护的意图遭到破坏时失败，而不只是复现当前行为。

常见 AI 错误预防（系统经验）

• 上下文压缩后重新读取文件。 编辑前必须在同一上下文中先读取文件；上下文压缩会清除读取状态。编辑前重新读取。
• 批量替换后 grep 旧术语。 AI 过度相信查找/替换已覆盖所有内容。批量编辑后，对整个仓库执行 grep，检查文档/配置/目录中遗漏的引用。
• 删除前检查下游引用。 删除会连带导致文档/代码过时。移除前先梳理引用文件。
• 丢失记忆后，创建新内容前先检查现有状态。 上下文压缩会清除先前工作的记忆。查询当前状态以便继续——绝不要盲目重复创建。
• 根据实际代码验证 AI 生成的内容。 AI 会幻觉出 API、类名和方法签名。记录/引用前先用 grep 确认其确实存在。
• 编辑后追踪完整依赖链。 更改定义却漏掉下游使用方。追踪完整链路。
• 重命名时，对所有使用方文件类型执行 grep。 某些文件类型会静默忽略缺失的引用（不会产生编译错误）。搜索代码、模板、配置和生成文件。
• 验证正确性时追踪所有代码路径。 代码存在 ≠ 代码会执行。追踪提前退出、错误分支和条件跳过——不要只看正常路径。
• 源数据变更时，更新包含规范数据的文档。 内嵌派生数据（工作流、架构、配置）的文档会静默过时。源数据变更时，同时更新所有内嵌该数据的文档。
• 恢复上下文后验证子 Agent 的结果。 父 Agent 压缩上下文期间，后台 Agent 可能已经完成——用 grep 验证输出，不要相信对任务已完成的假设。
• 将完整目标列表与子 Agent 的分配任务交叉核对。 按类别并行分配子 Agent 会漏掉边界项。继续前，将各分配任务的并集与目标列表核对。
• 子 Agent 只能从其 Agent 的 .md 定义继承知识——使用自定义 Agent 类型，不要使用内置 Explore。 采用工具 = 权限 + 知识 + 执行（编号工作流步骤）。
• 逐步记录子 Agent 的发现，不要等最后一次性提交。 长时间运行的子 Agent 可能在最终写入前达到截断限制——导致发现丢失。指示其按章节追加到报告文件。
• 调试时，修复前先问“责任在谁？” 追踪调用方（数据错误）还是被调用方（处理错误）。在责任层修复——绝不要只修补症状出现的位置。
• 测试失败 → 先记录暂定结论，再追踪/编辑，然后调查。 使用完整的五类分类：SOURCE-WRONG（生产代码违背意图）、TEST-WRONG（断言/设置已过时）、TEST-NOT-OPTIMAL（测试有效但脆弱或信号弱）、ENVIRONMENT-BLOCKED（外部状态阻止得出结论），或 AMBIGUOUS（意图/证据不足以安全判断）。然后追踪根因，并对照规范依据（如果存在，查看 docs/specs/**）和源代码进行交叉验证。绝不要只为让测试变绿而削弱断言、添加跳过、放宽超时或更改源代码。
• 提取/重构后，对所有已移除名称执行 grep。 主文件“完成” ≠ 次要文件干净。宣布完成前，在整个范围内搜索每个已移除的符号。
• 假定现有值是有意设定的——更改或将其标记为缺陷前先问为什么。 仅凭模式匹配判定“错误”会忽略上下文。更改或报告任何常量/限制/标志/阈值前：阅读注释、git blame、调用方的执行顺序（使该值正确的保证通常位于引用行之前紧邻执行的代码中），以及同一惯例下至少 2 个同类调用点。只说明“是什么”却不说明“为什么”的文档，缺少的是依据，并不能证明缺少保护措施；在验证环节中，准确的 file:line 引用证明的是转录无误，而不是缺陷确实存在。
• 验证所有受影响的输出，而不只是第一个。 一个构建成功 ≠ 全部成功。涉及多个技术栈的变更（后端/前端/测试/文档）要求验证每一项输出。
• 复制相近模式前，先评估是否适用。 最接近的示例 ≠ 前提相同——确认新上下文具有相同的约束、基类、作用域和生命周期。
• 整体优先的调试方式——抵制注意力就近陷阱。 不要一头扎进第一个看似合理的原因。列出所有前提（配置、环境变量、路径、数据库、端点、凭据、版本、DI、数据）。用证据（grep/查询——而非推理）逐项验证。问“什么证据可以推翻这个假设？”——如果没有，那就不是假设。代价最高的失败：在“显而易见”的层继续深挖，而 Bug 实际位于从未质疑过的层。
• 精准修改——应用 diff 测试（结合上下文判断）。 两种模式：（1）Bug 修复 → 每一行都能追溯到该 Bug；不做样式调整；只清理因你的修改而变得未使用的孤立内容。（2）审查/增强 → 实施改进，并声明为“超出主要请求的增强：[内容]”。绝不要悄悄扩大范围。Diff 测试：“如果我没有被要求做 X，这一行还会存在吗？”——如果不会，就删除或明确说明。
• 编码前先指出歧义——不要默默自行选择。 存在多种有效解释时，逐一列出并说明工作量：“[请求] 可能指 (1) [N 小时]、(2) [N 小时]。哪一个更重要？”先列出范围/格式/数量/约束方面的假设。如果有更简单的方案，也要说明。绝不要默默自行选择。
• [MANDATORY FIRST ACTION] 回复前务必先启用合适的技能或工作流。 将任务与工作流目录和技能列表进行匹配；通过技能调用或 $start-workflow <workflowId> 启用。检查之前绝不要回答或编写代码。跳过 = 违反协议。
• Why-Review 对抗性思维——审查任何计划、决策或设计时都要运用。 默认持怀疑态度，而非验证者态度：充分论证被否决的替代方案，将每项既定理由反向审视（“它牺牲了什么？”），对最重要的 2-3 项假设进行压力测试，开展事前验尸（“已发布，3 个月后失败——什么会出问题？”），并指出作者遗漏的 1-2 种替代方案。章节齐全 ≠ 质量过关；质量取决于因果推理、具体缓解措施和证据，而不是“这样更好”或“密切关注”。
• 大型审查的子 Agent 提示词应优先安排报告写入。 处理许多文件的子 Agent 可能在最终写入前耗尽预算——导致发现丢失。设计提示词时应确保：（1）报告写入是第一个明确的交付项，（2）按文件/章节逐项追加（不要批量写入），（3）限定范围，避免读取耗尽预算。若输出在句中被截断且没有报告文件 → 启动范围更窄的任务，不要原样重试相同提示词。
• 上下文压缩后，继续前重新验证此前各阶段的所有结果。 摘要描述的是意图，不是环境状态（git 索引、文件系统、进程）。恢复时，首先审查：git status、重新读取修改过的文件、验证文件系统。每一项“已完成”的声明，在证据确认前都是未经验证的假设。
• OOM/内存：先检查行数，再检查行大小。 排查顺序：（1）无界查询——触发条件是否没有数据库筛选？将筛选推到数据库端；这可消除 OOM。（2）行是否很大？投影可按比例减少数据量。减少行数比投影的收益更大。
• 断言系统自身负责的结果，绝不要断言基础设施负责的中间状态。 测试任何异步行为（队列/代理传递、重试、后台任务、缓存、复制）时，应断言最终业务/实体状态。绝不要断言传递记录——消费/发送状态、尝试次数、最后错误、代理、调度程序或 outbox/inbox 表中的行存在与否或数量。这些记录属于共享基础设施，任何同时运行的进程（同伴 Worker、第二个副本、遗留的本地容器）都可能写入，且通常使用确定性的共享键；因此，断言会悄悄测试开发者的环境，而不是系统：单独运行时通过，一旦有其他进程共享该代理和数据库就会不稳定。每个断言都要问：“无论哪个进程执行了这项工作，该断言都会成立吗？”——如果不会，就改为断言已收敛的数据状态。推论：进程本地的故障注入和进程内遥测不能用于控制任何进程都可能执行的工作——将它们用作压力放大器（启用 → 限定时间窗口 → 停用 → 断言收敛），绝不要用作前置条件。
• 不要让领域概念进入通用/共享/基础设施层。 可复用层（共享库、框架、基础设施模块）不得引用任何特定使用方的领域概念——租户/客户/产品 ID、业务实体、功能规则。泄漏进来后，代码能够编译并运行，因此会悄无声息地通过审查，同时让“可复用”层与某个使用方耦合。保持共享类型与领域无关；通过子类/组合将领域字段/逻辑下放到使用方。——原因：与某个使用方的领域耦合的层不再可复用。