Style Dictionary

What it does

• stoaken export writes the live release as JSON that Style Dictionary reads as its source: json-dtcg (W3C 2025.10) for Style Dictionary v5, or json-sd4 (hex colours, "16px", "200ms") for v4.
• Your Style Dictionary config decides the platforms and formats. Stoaken doesn't run the build.
• Aliases are resolved and each mode is its own file, so every build gets plain values.

Before you start

• Node and style-dictionary in the project (npm install -D style-dictionary).
• A Stoaken API key and a stoaken.config.json from npx stoaken init (see /docs/cli).

Setup

1. Add one saved target per mode. Mode names are your Brand's own (axis:mode); see /docs/exports.

{
  "brandId": "…",
  "brandName": "Acme",
  "serverUrl": "https://www.stoaken.com",
  "exports": [
    { "theme": "Default", "format": "json-dtcg", "mode": "scheme:light", "out": "tokens/light.json" },
    { "theme": "Default", "format": "json-dtcg", "mode": "scheme:dark", "out": "tokens/dark.json" }
  ]
}

2. Run npx stoaken export, then point Style Dictionary at one mode:

{
  "source": ["tokens/light.json"],
  "platforms": {
    "css": {
      "transformGroup": "css",
      "buildPath": "build/css/",
      "files": [{ "destination": "variables.css", "format": "css/variables" }]
    },
    "scss": {
      "transformGroup": "scss",
      "buildPath": "build/scss/",
      "files": [{ "destination": "_variables.scss", "format": "scss/variables" }]
    },
    "js": {
      "transformGroup": "js",
      "buildPath": "build/js/",
      "files": [{ "destination": "tokens.js", "format": "javascript/es6" }]
    }
  }
}

3. Build with npx style-dictionary build --config config.json. From Stoaken's sample theme (Style Dictionary 5.7.1):

:root {
  …
  --color-brand-primary: #007c2b; /** Primary actions: the one button that moves things forward. */
  …
  --spacing-md: 8px;
  …
  --button-primary-background: #007c2b;
  …
}

export const ColorBrandPrimary = "#007c2b"; // Primary actions: the one button that moves things forward.
…
export const SpacingMd = "8px";

4. In CI, run npx stoaken export --check before the build, so it never builds old tokens.

Configuration

• Style Dictionary v4: use "format": "json-sd4" in the saved targets. Nothing else changes.
• Dark mode: build each mode with its own selector. This script writes build/css/light.css and build/css/dark.css:

import StyleDictionary from 'style-dictionary'

const modes = { light: ':root', dark: '[data-scheme="dark"]' }

for (const [mode, selector] of Object.entries(modes)) {
  const sd = new StyleDictionary({
    source: [`tokens/${mode}.json`],
    platforms: {
      css: {
        transformGroup: 'css',
        buildPath: 'build/css/',
        files: [{ destination: `${mode}.css`, format: 'css/variables', options: { selector } }],
      },
    },
  })
  await sd.buildAllPlatforms()
}

[data-scheme="dark"] {
  …
  --color-brand-primary: #c8bdff; /** Primary actions: the one button that moves things forward. */
  …
}

• JavaScript from W3C JSON: durations and shadow parts come out as objects, like { value: 150, unit: "ms" }. With json-sd4 they're strings ("150ms").
• iOS and Android: use Stoaken's own swift, android and compose exports (/docs/exports). Style Dictionary's built-in ios-swift and android transform groups read sizes as rem, so 8px comes out as 128.00dp.

Try it

1. Run the build and open build/css/variables.css. --color-brand-primary has the live release's value.
2. Publish a change in Stoaken, run npx stoaken export and build again. Only the changed lines differ.

Troubleshooting

• Values from the wrong mode: both mode files are in source. Style Dictionary merges them, and the later file wins. Use one mode per build.
• [object Object] in a native file: that format can't read the value. Use Stoaken's native exports instead.
• stoaken export errors (401, unknown theme or mode) are explained in /docs/cli.

Limits

• References are resolved before export, so outputReferences has no aliases to keep.
• Stoaken's CI builds both JSON formats with Style Dictionary v5 (5.7.1). Style Dictionary v4 itself isn't run in Stoaken's tests.