style-dictionary-utils

Filters are used to include or exclude specific tokens when configuring output files in Style Dictionary. You can use filters in two ways:

1. As a registered filter: Use the filter's registered name as a string (e.g., "isSource") within your Style Dictionary configuration object.
2. As an importable function: Import the filter function directly (e.g., isSourceFilter) to use it in custom transformers or directly within platform configurations.

This allows for both high-level configuration via names and low-level programmatic control via function imports.

// Using registered filter by name
myStyleDictionary.extend({
  platforms: {
    ts: {
      files: [{
        filter: "isSource", // ← registered filter name
        // ...
      }]
    }
  }
});

// Importing and using filter function directly
import {isSourceFilter} from 'style-dictionary-utils/filter/isSource.js'

// Use in custom transformer
StyleDictionary.registerTransform({
  name: 'my-custom-transform',
  filter: isSourceFilter, // ← imported filter function
  transform: (token) => // ...
});

The css/advanced format exports a token dictionary as a CSS file using CSS variables. It supports advanced features like media queries and custom selectors.

Key Options:

• selector: A string wrapped around your CSS. Defaults to :root. Set to false to disable the selector.
• rules: An array of rule objects used to wrap specific tokens in CSS blocks (like @media queries or specific attribute selectors).

Rule Object Properties:

• atRule: A string or array of strings (e.g., @media (min-width: 768px)) that wraps the CSS.
• selector: A string that wraps the CSS inside the atRule. If undefined, it falls back to the global file.options.selector.
• matcher: A filter function (token: StyleDictionary.TransformedToken) => boolean. Only tokens returning true will be included in that specific rule.

myStyleDictionary.extend({
  "platforms": {
    "css": {
      "transforms": //...,
      "files": [{
        // ...
        "format": "css/advanced",
        "options": {
          selector: `body[theme="dark"]`,
          rules: [
          {
            atRule: '@media (min-width: 768px)',
            selector: `body[size="medium"]`,
            matcher: (token: StyleDictionary.TransformedToken) => token.filePath.includes('tablet')
          }]
        }
      }]
    }
  }
});

The getHasAttribute function returns a filter function that checks if a token has at least one of the specified properties.

You can use it in two ways:

1. Register it as a new filter: Use StyleDictionary.registerFilter to give it a name for use in configuration strings.
2. Use it directly in a platform: Pass the function returned by getHasAttribute directly into the filter key of a file configuration.

Signature: getHasAttribute(...properties: string[])

// Register as a new filter
import StyleDictionary from 'style-dictionary-utils'
import {getHasAttribute} from 'style-dictionary-utils/filter/getHasAttribute.js'

StyleDictionary.registerFilter({
  name: 'shouldAvoid',
  matcher: getHasAttribute('deprecated', 'removed'),
})

// Use directly in platform
import StyleDictionary from 'style-dictionary-utils'
import {getHasAttribute} from 'style-dictionary-utils/filter/getHasAttribute.js'

myStyleDictionary.extend({
  "platforms": {
    "deprecatedJson": {
      "transforms": //...,
      "files": [{
        "filter": getHasAttribute('deprecated','removed'),
        // ...
      }]
    }
  }
});

The getHasAttributeValue function returns a filter function that checks if a token has specific properties with specific values.

• If you provide an array of values for the second argument, every property checked can have any of those values.
• You can use it by registering it as a named filter or by using the function directly in a platform configuration.

Signature: getHasAttributeValue(attributes: string[], values: any[])

// Register as a new filter
import StyleDictionary from 'style-dictionary-utils'
import {getHasAttributeValue} from 'style-dictionary-utils/filter/getHasAttributeValue.js'

StyleDictionary.registerFilter({
  name: 'isDeprecated',
  matcher: getHasAttributeValue('deprecated', true),
})

// Use directly in platform
import StyleDictionary from 'style-dictionary-utils'
import {getHasAttributeValue} from 'style-dictionary-utils/filter/getHasAttributeValue.js'

myStyleDictionary.extend({
  "platforms": {
    "deprecatedJson": {
      "transforms": //...,
      "files": [{
        "filter": getHasAttributeValue('deprecated',true),
        // ...
      }]
    }
  }
});

The getIsType function returns a filter function that filters tokens based on their $type property. You can provide one or multiple types to match against.

Signature: getIsType(...types: string[])

Usage patterns:

• Register as a new filter: Use StyleDictionary.registerFilter to create a named filter (e.g., isAnimation) that matches multiple types like duration, transition, and cubicBezier.
• Use directly in platform: Pass the function directly to the filter key in your platform configuration to allow specific types (e.g., size or dimension).

// Register as a new filter
import StyleDictionary from 'style-dictionary-utils'
import {getIsType} from 'style-dictionary-utils/filter/getIsType.js'

StyleDictionary.registerFilter({
  name: 'isAnimation',
  matcher: getIsType('duration', 'transition', 'cubicBezier'),
})

// Use directly in platform
import StyleDictionary from 'style-dictionary-utils'
import {getIsType} from 'style-dictionary-utils/filter/getIsType.js'

myStyleDictionary.extend({
  "platforms": {
    "ts": {
      "transforms": //...,
      "files": [{
        "filter": getIsType('size','dimension'),
        // ...
      }]
    }
  }
});