可访问性文档库是嵌入开发流程的活依赖项，需用HTML模板+JSON Schema管理可访问性模式，支持CI检查、VS Code提示和自动修复；每个模式有唯一ID并标记于代码注释中，CI解析后验证DOM结构与schema合规性；新增模式须同步提供codemod脚本和迁移指南，降低纠错成本。
可访问性文档库不是静态 Wiki，而是活的开发依赖项
它必须能被开发者在写 form、button、dialog 时直接查到对应模式，而不是翻三页才找到一个带 bug 的示例。这意味着文档库要嵌入开发流程：CI 流水线里跑 axe-core 扫描失败时，报错应直接链接到文档中对应组件的“修复建议”锚点；VS Code 插件输入 aria- 时，提示应来自文档库最新版的属性约束说明。
用 HTML 模板 + JSON Schema 管理可访问性模式
别用纯 Markdown 存“怎么写表单”。每个可访问性模式（如“带错误提示的邮箱输入”）应是一个最小可运行 HTML 片段，配一个同名 schema.json 描述其约束：
-
required-attributes列出必须存在的属性，比如label必须关联for或包裹input -
allowed-roles明确禁止滥用role="button"套在div上 -
test-cases写明该模式需通过的 axe 规则 ID，如label、landmark-one-main
构建脚本读取这些文件，自动生成文档页面、VS Code snippets 和 CI 检查规则。改一个 schema.json，所有下游都同步更新。
把文档库接入 PR 检查流水线
当有人提交含 role="tablist" 的代码，CI 不该只报“axe 检测失败”，而应定位到具体组件，并检查其是否匹配文档库中 tablist 模式的 schema.json。不匹配就拒绝合并——哪怕 axe 当前没报错，因为语义结构已偏离约定。
立即学习“前端免费学习笔记（深入）”；
关键点：
- 文档库的每个模式必须有唯一 ID（如
pattern-form-email-v2），代码中通过注释标记引用：<!-- @a11y: pattern-form-email-v2 --> - CI 工具解析注释，拉取对应 schema，验证 DOM 结构与属性是否合规
- 开发者本地
npm run check:a11y就能复现 CI 行为，无需等远端反馈
维护者最容易忽略的其实是“废弃路径”
旧项目里一堆 div role="button" onclick="..."，文档库不能只写“正确写法”，还得提供 codemod 脚本一键替换为 button 并补全 aria-label。每次新增模式，必须同步产出迁移指南和破坏性变更日志——否则团队会自然绕过新规范，继续抄老代码。
真正难的不是写清楚“什么对”，而是让“改错的成本低于不改的成本”。
