HTML可读性指标必须可自动抓取、量化且与维护成本强相关，包含缩进统一、块级元素独占行、空行规范、闭合标签对齐四项；语义化需严格匹配内容职责，注释须指向结构意图；自动化检查需覆盖格式、语义、可访问性三层并设为error级别。
HTML可读性指标必须能被工具自动抓取，不能只靠人眼判断
可读性不是主观感受，而是可测量的结构特征。团队一旦把“看着舒服”当标准，审查就退化成风格争论。真正有效的指标必须满足：能在CI流程里跑出布尔值（通过/不通过），能定位到具体行号，且和后续维护成本强相关。
以下四项是尚拓云测在20+项目中验证过的最小可行指标集：
-
indent_size必须为 2 或 4，且全项目统一；混用空格与 tab 触发警告 - 块级元素（
<div>、<section>、<article>等）必须独占一行，禁止<div><p>文本</p></div>写在同一行 - 相邻逻辑区块间必须有且仅有一个空行，例如
<header>和<main>之间空一行，但<main>内部的<h2>与<p>之间不加空行 - 每个闭合标签后必须换行，且结束标签缩进与对应开始标签对齐，如
<nav>缩进 2 空格，则</nav>也缩进 2 空格
语义化不是“多用新标签”，而是标签与内容职责严格匹配
审查时最常误判的点：把 <section> 当 div 用，或硬塞 <article> 进非独立内容。语义错误不会导致页面崩溃，但会破坏可访问性、SEO 和后期重构路径。
落地时建议用三问法快速判断：
立即学习“前端免费学习笔记（深入）”；
- 这个内容是否能脱离当前页面独立存在？→ 能则用
<article>，否则不用 - 这个区域是否与主内容弱相关但可独立移除？→ 是则用
<aside>，比如侧边广告、作者简介 - 这个标题是否真实承担了层级结构功能？→
<h2>后直接跟<h4>属于结构性错误，必须报错
注意：<div> 没被淘汰，它仍是“无语义容器”的合法选择——当你明确不需要传达任何结构含义时，用 <div> 反而是正确做法。
注释必须指向结构意图，而非重复标签名
常见无效注释：<!-- header -->、<!-- end div -->。这类注释在 Prettier 自动格式化后极易失效，还增加维护噪音。
真正有用的注释只出现在两类位置：
- 大型嵌套容器结束处，标明其语义作用，例如
<!-- .product-grid: 用于响应式商品卡片列表，每行最多4项 --> - 绕过标准语义但有明确交互逻辑的地方，例如
<!-- aria-hidden="true" 为兼容旧屏幕阅读器，实际由 JS 控制焦点流 -->
所有注释必须用 kebab-case 命名，并以英文冒号分隔说明，避免中文注释在构建过程中因编码问题乱码。
自动化检查必须覆盖“格式+语义+可访问性”三层，缺一不可
只配 prettier 或只跑 htmlhint 都不够。前者管缩进换行，后者管标签拼写，但都看不到 <button> 是否漏了 type="button" 导致表单意外提交。
推荐组合配置：
- 格式层：Prettier +
html插件，强制统一缩进与换行 - 语义层：
html-validate配置自定义规则，例如禁止<div role="button">（应优先用<button>） - 可访问性层：
axe-coreCLI 在 CI 中扫描，拦截label missing for input类错误
关键细节：所有工具报错必须设为 error 级别，而非 warning。warning 在 MR 中容易被忽略，而 error 会阻断合并——这才是规范落地的真实门槛。
最容易被跳过的其实是注释规范和空行规则，它们不报错、不崩页面，却在三个月后让新成员花两小时搞不清一个 <section> 到底包裹了什么逻辑。可读性指标的价值，正在于守住这些“看不见的腐烂点”。
