Spaces:

riazmo
/

Design-System-Automation

Runtime error

App Files Files Community

Design-System-Automation / figma-plugin /README.md

riazmo

feat: move Figma plugin to figma-plugin/ with proper README

d969659 19 days ago

preview code

raw

history blame contribute delete

8.32 kB

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.

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

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

3. Run it

Open any Figma file (or create a new one)
Go to Plugins > Development > Design System Automation — Token Importer
Upload your JSON file or paste JSON directly
Click "Apply to Document"
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)

Go to the Design System Automation app
Enter any website URL
Click Extract — the app analyzes the site and extracts all design tokens
Download the AS-IS JSON (W3C DTCG format)
Upload it to this plugin

Option B: Create JSON Manually

The plugin accepts two formats:

W3C DTCG Format (recommended — output from the app):

{
  "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):

{
  "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:

Extract AS-IS — Run the app on a website, download JSON, import to Figma
Review — See the current state of the design system as a visual spec
AI Analysis — The app's 4 AI agents analyze and suggest improvements
Accept/Reject — Choose which suggestions to keep
Export TO-BE — Download the improved JSON, import to Figma
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
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 — an open-source tool that extracts, analyzes, and improves design systems from any live website.