frontend-atlas

Frontend Atlas

高品质前端的实现层。同系列技能负责判断是否需要以及做什么 （taste-skill 的反套路规则、impeccable 的评审／审计／润色、soft-skill、minimalist-skill、 brutalist-skill）。本技能负责如何实现：为动效、滚动、字体、悬停、过渡、背景、着色器和组件效果提供经过验证、可直接复制粘贴的方案。这些效果已应用于 2026 年最出色的网站；此外，本技能还具备挑选合适方案并不断调校、直至效果浑然天成的判断力。

已于 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）。

如何使用

1. 在编写任何代码之前，先写好下方的设计解读。最多五行。
2. 找到所需效果：查看下方的精选列表，或搜索 references/INDEX.md（其中列出了每个方案及其锚点）。
3. 只打开所需的章节。参考文件篇幅较长（700–3000 行）；除非需要在多个方案中做选择（此时先阅读该文件中的决策指南表格），否则不要全文加载。
4. 复制方案，然后根据选定的动效风格调整调校部分中的数值。
5. 使用真实浏览器，通过 scripts/motion-audit.mjs 进行验证（参见“验证”）。未实际查看，就不算完成。

参考索引

文件	适用场景
references/INDEX.md	按名称查找任何效果（共 474 项，按文件分组）。
references/motion-principles.md	缓动、时长、弹簧、交错、编排、7 种动效个性预设。构建动画较多的页面前请先阅读。
references/scroll-gsap.md	Lenis 平滑滚动、ScrollTrigger 显现、固定、滚动进度控制、横向画廊、堆叠卡片、滚动时使用 SplitText、图像序列、视频滚动进度控制、Flip、Observer 幻灯片、刷新规范。
references/scroll-css-native.md	零 JS 滚动效果：animation-timeline: scroll()/view()、进度条、显现、视差、CSS 轮播、scroll-state() 查询、回退方案、原生方案与 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	分字文本显现、乱码效果、打字机、轮换词语、文字滚动、可变字体动画、跑马灯、计数器、渐变/闪光文字、路径文字、自适应字标、动态开场动画。
references/typography.md	字号比例、流式字号、字距/行高、OpenType、27 组字体搭配及其来源与许可证、避免 CLS 的字体加载方式、编辑类排版布局。
references/interactions.md	自定义光标、磁吸效果、悬停显现、图像拖尾、按钮/链接悬停、倾斜、聚光卡片、标签页指示器、手风琴、弹出层、提示消息、抽屉、停靠栏、拖动、微交互反馈、手感调校表。
references/page-transitions.md	View Transitions（同文档、跨文档）、Next 16 中的 React <ViewTransition>、共享元素、GSAP 覆盖层转场、Swup/Barba/Astro、预加载器、开场门控、全屏菜单、路由规范。
references/backgrounds-svg-canvas.md	网格/极光/颗粒/网格背景、锥形渐变边框、SVG 绘制/变形/黏液/置换、Canvas 粒子/点阵/流场、Lottie 与 Rive 的比较。
references/webgl-shaders-3d.md	WebGL 加载外壳、着色器库（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 色阶、语义令牌、对比度（WCAG/APCA）、深色模式、渐变、玻璃与液态玻璃、阴影、边框、圆角、图像处理。
references/layout-composition.md	突破式网格、12 列/子网格、流式间距、10 种主视觉框架、便当盒布局、区块模式、粘性/重叠布局、导航、响应式策略。
references/aesthetic-directions.md	选择或实现 30 种视觉方向，每种都包含令牌、字体、动效特征、真实参考网站、AI 味设计的识别特征。
references/libraries.md	选择/设置 37 种库：体积、安装、SSR 注意事项、状态、按项目类型推荐的技术栈。
references/performance-a11y.md	发布任何动画前：属性开销、卡顿调试、暂停屏幕外任务、固定元素引起的 CLS、正确处理减少动态效果、WCAG 动效标准、QA 检查清单。
references/inspiration-sources.md	查找参考、组件、字体、图标、素材、工具；逆向分析线上网站中的效果。

效果精选（最常见需求）

效果	位置
平滑滚动（在 GSAP ticker 上运行 Lenis）	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
滚动速度倾斜 / 跑马灯	scroll-gsap.md#13-scroll-velocity-skew-and-marquee
Apple 图片序列 / 视频滚动控制	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-per-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
跑马灯（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 对话框 / 弹出框进入与退出	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
着色器渐变背景	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

设计解读（始终先做）

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>

如果需求模糊（如“做得高级一些”），请根据产品、受众和现有品牌推断，说明你的解读，然后继续。只有在两种截然不同的方向同样合理时才提问。

选择技术栈

选择能够实现效果的最轻量工具：

1. 仅 CSS：悬停／按压／焦点状态、弹出层／对话框的进入与退出（@starting-style）、折叠面板、进入时显现和进度条（滚动驱动动画，带回退方案）、跑马灯、渐变／圆锥渐变动画（@property）。零 JS，不占用主线程。
2. Motion（motion/react）：React 应用 UI。布局动画、layoutId 共享元素、显示／退出、手势和拖动、弹簧效果、可重排列表。
3. GSAP + ScrollTrigger + Lenis：滚动叙事和时间轴。固定、滚动联动、多步骤序列、横向区块、SplitText、Flip、DrawSVG/MorphSVG、引导动画序列。
4. WebGL（用于 2D 着色器效果的 OGL，用于场景的 R3F）：仅在概念需要时使用。始终通过加载外壳提供静态海报回退方案（webgl recipe 1）。

Motion 和 GSAP 可以在同一项目中承担不同工作，但绝不能用于同一元素。 只使用一个平滑滚动实例和一个 RAF 循环（存在 GSAP 时，通过 gsap.ticker 驱动 Lenis）。

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

• 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 无需标志即可使用。
• GSAP 默认的 pin: true 会导致 CLS：在 Chromium 中，每个 100vh 区块固定时测得 CLS 0.75，取消固定时测得 1.0（滚动不属于排除项输入）。CSS position: sticky + scrub 和 pinType: "transform" 的测量值均为 0。布局允许时优先使用 sticky 轨道。
• 按页面顺序之外创建的 ScrollTrigger（惰性区块、useGSAP dependencies 中的 useLenis() 值）会因固定长度而提前触发。较高的 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 类，并将其压缩至 0 px：对于接受 className 的任何组件，都应通过类来设置定位。

页面动效编排蓝图

层级	预算	常见方案
入场	首屏在 1.2 s 内清晰可读	仅在确有品牌展示需求或资源较大时使用预加载器，随后播放首屏时间轴：标题逐行遮罩显现、媒体缩放／裁切进入，导航最后淡入
标志性动效	每页恰好一个	固定滚动序列、水平画廊、堆叠卡片、WebGL 首屏或动感标题
节奏	每个区块采用同一套系统	所有显现效果使用相同的缓动、距离（24-48 px）和错开间隔（40-80 ms）；不要为各区块引入新花样
反馈	每个交互元素	悬停／按下／焦点状态的动效时长为 120-250 ms；仅在 pointer:fine 时使用磁吸或光标效果
过渡	路由和状态变化	视图过渡，或使用方向一致的幕布效果
收尾	页脚	大型适配字标、跑马灯或简洁收尾；不要再添加一场视觉盛宴

• 每个视口只安排一个首屏效果。两个相互竞争的动效会彼此抵消。
• 动效遵循空间模型：元素从符合逻辑的来源进入，并朝其去向离开。整页保持方向一致。
• 先呈现最大的元素，再呈现细节。媒体主导时最后呈现文字；标题是重点时则先呈现文字。
• 离场比入场快（约为 0.75 倍）。高频操作尽量少用或不用动效。
• 只显现一次。内容每次重新进入视口时都重复播放动效，会造成干扰。
• 与滚动联动的动效必须紧跟手指操作：使用略微平滑的 scrub（scrub: 0.5 到 1），绝不要使用与滚动相冲突的定时动效。
• 内容页面绝不要劫持滚动速度或方向。可以固定，不要锁住滚动。

不可妥协的要求

• prefers-reduced-motion：将位移动效替换为透明度变化或静态结束状态；停止视差、自动播放、跑马灯和滚动劫持；确保所有内容均可见（performance-a11y.md#15-reduced-motion-reduce-dont-remove）。
• 自动移动超过 5 s 的内容（跑马灯、轮播、视频背景）必须提供暂停控件，或在悬停／聚焦时暂停（WCAG 2.2.2）。
• 默认只对 transform 和 opacity 添加动效。filter、backdrop-filter、clip-path 和 mask 可用于较小或短暂显示的元素；绝不要让它们在全视口表面上与滚动联动。
• 指针效果（自定义光标、磁吸、倾斜、悬停显现）仅在 (hover: hover) and (pointer: fine) 条件下启用，并提供适合触屏的替代方案。仅悬停时显示的状态也必须采用相同的条件限制（横屏平板的宽度可能达到 lg，但不支持悬停）。
• LCP 元素绝不能被较长的预加载器遮挡。使用服务端渲染内容；从可见或能迅速显现的状态开始播放动效。加载器和开场幕布均为可选：默认隐藏，只有头部脚本设置 html[data-intro="run"] 时才显示，这样无 JS 的访客和加载失败的代码包都不会看到空白屏幕。
• 拆分文本时保留无障碍标签（在父元素上设置 aria-label，拆分后的片段设置 aria-hidden）。
• 清理所有内容：useGSAP 作用域、ScrollTriggers、Lenis、RAF 循环、观察器和 WebGL 上下文。不要在模块作用域中使用 window（SSR）。
• 使用令牌，不要使用随意填写的数值：时长、缓动、距离和错开间隔应放在 CSS 自定义属性或单个 TS 常量模块中。
• 在两种主题下（如果网站提供两种主题）、375 px 和 1440 px 屏幕尺寸下，以及 CPU 降速 4 倍的情况下进行测试。

验证流程

脚本位于此技能的 scripts/ 文件夹中，需要项目中安装 playwright-core（或 playwright），并安装 Chrome/Edge（或设置 AUDIT_BROWSER）。下文中的 <skill-dir> 指此技能的基础目录（技能加载时会显示；手动安装时为 ~/.claude/skills/frontend-atlas）。

1. 启动开发服务器，然后运行 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、帧间隔，以及长动画帧。无头模式下的数据仅用于前后对比，并非实测数据。
2. 运行 node <skill-dir>/scripts/contact-sheet.mjs motion-audit --match motion-1440-scroll，生成一张包含完整滚动过程的图片：查看图片以检查动画编排、固定效果和交叉淡化。
3. 如果滚动效果触发过早或过晚，请将 ScrollTrigger.getAll().map(t => [t.trigger, t.start]) 与每个触发元素的 getBoundingClientRect().top + scrollY 进行比较（创建顺序错误，见上文事实部分）。
4. 键盘检查：按 Tab 键遍历菜单、对话框和过渡效果；焦点应保持可见，并在需要时受到限制。然后对已更改的文件运行 web-design-guidelines 技能。

维护此技能：编辑任何参考资料后，运行 node scripts/maintenance/build-index.mjs（重新生成 references/INDEX.md）和 node scripts/maintenance/check-links.mjs --links，命令须在技能文件夹中执行。更改配方后，请先在浏览器中重新验证，再予以采信。

配套技能

建议与此技能搭配使用（安装命令见仓库 README）；安装后，在选定技术栈时可将它们作为深入的 API 参考：

• gsap-core、gsap-timeline、gsap-scrolltrigger、gsap-plugins、gsap-react、gsap-utils、 gsap-performance、gsap-frameworks：GreenSock 官方技能（greensock/gsap-skills）。如果 gsap-scrolltrigger 对 refreshPriority 排序的描述与上述平台事实不一致，请以平台事实为准。
• vercel-react-view-transitions：Next 中 React <ViewTransition> 的深入实践模式。
• web-design-guidelines：Vercel 的 Web 界面指南，可用于最终审查。
• vercel-react-best-practices：React/Next 性能规则（均来自 vercel-labs/agent-skills 的三个技能）。
• 品味与审视：taste-skill、redesign-skill、soft-skill（Leonxlnx/taste-skill）以及 impeccable（pbakaus/impeccable）。

优先级：项目规则 > 此技能对技术栈的选择 > 配套技能的默认建议（GSAP 技能中的“推荐 GSAP”不能推翻选择 CSS 或 Motion 的决定，尤其是在它们更轻量时）。

应拒绝的动画滥用（快速清单）

• 每个区块都用相同时间设置淡入上移，这是默认的 AI 显示效果。应采用一套精心设计的显示系统，并让某些区块直接呈现。
• 在 UI 中使用弹跳或弹性缓动、从零开始缩放、旋转或摇晃装饰元素。
• 紫到蓝的极光 + 网格 + 光束 + 闪烁按钮 + Bento 布局，堆叠使用一系列默认效果 （aesthetic-directions.md#global-ai-slop-tells-evidence-ranked）。
• 同时给所有元素添加倾斜、发光和磁吸效果。
• 在没有理由的内容或产品网站中使用自定义光标。
• 对文本块使用视差，在内容中使用高于约 0.3 的视差比例，或让纯文本内容横向滚动。
• 仅为显示计数器而存在的预加载动画。
• 打字机式标题、每个标题都使用渐变文本，以及概念不明确时使用故障效果。

如果某项请求会落入此清单，请从相关参考文件中选择更有品味的方案，并简要说明原因。