svg-stroke-reveal

Skill: svg-stroke-reveal

Component vanilla HTML/CSS/JS — nét <path> trong SVG "vẽ" dần ra như có tay đang kẻ, theo % cuộn qua viewport hoặc một lần khi vào khung nhìn. Không dùng thư viện ngoài (không Anime.js, không GSAP).

WHAT

Purpose và context

• Purpose: nét <path> trong SVG "vẽ" dần ra theo % cuộn hoặc một lần khi vào viewport (stroke-dasharray/dashoffset), vanilla không lib ngoài; mặc định dùng bản gốc nguyên văn ở Rheinmir/uiux-asset.
• Trigger (when to use):
  • Logo/chữ ký/icon cần hiệu ứng "vẽ dần" khi vào viewport (chạy 1 lần).
  • Biểu đồ đường, sơ đồ hành trình, đường route cần "vẽ ra" liên tục theo tiến trình cuộn (gắn với vị trí cuộn thật, không phải chạy 1 lần).
  • User nói "vẽ svg khi cuộn", "svg stroke draw", "logo vẽ dần", "path animation reveal", "stroke-dashoffset", hoặc /svg-stroke-reveal.
• Non-goals: KHÔNG dùng cho 7 hiệu ứng cuộn chung (opacity/translate reveal, stagger text, highlight, nav co, scroll-to-top, scrollspy, parallax) — đó là skills/scroll-effects. Không dùng cho <text> chưa convert outline (xem Rules).

Mental model

[data-svgr] > <path>×N → getTotalLength() → dasharray = dashoffset = length (ẩn) → mode "once" (IO một lần + CSS transition) hoặc mode "scroll" (IO bật cờ + 1 listener rAF ghi dashoffset theo progress) → reduce-motion: dashoffset = 0 ngay.

Input và output contract

	Field	Required?	Ý nghĩa
In	SVG thật của dự án (các <path> có nét)	có	<text> phải convert outline trước
In	mode once hoặc scroll	có	logo/chữ ký → once; biểu đồ/hành trình → scroll
In	design.md của dự án	không	có thì đổi token màu theo nó
Out	SVG gắn [data-svgr] + CSS/JS trong dự án	có	copy nguyên file gốc hoặc adapt assets/
Out	bằng chứng verify playwright-verify	có	ảnh trước/giữa/sau (scroll) + once chỉ trigger 1 lần

Rules và capabilities

• RULE-01 (MUST): getTotalLength() đo trên toạ độ nội tại của path, KHÔNG bị ảnh hưởng bởi CSS transform — nhưng nếu bạn scale phần tử chứa path bằng transform: scale(sx, sy) với sx != sy (scale KHÔNG ĐỀU hai trục) SAU khi đã set dasharray, tốc độ vẽ theo px sẽ méo lệch giữa hai trục vì animation vẫn chạy theo length gốc trong khi hiển thị đã bị bóp méo tỷ lệ. Luôn set kích thước qua viewBox + width/height đồng nhất tỉ lệ, tránh CSS scale lệch trục trên chính phần tử mang path.
• RULE-02 (MUST): <text> không stroke-draw được — phải convert chữ/font sang outline <path> thật trước (Illustrator "Create Outlines", Figma "Flatten", hoặc tool convert font-to-path) rồi mới áp [data-svgr]. Áp thẳng lên <text> sẽ không có gì xảy ra vì <text> không có getTotalLength().
• RULE-03 (MUST): Mode "once" dùng CSS transition (mượt, rẻ CPU); mode "scroll" set dashoffset trực tiếp mỗi frame qua JS (bắt buộc để đồng bộ khít với vị trí cuộn) — đừng đổi ngược hai cách này.
• RULE-04 (MUST): Một IntersectionObserver riêng cho mỗi mode (không gộp chung logic once/scroll vào 1 observer vì hành vi khác nhau: unobserve-1-lần vs toggle cờ liên tục) và một scroll listener rAF-throttle DUY NHẤT cho tất cả SVG mode "scroll" trên trang — không gắn nhiều listener scroll rời cho mỗi SVG.
• RULE-05 (MUST): Verify bằng playwright-verify: chụp trước/giữa/sau khi cuộn qua SVG mode "scroll" để thấy dashoffset giảm dần, và assert SVG mode "once" chỉ trigger 1 lần dù cuộn ra vào nhiều lần.
• Capabilities: đọc bản gốc (web/git) + asset skill + design.md; ghi HTML/CSS/JS vào dự án đích; chạy trình duyệt headless để verify.

Failure boundaries

• Áp lên <text> chưa convert outline → không có gì xảy ra: blocked, yêu cầu convert sang <path> trước (RULE-02).
• Phần tử mang path bị CSS scale lệch trục → tốc độ vẽ méo: failed, chuyển kích thước qua viewBox + width/height (RULE-01).
• Assert verify đỏ (dashoffset không giảm dần, once trigger lại) → failed, sửa rồi verify lại.

HOW

Main workflow

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	judgment	SVG + yêu cầu	Chọn mode once hay scroll; kiểm SVG đã là <path> (không <text>)	mode	<text> → blocked tới khi convert
W02	effect	bảng Pen gốc	Mở link chạy, copy nguyên file .html (+ _assets/) vào dự án, giữ comment ghi công	file gốc trong dự án	không được kéo lib ngoài → B01
W03	effect	file + SVG thật + design.md	Chỉ sửa nội dung/ảnh/màu (thay path d=)	SVG đã adapt	—
W04	deterministic	trang chạy qua HTTP	Verify bằng playwright-verify (RULE-05)	ảnh + assert	đỏ → sửa, lặp W04

Branches

ID	Kind	Guard	Hành vi	Skip / failure	Rejoin
B01	conditional_required	dự án KHÔNG được kéo lib ngoài (bản gốc)	dùng bản rút gọn vanilla assets/ (mục Reference — Assets), đọc rồi ADAPT	—	W04
B02	conditional_required	prefers-reduced-motion: reduce	strokeDashoffset = 0 ngay lúc init, bỏ observer/listener	—	W04

Validation và stopping

Assert tất định ở W04 (mode scroll: dashoffset giảm dần qua ảnh trước/giữa/sau; mode once: chỉ trigger 1 lần dù cuộn ra vào). Cần mắt: độ mượt, thứ tự nét. Dừng khi assert xanh.

Examples

• Positive: "logo vẽ dần khi vào màn hình" → data-svgr="once" trên logo 4 path → vào viewport 30% thì vẽ lần lượt (stagger 160ms theo thứ tự DOM), cuộn ra vào lại không vẽ lại.
• Boundary/failure: chữ ký là <text> font script → không có getTotalLength(), không vẽ gì → dừng, yêu cầu convert outline (Figma "Flatten") thành <path> rồi mới áp [data-svgr].

Reference — 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
Interactive Cicada Genomics Landing Page — alyona-mysiura	chạy · code
Scroll-Driven SVG Map Editorial Gallery — knyttneve	chạy · code
Scroll-Driven Godzilla Walk-and-Destroy Animation — creativeocean	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.

Reference — Assets

assets/demo.html + assets/svg-stroke-reveal.css + assets/svg-stroke-reveal.js — đọc rồi ADAPT vào SVG thật của dự án (thay path d=, đổi token màu theo design.md nếu có), không copy máy móc.

Reference — Cơ chế

• Với MỖI <path> trong [data-svgr]: JS gọi path.getTotalLength(), set inline style.strokeDasharray = length và style.strokeDashoffset = length lúc init → nét ẩn hoàn toàn (dash đúng bằng chiều dài path, offset đẩy hết dash ra ngoài).
• Mode data-svgr="once" (threshold 1 lần — logo/chữ ký): IntersectionObserver threshold 0.3, khi vào viewport → set strokeDashoffset = 0 cho tất cả path con → CSS transition: stroke-dashoffset chạy 1 lần → unobserve ngay sau khi trigger, không lặp lại kể cả cuộn ra rồi cuộn lại.
• Mode data-svgr="scroll" (progress liên tục — biểu đồ/hành trình): IntersectionObserver chỉ bật/tắt cờ "đang trong viewport"; khi đang bật, một scroll listener rAF-throttle (dùng chung 1 listener, không tạo nhiều) tính progress = (innerHeight - rect.top) / (innerHeight + rect.height) kẹp 0..1, rồi ghi trực tiếp strokeDashoffset = length * (1 - progress) mỗi frame — KHÔNG dùng CSS transition ở mode này (transition sẽ làm nét trễ nhịp so với vị trí cuộn thật).
• Path phức tạp nhiều <path> con (logo nhiều nét, chữ ký) — mode "once" stagger bằng transition-delay: calc(var(--svgr-i) * 160ms), JS gán --svgr-i theo THỨ TỰ path trong DOM (path đầu vẽ trước).
• prefers-reduced-motion: reduce → JS set strokeDashoffset = 0 ngay cho toàn bộ path lúc init, bỏ qua cả hai observer/listener — hiện full nét tức thì, không animate.

Origin