frontend-design

前端设计

创建具有鲜明特色、可用于生产环境的前端界面，避免千篇一律的“AI 垃圾”风格。编写真正可用的代码，并有意识地做出美学选择。

适用场景

用户提出以下需求时，触发此技能：

• 构建 UI 组件、页面或完整的前端应用
• 设计或实现前端功能（导航、表单、数据表、仪表板）
• 重新设计现有界面，以提升美观度或易用性
• 将模型图、线框图或规格说明转化为可运行的代码

说明

1. 记录明确的需求：用户提出的任何风格偏好、配色方案、品牌套件或风格方向。如果没有，则使用默认风格指南。
2. 如果请求未说明用途和目标受众，请先询问，再编写代码。
3. 如果工作涉及现有代码库，请先了解其框架、CSS 变量和组件模式，再提出方案。
4. 提出美学方向（设计思考）。对于现有代码库，还要列出将创建或修改的文件。输出设计思考步骤报告。
5. 等待用户批准方向后再编写代码。如果用户要求修改，请重新提出方案。如果用户说“直接构建”，用一行说明方向并继续。如果用户结束本次运行但未批准，请以 BLOCKED 最终报告结束。
6. 阅读 references/aesthetics-guide.md 和 references/usability-guide.md 中的快速规则。运行编辑前仓库同步，然后实现代码。在每个不明显的设计决策处添加简短注释（字体搭配、配色映射、动效时长）。
7. 运行验证检查：
   • **响应式：**如果有浏览器工具，请分别在 375、768 和 1280 px 宽度下渲染，并检查是否出现水平溢出。否则，检查 CSS 中的断点，并记录响应式渲染未经测试。
   • **对比度：**计算每组文字与背景颜色的对比度。每组对比度至少为 4.5:1；对于字号不小于 24 px 的文字（粗体时不小于 18.66 px），至少为 3:1。
   • **质量与易用性：**检查默认质量标准清单和六条易用性快速规则。
   • **构建：**如果项目有构建、lint 或测试命令，请运行并记录退出结果。否则记录 build: not run (no command)。
8. 如果检查失败，请修复并重新运行该检查。第二轮修复后，停止修复，并在最终报告中列出所有剩余问题。
9. 输出实现步骤报告，然后输出最终报告。

编辑前仓库同步（必须执行）

在第 6 步首次写入文件之前运行一次。同步目标是写入代码的目录。

1. 运行 repo="$(git -C "<target dir>" rev-parse --show-toplevel)"。如果失败，跳过同步并记录 sync: skipped (not a git repo)。
2. 运行 git -C "$repo" remote get-url origin。如果失败，跳过第 3–7 步并记录 sync: skipped (no origin)。
3. 运行 branch="$(git -C "$repo" rev-parse --abbrev-ref HEAD)"。如果输出 HEAD，跳过第 4–7 步并记录 sync: skipped (detached HEAD)。
4. 运行 git -C "$repo" status --porcelain。如果输出为空，运行 git -C "$repo" fetch origin && git -C "$repo" pull --rebase origin "$branch"。
5. 如果输出不为空，运行 git -C "$repo" stash push -u -m "frontend-design pre-sync"，然后运行相同的 fetch 和 pull，最后运行 git -C "$repo" stash pop。
6. 如果在 rebase 开始前 fetch 或 pull 失败（网络、身份验证或远程分支缺失），不要重试。如果第 5 步执行了 stash，则运行 git -C "$repo" stash pop，记录 sync: failed (<first error line>)，然后继续。
7. 如果 rebase 出现冲突，运行 git -C "$repo" rebase --abort，然后在第 5 步执行了 stash 时运行 git -C "$repo" stash pop。如果 stash pop 出现冲突，请保留 stash。无论哪种情况，都不要写入任何文件；停止并询问用户如何继续。如果用户未回复，状态为 BLOCKED。

此技能不会提交任何内容。

设计思维

开始编写代码前，先确定当前生效的风格来源，并确立明确的美学方向：

• 简述优先级：如果有明确的简述，请遵循其中的要求。如果没有，以下默认风格指南即为准则：保留其中的四种核心颜色（仅文本状态颜色例外），并采用优雅、清晰、简洁、专业的语言；通过构图、字体、间距、层次和动效打造独特效果，而不是增加核心颜色。
• 目的：此界面要解决什么问题？谁会使用它？
• 基调：如果有明确的简述，请遵循其中的方向。如果没有，可从极简主义、极繁主义、复古未来主义、有机／自然、奢华／精致、活泼、编辑／杂志、粗野／原始、装饰艺术／几何、柔和／粉彩或工业／实用主义等方向中选择，但所选方向必须符合默认风格指南。
• 限制条件：技术要求（框架、性能、无障碍）。
• 差异化：说出人们会对这个界面留下的一个印象。

大胆的极繁主义与精致的极简主义，只要符合当前生效的风格来源，都能奏效；关键在于有意识地设计，而非追求强烈效果。

默认风格指南

用户没有提供明确简述时，请遵循本风格指南：

1. **色彩搭配（严格限制）：**仅使用四种核心颜色——黑色（#000000）、白色（#FFFFFF）、灰色（#6B7280）和亮绿色（#22C55E）。
2. **美学：**保持优雅、清晰、简洁、专业的设计语言。
3. **视觉层次：**使用卡片、线条、边框和细微阴影等元素营造视觉层次。
4. **亮绿色使用限制：**亮绿色仅可用于高亮（文本、边框或线条），绝不能用作背景色。
5. **系统状态颜色：**危险（#EF4444）、警告（#F59E0B）和信息（#3B82F6）颜色仅可用于文本元素，不可用于背景或主要 UI 组件。

明确的简述仅覆盖默认的色彩搭配和美学要求。无论如何，都不得覆盖无障碍要求或系统状态颜色仅用于文本的规则。

默认质量标准

每个最终设计都必须专业、可用于生产、优雅且精致，无论用户是否提出要求，也不受美学方向影响。简述决定风格；本标准决定完成度。精致感源于匠心与执行，而非 references/aesthetics-guide.md 中 避免 一节列出的陈词滥调。交付前请检查：

• 间距节奏与字体比例保持一致；边缘像素对齐
• 色彩搭配经过审慎设计；圆角、边框和阴影协调一致
• 所有交互状态均已考虑：悬停、焦点、激活、禁用，以及适用时的加载、空状态和错误状态
• 没有占位符、lorem ipsum、TODO 或损坏的资源；没有任何内容看起来像草稿
• 不包含 避免 一节中列出的任何默认做法，除非明确简述要求使用

可用性与美学参考

• **可用性：**每项设计都要遵循 references/usability-guide.md 中的六条快速规则；完整的逐步指南紧随其后。
• 美学：references/aesthetics-guide.md 包含字体、色彩、动效、构图和背景指南，以及 避免 清单。

请在第 6 步阅读这两份指南，不要提前阅读，以便在简述和审批环节减少上下文窗口占用。

预期输出

交付一个或多个文件，其中包含可用于生产环境的前端代码。着陆页请求示例：

• index.html — 完全自包含的 HTML，内嵌 CSS 和 JS（或在使用框架时拆分为单独文件）
• 实现的功能：主视觉区域、CTA 按钮、响应式导航栏和功能网格
• 字体排版：采用独具特色的展示字体与正文字体搭配（例如 Playfair Display + DM Sans），不要使用 Inter/Roboto
• 配色方案：严格使用 Default Style Guide 规定的四种颜色，或明确需求中指定的配色
• 交互：按钮使用纯 CSS 悬停状态，页面加载时使用交错显示动画
• 所有文本元素均符合 WCAG AA 对比度要求
• 已检查在 375px、768px 和 1280px 屏幕上的移动端响应式布局

最终报告

每次运行结束时（包括停止运行时），都以以下简洁文本块收尾。状态为 COMPLETE（代码已编写，所有检查均通过）、PARTIAL（代码已编写，但第二轮修复后仍有检查失败）或 BLOCKED（未编写代码）。等待用户答复的问题不会结束运行；如果用户未作答便结束运行，状态为 BLOCKED。填写规则、PARTIAL 和 BLOCKED 示例以及读者检查项，见 references/final-report.md。示例：

Result: COMPLETE. Wrote index.html (landing page: hero, CTA, nav, features grid).
Evidence: Contrast lowest 4.8:1 (Gray on White). Quality Bar and usability Quick rules passed. build: not run (no command). sync: skipped (not a git repo)
Uncertainty: Responsive rendering untested: no browser available; breakpoints at 375/768/1280 px inspected in CSS. Assumed a developer audience; the brief did not say.
Decision: No approval needed. Replace the placeholder logo with your own asset.

验收标准

运行需满足以下所有条件才算通过：

• 编写任何代码之前，用户已批准美学方向，或表示“直接构建”。
• 交付的代码在目标框架（HTML/CSS/JS、React、Vue 等）中运行无错误；存在构建命令时，该命令已成功运行。
• 在 375px、768px 和 1280px 屏幕上，布局均无水平溢出；否则，最终报告需注明尚未测试响应式渲染。
• 满足基本无障碍要求：使用语义化 HTML，所有文本组合均符合 WCAG AA 对比度要求，包含键盘焦点状态，并在适用时使用 alt/aria-label。
• 没有明确需求时，只使用 Default Style Guide 中的颜色，且绝不将 Bright Green 用作背景色。
• 所有 Default Quality Bar 条目和所有 usability Quick 规则均通过，否则最终报告需列出未通过项。
• 最终报告以 Result: 和状态开头，并包含 Evidence:、Uncertainty: 和 Decision: 行。Evidence: 仅引用已执行的检查。
• 最终报告通过 references/final-report.md 中的四项读者检查（结果易于查找、事实与假设分开、声明可追溯、下一步决策明确）。如果未得到人工审核者的答复，则无法确认其是否理解。

边缘情况

• 样式约束冲突（例如，用户说“极简”，同时又要求“大量动画”）：指出冲突并询问哪项约束优先；不要擅自选择。
• 要扩展现有代码库：绝不要在第 3 步读取到的设计系统旁再引入第二套设计系统。
• 框架不匹配（例如，用户要求“React”，但代码库使用 Vue）：生成代码前先确认框架；绝不要将 React JSX 输出到 Vue 项目中。
• 页面区块超过 5 个：建议分阶段交付——先完成核心布局，再处理次要区块——而不是一次性生成过大的产物。
• 无障碍要求与美学方向冲突：绝不要为了美观而降低 WCAG AA 对比度；应改用其他颜色组合。
• 部署环境无法访问互联网/CDN：如果用户说明环境离线或与外部网络隔离，请使用本地打包的资源或内联关键 CSS/JS，而不是 CDN 链接。

步骤完成报告

在第 4 步输出 Design Thinking 报告，在第 9 步输出 Implementation 报告，然后输出最终报告。模板、符号说明和各阶段检查项见 references/step-reports.md。请保持报告简洁，以节省 Agent 的上下文预算。