accessibility-diff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Default branch: !

git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null | sed 's|.*/||' || echo main

Report only what changed. Locate; don't fix.

Shared grounding and honesty conventions:

../shared/methodology.md

Parse

$ARGUMENTS

: if

--branch <name>

is present, remove it and use branch mode (no value means the default branch above). The rest is the target: a URL, a config target name, or empty for the default target from

accesslint.config.json

. If it's empty and there's no config, ask for a URL.

默认分支：!

git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null | sed 's|.*/||' || echo main

仅报告变更内容。定位问题，不自动修复。

共享基准与诚信规范：

../shared/methodology.md

解析

$ARGUMENTS

：如果存在

--branch <name>

参数，则移除该参数并启用分支模式（无参数值时使用上述默认分支）。剩余部分为目标：可以是URL、配置中的目标名称，或留空以使用

accesslint.config.json

中的默认目标。如果留空且无配置文件，则提示输入URL。

1. Audit

1. 审计

bash

PORT=$(npx -y @accesslint/chrome@latest ensure | node -e 'process.stdin.on("data",d=>process.stdout.write(""+JSON.parse(d).port))')

Stash mode (default; uncommitted changes). Tell the user first: "Running in diff mode — stashing your changes to capture a baseline, then restoring. Your working tree will be fully restored." If

git stash push

fails, warn and exit.

bash

git stash push -u -m "accesslint-diff-baseline"
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --update-snapshot
git stash pop && sleep 2
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --format json

Branch mode (

--branch <name>

). Tell the user first: "Diffing against
<name>
— checking out that branch to capture a baseline, then restoring. Your working tree will be fully restored." Branch switching triggers a rebuild but not a browser reload, so the CLI opens a fresh tab each run to read the current build. Use

--wait-for "<selector>"

to hold the audit until the rebuild is ready; without it, warn that a slow build may give a stale baseline.

bash

git diff --quiet && git diff --cached --quiet || git stash push -u -m "accesslint-diff-branch"
git checkout <branch>
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --update-snapshot [--wait-for "<selector>"]
git checkout - && git stash pop 2>/dev/null
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --format json [--wait-for "<selector>"]

Pass

--selector

and

--include-aaa

to both runs.

bash

PORT=$(npx -y @accesslint/chrome@latest ensure | node -e 'process.stdin.on("data",d=>process.stdout.write(""+JSON.parse(d).port))')

Stash模式（默认；针对未提交变更）。首先告知用户："正在运行差异模式——将您的变更暂存以捕获基准版本，之后将恢复。您的工作区将完全恢复。" 如果

git stash push

执行失败，发出警告并退出。

bash

git stash push -u -m "accesslint-diff-baseline"
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --update-snapshot
git stash pop && sleep 2
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --format json

分支模式（

--branch <name>

）。首先告知用户："正在与
<name>
分支进行差异对比——将检出该分支以捕获基准版本，之后将恢复。您的工作区将完全恢复。" 分支切换会触发重建，但不会刷新浏览器，因此CLI每次运行都会打开新标签页以读取当前构建结果。使用

--wait-for "<selector>"

参数可等待重建完成后再执行审计；如果不使用该参数，需提示用户：构建过慢可能导致基准版本过时。

bash

git diff --quiet && git diff --cached --quiet || git stash push -u -m "accesslint-diff-branch"
git checkout <branch>
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --update-snapshot [--wait-for "<selector>"]
git checkout - && git stash pop 2>/dev/null
npx -y @accesslint/cli@latest scan <target> --port "$PORT" --snapshot accesslint-diff --snapshot-dir /tmp --format json [--wait-for "<selector>"]

两次运行均需传入

--selector

和

--include-aaa

参数。

2. Report

2. 报告

Accessibility diff — http://localhost:3000/ vs main (94 rules, live DOM)
2 new · 1 fixed · 4 pre-existing hidden

New — Critical
- color-contrast — 2.1:1 (needs 4.5:1), #bbb on #fff
    where: main > p.subtitle   fix: darken to #767676
Fixed
- img-alt — <img src="old.jpg"> (no longer present)

For each new violation: where (selector verbatim, plus

file:line (symbol)

source

is present; don't fabricate), evidence, and fix (mechanical change or

NEEDS HUMAN

Don't edit. For fixes, apply the mechanical ones and re-run

accesslint:accessibility-diff

to verify; for bulk work hand off to

accesslint:accessibility-fix

Accessibility diff — http://localhost:3000/ vs main (94 rules, live DOM)
2 new · 1 fixed · 4 pre-existing hidden

New — Critical
- color-contrast — 2.1:1 (needs 4.5:1), #bbb on #fff
    where: main > p.subtitle   fix: darken to #767676
Fixed
- img-alt — <img src="old.jpg"> (no longer present)

对于每个新增违规项：需包含位置（保留原始选择器，如果存在

source

则添加

file:line (symbol)

；请勿编造）、证据以及修复方案（自动修复或

NEEDS HUMAN

人工处理）。

请勿编辑报告内容。对于修复，先应用自动修复方案，然后重新运行

accesslint:accessibility-diff

进行验证；如需批量修复，请使用

accesslint:accessibility-fix

。

3. Tear down

3. 清理

bash

npx -y @accesslint/chrome@latest stop --all  # skip if ensure reported "managed":false

bash

npx -y @accesslint/chrome@latest stop --all  # 如果ensure返回"managed":false则跳过此步骤

Notes

注意事项

```
ensure
```
determines the port; don't hardcode 9222.
CLI exit 2 means a bad URL or target, or the page never loaded; check the dev server.
A target name resolves the same in both runs only if
```
accesslint.config.json
```
is unchanged across the stash or checkout. If your changes touch the config, pass an explicit URL.
Stash mode:
```
sleep 2
```
covers most HMR cases; if the baseline looks identical to current, add
```
--wait-for "<selector>"
```
.
Branch mode: no HMR; the CLI opens a fresh tab each run, and
```
--wait-for
```
is the rebuild gate.
Large DOM changes between runs cause selector drift; re-run
```
accesslint:accessibility-scan
```
for the full picture.

```
ensure
```
命令确定端口；请勿硬编码为9222。
CLI退出码为2表示URL或目标无效，或页面未加载；请检查开发服务器。
只有当
```
accesslint.config.json
```
在暂存或检出操作前后未发生变更时，目标名称在两次运行中的解析结果才会一致。如果您的变更涉及配置文件，请传入明确的URL。
Stash模式：
```
sleep 2
```
可覆盖大多数HMR（热模块替换）场景；如果基准版本与当前版本看起来完全相同，请添加
```
--wait-for "<selector>"
```
参数。
分支模式：无HMR；CLI每次运行都会打开新标签页，
```
--wait-for
```
参数是重建完成的触发条件。
两次运行之间DOM发生较大变更会导致选择器偏移；如需完整情况，请重新运行
```
accesslint:accessibility-scan
```
。