brandvm/webflow-prototype

Webflow 原型：Figma 設計 → 已核准的本機原型

專案的第一階段。每個網站都從 Figma 檔案開始，其設計以程式碼建置，使用與 Webflow 相同的 URL 和斷點、相同的變數與類別名稱，並逐頁獲得核准。最終產出的不是模擬圖：而是 Webflow 建置階段所依據的標記、類別、模組與手動步驟清單。

此階段絕不寫入 Webflow。 它讀取網站（快照）並提出變更；寫入操作屬於 webflow-build 技能，在原型獲得核准後於其專屬工作階段中進行。

• checklists.md 控管輸入、每個原型頁面以及移交。
• prototype-starter/ 是專案起始的原型資料夾（pnpm new-project 會複製它）。
• figma.md 透過 Figma 連接器讀取 Figma 檔案：每個斷點的影格、螢幕擷取畫面、變數、尺寸。
• 從影格建置單一頁面的步驟位於 webflow-build（SKILL.md › 原型，從 Figma 開始），與 Bench 的 AI 遵循的步驟相同。其 checklists.md 的 原型 階段會追蹤原型直到客戶核准。
• webflow-style-guide 技能負責建立樣式指南，也就是原型的第一頁。
• conventions.md（位於 webflow-build）設定原型遵循的頁面與區段結構以及類別與變數命名規則；lessons/ 記錄過去耗時較長的建置經驗。
• rules.md 包含所有 Webflow 技能共用的規則（未經確認不得提交或推送、先使用 Designer、聊天中不包含憑證）、工作階段總結與如何回饋。

每個檢查清單項目都會標明執行者：[Claude]、[Claude 檢查]（Claude 驗證並回報；人員修正 Claude 無法處理的部分）或 [人員]（Claude 可以提醒並追蹤，但從不執行）。

工作階段開始（每個工作階段）

1. 讀取工作區的 CLAUDE.md，然後是儲存庫的 AGENTS.md 和 GOTCHAS.md，最後是 docs/handoff/。瀏覽 lessons/README.md；lessons/mcp.md 中的匯入課程決定了原型標記的撰寫方式。
2. 讀取專案記憶：上一個工作階段停在哪裡、哪些問題待解決。用一句話說明目前狀態及下一步。
3. 對於新專案，首先執行 checklists.md 中的 原型開始之前。如果缺少輸入，請要求提供；不要猜測內容、狀態或 SEO 欄位。
4. 原型開發伺服器正在執行（在 prototype/ 中執行 pnpm dev）。
5. 今天的工作範圍是一個頁面。說明是哪一個。

專案設定（新專案）

在 Bench 中， 從 Figma 設計新增客戶會設定客戶資料夾、從此範本建立的儲存庫以及一個空的 prototype/，然後根據人員選擇的影格建立原型（步驟 6）。人員的步驟（4）和輸入仍然適用。

不在 Bench 中， 流程從一條訊息開始（README › 啟動專案），例如 「新專案：Webflow 網站 <名稱>，Figma <連結>。設定儲存庫和工作區，執行「原型開始之前」，然後根據 Figma 檔案逐頁建立原型；在我同意之前，等待我的指示再進行任何 Webflow 變更。」

在此之前，人員已從 GitHub 上的範本建立儲存庫，將其複製到自己的客戶資料夾中（<Client>/wf-<client>/），並在客戶名稱下複製了入門網站（starter-site.md）。

1. 技能優先。 提供 pnpm update-skills（詢問；它會取代本機技能編輯），以便專案從最新的課程開始。

2. 尋找網站。 透過 Webflow 連接器，列出網站並比對人員提供的名稱：網站 ID 和短名稱（暫存子網域，<短名稱>.webflow.io）。兩個相符或無相符 → 詢問。從 git remote get-url origin 讀取 GitHub 組織和儲存庫。

3. 填入儲存庫並設定工作區：

   pnpm install
   pnpm new-project --client "<客戶>" --slug <短名稱> --org <組織> --site-id <ID>
   

   它會填入 AGENTS.md 中的專案事實、package.json 的名稱、loader.html 中的 REPO 以及移交標題，並寫入 webflow-build.config.json。它還會在工作區周圍建立：<Client>/CLAUDE.md（匯入 AGENTS.md、GOTCHAS.md 和 docs/handoff/）、.mcp.json、技能連結、prototype/（prototype-starter/ 的副本）和 Assets/。將 Figma 連結寫入工作區 CLAUDE.md（設計行）。對於找不到的值，請詢問；切勿猜測。

4. 按此順序列出人員的步驟， 並在 docs/handoff/MANUAL-TODO.md 中追蹤直到完成：

   1. 儲存庫設定 → 頁面 → 來源：GitHub Actions；新增開發人員團隊。
   2. 首次推送：Claude 要求提交設定；推送後暫存工作流程必須通過（https://<組織>.github.io/<儲存庫>/styles.css 必須載入）。
   3. 從 loader.html 貼上載入器（ORG 和 REPO 現在已填入）：<head> 程式碼和頁尾代碼在網站設定中。嵌入程式碼 2a 和 2b 已位於 G | 帶有預留位置的元件中：Claude 會在獲得許可後透過 MCP 填入它們，或者人員貼上它們。
   4. 暫存密碼和 noindex 直到啟動。

5. 移至工作區。 從下一個工作階段開始，Claude 在 <Client>/ 中開啟，而不是在儲存庫中：這是 MCP 伺服器、技能和匯入設定的地方。在 prototype/ 中執行 pnpm install。

6. 輸入，然後是原型。 執行 checklists.md 中的 原型開始之前（包括元件計劃和影片清單），讀取 Figma 檔案（figma.md），取得 Webflow 快照，並從檔案建立原型：先建立樣式指南（webflow-style-guide 技能），在任何內容頁面之前獲得核准，然後根據選取的影格逐頁建立（webflow-build › 原型，從 Figma 開始），每個頁面都要通過 原型頁面完成。

7. 根據設計填寫 docs/handoff/HANDOFF.md；從第一個工作階段開始保持 MANUAL-TODO.md 和 BUILD-NOTES.md 為最新狀態。

原型

• 它鏡像 Webflow： 相同的 URL、相同的斷點（991、767、479）、Webflow 類別名稱，以及 conventions.md 的頁面外殼和區段結構。導覽和頁尾是單一的部分（每個一個元件）。
• 它標記元件和 CMS： 在元件實例的根元素上使用 data-component="<元件名稱>"（導覽和頁尾部分已有各自的）、在元件屬性設定的元素上使用 data-prop="<屬性名稱>"、在集合列表包裝器上使用 data-collection="<集合名稱>"，以及在綁定到 CMS 欄位的元素上（在列表項中或在 CMS 範本頁面上）使用 data-field="<欄位名稱>"。視覺上沒有任何改變，並且它們不會在 Webflow 中建立，Webflow 有自己的元件和 CMS 綁定（prototype-starter/README.md › 元件和 CMS 標記）。
• 它從 Webflow 快照讀取網站的變數（prototype-starter/README.md › Webflow 快照）。在寫入或重新整理快照之後：pnpm css，然後 pnpm check:snapshot，然後 pnpm check:drift，它將快照與暫存網站發布的樣式表進行比較，並列出每個不同的變數、類別和值（先發布到暫存）。
• 沒有 Webflow 連接器？（尚未設定、已登入其他網站，或不允許 MCP 呼叫）pnpm css:published <暫存 URL> 會從網站發布的 CSS 建立 tokens.css、webflow.css 和 webflow-base.css（僅 GET；逐頁讀取每頁 CSS 並合併），並盡可能恢復快照。CSS 是準確的；Designer 名稱、模式名稱、空類別和互動不包含在內（腳本的標頭會列出它猜測的所有內容），因此在 HANDOFF.md 中說明快照是替代品，切勿在未在 Designer 中檢查的情況下使用猜測的名稱提出變數或類別，並在連接器可用時立即從 MCP 替換快照（刪除 webflow-snapshot/source.json，然後 pnpm css）。當 source.json 存在時，pnpm css 拒絕執行。
• 變更提案，從不直接修改： 以舊 → 新的形式放在 proposed.css 中，分組並標上字母以便核准。新類別放在 new-classes*.css 中，以 Designer 可以處理的方式撰寫。
• 標記是為匯入器而寫： 形狀使用 div，而不是空的 span；表單控件放在 <form> 中；布林屬性帶有值；換行前有  ；模組依賴 data-* 鉤子，而不是類別名稱。pnpm wf:preflight 會檢查所有這些。

順序。

1. 快照，pnpm css，pnpm check:snapshot，pnpm check:drift（無連接器：pnpm css:published，然後執行相同檢查）。
2. 樣式指南（webflow-style-guide 技能），在任何內容頁面之前獲得核准。
3. 頁面，一次一個，根據它們的 Figma 影格（webflow-build › 原型，從 Figma 開始）。對於每個頁面：建立它；為引入的每個類別或元件新增一行（pnpm style-guide）；pnpm screens（從 2560 到 360 的每個寬度：溢出和錯誤）和 pnpm check:states（焦點和按下狀態）；執行 原型頁面完成；人員在 1440、820、667 和 390 寬度下核准它。
4. 客戶以書面形式核准原型。
5. 移交（如下）。

移交給建置階段

執行 checklists.md 中的 原型移交。建置工作階段從以下套件開始：

• docs/handoff/HANDOFF.md：頁面、變數和類別、CMS、要建立的元件、模組及其鉤子、影片清單。
• pnpm wf:styles：每個新類別，分類為連接器可以建立的、人員需要在 Designer 中手動設定的（已在 MANUAL-TODO.md 中列為工作項目）以及屬於儲存庫 CSS 的。
• pnpm wf:preflight：每個頁面已知的匯入器步驟。
• 已核准的原型本身，正在執行中，作為建置比對的參考（pnpm wf:compare，wf:pass）。

然後給人員一條訊息，內容已填寫好，用於在建置工作區中開啟的新工作階段中貼上：

繼續 <客戶>：在 Webflow 中建置。原型已核准（所有頁面和樣式指南，<日期>）。讀取工作區 CLAUDE.md、docs/handoff/ 和 webflow-build 技能。從基礎開始：從 proposed.css 提出變數批次，並在每次 Webflow 寫入之前等待我的許可。然後標記樣式、類別（根據樣式計劃）、CMS 集合、儲存庫埠和載入器、樣式指南頁面、媒體頁面（如果影片清單中有項目）、元件和頁面，每個工作階段一個頁面。

建置在其自己的工作階段中運行，以便僅載入建置規則，並保持原型不變作為參考。

工作節奏

• 每個工作階段一個頁面，完整完成： 建立、在每個寬度下檢查、其狀態完成、執行 原型頁面完成、更新移交。
• docs/handoff/ 在工作階段期間保持最新狀態，而不是在結束時：做出決定時即寫入 HANDOFF.md。
• 回饋經驗教訓。 在總結時，將每個 template-candidate 課程提供給範本（rules.md › 貢獻）。