brandvm/webflow-build

Webflow 建置：批准的設計 → Webflow，逐區塊

所有人批准每個設計決策；Claude 負責建置、驗證和回報。只有當一個區塊在每個寬度下都符合批准的設計、在每種進入方式下都正常運作，且其手動步驟都已列出時，該區塊才算完成。

• checklists.md 掌控每個步驟的大門：設計交接、Webflow 基礎、媒體頁面、每個元件、每個完成的頁面以及建置交接。其進度記錄在 docs/handoff/progress.json 中，使用 pnpm progress（checklists.md › 如何記錄進度）來記錄，Bench 的任務面板會顯示這些進度。
• conventions.md 設定頁面和區塊結構、類別和變數命名，以及每個建置專案都從其開始的元件、CMS 和樣式指南模式。
• lessons/ 按領域記錄了在早期建置中耗費時間的事項。在準備進行某個領域的工作前，請先閱讀該領域的檔案。
• 原型永遠優先：它是根據 Figma 檔案逐頁建立的（在 Bench 中，或由 Claude 在終端機中使用相同步驟建立），並且客戶在 Webflow 中建置任何內容之前就必須批准它。步驟如下（原型，來自 Figma）；webflow-prototype 技能包含專案設置、輸入、快照和樣式指南，而其 figma.md 說明了如何讀取 Figma 檔案。
• rules.md 包含所有 Webflow 技能共享的規則（未經確認不得提交或推送、優先使用 Designer、聊天中不包含憑證、手動步驟、經驗教訓）、會話總結以及如何貢獻回饋。
• starter-site.md 描述了專案會複製的起始 Webflow 網站，其中已包含基礎系統。
• webflow-style-guide 技能會建立樣式指南頁面，這是原型和 Webflow 建置中的第一個頁面，採用每個網站都使用的同一種版面配置。
• media.md 是媒體頁面：網站影片上傳到這裡，以便 Webflow 進行轉換和託管，並且會在播放第一個影片的頁面之前建立。
• 已經上線的網站不屬於建置：請使用 webflow-audit 技能（先稽核，然後進行小批量驗證；也適用於一次性修復）。
• 建置交接後，webflow-launch 技能會接手：上線前 QA、上線日、客戶交接以及前 30 天。

每個檢查清單項目都會說明由誰執行：

• [Claude] Claude 執行（透過 MCP、儲存庫或腳本）。
• [Claude 檢查] Claude 驗證並回報；Claude 無法處理的部分由人員修復。
• [人員] 由人員執行（客戶、專案經理、設計師、DNS、帳戶）。Claude 可以提醒和追蹤，但絕不能代為執行。

會話開始（每次會話）

1. 讀取工作區的 CLAUDE.md，然後讀取此儲存庫的 AGENTS.md 和 GOTCHAS.md，接著讀取 docs/handoff/（HANDOFF.md、MANUAL-TODO.md、BUILD-NOTES.md，以及如果審查階段已開始則讀取 REVIEW.md）。瀏覽 lessons/README.md 並閱讀今天工作領域的經驗教訓檔案（MCP 工作：lessons/mcp.md）。切勿重複已記錄的錯誤。
2. 讀取專案記憶：上次會話在哪裡停止、未完成的手動步驟、未解決的問題。執行 pnpm progress show 以查看階段、仍開放的檢查清單以及人員自己的待辦事項。用一句話說明當前狀況和下一步；如果不明確，請詢問要處理哪個頁面或區塊。
3. 在第一批 Webflow 操作之前，執行 checklists.md 中的 建置前 檢查；在原型完成之前執行 原型 階段（輸入內容來自 webflow-prototype）。與設計師協商同意對 conventions.md 的任何變更。如果缺少輸入內容，請提出要求；不要猜測內容、狀態或 SEO 欄位。
4. Webflow MCP：呼叫 webflow_guide_tool 一次，然後在整個會話中重複使用同一個 session id 和 agent id。
5. 原型開發伺服器正在執行，且 webflow-build.config.json 已存在（pnpm new-project 會建立它；webflow-prototype › 專案設置）。
6. 今天的範圍是一個頁面（參見工作節奏）。請說明是哪一個。

常設規則

共享規則在 rules.md 中。建置技能增加了以下規則：

• 在建立、編輯或移除類別和變數之前，必須先詢問，一次一批，並提供名稱和值。一個明確暗示這些操作的請求（例如在批准模型後說「在 Webflow 中建置它」）即視為確認同意。
• 發布與網站是否上線有關。
  • 新建置（未綁定自訂網域）： 發布到 webflow.io 暫存網域是可以的。
  • 已上線網站： 發布是整個網站範圍的。它會將所有待處理的項目一併送出，包括其他人未完成的編輯。僅發布到暫存環境，檢查還有哪些內容會一起上線，並等待人員輸入「publish」後才能發布到自訂網域（webflow-audit 有相關步驟）。
  • 未經詢問，絕不能發布到自訂網域、建立版本或變更 DNS。
• 在每次 Webflow 寫入批次完成後，必須說明兩件事：「重新載入 Designer」（已開啟的 Designer 分頁不會顯示 MCP 的變更，而從過時的分頁儲存可能會覆蓋這些變更），以及哪些內容尚未發布。
• 在頁面上標記手動步驟。 對於 MANUAL-TODO.md 中會留下明顯未完成事項（例如值仍缺失、綁定未建立）的行，請在元素旁邊或樣式指南上的樣本旁邊放置一個標記：一個帶有 data-manual-todo="<字母>" 和文字「手動步驟 <字母>: <說明>」的 Caption。它會顯示在畫布和暫存環境上，這樣就不會有人將未完成的狀態視為設計稿來審查。在完成該行的批次中移除此標記；在建置交接或上線時，不得留下任何此類標記（在已發布的 HTML 中搜尋 data-manual-todo）。

原型，來自 Figma

每個網站都從一個 Figma 檔案開始。原型是根據該檔案逐頁建立的，並在 Webflow 中建置任何內容之前獲得批准。

在 Bench 中。 新增客戶 › 從 Figma 設計設定客戶資料夾、從此模板建立的儲存庫和一個空的 prototype/（prototype-starter/ 的副本）。從 Figma 建置原型將圖框分組為頁面；人員選擇並排序它們，每個頁面都有自己的網址。然後一個 AI 任務會逐頁建置它們：每個頁面以一條獨立訊息的形式出現，其中包含其圖框的節點 ID。每個建置的頁面都會保留其 Figma 圖框，以便使用「與 Figma 比對」功能進行比較。Bench 會在客戶打開檔案時以及每小時重新檢查檔案，並提供更新圖框已變更的頁面：僅變更這些圖框中實際變更的部分，並保留自上次在原型中進行的編輯。

不在 Bench 中時， Claude 在終端機中遵循相同的步驟：列出圖框，與人員協商同意頁面、其順序和網址，然後一次建置一個頁面。

一個頁面：

1. 其圖框。 在桌面、平板和行動裝置上具有相同名稱的圖框構成一個頁面。使用 Figma 連接器（get_design_context、get_screenshot、get_variable_defs）或 Figma 應用程式的 MCP 伺服器（figma.md）讀取每個圖框。如果沒有平板圖框：在桌面和行動裝置之間繪製平板版本。如果沒有行動裝置圖框：從較大的圖框使其能在手機上運作，並說明這一點。非頁面的圖框（例如樣式指南）則用於讀取代號、類型和元件。
2. 代號來自檔案的變數和文字樣式，作為 CSS 自訂屬性：對快照變數的變更以及 src/css/proposed.css 中的新變數（舊 → 新），按照 conventions.md 第 4 節命名；切勿在自動產生的 tokens.css 中修改。
3. 字型由文字樣式使用，放在 public/fonts/ 中並包含其授權，在 src/css/prototype.css 中宣告，並在 partials/head.html 中預載入。
4. 圖片從檔案匯出到 prototype/images/：照片匯出為設計中使用的最大尺寸的 WebP 格式，圖示匯出為 SVG 格式。
5. 僅包含檔案中的內容。 檔案中未提供的值、狀態、文字或圖片是一個問題：在編造之前先詢問（在 Bench 中，使用 mcp__bench__todo_add 新增並繼續進行）。
6. 放置位置： prototype/<頁面>/index.html，使用其 Webflow 網址（首頁是 prototype/index.html），並新增到 prototype/vite.config.js 的 pages 中。導覽列和頁尾是共享的局部模板。僅更改該頁面，以及它需要的局部模板和代號。不要提交、推送或發布。
7. 檢查它在桌面、平板和行動裝置上是否與其圖框相符，以及 Figma 原型的連結是否正常運作（選單、分頁、表單）。

然後該頁面執行 原型頁面完成（webflow-prototype 的 checklists.md），並且人員批准它（在 Bench 中：在頁面上按右鍵）。checklists.md 中的 原型 階段會追蹤所有內容，直到客戶書面批准：

• 每個頁面在桌面、平板和行動裝置上都與其 Figma 圖框相符（Bench 的「與 Figma 圖框相符」檢查）；
• Figma 檔案已連結到客戶；
• 已選取圖框，按順序排列，每個都有其頁面網址；
• 每個選取的圖框都已建置為原型頁面；
• 代號、字型和圖片來自檔案；沒有虛構的內容；
• Figma 原型的連結正常運作；
• 每個頁面都在原型中獲得批准；
• 客戶已書面批准原型。

建置順序

在 原型 階段完成後開始。結構和名稱遵循 conventions.md。每個步驟都由 checklists.md 中的檢查清單控制：

1. 變數；
2. 標籤樣式（在 Designer 中設定一次，以便 MCP 可以存取它們）；
3. 類別；
4. CMS 集合；
5. 儲存庫連接埠（來自原型的模組和儲存庫 CSS）和載入器，以便暫存環境執行實際程式碼 → 基礎完成；
6. 樣式指南頁面，第一個建置的頁面（webflow-style-guide 技能）→ 樣式指南基礎完成；
7. 媒體頁面，當任何頁面播放影片時建置（media.md）→ 媒體完成；
8. 元件，從實際頁面標記（而非樣式指南預覽）建置，每個元件新增其樣式指南行 → 元件完成；
9. 頁面，逐區塊建置 → 頁面完成；
10. 樣式指南最終檢查，然後是 建置交接；
11. 審查階段：docs/handoff/REVIEW.md 列出每個頁面建置了什麼、每輪反饋以及上線前還剩下什麼，直到 webflow-launch 技能接手。

從起始網站複製的專案已經具有步驟 1 到 3 的基礎和頁面外殼；專案會在此基礎上新增內容。在每次匯入之前執行 pnpm wf:preflight；使用 pnpm wf:styles 規劃類別批次（參見檢查）。

區塊循環

對於每個區塊，按頁面順序：

1. 讀取原型：其標記、CSS 以及負責動畫效果的模組，並參考頁面的 Figma 圖框以了解狀態和互動規格。記錄每個 data-* 鉤子、id 和 aria 屬性。
2. 檢查 Webflow 有什麼：類別（query_styles）、元件及其屬性、CMS 欄位、資產。在建立之前先重複使用；根據 conventions.md（第 2–4 節）命名任何新內容。
3. 建置，按順序優先使用：
   • 元件實例；
   • 用於 DOM 元素的元素建置器（例如 button、當 ARIA 角色必須保留時的 ul/li、svg、帶有標籤的 span），包含巢狀子元素；
   • 用於純標記的 WHTML 匯入，然後修復它丟棄的內容（請參閱下面的匯入程式檢查清單）。 頁面內容位於 G | Page W 元件的 G | Main 插槽中。對於插槽仍為空的頁面：在 G | Page W 之後，在一個 To Slot 包裝器中建置區塊，要求人員將包裝器拖曳到插槽中，然後取消群組（將每個子元素移到包裝器之前，移除包裝器）。一旦區塊位於插槽中，就直接在其旁邊建置（conventions.md 第 1 節）。使用 query_elements 檢查插槽內容；頁面樹會將插槽顯示為空。
4. 連接屬性、CMS 綁定、屬性值、連結、表單設定。
5. 發布，然後執行檢查。修復、重新發布、重新檢查。
6. 回報：建置了什麼、哪些相符、哪些不同及其原因、手動步驟，以及等待提交確認的檔案。

當一個頁面完成時，在 checklists.md 中執行 頁面完成。

匯入程式檢查清單（每次 WHTML 匯入後）

• <button> 變成了連結 → 重建為 DOM button，將子元素移入。
• <img> 遺失了所有屬性和其資產連結 → set_image_asset，重新新增 data-*、loading、尺寸（或一個帶有 aspect-ratio 的類別）。
• <span> 變成了文字 Span → 形狀作為 <div>；文字片段作為 DOM span（否則編輯父元素的文字會將它們合併）。
• 一個缺少一個類別的類別清單會遺失 所有 類別 → 先建立類別，重新檢查 styleNames。
• DOM 元素保留了一個字面的 class 屬性 → remove_attribute class。
• <br> 前的正常空格會被修剪 → Line.&nbsp;<br>Next。
• 布林屬性需要一個值（muted="true"），否則發布時會丟棄它們。
• 清單發布為 role="list" → 在 DOM ul/li 上保留 ARIA 角色。

畫布衛生

• 空元素上的每個類別：所有邊的 padding 設為 0，以及 font-size: inherit（畫布的 .wf-empty 會新增 75px padding 和 font-size 0）。
• 每個網格至少設定一個行模板和一個列模板；使用 flex 居中單個子元素，而不是網格。
• 僅由偽元素（例如圖示字型字形）繪製的元素會得到一個空格作為其文字（set_settings，key text），這樣它在畫布上就不會顯示為空的元素。

…

[為翻譯而截斷]