用途:在任何人查看页面前,先度量真实浏览器中已渲染的屏幕。测量逻辑集中在自包含的 scripts/checks.js 中,因此可与任意浏览器工具配合。
主要能力:对比度基于实际绘制颜色进行像素取样;检查边框对比度、控制项对比度(WCAG 1.4.11)、悬停与聚焦状态对比度;通过逐个 Tab 走查键盘焦点;在触屏视口检查 44px、指针视口检查 24px 的命中区域;检查触控动作、减少动效、嵌套圆角、间距刻度、行宽、主操作数量、标题换行、图标刻度、视口溢出、缩放锁定和控制台错误。每个问题都附带分母。
用法(任意浏览器工具):以真实视口打开页面,等待字体,再在页面中求值 scripts/checks.js 内容——例如浏览器控制台、Claude in Chrome、Chrome DevTools MCP、agent-browser、Puppeteer 或任意 evaluate 调用。脚本为单个表达式,返回 JSON 报告,并保留在 window.__keroAudit。可选配置需在求值前设置:window.KERO_AUDIT = { minText: 14, icons: [16, 20, 24], spacing: [4, 8, 12, 16, 24, 32], measure: [45, 80] };。
用法(Playwright):启动开发服务器后,在项目根目录运行:node <skill-dir>/scripts/audit.mjs --routes /,/pricing,/settings --viewports 390x844,1440x900。它会注入同一份 checks.js,并补充需要驱动浏览器才能做的检查:走查键盘、强制悬停与聚焦、以减少动效重载、收集控制台错误、循环路由与视口并保存截图。
安装与命令:项目需安装 playwright 或 playwright-core(npm i -D playwright-core),使用已安装的 Chrome;没有 Chrome 时需 Playwright 的 Chromium,而 playwright-core 不会下载它:运行 npx playwright install chromium 一次。在 Windows 的 Git Bash 中,路由不要带前导斜杠(home,pricing,settings,其中 home 为 /),脚本路径写为 C:/...,因为 shell 会把前导 / 重写为 Windows 路径。不要使用 MSYS_NO_PATHCONV=1。
选项与退出码:可通过命令行参数或配置文件(命令运行目录下的 kero-audit.json,或 --config 指定,使用同名 camelCase)读取。--url 默认取 3000、3001、3002、4321、5173、8080 上找到的第一个服务器;--routes 默认 /;--viewports 默认 390x844(宽度低于 1024 计为触屏);--min-text 默认 14;--icons 默认 off(不超过 64px 的 SVG 计为图标,更小的图用 data-illustration 标记);--spacing 默认 4 的倍数;--measure 默认 45,80;--states-max 默认 40;--out 默认 audit;--config 默认 kero-audit.json;--json 默认 off;--verbose 默认 off。使用 Playwright 时,出现硬故障(文本、控制项或状态对比度低于 WCAG AA、横向滚动、缩放锁定、路由加载失败)退出码为 1,否则为 0,可用于提交或 CI 门禁。
限制:notMeasured 列出需要驱动浏览器而未被检查的项目——键盘焦点、悬停与聚焦状态对比度、减少动效和控制台错误,应报告为未检查,绝不记为零,或手工完成。图片上的文字单独计数而不测量;禁用控件不计入。开发覆盖层(Next.js、Vite、Astro)会被忽略。审计捕捉的是违反规则的问题,而非看起来不对的问题。应优先修复硬故障,再处理边界对比度与小目标;信任一次干净运行前先检查它打印的基准 URL。当项目规则可测量但不在本工具中时,可将其加入项目副本的脚本并写入项目设计技能(kero-system)。