核心是把语义标签写进开发规范和代码审查清单,不是贴在Wiki上就完事:

  • main必须全页唯一,且不能嵌套在articlesectionheader里;CI流水线可加HTML validator(如html-validate)校验<main></main>出现次数
  • 禁止给mainclassid——它本身就是语义锚点,样式应通过后代选择器(如main h1)或CSS自定义属性控制
  • 组件库中所有“内容容器”类组件(如<pagecontent></pagecontent>)的模板必须默认输出<main></main>,而非<div role="main"> <h3>为什么<nav>不能套在<div class="header">里? <p>因为<code>nav的语义是“主导航区域”,不是“导航样式的div”。嵌套错误会破坏辅助技术的导航逻辑:

    • 屏幕阅读器按nav标记跳转时,若它被包裹在div中,可能被忽略或误判为普通区块
    • header可以包含nav,但nav不能作为div的子元素还声称自己是导航——这等于给一个没有role的div加aria-label="导航",冗余且不可靠
    • 真实场景中,侧边栏的“快捷链接”、文章末尾的“相关阅读”都不该用nav,而该用aside或普通ul;只有顶部/底部主导航、面包屑、分页控件才符合nav定义

    如何避免
    变成另一个

    section不是视觉容器,是主题容器。滥用它的项目,90%都漏了标题:

    Markdown to HTML
    Markdown to HTML

    {"answer":"将 Markdown 转换为内嵌 CSS、样式精美的独立 HTML。完美适用于新闻简报、文档、报告及邮件模板。"}

    下载
    • 每个section必须有且仅有一个h2h6作为其显式标题(不能靠CSS伪元素生成,也不能用div class="title"模拟)
    • 如果删掉这个标题,用户无法立刻判断该区块讲什么——那它就不该是section,而是divarticle
    • 嵌套section要谨慎:section > section只在子主题明确独立时才合理(例如“安装步骤”下再分“Windows”“macOS”小节),否则就是语义套娃

    哪些地方最容易被忽略?

    不是标签选错,而是上下文断开:

    • time标签必须带datetime属性,否则对机器无意义;<time>2026年8月</time>不如不用
    • figure/figcaption必须成对出现,且figcaption要真正描述图的内容,不是“示意图”这种废话
    • blockquote必须包裹他人原话,不是用来缩进强调自己写的句子;引文出处要用cite,不能塞进span

    语义化真正的成本不在写标签,而在每次改结构时,重新问一句:这块内容去掉样式后,别人还能看出它是啥吗?