Communitygithub.com

promptory 網站建置器

指導 AI 代理如何進行藝術指導並建置「promptory 網站建置器」,確保最終產出是完整的影片剪輯。流程包含 Promptory Web Build、0. 黃金法則 — 不重新設計、0.5 需求調查問卷 — 每個新網站請求的第一步。在需要此工藝的新任務時使用。

promptory 網站建置器 是什麼?

Promptory Web Builder 是一套專為 AI 代理設計的專業技能,用於建置具備流暢動畫與高互動性的現代網站,並特別強調最終產出為一段完整的影片剪輯。此技能基於三項核心工具:Lenis(平滑滾動引擎)、GSAP + ScrollTrigger(動畫引擎)以及 React Bits(現成動畫組件庫),三者透過統一的動畫循環協同運作,實現精準的滾動驅動動畫。其工作流程以一份詳細的需求調查問卷為起點,確保代理在編寫任何程式碼前,已完整理解專案需求,並遵循「不重新設計」的黃金法則,嚴格按照客戶的設計與規格執行。技能內含豐富的參考文件,涵蓋視覺動向、品質檢查清單、設計風格指南,以及針對阿拉伯語/雙語網站的 RTL 支援,為 AI 代理提供從規劃到部署的完整指引,適合使用 Claude Code、Cursor 等工具的開發者。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/moramadan91/promptory-web-builder/tree/HEAD

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Promptory Web Build

三個工具,一個堆疊,各司其職:

工具角色經驗法則
Lenis滾動引擎 — 在原生生滾動之上提供平滑、慣性的滾動效果僅需全域安裝一次。切勿按區塊安裝。
GSAP (+ ScrollTrigger)動畫引擎 — 自訂時間軸、滾動驅動動畫、固定效果用於此網站設計中的任何客製化需求。
React Bits現成的動畫組件(文字、背景、游標、卡片、按鈕)當目錄組件已能實現所需效果時,優先選用。

它們共享一個動畫循環:GSAP 的 ticker 驅動 Lenis,而 ScrollTrigger 讀取 Lenis 的滾動位置。正確完成此連接是此技能中最重要的一件事(§3)。

範圍:僅限即時網頁/DOM。不適用於影片渲染(Remotion、reels)。

0. 黃金法則 — 不重新設計

實作用戶要求的設計和效果。請勿自行更改版面、顏色、字型、間距或文案,也請勿添加未經要求的額外區塊或「附加」效果。如果某個效果或修正明顯能改善設計,請用一行文字提出建議並等待同意。動畫與品質檢查應服務於現有設計,而非取代它。

0.5 需求調查問卷 — 每個新網站請求的第一步

在為新網站編寫任何程式碼之前,請先執行 references/intake-questionnaire.md 中的需求調查問卷:

  1. 閱讀請求,跳過任何已經回答的部分。
  2. 以最多 3 輪簡短的提問(專案 → 動畫 → 交付)詢問其餘問題。在可用時使用 Claude Code 的 AskUserQuestion 工具(可點擊選項 + 自動「其他」自由文字框);否則,將每輪提問以一個程式碼區塊呈現,每個問題附上帶字母的選項和一個空的「✎ 其他」欄位。
  3. 在一個程式碼區塊中顯示專案簡報,並等待客戶同意。
  4. 然後開始建置,嚴格遵循問卷的答案。

如果用戶說「ابدأ على طول」/「跳過」,請使用 ⭐ 預設值並在簡報中註明。對於現有網站的小型編輯,除非請求不明確,否則跳過問卷。

簡報必須記錄:語言與方向(阿拉伯語/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 並:

  1. 根據適合該行業和目標受眾的指南,從中選出三個方向。
  2. 跳過在此對話或專案中最後三個網站已使用過的方向(風格日誌)。
  3. 在專案簡報中寫下一行文字:方向:<名稱> — <原因>,並附上一個備選方案。
  4. 根據該方向的標誌性選擇進行建置,然後執行多樣性檢查:六個軸向中至少有四個必須與前一個網站不同。

這些方向是關於結構和感覺的參考。切勿複製參考來源的品牌、照片、文案或精確版面。如果客戶提供了設計,請遵循該設計並跳過此步驟(§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. 決策流程 — 哪個工具處理哪個請求

  1. 阿拉伯語、雙語或 RTL 網站 → 在編寫任何版面之前,先閱讀 references/rtl-arabic.md。方向是結構性的;事後調整成本高昂。
  2. 網站上任何地方的平滑滾動 → Lenis(全域提供者,§3)。在任何滾動動畫存在時,於專案設定時執行一次。
  3. 是否有 React Bits 組件已能實現該效果?→ 檢查 references/react-bits-catalog.md → 安裝它(§4)。常見的適用情境:分割/模糊/擾亂文字、滾動揭示文字、動畫背景(極光、粒子、網格、著色器)、自訂游標、磁吸/傾斜卡片、跑馬燈、圖庫、擴充塢/選單、動畫按鈕/計數器。
  4. 效果專屬於此設計(首頁開場序列、固定說故事區塊、水平滾動區塊、同步多元素揭示)→ GSAP 時間軸 / ScrollTrigger(§5,詳細資訊請參閱 references/gsap.md)。
  5. 專案不是 React(純 HTML / Vanilla JS)→ React Bits 不可用;僅使用 Lenis + GSAP(assets/vanilla-setup.js)。
  6. 任何表單、列表、預約或資料驅動的區塊 → references/forms-and-states.md(標籤、錯誤、五種狀態)。
  7. 選擇第三方服務(字型、表單後端、分析、託管、圖片)→ references/free-services.md,然後驗證當前限制。
  8. 沒有客戶設計的新網站 → 先選擇方向(§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 — 挑選和安裝組件

  1. 在 references/react-bits-catalog.md 中找到該組件(分組為:文字動畫、動畫、組件、微型、背景 — 名稱、功能、依賴項)。
  2. 選擇與專案匹配的風格:JS 或 TS,然後 CSS 或 TW(Tailwind)。
  3. 安裝:
    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
    
  4. 在使用前打開已安裝的檔案並閱讀其 props — 每個組件都是可配置的(顏色、速度、延遲、緩動、觸發器)。設定 props 以匹配網站現有的設計 Token(顏色、字型),而不是保留示範預設值。
  5. 如果用戶想要代理工作流程: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 時,無需 pinType hack。
  • 水平滾動區塊:固定包裝器,將軌道的 x 補間到 -(track.scrollWidth - innerWidth),scrub: true,invalidateOnRefresh: true。在 RTL 中,反轉方向(請參閱 references/rtl-arabic.md §6)。
  • 將裝飾性區塊包裹在 gsap.matchMedia() 中,以便減少動畫的用戶獲得替代方案(`references/accessibility-

…

[原文已截斷以進行翻譯]

相關技能