figma-plugin/README.md

# Design System Automation — Figma Plugin

Import design tokens into Figma and auto-generate a visual spec page. Works with W3C DTCG format (from the Design System Automation app) and legacy JSON formats.

![Figma Plugin](https://img.shields.io/badge/Figma-Plugin-ff7262) ![Version](https://img.shields.io/badge/version-7.0-blue) ![License](https://img.shields.io/badge/license-MIT-green)

---

## What It Does

Upload a JSON file with your design tokens. The plugin creates:

- **Figma Variables** — Color, number, and string variable collections
- **Paint Styles** — Every color as a reusable Figma paint style
- **Text Styles** — Typography with font family, size, weight, and line height
- **Effect Styles** — Shadows as Figma effect styles
- **Visual Spec Page** — Auto-generated frames showing all your tokens organized by category, with AA compliance badges on every color

The plugin auto-detects whether your JSON uses the **W3C DTCG format** (`$value`, `$type`) or a **legacy format** (`value`, `type`) and handles both.

---

## Quick Setup (5 Minutes)

### 1. Download the plugin

Clone this repo or download just the `figma-plugin/` folder. You need these three files:

```
figma-plugin/
  manifest.json
  src/code.js
  ui/ui.html
```

### 2. Load into Figma

1. Open **Figma** (desktop app)
2. Go to **Plugins** > **Development** > **Import plugin from manifest...**
3. Select the `manifest.json` file from this folder
4. Done — the plugin is now available under **Plugins > Development**

### 3. Run it

1. Open any Figma file (or create a new one)
2. Go to **Plugins** > **Development** > **Design System Automation — Token Importer**
3. Upload your JSON file or paste JSON directly
4. Click **"Apply to Document"**
5. Check the **Assets** panel — all your styles and variables are created

---

## How to Get Your Token JSON

### Option A: Use the Design System Automation App (Recommended)

1. Go to the [Design System Automation app](https://huggingface.co/spaces/riazmo/Design-System-Automation)
2. Enter any website URL
3. Click Extract — the app analyzes the site and extracts all design tokens
4. Download the **AS-IS JSON** (W3C DTCG format)
5. Upload it to this plugin

### Option B: Create JSON Manually

The plugin accepts two formats:

**W3C DTCG Format** (recommended — output from the app):
```json
{
  "color": {
    "brand": {
      "primary": {
        "$type": "color",
        "$value": "#0066ff",
        "$description": "Primary brand color"
      }
    },
    "text": {
      "primary": {
        "$type": "color",
        "$value": "#1a1a1a"
      }
    }
  },
  "font": {
    "heading": {
      "lg": {
        "$type": "typography",
        "$value": {
          "fontFamily": "Inter",
          "fontSize": "32px",
          "fontWeight": "700",
          "lineHeight": "1.3"
        }
      }
    }
  },
  "spacing": {
    "md": {
      "$type": "dimension",
      "$value": "16px"
    }
  },
  "radius": {
    "md": {
      "$type": "dimension",
      "$value": "8px"
    }
  },
  "shadow": {
    "sm": {
      "$type": "shadow",
      "$value": {
        "offsetX": "0px",
        "offsetY": "2px",
        "blur": "8px",
        "spread": "0px",
        "color": "#00000026"
      }
    }
  }
}
```

**Legacy Format** (also supported):
```json
{
  "global": {
    "colors": {
      "primary": { "value": "#0066ff", "type": "color" },
      "secondary": { "value": "#ff007f", "type": "color" }
    },
    "typography": {
      "heading": {
        "value": {
          "fontFamily": "Inter",
          "fontWeight": "700",
          "fontSize": "32px",
          "lineHeight": "1.3"
        },
        "type": "typography"
      }
    },
    "spacing": {
      "md": { "value": "16px", "type": "spacing" }
    }
  }
}
```

---

## The Visual Spec Page

After importing, the plugin generates a visual spec page with separate frames for each token category:

```
+------------------------------------------------------------------+
| TYPOGRAPHY (Desktop)          TYPOGRAPHY (Mobile)                  |
| H1  48px/Bold  Inter         H1  32px/Bold  Inter                |
| H2  36px/Bold  Inter         H2  28px/Bold  Inter                |
| Body 16px/Regular Inter      Body 14px/Regular Inter             |
+------------------------------------------------------------------+
| COLORS                                                            |
| BRAND         TEXT           BACKGROUND      FEEDBACK             |
| +------+      +------+      +------+        +------+             |
| |Primary|     |Primary|     |Primary|       | Error|             |
| +------+      +------+      +------+        +------+             |
| #0066ff       #1a1a1a       #ffffff         #dc2626              |
| AA:Pass       AA:Pass                       AA:Pass              |
+------------------------------------------------------------------+
| SPACING          RADIUS            SHADOWS                        |
| 4  8  16  24     sm md lg full     xs  sm  md  lg  xl            |
+------------------------------------------------------------------+
```

Every color swatch shows its AA compliance status (Pass/Fail against white and black backgrounds).

---

## AS-IS vs TO-BE Workflow

The full Design System Automation workflow uses this plugin twice:

1. **Extract AS-IS** — Run the app on a website, download JSON, import to Figma
2. **Review** — See the current state of the design system as a visual spec
3. **AI Analysis** — The app's 4 AI agents analyze and suggest improvements
4. **Accept/Reject** — Choose which suggestions to keep
5. **Export TO-BE** — Download the improved JSON, import to Figma
6. **Compare** — Place AS-IS and TO-BE visual specs side by side

This gives you a clear before/after view of every change.

---

## Plugin Features

| Feature | Description |
|---------|-------------|
| DTCG Auto-Detection | Automatically detects W3C DTCG vs legacy JSON format |
| Figma Variables | Creates Color, Number, and String variable collections |
| Paint Styles | Every color token becomes a reusable paint style |
| Text Styles | Typography tokens with font, size, weight, line height |
| Effect Styles | Shadow tokens as Figma drop shadow effects |
| Visual Spec | Auto-generated spec page with organized frames |
| AA Badges | Contrast ratio check on every color swatch |
| File Upload | Upload JSON file or paste directly |
| Token Preview | See all detected tokens before applying |
| Progress Bar | Real-time feedback while creating styles |

---

## Troubleshooting

**Plugin won't load?**
- Make sure you're using the Figma desktop app (not the browser version)
- Check that `manifest.json`, `src/code.js`, and `ui/ui.html` are all present
- Try: Plugins > Development > Import plugin from manifest... and re-select

**Styles not appearing?**
- Open the **Assets** panel (left sidebar) and check under Local styles
- Make sure you clicked "Apply to Document" and waited for the progress bar
- Try refreshing: Cmd+R (Mac) or Ctrl+R (Windows)

**JSON upload fails?**
- Validate your JSON at [jsonlint.com](https://jsonlint.com)
- Check that hex colors use the full 6-digit format: `#0066ff` (not `#06f`)
- Make sure font sizes include units: `"32px"` (not `"32"`)

**Fonts look wrong?**
- Figma needs the font installed on your system or available through Google Fonts
- If a font isn't found, Figma falls back to a default — install the font and re-run

---

## Project Structure

```
figma-plugin/
  manifest.json      # Plugin configuration (name, entry points)
  README.md          # This file
  src/
    code.js          # Main plugin logic (v7, ~1400 lines)
  ui/
    ui.html          # Plugin UI panel
```

---

## Compatibility

- **Figma**: Desktop app (latest version recommended)
- **JSON Formats**: W3C DTCG v1, Tokens Studio, legacy `{value, type}` format
- **Token Types**: Colors, typography, spacing, border radius, shadows
- **Downstream**: Works with tokens exported from Tokens Studio, Style Dictionary, or the Design System Automation app

---

## License

MIT — free to use, modify, and distribute.

---

Built as part of [Design System Automation](https://github.com/hiriazmo/design-system-automation) — an open-source tool that extracts, analyzes, and improves design systems from any live website.