style-dictionary 5.1.4 → 5.3.0

package/examples/advanced/assets-base64-embed/package.json

@@ -12,6 +12,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/create-react-app/package.json

@@ -12,7 +12,7 @@
   },
   "devDependencies": {
     "eslint-config-react-app": "^7.0.1",
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   },
   "resolutions": {
     "immer": "8.0.1",

package/examples/advanced/create-react-native-app/package.json

@@ -29,7 +29,7 @@
     "eslint-config-react-app": "^7.0.1",
     "jest": "~25.2.6",
     "react-test-renderer": "~16.13.1",
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   },
   "jest": {
     "preset": "react-native"

package/examples/advanced/custom-parser/package.json

@@ -10,6 +10,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/custom-transforms/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/font-face-rules/package.json

@@ -9,6 +9,6 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/format-helpers/package.json

@@ -2,6 +2,7 @@
   "name": "format-helpers",
   "version": "1.0.0",
   "description": "",
+  "type": "module",
   "main": "sd.config.js",
   "scripts": {
     "build": "style-dictionary build --config ./sd.config.js"
@@ -10,6 +11,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/matching-build-files/README.md

@@ -18,25 +18,25 @@ At this point, you can run `npm run build`. This command will generate the outpu
 
 The "build" command processes the JSON files in the `tokens` folder. The `index.js` file adds each folder, allowing you to map through them in `config.js`. The script goes through each folder and generates a file for each folder and populates it with tokens that match the filter.
 
-```sh
+```json
 # tokens/color/base.json
 {
-   "color": {
-       "red": {
-            "value": "#FF0000"
-        }
-   }
+  "color": {
+    "red": {
+      "value": "#FF0000"
+    }
+  }
 }
 ```
 
-```sh
+```json
 # tokens/size/base.json
 {
-   "size": {
-       "small": {
-            "value": "2px"
-        }
-   }
+  "size": {
+    "small": {
+      "value": "2px"
+    }
+  }
 }
 ```
 
@@ -46,16 +46,18 @@ Because the folder name matches the category, the output would automatically gen
 
 Open the `config.js` file and see how the script first looks within the `tokens` directory to map through each folder. The destination then outputs a file that would match the name, and fill that file with the tokens that match the filter criteria.
 
-```sh
- files: tokens.map(tokenCategory => ({
-          destination: `${tokenCategory}.js`,
-          format: "format/js",
-          filter: {
-            attributes: {
-              category: tokenCategory
-            }
-          }
-        }))
+```js
+{
+  files: tokens.map((tokenCategory) => ({
+    destination: `${tokenCategory}.js`,
+    format: 'format/js',
+    filter: {
+      attributes: {
+        category: tokenCategory,
+      },
+    },
+  }));
+}
 ```
 
 Now each new folder that gets added will automatically generate a corresponding file filled with tokens that match the category!

package/examples/advanced/matching-build-files/package.json

@@ -17,6 +17,6 @@
   "author": "Kelly Harrop <kn.harrop@gmail.com>",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/matching-build-files/tokens/index.js

@@ -1,4 +1,8 @@
-import { readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
-const dirs = (p) => readdirSync(p).filter((f) => statSync(join(p, f)).isDirectory());
-export default dirs(import.meta.url);
+import { readdirSync } from 'node:fs';
+
+const dirs = (p) =>
+  readdirSync(p, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+
+export default dirs(import.meta.dirname);

package/examples/advanced/multi-brand-multi-platform/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/node-modules-as-config-and-properties/package.json

@@ -20,7 +20,7 @@
   },
   "homepage": "https://github.com/dbanksdesign/style-dictionary-node#readme",
   "devDependencies": {
-    "style-dictionary": "^5.1.4",
+    "style-dictionary": "^5.3.0",
     "tinycolor2": "^1.4.1"
   }
 }

package/examples/advanced/npm-module/package.json

@@ -17,6 +17,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/referencing_aliasing/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/s3/package.json

@@ -16,6 +16,6 @@
   "devDependencies": {
     "aws-sdk": "^2.7.21",
     "fs-extra": "^1.0.0",
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/tailwind-preset/package.json

@@ -10,7 +10,7 @@
   },
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4",
+    "style-dictionary": "^5.3.0",
     "tailwindcss": "^3.4.15",
     "mocha": "^10.2.0",
     "chai": "^5.1.1"

package/examples/advanced/tokens-deprecation/package.json

@@ -16,6 +16,6 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/transitive-transforms/package.json

@@ -12,6 +12,6 @@
   "license": "ISC",
   "devDependencies": {
     "colorjs.io": "^0.5.2",
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/variables-in-outputs/package.json

@@ -11,6 +11,6 @@
   "author": "",
   "license": "MIT",
   "devDependencies": {
-    "style-dictionary": "^5.1.4"
+    "style-dictionary": "^5.3.0"
   }
 }

package/examples/advanced/yaml-tokens/package.json

@@ -10,7 +10,7 @@
   "author": "",
   "license": "Apache-2.0",
   "devDependencies": {
-    "style-dictionary": "^5.1.4",
+    "style-dictionary": "^5.3.0",
     "yaml": "^1.10.0"
   }
 }

package/lib/StyleDictionary.js

@@ -67,7 +67,7 @@ export default class StyleDictionary extends Register {
   // Placeholder is transformed on prepublish -> see scripts/inject-version.js
   // Another option might be import pkg from './package.json' with { "type": "json" } which would work in both browser and node, but support is not there yet.
   // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#browser_compatibility
-  static VERSION = '5.1.4';
+  static VERSION = '5.3.0';
 
   /** @returns {Config} */
   get options() {

package/lib/common/formatHelpers/fileHeader.js

@@ -61,11 +61,15 @@ export default async function fileHeader({ file, commentStyle, formatting = {},
     fn = file.options.fileHeader;
   }
 
-  let { prefix, lineSeparator, header, footer, fileHeaderTimestamp } = Object.assign(
-    {},
-    defaultFormatting,
-    formatting,
-  );
+  let {
+    prefix,
+    lineSeparator,
+    header,
+    commentStyle: _commentStyle,
+    footer,
+    fileHeaderTimestamp,
+  } = Object.assign({}, defaultFormatting, formatting);
+  const commentStyleMerged = commentStyle ?? _commentStyle;
 
   // default header
   const defaultHeader = [
@@ -73,11 +77,11 @@ export default async function fileHeader({ file, commentStyle, formatting = {},
     ...(fileHeaderTimestamp ? [`Generated on ${new Date().toUTCString()}`] : []),
   ];
 
-  if (commentStyle === commentStyles.short) {
+  if (commentStyleMerged === commentStyles.short) {
     prefix = `// `;
     header = `${lineSeparator}`;
     footer = `${lineSeparator}${lineSeparator}`;
-  } else if (commentStyle === 'xml') {
+  } else if (commentStyleMerged === 'xml') {
     prefix = `  `;
     header = `<!--${lineSeparator}`;
     footer = `${lineSeparator}-->`;

package/lib/common/formatHelpers/formattedVariables.d.ts

@@ -11,6 +11,7 @@
  * @param {Formatting} [options.formatting] - Custom formatting properties that define parts of a declaration line in code. This will get passed to `formatHelpers` -> `createPropertyformat` and used for the `lineSeparator` between lines of code.
  * @param {Boolean} [options.themeable] [false] - Whether tokens should default to being themeable.
  * @param {boolean} [options.usesDtcg] [false] - Whether DTCG token syntax should be uses.
+ * @param {SortOption} [options.sort] - Optional sorting strategy.
  * @returns {String}
  * @example
  * ```js
@@ -28,7 +29,7 @@
  * });
  * ```
  */
-export default function formattedVariables({ format, dictionary, outputReferences, outputReferenceFallbacks, formatting, themeable, usesDtcg, }: {
+export default function formattedVariables({ format, dictionary, outputReferences, outputReferenceFallbacks, formatting, themeable, usesDtcg, sort, }: {
     format: string;
     dictionary: Dictionary;
     outputReferences?: import("../../../types/Format.d.ts").OutputReferences | undefined;
@@ -36,9 +37,12 @@ export default function formattedVariables({ format, dictionary, outputReference
     formatting?: import("../../../types/File.d.ts").FormattingOptions | undefined;
     themeable?: boolean | undefined;
     usesDtcg?: boolean | undefined;
+    sort?: import("../../../types/Sort.d.ts").SortOption | undefined;
 }): string;
 export type Token = import("../../../types/DesignToken.d.ts").TransformedToken;
 export type Tokens = import("../../../types/DesignToken.d.ts").TransformedTokens;
 export type Formatting = import("../../../types/File.d.ts").FormattingOptions;
 export type OutputReferences = import("../../../types/Format.d.ts").OutputReferences;
+export type SortFn = import("../../../types/Sort.d.ts").SortFn;
+export type SortOption = import("../../../types/Sort.d.ts").SortOption;
 export type Dictionary = import("../../../types/DesignToken.d.ts").Dictionary;

package/lib/common/formatHelpers/formattedVariables.js

@@ -1,11 +1,14 @@
 import createPropertyFormatter from './createPropertyFormatter.js';
 import sortByReference from './sortByReference.js';
+import sortByName from './sortByName.js';
 
 /**
  * @typedef {import('../../../types/DesignToken.d.ts').TransformedToken} Token
  * @typedef {import('../../../types/DesignToken.d.ts').TransformedTokens} Tokens
  * @typedef {import('../../../types/File.d.ts').FormattingOptions} Formatting
  * @typedef {import('../../../types/Format.d.ts').OutputReferences} OutputReferences
+ * @typedef {import('../../../types/Sort.d.ts').SortFn} SortFn
+ * @typedef {import('../../../types/Sort.d.ts').SortOption} SortOption
  * @typedef {import('../../../types/DesignToken.d.ts').Dictionary} Dictionary
  */
 
@@ -26,6 +29,7 @@ const defaultFormatting = {
  * @param {Formatting} [options.formatting] - Custom formatting properties that define parts of a declaration line in code. This will get passed to `formatHelpers` -> `createPropertyformat` and used for the `lineSeparator` between lines of code.
  * @param {Boolean} [options.themeable] [false] - Whether tokens should default to being themeable.
  * @param {boolean} [options.usesDtcg] [false] - Whether DTCG token syntax should be uses.
+ * @param {SortOption} [options.sort] - Optional sorting strategy.
  * @returns {String}
  * @example
  * ```js
@@ -51,6 +55,7 @@ export default function formattedVariables({
   formatting = {},
   themeable = false,
   usesDtcg = false,
+  sort,
 }) {
   // typecast, we know that by know the tokens have been transformed
   let allTokens = /** @type {Token[]} */ (dictionary.allTokens);
@@ -59,18 +64,62 @@ export default function formattedVariables({
 
   let { lineSeparator } = Object.assign({}, defaultFormatting, formatting);
 
-  // Some languages are imperative, meaning a variable has to be defined
-  // before it is used. If `outputReferences` is true, check if the token
-  // has a reference, and if it does send it to the end of the array.
-  // We also need to account for nested references, a -> b -> c. They
-  // need to be defined in reverse order: c, b, a so that the reference always
-  // comes after the definition
-  if (outputReferences) {
+  const sortInputs = sort ? (Array.isArray(sort) ? sort : [sort]) : [];
+
+  // reference-safety sorter is an internal concern:
+  // we only compute it when outputReferences=true
+  const byReference = outputReferences
+    ? sortByReference(tokens, { unfilteredTokens: dictionary.unfilteredTokens, usesDtcg })
+    : null;
+
+  /**
+   * @param {SortFn} keyOrFn
+   * @returns {((a: Token, b: Token) => number) | null}
+   */
+  const normalize = (keyOrFn) => {
+    if (typeof keyOrFn === 'function') return keyOrFn;
+
+    if (keyOrFn === 'name') return sortByName;
+
+    // Fail loudly for invalid values (esp. typos)
+    if (typeof keyOrFn === 'string') {
+      throw new Error(
+        `Invalid "sort" option: "${keyOrFn}". ` +
+          `Use "name", a comparator function, or an array of those.`,
+      );
+    }
+
+    // Non-string non-function values are also invalid
+    throw new Error(
+      `Invalid "sort" option type: ${typeof keyOrFn}. ` +
+        `Use "name", a comparator function, or an array of those.`,
+    );
+  };
+
+  /**
+   * @param {((a: Token, b: Token) => number) | null} s
+   * @returns {s is ((a: Token, b: Token) => number)}
+   */
+  const isComparator = (s) => s !== null;
+
+  const requestedSorters = sortInputs.map(normalize).filter(isComparator);
+
+  // If outputReferences=true, enforce reference-safe ordering first (define-before-use safety).
+  // The user-provided sort acts as a tie-breaker on top.
+  const comparators = outputReferences
+    ? [byReference, ...requestedSorters].filter(isComparator)
+    : requestedSorters.filter(isComparator);
+
+  if (comparators.length > 0) {
     // note: using the spread operator here so we get a new array rather than
     // mutating the original
-    allTokens = [...allTokens].sort(
-      sortByReference(tokens, { unfilteredTokens: dictionary.unfilteredTokens, usesDtcg }),
-    );
+    allTokens = [...allTokens].sort((a, b) => {
+      for (const cmp of comparators) {
+        const r = cmp(a, b);
+        if (r !== 0) return r;
+      }
+      return 0;
+    });
   }
 
   return allTokens

package/lib/common/formats.js

@@ -193,7 +193,7 @@ const formats = {
       : options.selector
         ? [options.selector]
         : [`:root`];
-    const { outputReferences, outputReferenceFallbacks, usesDtcg, formatting } = options;
+    const { outputReferences, outputReferenceFallbacks, usesDtcg, formatting, sort } = options;
     const header = await fileHeader({
       file,
       formatting: getFormattingCloneWithoutPrefix(formatting),
@@ -219,6 +219,7 @@ const formats = {
         indentation: indentation.repeat(selector.length),
       },
       usesDtcg,
+      sort,
     });
 
     return (
@@ -289,7 +290,7 @@ const formats = {
    */
   [scssMapDeep]: async function ({ dictionary, options, file }) {
     // Default the "themeable" option to true for backward compatibility.
-    const { outputReferences, themeable = true, formatting, usesDtcg } = options;
+    const { outputReferences, themeable = true, formatting, usesDtcg, sort } = options;
     const header = await fileHeader({
       file,
       commentStyle: long,
@@ -306,6 +307,7 @@ const formats = {
         themeable,
         formatting,
         usesDtcg,
+        sort,
       }) +
       '\n' +
       scssMapDeepTemplate({ dictionary, options })
@@ -326,7 +328,7 @@ const formats = {
    * ```
    */
   [scssVariables]: async function ({ dictionary, options, file }) {
-    const { outputReferences, themeable = false, formatting, usesDtcg } = options;
+    const { outputReferences, themeable = false, formatting, usesDtcg, sort } = options;
     const header = await fileHeader({
       file,
       commentStyle: short,
@@ -342,6 +344,7 @@ const formats = {
         themeable,
         formatting,
         usesDtcg,
+        sort,
       }) +
       '\n'
     );
@@ -381,7 +384,7 @@ const formats = {
    * ```
    */
   [lessVariables]: async function ({ dictionary, options, file }) {
-    const { outputReferences, formatting, usesDtcg } = options;
+    const { outputReferences, formatting, usesDtcg, sort } = options;
     const header = await fileHeader({
       file,
       commentStyle: short,
@@ -396,6 +399,7 @@ const formats = {
         outputReferences,
         formatting,
         usesDtcg,
+        sort,
       }) +
       '\n'
     );
@@ -435,7 +439,7 @@ const formats = {
    * ```
    */
   [stylusVariables]: async function ({ dictionary, options, file, platform }) {
-    const { formatting, usesDtcg } = options;
+    const { formatting, usesDtcg, sort } = options;
     const outputReferences = !!platform.options?.outputReferences;
     const header = await fileHeader({
       file,
@@ -451,6 +455,7 @@ const formats = {
         outputReferences,
         formatting,
         usesDtcg,
+        sort,
       }) +
       '\n'
     );

package/lib/common/transforms.d.ts

@@ -1,3 +1,36 @@
+/**
+ * Check if a value is a DTCG color object
+ * @param {unknown} val
+ * @returns {val is DTCGColorValue}
+ */
+export function isDTCGColorObject(val: unknown): val is DTCGColorValue;
+/**
+ * Get color RGB values from either legacy string format or DTCG object format
+ * @param {Token} token
+ * @param {Config} options
+ * @returns {{ r: number, g: number, b: number, a: number }}
+ */
+export function getColorRgb(token: Token, options: Config): {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+/**
+ * Get a tinycolor2 Color instance from either legacy string format or DTCG object format
+ * This provides backward compatibility for transformers that use tinycolor2 methods
+ * @param {Token} token
+ * @param {Config} options
+ * @returns {ReturnType<typeof Color>}
+ */
+export function getColor(token: Token, options: Config): ReturnType<typeof Color>;
+/**
+ * Get a ColorJS Color instance from either legacy string format or DTCG object format
+ * @param {Token} token
+ * @param {Config} options
+ * @returns {ColorJS}
+ */
+export function getColorJS(token: Token, options: Config): ColorJS;
 /**
  * @param {Token} token
  * @param {Config} options
@@ -354,6 +387,78 @@ declare const _default: {
             alpha: number;
         };
     };
+    /**
+     * Transforms the value into an OKLCH CSS color function string.
+     * Preserves wide-gamut colors without lossy gamut mapping.
+     *
+     * ```css
+     * // Matches: token.type === 'color'
+     * // Returns:
+     * "oklch(0.7 0.15 180)"
+     * "oklch(0.7 0.15 180 / 0.5)"
+     * ```
+     *
+     * @memberof Transforms
+     */
+    "color/oklch": {
+        type: "value";
+        filter: typeof isColor;
+        transform: (token: import("../../types/DesignToken.d.ts").TransformedToken, _: import("../../types/Config.d.ts").PlatformConfig, options: import("../../types/Config.d.ts").Config) => string;
+    };
+    /**
+     * Transforms the value into an OKLAB CSS color function string.
+     * Preserves wide-gamut colors without lossy gamut mapping.
+     *
+     * ```css
+     * // Matches: token.type === 'color'
+     * // Returns:
+     * "oklab(0.7 -0.1 0.1)"
+     * "oklab(0.7 -0.1 0.1 / 0.5)"
+     * ```
+     *
+     * @memberof Transforms
+     */
+    "color/oklab": {
+        type: "value";
+        filter: typeof isColor;
+        transform: (token: import("../../types/DesignToken.d.ts").TransformedToken, _: import("../../types/Config.d.ts").PlatformConfig, options: import("../../types/Config.d.ts").Config) => string;
+    };
+    /**
+     * Transforms the value into a Display P3 CSS color function string.
+     * Preserves wide-gamut colors without lossy gamut mapping.
+     *
+     * ```css
+     * // Matches: token.type === 'color'
+     * // Returns:
+     * "color(display-p3 0.5 0.5 0.5)"
+     * "color(display-p3 0.5 0.5 0.5 / 0.5)"
+     * ```
+     *
+     * @memberof Transforms
+     */
+    "color/p3": {
+        type: "value";
+        filter: typeof isColor;
+        transform: (token: import("../../types/DesignToken.d.ts").TransformedToken, _: import("../../types/Config.d.ts").PlatformConfig, options: import("../../types/Config.d.ts").Config) => string;
+    };
+    /**
+     * Transforms the value into an LCH CSS color function string.
+     * Preserves wide-gamut colors without lossy gamut mapping.
+     *
+     * ```css
+     * // Matches: token.type === 'color'
+     * // Returns:
+     * "lch(50% 30 180)"
+     * "lch(50% 30 180 / 0.5)"
+     * ```
+     *
+     * @memberof Transforms
+     */
+    "color/lch": {
+        type: "value";
+        filter: typeof isColor;
+        transform: (token: import("../../types/DesignToken.d.ts").TransformedToken, _: import("../../types/Config.d.ts").PlatformConfig, options: import("../../types/Config.d.ts").Config) => string;
+    };
     /**
      * Transforms the value into a scale-independent pixel (sp) value for font sizes on Android. It will not scale the number.
      *
@@ -975,9 +1080,12 @@ declare const _default: {
 export default _default;
 export type Transform = import("../../types/Transform.d.ts").Transform;
 export type Token = import("../../types/DesignToken.d.ts").TransformedToken;
+export type DTCGColorValue = import("../../types/DesignToken.d.ts").DTCGColorValue;
+export type DTCGColorSpace = import("../../types/DesignToken.d.ts").DTCGColorSpace;
 export type PlatformConfig = import("../../types/Config.d.ts").PlatformConfig;
 export type Config = import("../../types/Config.d.ts").Config;
 import Color from 'tinycolor2';
+import ColorJS from 'colorjs.io';
 /**
  * @param {Token} token
  * @param {Config} options

package/lib/common/transforms.js

@@ -1,4 +1,5 @@
 import Color from 'tinycolor2';
+import ColorJS from 'colorjs.io';
 import { join } from 'path-unified/posix';
 import { snakeCase, kebabCase, camelCase } from 'change-case';
 import convertToBase64 from '../utils/convertToBase64.js';
@@ -8,6 +9,8 @@ import { transforms, transformTypes } from '../enums/index.js';
 /**
  * @typedef {import('../../types/Transform.d.ts').Transform} Transform
  * @typedef {import('../../types/DesignToken.d.ts').TransformedToken} Token
+ * @typedef {import('../../types/DesignToken.d.ts').DTCGColorValue} DTCGColorValue
+ * @typedef {import('../../types/DesignToken.d.ts').DTCGColorSpace} DTCGColorSpace
  * @typedef {import('../../types/Config.d.ts').PlatformConfig} PlatformConfig
  * @typedef {import('../../types/Config.d.ts').Config} Config
  */
@@ -15,6 +18,169 @@ import { transforms, transformTypes } from '../enums/index.js';
 const UNKNOWN_CSS_FONT_PROPS_WARNINGS = GroupMessages.GROUP.UnknownCSSFontProperties;
 const { value, name, attribute } = transformTypes;
 
+/**
+ * Valid DTCG v2025.10 color spaces
+ * @type {Set<string>}
+ */
+const DTCG_COLOR_SPACES = new Set([
+  'srgb',
+  'srgb-linear',
+  'display-p3',
+  'a98-rgb',
+  'prophoto-rgb',
+  'rec2020',
+  'xyz-d50',
+  'xyz-d65',
+  'lab',
+  'lch',
+  'oklab',
+  'oklch',
+  'hsl',
+  'hwb',
+]);
+
+/**
+ * Map DTCG color space names to colorjs.io color space IDs
+ * @type {Record<string, string>}
+ */
+const DTCG_TO_COLORJS_SPACE = {
+  srgb: 'srgb',
+  'srgb-linear': 'srgb-linear',
+  'display-p3': 'p3',
+  'a98-rgb': 'a98rgb',
+  'prophoto-rgb': 'prophoto',
+  rec2020: 'rec2020',
+  'xyz-d50': 'xyz-d50',
+  'xyz-d65': 'xyz-d65',
+  lab: 'lab',
+  lch: 'lch',
+  oklab: 'oklab',
+  oklch: 'oklch',
+  hsl: 'hsl',
+  hwb: 'hwb',
+};
+
+/**
+ * Check if a value is a DTCG color object
+ * @param {unknown} val
+ * @returns {val is DTCGColorValue}
+ */
+export function isDTCGColorObject(val) {
+  return (
+    typeof val === 'object' &&
+    val !== null &&
+    'colorSpace' in val &&
+    typeof val.colorSpace === 'string' &&
+    DTCG_COLOR_SPACES.has(val.colorSpace) &&
+    'components' in val &&
+    Array.isArray(val.components)
+  );
+}
+
+/**
+ * Convert a DTCG color object to a ColorJS Color instance
+ * Handles 'none' values in components and alpha
+ * @param {DTCGColorValue} dtcgColor
+ * @returns {ColorJS}
+ */
+function dtcgToColorJS(dtcgColor) {
+  const { colorSpace, components, alpha } = dtcgColor;
+
+  // Map DTCG color space to colorjs.io color space ID
+  const colorjsSpace = DTCG_TO_COLORJS_SPACE[colorSpace] ?? colorSpace;
+
+  // Convert 'none' values to NaN (as per CSS Color spec)
+  const coords = /** @type {[number, number, number]} */ (
+    components.map((c) => (c === 'none' ? NaN : c))
+  );
+  const alphaValue = alpha === 'none' ? NaN : (alpha ?? 1);
+
+  return new ColorJS(colorjsSpace, coords, alphaValue);
+}
+
+/**
+ * Get the sRGB representation of a color, with gamut mapping if needed
+ * Uses the hex property as fallback if provided and color is out of gamut
+ * @param {DTCGColorValue} dtcgColor
+ * @returns {{ r: number, g: number, b: number, a: number }}
+ */
+function dtcgColorToRgb(dtcgColor) {
+  const color = dtcgToColorJS(dtcgColor);
+
+  // Check if color is in sRGB gamut
+  if (!color.inGamut('srgb')) {
+    // If hex fallback is provided, use it
+    if (dtcgColor.hex) {
+      const fallback = Color(dtcgColor.hex).toRgb();
+      return fallback;
+    }
+    // Otherwise, perform gamut mapping
+    color.toGamut({ space: 'srgb' });
+  }
+
+  const srgb = color.to('srgb');
+  const alpha = isNaN(srgb.alpha) ? 1 : srgb.alpha;
+
+  return {
+    r: Math.round(Math.max(0, Math.min(1, srgb.coords[0])) * 255),
+    g: Math.round(Math.max(0, Math.min(1, srgb.coords[1])) * 255),
+    b: Math.round(Math.max(0, Math.min(1, srgb.coords[2])) * 255),
+    a: alpha,
+  };
+}
+
+/**
+ * Get color RGB values from either legacy string format or DTCG object format
+ * @param {Token} token
+ * @param {Config} options
+ * @returns {{ r: number, g: number, b: number, a: number }}
+ */
+export function getColorRgb(token, options) {
+  const val = options.usesDtcg ? token.$value : token.value;
+
+  if (isDTCGColorObject(val)) {
+    return dtcgColorToRgb(val);
+  }
+
+  // Legacy format - use tinycolor2
+  return Color(val).toRgb();
+}
+
+/**
+ * Get a tinycolor2 Color instance from either legacy string format or DTCG object format
+ * This provides backward compatibility for transformers that use tinycolor2 methods
+ * @param {Token} token
+ * @param {Config} options
+ * @returns {ReturnType<typeof Color>}
+ */
+export function getColor(token, options) {
+  const val = options.usesDtcg ? token.$value : token.value;
+
+  if (isDTCGColorObject(val)) {
+    const rgb = dtcgColorToRgb(val);
+    return Color(rgb);
+  }
+
+  return Color(val);
+}
+
+/**
+ * Get a ColorJS Color instance from either legacy string format or DTCG object format
+ * @param {Token} token
+ * @param {Config} options
+ * @returns {ColorJS}
+ */
+export function getColorJS(token, options) {
+  const val = options.usesDtcg ? token.$value : token.value;
+
+  if (isDTCGColorObject(val)) {
+    return dtcgToColorJS(val);
+  }
+
+  // Parse legacy format with ColorJS
+  return new ColorJS(val);
+}
+
 /**
  * @param {string} str
  * @returns {string}
@@ -33,8 +199,14 @@ const camelOpts = {
 export function isColor(token, options) {
   const val = options.usesDtcg ? token.$value : token.value;
   const type = options.usesDtcg ? token.$type : token.type;
+
+  if (type !== 'color') return false;
+
+  // DTCG object format
+  if (isDTCGColorObject(val)) return true;
+
+  // Legacy string format
   return (
-    type === 'color' &&
     Color(val).isValid() &&
     // exclude gradients from being color transformed
     ['linear', 'radial', 'conic']
@@ -257,7 +429,7 @@ export default {
     type: attribute,
     filter: isColor,
     transform: function (token, _, options) {
-      const color = Color(options.usesDtcg ? token.$value : token.value);
+      const color = getColor(token, options);
       return {
         hex: color.toHex(),
         rgb: color.toRgb(),
@@ -399,7 +571,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      return Color(options.usesDtcg ? token.$value : token.value).toRgbString();
+      return getColor(token, options).toRgbString();
     },
   },
 
@@ -419,7 +591,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      return Color(options.usesDtcg ? token.$value : token.value).toHslString();
+      return getColor(token, options).toHslString();
     },
   },
 
@@ -439,7 +611,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      const color = Color(options.usesDtcg ? token.$value : token.value);
+      const color = getColor(token, options);
       const o = color.toHsl();
       const vals = `${Math.round(o.h)} ${Math.round(o.s * 100)}% ${Math.round(o.l * 100)}%`;
       if (color.getAlpha() === 1) {
@@ -465,7 +637,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      const color = Color(options.usesDtcg ? token.$value : token.value);
+      const color = getColor(token, options);
       if (color.getAlpha() === 1) {
         return color.toHexString();
       } else {
@@ -489,7 +661,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      return Color(options.usesDtcg ? token.$value : token.value).toHex8String();
+      return getColor(token, options).toHex8String();
     },
   },
 
@@ -508,7 +680,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      const str = Color(options.usesDtcg ? token.$value : token.value).toHex8();
+      const str = getColor(token, options).toHex8();
       return '#' + str.slice(6) + str.slice(0, 6);
     },
   },
@@ -528,7 +700,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      const str = Color(options.usesDtcg ? token.$value : token.value).toHex8();
+      const str = getColor(token, options).toHex8();
       return 'Color(0x' + str.slice(6) + str.slice(0, 6) + ')';
     },
   },
@@ -548,7 +720,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      const rgb = Color(options.usesDtcg ? token.$value : token.value).toRgb();
+      const rgb = getColor(token, options).toRgb();
       return (
         '[UIColor colorWithRed:' +
         (rgb.r / 255).toFixed(3) +
@@ -581,7 +753,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      const { r, g, b, a } = Color(options.usesDtcg ? token.$value : token.value).toRgb();
+      const { r, g, b, a } = getColor(token, options).toRgb();
       const rFixed = (r / 255.0).toFixed(3);
       const gFixed = (g / 255.0).toFixed(3);
       const bFixed = (b / 255.0).toFixed(3);
@@ -604,7 +776,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      const { r, g, b, a } = Color(options.usesDtcg ? token.$value : token.value).toRgb();
+      const { r, g, b, a } = getColor(token, options).toRgb();
       const rFixed = (r / 255.0).toFixed(3);
       const gFixed = (g / 255.0).toFixed(3);
       const bFixed = (b / 255.0).toFixed(3);
@@ -628,7 +800,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      const color = Color(options.usesDtcg ? token.$value : token.value);
+      const color = getColor(token, options);
       if (color.getAlpha() === 1) {
         return color.toHexString();
       } else {
@@ -659,7 +831,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      let color = Color(options.usesDtcg ? token.$value : token.value).toRgb();
+      let color = getColor(token, options).toRgb();
       return {
         red: (color.r / 255).toFixed(5),
         green: (color.g / 255).toFixed(5),
@@ -669,6 +841,130 @@ export default {
     },
   },
 
+  /**
+   * Transforms the value into an OKLCH CSS color function string.
+   * Preserves wide-gamut colors without lossy gamut mapping.
+   *
+   * ```css
+   * // Matches: token.type === 'color'
+   * // Returns:
+   * "oklch(0.7 0.15 180)"
+   * "oklch(0.7 0.15 180 / 0.5)"
+   * ```
+   *
+   * @memberof Transforms
+   */
+  [transforms.colorOklch]: {
+    type: value,
+    filter: isColor,
+    transform: function (token, _, options) {
+      const color = getColorJS(token, options).to('oklch');
+      const [l, c, h] = color.coords;
+      const alpha = isNaN(color.alpha) ? 1 : color.alpha;
+      // Format: oklch(L C H) or oklch(L C H / alpha)
+      const lStr = (isNaN(l) ? 0 : l).toFixed(4);
+      const cStr = (isNaN(c) ? 0 : c).toFixed(4);
+      const hStr = (isNaN(h) ? 0 : h).toFixed(2);
+      if (alpha === 1) {
+        return `oklch(${lStr} ${cStr} ${hStr})`;
+      }
+      return `oklch(${lStr} ${cStr} ${hStr} / ${alpha})`;
+    },
+  },
+
+  /**
+   * Transforms the value into an OKLAB CSS color function string.
+   * Preserves wide-gamut colors without lossy gamut mapping.
+   *
+   * ```css
+   * // Matches: token.type === 'color'
+   * // Returns:
+   * "oklab(0.7 -0.1 0.1)"
+   * "oklab(0.7 -0.1 0.1 / 0.5)"
+   * ```
+   *
+   * @memberof Transforms
+   */
+  [transforms.colorOklab]: {
+    type: value,
+    filter: isColor,
+    transform: function (token, _, options) {
+      const color = getColorJS(token, options).to('oklab');
+      const [l, a, b] = color.coords;
+      const alpha = isNaN(color.alpha) ? 1 : color.alpha;
+      // Format: oklab(L a b) or oklab(L a b / alpha)
+      const lStr = (isNaN(l) ? 0 : l).toFixed(4);
+      const aStr = (isNaN(a) ? 0 : a).toFixed(4);
+      const bStr = (isNaN(b) ? 0 : b).toFixed(4);
+      if (alpha === 1) {
+        return `oklab(${lStr} ${aStr} ${bStr})`;
+      }
+      return `oklab(${lStr} ${aStr} ${bStr} / ${alpha})`;
+    },
+  },
+
+  /**
+   * Transforms the value into a Display P3 CSS color function string.
+   * Preserves wide-gamut colors without lossy gamut mapping.
+   *
+   * ```css
+   * // Matches: token.type === 'color'
+   * // Returns:
+   * "color(display-p3 0.5 0.5 0.5)"
+   * "color(display-p3 0.5 0.5 0.5 / 0.5)"
+   * ```
+   *
+   * @memberof Transforms
+   */
+  [transforms.colorP3]: {
+    type: value,
+    filter: isColor,
+    transform: function (token, _, options) {
+      const color = getColorJS(token, options).to('p3');
+      const [r, g, b] = color.coords;
+      const alpha = isNaN(color.alpha) ? 1 : color.alpha;
+      // Format: color(display-p3 r g b) or color(display-p3 r g b / alpha)
+      const rStr = (isNaN(r) ? 0 : r).toFixed(5);
+      const gStr = (isNaN(g) ? 0 : g).toFixed(5);
+      const bStr = (isNaN(b) ? 0 : b).toFixed(5);
+      if (alpha === 1) {
+        return `color(display-p3 ${rStr} ${gStr} ${bStr})`;
+      }
+      return `color(display-p3 ${rStr} ${gStr} ${bStr} / ${alpha})`;
+    },
+  },
+
+  /**
+   * Transforms the value into an LCH CSS color function string.
+   * Preserves wide-gamut colors without lossy gamut mapping.
+   *
+   * ```css
+   * // Matches: token.type === 'color'
+   * // Returns:
+   * "lch(50% 30 180)"
+   * "lch(50% 30 180 / 0.5)"
+   * ```
+   *
+   * @memberof Transforms
+   */
+  [transforms.colorLch]: {
+    type: value,
+    filter: isColor,
+    transform: function (token, _, options) {
+      const color = getColorJS(token, options).to('lch');
+      const [l, c, h] = color.coords;
+      const alpha = isNaN(color.alpha) ? 1 : color.alpha;
+      // Format: lch(L% C H) or lch(L% C H / alpha)
+      const lStr = (isNaN(l) ? 0 : l).toFixed(2);
+      const cStr = (isNaN(c) ? 0 : c).toFixed(2);
+      const hStr = (isNaN(h) ? 0 : h).toFixed(2);
+      if (alpha === 1) {
+        return `lch(${lStr}% ${cStr} ${hStr})`;
+      }
+      return `lch(${lStr}% ${cStr} ${hStr} / ${alpha})`;
+    },
+  },
+
   /**
    * Transforms the value into a scale-independent pixel (sp) value for font sizes on Android. It will not scale the number.
    *
@@ -1515,9 +1811,7 @@ export default {
     type: value,
     filter: isColor,
     transform: function (token, _, options) {
-      const str = Color(options.usesDtcg ? token.$value : token.value)
-        .toHex8()
-        .toUpperCase();
+      const str = getColor(token, options).toHex8().toUpperCase();
       return `Color(0x${str.slice(6)}${str.slice(0, 6)})`;
     },
   },

package/lib/enums/index.d.ts

@@ -1,12 +1,13 @@
 export { actions } from "./actions.js";
-export { logWarningLevels } from "./logWarningLevels.js";
-export { logVerbosityLevels } from "./logVerbosityLevels.js";
-export { logBrokenReferenceLevels } from "./logBrokenReferenceLevels.js";
-export { commentStyles } from "./commentStyles.js";
 export { commentPositions } from "./commentPositions.js";
+export { commentStyles } from "./commentStyles.js";
 export { fileHeaderCommentStyles } from "./fileHeaderCommentStyles.js";
 export { formats } from "./formats.js";
+export { logBrokenReferenceLevels } from "./logBrokenReferenceLevels.js";
+export { logVerbosityLevels } from "./logVerbosityLevels.js";
+export { logWarningLevels } from "./logWarningLevels.js";
+export { propertyFormatNames } from "./propertyFormatNames.js";
+export { builtInSorts } from "./sorts.js";
 export { transformGroups } from "./transformGroups.js";
 export { transforms } from "./transforms.js";
 export { transformTypes } from "./transformTypes.js";
-export { propertyFormatNames } from "./propertyFormatNames.js";

package/lib/enums/index.js

@@ -1,12 +1,13 @@
 export { actions } from './actions.js';
-export { logWarningLevels } from './logWarningLevels.js';
-export { logVerbosityLevels } from './logVerbosityLevels.js';
-export { logBrokenReferenceLevels } from './logBrokenReferenceLevels.js';
-export { commentStyles } from './commentStyles.js';
 export { commentPositions } from './commentPositions.js';
+export { commentStyles } from './commentStyles.js';
 export { fileHeaderCommentStyles } from './fileHeaderCommentStyles.js';
 export { formats } from './formats.js';
+export { logBrokenReferenceLevels } from './logBrokenReferenceLevels.js';
+export { logVerbosityLevels } from './logVerbosityLevels.js';
+export { logWarningLevels } from './logWarningLevels.js';
+export { propertyFormatNames } from './propertyFormatNames.js';
+export { builtInSorts } from './sorts.js';
 export { transformGroups } from './transformGroups.js';
 export { transforms } from './transforms.js';
 export { transformTypes } from './transformTypes.js';
-export { propertyFormatNames } from './propertyFormatNames.js';

package/lib/enums/sorts.d.ts

@@ -0,0 +1,3 @@
+export namespace builtInSorts {
+    let name: "name";
+}

package/lib/enums/sorts.js

@@ -0,0 +1,3 @@
+export const builtInSorts = {
+  name: /** @type {'name'} */ ('name'),
+};

package/lib/enums/transforms.d.ts

@@ -52,6 +52,10 @@ export namespace transforms {
     let assetObjCLiteral: "asset/objC/literal";
     let assetSwiftLiteral: "asset/swift/literal";
     let colorHex8flutter: "color/hex8flutter";
+    let colorOklch: "color/oklch";
+    let colorOklab: "color/oklab";
+    let colorP3: "color/p3";
+    let colorLch: "color/lch";
     let contentFlutterLiteral: "content/flutter/literal";
     let assetFlutterLiteral: "asset/flutter/literal";
     let sizeFlutterRemToDouble: "size/flutter/remToDouble";

package/lib/enums/transforms.js

@@ -52,6 +52,10 @@ export const transforms = {
   assetObjCLiteral: /** @type {'asset/objC/literal'} */ ('asset/objC/literal'),
   assetSwiftLiteral: /** @type {'asset/swift/literal'} */ ('asset/swift/literal'),
   colorHex8flutter: /** @type {'color/hex8flutter'} */ ('color/hex8flutter'),
+  colorOklch: /** @type {'color/oklch'} */ ('color/oklch'),
+  colorOklab: /** @type {'color/oklab'} */ ('color/oklab'),
+  colorP3: /** @type {'color/p3'} */ ('color/p3'),
+  colorLch: /** @type {'color/lch'} */ ('color/lch'),
   contentFlutterLiteral: /** @type {'content/flutter/literal'} */ ('content/flutter/literal'),
   assetFlutterLiteral: /** @type {'asset/flutter/literal'} */ ('asset/flutter/literal'),
   sizeFlutterRemToDouble: /** @type {'size/flutter/remToDouble'} */ ('size/flutter/remToDouble'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "style-dictionary",
-  "version": "5.1.4",
+  "version": "5.3.0",
   "description": "Style once, use everywhere. A build system for creating cross-platform styles.",
   "keywords": [
     "style dictionary",
@@ -112,15 +112,17 @@
   ],
   "homepage": "https://styledictionary.com",
   "overrides": {
-    "tmp": "0.2.5"
+    "tmp": "0.2.5",
+    "lodash": "4.17.23"
   },
   "dependencies": {
     "@bundled-es-modules/deepmerge": "^4.3.1",
-    "@bundled-es-modules/glob": "^11.1.0",
-    "@bundled-es-modules/memfs": "^4.9.4",
+    "@bundled-es-modules/glob": "^13.0.1",
+    "@bundled-es-modules/memfs": "^4.17.0",
     "@zip.js/zip.js": "^2.7.44",
     "chalk": "^5.3.0",
     "change-case": "^5.3.0",
+    "colorjs.io": "^0.5.2",
     "commander": "^12.1.0",
     "is-plain-obj": "^4.1.0",
     "json5": "^2.2.2",
@@ -163,7 +165,7 @@
     "lint-staged": "^12.3.1",
     "lit": "^3.1.2",
     "mdast": "^3.0.0",
-    "mermaid": "^11.6.0",
+    "mermaid": "^10.9.5",
     "mocha": "^10.2.0",
     "monaco-editor": "^0.47.0",
     "npm-run-all": "^4.1.5",

package/types/Config.d.ts

@@ -5,6 +5,7 @@ import type { Parser } from './Parser.js';
 import type { Preprocessor } from './Preprocessor.js';
 import type { Transform } from './Transform.js';
 import type { Format, OutputReferences } from './Format.js';
+import type { SortOption } from './Sort.js';
 import type { Action } from './Action.js';
 import { logBrokenReferenceLevels, logWarningLevels, logVerbosityLevels } from '../lib/enums/index.js';
 type logWarningLevels = typeof logWarningLevels;
@@ -26,6 +27,7 @@ export interface LocalOptions {
     outputReferences?: OutputReferences;
     outputReferenceFallbacks?: boolean;
     formatting?: FormattingOverrides;
+    sort?: SortOption;
     [key: string]: any;
 }
 export interface GetReferencesOptions {

package/types/DesignToken.d.ts

@@ -60,3 +60,18 @@ export interface Dictionary {
     unfilteredAllTokens?: TransformedToken[];
     unfilteredTokenMap?: Map<string, TransformedToken>;
 }
+/**
+ * DTCG v2025.10 color spaces
+ * @see https://tr.designtokens.org/format/#color
+ */
+export type DTCGColorSpace = 'srgb' | 'srgb-linear' | 'display-p3' | 'a98-rgb' | 'prophoto-rgb' | 'rec2020' | 'xyz-d50' | 'xyz-d65' | 'lab' | 'lch' | 'oklab' | 'oklch' | 'hsl' | 'hwb';
+/**
+ * DTCG v2025.10 color value format
+ * @see https://tr.designtokens.org/format/#color
+ */
+export interface DTCGColorValue {
+    colorSpace: DTCGColorSpace;
+    components: (number | 'none')[];
+    alpha?: number | 'none';
+    hex?: string;
+}

package/types/Sort.d.ts

@@ -0,0 +1,17 @@
+import type { TransformedToken } from './DesignToken.js';
+import { builtInSorts } from '../lib/enums/sorts.js';
+export type BuiltInSorts = typeof builtInSorts;
+export interface Sort {
+    name: string;
+    sort: SortFn;
+}
+/**
+ * A single sort function - either a built-in sort referenced by name string or a custom comparator function
+ * for inline usage
+ */
+export type SortFn = string | ((a: TransformedToken, b: TransformedToken) => number);
+/**
+ * Sort option for formattedVariables - can be a single sort item or an array of sort items
+ * (for chaining multiple sorts as tie-breakers)
+ */
+export type SortOption = SortFn | SortFn[];

package/types/index.d.ts

@@ -4,6 +4,7 @@ export type { DesignToken, DesignTokens, PreprocessedTokens, TransformedToken, T
 export type { FileHeader, File, FormattingOptions } from './File.js';
 export type { Filter } from './Filter.js';
 export type { Format, FormatFnArguments, FormatFn, OutputReferences } from './Format.js';
+export type { SortOption, SortFn, BuiltInSorts } from './Sort.js';
 export type { Parser, ParserOptions } from './Parser.js';
 export type { Preprocessor } from './Preprocessor.js';
 export type { Transform, NameTransform, AttributeTransform, ValueTransform } from './Transform.js';