dt 必须为纯文本或内联元素，不得嵌套块级标签；dd 必须紧随 dt 后且为 dl 直接子元素；布局推荐 css grid 并清零 dd margin；嵌套 dl 仅允许在 dd 内且不超过两层。
dt 里塞
或
会导致屏幕阅读器完全跳过术语
headers
很多开发者想让术语文字换行或加样式，就给 dt 套个 <p></p>，结果 NVDA、VoiceOver 都不再朗读里面的内容，只报“段落”。HTML5 虽然允许 dt 包含块级元素，但主流辅助技术根本不识别嵌套结构。
必须用纯文本或内联元素：<code>、<em></em>、<strong></strong>、<a></a> 可以，<p></p>、<div>、<code><span></span>（除非设 display: inline）不行。
- 需要换行？用 CSS 的
white-space: pre-line或display: inline-block - 要强调某词？用
<strong></strong>，别用<div> 包一层再设字体<li>术语带状态（如“已弃用”）？用 <code><span aria-label="已弃用">src</span>，不靠视觉色块暗示
dd 必须紧跟 dt，中间不能插任何标签或空白节点
常见错误是把 dt 和它对应的 dd 拆到不同 <div> 里，或者中间加个 <code><p></p> 分隔。一旦破坏 DOM 顺序，读屏器就无法建立术语-定义关联——它只按文档流顺序配对，不会“找最近的 dd”。
合法结构：
- timeout
- 请求超时毫秒数，默认 5000
- retry
- 失败重试次数，默认 2
非法结构（哪怕只多一个空格或换行符）：
- timeout
- ...
-
dt和dd必须是<dl></dl>的直接子元素 - 动态渲染时（比如从 JSON 生成），程序必须确保每个
dd前都有且仅有一个未被其他标签隔开的dt - 避免在
dt后加注释、空格、换行符——某些解析器会把它当文本节点处理，同样干扰配对
用 CSS Grid 布局时，dd 的 margin 必须手动清零
浏览器默认给 dd 设 margin-left: 40px 实现缩进，但在 Grid 中这个值会和 gap 叠加，导致术语列和描述列错位。更糟的是，不清零时 grid-column: 2 可能失效，dd 仍卡在第一列换行显示。
关键样式：
dl {
display: grid;
grid-template-columns: max-content 1fr;
}
dt {
grid-column: 1;
margin-bottom: 0.5em;
}
dd {
margin: 0;
grid-column: 2;
}
- 不要依赖默认缩进，语义布局和视觉呈现必须解耦
- 窄屏回退用
@media (max-width: 480px) { dt, dd { grid-column: 1; } }，比改grid-template-columns更稳 - 若需图标前缀，用
dd::before，别靠margin-left模拟
嵌套 dl 只允许出现在 dd 内，且建议不超过两层
元数据常有层级，比如 headers 参数下还有 Content-Type 和 Authorization。这时可在 dd 里嵌套新 dl，但绝不能写在 dt 里或 dl 外部。
正确写法：
- Content-Type
- application/json
- Authorization
- Bearer xxx
- 嵌套超过两层会让键盘导航路径变长，屏幕阅读器逐层进入退出成本高
- 视觉上容易混淆归属——第二层
dt看起来像顶级术语，需靠 CSS 显式降级样式（如缩小字号、浅色） - 自动化工具（如 JSDoc、Swagger UI）通常不支持深层嵌套输出，可能丢弃或扁平化内容
真正难的不是写对标签，而是让每个 dt 和 dd 在 DOM 树里严丝合缝地挨着，中间不插任何东西——连一个看不见的文本节点都可能让读屏器逻辑错乱。
