frontend-design · diff
git:20260910.4546a3c to git:20260923.8eb4b09
39 added, 43 removed. Audit A to A.
---
name: frontend-design
- description: 在用户要求新建、重设计、重排版或显著打磨网站、落地页、Web App、dashboard、editor、表单或前端组件，并需要形成可执行视觉方案或有真实交互和浏览器证据的可运行界面时使用。沿产品任务、真实内容、现有品牌、设计系统和代码约束完成设计与实现；产品方向或承诺未定交给 `shape`，只需非视觉代码修改交给 `dev`，完整验收交给 `test`，独立裁决交给 `review`。
+ description: 新建、重设计或明显打磨网站、落地页、Web App、dashboard、编辑器、表单或前端组件时使用，包括"把这个页面做好看点""重做一下这个界面""做个落地页"这类说法。先定一个明确的视觉方向，再实现可运行的界面，并在真实浏览器里检查桌面和移动端。只改和视觉无关的前端逻辑时不用。
---
# frontend-design
- 把本 Skill 当作可从任何工程阶段按需组合的前端设计 util。它提供视觉、交互与界面实现判断，不参与阶段链路，也不取得任务承诺、完整测试或独立裁决的责任。
-
- 开始前完整读取并应用 [`audience`](../audience/SKILL.md)。`audience` 负责目标受众、内容责任、理解路径与制作过程隔离；本 Skill 负责把这些判断落实为产品界面、视觉系统、交互行为和浏览器证据。若相邻 Skill 不存在，先如实报告安装缺口，不凭记忆重造一份规则。
-
- ## 让界面从产品任务长出来
-
- 当前任务有 `context.md` 时，先读取任务承诺和相关 Current Artifacts。随后锁定本轮真正要设计的表面、主要用户、首要任务、真实内容与数据、目标设备、交付形态和可见成功证据。不要从风格名、组件库或效果清单反推产品。
-
- 先读取用户提供的截图、原型、品牌、文案和素材。进入已有仓库时，打开实际 theme、tokens、共享组件、路由、页面和数据入口，提取准确值与既有交互；不要凭印象重建产品。已有信息架构、行为和视觉词汇默认属于当前契约，只有用户授权时才改变。
-
- 能够从代码、运行现场和资产查明的事实自行调查。只有会实质改变品牌身份、信息架构、关键流程、范围、成本或风险，且证据无法替用户决定的事项才集中询问；说明推荐答案和代价。问题数量由真实未知决定，小型视觉选择自行作出并保持一致。
-
- ## 先形成一个能执行的方向
+ 像一家小设计工作室的设计负责人那样工作。界面是产品里真实对象和数据的表达：先弄清有什么、谁在用，再决定怎么组织，然后定视觉，最后在浏览器里用真实数据确认它成立。顺序反过来，先挑好看的布局再往里塞内容，是大多数界面问题的来源。
- 在大面积编码前，用工作笔记、现有设计产物或一段简短说明固定本轮设计基准；不为形式新建报告。基准至少说清：
+ ## 1. 弄清对象、数据和用户
- - 产品要让用户感受到什么，以及明确不要成为什么；
- - 用户进入界面后最先理解、随后比较、最终执行什么；
- - 一个值得记住的视觉或交互特征；
- - 字体角色、色彩语气、信息密度、间距节奏、形状与层级；
- - 图像、图标和动效各自承担什么信息责任。
+ - **用户**：谁在用，在什么情况下用，进来要完成什么，用什么设备。
+ - **对象**：产品里有哪些对象，比如项目、实验、运行、配置，每个对象拥有哪些页面和操作。
+ - **数据**：真实的数据长什么样，会有 0 条、1 条、很多条，很长的名称，缺失的值，失败的记录。每个值从哪里来。
+ - **现状**：用户给的截图、原型、品牌素材和文案先读；有 `.agents/tasks/<任务>/shape.md` 时先读它。已有仓库里打开实际的 theme、tokens、共享组件和页面，取准确的值。已有的信息架构、交互和视觉语言默认保留，用户同意才改。
- 用户要求实现时，设计基准只是驱动代码的中间状态；把它落实到目标文件，不能用方向建议或实现计划代替交付。
+ 能查明的自己查。只有会改变品牌、信息架构、关键流程或范围的问题才问用户，并附上推荐。
- 用户明确要选项，或身份方向影响重大而证据不足时，给出两到三个真正不同的方向并推荐其一；差异应落在层级、布局、字体、色彩、密度或交互模型上，而不是只换装饰。其他情况直接承诺一个适合产品的方向，不混合多种情绪，也不把任何个人 house style 当成默认答案。
+ ## 2. 用结构表达真实关系
- 让领域约束影响表达：操作型工具优先扫描效率、状态清晰和任务密度；品牌、消费与编辑页面优先首屏信号、内容节奏和真实素材；已有产品先保持熟悉的导航与工作流，再支付视觉变化的成本。
+ 结构从对象和数据里推出来，不从模板里挑。
- ## 把方向压成最小可复用系统
+ - **导航跟着对象走**。页面放在它所属的对象下面：只属于某个实验的结果，从这个实验进入，不做成全局入口。功能清单不等于导航。
+ - **字段要有用处**。每个展示的字段都说得出谁用它做什么决定，说不出就不加。样例数据只能用来测布局，不能决定有哪些字段。来源不同的数值分开展示，缺失的值显示为缺失，不显示成 0。
+ - **载体按内容的变化来选**。先想数量变多、文字变长、字段增减之后它是否还成立：可比较的记录用表格，元数据用字段列表，连续内容用分区，汇总和明细用展开的层级；卡片只用于彼此独立、结构稳定的单元。不先定网格再补内容去填满。
+ - **分量按重要程度分配**。重要的给足空间，次要的退后；高度跟着内容走，内容多了在设定的最大高度内滚动；主操作任何时候都够得着，不被滚出视野。
- 现有设计系统优先。只补足当前表面真正缺少的 token、variant 和状态，不重命名一套已经足够的表达，也不为单页制造完整组件平台。没有系统时，从最小一致性开始；涉及共享主题、重复组件、深浅模式或复杂状态时，读取 [设计系统与状态](references/design-system.md)。
+ ## 3. 定一个视觉方向
- 重复的颜色、字体、间距、圆角、阴影和动效进入共享 token；重复结构或具有真实 variant、状态和组合规则的界面进入组件。差异成为有名字的 variant，不复制一份样式后任意漂移。组件需要覆盖当前流程实际可达的 default、hover、active、focus、disabled、loading、error 或 success 状态，而不是为清单制造不存在的状态。
+ 结构定了再定视觉。动手前在工作笔记里写下：
- ## 把内容边界落实到界面
+ - **调色板**：4 到 6 个具名的颜色值；
+ - **字体**：标题和正文，需要时再加说明或数据用字；
+ - **布局**：一句话，需要时画个 ASCII 草图；
+ - **记忆点**：最让人记住的一个元素，取材于产品本身的世界。
- 先按 `audience` 确定用户可见内容的责任与披露边界，再决定布局和样式。界面不是 Agent 的工作记录、设计说明、开发注释、验收报告或交接材料；只是在解释制作过程、标记交付缺口或方便验收的内容不能进入产品表面。
+ 写完对照需求检查：哪一部分换成任何类似页面都会得出同样的答案，就改掉它。AI 生成的设计常落在三种样子：米白底配高对比衬线标题和赤陶色点缀；近黑底配一个荧光绿或朱红点缀；报纸式的细线、零圆角和密集分栏。需求指定了就照做，没指定就别把自由度花在这几种上。
- 界面上的额外约束是：设计理由、技术注释、TODO、素材尺寸、验证证据、调试状态和面向开发者的操作指引放在代码注释、工作笔记或最终交付中；除非当前交付物明确就是 wireframe、spec 或开发工具，否则不能把这些内容渲染成产品功能，也不能为了填满版面补造指标、记录或名称。
+ 领域决定取向：操作型工具看重扫描效率、状态清晰和信息密度；品牌和内容页面看重首屏印象和真实素材；已有产品先保住熟悉的导航和流程。大胆只花在记忆点一处，其余保持安静；动效少而有目的，并提供 reduced-motion 的替代。用户要选项，或方向影响大而证据不足时，给两三个真正不同的方向并推荐一个。
- 产品契约确实需要且无法由交互本身表达的帮助、风险说明、空状态和操作提示可以进入界面，但只保留用户完成当前任务所必需的最短表达，并放在需要它的时刻和位置。不要用装饰性符号、emoji、箭头（→）、中点（·）或临时字符承担层级、动作或图标职责；需要图标时复用项目既有图标集，或使用光学尺寸和风格一致的专业图标库。
+ ## 4. 实现：组件负责一致，文字负责有用
- ## 实现真实可用的表面
+ **组件**。一种交互由一个完整的共享组件承担，它负责自己所有状态的外观：闭合、展开、选中、键盘焦点、禁用、加载、错误、窄屏。页面只负责位置、尺寸和间距。同一个外观有两处在画，就会出错，比如焦点被画成双层、三层描边；对齐靠共享的尺寸档位解决，不靠给单个元素调 margin。样式挂在具名的类或组件属性上，不用 `:nth-child` 这类位置选择器。已有设计系统优先，只补真正缺的 token、variant 和状态；要扩展共享主题、深浅模式或复杂状态时读 [design-system.md](references/design-system.md)。
- 先做能暴露结构错误的骨架，再投入细节抛光。遵循仓库现有框架、路由、状态、样式、图标、无障碍和依赖约定；新增依赖只有在它明显改善结果且当前授权允许时才成立。
+ **文字**。每一句都问：删掉它，用户会损失什么？
- - 保留用户给出的文案、数据、标签、操作和状态，补齐已授权功能所需的真实反馈。新增业务承诺或流程属于范围变化；视觉层级用布局与样式解决，不能编造看似真实的主张、记录、指标或名称。
- - 使用语义化、code-native 的导航、控件、表单、表格和文本。图片可以承载内容与品牌，但不能把截图伪装成应用界面；真实素材缺失且视觉资产确实承重时，再使用项目允许的素材来源或图像生成能力。
- - 让每个可操作元素都显得可操作，并在动作后给出真实状态。异步提交防止重复触发，校验错误靠近问题，成功、失败和当前选择可见。
- - 让响应式布局保持工作流和扫描价值。复杂表格、编辑器和 inspector 不自动堆成卡片；移动端可以滚动、折叠或重排，但不能丢掉完成任务所需的关系。
- - 用少量动效解释进入、选择和状态变化，不用动画遮掩层级问题、延迟任务或制造 layout shift；始终提供 reduced-motion 路径。
+ - 操作教程、读图说明、实现细节、重复的计数和对象名，删掉。
+ - 单位、错误、缺失提示和数据来源，保留。
+ - 有用但不影响当前操作的解释，放进默认折叠的帮助，或只在相关条件出现时显示。
+ - 按用户认得出的东西命名（"通知"，不是"webhook 配置"）；按钮写清点了会发生什么，同一个动作全程用同一个词；错误说清怎么解决，放在出错的位置。
+ - 演示开关、测试备注和开发说明不进界面；缺真实内容时在交付中说明，不编造。结构和动作用间距、分隔线和图标组件表达，不用中点、箭头字符拼凑。
- 非平凡或视觉主导的界面在最终浏览器循环前读取 [可见质量下限](references/quality-floor.md)，并只应用与真实表面相关的检查。
+ ## 5. 在浏览器里用真实数据验证
- ## 让浏览器反馈修正设计
+ 构建通过、测试全绿，只证明代码表达的逻辑成立，证明不了布局、焦点和信息架构。所以要在真实浏览器里看：
- 视觉验证服从当前任务与 `AGENTS.md` 的授权边界，build 通过不能代替视觉成立。在允许的范围内启动真实表面并记录 URL，至少检查一个目标桌面宽度和一个移动宽度；布局在断点附近发生结构变化时，再检查相邻宽度。亲自走过主要导航、筛选、表单、选择、播放或主 CTA，以及当前流程承重的 loading、error、empty、disabled 等状态。
+ - **数据**：至少一份完整记录、一份失败记录和一份超长内容。
+ - **宽度**：一个桌面宽度和约 375px 的移动宽度，断点附近布局变化时补看相邻宽度。
+ - **路径**：亲自走一遍主要操作，把改动涉及的组件逐一走过第 4 节列出的状态，包括用键盘进出弹出层。
+ - **视角**：以目标用户的身份看，最先注意到什么，哪里需要猜，主要动作能否一眼找到。
- 检查真实字体与素材是否加载、主动作能否在短时间内辨认、文字是否换行或裁切、层级与对齐是否稳定、移动端是否溢出、焦点和键盘路径是否可见、交互反馈和动效是否符合承诺。再以目标用户而非制作者的身份逐项审查可见内容：无法说明产品责任，只是在解释制作过程或弥补交付缺口的内容应移出界面。发现问题就回到代码继续修正；截图或 DOM 探针用于看见结果，不替代真实操作。
+ 判断时有三个前提：在动画结束后、在稳定的完整版本上看；写了样式就确认它真的生效，必要时查 computed style，旧规则可能以更高优先级覆盖它；接入新数据或新功能后，已经检查过的页面重新走一遍。非平凡或以视觉为主的界面，收尾前对照 [quality-floor.md](references/quality-floor.md)。
- 这个循环证明作者已经看见并校正了当前界面，不替 `test` 证明完整用户旅程，也不替 `review` 独立批准自己的设计。未获视觉验证授权或浏览器、数据不可用时，继续其余已授权工作，交付实际产物并具名说明未验证部分，不能宣称视觉成功。
+ 发现问题时，包括用户指出的问题，先问这里本来应该怎样组织，找到共享的根因修在那里，再检查这个组件所有用到的地方，而不是只修眼前的症状。
- 当主要任务与主动作清楚、视觉选择能够回到同一方向、重复表达由最小系统约束、核心交互有反馈、目标桌面和移动端没有明显缺陷，并且剩余限制已经具名时停止。交付实际结果、可打开路径或 URL、关键文件、运行过的检查、走过的交互和仍未证明的部分。
+ 这一步证明你看过并改过界面，不代替 `test` 的完整验收。浏览器、数据或输入法等条件不具备时照实说明。交付时给出可打开的路径或 URL、关键文件、检查过的数据、宽度和操作，以及仍未验证的部分。