maxgfr/ultra11y

ultra11y — 审计 RGAA 4.1.2 并编写无障碍代码

在无障碍领域，自动化工具只能发现部分问题。 ultra11y 通过分工来应对这一问题：确定性、零依赖的引擎（node scripts/ultra11y.mjs <命令> — 无需 npm install，无需密钥）完成机械性工作——检测机器可验证的不符合项并将其关联到正确的 RGAA 标准；而您则负责判断——替代文本的相关性、上下文中的标签、阅读顺序——以及需要渲染的标准（对比度、焦点、缩放）。门控机制可防止任何幻觉产生的不符合项存活。

核心规则：

1. 绝不捏造不符合项：每条 NC 都引用一个真实且可解决的元素（通过 check 验证）。
2. 原生 HTML 优先，ARIA 最后：不要重复隐含的语义。
3. 剩余项必须明确：任何未经验证的渲染/ 判断标准都进入“需人工评估”列表，绝不能默默标记为符合。

根据场景选择

• “审计 / 生成合规报告” → node scripts/ultra11y.mjs audit … --json， 然后 report，然后 check；阅读 references/audit.md。
• “在大型仓库上 / 智能审计” → 聚焦：--changed（git diff）， 优先处理模板，去重，--max-files；阅读 references/scale.md。
• “应用修复” → fix（默认 dry-run，--write 应用 安全的修复，其余修复以建议形式给出而不自行发明）；阅读 references/fix.md。
• “在仓库中自动防护（hook / CI）” → init --hook/--ci/--baseline （仅在出现新的不符合项时才失败）；阅读 references/automation.md。
• “使此代码可访问 / 审查它” → 审计片段 （audit - < 组件.html）遵循原生优先原则；阅读 references/authoring.md 和 references/forbidden-patterns.md。
• “标准 X 的含义 / 主题是什么” → criteria；参见 references/criteria.md。
• “国际标准（WCAG / EN 301 549 / Section 508）” → 在 report/criteria 上使用 --standard wcag ；参见 references/methodology.md。
• “高保证度审计” → verify --report … --semantic；参见 references/verify.md。方法论与格式：references/methodology.md。
• “检查对比度 / 渲染（可选的 Docker 层）” → scan <url> --merge … （在无头浏览器中使用 axe-core）；参见 references/dynamic.md。

命令速查表

node scripts/ultra11y.mjs audit "src/**/*.html" --json > audit.json
node scripts/ultra11y.mjs audit - < 组件.html        # 通过 stdin 传入 HTML
node scripts/ultra11y.mjs audit "src/**/*.tsx" --jsx       # JSX/TSX 尽力支持
node scripts/ultra11y.mjs audit --changed --json           # 仅 git diff（大型仓库）
node scripts/ultra11y.mjs report --in audit.json --out audits
node scripts/ultra11y.mjs report --in audit.json --standard wcag   # WCAG 视图（演示）
node scripts/ultra11y.mjs criteria 11.1                    # 一个标准及其测试
node scripts/ultra11y.mjs criteria --theme 8 --list        # 一个主题 / 列出所有
node scripts/ultra11y.mjs check  --report audits/rgaa-AAAA-MM-JJ.md
node scripts/ultra11y.mjs verify --report audits/rgaa-AAAA-MM-JJ.md --semantic
node scripts/ultra11y.mjs fix "src/**/*.html"              # dry-run；--write 应用修复
node scripts/ultra11y.mjs init --hook --baseline           # 回归防护（hook + baseline）
node scripts/ultra11y.mjs scan https://example.fr --merge audits/audit-latest.json  # Docker 层

所有命令均可使用 --json 输出机器可读结果。报告默认用法语生成，可使用 --lang en 切换为英语。

结合引擎、判断和残余风险

audit 输出将每个标准分类：对于静态子集为 C/NC/NA；对于渲染/判断标准则为 manual（列在 residualRisks 中）。引擎产生的 NC 是已确认的候选（引用了 文件:行号）。您需要裁定 manual 类别下的标准，并将渲染标准标记为“需人工验证”。只有当每个可适用的标准都被有依据地标记为 C/NC/NA，并且每个残余风险都被命名时，报告才算完成。

禁止事项

• 捏造引擎未找到且您无法验证的不符合项（对于内联字面颜色的对比度，静态分析已裁定；计算后的对比度——来自外部 CSS、变量——需要通过 scan（Docker 层）或在渲染后验证，才能声明为不符合项）。
• 添加与原生语义重复的 ARIA。
• 未经人工验证就将渲染/判断标准标记为“符合”。
• 手动编辑 references/criteria.md（它是从标准仓库自动生成的）。

适用范围

静态引擎：离线、确定性、零依赖；输入支持 HTML + JSX/TSX（尽力支持）+ stdin。渲染标准（计算后的对比度、reflow）由可选的 scan 层（Docker 中的 axe-core）覆盖；可见焦点、200% 文本缩放和悬停内容则仍需人工审查（作为残余风险）。数据来源：RGAA 4.1.2 © DINUM，Licence Ouverte / Etalab 2.0（参见 NOTICE）。