Communitygithub.com

brainzcode/premium-landing

正確地為網站加入 Lenis 平滑滾動 — 設定、固定式標頭的偏移、模態框與選單的滾動鎖定、以及減少動畫效果的處理。當被要求使用 smooth scroll、Lenis、動量/緩動滾動,或當平滑滾動破壞了固定式標頭、模態框鎖定或錨點連結時使用。包含那個只在非零滾動時才會出現的 sticky 定位陷阱。

premium-landing 是什麼?

這個技能提供了一套完整且經過實戰驗證的 Lenis 平滑滾動整合方案,專為 premium-landing 專案而設計。它不僅涵蓋了基本的設定步驟(如使用 IIFE 版本、設定 `autoRaf: true` 和 `anchors` 偏移量),更深入揭露了三個最常見的陷阱:首先,`lenis.stop()` 產生的 `overflow: clip` 會破壞 `position: sticky`,導致固定式標頭在選單開啟時消失;其次,同時使用 `lenis.stop()` 和 `position: fixed` 兩種滾動鎖定機制會造成衝突;最後,Lenis 錨點連結需要正確的偏移量設定才能避開固定式標頭。它支援所有的主流瀏覽器,並自帶一套偵測和修復這些陷阱的 CSS 與 JavaScript 程式碼。此外,它也考慮了無障礙性,能辨識 `prefers-reduced-motion` 媒體查詢,在用戶偏好減少動畫時自動停用 Lenis,並回退到瀏覽器原生的滾動行為。技能最後還提供了一個幀計時測試工具,幫助開發者量化評估效能,避免將其他效能瓶頸(如 `mix-blend-mode` 或 `backdrop-filter`)誤歸咎於 Lenis。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/brainzcode/premium-landing/tree/HEAD/plugins/premium-landing/skills/lenis-smooth-scroll

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Lenis 平滑滾動

Lenis 會攔截滾輪輸入,並對原生的滾動位置進行緩動處理。因此,position: sticky、IntersectionObserver 和 window.scrollY 都能繼續正常運作——這也是為何它是正確的選擇。問題往往來自於與它衝突的事物,而非 Lenis 本身。

設定

建議使用供應商 (Vendor) 方式引入,而非直接連結 CDN,這樣網站可以保持獨立,並且能從 file:// 協定下正常運作:

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

dist/lenis.min.js 是 IIFE 建置,會暴露 globalThis.Lenis——在一般的 <script> 標籤中運作良好。(dist/lenis.mjs 是 ESM 格式,不能在一般的 script 標籤中使用。)請在你自己的 script 之前載入它。

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 循環;無需手動 ticker
    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 class,其 CSS 設定 <html> 的 overflow: clip。此舉會移除滾動容器,而**position: sticky 就沒有東西可以附著了**——sticky 元素會跳回它在文件流中的位置,也就是頁面頂部。

在滾動到 1200px 時開啟選單,你的 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);

在覆蓋層仍然不透明的時候切換 class,讓 sticky → fixed 的版面變化不易察覺。在 Lenis 路徑和減少動畫效果的路徑上都套用這個 class。

在非零滾動偏移下測試覆蓋層。 在滾動為 0 時,損壞的 sticky 標頭與正常的標頭看起來一模一樣,所以這個 bug 會完全隱藏。請在 0、~1200 以及頁面深處進行驗證。

陷阱 2 — 不要疊加兩個滾動鎖定

同時固定 body 和呼叫 lenis.stop() 會讓它們互相衝突:body 上的 position: fixed 會使頁面高度崩潰,Lenis 會重新同步到 0,關閉覆蓋層後會把使用者丟回頁面頂部。

使用 Lenis 時,stop() 加上它自己的 overflow: clip 可以在不觸碰 body 的情況下鎖定頁面——因此滾動位置永遠不會遺失,也不需要還原:

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 選項,並設定一個等於你 sticky 標頭高度的負偏移量,或者手動透過 lenis.scrollTo(target, { offset: -navH }) 來路由點擊事件。

檢查著陸位置:章節頂部必須位於標頭底部邊緣的下方,而不是被它遮住。

陷阱 4 — Lenis 通常不是卡頓的原因

當加入 Lenis 後感覺滾動不順暢時,先測量再責怪它。在某個專案中,原生滾動實際上測量結果更差(掉幀 13% 對比 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);

使用真實的滾輪事件在可疑的區段上驅動它,然後回報平均值 (mean)、第 95 百分位數 (p95) 和超過 33ms 的幀數百分比。使用 add_style_tag 一次停用一個效果來進行二分法測試。健康的數值大約是平均值 ~16.7ms 且 0% 的長幀;超過 ~10% 的長幀就是肉眼可見的卡頓。

檢查清單

  • scroll-behavior: smooth 已從 html 移除
  • Lenis CSS 區塊已加入
  • 已設定 autoRaf: true(或手動的 RAF 循環——但不能兩者並存)
  • anchors 偏移量與 sticky 標頭高度相符
  • syncTouch: false 以讓手機保留原生動量
  • sticky 標頭在覆蓋層鎖定滾動時已固定
  • 只有一個滾動鎖定機制在運作
  • 覆蓋層已在非零的滾動偏移下測試過
  • 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.

相關技能