nikbearbrown/figma-webdesigner

網站設計審查 → 線稿圖 → 決策總帳

目的

將本機克隆的網站轉變為：(1) 固定到 git 提交的雜湊證據，(2) 每個發現都引用規則並指向可能的原始碼檔案，(3) Figma 中的現狀與目標線稿圖，(4) 解釋每個變更的決策記錄，(5) 人工核准記錄，以及 (6) 供 Claude Code 或 Codex 在獨立工作階段中執行的核准決策實作摘要。git 總帳是唯一真實來源。Figma 是其投影。此技能只負責設計與記錄；它從不編輯網站的原始碼。

預期工作流程

1. 學生克隆其網站的儲存庫（來自 GitHub，或 Vercel 專案部署的儲存庫）並在本機執行。學生應具備 Figma MCP 的教育版存取權。
2. 此技能從本機開發伺服器擷取、審查，並在 Figma 中建立線稿圖。
3. 人員處理發現、審查決策並核准。
4. 此技能為每個核准的決策撰寫交接摘要。Claude Code 或 Codex 在其各自的獨立方枝上實作每個決策。此技能會重新擷取以進行驗證。

命令

技能資料夾中有一個命令 fwd 和一個 CLAUDE.md，說明如何回應。當使用者輸入 help、check、init 或 tutorial 時，請遵循 CLAUDE.md：

• help 執行 fwd help（設定檢查加上一個後續步驟），並在 Figma 工具存在時，執行 whoami 以取得座位資訊。先找出缺少項目；只給一個後續步驟；不以學生名義進行任何變更。
• tutorial 執行七步驟的第一個教學課程（重新設計你的首頁）。這是此技能自己的階段，逐步驅動。
• fwd approve|reject|defer <D-id> 是學生在其自己的終端機中執行的命令。它會寫入核准檔案與總帳事件。不可協商第 1 點適用：永遠不要執行它，永遠不要寫入 audit/approvals/。
• fwd ledger verify 檢查雜湊鏈，並確保每個核准檔案都與總帳相符。

不可協商事項

1. 只有人類才能將決策設為已核准、已拒絕或已延期，或重新開啟決策。絕對不要寫入這些狀態。絕對不要寫入 audit/approvals/ 中的檔案。
2. 每個發現都必須引用 audit/rulebook/rules.yaml 中的 rule_id。沒有規則就沒有發現：將其記錄為給人類的 observation。
3. 發現標籤遵循規則層級：規範性 → failure、啟發式 → concern、自訂 → deviation。絕對不要將啟發式發現稱為失敗。絕對不要在啟發式發現上使用通過/失敗圖示或文字（✅ ❌ "violated"）。
4. 現狀影格與其目標影格之間的每個差異都必須帶有至少一個決策 ID。標記未標籤的差異；不要吸收它們。
5. 絕對不要編輯 00 As-Is 頁面。絕對不要修改或刪除此技能未建立的節點。只觸碰此技能自身類別中的註釋，並始終遵循讀取-合併-寫入。
6. 絕對不要設定開發模式狀態（Ready for dev / Completed）。絕對不要解決或刪除人類留言。
7. 在人類儲存已命名的基準版本並記錄其 ID 之前，不要對現有 Figma 檔案進行寫入。例外情況：此執行自身建立的 Figma 檔案。它從空檔案開始，因此空檔案本身就是其基準；將其記錄在 capabilities.json 中。
8. 僅從使用者擁有或擁有處理權限的儲存庫之本機克隆、從 localhost 提供服務，或當使用者提供 URL 時，從已部署的網站或同一儲存庫的 Vercel 預覽中進行擷取。絕對不要擷取、注入腳本或移除第三方即時網站的安全標頭。intent.yaml 必須記錄儲存庫與固定的提交。
9. 絕對不要覆蓋先前的發現影格或更早的執行輸出。重新執行會建立一個新的版本化影格（請參閱階段 7）。絕對不要透過圖層名稱、填色顏色或文字啟發式來定位你自己的節點；使用總帳中記錄的節點 ID。
10. 絕對不要編輯網站的原始碼。實作只會在獨立的 Claude Code 或 Codex 工作階段中，根據核准決策的交接摘要進行。

目錄結構

audit/
  intent.yaml                 # 人工填寫（階段 0）
  rulebook/rules.yaml         # 人工確認（階段 1）
  schema/                     # 發現、決策、核准、事件綱要
  runs/R-YYYYMMDD-NN/
    capabilities.json         # 此執行實際能做的事情
    manifest.json             # 擷取雜湊與狀態
    captures/{width}/         # screenshot.png, dom.html, axe.json, checks.json, skeleton.json
    findings.json
  decisions/D-NNNN.json
  approvals/A-NNNN.json       # 僅人類
  handoff/                    # 實作摘要，僅核准的決策
    README.md                 # 給實作代理人的共用規則
    D-NNNN.md                 # 每個核准決策一個摘要
  ledger.jsonl                # 僅可附加，雜湊鏈結事件

網站的克隆位於 audit/ 之外（位於 local_path）。此技能讀取它，但從不寫入它。audit/ 可以位於同級資料夾或自己的分支上，這樣審計記錄永遠不會與網站提交混在一起。

階段 0 — 意圖（閘門 G0）

如果 audit/intent.yaml 遺失或必要欄位為空，請以對話方式一次一兩個詢問缺少的欄位。在使用者填寫所有必要欄位之前，不要進行擷取、評估或寫入。如果使用者尚未克隆儲存庫，請在其自己的程式碼區塊中給予他們確切的 git clone 命令（對於 Vercel 專案，即其部署來源的 GitHub 儲存庫）並等待。

repo: ""                      # 必要：網站的 GitHub URL（或 Vercel 專案）
local_path: ""                # 必要：本機克隆的路徑
commit: ""                    # 必要：審查鎖定的提交 SHA
dev_command: ""               # 必要：例如 "npm run dev"
dev_url: "http://localhost:3000"
routes: []                    # 必要：要審查的路徑，例如 ["/", "/apply"]
ownership: ""                 # 必要："own repo"，或授予權限的人員及時間
implementer: ""               # 必要："claude-code" 或 "codex"
conformance_target: "WCAG 2.2 AA"
breakpoints: "derive"         # "derive" 從網站 CSS 推導，或寬度列表
house_rules: ""               # 設計系統 token 的路徑，或 "none"
figma_file: ""                # Figma 階段必要；空白 = 僅 JSON 模式
approvers: []                 # 必要：姓名與角色
out_of_scope: []

階段 1 — 綱要（閘門 G1）

總結規則手冊（按層級與模式統計的規則數量）與記錄綱要。要求使用者確認或編輯。記錄一個 schema.confirmed 總帳事件，包含使用者姓名與日期。在未獲得確認的情況下不要繼續。

執行時期能力探測

在階段 2 之前，寫入 capabilities.json：

• 有哪些 Figma MCP 工具可用（use_figma、generate_figma_design、html_to_figma、get_metadata、get_screenshot、generate_diagram、upload_assets）。
• whoami 結果：擁有 figma_file 的方案的座位類型。如果無法寫入，設定 mode: json-only 並跳過此執行的 Figma 寫入。學生應具備教育方案存取權；但仍要記錄實際座位與方案，而非假設，並記下任何速率限制錯誤。
• 本機環境：Node 與套件管理器版本，dev_command 是否啟動，以及 local_path 的工作目錄是否乾淨且處於 commit 狀態。
• 在每次 use_figma 呼叫之前載入 Figma 的 figma-use 技能。
• 讀取即時 use_figma 工具綱要，並記錄它是否接受 skillNames 參數。一個可比較的 Figma 技能（Throughline）在每次呼叫時傳遞 skillNames: "throughline"。如果該參數存在，則在每次 use_figma 呼叫時傳遞 skillNames: "figma-webdesigner"；如果不存在，則記錄 skillNames: unsupported。
• 從第一次執行（2026-11-07，完整學生座位）已知，請重新驗證而非假設：setSharedPluginData 有效；addAnnotationCategoryAsync 與 node.annotations（帶有 labelMarkdown 與 categoryId）有效；figma.saveVersionHistoryAsync 不支援，因此代理人永遠無法建立基準版本；figma.root.name 不可設定，因此無法透過 API 重新命名檔案。如果其中任何一項現在失敗，則在影格名稱中攜帶決策 ID 作為 ⟦D-0007⟧ 加上註釋，並記錄結果。
• 在呼叫 create_new_file 時，為網站命名 Figma 檔案（例如 jobs.humanitarians.ai）；之後無法重新命名。頁面是階段（00 Kit & Legend、01 As-Is Wireframes、02 To-Be Wireframes）；影格是 page / width / as-is|to-be / state。

use_figma 腳本慣例

此技能透過 use_figma 發送的每個腳本都必須遵循以下規則：

0. 高度相等的同層級子元素需要 layoutSizingVertical = 'FILL' 在每個子元素上（且僅有 layoutAlign = 'STRETCH' 在父元素高度貼合內容時是不夠的）。在中心或表格儲存格中需要換行的文字需要 textAutoResize = 'HEIGHT' 以及一個寬度。
1. 字型優先。 在一個頂層的 Promise.all 中呼叫 figma.loadFontAsync 載入腳本使用的每種字型樣式（包括斜體與中等字重，如果使用），然後再建立或編輯任何文字。
2. 在設定父元素後設定大小。 將每個節點附加到其父元素，然後設定 layoutSizingHorizontal 與 layoutSizingVertical。僅使用已記錄的屬性名稱（使用 cornerRadius，而非 corner）；未知屬性會被靜默忽略。
3. 回傳寫入收據。 腳本必須回傳一個物件，包含 createdNodeIds 與 mutatedNodeIds（兩者都必須誠實填寫；僅在未發生此類事件時才使用空陣列），加上 frameId、stamped（是否已寫入外掛資料）與 pageId。
4. 將收記錄入總帳。 每次呼叫後，附加一個 figma.write 事件，其中包含收據、執行 ID、涉及的決策 ID 以及 version_before。後續階段透過這些 ID 尋找技能擁有的節點，絕不透過名稱或顏色。
5. 變更的前置狀態。 如果腳本變更任何現有節點（技能建立節點上的註釋、文字、填色），請在收據中回傳先前的值，以便總帳可以記錄它們。不允許在未記錄前置狀態的情況下進行覆寫。
6. 失敗時要大聲。 不要靜默成功。如果查詢找不到任何結果，回傳一個錯誤，列出找到的內容；絕不要將無操作報告為成功。

階段 2 — 擷取

0. 準備克隆。確認 local_path 處於 commit 狀態且工作目錄乾淨（如果不是，記錄 dirty: true 並停止詢問），安裝相依套件，啟動 dev_command，並確認 dev_url 有回應。在 manifest.json 中記錄提交 SHA、髒污標記與 Node 版本。不要修改任何原始碼檔案。如果專案需要不存在的環境變數或秘密，請詢問使用者；絕對不要自行編造。
1. 從儲存庫自己的配置（Tailwind 配置、CSS 自訂媒體查詢、框架主題）以及從網站計算出的 CSS 媒體查詢中推導斷點（除非意圖中列出了寬度）。在 320、每個斷點減一與斷點處，以及一個大桌面寬度處進行擷取。
2. 每個寬度：全頁截圖、DOM、axe-core 結果（標籤 wcag2a、wcag2aa、wcag21aa、wcag22aa）、溢出檢查、目標幾何檢查、結構骨架（地標、標題、帶有邊界框的互動群集）。
3. 在 manifest.json 中記錄擷取狀態（同意橫幅、身分驗證、變體）以及每個檔案的 SHA-256。
4. 附加一個 capture.completed 事件。

階段 3 — 測量

執行自動化與輔助檢查。自動化結果直接成為發現。輔助結果成為帶有 mode: assisted 與 triage: null 的發現；註明可能適用的例外情況（間距、內聯、等效、必要、資料表）。

原始碼對應。 對於每個發現，在克隆中搜尋該元素的原始碼（其文字、類別名稱、元件名稱或資料屬性），並記錄 source: {file, line, confidence}。這是盡力而為：對於猜測使用 confidence: low，如果未找到位置則省略 source 而非聲稱找到。這些是給實作者的提示，而非指示。

階段 4 — 評估

執行啟發式檢查。對於每個發現記錄：

• rule_id、定位器、證據路徑與雜湊
• 嚴重性 0–4（Nielsen：頻率、影響、持續性）
• 信心水準（高/中/低）
• scope：single-section、cross-section、component、interaction 之一
• 關於證據顯示內容的一句陳述

範圍指引：

• single-section：問題位於一個頁面的一個區塊內。
• cross-section：問題僅跨區塊、頁面或寬度出現（優先順序與視覺順序、不一致的模式、在頁面間變化的導覽）。請刻意尋找這些；它們通常影響最深遠，且最容易在逐區塊審查時被忽略。
• component：一個可重複使用的元素在其出現的任何地方行為或外觀不一致。
• interaction：問題存在於狀態、流程或行為中，而非靜態佈局。

對於長頁面，從其各自截圖評估每個區塊並記下 y 位置；然後針對跨區塊發現進行單獨的檢查。僅包含有足夠可見證據的規則；跳過無法從擷取內容評估的規則，而不是猜測。將自己視為一個評估者；在發現摘要中說明。

閘門 G2 — 分類

按嚴重性分組呈現發現，然後按頁面分組，以表格形式呈現：ID、規則、標籤、範圍、頁面/寬度、嚴重性、信心水準、一行證據。要求使用者接受、拒絕或重新評分。將每個分類呼叫記錄為歸屬於使用者的總帳事件。只有被接受的發現才會繼續前進。

階段 5 — Figma 基準（閘門 G3）

1. 透過 generate_figma_design（或 html_to_figma）將現狀截圖擷取到頁面 00 As-Is，每個顯示結構變化的擷取寬度對應一個影格。
2. 從 skeleton.json 在頁面 01 As-Is Wireframes 上建立結構性現狀線稿圖，如果 search_design_system 找到檔案中的線稿圖工具包則使用它。
3. 交接：要求使用者鎖定 00 As-Is 並儲存一個名為 baseline R-… 的已命名版本，然後給你其版本 ID。你無法自己儲存版本。
4. 將 ID 記錄為 version_before。在獲得它之前不要進行進一步寫入。

階段 6 — 提案

1. 將接受的發現分組為決策。每個 D-NNNN.json：標題、發現 ID、上下文、提案、替代方案（如有）、理由、影響、核准狀態（"pending"）。
2. 在頁面 02 To-Be Wireframes 上為每個被接受的發現建立目標線稿圖。從尺寸和位置與現狀影格匹配的複本開始；僅變更為解決該發現所需的內容。變更後，返回並為該變更建立一個 annotation，引用決策 ID。每個變更必須有至少一個決策 ID 關聯；如果一個差異可以在多個決策下被合法分類，則包含所有適用的決策 ID 並引用理由。
3. 透過將目標線稿圖與其對應的現狀線稿圖進行比較來驗證目標線稿圖：對於每個差異，確認它與一個或多個決策 ID 相關聯。任何沒有決策 ID 的差異都是未標籤的，必須被標記。
4. 附加 figma.baseline.matched 事件，確認每個目標影格都有一個對應的 version_before 且每個已變更的差異都標記了決策 ID。

階段 7 — 交接與迭代

針對每個核准的決策，以其餘決策上下文寫入一個 handoff/D-NNNN.md。

對於 handoff/README.md，寫入實作代理人的規則：它必須使用 git 分支，不得對 audit/ 目錄進行 git 操作，不得修改非目標檔案。

針對實作摘要：

• 開始 — 簽出一個分支，安裝，執行測試。
• 問題 — 引用發現。
• 解決方案 — 簡短描述要做的事。
• 要碰觸的檔案 — 精確路徑。
• 驗證 — 如何確定它已按預期工作。

完成後，此技能會重新執行階段 2–3（僅限）以驗證。

如果使用者要求重新執行，則以新執行 ID 進行；不要覆蓋先前的執行。新增一個版本化影格，例如 03 R-20250215-01，其中包含舊目標與新目標。僅在相關時保留舊影格與註釋。

圖層參考使用完全在總帳中的節點 ID，而不是名稱或文字啟發式。

此技能也說明如何使用自己的工具。它是關於將其全部組合在一起。