figma-to-flutter

What this skill does

# Figma to Flutter Workflow

## Overview

Convert Figma designs into Flutter code through an automated workflow that extracts design metadata, generates reference code, exports assets, implements the UI, and iteratively tests until the implementation matches the design pixel-perfectly.

## When to Use This Skill

Trigger this workflow when users:
- Provide Figma design links and request Flutter implementation
- Say "convert this Figma design to Flutter code"
- Say "run Figma workflow" or "trigger flutter ui workflow"
- Say "implement this Figma screen"
- Request UI implementation from Figma designs

## Workflow Process

### Step 1: Preparation

#### Determine Feature Name

If not provided by the user, infer the feature name from:
- Branch name
- Conversation context
- Design content
- User's working directory

Ask the user if unclear.

#### Set Up Workspace Directory

Create the workspace structure at git repository root:

```bash
mkdir -p .ui-workspace/$FEATURE/{figma_screenshots,figma_images,figma_code,app_screenshots}
```

Ensure `.ui-workspace/` is in `.git/info/exclude`:

```bash
grep -q "^\.ui-workspace/$" .git/info/exclude || echo ".ui-workspace/" >> .git/info/exclude
```

#### Verify API Server

Check if the Figma API server is running:

```bash
curl -s http://localhost:3001/health
```

If server is not running, set it up (one-time):

```bash
# Check if already cloned
if [ ! -d ~/Documents/figma-api ]; then
  mkdir -p ~/Documents
  git clone https://github.com/prateekmedia/FigmaToCode-RestApi ~/Documents/figma-api
  echo "API server cloned. Please follow ~/Documents/figma-api/README to install dependencies and start the server."
else
  echo "API server exists but not running. Please start it: cd ~/Documents/figma-api && [start command from README]"
fi
```

Wait for user to start the server before proceeding.

### Step 2: Extract Figma Metadata

#### Analyze Asset Requirements First

Before making API calls, analyze the app's asset structure to determine which scales to download:

1. Check `assets/` directory structure
2. Search for `Image.asset` calls to identify scale parameters
3. Determine which scales are actually needed

See **Step 3: Asset Management** for detailed analysis instructions.

#### Run API Calls

Execute both API calls **in parallel** to extract all metadata from the Figma design.

**Screenshot API**:

```bash
curl -X POST http://localhost:3001/api/screenshot \
  -H "Content-Type: application/json" \
  -d "{
    \"url\": \"$FIGMA_URL\",
    \"format\": \"png\",
    \"scale\": 2,
    \"saveToFile\": true,
    \"directory\": \".ui-workspace/$FEATURE/figma_screenshots\"
  }"
```

**Convert API** (customize `scales` based on asset analysis):

```bash
# Default: Download all scales
curl -X POST http://localhost:3001/api/convert \
  -H "Content-Type: application/json" \
  -d "{
    \"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\"
    }
  }"
```

**Customize scales**: Modify the `scales` array based on your analysis (e.g., `[\"2x\", \"3x\"]` if app only uses those).

**Results**:
- Design screenshot: `.ui-workspace/$FEATURE/figma_screenshots/`
- Generated Flutter code: `.ui-workspace/$FEATURE/figma_code/`
- Exported assets: `.ui-workspace/$FEATURE/figma_images/{requested_scales}/`

### Step 3: Implementation

#### Review Reference Materials

Examine the extracted materials:
1. **Figma screenshot**: Visual reference for the design
2. **Generated code**: Reference for text styles, dimensions, colors, layout
3. **Assets**: Images to integrate into the app

#### Implement Flutter UI

Using the reference materials:

**Text Styles**: Extract font families, sizes, weights, and colors from generated code
**Layout**: Reference container dimensions, padding, margins, and widget hierarchy
**Colors**: Use exact hex values from the design
**Spacing**: Match padding, margin, and gap values

**Important**: Write proper Flutter code following app conventions. Do not copy generated code directly—use it as a reference.

#### Asset Management

**1. Analyze Existing Asset Structure**

Before downloading or copying assets, examine the app's current asset organization:

- Check if `assets/` directory exists and how it's structured
- Identify the scaling strategy used in the codebase:
  - **Multi-directory approach**: Separate directories for each scale (e.g., `assets/`, `assets/2x/`, `assets/3x/`, `assets/4x/`)
  - **Single directory with scale parameter**: Single `assets/` directory with explicit `scale` parameter in `Image.asset()` calls
  - **No standard structure**: May need to establish one

**2. Determine Required Asset Scales**

Based on the analysis:

- **If multi-directory structure exists**: Check which scale directories are present (e.g., only `assets/2x/` and `assets/3x/`)
- **If using scale parameter**: Search for `Image.asset` calls to identify what scale values are used (e.g., `scale: 4`)
- **If no standard exists**: Default to downloading 3x scale assets

Only download the scales actually needed by the app to avoid unnecessary files.

**3. Download Required Scales from API**

Modify the Convert API call to download only necessary scales:

```bash
# Example: If app uses only 2x and 3x
curl -X POST http://localhost:3001/api/convert \
  -H "Content-Type: application/json" \
  -d "{
    \"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\"
    }
  }"
```

**4. Identify Required Assets**

Review generated code to find referenced image assets.

**5. Copy and Rename Assets**

Copy assets from `.ui-workspace/$FEATURE/figma_images/` following the app's existing structure:

**Multi-directory structure**:
```bash
# Copy to matching scale directories
cp .ui-workspace/$FEATURE/figma_images/2x/asset.png assets/2x/new_name.png
cp .ui-workspace/$FEATURE/figma_images/3x/asset.png assets/3x/new_name.png
```

**Single directory with scale parameter**:
```bash
# Copy only the required scale (e.g., 4x)
cp .ui-workspace/$FEATURE/figma_images/4x/asset.png assets/new_name.png
# Then use: Image.asset('assets/new_name.png', scale: 4)
```

**No standard structure**:
```bash
# Default to 3x scale in single directory
cp .ui-workspace/$FEATURE/figma_images/3x/asset.png assets/new_name.png
# Use with explicit scale: Image.asset('assets/new_name.png', scale: 3)
```

Rename assets to meaningful names using snake_case (e.g., `profile_avatar.png`, `feed_background.png`).

**6. Create Asset Mapping**

Maintain `.ui-workspace/$FEATURE/figma_images/mapping.json`:

```json
{
  "123:456_user_avatar.png": "assets/profile_avatar.png",
  "789:012_background.png": "assets/feed_background.png"
}
```

**7. Update pubspec.yaml**

Ensure assets are declared according to the app's structure:

**Multi-directory**:
```yaml
flutter:
  assets:
    - assets/
    - assets/2x/
    - assets/3x/
```

**Single directory**:
```yaml
flutter:
  assets:
    - assets/
```

### Step 4: Testing

#### Create Golden Tests

Write golden tests to capture widget screenshots:

```dart
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';

void main() {
  testWidgets('FeatureName screen golden test', (WidgetTester tester) async {
    // Set device size to match Figma design
    await tester.binding.setSurfaceSize(Size(375, 812)); // Example: iPhone X

    await tester.pumpWidget(
      MaterialApp(
        home: YourImplementedScreen(),
      ),
    );

    await expectLater(