{"id":15485,"library":"style-dictionary","title":"Style Dictionary","description":"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.","status":"active","version":"5.4.0","language":"javascript","source_language":"en","source_url":"git://github.com/style-dictionary/style-dictionary","tags":["javascript","style dictionary","style","dictionary","css","design","tokens","sass","scss"],"install":[{"cmd":"npm install style-dictionary","lang":"bash","label":"npm"},{"cmd":"yarn add style-dictionary","lang":"bash","label":"yarn"},{"cmd":"pnpm add style-dictionary","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const StyleDictionary = require('style-dictionary');","symbol":"StyleDictionary","correct":"import StyleDictionary from 'style-dictionary';"},{"note":"Custom transforms, formats, and other hooks are registered directly on the `StyleDictionary` instance or the exported default, not as named exports.","wrong":"import { registerTransform } from 'style-dictionary';","symbol":"registerTransform, registerFormat, registerFilter","correct":"import StyleDictionary from 'style-dictionary'; StyleDictionary.registerTransform(...);"},{"note":"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.","wrong":"import type { Config } from 'style-dictionary';","symbol":"Config, DesignTokens, Transform","correct":"import type { Config, DesignTokens, Transform } from 'style-dictionary/types';"}],"quickstart":{"code":"import StyleDictionary from 'style-dictionary';\nimport fs from 'fs';\nimport path from 'path';\n\n// 1. Define your design tokens (e.g., in tokens/colors.json)\nconst tokens = {\n  \"color\": {\n    \"brand\": {\n      \"primary\": { \"value\": \"#007bff\" },\n      \"secondary\": { \"value\": \"#6c757d\" }\n    }\n  },\n  \"size\": {\n    \"font\": {\n      \"base\": { \"value\": \"16px\" },\n      \"large\": { \"value\": \"24px\" }\n    }\n  }\n};\n\n// Create a tokens directory and write the tokens file if it doesn't exist\nconst tokensDir = path.resolve(process.cwd(), 'tokens');\nconst tokensFilePath = path.join(tokensDir, 'colors.json');\nif (!fs.existsSync(tokensDir)) {\n  fs.mkdirSync(tokensDir, { recursive: true });\n}\nfs.writeFileSync(tokensFilePath, JSON.stringify(tokens, null, 2));\n\n// 2. Define your Style Dictionary configuration\nconst config = {\n  source: ['tokens/**/*.json'],\n  platforms: {\n    css: {\n      transformGroup: 'css',\n      buildPath: 'build/',\n      files: [\n        {\n          destination: '_variables.css',\n          format: 'css/variables'\n        }\n      ]\n    },\n    js: {\n      transformGroup: 'js/es6',\n      buildPath: 'build/',\n      files: [\n        {\n          destination: 'tokens.js',\n          format: 'javascript/es6'\n        }\n      ]\n    }\n  }\n};\n\n// Create a build directory if it doesn't exist\nconst outputDir = path.resolve(process.cwd(), 'build');\nif (!fs.existsSync(outputDir)) {\n  fs.mkdirSync(outputDir, { recursive: true });\n}\n\n// 3. Extend Style Dictionary and build all platforms\nasync function buildTokens() {\n  // StyleDictionary.extend is now asynchronous since v4\n  const sd = await StyleDictionary.extend(config);\n  sd.buildAllPlatforms();\n  console.log('Style Dictionary build completed successfully!');\n\n  // To clean generated files:\n  // sd.cleanAllPlatforms();\n}\n\nbuildTokens().catch(err => {\n  console.error('Style Dictionary build failed:', err);\n  process.exit(1);\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"Style 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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"As 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"References 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"Style 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.","severity":"gotcha","affected_versions":">=5.3.0"},{"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.","message":"Older 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.","severity":"gotcha","affected_versions":">=5.0.0 <5.0.4"},{"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.","message":"A 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.","severity":"gotcha","affected_versions":">=5.1.0 <5.1.4"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`.","cause":"The installed Node.js version does not meet Style Dictionary's minimum requirement.","error":"Error: Node.js version x.y.z is not supported. Required: >=22.0.0."},{"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;`.","cause":"Attempting to use ES module `import` syntax in a CommonJS context without proper configuration.","error":"TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension \".js\" for /path/to/build.js"},{"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.","cause":"Design tokens are referencing non-existent paths, tokens that have been filtered out, or incorrectly structured values.","error":"Reference Errors: Some token references (X) could not be found."},{"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.","cause":"Attempting to call `StyleDictionary.extend` on an already instantiated object, or using an incorrect import/instantiation pattern from v3 to v4/v5.","error":"StyleDictionary.extend is not a function"}],"ecosystem":"npm"}