frontend-design

前端设计

指导创建独具特色、达到生产级品质的前端界面，避免千篇一律的 AI 风格。本技能涵盖完整生命周期：检测现有内容、规划设计、有目的地构建，并通过视觉方式进行验证。

权威层级

本技能中的每条规则都是默认建议，而非强制要求。

1. 现有设计系统／代码库模式——优先级最高，始终遵循
2. 用户的明确指示——优先于技能默认建议
3. 技能默认建议——适用于从零开始的项目，或用户要求设计指导时

在已有既定模式的代码库中工作时，应遵循这些模式。用户指定的方向若与默认建议冲突，应遵循用户的指示。

工作流

Detect context -> Plan the design -> Build -> Verify visually

---

第 0 层：上下文检测

开始任何设计工作前，先检查代码库中现有的设计线索。这将决定本技能中有多少主观设计指导适用。

要查找的内容

• 设计令牌／CSS 变量：--color-*、--spacing-*、--font-* 自定义属性、主题文件
• 组件库：shadcn/ui、Material UI、Chakra、Ant Design、Radix，或项目专用的组件目录
• CSS 框架：tailwind.config.*、styled-components 主题、Bootstrap 导入项、命名方式一致的 CSS modules
• 排版：HTML/CSS 中的字体导入、@font-face 声明、Google Fonts 链接
• 调色板：已定义的色阶、品牌颜色文件、设计令牌导出内容
• 动画库：Framer Motion、GSAP、anime.js、Motion One、Vue Transition 导入项
• 间距／布局模式：一致的间距比例用法、网格系统、布局组件

使用平台原生的文件搜索和内容搜索工具（例如 Claude Code 中的 Glob/Grep）扫描这些线索。日常文件探索不要使用 shell 命令。

模式分类

根据检测到的线索选择一种模式：

• 现有系统（多个类别中合计检测到 4 个及以上线索）：遵循现有系统。技能中的美学建议（排版、颜色、动效）让位于既定系统。结构指导（构图、文案、无障碍、验证）仍然适用。
• 部分系统（检测到 1–3 个线索）：遵循现有内容；仅在未检测到惯例的领域应用技能默认建议。例如，如果已配置 Tailwind，但没有组件库，就遵循 Tailwind 令牌，并应用技能对组件结构的指导。
• 从零开始（未检测到任何线索）：完整应用技能指导。
• 不明确（线索相互矛盾或不清晰）：继续之前先询问用户。

询问用户

当上下文不明确时，使用平台提供的阻塞式提问工具（Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user）。如果没有可用的提问工具，就假设为“部分系统”模式，并谨慎推进。

问题示例：“我发现了[检测到的线索]。你希望我遵循现有设计模式，还是创建独具特色的设计？”

---

第 1 层：构建前规划

编写代码前，先写三条简短说明。这些说明有助于保持整体连贯，也让用户能在代码编写前提出调整意见。

1. 视觉主张——用一句话描述氛围、质感和活力

   • 全新项目示例：“简洁的编辑风格，留白充足，衬线标题，柔和的大地色系”或“密集、数据导向的仪表板，点缀等宽字体，采用深色表面层次”
   • 现有代码库：描述现有美学风格，以及新工作将如何延续这种风格

2. 内容规划——页面上展示哪些内容，以及按什么顺序排列

   • 落地页：主视觉区、辅助内容、详情、行动号召
   • 应用：主要工作区、导航、次要上下文
   • 组件：包含哪些状态，传达什么信息

3. 交互规划——提出 2-3 个能改变整体感觉的具体动效

   • 不要只说“添加动画”，而要说“主视觉区加载时依次淡入、区块间滚动时产生视差、悬停卡片时放大”
   • 在现有代码库中，只描述要添加的交互，并使用现有的动效库

---

第 2 层：核心设计指导

这些原则适用于所有上下文类型。根据权威层级，它们应服从现有设计系统和用户指示。

字体

• 选择独特、有个性的字体。除非现有代码库已在使用，否则避免采用常见选择（Inter、Roboto、Arial、系统默认字体）。
• 最多使用两种字体，除非有明确理由需要更多。将展示字体／标题字体与正文字体搭配。
• 若在第 0 层检测到现有字体选择，则遵循现有选择。

色彩与主题

• 使用 CSS 变量构建统一的配色方案。与其采用犹豫不决、平均分布的配色，不如选用一种主色并搭配鲜明的强调色。
• 不要默认使用白底紫色，也不要默认采用深色模式。根据上下文灵活选择明暗主题。
• 默认使用一种强调色，除非产品已有多色系统。
• 若检测到现有颜色令牌，则遵循现有令牌。

构图

• 从构图入手，而不是组件。将首屏视口视作海报，而非文档。
• 优先运用留白、对齐、比例、裁切和对比，再添加装饰元素（边框、阴影、卡片）。
• 默认采用无卡片布局。只有当卡片用作用户交互的容器时（可点击条目、可拖动单元、可选择选项），才使用卡片。如果去掉卡片样式也不影响理解，就不该使用卡片。
• 所有构图规则均为默认规则，用户可以覆盖。

动效

• 对于视觉主导的工作，加入 2-3 个经过设计的动效：一个入场序列、一个与滚动关联或体现景深的效果，以及一个悬停／显现过渡。
• 如果项目已有动画库，请使用该库。
• 如果未找到现有动画库，请根据框架使用以下默认方案：
  • CSS 动画作为通用基础方案
  • React 项目使用 Framer Motion
  • Vue 项目使用 Vue Transition / Motion One
  • Svelte 项目使用 Svelte transitions
• 动效应在快速录屏中清晰可见，在移动设备上流畅运行，并在整个页面保持一致。如果动效纯属装饰，则移除。

无障碍

• 默认使用语义化 HTML：nav、main、section、article、button——不要所有内容都用 div。
• 颜色对比度至少达到 WCAG AA 标准。
• 所有交互元素都应有焦点状态。
• 做得好时，无障碍与美观并不冲突。

图像

• 需要图像时，优先选择真实或逼真的摄影图，而非抽象渐变或虚假的 3D 物体。
• 选择或生成适合叠加文字、色调稳定的图像。
• 如果环境提供图像生成工具，请用它们创建符合上下文的视觉素材，而不是使用占位库存图。

---

上下文模块

选择适合当前构建内容的模块。在现有应用中工作时，无论功能是什么，默认使用模块 C。

模块 A：落地页与营销页面（从零构建）

默认板块顺序：

1. 首屏主视觉 —— 品牌／产品、承诺、行动号召、一个主导视觉元素
2. 支持内容 —— 一个具体功能、优惠或证明
3. 详情 —— 氛围、工作流、产品深度或故事
4. 最终行动号召 —— 转化、开始、访问或联系

首屏主视觉规则（默认）：

• 采用单一构图，而非仪表板。使用全幅图像或主导视觉区域。
• 品牌优先，其次是标题、正文和行动号召。
• 文本栏保持窄幅，并放在图像中视觉平静的区域。
• 没有明确理由时，板块总数不超过 6 个。
• 只使用一个 H1 标题。首屏可见区域中只放置一个主要行动号召。

文案：

• 让标题承载核心含义。辅助文案通常只需一个简短句子。
• 使用产品语言，而非设计评论。界面中不要出现提示词语言或 AI 评论。
• 每个板块只承担一项任务：解释、证明、深入阐述或转化。
• 每句话都应有存在的价值。默认少写，而不是多写。

模块 B：应用与仪表板（从零构建）

默认模式：

• 层级清晰、氛围平和，采用醒目的字体排印和留白，颜色精简，信息密集但易读，界面装饰尽量少。
• 围绕以下内容组织：主要工作区、导航、次要上下文／检查器，以及一种用于操作或状态的清晰强调色。
• 仅当卡片本身就是交互元素时才使用卡片（可点击的项目、可拖动的单元、可选选项）。如果改成普通布局也不会丢失含义，就移除卡片样式。

文案（实用，而非营销）：

• 优先传达方向、状态和操作，而非承诺、氛围或品牌调性。
• 板块标题应说明该区域的内容或用户可在此执行的操作。好的示例：“计划状态”“搜索指标”。不好的示例：“释放你的潜能”。
• 如果某个句子可以出现在首页首屏主视觉中，就重写它，直到听起来像产品界面文案。
• 检验标准：如果操作人员只浏览标题、标签和数字，能否立即理解页面？

模块 C：组件与功能（现有应用中的默认做法）

为现有应用添加内容时：

• 匹配现有的视觉语言。此模块的目标是打造融入应用的内容，而非刻意突出。
• 沿用周边代码中的间距比例、边框圆角、颜色令牌和字体排印。
• 关注交互质量：状态清晰（默认、悬停、激活、禁用、加载、错误），状态之间过渡流畅，操作暗示明确。
• 新增一个组件不应引入一套新的设计系统。如果现有应用采用 4px 边框圆角，就不要添加圆角为 8px 的组件。

---

强制规则与反模式

默认避免（可覆盖）

这些规则体现了该技能的明确立场。用户可以覆盖其中任何一条。

• 初次展示就使用通用的 SaaS 卡片网格
• 紫色配白色的配色方案、偏向深色模式
• 从零构建时使用泛滥的字体（Inter、Roboto、Arial、Space Grotesk、系统默认字体）
• 首屏主视觉塞满统计数据、日程、胶囊标签组和 Logo 墙
• 用不同措辞重复表达同一种氛围的板块
• 没有叙事目的的轮播
• 多种相互竞争的强调色
• 用装饰性渐变或抽象背景代替真实视觉内容
• 听起来像设计评论的文案（“体验无缝集成”）
• 文本位于图像中繁杂一侧的分屏式首屏主视觉

始终避免（质量底线）

这些是真正的质量缺陷，任何用户都不会希望出现。

• 提示词语言或 AI 评论渗入界面
• 对比度不合格——文字叠在图像或背景上难以辨认
• 交互元素没有可见的焦点状态
• 明明有合适的 HTML 元素，却堆砌语义模糊的 div

试金石检查

在开始视觉验证前，快速自查。并非每种情境都适用所有检查项，请判断哪些相关。

• 品牌或产品在首屏是否一目了然？
• 是否有一个鲜明的视觉焦点？
• 只浏览标题就能理解页面吗？
• 每个版块是否各司其职？
• 使用卡片的地方是否确实需要卡片？
• 动效是在强化层次感或氛围，还是只是为了动而动？
• 如果去掉所有装饰性阴影，设计是否仍有高级感？
• 文案听起来像产品本身，而不是像提示词吗？
• 新作品是否与现有设计系统相符？（模块 C）

---

视觉验证

完成实现后，进行视觉验证。这只是基本检查，不是像素级审查。检查一遍即可。如果有明显问题，就修复；如果看起来不错，就继续。

工具优先级

使用第一个可用选项：

1. 项目现有的浏览器工具——如果 Playwright、Puppeteer、Cypress 或类似工具已在项目依赖中，请使用它。不要仅为验证而引入新依赖。
2. 浏览器 MCP 工具——如果 Agent 环境中有浏览器自动化工具（例如 claude-in-chrome），请使用它们。
3. agent-browser CLI——如果没有其他可用选项，这是默认选择。加载 agent-browser skill，查看安装和使用说明。
4. 人工检查——如果无法访问浏览器（无头 CI、没有安装权限），请按试金石检查进行自查，并注明已跳过视觉验证。

评估内容

• 输出是否符合构建前计划中的视觉理念？
• 是否存在明显的视觉问题（布局损坏、文本难以阅读、图片缺失）？
• 效果是否符合该场景的预期（落地页是否像落地页，仪表板是否像仪表板，组件是否与周围环境协调）？

范围控制

只迭代一轮。截取屏幕截图，按试金石检查进行评估，修复明显问题，然后继续。将截图附在交付内容中（PR 描述、对话输出等）。

如需超出单轮检查进行迭代优化（多轮截图、评估、修复），请参阅 compound-engineering:design:design-iterator Agent。

---

创意能量

此技能提供结构，但目标是打造独特的作品，避免 AI 垃圾，而非产出千篇一律的内容。

对于从零开始的项目，请坚定采用大胆的美学方向。考虑整体调性：极简主义、繁复主义、复古未来主义、有机／自然、奢华／精致、俏皮、编辑风、粗野主义、装饰艺术、柔和／粉彩、工业风，或者创造一种符合项目情境的风格。风格可以无穷无尽。可以从这些方向汲取灵感，但最终设计应真正契合项目。

思考一下：怎样才能令人难忘？人们会记住的那一个特点是什么？

让实现复杂度与美学构想相匹配。繁复主义设计需要复杂的代码、大量动画和特效；极简主义设计则需要克制、精准，并仔细关注间距、排版和细节。优雅来自出色地实现构想，而非一味追求强烈效果。