Manage Design Tokens with CSS Variables

Read and write CSS custom properties on the canvas iframe :root to maintain a consistent color, spacing, and typography scale across every component.

Design tokens — shared values for color, spacing, typography, and shadow — are the connective tissue that keeps a design system coherent. In DesignJS, tokens live as CSS custom properties on the canvas iframe’s :root element. The get_variables tool reads the current token map, and set_variables writes or merges new values into it. Changes persist to .designjs.json under cssVariables and are re-applied every time the canvas reloads, so your token definitions survive across sessions and travel with the file in version control.

How tokens work in the canvas

Every CSS custom property you define on :root is available to any component on the canvas via var(--token-name). Because the canvas iframe runs Tailwind v4, you can also reference tokens inside arbitrary Tailwind values: bg-[var(--brand-primary)] or text-[var(--text-muted)] resolve at render time.

The full token lifecycle:

set_variables called
      │
      ▼
:root { --brand-primary: #6366f1; } injected into iframe
      │
      ▼
All components using var(--brand-primary) update immediately
      │
      ▼
Persisted to .designjs.json → cssVariables
      │
      ▼
Re-applied on next canvas load

---

Read the current token map

Before adding or changing tokens, read what’s already defined:

// Tool call
{
  "tool": "get_variables",
  "params": {}
}

// Response
{
  "variables": {
    "--brand-primary": "oklch(0.55 0.2 260)",
    "--brand-secondary": "oklch(0.65 0.15 200)",
    "--text-base": "oklch(0.15 0.01 260)",
    "--text-muted": "oklch(0.5 0.01 260)",
    "--surface-1": "oklch(1 0 0)",
    "--surface-2": "oklch(0.97 0.005 260)",
    "--radius-sm": "0.375rem",
    "--radius-md": "0.5rem",
    "--radius-lg": "0.75rem",
    "--space-4": "1rem",
    "--space-6": "1.5rem",
    "--space-8": "2rem"
  }
}

The response is a flat Record<string, string> — every key is a CSS custom property name (including the -- prefix) and every value is the raw CSS value string.

If the canvas has no variables set yet, get_variables returns an empty object {}. You’re starting with a clean slate.

---

Write or update tokens

set_variables merges the variables you provide into the existing set. Existing keys are overwritten; keys you don’t mention are preserved:

// Tool call — update the brand color and add a new shadow token
{
  "tool": "set_variables",
  "params": {
    "variables": {
      "--brand-primary": "#6366f1",
      "--brand-primary-hover": "#4f46e5",
      "--shadow-card": "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)"
    }
  }
}

// Response — full updated map
{
  "variables": {
    "--brand-primary": "#6366f1",
    "--brand-primary-hover": "#4f46e5",
    "--brand-secondary": "oklch(0.65 0.15 200)",
    "--text-base": "oklch(0.15 0.01 260)",
    "--text-muted": "oklch(0.5 0.01 260)",
    "--surface-1": "oklch(1 0 0)",
    "--surface-2": "oklch(0.97 0.005 260)",
    "--radius-sm": "0.375rem",
    "--radius-md": "0.5rem",
    "--radius-lg": "0.75rem",
    "--space-4": "1rem",
    "--space-6": "1.5rem",
    "--space-8": "2rem",
    "--shadow-card": "0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)"
  }
}

The response always returns the full updated map, so you can verify what’s in effect after the call.

There is no delete_variables tool. To remove a token, you currently need to edit .designjs.json directly and reload the canvas. Alternatively, set the variable to unset or an empty string to neutralize its effect in components.

---

Complete workflow: rebrand a design

This example shows a full token-driven rebrand — switching a design from an indigo palette to a violet one without touching any individual component.

1. Read the current token map

   {
     "tool": "get_variables",
     "params": {}
   }
   
   // Response
   {
     "variables": {
       "--brand-primary": "oklch(0.55 0.2 260)",
       "--brand-primary-hover": "oklch(0.50 0.22 260)",
       "--brand-accent": "oklch(0.70 0.18 260)",
       "--text-base": "oklch(0.15 0.01 260)",
       "--text-muted": "oklch(0.5 0.01 260)",
       "--surface-1": "oklch(1 0 0)",
       "--surface-2": "oklch(0.97 0.005 260)"
     }
   }
   

   Hue 260 in oklch is indigo. To shift to violet, move the hue to 290.

2. Apply the new brand palette

   {
     "tool": "set_variables",
     "params": {
       "variables": {
         "--brand-primary": "oklch(0.55 0.2 290)",
         "--brand-primary-hover": "oklch(0.50 0.22 290)",
         "--brand-accent": "oklch(0.70 0.18 290)"
       }
     }
   }
   

   Every component that references var(--brand-primary) updates immediately in the canvas iframe.

3. Verify visually with a screenshot

   {
     "tool": "get_screenshot",
     "params": {
       "scale": 2,
       "format": "png"
     }
   }
   

   If the rebrand looks correct, press Cmd+S to persist the new token values to .designjs.json.

---

Referencing tokens in components

There are two ways to use a token in a canvas component:

1. Direct CSS custom property reference

Pass the var() expression as a CSS value in update_styles:

{
  "tool": "update_styles",
  "params": {
    "componentId": "comp-btn-primary",
    "styles": {
      "background-color": "var(--brand-primary)",
      "border-radius": "var(--radius-md)"
    }
  }
}

2. Tailwind arbitrary value syntax

Because the canvas iframe runs Tailwind v4, you can use var() inside arbitrary value brackets in the HTML you pass to add_components:

{
  "tool": "add_components",
  "params": {
    "html": "<button class=\"bg-[var(--brand-primary)] hover:bg-[var(--brand-primary-hover)] text-[var(--text-base)] rounded-[var(--radius-md)] px-6 py-3 font-semibold\">Subscribe</button>"
  }
}

This keeps your HTML declarative and means a single set_variables call repaints every element that uses the token.

---

Token naming conventions

Consistent naming makes tokens easier to use across components and easier to reference in agent prompts. A recommended pattern:

--{category}-{variant}

Category	Example names
Brand colors	--brand-primary, --brand-secondary, --brand-accent
Text	--text-base, --text-muted, --text-inverse
Surface	--surface-1, --surface-2, --surface-overlay
Border	--border-subtle, --border-strong
Radius	--radius-sm, --radius-md, --radius-lg, --radius-full
Spacing	--space-2, --space-4, --space-6, --space-8
Shadow	--shadow-sm, --shadow-card, --shadow-modal

When prompting an agent to add components, mention tokens by name: “Use var(--brand-primary) for the button background.” The agent will use the token reference rather than hard-coding a hex value, so the component automatically participates in any future rebrands.

---

About oklch values

The canvas uses oklch as its preferred color format. oklch is perceptually uniform — equal changes in lightness or chroma look visually equal across the spectrum — which makes it well-suited for generating palette variants programmatically.

The format is oklch(lightness chroma hue):

Parameter	Range	Effect
lightness	0 to 1	0 = black, 1 = white
chroma	0 to ~0.4	0 = grey, higher = more saturated
hue	0 to 360	Color angle: 0 red, 120 green, 260 indigo, 290 violet

To generate a full tonal scale for a brand color, vary lightness while holding chroma and hue constant:

{
  "tool": "set_variables",
  "params": {
    "variables": {
      "--brand-50":  "oklch(0.97 0.04 260)",
      "--brand-100": "oklch(0.93 0.07 260)",
      "--brand-200": "oklch(0.85 0.10 260)",
      "--brand-300": "oklch(0.75 0.14 260)",
      "--brand-400": "oklch(0.65 0.17 260)",
      "--brand-500": "oklch(0.55 0.20 260)",
      "--brand-600": "oklch(0.47 0.22 260)",
      "--brand-700": "oklch(0.40 0.22 260)",
      "--brand-800": "oklch(0.32 0.18 260)",
      "--brand-900": "oklch(0.22 0.12 260)",
      "--brand-950": "oklch(0.14 0.07 260)"
    }
  }
}

---

Persistence and version control

Token values are stored under cssVariables in .designjs.json:

{
  "cssVariables": {
    "--brand-primary": "oklch(0.55 0.2 260)",
    "--text-base": "oklch(0.15 0.01 260)",
    "--surface-1": "oklch(1 0 0)",
    "--radius-md": "0.5rem"
  },
  "components": [...]
}

Because .designjs.json is plain JSON, token changes produce clean, readable git diffs — the exact keys that changed are visible line by line. This makes design-token changes reviewable in a pull request alongside the component changes that use them.

---

Next steps

Design with an agent

Use tokens in a full agent-driven design session — add components that reference your token names from the start.

Export to React

Export canvas components to .tsx files. Tailwind arbitrary values using var() tokens carry over directly.