Figma Migration Deep Dive
Overview
Automate migration of design data between Figma files, from other tools to Figma, or from Figma styles to the Variables API. Covers inventory, extraction, transformation, and validation.
Prerequisites
- Source and destination Figma file keys
FIGMA_PAT with file_content:read and file_variables:write (Enterprise) scopes- Understanding of source file structure
Instructions
Step 1: Inventory Source File
const PAT = process.env.FIGMA_PAT!;
async function inventoryFile(fileKey: string) {
const res = await fetch(
`https://api.figma.com/v1/files/${fileKey}`,
{ headers: { 'X-Figma-Token': PAT } }
);
const file = await res.json();
const inventory = {
name: file.name,
pages: file.document.children.map((p: any) => p.name),
componentCount: Object.keys(file.components).length,
styleCount: Object.keys(file.styles).length,
styles: {
fills: Object.values(file.styles).filter((s: any) => s.style_type === 'FILL').length,
text: Object.values(file.styles).filter((s: any) => s.style_type === 'TEXT').length,
effects: Object.values(file.styles).filter((s: any) => s.style_type === 'EFFECT').length,
grids: Object.values(file.styles).filter((s: any) => s.style_type === 'GRID').length,
},
};
let nodeCount = 0;
function countNodes(node: any) {
nodeCount++;
if (node.children) node.children.forEach(countNodes);
}
countNodes(file.document);
(inventory as any).totalNodes = nodeCount;
return inventory;
}
const inv = await inventoryFile(process.env.FIGMA_FILE_KEY!);
console.log(`File: ${inv.name}`);
console.log(`Pages: ${inv.pages.join(', ')}`);
console.log(`Components: ${inv.componentCount}, Styles: ${inv.styleCount}`);
console.log(`Total nodes: ${(inv as any).totalNodes}`);
Step 2: Extract Styles from Source
async function extractAllStyles(fileKey: string) {
const file = await fetch(
`https://api.figma.com/v1/files/${fileKey}`,
{ headers: { 'X-Figma-Token': PAT } }
).then(r => r.json());
const styleNodeIds = Object.keys(file.styles);
const nodesRes = await fetch(
`https://api.figma.com/v1/files/${fileKey}/nodes?ids=${styleNodeIds.join(',')}`,
{ headers: { 'X-Figma-Token': PAT } }
).then(r => r.json());
const extracted = [];
for (const [nodeId, styleMeta] of Object.entries(file.styles) as any[]) {
const node = nodesRes.nodes[nodeId]?.document;
if (!node) continue;
extracted.push({
: styleMeta.,
: styleMeta.,
nodeId,
: {
: node.,
: node.,
: node.,
: node.,
: node.,
},
});
}
extracted;
}
Step 3: Transform and Map to Target
interface MigrationToken {
name: string;
category: 'color' | 'typography' | 'effect';
source: { file: string; nodeId: string };
value: any;
}
function transformStyles(styles: any[], sourceFileKey: string): MigrationToken[] {
return styles.map(style => {
switch (style.type) {
case 'FILL':
const fill = style.data.fills?.[0];
return {
name: style.name,
category: 'color' as const,
source: { file: sourceFileKey, nodeId: style.nodeId },
value: fill?.color
? {
r: Math.round(fill.color. * ),
: .(fill.. * ),
: .(fill.. * ),
: fill.. ?? ,
}
: ,
};
:
{
: style.,
: ,
: { : sourceFileKey, : style. },
: style..
? {
: style...,
: style...,
: style...,
: style...,
}
: ,
};
:
{
: style.,
: ,
: { : sourceFileKey, : style. },
: style..,
};
}
}).( t. !== );
}
Step 4: Write to Target (Variables API)
async function migrateToVariables(
targetFileKey: string,
tokens: MigrationToken[]
) {
const colorTokens = tokens.filter(t => t.category === 'color');
const payload = {
variableCollections: [{
action: 'CREATE' as const,
id: 'temp_collection_1',
name: 'Migrated Colors',
}],
variables: colorTokens.map((token, i) => ({
action: 'CREATE' as const,
id: `temp_var_${i}`,
name: token.name.replace(/\//g, '/'),
variableCollectionId: 'temp_collection_1',
resolvedType: 'COLOR' as const,
codeSyntax: { WEB: `--` },
})),
: colorTokens.( ({
: ,
: ,
: {
: token.. / ,
: token.. / ,
: token.. / ,
: token..,
},
})),
};
res = (
,
{
: ,
: {
: ,
: ,
},
: .(payload),
}
);
(!res.) ();
res.();
}
Step 5: Validation
async function validateMigration(
sourceFileKey: string,
targetFileKey: string
): Promise<{ passed: boolean; issues: string[] }> {
const sourceStyles = await extractAllStyles(sourceFileKey);
const targetVars = await fetch(
`https://api.figma.com/v1/files/${targetFileKey}/variables/local`,
{ headers: { 'X-Figma-Token': PAT } }
).then(r => r.json());
const issues: string[] = [];
const targetNames = new Set(
Object.values(targetVars.meta.variables).map((v: any) => v.name)
);
for (const style of sourceStyles) {
if (style.type === 'FILL' && !targetNames.has(style.name)) {
issues.();
}
}
{ : issues. === , issues };
}
Output
- Source file inventoried (components, styles, nodes)
- Styles extracted and transformed to tokens
- Tokens written to target file via Variables API
- Migration validated with comparison report
Error Handling
| Error | Cause | Solution |
|---|
| 403 on Variables POST | Not Enterprise | Use JSON export instead of Variables API |
| Duplicate variable names | Name collision in target | Add prefix/suffix to migrated names |
| Missing node data | Node deleted between fetch and read | Re-fetch with error handling |
| Large file timeout | File >100MB | Use /nodes endpoint for specific pages |
Examples
Dry-run a styles→variables migration and review the mapping before writing (Steps 2-3):
node migrate.js --source ${SOURCE_FILE_KEY} --target ${TARGET_FILE_KEY} --dry-run
48 styles found in source (32 FILL, 12 TEXT, 4 EFFECT)
32 FILL styles → color variables in collection "Primitives"
Color/Brand/Primary → color/brand/primary #4F46E5
Color/Neutral/100 → color/neutral/100 #F5F5F5
2 styles skipped: gradient fills (no variable equivalent) — kept as styles
DRY RUN — no POST to /v1/files/{key}/variables performed
Then re-run without --dry-run to write via the Variables API and validate with Step 5 (GET /v1/files/{key}/variables/local count check). Transform rules: references/transform-and-map-to-target.md.
Resources
Next Steps
For advanced troubleshooting, see figma-advanced-troubleshooting.
