bdsanxz/figma-access

Figma 存取

您透過一個命令列工具與 Figma 協作。它輸出 KDL 格式，並將資料檔案儲存為 .kdl：每個節點一行，節點的純文字欄位以 key=value 的形式顯示在同一行，因此 grep、awk 和 sed 可直接對其操作。例外情況是 spec（輸出其自身的每行一個節點的文字大綱）、daemon log（照原樣輸出背景程式的日誌行），以及 render、screenshot、image-fills 和 compare（儲存影像檔案，其 stdout 上的摘要仍為 KDL）。它有兩種存取方式：

• REST（file、node、spec、render、image-fills、api）：使用用戶的權杖，從其 URL 讀取任何檔案。無需開啟任何內容。讀取會在本地快取，並在遇到速率限制時重試。
• Plugin（exec、screenshot、selection、logs、changes、call）：一個背景程式會與在 Figma Desktop 中執行的 Desktop Bridge 插件通訊。這是唯一能修改檔案的方式。您的主要工具是 exec，它會在檔案中執行 Figma Plugin API JavaScript。

references/tips.md 中記錄了實際運行經驗的教訓，按情境分類。這些是指導方針，而非規則：請閱讀您所處情境的章節，並根據您的情況進行調整。

規則

• 絕不顯示權杖。 不要列印、echo 或記錄它；使用 figma-access api /v1/me 測試它。
• 在您修改任何東西之前和之後都先查看。 根據影像而非產生影像的程式碼來判斷每個可見結果。
• 讀取值，不要猜測；以渲染結果為準。 從檔案中取得顏色、尺寸、間距、字型和文字，絕不要憑肉眼從影像判斷。當檔案的資料與渲染結果不一致時，以渲染結果為準，因為那是用戶看到的。
• 只修改用戶要求的內容。 讀取永遠沒問題。除非請求中明確說明，否則絕不要刪除或覆寫用戶現有的工作。
• 超時並非失敗。 Figma 無法停止正在執行的腳本；在再次執行腳本之前，請檢查 logs 和檔案。

工作流程

1. 設定

1. <skill> 是這個 SKILL.md 所在的目錄。請以 bun <skill>/scripts/figma-access.js COMMAND ... 的形式執行工具；此檔案將其簡寫為 figma-access COMMAND ...。它執行在 Bun 上，而非 Node：務必以 bun 啟動，絕不能用 node，您自己撰寫的任何 JavaScript 或 TypeScript 輔助程式也請使用 bun 執行。若要縮短指令，請在每次 shell 呼叫的開頭定義一個 shell 函數（fa(){ bun <skill>/scripts/figma-access.js "$@"; }; fa ...），而不是變數：zsh 不會將變數拆分成單詞。請對您傳入的每個 URL 和節點 ID 使用引號：?、& 和 ; 對 shell 而言是特殊字元。如果缺少 bun，請告知用戶從 https://bun.sh 安裝並停止。
2. 執行一次 figma-access --help，並在首次使用每個指令前執行 figma-access <command> --help。結束碼：0 成功，1 Figma 回報失敗，2 參數錯誤，3 背景程式、插件或權杖不可用。references/tips.md 中的「Reading the output」說明了格式及其搜尋方式。
3. 根據請求選擇路徑，如 references/tips.md 中的「Choosing a path」所述：URL 加上唯讀任務 → 使用 REST；任何對檔案的修改 → 使用 plugin；兩者可同時使用。

2a. 透過 REST 連接

1. 執行 figma-access api /v1/me。若出現「no token」：請找出用戶設定權杖的位置，並在同一個指令中載入它，如 references/tips.md 中的「Token」所述。只有在任何地方都沒有設定權杖時，才向用戶索取權杖（Figma：設定 > 安全性 > 個人存取權杖，檔案內容讀取）。
2. 執行 figma-access file <url> 來查看頁面和頂層框架。選擇要處理的節點，遵循 references/tips.md 中的「Finding the right node」。

2b. 透過 Plugin 連接

1. 執行 figma-access status。它會在需要時啟動背景程式。
   • 列出檔案：繼續。
   • 無檔案：執行 figma-access files，它會等待插件。如果它以 3 退出，請執行 figma-access setup，並將列印出的 steps 以簡單文字告知用戶：從列印的清單路徑匯入插件一次，然後在檔案中執行 Plugins > Development > Figma Desktop Bridge 並保持其視窗開啟。要求用戶在插件執行時通知您，然後再次執行 figma-access files。
2. 若連接了多個檔案：請在後續的每個指令中傳入 --file <fileKey>。

3. 理解設計

1. 讀取能回答問題的最小檢視，先看大綱，只有您需要處理的地方才看細節：
   • 結構：figma-access node <url|key> <id> --outline 2（REST），或 references/plugin-api.md 中的頁面大綱食譜（plugin）；
   • 程式碼所需的一切，每個可見節點一行：figma-access spec <url|key> <id> -o <file>；對於大型框架，先使用 node ... -o <file> 儲存一次，然後在後續的每個 spec 中傳入 --from <file>，如 references/tips.md 中的「Rate limits and the cache」所述；
   • 用戶所說「這個」或「選取的」：figma-access selection；
   • 外觀：figma-access render <key> <id>（REST，確切尺寸）或 figma-access screenshot <id>（plugin），然後開啟影像。
2. 讀取 node 的 reports：字型、影像填充，以及被修剪的隱藏圖層數量。閱讀 references/tips.md 中的「Hidden layers」和「Reading a design image」。
3. 對於元件、變體、變數和樣式，在您修改或複製它們之前，請先閱讀其實際結構，並重複使用現有內容，而不是建立重複項。

4. 執行任務

在程式碼中實作設計。 在撰寫程式碼之前，請閱讀 references/tips.md 中的「From design to code」：初次建置後仍存在的差異（影像裁切、字型、文字偏移、頁面寬度）大部分都已涵蓋在其中。請將程式碼寫在用戶或他們的專案所指定的位置（他們命名的路徑，或專案本身的結構）；_swe/figma-access/ 僅存放工作成品，例如渲染圖、儲存的節點檔案、規格、螢幕截圖和腳本。

1. 以 1 倍比例渲染框架作為參考，如果框架很高，則分段讀取。
2. 將框架的 spec 寫入檔案，並指定 --origin 為頁面內容開始的角落，然後從中取得所有值。請渲染影像，以及被標記為 ICON 或 MASKED 的內容，而不是重新建構它們。根據 spec 列印的方向、間距、內距和尺寸來建構自動佈局框架，而不是根據它們儲存的盒子，並將沒有自動佈局的群組和框架的子項放置在它們的盒子位置。不要手動或使用生成器將每個節點絕對定位在其儲存的盒子：這樣做會複製每個過時的盒子，當文字過長時會破壞佈局，也無法適應視窗。檢查每個標記為 LAYOUT DRIFT 的部分與渲染結果是否一致。
3. 列出所有字重；在專案中尋找任何非公開字型系列的檔案，並在一次訊息中向用戶詢問仍然缺少的字型，以及您無法從檔案中取得的任何其他資訊。在它們送達之前，或者當您無法詢問時，請使用替代字型並說明。
4. 省略裝置或瀏覽器 chrome，讓頁面適應視窗：框架的寬度是它所繪製的螢幕寬度，因此背景和分隔線應橫跨視窗，內容欄位居中，除非用戶要求固定寬度。
5. 逐個區塊建置，然後使用 figma-access compare <reference.png> <page> --nodes <node file> --wide <px> 將頁面與參考進行比對：它會擷取頁面，列印出框架每個區塊中不同的像素（附帶解釋每個差異的偏移量）、每個文字樣式和節點的位置偏差、以及哪些缺失，並寫出差異影像，同時檢查較寬的視窗。使用 --nodes 時，它會從框架自身的子項中取得區塊，並裁切一個參考（該參考曾被框架的陰影擴展）。同時查看擷取結果和差異影像，並重複直到每個區塊都匹配。當用戶要求像素級完美或 1:1 的結果，且您的會話中列出了相關技能時，請將這些渲染圖作為設計影像來使用。

修改檔案。 透過 Plugin：

1. 將修改內容撰寫為 Plugin API 程式碼，並使用 figma-access exec 執行，遵循 references/plugin-api.md 中有關 API 強制要求和放置位置的說明。較長的程式碼應放在工作檔案中（例如在 _swe/figma-access/ 下），並使用 exec -f 執行。始終 return 您下一步需要的 ID；對於長時間的工作，請加上 --timeout 30s 或更長時間。
2. 對於現成插件例行工作（元件集、lint 和可存取性稽核、影像填充、註解、FigJam 和 Slides 輔助程式），請使用 figma-access call <METHOD> '<json>'；figma-access methods <filter> 會列出參數。
3. 每次都要讀取輸出：如果是 ok #false，請修正原因並在重試前移除部分工作；如果 resultAnalysis 下出現 warning，請檢查 ID 和名稱；若要取得腳本自身的追蹤，請使用 figma-access logs --since 2m。
4. 對您建立或修改的每個節點進行螢幕截圖（小型節點使用 --scale 2），並與請求進行比對。修正後再次截圖；經過三輪仍未達到要求，請告訴用戶哪些遺漏了以及原因。

references/tips.md 中的「Working through the plugin」涵蓋了此處常見的問題。

5. 回報

將您讀取或修改的內容告知用戶，包含節點名稱和 ID，以及您寫入的渲染圖、螢幕截圖和檔案的路徑。說明您未完成的任何事項、您所做的每個假設（替代字型、跳過的隱藏圖層、省略的 chrome），以及哪些部分未經驗證。

疑難排解

• 「超出速率限制」(429)： CLI 已等待並重試。請遵循 references/tips.md 中的「Rate limits and the cache」，並在下次大量讀取前等待一分鐘。
• 結束碼 3，無檔案連接： 插件未在該檔案中執行，或仍在搜尋中（它每隔幾秒檢查一次）。要求用戶再次執行它。figma-access daemon log 會顯示連接發生的時間。
• 另一個工具使用同一個插件（例如 figma-console-mcp）：兩者並行運作；figma-access status 會顯示此背景程式是否持有該檔案。
• 技能更新後行為過時： 再次執行 figma-access setup，要求用戶在 Figma 中重新匯入清單，然後執行 figma-access daemon restart。
• 「插件在回應前中斷連線」： 用戶關閉了插件或檔案，或插件重新載入。在重複修改之前，請檢查檔案。