Skill: lenis-smooth-scroll

Thiết lập Lenis làm nền cuộn vật lý (physics-based) cho toàn trang, và đồng bộ đúng cách với GSAP ScrollTrigger — đây là bước hay bị làm sai nhất khi ráp 2 thư viện này chung.

WHAT

Purpose và context

Purpose: dựng Lenis làm nền cuộn vật lý cho TOÀN TRANG và đồng bộ đúng với GSAP ScrollTrigger (một driver raf, không lệch pha, không giật khi quay lại tab), mặc định bằng bản gốc nguyên văn ở
```
Rheinmir/uiux-asset
```
.
Trigger (when to use):
Trang cần cảm giác cuộn "nặng tay/mượt" kiểu Apple/awwwards thay vì cuộn giật cứng mặc định của trình duyệt.
Trang đã hoặc sẽ dùng GSAP ScrollTrigger (parallax, reveal, pin) và cần Lenis + ScrollTrigger KHÔNG đá nhau (giật, lệch vị trí trigger).
KHÔNG dùng nếu chỉ cần vài hiệu ứng cuộn nhẹ không cần smooth-scroll nền (dùng
```
scroll-effects
```
— vanilla, 0 dependency).
KHÔNG dùng để pin/cuộn-ngang một section riêng (đó là
```
gsap-scrolltrigger-pin
```
) — nhưng nếu trang có cả hai nhu cầu, khởi tạo Lenis theo skill này TRƯỚC, rồi
```
gsap-scrolltrigger-pin
```
hoạt động bình thường bên trên vì cả hai đều lấy ScrollTrigger làm trục.
- User nói "lenis", "smooth scroll", "cuộn mượt kiểu apple", "physics-based scroll", hoặc
```
/lenis-smooth-scroll
```
  .
Non-goals: không pin/cuộn ngang một section (→
```
gsap-scrolltrigger-pin
```
), không hiệu ứng cuộn lẻ 0-dependency (→
```
scroll-effects
```
), không viết lại code gốc của tác giả.

Mental model

bản gốc (Rheinmir/uiux-asset) → copy nguyên file → chỉ sửa nội dung

| nếu không được kéo lib ngoài:

assets/ (vanilla rút gọn) → ADAPT

. Lõi kỹ thuật:

reduced-motion? → không Lenis

new Lenis → driver: 2A raf tự quản (không GSAP) XOR 2B gsap.ticker (có GSAP) → lenis.on('scroll', ScrollTrigger.update) → reveal/data-speed ăn theo cùng driver

Input và output contract

	Field	Required?	Ý nghĩa
In	trang/dự án đích	có	có build step (npm) hay trang tĩnh (CDN)
In	có dùng GSAP ScrollTrigger?	có	quyết định driver 2A hay 2B
In	được kéo lib ngoài?	có	quyết định bản gốc hay `assets/`
Out	trang cuộn Lenis	có	một driver duy nhất; `* 1000` nếu qua `gsap.ticker` ; `lagSmoothing(0)` ; nhánh reduced-motion còn nguyên
Out	bằng chứng verify	có	`playwright-verify` : cuộn nhanh không nhảy vị trí + nhánh reduced-motion qua `page.emulateMedia`

Rules và capabilities

RULE-01 (MUST): Cài đặt:
```
npm i lenis gsap
```
(khuyến nghị cho dự án có build step) — hoặc CDN như trong
```
assets/demo.html
```
(
```
unpkg.com/lenis
```
,
```
cdnjs.cloudflare.com/.../gsap
```
) cho trang tĩnh/demo nhanh. Không dùng bản Lenis cũ tên gói
```
@studio-freight/lenis
```
(đã đổi tên thành
```
lenis
```
) trừ khi dự án đang pin phiên bản cũ có lý do.
RULE-02 (MUST): Lỗi thường gặp #1: quên
```
gsap.ticker.lagSmoothing(0)
```
→ cuộn mượt bình thường nhưng giật một cú khi người dùng đổi tab rồi quay lại — vì GSAP tự bù-lag chồng lên cơ chế làm mượt riêng của Lenis (xem giải thích ở mục Cơ chế).
RULE-03 (MUST): Lỗi thường gặp #2: chạy CẢ 2A (
```
requestAnimationFrame(raf)
```
tự quản) LẪN 2B (
```
gsap.ticker.add
```
) cùng lúc → hai vòng raf lệch pha, giật nhẹ liên tục. Chỉ chọn MỘT driver: có GSAP thì dùng 2B, không có thì dùng 2A.
RULE-04 (MUST): Lỗi thường gặp #3: gọi
```
lenis.raf(time)
```
từ
```
gsap.ticker
```
mà quên nhân
```
* 1000
```
(giây → mili-giây) → easing tính sai.
RULE-05 (MUST):
```
prefers-reduced-motion: reduce
```
→ không khởi tạo Lenis, không giả-mượt bằng CSS
```
scroll-behavior: smooth
```
thay thế — để cuộn gốc trình duyệt hoàn toàn (đã code trong
```
assets/lenis-demo.js
```
, đừng xoá nhánh này khi adapt).
RULE-06 (MUST): Verify bằng
```
playwright-verify
```
: cuộn nhanh liên tục, kiểm tra không có nhảy vị trí giữa
```
data-ls-reveal
```
và section chứa nó; test cả nhánh reduced-motion (giả lập qua
```
page.emulateMedia
```
).
Capabilities: đọc/copy file mẫu từ repo ngoài hoặc
```
assets/
```
; ghi vào dự án đích; cài dependency frontend (lenis, gsap); chạy trình duyệt headless để verify.

Failure boundaries

Không mở/clone được
```
Rheinmir/uiux-asset
```
→ dùng
```
assets/
```
vanilla rút gọn (partial), báo user.
User bật
```
prefers-reduced-motion: reduce
```
→ không khởi tạo Lenis (đúng hành vi, không phải lỗi).
Verify thấy nhảy vị trí/giật → failed, rà lại 3 lỗi thường gặp (#1–#3) trước khi báo xong.
Dự án pin
```
@studio-freight/lenis
```
có lý do → giữ nguyên, clarify với user trước khi đổi gói.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	yêu cầu	Chọn pen gốc phù hợp trong bảng "Bản gốc", mở link chạy xem đúng hiệu ứng	pen được chọn	không được kéo lib ngoài → B01
W02	effect	pen	Copy nguyên file `.html` (+ `_assets/` ) vào dự án, giữ comment ghi công, chỉ sửa nội dung/ảnh/màu; chạy qua HTTP	trang chạy	—
W03	deterministic	trang	Cài ( `npm i lenis gsap` hoặc CDN), khởi tạo Lenis sau guard reduced-motion; chọn MỘT driver (2A hoặc 2B)	Lenis chạy	có GSAP → B02
W04	deterministic	trang	Verify bằng `playwright-verify` (cuộn nhanh + reduced-motion qua `page.emulateMedia` )	pass	giật/nhảy → rà lỗi #1–#3, lặp W03

Chi tiết từng bước (nguồn chân lý cho W01–W04):

Bản gốc — dùng TRƯỚC (copy nguyên file, đừng viết lại)

Code gốc NGUYÊN VĂN của tác giả (CodePen public = MIT) nằm ở repo ngoài Rheinmir/uiux-asset
— gallery chạy thật: https://rheinmir.github.io/uiux-asset/scroll-effects/ . Quy trình: mở link chạy để xem đúng hiệu ứng → copy nguyên file

.html

(+ thư mục

_assets/

nếu file trỏ tới) vào dự án → giữ comment ghi công dòng đầu → chỉ sửa nội dung/ảnh/màu. Chạy local qua HTTP, không

file://

git clone --depth 1 https://github.com/Rheinmir/uiux-asset

nếu cần cả bộ offline.

Pen gốc — tác giả	Link
Lenis Smooth Scroll & GSAP Page — filipz	chạy · code
Lenis Smooth Scroll Cinematic Experience — filipz	chạy · code
Layout Explorations with GSAP, Flip, Lenis and ScrollTrigger N°2 — filipz	chạy · code
Staggered Text Scroll Reveal — gusevdigital	chạy · code

assets/

trong skill này chỉ là bản rút gọn vanilla tự viết — dùng khi dự án KHÔNG được kéo lib ngoài; mặc định dùng bản gốc ở trên.

Assets

assets/demo.html

assets/lenis-demo.css

assets/lenis-demo.js

— trang demo chạy được (CDN Lenis + GSAP), đọc rồi ADAPT (đổi token/section theo dự án, đổi CDN sang bundle npm nếu dự án đã có build step).

Cơ chế

1. Khởi tạo Lenis

const lenis = new Lenis({
  lerp: 0.1,        // nội suy mỗi frame (0–1): thấp = mượt/trễ hơn, cao = bám sát input hơn
  duration: 1.2,     // easing khi có target (vd anchor scroll), không áp dụng cho wheel liên tục
  smoothWheel: true, // bật vật lý mượt cho wheel/trackpad — lý do chính để dùng Lenis
});

2A. Đứng một mình (không GSAP) — vòng lặp raf tự quản

function raf(time) {
  lenis.raf(time);
  requestAnimationFrame(raf);
}
requestAnimationFrame(raf);

2B. Có GSAP ScrollTrigger — GỘP về một driver duy nhất (không dùng cả 2A lẫn 2B cùng lúc)

gsap.registerPlugin(ScrollTrigger);

lenis.on('scroll', ScrollTrigger.update);         // Lenis cuộn -> báo ScrollTrigger cập nhật ngay
gsap.ticker.add((time) => lenis.raf(time * 1000)); // gsap.ticker LÀM vòng raf cho Lenis luôn
gsap.ticker.lagSmoothing(0);                        // tắt bù-lag mặc định của GSAP (xem lý do bên dưới)

Tại sao phải làm đúng thứ tự 3 dòng này (điểm hay sai nhất):

```
gsap.ticker
```
đã tự chạy một vòng
```
requestAnimationFrame
```
nội bộ để lái mọi tween/ScrollTrigger. Nếu Lenis lại tự chạy thêm một
```
requestAnimationFrame(raf)
```
riêng (cách 2A) TRONG KHI đã có GSAP, hai vòng lặp không cùng nhịp — mỗi frame chúng cập nhật lệch nhau vài mili-giây, ScrollTrigger đọc vị trí cuộn "cũ hơn" hoặc "mới hơn" Lenis một khung hình. Cảm giác là giật nhẹ liên tục khi cuộn nhanh, đặc biệt ở section có
```
pin
```
hoặc
```
scrub
```
. Sửa bằng cách để gsap.ticker làm driver DUY NHẤT: bỏ hẳn
```
requestAnimationFrame(raf)
```
riêng, thay bằng
```
gsap.ticker.add(...)
```
.
```
gsap.ticker
```
phát
```
time
```
tính bằng giây, còn
```
lenis.raf()
```
cần mili-giây → phải nhân
```
* 1000
```
. Quên nhân là lỗi im lặng: Lenis chạy nhưng easing/velocity tính sai theo một hệ thời gian nhỏ hơn 1000 lần, scroll trông "đơ" hoặc "bay" tuỳ lerp.
```
lenis.on('scroll', ScrollTrigger.update)
```
bắt buộc vì Lenis cập nhật vị trí cuộn qua transform nội bộ (
```
lerp
```
mỗi frame, không phải
```
scrollTop
```
tức thời) — nếu không báo, ScrollTrigger vẫn dùng sự kiện
```
scroll
```
gốc của trình duyệt để tính pin/progress, vốn KHÔNG khớp với vị trí "mượt" mà Lenis đang vẽ ra → pin bị lệch vài px hoặc trigger bắn sai thời điểm.
```
gsap.ticker.lagSmoothing(0)
```
xử lý một lỗi khác, dễ bị bỏ sót: mặc định GSAP tự phát hiện khung hình bị trễ bất thường (ví dụ tab mất focus vài giây rồi quay lại) và "nén" thời gian lại để bù, cho animation không nhảy cóc. Nhưng Lenis đã tự có cơ chế làm mượt delta-time của riêng nó — hai hệ bù-thời-gian chồng lên nhau khiến cú quay-lại-tab bị giật một nhịp rõ rệt thay vì mượt. Tắt hẳn bù của GSAP (
```
lagSmoothing(0)
```
) để một mình Lenis lo phần đó.

3. Tôn trọng

prefers-reduced-motion: reduce

Không được "giả-mượt" cho người đã bật giảm chuyển động — không khởi tạo

Lenis

luôn, để trình duyệt cuộn gốc (jump-scroll bình thường). Kiểm tra TRƯỚC khi gọi

new Lenis(...)

if (!window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
  // new Lenis(...) + sync ở trên
} else {
  // cuộn gốc trình duyệt; nếu có reveal-on-scroll đi kèm, hiện thẳng bằng CSS/class, không chờ cuộn mượt
}

Xem cách áp dụng đầy đủ (kèm demo reveal fallback) trong

assets/lenis-demo.js

4. Demo: reveal +

data-speed

khi cuộn qua Lenis

assets/demo.html

có vài section gắn

data-ls-reveal

(stagger hiện dần, dùng

ScrollTrigger.create({ once: true })

ăn theo scroll đã sync ở bước 2B) và

data-speed="0.12"

(layer trôi lệch nhẹ qua

gsap.to(..., { scrollTrigger: { scrub: true } })

, giá trị kẹp

|v| ≤ 0.3

để tránh say chuyển động) — cả hai dùng CHUNG driver Lenis/GSAP đã thiết lập, không tạo listener

scroll

rời.

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	dự án KHÔNG được kéo lib ngoài / cần bản tự viết	dùng `assets/demo.html` + `assets/lenis-demo.css` + `assets/lenis-demo.js` , ADAPT token/section	—	W03
B02	conditional_required	trang có GSAP ScrollTrigger	driver 2B: `lenis.on('scroll', ScrollTrigger.update)` + `gsap.ticker.add((time) => lenis.raf(time * 1000))` + `gsap.ticker.lagSmoothing(0)` ; bỏ hẳn 2A	không GSAP → 2A	W04
B03	conditional_required	`prefers-reduced-motion: reduce`	không `new Lenis` , cuộn gốc; reveal hiện thẳng bằng CSS/class	—	W04
B04	user_optional	trang cần thêm pin/cuộn ngang section	khởi tạo Lenis theo skill này TRƯỚC rồi dùng `gsap-scrolltrigger-pin` bên trên	—	W04

Validation và stopping

Xong khi

playwright-verify

cuộn nhanh liên tục không nhảy vị trí giữa

data-ls-reveal

và section chứa nó, và nhánh reduced-motion (qua

page.emulateMedia

) cuộn gốc không Lenis. Code chỉ có MỘT driver raf.

Examples

Positive: "làm trang landing cuộn mượt kiểu apple có parallax" → chọn pen "Lenis Smooth Scroll & GSAP Page — filipz", copy nguyên
```
lenis-smooth-scroll-gsap-page.html
```
, đổi nội dung/ảnh → verify cuộn nhanh không lệch pin, reduced-motion cuộn gốc.
Boundary/failure: code adapt có cả
```
requestAnimationFrame(raf)
```
lẫn
```
gsap.ticker.add(...)
```
→ giật nhẹ liên tục (lỗi #2) → xoá vòng 2A, chỉ giữ 2B, verify lại; quên
```
* 1000
```
thì scroll "đơ/bay" (lỗi #3).

Origin

Batch 180926 — bản gốc NGUYÊN VĂN nằm ở

Rheinmir/uiux-asset/scroll-effects/

(xem mục "Bản gốc" ở trên);

assets/

là bản rút gọn vanilla tự viết.

lenis-smooth-scroll

NPX Install

Tags

SKILL.md Content