必须强制采用kebab-case命名并配合BEM约定，如card、card__title、card--featured，禁用驼峰、下划线、大写及泛语义词，确保模块独立闭合、语义清晰、验证合规。
模块化拼装时 class 命名不统一导致样式错乱
多个模块由不同人开发或复用旧代码时，class 名称风格混杂（比如 header-wrap、topSection、HeaderContainer 同时存在），CSS 选择器匹配失效或覆盖失控，最终表现为样式“时有时无”或局部失效。
必须强制采用 kebab-case（全小写+短横线）命名，且配合 BEM 约定明确层级关系。例如一个卡片模块应统一为：card（Block）、card__title（Element）、card--featured（Modifier）。
- 禁止使用驼峰、下划线、大写字母——它们在 CSS 中需转义或与预处理器行为冲突
- 避免泛用
container、wrap、box等无语义词，改用article-list、nav-primary等可读性强的名称 - 构建工具（如 Webpack + html-loader）中若启用了
html-minifier，需关闭collapseBooleanAttributes以免误删class属性值中的短横线
嵌套深度失控让模块失去独立性
常见错误是把整个页脚塞进 <section></section> 再套一层 <div class="wrapper">，结果模块一复用就带出多余父级结构，破坏语义且干扰 <code>main / aside 的逻辑边界。
每个模块应以语义化根标签起始，且自身闭合完整。例如页脚模块必须是：<footer class="site-footer">...</footer>，而非 <div class="footer-wrapper"><footer>...</footer></div>。
立即学习“前端免费学习笔记（深入）”；
-
header、nav、main、aside、footer不得相互嵌套（main不能包header，aside不能包nav） - 模块内部嵌套不超过 3 层：根标签 → 容器（如
section或article）→ 内容单元（如h2、p、time） - 若需视觉分组但无语义，用
div且加明确注释，例如：<!-- group for spacing only --><div class="spacing-xxs">...</div>
复用模块时 DOCTYPE 和 lang 属性被遗漏
单独抽离的模块 HTML 片段（如通过 <template> 或构建工具 include 引入）若不含 <!DOCTYPE html> 和 <html lang="zh-CN">，在独立预览或 SSR 渲染时会触发怪异模式（Quirks Mode），导致盒模型、字体渲染异常。
模块本身不写 <html> 或 <head>，但必须确保引入它的宿主页面已正确定义这些根级属性；同时模块内所有子元素要严格遵循语义层级，不擅自提升标签权重。
- 禁止在模块内写
<html>、<head>、<body>—— 这些属于宿主页面职责 - 模块内所有
<img>必须带alt，<time>必须带datetime，否则复用后无障碍检测失败 - 使用
<template>时，其内容不会被解析，所以无需担心重复lang；但通过构建工具 inline 的 HTML 片段，需确认是否被包裹在合法上下文中
HTML 验证失败却仍能“看起来正常”
W3C Validator 报错 Element div not allowed as child of element header in this context，但浏览器照样渲染——这种“侥幸运行”会在 SEO 抓取、屏幕阅读器解析、PWA 缓存策略中暴露问题，且越到后期越难定位。
模块拼装不是“能显示就行”，而是每一块都经得起验证。关键检查点：布尔属性是否显式书写（required="required"）、自闭合标签是否省略斜线（<img> 而非 <img/>）、属性值是否全用双引号（class="nav-primary"）。
- CI 流程中加入
html-validate或w3c-validator-cli，对每个 HTML 模块文件做静态校验 - VS Code 安装插件
Auto Close Tag和Auto Rename Tag，实时防止标签错配 - 团队共享一份
.htmlvalidate.json规则，禁用宽松选项如attr-no-unsafe-char的忽略配置
拼装一致性最易被忽略的点不在语法，而在“谁负责收尾”——每个模块只管自己闭合，不替别人补漏；宿主页面才承担全局结构责任。一旦混淆这个边界，模块就从“零件”退化成“补丁”。
