frontend-design git:20260910.4546a3cA

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

---
name: frontend-design
description: 在用户要求新建、重设计、重排版或显著打磨网站、落地页、Web App、dashboard、editor、表单或前端组件，并需要形成可执行视觉方案或有真实交互和浏览器证据的可运行界面时使用。沿产品任务、真实内容、现有品牌、设计系统和代码约束完成设计与实现；产品方向或承诺未定交给 `shape`，只需非视觉代码修改交给 `dev`，完整验收交给 `test`，独立裁决交给 `review`。
---

# frontend-design

把本 Skill 当作可从任何工程阶段按需组合的前端设计 util。它提供视觉、交互与界面实现判断，不参与阶段链路，也不取得任务承诺、完整测试或独立裁决的责任。

开始前完整读取并应用 [`audience`](../audience/SKILL.md)。`audience` 负责目标受众、内容责任、理解路径与制作过程隔离；本 Skill 负责把这些判断落实为产品界面、视觉系统、交互行为和浏览器证据。若相邻 Skill 不存在，先如实报告安装缺口，不凭记忆重造一份规则。

## 让界面从产品任务长出来

当前任务有 `context.md` 时，先读取任务承诺和相关 Current Artifacts。随后锁定本轮真正要设计的表面、主要用户、首要任务、真实内容与数据、目标设备、交付形态和可见成功证据。不要从风格名、组件库或效果清单反推产品。

先读取用户提供的截图、原型、品牌、文案和素材。进入已有仓库时，打开实际 theme、tokens、共享组件、路由、页面和数据入口，提取准确值与既有交互；不要凭印象重建产品。已有信息架构、行为和视觉词汇默认属于当前契约，只有用户授权时才改变。

能够从代码、运行现场和资产查明的事实自行调查。只有会实质改变品牌身份、信息架构、关键流程、范围、成本或风险，且证据无法替用户决定的事项才集中询问；说明推荐答案和代价。问题数量由真实未知决定，小型视觉选择自行作出并保持一致。

## 先形成一个能执行的方向

在大面积编码前，用工作笔记、现有设计产物或一段简短说明固定本轮设计基准；不为形式新建报告。基准至少说清：

- 产品要让用户感受到什么，以及明确不要成为什么；
- 用户进入界面后最先理解、随后比较、最终执行什么；
- 一个值得记住的视觉或交互特征；
- 字体角色、色彩语气、信息密度、间距节奏、形状与层级；
- 图像、图标和动效各自承担什么信息责任。

用户要求实现时，设计基准只是驱动代码的中间状态；把它落实到目标文件，不能用方向建议或实现计划代替交付。

用户明确要选项，或身份方向影响重大而证据不足时，给出两到三个真正不同的方向并推荐其一；差异应落在层级、布局、字体、色彩、密度或交互模型上，而不是只换装饰。其他情况直接承诺一个适合产品的方向，不混合多种情绪，也不把任何个人 house style 当成默认答案。

让领域约束影响表达：操作型工具优先扫描效率、状态清晰和任务密度；品牌、消费与编辑页面优先首屏信号、内容节奏和真实素材；已有产品先保持熟悉的导航与工作流，再支付视觉变化的成本。

## 把方向压成最小可复用系统

现有设计系统优先。只补足当前表面真正缺少的 token、variant 和状态，不重命名一套已经足够的表达，也不为单页制造完整组件平台。没有系统时，从最小一致性开始；涉及共享主题、重复组件、深浅模式或复杂状态时，读取 [设计系统与状态](references/design-system.md)。

重复的颜色、字体、间距、圆角、阴影和动效进入共享 token；重复结构或具有真实 variant、状态和组合规则的界面进入组件。差异成为有名字的 variant，不复制一份样式后任意漂移。组件需要覆盖当前流程实际可达的 default、hover、active、focus、disabled、loading、error 或 success 状态，而不是为清单制造不存在的状态。

## 把内容边界落实到界面

先按 `audience` 确定用户可见内容的责任与披露边界，再决定布局和样式。界面不是 Agent 的工作记录、设计说明、开发注释、验收报告或交接材料；只是在解释制作过程、标记交付缺口或方便验收的内容不能进入产品表面。

界面上的额外约束是：设计理由、技术注释、TODO、素材尺寸、验证证据、调试状态和面向开发者的操作指引放在代码注释、工作笔记或最终交付中；除非当前交付物明确就是 wireframe、spec 或开发工具，否则不能把这些内容渲染成产品功能，也不能为了填满版面补造指标、记录或名称。

产品契约确实需要且无法由交互本身表达的帮助、风险说明、空状态和操作提示可以进入界面，但只保留用户完成当前任务所必需的最短表达，并放在需要它的时刻和位置。不要用装饰性符号、emoji、箭头（→）、中点（·）或临时字符承担层级、动作或图标职责；需要图标时复用项目既有图标集，或使用光学尺寸和风格一致的专业图标库。

## 实现真实可用的表面

先做能暴露结构错误的骨架，再投入细节抛光。遵循仓库现有框架、路由、状态、样式、图标、无障碍和依赖约定；新增依赖只有在它明显改善结果且当前授权允许时才成立。

- 保留用户给出的文案、数据、标签、操作和状态，补齐已授权功能所需的真实反馈。新增业务承诺或流程属于范围变化；视觉层级用布局与样式解决，不能编造看似真实的主张、记录、指标或名称。
- 使用语义化、code-native 的导航、控件、表单、表格和文本。图片可以承载内容与品牌，但不能把截图伪装成应用界面；真实素材缺失且视觉资产确实承重时，再使用项目允许的素材来源或图像生成能力。
- 让每个可操作元素都显得可操作，并在动作后给出真实状态。异步提交防止重复触发，校验错误靠近问题，成功、失败和当前选择可见。
- 让响应式布局保持工作流和扫描价值。复杂表格、编辑器和 inspector 不自动堆成卡片；移动端可以滚动、折叠或重排，但不能丢掉完成任务所需的关系。
- 用少量动效解释进入、选择和状态变化，不用动画遮掩层级问题、延迟任务或制造 layout shift；始终提供 reduced-motion 路径。

非平凡或视觉主导的界面在最终浏览器循环前读取 [可见质量下限](references/quality-floor.md)，并只应用与真实表面相关的检查。

## 让浏览器反馈修正设计

视觉验证服从当前任务与 `AGENTS.md` 的授权边界，build 通过不能代替视觉成立。在允许的范围内启动真实表面并记录 URL，至少检查一个目标桌面宽度和一个移动宽度；布局在断点附近发生结构变化时，再检查相邻宽度。亲自走过主要导航、筛选、表单、选择、播放或主 CTA，以及当前流程承重的 loading、error、empty、disabled 等状态。

检查真实字体与素材是否加载、主动作能否在短时间内辨认、文字是否换行或裁切、层级与对齐是否稳定、移动端是否溢出、焦点和键盘路径是否可见、交互反馈和动效是否符合承诺。再以目标用户而非制作者的身份逐项审查可见内容：无法说明产品责任，只是在解释制作过程或弥补交付缺口的内容应移出界面。发现问题就回到代码继续修正；截图或 DOM 探针用于看见结果，不替代真实操作。

这个循环证明作者已经看见并校正了当前界面，不替 `test` 证明完整用户旅程，也不替 `review` 独立批准自己的设计。未获视觉验证授权或浏览器、数据不可用时，继续其余已授权工作，交付实际产物并具名说明未验证部分，不能宣称视觉成功。

当主要任务与主动作清楚、视觉选择能够回到同一方向、重复表达由最小系统约束、核心交互有反馈、目标桌面和移动端没有明显缺陷，并且剩余限制已经具名时停止。交付实际结果、可打开路径或 URL、关键文件、运行过的检查、走过的交互和仍未证明的部分。