accessibility-inspect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

This is the semi-automated manual tier of a WCAG assessment: the checks that need interaction (keyboard, focus, state changes, reflow) or human review (focus visibility, error recovery, reading order), which a static rule engine can't decide. Work against the running page; use source only to map a finding to

file:line

. Locate and assess — don't fix (that's

accesslint:accessibility-fix

). The automated tier is

accesslint:accessibility-scan

;

accesslint:accessibility-audit

runs both under WCAG-EM.

The shared rules — severity, the no-proxy boundary, high-risk patterns, conformance, grounding — are in

../shared/methodology.md

. Read it when a call needs judgment. The rules that always apply are below.

这是WCAG评估的半自动手动层级：需要交互（键盘、焦点、状态变化、重排）或人工审查（焦点可见性、错误恢复、阅读顺序）的检查项，这些都是静态规则引擎无法判定的。基于运行中的页面开展工作；仅使用源代码将检查结果映射到

file:line

。仅定位和评估问题——不进行修复（修复需使用

accesslint:accessibility-fix

）。自动化评估层级为

accesslint:accessibility-scan

；

accesslint:accessibility-audit

会在WCAG-EM框架下同时运行这两个层级。

共享规则——严重程度、无代理边界、高风险模式、合规性、依据——位于

../shared/methodology.md

。当需要做出判断时，请阅读该文档。以下是始终适用的规则。

Grading

评级规则

Tag each finding with a severity (user impact) and an evidence basis (what you can support). Keep the two separate.

● Verified — deterministic and reproducible. Cite the selector, the interaction, and the observed a11y-tree or DOM fact. Without that proof it is not ●.
◐ Flagged — you have evidence, but the decision needs a person. Attach the evidence and your opinion; don't decide it yourself.
○ Human-required — needs assistive technology or lived experience. Hand it off; don't emulate it.

When unsure between two evidence grades, use the lower one. The icons show evidence basis by fill, not color.

A finding that stacks a deterministic fact on an interpretive call takes the lower grade. The machine-checkable half (e.g. no programmatic status in the a11y tree — a 1.3.1 fact) is ● evidence inside a ◐ finding; the interpretive conclusion (e.g. that color is the sole carrier of the meaning — 1.4.1) stays ◐. Citing the ● half does not upgrade the whole.

Severity (user impact, separate from evidence basis):

Critical — blocks a core task, with no workaround.
Serious — a major barrier; the task is possible but difficult.
Moderate — noticeable friction; the task still completes.
Minor — a small inefficiency or polish issue.

为每个检查结果标记严重程度（用户影响）和证据基础（可支持的依据），两者需分开记录。

● 已验证——确定性且可复现。需引用选择器、交互操作以及观察到的无障碍树或DOM事实。若无此类证明，则不能标记为●。
◐ 标记——已有证据，但最终判定需人工确认。附上证据和你的观点，不要自行做出最终决定。
○ 需人工评估——需要辅助技术或实际使用经验。移交相关任务，不要自行模拟。

若不确定应选择哪一级证据基础，请选择较低的等级。图标通过填充程度而非颜色区分证据基础。

若某个检查结果同时包含确定性事实和解释性判断，需采用较低的评级。机器可检查的部分（例如无障碍树中无程序化状态——符合1.3.1事实）在◐级检查结果中属于●级证据；但解释性结论（例如颜色是唯一的含义载体——符合1.4.1）仍为◐级。引用●级证据部分不会提升整体评级。

严重程度（用户影响，与证据基础分开）：

关键——阻碍核心任务，无替代方案。
严重——主要障碍；任务可完成但难度极大。
中等——存在明显阻碍；任务仍可完成。
轻微——小范围低效或优化问题。

The ledger — a denominator, not a script

台账——统计基准，而非执行脚本

The checkpoint areas below are the run's denominator: every criterion in them ends the run in exactly one state, and the report says which.

● verified or ◐/○ flagged — you drove the check and have the evidence.
N/A — the triggering feature isn't on the page (no form, no media, no drag UI). Decided from the snapshot; free.
Not exercised — the feature is present but you didn't drive it. Reported as undetermined, never silently dropped, and never as a pass.

Not-exercised is a legitimate, honest outcome and it costs nothing. Drive only what the page's features and the engine's gaps demand; don't work through checkpoints to make the report look thorough. An "undetermined — not exercised" line and a driven-and-verified line differ in evidence, not in honesty.

Dedup before driving, not after: the engine (

accessibility-scan

) owns the statically-detectable criteria — name/label presence,

lang

autocomplete

, semantic markup, contrast of text on flat backgrounds. If a scan result set or engine-owned SC list was provided (as

accessibility-audit

does), never re-check those criteria; ledger them as engine-owned. Without one, read what you can from the initial snapshot rather than re-deriving what the engine would catch.

Area	SCs	Trigger to drive
Keyboard & focus	2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11	Always — one batched walk (below)
Structure & semantics	1.3.1, 1.3.2, 2.4.1, 2.4.6	Always — read from the initial snapshot; no extra driving
Names, roles, states	4.1.2, 2.5.3, 4.1.3	Custom widgets / stateful controls present (static name presence is engine-owned)
Visual adaptation	1.4.1, 1.4.4, 1.4.10, 1.4.12, 1.3.4, 2.3.3, 1.4.11	Reflow/zoom on every page (one resize each); motion checks only if motion is present
Forms & errors	3.3.1–3.3.3, 1.3.5, 3.3.7, 3.3.8	A form is present (label/ `autocomplete` presence is engine-owned)
Media & timing	1.2.x, 2.2.1, 2.2.2	`<video>` / `<audio>` , autoplay, or timeouts present
Pointer & target	2.5.1, 2.5.7, 2.5.8	Target size comes free from the batched walk; drag checks only if drag UI
Content & navigation	3.1.1/2, 2.4.4, 3.2.3/4, 3.2.6	`lang` and link purpose from the snapshot; cross-page consistency is `accessibility-audit` 's (not exercised here)

Per-checkpoint procedure and default grades:

references/checkpoints.md

. Read it when a triggered area needs its detailed steps, or when the user asks for a deep pass (

--deep

: drive every triggered area through its full procedure).

以下检查点领域是评估的统计基准：其中的每个标准在评估结束时都会处于唯一状态，报告中会明确说明。

● 已验证 或 ◐/○ 标记——你已完成该检查并具备相关证据。
不适用（N/A）——页面上不存在触发该检查的功能（无表单、无媒体、无拖拽UI）。基于快照判定；无需额外操作。
未执行——页面存在该功能，但你未进行测试。报告为未确定，不得静默忽略，也不得标记为通过。

未执行是合理且诚实的结果，无需额外投入精力。仅根据页面功能和引擎的空白点开展测试；不要为了让报告看起来全面而逐一检查所有检查点。「未确定——未执行」记录与「已执行并验证」记录的区别在于证据，而非诚实性。

在开始测试前进行去重：静态可检测的标准——名称/标签存在性、

lang

属性、

autocomplete

属性、语义化标记、纯色背景文本的对比度——由引擎（

accessibility-scan

）负责。若提供了扫描结果集或引擎负责的SC列表（如

accessibility-audit

所做的），请勿重新检查这些标准；将其记录为引擎负责项。若未提供此类列表，请从初始快照中读取尽可能多的信息，而非重复引擎可检测的内容。

领域	标准（SCs）	触发测试的条件
键盘与焦点	2.1.1, 2.1.2, 2.4.3, 2.4.7, 2.4.11	始终触发——一次性批量遍历（如下所述）
结构与语义	1.3.1, 1.3.2, 2.4.1, 2.4.6	始终触发——从初始快照读取；无需额外操作
名称、角色、状态	4.1.2, 2.5.3, 4.1.3	存在自定义组件/有状态控件（静态名称存在性由引擎负责）
视觉适配	1.4.1, 1.4.4, 1.4.10, 1.4.12, 1.3.4, 2.3.3, 1.4.11	每个页面都需进行重排/缩放测试（各一次）；仅当存在动画时才进行动画检查
表单与错误	3.3.1–3.3.3, 1.3.5, 3.3.7, 3.3.8	页面存在表单（标签/ `autocomplete` 属性存在性由引擎负责）
媒体与计时	1.2.x, 2.2.1, 2.2.2	存在 `<video>` / `<audio>` 、自动播放或超时功能
指针与目标	2.5.1, 2.5.7, 2.5.8	目标尺寸可通过批量遍历自动获取；仅当存在拖拽UI时才进行拖拽检查
内容与导航	3.1.1/2, 2.4.4, 3.2.3/4, 3.2.6	从快照读取 `lang` 属性和链接用途；跨页面一致性检查由 `accessibility-audit` 负责（此处不执行）

每个检查点的流程和默认评级：

references/checkpoints.md

。当触发的领域需要详细步骤，或用户要求深度检查（

--deep

：对每个触发领域执行完整流程）时，请阅读该文档。

Evidence budget — cap spend by grade

证据成本控制——按评级限制投入

Calibrated uncertainty must be cheaper than false certainty. The grade a finding can reach bounds the evidence worth gathering:

● — full proof, gathered once: selector, interaction, observed DOM or a11y-tree fact. Don't repeat an interaction you already recorded.
◐ — hard cap: one selector, one screenshot (only if the question is visual), your opinion, and what a person should confirm. Then stop. A ◐ is re-decided by a human whichever way you lean; more evidence doesn't upgrade it to ●, it just costs more.
○ — zero driving: name the functional ability, the assistive technology, and the flow you already exercised. Never drive the page to "strengthen" a ○.

可控的不确定性必须比错误的确定性成本更低。检查结果的评级决定了值得收集的证据范围：

●——完整证据，收集一次即可：选择器、交互操作、观察到的DOM或无障碍树事实。无需重复已记录的交互操作。
◐——严格限制：一个选择器、一张截图（仅当问题涉及视觉时）、你的观点，以及需人工确认的内容。然后停止。无论你倾向于哪种结论，◐级结果都需人工重新判定；更多证据无法将其升级为●级，只会增加成本。
○——无需操作：说明所需的功能能力、辅助技术以及你已执行的流程。切勿为了“强化”○级结果而操作页面。

Prerequisite: a browser to drive

前提：可操控的浏览器

This tier runs through a browser MCP:

chrome-devtools

(recommended),

playwright

, or

puppeteer

. If none is connected, run only the static checks, report the rest as ○ handoffs, and tell the user:

bash

claude mcp add chrome-devtools npx -- -y chrome-devtools-mcp@latest

该层级通过浏览器MCP运行：

chrome-devtools

（推荐）、

playwright

或

puppeteer

。若未连接任何浏览器，仅运行静态检查，其余结果标记为○级移交任务，并告知用户：

bash

claude mcp add chrome-devtools npx -- -y chrome-devtools-mcp@latest

Target

目标对象

$ARGUMENTS

is a URL, an

accesslint.config.json

target name, or empty for the default target.

--selector <css>

scopes to a component;

--wait-for <css>

waits for async content.

navigate_page

needs a URL, so resolve first:

A URL: use it.
A target name or empty: read
```
accesslint.config.json
```
(and the gitignored
```
accesslint.config.local.json
```
overlay) and resolve the name (or
```
default
```
) to its
```
url
```
; also take its
```
waitFor
```
and
```
selector
```
.
No config: ask for a URL, or suggest
```
npx @accesslint/cli init
```
.

Then navigate to the URL and wait for the gate (

--wait-for

if given, otherwise the target's

waitFor

) before testing.

$ARGUMENTS

可为URL、

accesslint.config.json

中的目标名称，或留空以使用默认目标。

--selector <css>

用于限定组件范围；

--wait-for <css>

用于等待异步内容加载。

navigate_page

需要URL，因此需先解析：

若为URL：直接使用。
若为目标名称或留空：读取
```
accesslint.config.json
```
（以及被Git忽略的
```
accesslint.config.local.json
```
覆盖配置），将名称（或
```
default
```
）解析为对应的
```
url
```
；同时获取其
```
waitFor
```
和
```
selector
```
配置。
若无配置：请求用户提供URL，或建议执行
```
npx @accesslint/cli init
```
。

然后导航至该URL，并在测试前等待 gate（若指定

--wait-for

则使用该配置，否则使用目标的

waitFor

配置）加载完成。

Driving efficiently

高效测试方法

One snapshot, then scoped reads. Take one full snapshot after the wait gate; it is the basis for structure, names, roles, states, and the N/A decisions. After a state change, don't re-snapshot the page — read only the widget that changed, via

evaluate_script

scoped to its selector (or a snapshot of that subtree). A full-page re-snapshot per interaction is the single largest avoidable cost in this tier.

One batched keyboard walk. Traverse focus in a single

evaluate_script

call, not one

press_key

/snapshot cycle per stop: compute the tabbable sequence,

focus()

each element in order, and return compact JSON per stop — selector, role/name,

document.activeElement

confirmation, computed

outline

box-shadow

:focus

, bounding box (which settles 2.5.8 for free), and whether the element sits under a sticky/overlay rect (2.4.11). The walk is deterministic DOM fact, so its results are ●-citable.

The walk finds candidates; real key events confirm behavior. Scripted

focus()

doesn't run an app's keydown handlers, so operability (

Enter

Space

/arrows) and trap claims still need

press_key

— but only at the walk's suspects: composite widgets (roving tabindex,

aria-activedescendant

), elements whose handlers plausibly capture Tab/Esc, anything the walk couldn't reach. A ● keyboard-trap finding needs the real

Tab

Esc

presses at that widget; it doesn't need them at every widget on the page.

**一次快照，然后按需读取。**等待gate加载完成后拍摄一次完整快照；该快照作为结构、名称、角色、状态以及不适用（N/A）判定的基础。状态变化后，无需重新拍摄页面快照——仅通过

evaluate_script

读取发生变化的组件（限定其选择器，或拍摄该子树的快照）。每次交互都重新拍摄全页快照是该层级中最大的可避免成本。

**一次批量键盘遍历。**通过单次

evaluate_script

调用遍历焦点，而非每次停止都执行

press_key

/快照循环：计算可切换焦点的序列，依次对每个元素执行

focus()

，并返回每个停止点的精简JSON数据——选择器、角色/名称、

document.activeElement

确认结果、

:focus

状态下的计算

outline

box-shadow

、边界框（可自动完成2.5.8标准检查），以及元素是否位于粘性/覆盖矩形下方（2.4.11标准）。遍历结果是确定性的DOM事实，因此可作为●级证据引用。

遍历会找出候选元素；真实按键事件可确认行为。脚本化的

focus()

不会触发应用的keydown处理程序，因此可操作性（

Enter

Space

/箭头键）和焦点陷阱声明仍需通过

press_key

验证——但仅需在遍历发现的疑似元素上执行：复合组件（roving tabindex、

aria-activedescendant

）、处理程序可能捕获Tab/Esc的元素、遍历无法触及的任何元素。●级焦点陷阱检查结果需要在该组件上执行真实的

Tab

Esc

按键操作；无需在页面上的每个组件都执行该操作。

High-risk patterns

高风险模式

For drag-and-drop, rich-text editors, tree views, data grids, custom comboboxes or menus, carousels, and toast or live-region-heavy UIs, heuristic checks are unreliable. Name the APG pattern, verify what you can (●/◐), and hand off the rest as ○ with the assistive-technology steps to run. Use

explain_rule

for engine rules and the APG for widget contracts.

对于拖拽、富文本编辑器、树视图、数据网格、自定义组合框或菜单、轮播图，以及大量使用提示框或实时区域的UI，启发式检查不可靠。明确APG模式，验证可确认的内容（●/◐），其余部分标记为○级并附上需运行的辅助技术步骤。使用

explain_rule

获取引擎规则，使用APG获取组件规范。

Report

报告

Group findings by evidence basis; mark severity inline. Close the ledger at the top — every SC in the denominator lands in exactly one bucket — and keep it compact: counts, then bare SC numbers. Group not-exercised SCs by shared reason, one parenthetical clause per group, never a line per SC.

The report spends its words on failures, flags, and handoffs. A pass is its SC number in the ledger — not a paragraph: no "what passed" narration beyond at most one sentence, and no restating in the recommendations a fix already given on its finding.

undefined

按证据基础分组检查结果；在结果内标记严重程度。报告顶部需完成台账记录——统计基准中的每个SC都需归入唯一的分类——并保持简洁：统计数量，然后列出SC编号。按共同原因分组未执行的SC，每组用一个括号说明原因，切勿为每个SC单独一行。

报告需重点描述失败、标记和移交任务。通过的标准只需在台账中列出SC编号——无需段落说明：最多用一句话简述“通过项”，且不要在建议部分重复已在检查结果中给出的修复方案。

undefined

Manual inspection — <target> · semi-automated tier

手动检查 — <target> · 半自动层级

Severity: <c> critical · <s> serious · <m> moderate Basis: ● <v> · ◐ <f> · ○ <h> Ledger: pass ● <SCs> · fail ● <SCs> · flagged ◐/○ <SCs> · engine-owned <SCs> · N/A <SCs> not exercised → undetermined: <SCs (shared reason)> · <SCs (shared reason)>

严重程度：<c> 关键 · <s> 严重 · <m> 中等证据基础：● <v> · ◐ <f> · ○ <h> 台账：通过 ● <SCs> · 失败 ● <SCs> · 标记 ◐/○ <SCs> · 引擎负责 <SCs> · 不适用 <SCs> 未执行 → 未确定：<SCs (共同原因)> · <SCs (共同原因)>

● Verified

● 已验证

[serious] Keyboard trap in date picker — SC 2.1.2 where: div.datepicker[role=dialog] repro: Tab into grid, focus never exits via Tab or Esc fix: <mechanical> | NEEDS HUMAN

[严重] 日期选择器存在焦点陷阱 — SC 2.1.2 位置：div.datepicker[role=dialog] 复现步骤：按Tab键进入网格，焦点无法通过Tab或Esc键退出修复：<机械修复> | 需人工确认

◐ Flagged

◐ 标记

[moderate] Focus indicator may be too faint — SC 2.4.7 where: button.ghost evidence: focus-ghost.png; outline = 1px rgba(0,0,0,.2) opinion: likely fails 3:1 non-text contrast — confirm visually

[中等] 焦点指示器可能过于微弱 — SC 2.4.7 位置：button.ghost 证据：focus-ghost.png; outline = 1px rgba(0,0,0,.2) 观点：可能不符合3:1的非文本对比度要求 — 需人工视觉确认

○ Human-required

○ 需人工评估

Live-region announcement on add-to-cart — SC 4.1.3 aria-live="polite" present (●); actual NVDA/JAWS/VoiceOver output unverified needs: screen-reader users (blind / low-vision, per Section 508 FPC) flow: add-to-cart → toast (exercised above)


Ground each entry by selector and visible text. Add `file:line (symbol)` only when `accessibility-scan`'s source maps provide it; don't guess. Each ○ entry is a handoff: the functional ability and assistive technology needed, plus the flow you exercised.

加入购物车时的实时区域通知 — SC 4.1.3 已存在aria-live="polite"（●）；实际NVDA/JAWS/VoiceOver输出未验证需求：屏幕阅读器用户（盲/低视力，符合Section 508 FPC）流程：加入购物车 → 提示框（已执行上述操作）


每个条目需通过选择器和可见文本明确依据。仅当`accessibility-scan`的源映射提供`file:line (symbol)`时才添加该信息；切勿猜测。每个○级条目都是移交任务：说明所需的功能能力和辅助技术，以及已执行的流程。

Notes

注意事项

The a11y tree shows machine state, not what a screen reader announces.
```
aria-live
```
being present does not mean it announces.
Browser zoom isn't exposed; CSS-zoom approximations are ◐.
Wait for async content before the initial snapshot; after that, prefer selector-scoped reads over re-snapshots.
Composing the tiers (dedup against
```
accessibility-scan
```
, one shared browser) is
```
accessibility-audit
```
's job. On its own, this skill reports what its checks find — and its ledger says what they didn't.

无障碍树显示的是机器状态，而非屏幕阅读器实际播报的内容。存在
```
aria-live
```
属性并不意味着会播报内容。
浏览器缩放比例无法暴露；CSS缩放近似值属于◐级。
初始快照前需等待异步内容加载；之后，优先选择限定选择器的读取方式，而非重新拍摄快照。
整合两个层级（与
```
accessibility-scan
```
去重、共享一个浏览器）是
```
accessibility-audit
```
的职责。单独使用该技能时，仅报告其检查发现的内容——台账会说明未检查的部分。