Figma Integration

Overview

Fataplus integrates with Figma to provide real-time design synchronization across your multi-tenant CRM. This enables seamless collaboration between designers and developers, with automated design asset management stored on Cloudflare R2.

Figma integration is essential for the design-first workflow at Fataplus, allowing teams to maintain design consistency across all client projects.

Setup and Configuration

Creating a Figma App

Visit the Figma Developers Portal
Create a new app for your Fataplus instance
Configure the required permissions:

{
  "scopes": [
    "files:read",
    "file_comments:read",
    "webhooks:write"
  ]
}

Environment Configuration

Add your Figma credentials to your environment configuration:

# Figma API Configuration
FIGMA_ACCESS_TOKEN=your_figma_token
FIGMA_TEAM_ID=your_team_id

# Cloudflare for asset storage
CLOUDFLARE_ACCOUNT_ID=your_account_id
CLOUDFLARE_API_KEY=your_api_key

Never commit your Figma access tokens to version control. Use environment variables and secrets management.

Real-Time Design Sync

How It Works

Fataplus uses Figma’s API to synchronize design files across the platform:

Fetching Design Files

The platform automatically syncs design files from your Figma workspace:

const FIGMA_API_BASE = 'https://api.figma.com/v1';

export async function fetchDesignFile(fileKey: string) {
  const response = await fetch(
    `${FIGMA_API_BASE}/files/${fileKey}`,
    {
      headers: {
        'X-Figma-Token': process.env.FIGMA_ACCESS_TOKEN,
      },
    }
  );
  
  if (!response.ok) {
    throw new Error(`Failed to fetch Figma file: ${response.statusText}`);
  }
  
  return response.json();
}

export async function exportDesignAssets(
  fileKey: string,
  nodeIds: string[],
  format: 'png' | 'svg' | 'jpg' = 'png'
) {
  const ids = nodeIds.join(',');
  const response = await fetch(
    `${FIGMA_API_BASE}/images/${fileKey}?ids=${ids}&format=${format}`,
    {
      headers: {
        'X-Figma-Token': process.env.FIGMA_ACCESS_TOKEN,
      },
    }
  );
  
  return response.json();
}

Webhooks for Updates

Setting Up Webhooks

Figma webhooks notify your application when designs are updated:

Configure Webhook Endpoint

Create a Cloudflare Worker endpoint to receive Figma webhooks:

src/api/webhooks/figma.ts

export async function handleFigmaWebhook(request: Request) {
  const payload = await request.json();
  
  // Verify webhook signature
  const isValid = await verifyFigmaSignature(
    request.headers.get('X-Figma-Signature'),
    payload
  );
  
  if (!isValid) {
    return new Response('Invalid signature', { status: 401 });
  }
  
  // Process design updates
  if (payload.event_type === 'FILE_UPDATE') {
    await syncDesignChanges(payload.file_key);
  }
  
  return new Response('OK', { status: 200 });
}

Use the Figma API to register your webhook endpoint:

curl -X POST https://api.figma.com/v2/webhooks \
  -H "X-Figma-Token: $FIGMA_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "FILE_UPDATE",
    "team_id": "your_team_id",
    "endpoint": "https://your-app.fata.plus/api/webhooks/figma",
    "passcode": "your_webhook_secret"
  }'

Handle Design Updates

Process incoming design changes and update your design system:

async function syncDesignChanges(fileKey: string) {
  // Fetch updated design
  const design = await fetchDesignFile(fileKey);
  
  // Extract design tokens
  const tokens = extractDesignTokens(design);
  
  // Update design system cache
  await updateDesignSystem(tokens);
  
  // Trigger rebuild for affected tenants
  await triggerTenantRebuild(fileKey);
}

Webhook Event Types

FILE_UPDATE

Triggered when a Figma file is modified:

{
  "event_type": "FILE_UPDATE",
  "file_key": "abc123",
  "timestamp": "2026-03-03T10:00:00Z",
  "triggered_by": {
    "id": "user_id",
    "handle": "designer@fata.plus"
  }
}

FILE_VERSION_UPDATE

Triggered when a new version is created:

{
  "event_type": "FILE_VERSION_UPDATE",
  "file_key": "abc123",
  "version_id": "v1.2.3",
  "description": "Updated brand colors"
}

FILE_COMMENT

Triggered when comments are added:

{
  "event_type": "FILE_COMMENT",
  "file_key": "abc123",
  "comment_id": "comment_123",
  "message": "Please review this design"
}

Authentication

Personal Access Tokens

For development and testing, use personal access tokens:

Generate Token

Go to Figma Settings → Account
Scroll to Personal Access Tokens
Click “Generate new token”
Copy the token immediately (it won’t be shown again)

Add to Environment

FIGMA_ACCESS_TOKEN=figd_your_personal_token_here

OAuth 2.0 (Production)

For production multi-tenant environments, use OAuth 2.0:

export async function initiateOAuth(tenantId: string) {
  const authUrl = new URL('https://www.figma.com/oauth');
  authUrl.searchParams.set('client_id', process.env.FIGMA_CLIENT_ID);
  authUrl.searchParams.set('redirect_uri', 
    `https://${tenantId}.fata.plus/auth/figma/callback`
  );
  authUrl.searchParams.set('scope', 'files:read');
  authUrl.searchParams.set('state', generateSecureState());
  authUrl.searchParams.set('response_type', 'code');
  
  return authUrl.toString();
}

export async function exchangeCodeForToken(code: string) {
  const response = await fetch('https://www.figma.com/api/oauth/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      client_id: process.env.FIGMA_CLIENT_ID,
      client_secret: process.env.FIGMA_CLIENT_SECRET,
      redirect_uri: process.env.FIGMA_REDIRECT_URI,
      code,
      grant_type: 'authorization_code',
    }),
  });
  
  return response.json();
}

Asset Storage

Cloudflare R2 Integration

Design assets are stored in Cloudflare R2 for fast global delivery:

# R2 Bucket for design assets
[[r2_buckets]]
binding = "DESIGN_ASSETS"
bucket_name = "fataplus-design-assets"

[[r2_buckets]]
binding = "TENANT_ASSETS"
bucket_name = "fataplus-tenant-assets"

Design System Workflow

Complete Integration Flow

Best Practices

Version Control

Always use Figma’s version history to track design changes and maintain rollback capability.

Caching Strategy

Implement proper caching with cache invalidation on design updates to ensure fresh assets.

Asset Optimization

Export assets in appropriate formats (SVG for icons, PNG for images) and optimize file sizes.

Tenant Isolation

Store tenant-specific design customizations separately to maintain multi-tenant architecture.

Troubleshooting

Webhook not receiving events

Solution:

Verify webhook is registered: curl -H "X-Figma-Token: $TOKEN" https://api.figma.com/v2/webhooks
Check webhook endpoint is publicly accessible
Verify webhook signature validation logic
Check Cloudflare Workers logs for errors

Authentication failures

Solution:

Verify token has not expired
Check token has correct permissions (files:read)
Ensure token is properly set in environment variables
For OAuth, verify redirect URI matches exactly

Assets not syncing

Solution:

Check R2 bucket permissions and bindings
Verify asset export format is supported
Check network connectivity to Figma API
Review Worker execution logs for errors

Next Steps

UI Components

Explore the component library built from Figma designs

Brand Management

Learn how to manage tenant-specific branding

​Overview

​Setup and Configuration

​Creating a Figma App

​Environment Configuration

​Real-Time Design Sync

​How It Works

​Fetching Design Files

​Webhooks for Updates

​Setting Up Webhooks

​Webhook Event Types

​Authentication

​Personal Access Tokens

​OAuth 2.0 (Production)

​Asset Storage

​Cloudflare R2 Integration

​Design System Workflow

​Complete Integration Flow

​Best Practices

Version Control

Caching Strategy

Asset Optimization

Tenant Isolation

​Troubleshooting

​Next Steps

UI Components

Brand Management

Overview

Setup and Configuration

Creating a Figma App

Environment Configuration

Real-Time Design Sync

How It Works

Fetching Design Files

Webhooks for Updates

Setting Up Webhooks

Webhook Event Types

Authentication

Personal Access Tokens

OAuth 2.0 (Production)

Asset Storage

Cloudflare R2 Integration

Design System Workflow

Complete Integration Flow

Best Practices

Troubleshooting

Next Steps