Front-End Checklist 定义列表语义指南用正确的 dl/dt/dd 结构构建无障碍术语-描述关系【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist定义列表dl用于成组呈现术语dt— 描述dd关系是文档结构无障碍accessibility审查中最容易踩坑、也最容易被忽视的一类元素。本文以本仓库中definition-list规则SKILL.md 与 references/rule.md为主体结合 dlitem、semantic-lists、list-structure 等配套规则及 frontendchecklist/rules 的加载器实现讲清定义列表的正确结构、错误形态、修复方法与验证手段让你在代码评审、渲染输出检查和 AI 辅助审查中都能准确识别并修复此类问题。规则速览这条规则到底在说什么本规则的核心主张只有一句话定义列表dl中只能包含合法的dt与dd元素。在 definition-list.mdx 中该规则被归类为accessibility类别、document-structure子类别优先级为medium难度为intermediate预计耗时 5 分钟。规则摘要Quick Reference包含三条核心约束确保dl只包含dt、dd或script/template标签避免把列表项包在不合法的容器元素如div中——注意HTML5 下div作为样式分组容器是合法的需要区分样式分组与错误嵌套两种场景维护术语与描述之间的语义关联。当结构被破坏时辅助技术assistive technology会被误导用户无法理解术语与其定义之间的对应关系——这正是whyItMatters字段所强调的Broken list structures confuse assistive technologies, preventing users from understanding the relationship between terms and their definitions.定义列表的三要素dl、dt、dd 各自的职责定义列表由三类元素协作完成语义表达元素全称职责dlDescription List定义列表容器成组承载术语与描述dtDescription Term被定义的术语ddDescription Details术语对应的描述/定义浏览器依靠dl容器把特定的术语与对应的描述关联起来。只有当这三者按正确层级嵌套时辅助技术才会把这段内容暴露为list角色让用户能够按列表项导航否则元素退化为无意义的文本流语义关联彻底丢失。值得注意的是HTML5 对dl的合法直接子元素做了放宽除了dt、dd还允许div仅用于样式分组div 内部仍只能放dt/dd、script与template。SKILL.md 的 Quick Reference 中避免div容器的表述准确含义是避免使用不合法容器——h3、p等出现在dl内才是真正的问题。代码示例Good vs Bad以下是 references/rule.md 中的完整对照示例可直接用于代码评审清单。!-- ✅ 正确结构 -- dl dtHTML/dt ddHyperText Markup Language/dd dtCSS/dt ddCascading Style Sheets/dd /dl !-- ✅ 正确结构使用 div 做样式分组HTML5 下合法 -- dl div classrow dtAuthor/dt ddJane Doe/dd /div /dl !-- ❌ 错误结构直接子元素不是 dt、dd 或 div -- dl h3Book Metadata/h3 !-- 标题应放在 dl 之外 -- pSome introductory text/p !-- 段落应放在 dl 之外 -- dtYear/dt dd2023/dd /dl错误示例的关键点h3和p是dl的非法直接子元素。修复方式是移出而非隐藏——把标题和引言段落挪到dl外部让列表只保留纯粹的术语-描述对维持语义完整性。为什么它如此重要Why It Matters规则文档列出了三条核心理由语义准确性Semantic Accuracy正确的嵌套让浏览器理解文档结构DOM 中表达的关系与视觉呈现一致屏幕阅读器导航Screen Reader Navigation部分屏幕阅读器提供在列表项之间跳转的快捷键非法标记会直接打断这类导航能力分组Grouping一个术语对应多个定义时正确的结构能保证多个dd与同一个dt正确归组。对照配套规则 dlitem.mdx 可以看得更透dt和dd只有在作为dl的子元素时才具有语义价值孤儿化的dt/dd不在任何dl内会失去语义含义辅助技术无法再把术语与定义联系起来而 list-structure.mdx 则从列表通性角度补充屏幕阅读器进入列表时会播报List of 3 items结构损坏会导致列表被错误计数甚至被完全忽略同时破坏父子关系的标记无法通过 HTML 校验可能引发不可预测的渲染问题。最佳实践Best Practices规则文档给出三条可直接落地的实践原则✅保持简单Keep it simple列表里只放术语和定义其他内容一律移出dl。✅只为样式使用 divUse DIVs for styling only当需要 Grid/Flexbox 布局容器时用div包裹dt/dd对是合法的HTML5但 div 内部仍然只能包含dt/dd不能携带其他内容。✅检查孤儿项Check for Orphaned Items确保每个dt至少有一个关联的dd。结合 dlitem.mdx 的最佳实践还能补足三点细节永远用dl不要为了样式目的单独使用dt或dd逻辑顺序dt通常出现在其关联dd之前一术语多描述一个dt后面跟随多个dd是完全合法的例如dl dt术语/dt dd定义一/dd dd定义二/dd /dl典型应用场景术语表、FAQ 与元数据semantic-lists.mdx 明确给出了定义列表的典型用武之地——术语表glossary与 FAQ!-- 术语表 -- dl classglossary dtAPI/dt ddApplication Programming Interface/dd dtREST/dt ddRepresentational State Transfer/dd dtJSON/dt ddJavaScript Object Notation/dd /dl !-- FAQ 用定义列表表达“问题-答案”对 -- dl classfaq dtHow do I reset my password?/dt ddClick the Forgot Password link on the login page./dd dtWhat payment methods do you accept?/dt ddWe accept Visa, Mastercard, and PayPal./dd /dlFAQ 的问题—答案结构天然契合术语—描述模型用dl表达能让屏幕阅读器把问答成组播报元数据型内容如文章的作者、日期、标签也适合dl承载。与之对照的是无意义的纯样式div列表如div classfeature.../div模拟列表不会播报任何列表上下文这正是 semantic-lists.mdx 要解决的另一个侧面屏幕阅读器会为正确的语义列表播报list with X items而样式化 div 提供不了任何上下文。检查、修复与解释Check / Fix / ExplainSKILL.md 为 AI 与人工审查都设计了标准化的三段式指令分别对应审查的不同环节Check检查验证所有dl元素只包含合法子元素dt、dd或允许的包装容器。同时结合 dlitem.mdx 的检查视角定位所有不属于dl子元素的dt/dd找出孤儿元素。Fix修复从dl内移除任何非法元素或将它们包装到合适位置以维持语义完整性。对孤儿dt/dd则是把它们包进一个父级dl容器中。Explain解释向团队或 AI 说明正确的定义列表结构如何帮助屏幕阅读器导航并归组相关信息。Code Review代码评审SKILL.md 的codeReview提示词要求审查渲染后的标记与交互状态精确指出违反规则的元素、角色、标签、焦点行为或键盘交互并说明如何用浏览器无障碍工具或辅助技术验证修复效果。这套字段在内容层被结构化为prompts.check、prompts.fix、prompts.explain、prompts.codeReview见 definition-list.mdx 的 frontmatter在运行时则由 load-rules.ts 解析——该加载器用轻量正则从 MDX frontmatter 中提取title、priority、subcategory、categories与prompts字段产出统一的规则记录含slug、content、primaryCategory、url可被上层消费。工具与验证Tools Validation规则文档推荐两类验证路径自动化检查Automated Checks检查浏览器无障碍树accessibility tree或无障碍面板中相关元素、角色或可访问名称是否正确运行自动化无障碍检查器如 axe、Lighthouse扫描页面——axe 中与本规则对应的检查点是definition-listdl 结构与dlitemdt/dd 孤儿项见 dlitem.mdx 的资源引用用 W3C 标记校验服务验证 HTML 合法性。手动检查Manual Checks用纯键盘操作测试受影响的 UI确认规则在渲染结果中成立如果该规则影响关键交互用屏幕阅读器重测一个有代表性的用户流程对列表场景可进一步验证list with X items播报以及条目数与可见项一致semantic-lists.mdx 的 Verification 部分。规则文档的 Standards 部分强调两点方法论实现要与 W3C WAI/WCAG 对齐并验证渲染后的真实体验而非只盯源码。异常与优先级Exceptions规则文档给出的 Exceptions 部分为处理多条无障碍问题叠加的场景提供了决策依据简单数据表有时因缺失表头关联header relationships而失败的程度比缺失标题或移动端包装等增强项更严重应优先处理最核心的语义问题不要为了满足规则而把布局结构改造成 contenteditable="false">【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/19 3:42:11 · 阅读 1.2k Front-End Checklist 定义列表语义指南：用正确的 dl/dt/dd 结构构建无障碍术语-描述关系
Front-End Checklist 定义列表语义指南用正确的 dl/dt/dd 结构构建无障碍术语-描述关系【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist定义列表dl用于成组呈现术语dt— 描述dd关系是文档结构无障碍accessibility审查中最容易踩坑、也最容易被忽视的一类元素。本文以本仓库中definition-list规则SKILL.md 与 references/rule.md为主体结合 dlitem、semantic-lists、list-structure 等配套规则及 frontendchecklist/rules 的加载器实现讲清定义列表的正确结构、错误形态、修复方法与验证手段让你在代码评审、渲染输出检查和 AI 辅助审查中都能准确识别并修复此类问题。规则速览这条规则到底在说什么本规则的核心主张只有一句话定义列表dl中只能包含合法的dt与dd元素。在 definition-list.mdx 中该规则被归类为accessibility类别、document-structure子类别优先级为medium难度为intermediate预计耗时 5 分钟。规则摘要Quick Reference包含三条核心约束确保dl只包含dt、dd或script/template标签避免把列表项包在不合法的容器元素如div中——注意HTML5 下div作为样式分组容器是合法的需要区分样式分组与错误嵌套两种场景维护术语与描述之间的语义关联。当结构被破坏时辅助技术assistive technology会被误导用户无法理解术语与其定义之间的对应关系——这正是whyItMatters字段所强调的Broken list structures confuse assistive technologies, preventing users from understanding the relationship between terms and their definitions.定义列表的三要素dl、dt、dd 各自的职责定义列表由三类元素协作完成语义表达元素全称职责dlDescription List定义列表容器成组承载术语与描述dtDescription Term被定义的术语ddDescription Details术语对应的描述/定义浏览器依靠dl容器把特定的术语与对应的描述关联起来。只有当这三者按正确层级嵌套时辅助技术才会把这段内容暴露为list角色让用户能够按列表项导航否则元素退化为无意义的文本流语义关联彻底丢失。值得注意的是HTML5 对dl的合法直接子元素做了放宽除了dt、dd还允许div仅用于样式分组div 内部仍只能放dt/dd、script与template。SKILL.md 的 Quick Reference 中避免div容器的表述准确含义是避免使用不合法容器——h3、p等出现在dl内才是真正的问题。代码示例Good vs Bad以下是 references/rule.md 中的完整对照示例可直接用于代码评审清单。!-- ✅ 正确结构 -- dl dtHTML/dt ddHyperText Markup Language/dd dtCSS/dt ddCascading Style Sheets/dd /dl !-- ✅ 正确结构使用 div 做样式分组HTML5 下合法 -- dl div classrow dtAuthor/dt ddJane Doe/dd /div /dl !-- ❌ 错误结构直接子元素不是 dt、dd 或 div -- dl h3Book Metadata/h3 !-- 标题应放在 dl 之外 -- pSome introductory text/p !-- 段落应放在 dl 之外 -- dtYear/dt dd2023/dd /dl错误示例的关键点h3和p是dl的非法直接子元素。修复方式是移出而非隐藏——把标题和引言段落挪到dl外部让列表只保留纯粹的术语-描述对维持语义完整性。为什么它如此重要Why It Matters规则文档列出了三条核心理由语义准确性Semantic Accuracy正确的嵌套让浏览器理解文档结构DOM 中表达的关系与视觉呈现一致屏幕阅读器导航Screen Reader Navigation部分屏幕阅读器提供在列表项之间跳转的快捷键非法标记会直接打断这类导航能力分组Grouping一个术语对应多个定义时正确的结构能保证多个dd与同一个dt正确归组。对照配套规则 dlitem.mdx 可以看得更透dt和dd只有在作为dl的子元素时才具有语义价值孤儿化的dt/dd不在任何dl内会失去语义含义辅助技术无法再把术语与定义联系起来而 list-structure.mdx 则从列表通性角度补充屏幕阅读器进入列表时会播报List of 3 items结构损坏会导致列表被错误计数甚至被完全忽略同时破坏父子关系的标记无法通过 HTML 校验可能引发不可预测的渲染问题。最佳实践Best Practices规则文档给出三条可直接落地的实践原则✅保持简单Keep it simple列表里只放术语和定义其他内容一律移出dl。✅只为样式使用 divUse DIVs for styling only当需要 Grid/Flexbox 布局容器时用div包裹dt/dd对是合法的HTML5但 div 内部仍然只能包含dt/dd不能携带其他内容。✅检查孤儿项Check for Orphaned Items确保每个dt至少有一个关联的dd。结合 dlitem.mdx 的最佳实践还能补足三点细节永远用dl不要为了样式目的单独使用dt或dd逻辑顺序dt通常出现在其关联dd之前一术语多描述一个dt后面跟随多个dd是完全合法的例如dl dt术语/dt dd定义一/dd dd定义二/dd /dl典型应用场景术语表、FAQ 与元数据semantic-lists.mdx 明确给出了定义列表的典型用武之地——术语表glossary与 FAQ!-- 术语表 -- dl classglossary dtAPI/dt ddApplication Programming Interface/dd dtREST/dt ddRepresentational State Transfer/dd dtJSON/dt ddJavaScript Object Notation/dd /dl !-- FAQ 用定义列表表达“问题-答案”对 -- dl classfaq dtHow do I reset my password?/dt ddClick the Forgot Password link on the login page./dd dtWhat payment methods do you accept?/dt ddWe accept Visa, Mastercard, and PayPal./dd /dlFAQ 的问题—答案结构天然契合术语—描述模型用dl表达能让屏幕阅读器把问答成组播报元数据型内容如文章的作者、日期、标签也适合dl承载。与之对照的是无意义的纯样式div列表如div classfeature.../div模拟列表不会播报任何列表上下文这正是 semantic-lists.mdx 要解决的另一个侧面屏幕阅读器会为正确的语义列表播报list with X items而样式化 div 提供不了任何上下文。检查、修复与解释Check / Fix / ExplainSKILL.md 为 AI 与人工审查都设计了标准化的三段式指令分别对应审查的不同环节Check检查验证所有dl元素只包含合法子元素dt、dd或允许的包装容器。同时结合 dlitem.mdx 的检查视角定位所有不属于dl子元素的dt/dd找出孤儿元素。Fix修复从dl内移除任何非法元素或将它们包装到合适位置以维持语义完整性。对孤儿dt/dd则是把它们包进一个父级dl容器中。Explain解释向团队或 AI 说明正确的定义列表结构如何帮助屏幕阅读器导航并归组相关信息。Code Review代码评审SKILL.md 的codeReview提示词要求审查渲染后的标记与交互状态精确指出违反规则的元素、角色、标签、焦点行为或键盘交互并说明如何用浏览器无障碍工具或辅助技术验证修复效果。这套字段在内容层被结构化为prompts.check、prompts.fix、prompts.explain、prompts.codeReview见 definition-list.mdx 的 frontmatter在运行时则由 load-rules.ts 解析——该加载器用轻量正则从 MDX frontmatter 中提取title、priority、subcategory、categories与prompts字段产出统一的规则记录含slug、content、primaryCategory、url可被上层消费。工具与验证Tools Validation规则文档推荐两类验证路径自动化检查Automated Checks检查浏览器无障碍树accessibility tree或无障碍面板中相关元素、角色或可访问名称是否正确运行自动化无障碍检查器如 axe、Lighthouse扫描页面——axe 中与本规则对应的检查点是definition-listdl 结构与dlitemdt/dd 孤儿项见 dlitem.mdx 的资源引用用 W3C 标记校验服务验证 HTML 合法性。手动检查Manual Checks用纯键盘操作测试受影响的 UI确认规则在渲染结果中成立如果该规则影响关键交互用屏幕阅读器重测一个有代表性的用户流程对列表场景可进一步验证list with X items播报以及条目数与可见项一致semantic-lists.mdx 的 Verification 部分。规则文档的 Standards 部分强调两点方法论实现要与 W3C WAI/WCAG 对齐并验证渲染后的真实体验而非只盯源码。异常与优先级Exceptions规则文档给出的 Exceptions 部分为处理多条无障碍问题叠加的场景提供了决策依据简单数据表有时因缺失表头关联header relationships而失败的程度比缺失标题或移动端包装等增强项更严重应优先处理最核心的语义问题不要为了满足规则而把布局结构改造成 contenteditable="false">【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考