语义标签误用导致屏幕阅读器失效、seo下降及dom查询失败，需严格遵循html5语义规范：header/main/article/section各司其职，禁用div模拟语义标签，避免class与语义冲突，确保跨iframe和template克隆的结构完整性。
组件库中 HTML 语义标签用错的典型表现
页面能渲染，但屏幕阅读器读不出结构、Lighthouse SEO 分数掉、document.querySelector('main') 返回 null——这些不是样式问题，而是语义标签误用的直接后果。
常见错误包括：<div class="header"> 替代 <code><header></header>；把轮播容器、筛选区硬塞进 <article></article>；在 <main></main> 外再嵌套一个 <main></main>；用 <section></section> 包裹整个页脚。
-
<article></article>必须可独立分发（如博客正文、新闻条目），不能用于“关于我们”这类页面内逻辑块 -
<section></section>必须有明确主题且含标题（<h2></h2>或更高），否则语义失效 -
<main></main>全局唯一，且不可嵌套在<article></article>或<section></section>内——它定义的是页面主内容边界，不是视觉容器
class 命名与语义标签冲突时怎么选
当团队坚持用 .card 而设计稿要求“推荐位卡片”，硬套 .card--featured 看似合理，但若外层是 <article></article>，就暴露了根本矛盾：类名在描述视觉变体，而标签本该表达内容角色。
真正要防的是「语义标签 + 表现类名」的双重背叛，比如 <nav class="flex-row justify-between"></nav> 或 <header class="float-right"></header>。
- 优先用语义类名：
.post-card比.flex-col更可持续；.search-form比.w-full更易维护 - 修饰符应强化业务含义而非视觉副作用：
.post-card--featured可接受，.post-card--large不推荐 - 禁止在语义标签上叠加布局类：
<nav></nav>的定位逻辑应由 CSS 控制，而非靠.ml-auto暴露意图
跨 iframe 组件嵌套时 DOM 结构突然失效
父页调用 iframe.contentDocument.querySelector('header') 返回 null，不是选择器写错，而是子页面文档上下文未就绪或降级为怪异模式。
关键检查点不在 JS 逻辑，而在子页面 HTML 的第一行和编码声明：
- 子页面首行必须严格为
，前面不能有任何字符（含 BOM、空格、注释） -
<meta charset="utf-8">必须紧随后第一或第二行，不能放在<title></title>后面 - 服务端响应头必须是
Content-Type: text/html; charset=utf-8，不能是text/plain或缺失charset - 避免在子页面
<script></script>中使用未转义的模板字符串（如``），会提前截断 HTML 解析
HTML 模块复用中 template 克隆后状态丢失
template.content.cloneNode(true) 克隆出的表单控件全被重置——<select></select> 回到默认项、<input type="checkbox"> 变成未勾选，这不是 bug，是 DOM 规范行为。
原生 <template></template> 不带状态，克隆只复制结构。要保留可序列化状态，必须用专用 API：
- 改用
document.importNode(template.content, true)，它是专为<template></template>设计的深拷贝方法 - 必须等
DOMContentLoaded后执行，否则template.content可能为空 - 克隆后通过
querySelector注入数据，别用innerHTML = ''覆盖——会清空事件绑定 - 禁止在
<template></template>内写id，克隆后 ID 重复会破坏document.getElementById和无障碍焦点流
语义结构不是锦上添花，而是组件可维护性的底线。一旦外层标签选错，所有 BEM 类名、CSS-in-JS 封装、甚至 Web Components 都救不回结构失焦——它们只是在错误的骨架上叠更多装饰。
