llms-full.txt

# ExFig

> Command-line utility to export colors, typography, icons, and images from Figma
> to Xcode, Android Studio, Flutter, and Web (React/TypeScript) projects.
> Supports Dark Mode, SwiftUI, UIKit, Jetpack Compose, Flutter, and React/TypeScript.
> Configuration via PKL. Jinja2 templates for custom code generation.

## Documentation

### README

# ExFig


Export colors, typography, icons, and images from Figma and Penpot to Xcode, Android Studio, Flutter, and Web projects — automatically. Runs on macOS, Linux, and Windows.

## The Problem

- Figma has no "Export to Xcode" button. You copy hex codes by hand, one by one.
- Switching from Figma to Penpot? Your export pipeline shouldn't break.
- Every color change means updating files across 3 platforms manually.
- Dark mode variant? An afternoon spent on light/dark pairs and @1x/@2x/@3x PNGs.
- Android gets XML. iOS gets xcassets. Flutter gets Dart. Someone maintains all three.
- Design and code drift apart because nobody runs the manual export often enough.

## Who Is This For?

**iOS developer** — You have 100+ colors and 200+ icons. ExFig generates Color Sets with light/dark/high-contrast variants, PDF vectors in `.xcassets`, and type-safe SwiftUI + UIKit extensions.

**Android developer** — Your team uses Compose but legacy views need XML. ExFig generates both: `colors.xml` for views, Compose `Color` objects, and `VectorDrawable` icons with pathData validation.

**Flutter developer** — You need dark mode icon variants and `@2x`/`@3x` image scales. ExFig exports SVG icons with dark suffixes, raster images with scale directories, and Dart constants.

**Design Systems lead** — One Figma or Penpot file feeds four platforms. ExFig's unified PKL config exports everything from a single `exfig batch` run. One CI pipeline, one source of truth.

**CI/CD engineer** — Quiet mode, JSON reports, exit codes, version tracking, and checkpoint/resume. The [GitHub Action](https://github.com/DesignPipe/exfig-action) handles installation and caching.

## Quick Start

```bash
# 1. Install
brew install designpipe/tap/exfig

# 2. Set Figma token (or PENPOT_ACCESS_TOKEN for Penpot)
export FIGMA_PERSONAL_TOKEN=your_token_here

# 3a. Quick one-off export (interactive wizard)
exfig fetch

# 3b. Or generate config for full pipeline (interactive wizard)
exfig init
exfig batch exfig.pkl
```

See the [Getting Started guide](https://DesignPipe.github.io/exfig/documentation/exfigcli/gettingstarted) for detailed setup, including Mint, mise, and building from source.

## GitHub Action

```yaml
- uses: DesignPipe/exfig-action@v1
  with:
    figma_token: ${{ secrets.FIGMA_TOKEN }}
    command: batch exfig.pkl
    cache: true
```

## Claude Code Plugins

Use ExFig directly from Claude Code with the [exfig-plugins](https://github.com/DesignPipe/exfig-plugins) marketplace:

```bash
claude /plugin marketplace add https://github.com/DesignPipe/exfig-plugins
```

Includes MCP integration, setup wizard, config review, troubleshooting, and `/export-*` slash commands.

## Documentation

Full documentation — platform guides, configuration reference, batch processing, design tokens, custom templates, and MCP server — is available at **[DesignPipe.github.io/exfig](https://DesignPipe.github.io/exfig/documentation/exfigcli)**.

Configuration reference: [CONFIG.md](CONFIG.md).

## Contributing

See the [Development Guide](https://DesignPipe.github.io/exfig/documentation/exfigcli/development) for setup, testing, and code style.

## License

MIT. See [LICENSE](LICENSE).

---

<sub>Originally inspired by [figma-export](https://github.com/RedMadRobot/figma-export).</sub>

### Getting Started

# Getting Started

Install ExFig and configure your first export.


## Overview

ExFig is a command-line tool that exports design resources from Figma and Penpot to iOS, Android, Flutter, and Web projects.

## Requirements

- macOS 13.0 or later, Linux (Ubuntu 22.04), or Windows (Swift 6.3+)
- Figma account with file access, **or** Penpot account
- Figma Personal Access Token (for Figma sources) or Penpot Access Token (for Penpot sources)

## Installation

### Using Homebrew (Recommended)

```bash
brew install designpipe/tap/exfig
```

### Using Mint

```bash
mint install DesignPipe/exfig
```

### Using Mise

```bash
mise use -g github:DesignPipe/exfig
```

### From Source

```bash
git clone https://github.com/DesignPipe/exfig.git
cd ExFig
swift build -c release
cp .build/release/exfig /usr/local/bin/
```

### Download Binary

Download the latest release from [GitHub Releases](https://github.com/DesignPipe/exfig/releases).

## Authentication

### Figma Access Token

ExFig requires a Figma Personal Access Token to access the Figma API.

### Create a Token

1. Open [Figma Account Settings](https://www.figma.com/settings)
2. Scroll to **Personal access tokens**
3. Click **Create a new personal access token**
4. Give it a descriptive name (e.g., "ExFig CLI")
5. Copy the generated token

### Set the Token

Set the `FIGMA_PERSONAL_TOKEN` environment variable:

```bash nocopy
# Add to ~/.zshrc or ~/.bashrc
export FIGMA_PERSONAL_TOKEN="your-token-here"
```

Or pass it directly to commands:

```bash nocopy
FIGMA_PERSONAL_TOKEN="your-token" exfig colors
```

### Penpot Access Token

For Penpot sources, set the `PENPOT_ACCESS_TOKEN` environment variable:

1. Open your Penpot instance → Settings → Access Tokens
2. Create a new token
3. Set it:

```bash nocopy
export PENPOT_ACCESS_TOKEN="your-penpot-token-here"
```

> Note: `PENPOT_ACCESS_TOKEN` is only required when using `penpotSource` in config.

### Quick Penpot Icons Export (No Config)

```bash
# Export Penpot icons as SVG
export PENPOT_ACCESS_TOKEN="your-token"
exfig fetch --source penpot -f "file-uuid" -r "Icons" -o ./icons --format svg

# Export as PNG at 3x scale
exfig fetch --source penpot -f "file-uuid" -r "Icons" -o ./icons --format png --scale 3
```

> File UUID is in the Penpot workspace URL: `?file-id=UUID`.
> For shared libraries, use the library's file ID from the Assets panel.

## Quick Start

### 1. Initialize Configuration

Generate a starter configuration file for your platform:

```bash
# For iOS projects
exfig init --platform ios

# For Android projects
exfig init --platform android

# For Flutter projects
exfig init --platform flutter
```

This creates an `exfig.pkl` file in your current directory.

### 2. Get Your Figma File ID

The file ID is in the Figma URL:

```
https://www.figma.com/file/ABC123xyz/My-Design-System
                          ^^^^^^^^^^^
                          This is your file ID
```

### 3. Configure exfig.pkl

Edit the generated `exfig.pkl`:

```pkl
amends ".exfig/schemas/ExFig.pkl"

import ".exfig/schemas/Figma.pkl"
import ".exfig/schemas/iOS.pkl"

figma = new Figma.FigmaConfig {
  lightFileId = "YOUR_FILE_ID_HERE"
}

ios = new iOS.iOSConfig {
  xcodeprojPath = "./MyApp.xcodeproj"
  xcassetsPath = "./Resources/Assets.xcassets"
  // ... other iOS settings
}
```

### 4. Validate & Export

```bash
# Validate Figma file structure before exporting
exfig lint

# Export individual resource types
exfig colors
exfig icons
exfig images
exfig typography

# Or export everything at once with batch
exfig batch exfig.pkl
```

> Note: Individual commands use the `-i` flag for custom config paths (`exfig colors -i path.pkl`),
> while `batch` takes paths as positional arguments (`exfig batch path.pkl`).

## What's Next

- Usage - Learn about all CLI commands and options
- Configuration - Full configuration reference
- DesignRequirements - How to structure your Figma files
- iOS - iOS-specific export guide
- Android - Android-specific export guide
- Flutter - Flutter-specific export guide

### Usage

# Usage

Command-line interface reference and common usage patterns.


## Overview

ExFig provides commands for exporting colors, icons, images, and typography from Figma and Penpot to native platform resources.

## Basic Commands

```bash
# Export colors
exfig colors

# Export icons
exfig icons

# Export images
exfig images

# Export typography
exfig typography
```

## Getting Started

Generate a config file with the interactive wizard:

```bash
exfig init
```

The wizard guides you through platform selection, asset types, and Figma file IDs.
For non-interactive use, specify the platform directly:

```bash
exfig init -p ios       # Full iOS template
exfig init -p android   # Full Android template
```

## Configuration File

By default, ExFig looks for `exfig.pkl` in the current directory. Specify a different location:

```bash
exfig colors -i path/to/exfig.pkl
exfig colors --input path/to/exfig.pkl
```

## Filtering Exports

Export specific items by name:

### Single Item

```bash
exfig icons "ic/24/edit"
```

### Multiple Items

Separate names with commas:

```bash
exfig icons "ic/24/edit, ic/16/notification"
```

### Wildcard Patterns

Use `*` to match multiple items:

```bash
# Export all icons starting with "ic/24/videoplayer/"
exfig icons "ic/24/videoplayer/*"

# Export all colors starting with "common/"
exfig colors "common/*"

# Export all typography styles starting with "heading/"
exfig typography "heading/*"
```

> Note: Wildcard patterns don't work on Linux systems.

## Version Tracking

Skip unchanged exports with version tracking:

```bash
# Enable version tracking
exfig colors --cache
exfig icons --cache

# Disable version tracking
exfig icons --no-cache

# Force export and update cache
exfig icons --force

# Custom cache file path
exfig icons --cache-path ./custom-cache.json
```

> Note: The version changes when a Figma library is **published**, not on every auto-save.

For batch mode version tracking and granular cache, see BatchProcessing.

## Fault Tolerance

All commands support fault tolerance options:

### Basic Options

```bash
# Custom retry count (default: 4)
exfig colors --max-retries 6

# Custom rate limit (default: 10 req/min)
exfig icons --rate-limit 20
```

### Extended Options

Commands that download many files (`icons`, `images`, `fetch`, `download all`) support additional options:

```bash
# Stop on first error
exfig icons --fail-fast

# Resume from checkpoint after interruption
exfig images --resume

# Increase concurrent downloads (default: 20)
exfig icons --concurrent-downloads 50
```

| Option                   | Description                                    | Commands              | PKL key                       |
| ------------------------ | ---------------------------------------------- | --------------------- | ----------------------------- |
| `--max-retries`          | Maximum retry attempts (default: 4)            | All                   | `figma.maxRetries`            |
| `--rate-limit`           | API requests per minute (default: 10)          | All                   | `figma.rateLimit`             |
| `--timeout`              | Figma API request timeout, sec (default: 30)   | All                   | `figma.timeout`               |
| `--concurrent-downloads` | Concurrent CDN downloads (default: 20)         | icons, images, fetch, download all, batch | `figma.concurrentDownloads`*  |
| `--fail-fast`            | Stop immediately on error                      | icons, images, batch, fetch | `batch.failFast` (batch only)†|
| `--resume`               | Continue from checkpoint                       | icons, images, batch, fetch | `batch.resume` (batch only)†  |
| `--parallel`             | Concurrent batch configs (default: 3)          | batch                 | `batch.parallel`              |

CLI flags override PKL config; PKL config overrides built-in defaults. `fetch` is config-free —
only CLI flags and built-in defaults apply there.

*`figma.concurrentDownloads` is silently ignored by `colors`/`typography` (no CDN downloads); under
`-v` a debug log records the skip.

†The `batch.failFast` / `batch.resume` PKL keys apply ONLY to `exfig batch`. Standalone `icons` /
`images` commands accept the corresponding CLI flags but do not read these PKL fields.

### Checkpoint System

Long-running exports create checkpoints for resumption:

```bash
# Resume interrupted export
exfig icons --resume

# Checkpoints stored in: .exfig-checkpoint.json
# Checkpoints expire after 24 hours
# Successful completion deletes the checkpoint
```

## Quick Fetch

Download images without a configuration file. Run `exfig fetch` with no arguments for an
interactive wizard that guides you through file ID, asset type, platform, frame selection,
format, output directory, and more:

```bash
# Interactive wizard — asks platform, format, output step by step
exfig fetch

# Or pass all options directly
exfig fetch --file-id YOUR_FILE_ID --frame "Illustrations" --output ./images

# Using short options
exfig fetch -f YOUR_FILE_ID -r "Icons" -o ./icons
```

The wizard provides smart defaults per platform (e.g., SVG + camelCase for iOS icons,
WebP + snake_case for Android illustrations) and only runs in interactive terminals.

### Disambiguating Frames by Page

When the same frame name appears on multiple Figma pages (e.g., a `🏞 Illustrations` file
with frame `InDrive` on both an "Old" and a "New" page), use `-p` / `--page` to filter
by page name and avoid downloading components from the wrong frame:

```bash
# Only components from frame "InDrive" on the specified page
exfig fetch \
  -f wdUfYHrScBXtgRSyCbwY31 \
  -r "InDrive" \
  -p "New illustration - figma export" \
  -o ./illustrations \
  --format svg
```

Without `--page`, `fetch` matches the frame name across the entire file, which can pull in
components from frames you didn't intend to export.

### Format Options

```bash
# SVG (vector)
exfig fetch -f abc123 -r "Icons" -o ./icons --format svg

# PDF (vector)
exfig fetch -f abc123 -r "Icons" -o ./icons --format pdf

# JPG
exfig fetch -f abc123 -r "Photos" -o ./photos --format jpg

# WebP with quality
exfig fetch -f abc123 -r "Images" -o ./images --format webp --webp-quality 90

# WebP lossless
exfig fetch -f abc123 -r "Images" -o ./images --format webp --webp-encoding lossless
```

### Penpot Fetch

```bash
# Fetch icons from Penpot as SVG
exfig fetch --source penpot -f "a1b2c3d4-..." -r "Icons / App" -o ./icons --format svg

# Fetch as PNG at 3x scale (SVG reconstructed, then rasterized via resvg)
exfig fetch --source penpot -f "a1b2c3d4-..." -r "Icons" -o ./icons --format png --scale 3

# From a shared library (use library file ID)
exfig fetch --source penpot -f "library-uuid" -r "Icons / Actions" -o ./icons --format svg

# Self-hosted Penpot instance
exfig fetch --source penpot --penpot-base-url https://penpot.mycompany.com/ \
  -f "uuid" -r "Icons" -o ./icons --format svg
```

> Set `PENPOT_ACCESS_TOKEN` environment variable (generate at Settings → Access Tokens).
> File ID is in the Penpot workspace URL: `?file-id=UUID`.

### Scale Options

```bash
# PNG at 2x scale
exfig fetch -f abc123 -r "Images" -o ./images --scale 2

# Note: Scale is ignored for vector formats (SVG, PDF)
```

### Filtering and Naming

```bash
# Filter specific images
exfig fetch -f abc123 -r "Images" -o ./images --filter "logo/*"

# Convert names to camelCase
exfig fetch -f abc123 -r "Images" -o ./images --name-style camelCase

# Custom regex replacement
exfig fetch -f abc123 -r "Images" -o ./images \
  --name-validate-regexp "^icon/(.*)$" \
  --name-replace-regexp "ic_$1"
```

### All Fetch Options

| Option               | Short | Description                            | Default |
| -------------------- | ----- | -------------------------------------- | ------- |
| `--file-id`          | `-f`  | Figma file ID (required)               | -       |
| `--frame`            | `-r`  | Figma frame name (required)            | -       |
| `--page`             | `-p`  | Filter by Figma page name              | -       |
| `--output`           | `-o`  | Output directory (required)            | -       |
| `--format`           | -     | Image format: png, svg, jpg, pdf, webp | png     |
| `--scale`            | -     | Scale factor (0.01-4.0)                | 3       |
| `--filter`           | -     | Filter pattern                         | -       |
| `--name-style`       | -     | Name style                             | -       |
| `--dark-mode-suffix` | -     | Suffix for dark variants               | -       |
| `--webp-encoding`    | -     | WebP encoding: lossy, lossless         | lossy   |
| `--webp-quality`     | -     | WebP quality (0-100)                   | 80      |

## Linting

Validate your Figma file structure against your PKL config before exporting:

```bash
# Lint with default rules
exfig lint -i exfig.pkl

# Add lint-only policies from a separate config
exfig lint -i exfig.pkl --lint-config lint.pkl

# Only check specific rules
exfig lint -i exfig.pkl --rules naming-convention,deleted-variables

# JSON output for CI (exit code 1 on errors)
exfig lint -i exfig.pkl --format json --severity error
```

### Available Rules

| Rule                        | Severity | Description                                            |
| --------------------------- | -------- | ------------------------------------------------------ |
| `frame-page-match`          | error    | Frame/page names in config exist in Figma file         |
| `naming-convention`         | error    | Component names match `nameValidateRegexp` patterns    |
| `component-not-frame`       | error    | Configured frames contain published components         |
| `duplicate-component-names` | error    | No duplicate component names in configured frames      |
| `deleted-variables`         | warning  | No `deletedButReferenced` variables in collections     |
| `alias-chain-integrity`     | warning  | Variable alias chains resolve without broken refs      |
| `dark-mode-variables`       | error    | With `variablesDarkMode`, fills bound to Variables     |
| `dark-mode-suffix`          | warning  | With `suffixDarkMode`, light components have dark pair |
| `path-data-length`          | error    | Icon SVG pathData within 32,767-byte AAPT limit        |
| `icon-color-variables`      | error    | Icon paints use configured Figma Variables             |

## Help and Version

```bash
# Show help
exfig --help
exfig colors --help

# Show version
exfig --version
```

## See Also

- BatchProcessing
- DesignTokens
- MCPServer
- Configuration
- DesignRequirements
- iOS
- Android
- Flutter

### Configuration

# Configuration

Complete reference for exfig.pkl configuration options.


## Overview

ExFig uses a PKL configuration file (typically `exfig.pkl`) to define export settings. PKL (Programmable, Scalable, Safe)
provides type-safe configuration with IDE support. This document covers all available options.

## Configuration File

By default, ExFig looks for `exfig.pkl` in the current directory.

Specify a custom path with the `-i` flag:

```bash
exfig colors -i path/to/config.pkl
```

## Unified Config with Batch

A single `exfig.pkl` can contain all resource types. Use `batch` to export everything at once:

```bash
# Export all resource types from a single config
exfig batch exfig.pkl

# With version tracking
exfig batch exfig.pkl --cache
```

> Note: The `batch` command takes config paths as **positional arguments** (not via `-i` flag).

## Figma Section

```pkl showLineNumbers
import ".exfig/schemas/Figma.pkl"

figma = new Figma.FigmaConfig {
  // Figma file ID for light mode assets.
  // Required for icons, images, and typography export.
  // Optional when using only variablesColors (or multi-entry colors) for colors export.
  lightFileId = "ABC123xyz"

  // Optional: Separate file for dark mode assets
  darkFileId = "DEF456abc"

  // Optional: API request timeout in seconds (default: 30)
  timeout = 60

  // Optional: API requests per minute (default: 10). CLI --rate-limit overrides.
  rateLimit = 25

  // Optional: Retry attempts for failed API requests (default: 4). CLI --max-retries overrides.
  maxRetries = 6

  // Optional: Concurrent CDN downloads — icons/images only (default: 20).
  // Ignored by colors/typography. CLI --concurrent-downloads overrides.
  // Client-side cap on connections (URLSession.httpMaximumConnectionsPerHost), not a Figma REST limit.
  concurrentDownloads = 50
}
```

**Precedence (per knob):** CLI flag > PKL config > built-in default. The same rule applies to
all five fields above. CI workflows can keep one value here instead of repeating CLI flags
everywhere; ad-hoc invocations still override per-run.

## Common Section

Shared settings across all platforms.

### Colors

```pkl showLineNumbers
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  colors = new Common.Colors {
    // Frame name containing color styles (default: null, uses all styles)
    figmaFrameName = "Colors"

    // Regex to validate color names
    nameValidateRegexp = "^[a-z][a-zA-Z0-9]*$"

    // Regex replacement for color names
    nameReplaceRegexp = "$1"

    // suffixDarkMode = new Common.SuffixDarkMode { suffix = "_dark" }
  }
}
```

### Variables Colors

```pkl showLineNumbers
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  // Use variablesColors instead of colors to export colors from Figma Variables.
  // Cannot be used together with colors.
  variablesColors = new Common.VariablesColors {
    // Identifier of the file containing variables
    tokensFileId = "ABC123xyz"

    // Variables collection name
    tokensCollectionName = "Colors"

    // Name of the column containing light color variables
    lightModeName = "Light"

    // Name of the column containing dark color variables
    darkModeName = "Dark"
  }
}
```

### Penpot Source

Use a Penpot project instead of Figma as the design source. For file preparation guidelines,
see DesignRequirements.

**Colors:**

```pkl
import ".exfig/schemas/Common.pkl"
import ".exfig/schemas/iOS.pkl"

ios = new iOS.iOSConfig {
  colors = new iOS.ColorsEntry {
    penpotSource = new Common.PenpotSource {
      fileId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      // baseUrl = "https://penpot.mycompany.com/"  // optional: self-hosted
      pathFilter = "Brand"  // optional: filter by path prefix
    }
    assetsFolder = "Colors"
    nameStyle = "camelCase"
  }
}
```

**Icons:**

```pkl
ios = new iOS.iOSConfig {
  icons = new Listing {
    new iOS.IconsEntry {
      penpotSource = new Common.PenpotSource {
        fileId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
        // pathFilter = "Icons / Actions"  // optional: filter by path prefix
      }
      figmaFrameName = "Icons"  // path prefix filter (same field as Figma)
      format = "svg"            // svg or pdf — SVG reconstructed from shape tree
      assetsFolder = "Icons"
      nameStyle = "camelCase"
    }
  }
}
```

**Typography:**

```pkl
ios = new iOS.iOSConfig {
  typography = new iOS.TypographyEntry {
    penpotSource = new Common.PenpotSource {
      fileId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  }
}
```

> When `penpotSource` is set, `sourceKind` auto-detects as `"penpot"`. ExFig reads from
> the Penpot API and does not require `FIGMA_PERSONAL_TOKEN`. Set `PENPOT_ACCESS_TOKEN` instead.
>
> Icons and images are exported via **SVG reconstruction** from Penpot's shape tree —
> no headless Chrome needed. Supported formats: SVG, PNG (any scale), PDF, WebP.

### Tokens File Source

Use a local W3C DTCG `.tokens.json` file instead of the Figma Variables API:

```pkl
import ".exfig/schemas/Common.pkl"
import ".exfig/schemas/iOS.pkl"

ios = new iOS.iOSConfig {
  colors = new iOS.ColorsEntry {
    // Load colors from a local .tokens.json file
    tokensFile = new Common.TokensFile {
      // Path to the .tokens.json file
      path = "./design-tokens/colors.tokens.json"

      // Optional: filter to specific token group
      groupFilter = "Brand.Colors"
    }

    assetsFolder = "Colors"
    nameStyle = "camelCase"
  }
}
```

> When `tokensFile` is set, ExFig reads color tokens from the local file and does not require `FIGMA_PERSONAL_TOKEN` or Figma Variables configuration (`tokensFileId`, `tokensCollectionName`, `lightModeName`).

### Icons

```pkl
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  icons = new Common.Icons {
    // Default frame name for icon components (can be overridden per-entry)
    figmaFrameName = "Icons"

    // Regex to validate icon names
    nameValidateRegexp = "^ic/.*$"

    // Regex replacement for icon names
    nameReplaceRegexp = "ic_$1"

    // suffixDarkMode = new Common.SuffixDarkMode { suffix = "_dark" }
  }
}
```

### RTL (Right-to-Left) Configuration

Icons in a COMPONENT_SET can have an RTL variant property (e.g., `RTL=Off` and `RTL=On`).
The "active" variant is skipped during export — platforms mirror the base icon at runtime.

```pkl
new iOS.IconsEntry {
  // Property name in Figma (default: "RTL")
  rtlProperty = "RTL"

  // Values meaning "active RTL" — these variants are skipped.
  // Default: new { "On" } (paired with "Off")
  rtlActiveValues = new { "On" }

  // If your Figma uses true/false instead of On/Off:
  // rtlActiveValues = new { "true" }
}
```

Set `rtlProperty = null` to disable RTL detection entirely.

The `exfig lint` rule `invalid-rtl-variant-value` validates that RTL variant values
match the configured `rtlActiveValues` and their known counterparts
(On↔Off, true↔false, True↔False, Yes↔No, 0↔1).

### Images

```pkl
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  images = new Common.Images {
    // Frame name containing image components
    figmaFrameName = "Illustrations"

    // Regex to validate image names
    nameValidateRegexp = "^img_.*$"

    // Regex replacement for image names
    nameReplaceRegexp = "$1"

    // suffixDarkMode = new Common.SuffixDarkMode { suffix = "_dark" }
  }
}
```

### Typography

```pkl
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  typography = new Common.Typography {
    // Regex to validate style names
    nameValidateRegexp = "^[a-z].*$"
  }
}
```

## iOS Section

```pkl
import ".exfig/schemas/iOS.pkl"

ios = new iOS.iOSConfig {
  // Path to Xcode project
  xcodeprojPath = "./MyApp.xcodeproj"

  // Target name for adding generated files
  target = "MyApp"

  // Path to Assets.xcassets
  xcassetsPath = "./Resources/Assets.xcassets"

  // Colors
  colors = new iOS.ColorsEntry {
    // Use color assets in xcassets
    useColorAssets = true

    // Folder in xcassets for colors
    assetsFolder = "Colors"

    // Naming style: camelCase, snake_case, PascalCase, kebab-case, SCREAMING_SNAKE_CASE
    nameStyle = "camelCase"

    // Group colors in subfolders by prefix
    groupUsingNamespace = true

    // UIKit extension output path
    colorSwift = "./Sources/Generated/UIColor+Colors.swift"

    // SwiftUI extension output path
    swiftuiColorSwift = "./Sources/Generated/Color+Colors.swift"
  }

  // Icons
  icons = new iOS.IconsEntry {
    // Folder in xcassets for icons
    assetsFolder = "Icons"

    // Naming style
    nameStyle = "camelCase"

    // Icon format: pdf or svg
    format = "pdf"

    // Preserve vector data
    preservesVectorRepresentation = new Listing {
      "ic24TabBarMain"
      "ic24TabBarEvents"
    }

    // UIKit extension output path
    imageSwift = "./Sources/Generated/UIImage+Icons.swift"

    // SwiftUI extension output path
    swiftUIImageSwift = "./Sources/Generated/Image+Icons.swift"
  }

  // Images
  images = new iOS.ImagesEntry {
    // Folder in xcassets for images
    assetsFolder = "Images"

    // Naming style
    nameStyle = "camelCase"

    // Scales to export (default: [1, 2, 3])
    scales = new Listing { 1; 2; 3 }

    // UIKit extension output path
    imageSwift = "./Sources/Generated/UIImage+Images.swift"

    // SwiftUI extension output path
    swiftUIImageSwift = "./Sources/Generated/Image+Images.swift"
  }

  // Typography
  typography = new iOS.Typography {
    // Generate labels with predefined styles
    generateLabels = true

    // Font extension output path
    fontSwift = "./Sources/Generated/UIFont+Typography.swift"

    // SwiftUI font extension output path
    swiftUIFontSwift = "./Sources/Generated/Font+Typography.swift"

    // UIKit label extension output path
    labelStyleSwift = "./Sources/Generated/UILabel+Typography.swift"

    // Typography name style
    nameStyle = "camelCase"
  }
}
```

## Android Section

```pkl
import ".exfig/schemas/Android.pkl"

android = new Android.AndroidConfig {
  // Path to main res directory
  mainRes = "./app/src/main/res"

  // Package for R class references
  resourcePackage = "com.example.app"

  // Path to main source directory (for Compose)
  mainSrc = "./app/src/main/java"

  // Colors
  colors = new Android.ColorsEntry {
    // Output filename
    xmlOutputFileName = "colors.xml"

    // Jetpack Compose package name
    composePackageName = "com.example.app.ui.theme"
  }

  // Icons
  icons = new Android.IconsEntry {
    // Output directory (relative to mainRes)
    output = "exfig-icons"

    // Jetpack Compose package name
    composePackageName = "com.example.app.ui.icons"
  }

  // Images
  images = new Android.ImagesEntry {
    // Output directory (relative to mainRes)
    output = "exfig-images"

    // Image format: svg, png, or webp
    format = "webp"

    // WebP encoding options
    webpOptions = new Common.WebpOptions {
      encoding = "lossy"
      quality = 90
    }

    // Density scales (default: [1, 1.5, 2, 3, 4])
    scales = new Listing { 1; 1.5; 2; 3; 4 }
  }

  // Typography
  typography = new Android.Typography {
    // Naming style
    nameStyle = "snake_case"

    // Jetpack Compose package name
    composePackageName = "com.example.app.ui.typography"
  }
}
```

## Flutter Section

```pkl
import ".exfig/schemas/Flutter.pkl"

flutter = new Flutter.FlutterConfig {
  // Output directory for generated Dart files
  output = "lib/generated"

  // Colors
  colors = new Flutter.ColorsEntry {
    // Output filename
    output = "colors.dart"

    // Class name for colors
    className = "AppColors"
  }

  // Icons
  icons = new Flutter.IconsEntry {
    // Output directory for SVG files
    output = "assets/icons"

    // Dart file output
    dartFile = "icons.dart"

    // Class name for icons
    className = "AppIcons"
  }

  // Images
  images = new Flutter.ImagesEntry {
    // Output directory for images
    output = "assets/images"

    // Dart file output
    dartFile = "images.dart"

    // Class name for images
    className = "AppImages"

    // Image format: svg, png, or webp
    format = "png"

    // Scales to export (default: [1, 2, 3])
    scales = new Listing { 1; 2; 3 }
  }
}
```

## Batch Section

Top-level `batch:` block (read by `exfig batch`). Read ONLY from the **first** config in argv —
per-target `batch:` blocks in subsequent configs are ignored (logged under `-v`).

```pkl showLineNumbers
import ".exfig/schemas/Batch.pkl"

batch = new Batch.BatchConfig {
  // Optional: Maximum configs to process in parallel (default: 3). CLI --parallel overrides.
  parallel = 8

  // Optional: Stop processing on first error (default: false). CLI --fail-fast overrides.
  failFast = true

  // Optional: Resume from previous checkpoint (default: false). CLI --resume overrides.
  resume = false
}
```

For `exfig batch ./configs/`, `parallel`/`failFast`/`resume` come from the FIRST config (or CLI flags
if passed). Boolean fields use OR semantics: CLI `--fail-fast` activates fail-fast even if the config
has `failFast = false`.

## Example Configurations

### iOS Project

```pkl
amends ".exfig/schemas/ExFig.pkl"

import ".exfig/schemas/Figma.pkl"
import ".exfig/schemas/Common.pkl"
import ".exfig/schemas/iOS.pkl"

figma = new Figma.FigmaConfig {
  lightFileId = "ABC123"
  darkFileId = "DEF456"
}

common = new Common.CommonConfig {
  colors = new Common.Colors {
    figmaFrameName = "Colors"
  }
  icons = new Common.Icons {
    figmaFrameName = "Icons"
  }
  images = new Common.Images {
    figmaFrameName = "Illustrations"
  }
}

ios = new iOS.iOSConfig {
  xcodeprojPath = "./MyApp.xcodeproj"
  target = "MyApp"
  xcassetsPath = "./Resources/Assets.xcassets"

  colors = new iOS.ColorsEntry {
    assetsFolder = "Colors"
    colorSwift = "./Sources/UIColor+Colors.swift"
    swiftuiColorSwift = "./Sources/Color+Colors.swift"
  }

  icons = new iOS.IconsEntry {
    assetsFolder = "Icons"
    format = "pdf"
    imageSwift = "./Sources/UIImage+Icons.swift"
  }
}
```

### Android Project

```pkl
amends ".exfig/schemas/ExFig.pkl"

import ".exfig/schemas/Figma.pkl"
import ".exfig/schemas/Common.pkl"
import ".exfig/schemas/Android.pkl"

figma = new Figma.FigmaConfig {
  lightFileId = "ABC123"
}

common = new Common.CommonConfig {
  icons = new Common.Icons {
    figmaFrameName = "Icons"
  }
}

android = new Android.AndroidConfig {
  mainRes = "./app/src/main/res"
  mainSrc = "./app/src/main/java"
  resourcePackage = "com.example.app"

  colors = new Android.ColorsEntry {
    xmlOutputFileName = "colors.xml"
    composePackageName = "com.example.app.ui"
  }

  icons = new Android.IconsEntry {
    output = "exfig-icons"
    composePackageName = "com.example.app.ui"
  }
}
```

### Multi-Platform Project

```pkl
amends ".exfig/schemas/ExFig.pkl"

import ".exfig/schemas/Figma.pkl"
import ".exfig/schemas/Common.pkl"
import ".exfig/schemas/iOS.pkl"
import ".exfig/schemas/Android.pkl"
import ".exfig/schemas/Flutter.pkl"

figma = new Figma.FigmaConfig {
  lightFileId = "ABC123"
  darkFileId = "DEF456"
}

common = new Common.CommonConfig {
  colors = new Common.Colors {
    figmaFrameName = "Colors"
  }
  icons = new Common.Icons {
    figmaFrameName = "Icons"
  }
  images = new Common.Images {
    figmaFrameName = "Images"
  }
}

ios = new iOS.iOSConfig {
  xcodeprojPath = "./ios/MyApp.xcodeproj"
  xcassetsPath = "./ios/Resources/Assets.xcassets"
  colors = new iOS.ColorsEntry {
    assetsFolder = "Colors"
  }
}

android = new Android.AndroidConfig {
  mainRes = "./android/app/src/main/res"
  colors = new Android.ColorsEntry {
    xmlOutputFileName = "colors.xml"
  }
}

flutter = new Flutter.FlutterConfig {
  output = "lib/generated"
  colors = new Flutter.ColorsEntry {
    output = "colors.dart"
  }
}
```

## See Also

- Usage
- DesignRequirements

### Design Requirements

# Design File Structure

How to structure your design files for optimal export with ExFig.


## Overview

ExFig extracts design resources from **Figma** files and **Penpot** projects based on naming conventions
and organizational structures. This guide explains how to set up your design files for seamless export.

- **Figma**: Uses frames, components, color styles, and Variables
- **Penpot**: Uses shared library colors, components, and typographies

## Figma

### Frame Organization

ExFig looks for resources in specific frames. Configure frame names in your `exfig.pkl`:

```pkl
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  colors = new Common.Colors {
    figmaFrameName = "Colors"
  }
  icons = new Common.Icons {
    figmaFrameName = "Icons"
  }
  images = new Common.Images {
    figmaFrameName = "Illustrations"
  }
  typography = new Common.Typography {
    figmaFrameName = "Typography"
  }
}
```

### Naming Conventions

Use consistent naming patterns for all resources. ExFig supports regex validation:

```pkl
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  icons = new Common.Icons {
    nameValidateRegexp = "^ic/[0-9]+/[a-z_]+$"  // e.g., ic/24/arrow_right
  }
}
```

### Colors

#### Using Color Styles

Create color styles in Figma with descriptive names:

```
Colors frame
├── primary
├── secondary
├── background/primary
├── background/secondary
├── text/primary
├── text/secondary
└── border/default
```

#### Using Figma Variables

For Figma Variables API support:

```pkl
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  variablesColors = new Common.VariablesColors {
    tokensFileId = "ABC123xyz"
    tokensCollectionName = "Colors"
    lightModeName = "Light"
    darkModeName = "Dark"
  }
}
```

Variable structure in Figma:

```
Colors collection
├── Mode: Light
│   ├── primary: #007AFF
│   ├── background: #FFFFFF
│   └── text: #000000
└── Mode: Dark
    ├── primary: #0A84FF
    ├── background: #000000
    └── text: #FFFFFF
```

#### Naming Guidelines

- Use lowercase with optional separators: `/`, `-`, `_`
- Group related colors with prefixes: `text/primary`, `background/card`
- Avoid special characters except separators

### Icons

#### Component Structure

Icons must be **components** (not plain frames):

```
Icons frame
├── ic/24/arrow-right     (component)
├── ic/24/arrow-left      (component)
├── ic/16/close           (component)
├── ic/16/check           (component)
└── ic/32/menu            (component)
```

#### Size Conventions

Organize icons by size:

```
Icons frame
├── ic/16/...   (16pt icons)
├── ic/24/...   (24pt icons)
├── ic/32/...   (32pt icons)
└── ic/48/...   (48pt icons)
```

#### Vector Requirements

For optimal vector export:

1. **Use strokes carefully**: Convert strokes to outlines for complex icons
2. **Flatten boolean operations**: Flatten complex boolean operations before export
3. **Remove hidden layers**: Delete unused or hidden elements
4. **Use consistent viewBox**: Keep viewBox dimensions consistent within size groups

#### Dark Mode Icons

Two approaches for dark mode support:

**Separate files:**

```pkl
import ".exfig/schemas/Figma.pkl"

figma = new Figma.FigmaConfig {
  lightFileId = "abc123"
  darkFileId = "def456"
}
```

Create matching component names in both files.

**Single file with suffix:**

```pkl
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  icons = new Common.Icons {
    suffixDarkMode = new Common.SuffixDarkMode { suffix = "_dark" }
  }
}
```

```
Icons frame
├── ic/24/arrow-right
├── ic/24/arrow-right_dark
├── ic/24/close
└── ic/24/close_dark
```

### Images

#### Component Structure

Images must be **components**:

```
Illustrations frame
├── img-empty-state       (component)
├── img-onboarding-1      (component)
├── img-onboarding-2      (component)
└── img-hero-banner       (component)
```

#### Size Recommendations

Design at the largest needed scale:

- **iOS**: Design at @3x, ExFig generates @1x, @2x, @3x
- **Android**: Design at xxxhdpi (4x), ExFig generates all densities
- **Flutter**: Design at 3x, ExFig generates 1x, 2x, 3x

#### Multi-Idiom Support (iOS)

Use suffixes for device-specific variants:

```
Illustrations frame
├── img-hero~iphone       (iPhone variant)
├── img-hero~ipad         (iPad variant)
├── img-hero~mac          (Mac variant)
└── img-sidebar~ipad
```

#### Dark Mode Images

Same approaches as icons:

**Separate files** or **suffix-based**:

```
Illustrations frame
├── img-empty-state
├── img-empty-state_dark
├── img-hero
└── img-hero_dark
```

### Typography

#### Text Style Structure

Create text styles with hierarchical names:

```
Typography frame
├── heading/h1
├── heading/h2
├── heading/h3
├── body/regular
├── body/bold
├── caption/regular
└── caption/small
```

#### Required Properties

Each text style should define:

- **Font family**: e.g., "SF Pro Text"
- **Font weight**: e.g., Regular, Bold, Semibold
- **Font size**: in pixels
- **Line height**: in pixels or percentage
- **Letter spacing**: in pixels or percentage

#### Font Mapping

Map Figma fonts to platform fonts in your config:

```pkl
import ".exfig/schemas/iOS.pkl"
import ".exfig/schemas/Android.pkl"

ios = new iOS.iOSConfig {
  typography = new iOS.Typography {
    // fontMapping configured via custom templates
  }
}

android = new Android.AndroidConfig {
  typography = new Android.Typography {
    // fontMapping configured via custom templates
  }
}
```

### Validation Regex Patterns

#### Common Patterns

```pkl
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  colors = new Common.Colors {
    // Allow: primary, text/primary, background_card
    nameValidateRegexp = "^[a-z][a-z0-9_/]*$"
  }

  icons = new Common.Icons {
    // Require: ic/SIZE/name format
    nameValidateRegexp = "^ic/[0-9]+/[a-z][a-z0-9_-]*$"
  }

  images = new Common.Images {
    // Require: img- prefix
    nameValidateRegexp = "^img-[a-z][a-z0-9_-]*$"
  }
}
```

#### Transform Patterns

Transform names during export:

```pkl
import ".exfig/schemas/Common.pkl"

common = new Common.CommonConfig {
  icons = new Common.Icons {
    nameValidateRegexp = "^ic/([0-9]+)/(.+)$"
    nameReplaceRegexp = "ic$1_$2"  // ic/24/arrow -> ic24_arrow
  }
}
```

### Recommended Figma Structure

```
Design System
├── Colors
│   ├── Primary palette
│   ├── Secondary palette
│   ├── Semantic colors
│   └── Dark mode colors
├── Icons
│   ├── 16pt icons
│   ├── 24pt icons
│   └── 32pt icons
├── Illustrations
│   ├── Empty states
│   ├── Onboarding
│   └── Marketing
└── Typography
    ├── Headings
    ├── Body text
    └── Captions
```

### Light and Dark Mode Files

For complex theming, use separate files:

- `Design-System-Light.fig`: Light mode resources
- `Design-System-Dark.fig`: Dark mode resources

Ensure component names match exactly between files.

### Figma Troubleshooting

#### Resources Not Found

- Verify frame names match `figmaFrameName` in config
- Check that resources are **components**, not plain frames
- Ensure names pass validation regex

#### Missing Dark Mode

- Verify `darkFileId` is set correctly
- Check component names match between light and dark files
- For single-file mode, verify suffix is correct

#### Export Quality Issues

- Design at highest needed resolution
- Use vector graphics when possible
- Avoid raster effects in vector icons
- Flatten complex boolean operations

## Penpot

ExFig reads Penpot library assets — colors, components, and typographies — from the shared library
of a Penpot file. All assets must be added to the **shared library** (Assets panel), not just placed
on the canvas.

### Authentication

Set the `PENPOT_ACCESS_TOKEN` environment variable:

1. Open Penpot → Settings → Access Tokens
2. Create a new token (no expiration recommended for CI)
3. Export:

```bash
export PENPOT_ACCESS_TOKEN="your-token-here"
```

No `FIGMA_PERSONAL_TOKEN` needed when using only Penpot sources.

### Library Colors

Colors must be in the shared **Library** (Assets panel → Local library → Colors):

```
Library Colors
├── Brand/Primary      (#3B82F6)
├── Brand/Secondary    (#8B5CF6)
├── Semantic/Success   (#22C55E)
├── Semantic/Warning   (#F59E0B)
├── Semantic/Error     (#EF4444)
├── Neutral/Background (#1E1E2E)
├── Neutral/Text       (#F8F8F2)
└── Neutral/Overlay    (#000000, 50% opacity)
```

Key points:

- Only **solid hex colors** are exported. Gradients and image fills are skipped in v1.
- The `path` field organizes colors into groups: `path: "Brand"`, `name: "Primary"` → `Brand/Primary`
- Use `pathFilter` in your config to select a specific group: `pathFilter = "Brand"` exports only Brand colors
- **Opacity** is preserved (0.0–1.0)

Config example:

```pkl
penpotSource = new Common.PenpotSource {
  fileId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  pathFilter = "Brand"  // optional: export only Brand/* colors
}
```

### Library Components (Icons and Images)

Components must be in the shared **Library** (Assets panel → Local library → Components).
ExFig filters by the component `path` prefix (equivalent to Figma's frame name):

```
Library Components
├── Icons/Navigation/arrow-left
├── Icons/Navigation/arrow-right
├── Icons/Actions/close
├── Icons/Actions/check
├── Illustrations/Empty States/no-data
└── Illustrations/Onboarding/welcome
```

Config example:

```pkl
penpotSource = new Common.PenpotSource {
  fileId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
// Use path prefix as the frame filter
figmaFrameName = "Icons/Navigation"  // exports arrow-left, arrow-right
```

ExFig reconstructs SVG directly from Penpot's shape tree — no headless Chrome or CDN needed.
Supported output formats: **SVG** (native vector), **PNG** (via resvg at any scale), **PDF**, **WebP**.

### Library Typography

Typography styles must be in the shared **Library** (Assets panel → Local library → Typography):

```
Library Typography
├── Heading/H1     (Roboto Bold 32px)
├── Heading/H2     (Roboto Bold 24px)
├── Body/Regular   (Roboto Regular 16px)
├── Body/Bold      (Roboto Bold 16px)
└── Caption/Small  (Roboto Regular 12px)
```

Required fields:

- **fontFamily** — e.g., "Roboto", "DM Mono"
- **fontSize** — must be set (styles without a parseable font size are skipped)

Supported fields: `fontWeight`, `lineHeight`, `letterSpacing`, `textTransform` (uppercase/lowercase).

> Penpot may serialize numeric fields as strings (e.g., `"24"` instead of `24`). ExFig handles both formats automatically.

### Recommended Penpot Structure

```
Design System (Penpot file)
├── Library Colors
│   ├── Brand/* (primary, secondary, accent)
│   ├── Semantic/* (success, warning, error, info)
│   └── Neutral/* (background, text, border, overlay)
├── Library Components
│   ├── Icons/Navigation/* (arrow, chevron, menu)
│   ├── Icons/Actions/* (close, check, edit, delete)
│   └── Illustrations/* (empty states, onboarding)
└── Library Typography
    ├── Heading/* (H1, H2, H3)
    ├── Body/* (regular, bold, italic)
    └── Caption/* (regular, small)
```

### Known Limitations

- **No dark mode support** — Penpot has no Variables/modes equivalent; colors export as light-only
- **No `exfig_inspect` for Penpot** — the MCP inspect tool works with Figma API only
- **Gradients skipped** — only solid hex colors are supported
- **No page filtering** — all library assets are global to the file, not page-scoped
- **SVG reconstruction scope** — supports path, rect, circle, bool, group shapes; complex effects (blur, shadow, gradients on shapes) are not yet rendered

### Penpot Troubleshooting

#### No Colors Exported

- Verify colors are in the **shared library**, not just swatches on the canvas
- Check `pathFilter` — a too-specific prefix returns no results
- Gradient colors are skipped; use solid fills

#### No Components Exported

- Verify components are in the **shared library** (right-click shape → "Create component")
- Check the path prefix in `figmaFrameName` matches the component `path`
- Thumbnails may not be generated for programmatically created components

#### Typography Styles Skipped

- Ensure `fontSize` is set on the typography style
- Styles with unparseable font size values are silently skipped

#### Authentication Errors

- `PENPOT_ACCESS_TOKEN environment variable is required` — set the token
- Penpot 401 — token expired or invalid; regenerate in Settings → Access Tokens
- Self-hosted instances: set `baseUrl` in `penpotSource`

## See Also

- Configuration
- iOS
- Android
- Flutter

### Custom Templates

# Custom Templates

Customize generated code using Jinja2 templates.


## Overview

ExFig uses [Jinja2](https://github.com/huggingface/swift-jinja) templates to generate platform-specific code. You can customize the
output by providing your own templates.

## Setting Up Custom Templates

### 1. Create Templates Directory

```bash
mkdir -p ./templates
```

### 2. Configure Template Path

```pkl
import ".exfig/schemas/iOS.pkl"
import ".exfig/schemas/Android.pkl"
import ".exfig/schemas/Flutter.pkl"
import ".exfig/schemas/Web.pkl"

ios = new iOS.iOSConfig {
  templatesPath = "./templates"
}

android = new Android.AndroidConfig {
  templatesPath = "./templates"
}

flutter = new Flutter.FlutterConfig {
  templatesPath = "./templates"
}

web = new Web.WebConfig {
  templatesPath = "./templates"
}
```

### 3. Copy Default Templates

Copy the default templates from ExFig source to use as a starting point. Templates are located in:

- `Sources/XcodeExport/Resources/` - iOS templates
- `Sources/AndroidExport/Resources/` - Android templates
- `Sources/FlutterExport/Resources/` - Flutter templates
- `Sources/WebExport/Resources/` - Web templates

## iOS Templates

### Available Templates

| Template                              | Output            | Description               |
| ------------------------------------- | ----------------- | ------------------------- |
| `UIColor+extension.swift.jinja`       | UIColor extension | UIKit color definitions   |
| `Color+extension.swift.jinja`         | Color extension   | SwiftUI color definitions |
| `UIImage+extension.swift.jinja`       | UIImage extension | UIKit image accessors     |
| `Image+extension.swift.jinja`         | Image extension   | SwiftUI image accessors   |
| `UIFont+extension.swift.jinja`        | UIFont extension  | UIKit font definitions    |
| `Font+extension.swift.jinja`          | Font extension    | SwiftUI font definitions  |
| `Label.swift.jinja`                   | Label class       | UIKit label styles        |
| `LabelStyle.swift.jinja`             | LabelStyle enum   | Label style definitions   |
| `LabelStyle+extension.swift.jinja`   | LabelStyle ext.   | LabelStyle factory methods |
| `CodeConnect.figma.swift.jinja`      | Code Connect      | Figma Code Connect (debug) |
| `header.jinja`                        | File header       | Common header comment     |

> Note: Files ending in `.jinja.include` (e.g., `Bundle+extension.swift.jinja.include`) are partial templates — they are pre-rendered into context variables (like `bundleExtension`) and included in the main template output. You typically don't need to customize these.

### Context Variables (Colors)

```swift
// Available in color templates
colors: [
    {
        name: "primaryBlue",           // Formatted name
        originalName: "primary/blue",  // Original Figma name
        red: 0.0,                       // RGB components (0-1)
        green: 0.478,
        blue: 1.0,
        alpha: 1.0,
        hex: "#007AFF"                  // Hex string
    }
]
darkColors: [...]  // Same structure for dark mode
```

### Context Variables (Icons)

```swift
// Available in icon templates
icons: [
    {
        name: "icArrowRight",          // Formatted name
        originalName: "ic/24/arrow-right"
    }
]
```

### Context Variables (Typography)

```swift
// Available in typography templates
textStyles: [
    {
        name: "bodyRegular",
        fontFamily: "Inter",
        fontWeight: "regular",         // regular, medium, semibold, bold
        fontWeightValue: 400,          // Numeric weight
        fontSize: 16.0,
        lineHeight: 24.0,              // nil if not set
        letterSpacing: 0.0
    }
]
```

### Example: Custom UIColor Template

```jinja
{{ header }}

import UIKit

public extension UIColor {
    {% for color in colors %}
    /// {{ color.originalName }}
    static let {{ color.name }} = UIColor(
        red: {{ color.red }},
        green: {{ color.green }},
        blue: {{ color.blue }},
        alpha: {{ color.alpha }}
    )
    {% endfor %}
}
```

## Android Templates

### Available Templates

| Template               | Output         | Description               |
| ---------------------- | -------------- | ------------------------- |
| `colors.xml.jinja`     | colors.xml     | XML color resources       |
| `Colors.kt.jinja`      | Colors.kt      | Compose color definitions |
| `typography.xml.jinja`  | typography.xml | XML text styles           |
| `Typography.kt.jinja`  | Typography.kt  | Compose typography        |
| `Icons.kt.jinja`       | Icons.kt       | Compose icon composables  |
| `CodeConnect.figma.kt.jinja` | Code Connect | Figma Code Connect (debug) |
| `header.jinja`         | File header    | Common header comment     |

### Context Variables (Colors)

```kotlin
// Available in color templates
colors: [
    {
        name: "primary_blue",          // snake_case name
        hex: "#007AFF",                // With alpha: "#FF007AFF"
        hexARGB: "FF007AFF"            // ARGB without #
    }
]
```

### Context Variables (Typography)

```kotlin
// Available in typography templates
textStyles: [
    {
        name: "body_regular",
        fontFamily: "inter",           // Lowercase
        fontWeightName: "Normal",      // FontWeight constant name
        fontSize: 16,                  // In sp
        lineHeight: 24,                // In sp, nil if not set
        letterSpacing: 0.0             // In em
    }
]
```

### Example: Custom Colors.kt Template

```jinja
{{ header }}

package {{ packageName }}

import androidx.compose.ui.graphics.Color

object AppColors {
    {% for color in colors %}
    val {{ color.name }} = Color(0x{{ color.hexARGB }})
    {% endfor %}
}

object AppColorsDark {
    {% for color in darkColors %}
    val {{ color.name }} = Color(0x{{ color.hexARGB }})
    {% endfor %}
}
```

## Flutter Templates

### Available Templates

| Template            | Output      | Description           |
| ------------------- | ----------- | --------------------- |
| `colors.dart.jinja` | colors.dart | Dart color constants  |
| `icons.dart.jinja`  | icons.dart  | Dart icon paths       |
| `images.dart.jinja` | images.dart | Dart image paths      |
| `header.jinja`      | File header | Common header comment |

### Context Variables

```dart
// Available in Flutter templates
colors: [
    {
        name: "primaryBlue",
        hex: "0xFF007AFF"              // Dart Color format
    }
]

icons: [
    {
        name: "icArrowRight",
        path: "assets/icons/ic_arrow_right.svg"
    }
]

images: [
    {
        name: "imgHero",
        path: "assets/images/img_hero.png"
    }
]
```

### Example: Custom colors.dart Template

```jinja
{{ header }}

import 'package:flutter/material.dart';

class {{ className }} {
  {{ className }}._();

  {% for color in colors %}
  /// {{ color.originalName }}
  static const Color {{ color.name }} = Color({{ color.hex }});
  {% endfor %}
}

class {{ className }}Dark {
  {{ className }}Dark._();

  {% for color in darkColors %}
  static const Color {{ color.name }} = Color({{ color.hex }});
  {% endfor %}
}
```

## Web Templates

### Available Templates

| Template              | Output          | Description                        |
| --------------------- | --------------- | ---------------------------------- |
| `theme.css.jinja`     | theme.css       | CSS custom properties (light/dark) |
| `variables.ts.jinja`  | variables.ts    | TypeScript CSS variable references |
| `theme.json.jinja`    | theme.json      | JSON theme tokens                  |
| `Icon.tsx.jinja`      | Icon component  | React SVG icon component           |
| `types.ts.jinja`      | types.ts        | TypeScript type definitions        |
| `IconIndex.ts.jinja`  | index.ts        | Icon barrel exports                |
| `Image.tsx.jinja`     | Image component | React image component              |
| `ImageIndex.ts.jinja` | index.ts        | Image barrel exports               |
| `header.jinja`        | File header     | Common header comment              |

### Context Variables (Colors)

```typescript
// variables.ts context
colors: [{ camelName: "primaryBlue", cssName: "primary-blue" }]

// theme.css / theme.json context
lightColors: [{ cssName: "primary-blue", value: "#007AFF" }]
darkColors: [{ cssName: "primary-blue", value: "#0A84FF" }]
hasDarkColors: true
```

### Context Variables (Icons)

```typescript
// Icon.tsx context (per component)
componentName: "ArrowRight"
viewBox: "0 0 24 24"
svgContent: "<path ...>"

// IconIndex.ts context
icons: [{ componentName: "ArrowRight", fileName: "arrow_right" }]
```

### Context Variables (Images)

```typescript
// Image.tsx context (per component)
componentName: "HeroBanner"
name: "hero_banner"
assetPath: "assets/images/hero_banner.png"

// ImageIndex.ts context
images: [{ componentName: "HeroBanner", fileName: "hero_banner" }]
```

### Example: Custom theme.css Template

```jinja
:root {
  {% for color in lightColors %}
  --{{ color.cssName }}: {{ color.value }};
  {% endfor %}
}

{% if hasDarkColors %}
@media (prefers-color-scheme: dark) {
  :root {
    {% for color in darkColors %}
    --{{ color.cssName }}: {{ color.value }};
    {% endfor %}
  }
}
{% endif %}
```


## Jinja2 Syntax Reference

### Variables

```jinja
{{ variableName }}
{{ object.property }}
```

### Loops

```jinja
{% for item in items %}
{{ item.name }}
{% endfor %}
```

### Loop Variables

```jinja
{% for item in items %}
{{ loop.index }}        {# 1-based index #}
{{ loop.index0 }}       {# 0-based index #}
{{ loop.first }}        {# true on first iteration #}
{{ loop.last }}         {# true on last iteration #}
{% endfor %}
```

### Conditionals

```jinja
{% if condition %}
...
{% elif otherCondition %}
...
{% else %}
...
{% endif %}
```

### Filters

```jinja
{{ name | upper }}
{{ name | lower }}
{{ name | capitalize }}
```

> Note: Name transformation filters (camelCase, snake_case, etc.) are not needed — name formatting is applied before template rendering, so variable values arrive pre-formatted.

### Comments

```jinja
{# This is a comment #}
```

## Best Practices

1. **Start from defaults**: Copy default templates as a starting point
2. **Use context variables**: Common data (like headers) is provided as pre-rendered context variables
3. **Validate output**: Test generated code compiles correctly
4. **Document changes**: Add comments explaining customizations
5. **Version control**: Keep templates in your repository
6. **Pre-formatted names**: Name formatting (camelCase, snake_case, etc.) is done before template rendering — use names as-is

## See Also

- Configuration
- iOS
- Android
- Flutter
- [swift-jinja Documentation](https://github.com/huggingface/swift-jinja)

## Platform Guides

### iOS Platform Guide

# iOS Export

Export Figma resources to Xcode projects with Assets catalogs and Swift extensions.


## Overview

ExFig exports design resources from Figma to iOS projects:

- **Colors**: Color Sets in Assets.xcassets with UIColor/Color extensions
- **Icons**: PDF or SVG icons in Image Sets with UIImage/Image extensions
- **Images**: Multi-scale PNG, HEIC, or WebP images with UIImage/Image extensions
- **Typography**: UIFont/Font extensions with text style configurations

## Quick Start

### 1. Generate Configuration

```bash
exfig init --platform ios
```

### 2. Configure Your Project

Edit `exfig.pkl`:

```pkl
amends ".exfig/schemas/ExFig.pkl"

import ".exfig/schemas/Figma.pkl"
import ".exfig/schemas/iOS.pkl"

figma = new Figma.FigmaConfig {
  lightFileId = "YOUR_FILE_ID"
  darkFileId = "YOUR_DARK_FILE_ID"  // Optional
}

ios = new iOS.iOSConfig {
  xcodeprojPath = "./MyApp.xcodeproj"
  target = "MyApp"
  xcassetsPath = "./Resources/Assets.xcassets"

  colors = new iOS.ColorsEntry {
    assetsFolder = "Colors"
    colorSwift = "./Sources/UIColor+Colors.swift"
    swiftuiColorSwift = "./Sources/Color+Colors.swift"
  }

  icons = new iOS.IconsEntry {
    assetsFolder = "Icons"
    format = "pdf"
    imageSwift = "./Sources/UIImage+Icons.swift"
    swiftUIImageSwift = "./Sources/Image+Icons.swift"
  }

  images = new iOS.ImagesEntry {
    assetsFolder = "Images"
    scales = new Listing { 1; 2; 3 }
    imageSwift = "./Sources/UIImage+Images.swift"
  }

  typography = new iOS.Typography {
    fontSwift = "./Sources/UIFont+Typography.swift"
    swiftUIFontSwift = "./Sources/Font+Typography.swift"
  }
}
```

### 3. Export Resources

```bash
exfig colors
exfig icons
exfig images
exfig typography
```

## Generated Output

### Colors

**Assets.xcassets/Colors/**

```
Colors/
├── primary.colorset/
│   └── Contents.json
├── secondary.colorset/
│   └── Contents.json
└── background/
    ├── primary.colorset/
    └── secondary.colorset/
```

**UIColor+Colors.swift**

```swift
import UIKit

extension UIColor {
    static var primary: UIColor {
        UIColor(named: "primary")!
    }
    static var backgroundPrimary: UIColor {
        UIColor(named: "background/primary")!
    }
}
```

**Color+Colors.swift**

```swift
import SwiftUI

extension Color {
    static var primary: Color {
        Color("primary")
    }
    static var backgroundPrimary: Color {
        Color("background/primary")
    }
}
```

### Icons

**Assets.xcassets/Icons/**

```
Icons/
├── icArrowRight.imageset/
│   ├── icArrowRight.pdf
│   └── Contents.json
└── icClose.imageset/
    ├── icClose.pdf
    └── Contents.json
```

### Images

**Assets.xcassets/Images/**

```
Images/
├── imgHero.imageset/
│   ├── imgHero.png       # @1x
│   ├── imgHero@2x.png    # @2x
│   ├── imgHero@3x.png    # @3x
│   └── Contents.json
```

## Usage in Code

### UIKit

```swift
// Colors
view.backgroundColor = .primary
label.textColor = .textPrimary

// Icons
let icon = UIImage.icArrowRight
button.setImage(.icClose, for: .normal)

// Images
imageView.image = .imgHero

// Typography
label.font = .bodyRegular()
titleLabel.font = .headingH1()
```

### SwiftUI

```swift
struct ContentView: View {
    var body: some View {
        VStack {
            // Colors
            Rectangle()
                .fill(Color.primary)

            // Icons
            Image.icArrowRight
                .renderingMode(.template)
                .foregroundColor(.textPrimary)

            // Images
            Image.imgHero
                .resizable()
                .aspectRatio(contentMode: .fit)

            // Typography
            Text("Hello")
                .font(.bodyRegular)
        }
    }
}
```

## Topics

### Resources

@Links(visualStyle: compactGrid) {
    - iOSColors
    - iOSIcons
    - iOSImages
    - iOSTypography
}

## See Also

- Configuration
- DesignRequirements

### Android Platform Guide

# Android Export

Export Figma resources to Android projects with XML resources and Jetpack Compose code.


## Overview

ExFig exports design resources from Figma to Android projects:

- **Colors**: XML color resources and Compose Color constants
- **Icons**: VectorDrawable XML files and Compose Icon composables
- **Images**: Multi-density PNG/WebP images
- **Typography**: XML text styles and Compose Typography definitions

## Quick Start

### 1. Generate Configuration

```bash
exfig init --platform android
```

### 2. Configure Your Project

Edit `exfig.pkl`:

```pkl
amends ".exfig/schemas/ExFig.pkl"

import ".exfig/schemas/Figma.pkl"
import ".exfig/schemas/Android.pkl"

figma = new Figma.FigmaConfig {
  lightFileId = "YOUR_FILE_ID"
  darkFileId = "YOUR_DARK_FILE_ID"  // Optional
}

android = new Android.AndroidConfig {
  mainRes = "./app/src/main/res"
  mainSrc = "./app/src/main/java"
  resourcePackage = "com.example.app"

  colors = new Android.ColorsEntry {
    xmlOutputFileName = "colors.xml"
    composePackageName = "com.example.app.ui.theme"
  }

  icons = new Android.IconsEntry {
    output = "exfig-icons"
    composePackageName = "com.example.app.ui.icons"
  }

  images = new Android.ImagesEntry {
    output = "exfig-images"
    format = "webp"
    scales = new Listing { 1; 1.5; 2; 3; 4 }
  }

  typography = new Android.Typography {
    nameStyle = "camelCase"
    composePackageName = "com.example.app.ui.theme"
  }
}
```

### 3. Configure build.gradle

Add generated resource directories:

```gradle
android {
    sourceSets {
        main {
            res.srcDirs += "src/main/res/exfig-icons"
            res.srcDirs += "src/main/res/exfig-images"
        }
    }
}
```

### 4. Export Resources

```bash
exfig colors
exfig icons
exfig images
exfig typography
```

## Generated Output

### Colors

**res/values/colors.xml**

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="primary">#FF007AFF</color>
    <color name="secondary">#FF5856D6</color>
    <color name="background_primary">#FFFFFFFF</color>
    <color name="text_primary">#FF000000</color>
</resources>
```

**res/values-night/colors.xml**

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <color name="primary">#FF0A84FF</color>
    <color name="secondary">#FF5E5CE6</color>
    <color name="background_primary">#FF000000</color>
    <color name="text_primary">#FFFFFFFF</color>
</resources>
```

**Colors.kt (Compose)**

```kotlin
package com.example.app.ui.theme

import androidx.compose.ui.graphics.Color

object AppColors {
    val Primary = Color(0xFF007AFF)
    val Secondary = Color(0xFF5856D6)
    val BackgroundPrimary = Color(0xFFFFFFFF)
    val TextPrimary = Color(0xFF000000)
}

object AppColorsDark {
    val Primary = Color(0xFF0A84FF)
    val Secondary = Color(0xFF5E5CE6)
    val BackgroundPrimary = Color(0xFF000000)
    val TextPrimary = Color(0xFFFFFFFF)
}
```

### Icons

**exfig-icons/drawable/ic_arrow_right.xml**

```xml
<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="24dp"
    android:height="24dp"
    android:viewportWidth="24"
    android:viewportHeight="24">
    <path
        android:fillColor="#000000"
        android:pathData="M8,4 L16,12 L8,20"/>
</vector>
```

### Images

```
exfig-images/
├── drawable-mdpi/
│   └── img_hero.webp        # @1x (160 dpi)
├── drawable-hdpi/
│   └── img_hero.webp        # @1.5x (240 dpi)
├── drawable-xhdpi/
│   └── img_hero.webp        # @2x (320 dpi)
├── drawable-xxhdpi/
│   └── img_hero.webp        # @3x (480 dpi)
└── drawable-xxxhdpi/
    └── img_hero.webp        # @4x (640 dpi)
```

## Usage in Code

### XML Views

```xml
<!-- Colors -->
<TextView
    android:textColor="@color/text_primary"
    android:background="@color/background_primary"/>

<!-- Icons -->
<ImageView
    android:src="@drawable/ic_arrow_right"
    android:tint="@color/primary"/>

<!-- Images -->
<ImageView
    android:src="@drawable/img_hero"
    android:scaleType="centerCrop"/>
```

### Jetpack Compose

```kotlin
@Composable
fun MyScreen() {
    Column(
        modifier = Modifier
            .fillMaxSize()
            .background(AppColors.BackgroundPrimary)
    ) {
        Text(
            text = "Hello",
            color = AppColors.TextPrimary,
            style = AppTypography.HeadingH1
        )

        Icon(
            painter = painterResource(R.drawable.ic_arrow_right),
            contentDescription = null,
            tint = AppColors.Primary
        )

        Image(
            painter = painterResource(R.drawable.img_hero),
            contentDescription = null,
            contentScale = ContentScale.Crop
        )
    }
}
```

## Topics

### Resources

@Links(visualStyle: compactGrid) {
    - AndroidColors
    - AndroidIcons
    - AndroidImages
    - AndroidTypography
}

## See Also

- Configuration
- DesignRequirements

### Flutter Platform Guide

# Flutter Export

Export Figma resources to Flutter projects with Dart code and asset files.


## Overview

ExFig exports design resources from Figma to Flutter projects:

- **Colors**: Dart constants with `Color(0xAARRGGBB)` format
- **Icons**: SVG icons with optional dark mode variants
- **Images**: Multi-scale images (1x, 2x, 3x) in PNG, SVG, or WebP format

> Note: Typography export is not currently supported for Flutter.

## Quick Start

### 1. Generate Configuration

```bash
exfig init --platform flutter
```

### 2. Configure Your Project

Edit `exfig.pkl`:

```pkl
amends ".exfig/schemas/ExFig.pkl"

import ".exfig/schemas/Figma.pkl"
import ".exfig/schemas/Flutter.pkl"

figma = new Figma.FigmaConfig {
  lightFileId = "YOUR_FILE_ID"
  darkFileId = "YOUR_DARK_FILE_ID"  // optional
}

flutter = new Flutter.FlutterConfig {
  output = "lib/generated"

  colors = new Flutter.ColorsEntry {
    output = "colors.dart"
    className = "AppColors"
  }

  icons = new Flutter.IconsEntry {
    output = "assets/icons"
    dartFile = "icons.dart"
    className = "AppIcons"
  }

  images = new Flutter.ImagesEntry {
    output = "assets/images"
    dartFile = "images.dart"
    className = "AppImages"
    format = "png"
    scales = new Listing { 1; 2; 3 }
  }
}
```

### 3. Export Resources

```bash
# Export colors
exfig colors

# Export icons
exfig icons

# Export images
exfig images
```

## Generated Output

### Colors

**lib/generated/colors.dart**

```dart
// Do not edit this file!
// Generated by ExFig

import 'package:flutter/material.dart';

class AppColors {
  AppColors._();
  static const Color primary = Color(0xFF007AFF);
  static const Color secondary = Color(0xFF5856D6);
  static const Color background = Color(0xFFFFFFFF);
  static const Color textPrimary = Color(0xFF000000);
}

class AppColorsDark {
  AppColorsDark._();
  static const Color primary = Color(0xFF0A84FF);
  static const Color secondary = Color(0xFF5E5CE6);
  static const Color background = Color(0xFF000000);
  static const Color textPrimary = Color(0xFFFFFFFF);
}
```

### Icons

**File structure:**

```
assets/
└── icons/
    ├── ic_add.svg
    ├── ic_add_dark.svg
    ├── ic_settings.svg
    └── ic_settings_dark.svg

lib/
└── generated/
    └── icons.dart
```

**icons.dart:**

```dart
// Do not edit this file!
// Generated by ExFig

class AppIcons {
  AppIcons._();
  static const String icAdd = 'assets/icons/ic_add.svg';
  static const String icAddDark = 'assets/icons/ic_add_dark.svg';
  static const String icSettings = 'assets/icons/ic_settings.svg';
}
```

### Images

**File structure:**

```
assets/
└── images/
    ├── logo.png           # 1x scale
    ├── 2.0x/
    │   └── logo.png       # 2x scale
    └── 3.0x/
        └── logo.png       # 3x scale

lib/
└── generated/
    └── images.dart
```

**images.dart:**

```dart
// Do not edit this file!
// Generated by ExFig

class AppImages {
  AppImages._();
  static const String logo = 'assets/images/logo.png';
  static const String hero = 'assets/images/hero.png';
  static const String heroDark = 'assets/images/hero_dark.png';
}
```

## Usage in Flutter

### Using Colors

```dart
import 'package:your_app/generated/colors.dart';

Container(
  color: AppColors.primary,
  // For dark mode:
  // color: AppColorsDark.primary,
)
```

### Using Icons with flutter_svg

```dart
import 'package:flutter_svg/flutter_svg.dart';
import 'package:your_app/generated/icons.dart';

SvgPicture.asset(
  AppIcons.icSettings,
  width: 24,
  height: 24,
)
```

### Using Images

```dart
import 'package:your_app/generated/images.dart';

Image.asset(
  AppImages.logo,
  width: 200,
)
```

## pubspec.yaml Configuration

Register your assets in `pubspec.yaml`:

```yaml
flutter:
  assets:
    - assets/icons/
    - assets/images/
    - assets/images/2.0x/
    - assets/images/3.0x/
```

## Configuration Reference

### flutter

| Option          | Type   | Required | Default | Description                             |
| --------------- | ------ | -------- | ------- | --------------------------------------- |
| `output`        | String | Yes      | -       | Path to output directory for Dart files |
| `templatesPath` | String | No       | -       | Path to custom Jinja2 templates        |

### flutter.colors

| Option      | Type   | Required | Default       | Description          |
| ----------- | ------ | -------- | ------------- | -------------------- |
| `output`    | String | No       | `colors.dart` | Output filename      |
| `className` | String | No       | `AppColors`   | Generated class name |

### flutter.icons

| Option      | Type   | Required | Default      | Description                        |
| ----------- | ------ | -------- | ------------ | ---------------------------------- |
| `output`    | String | Yes      | -            | Path for SVG asset files           |
| `dartFile`  | String | No       | `icons.dart` | Output filename for Dart constants |
| `className` | String | No       | `AppIcons`   | Generated class name               |

### flutter.images

| Option                 | Type   | Required | Default       | Description                           |
| ---------------------- | ------ | -------- | ------------- | ------------------------------------- |
| `output`               | String | Yes      | -             | Path for image asset files            |
| `dartFile`             | String | No       | `images.dart` | Output filename for Dart constants    |
| `className`            | String | No       | `AppImages`   | Generated class name                  |
| `format`               | String | No       | `png`         | Image format: `svg`, `png`, or `webp` |
| `scales`               | Array  | No       | `[1, 2, 3]`   | Asset scales to generate              |
| `webpOptions.encoding` | String | No       | -             | WebP encoding: `lossy` or `lossless`  |
| `webpOptions.quality`  | Number | No       | -             | Quality (0-100) for lossy encoding    |

## Tips

1. **Use WebP** for smaller image sizes
2. **Use SVG** for icons to reduce bundle size
3. **Only include necessary scales**: `[2, 3]` for most modern devices
4. **Post-export optimization** for PNG format:
   ```bash
   oxipng -o max -Z ./assets/images/**/*.png
   ```

## Troubleshooting

### WebP encoding quality not specified

When using `format = "webp"` with `encoding = "lossy"`, you must specify a quality value:

```pkl
flutter = new Flutter.FlutterConfig {
  images = new Flutter.ImagesEntry {
    format = "webp"
    // webpOptions configured via Common.WebpOptions
  }
}
```

For lossless encoding, quality is not required.

## See Also

- Configuration
- DesignRequirements
- CustomTemplates