Colour Design Tokens - One Palette, Every Platform

## Why it matters

Design and engineering drift apart when a colour lives in a Figma file and, separately, in CSS, and again in Swift. A token makes the palette the single source: change the JSON, rebuild, and web, iOS and Android update together.

Without tokens, rebranding means chasing the same hex code across three codebases and almost always missing one. With tokens, the Figma team updates one JSON file and a build step (like Style Dictionary) generates the CSS variables, the Swift constants, and the Android resources in one pass.

## How it works

A design token is a JSON object with a name, a value, and metadata. The simplest shape is:

{
  "color": {
    "brand": {
      "primary": {
        "$value": "#38bdf8",
        "$type": "color",
        "description": "Primary brand blue"
      }
    }
  }
}
Copy

A build tool (like Style Dictionary) reads this JSON and outputs platform-specific code:

• CSS: --color-brand-primary: #38bdf8; (or --color-brand-primary: rgb(56, 189, 248);)
• Swift: static let colorBrandPrimary = UIColor(red: 0.22, green: 0.74, blue: 0.98, alpha: 1)
• Kotlin: @ColorInt val colorBrandPrimary: Int = 0xff38bdf8

The W3C Design Tokens format standardises the shape so different tools can read and write the same JSON without conversion. The $type field signals that this is a colour token; other types include typography, sizing, and spacing. The $value is the actual colour, and any extra keys like description are metadata for teams.

Semantic tokens layer on top of primitive ones. A primitive token is a raw value like color.red.500. A semantic token uses that primitive: color.feedback.error: { $value: "{color.red.500}" }. Now if error changes from red to orange, you update one line.

## What does not matter

Not all teams need tokens. If your product is web-only and you are using CSS custom properties already, you may not need the JSON layer; the CSS variables are enough. Tokens shine when you have multiple platforms or when you want to version and audit palette changes.

## Code example

A token file suitable for Style Dictionary:

{
  "color": {
    "primitive": {
      "blue": {
        "500": {
          "$value": "#38bdf8",
          "$type": "color",
          "description": "Light blue"
        },
        "700": {
          "$value": "#0369a1",
          "$type": "color",
          "description": "Medium blue"
        }
      }
    },
    "semantic": {
      "feedback": {
        "success": {
          "$value": "{color.primitive.blue.500}",
          "$type": "color",
          "description": "Positive feedback or valid state"
        },
        "error": {
          "$value": "#dc2626",
          "$type": "color",
          "description": "Error or invalid state"
        }
      }
    }
  }
}
Copy

This generates CSS like:

:root {
  --color-primitive-blue-500: #38bdf8;
  --color-primitive-blue-700: #0369a1;
  --color-semantic-feedback-success: #38bdf8;
  --color-semantic-feedback-error: #dc2626;
}
Copy

Wrong – no tokens, colours scattered:

// Web: hardcoded hex
const buttonColor = "#38bdf8";

// Swift: magic number
let buttonColor = UIColor(red: 0.22, green: 0.74, blue: 0.98, alpha: 1)

// Kotlin: hex literal
const val buttonColor = 0xff38bdf8

// Later, design changes the blue. You update 1 out of 3. Drift.
Copy

## How Scalpel Color shows it

The Palette tab has a "JSON" export button. Select it to download a JSON file with your scanned palette, each colour as a token with its name and its value in hex, RGB, HSL, and OKLCH. The format matches the W3C Design Tokens spec so you can feed it directly into Style Dictionary or any other compatible tool. Paste the tokens into your design-tokens repo, run your build, and the CSS, Swift and Kotlin code regenerates automatically.