建立動態規格
直接在 Figma 中產生動態規格 — 時間軸條形圖與詳細表格,記錄來自 After Effects 合成的所有動畫屬性。
超出元件 Markdown (
.md) 消費者合約範圍。 其他create-*技能需要元件.md(由 {{skill:create-component-md}} 產生)並從其render-meta渲染。create-motion是刻意為之的例外:它的輸入是 After Effects 時間軸匯出檔({{ref:motion/export-timeline.jsx}}),而非 Figma 元件走查 — 沒有_base.json、沒有extract-motion,也沒有.md中的 Motion 區段。這個技能不需要.md,也不參與需要.md/快速失敗/白名單讀取的改造。
執行合約(請先閱讀)。
- 這個檔案是執行指示,不是要編輯的文件。啟用技能 = 從 After Effects 時間軸 JSON 將動態規格渲染到 Figma 中。
- 絕對不要在回應中編輯此
SKILL.md或任何其他技能檔案,即使它們在編輯器中開啟或聚焦。僅在使用者明確要求修改技能本身時才修改技能。 - 輸入的時間軸 JSON 是唯讀的事實來源。請勿編輯。 這個技能產生的唯一成品是 Figma 註解;只會將渲染請求寫入 Figma,絕不會以檔案編輯方式進行。
- 絕對不要呼叫
AskQuestion、要求確認或暫停等待輸入(包括在 Figma 寫入之前,預期輸出)。遇到模糊情況時,選擇最合理的選項並繼續。 - 只有兩種合法停止情況:(a) 缺少或無效的 AE 時間軸 JSON(步驟 4/5 收集 + 驗證關卡);(b) 如果 Figma MCP 連線中斷,則以一行訊息中止。
MCP 介面卡
讀取 uspecs.config.json → mcpProvider。針對此技能中的每個 MCP 呼叫,遵循對應的欄位。
| 操作 | figma-console | figma-mcp |
|---|---|---|
| 驗證連線 | figma_get_status | 跳過 — 隱含驗證。如果第一次 use_figma 呼叫失敗,引導使用者檢查 MCP 設定。 |
| 導覽至檔案 | figma_navigate 搭配 URL | 從 URL 中提取 fileKey (figma.com/design/:fileKey/...)。無需導覽。 |
| 擷取螢幕截圖 | figma_take_screenshot | get_screenshot 搭配 fileKey + nodeId |
| 執行外掛程式 JS | figma_execute 搭配 code | use_figma 搭配 fileKey、code、description。JS 程式碼完全相同 — 無需修改包裝器。 |
| 搜尋元件 | figma_search_components | search_design_system 搭配 query + fileKey + includeComponents: true |
| 取得檔案/元件資料 | figma_get_file_data / figma_get_component | get_metadata 或 get_design_context 搭配 fileKey + nodeId |
| 取得變數(檔案範圍) | figma_get_variables | use_figma 腳本:return await figma.variables.getLocalVariableCollectionsAsync(); |
| 取得權杖值 | figma_get_token_values | use_figma 腳本,依模式/集合讀取變數值 |
| 取得樣式 | figma_get_styles | search_design_system 搭配 includeStyles: true,或使用 use_figma:return figma.getLocalPaintStyles(); |
| 取得選取範圍 | figma_get_selection | use_figma 腳本:return figma.currentPage.selection.map(n => ({id: n.id, name: n.name, type: n.type})); |
figma-mcp 每次呼叫都需要 fileKey。 在工作流程開始時從使用者的 Figma URL 提取一次。對於分支 URL (figma.com/design/:fileKey/branch/:branchKey/:fileName),使用 :branchKey 作為 fileKey。
figma-mcp 頁面上下文: use_figma 每次呼叫都會將 figma.currentPage 重設為第一個頁面。當腳本透過 getNodeByIdAsync(ID) 存取前一步驟的節點時,頁面內容可能尚未載入 — findAll、findOne 和 characters 在頁面啟用前會因 TypeError 而失敗。在 getNodeByIdAsync 之後立即插入此頁面載入區塊:
let _p = node; while (_p.parent && _p.parent.type !== 'DOCUMENT') _p = _p.parent;
if (_p.type === 'PAGE') await figma.setCurrentPageAsync(_p);
這會向上遍歷到 PAGE 祖先並載入其內容。Console MCP 不需要這個 — figma_execute 會繼承 Desktop 頁面上下文。
預期輸入
使用者透過以下模式之一觸發此技能:
- {{skill:create-motion}} + 貼上的 JSON(從剪貼簿,透過
{{ref:motion/export-timeline.jsx}}匯出) - {{skill:create-motion}} + 檔案參考(例如
@motion-ex.json或.json檔案的路徑) - {{skill:create-motion}} + Figma 連結(註解應放置的目標頁面/檔案)
必要: 匯出的 JSON 資料 — 內嵌貼上或作為檔案參考。
選用:
- 目標頁面的 Figma 連結(如果未提供,則放置在目前頁面的檢視區中心)
- 動畫的螢幕截圖或錄影
- 動畫用途的描述
工作流程
複製此檢查清單並在進展時更新:
任務進度:
- [ ] 步驟 1:讀取指示檔案
- [ ] 步驟 2:驗證 MCP 連線
- [ ] 步驟 3:從 uspecs.config.json 讀取範本金鑰
- [ ] 步驟 4:收集上下文(從貼上內容、檔案參考或提示使用者取得 JSON)
- [ ] 步驟 5:解析並驗證 JSON(包括 segments[] 和 hasAnimatedSegments)
- [ ] 步驟 6:轉換資料(讀取預先計算的區段、計算軌道寬度、時間軸位置)
- [ ] 步驟 7:重新讀取指示檔案(錯誤與反模式、驗證檢查清單)並稽核
- [ ] 步驟 8:匯入並分離 Motion 範本
- [ ] 步驟 9:填寫標頭欄位
- [ ] 步驟 10:產生時間標尺
- [ ] 步驟 11:渲染時間軸圖層(每個圖層一個 figma_execute)
- [ ] 步驟 12:隱藏範本
- [ ] 步驟 13:渲染表格列
- [ ] 步驟 14:視覺驗證
步驟 1:讀取指示
讀取 agent-motion-instruction.md
步驟 2:驗證 MCP 連線
從 uspecs.config.json 讀取 mcpProvider 以決定要使用哪個 Figma MCP。
如果是 figma-console:
figma_get_status— 確認 Desktop Bridge 外掛程式已啟用- 如果連線失敗:「請開啟 Figma Desktop 並執行 Desktop Bridge 外掛程式。然後再試一次。」
如果是 figma-mcp:
- 連線會在第一次
use_figma呼叫時隱含驗證。無需明確檢查。 - 如果第一次呼叫失敗:「請確認您的 FIGMA_API_KEY 在 MCP 設定中正確設定。」
步驟 3:讀取範本金鑰
讀取檔案 uspecs.config.json 並提取:
templateKeys物件中的motionSpec值 → 儲存為MOTION_TEMPLATE_KEY
如果範本金鑰為空,告知使用者:
動態規格範本金鑰尚未設定。請先使用您的 Figma 範本圖書館連結執行 {{skill:firstrun}}。
步驟 4:收集上下文
檢查使用者提供的內容:
- 已提供 JSON(內嵌貼上或作為檔案參考,如
@motion-ex.json)→ 讀取並直接進入步驟 5。不要再次要求。 - 僅提供 Figma 連結(目的地)但無 JSON → 提示:
請貼上匯出的 JSON 或參考
.json檔案(例如@motion-ex.json)。 - 未提供任何內容 → 提示:
請貼上從
export-timeline.jsx匯出的 JSON,或參考.json檔案。
如果提供了 Figma 目的地連結,請在渲染(步驟 8)之前使用 figma_navigate 開啟它。
同時接受使用者提供的任何選用螢幕截圖、錄影或描述作為額外上下文。
步驟 5:解析並驗證 JSON
根據指示檔案中的結構描述和驗證規則(JSON 結構描述和 JSON 驗證規則章節)驗證剪貼簿 JSON。如果驗證失敗,請確切告知使用者哪個欄位遺失或格式錯誤,並要求他們重新匯出。
步驟 6:轉換資料
匯出腳本會預先計算區段、值格式化、條形標籤、緩動標籤和無變更過濾。代理程式直接讀取這些內容,只計算版面相依的值。
6a. 跳過非動畫圖層 — 檢查 layer.hasAnimatedSegments。如果為 false,從時間軸和表格中省略該圖層。
6b. 讀取預先計算的區段 — 每個屬性都有一個 segments[] 陣列,包含 startMs、endMs、durationMs、fromValue、toValue、barLabel、easing 和 easingType。直接使用這些值 — 無需手動計算。
6c. 計算軌道寬度和 pxPerMs — pxPerMs 是固定速率;trackWidth 是動態的,右側有刻度標籤的內距:
compDurationMs = composition.durationMs // 直接從 JSON 讀取
pxPerMs = 0.64 // 固定速率 — 每 500ms 刻度約 320px
trackWidth = max(compDurationMs * pxPerMs + 50, 1600) // 資料區域 + 50px 標籤內距,最小值 1600
將 trackWidth 和 pxPerMs 傳遞給 Figma 渲染程式碼。pxPerMs 是固定速率 (0.64),不是從 trackWidth / compDurationMs 推導而來。條形位置 (barX、barWidth) 會在渲染時在 Figma 程式碼內部計算 — 代理程式不計算每個區段的位置。
在渲染時,將 #track-area 和 #ruler-track 都調整為這個計算出的 trackWidth。父容器使用 HUG 尺寸並自動展開。
6d. 格式化合成元資料 根據指示檔案的合成元資料規則。儲存為 COMPOSITION_META。
步驟 7:稽核
重新讀取指示檔案,重點關注:
- 錯誤與反模式章節
- 輸出前驗證檢查清單
根據每個規則檢查您轉換後的資料。修正任何違規。
步驟 8:匯入並分離範本
透過 figma_execute 執行(取代 __MOTION_TEMPLATE_KEY__ 和 __COMPONENT_NAME__):
const TEMPLATE_KEY = '__MOTION_TEMPLATE_KEY__';
const templateComponent = await figma.importComponentByKeyAsync(TEMPLATE_KEY);
const instance = templateComponent.createInstance();
const { x, y } = figma.viewport.center;
instance.x = x - instance.width / 2;
instance.y = y - instance.height / 2;
const frame = instance.detachInstance();
frame.name = '__COMPONENT_NAME__ Motion';
figma.currentPage.selection = [frame];
figma.viewport.scrollAndZoomIntoView([frame]);
return { frameId: frame.id };
儲存回傳的 frameId — 後續所有步驟都需要它。
步驟 9:填寫標頭欄位
透過 figma_execute 執行(取代 __FRAME_ID__、__COMPONENT_NAME__、__COMPOSITION_META__):
const FRAME_ID = '__FRAME_ID__';
const frame = await figma.getNodeByIdAsync(FRAME_ID);
const textNodes = frame.findAll(n => n.type === 'TEXT');
const fontSet = new Set();
const fontsToLoad = [];
for (const tn of textNodes) {
try {
const fn = tn.fontName;
if (fn && fn !== figma.mixed && fn.family) {
const key = fn.family + '|' + fn.style;
if (!fontSet.has(key)) { fontSet.add(key); fontsToLoad.push(fn); }
}
} catch {}
}
await Promise.all(fontsToLoad.map(f => figma.loadFontAsync(f).catch(() => {})));
const compName = frame.findOne(n => n.name === '#component-name');
if (compName) {
const t = compName.type === 'TEXT' ? compName : compName.findOne(n => n.type === 'TEXT');
if (t) t.characters = '__COMPONENT_NAME__';
}
const compDesc = frame.findOne(n => n.name === '#component-description');
if (compDesc) {
const t = compDesc.type === 'TEXT' ? compDesc : compDesc.findOne(n => n.type === 'TEXT');
if (t) t.characters = 'Motion Specification';
}
const compMeta = frame.findOne(n => n.name === '#composition-meta');
if (compMeta) {
const t = compMeta.type === 'TEXT' ? compMeta : compMeta.findOne(n => n.type === 'TEXT');
if (t) t.characters = '__COMPOSITION_META__';
}
return { success: true };
步驟 10:產生時間標尺
透過 figma_execute 執行。計算理想的軌道寬度,調整 #ruler-track 和所有 #track-area 節點的大小,然後為每個間隔複製 #tick。
取代 __FRAME_ID__、__COMP_DURATION_MS__(從 composition.durationMs 讀取)、__TRACK_WIDTH__(在步驟 6c 中計算)和 __PX_PER_MS__(固定為 0.64):
const FRAME_ID = '__FRAME_ID__';
const COMP_DURATION_MS = __COMP_DURATION_MS__;
const TRACK_WIDTH = __TRACK_WIDTH__;
const PX_PER_MS = __PX_PER_MS__;
const frame = await figma.getNodeByIdAsync(FRAME_ID);
const rulerTrack = frame.findOne(n => n.name === '#ruler-track');
if (!rulerTrack) return { error: '#ruler-track not found' };
// 將標尺軌道調整為計算寬度
rulerTrack.resize(TRACK_WIDTH, rulerTrack.height);
// 調整所有 #track-area 節點的大小(在圖層範本和任何複製的圖層中)
const trackAreas = frame.findAll(n => n.name === '#track-area');
for (const ta of trackAreas) {
ta.resize(TRACK_WIDTH, ta.height);
}
// 在標尺軌道中找到 #tick 範本
const tickTemplate = rulerTrack.findOne(n => n.name === '#tick');
if (!tickTemplate) return { error: '#tick template not found in #ruler-track' };
// 從 tick 範本的文字節點載入字型
const tickTextNodes = tickTemplate.findAll(n => n.type === 'TEXT');
for (const tn of tickTextNodes) {
if (tn.characters.length > 0) {
try { await figma.loadFontAsync(tn.fontName); } catch {}
}
}
// 刻度間隔:目標為 6–12 個刻度
const tickInterval = COMP_DURATION_MS <= 300 ? 50
: COMP_DURATION_MS <= 600 ? 100
: COMP_DURATION_MS <= 1500 ? 250
: COMP_DURATION_MS <= 4000 ? 500
: COMP_DURATION_MS <= 10000 ? 1000
: 2000;
for (let ms = 0; ms <= COMP_DURATION_MS; ms += tickInterval) {
const xPos = ms * PX_PER_MS;
const tick = tickTemplate.clone();
rulerTrack.appendChild(tick);
tick.name = ms + 'ms';
tick.visible = true;
tick.x = xPos;
const label = tick.findOne(n => n.type === 'TEXT');
if (label) {
try { await figma.loadFontAsync(label.fontName); } catch {}
label.characters = ms + 'ms';
}
}
tickTemplate.visible = false;
return { success: true, trackWidth: TRACK_WIDTH, tickInterval: tickInterval };
步驟 11:渲染時間軸圖層
為避免超時,每個圖層執行一個 figma_execute 呼叫。對於每個圖層(其中 hasAnimatedSegments 為 true),複製 #layer-template,設定圖層名稱,然後為每個動畫屬性複製 #property-template 並定位條形。
取代所有 __PLACEHOLDER__ 值。
…
[因翻譯需求而截斷]