ui-ux-pro-max

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 Spec
• 集成测试实现／审查：integration-test-reference.md
• E2E 测试实现／审查：e2e-test-reference.md
• 代码审查／审计：code-review-rules.md 以及根据变更文件选择的领域文档

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

快速摘要

目标： 提供可搜索的 UI/UX 设计知识库——50 种风格、21 套配色、50 组字体搭配、20 种图表、8 种技术栈。

工作流：

1. 分析 — 从用户请求中提取产品类型、风格关键词、行业和技术栈
2. 搜索 — 使用 search.py 搜索各个领域：产品、风格、字体排版、颜色、落地页、图表、UX
3. 技术栈指南 — 获取特定技术栈的最佳实践（默认：html-tailwind）
4. 实施 — 将搜索结果综合为协调一致的设计和代码

关键规则：

• UI 图标不要使用表情符号（使用 SVG：Heroicons、Lucide、Simple Icons）
• 所有可点击元素都需要 cursor-pointer 和悬停反馈
• 浅色模式下，文本的最低对比度必须达到 4.5:1
• 每个异步界面都必须处理所有状态——加载期间显示加载指示器，失败时显示用户可见的错误（并提供重试），无数据时显示有意义的空状态。绝不能出现空白冻结、静默失败或空白列表。
• 默认支持响应式布局——布局在小屏设备上必须保持可用。首选：重新排列布局（行使用 flex-wrap，或从行布局改为列布局；网格收缩为单列）。如果布局确实无法重新排列（表格、画布、宽网格），可接受的备用方案是设置固定的 min-width/min-height，并使用 overflow: auto 滚动——滚动是允许的。最低要求：布局不能损坏——不能有被裁切、截断或无法访问的内容。如果支持小屏需要进行超出任务范围的大规模重构，请先与用户确认范围。
• 交付前，测试浅色/深色模式、所有 UI 状态（加载/错误/空）以及响应式断点（320/768/1024/1440）

预先阅读（项目设计系统）： 如果项目有设计系统，请从 docs/project-config.json 加载 designSystem.canonicalDoc 和 tokenFiles，并优先使用项目令牌/组件，而不是通用风格知识库。

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

UI/UX Pro Max - 设计知识库

可搜索的数据库，包含 UI 风格、配色方案、字体搭配、图表类型、产品建议、UX 指南和特定技术栈的最佳实践。

前提条件

检查是否已安装 Python：

python3 --version || python --version

如果未安装 Python，请根据用户的操作系统进行安装：

macOS：

brew install python3

Ubuntu/Debian：

sudo apt update && sudo apt install python3

Windows：

winget install Python.Python.3.12

---

如何使用此技能

当用户提出 UI/UX 相关请求（设计、构建、创建、实施、评审、修复、改进）时，请遵循以下工作流：

第 1 步：分析用户需求

从用户请求中提取关键信息：

• 产品类型：SaaS、电商、作品集、仪表板、落地页等
• 风格关键词：极简、活泼、专业、优雅、深色模式等
• 行业：医疗保健、金融科技、游戏、教育等
• 技术栈：React、Vue、Next.js，或默认使用 html-tailwind

第 2 步：搜索相关领域

多次使用 search.py，收集全面的信息。持续搜索，直到获取足够的上下文。

python .claude/skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]

推荐搜索顺序：

1. 产品 - 获取针对产品类型的风格建议
2. 风格 - 获取详细的风格指南（颜色、效果、框架）
3. 字体排版 - 获取包含 Google Fonts 导入方式的字体搭配
4. 颜色 - 获取配色方案（主色、辅助色、CTA、背景、文本、边框）
5. 落地页 - 获取页面结构（如果是落地页）
6. 图表 - 获取图表建议（如果是仪表板/数据分析）
7. UX - 获取最佳实践和反模式
8. 技术栈 - 获取特定技术栈的指南（默认：html-tailwind）

第 3 步：技术栈指南（默认：html-tailwind）

如果用户未指定技术栈，默认使用 html-tailwind。

python .claude/skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack html-tailwind

可用技术栈：html-tailwind、react、nextjs、vue、svelte、swiftui、react-native、flutter

---

搜索参考

可用领域

领域	用途	示例关键词
product	产品类型推荐	SaaS、电商、作品集、医疗保健、美容、服务
style	UI 样式、颜色、效果	玻璃拟态、极简主义、暗色模式、粗野主义
typography	字体搭配、Google Fonts	优雅、活泼、专业、现代
color	按产品类型划分的配色方案	SaaS、电商、医疗保健、美容、金融科技、服务
landing	页面结构、CTA 策略	首屏、以首屏为中心、客户评价、定价、社交证明
chart	图表类型、库推荐	趋势、对比、时间线、漏斗、饼图
ux	最佳实践、反模式	动画、无障碍、z-index、加载
prompt	AI 提示词、CSS 关键词	（样式名称）

可用技术栈

技术栈	重点
html-tailwind	Tailwind 实用类、响应式、无障碍（默认）
react	状态、钩子、性能、模式
nextjs	SSR、路由、图片、API 路由
vue	Composition API、Pinia、Vue Router
svelte	Runes、stores、SvelteKit
swiftui	视图、状态、导航、动画
react-native	组件、导航、列表
flutter	组件、状态、布局、主题

---

示例工作流

用户请求：“为专业护肤服务制作一个落地页”

AI 应：

# 1. Search product type
python .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --domain product

# 2. Search style (based on industry: beauty, elegant)
python .claude/skills/ui-ux-pro-max/scripts/search.py "elegant minimal soft" --domain style

# 3. Search typography
python .claude/skills/ui-ux-pro-max/scripts/search.py "elegant luxury" --domain typography

# 4. Search color palette
python .claude/skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness" --domain color

# 5. Search landing page structure
python .claude/skills/ui-ux-pro-max/scripts/search.py "hero-centric social-proof" --domain landing

# 6. Search UX guidelines
python .claude/skills/ui-ux-pro-max/scripts/search.py "animation" --domain ux
python .claude/skills/ui-ux-pro-max/scripts/search.py "accessibility" --domain ux

# 7. Search stack guidelines (default: html-tailwind)
python .claude/skills/ui-ux-pro-max/scripts/search.py "layout responsive" --stack html-tailwind

**然后：**综合所有搜索结果并实现设计。

---

提升效果的技巧

1. 关键词要具体——“医疗保健 SaaS 仪表板”>“应用”
2. 多次搜索——不同关键词会带来不同见解
3. 组合领域——样式 + 字体排版 + 颜色 = 完整设计系统
4. 始终检查 UX——搜索“动画”“z-index”“无障碍”，排查常见问题
5. 使用技术栈标记——获取针对具体实现的最佳实践
6. 反复迭代——如果首次搜索结果不匹配，请尝试不同的关键词

---

筛选约束（UI/UX 设计原则）

数据库提供建议；40 条 UI/UX 设计原则（UI-1.1–UI-9.4，下方的 SYNC:ui-ux-design-principles 区块）则限定你可以推荐的内容。搜索命中项只是候选内容，并非结论——在交给用户或 design 之前，请依据各项条款进行核验。项目设计系统文档的优先级高于条款和这些数据库；如果确实存在冲突，应交由用户处理，绝不能悄然自行解决。

精选输出	推荐前必须满足的条款约束
配色方案（--domain color，风格配色方案）	测量你提出的配色组合——文字与背景的对比度 ≥4.5:1，UI 边缘/边框 ≥3:1（UI-3.1）——并报告测量结果；绝不能只说“看起来不错”。只保留一个强调色，并让它只承担一种用途（UI-3.2）；绝不能仅靠颜色表达状态含义——还要配上图标或标签（UI-3.3）。深色变体应通过提高表面亮度来体现层级，并柔化纯白文字；它不是将浅色配色方案反转（UI-3.4）。
字体搭配（--domain typography）	最多使用 2 种字体 × 3 种字重（UI-2.1）——需要第三种字体的搭配就是过度设计。正文在 Web 上为 16px、在移动端为 17px，且易读内容绝不能小于 14px（UI-2.2）；将每行长度控制在 45–75 个字符（UI-2.3）；正文行高为 1.5，展示文字为 1.1–1.2（UI-2.4）。交付时应将字体搭配整理成包含 6 个层级且各有名称的字体比例，而非松散的字号列表（UI-2.5）。
风格 / 产品建议（--domain style、--domain product）	风格仍须允许每个屏幕只有一个视觉焦点（UI-1.1），并通过留白而非嵌套方框来分组（UI-1.3）。如果某种美学风格要求移除焦点环（UI-5.5）、用占位符隐藏标签（UI-7.2），或使用未遵循减少动态效果设置的 150–250ms 缓出动画（UI-5.4），则应拒绝或调整该风格。
间距 / 布局指南（--domain style、堆叠布局指南）	将间距表示为一个基准单位的倍数——以 4px 或 8px 为基准，每个间隔均为其倍数（UI-4.1）——由容器通过 gap 属性管理（UI-4.2）；组内间距小于组间间距（UI-4.3）；断点应依据内容，而非设备名称（UI-4.4）。
依据这些信息交付或构建的任何 UI	首先规定空状态、加载状态和错误状态，再规定已填充状态（UI-1.5），并预留空间，确保内容加载后布局不会偏移（UI-9.3）；为每个交互元素列出全部 5 种交互状态——默认、悬停、焦点、激活、禁用——适用时还要包括加载状态（UI-5.2）；在移动端/触控界面上，触控目标至少为 44×44pt，彼此间隔 8px（UI-8.1），主要操作应位于屏幕下三分之一处（UI-8.2）。

**如果精选建议无法满足某项条款，**请明确说明，并标注条款 ID，同时提供符合要求的替代方案——无法通过 UI-3.1 的精美配色是一个发现项，而不是可交付成果。

专业 UI 的常见规则

以下是一些经常被忽略、会让 UI 显得不专业的问题：

图标和视觉元素

规则	应该	不应该
不使用表情符号图标	使用 SVG 图标（Heroicons、Lucide、Simple Icons）	使用 🎨 🚀 ⚙️ 等表情符号作为 UI 图标
稳定的悬停状态	悬停时使用颜色/不透明度过渡	使用会导致布局偏移的缩放变换
正确的品牌徽标	从 Simple Icons 查找官方 SVG	猜测或使用错误的徽标路径
图标尺寸一致	使用固定的 viewBox（24x24）和 w-6 h-6	随意混用不同尺寸的图标

交互和光标

规则	应该	不应该
指针光标	为所有可点击/可悬停的卡片添加 cursor-pointer	让交互元素使用默认光标
悬停反馈	提供视觉反馈（颜色、阴影、边框）	不提示元素具有交互性
平滑过渡	使用 transition-colors duration-200	状态瞬间变化或过渡太慢（>500ms）

浅色/深色模式对比度

规则	应该	不应该
浅色模式玻璃卡片	使用 bg-white/80 或更高的不透明度	使用 bg-white/10（透明度过高）
浅色模式文字对比度	文字使用 #0F172A（slate-900）	正文使用 #94A3B8（slate-400）
浅色模式弱化文字	至少使用 #475569（slate-600）	使用 gray-400 或更浅的颜色
边框可见性	浅色模式下使用 border-gray-200	使用 border-white/10（不可见）

布局和间距

规则	应该	不应该
悬浮导航栏	添加 top-4 left-4 right-4 间距	将导航栏固定在 top-0 left-0 right-0
内容内边距	考虑固定导航栏的高度	让内容被固定元素遮挡
最大宽度一致	使用相同的 max-w-6xl 或 max-w-7xl	混用不同的容器宽度

异步 UI 状态与反馈（最容易遗漏的基本要求）

每个获取、提交或修改数据的屏幕或组件都必须呈现其所有状态——不能只呈现顺利完成时的状态。 界面在数据加载完成后看起来再完美，如果加载时显示冻结的空白页面、出错时悄无声息地失败，或无数据时什么都不显示，用户体验就是有问题的。规范状态词汇（与 design-spec 共用）：Default / Loading / Disabled / Error / Empty / Success。

状态	应做	不应做
Loading	请求进行期间显示加载指示器、骨架屏或进度条	留下冻结或空白的屏幕；在没有提示的情况下阻塞整个页面
Error	显示易于理解的消息，并提供重试或恢复操作	悄无声息地失败、吞掉错误，或直接输出原始堆栈跟踪 / JSON
Empty	显示有意义的空状态（插图 / 消息 + 可选的行动号召）	列表 / 表格没有条目时显示空白区域
In-flight / disabled	请求进行期间禁用提交 / 操作按钮（或显示其正在处理）	保持触发按钮可用，导致重复提交
Success	确认操作已完成（提示消息 / 行内提示 / 明显更新的数据）	完成数据修改后不向用户提供任何确认

响应式与多设备（在小屏幕上也易于使用）

规则	应做	不应做
行重排	小屏幕上使用 flex-wrap: wrap，或将 flex-direction: row 切换为 column	固定使用 flex-direction: row，导致内容在手机上溢出
网格折叠	多列网格在小屏幕上折叠为单列	固定列数 / 轨道宽度，始终不折叠
滚动回退可接受	无法重排（表格 / 画布 / 宽网格）？使用固定的 min-width/min-height + overflow: auto——允许滚动	内容被裁切或截断，或控件滚出屏幕且无法通过滚动访问
流式布局优于固定布局	使用 min/max-width、flex-grow、%/rem 尺寸	容器 / 卡片 / 对话框使用过大的固定 px 宽度
大规模重构 → 确认	小屏幕支持需要大幅重写布局 → 标记出来，并与用户确认范围	悄无声息地重写大段布局，或交付在小屏幕上无法正常使用的布局

---

交付前检查清单

交付 UI 代码前，请核对以下项目：

视觉质量

• 不使用表情符号作为图标（改用 SVG）
• 所有图标都来自一致的图标集（Heroicons/Lucide）
• 品牌标志正确（已通过 Simple Icons 核实）
• 悬停状态不会导致布局偏移

交互

• 所有可点击元素都设置了 cursor-pointer
• 悬停状态提供明确的视觉反馈
• 过渡效果流畅（150-300ms）
• 键盘导航时焦点状态清晰可见

状态与反馈（异步界面——逐项验证）

• 加载中 — 每次获取、提交或修改数据时，在请求进行期间都显示加载指示器或骨架屏（绝不能显示冻结的空白屏幕）
• 错误 — 每项可能失败的操作都显示易于理解的错误信息，并提供重试或恢复途径（不能静默失败，也不能显示原始堆栈跟踪）
• 空状态 — 每个列表、表格或集合视图都有明确的空状态（提示信息 + 可选的操作按钮），不能留白
• 请求进行中时禁用 — 请求执行期间，提交或操作按钮应处于禁用或忙碌状态（防止重复提交）
• 成功 — 修改操作完成后应提供确认反馈（提示消息、行内提示或更新后的数据）

浅色/深色模式

• 浅色模式下的文字对比度充足（最低 4.5:1）
• 玻璃质感或透明元素在浅色模式下清晰可见
• 两种模式下的边框均清晰可见
• 交付前测试两种模式

布局与响应式设计

• 浮动元素与边缘之间留有适当间距
• 固定导航栏不会遮挡内容
• 在 320px、768px、1024px 和 1440px 屏幕宽度下均能响应式适配
• 小屏幕下，行使用 flex-wrap 或从 row 切换为 column；多列网格收起为单列
• 在 320px 宽度下仍可正常使用——没有任何内容损坏（没有内容被裁切、截断或无法访问）；若布局确实无法重排，可接受使用 min-width/min-height + overflow: auto 滚动
• 任何需要大幅重构布局的小屏幕适配方案，都已告知用户并获得确认（不能擅自改写）

无障碍访问

• 所有图片均有替代文本
• 表单输入框均有标签
• 不能只通过颜色传递信息
• 遵循 prefers-reduced-motion 设置

相关内容

• design --lane=marketing — 营销/创意界面（落地页、营销活动）
• design --lane=product — 产品界面（仪表板、管理面板、SaaS 应用）
• shadcn-tailwind
• design-spec

---

[IMPORTANT] 开始前使用任务跟踪将所有工作拆分为小任务——包括为每个要读取的文件创建任务。这样可以避免因文件过长而丢失上下文。对于简单任务，AI 必须主动询问用户是否跳过。 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 系统	记录项目有意偏离这些条款之处，使起优先作用的文档成为有据可查的权威依据

仅当变更没有面向用户的界面（仅后端、工具或文档）时才可跳过——须明确说明，以便跳过行为可审计，而非看起来像遗漏。 AI 错误预防 — 每项任务都要避免以下失败模式：

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

批判性思维模式 — 运用批判性思维和顺序思维。每项主张都需要有可追溯的证据，采取行动的置信度必须高于 80%。 反幻觉： 绝不把猜测当作事实；每项主张都要引用来源；坦诚承认不确定性；自查输出错误；独立交叉核对；对自己的信心保持怀疑——缺乏证据的确定性是一切幻觉的根源。

务必注意：运用批判性和顺序思维——每项主张都需要有适当的可追溯证据（仓库／代码主张需提供 file:line；研究、产品、内容和文档主张需提供源 URL 或产物章节）；采取行动的置信度必须高于 80%，低于 60% 时不要提出建议。反幻觉：绝不把猜测当作事实；坦诚承认不确定性；独立交叉核对；对自己的信心保持怀疑。

务必注意：遵循 AI 错误预防原则——根据证据核实生成的内容；删除或重命名前追踪下游引用；核实所有受影响的输出；上下文丢失后重新读取文件；行动前指出歧义。

• 务必注意：将 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）。项目设计系统文档的优先级高于这些条款——如有真正冲突，应交由用户决定，绝不静默解决。每项发现均须引用 UI-<clause> 和 file:line。仅当变更不涉及面向用户的界面时才可跳过，并须明确说明。

项目协议叠加规则 — 执行此技能前，先解析项目中叠加在此技能之上的协议规则：将此技能名称与项目技能协议索引的 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 中匹配规则的正文；正文缺失或格式错误时须报告，绝不可重建。叠加规则仅可补充（绝不取代此技能自身的规则），且属于简报，绝非权力升级；具体程度相同的规则如有矛盾，须交由用户决定。

收尾提醒

**重要，务必注意目标：**提供可搜索的 UI/UX 设计智能——50 种风格、21 套配色、50 种字体搭配、20 种图表、8 种技术栈——综合生成无障碍、专业且对比度合规的界面。

现行协议（本技能所包含 SYNC/共享区块的简明摘要）：

• **防止 AI 出错：**依据证据核验生成的内容，追踪下游引用，核验所有受影响的输出，在上下文丢失后重新阅读，并明确指出歧义。
• **批判性思维：**每项声明都要提供可追溯的 file:line 证据，置信度 >80% 才能采取行动，绝不猜测。

**重要，务必注意：**开始前，使用任务跟踪将工作拆分为小型待办任务 **重要，务必注意：**创建新代码前，在代码库中搜索 3 个或更多相似模式 **重要，务必注意：**每项声明都要引用 file:line 证据（置信度 >80% 才能采取行动） **重要，务必注意：**添加最终审核待办任务，以核验工作质量 **重要，务必注意：**40 条 UI/UX 设计原则（UI-1.1–UI-9.4）会约束策选工作——策选的配色仍须满足文本对比度 4.5:1 / 边缘对比度 3:1（UI-3.1），使用一个强调色（UI-3.2），且颜色不得作为唯一的区分方式（UI-3.3）；策选的字体搭配仍须满足最多 2 种字体系列 × 3 种字重（UI-2.1），网页端字号为 16px / 移动端为 17px，绝不低于 14px（UI-2.2），并提供 6 级字体比例（UI-2.5）；间距统一使用一个 4/8px 单位的倍数（UI-4.1）；任何基于此构建的内容都必须优先明确空状态/加载状态/错误状态（UI-1.5）和全部 5 种交互状态（UI-5.2）——不符合任一条款的搜索结果属于发现项，而非交付物

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

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

来源：.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、业务实体、功能规则。泄漏进来后，代码能够编译并运行，因此会悄无声息地通过审查，同时让“可复用”层与某个使用方耦合。保持共享类型与领域无关；通过子类/组合将领域字段/逻辑下放到使用方。——原因：与某个使用方的领域耦合的层不再可复用。