The Complete Guide to Design Tokens in 2024

Design tokens are not limited to colors. A robust token system covers every aspect of the visual language. Here are the four primary categories you should define.

A chaotic naming convention is the fastest way to break a design system. The industry standard follows a hierarchical structure: Global → Alias → Component.

Global tokens are the raw values (e.g., `color-brand-primary-500`). Alias tokens provide semantic meaning (e.g., `color-text-heading`). Component tokens are specific instances (e.g., `color-button-primary-text`). This three-layer approach allows you to change a value at the global level and have it ripple through the entire system instantly.

Using a tool like Modly helps visualize this hierarchy, ensuring that when you update a token, you can see exactly which components will be affected before you ship.

Supporting multiple themes is no longer optional. The best strategy is to define your tokens in a way that separates values from names.

Instead of `color-primary-light` and `color-primary-dark`, use a theme object structure. For example, define a `light` theme with a `primary` value of `#7c3aed` and a `dark` theme with a `primary` value of `#9d5ff5`. This makes it trivial to add a high-contrast mode or a seasonal theme later.

Below is a JSON representation of a typical token file structure. Notice how semantic aliases are built upon raw values.

{
  "global": {
    "color": {
      "brand": {
        "primary": "#7c3aed",
        "secondary": "#c0376e"
      },
      "text": {
        "primary": "#ffffff",
        "secondary": "rgba(255,255,255,0.70)"
      }
    },
    "spacing": {
      "xs": "0.5rem",
      "sm": "1rem",
      "md": "1.5rem",
      "lg": "2rem"
    }
  },
  "alias": {
    "color": {
      "primary": "{global.color.brand.primary}",
      "text-body": "{global.color.text.secondary}"
    },
    "spacing": {
      "section-padding": "{global.spacing.lg}"
    }
  }
}