> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sitecopilot.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Figma Mapping

This page explains how to map Figma variables (the exported tokens) to Sitecopilot theme keys and the Tailwind config structure used by our templates.

## Purpose

Figma tokens names rarely match your runtime CSS variable names or Tailwind keys. A mapping step aligns the exported JSON tokens with the keys expected by `tailwind.config.js` and the Sitecopilot template engine.

## Example token snippet (from design-tokens plugin)

```json theme={null}
{
  "color": {
    "brand": { "value": "#0f172a" },
    "accent": { "value": "#3B82F6" }
  },
  "spacing": {
    "small": { "value": "8" },
    "medium": { "value": "16" }
  }
}
```

## Mapping file (example)

Create a simple mapping JSON that maps Figma token paths to Tailwind theme keys:

```json theme={null}
{
  "color.brand": "colors.brand.DEFAULT",
  "color.accent": "colors.accent.DEFAULT",
  "spacing.small": "spacing.2",
  "spacing.medium": "spacing.4"
}
```

### How to apply the mapping

1. After exporting `tokens.json`, run a small script (node/python) that reads the mapping, transforms token names, and outputs a normalized token JSON consumed by the `generate_tailwindconfig` tool.
2. Regenerate `tailwind.config.js` and inspect the generator report for unresolved names.
3. Iterate: fix Figma variable names if necessary or update the mapping file.

## Recommendations

* Use consistent, kebab-case or dot.notation naming in Figma to simplify mapping.
* Keep the mapping file in the theme repo (`/themes/<theme-name>/mapping.json`) so designers & developers can collaborate.
* Validate the final `tailwind.config.js` by running `npx tailwindcss -i ./src/input.css -o ./dist/output.css --minify` in a local build.