我手里 25 个产品全在线上跑着,上线前有一套体检:页面能不能打开、链接断没断、速度过不过关。这些都过了,我以前就觉得可以发了。后来我发现这套检查漏了一整面:页面能打开,不等于人人能用。键盘走不走得通、读屏读不读得出、字放大两倍版式塌不塌——打开页面是看不出来的。所以我给工具箱加了一个新 skill:无障碍审计,专门补这一面。

方法从哪来:拿现成的好方法改编,不从零造

这个 skill 不是我凭空写的。自我进化雷达今天上午翻到 addyosmani 的 agent-skills 仓库,里面有个 accessibility-engineering 技能,讲怎么按 WCAG 2.2 AA 标准审计已有界面。仓库是 MIT 协议,我按 GitHub API 核实过,改编没有许可证问题。我保留了它的方法骨架,补了中文说明、业务映射和适用边界,写成 157 行的 skill 文件。原技能配套的 audit-a11y.sh 脚本我没搬,只借鉴方法。

它在我这的定位很具体:19 个子域加 15 个微产品,上线前先确认页面能打开,再确认人人能用。和 chrome-devtools 技能分工明确:后者在真 Chrome 里打开页面、截图、看控制台,确认页面能打开;这个 skill 负责 WCAG 2.2 AA 合规审计,确认页面人人能用。顺序不能反,先打开截图,再走审计。

四阶段流程:先跑工具,再动手验

第一阶段跑自动化审计,版本钉死原文给的数字,不要随手升:npx --yes @axe-core/cli@4.13.0 http://localhost:3000 --exit,结果加 --dir ./a11y-reports --save axe.json 留 JSON 备查;再用 npx --yes pa11y@9.1.1 http://localhost:3000 做 HTML 校验。axe-core 的包本身不带 CLI,所以用的是 @axe-core/cli。

结果按严重度分四档,先修上面两档:Critical 是读屏完全进不去,比如信息图没 alt、空按钮;Serious 是内容很难触达,比如对比度不够、表单没 label;Moderate 是造成困惑,比如标题层级跳号;Minor 是观感问题。每条结果先在浏览器里看一眼元素本身,确认是真问题再修——工具会报假阳性,照单全修会越修越糟。

第二阶段手动验证。键盘:Tab 走完所有可交互元素,焦点看得见;Enter 和 Space 能激活按钮和链接;Esc 能关弹窗;没有键盘陷阱。读屏:macOS 用 VoiceOver、Windows 用 NVDA,按标题、地标、链接导航各走一遍,填一次表单、走一次动态更新。视觉:正文对比度 4.5:1、大字 3:1、UI 组件 3:1;放到 200% 看布局破不破;开了减少动态,动画停了没有。

第三阶段修,顺序不要反:先修根因——<div> 换成 <button>、补 <label>、补 alt;再补 ARIA 做桥,只有原生 HTML 表达不了的模式才加 ARIA;修完复测,自动化和手动验证都重走一遍。不要用 aria-label 满天飞:语义化 HTML 是地基,ARIA 是桥。第四阶段复验:Critical 和 Serious 必须清零;其余分档要么修掉,要么写进已知问题清单并标明影响范围,不许默默留着。

最关键的一条边界:工具跑绿了不算通过

整个 skill 里我最看重的是适用边界那一段:自动化工具只能算烟雾测试,不能证明合规。键盘全流程、读屏实测、200% 缩放下的布局、真机触屏目标尺寸这四类,必须真人或真机复核,工具跑绿了也不算通过。触屏目标尺寸是 24×24 CSS px 起,44×44 是 AAA 目标,别混了。

验收清单里有一条我特意写死:读屏导航已验证,要写明用的浏览器加读屏组合;没测就写“未测”,不许写“已验证”。这和我另一篇讲验收的文章是同一个态度:没证据的话不许写成已完成。Lighthouse 绿灯不是合格证,axe 过了也不是。还有一条:一次审计只对“当时那个页面加当时那个版本”负责,改了组件、换了主题色、改了文案,都要重跑自动化那一步。

它和上线前体检不是一回事

我已经有个上线前体检产品 check.gaoqiangq.cn,44 条规则,面向 GitHub 仓库做自动化规则体检。这个 skill 是“怎么做一次无障碍审计”的方法,两者各做各的,只在“上线前体检”这个环节互相补位。性能也一样:debug-optimize-lcp 管加载速度,和这个 skill 别混成一件事。

上线 25 个产品的人,最容易犯的错是把“能打开”当成“能用”。多一个 skill 不会让页面自己变好,但它把“人人能用”从一句口号变成一张清单:四阶段、四个严重度、十条验收项。下次上线前,照着走一遍就行。

来源

addyosmani/agent-skills,skills/accessibility-engineering/SKILL.md(MIT 协议,2026-11-19 经 GitHub API 核实):GitHub 仓库

WCAG 2.2(W3C 万维网联盟,无障碍内容标准):W3C 官方文档

axe-core(Deque Systems,无障碍规则引擎):GitHub 仓库

pa11y(HTML 无障碍校验工具):GitHub 仓库

我的无障碍审计 skill(改编自 addyosmani/agent-skills):~/workspace/custom-skills/accessibility-audit/SKILL.md;方法由自我进化雷达 2026-11-19 上午档收录,当日立项。