HTML代码质量差会直接拖慢迭代节奏：CI因aria-*缺失失败、测试脚本定位失败、新人理解成本高；role和aria-属性仅在必要时添加，避免干扰读屏器；交互元素须有明确tabindex和键盘焦点路径；data-testid应反映行为意图而非位置样式，且不得用于CSS选择器。
HTML 代码质量差，不是“看着不爽”的问题，而是会直接拖慢迭代节奏：CI 流水线因 aria-* 缺失失败、测试脚本因无语义结构定位不到元素、新成员改个按钮要花半小时理清嵌套逻辑——敏捷团队没时间返工。
检查 role 和 aria- 属性是否只在必要时出现
很多团队把 role="button" 或 aria-label 当装饰用，结果反而干扰屏幕阅读器或触发 Lighthouse 可访问性警告。React/Vue 组件库已默认处理多数语义，手动加反而错。
- 仅当原生 HTML 元素无法表达交互意图时才加
role：比如用<div>实现折叠面板，必须加role="region"+aria-expanded -
aria-label优先于aria-labelledby；但若标签文本已可见（如按钮内文字），不要重复加 —— 这会导致读屏器读两遍 - 检查构建产物（非源码）：Svelte/Next.js 等可能在编译时移除未使用的
aria-，本地开发看着有，上线就丢
确保所有交互元素都有明确的 tabindex 和键盘焦点路径
“能点就行”是前端最常踩的坑。QA 用鼠标点通了，但产品验收时用键盘操作卡死在第 3 个卡片——这在每日站会后 2 小时内就得修复，没时间查 DOM 树。
- 原生可聚焦元素（
<button>、<a href>、<input>）默认tabindex="0"，禁止手动设tabindex="0"，否则会破坏默认顺序 - 自定义组件（如
<app-toggle>）必须响应Enter和Space键，并在 JS 中调用element.focus()主动接管焦点 - 用浏览器 DevTools 的
Elements > Accessibility面板实时查看焦点顺序，比写测试更快
验证 data-testid 是否与组件逻辑解耦
E2E 测试频繁失败？大概率是 data-testid="header-button-3" 这类硬编码标识随 UI 调整失效了。敏捷团队的测试稳定性和交付速度强相关。
立即学习“前端免费学习笔记（深入）”；
-
data-testid值必须反映行为意图，而非位置或样式：用data-testid="save-draft-btn"，不用data-testid="primary-btn-2" - 禁止在 CSS 选择器中引用
data-testid（如[data-testid*="btn"]）—— 这会让样式和测试强耦合，重构时不敢动 - CI 阶段用
grep -r "data-testid=" src/ | grep -v "test"快速扫出漏删的调试用标识
真正卡住交付的，往往不是没写语义化标签，而是写了却和 JS 逻辑冲突（比如 aria-live 区域被 Vue 的 v-if 频繁销毁重建），或者测试标识随组件拆分散落在三个文件里。每次 PR 前花 90 秒过一遍这三条，比等 CI 报错再修快得多。
