a11y-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Accessibility Audit

无障碍审计

Architecture

架构

This skill operates as a single layer. It reads the project environment, runs automated accessibility tools, maps findings to compliance standards, and produces output in a configurable format. No external skill dependency is required.

Store project-specific audit state in the target workspace, not in the installed skill directory. Default path:

.a11y-audit/PROJECT_CONTEXT.md

at the workspace root. When that file exists, use it for project-specific configuration: output mode, additional compliance standards, issue tracker settings, route lists, color palettes, and cross-references to existing documentation. When absent, use WCAG 2.1 AA as the sole standard,

markdown

as the output mode, and generic defaults for everything else.

Use

references/project-context-template.md

as the canonical schema for that file, including minimal and

markdown+issues

examples.

Prefer bundled helpers over ad hoc generation when they fit:

scripts/bootstrap-context.js

creates a workspace-local

.a11y-audit/PROJECT_CONTEXT.md

from simple inputs.

```
scripts/scan.js
```
runs reusable axe-based scans and records optional Lighthouse execution intent. Use
```
--summary
```
to reduce output size (keeps full violation detail, strips node data from passes/inapplicable).
```
scripts/report.js
```
generates the markdown report and JSON data file from scan.js output. Handles WCAG compliance matrix, violation aggregation, and color-contrast detail extraction deterministically.
```
scripts/discover.js
```
identifies template groups on large sites and selects representative pages for scanning. Reads sitemap.xml first, falls back to HTML navigation crawl. Outputs a scan plan with template groups and a ready-to-use URL list for scan.js.

本技能以单层架构运行，它会读取项目环境，运行自动化无障碍工具，将扫描结果映射到合规标准，并以可配置的格式生成输出，无需依赖外部技能。

请将项目专属的审计状态存储在目标工作区中，不要存放在已安装的技能目录下，默认路径为工作区根目录的

.a11y-audit/PROJECT_CONTEXT.md

。当该文件存在时，将其用于项目专属配置：输出模式、额外合规标准、问题追踪器设置、路由列表、调色板，以及现有文档的交叉引用。如果文件不存在，则默认仅使用WCAG 2.1 AA作为标准，输出模式为

markdown

，其余配置均使用通用默认值。

请使用

references/project-context-template.md

作为该文件的标准规范，其中包含最简配置和

markdown+issues

模式的配置示例。

当内置辅助工具符合需求时，优先使用它们而不是临时生成脚本：

scripts/bootstrap-context.js

可通过简单输入在工作区生成本地的

.a11y-audit/PROJECT_CONTEXT.md

文件

```
scripts/scan.js
```
运行可复用的axe基础扫描，支持记录可选的Lighthouse执行意图。使用
```
--summary
```
参数可减小输出体积（保留完整的违规详情，移除通过/不适用规则的节点数据）
```
scripts/report.js
```
可基于scan.js的输出生成markdown报告和JSON数据文件，确定性地处理WCAG合规矩阵、违规聚合和颜色对比度详情提取
```
scripts/discover.js
```
可识别大型站点的模板组，选择代表性页面进行扫描。优先读取sitemap.xml，降级方案为HTML导航爬取，输出包含模板组的扫描计划和可直接供scan.js使用的URL列表

Dependencies

依赖

scan.js requires

axe-core

and

puppeteer

. It resolves these in order:

Skill-local
```
deps/
```
directory (sibling to
```
scripts/
```
)
Target project
```
node_modules/
```
(and common workspace subdirs)
Global npm modules

If not found anywhere, scan.js auto-installs both packages to the skill-local

deps/

directory. This means the skill works against any project without requiring the target to have accessibility tooling installed. The

deps/

directory is gitignored.

scan.js 需要

axe-core

和

puppeteer

，它会按以下顺序解析依赖：

技能本地的
```
deps/
```
目录（与
```
scripts/
```
同级）
目标项目的
```
node_modules/
```
（以及通用工作区子目录）
全局npm模块

如果所有位置都找不到依赖，scan.js会自动安装两个包到技能本地的

deps/

目录。这意味着该技能可针对任何项目运行，无需目标项目预先安装无障碍工具，

deps/

目录已加入gitignore。

Platform-Specific References

平台专属参考

If running in Claude Code, read
```
references/claude-code.md
```
for
```
.claude/launch.json
```
handling and Preview tool usage.
If running in Codex, read
```
references/codex.md
```
for workspace-local state handling and execution assumptions.

references/output-contract.md

and

references/output-schema.json

are encoded in

scripts/report.js

. Read them only when modifying the report script.

Read

references/issue-trackers.md

only when

output_mode

markdown+issues

If the user wants to operationalize recurring audits in CI, start from
```
assets/ci/github-actions/accessibility-audit.yml
```
.
Prefer
```
scripts/plan-issues.js
```
before live ticket creation when you need a safe review and deduplication pass.

The skill does not modify source code. It is an auditor, not a fixer. Findings are reported with remediation guidance; the user decides what to act on.

如果在Claude Code中运行，请阅读
```
references/claude-code.md
```
了解
```
.claude/launch.json
```
处理方式和预览工具使用方法
如果在Codex中运行，请阅读
```
references/codex.md
```
了解工作区本地状态处理方式和执行假设

references/output-contract.md

和

references/output-schema.json

已编码在

scripts/report.js

中，仅在修改报告脚本时需要阅读

仅当

output_mode

为

markdown+issues

时需要阅读

references/issue-trackers.md

如果用户想要在CI中落地定期审计，可以基于
```
assets/ci/github-actions/accessibility-audit.yml
```
实现
需要安全评审和去重流程时，在正式创建工单前优先运行
```
scripts/plan-issues.js
```

本技能不会修改源代码，它是审计工具而非修复工具。报告的结果会附带修复指引，由用户决定要处理哪些问题。

Output Modes

输出模式

The skill supports three output modes, configured via the

output_mode

field in

.a11y-audit/PROJECT_CONTEXT.md

Mode	Output	Use Case
`markdown`	Markdown report only	Human review, documentation
`markdown+json`	Markdown report + JSON data file	CI integration, dashboards, trend tracking
`markdown+issues`	Markdown report + issue tracker tickets	Active remediation workflow

On first run, if no

output_mode

is set in

.a11y-audit/PROJECT_CONTEXT.md

, ask the user which mode they prefer and persist their choice by appending an

## Output Configuration

section to that file. If no context file exists, create it at the default path following

references/project-context-template.md

. Prefer

scripts/bootstrap-context.js

for first-run context creation when a simple generated file is sufficient.

The

markdown+json

mode writes a companion file alongside the report:

audit-YYYY-MM-DD.json

containing the raw axe-core results, Lighthouse scores, and the compliance matrix as structured data. This file is machine-readable and can be consumed by CI pipelines, dashboards, or trend-tracking tools.

The

markdown+issues

mode requires additional configuration in the context file (see Phase 6).

本技能支持三种输出模式，可通过

.a11y-audit/PROJECT_CONTEXT.md

中的

output_mode

字段配置：

模式	输出内容	使用场景
`markdown`	仅Markdown报告	人工评审、文档留存
`markdown+json`	Markdown报告 + JSON数据文件	CI集成、仪表盘、趋势跟踪
`markdown+issues`	Markdown报告 + 问题追踪器工单	主动修复工作流

首次运行时，如果

.a11y-audit/PROJECT_CONTEXT.md

中未设置

output_mode

，请询问用户偏好的模式，并通过在文件中追加

## 输出配置

章节的方式保存用户选择。如果不存在上下文文件，请按照

references/project-context-template.md

的规范在默认路径创建。简单生成的文件即可满足需求时，优先使用

scripts/bootstrap-context.js

完成首次运行的上下文创建。

markdown+json

模式会在报告旁生成配套文件：

audit-YYYY-MM-DD.json

，包含原始axe-core结果、Lighthouse得分和合规矩阵的结构化数据。该文件是机器可读的，可被CI流水线、仪表盘或趋势跟踪工具使用。

markdown+issues

模式需要在上下文文件中额外配置（参见第6阶段）。

Pipeline

工作流

An accessibility audit moves through six phases. Each phase produces data the next phase consumes. Phases 1-4 always run. Phase 5 produces output based on the configured output mode. Phase 6 runs only in

markdown+issues

mode and requires explicit user confirmation.

The user can request a partial run. Common patterns:

"Quick scan": Phases 1-2 only, results summarized in conversation
"Full audit": Phases 1-5, output per configured mode
"Audit with issues": Phases 1-6, report plus tracker tickets

无障碍审计分为六个阶段，每个阶段生成的数据供下一阶段使用。阶段1-4始终运行，阶段5根据配置的输出模式生成结果，阶段6仅在

markdown+issues

模式下运行，且需要用户显式确认。

用户可以请求部分运行，常见模式：

「快速扫描」：仅运行阶段1-2，在对话中返回结果摘要
「全量审计」：运行阶段1-5，按配置模式输出结果
「带工单的审计」：运行阶段1-6，输出报告和追踪器工单

Phase 1 -- Environment Discovery

阶段1 -- 环境发现

Purpose: Understand the project before scanning.

Read

.a11y-audit/PROJECT_CONTEXT.md

if it exists (standards, routes, output mode, labels). If absent, create it via

scripts/bootstrap-context.js

or from

references/project-context-template.md

Read
```
package.json
```
for tech stack, existing a11y tooling, and available browser automation (
```
puppeteer
```
/
```
playwright
```
).
Build a scannable URL list from router config or HTML file glob. For sites with many pages (>15 routes), prefer
```
scripts/discover.js
```
to classify pages into template groups and select representatives. Review the scan plan with the user before proceeding to Phase 2.
Confirm a dev server is reachable. Check
```
.claude/launch.json
```
and platform-specific references for launch hints. If the app starts on a different URL than expected, switch to the live URL, record the mismatch, and update the context file.
Ask before installing any missing dependencies.

Output: Structured summary reported to the user before proceeding.

目标： 在扫描前了解项目情况

读取
```
.a11y-audit/PROJECT_CONTEXT.md
```
（如果存在），包含标准、路由、输出模式、标签。如果不存在，通过
```
scripts/bootstrap-context.js
```
或
```
references/project-context-template.md
```
创建
读取
```
package.json
```
了解技术栈、现有a11y工具、可用的浏览器自动化工具（
```
puppeteer
```
/
```
playwright
```
）
从路由配置或HTML文件通配符构建可扫描的URL列表。对于页面较多的站点（>15个路由），优先使用
```
scripts/discover.js
```
将页面分类到模板组并选择代表性页面。进入阶段2前请和用户确认扫描计划
确认开发服务器可访问。检查
```
.claude/launch.json
```
和平台专属参考获取启动提示。如果应用启动的URL和预期不一致，切换到实际可用的URL，记录不一致的情况并更新上下文文件
安装任何缺失依赖前请先询问用户

输出： 进入下一阶段前向用户报告结构化摘要

Phase 2 -- Automated Scanning

阶段2 -- 自动化扫描

Purpose: Run automated accessibility checks against live pages.

Prerequisite: A running dev server (or production URL provided by the user).

目标： 对在线页面运行自动化无障碍检查

前置条件： 运行中的开发服务器（或用户提供的生产环境URL）

axe-core Scanning

axe-core 扫描

Prefer the bundled

scripts/scan.js

before writing a throwaway scan script. Use an ad hoc script only when the workspace needs behavior that the bundled script does not yet support.

The reusable scanner should:

Imports
```
puppeteer
```
and
```
axe-core
```
Launches a headless browser
For each target URL: a. Navigates to the page b. Waits for network idle (
```
waitUntil: 'networkidle0'
```
) c. Injects axe-core: reads the axe-core source file from
```
node_modules/axe-core/axe.min.js
```
and injects it via
```
page.evaluate()
```
d. Runs the audit:
```
page.evaluate(() => axe.run())
```
e. Collects the results JSON
Closes the browser
Writes raw results to JSON

Example invocation:

bash

node a11y-audit/scripts/scan.js \
  --root . \
  --urls http://127.0.0.1:3000/,http://127.0.0.1:3000/about \
  --output /tmp/a11y-scan.json \
  --summary

Adapt to the project. If dependencies live in a frontend subdirectory, point

--root

at the workspace root; the bundled script already checks common frontend paths. If that still fails, fall back to an ad hoc script or run from the frontend directory directly.

Common mistake: Do not use

require()

in an ES module project. Check

package.json

for

"type": "module"

. If present, use

import

syntax and the

__dirname

workaround in any ad hoc script. If absent,

require()

is fine.

Playwright alternative: If the project uses Playwright instead of Puppeteer, adapt the script: replace

puppeteer.launch()

with

chromium.launch()

, use

page.goto()

the same way, and inject axe-core via

page.evaluate()

. The axe-core injection pattern is identical. Use whichever browser automation library the project already has installed.

优先使用内置的

scripts/scan.js

，不要编写临时扫描脚本。仅当工作区需要内置脚本暂不支持的行为时，才使用临时脚本。

可复用扫描器应当：

导入
```
puppeteer
```
和
```
axe-core
```
启动无头浏览器
对每个目标URL： a. 导航到该页面 b. 等待网络空闲（
```
waitUntil: 'networkidle0'
```
） c. 注入axe-core：从
```
node_modules/axe-core/axe.min.js
```
读取axe-core源文件，通过
```
page.evaluate()
```
注入 d. 运行审计：
```
page.evaluate(() => axe.run())
```
e. 收集结果JSON
关闭浏览器
将原始结果写入JSON文件

调用示例：

bash

node a11y-audit/scripts/scan.js \
  --root . \
  --urls http://127.0.0.1:3000/,http://127.0.0.1:3000/about \
  --output /tmp/a11y-scan.json \
  --summary

适配项目情况：如果依赖存放在前端子目录中，将

--root

指向工作区根目录；内置脚本已经会检查常见的前端路径。如果仍然失败，降级使用临时脚本或直接从前端目录运行。

常见错误： 不要在ES module项目中使用

require()

。检查

package.json

是否有

"type": "module"

配置，如果有，在临时脚本中使用

import

语法和

__dirname

兼容方案。如果没有，可以正常使用

require()

。

Playwright替代方案： 如果项目使用Playwright而非Puppeteer，调整脚本：将

puppeteer.launch()

替换为

chromium.launch()

，

page.goto()

的用法不变，同样通过

page.evaluate()

注入axe-core，axe-core的注入模式完全相同。优先使用项目已经安装的浏览器自动化库。

Lighthouse Scanning

Lighthouse 扫描

Run Lighthouse CLI against each target URL:

bash

npx lighthouse <url> \
  --output=json \
  --output-path=stdout \
  --only-categories=accessibility \
  --chrome-flags="--headless --no-sandbox" \
  --quiet

Parse the JSON output. Extract:

```
categories.accessibility.score
```
(0-1, multiply by 100)
```
audits
```
where
```
score !== 1
```
(failed or partial audits)
Each audit's
```
description
```
and
```
details.items
```

If Lighthouse is unavailable or fails (common in CI environments), skip it and note the gap in the report. In the executive summary and methodology, explicitly say whether Lighthouse was skipped because the CLI was missing, Chrome launch failed, or another runtime error occurred. axe-core results alone are sufficient for a valid audit.

对每个目标URL运行Lighthouse CLI：

bash

npx lighthouse <url> \
  --output=json \
  --output-path=stdout \
  --only-categories=accessibility \
  --chrome-flags="--headless --no-sandbox" \
  --quiet

解析JSON输出，提取：

```
categories.accessibility.score
```
（0-1，乘以100转为百分制）
```
score !== 1
```
的
```
audits
```
（未通过或部分通过的审计项）
每个审计项的
```
description
```
和
```
details.items
```

如果L不可用或运行失败（CI环境中很常见），跳过该步骤并在报告中注明缺失项。在执行摘要和方法论中，明确说明Lighthouse是因为CLI缺失、Chrome启动失败还是其他运行时错误被跳过，仅axe-core的结果就足以支撑有效的审计。

Scope Control

范围控制

Default: scan routes discovered in Phase 1
If a discover.js scan plan exists, use its
```
scanList
```
for
```
--urls
```
. The report methodology will record the sampling strategy.
If more than 10 routes exist and no discover plan is available, ask the user which to scan or whether to scan all
The user can provide a specific URL list to override discovery
For SPAs: navigate via the router, not by reloading the page (some routes may not work as direct URLs)

默认：扫描阶段1发现的所有路由
如果存在discover.js生成的扫描计划，使用其
```
scanList
```
作为
```
--urls
```
参数，报告方法论中会记录采样策略
如果存在超过10个路由且没有发现计划，询问用户要扫描哪些路由或者是否全量扫描
用户可以提供特定的URL列表覆盖自动发现的结果
对于单页应用：通过路由导航，不要重载页面（部分路由作为直接URL可能无法访问）

Result Structure

结果结构

For each page, collect:

```
url
```
: the scanned URL
```
violations
```
: array of axe violations, each with
```
id
```
,
```
impact
```
(critical/serious/moderate/minor),
```
description
```
,
```
help
```
,
```
helpUrl
```
,
```
tags
```
(WCAG criteria),
```
nodes
```
(affected elements with selectors)
```
passes
```
: count of passing rules
```
incomplete
```
: rules that could not be fully evaluated
```
lighthouseScore
```
: 0-100 (if available)
```
lighthouseAudits
```
: failed audit details (if available)

对每个页面，收集：

```
url
```
：扫描的URL
```
violations
```
：axe违规项数组，每个项包含
```
id
```
、
```
impact
```
（严重/重要/中等/轻微）、
```
description
```
、
```
help
```
、
```
helpUrl
```
、
```
tags
```
（WCAG标准项）、
```
nodes
```
（带选择器的受影响元素）
```
passes
```
：通过的规则数量
```
incomplete
```
：无法完整评估的规则
```
lighthouseScore
```
：0-100（如果可用）
```
lighthouseAudits
```
：未通过的审计详情（如果可用）

Phase 3 -- Compliance Mapping

阶段3 -- 合规映射

Purpose: Map automated findings to WCAG 2.1 AA success criteria and any project-specific standards.

scripts/report.js

handles the compliance matrix deterministically. It hardcodes all 50 WCAG 2.1 Level A and AA criteria, maps axe tags to success criteria, and produces the matrix as part of its markdown and JSON output. You do not need to build the matrix manually.

.a11y-audit/PROJECT_CONTEXT.md

specifies additional standards (e.g., CAN-ASC-6.2), build a secondary mapping. Cross-reference automated findings where the standard maps to WCAG criteria. For requirements that go beyond WCAG (equity, organizational processes, transparency), note them as manual review items referencing the project's existing conformance documentation.

目标： 将自动化扫描发现的问题映射到WCAG 2.1 AA成功标准和任何项目专属标准。

scripts/report.js

会确定性地处理合规矩阵，它硬编码了全部50项WCAG 2.1 A级和AA级标准，将axe标签映射到成功标准，作为markdown和JSON输出的一部分生成矩阵，你无需手动构建矩阵。

如果

.a11y-audit/PROJECT_CONTEXT.md

指定了额外标准（例如CAN-ASC-6.2），构建二级映射。对于标准映射到WCAG项的自动化发现结果进行交叉引用。对于超出WCAG的要求（公平性、组织流程、透明度），将其标注为人工审核项，引用项目现有的合规文档。

Phase 4 -- Manual Check Guidance

阶段4 -- 人工检查指引

Purpose: Generate targeted checklists for what automation cannot verify, prioritized by the automated findings.

For each WCAG criterion marked "Manual" in the Phase 3 matrix, generate a testing item. Organize by testing method: Keyboard Navigation, Screen Reader, Visual Inspection, Cognitive, and Timing/Motion.

Dynamic prioritization: Do not produce a static checklist. Use the Phase 2 results to focus manual effort:

If axe found color-contrast violations, prioritize visual inspection items (SC 1.4.1, 1.4.11, 1.4.10, 1.4.12, 1.4.13)
If axe found ARIA or landmark violations, prioritize screen reader items (SC 1.3.1, 4.1.3, 3.3.1, 3.3.2)
If axe found heading or structure violations, prioritize keyboard navigation items (SC 2.4.3, 2.4.7, 2.1.1)
If no form-related violations were found, deprioritize form testing (SC 3.3.3, 3.3.4) with a note that automated checks passed
Always include timing items (SC 2.2.1, 2.2.2, 2.3.1) since these cannot be automated at all

Each checklist item specifies: the WCAG criterion, what to test, how to test it, and which pages to focus on (pages where automated issues were found get priority).

.a11y-audit/PROJECT_CONTEXT.md

references an existing testing guide, cross-link to it rather than duplicating procedures.

目标： 为自动化无法验证的内容生成针对性检查清单，按自动化发现的结果优先级排序。

对阶段3矩阵中标注为「人工检查」的每个WCAG标准项，生成测试项。按测试方法组织：键盘导航、屏幕阅读器、视觉检查、认知、时间/动效。

动态优先级： 不要生成静态清单，使用阶段2的结果聚焦人工检查工作：

如果axe发现颜色对比度违规，优先安排视觉检查项（SC 1.4.1, 1.4.11, 1.4.10, 1.4.12, 1.4.13）
如果axe发现ARIA或地标违规，优先安排屏幕阅读器检查项（SC 1.3.1, 4.1.3, 3.3.1, 3.3.2）
如果axe发现标题或结构违规，优先安排键盘导航检查项（SC 2.4.3, 2.4.7, 2.1.1）
如果没有发现表单相关违规，降低表单测试的优先级（SC 3.3.3, 3.3.4），并注明自动化检查已通过
始终包含时间相关项（SC 2.2.1, 2.2.2, 2.3.1），因为这些完全无法自动化检查

每个清单项需明确：WCAG标准项、测试内容、测试方法、需要重点关注的页面（发现自动化问题的页面优先级更高）。

如果

.a11y-audit/PROJECT_CONTEXT.md

引用了现有的测试指南，请交叉链接到该指南而不是重复流程。

Phase 5 -- Output Generation

阶段5 -- 输出生成

Purpose: Produce output based on the configured output mode.

Run

scripts/report.js

to generate the markdown report and JSON data file from the Phase 2 scan output:

bash

node a11y-audit/scripts/report.js \
  --input /tmp/a11y-scan.json \
  --output-dir docs/accessibility/audits \
  --project-name "Project Name" \
  --runtime-url http://127.0.0.1:3000 \
  --expected-url http://localhost:3000 \
  --discover /tmp/a11y-discover.json

Pass

--discover

when a discover.js scan plan was used. This adds a Sampling Strategy subsection to the report methodology documenting template groups and coverage ratio.

Pass

--previous <prior-audit.json>

to generate a Delta from Previous Audit section showing fixed rules, new rules, changed instance counts, and net progress.

The script produces

audit-YYYY-MM-DD.md

and

audit-YYYY-MM-DD.json

following the contracts in

references/output-contract.md

and

references/output-schema.json

. You do not need to read those reference files unless modifying the report script itself.

After running report.js, review its output and fill in the Manual Testing Recommendations section with the Phase 4 guidance (report.js leaves a placeholder for this since it requires reasoning about the specific findings pattern).

.a11y-audit/PROJECT_CONTEXT.md

can override the output path.

If the user wants a recurring or on-demand CI job, adapt

assets/ci/github-actions/accessibility-audit.yml

to the target workspace instead of inventing a workflow from scratch.

目标： 基于配置的输出模式生成结果

运行

scripts/report.js

，基于阶段2的扫描输出生成markdown报告和JSON数据文件：

bash

node a11y-audit/scripts/report.js \
  --input /tmp/a11y-scan.json \
  --output-dir docs/accessibility/audits \
  --project-name "项目名称" \
  --runtime-url http://127.0.0.1:3000 \
  --expected-url http://localhost:3000 \
  --discover /tmp/a11y-discover.json

如果使用了discover.js生成的扫描计划，请传入

--discover

参数，这会在报告方法论中添加采样策略子章节，记录模板组和覆盖率。

传入

--previous <prior-audit.json>

可生成与上一次审计的差异章节，展示已修复规则、新增规则、实例数量变化和净进度。

脚本会按照

references/output-contract.md

和

references/output-schema.json

的规范生成

audit-YYYY-MM-DD.md

和

audit-YYYY-MM-DD.json

，仅在修改报告脚本本身时需要阅读这些参考文件。

运行report.js后，审核输出内容，用阶段4的指引填充人工测试建议章节（report.js会预留占位符，因为该部分需要基于具体的发现模式推理）。

.a11y-audit/PROJECT_CONTEXT.md

可覆盖输出路径。

如果用户需要定期或按需运行的CI任务，基于

assets/ci/github-actions/accessibility-audit.yml

适配目标工作区，不要从零构建工作流。

Phase 6 -- Issue Creation (conditional)

阶段6 -- 问题创建（条件执行）

Purpose: Create issue tracker tickets for findings. Runs only when the output mode is

markdown+issues

This phase requires explicit user confirmation. Before creating any tickets, show the user how many will be created, at what priority levels, and ask for approval.

Read

references/issue-trackers.md

for tracker configuration, deduplication, priority mapping, and ticket structure. Use the tracker settings from

.a11y-audit/PROJECT_CONTEXT.md

目标： 为发现的问题创建问题追踪器工单，仅当输出模式为

markdown+issues

时运行。

本阶段需要用户显式确认。创建任何工单前，向用户展示待创建的工单数量、优先级等级，请求用户批准。

阅读

references/issue-trackers.md

了解追踪器配置、去重、优先级映射和工单结构，使用

.a11y-audit/PROJECT_CONTEXT.md

中的追踪器设置。

Verification

验证

After completing an audit, verify these quality checks:

axe results valid: Compare violation count against a manual axe DevTools browser extension run on the same page. Counts should match within tolerance (axe versions may differ slightly).
Lighthouse score consistent: Compare against a manual Chrome DevTools Lighthouse run when Lighthouse was actually executed. Should be within 5 points.
WCAG matrix complete: All 50 AA criteria appear in the compliance matrix. No criterion is missing.

Treat the matrix as evidence-oriented status reporting. Do not frame it as proof of full conformance, because many WCAG criteria remain manual even in a strong automated run.
Report structure: All required sections present. Tables render correctly in a markdown viewer.
JSON validity (
```
markdown+json
```
mode): JSON file parses without error. Violation counts match the markdown report.
Issue deduplication (
```
markdown+issues
```
mode): Run the skill twice. The second run should create zero duplicate tickets.
Output mode persistence: After first run, verify the output mode is saved to
```
.a11y-audit/PROJECT_CONTEXT.md
```
and used automatically on next run.
Runtime URL reconciliation: If the app started on a different local URL than expected, verify the report records the mismatch and the context file reflects the actual working
```
base_url
```
.

完成审计后，验证以下质量检查项：

axe结果有效：将违规数量与在相同页面手动运行axe DevTools浏览器扩展的结果对比，数量应该在容差范围内匹配（axe版本可能有细微差异）
Lighthouse得分一致：如果实际运行了Lighthouse，与手动在Chrome DevTools中运行Lighthouse的结果对比，得分差应该在5分以内
WCAG矩阵完整：全部50项AA级标准都出现在合规矩阵中，没有缺失项

请将矩阵作为面向证据的状态报告，不要将其表述为完全合规的证明，因为即使是完善的自动化运行，很多WCAG标准仍然需要人工检查
报告结构完整：所有必填章节都存在，表格在markdown查看器中可以正确渲染
JSON有效性（
```
markdown+json
```
模式）：JSON文件可正常解析无错误，违规数量与markdown报告一致
问题去重（
```
markdown+issues
```
模式）：运行两次技能，第二次运行应该不会创建重复工单
输出模式持久化：首次运行后，验证输出模式已保存到
```
.a11y-audit/PROJECT_CONTEXT.md
```
，下次运行时会自动使用
运行时URL对齐：如果应用启动的本地URL与预期不一致，验证报告中记录了该差异，且上下文文件反映了实际可用的
```
base_url
```

What This Skill Does NOT Do

本技能不支持的功能

Visual regression testing: does not compare screenshots between runs. Use Percy, Chromatic, or BackstopJS for that.
PDF accessibility: does not audit PDF documents for tagged structure, reading order, or alternative text.
Real device/AT testing: runs in headless Chromium only. Cannot test on real iOS/Android or with real screen readers. Phase 4 generates manual checklists for this.
Code fixes: reports findings but does not modify source code.
VPAT generation: does not produce Voluntary Product Accessibility Templates (specific legal format).
Continuous monitoring: runs on demand, not as a CI pipeline. The
```
markdown+json
```
output mode provides structured data for building CI integrations, but the skill itself does not run in CI.
Third-party auditing: only audits the project's own frontend, not embedded third-party services.

视觉回归测试：不会对比运行前后的截图，请使用Percy、Chromatic或BackstopJS实现该功能
PDF无障碍检查：不会审计PDF文档的标签结构、阅读顺序或替代文本
真实设备/辅助技术测试：仅在无头Chromium中运行，无法在真实iOS/Android设备或真实屏幕阅读器上测试，阶段4会生成对应的人工检查清单
代码修复：仅报告发现的问题，不会修改源代码
VPAT生成：不会生成自愿产品无障碍模板（特定法律格式）
持续监控：按需运行，不会作为CI流水线运行。
```
markdown+json
```
输出模式提供了构建CI集成的结构化数据，但技能本身不会在CI中运行
第三方审计：仅审计项目自身的前端代码，不会审计嵌入的第三方服务