<p>DOCTYPE 和 lang 属性必须严格正确：<!DOCTYPE html> 独占首行无前缀，<html lang="zh-CN"> 大小写敏感；语义标签需按内容结构而非样式选用；HTML 格式化须自动化；注释与 data-* 属性应明确业务意图。</p>
DOCTYPE 和 lang 属性必须写对，否则后续所有语义化都白搭
很多团队在初建项目时会跳过文档类型和语言声明，结果在后期接入无障碍检测或 SEO 审计时才发现问题。这不是“可选配置”，而是解析引擎的启动开关。
-
<!DOCTYPE html>必须独占首行，不能有空格、注释或 BOM 前缀；任何其他写法（如<!DOCTYPE HTML PUBLIC ...>）都会触发怪异模式，导致 CSS 盒模型错乱、Flex/Grid 行为异常 -
<html lang="zh-CN">中的zh-CN不能简写成zh或zh-cn（大小写敏感），否则部分屏幕阅读器无法匹配中文语音库 - CI 流程中建议用
html-validate检查这两项，规则名是doctype-html5和lang-valid，报错即阻断构建
语义标签不是“换词游戏”，要按内容结构选，不是按视觉样式选
常见错误是看到设计稿里有个灰色区块就套 <section>，看到圆角卡片就用 <article>。语义标签的意义在于表达“这个内容是否能独立存在、是否被外部引用、是否属于页面主干”。
-
<article>只用于可单独分发的内容（如博客正文、新闻稿），不用于产品列表中的单个卡片；后者应使用<li>或普通<div>配合 ARIA role -
<aside>不等于“侧边栏”，而是指与当前内容相关但非核心的补充信息（如作者简介、延伸阅读），广告位通常不该用它 - 导航必须用
<nav>，但不是所有带链接的区域都是导航——页脚友情链接、文章内跳转锚点都不算，硬套会导致辅助技术误读
团队协作时 HTML 格式化必须自动化，靠人盯人没用
格式混乱最直接的后果不是难看，而是 Git diff 里全是缩进和引号变更，掩盖真实逻辑修改。人工统一标准只在小团队短期有效，超过 3 人就必须工具链兜底。
- 在项目根目录配
.prettierrc，关键项至少包含："tabWidth": 2、"useTabs": false、"singleQuote": false（强制双引号）、"htmlWhitespaceSensitivity": "css" - VS Code 的
.vscode/settings.json必须启用"editor.formatOnSave": true，且指定"editor.defaultFormatter": "esbenp.prettier-vscode" - 用
husky+lint-staged在 commit 前跑npx prettier --write，避免有人绕过编辑器设置直接命令行提交
注释和 data-* 属性是协作关键，但容易写成“自说自话”
注释不是越多越好，data- 属性也不是随便加。它们的真实价值在于让下游开发者（尤其是后端或测试同学）能快速理解前端结构意图，而不是让写的人自我感动。
立即学习“前端免费学习笔记（深入）”；
- 头部注释模板必须含
文件名、模块用途、数据来源说明（例如“此页数据由 /api/v2/home 接口返回，字段映射见 Jira TASK-123”） -
data-属性命名要带业务前缀，比如data-product-id而不是data-id，避免与框架内部属性冲突；值必须是字符串，数字要String(id)转换 - 禁止在注释里写“TODO：后面优化”，必须带截止时间或负责人，例如
<!-- TODO(张三, 2026-07-15): 重构轮播图加载逻辑，当前阻塞 LCP -->
实际落地最难的不是写规范，而是让所有人接受“HTML 不只是画布，它是接口契约”。一个 <button> 标签背后连着无障碍交互、SEO 权重、自动化测试断言——这些都不是前端一个人的事。
