html验证失败应卡在pr阶段而非sprint评审，需通过html-validate/vnu.jar自动拦截语法错误、缺失alt等；语义化是验收必检项，须用axe-core确保violations为0；构建产物和多语言页需单独校验；设计师交付物须含html结构约束说明。
HTML验证失败直接卡住Sprint评审
HTML语法错误、缺失alt、未闭合标签这类问题，只要CI流水线里接入了html-validate或vnu.jar，就能在PR阶段自动拦截。别等Sprint评审时现场打开浏览器开发者工具才发现<img>没src——那时改代码+回归测试已来不及。
实操建议：
- 把
html-validate配置成npm run validate:html脚本，加入pre-commit和CI的test阶段 - 团队共用一份
.htmlvalidate.json，重点开启require-alt、require-lang、no-unknown-elements规则 - 对CMS生成页或模板引擎输出（如
handlebars），需在配置中用ignoreFiles排除动态片段，否则误报率高
语义化不是“加分项”，而是验收必检项
用<div class="heading">代替<code><h2></h2>，或把导航塞进<span></span>里，视觉上没问题，但会破坏屏幕阅读器路径、影响SEO权重，也违反WCAG 2.1 AA级要求。Sprint计划会必须明确：所有新增页面组件，需通过axe-core扫描且violations为0才能进入评审。
实操建议：
- 本地开发时加Chrome插件
Axe DevTools，右键→“Analyze”一键检测 - 自动化集成选
jest-axe，配合React/Vue组件测试，在describe里写expect(await axe(container)).toHaveNoViolations() - 警惕“伪语义”：比如给
<button></button>加role="link"却不处理Enter/Space键行为，反而更不合规
构建产物里的HTML不能靠“肉眼确认”
开发环境跑的是源码模板，构建后可能被Webpack插件（如html-webpack-plugin）注入<script></script>、删空格、甚至重写<base href>。Sprint验收前必须验证实际部署包里的index.html，而不是本地localhost:3000看到的。
实操建议：
- CI中增加步骤：解压构建产物zip包 → 运行
html-validate dist/index.html→ 失败则exit 1 - 对多语言站点，确保每个
dist/zh-CN/index.html、dist/en-US/index.html都单独校验，避免i18n插件漏替换lang属性 - 若用CDN缓存，记得清缓存后再抓取线上HTML做二次校验——有时构建成功但CDN回源失败，线上HTML仍是旧版
设计师交付物要带HTML结构约束说明
UI设计稿里一个“卡片组件”没标注是否需要<article></article>包裹、内链是否强制用<a href></a>而非<div onclick>，前端实现就容易自由发挥。Sprint Backlog条目里，每个页面需求必须附带<code>semantic-structure.md文档，列明根元素、关键ARIA属性、焦点顺序逻辑。
实操建议：
- 用Figma插件
Stark或Whimsical导出可读的结构注释，转成Markdown嵌入Jira任务描述 - 评审时对照
semantic-structure.md逐项检查DOM树，用document.querySelector手动验证role和tabindex是否到位 - 拒绝“样式优先”的实现：比如为动画效果把
<nav></nav>改成<div>再加CSS类，必须同步补全<code>role="navigation"及键盘导航支持真正卡住Sprint的往往不是功能没做完，而是HTML层面的隐性债务——它不报错，但会让无障碍测试挂掉、让SEO爬虫跳过、让后续组件复用成本翻倍。把
html-validate和axe当成编译器一样的硬性门槛，比事后修bug省十倍力气。
