# Figma Integration Guide

## Overview

This document explains how to work with Figma files for Symph Agency design outputs.

**⚠️ Key Limitation:** Figma's REST API is **read-only for file management**. You cannot create, duplicate, rename, or delete files via API.

---

## What Figma REST API CAN Do

| Action | Endpoint | Notes |
|--------|----------|-------|
| Get file structure | `GET /v1/files/{key}` | Read JSON representation |
| Export images | `GET /v1/images/{key}` | Render nodes as PNG/SVG/PDF |
| Get file metadata | `GET /v1/files/{key}/meta` | Name, timestamps, etc. |
| Comments | `GET/POST /v1/files/{key}/comments` | Read/write comments |
| List projects | `GET /v1/teams/{id}/projects` | List team projects |
| List files | `GET /v1/projects/{id}/files` | List files in project |
| Webhooks | Various | Event subscriptions |

## What Figma REST API CANNOT Do

- ❌ Create files
- ❌ Duplicate files  
- ❌ Rename files
- ❌ Delete files
- ❌ Import images into files
- ❌ Modify file contents

---

## Current Workflow (Manual Figma Steps)

### Prerequisites

1. **Starter Template** in Figma project
   - Name: `Starter (DON'T DELETE!)`
   - Contains: Brand system, component library, page templates
   - Location: Team 967020711342847286 / Project 546009610
   - **NEVER delete or modify this file directly**

2. **Figma Access** for the human operator
   - Account: designers@symph.co (or team member)
   - Must have edit access to the project

### Step-by-Step Process

#### 1. Generate All Screens (ARIA does this)
```bash
# Use Nano Banana Pro to generate each screen
uv run $NANO_DIR/scripts/generate_image.py \
  --prompt "Dashboard screen for [product], showing..." \
  --filename "S001-dashboard.png" \
  --resolution 2K
```

#### 2. Create Figma File (Human does this)
1. Open Figma project: https://www.figma.com/files/team/967020711342847286/project/546009610
2. Right-click on `Starter (DON'T DELETE!)` 
3. Click **Duplicate**
4. Right-click the new copy
5. Click **Rename** → Enter: `[Product Name] - UI Screens`
6. Right-click → **Copy link**

#### 3. Register File URL (ARIA does this)
```bash
./scripts/figma-set-url.sh <product-name> <figma-url>
```

#### 4. Import Images (Human does this)
1. Open the duplicated Figma file
2. Use Place Image (Ctrl/Cmd + Shift + K)
3. Select all PNGs from product's `artifacts/design/screens/`
4. Place each as a frame
5. Organize into pages by flow

#### 5. Finalize (ARIA does this)
```bash
./scripts/design-workflow.sh <product-name> complete <approver>
```

---

## Symph Figma Configuration

Store in `.env`:
```bash
FIGMA_ACCESS_TOKEN=figd_xxxxx
FIGMA_TEAM_ID=967020711342847286
FIGMA_PROJECT_ID=546009610
FIGMA_STARTER_FILE_KEY=<key-of-starter-file>
```

---

## API Scripts (Read Operations Only)

### Get File Info
```bash
./scripts/figma-get-file.sh <file-key>
```

### Set URL After Manual Creation
```bash
./scripts/figma-set-url.sh <product-name> <figma-url>
```

---

## Future: Figma Plugin (For Full Automation)

The only way to programmatically create/modify Figma files is via a **Figma Plugin** running inside the Figma app.

### Plugin Would Enable:
- Read screen images from URL/path
- Create frames automatically
- Import images into frames
- Apply component library styles

### Plugin Development Requirements:
- TypeScript/JavaScript
- Figma Plugin API knowledge
- Figma Desktop app for testing
- Publish to Figma Community or keep private

**Decision:** Manual workflow (one click per product) is acceptable for now. Plugin is future enhancement if volume increases.

### Human Designer Handoff Checklist
After ARIA generates design assets, the human designer needs to:
1. **Duplicate** the Starter file (browser automation can do this)
2. **Rename** the copy to `[Product Name] - UI Screens` (manual — API doesn't support)
3. **Import** generated PNGs into the Figma file

---

## Troubleshooting

### "Duplicate" option not showing
- Must right-click from **project view**, not search results
- Must have edit permissions on the project

### Starter file was deleted
- Create new file with brand system and components
- Rename to `Starter (DON'T DELETE!)`
- Update `FIGMA_STARTER_FILE_KEY` in `.env`

### API returns 403
- Token expired → Generate new token in Figma settings
- Wrong scope → Token needs `file_content:read` minimum

---

## Resources

- Figma REST API Docs: https://developers.figma.com/docs/rest-api/
- Figma Plugin Docs: https://www.figma.com/plugin-docs/
- OpenAPI Spec: https://github.com/figma/rest-api-spec
