Code Connect：把設計元件對應到 codebase 既有元件

Code Connect 把 Figma 元件連結到它在程式碼中對應的元件。當 MCP server 處理一個含有已連結元件的 frame 時，它會把該元件的實作脈絡一併送給 agent——import 敘述、使用範例、屬性對應，以及你自訂的指示。這是整個主題投報率最高的一項設定：沒有它，agent 每次都會重寫一套新元件；有了它，agent 會用你真正的 <Button>。

官方文件把它描述為讓 agent 重用你真實元件的「the most effective way」。

📖 它實際送出什麼

官方沒有公開比對演算法，但明確描述了輸出格式：每個已連結的元件會被包在一個 <CodeConnectSnippet> 標記裡，內含：

設計屬性——來自 Figma 的變體、布林屬性、文字
import 敘述
元件片段——展示用法的程式碼
你加入的自訂指示

第四項常被忽略，但它是這個機制真正的槓桿點。 自訂指示可以寫 prop 的使用慣例、無障礙要求、團隊約定——這些是 agent 無論多聰明都猜不到的事，而它們會跟著每一次生成被送進脈絡。

📖 CLI 版與 UI 版的差別

官方提供兩種建立方式，產出的品質不同：

	Code Connect CLI	Code Connect UI
import 來源	Code Connect 檔案的 `imports` 欄位；該欄位為空時用 `source`	由你輸入的元件路徑與名稱生成
程式碼片段	你自己寫的那段，展示 Figma 屬性如何對應到 props	由 Figma 元件的名稱與屬性自動生成
官方評價	—	「more basic」

結論很清楚：要效果就用 CLI 版。 UI 版的片段是機器從元件名稱推出來的，它知道「有一個叫 Size 的變體」，但不知道那對應到你的 size="lg" 還是 scale="large"。CLI 版讓你把真實的對應關係寫出來，而那正是 agent 最需要、也最猜不準的部分。

UI 版的價值在於門檻低——設計師可以自己做，不需要動 codebase。對一個還沒有 Code Connect 的團隊，用 UI 版先覆蓋最常用的 10 個元件，是合理的起手。

📖 多框架

若一個元件連結了多個框架：

遠端伺服器用 clientFrameworks 參數決定給哪一個（值如 React、SwiftUI）
本機伺服器用 Dev Mode 裡選定的連接

但要注意方案限制：官方明確指出 Professional 方案一次只能啟用一個框架，由團隊管理員在 Admin → Settings → Resources → Code Connect 切換。同時維護 Web 與原生 App 的 Professional 團隊，會持續被這一條卡住，見指定框架。

📖 要求

Code Connect 的連結需要 Professional、Organization、Government 或 Enterprise 方案，以及 Full 或 Dev 席次。

注意這與 MCP server 本身的要求不同——Starter 方案可以用 MCP server 的部分功能，但不能用 Code Connect。而 Code Connect 恰好是價值最高的那一塊，所以「先用免費的試試看」這個策略會系統性地低估它的價值。

📖 MCP 這一側的三個工具

工具	用途
`get_code_connect_map`	回傳選取實例的對應；參數 `clientFrameworks`、`clientLanguages`
`add_code_connect_map`	讓 agent 建立新的對應
`get_code_connect_suggestions`／`send_code_connect_mappings`	建議與確認對應（Figma 內部使用）

add_code_connect_map 值得特別注意：它代表建立對應這件事本身可以交給 agent。agent 看得到你的 codebase，也看得到 Figma 元件，理論上能自己提出對應。

兩個現實的限制：官方載明元件必須先手動發布，才能完成 Code Connect 對應；而且這個工具屬於寫入類，建議先在複本測試。

另外，add_code_connect_map 是少數不計入 MCP 限額的寫入工具之一（與 create_new_file、generate_figma_design、whoami 同列），所以批次建立對應不會吃掉你每天的呼叫額度——這讓「一次把整個元件庫對應起來」成為可行的做法。

📖 導入順序

Code Connect 的覆蓋率不必一步到位。按使用頻率排序，前 10 個元件通常覆蓋大部分畫面：

① 盤點：哪些元件在設計檔裡實例數最多
   └─ 用 search_design_system 或 get_libraries 查

② 確認 codebase 這一側存在對應元件
   └─ 不存在就先別連——Code Connect 連到一個不該用的元件更糟

③ 用 CLI 建立前 10 個對應
   └─ 重點寫清楚 props 如何對應到 Figma 變體

④ 在每個對應裡加自訂指示
   └─ 寫 agent 猜不到的：無障礙要求、prop 慣例、不要用哪些寫法

⑤ 驗證：對一個含這些元件的 frame 生成程式碼
   └─ 檢查產出是否真的 import 了你的元件

⑥ 擴大覆蓋

第 ② 步值得強調。 Code Connect 的風險不是「沒連到」，而是連到一個已經被淘汰、或不該在新畫面使用的元件——那會讓 agent 穩定地產出錯誤的程式碼，而且因為「看起來用了設計系統」而更難被發現。

🧠 重點整理

Code Connect 是整個主題投報率最高的設定，官方稱其為讓 agent 重用真實元件的最有效方式。

它送出四樣東西：設計屬性、import、用法片段、你的自訂指示——第四項是最大的槓桿。

CLI 版的片段是你寫的，UI 版是機器生成的，官方評價後者「more basic」。要效果用 CLI。

UI 版的價值在門檻低，設計師可自行建立，適合當起手。

需要 Professional 以上方案＋ Full／Dev 席次，與 MCP server 本身的要求不同。

Professional 一次只能啟用一個框架，跨平台團隊會卡住。

add_code_connect_map 不計入限額，所以批次建立對應可行。

元件必須先手動發布才能完成對應。

最大的風險是連到不該用的元件，那會讓錯誤穩定地產生且難以察覺。

✍️ 動手做

用一個元件驗證整條鏈路，約 30 分鐘：

挑一個你 codebase 裡最常用、介面最穩定的元件（按鈕最合適）。
用 CLI 建立它的 Code Connect，把 Figma 變體對應到真實 props 寫清楚。
在自訂指示裡加一條 agent 猜不到的規則——例如「icon-only 時必須提供 aria-label」。
在 Figma 選一個用到這個按鈕的 frame，請 agent 生成程式碼。
檢查三件事：有沒有 import 你的元件？變體有沒有對應到正確的 prop？第 3 步那條規則有沒有被遵守？

第 5 步的第三項是真正的測試。如果自訂指示有生效，你就知道這個欄位是可靠的槓桿——接下來所有「agent 老是忘記的事」都可以寫在那裡。

🔗 資料來源

Figma 開發者文件 — Code Connect 整合——<CodeConnectSnippet> 輸出內容、CLI 與 UI 版的差別與官方評價、多框架處理、方案與席次要求（一手，2026-11-01 查證）。
Figma 開發者文件 — 工具與提示——三個 Code Connect 工具與參數。
Figma 開發者文件 — 限額與存取——add_code_connect_map 不計入限額。
Figma 開發者文件 — 寫回畫布——元件須先手動發布。
Figma 開發者文件 — 伺服器回傳網頁程式碼——Professional 單框架限制與管理員路徑。
導入順序與「連到錯元件」的風險判斷是我的歸納，非官方建議。

我的知識庫

探索