Communitygithub.com

brainzcode/premium-landing

为网站正确添加 Lenis 平滑滚动——包括设置、粘性标题的锚点偏移、模态框和菜单的滚动锁定以及减少运动处理。当被要求实现平滑滚动、Lenis、动量/缓冲滚动,或者平滑滚动导致粘性标题、模态框锁定或锚点链接出现问题时使用。

premium-landing 是什么?

该技能(Skill)旨在帮助开发者正确集成并配置 Lenis 滚动库,避免常见的集成陷阱。它详细说明了如何通过 `curl` 进行本地化安装而非使用 CDN,并提供了完整的初始化代码片段,包括对 `prefers-reduced-motion` 媒体查询的支持。 其核心价值在于预防并解决三个易被忽视的‘陷阱’:第一,当 Lenis 停止滚动(如打开菜单)时,其 `overflow: clip` CSS 属性会破坏 `position: sticky` 效果,导致粘性标题消失;技能提供了通过 CSS 固定定位修复的完整方案。第二,避免同时使用 `lenis.stop()` 和传统的 `body { position: fixed }` 滚动锁定,防止滚动位置重置。第三,正确处理锚点链接,利用 Lenis 内置的 `anchors` 选项和负偏移量,确保页面内跳转能正确避开粘性标题。 技能同时提供了一个用于诊断滚动性能的帧计时方案,帮助开发者区分 Lenis 引入的卡顿与页面其他(如 `backdrop-filter`、`mix-blend-mode`)的渲染开销。它适用于任何使用 Lenis 的 Web 项目,最终通过一份详尽的部署清单来验证所有关键点,确保集成万无一失。

兼容平台~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 拦截滚轮输入并缓动原生滚动位置。粘性定位、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 标签中不能工作。) 在你的脚本之前加载它。

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 { /* 没有 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 就没有东西可以粘附了**——粘性元素会弹回它们在文档中的位置,即页面顶部。

在滚动到 1200px 时打开一个菜单,你的粘性标题渲染在 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);

在遮罩层仍不透明时切换类,以便粘性→固定布局的变化不可见。在 Lenis 路径和减少运动路径上都应用此修复。

在非零滚动偏移处测试遮罩层。 在滚动 0 处,有问题的粘性标题与正常工作的粘性标题像素级一致,所以 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 选项,并设置等于粘性标题高度的负偏移量,或者通过 lenis.scrollTo(target, { offset: -navH }) 手动路由点击。

检查目标位置:区域顶部必须位于标题底边处或其下方,而不是被其遮盖。

陷阱 4 —— Lenis 通常不是你的卡顿来源

添加 Lenis 后感觉滚动变差时,先测量再归咎于它。在某个版本中,原生滚动实际上测量结果更差(13% 丢帧 vs 9%)——Lenis 没问题,真正的开销在别处:

  • 一个固定的全视口 mix-blend-mode 叠加层(胶片颗粒):仅通过去除混合模式,丢帧率从 34% 降到了 3%
  • 粘性元素上的 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 以保持手机的原生动量
  • 在遮罩层锁定滚动期间,粘性标题已固定
  • 只有一个滚动锁定机制在起作用
  • 已在非零滚动偏移处测试遮罩层
  • 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.

相关技能