frontend-design git:20261001.490039eA

Immutable. This exact content never changes and is served at /api/v1/blob/3d3c723987bc8e76.

---
name: frontend-design
description: 新建、重设计或明显打磨网站、落地页、Web App、dashboard、编辑器、表单或前端组件时使用，包括"把这个页面做好看点""重做一下这个界面""做个落地页"这类说法。先定一个明确的视觉方向，再实现可运行的界面，并在真实浏览器里检查桌面和移动端。只改和视觉无关的前端逻辑时不用。
---

# frontend-design

像一家小设计工作室的设计负责人那样工作。界面是产品里真实对象和数据的表达：先弄清有什么、谁在用，再决定怎么组织，然后定视觉，最后在浏览器里用真实数据确认它成立。顺序反过来，先挑好看的布局再往里塞内容，是大多数界面问题的来源。

## 1. 弄清对象、数据和用户

- **用户**：谁在用，在什么情况下用，进来要完成什么，用什么设备。
- **对象**：产品里有哪些对象，比如项目、实验、运行、配置，每个对象拥有哪些页面和操作。
- **数据**：真实的数据长什么样，会有 0 条、1 条、很多条，很长的名称，缺失的值，失败的记录。每个值从哪里来。
- **现状**：用户给的截图、原型、品牌素材和文案先读；有 `.agents/tasks/<任务>/shape.md` 时先读它。已有仓库里打开实际的 theme、tokens、共享组件和页面，取准确的值。已有的信息架构、交互和视觉语言默认保留，用户同意才改。

能查明的自己查。只有会改变品牌、信息架构、关键流程或范围的问题才问用户，并附上推荐。

## 2. 用结构表达真实关系

结构从对象和数据里推出来，不从模板里挑。

- **导航跟着对象走**。页面放在它所属的对象下面：只属于某个实验的结果，从这个实验进入，不做成全局入口。功能清单不等于导航。
- **字段要有用处**。每个展示的字段都说得出谁用它做什么决定，说不出就不加。样例数据只能用来测布局，不能决定有哪些字段。来源不同的数值分开展示，缺失的值显示为缺失，不显示成 0。
- **载体按内容的变化来选**。先想数量变多、文字变长、字段增减之后它是否还成立：可比较的记录用表格，元数据用字段列表，连续内容用分区，汇总和明细用展开的层级；卡片只用于彼此独立、结构稳定的单元。不先定网格再补内容去填满。
- **分量按重要程度分配**。重要的给足空间，次要的退后；高度跟着内容走，内容多了在设定的最大高度内滚动；主操作任何时候都够得着，不被滚出视野。

## 3. 定一个视觉方向

结构定了再定视觉。动手前在工作笔记里写下：

- **调色板**：4 到 6 个具名的颜色值；
- **字体**：标题和正文，需要时再加说明或数据用字；
- **布局**：一句话，需要时画个 ASCII 草图；
- **记忆点**：最让人记住的一个元素，取材于产品本身的世界。

写完对照需求检查：哪一部分换成任何类似页面都会得出同样的答案，就改掉它。AI 生成的设计常落在三种样子：米白底配高对比衬线标题和赤陶色点缀；近黑底配一个荧光绿或朱红点缀；报纸式的细线、零圆角和密集分栏。需求指定了就照做，没指定就别把自由度花在这几种上。

领域决定取向：操作型工具看重扫描效率、状态清晰和信息密度；品牌和内容页面看重首屏印象和真实素材；已有产品先保住熟悉的导航和流程。大胆只花在记忆点一处，其余保持安静；动效少而有目的，并提供 reduced-motion 的替代。用户要选项，或方向影响大而证据不足时，给两三个真正不同的方向并推荐一个。

## 4. 实现：组件负责一致，文字负责有用

**组件**。界面上每个交互控件都是自己设计系统里的组件，不用浏览器原生控件的外观：下拉选择、数字输入、日期时间、复选框、单选、开关、滑块、文件选择、提示和确认框都一样。原生的弹层、步进按钮和系统对话框跟主题对不上，在不同浏览器和系统里还长得不一样，一眼就能看出是拼上去的。原生元素可以留在底层负责语义、表单提交和读屏，用户看到的外观、弹出层和状态都由组件自己画。一种交互由一个完整的共享组件承担，它负责自己所有状态的外观：闭合、展开、选中、键盘焦点、禁用、加载、错误、窄屏；弹出层在靠近视口边缘时换方向，不被容器裁掉。页面只负责位置、尺寸和间距。同一个外观有两处在画，就会出错，比如焦点被画成双层、三层描边；对齐靠共享的尺寸档位解决，不靠给单个元素调 margin。样式挂在具名的类或组件属性上，不用 `:nth-child` 这类位置选择器。已有设计系统优先，只补真正缺的 token、variant 和状态；要扩展共享主题、深浅模式或复杂状态时读 [design-system.md](references/design-system.md)。

**文字**。每一句都问：删掉它，用户会损失什么？

- 操作教程、读图说明、实现细节、重复的计数和对象名，删掉。
- 单位、错误、缺失提示和数据来源，保留。
- 有用但不影响当前操作的解释，放进默认折叠的帮助，或只在相关条件出现时显示。
- 按用户认得出的东西命名（"通知"，不是"webhook 配置"）；按钮写清点了会发生什么，同一个动作全程用同一个词；错误说清怎么解决，放在出错的位置。
- 演示开关、测试备注和开发说明不进界面；缺真实内容时在交付中说明，不编造。结构和动作用间距、分隔线和图标组件表达，不用中点、箭头字符拼凑。

不要在页面上写业务规则约束，不要写对于用户体验而言没有用的废话文案。页面只呈现能帮助用户完成当前任务、理解当前数据或决定下一步操作的信息；业务规则应通过控件限制、字段级校验、提交前确认和失败反馈体现，不得以常驻说明文字堆在页面、面板、表单或弹窗中。重复标题、重复按钮含义、实现细节、接口约束和对当前操作没有帮助的解释一律删除。

## 5. 在浏览器里用真实数据验证

构建通过、测试全绿，只证明代码表达的逻辑成立，证明不了布局、焦点和信息架构。所以要在真实浏览器里看：

- **数据**：至少一份完整记录、一份失败记录和一份超长内容。
- **宽度**：一个桌面宽度和约 375px 的移动宽度，断点附近布局变化时补看相邻宽度。
- **路径**：亲自走一遍主要操作，把改动涉及的组件逐一走过第 4 节列出的状态，包括用键盘进出弹出层。
- **视角**：以目标用户的身份看，最先注意到什么，哪里需要猜，主要动作能否一眼找到。

判断时有三个前提：在动画结束后、在稳定的完整版本上看；写了样式就确认它真的生效，必要时查 computed style，旧规则可能以更高优先级覆盖它；接入新数据或新功能后，已经检查过的页面重新走一遍。非平凡或以视觉为主的界面，收尾前对照 [quality-floor.md](references/quality-floor.md)。

发现问题时，包括用户指出的问题，先问这里本来应该怎样组织，找到共享的根因修在那里，再检查这个组件所有用到的地方，而不是只修眼前的症状。

这一步证明你看过并改过界面，不代替 `test` 的完整验收。浏览器、数据或输入法等条件不具备时照实说明。交付时给出可打开的路径或 URL、关键文件、检查过的数据、宽度和操作，以及仍未验证的部分。