Web无障碍开发规范

人工走查缺位时，无障碍谁来兜底

在 AI 驱动的前端流程里，手动测试往往被压缩到极低比例，缺陷常常拖到上线才暴露。无障碍问题尤其隐蔽：用 <div> 伪装的按钮看起来一切正常，键盘用户却无法聚焦和触发；图片少了 alt 属性，视觉上毫无破绽，屏幕阅读器只能念出一串文件名。事后补修的成本远高于从第一天就做对，因此这套规范把无障碍优先设为所有开发任务的起点。

规范要求怎么做

• 语义化优先：能用原生元素就不自造组件。<button> 自带键盘聚焦与激活能力，<nav>、<main>、<form> 为页面划出清晰的结构地标；只有原生元素确实无法满足时才引入 ARIA，并必须记录选择理由。
• 代码即文档：凡为无障碍而写的实现，都要在注释中标注对应的 WCAG 2.2 条款等级，说明预期的用户流程。
• 键盘可达是硬指标：所有交互元素必须仅靠 Tab、Enter、Space 与方向键就能到达并操作，焦点指示器保持一致可见；自定义组件上 tabindex 只允许负值。
• 指标可量化：正文文本对比度不低于 4.5:1，大字不小于 3:1，按 (L1 + 0.05) / (L2 + 0.05) 公式或检查工具验证；鼠标拖拽类交互必须给出替代路径。
• 持续回归：把 pa11y 这类自动化检查纳入回归测试，每新增媒体就补 alt 文本，图标加标签，纯装饰元素用 aria-hidden="true"。
• 反模式清单：拒绝 <div onclick> 假按钮、outline: none、用 aria-label 顶替可见标签、给外链加 role="button" 等做法。

适用边界

• 规范不声称覆盖全部无障碍知识，遇到不确定的场景应查阅 W3C / WCAG / WAI-ARIA 官方资源并记录待办。
• 对已有代码库无法整体重构时，给出谨慎的局部建议，而不是推倒重来。
• lang 属性、skip links、prefers-reduced-motion、缩放回流、表单错误提示等事项仍需在项目中持续落实。
• 当需求本身可能引入无障碍缺陷时，先向用户说明风险并征询是否继续，而不是默默实现。