name: lenis-optimizer description: Audit and optimize Lenis smooth-scroll setups (lenis, lenis/react, lenis/vue,+lenis/snap) — missing or duplicated RAF loops, the required lenis.css classes, scroll-behavior conflicts, GSAP ScrollTrigger sync, anchor links anchors option, nested scroll (allowNestedScroll vs data-lenis-prevent), stop/lock during modals, respectReducedMotion/a11y, touch and performance settings (naiveDimensions, syncTouch). Report with evidence and a fix plan approved before edits. Use when the user mentions Lenis, smooth scrolling, lenis/react, data-lenis-prevent, ScrollTrigger jank, "scroll feels weird/janky after adding Lenis", or smooth scroll in a Next.js/React/Vue site -- even if they don't say the word "optimize".

Lenis Optimizer

Audit how a site uses Lenis, report what is wrong or wasting main-thread time, agree a plan, then fix. Lenis runs on the browser's own scroll and drives a RAF loop every frame, so the classic failure modes are: no RAF driver at all (scroll never smooths), two instances fighting, missing recommended CSS, breaking anchors/nested/modals, and syncing it wrong w/ ScrollTrigger or WebGL. Nothing is edited before the plan is approved.

Workflow

1. Scope (quick)

• Project root (package.json with lenis or lenis/react; plain sites with a lenis.min.js script tag count too).
• Run python <skill-dir>/scripts/audit.py <project-root> [--json] — detects how Lenis is initialized and driven (autoRaf vs manual raf/GSAP ticker), instance count, React lifecycle (effect + destroy cleanup), presence of the required CSS, scroll-behavior conflicts, anchors setup, data-lenis-prevent usage, GSAP/ScrollTrigger sync, and perf/a11y option flags.

2. Audit

Read the init file plus whatever the leads point to. Load only what applies:

Confirm by reading (the script can't see DOM):

• Which scroll container is wrapped — root (window) vs a wrapper element; content mismatches silently do nothing.
• Where lenis.on('scroll') handlers run — anything heavy in a per-frame handler is the site's new frame budget.
• Whether the site needs smooth scroll at all — pages that are mostly form/app UI usually shouldn't smooth; content-heavy marketing pages benefit most.
• Version gulfs: v0.x (@studio-freight/lenis) vs lenis v1.x — renamed imports, autoRaf/anchors availability, React adapter placement.

Measure where it matters: if scroll feels janky, capture a Performance trace while scrolling (main-thread budget per frame is Lenis's own raf step + every handler attached to it). Report what you measured; say plainly when you couldn't.

Mark findings Confirmed or Suspected.

3. Report

Fill in assets/report-template.md, save as LENIS_REPORT.md in the project root. Group the lumps: setup correctness, framework lifecycle, integrations, a11y/perf.

4. Plan — stop for approval

1. Quick wins — add/repair the RAF driver, import lenis/dist/lenis.css (or inlined classes), remove scroll-behavior: smooth, kill duplicate instances, add anchors: true.
2. Structural — React/Vue lifecycle fixes (single root provider, destroy on unmount), GSAP ScrollTrigger sync per docs, data-lenis-prevent on modals/menus (or allowNestedScroll conscious choice), scroll locking (stop()/start() around modals).
3. Heavy/optional — syncTouch/infinite features, snapping via lenis/snap, swapping wrapper strategy, removing Lenis on app-heavy routes. Per step: files, expected effect, verification, rollback. Let the user drop/reorder.

5. Fix

Approved items only. Lenis behavior changes are user-visible in motion; change one thing at a time and test wheel + keyboard + touch on each. If an approved fix turns out to alter scrolling semantics (e.g. enabling syncTouch), stop and confirm.

6. Verify and wrap up

• Console for errors, wheel scroll, anchor click, open/close modal, nested scroll region, tab navigation, prefers-reduced-motion emulation (smoothing off, jump scrolls).
• If jank was the complaint: before/after Performance traces; report the real difference or say you couldn't measure.
• Deferred items + one suggested next step.

Principles

• One instance, one driver. A single Lenis instance with exactly one RAF source (autoRaf, own raf loop, or GSAP ticker — never two).
• The CSS is not optional. Without the recommended lenis classes/styles Lenis fights the browser (and the docs say so); first check in any jank report.
• Native scroll stays native. Lenis wraps the browser's own scroll, so position: sticky, anchors and a11y keep working; data-lenis-prevent reserves native scrolling for nested elements instead of fighting them.
• Motion preference first. respectReducedMotion is on by default — turning it off is a deliberate product call the user must approve, not an optimization.
• Interop is documented, not improvised: GSAP ScrollTrigger sync, anchors, and stop/lock patterns all have a canonical snippet; don't invent scrollTo shims.
• Length still costs frames. Every lenis.on('scroll') handler runs per frame; the fewer and cheaper the handlers, the smoother the site.
• Docs over memory. Lenis moves fast (options get renamed); fetch the current README (https://github.com/darkroomengineering/lenis) when unsure of an option name before adding it to the plan.