Promptory Web Build
三個工具,一個堆疊,各司其職:
| 工具 | 角色 | 經驗法則 |
|---|---|---|
| Lenis | 滾動引擎 — 在原生生滾動之上提供平滑、慣性的滾動效果 | 僅需全域安裝一次。切勿按區塊安裝。 |
| GSAP (+ ScrollTrigger) | 動畫引擎 — 自訂時間軸、滾動驅動動畫、固定效果 | 用於此網站設計中的任何客製化需求。 |
| React Bits | 現成的動畫組件(文字、背景、游標、卡片、按鈕) | 當目錄組件已能實現所需效果時,優先選用。 |
它們共享一個動畫循環:GSAP 的 ticker 驅動 Lenis,而 ScrollTrigger 讀取 Lenis 的滾動位置。正確完成此連接是此技能中最重要的一件事(§3)。
範圍:僅限即時網頁/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、粒子、形狀、圖表…,每個都附帶其提示詞)。僅在用戶要求靈感、在問卷中選擇「需要提案」/「大膽動畫」,或分享了該網站的連結時使用。借用動畫概念,使用 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 優先:遵循客戶的設計和簡報本身的描述,包括當簡報要求使用下列某種外觀時。
- 首先識別主題:產品、目標受眾、主要任務。如果簡報未說明,提出一個並確認。行業和素材是產生獨特選擇的來源。
- 首屏以主題世界中最具特色的事物開場(標題、圖片、即時示範或互動)。避免使用大數字、小標籤和漸層強調色的預設組合,除非這顯然是最佳選擇。
- 字體:使用一款字體家族,或兩款明顯不同的字體。設定清晰的字體比例。在標題中,字體的處理方式本身就是設計的一部分。
- 行長保持在 80 個字元以下。襯線體正文字體需要比無襯線體稍大的行高。
- 避免排版上的常見特徵:標題中一個斜體或有顏色的詞、全大寫的標籤,以及無貢獻的標題上方標籤。
- 數字標記(01 / 02 / 03)僅在內容確實是序列時使用。
- 動畫:一個精心編排的時刻(頁面載入或一次揭示)。不要在每個區塊都使用淡入滑出,不要在每張卡片上都使用懸停過渡。回應使用者操作(開啟、展開、確認)的動畫則沒問題。
- 在編碼前規劃:4–6 個命名的十六進位顏色、字體角色、版面概念(允許 ASCII 線框圖)和原則。根據簡報審查規劃。如果某部分讀起來像任何類似頁面的通用預設,請修改它並說明更改了什麼。
- 除非簡報要求,否則應避免的預設外觀:奶油色背景搭配赭色強調色;近似黑色搭配螢光綠或朱紅色強調色;帶有極細分隔線和零圓角的寬幅報紙風格;完全相同、單一半徑和一種灰色陰影的圓角 SaaS 卡片;每個標題上方的大寫眉題;中間點分隔的中繼資料字串('A · B · C');'WORD — fragment' 標籤;用 #0B0B0B 或 #111 代表黑色;用小標籤使用等寬字體;每個連結上的 '→'。
- 將大膽的設計集中在一個地方。保持其餘部分低調。刪除不服務於簡報的裝飾。
- 品質底線:響應式行動裝置、可見的焦點指示器、尊重減少動畫設定、可訪問的對比度。
- 注意 CSS 選擇器的特定性,特別是區塊之間的內邊距和外邊距,這些地方的規則可能會互相抵消。
- 文案:對最終用戶使用平實的詞彙、主動語態、句子大小寫。在一個流程中保持一致動詞(「發布」引導至「已發布」)。錯誤訊息說明發生了什麼事以及如何修正,無需道歉。空狀態應引導下一步行動。
1. 決策流程 — 哪個工具處理哪個請求
- 阿拉伯語、雙語或 RTL 網站 → 在編寫任何版面之前,先閱讀
references/rtl-arabic.md。方向是結構性的;事後調整成本高昂。 - 網站上任何地方的平滑滾動 → Lenis(全域提供者,§3)。在任何滾動動畫存在時,於專案設定時執行一次。
- 是否有 React Bits 組件已能實現該效果?→ 檢查
references/react-bits-catalog.md→ 安裝它(§4)。常見的適用情境:分割/模糊/擾亂文字、滾動揭示文字、動畫背景(極光、粒子、網格、著色器)、自訂游標、磁吸/傾斜卡片、跑馬燈、圖庫、擴充塢/選單、動畫按鈕/計數器。 - 效果專屬於此設計(首頁開場序列、固定說故事區塊、水平滾動區塊、同步多元素揭示)→ GSAP 時間軸 / ScrollTrigger(§5,詳細資訊請參閱
references/gsap.md)。 - 專案不是 React(純 HTML / Vanilla JS)→ 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()→ 觸發位置與最終版面匹配。
Vanilla 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 以匹配網站現有的設計 Token(顏色、字型),而不是保留示範預設值。
- 如果用戶想要代理工作流程:
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搭配sso: false或React.lazy),並為它們提供一個固定尺寸的容器。當它們離開螢幕或分頁隱藏時暫停它們。 - 請勿在同一個視口中疊加兩個游標效果或兩個背景。
- 如果組件循環超過 5 秒,請檢查每個組件的暫停控制(請參閱
references/accessibility-motion.md§5)。 - 授權:React Bits 是 MIT + Commons Clause — 可在任何客戶網站內免費使用(包括付費客戶專案),但組件本身不得作為套件/範本轉售或重新分發。切勿將 React Bits 的原始碼貼到此技能或共享函式庫中;請始終從註冊表安裝。
5. GSAP 基礎(自訂動畫)
在 React 中始終使用帶有 scope 的 useGSAP — 切勿使用原始的 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):
- 對於包含 >1 個元素的任何內容使用時間軸;對於重複的卡片使用
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-
…
[原文已截斷以進行翻譯]