@ch-ui/tokens

The tokens package renders sets of CSS custom properties, a.k.a. CSS variables, that you can put upstream of a utility system like Tailwind or a web component library (or use on their own of course).

This package generates tokens using a principled approach that aims to make it easier for platform developers, app developers, and end-users alike to maintain and apply adjustments to an app’s design system tokens.

Getting started

pnpm add -D @ch-ui/tokens

Then, use any of the render functions as you like. If you’re using Vite, there’s already @ch-ui/vite-plugin-tokens if you like.

Use with PostCSS

To add to your PostCSS setup:

import chTokens from '@ch-ui/tokens/postcss';
import myTokenSet from './config';
//...
plugins: [
  // ...
  chTokens((params: string) => myTokenSet),
  // ...
]
//...

In your PostCSS:

@layer tokens {
  @tokens myTokens
}

Easy.

If you like, you can resolve different sets of tokens using the params provided after @tokens.

A “default token set” is provided if you suffer from blank canvas syndrome:

import chTokens from '@ch-ui/tokens/postcss';
import { defaultTokenSet } from '@ch-ui/tokens';
import myTokenSet from './config';
//...
plugins: [
  // ...
  chTokens(
    (params: string) => params === 'myProductionApp'
      ? myTokenSet
      : defaultTokenSet
  ),
  // ...
]
//...

Background

Design systems often maintain an intentionally limited set of design tokens, such as:

• specific colors arranged in “palettes”,
• font sizes arranged in a “type scale” or “font ramp”.

These physical tokens are the most fundamental layer, naming specific scalar (numeric) values to use. The same tokens can be redefined within conditional at-rules e.g. to support broader gamuts like rec2020.

The base layer of physical tokens can then be built upon with a layer of semantic tokens, which map physical values guarded by conditional at-rules to one coherent meaningful name, for example --fg-description (for “foreground color: descriptions”) can map to one physical color by default or a different one when prefers-color-palette: dark.

Physical series

All design tokens ultimately resolve to physical values, which in @ch-ui/tokens are generated by a series of inputs along a continuum.

@ch-ui/tokens implements three kinds of series:

• linear,
• exponential, and
• helical arc for color palettes

For example, the package comes with default font sizes in an exponential series:

const defaultSizes = {
  initial: 1,
  unit: 'rem',
  base: 1.2,
  naming: {
    '2xs': -3,
    xs: -2,
    s: -1,
    base: 0,
    lg: 1,
    xl: 2,
    '2xl': 3,
    '3xl': 4,
    '4xl': 5,
  },
} satisfies ExponentialSeries;

This will output physical tokens in rem for the input values [-3, -2, -1, 0, 1, 2, 3, 4, 5] using the equation initial * Math.pow(base, input).

Layers

Rendered by:

• renderPhysicalLayer(physicalLayer: PhysicalLayer, semanticValues?: SemanticValues)
• renderSemanticLayer(semanticLayer: SemanticLayer)

Physical and semantic configurations are defined in a layer which lets you redefine slates of tokens based on conditions, which are just nested CSS statements (at-rules or selectors). Additionally, layers are where you can set a namespace.

For example, the package comes with default colors that use conditions to redefine the tokens when the browser supports broader gamuts:

export const defaultPhysicalColors = {
  conditions: {
    srgb: [':root'],
    p3: ['@media (color-gamut: p3)', ':root'],
    rec2020: ['@media (color-gamut: rec2020)', ':root'],
  },
  series: {
    neutral: {
      srgb: neutralArc,
      p3: neutralArc,
      rec2020: neutralArc,
    },
    accent: {
      srgb: accentArc,
      p3: accentArc,
      rec2020: accentArc,
    },
  },
  namespace: 'ch-',
} satisfies ColorsPhysicalLayer;

Note that neutralArc and accentArc are helical arc series which are repeated; the repetition is incidental, since you may want to use a different series in different conditions. How this applies to colors in particular is described in more detail in @ch-ui/colors.

Semantic layers

Using semantic layers, you can define names which map to different physical tokens in different conditions. Where physical layers describe their values as a series, semantic layers describe their values as sememes (/ˈsɛmiːms/), which map meaningful names to a physical value for each condition in the layer.

For example, the package comes with a default semantic layer for colors to apply between light and dark modes:

export const defaultSemanticColors = {
  conditions: {
    light: [':root'],
    dark: ['@media (prefers-color-scheme: dark)', ':root'],
  },
  sememes: {
    'bg-base': {
      light: ['neutral', 975],
      dark: ['neutral', 150],
    },
    'fg-base': {
      light: ['neutral', 0],
      dark: ['neutral', 900],
    },
    // etc
  },
  namespace: 'ch-',
} satisfies SemanticLayer;

Semantic expressions

Semantic layers support expressions where, instead of a literal value, you can specify some operation on either a literal value or a reference to another semantic token, for example:

export const defaultSemanticColors = {
  // ...
  sememes: {
    'bg-base': {
      // ...
    },
    'fg-base': {
      light: ['neutral', '88f:bg-base'],
      dark: ['neutral', '-88f:bg-base'],
    },
    // ...
  },
  // ...
} satisfies SemanticLayer;

With this configuration, fg-base’s light and dark values will be computed to be a value that should each result in an APCA Lc value of ±88 when fg-base is used as a foreground against bg-base.

Note when referring to other tokens in expressions that they must not cycle and must ultimately resolve to a literal value.

Valid operations depend on the type of series the semantic layer configures. Currently only f and b operations are supported, and f and b only apply to color series a.k.a. HelicalArcSeries.

Facets

Rendered by renderFacet(facet: Facet).

For better ergonomics, physical and semantic layers can be combined into a facet. When rendered together like this, @ch-ui/tokens will automatically infer that any values mentioned in the semantic layer should be added to the inputs of the physical layer. If you will only use semantic values, this means you don’t need to define any values in the physical layer.

Render all tokens

All tokens can be rendered using renderTokenSet(tokenSet: TokenSet).

A TokenSet is just a Record<string, Facet> containing all the facets you’d like to render, keyed by ids you provide.

Auditing

You can audit tokens (one facet at a time) if you’d like more information about why the system is rendering the physical tokens it’s rendering.

import { auditFacet } from '@ch-ui/tokens';
const colorsAudit = auditFacet(tokenSet.colors, { condition: 'p3' });