Skip to main content

flattenTokens

Tool to combine tokens from multiple sources into a single object.

github
View source code
import { flattenTokens } from '@uhg-abyss/web/tools/theme';

Properties​

flattenTokens(...themes: TokenTheme[])

Usage​

The flattenTokens function is designed to flatten and merge tokens from multiple JSON structures, to support a layered system where tokens from different themes can override core- and semantic-level tokens.

The Abyss theme accepts an object with the following style category keys to define the theme: sizing, spacing, color, borderRadius, borderWidth, boxShadow, fontFamilies, fontWeights, fontSizes, lineHeights, letterSpacing, border, and opacity.

This function will return a single object in this format that can be used to create a theme object via createTheme for later use in the ThemeProvider.

Token format support​

The flattenTokens function supports both legacy and DTCG (Design Tokens Community Group) token formats, allowing for backward compatibility during the transition to the standardized DTCG format.

DTCG format (current standard)​

The DTCG format uses $-prefixed properties to distinguish token metadata from user-defined properties:

{
  "brand": {
    "$value": "#0071e3",
    "$type": "color",
    "$description": "Primary brand color"
  }
}

Legacy format (deprecated)​

The legacy format uses unprefixed properties:

{
  "brand": {
    "value": "#0071e3",
    "type": "color",
    "description": "Primary brand color"
  }
}

Format detection​

The flattenTokens function automatically detects which format is being used by checking for the presence of $value (DTCG) or value (legacy) properties. Both formats are parsed identically and produce the same output, ensuring seamless compatibility regardless of which format your tokens use.

Key features:

  • Automatic format detection per token
  • Support for mixed formats within the same token structure
  • Identical output regardless of input format
  • Type inheritance from parent groups (for DTCG format with hoisted $type)

Overriding Abyss token theme​

In this example, we use flattenTokens and createTheme to create a new theme object, which is then passed into ThemeProvider to override the Abyss theme and customize the Button and Accordion components.

Table of Contents