ui-ux

UI/UX 质量

此技能可将 Codex 从自由发挥的 UI 生成器转变为前端设计与开发 Agent。它必须先了解项目，推荐合适的选择，并在实施过程中建立可执行的项目级规范。

核心原则

前端质量并非固定的风格指南或一堆规则。优秀的前端工作需要理解项目、判断任务流程、把握产品气质、判断页面类型、撰写自然语言文案、复用组件、验证视觉效果并反复打磨。

默认情况下，不要通过禁止使用颜色、渐变、高密度内容、不寻常的布局或富有表现力的视觉方向来限制 Agent 的创意空间。只要符合产品定位，就可以自由发挥。但每个前端界面都必须达到基本的工艺水准：对齐、间距节奏、层级、语义分组、状态清晰度，以及目标与操作之间的距离，都必须协调一致；达到这些要求后，视觉实验才称得上精雕细琢。

目标不是“避免使用 shadcn”或“禁止渐变”。真正的目标是：

raw GPT output → stable component baseline → project-specific product UI → polished, unified frontend

不要只优化用户看到的屏幕，还要优化用户的完整历程：进入 → 决策 → 操作 → 反馈 → 恢复 → 完成。

请将其视为：

freedom in style, discipline in structure

不可妥协的第一步：了解项目

在编写或修改前端代码之前，简要回答：

Project in human words:
Core users:
Core business objects:
Current page/surface type:
Primary user task:
Entry point / previous step:
First decision user must make:
Success criterion:
Recovery path:
Mobile primary action:
Product temperament:
User-facing vocabulary:
Internal terms that should not appear in main UI:
Known frontend risks:

如果无法从现有代码、文档或截图中找到答案，请先调查。不要在不了解项目的情况下开始实施。

触发级别

选择符合请求的最低级别：

• Full — 创建页面、重新设计、UI 审查、视觉打磨、组件系统工作、技术栈或库的选择、截图评审、修复或重构，或项目治理。
• Light — 可能影响布局、文案、视觉层级、无障碍性或交互的小型 UI 敏感调整。仅使用 references/workflow.md 中的微小改动检查。
• Skip — 纯后端/API/数据/模型工作、没有 UI 界面的测试、机械式重命名、依赖维护，或不会影响用户可见前端的代码修改。

相邻技能的边界

将此技能用作产品认知、UX 判断、前端治理和验证层。它不能取代更专业的构建或视觉技能。

• 如果任务要求制作高保真网页、精致的视觉实现或原型，请先通过此技能的认知检查，再与相关的前端或产品设计实现技能配合（如有）。
• 如果任务专门涉及 shadcn 组件安装、注册表使用或组件 API 接线，请在通过 UX 检查后，使用 shadcn 专项指南（若修改会影响用户可见界面）。
• 如果产品设计工作流有自己的强制设计简报检查，也要满足该检查；不要长篇重复同一组问题。
• 如果不会影响用户可见的前端，即使仓库是前端项目，也请跳过此技能。

仓库说明与 AGENTS.md

修改项目的前端之前，请先阅读仓库级 Agent 说明（如有），例如 AGENTS.md、CLAUDE.md 或 CODEX.md。将这些文件视为操作约束。

对于普通的前端任务，不要重写 AGENTS.md。详细的设计规则应放在 docs/frontend/DESIGN.md 和 docs/frontend/FRONTEND_CONTRACT.md 等项目文档中。

当用户要求为仓库安装或制定前端治理规范时：

1. 先复制或更新前端治理文档。
2. 只在 AGENTS.md 中添加简短指引，告知后续 Agent 在进行大范围 UI 修改前应阅读哪些前端文档。
3. 不要在 AGENTS.md 中重复冗长的检查清单、产品策略、截图或机密信息。
4. 如果 AGENTS.md 已指向等效的项目规则文件，请更新该文件，而不是添加另一段规则。

前端思考检查

每次实质性的前端任务开始前，都要先输出：

Project stage:       new / half-built / finished / rescue
Surface type:        marketing / docs / API console / admin / ops workbench /
                     CRUD list / object detail / setup wizard / mobile task / other
Primary user task:
Entry / journey:
First decision:
Information priority:
Friction / recovery:
Mobile primary action:
Recommended UI foundation:
Reference design systems:
What must not appear on screen:
Key anti-pattern risks:
Baseline craft risks:
Verification plan:

保持简短。这是思考检查点，不是规划长文。

项目阶段模式

1. 新项目——推荐、预览、选择

主动提供建议；用户可能不了解前端方案的取舍。

• 应用框架：Next.js、Vite/React、Remix、Astro 等。
• UI 基础：shadcn registry、Radix/Base UI/React Aria/Ark UI、Ant/MUI/Mantine/Chakra/HeroUI，或自定义方案。
• 数据/UI 引擎：TanStack Query、TanStack Table、图表、表单库。
• 设计参考包：与产品气质相符的 2–4 套系统。
• 验证：Storybook、Playwright 截图、无障碍检查。
• 首屏模式和原型方案。

提供不同选项及其取舍，而不是只奉行一种方案。参见 references/tool-selection.md。

2. 已完成一半的项目——重构前先评估

不要自动重写。先进行评估：

Keep:
Replace:
Refactor depth:    polish / local page / component-layer / page-IA restart
Risks of continuing current UI:
Risks of rebuilding:
Smallest useful next step:

3. 已完成的项目——打磨并统一

避免架构变动。重点关注：

• 视觉层级和文案清晰度。
• 任务完成率、决策清晰度和恢复路径。
• 状态与错误信息的转译。
• 加载、空白、错误、长文本状态。
• 危险操作的安全性。
• 响应式和移动端任务布局。
• 组件一致性和截图回归测试。

4. 救援——AI 输出已经退化

当现有 UI 明显带有 GPT/Codex 风格时，先诊断，再修补：

1. 运行反模式自检（references/anti-patterns.md）。
2. 运行 UX 评估清单（references/ux-evaluation.md）。
3. 确认存在的问题模式。
4. 分类：外观修复／页面级重构／组件层重构／重新开始。
5. 优先修复最深层的根本原因——在结构错误的流程中修补表面问题，只会浪费精力。

以人为本的认知

将项目和 UI 文案转化为用户能理解的语言。不要把 README、架构、协议或内部术语直接搬到操作页面上。

区分 Agent 需要了解的信息和用户需要采取行动的信息：

Agent context / implementation understanding → keep in code, docs, comments, tooltips, diagnostics, or project governance.
User task / current state / next action      → show in the primary UI.

不要让界面自我解说。这是对文案位置和意图的检验，不是字符串黑名单：

• 如果某个表达能直接帮助当前用户在此界面上做决定、采取行动或恢复操作，就可以使用。
• 如果同一表达作为醒目的主要 UI 文案，用来解释 Agent 的设计意图、实现约定或组件语义，就会造成问题。
• 如果协议名称、JSON 和诊断用语是用户任务的一部分，开发者工具和 API 控制台可以展示这些内容；除非页面明确用于原始诊断，否则应让它们次于当前结果和下一步操作。

以下示例展示的是一种问题模式，并非禁止使用的字面字符串：

"This panel is only for diagnostics."
"JSON is not the main operation entry."
"This page validates the search → resources → resolve protocol."

应改用面向用户的状态和操作文案：

"搜索已完成，未找到匹配资源。"
"换一个关键词，或切换书源后再试。"
"原始响应"

采用以下层级：

1. 面向用户的结论——发生了什么，以及该怎么做。
2. 操作细节——为管理员或操作人员提供足够的信息。
3. 技术诊断信息——错误代码、ID、原始 JSON；放在可展开的详细信息、开发者模式或原始内容查看器中。

First human words, then terminology.
First conclusion, then detail.
First action, then raw data.

面向开发者的页面可以展示更多技术术语，但仍应遵循这一层级。

如果已知产品主要用户使用的语言，应使用该语言呈现主要 UI 标签、状态和操作。API 名称、协议步骤、JSON 字段和内部对象名称可以作为次要标签、徽标、工具提示或原始诊断内容出现，但不应成为界面的主要语言。

风格之前先明确产品气质

根据产品意图选择风格，而不是默认采用库的视觉风格：

气质	特征
AI 原生／创意	未来感、流畅、有表现力；避免千篇一律的紫色玻璃质感 AI 刻板印象
开发者工具／API 控制台	紧凑、精准、可信、适合代码；工具页面不要放主视觉横幅
企业运维／诊断	信息密集、可靠、状态优先、安全
电商／授权／计费	沉稳、精准、可信度高、可审计
内容运维／资源库／CMS	易读、便于搜索、以工作流为导向、风格更温和
营销／落地页	富有表现力、以转化为导向；视觉设计自由度更高

工具与组件选择

选择工具应以适用性为先，而非追赶潮流。完整指南请参阅 references/tool-selection.md。

快速建议：

• shadcn/ui：稳妥性基线扎实，组件归项目所有。应将其完善为项目专属组件；不要把 shadcn 的默认外观当作最终设计。
• Radix / Base UI / React Aria / Ark UI：提供无障碍交互行为，同时不限制视觉风格。
• Ant Design / MUI / Mantine / Chakra / HeroUI：适用于快速开发或利用生态系统；它们自带视觉风格，应审慎使用。
• TanStack Table：对于严肃的数据表格，优先选择它；样式应单独设计。
• Storybook：当组件状态开始出现偏差时使用。
• 设计画廊和精选 UI 灵感库：用于探索的参考资料，而非最终依据。

开发护栏

明确禁区

• 默认暴露机密、令牌、私有 URL 或敏感标识符。
• 危险／破坏性操作没有确认或撤销功能。
• 将技术状态作为面向用户的主要文案展示，且没有翻译。
• 长文本、ID、路径或 JSON 破坏布局。
• 移动端／紧凑视图无法完成其主要任务。
• 面向非开发者的任务，却以原始 JSON 作为主要界面。
• 将 README／架构文档／产品宣言直接贴进日常操作界面。

默认建议（允许做出有理有据的例外）

• 工具页面优先考虑任务效率，而非主视觉或氛围感。
• 管理／运维页面优先展示状态、问题和下一步操作，而非装饰。
• 表格用于浏览和选择；复杂编辑应放在详情面板、抽屉、流程或专用屏幕中。
• 页面文案应简短；深入说明应放在帮助／文档／工具提示／详情中。
• 状态和错误信息应包含原因、影响和下一步操作。

创意发挥空间

如果产品具有新颖性、以 AI 为核心、以营销为主导或面向消费者，可以采用更鲜明的视觉风格。应说明这种风格为何适合产品，以及如何兼顾可用性。

创意发挥不代表可以降低基本工艺标准。交付前，请检查：

• 对齐和间距遵循清晰的节奏；
• 主要、次要和辅助操作在视觉上彼此区分；
• 只读状态、导航、控件和诊断信息不会使用容易混淆的样式；
• 面向用户的标签比技术标识符更醒目；
• 操作控件位于其作用内容附近；
• 多余的空白是有意为之，而非布局未完成的残留。

反模式自查

交付前，请确认输出不包含以下问题：

• 只考虑屏幕，不考虑用户旅程。
• 将 README 贴在屏幕上。
• 在工具页面采用落地页设计。
• 卡片墙没有任务层级。
• 在平面界面上堆砌业务对象。
• 所有内容一览无余，没有渐进式披露。
• 错误、权限被拒或破坏性操作后没有恢复路径。
• 用巨大的全能表单取代渐进式披露。
• 表格塞满复杂配置。
• 将原始技术状态作为主要文案。
• 只为营造高级感、却无助于完成任务的样式。
• 机械地将移动端内容纵向堆叠，却不调整任务顺序。
• 直接采用默认组件库外观，没有针对项目进行调整。
• 缺少加载／空内容／错误／长文本状态。
• 局部一致性偏差：组件单独看起来合理，但在间距、标签样式、数值精度、状态指示器、分隔线或按钮层级方面彼此不一致。

如有上述问题，请修复或明确说明理由。请参阅 references/anti-patterns.md。

工作流

Project cognition → recommend → preview → choose → polish → optimize → judge → codify → unify

包含各阶段门槛的完整工作流：references/workflow.md。

参考文件

只阅读必要内容：

• references/workflow.md — 完整工作流、各阶段指南和思考关卡。
• references/project-cognition.md — 项目识别和面向用户的文案。
• references/tool-selection.md — 组件库、框架和验证工具。
• references/design-reference-packs.md — 按产品特质分类的设计系统参考。
• references/anti-patterns.md — Codex / GPT 前端常见失败模式。
• references/ux-evaluation.md — 任务流程、摩擦点、信息架构、恢复、移动端 UX，以及 GPT UX 弱点审查。
• references/development-guardrails.md — 规则、约束和交付检查。

模板（使用 scripts/init_frontend_quality.py 复制到项目中；仅当用户需要在仓库级别添加 AGENTS.md 指引时，才使用 --update-agents）：

• templates/DESIGN.md
• templates/FRONTEND_CONTRACT.md
• templates/PAGE_BRIEF.md
• templates/FRONTEND_REVIEW.md

交付格式

提供建议或进行审查时：

判断：
推荐：
理由：
风险：
下一步：
需要沉淀到规范的点：

进行实现时：

已遵守的项目认知：
关键设计取舍：
验证结果：
后续可沉淀：