Back to Details

design-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design Review

设计评审

Evaluate your application's visual quality and usability against established design standards. This review catches issues that typically require a trained designer's eye — responsive breakpoints, accessibility compliance, visual hierarchy, spacing consistency, and internationalization readiness.
对照既定设计标准评估应用的视觉质量与可用性。本次评审能发现通常需要专业设计师才能识别的问题——响应式断点、可访问性合规性、视觉层级、间距一致性以及国际化就绪程度。

When to use

使用场景

Use 
/design-review
when:
  • Shipping UI without a designer reviewing it
  • Before a launch or demo
  • After significant UI changes or redesigns
  • Checking accessibility compliance (WCAG 2.1 AA)
  • Validating responsive behavior across devices
在以下场景使用 
/design-review
：
  • 无设计师参与评审就发布UI时
  • 上线或演示前
  • 重大UI变更或重新设计后
  • 检查可访问性合规性（WCAG 2.1 AA）
  • 验证跨设备的响应式表现

Standards Referenced

参考标准

  • WCAG 2.1 Level AA — Web Content Accessibility Guidelines
  • Material Design / Human Interface Guidelines — spacing, touch targets, typography scales
  • ISO 9241-110 — Interaction principles (suitability, self-descriptiveness, conformity)
  • APCA — Advanced Perceptual Contrast Algorithm (next-gen contrast)
  • WCAG 2.1 Level AA — 网页内容可访问性指南
  • Material Design / Human Interface Guidelines — 间距、触摸目标、排版比例
  • ISO 9241-110 — 交互原则（适用性、自描述性、一致性）
  • APCA — 高级感知对比度算法（下一代对比度标准）

Phase Overview

阶段概述

Phase 1: EDUCATE   → Brief context on what we check and why
Phase 2: SCOPE     → Identify pages, breakpoints, and focus areas
Phase 3: ANALYZE   → Browser-based checks with evidence capture
Phase 4: REPORT    → Findings with screenshots, scores, confidence
Phase 5: REMEDIATE → Fix guidance + YAML regression tests
Phase 1: EDUCATE   → 简要说明我们的检查内容及原因
Phase 2: SCOPE     → 确定页面、断点和重点关注区域
Phase 3: ANALYZE   → 基于浏览器的检查并捕获证据
Phase 4: REPORT    → 包含截图、分数和可信度的检查结果
Phase 5: REMEDIATE → 修复指南 + YAML回归测试

Phase 1: Educate

阶段1：认知

Why this matters: 94% of first impressions are design-related. Poor visual quality erodes trust even when functionality is correct. Accessibility issues affect 15-20% of users and carry legal risk (ADA lawsuits increased 300% since 2018).
This review checks your app against objective, measurable design criteria — not subjective taste. Every finding references a specific standard.
重要性说明： 94%的第一印象由设计决定。即使功能正常，糟糕的视觉质量也会削弱用户信任。可访问性问题影响15-20%的用户，还存在法律风险（自2018年以来，ADA诉讼增加了300%）。
本次评审对照客观、可衡量的设计标准检查应用——而非主观审美偏好。每一项检查结果都对应具体标准。

Phase 2: Scope

阶段2：范围确定

Gather context

收集上下文信息

  1. Auto-detect — scan the project for:
    • Framework (React, Vue, Next.js, etc.)
    • CSS approach (Tailwind, CSS modules, styled-components, etc.)
    • Design system in use (if any)
    • Route structure → list of pages
    • Existing a11y tooling (eslint-plugin-jsx-a11y, axe-core, etc.)
  2. Ask the user (one at a time, with auto-detected defaults):
    • Target URL: Where is the app running? (auto-detect dev server)
    • Key pages: Which pages matter most? (recommend top 3-5 from routes)
    • Target devices: Desktop only? Mobile-first? Both? (default: both)
    • Brand guidelines: Any specific colors, fonts, or design system? (default: evaluate against general best practices)
    • Focus areas: Any known concerns? (optional)
  3. Define breakpoints to test:
    • Mobile: 375px (iPhone SE), 390px (iPhone 14)
    • Tablet: 768px (iPad)
    • Desktop: 1280px, 1920px
    • (Adjust based on user's target audience)
  1. 自动检测 — 扫描项目以获取：
    • 框架（React、Vue、Next.js等）
    • CSS方案（Tailwind、CSS modules、styled-components等）
    • 使用的设计系统（如有）
    • 路由结构 → 页面列表
    • 现有可访问性工具（eslint-plugin-jsx-a11y、axe-core等）
  2. 询问用户（逐一提问，附带自动检测的默认值）：
    • 目标URL：应用部署在哪里？（自动检测开发服务器）
    • 关键页面：哪些页面最重要？（推荐路由中的前3-5个页面）
    • 目标设备：仅桌面端？移动端优先？两者兼顾？（默认：两者兼顾）
    • 品牌指南：是否有特定的颜色、字体或设计系统？（默认：对照通用最佳实践评估）
    • 重点区域：是否有已知问题？（可选）
  3. 定义测试断点：
    • 移动端：375px（iPhone SE）、390px（iPhone 14）
    • 平板端：768px（iPad）
    • 桌面端：1280px、1920px
    • （可根据用户目标受众调整）

Phase 3: Analyze

阶段3：分析

Open a browser session with 
new_session
using 
record_evidence: true
. For each page in scope, run the following check categories.
使用 
new_session
打开浏览器会话，设置 
record_evidence: true
。对范围内的每个页面，运行以下检查类别。

Category A: Responsive Design (RES)

类别A：响应式设计（RES）

Check IDCheckStandardMethod
RES-01Viewport meta tag presentMobile best practiceInspect 
<meta name="viewport">
RES-02No horizontal overflow at any breakpointResponsive designResize viewport, check for horizontal scrollbar
RES-03Touch targets ≥ 48x48px on mobileWCAG 2.5.8 / Material DesignMeasure interactive element sizes at mobile breakpoint
RES-04Text remains readable without zoom at 375pxWCAG 1.4.4Check font sizes ≥ 16px for body text on mobile
RES-05Navigation is accessible at all breakpointsUsabilityVerify nav collapses/adapts, hamburger menu works
RES-06Images scale appropriatelyResponsive imagesCheck for 
srcset
/
sizes
or CSS containment
RES-07No content truncation without indicationUsabilityCheck text overflow, ellipsis with tooltip or expand
RES-08Form inputs are usable on mobileUsabilityCheck input sizes, proper input types (tel, email)
Browser validation: For each breakpoint, use 
act
to resize the viewport, then 
inspect_page
to capture DOM and screenshot. Check for overflow elements, measure sizes via JavaScript.
检查ID检查内容参考标准方法
RES-01存在视口元标签移动端最佳实践检查 
<meta name="viewport">
RES-02所有断点下无水平溢出响应式设计调整视口大小，检查是否出现水平滚动条
RES-03移动端触摸目标≥48x48pxWCAG 2.5.8 / Material Design在移动端断点测量交互元素尺寸
RES-04375px断点下文本无需缩放即可阅读WCAG 1.4.4检查移动端正文文本字体大小≥16px
RES-05导航在所有断点下均可访问可用性验证导航是否折叠/适配，汉堡菜单是否正常工作
RES-06图片适当缩放响应式图片检查是否使用 
srcset
/
sizes
或CSS containment
RES-07内容截断时有提示可用性检查文本溢出情况，是否使用省略号搭配 tooltip 或展开功能
RES-08表单输入在移动端可用可用性检查输入框大小，是否使用合适的输入类型（tel、email等）
浏览器验证： 针对每个断点，使用 
act
调整视口大小，然后使用 
inspect_page
捕获DOM和截图。检查溢出元素，通过JavaScript测量尺寸。

Category B: Accessibility (A11Y)

类别B：可访问性（A11Y）

Check IDCheckStandardMethod
A11Y-01Color contrast ratio ≥ 4.5:1 (normal text)WCAG 1.4.3 AAExtract computed colors, calculate ratio
A11Y-02Color contrast ratio ≥ 3:1 (large text ≥ 18pt)WCAG 1.4.3 AASame as above for large text
A11Y-03All images have alt textWCAG 1.1.1Check 
<img>
elements for 
alt
attribute
A11Y-04Form inputs have associated labelsWCAG 1.3.1Check 
<label for="">
or 
aria-label
A11Y-05Heading hierarchy is logical (h1→h2→h3)WCAG 1.3.1Extract heading levels, check sequence
A11Y-06Focus is visible on all interactive elementsWCAG 2.4.7Tab through elements, check focus ring visibility
A11Y-07Keyboard navigation works (Tab, Enter, Escape)WCAG 2.1.1Navigate entire page via keyboard
A11Y-08Skip navigation link presentWCAG 2.4.1Check for skip-to-content link
A11Y-09ARIA roles used correctlyWCAG 4.1.2Check for misused/redundant ARIA
A11Y-10Page has lang attributeWCAG 3.1.1Check 
<html lang="">
A11Y-11Modal focus trapping worksWCAG 2.4.3Open modal, verify Tab stays within
A11Y-12Error messages are associated with inputsWCAG 3.3.1Check 
aria-describedby
or 
aria-errormessage
A11Y-13Reduced motion respectedWCAG 2.3.3Check for 
prefers-reduced-motion
media query
A11Y-14No seizure-inducing content (>3 flashes/sec)WCAG 2.3.1Visual inspection of animations
Browser validation: Use 
inspect_page
to extract the DOM. Run JavaScript via 
act
to compute contrast ratios, check ARIA attributes, extract heading hierarchy. Use keyboard navigation (Tab, Enter, Escape) to test focus management.
检查ID检查内容参考标准方法
A11Y-01普通文本颜色对比度≥4.5:1WCAG 1.4.3 AA提取计算后的颜色，计算对比度
A11Y-02大文本（≥18pt）颜色对比度≥3:1WCAG 1.4.3 AA同上，针对大文本
A11Y-03所有图片均有替代文本WCAG 1.1.1检查 
<img>
元素的 
alt
属性
A11Y-04表单输入关联标签WCAG 1.3.1检查 
<label for="">
或 
aria-label
A11Y-05标题层级逻辑合理（h1→h2→h3）WCAG 1.3.1提取标题层级，检查顺序
A11Y-06所有交互元素的焦点可见WCAG 2.4.7按Tab键遍历元素，检查焦点环可见性
A11Y-07键盘导航正常工作（Tab、Enter、Escape）WCAG 2.1.1通过键盘导航整个页面
A11Y-08存在跳过导航链接WCAG 2.4.1检查是否有跳转到内容的链接
A11Y-09ARIA角色使用正确WCAG 4.1.2检查是否误用/冗余使用ARIA
A11Y-10页面包含lang属性WCAG 3.1.1检查 
<html lang="">
A11Y-11模态框焦点捕获正常WCAG 2.4.3打开模态框，验证Tab键仅在框内循环
A11Y-12错误消息与输入框关联WCAG 3.3.1检查 
aria-describedby
或 
aria-errormessage
A11Y-13遵循减少动画的设置WCAG 2.3.3检查是否使用 
prefers-reduced-motion
媒体查询
A11Y-14无诱发癫痫的内容（每秒闪烁>3次）WCAG 2.3.1视觉检查动画内容
浏览器验证： 使用 
inspect_page
提取DOM。通过 
act
运行JavaScript计算对比度、检查ARIA属性、提取标题层级。使用键盘导航（Tab、Enter、Escape）测试焦点管理。

Category C: Visual Consistency (VIS)

类别C：视觉一致性（VIS）

Check IDCheckStandardMethod
VIS-01Consistent spacing scaleDesign systemsExtract margins/paddings, check for consistent scale (4px/8px grid)
VIS-02Typography scale is consistentTypographic hierarchyExtract font sizes, check for consistent ratio/scale
VIS-03Color palette is limited and intentionalDesign best practiceExtract all used colors, flag if >10 unique non-gray colors
VIS-04Interactive elements have consistent stylingConsistencyCompare button styles, link styles across pages
VIS-05Alignment grid is consistentLayoutCheck for misaligned elements that break the visual grid
VIS-06Loading states exist for async operationsUX best practiceTrigger async actions, verify loading indicators
VIS-07Empty states are handledUX best practiceNavigate to pages with no data, check for meaningful empty states
VIS-08Error states are styled consistentlyUX best practiceTrigger validation errors, check styling
VIS-09Dark mode consistency (if applicable)Design systemsToggle dark mode, check for un-themed elements
Browser validation: Use JavaScript to extract computed styles, compare across elements and pages. Screenshot comparison between pages for visual consistency.
检查ID检查内容参考标准方法
VIS-01间距比例一致设计系统提取外边距/内边距，检查是否符合一致的比例（4px/8px网格）
VIS-02排版比例一致排版层级提取字体大小，检查比例是否一致
VIS-03调色板有限且合理设计最佳实践提取所有使用的颜色，若独特非灰色颜色>10种则标记
VIS-04交互元素样式一致一致性对比不同页面的按钮样式、链接样式
VIS-05对齐网格一致布局检查破坏视觉网格的错位元素
VIS-06异步操作有加载状态UX最佳实践触发异步操作，验证加载指示器存在
VIS-07空状态处理得当UX最佳实践导航到无数据页面，检查是否有有意义的空状态提示
VIS-08错误状态样式一致UX最佳实践触发验证错误，检查样式
VIS-09深色模式一致性（如适用）设计系统切换深色模式，检查未适配主题的元素
浏览器验证： 使用JavaScript提取计算后的样式，跨元素和页面对比。通过页面间截图对比检查视觉一致性。

Category D: Typography & Readability (TYP)

类别D：排版与可读性（TYP）

Check IDCheckStandardMethod
TYP-01Body text 16-20pxReadability researchExtract computed font-size
TYP-02Line height 1.4-1.6 for body textReadabilityExtract computed line-height
TYP-03Line length 45-75 charactersReadability (Bringhurst)Measure character count per line
TYP-04Font loading strategy (FOUT/FOIT prevention)Web performanceCheck font-display CSS, preload hints
TYP-05Sufficient hierarchy levels (≥3 distinct sizes)TypographyExtract and count distinct heading sizes
TYP-06Text is left-aligned (not justified) for bodyReadabilityCheck text-align for body paragraphs
检查ID检查内容参考标准方法
TYP-01正文文本16-20px可读性研究提取计算后的字体大小
TYP-02正文文本行高1.4-1.6可读性提取计算后的行高
TYP-03每行长度45-75字符可读性（Bringhurst）测量每行字符数
TYP-04字体加载策略（预防FOUT/FOIT）Web性能检查font-display CSS、预加载提示
TYP-05足够的层级（≥3种不同大小）排版提取并统计不同的标题大小
TYP-06正文文本左对齐（非两端对齐）可读性检查正文段落的text-align属性

Category E: Internationalization Readiness (I18N)

类别E：国际化就绪程度（I18N）

Check IDCheckStandardMethod
I18N-01No hardcoded strings in componentsi18n best practiceScan source code for string literals in JSX/templates
I18N-02Layout handles text expansion (+30%)i18n designInject longer text strings, check for overflow
I18N-03RTL layout support (if applicable)i18nToggle 
dir="rtl"
, check layout adaptation
I18N-04Date/number formatting uses localei18nCheck for hardcoded date/number formats
I18N-05Font stack includes CJK/Unicode fallbacksi18n typographyCheck font-family declarations
I18N-06Icons/images don't contain texti18nVisual inspection of image content
Browser validation: Use JavaScript to modify 
dir
attribute, inject longer text, change locale settings. Screenshot at each state.
检查ID检查内容参考标准方法
I18N-01组件中无硬编码字符串国际化最佳实践扫描源代码中的JSX/模板字符串字面量
I18N-02布局可容纳文本扩展（+30%）国际化设计注入更长的文本字符串，检查是否溢出
I18N-03支持RTL布局（如适用）国际化切换 
dir="rtl"
，检查布局适配情况
I18N-04日期/数字格式使用本地化设置国际化检查是否有硬编码的日期/数字格式
I18N-05字体栈包含CJK/Unicode回退字体国际化排版检查font-family声明
I18N-06图标/图片不含文本国际化视觉检查图片内容
浏览器验证： 使用JavaScript修改 
dir
属性、注入更长文本、更改本地化设置。在每个状态下截图。

Phase 4: Report

阶段4：报告

Generate a structured report saved to 
shiplight/reports/design-review-{date}.md
:
markdown
undefined
生成结构化报告并保存到 
shiplight/reports/design-review-{date}.md
：
markdown
undefined

Design Review Report

设计评审报告

Date: {date} URL: {url} Pages reviewed: {list} Breakpoints tested: {list}
日期： {date} URL： {url} 评审页面： {list} 测试断点： {list}

Overall Score: {X}/10 | Confidence: {X}%

总体评分：{X}/10 | 可信度：{X}%

Score Breakdown

评分细分

CategoryScoreFindings
Responsive (RES)7/102 high, 1 medium
Accessibility (A11Y)5/101 critical, 3 high
Visual Consistency (VIS)8/101 medium
Typography (TYP)9/101 low
i18n Readiness (I18N)6/102 medium
类别得分问题数量
响应式设计（RES）7/102个高优先级，1个中优先级
可访问性（A11Y）5/101个关键级，3个高优先级
视觉一致性（VIS）8/101个中优先级
排版（TYP）9/101个低优先级
国际化就绪（I18N）6/102个中优先级

Findings

检查结果

CRITICAL

关键级

A11Y-01: Insufficient color contrast on primary buttons

A11Y-01：主按钮颜色对比度不足

  • Standard: WCAG 1.4.3 AA (minimum 4.5:1)
  • Finding: Primary button (#4A90D2 on #FFFFFF) has contrast ratio 3.1:1
  • Evidence: [screenshot with annotation]
  • Pages affected: All pages with primary CTA
  • Confidence: 97%
  • 标准： WCAG 1.4.3 AA（最低4.5:1）
  • 问题： 主按钮（#4A90D2 底色搭配 #FFFFFF 文字）对比度为3.1:1
  • 证据： [带标注的截图]
  • 影响页面： 所有包含主CTA的页面
  • 可信度： 97%

HIGH

高优先级

...
...

MEDIUM

中优先级

...
...

LOW / INFO

低优先级 / 信息

...
undefined
...
undefined

Confidence Scoring

可信度评分

  • 90-100%: Browser-validated, measured programmatically (contrast ratio calculated, element size measured)
  • 70-89%: Strong evidence from DOM inspection, screenshot supports finding
  • 50-69%: Heuristic-based, may vary by context (e.g., "spacing looks inconsistent")
  • Below 50%: Don't report
  • 90-100%：浏览器验证，程序化测量（对比度计算、元素尺寸测量）
  • 70-89%：DOM检查有充分证据，截图支持结论
  • 50-69%：基于启发式判断，可能因上下文而异（如“间距看起来不一致”）
  • 低于50%：不纳入报告

Phase 5: Remediate

阶段5：修复

For each finding, provide:
针对每个问题，提供：

1. Fix guidance

1. 修复指南

markdown
undefined
markdown
undefined

A11Y-01: Insufficient color contrast

A11Y-01：颜色对比度不足

File: src/components/Button.tsx:23 Current: 
background: #4A90D2
(contrast 3.1:1 against white) Fix: 
background: #2563EB
(contrast 4.8:1 against white) — maintains blue hue, meets AA Alternative: 
background: #1D4ED8
(contrast 7.1:1) — meets AAA
undefined
文件： src/components/Button.tsx:23 当前代码： 
background: #4A90D2
（与白色文字对比度3.1:1） 修复方案： 
background: #2563EB
（与白色文字对比度4.8:1）—— 保持蓝色色调，符合AA标准 替代方案： 
background: #1D4ED8
（对比度7.1:1）—— 符合AAA标准
undefined

2. YAML regression test

2. YAML回归测试

yaml
- name: a11y-01-button-contrast
  description: Verify primary button meets WCAG AA contrast ratio
  severity: critical
  standard: WCAG-1.4.3-AA
  steps:
    - URL: /
    - VERIFY: Primary action buttons have sufficient color contrast (minimum 4.5:1 ratio for normal text)
      timeout_seconds: 15
Save all YAML tests to 
shiplight/tests/design-review.test.yaml
.
yaml
- name: a11y-01-button-contrast
  description: Verify primary button meets WCAG AA contrast ratio
  severity: critical
  standard: WCAG-1.4.3-AA
  steps:
    - URL: /
    - VERIFY: Primary action buttons have sufficient color contrast (minimum 4.5:1 ratio for normal text)
      timeout_seconds: 15
将所有YAML测试保存到 
shiplight/tests/design-review.test.yaml
。

Tips

提示

  • Use 
    inspect_page
    to read the DOM first — it's cheaper than screenshots and provides element indices for 
    act
    .
  • For contrast checking, use JavaScript via 
    act
    with 
    window.getComputedStyle()
    to extract actual rendered colors.
  • Test keyboard navigation by using 
    act
    with keyboard actions (Tab, Enter, Escape, Arrow keys).
  • Run this review at multiple breakpoints — many issues only appear at specific viewport sizes.
  • For i18n text expansion testing, use 
    act
    with JavaScript to modify 
    textContent
    to longer strings.
  • Close the session with 
    close_session
    and use 
    generate_html_report
    for a shareable evidence report.
  • 先使用 
    inspect_page
    读取DOM——这比截图成本更低，还能为 
    act
    提供元素索引。
  • 对比度检查时，通过 
    act
    运行JavaScript，使用 
    window.getComputedStyle()
    提取实际渲染颜色。
  • 使用 
    act
    模拟键盘操作（Tab、Enter、Escape、方向键）测试键盘导航。
  • 在多个断点运行评审——许多问题仅在特定视口尺寸下出现。
  • 国际化文本扩展测试时，使用 
    act
    通过JavaScript修改 
    textContent
    为更长的字符串。
  • 使用 
    close_session
    关闭会话，然后使用 
    generate_html_report
    生成可分享的证据报告。