不加lang="zh-CN"、嵌套<main>、标题跳级——这三类错误任一发生，页面就在渲染安全、可读性、无障碍三方面同时失守。lang必须写在<html>上以确保分词与语音准确；<main>须为<body>直接子元素且唯一；标题必须连续层级（h2后不可直接h4），否则屏幕阅读器导航逻辑塌方。
不加 lang="zh-CN"、把 <main> 套在 <div> 里、标题跳级（比如 <h2> 后直接 <h4>），这三件事只要发生任意一项，页面就在安全、可读性、无障碍三方面同时失守——不是“体验差”，而是基础结构已失效。
为什么 lang="zh-CN" 必须写在 <html> 标签上
浏览器和屏幕阅读器（NVDA/VoiceOver）依赖 lang 属性决定分词、标点朗读方式和语音引擎。写成 lang="ch" 或漏掉，中文内容大概率被读成日语腔调，或整段跳过；lang="zh" 不符合 IETF 标准，部分 AT 工具会 fallback 到英文。
- 必须是
lang="zh-CN"（简体）、lang="zh-TW"（繁体）或lang="zh-HK"（港澳），后缀不可省略 - 必须直接写在
<html lang="zh-CN">上，不能只靠<meta>或 JS 动态插入 - 多语言页面中局部切换语言，用嵌套：例如
<p lang="en">Hello world</p> - React/Vue 中避免运行时拼接
locale变量，确保 SSR 输出的首屏 HTML 就带对
<main> 必须是 <body> 的直接子元素且唯一
<main> 是 W3C 定义的“独立、可分发、可索引”主内容区。一旦嵌套在 <div class="wrapper"> 或 <section> 里，屏幕阅读器会忽略它，Googlebot 也可能降权。
- 错误写法：
<body><div class="container"><main></main></div></body>—— 这个<main>在无障碍树里不可见 - 正确结构：
<body><header></header><main></main><footer></footer></body> -
<main>内部可以有<header>和<footer>，但不能再出现第二个<main> - 组件化项目中，需在布局层统一控制输出，禁止子组件意外渲染
<main>
标题层级断裂会让屏幕阅读器用户“掉层”导航
用户按 H 键逐级跳转时，依赖的是显式存在的 <h1>～<h6> 构成的语义树。如果结构是 <h2>产品介绍</h2><h4>规格参数</h4>，中间缺 <h3>，AT 就会认为“产品介绍”章节已结束，后续内容无法被定位。
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
立即学习“前端免费学习笔记（深入）”；
- 常见原因：CSS 用
display: none隐藏了某个<h3>却没删 DOM；第三方组件默认用<h2>作卡片标题，嵌套在<h2>主区域下 - 修复方式：删 DOM 而非仅视觉隐藏；若必须保留，用
aria-hidden="true"+ 视觉隐藏类（如visually-hidden）替代display: none - 每个
<section>应以<h2>或更高级别标题开头；HTML5 允许重置层级，但前提是显式提供标题 - 不要用
<div role="heading" aria-level="3">替代原生标签，除非完全无法改结构
CI 阶段必须集成 HTMLHint 做自动化校验
人工检查易遗漏，且无法覆盖 SSR/模板渲染场景。HTMLHint 可在 pre-commit 或 CI 流水线中强制拦截问题，例如 doctype-first、meta-charset-require、attr-lowercase 等规则。
- 关键规则建议启用：
doctype-first、lang-require、attr-lowercase、id-class-value、head-script-disabled - VS Code 中安装 HTMLHint 扩展后，编辑时即可实时提示
<main>嵌套、lang缺失等严重问题 - Git hooks 中配置 pre-commit 检查，防止带错
lang或嵌套<main>的代码合入主干 - 注意：HTMLHint 默认不校验标题层级连续性，需配合 axe-core 或 custom rule 补充
真正难的不是写出合规的 HTML，而是在组件复用、SSR 渲染、多语言切换、第三方库集成这些真实场景里，始终守住 lang、<main>、标题层级这三条底线——它们一旦松动，所有后续的 a11y 优化都建立在流沙之上。
