frontend-design

前端设计

阅读用户的前端需求：要构建的组件、页面、应用或界面。留意用途、受众或技术限制等背景信息。

工作规则

• 匹配现有设计系统；对于从零开始的项目，选择明确的视觉方向。
• 如果组件的数据或操作生命周期可能进入加载、空内容或错误状态，就要涵盖这些状态。为交互控件提供清晰可见的焦点状态和恰当的按压反馈。
• 保留可见的焦点状态和减少动态效果行为；验证窄屏和宽屏视口中的渲染效果。
• 将 Next.js 交互代码放在客户端边界，并将浏览器内容视为不可信数据。

上下文检测

实现给定的模型图、截图或设计稿时，即使仓库为空，也要使用 redesigning-existing.md 中的参考还原模式。跳过设计理念和交换测试；还原参考内容的视觉语言。

否则，先评估现有设计环境，再开始设计。统计项目中的设计信号：设计令牌/CSS 变量、组件库（shadcn、MUI、Ant）、CSS 框架配置（Tailwind、styled-components）、字体导入、配色系统、动画模式、间距比例。

• 4 个或更多信号 = 现有系统。与其保持一致。不要强加新的美学风格；在现有基础上扩展。
• 1–3 个信号 = 部分系统。融合现有选择，并用本技能指南补齐缺漏。
• 0 个信号 = 从零开始。应用下方的完整设计理念。产品定位：在进行定制设计前，阅读 design-system-routing.md。

如有疑问，在做决定前检查 package.json、tailwind.config.*、全局 CSS 文件和现有组件。Tailwind 实现规则（令牌、变体、v4 配置）请加载 ia-react-frontend 并阅读其 Tailwind 参考文档。

设计理念（先写，再编码）

对于不处于参考还原模式的完整页面、应用或多组件界面：在编写任何代码之前，先写一份 3 句话的设计理念。这有助于形成连贯的美学方向，避免产出千篇一律的内容。

1. 第 1 句，意图：这个界面应引发怎样的情绪反应？（不要说“简洁现代”，这是每个 AI 的默认答案。要具体，比如：“在信息密度与呼吸空间之间形成可控的张力”或“像一本装帧精良的书那样沉静自信。”）
2. 第 2 句，标志：哪一个视觉选择能让这个界面独树一帜？（字体、色彩关系、空间布局或动态效果。）
3. 第 3 句，约束：这个设计会刻意避免什么？（约束与选择同样塑造设计个性。）

在开始实现前，将设计理念写成注释或在对话中说明。设计理念为实现设定边界，但不规定具体做法：它是指南针，而不是蓝图。

对于小型组件或现有界面中的快速补充，跳过设计理念，并匹配周围的设计系统。

设计思维

明确理念后，就要落实到具体细节：

• 目的：这个界面解决什么问题？谁会使用它？
• 风格：选择一个极端方向：极简冷峻、混乱张扬、复古未来主义、有机自然、奢华精致、俏皮玩具感、编辑杂志风、粗野原始、装饰艺术／几何、柔和粉彩、工业实用主义等。可从这些方向汲取灵感，但设计必须忠于所选美学方向。
• 设计调性与模式（有别于创意工具箱中的文案调性，即 UI 文本的语气）：品牌型（设计本身就是产品；风格更大胆）或产品型（设计服务于任务；采用统一的组件体系，注重清晰度与信息密度）。模式：说服、操作、阅读（文档、文章）或体验（作品集、画廊）。
• 约束：技术要求（框架、性能、无障碍性）。
• 差异化：什么会让这个设计令人难忘？人们会记住哪一点？

选定清晰的概念方向，并精准地贯彻执行。大胆张扬与精致极简都可行；关键在于有意为之，而非追求强烈。

**验证关卡（针对全新页面和应用，且不处于参考还原模式时，在编写代码前执行）：**对拟定的设计令牌系统进行替换测试。把这套配色、字体组合和布局原样套用到一个毫不相关的需求上，是否会让人看不出问题？如果会，说明这只是默认方案，而非经过选择的设计：重新选择显得泛化的维度（为标志性色彩重新配色、更换字体、重构网格），然后再次测试，通过后再开始实现。独特性源自主题本身的世界（它的材料、工具、工件与行话），因此要让泛化的设计维度扎根于只有这个主题才会使用的元素。对于与现有系统匹配的小型组件，跳过此关卡（参见上下文检测）；此时的目标是与系统保持一致，而非追求独特性。

在导入任何第三方库（framer-motion、lucide-react、zustand 等）之前，先检查 package.json。如果缺少所需软件包，请在代码之前输出安装命令。切勿假设某个库已经存在。

然后，编写可运行的代码（HTML/CSS/JS、React、Vue 等），并确保代码：

• 达到生产级质量且功能完整
• 视觉效果鲜明、令人难忘
• 风格统一，具有清晰的美学主张
• 每个细节都经过精心打磨

验证

以下大多数项目只能在渲染后的视口中观察到，无法从差异中看出。如果有可用的渲染工具，不要仅凭源码检查就声称已完成视觉验证：请在一个窄视口和一个宽视口下截取屏幕截图或 DOM 快照，并测试每个已更改的交互和状态。如果环境无法渲染（CI、无头子代理、纯终端），请明确说明，并报告实际检查了哪些内容。完成情况的声明规范本身详见 ia-verification-before-completion。

• （对于参考保真模式以外的完整页面）先写设计理念，再编写代码
• 除供应的参考内容所要求的视觉选择外，不引入任何禁止的 AI 模式
• 导入任何新库之前先检查依赖
• 确认代码在浏览器中无错误地渲染
• 字体加载后，确认实际渲染的字体及其所需字重；检查浏览器中的渲染字体信息，而不只是声明的 font-family
• 不得使用没有替代焦点指示器的 outline: none
• 测量 CTA／表单文字以及必要的控件／焦点对比度，包括图像背景和状态变化；使用 aesthetics-and-interaction.md 中的阈值
• 测试可触达的加载、空白和错误状态；检查已更改控件的焦点和按压反馈。对于同步链接、切换控件或手风琴，将不适用的状态记录下来，不要凭空添加异步行为。
• 不得对 top／left／width／height 设置动画（仅使用 transform／opacity）
• 在 prefers-reduced-motion: reduce 下禁用非必要动效
• 颗粒／噪点滤镜只能用于固定的 pointer-events-none 图层
• 交互式／动画组件须隔离为叶级 'use client' 组件（Next.js App Router）
• 对于从零开始创建的页面／屏幕，在完成报告中列出虚构的品牌、文案、占位素材和模拟数据；为每项指出一个替换常量、令牌或模块，并确保重复使用的内容都关联到该项

参考资料

• 动效模式：弹簧参数、交错效果方案、悬停动画、滚动入场效果、性能规则
• 创意工具箱：导航、布局、卡片、字体排印和微交互模式
• 重设计现有界面：面向现有项目的先审计后升级工作流
• 重设计审计清单：涵盖字体排印、颜色、布局、交互性、内容和组件模式的 60 多项检查
• RSC／客户端组件边界：Next.js App Router 中关于服务端与客户端组件、连续动画和 Provider 隔离的规则
• 高级细节模式：<kbd> 按键显示、仿操作系统界面、主视觉图片渐隐、禁用的元标签、卡片组基线对齐、浏览器自动化安全边界
• 移动端折叠与性能防护规则：md: 以下采用单列布局、触控目标、移动端旋转、GPU 合成动画、z-index 规范
• 设计系统路由：从需求简介到组件系统的映射表，适用于从零开始的产品目录工作，须在拟定专属令牌之前使用
• SVG 装饰：实例 ID、主题继承、装饰性无障碍支持和响应式裁切
• 对于 WCAG 审计，请使用可用的无障碍审查能力，或在限定范围内直接执行检查。记录 WCAG 版本／等级、已测试页面、键盘操作和对比度证据，以及任何实际进行的屏幕阅读器测试。将无法使用浏览器或辅助技术进行的检查标记为未经验证；仅检查源码不足以证明符合标准。

特定任务参考

在实现或审查相应行为前，请先阅读相关参考文档：

• 关于排版、颜色、布局、动效、组件状态、移动端行为或视觉细节：aesthetics-and-interaction.md。

现有的专项参考文档（适用时）：

• banned-ai-patterns.md。