1LunarVeil/前端美学

前端美学 是做什么的？

frontend-design 确立了姿态：致力于一个方向，并避免使用无人选择的默认值。本技能提供决策规则、数字、先例数据和校验，使得这些选择变得可验证。在需要时打开参考步骤的名称；不要一开始就全部阅读它们。

1. 首先阅读项目的规则

• 在设计之前，查找简报或合同：DESIGN.md、PRODUCT.md、Token 文件（tokens.css、theme.*、tailwind.config.*）或合同文档如 FRONTEND_CONTRACT.md。这些文件优先于本技能中的默认规则。
• 如果项目通过 Token 路由视觉值，那么组件中出现新的原始 hex、px 或 rgba 值是一个发现，而不是一种样式选择。
• 保留已有功能：主题切换、i18n 键、无障碍行为、现有组件。只修改被要求的作用域，而不是整个应用。

2. 简报

编写 references/principles.md 中描述的简报：主题、受众和上下文、主屏幕的任务、密度、语言以及五个维度（排版、颜色、布局、动效、细节）。添加三个拒绝项：此设计不得看起来像的默认样式。如果用户没有描述品味，提出一个方向并说明原因。不要审问用户。

3. 先例

从技能的基础目录运行以下命令：

python scripts/design_lookup.py "saas dashboard dark" --ux --motion

使用英文关键词。输出给出了匹配的产品类型、其样式、包含对比度检查的文本和 UI 配对的调色板、排版配对和推理规则。将其视为证据，而非答案。它的第一个样式通常是趋势选择（如毛玻璃风格、霓虹灯、禅意布局），这对于密集的工具来说可能是错误的。文本配对在 192 个调色板行中只有一个失败，但大多数调色板的边框与背景对比度低于 3:1，因此每个调色板的 UI 在使用前都需要检查其配对。

4. 方向

从 references/directions.md 中选择一个方向，或定义你自己的方向，并说明它为何适合此简报，以及最接近的替代方案为何不适合。在一个地方大胆使用：一个标志性元素。其周围的一切都需克制。

5. 先定义 Token, 再定义组件

首先将颜色角色、字号比例、间距、圆角、阴影和动效时长定义为变量（参见 references/color-and-type.md、references/layout-and-motion.md）。检查每个你交付的文本配对：

python scripts/wcag.py "#1f2937" "#ffffff" "#556070" "#f6f7f9"

6. 构建

覆盖所有状态，而不仅仅是理想路径（参见 references/components-and-states.md）。保持文案为产品的语言，并测试最长的翻译。

7. 报告前进行验证

• 渲染并查看。python scripts/visual_capture.py <url> --out shots --matrix 提供默认、150% 缩放、窄屏和手机视图，等待稳定帧，并报告控制台错误。阅读 references/visual-review.md；没有截图的审查不是视觉审查。
• 更改后，再次截图并运行 scripts/image_diff.py before.png after.png。如果更改的区域与你声称更改的内容不匹配，则该声明是错误的。
• python scripts/slop_scan.py <changed paths>。退出状态 1 表示阻塞性问题。
• 检查你实际交付的每个文本和 UI 配对的对比度（wcag.py）。
• 纯键盘通过测试、减少动效通过测试以及使用最坏情况数据的断点测试。
• 控制台错误是失败。被报告为 blank 的截图也是失败；将报告为 unsettled 的截图视为可疑。

当无法访问浏览器时，请写下“未进行视觉验证”，命名跳过的状态，并且不要声称渲染的 UI 看起来是什么样子。

8. 报告

命名方向及其理由，提供 Token 块，并列明每项验证及其命令和结果。列出未验证的内容。

底线（绝不能为外观妥协这些）

• 文本对比度至少 4.5:1。大文本（24px 或 18.66px 粗体）以及 UI 边界或焦点指示器需要至少 3:1。
• 每个可交互元素都有可见的键盘焦点指示器，且该指示器不同于其悬停状态。
• 颜色单独不能传达含义。
• 动效遵循 prefers-reduced-motion。任何闪烁频率不得超过每秒三次。
• 正文文本在 Web 上至少 16px，在密集型桌面 UI 中至少 14px。无文本低于 12px。
• 每个状态都存在：加载、空状态、错误、禁用和部分数据。
• 无占位符文案交付。错误信息说明发生了什么以及下一步该怎么做。
• 文本能承受最长的实际字符串：翻译、中文日文韩文、长路径和模型名称。

品味规则

• 一种主中性色完成大部分工作。一种强调色最多覆盖屏幕的约 10%。成功、警告和危险颜色在不同主题间保持一致。
• 最多两种字型，必要时加上等宽字体。一种比例缩放。层次结构来自大小、粗细、颜色和间距，而不是盒子。
• 更少的边框和更少的嵌套卡片。圆角来自一个小比例的尺寸。阴影色调与调色板匹配，最多三个高度层级。
• 动效：每屏幕一个有意为之的时刻，仅使用 transform 和 opacity，并且不对会话中重复多次的操作进行动画。
• 文案：句子式大小写、简单动词，并在按钮、结果消息和菜单中为同一操作使用相同的名称。

选择测试

每个默认值（字体、调色板、圆角、阴影、布局、图标集）都必须为此简报选择。如果你无法说出原因，请更改它。你选择的一个默认值并不是一个特征。references/anti-slop.md 列出了常见的识别特征以及标记每个特征的扫描器规则。

文件

• references/principles.md：决策顺序、简报模板、拒绝项。
• references/directions.md：九个方向，附带经过验证的起始 Token。
• references/color-and-type.md：调色板、暗黑模式、对比度、字号比例、字体加载、中文日文韩文。
• references/layout-and-motion.md：网格、密度、间距、圆角、阴影、动效。
• references/components-and-states.md：组件、状态矩阵、文案、断点测试。
• references/desktop-app.md：针对 WebView 和桌面应用的规则。
• references/anti-slop.md：识别特征、为什么它们看起来像默认值、要询问的问题、扫描器规则 ID。
• references/critique.md：审查程序、九大支柱、严重性、输出格式。
• references/visual-review.md：如何渲染、截图、读取和重新差异对比 UI。
• references/sources.md：每条规则的来源以及故意未使用的内容。
• scripts/wcag.py、scripts/design_lookup.py、scripts/slop_scan.py、scripts/visual_capture.py、scripts/image_diff.py：只读、无第三方包、无网络。如果 python 不在 PATH 中，请使用 py -3。
• data/：从 ui-ux-pro-max 购买的 MIT 许可 CSV 数据（参见 data/PROVENANCE.md）。