Tokens

Design tokens are a set of variables that are used to style the UI. They are used to ensure consistency across the UI and to make it easier to change the look of the UI.

Tiers

There are three tiers of tokens: primitive, semantic, and component. Each tier builds on the previous tier, so the primitive tokens are the most basic and the component tokens are the most specific.

Tier	Description
Primitive	All of the possible options for commonly used values. Your project likely won’t use all of these, but they represent the range of possibilities for colors, spacing, and other values.
Semantic	These tokens take some of the primitives and assign them to particular UI patterns. You can see these as the design decisions that shape the look and feel of the UI.
Component	These tokens are specific to particular components. They are often based on semantic tokens, but may also refer to primitives or even raw values. In Fusion, this section directly follows the CSS specification.

To give you an idea of how the tokens are structured, here are some examples:


import { tokens } from "@codedazur/fusion-ui/style";
 
tokens.primitive.spacing[300]; // e.g. "16px"
tokens.primitive.colors.deepPurple[50]; // e.g. "#7d14d8"
 
tokens.semantic.colors.primary.base; // e.g. "var(--primitive-colors-deepPurple-50)"
tokens.semantic.typography.body.medium; // e.g. "var(--semantic-typography-body-medium)"
 
tokens.component.button.container.borderRadius; // e.g. "var(--primitive-spacing-300)"
tokens.component.button.container.variants.primary.backgroundColor; // e.g. "var(--semantic-colors-primary-base)"

For an overview of the available tokens, see the Tokens reference documentation.

Using Tokens

Fusion UI uses vanilla-extract for styling, providing a type-safe, zero-runtime CSS-in-JS solution with built-in design token support. With this system, the tokens are implemented as CSS variables.

With CSS Classes

In order to use those variables, you can import the variable names from Fusion and use them in a Vanilla Extract style object.


import { tokens } from "@codedazur/fusion-ui/style";
import { style } from "@vanilla-extract/css";
 
const myStyle = style({
  backgroundColor: tokens.semantic.primary.base,
  padding: tokens.primitive.spacing[400],
});

Note

Note that even if you provide you own themes, you still import the tokens from Fusion. The tokens are just the names of the CSS variables after all, not their values.

Warning

Although you technically have access to the component tokens as well, those tokens should not be used outside of the component they are intended for. It is important for sustainability that those tokens have a clear scope and that components don’t have cross-dependencies.

With Inline Styles

You can also use the tokens directly in the inline styles of your components.


import { tokens } from "@codedazur/fusion-ui/style";
 
function Example() {
  return (
    <div
      style={{
        color: tokens.semantic.colors.primary.base,
        fontFamily: tokens.primitive.fontFamily[1],
        padding: tokens.primitive.spacing[100],
        borderRadius: tokens.primitive.borderRadius[100],
      }}
    >
      Content styled with tokens
    </div>
  );
}