Figma Multi Env Setup

---
name: figma-multi-env-setup
description: 'Configure Figma API access across dev, staging, and production environments.

  Use when setting up per-environment tokens, managing multiple Figma files,

  or isolating development from production Figma resources.

  Trigger with phrases like "figma environments", "figma staging",

  "figma dev prod", "figma environment config".

  '
allowed-tools: Read, Write, Edit, Bash(gcloud:*), Bash(vault:*)
version: 1.6.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- figma
compatibility: Designed for Claude Code
---
# Figma Multi-Environment Setup

## Overview

Configure separate Figma API credentials and file targets per environment. Use different PATs with minimal scopes, point to different Figma files, and prevent accidental production operations from dev.

## Prerequisites

- Separate Figma PATs for each environment
- Secret management solution
- Environment detection in application

## Instructions

### Step 1: Environment Strategy

| Environment | PAT Scopes | Figma File | Cache TTL |
|-------------|-----------|------------|-----------|
| Development | `file_content:read` | Copy of design file | 10s (fast iteration) |
| Staging | `file_content:read`, `file_comments:read` | Staging branch/file | 60s |
| Production | `file_content:read`, `webhooks:write` | Production design file | 300s |

### Step 2: Configuration by Environment

```typescript
// src/config/figma.ts
interface FigmaEnvConfig {
  token: string;
  fileKey: string;
  cacheTTL: number;
  webhookPasscode?: string;
  maxConcurrency: number;
}

function getFigmaConfig(): FigmaEnvConfig {
  const env = process.env.NODE_ENV || 'development';

  const configs: Record<string, Partial<FigmaEnvConfig>> = {
    development: {
      token: process.env.FIGMA_PAT_DEV!,
      fileKey: process.env.FIGMA_FILE_KEY_DEV!,
      cacheTTL: 10_000,
      maxConcurrency: 1,
    },
    staging: {
      token: process.env.FIGMA_PAT_STAGING!,
      fileKey: process.env.FIGMA_FILE_KEY_STAGING!,
      cacheTTL: 60_000,
      maxConcurrency: 3,
    },
    production: {
      token: process.env.FIGMA_PAT_PROD!,
      fileKey: process.env.FIGMA_FILE_KEY_PROD!,
      cacheTTL: 300_000,
      maxConcurrency: 5,
      webhookPasscode: process.env.FIGMA_WEBHOOK_PASSCODE,
    },
  };

  const config = configs[env];
  if (!config?.token) throw new Error(`Figma token not configured for env: ${env}`);
  if (!config?.fileKey) throw new Error(`Figma file key not configured for env: ${env}`);

  return config as FigmaEnvConfig;
}
```

### Step 3: Environment Files

```bash
# .env.development
FIGMA_PAT_DEV="figd_dev-token-read-only"
FIGMA_FILE_KEY_DEV="devFileKey123"

# .env.staging
FIGMA_PAT_STAGING="figd_staging-token"
FIGMA_FILE_KEY_STAGING="stagingFileKey456"

# .env.production (stored in secret manager, not in repo)
FIGMA_PAT_PROD="figd_prod-token"
FIGMA_FILE_KEY_PROD="prodFileKey789"
FIGMA_WEBHOOK_PASSCODE="webhook-secret"

# .env.example (committed to repo as template)
FIGMA_PAT_DEV=
FIGMA_FILE_KEY_DEV=
```

### Step 4: Secret Management

```bash
# GitHub Actions -- use environment-scoped secrets
gh secret set FIGMA_PAT_PROD --env production --body "figd_..."
gh secret set FIGMA_PAT_STAGING --env staging --body "figd_..."

# Google Cloud Secret Manager
echo -n "figd_prod-token" | gcloud secrets create figma-pat-prod --data-file=-
echo -n "figd_staging-token" | gcloud secrets create figma-pat-staging --data-file=-

# Load in Cloud Run
gcloud run deploy my-service \
  --set-secrets="FIGMA_PAT_PROD=figma-pat-prod:latest"
```

### Step 5: Environment Guards

```typescript
// Prevent production-specific operations in non-production
function requireProduction(operation: string) {
  if (process.env.NODE_ENV !== 'production') {
    throw new Error(
      `${operation} is only allowed in production. ` +
      `Current env: ${process.env.NODE_ENV}`
    );
  }
}

// Prevent destructive operations in production
function blockInProduction(operation: string) {
  if (process.env.NODE_ENV === 'production') {
    throw new Error(`${operation} is blocked in production for safety`);
  }
}

// Usage
async function createWebhook(config: any) {
  requireProduction('createWebhook'); // Only in prod
  return fetch('https://api.figma.com/v2/webhooks', { ... });
}

async function deleteAllCachedData() {
  blockInProduction('deleteAllCachedData'); // Never in prod
  await cache.clear();
}
```

## Output

- Per-environment Figma configuration
- Secrets stored in appropriate secret managers
- Environment guards preventing cross-env mistakes
- Template env files for team onboarding

## Error Handling

| Issue | Cause | Solution |
|-------|-------|----------|
| Wrong file in dev | Using prod file key | Verify FIGMA_FILE_KEY_DEV |
| PAT expired in CI | 90-day expiry | Set rotation reminder per environment |
| Staging webhook pointing to prod | Wrong endpoint URL | Verify webhook endpoint per env |
| Config not loading | Missing NODE_ENV | Set NODE_ENV in deployment config |

## Examples

Point the same integration at a staging file locally and the production file in CI using the Step 2 config loader:

```bash
# .env.development
FIGMA_ENV=development
FIGMA_FILE_KEY=stgAbC123fileKey
FIGMA_WEBHOOK_ENDPOINT=https://dev.example.com/figma/webhook

# CI (production) — secrets injected, never committed
FIGMA_ENV=production
FIGMA_FILE_KEY=prodXyZ789fileKey
```

Verify the guard refuses a cross-environment mistake before any API call is made:

```bash
FIGMA_ENV=production FIGMA_FILE_KEY=stgAbC123fileKey node sync-tokens.js
# Error: production run pointed at a non-production file key — aborting
```

Environment strategy and per-env webhook registration (`POST /v2/webhooks` per environment): `references/configuration-by-environment.md` and `references/environment-guards.md`.

## Resources

- [Figma Authentication](https://developers.figma.com/docs/rest-api/authentication/)
- [12-Factor App Config](https://12factor.net/config)
- [GitHub Environments](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment)

## Next Steps

For observability setup, see `figma-observability`.