Communitygithub.com

brainzcode/premium-landing

사이트에 Lenis 부드러운 스크롤을 올바르게 추가합니다 — 설정, 고정 헤더를 위한 앵커 오프셋, 모달 및 메뉴를 위한 스크롤 잠금, 축소 모션 처리를 포함합니다.

premium-landing란 무엇인가요?

이 스킬은 Lenis 라이브러리를 사용하여 웹사이트에 부드러운 스크롤 효과를 올바르게 통합하는 방법을 설명합니다. Lenis는 네이티브 스크롤 위치를 보간하여 부드러운 스크롤을 제공하며, sticky 포지셔닝, IntersectionObserver, window.scrollY와의 호환성을 유지합니다. 이 스킬은 Lenis 설정, 고정 헤더를 위한 앵커 오프셋 조정, 모달 및 메뉴 열기 시 스크롤 잠금 처리, 사용자의 축소 모션 선호도에 따른 대응 방법을 다룹니다. 특히 개발자들이 자주 실수하는 sticky 포지셔닝과 overflow: clip의 충돌 문제를 해결하는 방법을 상세히 설명하며, 프레임 타이밍 측정 도구를 사용해 성능을 분석하고 Lenis 도입 후 발생할 수 있는 다른 성능 문제를 식별하는 방법도 제공합니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 활용 가능한 실용적인 가이드입니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/brainzcode/premium-landing/tree/HEAD/plugins/premium-landing/skills/lenis-smooth-scroll

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Lenis 부드러운 스크롤

Lenis는 휠 입력을 가로채서 네이티브 스크롤 위치를 부드럽게 보간합니다. sticky 포지셔닝, IntersectionObserver, window.scrollY가 모두 계속 작동합니다 — 이것이 Lenis가 올바른 선택인 이유입니다. 문제는 Lenis 자체가 아니라 Lenis와 충돌하는 것들에서 발생합니다.

설정

CDN을 직접 링크하는 대신 벤더 파일로 가져와서 사이트가 자체적으로 완결되고 file://에서도 작동하도록 합니다:

curl -sSL -o assets/vendor/lenis.min.js https://unpkg.com/[email protected]/dist/lenis.min.js

dist/lenis.min.js 빌드는 globalThis.Lenis를 노출하는 IIFE입니다 — 일반 <script> 태그에서 문제없이 사용할 수 있습니다. (dist/lenis.mjs는 ESM이며 일반 스크립트 태그에서는 작동하지 않습니다.) 자체 스크립트 전에 로드하세요.

var reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
var lenis = null;

if (!reduced && window.Lenis) {
  var navH = parseInt(getComputedStyle(document.documentElement)
                        .getPropertyValue('--nav-h'), 10) || 0;
  lenis = new Lenis({
    duration: 1.05,
    easing: t => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
    smoothWheel: true,
    syncTouch: false,        // 터치는 네이티브로 남김 — 부드럽게 하면 폰에서 느리게 느껴짐
    autoRaf: true,           // Lenis가 자체 RAF 루프를 실행하므로 수동 티커 불필요
    anchors: { offset: -(navH + 10) }   // 페이지 내 링크가 고정 헤더를 피함
  });
} else {
  // Lenis 없음 — 브라우저에 자체 동작을 되돌려줌
  document.documentElement.style.scrollBehavior = reduced ? 'auto' : 'smooth';
}

필수 CSS

html { /* NO scroll-behavior: smooth — Lenis와 충돌함 */ }

html.lenis, html.lenis body { height: auto; }
.lenis:not(.lenis-autoToggle).lenis-stopped { overflow: clip; }
.lenis.lenis-smooth [data-lenis-prevent] { overscroll-behavior: contain; }
.lenis.lenis-smooth iframe { pointer-events: none; }

html에 scroll-behavior: smooth가 있으면 안 됩니다. 유지하면 앵커 점프가 이중으로 애니메이션되어 부드러운 효과와 충돌합니다.

함정 1 — overflow: clip이 position: sticky를 죽임

이게 한 시간을 날리게 할 함정입니다.

lenis.stop()은 .lenis-stopped를 추가하고, 그 CSS는 <html>에 overflow: clip을 설정합니다. 이렇게 하면 스크롤포트가 제거되고, position: sticky가 붙을 곳이 없어집니다 — sticky 요소가 문서에서의 위치, 즉 페이지 상단으로 튕겨버립니다.

스크롤 1200에서 메뉴를 열면 sticky 헤더가 top: -1200에 렌더링됩니다. 화면 밖입니다. 닫기 버튼도 함께 사라집니다. 사용자는 "닫기 버튼이 사라졌어요"라고 보고합니다.

클래식한 body { position: fixed } 스크롤 잠금에서도 같은 이유로 동일한 현상이 발생합니다 — 스크롤포트가 없기 때문입니다.

수정: 스크롤이 잠겨 있는 동안 헤더를 뷰포트에 고정합니다.

html.menu-open .nav-wrap { position: fixed; top: 0; left: 0; right: 0; }
document.documentElement.classList.toggle('menu-open', open);

오버레이가 아직 불투명한 상태에서 클래스를 전환하여 sticky→fixed 레이아웃 변경이 눈에 띄지 않도록 합니다. Lenis 경로와 축소 모션 경로 모두에 적용합니다.

0이 아닌 스크롤 오프셋에서 오버레이를 테스트하세요. 스크롤 0에서는 깨진 sticky 헤더가 정상 헤더와 픽셀 단위로 동일하므로 버그가 완전히 숨겨집니다. 0, ~1200, 그리고 페이지 깊숙한 곳에서 확인하세요.

함정 2 — 두 개의 스크롤 잠금을 쌓지 마세요

본문을 고정하고 동시에 lenis.stop()을 호출하면 서로 충돌합니다: position: fixed가 본문에 적용되면 페이지 높이가 줄어들고, Lenis가 0으로 재동기화되며, 오버레이를 닫으면 사용자가 페이지 상단으로 떨어집니다.

Lenis를 사용하면 stop()과 자체 overflow: clip이 본문을 건드리지 않고 페이지를 고정합니다 — 따라서 스크롤 위치가 절대 손실되지 않고 복원할 것도 없습니다:

if (lenis) {
  open ? lenis.stop() : lenis.start();
} else if (open) {                       // 축소 모션 경로만
  scrollY = window.scrollY;
  document.body.style.position = 'fixed';
  document.body.style.top = -scrollY + 'px';
  document.body.style.width = '100%';
} else if (document.body.style.position === 'fixed') {
  document.body.style.position = '';
  document.body.style.top = '';
  document.body.style.width = '';
  window.scrollTo(0, scrollY);
}

확인: 1200까지 스크롤 → 열기 → 휠 → 닫기. 모든 단계에서 위치가 1200을 읽어야 하며, 그 후에 스크롤이 다시 작동해야 합니다.

함정 3 — 앵커 링크

Lenis가 스크롤을 소유하므로 일반 href="#id" 점프는 잘못 보입니다. 고정 헤더 높이와 같은 음수 오프셋을 가진 내장 anchors 옵션을 사용하거나, 클릭을 lenis.scrollTo(target, { offset: -navH })를 통해 수동으로 라우팅하세요.

도착 위치를 확인하세요: 섹션 상단이 헤더 하단 가장자리 아래에 위치해야 하며, 그 아래에 숨겨지면 안 됩니다.

함정 4 — 일반적으로 Lenis가 버벅거림의 원인이 아닙니다

Lenis를 추가한 후 스크롤이 나빠졌을 때, 먼저 측정하고 비난하기 전에 확인하세요. 한 빌드에서는 네이티브 스크롤이 실제로 더 나빴습니다 (13% 드롭된 프레임 vs 9%) — Lenis는 괜찮았고 실제 비용은 다른 곳에 있었습니다:

  • 고정된 전체 뷰포트 mix-blend-mode 오버레이 (필름 그레인): 블렌드 모드만 제거하여 34% → 3% 드롭된 프레임
  • sticky 요소의 backdrop-filter: 스크롤의 모든 프레임마다 화면에 표시됨
  • 일반적으로 큰 요소의 backdrop-filter — 프레임마다 다시 샘플링함

프레임 타이밍 측정 도구

// 페이지 내부
window.__f = []; let l = performance.now();
const t = n => { window.__f.push(n - l); l = n; requestAnimationFrame(t); };
requestAnimationFrame(t);

의심되는 구역에서 실제 휠 이벤트로 구동한 후, 평균, p95, 33ms를 초과하는 프레임 비율을 보고하세요. 한 번에 하나의 효과를 add_style_tag로 비활성화하여 이분법으로 찾습니다. 건강한 수치는 ~16.7ms 평균과 0% 긴 프레임입니다. 약 10% 이상의 긴 프레임은 눈에 띄는 끊김입니다.

체크리스트

  • html에서 scroll-behavior: smooth 제거됨
  • Lenis CSS 블록 추가됨
  • autoRaf: true (또는 수동 RAF 루프 — 둘 다는 안 됨)
  • anchors 오프셋이 고정 헤더 높이와 일치함
  • syncTouch: false로 폰이 네이티브 모멘텀을 유지함
  • 오버레이가 스크롤을 잠그는 동안 sticky 헤더가 고정됨
  • 하나의 스크롤 잠금 메커니즘만 활성화됨
  • 0이 아닌 스크롤 오프셋에서 오버레이 테스트됨
  • prefers-reduced-motion이 Lenis를 건너뛰고 네이티브 동작을 복원함
  • 열기 → 닫기 과정에서 스크롤 위치 유지됨
  • 프레임 타이밍이 가정되지 않고 측정됨

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

brainzcode/premium-landing

Add a studio or agency build credit to a website footer — "Site by <Studio>" linking to the studio's site. Use when finishing or shipping a site, adding a footer, or when asked for an agency credit, build credit, designed-by line, or attribution. Covers wording, placement opposite the client's copyright, markup for each stack, styling from the host site's tokens, and the sitewide-footer-link SEO footprint when the same credit runs across many client sites.

brainzcode/premium-landing

Build a complete premium landing page, either replicated from a reference screenshot/URL or designed from a written brief, in HTML, React, Next.js or Astro. Use when asked to build, design, replicate or clone a landing page, marketing page, or one-page site; when handed a design screenshot or Figma/Pinterest reference to turn into code; or when a landing page needs a full premium pass. Covers design tokens, section patterns, the layout traps that silently break grids and marquees, and screenshot-based responsive verification from 320px to 1920px.

brainzcode/premium-landing

Build true Apple-style liquid glass in the browser — real refraction via SVG displacement maps, chromatic dispersion, specular edges. Use when asked for liquid glass, glassmorphism, frosted/glass cards, glass navbars, or when a blur-based "glass" effect looks flat. Includes the performance trap that makes backdrop-filter stutter on scroll and the contrast trap that makes text unreadable on glass.

brainzcode/premium-landing

Build a premium mobile nav — a hamburger button that morphs into a close X, a full-screen overlay panel with staggered link reveal, scroll lock, focus trap, and reduced-motion handling. Use when asked for a mobile menu, hamburger/burger button, nav drawer, off-canvas menu, or when a menu loses scroll position, still scrolls behind on iOS, leaks Tab focus to the page underneath, or the close button stops responding. Includes the z-index trap that swallows the close button and the iOS rubber-band trap.

brainzcode/premium-landing

Rebuild a design accurately from a supplied reference — a screenshot, PDF page, mockup or live URL — by measuring it numerically instead of eyeballing it. Use when asked to replicate, clone, match or rebuild a design "exactly", "1 to 1" or "with no mistakes", or when a build drifts from its reference. Covers extracting the true content box from a padded screenshot, deriving element positions as percentages, solving object-fit framing, and knowing when a reference cannot be matched.

brainzcode/premium-landing

Ship link previews and favicons that actually work - Open Graph and Twitter card tags, a correctly framed 1200x630 share image, and a full favicon set (SVG, ICO, apple-touch, maskable manifest icons). Use when asked for social sharing, OG image, open graph, twitter card, link preview, share image, favicon, app icon, apple touch icon, or web manifest. Also use when a shared link previews blank, shows the wrong image, or a favicon will not appear. Includes the absolute-URL trap that silently blanks every preview and the font trap that breaks SVG favicons on other machines.

brainzcode/premium-landing

Source free, licence-clear photography for a site from Unsplash — searching by mood rather than noun, sizing and cropping for the slot, honouring the API's hotlink and download-tracking requirements, and writing real alt text. Use when a page needs a hero image, section photography, avatars or card art and none was supplied; when placeholder greys need replacing with real imagery; or when asked to find, pick or swap photos for a design.

관련 스킬