review-accessibility

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Accessibility and Usability Fitness Review

无障碍与可用性适配度审查

Analyze frontend code (HTML, CSS, JavaScript, templates, components) for accessibility and usability fitness against WCAG 2.1 AA baseline and usability best practices.

Reference: Fundamentals of Software Accessibility, Fundamentals of Software Usability, Fundamentals of Color and Contrast — see also Fundamentals

根据 WCAG 2.1 AA 基线和可用性最佳实践，分析前端代码（HTML、CSS、JavaScript、模板、组件）的无障碍与可用性适配度。

参考：软件无障碍基础、软件可用性基础、颜色与对比度基础——另见基础

Domain Knowledge

领域知识

```
references/rubric.md
```
is the scoring source: severity levels, 1-10 anchors per dimension, N/A rules, and the Overall formula. Read it first; it is short. Scores taken from it are repeatable; improvised ones are not.
```
references/checklist.md
```
is what to check, file by file, with the WCAG thresholds.
```
scripts/contrast.py
```
computes contrast ratios. Every ratio in a report comes from it, because guessed ratios are the most common wrong number in accessibility reviews.
```
references/wisdom.md
```
is optional background, auto-generated from the three articles above (about 2,500 lines). Grep it by heading for a specific question (
```
grep -n "^#" references/wisdom.md
```
); never read it whole.

```
references/rubric.md
```
是评分依据：包含严重程度级别、各维度的 1-10 分锚点、N/A 规则和 Overall 计算公式。先阅读它；文件很短。依据它给出的分数具有可重复性；临时估算的分数则没有。
```
references/checklist.md
```
包含需要逐文件检查的内容以及 WCAG 阈值。
```
scripts/contrast.py
```
用于计算对比度。报告中的每个比值都应来自该脚本，因为凭猜测得出的比值是无障碍审查中最常出现的错误数值。
```
references/wisdom.md
```
是可选的背景资料，由上述三篇文章自动生成（约 2,500 行）。按标题 grep 内容（
```
grep -n "^#" references/wisdom.md
```
）；绝不要整篇读取。

Configuration

配置

Invoke the resolver CLI to obtain effective weights and thresholds for the review target. Never load

fitness-config.json

directly.

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" show --path <target>

${CLAUDE_SKILL_DIR}

is this skill's directory; the resolver ships two levels up in the plugin's

scripts/

. If your agent does not expand the variable, substitute the directory containing this

SKILL.md

Where

<target>

is the file or directory under review. The CLI walks up to discover any module override and merges it with the root config. Copy its

Config:

and

Effective weights:

lines into the report header (the template has the slots) as the provenance trail (AC-03.1, AC-08.2). Those weights rank the ten review domains for review-full; they do not weight the seven dimensions here. Use

statusThresholds

from the

effective

JSON block (between

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

and

<!-- END_EFFECTIVE_CONFIG_JSON -->

) for the status band when present.

调用 resolver CLI，获取审查目标的有效权重和阈值。绝不直接加载

fitness-config.json

。

bash

python3 "${CLAUDE_SKILL_DIR}/../../scripts/fitness-config.py" show --path <target>

${CLAUDE_SKILL_DIR}

是此 skill 的目录；resolver 随插件提供，位于上两级的

scripts/

目录中。如果你的 Agent 不会展开该变量，则替换为包含此

SKILL.md

的目录。

其中

<target>

是待审查的文件或目录。CLI 会向上遍历，发现任何模块级 override，并将它与根配置合并。将其

Config:

和

Effective weights:

行复制到报告头（模板中已有相应占位符），作为来源追踪记录（AC-03.1、AC-08.2）。这些权重用于对 review-full 的十个审查领域进行排序；它们不用于对此处的七个维度加权。如果存在

effective

JSON 区块（位于

<!-- BEGIN_EFFECTIVE_CONFIG_JSON -->

和

<!-- END_EFFECTIVE_CONFIG_JSON -->

之间），则使用其中的

statusThresholds

确定状态区间。

Modes

模式

Full review (default): all seven dimensions over the frontend surface or the diff.
Focused review: the user asks one thing, such as "check color contrast", "are my images missing alt text", or "can this menu be used by keyboard". Score only the dimension(s) asked about, mark the rest
```
N/A — not requested
```
, and answer the question in
```
## Direct Answer
```
. Skip steps that cannot affect the answer. A focused run is never a full audit, so it always writes to a scoped report path (see Output Format).

完整审查（默认）：对整个前端界面或 diff 中的全部七个维度进行审查。
聚焦审查：用户只询问一个事项，例如“检查颜色对比度”“我的图片是否缺少 alt text”或“这个菜单能否使用键盘操作”。仅对所询问的维度评分，将其余维度标记为
```
N/A — not requested
```
，并在
```
## Direct Answer
```
中回答问题。跳过不会影响答案的步骤。聚焦审查绝不等同于完整审计，因此始终写入限定范围的报告路径（见“输出格式”）。

Workflow

工作流

Load the rubric — Read
```
references/rubric.md
```
and
```
references/checklist.md
```
. Run the resolver.
Identify scope — Find the HTML templates, JSX/TSX/Vue/Svelte components, CSS, and UI JavaScript. Review changed files for a diff, the named files when the user names them, otherwise the whole frontend. Note context that lives outside scope but decides a finding (base layout with the skip link, theme files that define color tokens) and read just enough of it to reach confidence 7.
Decide applicability — For each dimension, decide whether anything in scope can show it. Mark the rest
```
N/A — <reason>
```
using the rubric's N/A rules. A placeholder score skews the Overall here and the domain average in review-full.
Run the checklist — Evaluate each file against
```
references/checklist.md
```
. Record file:line evidence for every finding. Alt text and other text alternatives belong to Screen Reader Support (what assistive technology announces), not Semantic HTML; score a missing alt once, there.
Compute contrast — When Color and Contrast applies, run the script over every stylesheet that defines or overrides the color tokens (theme and framework files included, read-only), so
```
var()
```
chains resolve:
bash
```
python3 "${CLAUDE_SKILL_DIR}/scripts/contrast.py" css <css and template files...> --fails-only
python3 "${CLAUDE_SKILL_DIR}/scripts/contrast.py" css <css files...> --pair=--muted:--card   # extra token pairs
python3 "${CLAUDE_SKILL_DIR}/scripts/contrast.py" pair '#6b5a80' '#ffffff'                # literal colors
```
Template and HTML files are read for inline
```
<style>
```
blocks.
```
--fails-only
```
still prints unresolved (
```
UNRES
```
) rows and a per-theme count, because an unchecked pair is not a pass. It reports each theme (base/light, dark, others it finds) separately, merges theme overrides per selector, checks text at 4.5:1 and borders/outlines at 3:1, and flags
```
outline: none
```
. Add
```
:3
```
to a
```
--pair
```
for a non-text check (focus backgrounds, icons). Rows marked
```
(page)
```
assume the element sits on the page background; when a rule repaints part of the page (a
```
.list
```
or card background), add
```
--pair
```
rows for the tokens drawn on it.
```
text?
```
rows are tokens that may never be used as text: confirm in the markup. When the markup or theme that would confirm a row is not available, report it only if the token's role is clear from its name or a comment, say in the finding that usage was not verified, and keep confidence at 7.
```
UNRES
```
means the script could not resolve a value (gradient,
```
currentColor
```
,
```
color-mix()
```
); check it by hand or leave it out. For colors in markup (inline styles, utility classes), resolve the hex values and use
```
pair
```
. Quote the ratio the script printed.
Score each dimension — Use the anchors in
```
references/rubric.md
```
. A score needs file:line evidence from the code.
Identify patterns — Systemic issues (a shared partial, a design token, a global CSS rule) are one finding listing every location, ranked above one-off issues.
Self-check, then write — Before writing: every file:line exists and says what the finding claims; every finding has confidence >= 7; every ratio came from the script; the Overall equals the stated computation; any CRITICAL caps it at 4.0. Then write the report.

加载评分标准——读取
```
references/rubric.md
```
和
```
references/checklist.md
```
。运行 resolver。
确定范围——查找 HTML 模板、JSX/TSX/Vue/Svelte 组件、CSS 和 UI JavaScript。如果审查 diff，则检查变更过的文件；如果用户指定了文件，则检查这些文件；否则检查整个前端。记录范围之外但会决定某项发现的上下文，例如包含跳转链接的基础布局，以及定义颜色 token 的主题文件；只读取足以将置信度提升至 7/10 的内容。
判断适用性——针对每个维度，判断范围内的内容是否能够体现该维度。使用 rubric 中的 N/A 规则，将其余维度标记为
```
N/A — <reason>
```
。占位分数会扭曲此处的 Overall 以及 review-full 中的领域平均值。
运行检查清单——逐文件对照
```
references/checklist.md
```
进行评估。为每项发现记录 file:line 证据。alt text 和其他文本替代方案属于屏幕阅读器支持（辅助技术会播报的内容），而不是语义化 HTML；缺失的 alt 只在该维度计分一次。
计算对比度——当颜色与对比度适用时，对每个定义或覆盖颜色 token 的样式表运行脚本（也包括主题和框架文件，以只读方式），从而解析
```
var()
```
链：
bash
```
python3 "${CLAUDE_SKILL_DIR}/scripts/contrast.py" css <css and template files...> --fails-only
python3 "${CLAUDE_SKILL_DIR}/scripts/contrast.py" css <css files...> --pair=--muted:--card   # extra token pairs
python3 "${CLAUDE_SKILL_DIR}/scripts/contrast.py" pair '#6b5a80' '#ffffff'                # literal colors
```
模板和 HTML 文件会被读取，以检查内联
```
<style>
```
块。
```
--fails-only
```
仍会打印未解析（
```
UNRES
```
）的行和每个主题的计数，因为未检查的配对不能算作通过。它会分别报告每种主题（base/light、dark 以及发现的其他主题），按选择器合并各主题的 override，按 4.5:1 检查文本，按 3:1 检查边框/轮廓，并标记
```
outline: none
```
。如果检查非文本内容（焦点背景、图标），则向
```
--pair
```
添加
```
:3
```
。标记为
```
(page)
```
的行假定元素位于页面背景上；当某条规则会重新绘制页面的一部分（例如
```
.list
```
或卡片背景）时，为绘制于该背景上的 token 添加
```
--pair
```
行。
```
text?
```
行对应的 token 可能永远不会作为文本使用，需要在标记中确认。当缺少可用于确认某行的标记或主题时，仅当 token 的用途可从其名称或注释明确判断时才报告该问题；在发现中说明其使用情况尚未得到验证，并将置信度保持在 7。
```
UNRES
```
表示脚本无法解析某个值（渐变、
```
currentColor
```
、
```
color-mix()
```
）；请手动检查或将其排除。对于标记中的颜色（内联样式、utility class），请解析十六进制值并使用
```
pair
```
。引用脚本打印出的比值。
为每个维度评分——使用
```
references/rubric.md
```
中的锚点。每个分数都需要代码中的 file:line 证据。
识别模式——系统性问题（共享 partial、design token、全局 CSS 规则）应合并为一条发现，列出所有位置，并排在单点问题之前。
自检后编写报告——写入之前：确认每个 file:line 都存在且确实表明发现所声称的问题；每项发现的置信度都 >= 7；每个比值都来自脚本；Overall 等于规定的计算结果；任何 CRITICAL 问题都会将总分上限设为 4.0。然后编写报告。

Confidence and Severity

置信度与严重程度

Only report findings with confidence >= 7/10. For each finding, assess:

Is this a real pattern in the code, not a guess about runtime behavior?
Can you point to a specific file and line?
Is the problematic pattern actually reachable in normal execution?

If any answer is no, do not report it. It is better to miss a theoretical issue than to flood the report with noise.

Severity levels (CRITICAL, HIGH, MEDIUM, LOW) with WCAG-mapped examples are defined in

references/rubric.md

仅报告置信度 >= 7/10 的发现。对于每项发现，评估：

这是代码中的真实模式，而不是对运行时行为的猜测吗？
能否指出具体的文件和行号？
该问题模式在正常执行过程中是否确实可以触达？

如果任何一个问题的答案为否，则不要报告。遗漏一个理论问题，好过用报告噪声淹没结果。

严重程度级别（CRITICAL、HIGH、MEDIUM、LOW）及映射到 WCAG 的示例定义于

references/rubric.md

。

Scoring Dimensions (1-10 each)

评分维度（每项 1-10 分）

Anchors for each band are in

references/rubric.md

; what to check is in

references/checklist.md

Semantic HTML — Heading hierarchy, landmark elements, form labels, correct element types, table structure
Keyboard Navigation — Tab order, focus indicators, skip links, focus trapping in modals, keyboard patterns for custom widgets
Screen Reader Support — Alt text and other text alternatives, accessible names, ARIA roles and states, live regions, error linking, hidden content management
Color and Contrast — Text contrast ratios, UI component contrast, color-independent information, focus indicator contrast, system preference respect
Progressive Enhancement — Core functionality without JS, standard form submission fallbacks, media fallbacks, prefers-reduced-motion support
Responsive Design — Viewport meta, relative units, zoom support, touch targets, breakpoint handling, text readability at all sizes
Usability Heuristics — Nielsen's 10 heuristics: system status visibility, real-world match, user control, consistency, error prevention, recognition over recall, flexibility, minimalist design, error recovery, help and documentation

各分数区间的锚点位于

references/rubric.md

；需要检查的内容位于

references/checklist.md

。

语义化 HTML——标题层级、地标元素、表单标签、正确的元素类型、表格结构
键盘导航——Tab 顺序、焦点指示器、跳转链接、模态框中的焦点陷阱、自定义 widget 的键盘模式
屏幕阅读器支持——alt text 和其他文本替代方案、可访问名称、ARIA role 和 state、live region、错误关联、隐藏内容管理
颜色与对比度——文本对比度、UI 组件对比度、不依赖颜色的信息传达、焦点指示器对比度、对系统偏好的遵循
渐进增强——无 JS 时的核心功能、标准表单提交回退机制、媒体回退机制、prefers-reduced-motion 支持
响应式设计——viewport meta、相对单位、缩放支持、触控目标、断点处理、各种字号下的文本可读性
可用性启发式方法——Nielsen 的 10 条启发式方法：系统状态可见性、与真实世界匹配、用户控制、一致性、错误预防、识别优于回忆、灵活性、极简设计、错误恢复、帮助与文档

Output Format

输出格式

Write the report to

docs/accessibility-review.md

at the root of the repository that contains the target, unless the user gives a path. For a review scoped to a subdirectory or a file set, or a focused review, write

docs/accessibility-review-<scope-slug>.md

instead, where the slug is the focused topic or the scope's directory/file names in kebab-case, at most 40 characters (for example

docs/accessibility-review-color-contrast.md

docs/accessibility-review-layouts-partials.md

), so a partial run never replaces the whole-repo report that review-full reads.

markdown

undefined

除非用户指定路径，否则将报告写入包含目标的仓库根目录下的

docs/accessibility-review.md

。对于范围限定为某个子目录或文件集的审查，或聚焦审查，改写为

docs/accessibility-review-<scope-slug>.md

，其中 slug 是聚焦主题或范围目录/文件名的 kebab-case，最长 40 个字符（例如

docs/accessibility-review-color-contrast.md

或

docs/accessibility-review-layouts-partials.md

），从而避免局部审查覆盖 review-full 读取的全仓库报告。

markdown

undefined

Accessibility and Usability Review

Target: <path(s) or scope reviewed; "focused: <topic>" for a focused review> Config: <copied from resolver output> Effective weights: <copied from resolver output>

Direct Answer

(Whenever the user asked a specific question, in either mode — "what fails AA?", "is the contrast OK?": answer it in 1-3 sentences, with the numbers. Omit the section otherwise.)

Summary

Dimension	Score	Key Finding
Semantic HTML	X/10 or N/A — reason	...
Keyboard Navigation	X/10 or N/A — reason	...
Screen Reader Support	X/10 or N/A — reason	...
Color/Contrast	X/10 or N/A — reason	...
Progressive Enhancement	X/10 or N/A — reason	...
Responsive Design	X/10 or N/A — reason	...
Usability Heuristics	X/10 or N/A — reason	...
Overall	X.X/10 (status)	Mean of <dimensions scored>; capped at 4.0 if any CRITICAL

Dimension	Score	Key Finding
Semantic HTML	X/10 or N/A — reason	...
Keyboard Navigation	X/10 or N/A — reason	...
Screen Reader Support	X/10 or N/A — reason	...
Color/Contrast	X/10 or N/A — reason	...
Progressive Enhancement	X/10 or N/A — reason	...
Responsive Design	X/10 or N/A — reason	...
Usability Heuristics	X/10 or N/A — reason	...
Overall	X.X/10 (status)	Mean of <dimensions scored>; capped at 4.0 if any CRITICAL

Detailed Findings

Finding 1: [Title]

Severity: CRITICAL / HIGH / MEDIUM / LOW
Confidence: X/10
Dimension: [which scoring dimension]
WCAG: [success criterion, e.g. 1.4.3 Contrast (Minimum)]
Location: file:line (every location, for systemic issues)
Description: What the issue is and why it matters.
Evidence: The specific code pattern found (and the computed ratio, for contrast).
Impact: What users are affected and how.
Remediation: Concrete fix with code example or specific steps.

(repeat for each finding, ordered by severity)

Severity: CRITICAL / HIGH / MEDIUM / LOW
Confidence: X/10
Dimension: [which scoring dimension]
WCAG: [success criterion, e.g. 1.4.3 Contrast (Minimum)]
Location: file:line (every location, for systemic issues)
Description: What the issue is and why it matters.
Evidence: The specific code pattern found (and the computed ratio, for contrast).
Impact: What users are affected and how.
Remediation: Concrete fix with code example or specific steps.

(repeat for each finding, ordered by severity)

Contrast Table

(When Color/Contrast was scored: the failing pairs and the main text pairs per theme, copied from contrast.py output: theme, foreground, background, ratio, required, result, file:line. List UNRES pairs as "not verified".)

Dimension Details

[Dimension Name] (X/10)

Evidence: file:line references
Issues found
Recommendations

Evidence: file:line references
Issues found
Recommendations

...

Top Action Items (by impact, up to 5)

[CRITICAL/HIGH/MEDIUM] Description -- file:line
...

[CRITICAL/HIGH/MEDIUM] Description -- file:line
...

Checklist Reference

See references/checklist.md for the full accessibility checklist used in this review.

Reference

Based on Fundamentals of Software Accessibility, Fundamentals of Software Usability, Fundamentals of Color and Contrast, and guidance from https://jeffbailey.us/categories/fundamentals/


Prioritize action items by: severity of user impact, number of users affected, and effort to fix. Systemic issues rank above one-off issues. Fewer than five is fine.

WCAG 2.1 AA is the baseline standard. Note any findings that would additionally meet or fail AAA criteria, but do not require AAA for a passing score.

Based on Fundamentals of Software Accessibility, Fundamentals of Software Usability, Fundamentals of Color and Contrast, and guidance from https://jeffbailey.us/categories/fundamentals/


按以下因素确定行动项的优先级：用户影响的严重程度、受影响用户数量以及修复成本。系统性问题应排在单点问题之前。少于五项也没有问题。

WCAG 2.1 AA 是基线标准。请注明哪些发现还会达到或不符合 AAA 标准，但不要将 AAA 作为通过评分的必要条件。