scroll-effects

技能：scroll-effects

页面滚动效果中心：Rheinmir/uiux-asset 中有 64 个原始版本，未经修改（freefrontend/CodePen，MIT）——浏览 gallery，复制整个文件。还附带 assets/ 中 7 个自行编写的 vanilla 效果，适用于不能引入外部库的项目。

WHAT

用途与背景

• **用途：**为落地页添加轻量滚动效果——默认复制 Rheinmir/uiux-asset 中的原始版本文件；不能引入外部库的项目则使用 assets/ 中的 7 种 vanilla 模式。
• 触发条件（何时使用）：
  • 页面需要滚动时渐显、文字交错出现、引导视线的高亮、收缩导航、回到顶部按钮、随 section 固定的目录，或轻度视差效果。
  • 用户提到“滚动效果”“回到顶部”“scrollspy”“视差”“滚动时渐显”。
• **非目标：**不要用于：GPU 开销大的电影感图像转场（使用 blur）、时间线节点轴（使用 timeline）、复杂的 GSAP ScrollTrigger 式横向固定 section 滚动（超出此轻量技能的范围——向用户明确说明）。

思维模型

效果需求 → 64 个原始版本的 gallery（默认，复制整个文件）或 7 种 vanilla 模式（不能引入库）→ 按 design.md 调整 token → 一个 IntersectionObserver + 一个 rAF 滚动监听器 → reduced-motion 时全部关闭 → 使用 playwright 验证。如果 gallery 项目属于子技能，则转到相应的子技能。

输入与输出约定

	字段	必填？	含义
输入	所需效果	是	7 种模式之一或 gallery 项目
输入	项目约束	否	是否允许引入库/外部文件；是否有 design.md
输出	项目中的效果文件	是	直接复制的原始版本（保留首行的署名注释）或调整后的 vanilla 资源
输出	验证证据	是	滚动前后截图、.is-in 出现、无水平溢出

规则与能力

• RULE-01 (MUST)：prefers-reduced-motion: reduce → 关闭全部效果：CSS 强制 .is-in 立即显示且无 transition，JS 禁用平滑滚动和视差（资源中已写好相关逻辑，调整时不要删除此分支）。
• RULE-02 (MUST)：reveal + stagger + highlight + TOC 共用一个 IntersectionObserver（已合并在 scroll-effects.js 中）——不要分别创建 4 个 observer。
• RULE-03 (MUST)：只使用一个滚动监听器，并通过 rAF 限频——nav + top + parallax 每帧共用同一个 scrollY，不要分别绑定 3 个 scroll 监听器。
• RULE-04 (MUST)：使用 playwright-verify 验证：截取滚动前后截图、断言 .is-in 出现、测量是否存在由视差导致的水平溢出。
• RULE-05 (MUST)：调整到有 design.md 的项目时：更改颜色/spacing token，保留 data-se-* 名称（JS 依赖这些名称）。
• 能力：读取外部 gallery/repo 资源（网络）或内部资源；向项目写入前端文件；通过本地 HTTP 使用无头浏览器。

失败边界

• 如果需求是高开销 WebGL、时间线节点轴或复杂的 GSAP 固定 section → blocked，超出范围；明确告知用户并指向正确的技能。
• 无法访问外部 gallery/repo，或项目禁止引入外部库 → 使用 7 种 vanilla 模式（不算错误）。
• playwright 验证未发现 .is-in 或出现水平溢出 → failed，修复后重新验证。

HOW

主工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	判断	需求	确认是否在范围内（不是 blur/timeline/GSAP pin）	范围内的效果	超出范围 → blocked
W02	判断	项目约束	选择来源：gallery 原始版本（默认）或 vanilla assets/（B01）	来源	—
W03	执行	来源	原始版本：打开链接运行 → 复制整个 .html（以及 _assets/）→ 保留署名注释 → 只修改内容/图片/颜色	项目中的文件	—
W04	执行	design.md	调整颜色/spacing token，保留 data-se-*，保留 reduced-motion 分支	已调整的文件	—
W05	确定性	通过 HTTP 访问的页面	使用 playwright-verify：截取滚动前后截图、断言 .is-in 出现、测量溢出	PASS	FAIL → 修复并重复 W05

各步骤详情（W01–W05 的权威来源）：

原始版本 — 优先使用（原样复制整个文件，不要重写）

作者的原始代码（公开 CodePen = MIT）位于外部仓库 Rheinmir/uiux-asset — 可实际运行的 gallery：https://rheinmir.github.io/uiux-asset/scroll-effects/ 。 流程：打开可运行的链接查看准确效果 → 将整个 .html 文件（如果文件引用了 _assets/ 文件夹，也一并复制）复制到项目中 → 保留首行的署名注释 → 仅修改内容/图片/颜色。通过 HTTP 在本地运行，不要用 file://。 如需整个离线资源包，可运行 git clone --depth 1 https://github.com/Rheinmir/uiux-asset。

Hub：在 gallery 中浏览全部 64 个条目（按名称/技术/作者筛选），然后转到相应的子 skill。

此 skill 中的 assets/ 仅包含自行编写的精简 vanilla 版本 — 仅当项目不允许引入外部库时使用；默认使用上面的原始版本。

Assets

assets/demo.html（已拼装好全部 7 种效果的演示页面）+ assets/scroll-effects.css + assets/scroll-effects.js — 阅读后进行适配（如果项目有 design.md，则按其调整 class/token）。

Branches

ID	Kind	Guard	行为	Skip / failure	Rejoin
B01	conditional_required	项目不允许引入外部库/文件	使用 assets/ 中的 7 种 vanilla 模式（见下方 Reference），替代原始版本	允许引入外部内容 → 使用 gallery 中的原始版本	W04
B02	user_optional	需要整个原始资源包离线使用	对 Rheinmir/uiux-asset 仓库运行 git clone --depth 1	—	W03
B03	conditional_required	gallery 条目属于某个子 skill	转到相应的子 skill	—	在子 skill 中结束

Validation 和 stopping

通过本地 HTTP 运行（不要用 file://）。Playwright 截取滚动前后的画面，确认出现 .is-in、没有水平溢出，并且启用 reduced-motion 时所有元素都会立即显示，即为 PASS。PASS 后停止；FAIL 则修复并重新验证。

Examples

• Positive：“为文档页面添加 scroll to top + scrollspy，不允许引入库” → B01 使用 assets/ 中的 [data-se-top] + [data-se-toc]，按 design.md 调整 token，保留 data-se-* → Playwright 验证：scrollY > innerHeight 时按钮出现，TOC 链接获得 .is-active。
• Boundary/failure：“制作类似 GSAP 的横向滚动固定区块” → 超出此轻量 skill 的范围 → 向用户说明，不要尝试用 parallax data-se-parallax 实现。

Reference — 7 种模式（最简标记 + 机制）

1. 滚动时显示 — [data-se-reveal]

元素先淡出并轻微滑动，滚入视口时显示。

<div data-se-reveal>Lộ dần khi cuộn tới</div>

IntersectionObserver 添加 .is-in → CSS transition opacity/translateY。可参考 gallery scroll-effects #9（Animated Scroll Highlight Annotations）了解适用场景，不要使用其代码。

2. 文字依次显示 — [data-se-stagger]

文字行依次显示。

<h2 data-se-stagger>
  <span>Dòng một</span><span>Dòng hai</span><span>Dòng ba</span>
</h2>

JS 为每个 span 设置 --i → CSS transition-delay: calc(var(--i) * 90ms)。只按现有子元素拆分，不要自行拆分 text node（保持 DOM 简单，避免 a11y 问题）。

3. 滚动高亮 — [data-se-highlight] > mark

突出显示重点，段落进入视口时，颜色从左→右扫过。

<p data-se-highlight>Đọc tới đây <mark>ý chính hiện ra</mark> rồi đọc tiếp.</p>

mark 使用 background-size: 0% → 100%，在父元素具有 .is-in 时执行 transition。使用真正具有语义的 <mark>，不要用假 span。

4. 粘性缩小导航栏 — [data-se-nav]

向下滚动时，页眉收缩；回到顶部时，恢复原状。

<header data-se-nav class="site-nav">…</header>

滚动监听器（rAF-throttle）在 scrollY > 24 时切换 .is-shrunk。只通过 class 更改 padding/font-size，不要逐帧设置 inline style。

5. 回到顶部 — [data-se-top]

回到页面顶部的按钮，只在滚动超过一屏后显示。

<button data-se-top aria-label="Về đầu trang">↑</button>

点击 → window.scrollTo({ top: 0, behavior: "smooth" })（除非 prefers-reduced-motion → "auto"）。显示阈值：scrollY > innerHeight。

6. Scrollspy TOC — [data-se-toc] a[href^="#"] + section[id]

粘性目录，链接随正在阅读的 section 高亮。

<nav data-se-toc><a href="#s1">Mục 1</a><a href="#s2">Mục 2</a></nav>
<section id="s1">…</section><section id="s2">…</section>

IntersectionObserver 配合 rootMargin: "-40% 0px -55% 0px" → 匹配的链接获得 .is-active。可参考 gallery #19（Auto-Generated Anchor TOC）的思路，代码需自行编写。

7. Parallax nhẹ — [data-se-parallax="0.2"]

Lớp nội dung trôi chậm hơn/nhanh hơn tốc độ cuộn.

<div data-se-parallax="0.15">Trôi chậm tạo chiều sâu</div>

rAF loop: translateY = (elCenter - viewportCenter) * speed. Giá trị speed khuyến nghị |v| ≤ 0.3; vượt quá gây say chuyển động. KHÔNG dùng cho chữ nhỏ cần đọc chính xác.

Origin

• User chốt "làm đi hỏi nhiều quá" → thay vì bulk-copy 81 tác phẩm, viết BỘ GỐC 7 pattern generic (kỹ thuật chuẩn ngành: IntersectionObserver/scroll listener/rAF — không phải biểu đạt sáng tạo riêng của ai) để downstream tham khảo code mẫu ngay, đúng cách blur/timeline đã làm.