Promptory Web Build
三种工具,同一技术栈,各司其职:
| 工具 | 角色 | 经验法则 |
|---|---|---|
| Lenis | 滚动引擎 — 在原生的基础上实现平滑、惯性的滚动 | 全局安装一次,切勿按区块安装。 |
| GSAP (+ ScrollTrigger) | 动画引擎 — 自定义时间线、滚动驱动动画、固定 | 专注于本网站设计中的特有动画。 |
| React Bits | 现成的动画组件(文字、背景、光标、卡片、按钮) | 当目录中已有现成组件时,优先使用。 |
它们共享一个动画循环:GSAP的ticker驱动Lenis,ScrollTrigger读取Lenis的滚动。正确设置这一连接是此技能中最重要的环节(§3)。
范围:仅限实时Web/DOM。不适用于视频渲染(Remotion、reels等)。
0. 黄金法则 — 不要重新设计
按照用户要求的设计和效果进行实现。不要自行更改布局、颜色、字体、间距或文案,也不要添加任何额外的区块或未经验证的效果。如果某个效果或改进确实能提升体验,用一句话建议并等待批准。动效和质量检查应服务于现有设计,而非替代它。
0.5 需求问卷 — 处理每个新建站请求的首步
在开始编写任何新网站的代码之前,运行 references/intake-questionnaire.md 中的需求问卷:
- 阅读请求,跳过已回答的问题。
- 在最多3轮简短对话中提出剩余问题(项目→动效→交付)。如果可用,使用Claude Code的
AskUserQuestion工具(可点击选项 + 自动“其他”自由文本框);否则,将每轮作为代码块输出,每道问题都包含字母选项和一个空的“✎ أخرى”行。 - 在一个代码块中展示项目简报,并等待用户确认。
- 然后开始构建,严格遵循答案。
如果用户说“ابدأ على طول”/“跳过”,则使用⭐默认值,并在简报中注明。对于现有网站的小修改,除非需求不明确,否则跳过问卷。
简报必须记录:语言和方向(阿拉伯语/RTL、英语/LTR、或两者)、可访问性目标(默认WCAG 2.2 AA)、表单及其后端,以及(如有)分析工具。
0.6 视觉参考 — Prompt Motion
https://prompt-motion.com/ 是动效方向的视觉库(动态文字、产品UI、粒子、形状、图表……,每个都附带prompt)。仅在用户提出灵感需求、在问卷中选择“需要建议”/“大胆动效”、或分享链接时使用。借用动效思路,使用GSAP / Lenis / React Bits重构,并保留客户的设计。工作流程、类别→组件映射以及动效规范模板:references/visual-references.md。
0.7 质量标准 — 展示前检查
检查构建中是否有泛化输出的特征(默认靛蓝色强调、表情图标、虚构的指标、Lorem Ipsum文字、模板化区块)。修复自己代码中的问题;针对客户设计中的问题,提供一行建议的修复方案。完整列表:references/quality-bar.md。
0.8 设计方向 — 每个网站应与众不同
当客户没有自己的设计时,在编码前选择一个方向。阅读references/design-styles.md并:
- 从适合当前行业和受众的适配指南中,短选出三个方向。
- 跳过此对话或项目中最近三个网站已使用的方向(风格日志)。
- 在项目简报中写一行:
方向:<名称> — <理由>,并附一个备选方案。 - 按照该方向的特征选择进行构建,然后运行多样性检查:至少四个维度(共六个)必须与上一个网站不同。
这些方向是用于结构感和风格的参考。切勿复制参考中的品牌、照片、文案或精确布局。如果客户提供了设计,则遵循客户设计并跳过此步骤(§0黄金法则)。
0.9 独特的视觉设计(当简报未明确时)
来源:anthropics/skills,技能 frontend-design (Apache-2.0,详见其 LICENSE.txt)。仅适用于简报未明确视觉方向的情况。§0优先:遵循客户设计和简报本身的语言,包括当简报要求使用以下列表中某个外观时。
- 首先明确主体:产品、受众、主要功能。如果简报未提及,提出一个并确认。行业和材料是产生独特选择的出处。
- Hero区域以主体世界中最具特性的事物开场(标题、图片、实时演示或交互)。避免使用默认的大数字+小标签+渐变强调,除非它显然是最佳选择。
- 字体:一个系列,或两个明显不同的系列。设置清晰的字体比例。在标题中,字体处理是设计的一部分。
- 行宽小于80字符。带衬线的正文需要略大的行高。
- 避免排版特征:标题中一个斜体或彩色单词、全大写标签、以及位于标题上方且无实质贡献的标签。
- 带编号的标记(01 / 02 / 03)仅当内容确实是序列时使用。
- 动效:一个编排好的时刻(页面加载或一次展示)。避免每个区块淡入滑动、每个卡片hover过渡。响应用户操作(打开、展开、确认)的动效是OK的。
- 编码前规划:4-6个具名十六进制颜色、字体角色、布局概念(允许ASCII线框图)和原则。对照简报评审计划。若某部分读起来像任何类似页面的通用默认值,则修改它并说明变化。
- 应避免的默认外观(除非简报要求):奶色背景配赤陶色强调;近黑色配酸橙色或朱红色强调;宽幅报纸风格配细线边框和零圆角;相同的圆角SaaS卡片配一种灰色阴影;每个标题上方的全大写眉毛;中点分隔的元字符串('A · B · C');'WORD — 片段'标签;用#0B0B0B或#111代替纯黑;小型标签使用等宽字体;每个链接上放'→'。
- 在一个地方大胆使用,周围保持克制。删除不为简报服务的装饰。
- 质量标准:响应式移动端、可见的focus、尊重
prefers-reduced-motion、可访问的对比度。 - 注意CSS选择器特殊性,尤其是区块之间的padding和margin,否则规则会相互抵消。
- 文案:对最终用户使用平实的词语、主动语态、句子大小写。在整个流程中保持动词一致(“发布”后接“已发布”)。错误消息说明发生了什么以及如何修复,无需道歉。空状态引导下一步操作。
1. 决策流程 — 为不同请求选择工具
- 阿拉伯语、双语或RTL网站 → 在编写任何布局之前先阅读
references/rtl-arabic.md。方向是结构性的;后期改造代价高昂。 - 网站任何地方需要平滑滚动 → Lenis(全局提供器,§3)。在需要任何滚动动画的项目设置时执行一次。
- 是否存在已实现该效果的React Bits组件? → 检查
references/react-bits-catalog.md→ 安装它(§4)。常见匹配:分割/模糊/扰乱文字、滚动展示文字、动画背景(极光、粒子、网格、着色器)、自定义光标、磁吸/倾斜卡片、跑马灯、画廊、坞/菜单、动画按钮/计数器。 - 效果是本设计特有的(Hero开场序列、固定讲故事的区块、水平滚动区块、同步多元素展示) → GSAP时间线 / ScrollTrigger(§5,详细内容见
references/gsap.md)。 - 项目不是React(普通HTML/Vanilla) → React Bits不可用;仅使用Lenis + GSAP(
assets/vanilla-setup.js)。 - 任何表单、列表、预订或数据驱动的区块 →
references/forms-and-states.md(标签、错误、五种状态)。 - 选择第三方服务(字体、表单后端、分析、托管、图片) →
references/free-services.md,然后验证当前限制。 - 新网站,客户无设计 → 先选择一个方向(§0.8,
references/design-styles.md)。
2. 安装
npm install gsap @gsap/react lenis
@gsap/react→ 仅适用于React项目(提供useGSAP)。lenis/react和lenis/snap已包含在lenis包内 — 无需额外包。- 所有GSAP插件(ScrollTrigger, SplitText, Flip, ScrollSmoother, Draggable…)已包含在
gsap包内。 - React Bits组件通过CLI单独添加(§4);部分组件会引入自己的依赖(
motion、three、ogl、matter-js…) — CLI会自动安装它们,但在选择前请查看目录中的依赖列,以避免膨胀打包结果。
永远不要将GSAP的ScrollSmoother与Lenis一起使用 — 它们是两个冲突的平滑滚动引擎。Lenis是本技术栈中的滚动引擎。
3. 连接 Lenis + GSAP + ScrollTrigger(请精确执行)
React / Next.js
将assets/SmoothScroll.jsx复制到项目中(例如components/SmoothScroll.jsx),并在应用中包裹一次:
// app/layout.jsx (Next.js App Router)
import SmoothScroll from '@/components/SmoothScroll';
import ScrollToTopOnRoute from '@/components/ScrollToTopOnRoute';
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
<SmoothScroll>
<ScrollToTopOnRoute />
{children}
</SmoothScroll>
</body>
</html>
);
}
对于阿拉伯语,根据语言环境在<html>上设置lang和dir(参见references/rtl-arabic.md §1)。
对于Vite/React,同样在main.jsx中包裹<App />,并跳过ScrollToTopOnRoute(它使用next/navigation)。
提供器的功能 — 以及每行代码为何重要:
<ReactLenis root options={{ autoRaf: false }}>→ 在<html>上设置一个全局实例;autoRaf: false因为GSAP将驱动它。lenis.on('scroll', ScrollTrigger.update)→ ScrollTrigger在每个平滑滚动帧上重新计算。缺失此行 = 动画触发延迟/位置错误。gsap.ticker.add(t => lenis.raf(t * 1000))→ 一个共享循环(GSAP时间单位为秒,Lenis期望毫秒)。gsap.ticker.lagSmoothing(0)→ 切换标签页后恢复时不会出现卡顿。- 字体和加载完成后调用
ScrollTrigger.refresh()→ 触发器位置匹配最终布局。
普通 HTML/JS
使用assets/vanilla-setup.js作为入口模块,在需要的地方从中导入lenis。
4. React Bits — 选择并安装组件
- 在
references/react-bits-catalog.md中找到组件(分组:文字动画、动画、组件、微型、背景 — 名称、功能、依赖)。 - 选择与项目匹配的变体:
JS或TS,然后CSS或TW(Tailwind)。 - 安装:
要使npx shadcn@latest add @react-bits/SplitText-TS-TW@react-bits/简写可用,项目的components.json必须包含:没有{ "registries": { "@react-bits": "https://reactbits.dev/r/{name}.json" } }components.json/ 不是shadcn项目?使用直接URL代替:npx shadcn@latest add https://reactbits.dev/r/SplitText-TS-TW.json # 或 npx jsrepo@latest add https://reactbits.dev/r/SplitText-TS-TW - 打开安装的文件,在使用前阅读其props — 每个组件都是可配置的(颜色、速度、延迟、缓动、触发器)。设置props以匹配网站现有的设计令牌(颜色、字体),而不是保留演示的默认值。
- 如果用户希望使用智能体工作流:
npx shadcn@latest mcp init --client claude通过MCP将Claude Code连接到注册表。
集成注意事项:
- 在滚动时动画的React Bits组件(ScrollReveal, ScrollFloat, AnimatedContent, SplitText…)内部使用GSAP ScrollTrigger或IntersectionObserver → 只要§3已设置好,它们就能自动与Lenis协同工作。
- 这些组件是客户端组件(
'use client')。在Next.js中,将它们放在允许客户端渲染的组件或页面内。 - WebGL/着色器背景(依赖
three、ogl、vgpu)较重:每页最多一个或两个,对折页以下部分进行懒加载(使用next/dynamic设置ssr: false或React.lazy),并为其提供固定大小的容器。当离开屏幕或标签页隐藏时暂停它们。 - 不要在同一视口中叠加两个光标效果或两个背景。
- 如果组件循环超过5秒,请检查是否有暂停控制(参见
references/accessibility-motion.md§5)。 - 许可证:React Bits是MIT + Commons Clause — 可以在任何客户端网站(包括付费客户项目)中免费使用,但组件本身不得作为包/模板转售或重新分发。切勿将React Bits源代码粘贴到此技能或共享库中;始终从注册表安装。
5. GSAP 要点(自定义动画)
在React中始终使用useGSAP配合scope — 绝不要使用原始的useEffect:
'use client';
import { useRef } from 'react';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import { useGSAP } from '@gsap/react';
gsap.registerPlugin(ScrollTrigger, useGSAP);
export default function Story() {
const root = useRef(null);
useGSAP(() => {
const tl = gsap.timeline({
scrollTrigger: { trigger: root.current, start: 'top top', end: '+=150%', scrub: 1, pin: true },
});
tl.from('.line', { yPercent: 100, autoAlpha: 0, stagger: 0.15 })
.to('.image', { scale: 1.15 }, '<');
}, { scope: root });
return <section ref={root}>…</section>;
}
核心模式(详情 + 响应式matchMedia、批处理、FOUC、清单见references/gsap.md):
- 对于包含多于一个元素的情况使用时间线;使用
ScrollTrigger.batch()处理重复卡片。 scrub用于滚动链接动画(与Lenis配合时,scrub: true已足够平滑;scrub: 1增加额外延迟)。pin: true与基于原生滚动的Lenis配合良好 — 当Lenis使用root时,无需pinTypehack。- 水平滚动区块:固定父容器,将轨道的
x渐变为-(track.scrollWidth - innerWidth),设置scrub: true和invalidateOnRefresh: true。在RTL中,反转方向(参见references/rtl-arabic.md§6)。 - 将装饰性区块包裹在
gsap.matchMedia()中,以便偏好减少动画效果的用户获得替代方案(references/accessibility-motion.md)。