html

HTML

编写语义清晰、无障碍、易于维护且易于浏览的 HTML。优先采用简单的结构、有意义的元素，并尽量减少多余的包装元素。

核心原则

针对内容或交互，选择最合适的 HTML 元素。不要机械地套用最佳实践。

适用场景

在以下情况下使用此技能：

• 编写原始 HTML 或模板标记
• 重构冗杂或包装元素过多的标记
• 改进语义、页面地标或标题结构
• 修复表单标签和控件选择问题
• 在 div、section、article、ul 和其他结构元素之间做选择
• 用更合适的原生 HTML 替代自定义交互
• 清理 Svelte 组件标记，同时不改变其行为

以下情况不要使用此技能：

• 纯 CSS 架构决策
• 除非 HTML 选择是根本问题，否则不要用于 JavaScript 行为设计
• 营销文案或内容策略
• 与标记结构无关的深层框架状态或响应性变更

决策顺序

编写或审查标记时：

1. 选择最符合内容或交互的元素
2. 优先采用原生 HTML 行为，而非自定义行为
3. 移除没有结构价值的包装元素
4. 确保标签、标题、地标和图像处理正确
5. 只有原生 HTML 无法表达所需行为时才添加 ARIA

模板安全

当标记位于 Svelte 或其他类似 HTML 的模板语言中时：

• 将文件视为模板标记，而非独立的纯 HTML 文档
• 保留框架语法，例如 {#if}、{#each}、{:else}、{@html}、bind:、class、style:、事件属性，以及 <svelte:head> 等特殊元素
• 除非任务明确要求，否则不要将组件或首字母大写的标签替换为原生元素
• 改进指令和代码块周围的 HTML，但不要破坏绑定、键、控制流或组件边界
• 仅当文件实际是文档外壳时，才应用 <!doctype html>、html、head 和 body 等完整文档规则
• 在 Svelte 中，将编译器的无障碍警告视为有用的约束，不要随意添加 svelte-ignore 注释

规则

1. 优先使用语义化元素

• 内容匹配时，使用语义化标签：
  • header
  • main
  • section
  • article
  • nav
  • aside
  • footer
  • button
  • form
  • label
• 明明有更合适的语义化元素时，不要使用 div
• 普通容器更准确时，不要强行使用语义化元素

2. 按含义组织内容

• HTML 应描述内容结构，而非视觉外观
• 根据内容本身选择元素
• 不要根据浏览器默认样式选择元素
• 不要为了满足规则而凭空添加额外结构

3. 保持嵌套浅显

• 避免不必要的包装元素
• 优先采用更扁平、更易读的标记
• 每增加一层，都应有实际的结构、行为或样式用途

4. 标题层级必须合理

• 为页面或主视图使用一个清晰的 h1
• 按逻辑顺序排列标题：
  • h1
  • h2
  • h3
• 没有理由时不要跳过标题级别
• 不要仅为了显示大号文本而使用标题

5. 必须保证无障碍性

• 始终为表单控件使用恰当的标签
• 操作用 button，导航用 a
• 为传达信息的图像添加有意义的 alt 文本
• 只有原生 HTML 无法解决问题时才使用 ARIA
• 不要添加不必要的 ARIA

6. 优先采用原生 HTML 行为

• 优先使用 HTML 内置功能，而非自定义方案
• 优先使用：
  • button
  • details
  • summary
  • dialog
  • input
  • select
  • fieldset
  • table
• 避免用通用元素重新实现原生控件

7. 编写易读的标记

• 保持格式一致
• 使用清晰的缩进
• 保持属性易读
• 标记变得难以浏览时换行
• 优先考虑阅读源代码的人

8. 让类名有明确用途

• 仅在样式或脚本需要时添加类
• 不要默认给每个元素都添加类
• 优先使用简单且有意义的类名
• 尽可能避免仅根据呈现方式命名

9. 避免堆砌 div

• 不要创建由多个匿名 div 组成的长链
• 如果出现很多包装元素，请重新考虑结构
• 添加更多容器之前先尝试简化
• 如果没有更合适的语义元素，使用普通 div 即可

10. 明确标记表单

• 每个输入项都需要关联的标签
• 正确使用 type 值
• 为要提交的字段使用 name
• 对分组输入使用 fieldset 和 legend
• 使用 HTML 属性标记必填字段，而不只是用文本说明
• 不要将占位文本当作标签

11. 仅在内容确实属于列表时使用列表

• 当内容确实属于列表时，使用 ul / ol / li：
  • 步骤
  • 菜单项
  • 项目符号
  • 以列表成员身份为重要含义的分组项目
• 不要仅仅因为内容重复就使用列表标记
• 内容重复本身并不意味着它具有列表语义

在以下情况下使用 article：

• 每个重复项目都可以独立成立
• 每个项目都有自己的标题、元数据或操作
• 重复内容更像卡片、帖子、结果、故事或条目

在以下情况下使用 section：

• 内容按主题或用途分组
• 为该分组设置独立标题会有所帮助
• 重点是主题分组，而非列表成员身份

在以下情况下使用普通容器：

• 标记主要用于布局
• 不存在更明确的语义
• 列表或地标语义会显得牵强

避免：

• 默认使用 ul / li 包裹卡片网格
• 将 li 用于任何重复的组件模式
• 强行为仅用于布局的结构赋予语义

12. 分离内容与行为

• HTML 定义结构
• CSS 定义呈现
• JavaScript 定义行为
• 避免使用内联样式和类似 onclick="..." 的纯 HTML 事件处理程序字符串
• 在模板语言中，不要把框架事件属性误认为普通内联 JS

13. 链接和按钮不能互换

• 使用 a 跳转到其他位置
• 使用 button 执行操作
• 绝不要用可点击的 div 或 span 代替按钮
• 除非确有应用风格的理由，否则不要用按钮进行纯导航

14. 有意识地处理图像

• 装饰性图像使用 alt=""
• 信息性图像使用描述性的 alt
• 尽可能提供宽度和高度，以减少布局偏移
• 当说明文字属于内容时，使用 figure 和 figcaption

15. 元数据很重要

• 对于完整的 HTML 文档，请包含：
  • <!doctype html>
  • html 上的 lang
  • meta charset="utf-8"
  • meta name="viewport" content="width=device-width, initial-scale=1"
  • 有意义的 title
• 对于组件文件或模板片段，仅通过框架提供的适当机制添加文档元数据，例如在 Svelte 中使用 <svelte:head>
• 仅在有明确用途时添加其他元数据

16. 避免语义过度拟合

• 不要机械地套用规则
• “语义化 HTML”并不意味着处处都要使用最专门的元素
• 最合适的元素，是最准确反映内容和交互的元素
• 与不正确的语义相比，包含少量普通容器的简单结构更好

17. 地标应有实际意义

• 在有助于明确页面结构时，使用 main、nav、header、footer 和 aside 等地标
• 不要用地标元素包裹每个小节
• 地标应帮助用户定位，而不是制造干扰

18. 优先采用精简且准确的标记

• 从最小且正确的结构开始
• 仅在元素能改善含义、无障碍性或可维护性时添加
• 不要为了以防万一而添加包装元素、标签或语义

反模式

• 使用 div 作为按钮或链接
• 原生 HTML 已经可用时仍添加 ARIA
• 输入框缺少标签
• 仅为设置样式而使用标题
• 嵌套层级过深的包装元素
• 使用表格进行布局
• 使用普通 HTML 内联事件处理程序字符串，例如 onclick="..."
• 把有效的 Svelte 指令或代码块改写成仿佛有问题的 HTML
• 在组件文件中添加 html、head 或 body 标签
• 使用 box1、red_text、left_side 之类毫无意义的类名
• 默认用 ul / li 包裹卡片布局
• 仅仅因为内容重复就使用语义化元素
• 添加没有导航价值的额外地标
• 用占位文本代替标签

启发式问题

• 每个元素是否都能说明自己存在的理由？
• 是否有语义化元素应该替换这个 div？
• 如果没有 CSS，这样的结构是否仍然合理？
• 屏幕阅读器能否理解其结构？
• 操作是否使用按钮，目标位置是否使用链接？
• 标题顺序是否合乎逻辑？
• 表单是否都标注清楚并正确分组？
• 是否真的有必要使用 ARIA？
• 这确实是一个列表，还是只是重复的内容？
• 每个重复项是否足够独立，可以作为 article？
• 我编辑的是完整文档，还是组件／模板片段？
• 这次清理是否会破坏 Svelte 指令、绑定、代码块、键或组件边界？
• 我选择某个元素是因为它准确，还是因为这是我死记硬背的规则？

输出指南

编写 HTML 时：

• 从语义结构入手
• 保持标记简洁
• 优先使用原生元素和原生行为
• 优化可读性和可维护性
• 删除不必要的包装元素
• 除非 ARIA、类或属性有明确作用，否则不要添加
• 语义不够明确时，不要强行使用 ul / li、section 或 article
• 在 Svelte 或其他模板文件中，保留指令、代码块语法、绑定和特殊元素
• 优先选择准确的结构，而不是机械地遵循最佳实践

示例偏好

好的做法

• 在有帮助时使用语义化地标
• 浅层嵌套
• 明确标注
• 合乎逻辑的标题
• 尽量少用包装元素
• 使用原生控件
• 将 article 用于独立的重复条目
• 仅在确实是列表时使用 ul / ol
• 语义要求很少时使用普通容器

不好的做法

• div 堆砌
• 可点击但不可交互的元素
• 含糊的结构
• 用辅助文本代替恰当的语义
• 无缘无故添加额外包装元素
• 原生 HTML 可用时仍使用自定义控件
• 为所有重复卡片都使用列表标记
• 过度设计简单布局的结构
• 语义过度拟合