Spreadsheet Sync

About this plugin

# Spreadsheet Sync (Figma Plugin)

Populate and duplicate Figma frames from a local `CSV` or `XLSX` file.

The plugin reads your spreadsheet rows, duplicates selected parent frames, and updates layers named with `#` to match your columns.

## Brief Description

- Input: local `CSV` or `XLSX` file

- Mapping: layer names starting with `#` (example: `#Title`, `#Image`)

- Output: one duplicate per data row (for each selected parent frame)

- Supports:

- text content

- images

- fill/stroke colors

- show/hide

- variant swaps

- random row selectors

## Full Tutorial

1. Prepare your file

- Row 1 must be headers.

- Each next row is one data record.

- Save as `.csv` or `.xlsx`.

2. Prepare your Figma frame/component

- Create a parent frame/group you want to duplicate.

- Name child layers with `#` + column name.

- Examples:

- `#Question`

- `#Option A`

- `#Image`

- `#Auto`

3. Optional suffix rules on layer names

- `#Column.3` -> always use row 3 (1-based index)

- `#Column.rand` -> random row each duplicate

- `#Column.randsave` -> one random row chosen per run and reused

4. Optional text placeholder mode

- If a text layer already contains placeholders like `{name}`, they will be replaced with that layer's mapped value.

- Placeholders in LaTeX/math contexts are ignored (for example `^{3}` stays unchanged).

5. Select parent frame(s) in Figma

- Select one or more parent layers (frames/groups/components containing `#...` children).

- Important: total output count = `data rows x selected parent layers`.

6. Open plugin and choose positioning

- Default: Diagonal

- Optional: check `Horizontal` for side-by-side placement

7. Upload file

- Click `Choose File`, select your `CSV/XLSX`.

- Plugin duplicates and fills data automatically.

8. Result behavior

- Duplicates are created and renamed with sequence numbers.

- Original selected parent layers are removed after sync.

- A completion notification shows success/error counts.

## Changeable Variables And Directives

### 1) Layer name variables

Use `#` prefix in layer names:

- `#ColumnName` -> value from same row and matching column

- `#ColumnName.N` -> fixed row `N`

- `#ColumnName.rand` -> random row

- `#ColumnName.randsave` -> stable random row for current run

### 2) Cell value commands

Put these in spreadsheet cells:

- Plain text: updates text nodes

- Example: `Hello world`

- Fill color:

- Format: `/#HEX`

- Example: `/#FFAA00`, `/#F80`, `/#FFAA00CC`

- Stroke color (+ optional width):

- Format: `/WIDTH|#HEX`

- Example: `/2|#222222`

- Visibility:

- `/show`

- `/hide`

- Image:

- any URL starting with `http://` or `https://`

- Variant swap (instance):

- Format: `Property=Value`

- Example: `Type=Primary`

## Example Table

Use this as a starter (`CSV` style shown as markdown table):

| Title | Equation | Subtitle | Accent | Border | Visible | Image | Card Variant |

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

| Welcome | $-a^{3}$ | First card | /#5BA551 | /2\|#111111 | /show | https://picsum.photos/400/240 | Type=Primary |

| Welcome | $-a^{3}$ | Second card | /#18A0FB | /1\|#333333 | /hide | https://picsum.photos/401/240 | Type=Secondary |

### Copy-Ready Example CSV

Use the copy icon on this code block:

```csv

Title,Equation,Subtitle,Accent,Border,Visible,Image,Card Variant

"Welcome","$-a^{3}$","First card","/#5BA551","/2|#111111","/show","https://picsum.photos/400/240","Type=Primary"

"Welcome","$-a^{3}$","Second card","/#18A0FB","/1|#333333","/hide","https://picsum.photos/401/240","Type=Secondary"

```

Matching Figma layer names for that table:

- `#Title`

- `#Equation`

- `#Subtitle`

- `#Accent`

- `#Border`

- `#Visible`

- `#Image`

- `#Card Variant`

## Notes

- The plugin currently uses local file upload (not direct Google Sheets URL fetch).

- Sync safety guard exists to block crash-scale runs when generated frame count is too high.