gh-prateekmedia-claude-dev-skills-figma-to-flutter/skills/figma-to-flutter/references/api_setup.md

Figma API Server Setup

Prerequisites Check

Before starting the workflow, verify the Figma API server is running at http://localhost:3001.

Test with:

curl -s http://localhost:3001/health || echo "Server not running"

Initial Setup (One-Time)

If the server is not running, set it up:

1. Clone Repository

mkdir -p ~/Documents
git clone https://github.com/prateekmedia/FigmaToCode-RestApi ~/Documents/figma-api

2. Launch Server

cd ~/Documents/figma-api
# Follow the README instructions to:
# - Install dependencies
# - Set up FIGMA_TOKEN in .env
# - Start the server on port 3001

API Endpoints

Screenshot API

Captures Figma design screenshots.

Endpoint: POST http://localhost:3001/api/screenshot

Request Body:

{
  "url": "$FIGMA_URL",
  "format": "png",
  "scale": 2,
  "saveToFile": true,
  "directory": ".ui-workspace/$FEATURE/figma_screenshots"
}

Parameters:

• url: Full Figma design URL
• format: Output format (png/svg/jpg)
• scale: Screenshot scale (0.5-4, recommend 2)
• saveToFile: Always true for this workflow
• directory: Relative path from git repo root

Convert API

Converts Figma designs to Flutter code and exports assets.

Endpoint: POST http://localhost:3001/api/convert

Request Body (Default - All Scales):

{
  "url": "$FIGMA_URL",
  "settings": {
    "framework": "Flutter"
  },
  "exportImages": true,
  "exportImagesOptions": {
    "scales": ["1x", "2x", "3x", "4x"],
    "directory": ".ui-workspace/$FEATURE/figma_images"
  },
  "output": {
    "saveToFile": true,
    "directory": ".ui-workspace/$FEATURE/figma_code"
  }
}

Request Body (Customized Scales):

{
  "url": "$FIGMA_URL",
  "settings": {
    "framework": "Flutter"
  },
  "exportImages": true,
  "exportImagesOptions": {
    "scales": ["2x", "3x"],
    "directory": ".ui-workspace/$FEATURE/figma_images"
  },
  "output": {
    "saveToFile": true,
    "directory": ".ui-workspace/$FEATURE/figma_code"
  }
}

Parameters:

• settings.framework: Must be "Flutter"
• exportImages: Always true to get asset images
• exportImagesOptions.scales: Array of scales to export (e.g., ["1x", "2x", "3x", "4x"] or subset like ["3x"])
• exportImagesOptions.directory: Where to save exported assets
• output.directory: Where to save generated Flutter code

Customizing Scales:

Before calling this API, analyze the app's asset structure to determine which scales are needed:

1. Multi-directory structure (e.g., assets/, assets/2x/, assets/3x/):

   • Check which scale directories exist
   • Request only those scales: ["1x", "2x", "3x"]

2. Single directory with scale parameter (e.g., Image.asset('img.png', scale: 4)):

   • Search codebase for Image.asset calls with scale parameters
   • Request only the scale value used: ["4x"] or ["3x"]

3. No standard or new project:

   • Default to 3x scale: ["3x"]

Benefits of Customizing Scales:

• Reduces download size and time
• Avoids cluttering workspace with unused resolutions
• Matches app's existing conventions

Output Structure:

• Code files saved to figma_code/
• Assets exported to figma_images/ with subdirectories based on requested scales:
  • 1x/ - Base resolution assets (if requested)
  • 2x/ - 2x resolution assets (if requested)
  • 3x/ - 3x resolution assets (if requested)
  • 4x/ - 4x resolution assets (if requested)

Image Export API (Optional)

For re-exporting specific images or different scales.

Endpoint: POST http://localhost:3001/api/export-images

Request Body:

{
  "url": "$FIGMA_URL",
  "exportOptions": {
    "scales": ["1x", "2x", "3x", "4x"],
    "directory": ".ui-workspace/$FEATURE/figma_images"
  }
}

Image Naming Convention

Exported images use the format: {nodeId}_{originalName} to prevent conflicts.

Example: 123:456_user_avatar.png

Troubleshooting

Server Not Responding

• Check if process is running: lsof -i :3001
• Review server logs in the figma-api directory
• Verify FIGMA_TOKEN is set in .env

Authentication Errors

• Ensure FIGMA_TOKEN is valid
• Check token has access to the Figma file
• Verify file URL is correct and accessible

Export Failures

• Confirm directory paths are relative to git repo root
• Ensure sufficient disk space
• Check file permissions for target directories