敏捷开发流：把HTML代码质量纳入Sprint验收标准

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">代替<h2>，或把导航塞进<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>加role="link"却不处理Enter/Space键行为，反而更不合规

构建产物里的HTML不能靠“肉眼确认”

开发环境跑的是源码模板，构建后可能被Webpack插件（如html-webpack-plugin）注入<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>包裹、内链是否强制用<a href>而非<div onclick>，前端实现就容易自由发挥。Sprint Backlog条目里，每个页面需求必须附带semantic-structure.md文档，列明根元素、关键ARIA属性、焦点顺序逻辑。

实操建议：

立即学习“前端免费学习笔记（深入）”；

• 用Figma插件Stark或Whimsical导出可读的结构注释，转成Markdown嵌入Jira任务描述
• 评审时对照semantic-structure.md逐项检查DOM树，用document.querySelector手动验证role和tabindex是否到位
• 拒绝“样式优先”的实现：比如为动画效果把<nav>改成<div>再加CSS类，必须同步补全role="navigation"及键盘导航支持

真正卡住Sprint的往往不是功能没做完，而是HTML层面的隐性债务——它不报错，但会让无障碍测试挂掉、让SEO爬虫跳过、让后续组件复用成本翻倍。把html-validate和axe当成编译器一样的硬性门槛，比事后修bug省十倍力气。