企业官网建设流程全解析

dlitem 无障碍规则实战：让<dt>/<dd>各归其位，正确包裹在<dl>定义列表中

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist

本篇技术指南以 Front-End-Checklist 仓库中的 dlitem 技能定义 及其详细规则参考 references/rule.md 为核心主体，系统讲解 HTML 定义列表（Description List）的无障碍规范：为什么<dt>（描述术语）与<dd>（描述详情）必须作为<dl>的子元素存在，以及如何在代码审查、自动化检测与人工验证中落实这一规则。读完本文，你将掌握该规则的正确/错误写法、底层语义原理、仓库内的真实实现样例，以及一套可直接落地的检查与修复流程，适用于网页无障碍审查、设计系统组件评审与 AI 辅助代码审查场景。

一、规则速览：这条规则到底在检查什么

dlitem（definition-list-item）是 Front-End-Checklist 无障碍（accessibility）类别下的一条中等优先级规则，其核心约束只有一句话：

描述术语（<dt>）和描述详情（<dd>）必须包含在<dl>元素内。

在 SKILL.md 的 frontmatter 中，仓库为这条规则标注了完整的元数据：

技能描述（description）还给出了触发场景：审查渲染后的 HTML、交互组件或设计系统模式时，凡涉及定义列表项的包裹方式，都要先检查原生语义，再检查键盘行为、焦点流、可访问名称以及屏幕阅读器输出。这为 AI Agent 和人工审查者划定了检查顺序：语义优先，行为次之。

Quick Reference给出了三条最精简的检查要点：

• 所有<dt>（术语）与<dd>（描述）都必须放在<dl>内；
• 避免将定义列表项作为独立元素使用；
• 确保相关的元数据或术语表条目被正确分组。

二、为什么这条规则重要：丢失语义等于切断"术语—定义"关联

根据 references/rule.md 与内容规则的 dlitem.mdx，游离在<dl>之外的<dt>/<dd>会带来三个层面的问题：

1. 关系映射丢失（Relationship Mapping）：浏览器依赖<dl>这个容器来建立"某个术语对应哪些描述"的关联关系。一旦<dt>或<dd>脱离<dl>，这种关联在文档结构层面就断裂了。
2. 无障碍树失效（Accessibility Tree）：辅助技术（如屏幕阅读器）只有在正确包裹时才会把该区域暴露为"列表"，用户才能按列表项进行跳转导航。孤立的<dt>/<dd>会退化为无结构文本，屏幕阅读器无法将术语与定义联系起来。
3. HTML 校验失败（Validation）：错误的嵌套会导致 HTML 校验器报错，进而可能引发不可预测的渲染行为。

这也是为什么 SKILL.md 开篇就点明：孤立的<dt>或<dd>元素会失去语义含义，无法为辅助技术提供"连接术语与定义"所需的上下文。

三、正误对照：三种典型代码形态

references/rule.md 给出了可直接对照的标准示例：

<!-- ✅ 正确：完整包裹 --> <dl> <dt>Term</dt> <dd>The definition of the term.</dd> </dl> <!-- ❌ 错误：孤儿元素 --> <dt>Orphaned Term</dt> <dd>This is not inside a list.</dd> <!-- ❌ 错误：使用了不正确的容器 --> <ul> <li> <dt>Invalid usage</dt> <!-- dt 不能作为 li 或 ul 的子元素 --> </li> </ul>

第一种写法是标准形态：<dl>作为父容器，<dt>在前、<dd>在后，浏览器和辅助技术据此建立"术语 → 定义"的映射。

第二种写法是本规则要抓的典型问题：<dt>与<dd>脱离<dl>直接裸露在文档中。它们虽然仍能被渲染，但语义关联已经丢失。

第三种写法是常见的错误嵌套：把<dt>塞进<ul>/<li>。<dt>在 HTML 内容模型中只允许作为<dl>的子元素，放进无序列表属于无效嵌套，同样会被本规则与 HTML 校验器标记。

四、最佳实践：什么时候能用、什么时候不能用

references/rule.md 与内容规则 dlitem.mdx 共同总结出三条最佳实践：

• 始终使用<dl>：永远不要为了样式目的单独使用<dt>或<dd>。如果只是想要"标签—值"的视觉排版，也应保留dl/dt/dd语义或改用其他语义结构。
• 保持逻辑顺序：通常<dt>出现在其关联的<dd>之前，一个术语（<dt>）后紧跟其定义（<dd>）。
• 允许多个<dd>：一个<dt>后跟多个<dd>是完全合法的，用于表达单个术语的多个定义或详情。

需要特别说明的是，这条规则与同属accessibility/document-structure子类的 definition-list 规则（"Use correct definition list structure"）互为补充、经常一起审查：dlitem关注项必须包裹在<dl>内，definition-list则关注<dl>内只能包含合法子元素（仅允许dt、dd、以及 HTML5 中用于排版的<div>包裹层）。两者一个向内看、一个向外看，共同保证定义列表结构完整。

五、仓库内的真实实现佐证

本仓库不仅是规则的承载者，代码库自身也遵循这一规范。在 profile-github-metadata-section.tsx/(account)/profile/profile-github-metadata-section.tsx) 中，GitHub 资料元数据区块就使用了一个标准的定义列表：<dl>作为网格容器，每一条"标签—值"对用<div>包裹（这正是 HTML5 允许的、仅为 Grid/Flexbox 布局服务的包裹层），内部是成对的<dt>（标签）与<dd>（值）：

<dl className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3"> {items.map(item => ( <div key={item.label} className="rounded-md border border-border bg-card px-3 py-2"> <dt className="text-foreground-muted text-xs">{item.label}</dt> <dd className="mt-1 break-words font-medium text-foreground text-sm"> {/* 值为链接时渲染 <a>，否则渲染纯文本 */} </dd> </div> ))} </dl>

这个真实组件恰好演示了本规则的两个关键点：

1. 所有<dt>/<dd>都严格作为<dl>的子元素（中间只隔了合法的<div>包裹层），没有孤儿项；
2. <div>仅用于 CSS 网格布局，不破坏dt/dd的语义层级——这正是definition-list规则与dlitem规则共同认可的模式。

同时，规则在仓库中有三个层级的"内容制品"相互印证：

• 技能定义：skills/dlitem/SKILL.md —— 面向 AI Agent 的触发式技能，包含 frontmatter 元数据、快速参考与 Check / Fix / Explain / Code Review 四类提示词；
• 详细规则参考：skills/dlitem/references/rule.md —— 面向人类与 Agent 的完整实现细节，含代码示例、最佳实践、工具与验证清单；
• 内容规则源：packages/content/rules/en/accessibility/dlitem.mdx —— 站点内容系统使用的结构化规则，通过 frontmatter 的prompts字段（check/fix/explain/codeReview）为 LLM 生成审查指令，并通过relatedRules字段挂接了definition-list、listitem、list-structure、semantic-lists四条关联规则。

六、如何在代码审查中执行这条规则

SKILL.md 为审查者定义了四个可执行的步骤：

1. Check（检查）：定位所有不属于<dl>子元素的<dt>或<dd>元素。
2. Fix（修复）：将孤立的<dt>与<dd>包裹进父级<dl>容器中。
3. Explain（解释）：说明为什么<dt>/<dd>必须包含在<dl>内才能建立正确的语义关联——即本文第二节所述的"关系映射、无障碍树、校验"三重原因。
4. Code Review（代码审查）：审查渲染后的标记与交互状态，精确定位违反规则的元素、角色、标签、焦点行为或键盘交互，并说明如何借助浏览器无障碍工具或辅助技术验证修复效果。

在 AI 辅助场景下，dlitem.mdx 的aiContext字段给出了同样的审查顺序建议：先检查原生语义，再检查键盘行为、焦点流、可访问名称与屏幕阅读器输出——语义层面的问题（如孤儿<dt>）优先级高于交互细节。

七、验证方法：自动化与人工双通道

references/rule.md 的 Verification 一节提供了完整的验证矩阵：

自动化检查

• 检查浏览器无障碍树或无障碍面板（Accessibility Pane）中相关元素的角色与可访问名称——若<dt>/<dd>未包裹进<dl>，无障碍树中不会呈现"列表"结构；
• 运行自动化无障碍检查器，如 axe 或 Lighthouse。其中 axe-core 有对应的definition-list-item（dlitem）规则可直接命中本问题。

人工检查

• 使用纯键盘导航测试受影响的 UI，确认规则在真实渲染体验中成立（键盘导航不受影响，但可作为整体回归手段）；
• 如果该规则影响关键交互，用屏幕阅读器重新走一遍具有代表性的用户流程，确认"术语—定义"的关联播报正确。

八、相关规则地图：同属文档结构无障碍

dlitem并非孤立规则，在 dlitem.mdx 的relatedRules中，它与以下规则同属accessibility/document-structure区域，建议在审查时一并处理：

可以看出，dlitem是"HTML 列表元素必须待在正确的父容器里"这一大主题下针对定义列表的具体分支——它与listitem（针对<li>）一脉相承，共同守护文档结构的语义完整性。

九、结语

dlitem规则看似简单（把<dt>/<dd>放进<dl>），背后却是 HTML 语义模型、无障碍树构建与辅助技术导航三者共同作用的结果。Front-End-Checklist 将其沉淀为带完整元数据的技能（SKILL.md）与结构化内容规则（dlitem.mdx），既能指导人工代码审查，也能作为 AI Agent 的可触发审查技能。实践中的关键是记住三条主线：项必须入列表、div只能为样式、审查先看语义再看交互。配合 axe 等自动化工具与屏幕阅读器的人工抽验，即可确保定义列表在任何渲染环境中都保持正确的语义关联。

【免费下载链接】Front-End-Checklist🗂 The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist