scroll-progress-timeline

滚动进度时间线

用一条进度线串联有序信息。添加动画前，必须确保整个序列完整、易读且便于导航。

建模步骤

让内容由数据驱动：

const steps = [
  { id: "brief", number: "01", title: "Set the direction", body: "..." },
  { id: "build", number: "02", title: "Make the system", body: "..." },
  { id: "ship", number: "03", title: "Release and learn", body: "..." }
];

将其渲染为带有真实标题的有序列表。线条、圆点、媒体内容和活动状态用于增强这一结构，而不是取代它。

构建线条

1. 在所有节点后方渲染一条低调的基线。
2. 在其上方放置一条进度线；垂直布局使用 transform-origin: top，水平布局使用 left。
3. 测量第一个和最后一个节点的中心点，而不是任意选取区块边缘。
4. 以这两个中心点为基准，对滚动位置进行归一化。
5. 应用 scaleY(progress) 或 scaleX(progress)，让更新保持在合成器上执行。
6. 当进度线头越过某个步骤的中心点时，将该步骤标记为活动状态。

const progress = Math.min(1, Math.max(0,
  (viewportAnchor - lineStart) / (lineEnd - lineStart)
));
line.style.transform = `scaleY(${progress})`;

在一个动画帧中安排 DOM 写入。字体和图像加载完成、窗口大小变化、方向变化以及内容发生变化后，重新计算几何信息。

选择布局

• 仅当两侧都有足够宽度且内容分量相近时，才使用居中的交替式时间线。
• 对于较长的文案、紧凑的步骤或卡片高度不一的情况，使用左侧轨道。
• 对于标签简短的序列，使用水平线，并明确处理对键盘操作安全的溢出。
• 仅当每个步骤都有独特的视觉状态时，才使用固定的全屏章节。固定时长应有限，并在进入下一章节前解除固定。
• 在小屏幕上折叠为简洁的左侧轨道。不要为了保留交替布局而牺牲阅读顺序。

为步骤状态添加动画

使用轻微的不透明度、位移、缩放、模糊、颜色或媒体过渡效果。即使处于非活动状态，也要确保每个步骤都清晰可读。仅当活动状态有实际意义且当前有效时，才使用 aria-current="step" 暴露活动索引；不要通过实时区域播报每次滚动更新。

对于简单的活动状态进入效果，使用 IntersectionObserver。当进度线需要连续填充或与固定媒体协调时，使用归一化滚动测量或 GSAP ScrollTrigger。

处理导航

• 如果用户可以跳转到流程中的任意步骤，请将步骤链接设为真实锚点。
• 为粘性页眉添加 scroll-margin。
• 保留焦点，不要在被动滚动时移动焦点。
• 除非用户明确选择某个步骤，否则保持 URL 和浏览器历史记录稳定。
• 如果步骤具有交互性，请使用按钮或链接并显示焦点；切勿让装饰性圆点成为唯一控件。

减少动态效果

在 prefers-reduced-motion: reduce 条件下，显示完整的进度线或已到达的离散状态，不使用随滚动插值的动画、模糊效果、固定效果或大幅变换。保留常规文档流和所有步骤内容。

验证

测试不同的步骤数量、高度不一的卡片、缺失的媒体内容、较长的译文、390/768/1024/1440 宽度、200% 缩放、快速向前和向后滚动、直接锚点导航、键盘顺序、减少动态效果、字体或图像延迟加载导致的布局变化、路由清理，以及控制台错误。每个边界处的活动步骤都必须与进度线头一致。

使用 demo/index.html 作为实践参考，并使用 demo/PROMPT.md 重新创建或改编它。将 REFERENCES.md 保留为仅包含链接的实现资料清单。