Sheet to Layers

A powerful Figma plugin that automatically populates your designs with data from CSV or XLSX files. Simply prepare your spreadsheet, name your layers with `#` prefixes, and watch as the plugin duplicates frames and fills them with your data—perfect for creating multiple variations, data tables, or dynamic content.

## Features

- 📊 **CSV/XLSX Support** - Works with standard spreadsheet files

- 🔄 **Automatic Duplication** - Creates multiple frame instances based on your data rows

- 🎨 **Smart Layer Mapping** - Maps spreadsheet columns to Figma layers using `#` prefix

- 🧩 **Component Variables** - Swap component variants using spreadsheet data

- 📝 **Text & Content Updates** - Automatically updates text, images, colors, and more

- 📐 **Flexible Positioning** - Choose between diagonal or horizontal frame arrangement

- 🏷️ **Auto-Renaming** - Frames are automatically renamed with sequence numbers

## Quick Start

1. **Prepare your spreadsheet** with headers in the first row

2. **Name your Figma layers** with `#` prefix matching column names

3. **Select your frame** containing those layers

4. **Upload your file** - the plugin does the rest automatically!

## Comprehensive Tutorial

### Step 1: Prepare Your Spreadsheet

Create a CSV or XLSX file with your data. The first row should contain column headers that will map to your Figma layers.

**Example spreadsheet structure:**

| Title | Description | Image | State |

|-------|-------------|-------|-------|

| Product A | Great product | https://example.com/image1.jpg | Primary |

| Product B | Another product | https://example.com/image2.jpg | Secondary |

| Product C | Best product | https://example.com/image3.jpg | Primary |

### Step 2: Set Up Your Figma Layers

In your Figma file, name layers that should receive data with a `#` prefix matching your column headers:

- `#Title` → maps to "Title" column

- `#Description` → maps to "Description" column

- `#Image` → maps to "Image" column

- `#State` → maps to "State" column (for component variables)

**Important:** The layer name (without `#`) must exactly match the column header in your spreadsheet.

### Step 3: Component Variables

To change component variants using spreadsheet data:

1. **Name the component instance** with `#` prefix (e.g., `#Button`)

2. **In your spreadsheet**, use the format: `Property Name=Variable Name`

- Example: `State=Primary` or `Size=Large`

3. The plugin will automatically swap the component variant based on the data

**Example:**

- Component instance named: `#Button`

- Spreadsheet column: `State` with values like `Primary`, `Secondary`

- Result: Component variants are swapped automatically

### Step 4: Select and Upload

1. **Select the frame or group** containing your `#`-prefixed layers

2. **Open the plugin** in Figma

3. **Click "Choose File"** and select your CSV/XLSX file

4. The plugin will automatically:

- Duplicate your frame for each data row

- Populate all layers with corresponding data

- Rename frames with sequence numbers

### Step 5: Frame Renaming

Frames are automatically renamed based on these rules:

**If frame name starts with `#`:**

- The plugin cross-references with your spreadsheet

- Renames to: `[Value from Spreadsheet] - [N]`

- Example: Frame `#Product` → `Product A - 1`, `Product B - 2`

**If frame name does NOT start with `#`:**

- Keeps the original name

- Adds sequence number: `[Original Name] - [N]`

- Example: Frame `Card` → `Card - 1`, `Card - 2`

### Step 6: Positioning Options

Choose how duplicated frames are positioned:

- **Diagonal (Default)**: Frames are offset diagonally (20px x, 20px y)

- **Horizontal**: Frames are arranged horizontally with spacing = frame width + 50px

Toggle the checkbox in the plugin UI to switch between modes.

## Supported Data Types

The plugin intelligently handles different data formats:

- **Text**: Plain text values update text layers

- **Images**: URLs automatically load images into image layers

- **Colors**: Use format `/#RRGGBB` or `/#RRGGBBAA` for fill colors

- **Strokes**: Use format `/N|#RRGGBB` where N is stroke weight

- **Visibility**: Use `/show` or `/hide` to toggle layer visibility

- **Component Variables**: Use `Property=Value` format

## Processing Order

The plugin processes changes in a specific order to ensure accuracy:

1. **Component Variables** - Swapped first

2. **Text Layers** - Updated after variables (including text inside swapped components)

3. **Other Layers** - Colors, images, visibility, etc.

This ensures that text inside component instances is properly updated after variant swaps.

## Tips & Best Practices

- ✅ Use descriptive column headers that match your layer names

- ✅ Keep your spreadsheet organized with consistent data types

- ✅ Test with a small dataset first (2-3 rows) before processing large files

- ✅ Ensure image URLs are publicly accessible

- ✅ Use component variables for dynamic UI states

- ✅ Frame names starting with `#` will be renamed from spreadsheet data