design-critique

设计评审

系统地评估现有设计，并提供具体、可执行的改进建议和代码。

前提条件

• 阅读 .agents/design-context.md（参见 design-context），了解品牌颜色、字体、风格原型、受众和语气。“符合品牌”以此文件为判断依据，而非个人喜好。如果该文件不存在，请说明一致性／美感评分是在没有品牌背景的情况下评定的。
• 了解项目的用途、受众，以及设计应引导用户采取的唯一操作。
• 绝不能只根据源代码进行评审。先查看渲染结果（步骤 0）。

---

步骤 0：捕获设计稿（始终首先执行）

设计稿	查看方式
HTML 文件／本地开发服务器／URL	运行下方的捕获脚本，然后阅读它生成的每张 PNG 图片
PNG/JPG/WebP（屏幕截图、生成的图片、海报）	阅读文件。查看细节时，使用 Pillow 裁剪／放大（Image.open(p).crop(box).resize(...)），然后阅读裁剪结果
Figma 画板	如果已连接，使用 Figma MCP get_screenshot（以及 get_variable_defs 获取设计令牌）；否则请对方导出
React/Vue 组件	在项目的开发服务器或 Storybook 中渲染，然后将其视为 URL

捕获脚本——位于 <design-critique>/scripts/audit.mjs（<design-critique> 是此技能所在目录）。需要 Playwright 和 Chromium；安装 npm i -D axe-core 可启用离线无障碍检查（否则脚本会从 CDN 加载 axe）：

node <design-critique>/scripts/audit.mjs <url-or-html-file> audit/            # 375, 768, 1440 px
node <design-critique>/scripts/audit.mjs http://localhost:3000 audit/ --widths 390,1280

脚本会生成 {mobile,tablet,desktop}-fold.png（第一印象）、*-full.png、desktop-dark-fold.png 和 report.json（也会打印出来），其中包含：

部分	检查内容
widths.<name>	水平溢出、正在使用的字体大小／字体系列／文本颜色（一致性）、偏离 4px 网格的间距、小于 24px 的触控目标、与最近的纯色背景相比未达到 WCAG 对比度要求的文本、叠加在图片上的文本（需目视检查）
darkMode	prefers-color-scheme: dark 下的对比度问题
structure	lang、视口 meta 标签、h1 数量、跳级的标题层级、缺少 alt 的图片、未标注的表单控件、首屏视口中的延迟加载图片（LCP 风险）、未设置 prefers-reduced-motion 规则的动画
axe	axe-core 违规项：规则 id、影响程度、数量、第一个选择器

请将数值视为证据，而非结论：禁用控件或装饰性文本上的对比度“未达标”可能是合理的；如确实如此，请明确说明。

流程（每次都按相同顺序，以便比较评审结果）：

1. 查看 desktop-fold.png 5 秒钟：记下首先、其次、第三注意到的内容，以及页面希望你做什么。这就是判断视觉层级的依据。
2. 使用屏幕截图和 JSON，依次完成步骤 1-7。每项发现都必须引用证据：屏幕截图中的区域、测量值或 axe 规则 id。
3. 评定严重程度（步骤 8）和分数（步骤 10），并撰写报告。
4. 应用修复后，重新运行捕获脚本并对比修复前后的屏幕截图（步骤 9）。

对于静态图片（海报、广告、社交媒体图片、生成的图片），不存在 DOM：跳过键盘／性能检查，使用 Pillow（im.getpixel((x, y))）采样像素颜色并套用 WCAG 公式估算对比度，同时也要按图片的实际显示尺寸进行评判（例如，将缩略图缩小到 320px 宽后阅读）。要修复生成的图片，请为 image-generation 技能提供具体的编辑说明，而不是 CSS。

---

步骤 1：视觉层级评估

评估设计引导用户视线的效果。

检查清单

• 主要视觉焦点：是否有一个清晰的元素最先吸引注意力？
• 次要元素：能否明确辨别出重要性第 2、第 3 的元素？
• 尺寸对比：最重要的元素是否最大？不同层级之间的尺寸差异是否足够？
• 颜色对比：主要 CTA 是否使用最醒目的颜色？次要元素是否在视觉上弱化？
• 字重对比：标题是否比正文更粗？
• 留白：最重要的元素周围是否有最多的呼吸空间？
• 阅读流：布局是否遵循 F 型（内容）或 Z 型（落地页）？

常见修复

/* Problem: All elements same visual weight */
/* Fix: Create clear hierarchy with size and color */

/* Before: flat hierarchy */
.heading { font-size: 1.5rem; color: #333; }
.subheading { font-size: 1.25rem; color: #333; }
.body { font-size: 1rem; color: #333; }

/* After: clear hierarchy */
.heading { font-size: 2.5rem; font-weight: 800; color: var(--gray-900); letter-spacing: -0.02em; }
.subheading { font-size: 1.25rem; font-weight: 500; color: var(--gray-500); }
.body { font-size: 1rem; font-weight: 400; color: var(--gray-700); line-height: 1.65; }

---

第 2 步：颜色使用评估

检查清单

• 调色板协调性：所有颜色是否来自同一色系／系统，还是有些颜色显得突兀？
• 颜色含义：每种颜色是否都有明确用途（品牌、语义或装饰）？
• 颜色数量：颜色是否过多？（建议使用 1–2 种品牌色 + 4 种语义色 + 中性色。）
• 对比度：所有文本是否符合 WCAG AA 标准（普通文本为 4.5:1；≥24px 或 ≥18.66px 粗体文本为 3:1）？使用 axe 的 color-contrast 结果；对于图片／渐变上的文本，应测量截图中对比度最差的位置。
• 语义颜色一致性：红色是否始终表示错误？绿色是否始终表示成功？
• 深色模式：如果有深色模式，颜色是否经过适配（而非只是反转）？
• 仅靠颜色传达的信息：是否有信息仅通过颜色传达？（不应该这样。）

常见修复

/* Problem: Text fails contrast check */
/* Before: light gray on white */
.muted-text { color: #aaa; } /* ~2.3:1 on white -- FAILS AA */

/* Fix: darken until AA passes */
.muted-text { color: #737373; } /* 4.74:1 on white -- passes AA (design-context Neutral 500) */

/* Problem: Link indistinguishable from text */
/* Fix: underline + color */
a { color: var(--brand-500); text-decoration: underline; text-underline-offset: 2px; }

---

第 3 步：字体排版一致性检查

检查清单

• 字体数量：最多使用 2 种字体（含等宽字体时最多 3 种）。更多会显得杂乱。
• 字号比例：字号是否遵循一致的比例，还是随意设定？
• 字重使用：是否只使用 2–3 种字重？（400、600、700 是一组合适的取值。）
• 行高：正文行高是否为 1.5–1.75？标题行高是否为 1.1–1.3？
• 行长：正文每行是否限制在 45–75 个字符？
• 一致性：相同类型的元素是否始终使用相同样式？
• 文本换行：标题是否使用 text-wrap: balance（避免最后一行只有一个词）？
• 比例依据：采集的 JSON 中，fontSizes 应显示大约 5–8 种不同字号；达到 12 种或更多则意味着没有遵循字号比例。
• 响应式：文本在移动设备上是否按比例缩放？

常见修复

/* Problem: Line length too long */
/* Before: text spans full 1400px container */
.content { max-width: 1400px; }

/* Fix: constrain prose */
.content { max-width: 1400px; }
.content .prose { max-width: 65ch; }

/* Problem: Arbitrary font sizes -- Fix: adopt the typography skill's modular scale */
:root {
  --type-ratio: 1.25; /* design-context Scale Ratio */
  --text-base: 1rem;
  --text-lg: calc(var(--text-base) * var(--type-ratio));
  --text-xl: calc(var(--text-lg) * var(--type-ratio)); /* ...see typography Step 1 */
}

---

第 4 步：间距与对齐审查

检查清单

• 间距一致性：相似元素之间的间隔是否相同？
• 间距比例：间距是否采用基础单位（4px 或 8px 的倍数）？
• 对齐：元素是否与网格对齐？左边缘是否对齐？
• 邻近关系：相关项目之间的距离是否比不相关项目更近？
• 内边距平衡：组件内的内边距是否保持一致？
• 垂直节奏：垂直间距是否保持一致的节奏？
• 边缘一致性：各区块的页面边距是否一致？

常见修复

/* Problem: Inconsistent spacing */
/* Before: random pixel values */
.card { padding: 17px; margin-bottom: 23px; }
.section { padding: 45px 30px; }

/* Fix: use a 4px/8px scale */
.card { padding: var(--space-5); margin-bottom: var(--space-6); }
.section { padding: var(--space-12) var(--space-8); }

/* Problem: Misaligned elements */
/* Fix: use consistent padding and max-width */
.container {
  max-width: 1200px;
  margin-inline: auto;
  padding-inline: var(--space-6);
}

---

第 5 步：无障碍审查

对比度

• 普通文本：最低对比度为 4.5:1。
• 大号文本（≥24px，或 ≥18.66px 粗体）：最低对比度为 3:1。
• UI 组件（边框、图标）：与相邻颜色的对比度为 3:1。
• 焦点指示器：与相邻背景的对比度为 3:1。

键盘导航

• 所有可交互元素都可以获得焦点。
• 焦点顺序与视觉顺序一致。
• 焦点指示器清晰可见，且对比度足够。
• 没有键盘陷阱（用户始终可以通过 Tab 键移开焦点）。
• 存在跳转到内容的链接。

屏幕阅读器

• 图片具有有意义的替代文本（或在纯装饰图片上使用 alt=""）。
• 表单输入控件具有关联的标签。
• 仅含图标的按钮具有 aria-label。
• 标题构成逻辑清晰的大纲（没有跳过层级）。
• 动态内容变化会通过 aria-live 区域播报。

常见修复

/* Problem: Custom focus style removed */
/* Before */
*:focus { outline: none; } /* NEVER DO THIS */

/* Fix: custom but visible focus */
*:focus-visible {
  outline: 2px solid var(--brand-500);
  outline-offset: 2px;
}

/* Problem: No skip link */
/* Fix: */
.skip-link {
  position: absolute;
  top: -100%;
  left: 0;
  padding: 0.5rem 1rem;
  background: var(--brand-500);
  color: white;
  z-index: 9999;
}

.skip-link:focus {
  top: 0;
}

<a href="#main-content" class="skip-link">Skip to main content</a>

---

第 6 步：响应式行为检查

检查清单

• 移动端布局：布局在小屏幕上是否能合理地堆叠？
• 触控目标：至少为 24x24px（WCAG 2.2 AA，SC 2.5.8；参见 JSON 中的 smallTargets）；建议移动端使用 44x44px。
• 文本可读性：正文在移动端是否至少为 16px（无需缩放）？
• 水平滚动：是否存在水平溢出？
• 图像：图像是否能适当调整大小（max-width: 100%）？
• 导航：移动端导航是否易于访问和使用？
• 断点：布局在不同断点之间是否平滑过渡？

常见修复

/* Problem: Fixed widths cause overflow */
/* Before */
.card { width: 400px; }

/* Fix: flexible with max */
.card { width: 100%; max-width: 400px; }

/* Problem: Small touch targets */
/* Before */
.icon-button { width: 24px; height: 24px; }

/* Fix: larger hit area, same visual icon (works with box-sizing: border-box) */
.icon-button {
  min-width: 44px;
  min-height: 44px;
  display: inline-grid;
  place-items: center;
}

/* Problem: Images overflow container */
img {
  max-width: 100%;
  height: auto;
}

---

第 7 步：性能影响评估

检查清单

• 字体加载：是否使用 font-display: swap？是否预加载关键字体？
• 图像格式：是否使用 AVIF/WebP 并提供回退格式，以及 srcset + sizes，以免手机加载桌面端图像？
• 图像尺寸：图像尺寸是否合适（是否避免为 400px 的显示区域加载 4000px 的图像）？
• 动画性能：动画是否仅使用 transform 和 opacity？
• CSS 效率：是否存在冗余或覆盖其他样式的样式？
• 布局偏移：是否为图像/嵌入内容预留了尺寸（aspect-ratio、width/height）？
• 过多的阴影/模糊效果：频繁重绘的元素上是否有复杂的 box-shadow？

常见修复

/* Problem: Animation causes layout recalculation */
/* Before */
.card:hover { margin-top: -5px; }  /* triggers layout */

/* Fix: use transform */
.card:hover { transform: translateY(-5px); }  /* GPU composited */

/* Problem: Layout shift from images */
/* Fix: put the intrinsic size in HTML (<img width="1600" height="900">), then: */
img { max-width: 100%; height: auto; }

---

第 8 步：严重程度与建议格式

严重程度级别（每个问题必须且只能分配一个级别）

严重程度	标准	示例
严重	阻止用户完成核心任务，或核心内容未达到 WCAG A/AA 标准	正文文本对比度为 2.3:1、移动端 CTA 不可见、键盘陷阱、移动端水平滚动、表单字段缺少标签
高	核心任务可以完成，但明显更困难，或设计削弱了其主要目标	没有明确的主要 CTA、视觉焦点相互竞争、颜色/字体不符合品牌风格、点击目标 < 24px
中	大多数用户都能察觉的可见精致度/一致性问题，但可以绕过	字号超过 10 种、间距偏离网格、圆角不一致、次级层级不明显
低	设计师会注意到的细节优化	标题孤行、字间距略显宽松、轻微的对齐偏差

修复列表应先按严重程度排序，再按同一严重程度内的影响 ÷ 工作量排序。

建议格式

### [Severity] Issue: [What's wrong]
**Category**: Hierarchy | Color | Typography | Spacing | Accessibility | Responsive | Performance
**Evidence**: [screenshot + region, measured value, or axe rule id]
**Problem**: [1-2 sentences: what's wrong and why it matters]
**Fix**: [Specific CSS/HTML using the project's tokens]
**Impact**: [What improves]

示例

### [High] Issue: Hero headline, subtitle, and CTA compete for attention
**Category**: Hierarchy
**Evidence**: desktop-fold.png -- headline 28px/600, subtitle 24px/600, CTA is a gray outline button
**Problem**: Nothing reads first, and the only action looks secondary.
**Fix**: .hero-headline { font-size: clamp(2.5rem, 5vw + 1rem, 5rem); font-weight: 800; }
         .hero-subtitle { font-size: var(--text-xl); color: var(--text-secondary); max-width: 50ch; }
         .hero-cta { background: var(--interactive-primary); color: white; }
**Impact**: Headline -> value prop -> CTA reads in order within 3 seconds.

---

第 9 步：前后验证

只有在渲染后的页面上检查修复效果后，评审才算完成。

1. 对于每项修复，展示当前 CSS（修复前）和改进后的 CSS（修复后），并说明改了什么以及原因。使用现有设计令牌（--space-*、--text-*、--bg-*、--text-primary、--interactive-primary、--radius-*、--shadow-*）；绝不引入新的硬编码值。
2. 如果已应用修复，请将捕获脚本重新运行到新文件夹中，并并排查看相同视口下修复前后的截图。
3. 确认所有严重/高优先级问题均已解决（axe 违规项消失、无溢出、目标尺寸 ≥ 24px），且其他宽度或深色模式下没有出现回归。仅在完成此检查后重新评分。

---

第 10 步：评分框架

从以下维度对设计进行评分（1-10 分）：

类别

类别	权重	评估内容（检查步骤）
层级	25%	焦点明确、易于浏览、流程清晰（步骤 1、5 秒测试）
一致性	25%	间距比例、色彩系统、字体系统、品牌匹配度（步骤 2-4，捕获 JSON）
美观度	25%	色彩协调、留白、精致度、是否符合风格原型
易用性	25%	无障碍性、响应式、清晰度、性能（步骤 5-7，axe）

总分 = 加权平均值，四舍五入到小数点后一位。上限让评分更客观：任何未解决的严重问题都会将其所属类别的分数限制在 4 分，并将总分限制在 6 分；任何未解决的高优先级问题都会将其所属类别的分数限制在 7 分。美观度必须至少引用一条具体观察，不能只说“看起来很现代”。

评分标准

分数	含义
1-2	从根本上无法正常使用。需要大幅返工。
3-4	存在严重问题。多个方面需要改进。
5-6	功能可用，但不够完善。有明确的改进空间。
7-8	良好。稍作润色即可更上一层楼。
9-10	出色。达到专业水准，执行到位。

报告模板

## Design Critique Report

### Overall Score: X/10

| Category    | Score | Notes                                |
|-------------|-------|--------------------------------------|
| Hierarchy   | X/10  | [brief note]                         |
| Consistency | X/10  | [brief note]                         |
| Aesthetics  | X/10  | [brief note]                         |
| Usability   | X/10  | [brief note]                         |

### Top 3 Strengths
1. [What's working well]
2. [What's working well]
3. [What's working well]

### Issues by Severity
| # | Severity | Category | Issue | Evidence |
|---|----------|----------|-------|----------|
| 1 | Critical | ...      | ...   | ...      |

### Fixes (in priority order, with code -- Step 8 format)

### Quick Wins (< 5 min each)
- [Small change, big impact]
- [Small change, big impact]

---

评审流程摘要

0. 捕获成品（步骤 0），先查看截图，再阅读代码。
1. 阅读设计背景并了解目标。
2. 评估视觉层级：是否有清晰的 1-2-3 优先级？
3. 评估色彩：是否协调？是否无障碍？是否用途明确？
4. 检查字体排版：比例是否一致？行长是否合适？是否易读？
5. 审查间距：是否采用统一系统？是否对齐？是否一致？
6. 检查无障碍性：对比度、焦点、标签、键盘操作？
7. 测试响应式布局：移动端堆叠、触控目标、溢出？
8. 检查性能：动画是否高效？图片尺寸是否合适？字体是否已加载？
9. 提供具体修复方案：始终包含代码，不要只做描述。
10. 评分并确定优先级：分配严重程度、应用上限、排列修复项。
11. 重新验证：修复后重新捕获并确认严重/高优先级问题已解决（步骤 9）。