目录（ToC）系统 是做什么的？
目的
目录（ToC）系统提供了一种为单页或文档设计页面内导航菜单的方法。它解决了长格式内容中的“滚动疲劳”问题，通过持续展示页面层次结构的可视地图，让用户了解其当前上下文，并能够在不迷失位置的情况下直接跳转到特定章节。
使用场景
- 文档和技术指南： 浏览标题和子标题的深层层次结构。
- 长篇文章和博客帖子： 为 2000 字以上的编辑内容提供路线图。
- 复杂的着陆页： 帮助用户在功能、定价和常见问题解答部分之间跳转。
- 法律和政策页面： 浏览密集的条款和编号部分。
- 资源中心： 在单个页面上组织大量的链接或工具列表。
何时不使用
- 短内容（少于 3 个部分）： 如果整个页面可以在两次滚动内浏览完毕，则添加目录会产生不必要的视觉噪音。
- 主导航： 不要使用目录在不同的页面之间移动，应使用
site-navigation-system。 - 线性向导： 对于用户必须遵循固定顺序的逐步流程，请使用
step-progress-system。 - 极简主义营销： 目标是实现单一、不间断的叙事流程，不提供转移注意力的内容。
输入
- 标题层级： 页面上的
<h2>到<h4>标签的映射。 - 布局上下文： 可用的水平空间（侧边栏 vs 内联）。
- 滚动容器： 滚动发生在 body 上还是特定的溢出容器上？
- 品牌令牌： 来自设计系统的间距、排版和“活动”状态颜色。
输出
- 目录结构规范： 列表项、缩进级别和“活动”指示器的视觉定义。
- 滚动监听蓝图： 当用户滚动时，“活动”状态如何更新的逻辑。
- 响应式适配图： 目录如何从桌面侧边栏转换为移动实用工具（例如，粘性页眉或底部抽屉）。
- 寻路规范： 平滑滚动行为和焦点管理的定义。
工作流程
1. 审核文档大纲
提取标题结构。清晰的目录依赖于逻辑上的 h1 -> h2 -> h3 递进。
- 主级别： 通常从
<h2>标签派生。 - 次级别： 从
<h3>标签派生（缩进）。 - 第三级别： 除非文档非常密集，否则很少在目录中显示；考虑默认折叠这些级别。
2. 选择布局模式
根据页面布局选择空间安排：
- 持久侧边栏（右侧/左侧）： 最适合宽屏（桌面）。始终保持地图可见。
- 内联摘要： 放置在文章顶部。最适合移动设备或中等长度的内容，无需“粘性”。
- 粘性页眉/浮动栏： 仅在滚动过首屏后出现的简化版本。
3. 建立视觉层次结构（级别）
应用 visual-hierarchy-system 来表示深度：
- 缩进： 使用一致的水平内边距（例如，每级别
--space-s）来显示父子关系。 - 排版： 对子级别（h3）使用比主级别（h2）更小的字号或更柔和的颜色。
- 指示器： 在列表的左侧/右侧使用垂直“进度线”来视觉连接项目。
4. 设计滚动监听（活动）状态
目录必须与用户的视口保持同步：
- 活动链接： 高亮显示与当前位于视口顶部的章节相对应的链接。
- “活动线”效果： 如果使用垂直线，请为标记设置动画，使其滑动到活动项目的位置。
- 反馈延迟： 确保活动状态快速（<100ms）更新，但包含一个小的缓冲，以防止在标题之间滚动时闪烁。
5. 规划响应式寻路
侧边栏通常在移动设备上消失；请提供替代方案：
- 移动目录触发器： 屏幕顶部或底部的粘性按钮（例如，“在此部分中”），用于打开抽屉。
- 渐进式显示： 在粘性栏中仅显示当前的
<h2>，并带有展开完整列表的箭头。
决策规则
- “三级”限制： 永远不要在目录中显示超过 3 个深度级别。如果内容更深，则简化目录以仅关注
h2和h3。 - 缩进优先于图标： 使用缩进来显示层次结构，而不是项目符号或图标，这会使密集的文本列表变得杂乱。
- 活动状态的唯一性： 目录中一次只能有一个项目处于“活动”状态。
- 粘性阈值： 目录只有在到达视口顶部时才应变为粘性（固定），而不是在页面加载时立即固定。
- 点击跳转： 单击目录链接必须使用“平滑滚动”，以防止迷失方向，并且必须更新 URL 哈希（
#section-id）以便分享。
约束条件
- 可访问性： 目录必须包含在带有
aria-label="Table of contents"的<nav>中。活动链接必须使用aria-current="true"（或aria-current="location"）。确保在通过 Tab 键浏览链接时焦点环可见。 - 对比度： 活动和非活动状态必须满足 WCAG AA（4.5:1）要求。
- 响应式： 在移动设备上，目录不得与主要文本内容重叠；应使用抽屉或可切换的部分。
- 内容同步： 目录中的链接文本应与标题文本完全匹配（或者是清晰可辨的缩写版本）。
常见失败模式
- “过时”状态： 由于滚动监听触发点设置得过高或过低，目录高亮显示了错误的章节。
- 内容遮挡： 粘性目录覆盖了它本应帮助用户阅读的文本。
- 深度过载： 显示每一个
h4和h5，使目录比视口还长，需要自己的滚动条（避免嵌套滚动条）。 - 缺少 ID： 由于标题缺少匹配的
id属性而导致链接无法工作。 - 返回按钮失效： 跳转到章节时未更新 URL 哈希，导致用户无法使用浏览器的“返回”按钮返回到目录。
验证标准
-
h2和h3级别之间存在清晰的视觉层次结构（缩进）。 - 滚动监听能随着用户滚动正确高亮显示活动章节。
- 单击链接会平滑滚动到正确的章节。
- 单击目录链接后会更新 URL 哈希。
- 目录包含在
<nav aria-label="Table of contents">地标中。 - 活动状态可通过
aria-current访问。 - 定义了特定于移动设备的寻路模式（例如，抽屉或粘性栏）。
- 显示的层次结构不超过 3 个级别。