bug-reporting

无障碍缺陷报告技能

权威来源：mgifford/ACCESSIBILITY.md 中的 examples/ACCESSIBILITY_BUG_REPORTING_BEST_PRACTICES.md 此技能根据该文件整理。如有疑问，以示例为准。

在提交、审查或生成来自任何来源的无障碍缺陷报告时，请遵循以下规则，包括自动化工具输出、手动测试、用户报告或与残障人士一起进行的测试。

---

核心要求

一份有用的报告能让他人了解障碍、识别受影响的人群、尽可能复现问题、判断其影响、找出问题来源，并验证修复是否有效。并非每项发现都适用于所有字段——不要因为无法提供选择器、工具规则、WCAG 对应关系或代码级修复方案而延迟提交有效报告。

原则：

1. 先描述障碍，再说明标准——说明哪些任务或交互无法完成，以及在什么条件下无法完成
2. 指出受影响的人群——在证据支持的情况下，描述访问需求、交互方式或辅助技术；绝不推断诊断结果，也不要暗示一个人代表整个残障群体
3. 说明证据依据——区分用户报告、与残障人士一起进行的测试、手动评估、自动化结果和基于推理的推断
4. 将观察到的事实与假设、疑似原因和建议的修复方案分开记录
5. 采用互补的测试方法——自动化测试、手动测试和与残障人士一起进行的测试回答的是不同问题，彼此不能替代
6. 只收集相关上下文——只有在会影响结果时，才需要记录浏览器、辅助技术、视口或偏好设置
7. 保护人员与系统——从所有附件中删除个人数据、凭据、令牌和私人内容
8. 将工具输出视为证据，而非符合性结论
9. 区分严重程度与优先级——任务影响和变通方案的效果决定严重程度；受影响范围、发生频率、截止期限和业务背景决定优先级
10. 尽可能修复问题源头——修复共享组件、模板或令牌通常比针对多个页面分别打补丁更安全
11. 以验证证据结尾——仅有代码更改、自动化测试通过或视觉检查，并不能证明面向用户的障碍已消除

---

术语

术语	含义
发现项	观察到或疑似存在的无障碍障碍或测试结果
问题	正在跟踪的工作，可能包含一个或多个相关发现项
出现位置	发现项出现的某个位置或状态
根本原因	导致一个或多个出现位置的来源（例如，共享组件）
受影响的人群	已确认或合理预计其任务或体验会受到影响的人群——描述的具体程度不得超出证据所能支持的范围
手动无障碍评估	使用相关输入、设置或辅助技术进行的人工评估——不同于与残障人士一起进行的测试
与残障人士一起进行的测试	由残障参与者执行具有代表性的任务，并提供基于亲身经历的证据
符合性结论	针对明确范围、标准、等级和评估方法得出的结论

**自动化规则未通过，并不自动证明违反了 WCAG；自动化规则通过，也不能证明符合要求。**在作出符合性声明之前，请先确认结果及其适用范围。

---

严重程度等级（本技能）

严重程度	定义
阻断级	核心任务无法完成，或存在严重的安全、隐私或数据丢失风险，且没有合理的解决方法
重大	任务失败、不可靠，或需要大幅变通
中等	任务仍可完成，但需要付出大量额外努力或寻求协助
轻微	局部操作不便，但不会实质性妨碍任务
待审查	尚未确认结果或影响

这只是一个示例等级，并非通用标准——应与残障人士和产品团队在本地校准，并记录本地定义。

严重程度、优先级、影响范围、发生频率和置信度回答的是不同的问题——不要混为一谈：

字段	问题
严重程度	在本次发生时，对任务造成的后果有多严重？
优先级	团队应何时处理？
影响范围	可能有多少人、页面或组件受到影响？
发生频率	这种情况出现得有多频繁？
置信度	对发现、影响或成因的理解有多确定？

发生频率和影响范围可以提高优先级，但不会改变单次发生的严重程度——不要仅仅因为低严重程度的问题出现在许多页面上，就自动将其升级为更高严重程度；应将其记录为优先级因素。

---

关键：有用报告所需的最低信息

报告在接收时可以有效，但尚未达到修复所需的完整程度——两者的要求不同。不要因为用户缺少技术细节就拒绝其报告；分诊人员之后会收集定位信息、标准映射和验证计划。完整的阶段模型请参阅下文的可执行发现与可复现性。

有效的初始报告只需包含：标题、位置／状态（尽可能准确且安全地提供）、任务及影响、实际结果、证据依据。

用于评估和修复的附加字段——由分诊人员收集，而非要求报告者提供：

字段	记录内容
标题	组件／位置、故障和对任务的影响
位置和状态	安全的 URL／路由、组件名称、构建版本，以及问题出现时的状态
受影响的人群	已确认或可能受影响的无障碍需求／交互方式／辅助技术（AT）；相关时列出多个群体
证据依据和置信度	用户报告／与残障人士共同测试／手动评估／自动化结果／有理有据的推断，以及不确定性
任务和影响	用户尝试完成什么、障碍如何影响任务、变通方法的质量／成本
步骤或条件	最短的可靠操作路径，包括前置条件
预期结果	应出现的面向用户的行为
实际结果	观察到的情况，包括相关的辅助技术输出
环境	仅记录会影响结果的浏览器／操作系统／辅助技术／输入方式／视口／缩放／偏好设置／区域设置
证据	有帮助时，提供少量经过脱敏的摘录或可访问的附件

---

关键：编写具体的标题

指出组件、故障和后果。

良好示例： 结账：银行卡错误文本未与输入框关联 / 账户菜单：打开的对话框中，键盘焦点移到了对话框后方

避免使用： 无障碍问题、屏幕阅读器故障、WCAG 不符合项——这些标题没有指出受影响的行为。标题中可以包含 WCAG 标准条款，但不是必需的；报告应让不了解条款编号的人也能看懂。

---

重要：安全记录位置和状态

Page or route: /checkout/payment
Build or commit: 2026.07.18.2
Component: Payment form
UI state: Form submitted with an invalid card number
Account role: Test customer

仅当查询参数或片段值相关且可安全分享时，才使用精确 URL。请删除或替换会话标识符、访问令牌、电子邮件地址、姓名、账号及其他机密或个人数据：

Unsafe: https://example.com/orders/847291?token=secret-value
Safe:   https://example.com/orders/[test-order-id]

切勿包含生产凭据——请通过组织的安全流程提供获批的测试账号。

**元素定位器：**从易于理解的组件名称和位置开始；如果有帮助，再添加稳定的技术定位器（[data-component="cookie-settings"] [data-action="close"]、工具原生选择器、无障碍树路径、测试 ID 或简短 XPath）。不应强制要求提供完整的绝对 DOM XPath——当包装元素、列表位置或生成的标记发生变化时，绝对路径很脆弱。如果没有可靠的定位器，请描述可见标签、无障碍名称、角色、附近的标题以及交互状态。相关时，请记录 iframe／shadow root 边界。

---

重要：前置条件和复现步骤

仅列出重现故障所需的步骤，包括相关的输入方式和 AT 命令：

Preconditions:
- Signed in as a test customer
- Cart contains one item
- NVDA is running with Firefox

Steps:
1. Open the checkout payment step.
2. Leave the card number empty.
3. Move to the Submit order button with Tab.
4. Activate the button with Enter.
5. Listen for feedback without moving focus.

对于间歇性问题，请记录复现次数、时序／网络／加载条件以及已知的最早受影响构建。“无法复现”是一种分诊状态，并不能证明报告无效——请保留原始条件。

---

重要：分别说明预期结果和实际结果

将预期行为写成结果，而非要求采用特定实现：

Expected:
After submission, the card number error is associated with the field. When
focus moves to the field, its label, invalid state, and error are available.

Actual:
The visible error appears, but the card number field has no programmatic error
association. When focus moves to the field, NVDA announces only its label.

除非产品规范要求采用特定实现，否则请勿在预期结果中指定某个 ARIA 属性或 JS 方法——请将可能的代码更改放在“建议修复”部分。

---

重要：确定受影响人群——切勿猜测诊断

请将障碍与相关人群及其任务联系起来，而不只是描述技术缺陷或工具规则。仅在证据支持时，根据人们的访问需求／交互方式／AT 描述他们；不要猜测诊断、要求披露诊断，也不要暗示残障群体中的每个人都有相同的体验。

证据状态	含义
受影响者报告或确认	残障人士报告了该问题，或在残障参与者执行任务时观察到该问题
通过人工评估观察到	评估者使用相关方法／设置／AT 复现了该问题——这是行为证据，但不等同于与残障人士共同测试
可能受影响	可合理推断受影响人群及其影响，但尚未向受影响者确认
未知或需要审核	来自自动化或技术检查；尚未确定对用户的影响

有用：“可能会影响使用屏幕阅读器的人，包括部分盲人和低视力人士。使用 NVDA 和 Firefox 进行人工评估时发现，提交失败未被播报。该影响尚未通过与残障参与者共同测试予以确认。”

无用：“这会影响盲人并违反 WCAG。”

报告可以指出多个受影响人群——不要假定 WCAG 准则或自动化规则与残障群体之间存在一一对应关系。

---

严重：仅记录相关环境

只有描述了导致该结果的条件时，环境列表才有用——不要在每个问题中都粘贴通用的浏览器／AT 矩阵：

Test date and time: 2026-07-18 14:30 EDT
Browser: Firefox 140
Operating system: Windows 11 24H2
Assistive technology: NVDA 2026.1
Input: Keyboard
Viewport: 1280 by 720 CSS pixels
Zoom or text size: 200% text size
Color scheme: Dark
Forced colors: Active
prefers-reduced-motion: reduce
prefers-contrast: more
Locale and language: en-CA

请使用实际测试的值——不要根据视口宽度断点推断设备类型；视口、输入能力、浏览器、操作系统和实体设备是相互独立的信息。相关的 CSS 偏好值：prefers-color-scheme（light/dark）、prefers-reduced-motion（reduce/no-preference）、prefers-contrast（more/less/custom/no-preference）、forced-colors（active/none）。

---

严重：添加技术证据，但不要暴露数据

如果观察到的行为已经很明确，技术证据并非必需。 自动化发现和技术发现通常需要提供一段有针对性的 HTML/DOM/ 无障碍树/组件摘录，之后才能进行代码级修复—— 由分诊人员收集，而不是报告者。 残障人士或其他 报告者可能不知道如何截取这类内容；在受理报告前要求提供这些内容， 恰恰会将最有可能发现障碍的人排除在外。不要假设源 HTML 能代表实时 DOM 或无障碍树——客户端渲染和水合可能导致它们不一致；如果发现取决于运行时状态，请截取实时 DOM/ 无障碍树的输出。

<label for="card-number">Card number</label>
<input id="card-number" name="card-number">
<p id="card-number-error">Enter a card number.</p>

说明该摘录展示了什么——此处展示的是，可见错误没有以编程方式与字段关联。不要假设摘录显示了完整的计算后无障碍树。

**分享 HTML、DOM 快照、日志或屏幕截图前，请删除：**令牌/ Cookie/隐藏凭据；姓名/地址/账户数据；私人表单字段 值；不必要的内部 URL 或 ID。对于屏幕截图/录屏： 在问题文本中描述相关内容；使用箭头/标记并配上 文字，不要只依赖颜色；为视频/音频提供字幕/文字稿；裁剪或遮挡面部/姓名/私人内容。

---

严重：标准、规则和测试结果

WCAG 映射——已知时，记录确切的版本、成功标准和等级； 不确定时使用 suspected/needs review；不要仅仅因为工具将某些标准列为标签就添加它们：

Standard: WCAG 2.2
Success Criterion: 1.3.1 Info and Relationships
Level: A
Relationship: Confirmed failure

自动化结果的工具/规则信息：

Tool and version: axe-core 4.9.1
Rule ID and version: button-name
Configuration: wcag2a, wcag2aa tags
Test method: Automated
Raw outcome: failed
Human review: Confirmed / Rejected / Needs review

将工具的影响/置信度值与项目的严重性分开处理——工具元数据只是启发式信息，并非对任务/上下文/变通方案/根本原因的评估。如果使用 ACT Rules Format 1.1，请保留其某个结果值 （inapplicable、passed、failed、cantTell、untested）——将 cantTell 结果送交人工审核；即使结果为 passed/inapplicable，也可能仍需进行其他测试，才能得出 WCAG 结论。

义务和处理方式与 WCAG 映射相互独立。 应根据标准映射指定，而不是根据严重性或生命周期状态推断：

• obligation：required | aspirational | advisory | unmapped | not-applicable。 在 AA 基线目标下确认的 AAA 发现属于 aspirational，而非 advisory——应将其记录为明确的提升目标，而不是随意的 建议。项目可以将特定 AAA 成功标准提升为 required； 如此处理时，请在 obligation_basis 中引用本地政策或权威依据。不要 将满足单项 AAA 成功标准描述为符合 WCAG AAA。
• handling：report | review | suppress。未解决的 自动化指示应设为 review，绝不能直接设为 report，将其视为已确认 的失败，也不能设为 suppress。 suppress 必须有记录在案的例外说明——明确范围、理由、证据、负责人以及审核或到期日期——且绝不表示该发现已解决或已删除。

完整定义和示例请参阅无障碍发现跟踪：政策分类。

---

严重：规划互补的测试与验证

自动化测试、人工评估和与残障人士一起测试回答的是不同的问题——请说明需要哪些方法、原因及其局限。

• **自动化：**识别可由机器测试的模式，并提供可重复的回归覆盖；但无法确定对用户的全面影响、可用性或符合性。保留原始结果和配置；在将问题确认为面向用户的障碍之前，必须经过人工审核；不要把自动化测试通过视为足以结案的证据。
• **人工无障碍评估：**当结果取决于人的判断或交互时，必须进行评估——包括键盘操作、焦点、屏幕阅读器输出、缩放／重排、强制颜色、标签／错误／状态消息以及相关状态。按风险挑选一组环境进行测试，不必针对每个问题测试所有组合。
• **与残障人士一起测试：**考察真实任务和实际交互体验，可以发现基于标准的评估容易漏掉的障碍。以下情况应规划此类测试：任务至关重要（身份验证、付款、健康、安全、公共服务）；障碍／修复的影响重大或不确定；组件复杂或新颖；替代方案的效果不明确；残障人士的反馈与技术结果相矛盾。不要让残障参与者去重新发现显而易见、应先修复的已知问题。一位参与者只能确认其个人体验——不要将其视为整个残障群体的代表。这不能取代基于标准的评估，基于标准的评估也不能取代直接向残障人士学习。

记录验证计划：自动化检查的必需／计划／已完成状态；人工检查的必需／计划／已完成状态；相关的受支持环境；与残障人士一起测试的必需／计划／已完成状态及理由。

---

中等：记录范围、频率和根本原因

Observed occurrences: 7
Pages checked: 12
Pages affected: 5
States checked: Default, error, disabled
Likely source: Shared address form component
Unchecked scope: Mobile app and authenticated administrator flow

不要在未说明是估算的情况下根据样本进行推断——全站模板缺陷和七个互不相关的内容错误，数量可能相同，但需要采取不同的处理方式。谨慎地对发现项进行分组——仅当多个问题共用同一修复单元或已确认的根本原因时，才合并出现次数；不要仅因它们共用规则 ID 或相似的选择器就合并。

---

建议修复方案与验收标准

建议修复方案并非必需——请将其标注为提议；负责团队可能知道更安全的源代码级修正方式：

Suggested fix:
Associate the error message with the field and expose the invalid state after
validation.

验收标准应描述可验证的面向用户的行为，而不只是某个属性／选择器／自动化规则的结果：

- Submitting the empty field identifies the card number error in text.
- The field exposes the error association and invalid state programmatically.
- Keyboard focus remains predictable.
- The original interaction is manually retested.
- Testing with disabled people is completed when required by the verification plan.

---

Markdown 问题模板

## Accessibility finding

### Summary
[Component or location: failure and task effect]

### Location and state
- Page or route:
- Build or commit:
- Component:
- Preconditions and UI state:
- Safe locator (optional):

### Steps or conditions
1.
2.

### Expected result
[Describe the user-facing outcome.]

### Actual result
[Describe what was observed.]

### People affected and impact
- People confirmed or likely to be affected:
- Relevant access needs, interaction methods, or assistive technologies:
- Affected task:
- Consequence:
- Workaround and its cost, if any:
- Evidence basis: User report / Testing with disabled people / Manual evaluation / Automated result / Reasoned inference
- Confidence: Confirmed for reported scope / Observed / Likely / Unknown
- Scope limits or uncertainty:

### Relevant environment
- Test date:
- Browser and operating system:
- Assistive technology and version:
- Input method:
- Viewport, zoom, text size, and orientation:
- Active preferences or display modes:

### Evidence
[Small redacted excerpt, attachment description, or link to protected evidence.]

### Standards and tests (optional)
- WCAG version, success criterion, and level:
- Relationship: Confirmed / Suspected / Needs review
- Tool, rule, version, and configuration:

### Verification plan
- Automated checks: Required / Not required / Planned / Completed
- Manual checks: Required / Not required / Planned / Completed
- Testing with disabled people: Required / Not required / Not yet determined / Planned / Completed
- Rationale:

### Scope and source
- Occurrences and sample checked:
- Suspected or confirmed root cause:

### Suggested fix (optional)
[Describe a possible approach without replacing acceptance criteria.]

### Acceptance criteria
- [ ] The reported user-facing barrier is no longer present.
- [ ] The original environment and interaction have been manually retested.
- [ ] An automated pass was not treated as sufficient evidence on its own.
- [ ] Testing with disabled people was completed when required by the verification plan.
- [ ] The impact statement does not go beyond the available evidence.
- [ ] Appropriate regression coverage has been added or updated.

### Privacy and attachment check
- [ ] Secrets, personal data, and private content have been removed.
- [ ] Screenshots are described and recordings have captions or transcripts.

---

机器可读的问题发现项架构

机器可读的输出有助于导入、报告和回归分析。此 JSON 格式为可选格式——不得要求手动发现或用户报告的问题发现项中不存在的字段。

规范的、带版本且通过架构验证的格式为 schema_version: "2.0" 或 "2.1"（JSON Schema Draft 2020-12），定义于 mgifford/ACCESSIBILITY.md 中的 examples/schemas/。请勿使用 schema_version: "1.1"——它是本技能早期草案中的示例结构，现已弃用。"2.1" 新增了可选的顶层 policy 对象（standards_obligations、handling、evidence_status、suppression），用于上述义务／处理分类；"2.0" 记录不得填入该对象。policy 绝不是指纹身份的一部分，也不会更改 tracking.fingerprints。以下是使用当前架构的简要摘录：

{
  "schema_version": "2.0",
  "title": "Checkout: card error text is not associated with the field",
  "reported_at": "2026-07-18T14:30:00-04:00",
  "source": { "method": "manual-evaluation" },
  "location": {
    "safe_url": "https://example.com/checkout/payment",
    "component": "Payment form"
  },
  "description": {
    "summary": "The visible card error is not programmatically associated with the field.",
    "expected": "The field exposes its label, invalid state, and associated error programmatically.",
    "actual": "A visible error appears, but the field has no error association."
  },
  "affected_people": [{
    "description": "People who use screen readers",
    "status": "likely",
    "evidence_basis": "manual-evaluation",
    "scope_limit": "Observed with NVDA and Firefox; not yet evaluated with disabled participants"
  }],
  "standards": [{ "standard": "WCAG", "version": "2.2", "requirement": "1.3.1", "level": "A", "relationship": "confirmed-failure" }],
  "verification": {
    "automated": { "required": true, "status": "planned" },
    "manual": { "required": true, "status": "completed-for-original-finding" },
    "testing_with_disabled_people": { "required": true, "status": "planned" }
  }
}

tracking.fingerprints、tracking.tracker_ids 和 tracking.lifecycle 是可选字段，可用于自动发现或关联的问题发现项——请参阅完整示例、最小示例（其中的问题发现项不包含这些字段），以及政策分类示例（展示了八种 obligation／handling／evidence_status 场景）。请勿手动计算指纹，也不要在此处重复指纹算法；请参阅 Fingerprint Profiles，了解冻结且带版本的 a11y/pattern/v1／a11y/occurrence/v1 契约。已发布的指纹配置文件不可变——算法变更必须使用新的配置文件版本，绝不能直接修改现有版本。

根据已发布的架构验证导入数据；按照架构自身的约定说明 null／省略值；使用 Accessibility Finding Tracking 中的 equivalent／split／merged／unresolved 术语规划迁移。当精确往返保真度很重要时，应单独保留工具的原始输出（source.raw_result_reference／evidence.references）。

---

自动化与 AI 防护措施

自动化可以收集和整理证据，但不应臆造确定性、受影响人群或亲身经历。

自动化／AI 辅助工作流应：

1. 保留原始结果、工具／规则版本、配置、时间以及受测 URL／路由
2. 标注方法：自动化／半自动化／人工／用户报告／与残障人士共同测试
3. 保留工具的原始结果；将 cantTell／不确定的结果转交审核队列
4. 在将证据发送到其他系统前，移除凭据和个人数据
5. 当证据不支持时，避免生成 WCAG 映射、受影响人群、影响说明、 严重程度或根本原因
6. 区分已确认的参与者证据、人工观察和基于推理得出的结论
7. 在创建高影响工作或合规性声明前，按照项目的风险／分流规则要求人工验证
8. 仅当修复单元或根本原因已得到充分确认时，才对多个出现实例进行归组
9. 发现新的出现实例时，更新现有问题，而不是悄然丢弃重复项
10. 保留工具结果、评估者审核和参与者反馈之间的分歧
11. 当自动化无法验证结果时，关闭问题前必须进行面向用户的人工复测
12. 记录是否需要／计划进行／已完成与残障人士共同测试，并说明理由
13. 除非确实进行过，否则绝不声称已与残障人士共同测试
14. 将每项自动化结果转入当前有效的修复队列、调查队列或观察历史记录——绝不将未经复现的原始自动化结果直接放入当前有效的修复队列
15. 绝不只因内部重新运行未能复现，就自动驳回可信的用户报告或可能造成严重后果的障碍——应将其转入范围明确的调查
16. 将未经审核的自动化结果记录为 evidence_status: automated-indicator，并标记 handling: review——在人工确认前，绝不能标记为 confirmed-standards-failure、confirmed-user-facing-barrier 或 handling: suppress。不要因为某个目标产生噪声就禁用整个规则或引擎；应仅抑制范围明确的具体发现。

不要仅因原始自动化规则通过就关闭问题——实现可能已更改选择器、隐藏受测节点，或引入了不同的障碍。

可采取行动的发现与可重复性

在团队拥有足够证据采取行动之前，一项发现仍可能有效且值得保留。应使用三个去向，而非一个不加区分的队列：

• 当前有效的修复队列——可复现，或有其他充分证据支持：明确且安全的位置、适用时的技术证据、负责人、验收标准、验证计划。WCAG 映射、严重程度、频率和指纹虽有帮助，但并非必要条件。
• 调查队列——可信，但间歇出现／证据不足：必须有负责人、当前证据、下一步行动、晋级所需证据以及审核／到期日期。不要让无人负责的 needs_review 发现无限期搁置。
• 观察历史记录——为未复现的自动化结果保留精简且有期限的证据（指纹、位置、工具／规则标识、扫描运行 ID、首次／最近发现时间、未晋级的原因）。这不是当前有效的人工问题队列。

自动化发现的可操作性门槛——自动化结果进入当前有效的修复队列前，应先询问：团队能否定位该结果、重新运行或评估检查、检查受影响的输出，并确定什么情况可证明问题已修正？ 如果不能，应将其转入调查队列或观察历史记录，而不是创建无人能够处理的问题。此门槛针对自动化发现的数量；它不会增加在接受人工报告的发现为有效之前必须复现或提供证据的要求。 可比较的运行，以及 not_observed 与 not_tested： 只有在重新运行确实可比较时（相同资源、成功加载、已达到所需的认证状态、相同规则、扫描器已完成，且排除项没有实质变化），缺失的结果才有意义。超时、认证失败、规则已禁用或爬取未完成，应归类为 not_tested，绝不能视为不存在。可比较的运行确认确实不存在时，应归类为 not_observed，绝不能悄然归类为 resolved。

优先直接复现；无法精确复现时可接受等效证据——例如有针对性的 HTML/DOM/无障碍树摘录、附带配置和版本信息的工具输出、附有说明的录制内容、重复报告或有记录的复现尝试。无法复现描述的是团队目前掌握的证据，而不是对报告者可信度的判断。

不要让发现项在没有计划的情况下长期保留：没有负责人和审查日期的调查项，实际上等同于已丢弃的报告。

完整的阶段模型、三个去向、可采取行动的门槛、可比较运行规则，以及激进筛选的后果和例外，请参阅规范仓库中的 Accessibility Finding Tracking § Actionability。此处不要重述阶段晋级门槛或指纹算法；请链接至相关内容。

去重与跟踪： 跟踪器 ID（问题跟踪器自身的 ID）是已跟踪修复工作的持久标识——它由提交或关联问题的人分配，绝不能根据发现内容计算得出。扫描请求 ID标识扫描运行的原因；它不会自动成为该扫描产生的每个发现项的跟踪器 ID。指纹（用于一个位置的出现指纹，或用于关联多个位置候选项的模式指纹）有助于关联重复结果，但它是计算得出的关联键，而不是永久的 Bug ID——指纹匹配有助于分组和调查，但本身不能证明它们具有相同的根本原因。从指纹派生的短 显示 ID（例如 A11Y-PAT-EA3B846C4F12）是便于人阅读的别名，绝不是权威标识。如果使用指纹，应对算法和配置进行版本管理。将工具和规则版本记录为来源信息；只有在适用的冻结指纹配置明确要求时，才将它们纳入指纹标识。谨慎规范化 URL/选择器；指纹只能在引入新配置版本时发生变化，绝不能悄然变化；指纹算法变更时保留旧标识符；不要根据宽度阈值推断移动端/桌面端；不要仅因哈希匹配就合并结果。后续扫描中未出现某项，本身并不能证明问题已解决——除非实际重新测试了相关范围或通过其他方式进行了验证，否则应将其视为 not_observed。

完整模型（包括扫描运行 ID、旧标识符迁移，以及带有已发布测试向量的冻结 a11y/pattern/v1 / a11y/occurrence/v1 指纹配置），请参阅规范仓库中的 Accessibility Finding Tracking 和 Fingerprint Profiles。此处不要重述指纹算法；请链接至相关内容。

---

问题生命周期

1. **记录：**记录障碍、位置、状态、受影响的人群、影响、证据依据和安全的证据
2. **分诊：**尽可能确认结果，找出缺失的上下文，将严重程度与优先级区分开来
3. **隔离：**找出产生这些问题的源组件／模板／令牌／流程
4. **指派：**指派能修改源头的负责人，而不只是负责单个页面的人
5. **定义：**商定面向用户的验收标准、支持的环境和验证计划
6. **修正：**修复源头；更新文档／示例／内容指南
7. **预防：**添加适当的回归测试
8. **复测：**重复原始交互，并测试相关的相邻状态／偏好／环境
9. **与残障人士共同评估：**在需要时完成计划中的参与者测试
10. **关闭：**记录变更内容、验证证据、仍存的限制和后续事项

如果修复不彻底，应记录剩余的问题／环境，而不是将更广泛的问题标记为已完全解决。

---

向外部组织报告

首先查找无障碍声明、accessibility@ 联系方式或反馈表单。撰写报告时要考虑接收者，他们可能并非无障碍领域的专业人士。开头应说明页面／功能、观察到的障碍、已知且可安全分享的受影响人群／使用方法、该障碍妨碍完成的任务、简明的操作步骤和环境，以及请求对方确认收到报告。WCAG 参考资料和修复建议均为可选内容。请勿包含密码、个人信息或敏感文件，也不要要求报告者透露诊断结果。没有通用的回复期限；适当的跟进方式取决于组织／合同／司法管辖区（这并非法律建议）。

Subject: Accessibility barrier in [page or feature]

Hello,

I encountered an accessibility barrier in [page or feature].

Location: [safe URL, route, or feature name]
Task: [what you were trying to do]
Barrier: [what happened]
People or interaction methods affected, if known: [description]
Impact: [how this affected the task]

Steps or conditions:
1. [Step]

Expected: [user-facing outcome]
Actual: [observed result]

Relevant environment: [only details that affect the result]
WCAG reference, if known: [version, criterion, and level]

Please acknowledge this report and let me know how I can follow its status.

Thank you.

---

常见的报告错误

• 要求提供完整的 DOM XPath、HTML 摘录、工具规则或 WCAG 标准条款，才受理报告
• 复制包含令牌或个人数据的完整 URL
• 只报告“未通过 WCAG”，却不描述面向用户的行为
• 根据 WCAG 标准条款或工具规则推断某个残障群体或大范围人群受到影响
• 将工具结果视为已确认的缺陷或合规结论
• 将评估者使用辅助技术视为等同于与残障人士共同测试
• 根据工具的影响字段判定严重程度，或仅因问题出现次数而自动提高严重程度（这反映的是优先级，而非严重程度）
• 声称视口宽度能够证明实体设备类型
• 列出所有辅助技术版本，而非实际测试所用的环境
• 因规则 ID 或选择器看起来相似，就合并无关问题
• 未设定基于行为的验收标准，就指定代码变更方案
• 因自动化检查通过，就跳过手动测试
• 代码合并或自动化检查通过后，未重复原始交互就关闭问题
• 在修正已知的基本问题之前，就让残障参与者重新发现这些问题
• 将一位参与者的体验泛化为整个残障群体的体验
• 未经知情许可，披露报告者或参与者的诊断、身份或私人内容

---

提交前质量检查清单

• 已记录位置和状态，并从 URL 中移除机密信息／令牌／个人数据
• 标题说明组件、故障及其对任务的影响（而非“无障碍问题”）
• 复现步骤已编号，精简且完整
• 预期结果和实际结果以面向用户的结果表述，而非实现方案
• 仅在证据允许的范围内具体描述受影响的人群——不猜测诊断结果
• 已说明证据依据和置信度（用户报告／与残障人士共同测试／手动／自动化／推断）
• 仅记录相关环境字段——而非通用的浏览器／辅助技术矩阵
• 技术证据（HTML／屏幕截图／日志）已移除机密信息和个人数据
• WCAG 对应关系已酌情标记为已确认／疑似／待审核
• 根据任务影响分配严重程度——而非根据工具输出或发生次数
• 将频率／影响范围单独记录为优先级因素，而非纳入严重程度
• 验证计划说明需要进行自动化／手动／与残障人士共同测试中的哪些测试，以及原因
• 仅在确认修复单元或根本原因相同时才合并问题

---

常见违反的 WCAG 成功标准

SC	名称	等级	常见违规
1.1.1	非文本内容	A	图片缺少 alt，图标按钮未标注
1.3.1	信息和关系	A	标题结构不符合语义，表单缺少标签
1.3.3	感官特征	A	说明仅依赖形状、颜色或位置
1.4.1	使用颜色	A	仅通过颜色传达状态
1.4.3	对比度（最低）	AA	文本对比度低于 4.5:1
1.4.4	调整文本大小	AA	页面在 200% 缩放时布局错乱
1.4.11	非文本对比度	AA	UI 组件边框对比度低于 3:1
2.1.1	键盘	A	元素无法通过键盘访问或操作
2.4.3	焦点顺序	A	Tab 顺序不合逻辑，焦点意外移动
2.4.7	焦点可见	AA	没有可见的焦点指示器
3.3.1	错误识别	A	未以文本说明表单错误
3.3.2	标签或说明	A	表单字段没有可见标签
4.1.2	名称、角色、值	A	自定义组件缺少 ARIA 名称、角色或状态
4.1.3	状态消息	AA	屏幕阅读器无法获取通知

完整列表请参阅 WCAG 2.2 快速参考。

---

参考资料

• 完整的最佳实践指南
• 无障碍问题跟踪 — 跟踪器 ID、扫描请求/运行 ID、发生项和模式指纹、显示 ID、旧版标识符迁移，以及可操作性策略（阶段模型、活动/调查/观察历史目标位置、自动化发现门槛）
• 指纹配置文件 — 冻结的 a11y/pattern/v1 / a11y/occurrence/v1 契约和黄金测试向量
• 无障碍问题架构 — schema_version: "2.0" JSON Schema 和经过验证的示例
• 网站无障碍符合性评估方法（WCAG-EM）
• 让用户参与评估 Web 无障碍
• 运用综合专业知识评估 Web 无障碍
• 联系相关组织，反馈网站无障碍问题
• EARL 1.0 架构 — W3C 工作组的非规范性说明，常规报告无需遵循
• ACT 规则格式 1.1
• WCAG 2.2 快速参考