hivellm/Figma

<!-- FIGMA:START -->

Figma MCP Instructions

CRITICAL: Use MCP Figma for design system integration, asset export, and design-to-code workflows.

Core Operations

File Operations

// Get file
figma.getFile({ file_key: 'file-key' })

// Get file nodes
figma.getFileNodes({
  file_key: 'file-key',
  ids: ['node-id-1', 'node-id-2']
})

// Get file versions
figma.getFileVersions({ file_key: 'file-key' })

Image Export

// Export images
figma.getImage({
  file_key: 'file-key',
  ids: 'node-id',
  format: 'png',  // png, jpg, svg, pdf
  scale: 2  // @2x resolution
})

// Export multiple
figma.getImage({
  file_key: 'file-key',
  ids: 'node-1,node-2,node-3',
  format: 'svg',
  svg_outline_text: true
})

Components

// Get components
figma.getFileComponents({ file_key: 'file-key' })

// Get component sets
figma.getFileComponentSets({ file_key: 'file-key' })

// Get team components
figma.getTeamComponents({ team_id: 'team-id' })

Styles

// Get file styles
figma.getFileStyles({ file_key: 'file-key' })

// Get team styles
figma.getTeamStyles({ team_id: 'team-id' })

Comments

// Get comments
figma.getComments({ file_key: 'file-key' })

// Post comment
figma.postComment({
  file_key: 'file-key',
  message: 'Approved for development',
  comment_id: 'parent-comment-id'  // For replies
})

Common Patterns

Design Token Export

// Export design tokens from Figma styles
const { data: { styles } } = await figma.getFileStyles({ file_key: fileKey })

const tokens = {
  colors: {},
  typography: {},
  spacing: {}
}

for (const style of Object.values(styles)) {
  if (style.style_type === 'FILL') {
    tokens.colors[style.name] = extractColor(style)
  } else if (style.style_type === 'TEXT') {
    tokens.typography[style.name] = extractTextStyle(style)
  }
}

// Write to tokens.json
fs.writeFileSync('tokens.json', JSON.stringify(tokens, null, 2))

Component Sync

// Sync Figma components to code
const { data: components } = await figma.getFileComponents({ file_key: fileKey })

for (const component of Object.values(components)) {
  // Export component as SVG
  const { data: images } = await figma.getImage({
    file_key: fileKey,
    ids: component.node_id,
    format: 'svg'
  })
  
  // Save to assets folder
  const svg = await fetch(images[component.node_id]).then(r => r.text())
  fs.writeFileSync(`assets/icons/${component.name}.svg`, svg)
}

Screenshot Generation

// Generate screenshots for documentation
const screens = ['home-screen', 'login-screen', 'dashboard']

for (const screenId of screens) {
  const { data: images } = await figma.getImage({
    file_key: fileKey,
    ids: screenId,
    format: 'png',
    scale: 2
  })
  
  const imageUrl = images[screenId]
  const response = await fetch(imageUrl)
  const buffer = await response.buffer()
  
  fs.writeFileSync(`docs/screenshots/${screenId}.png`, buffer)
}

Design Review Automation

// Check for new comments
const { data: comments } = await figma.getComments({ file_key: fileKey })

const unresolved = comments.filter(c => !c.resolved_at)

if (unresolved.length > 0) {
  console.log(`${unresolved.length} unresolved design comments`)
  
  // Create Jira issues for unresolved comments
  for (const comment of unresolved) {
    await jira.issues.createIssue({
      fields: {
        project: { key: 'DESIGN' },
        summary: `Design feedback: ${comment.message.substring(0, 50)}`,
        description: comment.message,
        issuetype: { name: 'Task' }
      }
    })
  }
}

Design System Documentation

// Generate component documentation
const { data: components } = await figma.getFileComponents({ file_key: fileKey })

let markdown = '# Design System Components\n\n'

for (const [id, component] of Object.entries(components)) {
  // Export thumbnail
  const { data: images } = await figma.getImage({
    file_key: fileKey,
    ids: id,
    format: 'png',
    scale: 1
  })
  
  markdown += `## ${component.name}\n\n`
  markdown += `![${component.name}](${images[id]})\n\n`
  markdown += `**Description:** ${component.description || 'No description'}\n\n`
}

fs.writeFileSync('docs/design-system.md', markdown)

Best Practices

✅ DO:

• Cache file data to reduce API calls
• Use version history for tracking changes
• Export assets at appropriate resolutions
• Document component usage
• Use meaningful component names
• Keep design tokens in sync
• Handle rate limits (requests/minute)

❌ DON'T:

• Export entire files repeatedly
• Ignore version control
• Hardcode file keys
• Skip error handling
• Export at wrong resolutions
• Commit API tokens

Configuration

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-figma"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Setup:

1. Generate personal access token: Account Settings → Personal Access Tokens
2. Grant appropriate scopes (file content, comments)
3. Store token securely

Integration Patterns

CI/CD Asset Pipeline

# Export icons on every design update
figma-export --file-key=$FIGMA_FILE --format=svg --output=src/assets/icons

# Optimize SVGs
svgo --folder src/assets/icons

# Commit if changes detected
git diff --quiet src/assets/icons || git commit -m "chore: Update design assets"

Design-to-Code Workflow

// 1. Detect design changes
const currentVersion = await figma.getFile({ file_key: fileKey })
const lastVersion = loadLastProcessedVersion()

if (currentVersion.version !== lastVersion) {
  // 2. Export updated components
  await exportComponents(fileKey)
  
  // 3. Generate code
  await generateComponentCode()
  
  // 4. Run tests
  await runVisualRegressionTests()
  
  // 5. Create PR if tests pass
  if (testsPass) {
    await createPullRequest('Update components from Figma')
  }
}

<!-- FIGMA:END -->