Figma 變數是讓產出使用 token 而非硬編碼值的前提。官方建議用變數管理間距、顏色、圓角與字體四類，理由直接：agent 只能引用檔案裡真的存在的東西——沒有變數，它拿到的就是 #3B82F6 這樣的十六進位值，而那是後續所有不一致的起點。
get_variable_defs 負責取出選取範圍用到的變數與樣式。但這裡有一個官方文件沒有處理的核心問題，本篇大部分篇幅用來談它。
📖 官方文件的缺口
Figma 有一頁叫「變數沒有正確帶入程式碼」，但它只處理了一個成因：agent 挑錯工具。官方的建議是把要求講明確，並給了範例：
「Get the variable names and values for this selection.」
官方沒有說明的是：當 Figma 變數的名稱與你 codebase 裡 token 的名稱不一致時該怎麼辦。而這在實務上幾乎是常態——設計端叫 color/bg/subtle，程式端叫 --surface-muted 或 colors.surface.muted。
這個缺口要靠規則檔補，見下。
📖 命名對應的三種策略
依維護成本由低到高：
一、兩邊名稱對齊（最省事，但要先談好）
讓 Figma 變數名稱與 codebase token 名稱採用同一套命名。這是最乾淨的做法，但它是一個組織決定而非技術決定——需要設計與工程同意採用同一份命名規範，並在兩邊同步維護。
適合：新專案、或正在重建設計系統的團隊。
二、在規則檔寫一份對應表
在 CLAUDE.md 或 .cursor/rules 裡明確寫出對應：
Figma 變數 → codebase token
color/bg/subtle → var(--surface-muted)
color/text/primary → var(--text-primary)
spacing/md → var(--space-3)
radius/card → var(--radius-lg)
適合：既有專案，兩邊名稱已經各自長成不同樣子。
代價：這份表會過期。每次任一邊新增變數都要同步，而沒有機制會提醒你。
三、建立一層轉換
在 codebase 裡建立一層以 Figma 命名為準的別名，讓兩套名稱並存。成本最高，但只需要維護一次。
三者之間沒有正確答案，取決於你的設計系統成熟度。 但有一條通則：不要讓 agent 自己猜對應。猜測在單次生成時看起來可行，但它每次猜的結果可能不同——而不一致的 token 使用比硬編碼更難發現，因為程式碼看起來是對的。
📖 讓變數真的被用上
四件事依序做：
一、在 Figma 建立變數並實際套用。 建立了但圖層仍用硬刻值，get_variable_defs 一樣取不到。
二、在提示裡明確要求。 官方的範例句式即可。
三、在規則檔寫死「不准硬編碼」。 官方建議的規則檔內容明確包含「use design tokens instead of hardcoded values」這一條。見 規則檔。
四、把對應關係寫進 Code Connect 的自訂指示。 這一項最容易被忽略——Code Connect 的自訂指示會跟著每一次元件生成被送進脈絡，比規則檔更貼近使用現場。見 Code Connect。
📖 與設計系統的整合
遠端伺服器提供兩個跨檔案的查詢工具，它們把 MCP 從「讀這一個 frame」擴展成「查整個設計系統」：
| 工具 | 用途 |
|---|---|
search_design_system | 在元件庫中搜尋元件、變數與樣式 |
get_libraries | 列出已加入與可用的元件庫 |
這兩個是遠端限定的，也是本機版與遠端版差距最具體的地方之一。
它們改變了可行的提問方式。 沒有這兩個工具，你只能問「把這個 frame 做出來」；有了之後，可以問「我們的設計系統裡有沒有現成的 empty state 元件」——agent 能在生成前先查，而不是直接造一個新的。
這正是「避免每次重生」的第二道防線。 第一道是 Code Connect（已選中的元件對應到程式碼），第二道是
search_design_system（還沒選中的時候，先去找有沒有現成的）。兩者解決的是同一個問題的不同階段。
📖 主題與多模式
Figma 變數支援 mode（例如淺色／深色），而這正好對應到前端的主題切換。官方文件沒有專門說明 MCP 如何處理多 mode 的變數——get_variable_defs 的輸出格式官方未載明，我也無法確認它是否會一併帶出各 mode 的值。
實務上可行的做法是在規則檔中明確指示主題的實作方式（CSS 自訂屬性、data-theme 屬性、prefers-color-scheme 等），讓 agent 知道它拿到的變數要落到哪一種架構裡。完整的淺色／深色架構見 Light／Dark 主題。
這一項列為待確認，見 主張 vs 可佐證。
📖 檔案結構決定一切
官方「組織 Figma 檔案」那一頁，本質上是在說設計系統的衛生狀況直接決定 MCP 的產出品質：
- 會重複的東西都做成元件——按鈕、卡片、輸入框、導覽項目
- 用 Code Connect 連到程式碼——官方稱最有效
- 用變數管間距、顏色、圓角、字體
- 圖層與元件取語意化名稱——不要留
Frame1268、Group5 - 用 auto layout，避免絕對定位，並在生成前縮放 frame 確認行為
- 加註解說明難以用視覺表達的行為、對齊與響應式規則
- 在 Dev Mode 掛上 dev resources——文件、程式碼、ticket
這份清單沒有一條是「為了 MCP」才需要做的——它們本來就是健康設計系統的特徵。MCP 的作用是讓這些工作第一次有了直接、可量測的回報：以前「圖層命名整齊」只是美德，現在它直接決定生成出來的變數名稱。
🧠 重點整理
沒有變數，agent 只能給硬編碼值，那是所有不一致的起點。
官方只處理了「agent 挑錯工具」這一個成因，沒有處理命名不一致——那要靠規則檔補。
命名對應三策略：兩邊對齊（最省事，需組織決定）、規則檔對應表（會過期）、建立轉換層（成本高但一次性）。
不要讓 agent 自己猜對應——不一致的 token 比硬編碼更難發現。
讓變數真的被用上要做四件事，其中「寫進 Code Connect 自訂指示」最常被忽略，卻最貼近使用現場。
search_design_system 是避免重生的第二道防線——Code Connect 管已選中的，它管還沒選中的。
多 mode 變數如何經 MCP 傳遞，官方未載明，列為待確認。
官方的檔案結構建議，本質上就是健康設計系統的特徵——MCP 讓這些工作第一次有了可量測的回報。
✍️ 動手做
查清楚你的變數實際傳了什麼過去，約 25 分鐘：
- 在 Figma 選一個使用了多個變數的元件。
- 明確要求 agent：「Get the variable names and values for this selection.」
- 把回傳的原始內容記下來——有哪些名稱、值的格式是什麼、有沒有帶出 mode。
- 拿這份清單對照你 codebase 的 token 名稱，列出對不上的部分。
- 把對不上的部分寫成規則檔裡的對應表，再生成一次，確認這次有沒有用對。
第 3 步是本篇的核心，因為官方沒有記載這個輸出格式。自己實測一次，你會得到比任何教學都準確的資訊——而且第 4 步列出的落差清單，就是你設計系統與程式碼之間真實的距離。
🔗 資料來源
- Figma 開發者文件 — 組織 Figma 檔案——元件、Code Connect、變數四類、語意化命名、auto layout、註解、dev resources（一手，2026-11-01 查證）。
- Figma 開發者文件 — 變數沒有正確帶入程式碼——agent 挑錯工具與官方範例提示；該頁未處理命名不一致問題。
- Figma 開發者文件 — 工具與提示——
get_variable_defs、search_design_system、get_libraries與 Remote only 標註。 - Figma 開發者文件 — 加入自訂規則——「use design tokens instead of hardcoded values」。
- 三種命名對應策略與兩道防線的框架是我的歸納，非官方建議。