Registry / devops / style-dictionary

style-dictionary

library5.4.0jsnpmunverified

Style Dictionary is a powerful build system for creating and managing design tokens across multiple platforms and technologies. It allows developers and designers to define styles once using a single source of truth, typically JSON-based design tokens, and then automatically generate platform-specific assets such as CSS variables, Sass maps, iOS `.h`/`.m` files, Android XML resources, and JavaScript objects. The current stable version is 5.4.0, with frequent patch and minor releases, often adding support for the latest Design Token Community Group (DTCG) specification drafts. Its key differentiator is its highly configurable transformation and formatting pipeline, enabling extensive customization for diverse output requirements across web, iOS, and Android ecosystems. It's designed to streamline design system implementation by ensuring consistency and reducing manual synchronization efforts, thereby solving errors, roadblocks, and workflow inefficiencies.

devops

npm install style-dictionary

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · STYLE-DICTIONARY

style-dictionary

devopsjavascriptv5.4.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

StyleDictionary

✓ import StyleDictionary from 'style-dictionary';

✗ const StyleDictionary = require('style-dictionary');

Since v4, Style Dictionary has been rewritten in ES Modules. While dynamic `import()` is possible in CJS, direct `require()` is not supported. Node.js >=22.0.0 is required.

registerTransform, registerFormat, registerFilter

✓ import StyleDictionary from 'style-dictionary'; StyleDictionary.registerTransform(...);

✗ import { registerTransform } from 'style-dictionary';

Custom transforms, formats, and other hooks are registered directly on the `StyleDictionary` instance or the exported default, not as named exports.

Config, DesignTokens, Transform

✓ import type { Config, DesignTokens, Transform } from 'style-dictionary/types';

✗ import type { Config } from 'style-dictionary';

Standalone type interfaces for configuration, design tokens, and other extensibility points are available from the `style-dictionary/types` entrypoint since v4, offering better type safety.

This quickstart demonstrates how to programmatically define design tokens, configure Style Dictionary, and build platform-specific output files like CSS variables and ES Modules JavaScript. It highlights the asynchronous nature of `extend` and `build` methods introduced in v4.

import StyleDictionary from 'style-dictionary'; import fs from 'fs'; import path from 'path'; // 1. Define your design tokens (e.g., in tokens/colors.json) const tokens = { "color": { "brand": { "primary": { "value": "#007bff" }, "secondary": { "value": "#6c757d" } } }, "size": { "font": { "base": { "value": "16px" }, "large": { "value": "24px" } } } }; // Create a tokens directory and write the tokens file if it doesn't exist const tokensDir = path.resolve(process.cwd(), 'tokens'); const tokensFilePath = path.join(tokensDir, 'colors.json'); if (!fs.existsSync(tokensDir)) { fs.mkdirSync(tokensDir, { recursive: true }); } fs.writeFileSync(tokensFilePath, JSON.stringify(tokens, null, 2)); // 2. Define your Style Dictionary configuration const config = { source: ['tokens/**/*.json'], platforms: { css: { transformGroup: 'css', buildPath: 'build/', files: [ { destination: '_variables.css', format: 'css/variables' } ] }, js: { transformGroup: 'js/es6', buildPath: 'build/', files: [ { destination: 'tokens.js', format: 'javascript/es6' } ] } } }; // Create a build directory if it doesn't exist const outputDir = path.resolve(process.cwd(), 'build'); if (!fs.existsSync(outputDir)) { fs.mkdirSync(outputDir, { recursive: true }); } // 3. Extend Style Dictionary and build all platforms async function buildTokens() { // StyleDictionary.extend is now asynchronous since v4 const sd = await StyleDictionary.extend(config); sd.buildAllPlatforms(); console.log('Style Dictionary build completed successfully!'); // To clean generated files: // sd.cleanAllPlatforms(); } buildTokens().catch(err => { console.error('Style Dictionary build failed:', err); process.exit(1); });

style-dictionary --version

Debug

Known issues

breakingStyle Dictionary v4 introduced significant breaking changes, including a complete rewrite to ES Modules, making `StyleDictionary.extend()` and build methods asynchronous, and changes to the API for registering custom transforms and formats. Codemods are available to assist with migration.

fix

Refer to the official v4 migration guide for a comprehensive list of changes. For JavaScript files, convert to ESM or use dynamic imports. Update API calls to `await StyleDictionary.extend(...)` and `await sd.buildAllPlatforms()`. Consider using `npx codemod styledictionary/4/migration-recipe` for automated updates.

affects: >=4.0.0

breakingAs of Style Dictionary v5.0.0, the minimum required Node.js version is 22.0.0. This is primarily to leverage `Set.prototype.union` for performance improvements in token reference resolution.

fix

Ensure your development environment and CI/CD pipelines use Node.js version 22.0.0 or higher. Update your `package.json` engines field accordingly.

affects: >=5.0.0

breakingReferences to non-token leaf nodes or with the `.value` suffix are no longer supported. The reference syntax (e.g., `{ref.foo}`) is now strictly aligned with the DTCG spec and cannot be customized via options.

fix

Ensure token references point directly to design token values and adhere to the DTCG-aligned syntax without custom separators or the `.value` suffix. Review your token definitions for strictness.

affects: >=5.0.0

gotchaStyle Dictionary is actively adopting the Design Token Community Group (DTCG) specification. Recent versions (v5.3.x, v5.4.x) added support for structured color and dimension token formats (DTCG v2025.10). While largely backwards compatible, fully leveraging these new formats might require adjusting existing token definitions or custom transforms.

fix

Review the DTCG specification and Style Dictionary release notes for new token structures. Update your token definitions to use the structured formats where appropriate to benefit from new transforms and improved interoperability. Verify custom transforms handle both legacy string and new object formats if mixed usage is expected.

affects: >=5.3.0

gotchaOlder v5.x versions (pre-5.0.4) had an issue with overly eager token collision warnings. While fixed in 5.0.4, users on earlier patches might encounter excessive warnings for identical token values.

fix

Upgrade to Style Dictionary v5.0.4 or newer to resolve the excessive token collision warnings. Alternatively, you can configure logging to disable warnings if they are not critical (`log.warnings: 'disabled'`) in your configuration.

affects: >=5.0.0 <5.0.4

gotchaA regression bug in `sizeRem` transform could cause errors for NaN values in v5.1.4. Also, issues with `outputReferences` for tokens containing `.value` in their name (pre-v5.1.1) and `fontName` parsing (pre-v5.1.0) have been patched.

fix

Upgrade to the latest patch release of Style Dictionary (v5.4.0 or newer) to ensure these specific bugs are resolved. Verify your token data doesn't contain unexpected `NaN` values for `size` tokens or unusual `fontName` patterns.

affects: >=5.1.0 <5.1.4

Errors

Common errors & fixes

Error: Node.js version x.y.z is not supported. Required: >=22.0.0.

The installed Node.js version does not meet Style Dictionary's minimum requirement.

fix

Upgrade your Node.js installation to version 22.0.0 or newer. Use a tool like `nvm` to manage Node.js versions: `nvm install 22 && nvm use 22`.

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".js" for /path/to/build.js

Attempting to use ES module `import` syntax in a CommonJS context without proper configuration.

fix

Ensure your `package.json` contains `"type": "module"` if you are using `.js` files with `import`/`export`. Alternatively, rename your build script to `build.mjs` or dynamically import Style Dictionary: `const StyleDictionary = (await import('style-dictionary')).default;`.

Reference Errors: Some token references (X) could not be found.

Design tokens are referencing non-existent paths, tokens that have been filtered out, or incorrectly structured values.

fix

Review your token files and configuration. Ensure all references (`{...}`) point to valid, defined design token paths. Check that no filters are inadvertently excluding referenced tokens. Pay close attention to nested namespaces, especially those with special characters or if exporting from tools like Figma Tokens Studio.

StyleDictionary.extend is not a function

Attempting to call `StyleDictionary.extend` on an already instantiated object, or using an incorrect import/instantiation pattern from v3 to v4/v5.

fix

Since v4, `StyleDictionary` is a class. You should use `await StyleDictionary.extend(config)` or `const sd = new StyleDictionary(config); await sd.init();` to create an instance. Ensure `await` is used as `extend` is now asynchronous.

Upgrade

Version history

5.4.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/style-dictionary/style-dictionary ↗

packagehttps://www.npmjs.com/package/style-dictionary ↗

homepagehttps://style-dictionary.readthedocs.io ↗