frontend-atlas

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Atlas

The implementation layer for premium front ends. Sibling skills judge whether and what (

taste-skill

anti-slop rules,

impeccable

critique/audit/polish,

soft-skill

minimalist-skill

brutalist-skill

). This skill knows how: verified, copy-pasteable recipes for the motion, scroll, type, hover, transition, background, shader and component effects that ship on the best sites in 2026, plus the judgment to pick the right one and tune it until it feels inevitable.

Verified 2026-09-27 against: gsap 3.15 (every plugin free, new SplitText), @gsap/react 2.1, motion 13.4 (

motion/react

), lenis 1.3 (

lenis/react

), three r186, @react-three/fiber 9.8, drei 10.7, animejs 4.5, tailwindcss 4.3, next 16.3, react 19.3. All TS/TSX recipes type-check against those packages; the signature recipes were run in Chromium and audited with the scripts below. Project rules beat this file (a project that is "GSAP only" stays GSAP only).

优质前端的实现层。配套 skill 负责判断是否应该做以及做什么 （

taste-skill

反粗制滥造规则、

impeccable

评审/审计/打磨、

soft-skill

、

minimalist-skill

、

brutalist-skill

）。本 skill 知道如何实现：提供经过验证、可直接复制粘贴的配方，涵盖 2026 年最优秀网站所采用的动效、滚动、字体、悬停、过渡、背景、shader 和组件效果，同时具备判断应选用哪种效果并持续调优，直到最终效果显得自然且水到渠成。

已于 2026-09-27 针对以下版本完成验证：gsap 3.15（所有插件均已免费，新版 SplitText）、@gsap/react 2.1、 motion 13.4（

motion/react

）、lenis 1.3（

lenis/react

）、three r186、@react-three/fiber 9.8、 drei 10.7、animejs 4.5、tailwindcss 4.3、next 16.3、react 19.3。所有 TS/TSX 配方均已针对上述包通过类型检查；代表性配方已在 Chromium 中运行，并使用下方脚本完成审计。项目规则优先于本文件（采用“仅 GSAP”的项目就始终只使用 GSAP）。

How to use

使用方法

Write the Design Read (below) before any code. Five lines, no more.
Find the effect: the shortlist below, or search
```
references/INDEX.md
```
(every recipe with its anchor).
Open ONLY the section you need. Reference files are long (700-3000 lines); never load them whole unless you are choosing between many options (then read that file's Decision guide table first).
Copy the recipe, then tune the values under Tune to the chosen motion personality.
Verify in a real browser with
```
scripts/motion-audit.mjs
```
(see Verification). Not watched = not done.

编写任何代码前，先撰写 Design Read（设计解读，见下文）。最多五行。
查找所需效果：使用下方短列表，或搜索
```
references/INDEX.md
```
（其中包含每个配方及其锚点）。
只打开所需章节。参考文件很长（700-3000 行）；除非需要在多个选项之间做选择，否则切勿整体加载（需要选择时，先阅读该文件的 Decision guide 表格）。
复制配方，然后根据所选动效人格调整 Tune 下的参数。
使用
```
scripts/motion-audit.mjs
```
在真实浏览器中验证（参见“验证协议”）。未实际观看就等于未完成。

Reference map

参考文件索引

File	Open when
`references/INDEX.md`	Looking up any effect by name (474 entries, grouped by file).
`references/motion-principles.md`	Easings, durations, springs, stagger, choreography, 7 motion personality presets. Read before any animation-heavy build.
`references/scroll-gsap.md`	Lenis smooth scroll, ScrollTrigger reveals, pinning, scrub, horizontal galleries, stacked cards, SplitText on scroll, image sequences, video scrub, Flip, Observer slides, refresh discipline.
`references/scroll-css-native.md`	Zero-JS scroll effects: `animation-timeline: scroll()/view()` , progress bars, reveals, parallax, CSS carousels, `scroll-state()` queries, fallbacks, native-vs-GSAP split.
`references/css-modern.md`	`@starting-style` , dialog/popover, anchor positioning, `interpolate-size` , `@property` , container/style queries, `:has()` , OKLCH, `text-wrap` , `sibling-index()` , `corner-shape` , customizable select, Tailwind v4 mapping, support matrix.
`references/text-effects.md`	Split-text reveals, scramble, typewriter, rotating words, text roll, variable-font play, marquees, counters, gradient/shimmer text, text on path, fitted wordmarks, kinetic intros.
`references/typography.md`	Type scale, fluid type, tracking/leading, OpenType, 27 font pairings with sources and licences, loading without CLS, editorial type layouts.
`references/interactions.md`	Custom cursor, magnetic, hover reveals, image trail, button/link hovers, tilt, spotlight cards, tabs indicator, accordion, popovers, toasts, drawers, dock, drag, micro-feedback, feel-tuning table.
`references/page-transitions.md`	View Transitions (same-doc, cross-doc), React `<ViewTransition>` in Next 16, shared elements, GSAP overlay transitions, Swup/Barba/Astro, preloaders, intro gating, fullscreen menus, route hygiene.
`references/backgrounds-svg-canvas.md`	Mesh/aurora/grain/grid backgrounds, conic borders, SVG draw/morph/goo/displacement, canvas particles/dot grids/flow fields, Lottie vs Rive.
`references/webgl-shaders-3d.md`	WebGL loading shell, shader library (GLSL), image distortion, DOM-to-WebGL galleries, fluid cursor, particles, R3F glass hero, globes, post-processing, Paper Shaders, WebGPU/TSL.
`references/component-recipes.md`	67 named components (21st.dev, Aceternity, Magic UI, React Bits, Motion Primitives, Cult UI...): install commands, self-owned code, overuse scores, section combos.
`references/color-surfaces.md`	OKLCH ramps, semantic tokens, contrast (WCAG/APCA), dark mode, gradients, glass and liquid glass, shadows, borders, radius, image treatment.
`references/layout-composition.md`	Breakout grid, 12-col/subgrid, fluid space, 10 hero skeletons, bento, section patterns, sticky/overlap layouts, navigation, responsive strategy.
`references/aesthetic-directions.md`	Choosing or executing one of 30 visual directions, each with tokens, fonts, motion signature, real reference sites, AI-slop tells.
`references/libraries.md`	Choosing/setting up any of 37 libraries: size, install, SSR caveats, status, recommended stacks per project type.
`references/performance-a11y.md`	Before shipping anything animated: property cost, jank debugging, pausing offscreen work, CLS from pins, reduced motion done right, WCAG motion criteria, QA checklist.
`references/inspiration-sources.md`	Finding references, components, fonts, icons, assets, tools; reverse-engineering an effect seen on a live site.

文件	何时打开
`references/INDEX.md`	按名称查找任何效果（474 个条目，按文件分组）。
`references/motion-principles.md`	缓动、时长、弹簧、stagger、编排以及 7 种动效人格预设。进行任何动画密集型构建前应先阅读。
`references/scroll-gsap.md`	Lenis 平滑滚动、ScrollTrigger 显现、pinning、scrub、横向画廊、堆叠卡片、随滚动 SplitText、图像序列、视频 scrub、Flip、Observer 幻灯片、refresh 纪律。
`references/scroll-css-native.md`	纯 JS 滚动效果： `animation-timeline: scroll()/view()` 、进度条、显现、视差、CSS 轮播、 `scroll-state()` 查询、回退方案，以及原生 CSS 与 GSAP 的分工。
`references/css-modern.md`	`@starting-style` 、dialog/popover、锚点定位、 `interpolate-size` 、 `@property` 、容器/样式查询、 `:has()` 、OKLCH、 `text-wrap` 、 `sibling-index()` 、 `corner-shape` 、可定制 select、Tailwind v4 映射、兼容性矩阵。
`references/text-effects.md`	文字拆分显现、打乱、打字机、轮换词语、文字滚动、可变字体玩法、marquee、计数器、渐变/微光文字、路径文字、自适应字标、动态标题。
`references/typography.md`	字号体系、流式字体、字距/行距、OpenType、27 组字体搭配及其来源和许可、无 CLS 加载、编辑型排版布局。
`references/interactions.md`	自定义光标、磁吸、悬停显现、图像拖尾、按钮/链接悬停、倾斜、聚光卡片、标签指示器、手风琴、popover、toast、抽屉、dock、拖拽、微反馈、质感调优表。
`references/page-transitions.md`	View Transitions（同文档、跨文档）、Next 16 中的 React `<ViewTransition>` 、共享元素、GSAP 遮罩过渡、Swup/Barba/Astro、预加载器、首次展示门控、全屏菜单、路由清理。
`references/backgrounds-svg-canvas.md`	网格/极光/颗粒背景、锥形边框、SVG 描边/变形/ goo /位移、canvas 粒子/点阵/流场、Lottie 与 Rive 对比。
`references/webgl-shaders-3d.md`	WebGL 加载外壳、shader 库（GLSL）、图像扭曲、DOM 到 WebGL 画廊、流体光标、粒子、R3F 玻璃首屏、地球、后处理、Paper Shaders、WebGPU/TSL。
`references/component-recipes.md`	67 个具名组件（21st.dev、Aceternity、Magic UI、React Bits、Motion Primitives、Cult UI……）：安装命令、自主维护代码、过度使用评分、区块组合。
`references/color-surfaces.md`	OKLCH 色阶、语义 token、对比度（WCAG/APCA）、暗色模式、渐变、玻璃与液态玻璃、阴影、边框、圆角、图像处理。
`references/layout-composition.md`	突破式网格、12 栏/subgrid、流式间距、10 种首屏骨架、Bento、区块模式、粘性/重叠布局、导航、响应式策略。
`references/aesthetic-directions.md`	选择或执行 30 种视觉方向之一，每种均包含 token、字体、动效特征、真实参考站点和 AI 粗制滥造特征。
`references/libraries.md`	选择/设置 37 个库：体积、安装、SSR 注意事项、维护状态以及按项目类型推荐的组合。
`references/performance-a11y.md`	发布任何动画前：属性开销、卡顿调试、暂停离屏工作、pin 引起的 CLS、正确处理 reduced motion、WCAG 动效标准、QA 清单。
`references/inspiration-sources.md`	查找参考、组件、字体、图标、素材和工具；逆向分析在线站点中看到的某种效果。

Effect shortlist (most requested)

常用效果短列表

Effect	Where
Smooth scroll (Lenis on the GSAP ticker)	`scroll-gsap.md#1-setup-and-lenis-sync`
Reveal on scroll, zero JS	`scroll-css-native.md#5-reveal-on-enter-fade--slide--clip--blur`
Staggered card reveal	`scroll-gsap.md#3-batch-reveal-on-enter`
Headline line-mask reveal	`text-effects.md#1-line-mask-reveal-splittext-mask-lines`
Kinetic hero intro timeline	`text-effects.md#27-kinetic-headline-intro-sequence` , `motion-principles.md#9-orchestrating-a-hero-intro-gsap-motion-css`
Pinned hero zoom / clip expand	`scroll-gsap.md#6-pinned-hero-zoom-and-clip-expansion`
Pinned multi-step story	`scroll-gsap.md#7-pinned-multi-step-timeline-with-label-snap`
Horizontal scroll gallery	`scroll-gsap.md#8-horizontal-scroll-gallery` , CSS: `scroll-css-native.md#10-horizontal-scroll-section-sticky--view-timeline`
Stacked cards	`scroll-gsap.md#9-stacked-cards` , CSS: `scroll-css-native.md#11-stacking-cards`
Sticky split scrollytelling	`scroll-gsap.md#10-sticky-split-layout`
Parallax	`scroll-css-native.md#6-parallax-layers` , `scroll-gsap.md#11-parallax-layers`
Words light up as you scroll	`scroll-gsap.md#5-text-fills-as-you-scroll` , `scroll-css-native.md#12-text-fill--word-by-word-highlight-on-scroll`
Scroll-velocity skew / marquee	`scroll-gsap.md#13-scroll-velocity-skew-and-marquee`
Apple image sequence / video scrub	`scroll-gsap.md#17-scroll-scrubbed-video-and-image-sequence`
Full-screen slide sections	`scroll-gsap.md#15-observer-full-screen-slides`
Reading progress, sticky header shrink	`scroll-css-native.md#4-reading-progress-bar-page-and-per-article` , `#8-sticky-header-compact--frosted-on-scroll`
Scramble / decrypt text	`text-effects.md#6-scramble--decode--decrypted-text`
Rotating words, text roll on hover	`text-effects.md#8-rotating-words-height-masked-slot` , `#9-text-roll-on-hover`
Cursor-proximity variable type	`text-effects.md#12-cursor-proximity-variable-type`
Giant fitted footer wordmark	`text-effects.md#14-fit-text-to-width-giant-wordmark-footer`
Marquee (CSS / velocity)	`text-effects.md#22-css-only-infinite-marquee` , `#23-velocity-reactive-marquee`
Number counters	`text-effects.md#24-number-animation`
Font pairing	`typography.md#9-font-pairing-playbook-2026`
Custom cursor, magnetic buttons	`interactions.md#1-custom-cursor-with-trailing-ring` , `#2-magnetic-elements`
Hover image reveal list, image trail	`interactions.md#3-hover-image-reveal-and-image-trail`
Button hover/press system	`interactions.md#4-button-hover-and-press-system`
Spotlight glow card grid	`interactions.md#7-spotlight-glow-card-grid`
Tabs sliding indicator	`interactions.md#8-tabs-indicator-and-nav-hover-highlight`
Micro kit (hold, copy, like, switch)	`interactions.md#13-micro-interaction-kit`
Route transitions in Next 16 (native)	`page-transitions.md#4-react-193-viewtransition--next-16-routes`
Shared element list -> detail	`page-transitions.md#5-shared-element-list-detail-3-ways`
Curtain / overlay route transition	`page-transitions.md#7-gsap-overlay-route-transitions-the-awwwards-default`
Theme toggle circle reveal	`page-transitions.md#10-circle-reveal-from-the-click-point-theme-toggle--routes`
Preloader + gated hero intro	`page-transitions.md#18-counter-0-100--curtain-skipped-on-repeat-visits` , `#19-intro-gate-store-hero-waits-for-preloader`
Fullscreen menu, hide-on-scroll nav	`page-transitions.md#23-fullscreen-menu-overlay` , `#24-nav-hide-on-scroll-down--show-on-up`
Dialog / popover enter-exit in CSS	`css-modern.md#1-enterexit-from-displaynone-starting-style--allow-discrete`
Mesh gradient, aurora, grain	`backgrounds-svg-canvas.md#1-layered-radial-mesh-gradient` , `#2-aurora-blobs` , `#3-grain-noise-overlay`
Border beam / rotating conic border	`backgrounds-svg-canvas.md#8-border-beam-along-the-edge` , `#7-animated-conic-border`
SVG line drawing, morphing	`backgrounds-svg-canvas.md#14-stroke-drawing` , `#15-shape-morphing`
Interactive dot grid, constellation	`backgrounds-svg-canvas.md#29-interactive-spring-dot-grid` , `#27-constellation-network`
Shader gradient background	`webgl-shaders-3d.md#1-gatekeeping-and-loading-shell-next-16` + `#3-shader-library-glsl`
WebGL image hover / gallery	`webgl-shaders-3d.md#4-image-effects-and-dom-to-webgl`
Fluid cursor, particle morph	`webgl-shaders-3d.md#5-cursor-fluid-simulation` , `#6-particles-morphing-points-mouse-repulsion-gpgpu`
3D glass hero (R3F)	`webgl-shaders-3d.md#7-r3f-hero-scene-glass-environment-gltf-scroll-camera-3d-text`
Globe	`component-recipes.md#14-globe-cobe` , `webgl-shaders-3d.md#8-globes-cobe-three-globe-custom`
Bento grid	`layout-composition.md#7-bento-grids-done-right` , `component-recipes.md#43-bento-grid`
Proven section combos	`component-recipes.md#recipe-combos`
Hero layouts	`layout-composition.md#6-hero-paradigms-10-skeletons`
Palette from one brand color	`color-surfaces.md#2-12-step-ramp-generator-ts-gamut-aware`
Dark mode, no theme flash	`color-surfaces.md#10-dark-mode-done-right` , `#11-theme-switch-without-fouc`
Glass / liquid glass	`color-surfaces.md#15-glassmorphism-done-right` , `#16-liquid-glass-approximations-tiered`
Choosing a visual direction	`aesthetic-directions.md#decision-guide---choosing-a-direction-from-a-brief`

效果	位置
平滑滚动（Lenis 接入 GSAP ticker）	`scroll-gsap.md#1-setup-and-lenis-sync`
滚动显现，零 JS	`scroll-css-native.md#5-reveal-on-enter-fade--slide--clip--blur`
卡片错峰显现	`scroll-gsap.md#3-batch-reveal-on-enter`
标题逐行遮罩显现	`text-effects.md#1-line-mask-reveal-splittext-mask-lines`
动态首屏标题时间线	`text-effects.md#27-kinetic-headline-intro-sequence` 、 `motion-principles.md#9-orchestrating-a-hero-intro-gsap-motion-css`
固定首屏缩放/裁剪扩展	`scroll-gsap.md#6-pinned-hero-zoom-and-clip-expansion`
固定式多步骤叙事	`scroll-gsap.md#7-pinned-multi-step-timeline-with-label-snap`
横向滚动画廊	`scroll-gsap.md#8-horizontal-scroll-gallery` ，CSS： `scroll-css-native.md#10-horizontal-scroll-section-sticky--view-timeline`
堆叠卡片	`scroll-gsap.md#9-stacked-cards` ，CSS： `scroll-css-native.md#11-stacking-cards`
粘性分栏滚动叙事	`scroll-gsap.md#10-sticky-split-layout`
视差	`scroll-css-native.md#6-parallax-layers` 、 `scroll-gsap.md#11-parallax-layers`
文字随滚动逐词点亮	`scroll-gsap.md#5-text-fills-as-you-scroll` 、 `scroll-css-native.md#12-text-fill--word-by-word-highlight-on-scroll`
滚动速度倾斜 / marquee	`scroll-gsap.md#13-scroll-velocity-skew-and-marquee`
Apple 风格图像序列/视频 scrub	`scroll-gsap.md#17-scroll-scrubbed-video-and-image-sequence`
全屏幻灯片区块	`scroll-gsap.md#15-observer-full-screen-slides`
阅读进度、粘性页头收缩	`scroll-css-native.md#4-reading-progress-bar-page-and-article` 、 `#8-sticky-header-compact--frosted-on-scroll`
文字打乱/解密	`text-effects.md#6-scramble--decode--decrypted-text`
轮换词语、悬停文字滚动	`text-effects.md#8-rotating-words-height-masked-slot` 、 `#9-text-roll-on-hover`
随光标距离变化的可变字体	`text-effects.md#12-cursor-proximity-variable-type`
超大宽度自适应页脚字标	`text-effects.md#14-fit-text-to-width-giant-wordmark-footer`
Marquee（CSS/速度响应式）	`text-effects.md#22-css-only-infinite-marquee` 、 `#23-velocity-reactive-marquee`
数字计数器	`text-effects.md#24-number-animation`
字体搭配	`typography.md#9-font-pairing-playbook-2026`
自定义光标、磁吸按钮	`interactions.md#1-custom-cursor-with-trailing-ring` 、 `#2-magnetic-elements`
悬停图像显现列表、图像拖尾	`interactions.md#3-hover-image-reveal-and-image-trail`
按钮悬停/按压系统	`interactions.md#4-button-hover-and-press-system`
聚光发光卡片网格	`interactions.md#7-spotlight-glow-card-grid`
标签滑动指示器	`interactions.md#8-tabs-indicator-and-nav-hover-highlight`
微交互套件（长按、复制、点赞、切换）	`interactions.md#13-micro-interaction-kit`
Next 16 原生路由过渡	`page-transitions.md#4-react-193-viewtransition--next-16-routes`
共享元素列表 -> 详情	`page-transitions.md#5-shared-element-list-detail-3-ways`
幕布/遮罩路由过渡	`page-transitions.md#7-gsap-overlay-route-transitions-the-awwwards-default`
主题切换圆形显现	`page-transitions.md#10-circle-reveal-from-the-click-point-theme-toggle--routes`
预加载器 + 首屏门控	`page-transitions.md#18-counter-0-100--curtain-skipped-on-repeat-visits` 、 `#19-intro-gate-store-hero-waits-for-preloader`
全屏菜单、滚动隐藏导航	`page-transitions.md#23-fullscreen-menu-overlay` 、 `#24-nav-hide-on-scroll-down--show-on-up`
CSS dialog/popover 进入与退出	`css-modern.md#1-enterexit-from-displaynone-starting-style--allow-discrete`
网格渐变、极光、颗粒	`backgrounds-svg-canvas.md#1-layered-radial-mesh-gradient` 、 `#2-aurora-blobs` 、 `#3-grain-noise-overlay`
边缘光束/旋转锥形边框	`backgrounds-svg-canvas.md#8-border-beam-along-the-edge` 、 `#7-animated-conic-border`
SVG 线条绘制、变形	`backgrounds-svg-canvas.md#14-stroke-drawing` 、 `#15-shape-morphing`
交互式点阵、星座网络	`backgrounds-svg-canvas.md#29-interactive-spring-dot-grid` 、 `#27-constellation-network`
Shader 渐变背景	`webgl-shaders-3d.md#1-gatekeeping-and-loading-shell-next-16` + `#3-shader-library-glsl`
WebGL 图像悬停/画廊	`webgl-shaders-3d.md#4-image-effects-and-dom-to-webgl`
流体光标、粒子变形	`webgl-shaders-3d.md#5-cursor-fluid-simulation` 、 `#6-particles-morphing-points-mouse-repulsion-gpgpu`
3D 玻璃首屏（R3F）	`webgl-shaders-3d.md#7-r3f-hero-scene-glass-environment-gltf-scroll-camera-3d-text`
地球	`component-recipes.md#14-globe-cobe` 、 `webgl-shaders-3d.md#8-globes-cobe-three-globe-custom`
Bento 网格	`layout-composition.md#7-bento-grids-done-right` 、 `component-recipes.md#43-bento-grid`
经过验证的区块组合	`component-recipes.md#recipe-combos`
首屏布局	`layout-composition.md#6-hero-paradigms-10-skeletons`
从单一品牌色生成调色板	`color-surfaces.md#2-12-step-ramp-generator-ts-gamut-aware`
暗色模式、无主题闪烁	`color-surfaces.md#10-dark-mode-done-right` 、 `#11-theme-switch-without-fouc`
玻璃/液态玻璃	`color-surfaces.md#15-glassmorphism-done-right` 、 `#16-liquid-glass-approximations-tiered`
选择视觉方向	`aesthetic-directions.md#decision-guide---choosing-a-direction-from-a-brief`

Design Read (always first)

Design Read（始终先做）

Direction:           <one entry from aesthetic-directions.md, or a named blend of two>
Motion personality:  <preset from motion-principles.md#21-motion-personality-presets>
Signature moment:    <the ONE effect a visitor will remember, and where it lives>
Supporting layer:    <one reveal system + hover/press/focus feedback + transitions>
Stack:               <CSS-native | Motion | GSAP+Lenis | +OGL/R3F> because <reason>

If the brief is vague ("make it premium"), infer from the product, audience and existing brand, state the read, and proceed. Ask only when two very different directions are equally plausible.

Direction:           <one entry from aesthetic-directions.md, or a named blend of two>
Motion personality:  <preset from motion-principles.md#21-motion-personality-presets>
Signature moment:    <the ONE effect a visitor will remember, and where it lives>
Supporting layer:    <one reveal system + hover/press/focus feedback + transitions>
Stack:               <CSS-native | Motion | GSAP+Lenis | +OGL/R3F> because <reason>

如果需求描述较为模糊（例如“让它更有高级感”），应根据产品、受众和现有品牌进行推断，陈述 Design Read 后继续执行。只有当两种截然不同的方向具有同等合理性时，才需要提问。

Choosing the stack

选择技术栈

Pick the lightest tool that can express the effect:

CSS only: hover/press/focus, popover/dialog enter-exit (
```
@starting-style
```
), accordions, reveal-on-enter and progress bars (scroll-driven animations, with a fallback), marquees, gradient/conic animations (
```
@property
```
). Zero JS, off the main thread.
Motion (
motion/react
): React app UI. Layout animations,
```
layoutId
```
shared elements, presence/exit, gestures and drag, springs, reorderable lists.
GSAP + ScrollTrigger + Lenis: scroll storytelling and timelines. Pinning, scrubbed multi-step sequences, horizontal sections, SplitText, Flip, DrawSVG/MorphSVG, intro sequences.
WebGL (OGL for 2D shader effects, R3F for scenes): only when the concept needs it. Always ship a static poster fallback through the loading shell (webgl recipe 1).

Motion and GSAP can live in one project for different jobs, never on the same element. One smooth-scroll instance, one RAF loop (drive Lenis from

gsap.ticker

when GSAP is present).

选择能够表达所需效果的最轻量工具：

仅 CSS：悬停/按压/聚焦、popover/dialog 进入与退出（
```
@starting-style
```
）、手风琴、进入时显现和进度条（滚动驱动动画，并提供回退方案）、marquee、渐变/锥形动画（
```
@property
```
）。零 JS，不占用主线程。
Motion（
motion/react
）：React 应用 UI。布局动画、
```
layoutId
```
共享元素、存在/退出、手势与拖拽、弹簧、可重排列表。
GSAP + ScrollTrigger + Lenis：滚动叙事和时间线。Pinning、scrub 多步骤序列、横向区块、SplitText、Flip、DrawSVG/MorphSVG、首次展示序列。
WebGL（2D shader 使用 OGL，场景使用 R3F）：仅在概念确实需要时使用。始终通过加载外壳提供静态海报回退方案（见 WebGL 配方 1）。

Motion 和 GSAP 可以用于同一项目中的不同任务，但绝不能作用于同一元素。只能存在一个平滑滚动实例和一个 RAF 循环（存在 GSAP 时，通过

gsap.ticker

驱动 Lenis）。

Platform facts that change the code (verified 2026-09-27)

会影响代码的平台事实（已于 2026-09-27 验证）

CSS scroll-driven animations: Chrome 115+, Safari 26+, Firefox only from 159 (scheduled 2026-10-27). Not Baseline: always
```
@supports (animation-timeline: view())
```
+ a fallback.
View Transitions: same-document in all engines (Firefox 144+), cross-document not in Firefox. React 19.3 stable exports
```
<ViewTransition>
```
/
```
addTransitionType
```
; Next 16.3 needs no flag.
Default GSAP
pin: true
causes CLS: measured 0.75 at pin + 1.0 at unpin per 100vh section in Chromium (scroll is not an excluding input). CSS
```
position: sticky
```
+ scrub and
```
pinType: "transform"
```
both measured 0. Prefer sticky tracks where the layout allows.
ScrollTriggers created out of page order (lazy sections, a
```
useLenis()
```
value in useGSAP
```
dependencies
```
) fire early by the pin length. Higher
```
refreshPriority
```
refreshes first, and any
```
refreshPriority
```
enables auto-sorting by page position. (The official gsap-scrolltrigger skill states this backwards; the source is authoritative.)
Chromium-only today:
```
interpolate-size
```
,
```
corner-shape
```
, CSS carousels (
```
::scroll-marker
```
),
```
scroll-state()
```
queries,
```
if()
```
,
```
@function
```
. Use them as progressive enhancement only.
API changes that break older snippets: cobe 2 has no
```
onRender
```
(drive
```
globe.update()
```
from your own rAF); drei 10
```
PresentationControls
```
takes
```
damping
```
, not
```
config
```
;
```
THREE.Clock
```
is deprecated (r183+); Next 16
```
Image
```
uses
```
preload
```
instead of
```
priority
```
; Motion's
```
AnimateView
```
imports from
```
motion/react-animate-view
```
; tsParticles v4 uses
```
ParticlesProvider
```
.
Inline
```
style={{ position: ... }}
```
on a wrapper overrides a caller's
```
absolute inset-0
```
class and collapses it to 0 px: keep positioning in classes for any component that accepts
```
className
```
.

CSS 滚动驱动动画：Chrome 115+、Safari 26+、Firefox 仅从 159 开始支持（计划于 2026-10-27 发布）。尚未达到 Baseline：始终应使用
```
@supports (animation-timeline: view())
```
并提供回退方案。
View Transitions：同文档转换在所有引擎中均受支持（Firefox 144+），跨文档转换尚不支持 Firefox。 React 19.3 稳定版导出
```
<ViewTransition>
```
/
```
addTransitionType
```
；Next 16.3 无需开启 flag。
GSAP 默认的
pin: true
会导致 CLS：在 Chromium 中实测，每个 100vh 区块在 pin 时为 0.75， unpin 时为 1.0（滚动不属于可排除的输入）。CSS
```
position: sticky
```
配合 scrub，以及
```
pinType: "transform"
```
，两者实测均为 0。布局允许时，应优先采用 sticky 轨道。
脱离页面顺序创建的 ScrollTrigger（懒加载区块、useGSAP
```
dependencies
```
中变化的
```
useLenis()
```
值）会根据 pin 长度提前触发。较高的
```
refreshPriority
```
会优先刷新；设置任意
```
refreshPriority
```
都会启用按页面位置自动排序。（官方 gsap-scrolltrigger skill 的描述与此相反；应以源码为准。）
目前仅 Chromium 支持：
```
interpolate-size
```
、
```
corner-shape
```
、CSS 轮播（
```
::scroll-marker
```
）、
```
scroll-state()
```
查询、
```
if()
```
、
```
@function
```
。仅应将其作为渐进增强功能使用。
会破坏旧代码片段的 API 变更：cobe 2 不再提供
```
onRender
```
（应通过自己的 rAF 驱动
```
globe.update()
```
）； drei 10 的
```
PresentationControls
```
接受
```
damping
```
，而不是
```
config
```
；
```
THREE.Clock
```
已弃用（r183+）；Next 16 的
```
Image
```
使用
```
preload
```
，而不是
```
priority
```
；Motion 的
```
AnimateView
```
从
```
motion/react-animate-view
```
导入；tsParticles v4 使用
```
ParticlesProvider
```
。
包装元素上的内联
```
style={{ position: ... }}
```
会覆盖调用方传入的
```
absolute inset-0
```
class，并将其高度压缩为 0 px：对于接受
```
className
```
的组件，应始终使用 class 管理定位。

Page choreography blueprint

页面编排蓝图

Layer	Budget	Typical recipe
Arrival	hero readable in under 1.2 s	optional preloader only for a real brand moment or heavy assets, then a hero timeline: headline line-mask reveal, media scale/clip-in, nav fade last
Signature	exactly one per page	pinned scrub sequence, horizontal gallery, stacked cards, WebGL hero, or kinetic headline
Rhythm	one system for every section	same ease, distance (24-48 px), stagger (40-80 ms) for all reveals; no per-section novelty
Feedback	every interactive element	hover/press/focus at 120-250 ms; magnetic or cursor effects only on pointer:fine
Transitions	route and state changes	view transitions or a curtain matching the direction
Finale	footer	giant fitted wordmark, marquee, or a quiet sign-off; not another spectacle

One hero effect per viewport. Two competing motions cancel each other.
Motion follows the spatial model: things enter from where they logically come from and leave toward where they go. Keep direction consistent across the page.
Lead with the largest element, follow with detail. Text last when media carries the moment, text first when the headline is the moment.
Exits are faster than entrances (about 0.75x). High-frequency actions get little or no motion.
Reveal once. Re-animating content every time it re-enters the viewport is noise.
Scroll-linked motion must feel attached to the finger: scrub with slight smoothing (
```
scrub: 0.5
```
to
```
1
```
), never time-based animations that fight the scroll.
Never hijack scroll speed or direction on content pages. Pin, do not trap.

层级	预算	典型配方
到达	首屏应在 1.2 秒内可读	仅在确有品牌时刻或资源较重时使用可选预加载器，随后执行首屏时间线：标题逐行遮罩显现、媒体缩放/裁剪进入、导航最后淡入
标志性效果	每页恰好一个	pinned scrub 序列、横向画廊、堆叠卡片、WebGL 首屏或动态标题
节奏	每个区块使用同一套系统	所有显现采用相同的缓动、距离（24-48 px）和 stagger（40-80 ms）；不要每个区块都标新立异
反馈	每个可交互元素	hover/press/focus 控制在 120-250 ms；磁吸或光标效果仅适用于 `pointer:fine`
过渡	路由和状态变化	View Transitions 或与移动方向一致的幕布过渡
收尾	页脚	超大宽度自适应字标、marquee 或安静的结束语；不要再加入另一场视觉奇观

每个视口只保留一个首屏效果。两个相互竞争的动效会彼此抵消。
动效应遵循空间模型：元素应从逻辑上的来源方向进入，并向其目标方向离开。整个页面的方向应保持一致。
先呈现最大元素，再补充细节。当媒体是重点时，文字最后出现；当标题是重点时，文字最先出现。
退场应快于入场（约为 0.75 倍）。高频操作应使用很少的动效或完全不使用动效。
只显现一次。内容每次重新进入视口时都重复播放动画，只会制造噪声。
滚动关联动效必须让人感觉与手指相连：scrub 应带少量平滑处理（
```
scrub: 0.5
```
到
```
1
```
），切勿使用与滚动相互对抗的基于时间的动画。
在内容页面上，绝不要劫持滚动速度或方向。可以 pin，但不要困住用户。

Non-negotiables

不可妥协的原则

```
prefers-reduced-motion
```
: replace movement with opacity or the static end state; stop parallax, auto-play, marquees and scroll-jacking; keep all content visible (
```
performance-a11y.md#15-reduced-motion-reduce-dont-remove
```
).
Auto-moving content longer than 5 s (marquees, carousels, video backgrounds) needs a pause control or pause on hover/focus (WCAG 2.2.2).
Animate
```
transform
```
and
```
opacity
```
by default.
```
filter
```
,
```
backdrop-filter
```
,
```
clip-path
```
and
```
mask
```
are fine on small or short-lived elements; never scrub them on full-viewport surfaces.
Pointer effects (custom cursor, magnetic, tilt, hover reveals) only under
```
(hover: hover) and (pointer: fine)
```
, with a touch-friendly equivalent. Hide-until-hover states must be gated the same way (a landscape tablet is
```
lg
```
wide and cannot hover).
The LCP element is never hidden behind a long preloader. Server-render content; animate from a visible or quickly revealed state. Loaders and intro curtains are opt-in: hidden unless a head script sets
```
html[data-intro="run"]
```
, so no-JS visitors and failed bundles never see a blank screen.
Split text keeps an accessible label (
```
aria-label
```
on the parent, split pieces
```
aria-hidden
```
).
Clean up everything:
```
useGSAP
```
scope, ScrollTriggers, Lenis, RAF loops, observers, WebGL contexts. No
```
window
```
at module scope (SSR).
Tokens, not magic numbers: durations, easings, distances and staggers live in CSS custom properties or one TS constants module.
Test in both themes (if the site has two), at 375 px and 1440 px, and with CPU throttled 4x.

```
prefers-reduced-motion
```
：用透明度变化或静态结束状态替代运动；停止视差、自动播放、marquee 和滚动劫持；确保所有内容均可见（
```
performance-a11y.md#15-reduced-motion-reduce-dont-remove
```
）。
自动运动且持续超过 5 秒的内容（marquee、轮播、视频背景）需要暂停控件，或在 hover/聚焦时暂停（WCAG 2.2.2）。
默认只动画化
```
transform
```
和
```
opacity
```
。
```
filter
```
、
```
backdrop-filter
```
、
```
clip-path
```
和
```
mask
```
可用于较小或短生命周期的元素；绝不要在覆盖整个视口的表面上对它们使用 scrub。
指针效果（自定义光标、磁吸、倾斜、悬停显现）只能在
```
(hover: hover) and (pointer: fine)
```
下使用，并提供适合触控设备的等效方案。悬停前隐藏的状态也必须采用相同限制（横向平板虽然宽度达到
```
lg
```
，但无法 hover）。
LCP 元素绝不能被长时间预加载器遮挡。应在服务端渲染内容；从可见或快速显现的状态开始动画。加载器和首次展示幕布必须由用户主动选择启用：除非 head script 设置
```
html[data-intro="run"]
```
，否则一律隐藏，确保禁用 JS 的访问者和加载失败的 bundle 永远不会看到空白页面。
拆分文字必须保留可访问标签（父元素使用
```
aria-label
```
，拆分片段使用
```
aria-hidden
```
）。
清理所有资源：
```
useGSAP
```
scope、ScrollTrigger、Lenis、RAF 循环、观察器和 WebGL 上下文。模块作用域中不得使用
```
window
```
（SSR）。
使用 token，而不是魔法数字：时长、缓动、距离和 stagger 应存放在 CSS 自定义属性或一个 TS 常量模块中。
在两种主题（如网站支持双主题）、375 px 和 1440 px 宽度下进行测试，并将 CPU 限制为 4 倍后复测。

Verification protocol

验证协议

Scripts live in this skill's

scripts/

folder and need

playwright-core

(or

playwright

) in the project plus an installed Chrome/Edge (or set

AUDIT_BROWSER

<skill-dir>

below is this skill's base directory (shown when the skill loads;

~/.claude/skills/frontend-atlas

for a manual install).

Start the dev server, then run
```
node <skill-dir>/scripts/motion-audit.mjs http://localhost:3000 --out motion-audit --widths 1440,390 --steps 16
```
. It scrolls with real wheel input (so Lenis/ScrollTrigger react), screenshots intro frames and every scroll step, and runs again with
```
prefers-reduced-motion: reduce
```
. It reports console errors, horizontal overflow with the culprit element, content that entered the viewport but was never visible (reveals that never fired), CLS with the shifting nodes, frame pacing and long animation frames. Headless numbers are for before/after comparison, not field data.
```
node <skill-dir>/scripts/contact-sheet.mjs motion-audit --match motion-1440-scroll
```
builds one image of the whole scroll: read it to check choreography, pins and crossfades.
When a scroll effect fires early or late, compare
```
ScrollTrigger.getAll().map(t => [t.trigger, t.start])
```
with each trigger's
```
getBoundingClientRect().top + scrollY
```
(creation-order bug, see facts above).
Keyboard pass: tab through menus, dialogs and transitions; focus stays visible and trapped where it should be. Then run the
```
web-design-guidelines
```
skill over the changed files.

Maintaining this skill: after editing any reference, run

node scripts/maintenance/build-index.mjs

(regenerates

references/INDEX.md

) and

node scripts/maintenance/check-links.mjs --links

from the skill folder. Re-verify changed recipes in a browser before trusting them.

脚本位于本 skill 的

scripts/

目录，需要项目安装

playwright-core

（或

playwright

），并安装 Chrome/Edge（或设置

AUDIT_BROWSER

）。下方的

<skill-dir>

表示本 skill 的基础目录（加载 skill 时会显示；手动安装时为

~/.claude/skills/frontend-atlas

）。

启动开发服务器，然后运行
```
node <skill-dir>/scripts/motion-audit.mjs http://localhost:3000 --out motion-audit --widths 1440,390 --steps 16
```
。它会使用真实滚轮输入进行滚动（使 Lenis/ScrollTrigger 正常响应），截取初始画面和每个滚动步骤的画面，并在
```
prefers-reduced-motion: reduce
```
下再次运行。它会报告控制台错误、带有问题元素的水平溢出、已进入视口却从未显示的内容（未触发的显现）、包含发生位移节点的 CLS、帧节奏以及耗时过长的动画帧。无头模式下的数值用于前后对比，不代表真实环境数据。
```
node <skill-dir>/scripts/contact-sheet.mjs motion-audit --match motion-1440-scroll
```
会将整个滚动过程合成为一张图片：读取该图片，检查编排、pin 和交叉淡入淡出。
当滚动效果过早或过晚触发时，将
```
ScrollTrigger.getAll().map(t => [t.trigger, t.start])
```
的结果与每个触发器的
```
getBoundingClientRect().top + scrollY
```
进行比较（创建顺序问题参见上方事实）。
键盘检查：通过 Tab 键依次访问菜单、dialog 和过渡；焦点必须始终可见，并在适当位置受到约束。然后对变更过的文件运行
```
web-design-guidelines
```
skill。

维护本 skill：编辑任何参考文件后，运行

node scripts/maintenance/build-index.mjs

（重新生成

references/INDEX.md

），并从 skill 目录运行

node scripts/maintenance/check-links.mjs --links

。在信任变更后的配方前，应重新在浏览器中完成验证。

Companion skills

配套 skills

Recommended alongside this skill (install commands in the repository README); when installed, use them as deep API references once the stack is chosen:

gsap-core

gsap-timeline

gsap-scrolltrigger

gsap-plugins

gsap-react

gsap-utils

gsap-performance

gsap-frameworks

: official GreenSock skills (

greensock/gsap-skills

). Where

gsap-scrolltrigger

describes

refreshPriority

ordering, trust the platform fact above.

vercel-react-view-transitions

: deep patterns for React

<ViewTransition>

in Next.

```
web-design-guidelines
```
: Vercel's Web Interface Guidelines as a final review pass.

vercel-react-best-practices

: React/Next performance rules (all three from

vercel-labs/agent-skills

Taste and critique:

taste-skill

redesign-skill

soft-skill

(

Leonxlnx/taste-skill

) and

impeccable

(

pbakaus/impeccable

Precedence: project rules > this skill's stack decision > a companion's default ("recommend GSAP" in the GSAP skills does not override choosing CSS or Motion when they are lighter).

建议与本 skill 搭配使用（安装命令见仓库 README）；技术栈确定后，可将其作为深入 API 参考：

gsap-core

、

gsap-timeline

、

gsap-scrolltrigger

、

gsap-plugins

、

gsap-react

、

gsap-utils

、

gsap-performance

、

gsap-frameworks

：官方 GreenSock skills（

greensock/gsap-skills

）。如果

gsap-scrolltrigger

对

refreshPriority

顺序的描述与此不同，请以上方平台事实为准。

vercel-react-view-transitions

：React

<ViewTransition>

在 Next 中的深入模式。

```
web-design-guidelines
```
：将 Vercel Web Interface Guidelines 作为最终审查环节。

vercel-react-best-practices

：React/Next 性能规则（三项均来自

vercel-labs/agent-skills

）。

审美与评审：

taste-skill

、

redesign-skill

、

soft-skill

（

Leonxlnx/taste-skill

）和

impeccable

（

pbakaus/impeccable

）。

优先级：项目规则 > 本 skill 的技术栈决策 > 配套 skill 的默认设置（GSAP skills 中“推荐 GSAP”的建议，不会覆盖在更轻量方案可完成时应选择 CSS 或 Motion 的原则）。

Motion slop to refuse (quick list)

必须拒绝的低质动效（快速清单）

Fade-up on every section with identical timing, the default AI reveal. Use one crafted reveal system and let some sections simply be there.
Bounce or elastic easing on UI, scale-from-zero, spinning or wobbling decorations.
Purple-to-blue aurora + grid + beams + shimmer button + bento as a stack of defaults (
```
aesthetic-directions.md#global-ai-slop-tells-evidence-ranked
```
).
Tilt, glow and magnetic effects on everything at once.
Custom cursor on a content or product site with no reason for it.
Parallax on text blocks, parallax ratios above about 0.3 on content, horizontal scroll for plain text content.
Preloaders that exist only to show a counter.
Typewriter headlines, gradient text on every heading, glitch effects outside a clear concept.

When a request would land in this list, pick the tasteful variant from the relevant reference file and say briefly why.

每个区块都以相同时序淡入上移，即默认的 AI 显现方式。应设计一套精心打造的显现系统，并允许部分区块直接保持可见。
UI 使用弹跳或弹性缓动，从零开始缩放，或让装饰元素持续旋转、晃动。
将紫蓝极光、网格、光束、微光按钮和 Bento 机械地堆叠在一起（
```
aesthetic-directions.md#global-ai-slop-tells-evidence-ranked
```
）。
对所有元素同时使用倾斜、发光和磁吸效果。
在没有合理目的的内容站或产品站上使用自定义光标。
对文字区块使用视差；内容上的视差比例超过约 0.3；为纯文本内容使用横向滚动。
预加载器仅仅用于展示一个计数器。
使用打字机标题、给每个标题添加渐变文字，或在概念不明确时使用故障效果。

如果某项需求会落入上述清单，应从相关参考文件中选择更有品味的变体，并简要说明原因。