# Figma to Next.js Code Generator (`enforceable_orbit/figma-actor`) Actor

AI-powered Figma to Next.js code generator. Converts Figma designs to React components with Tailwind CSS. Auto-generates landing pages, dashboards, and complete websites. Claude AI included - no API key needed.

- **URL**: https://apify.com/enforceable\_orbit/figma-actor.md
- **Developed by:** [Cytech Development SRL](https://apify.com/enforceable_orbit) (community)
- **Categories:** AI, Developer tools, Automation
- **Stats:** 19 total users, 0 monthly users, 0.0% runs succeeded, 1 bookmarks
- **User rating**: 4.00 out of 5 stars

## Pricing

from $0.01 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Figma to Next.js Code Generator

Transform your Figma designs into production-ready Next.js applications with Tailwind CSS in minutes. This Apify Actor uses **Claude AI (included - no API key needed!)** to generate clean, responsive, and fully-typed React code from any Figma file.

> **⚠️ Important - Scope Clarification:** This Actor generates **frontend UI code only** (React components, layouts, navigation, styling). It does **NOT** generate backend logic, authentication, APIs, or database integrations. Perfect for landing pages, marketing websites, portfolios, and UI prototypes that you'll connect to your existing backend.

### 🚀 What Does This Actor Do?

This Actor automatically converts your Figma designs into **production-ready frontend code**. Simply provide your Figma file key and access token, and get back a fully functional Next.js UI with:

- **✅ Next.js Frontend App** - Complete UI with App Router, pages, and components
- **✅ Pixel-Perfect Components** - React components matching your Figma designs exactly
- **✅ Responsive by Default** - Automatically handles Desktop, Tablet, and Mobile breakpoints
- **✅ Design System Ready** - Your colors, typography, and spacing as Tailwind tokens
- **✅ TypeScript Support** - Fully typed components and pages for better developer experience
- **✅ Navigation & Routing** - Next.js Link components for page navigation
- **✅ Production-Quality Code** - Clean, maintainable React following best practices

**What you'll need to add yourself:**
- **❌ Backend APIs** - Connect to your existing backend or build one
- **❌ Authentication** - Implement login/signup with NextAuth, Clerk, Auth0, etc.
- **❌ Database** - Connect PostgreSQL, MongoDB, Supabase, etc.
- **❌ Business Logic** - Form validation, data processing, API calls
- **❌ State Management** - Redux, Zustand, Jotai for complex state
- **❌ Real-time Features** - WebSockets, live updates, subscriptions

**Perfect for:** Landing pages • Marketing websites • Portfolios • UI prototypes • Design systems • Dashboards
**Not suitable for:** Full-stack apps requiring backend (use the generated UI as your starting point!)

### ✨ Main Features

- **🤖 AI-Powered Generation** - Uses Claude Sonnet 4.5 (included - no API key needed!)
- **🎨 Smart Component Detection** - Automatically identifies and extracts reusable components
- **📱 Responsive Design** - Intelligently groups Desktop/Mobile/Tablet variants
- **🎯 Design Token Export** - Your Figma styles become Tailwind configuration
- **🔄 Prototype Flow Analysis** - Analyzes interactions and navigation patterns
- **🛡️ Error Recovery** - Automatic retries and graceful handling of API limits
- **📦 Ready to Deploy** - Get a ZIP file with complete Next.js project
- **⚡ Fast Processing** - Typically completes in 2-5 minutes

### 🎯 Scope & Limitations

#### What This Tool Generates

This Actor creates the **visual layer** of your application - everything users see and interact with in the browser. Think of it as automating the tedious "design-to-code translation" part of development, not building complete full-stack applications.

**Generated Output:**
- ✅ React/TypeScript components for all UI elements
- ✅ Tailwind CSS classes for styling
- ✅ Next.js App Router pages and layouts
- ✅ Navigation components with Next.js Link
- ✅ Responsive breakpoints (mobile, tablet, desktop)
- ✅ Design tokens as Tailwind config
- ✅ Package.json with dependencies
- ✅ README with setup instructions

#### What You Need to Add

To make your generated UI functional, you'll need to add:

**Backend & Data:**
- 🔧 **REST/GraphQL APIs** - Connect to your backend endpoints
- 🔧 **Database Integration** - PostgreSQL, MongoDB, Supabase, etc.
- 🔧 **Data Fetching** - Add fetch() calls, React Query, SWR, etc.
- 🔧 **Server Actions** - Next.js 14+ server actions for mutations

**Authentication & Security:**
- 🔧 **Auth System** - NextAuth, Clerk, Auth0, Supabase Auth
- 🔧 **Protected Routes** - Middleware for authenticated pages
- 🔧 **User Sessions** - Session management and persistence
- 🔧 **Authorization** - Role-based access control (RBAC)

**Business Logic:**
- 🔧 **Form Handling** - Form validation, submission, error handling
- 🔧 **State Management** - Redux, Zustand, Jotai for complex state
- 🔧 **API Integration** - Connect forms and buttons to your backend
- 🔧 **Error Handling** - Production-ready error boundaries

**Advanced Features:**
- 🔧 **Real-time** - WebSockets, Server-Sent Events, subscriptions
- 🔧 **Payments** - Stripe, PayPal integration
- 🔧 **File Uploads** - Image/document upload handling
- 🔧 **Search** - Full-text search, filtering, pagination
- 🔧 **Analytics** - Google Analytics, Mixpanel, etc.

#### Typical Development Workflow

1. **Generate UI with this Actor** (10 minutes)
   - Get pixel-perfect components and layouts
   - Review code quality and structure
   - Make minor adjustments if needed

2. **Add Backend Integration** (your existing development time)
   - Connect forms to your API endpoints
   - Implement authentication
   - Add database queries
   - Wire up business logic

3. **Deploy to Production**
   - Vercel, Netlify, or your platform
   - Connect environment variables
   - Set up domain and SSL

**Time Savings:** This Actor saves 10-20 hours of manual UI coding per project, letting you focus on the backend logic that actually differentiates your application.

#### Best Use Cases

**✅ Excellent for:**
- Landing pages and marketing websites
- SaaS marketing sites (homepage, pricing, about)
- Portfolios and personal websites
- UI prototypes for user testing
- Design systems and component libraries
- Admin dashboards (UI only)
- Documentation sites

**⚠️ Not ideal for:**
- E-commerce (needs Stripe, cart, inventory backend)
- Social networks (needs user system, feeds, notifications)
- Real-time apps (needs WebSocket backend)
- Full-stack SaaS (needs backend, DB, auth - but use UI as starting point!)

**💡 Pro Tip:** Even for full-stack apps, this tool gives you a massive head start. Generate the UI in 10 minutes, then spend your development time on the interesting backend logic instead of manually coding layouts.

### 🎯 Preparing Your Figma File for Flawless Generation

To ensure the best possible code generation, your Figma file must follow specific structural requirements. Following these guidelines will result in clean, accurate code on the first try.

#### Critical Requirements Checklist

Before running this Actor, verify your Figma file has:

- ✅ **Clear, descriptive frame names** (e.g., "Homepage", "HeroSection" - NOT "Frame 1", "Frame 2")
- ✅ **All reusable elements converted to Figma components**
- ✅ **Auto Layout applied to containers** (helps generate proper flex/grid layouts)
- ✅ **Named color and text styles defined** in Figma
- ✅ **Logical section organization** (1st-level children of frames become sections)
- ✅ **Hidden guide layers prefixed with "_"** (e.g., "_notes", "_guides")

#### Figma File Structure Requirements

Your Figma file structure differs based on the mode you choose:

##### Landing Page Mode Structure

For a single responsive page, organize your file like this:

````

📄 Page (any name)
└── 🖼️ Frame (e.g., "Landing Page" or "Homepage")
├── Header (section)
├── Hero (section)
├── Features (section)
├── Testimonials (section)
├── Pricing (section)
└── Footer (section)

```

**Important Notes:**
- Each **1st-level child** of the frame becomes a section in your page
- Sections are automatically sorted top-to-bottom by Y-coordinate
- Typical landing pages have **5-10 sections**
- Avoid deeply nested structures (sections should be direct children)

##### Multi-Page Mode Structure

For multiple pages with navigation, organize like this:

```

📄 Page (any name)
├── 🖼️ Home (frame → becomes / route)
│    ├── HomeHero (section)
│    ├── HomeFeatures (section)
│    └── HomeFooter (section)
├── 🖼️ Pricing (frame → becomes /pricing route)
│    ├── PricingHero (section)
│    ├── PricingTable (section)
│    └── PricingFAQ (section)
├── 🖼️ About (frame → becomes /about route)
│    ├── AboutHero (section)
│    └── AboutTeam (section)
└── 🖼️ Contact (frame → becomes /contact route)
├── ContactHero (section)
└── ContactForm (section)

```

**Important Notes:**
- Each **frame** becomes a separate page/route
- Frame names must **match exactly** (case-sensitive) with `frameNames` input
- First frame (or frame named "Home") becomes homepage `/`
- Other frames become routes like `/pricing`, `/about`, `/contact`
- Each frame's 1st-level children become that page's sections

#### Component Classification System

The Actor automatically classifies elements based on size and complexity:

**UI Components** (Small, reusable elements):
- **Size**: Width < 400px AND height < 300px
- **Examples**: Buttons, icons, badges, inputs, checkboxes, avatars, cards
- **Naming**: Use descriptive names like "PrimaryButton", "UserAvatar", "PriceCard"

**Sections** (Large, structural elements):
- **Size**: Width > 500px OR height > 350px
- **Examples**: Headers, heroes, footers, navigation bars, feature grids, testimonials
- **Naming**: Use descriptive names like "HeroSection", "NavigationBar", "FeatureGrid"

#### Naming Conventions for Best Results

| Element Type | Good Examples | Bad Examples |
|--------------|---------------|--------------|
| **Frames** | "Homepage", "Pricing", "Contact" | "Frame 1", "Frame 2", "Untitled" |
| **Components** | "PrimaryButton", "UserCard", "NavigationBar" | "Component 1", "Rectangle 45" |
| **Sections** | "HeroSection", "PricingTable", "Footer" | "Group 7", "Frame 123" |
| **Responsive Variants** | "Header/Desktop", "Header/Mobile", "Header/Tablet" | "Header 1", "Header Copy" |

#### Asset Naming Best Practices (Icons, Logos, Images)

**Why Asset Naming Matters:**
Proper asset naming ensures the actor downloads your icons and logos correctly, generates descriptive filenames, and helps the AI code generator use them appropriately in your components.

##### 7 Best Practices for Asset Naming

**1. Avoid Numeric Suffixes for Duplicates**
- ❌ **Bad**: `apple-logo 2`, `apple-logo 3`, `icon-home 2`
- ✅ **Good**: Use unique descriptive names like `apple-logo-dark`, `apple-logo-light`, `icon-home-filled`
- **Note**: The actor automatically strips numeric suffixes for deduplication (e.g., "apple-logo 2" → "apple-logo"), but it's better to name them uniquely from the start

**2. Use Descriptive, Semantic Names**
- ❌ **Bad**: `Frame 1`, `Rectangle 45`, `Group 7`, `Vector`
- ✅ **Good**: `HeroSection`, `CTAButton`, `UserAvatar`, `AppleLogo`
- **Why**: Helps the AI understand what each element represents and use it correctly in generated code

**3. Follow Consistent Naming Conventions**
- **kebab-case for assets**: `apple-logo`, `icon-home`, `user-avatar`, `hero-background`
- **PascalCase for components**: `PrimaryButton`, `NavigationBar`, `UserCard`
- **Prefix hidden elements**: `_notes`, `_guides`, `_annotations`

**4. Be Specific About Asset Type**
- **Icons**: Include "icon" in the name → `icon-search`, `icon-menu`, `icon-close`
- **Logos**: Include "logo" in the name → `company-logo`, `brand-wordmark`, `footer-logo`
- **Images**: Describe the content → `hero-background`, `product-photo`, `team-image`
- **Graphics**: Use descriptive names → `wave-decoration`, `circle-pattern`

**5. Include Variants in the Name**
- **States**: `button-primary-hover`, `button-primary-disabled`, `link-active`
- **Colors**: `logo-black`, `logo-white`, `icon-blue`, `icon-gray`
- **Sizes**: `avatar-small`, `avatar-large`, `logo-compact`, `logo-full`
- **Themes**: `icon-light-mode`, `icon-dark-mode`

**6. Avoid Special Characters**
- ✅ **Use**: Letters (a-z, A-Z), numbers (0-9), hyphens (-), underscores (_)
- ❌ **Avoid**: Spaces, slashes (/), periods (.), @, #, $, %, &, *, etc.
- **Why**: The actor sanitizes names, but clean names from the start prevent confusion

**7. Use Figma Components for Reusable Assets**
- For icons/logos used multiple times, convert to **Figma Components**
- This prevents duplicate exports and numeric suffix issues
- Components are automatically deduplicated by the actor

##### Quick Reference: Asset Naming Examples

| Asset Type | ✅ Good Name | ❌ Bad Name |
|------------|-------------|------------|
| Platform logo | `apple-logo`, `windows-icon`, `android-logo` | `Vector 7`, `apple-logo 2`, `Logo Copy` |
| UI icon | `icon-search`, `icon-menu`, `icon-close` | `icon 2`, `Vector`, `Rectangle 45` |
| Brand logo | `company-logo`, `brand-wordmark`, `logo-dark` | `logo`, `Frame 123`, `Group 7` |
| Background image | `hero-background`, `section-bg`, `pattern-waves` | `image`, `Rectangle 1`, `bg` |
| Product image | `product-photo`, `screenshot-dashboard`, `feature-image` | `IMG_1234`, `photo`, `pic` |

#### Auto Layout Best Practices

**Why Auto Layout matters:** Auto Layout in Figma translates directly to Flexbox/Grid in your generated code, ensuring proper responsive behavior.

**Apply Auto Layout to:**
- ✅ All container frames and sections
- ✅ Navigation bars and menus
- ✅ Card layouts and grids
- ✅ Button groups and form fields
- ✅ Headers and footers

**Auto Layout Tips:**
- Set proper spacing and padding in Figma (becomes CSS margins/padding)
- Use "Hug contents" for components that adapt to content size
- Use "Fill container" for responsive sections
- Define proper alignment (start, center, end) for correct flex alignment

#### Multi-Page Mode: Prototype Navigation Requirements

For multi-page websites with proper navigation, set up **prototype flows** in Figma:

##### Required Setup:
1. **Create prototype flows** between frames in Figma
2. **Add click interactions** on buttons/links that navigate to other pages
3. **Connect frames** using Figma's prototype mode (right panel → Prototype tab)
4. **Test your prototype** in Figma before exporting

##### How Navigation Detection Works:
```

Button/Link in "Home" frame
→ Click interaction
→ Navigates to "Pricing" frame
→ Actor generates: <Link href="/pricing">...</Link>

```

##### What if I don't add prototype flows?
- Navigation will still be generated from frame order
- All specified frames will be included in navigation
- You'll see a warning in the log
- Links will work but may not match your intended user flow

#### Common Pitfalls and How to Avoid Them

##### ❌ Problem: Too Few Sections Generated
**Symptoms:** Actor finds only 1-2 sections instead of expected 5-10

**Causes:**
- Sections nested too deep (not 1st-level children)
- Sections grouped inside parent containers
- Frame has no clear section structure

**Solutions:**
- ✅ Flatten your frame structure - make sections direct children
- ✅ Ungroup nested containers if needed
- ✅ Increase `sectionExtractionDepth` (default: 5) if legitimately nested
- ✅ Check frame structure in Figma layers panel

##### ❌ Problem: Navigation Links Missing or Incorrect
**Symptoms:** Generated navigation doesn't include all pages or links are wrong

**Causes:**
- `frameNames` don't match Figma frame names exactly (case-sensitive!)
- Missing prototype flows between frames
- Typos in frame names

**Solutions:**
- ✅ Check frame names in Figma (must match exactly, including case)
- ✅ Add prototype flows in Figma (recommended)
- ✅ Verify `frameNames` array in input matches Figma
- ✅ Use consistent naming without special characters

##### ❌ Problem: Generic Component Names in Code
**Symptoms:** Generated code has names like "Frame123", "Rectangle45"

**Causes:**
- Using Figma's default auto-generated names
- Not renaming elements during design

**Solutions:**
- ✅ Rename all frames with descriptive names
- ✅ Rename components before running Actor
- ✅ Use PascalCase or descriptive naming conventions
- ✅ Convert reusable elements to Figma components with proper names

##### ❌ Problem: Poor Responsive Behavior
**Symptoms:** Generated code doesn't adapt well to different screen sizes

**Causes:**
- No Auto Layout applied in Figma
- Missing responsive variants (Desktop/Mobile/Tablet)
- Fixed-size elements instead of flexible containers

**Solutions:**
- ✅ Apply Auto Layout to all containers
- ✅ Create responsive variants with proper naming
- ✅ Use "Fill container" for flexible widths
- ✅ Define proper constraints in Figma

##### ❌ Problem: "Frame Not Found" Error
**Symptoms:** Actor fails with "Frame 'X' not found in Figma file"

**Causes:**
- Typo in `frameNames` input
- Case sensitivity mismatch
- Frame name changed in Figma after initial planning

**Solutions:**
- ✅ Copy frame names directly from Figma
- ✅ Check capitalization matches exactly
- ✅ Verify frame exists on the specified page
- ✅ Ensure frame is not inside another frame (should be top-level)

#### Pre-Flight Checklist

Use this checklist before running the Actor to ensure optimal results:

##### For Landing Page Mode:
- [ ] Frame has a descriptive name (not "Frame 1")
- [ ] Frame contains 5-10 section elements as direct children
- [ ] All sections have descriptive names
- [ ] Auto Layout applied to main containers
- [ ] Color and text styles defined in Figma
- [ ] Reusable elements converted to components
- [ ] Hidden layers/guides prefixed with "_"

##### For Multi-Page Mode:
- [ ] Each page is a separate top-level frame
- [ ] Frame names are descriptive and match `frameNames` input exactly
- [ ] Each frame contains logical sections as direct children
- [ ] Prototype flows connect navigation elements (recommended)
- [ ] Frame names don't contain special characters
- [ ] Auto Layout applied throughout
- [ ] Consistent naming across all frames

##### General Requirements:
- [ ] Figma Access Token is valid and starts with `figd_`
- [ ] File key extracted correctly from Figma URL
- [ ] No extremely complex components (> 50 nested layers)
- [ ] File size is reasonable (< 100 top-level frames)
- [ ] All important elements are visible (not hidden in Figma)

#### Tips for Best Results

**🎨 Design System Setup:**
- Define color styles in Figma (becomes Tailwind color tokens)
- Define text styles in Figma (becomes Tailwind typography)
- Use consistent spacing (8px grid recommended)
- Create component sets for variants

**📐 Layout Organization:**
- Use frames for pages/screens
- Use sections for major layout divisions
- Use components for reusable UI elements
- Keep hierarchy shallow (avoid deep nesting)

**🏷️ Naming Strategy:**
- Be descriptive and specific
- Use consistent casing (PascalCase recommended)
- Avoid generic names ("Frame", "Group", "Rectangle")
- Include semantic meaning ("Header", "Hero", "CTA")

**📱 Responsive Design:**
- Create variants for Desktop (1440px), Tablet (768px), Mobile (375px)
- Name variants consistently: "ComponentName/Desktop", "ComponentName/Mobile"
- Use Auto Layout for flexible components
- Test your Figma responsive behavior before generating code

### 💰 How Much Does It Cost to Generate Code from Figma?

This Actor uses **pay-per-event pricing** - you only pay for what you use:

- **$0.05** - Actor start (base fee)
- **$0.15** - Design extraction
- **$0.03** - Per component generated
- **$0.08** - Per page generated
- **$0.02** - Per AI code generation call

**Example:** A project with 10 components and 3 pages costs approximately **$1.00**.

**What's included:** AI code generation (Claude API), Figma integration, production-ready Next.js code, Tailwind CSS configuration, and design tokens.

**What you need:** Only your Figma Personal Access Token (free from Figma).

### 🎯 How to Generate Next.js Code from Figma Designs

#### Step 1: Get Your Figma Token (Free)

1. Go to [Figma Settings → Personal Access Tokens](https://www.figma.com/settings)
2. Click "Generate new token"
3. Give it a name (e.g., "Code Generator")
4. Copy the token (starts with `figd_`)

#### Step 2: Get Your Figma File Key

Extract the file key from your Figma URL:
```

https://www.figma.com/file/abc123def456/My-Design
↑
This is your file key: abc123def456

````

**Try with Example:** Use this public Figma file for testing:
- **[Whitepace - SaaS Landing Page](https://www.figma.com/community/file/1156860863353724933)**
- File key: `1156860863353724933`


#### Step 3: Run the Actor

1. Click the **"Try for free"** button on this page
2. Enter your inputs:
   - **Figma File Key**: Your file key or use `1156860863353724933` for testing
   - **Figma Access Token**: Your token from step 1
   - **Component Naming**: Choose PascalCase (recommended)
   - **TypeScript**: Enable (recommended)
3. Click **"Start"** and wait a few minutes

#### Step 4: Download Your Next.js App

1. When the run completes, go to the **Storage** tab
2. Click **Key-value store**
3. Find the **OUTPUT** record
4. Click **Download** to get your ZIP file
5. Extract and run your new Next.js app:
   ```bash
   npm install
   npm run dev
````

6. Open http://localhost:3000 🎉

**✅ That's it!** Your Figma design is now a working Next.js application.

### 📋 What This Actor Does

#### ✨ Perfect For

- **Landing Pages** - Marketing sites, product pages, portfolios
- **Dashboards** - Admin panels, analytics interfaces, data visualizations
- **SaaS Applications** - User interfaces, onboarding flows, settings pages
- **E-commerce** - Product listings, checkout flows, user accounts
- **Design Systems** - Component libraries with consistent theming
- **Prototypes** - Quick MVPs and proof-of-concepts from Figma designs

#### ✅ What's Included

- Extracts all frames, components, and styles from your Figma file
- Generates a complete Next.js application with App Router
- Creates responsive layouts from Desktop/Mobile/Tablet variants
- Converts Figma components to reusable React components
- Exports design tokens (colors, typography, spacing) as Tailwind config
- Handles nested components and complex layouts
- Generates TypeScript interfaces for type safety

#### ⚠️ Current Limitations

- Focuses on single-page applications (multi-page routing in development)
- Images are exported as placeholders (add your assets after generation)
- Complex animations need manual implementation
- Custom fonts should be added manually to the generated project

### 📤 Output - What You'll Get

The Actor generates a **ZIP file** containing a complete Next.js project with:

```
/
├── app/                    # Next.js App Router pages
│   ├── page.tsx           # Home page
│   ├── layout.tsx         # Root layout
│   ├── globals.css        # Global styles with Tailwind
│   └── [page-name]/       # Additional pages
│       └── page.tsx
├── components/            # React components from Figma
│   ├── Button.tsx
│   ├── Card.tsx
│   └── ...
├── tailwind.config.js     # Tailwind config with Figma design tokens
├── next.config.js         # Next.js configuration
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md             # Setup instructions
```

### 📥 Input Parameters

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `figmaFileKey` | string | Required | The Figma file key from the URL |
| `figmaAccessToken` | string | Required | Your Figma Personal Access Token |
| `componentNaming` | string | "PascalCase" | Component naming convention |
| `includeTypeScript` | boolean | true | Generate TypeScript (.tsx) files |
| `maxRequestsPerCrawl` | number | 100 | Max Figma API requests |

### 🔧 What Technology Is Used

Your generated Next.js application will use:

- **Next.js 14+** - Modern React framework with App Router
- **Tailwind CSS 3.4+** - Utility-first CSS framework
- **TypeScript 5+** - Type-safe JavaScript
- **React 18+** - Component library

### ⚡ Performance

| Metric | Typical Value |
|--------|--------------|
| **Processing Time** | 2-5 minutes for average designs |
| **Large Files** | 5-10 minutes for complex designs |
| **Memory Usage** | 512MB - 2GB depending on file size |
| **Output Size** | 100KB - 2MB ZIP file |
| **API Calls** | ~10-50 Figma API requests |

### 🐛 Troubleshooting

#### Common Issues and Solutions

##### 🔑 Authentication & Access Issues

**"Invalid Figma file key format"**

```
Error: Invalid Figma file key format. Should contain only alphanumeric characters.
```

- **Solution**: Extract the key from your Figma URL: `figma.com/file/KEY_HERE/name`
- File key should only contain letters and numbers, no special characters
- Don't include hyphens or other characters from the URL

**"Invalid Figma access token"**

```
Error: Invalid Figma access token or insufficient permissions
```

- **Solutions**:
  - Ensure token starts with `figd_`
  - Generate a new token from [Figma Settings](https://www.figma.com/settings)
  - Check token hasn't expired (tokens don't expire but can be revoked)
  - Verify you have access to the Figma file (check file permissions)

**"Figma API rate limited"**

```
Figma API rate limited. Waiting 60s before retry...
```

- **Solution**: Actor handles this automatically with exponential backoff retry logic
- Just wait for completion - the Actor will resume automatically
- Figma API has rate limits of ~100 requests per minute

##### 📊 Design Structure Issues

**"Too Few Sections Generated"**

```
Warning: Only found 2 sections, expected 5-10 for a typical landing page
```

- **Cause**: Sections are nested too deep or not direct children of the frame
- **Solutions**:
  - ✅ Check your Figma layers panel - sections should be 1st-level children of the frame
  - ✅ Ungroup any containers that wrap your sections
  - ✅ Flatten your structure: `Frame → Section` not `Frame → Group → Section`
  - ✅ Increase `sectionExtractionDepth` (default: 5) if you need deeper traversal
- **Tip**: See the "Figma File Structure Requirements" section above for correct structure

**"Frame Not Found" Error**

```
Error: Frame 'Pricing' not found in Figma file. Available frames: ['Home', 'pricing', 'About']
```

- **Cause**: Frame name mismatch (often due to case sensitivity)
- **Solutions**:
  - ✅ Copy frame names directly from Figma layers panel
  - ✅ Check capitalization matches exactly - "Pricing" ≠ "pricing"
  - ✅ Ensure frames are top-level (not nested inside other frames)
  - ✅ Verify frame exists on the selected page
- **Tip**: The error message lists available frames for easy comparison

**"No Navigation Links Generated"**

```
Warning: No prototype flows found. Navigation will be generated from frame order.
```

- **Cause**: Missing prototype flows in Figma (Multi-Page mode)
- **Impact**: Navigation still works but may not match your intended user flow
- **Solutions**:
  - ✅ Add prototype flows in Figma: Select button → Prototype tab → Click → Navigate to frame
  - ✅ Test your prototype in Figma before generating code
  - ✅ Ensure `usePrototypeNavigation` is enabled in input (default: true)
- **Note**: This is a warning, not an error - the Actor will still generate navigation

##### 🎨 Code Quality Issues

**"Generic Component Names in Generated Code"**

```
// Generated code has names like:
<Frame123 />
<Rectangle45 />
<Group7 />
```

- **Cause**: Using Figma's default auto-generated names
- **Solutions**:
  - ✅ Rename all frames with descriptive names before running the Actor
  - ✅ Use semantic names: "HeroSection", "PricingCard", "CTAButton"
  - ✅ Convert reusable elements to Figma components with proper names
  - ✅ Choose `componentNaming: "PascalCase"` for React best practices

**"Generated Code Has Poor Responsive Behavior"**

- **Symptoms**: Layout breaks on mobile/tablet, elements don't adapt
- **Cause**: No Auto Layout in Figma or missing responsive variants
- **Solutions**:
  - ✅ Apply Auto Layout to all containers in Figma
  - ✅ Create responsive variants: "Component/Desktop", "Component/Mobile", "Component/Tablet"
  - ✅ Use "Fill container" for flexible widths
  - ✅ Define proper spacing and padding in Figma Auto Layout

**"Generated Code Appears Truncated or Incomplete"**

```
Warning: Component generation hit token limit, retrying with higher limit...
```

- **Cause**: Very complex components exceeding AI token limits
- **Automatic Handling**: Actor automatically retries with higher token limits
- **If Problems Persist**:
  - ✅ Simplify extremely complex components (> 50 nested layers)
  - ✅ Break large components into smaller, reusable sub-components
  - ✅ Reduce nesting depth in your Figma design

##### 💰 Resource & Performance Issues

**"Spending Limit Reached"**

```
Message: Spending limit reached. Partial results saved.
```

- **Solution**: Increase your spending limit in Apify Console under Settings → Limits
- **Prevention**: Estimate cost based on component count (~$0.03/component + $0.08/page)
- **Note**: Partial results are saved in Key-Value Store, you can still download what was generated

**"Actor Timeout or Very Slow Processing"**

- **Typical Causes**:
  - Very large Figma files (> 100 frames)
  - Extremely complex components
  - Network issues with Figma API
- **Solutions**:
  - ✅ Increase `maxRequestsPerCrawl` if needed (default: 100)
  - ✅ Use `selectedPages` to process specific pages only
  - ✅ Break very large files into multiple smaller files
  - ✅ Check Actor timeout setting (default: 3600s = 1 hour)

**"Memory Limit Exceeded"**

```
Error: Actor run out of memory
```

- **Solution**: Increase memory allocation in Run Settings
- **Recommended**:
  - Small files (< 20 frames): 512MB
  - Medium files (20-50 frames): 1-2GB
  - Large files (> 50 frames): 2-4GB

##### 🔧 Setup & Installation Issues

**"TypeScript Errors in Generated Code"**

```
Error: Cannot find module 'react' or its corresponding type declarations
```

- **Solutions**:
  - ✅ Run `npm install` in the generated project directory
  - ✅ Ensure you're using Node.js 18+ and npm 9+
  - ✅ Delete `node_modules` and `package-lock.json`, then reinstall
  - ✅ Check that all peer dependencies are installed

**"Next.js Dev Server Won't Start"**

```
Error: Port 3000 is already in use
```

- **Solutions**:
  - ✅ Kill existing process on port 3000: `lsof -ti:3000 | xargs kill`
  - ✅ Use different port: `npm run dev -- -p 3001`
  - ✅ Check for other Next.js instances running

**"Images Not Displaying"**

- **Expected Behavior**: Images export as placeholders
- **Solution**: Add your actual images manually:
  ```tsx
  // Replace placeholder:
  <img src="/placeholder.png" alt="..." />
  // With actual image:
  <img src="/images/hero.jpg" alt="..." />
  ```
- **Tip**: Put images in `public/images/` directory

#### Still Having Issues?

If your problem isn't covered here:

1. **Check the Actor Run Log** - Look for specific error messages and warnings
2. **Review the "Preparing Your Figma File" section** - Most issues stem from incorrect Figma structure
3. **Use the Issues Tab** - Report your issue on the Actor's page with:
   - Your Figma file key (if possible to share)
   - Complete error message from the log
   - What you expected vs. what happened
   - Screenshots of your Figma file structure
4. **Response Time**: We typically respond within 24-48 hours

#### Debug Checklist

Before reporting an issue, verify:

- \[ ] Figma file key is correct and file is accessible
- \[ ] Access token starts with `figd_` and has permissions
- \[ ] Frame names in input match Figma exactly (case-sensitive)
- \[ ] Figma file structure follows the requirements in "Preparing Your Figma File"
- \[ ] You've read the relevant troubleshooting section above
- \[ ] Actor log has been checked for specific error messages

### ❓ FAQ

#### Can I use the generated code commercially?

Yes! The generated code is yours to use for any purpose, including commercial projects. There are no licensing restrictions on the output.

#### What if my Figma file is very complex?

The Actor handles complex designs well, but extremely large files (100+ frames) may take longer to process. For best results, organize your Figma file with clear naming conventions and component structure.

#### Do I need coding knowledge to use this Actor?

You don't need coding knowledge to run the Actor, but you'll need basic development skills to deploy and customize the generated Next.js application.

#### Can I customize the generated code?

Absolutely! The generated code is clean, well-structured React/Next.js that you can modify as needed. It's designed to be a starting point for your project.

#### What are the limitations?

- Currently focuses on single-page applications (multi-page routing in development)
- Images are exported as placeholders - add your actual assets after generation
- Complex animations need manual implementation
- Custom fonts should be added manually

#### How accurate is the code generation?

The Actor uses Claude Sonnet 4.5 to generate pixel-perfect components matching your Figma designs. It handles responsive layouts, design tokens, and component structure with high accuracy.

#### Can it handle Design Systems?

Yes! The Actor excels at extracting design tokens (colors, typography, spacing) and converting them into a Tailwind configuration, making it perfect for design system implementation.

#### What if I encounter errors?

Check the Troubleshooting section above. If your issue isn't covered, use the Issues tab in the Actor's page to report problems or ask questions.

### 📧 Support

#### Need Help?

- **Report Issues**: Use the **Issues** tab on this Actor's page to report bugs or ask questions
- **Response Time**: We typically respond within 24-48 hours
- **Include Details**: When reporting issues, please include:
  - Your Figma file key (if possible to share)
  - The error message you received
  - What you expected to happen

#### Custom Solutions

Need a customized version of this Actor for your team? We offer:

- Custom feature development
- Enterprise support
- Bulk processing solutions
- API integration assistance

Contact us through the Issues tab to discuss your requirements.

#### Other Actors

Check out our other Actors on the [Apify Store](https://apify.com/store) for more automation tools.

***

**Made with ❤️ for designers and developers**

# Actor input Schema

## `figmaFileKey` (type: `string`):

The file key from your Figma URL. <strong>Example:</strong> If your URL is <code>figma.com/file/<strong>abc123def456</strong>/My-Design</code>, the file key is <code>abc123def456</code><br><br><strong>Where to find it:</strong> Open your Figma file → Look at the browser URL → Copy the alphanumeric string after <code>/file/</code><br><br><strong>Try with example:</strong> Use <code>1156860863353724933</code> to test with our <a href='https://www.figma.com/community/file/1156860863353724933' target='_blank'>Whitepace SaaS Landing Page</a>

## `figmaAccessToken` (type: `string`):

Your Figma Personal Access Token for API access. Must start with <code>figd\_</code><br><br><strong>How to get your token:</strong><br>1. Go to <a href='https://www.figma.com/settings' target='_blank'>Figma Settings → Account</a><br>2. Scroll to <strong>Personal Access Tokens</strong><br>3. Click <strong>Generate new token</strong><br>4. Give it a name (e.g., 'Code Generator')<br>5. Copy the token and paste it here<br><br><strong>⚠️ Note:</strong> Keep your token secure! It provides access to your Figma files.

## `componentNaming` (type: `string`):

Choose how to name generated React components in your code.<br><br><strong>PascalCase</strong> (recommended) - Standard React convention: <code>MyComponent</code><br><strong>camelCase</strong> - Lowercase first letter: <code>myComponent</code><br><strong>kebab-case</strong> - Hyphenated lowercase: <code>my-component</code><br><br><strong>💡 Tip:</strong> Use PascalCase for React best practices.

## `includeTypeScript` (type: `boolean`):

Enable this to generate TypeScript (<code>.tsx</code>) files with full type safety instead of JavaScript (<code>.jsx</code>).<br><br><strong>Why TypeScript?</strong><br>• Better IDE autocomplete and intellisense<br>• Catch errors before runtime<br>• Self-documenting code with type annotations<br>• Industry standard for modern React development<br><br><strong>✅ Recommended:</strong> Keep this enabled unless you specifically need JavaScript.

## `websiteMode` (type: `string`):

Choose the generation mode based on your Figma design structure.<br><br><strong>🎨 Landing Page Mode</strong> (Single responsive page)<br>• Automatically extracts sections from your frame<br>• Perfect for: Marketing pages, portfolios, product pages<br>• No frame names needed - just point to your Figma file!<br><br><strong>📄 Multi-Page Mode</strong> (Complete website)<br>• Creates separate pages with routing and navigation<br>• Perfect for: Full websites, SaaS apps, multi-page sites<br>• Requires: Exact frame names in <code>frameNames</code> field<br>• Optional: Prototype flows for navigation<br><br><strong>💡 Tip:</strong> Start with Landing Page mode if you're unsure - it's simpler!

## `frameNames` (type: `array`):

<strong>⚠️ Required for Multi-Page mode</strong><br><br>Enter the <strong>exact names</strong> of Figma frames to convert into pages. Each frame becomes a separate page in your website.<br><br><strong>Important:</strong><br>• Names are <strong>case-sensitive</strong>: 'Home' ≠ 'home'<br>• Copy names directly from your Figma layers panel<br>• First frame (or 'Home') becomes the homepage (<code>/</code>)<br>• Other frames become routes like <code>/pricing</code>, <code>/about</code><br><br><strong>Example:</strong><br>• Frame 'Home' → <code>/</code> (homepage)<br>• Frame 'Pricing' → <code>/pricing</code><br>• Frame 'Contact' → <code>/contact</code><br><br><strong>💡 Tip:</strong> Check the <a href='#multi-page-mode-structure' target='_blank'>Multi-Page Structure Guide</a> in the README for proper Figma setup.

## `usePrototypeNavigation` (type: `boolean`):

Generate navigation components based on your Figma prototype flows.<br><br><strong>When enabled:</strong><br>• Actor analyzes your Figma prototype interactions<br>• Creates navigation based on click actions between frames<br>• Generates proper Next.js <code>\<Link></code> components<br>• Results in more accurate navigation matching your design intent<br><br><strong>When disabled:</strong><br>• Navigation generated from frame order only<br>• All frames included in navigation<br>• May not match your intended user flow<br><br><strong>💡 How to set up prototype flows in Figma:</strong><br>1. Select a button/link in your Figma frame<br>2. Go to Prototype tab (right panel)<br>3. Add interaction: Click → Navigate to → \[Target Frame]<br>4. Repeat for all navigation elements<br><br><strong>✅ Recommended:</strong> Keep enabled if you've set up prototype flows in Figma. See <a href='#multi-page-mode-prototype-navigation-requirements' target='_blank'>Prototype Navigation Guide</a>.

## `selectedPages` (type: `array`):

<strong>Optional:</strong> Filter which Figma <em>pages</em> to process (not to be confused with frames).<br><br>In Figma, pages are the tabs at the top (like 'Page 1', 'Page 2'). Leave empty to process all pages.<br><br><strong>Example use cases:</strong><br>• Your file has multiple pages for different projects<br>• You only want to convert designs from a specific page<br>• Testing with a subset of your design<br><br><strong>⚠️ Note:</strong> Page names are <strong>case-sensitive</strong>. Copy them exactly from Figma.<br><br><strong>💡 Tip:</strong> Most users should leave this empty to process all pages.

## `sectionExtractionDepth` (type: `integer`):

How many layers deep to traverse when extracting sections from frames (1-10).<br><br><strong>What this means:</strong><br>• Controls how deep the Actor looks for section elements<br>• <strong>1</strong> = Only direct children of frames (fastest, recommended)<br>• <strong>5</strong> = Default, handles most design structures<br>• <strong>10</strong> = Maximum depth for complex nested designs<br><br><strong>When to increase:</strong><br>• Your sections are nested inside multiple groups<br>• You're getting 'Too few sections' warnings<br>• Your Figma structure is legitimately complex<br><br><strong>⚠️ Trade-offs:</strong><br>• Higher values = More thorough but slower processing<br>• Higher values = May extract unwanted nested elements<br><br><strong>✅ Recommended:</strong> Keep default (5) unless you have specific nesting needs. See <a href='#-problem-too-few-sections-generated' target='_blank'>Troubleshooting Guide</a>.

## `maxRequestsPerCrawl` (type: `integer`):

Maximum number of Figma API requests to prevent excessive usage on very large files.<br><br><strong>What this controls:</strong><br>• Safety limit to prevent runaway API usage<br>• Typical files use 10-50 requests<br>• Large files (100+ frames) may need more<br><br><strong>When to increase:</strong><br>• You have a very large Figma file (> 50 frames)<br>• You're getting 'Max requests reached' errors<br>• You're processing multiple pages with many frames<br><br><strong>⚠️ Note:</strong> Each request costs a small amount. Higher limits = potentially higher costs for very large files.<br><br><strong>✅ Recommended:</strong> Keep default (100) for most projects. Only increase for enterprise-scale Figma files.

## `enableVisualTesting` (type: `boolean`):

<strong>EXPERIMENTAL - Phase 6</strong><br><br>Automatically test generated code against Figma designs using visual regression testing.<br><br><strong>What it does:</strong><br>• Launches generated Next.js code in headless browser<br>• Captures screenshots of each section<br>• Compares screenshots with Figma references using pixel-level comparison<br>• Attempts to fix sections that fail visual tests (iterative correction)<br>• Generates detailed HTML diff report<br><br><strong>⚠️ Important:</strong><br>• Adds 3-5 minutes to generation time<br>• Requires downloading Playwright browsers (~100MB first run)<br>• Uses additional compute resources<br>• May fail on complex layouts or animations<br><br><strong>Benefits:</strong><br>• Higher accuracy: Automatically catches visual discrepancies<br>• Quality assurance: Get reports showing exact differences<br>• Iterative fixes: AI re-generates failed sections with corrections<br><br><strong>💡 Recommended:</strong> Disable for testing. Enable for production-quality output when time allows.

## `visualTestingThreshold` (type: `integer`):

Maximum acceptable visual difference percentage (0-100) between Figma design and generated code.<br><br><strong>How it works:</strong><br>• After generating code, each section is compared pixel-by-pixel with Figma<br>• Difference is calculated as percentage of mismatched pixels<br>• Sections exceeding threshold are marked as failed<br>• Failed sections trigger automatic regeneration with corrections<br><br><strong>Threshold guidelines:</strong><br>• <strong>3%</strong> = Very strict (near-perfect match, may be too sensitive)<br>• <strong>5%</strong> = Recommended (catches significant differences, tolerates minor variations)<br>• <strong>10%</strong> = Moderate (allows more variation in fonts, spacing)<br>• <strong>15%+</strong> = Lenient (only catches major layout issues)<br><br><strong>What causes differences:</strong><br>• Font rendering variations (browser vs Figma)<br>• Anti-aliasing differences<br>• Spacing/padding minor deviations<br>• Color rounding (hex to RGB conversions)<br><br><strong>✅ Recommended:</strong> Start with 5% for balanced accuracy.

## `enableIconVerification` (type: `boolean`):

<strong>EXPERIMENTAL - Phase 6.5</strong><br><br>Visually verify that downloaded icons match their appearance in Figma designs.<br><br><strong>What it does:</strong><br>• Captures high-res screenshots of icons from Figma<br>• Compares screenshots with downloaded icon files<br>• Automatically retries failed icons with alternative formats/scales<br>• Tries: SVG 1x, SVG 2x, PNG 2x, PNG 3x, PNG 4x<br>• Generates icon verification report<br><br><strong>Why this matters:</strong><br>• Icons may look different when exported (especially SVGs)<br>• Gradients, filters, or effects may not export correctly<br>• Ensures visual consistency between design and code<br><br><strong>⚠️ Trade-offs:</strong><br>• Adds 10-30 seconds per icon batch<br>• Makes additional Figma API requests for screenshots<br>• May retry failed icons multiple times<br><br><strong>Benefits:</strong><br>• Higher icon accuracy with automatic retries<br>• Catches export issues early<br>• Detailed verification reports<br><br><strong>✅ Recommended:</strong> Keep enabled for icon-heavy designs.

## `iconVerificationThreshold` (type: `integer`):

Maximum acceptable visual difference percentage (0-100) for icon verification.<br><br><strong>How it works:</strong><br>• Each downloaded icon is compared with its Figma screenshot<br>• Difference calculated as percentage of mismatched pixels<br>• Icons exceeding threshold trigger retry with alternative settings<br><br><strong>Threshold guidelines:</strong><br>• <strong>5%</strong> = Very strict (exact match, may cause excessive retries)<br>• <strong>10%</strong> = Recommended (catches significant issues, tolerates minor rendering differences)<br>• <strong>15%</strong> = Moderate (allows more variation)<br>• <strong>20%+</strong> = Lenient (only catches major export failures)<br><br><strong>Common sources of variation:</strong><br>• SVG rendering differences (browser vs Figma)<br>• Anti-aliasing differences at small sizes<br>• Color space conversions<br>• Path rounding differences<br><br><strong>⚠️ Note:</strong> Higher thresholds reduce retry attempts but may accept lower-quality icons.<br><br><strong>✅ Recommended:</strong> Use 10% for balanced icon quality.

## Actor input object example

```json
{
  "figmaFileKey": "abc123def456",
  "componentNaming": "PascalCase",
  "includeTypeScript": true,
  "websiteMode": "landing-page",
  "frameNames": [
    "Home",
    "Pricing",
    "About",
    "Contact"
  ],
  "usePrototypeNavigation": true,
  "selectedPages": [
    "Homepage",
    "Landing Page"
  ],
  "sectionExtractionDepth": 5,
  "maxRequestsPerCrawl": 100,
  "enableVisualTesting": false,
  "visualTestingThreshold": 5,
  "enableIconVerification": true,
  "iconVerificationThreshold": 10
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "figmaFileKey": "1156860863353724933"
};

// Run the Actor and wait for it to finish
const run = await client.actor("enforceable_orbit/figma-actor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "figmaFileKey": "1156860863353724933" }

# Run the Actor and wait for it to finish
run = client.actor("enforceable_orbit/figma-actor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "figmaFileKey": "1156860863353724933"
}' |
apify call enforceable_orbit/figma-actor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=enforceable_orbit/figma-actor",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Figma to Next.js Code Generator",
        "description": "AI-powered Figma to Next.js code generator. Converts Figma designs to React components with Tailwind CSS. Auto-generates landing pages, dashboards, and complete websites. Claude AI included - no API key needed.",
        "version": "0.0",
        "x-build-id": "9DTs3LBbtheCAO6ci"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/enforceable_orbit~figma-actor/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-enforceable_orbit-figma-actor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/enforceable_orbit~figma-actor/runs": {
            "post": {
                "operationId": "runs-sync-enforceable_orbit-figma-actor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/enforceable_orbit~figma-actor/run-sync": {
            "post": {
                "operationId": "run-sync-enforceable_orbit-figma-actor",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "figmaFileKey",
                    "figmaAccessToken"
                ],
                "properties": {
                    "figmaFileKey": {
                        "title": "📁 Figma File Key",
                        "type": "string",
                        "description": "The file key from your Figma URL. <strong>Example:</strong> If your URL is <code>figma.com/file/<strong>abc123def456</strong>/My-Design</code>, the file key is <code>abc123def456</code><br><br><strong>Where to find it:</strong> Open your Figma file → Look at the browser URL → Copy the alphanumeric string after <code>/file/</code><br><br><strong>Try with example:</strong> Use <code>1156860863353724933</code> to test with our <a href='https://www.figma.com/community/file/1156860863353724933' target='_blank'>Whitepace SaaS Landing Page</a>"
                    },
                    "figmaAccessToken": {
                        "title": "🔑 Figma Personal Access Token",
                        "type": "string",
                        "description": "Your Figma Personal Access Token for API access. Must start with <code>figd_</code><br><br><strong>How to get your token:</strong><br>1. Go to <a href='https://www.figma.com/settings' target='_blank'>Figma Settings → Account</a><br>2. Scroll to <strong>Personal Access Tokens</strong><br>3. Click <strong>Generate new token</strong><br>4. Give it a name (e.g., 'Code Generator')<br>5. Copy the token and paste it here<br><br><strong>⚠️ Note:</strong> Keep your token secure! It provides access to your Figma files."
                    },
                    "componentNaming": {
                        "title": "🏷️ Component Naming Convention",
                        "enum": [
                            "PascalCase",
                            "camelCase",
                            "kebab-case"
                        ],
                        "type": "string",
                        "description": "Choose how to name generated React components in your code.<br><br><strong>PascalCase</strong> (recommended) - Standard React convention: <code>MyComponent</code><br><strong>camelCase</strong> - Lowercase first letter: <code>myComponent</code><br><strong>kebab-case</strong> - Hyphenated lowercase: <code>my-component</code><br><br><strong>💡 Tip:</strong> Use PascalCase for React best practices.",
                        "default": "PascalCase"
                    },
                    "includeTypeScript": {
                        "title": "📘 Generate TypeScript",
                        "type": "boolean",
                        "description": "Enable this to generate TypeScript (<code>.tsx</code>) files with full type safety instead of JavaScript (<code>.jsx</code>).<br><br><strong>Why TypeScript?</strong><br>• Better IDE autocomplete and intellisense<br>• Catch errors before runtime<br>• Self-documenting code with type annotations<br>• Industry standard for modern React development<br><br><strong>✅ Recommended:</strong> Keep this enabled unless you specifically need JavaScript.",
                        "default": true
                    },
                    "websiteMode": {
                        "title": "🌐 Website Mode",
                        "enum": [
                            "landing-page",
                            "multi-page"
                        ],
                        "type": "string",
                        "description": "Choose the generation mode based on your Figma design structure.<br><br><strong>🎨 Landing Page Mode</strong> (Single responsive page)<br>• Automatically extracts sections from your frame<br>• Perfect for: Marketing pages, portfolios, product pages<br>• No frame names needed - just point to your Figma file!<br><br><strong>📄 Multi-Page Mode</strong> (Complete website)<br>• Creates separate pages with routing and navigation<br>• Perfect for: Full websites, SaaS apps, multi-page sites<br>• Requires: Exact frame names in <code>frameNames</code> field<br>• Optional: Prototype flows for navigation<br><br><strong>💡 Tip:</strong> Start with Landing Page mode if you're unsure - it's simpler!",
                        "default": "landing-page"
                    },
                    "frameNames": {
                        "title": "📄 Frame Names",
                        "type": "array",
                        "description": "<strong>⚠️ Required for Multi-Page mode</strong><br><br>Enter the <strong>exact names</strong> of Figma frames to convert into pages. Each frame becomes a separate page in your website.<br><br><strong>Important:</strong><br>• Names are <strong>case-sensitive</strong>: 'Home' ≠ 'home'<br>• Copy names directly from your Figma layers panel<br>• First frame (or 'Home') becomes the homepage (<code>/</code>)<br>• Other frames become routes like <code>/pricing</code>, <code>/about</code><br><br><strong>Example:</strong><br>• Frame 'Home' → <code>/</code> (homepage)<br>• Frame 'Pricing' → <code>/pricing</code><br>• Frame 'Contact' → <code>/contact</code><br><br><strong>💡 Tip:</strong> Check the <a href='#multi-page-mode-structure' target='_blank'>Multi-Page Structure Guide</a> in the README for proper Figma setup.",
                        "items": {
                            "type": "string"
                        },
                        "default": []
                    },
                    "usePrototypeNavigation": {
                        "title": "🔗 Use Prototype Navigation",
                        "type": "boolean",
                        "description": "Generate navigation components based on your Figma prototype flows.<br><br><strong>When enabled:</strong><br>• Actor analyzes your Figma prototype interactions<br>• Creates navigation based on click actions between frames<br>• Generates proper Next.js <code>&lt;Link&gt;</code> components<br>• Results in more accurate navigation matching your design intent<br><br><strong>When disabled:</strong><br>• Navigation generated from frame order only<br>• All frames included in navigation<br>• May not match your intended user flow<br><br><strong>💡 How to set up prototype flows in Figma:</strong><br>1. Select a button/link in your Figma frame<br>2. Go to Prototype tab (right panel)<br>3. Add interaction: Click → Navigate to → [Target Frame]<br>4. Repeat for all navigation elements<br><br><strong>✅ Recommended:</strong> Keep enabled if you've set up prototype flows in Figma. See <a href='#multi-page-mode-prototype-navigation-requirements' target='_blank'>Prototype Navigation Guide</a>.",
                        "default": true
                    },
                    "selectedPages": {
                        "title": "⚙️ Pages to Convert",
                        "type": "array",
                        "description": "<strong>Optional:</strong> Filter which Figma <em>pages</em> to process (not to be confused with frames).<br><br>In Figma, pages are the tabs at the top (like 'Page 1', 'Page 2'). Leave empty to process all pages.<br><br><strong>Example use cases:</strong><br>• Your file has multiple pages for different projects<br>• You only want to convert designs from a specific page<br>• Testing with a subset of your design<br><br><strong>⚠️ Note:</strong> Page names are <strong>case-sensitive</strong>. Copy them exactly from Figma.<br><br><strong>💡 Tip:</strong> Most users should leave this empty to process all pages.",
                        "items": {
                            "type": "string"
                        },
                        "default": []
                    },
                    "sectionExtractionDepth": {
                        "title": "🔍 Section Extraction Depth",
                        "minimum": 1,
                        "maximum": 10,
                        "type": "integer",
                        "description": "How many layers deep to traverse when extracting sections from frames (1-10).<br><br><strong>What this means:</strong><br>• Controls how deep the Actor looks for section elements<br>• <strong>1</strong> = Only direct children of frames (fastest, recommended)<br>• <strong>5</strong> = Default, handles most design structures<br>• <strong>10</strong> = Maximum depth for complex nested designs<br><br><strong>When to increase:</strong><br>• Your sections are nested inside multiple groups<br>• You're getting 'Too few sections' warnings<br>• Your Figma structure is legitimately complex<br><br><strong>⚠️ Trade-offs:</strong><br>• Higher values = More thorough but slower processing<br>• Higher values = May extract unwanted nested elements<br><br><strong>✅ Recommended:</strong> Keep default (5) unless you have specific nesting needs. See <a href='#-problem-too-few-sections-generated' target='_blank'>Troubleshooting Guide</a>.",
                        "default": 5
                    },
                    "maxRequestsPerCrawl": {
                        "title": "🚦 Max API Requests",
                        "minimum": 10,
                        "maximum": 1000,
                        "type": "integer",
                        "description": "Maximum number of Figma API requests to prevent excessive usage on very large files.<br><br><strong>What this controls:</strong><br>• Safety limit to prevent runaway API usage<br>• Typical files use 10-50 requests<br>• Large files (100+ frames) may need more<br><br><strong>When to increase:</strong><br>• You have a very large Figma file (> 50 frames)<br>• You're getting 'Max requests reached' errors<br>• You're processing multiple pages with many frames<br><br><strong>⚠️ Note:</strong> Each request costs a small amount. Higher limits = potentially higher costs for very large files.<br><br><strong>✅ Recommended:</strong> Keep default (100) for most projects. Only increase for enterprise-scale Figma files.",
                        "default": 100
                    },
                    "enableVisualTesting": {
                        "title": "🧪 Enable Visual Testing",
                        "type": "boolean",
                        "description": "<strong>EXPERIMENTAL - Phase 6</strong><br><br>Automatically test generated code against Figma designs using visual regression testing.<br><br><strong>What it does:</strong><br>• Launches generated Next.js code in headless browser<br>• Captures screenshots of each section<br>• Compares screenshots with Figma references using pixel-level comparison<br>• Attempts to fix sections that fail visual tests (iterative correction)<br>• Generates detailed HTML diff report<br><br><strong>⚠️ Important:</strong><br>• Adds 3-5 minutes to generation time<br>• Requires downloading Playwright browsers (~100MB first run)<br>• Uses additional compute resources<br>• May fail on complex layouts or animations<br><br><strong>Benefits:</strong><br>• Higher accuracy: Automatically catches visual discrepancies<br>• Quality assurance: Get reports showing exact differences<br>• Iterative fixes: AI re-generates failed sections with corrections<br><br><strong>💡 Recommended:</strong> Disable for testing. Enable for production-quality output when time allows.",
                        "default": false
                    },
                    "visualTestingThreshold": {
                        "title": "📊 Visual Difference Threshold (%)",
                        "minimum": 0,
                        "maximum": 100,
                        "type": "integer",
                        "description": "Maximum acceptable visual difference percentage (0-100) between Figma design and generated code.<br><br><strong>How it works:</strong><br>• After generating code, each section is compared pixel-by-pixel with Figma<br>• Difference is calculated as percentage of mismatched pixels<br>• Sections exceeding threshold are marked as failed<br>• Failed sections trigger automatic regeneration with corrections<br><br><strong>Threshold guidelines:</strong><br>• <strong>3%</strong> = Very strict (near-perfect match, may be too sensitive)<br>• <strong>5%</strong> = Recommended (catches significant differences, tolerates minor variations)<br>• <strong>10%</strong> = Moderate (allows more variation in fonts, spacing)<br>• <strong>15%+</strong> = Lenient (only catches major layout issues)<br><br><strong>What causes differences:</strong><br>• Font rendering variations (browser vs Figma)<br>• Anti-aliasing differences<br>• Spacing/padding minor deviations<br>• Color rounding (hex to RGB conversions)<br><br><strong>✅ Recommended:</strong> Start with 5% for balanced accuracy.",
                        "default": 5
                    },
                    "enableIconVerification": {
                        "title": "🎨 Enable Icon Verification",
                        "type": "boolean",
                        "description": "<strong>EXPERIMENTAL - Phase 6.5</strong><br><br>Visually verify that downloaded icons match their appearance in Figma designs.<br><br><strong>What it does:</strong><br>• Captures high-res screenshots of icons from Figma<br>• Compares screenshots with downloaded icon files<br>• Automatically retries failed icons with alternative formats/scales<br>• Tries: SVG 1x, SVG 2x, PNG 2x, PNG 3x, PNG 4x<br>• Generates icon verification report<br><br><strong>Why this matters:</strong><br>• Icons may look different when exported (especially SVGs)<br>• Gradients, filters, or effects may not export correctly<br>• Ensures visual consistency between design and code<br><br><strong>⚠️ Trade-offs:</strong><br>• Adds 10-30 seconds per icon batch<br>• Makes additional Figma API requests for screenshots<br>• May retry failed icons multiple times<br><br><strong>Benefits:</strong><br>• Higher icon accuracy with automatic retries<br>• Catches export issues early<br>• Detailed verification reports<br><br><strong>✅ Recommended:</strong> Keep enabled for icon-heavy designs.",
                        "default": true
                    },
                    "iconVerificationThreshold": {
                        "title": "🔍 Icon Verification Threshold (%)",
                        "minimum": 0,
                        "maximum": 100,
                        "type": "integer",
                        "description": "Maximum acceptable visual difference percentage (0-100) for icon verification.<br><br><strong>How it works:</strong><br>• Each downloaded icon is compared with its Figma screenshot<br>• Difference calculated as percentage of mismatched pixels<br>• Icons exceeding threshold trigger retry with alternative settings<br><br><strong>Threshold guidelines:</strong><br>• <strong>5%</strong> = Very strict (exact match, may cause excessive retries)<br>• <strong>10%</strong> = Recommended (catches significant issues, tolerates minor rendering differences)<br>• <strong>15%</strong> = Moderate (allows more variation)<br>• <strong>20%+</strong> = Lenient (only catches major export failures)<br><br><strong>Common sources of variation:</strong><br>• SVG rendering differences (browser vs Figma)<br>• Anti-aliasing differences at small sizes<br>• Color space conversions<br>• Path rounding differences<br><br><strong>⚠️ Note:</strong> Higher thresholds reduce retry attempts but may accept lower-quality icons.<br><br><strong>✅ Recommended:</strong> Use 10% for balanced icon quality.",
                        "default": 10
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```