html代码质量合规化重塑是全链路重校准，涵盖语义结构、焦点流、颜色系统与动态反馈；wcag 2.1 aa级本质是交互逻辑的重新定义，而非检查清单。
直接说结论：HTML代码质量合规化重塑不是“加几个aria-属性就完事”，而是从语义结构、焦点流、颜色系统到动态反馈的全链路重校准。WCAG 2.1 AA 级不是检查清单，是交互逻辑的重新定义。
语义化标签不能只靠视觉对齐
很多人把<header></header>、<nav></nav>当成视觉容器来用，结果是屏幕阅读器能读出标签名，但逻辑关系断裂。比如一个<nav></nav>里塞了广告位和搜索框，它就不再是“主导航”。
- 用
<nav aria-label="主导航"></nav>明确意图，而非依赖CSS类名暗示 -
<main></main>必须且只能出现一次，且不能嵌套在<article></article>或<section></section>内 - 时间、地址、联系人等信息优先用
<time></time>、<address></address>，不要统一用<div class="meta"> <li>表格必须有<code><caption></caption>或aria-labelledby，否则屏幕阅读器无法理解上下文 - 所有交互控件（按钮、输入框、下拉、滑块）必须能通过
Tab抵达，且顺序与视觉流一致 - 模态框打开后，焦点必须自动移入，且
Esc关闭时焦点要回退到触发按钮 - 禁用状态元素（如
disabled按钮）仍需保留在Tab顺序中，否则用户会误以为功能缺失 - 动态插入的内容（如加载后的列表）需用
aria-live="polite"通知屏幕阅读器，但不能打断当前朗读 - 正文文本与背景对比度必须≥4.5:1，大号文字（≥18pt或粗体≥14pt）≥3:1
- 图标按钮必须带
alt或aria-label，不能仅靠颜色区分状态（如绿色=开启/灰色=关闭） - 错误提示不能只改边框颜色，要叠加图标+文字+
aria-invalid="true"和aria-describedby - 高对比度模式需用
@media (prefers-contrast: high)主动适配，而不是靠系统强制反转 - 复杂组件（如树形菜单、多步骤向导）才需完整ARIA标注：
role、aria-expanded、aria-controls、aria-level缺一不可 -
aria-hidden="true"不能乱加——隐藏了视觉元素，也同时屏蔽了屏幕阅读器，除非确认该内容纯装饰 - 所有
aria-*属性值必须是合法字符串或布尔值，aria-valuemin="0"写成aria-valuemin="zero"会导致解析失败
键盘焦点流必须可预测、不可跳过
Tab键顺序错乱、焦点消失、模态框逃逸——这些不是UI bug，是可访问性致命缺陷。Gradio、Streamlit等低代码框架生成的界面常默认禁用键盘导航。
颜色对比度不是设计师的事，是HTML验证环节
对比度不足的按钮，在Color Contrast Analyzer里标红，但在浏览器里看起来“好像也还行”。这种侥幸心理会导致大量AA级不达标项。
ARIA不是补丁，是语义缺位时的临时替代
滥用role="button"包裹<div>，比不用更危险——它欺骗辅助技术，却没提供键盘事件支持。<ul><li>优先用原生语义元素：<code><button></button>代替<div role="button">，<code><input type="checkbox">代替自定义复选框
真正难的不是写对某一行aria-label，而是当产品需求变更、UI快速迭代时，还能守住焦点路径不崩、语义层级不塌、对比度不掉。这需要把可访问性检查嵌入CI流程，用axe-core跑自动化扫描，再辅以真实屏幕阅读器人工走查——否则，代码越“新”，障碍越深。
