What Are Design Tokens?

Design tokens are the central source for all design properties like colors, typography, spacing, and shadows. They are named variables for your design system.

Instead of hardcoding values (e.g., #4F46E5), you define a token like color.primary.DEFAULT and use it everywhere. This fosters a shared language between designers and developers, ensuring consistency and scalability across all platforms.

Why Are Design Tokens Useful?

Using design tokens offers several significant advantages:

• Consistency: Ensure consistent design elements across your application, eliminating inconsistencies and creating a cohesive user experience.
• Scalability: Simplify scaling your design system. Update a token's value once, and the change propagates everywhere, making complex property management easy as your project grows.
• Maintainability: Improve codebase maintainability. Eliminate hunting for and replacing hardcoded values, saving time and reducing errors.
• Bridging the Gap Between Design and Development: Foster a shared language between designers and developers. Designers manage tokens in design tools (e.g., Figma), while developers use them in code, streamlining handoff and improving collaboration.
• Theming: Enable easy theming, like dark mode. Create distinct token sets for each theme and switch them to alter your application's appearance.

How Do They Work in Practice?

Design tokens are typically stored in a structured format like JSON. Here is a simple example of what a design token file might look like:

{
  "other": {
    "layer-1": {
      "value": 1,
      "type": "other"
    },
  },
  "sizing": {
    "size-2": {
      "value": "0.5em",
      "type": "sizing"
    },
    "size-4": {
      "value": "4em",
      "type": "sizing"
    }
  },
  "color": {
    "color-primary-lighter": {
      "value": "oklch(62.3% 0.214 259.815)",
      "type": "color"
    },
    "color-primary": {
      "value": "oklch(54.6% 0.245 262.881)",
      "type": "color"
    },
    "color-primary-darker": {
      "value": "oklch(37.9% 0.146 265.522)",
      "type": "color"
    }
  },
  "borderWidth": {
    "border-size-2": {
      "value": "0.5em",
      "type": "borderWidth"
    },
    "border-size-4": {
      "value": "4em",
      "type": "borderWidth"
    }
  },
  "boxShadow": {
    "shadow-1": {
      "value": "0 2px 1px -1px hsl({shadow.color.value} / calc({shadow.weight.value} + 18%)),0 1px 1px hsl({shadow.color.value} / calc({shadow.weight.value} + 12%)),0 1px 3px hsl({shadow.color.value} / calc({shadow.weight.value} + 10%))",
      "type": "boxShadow"
    },
    "shadow-color": {
      "value": "gray",
      "type": "boxShadow"
    },
    "shadow-weight": {
      "value": "1%",
      "type": "boxShadow"
    },
    "shadow-@media:dark-color": {
      "value": "hsl(220 40% 2%)",
      "type": "boxShadow"
    },
    "shadow-@media:dark-weight": {
      "value": "25%",
      "type": "boxShadow"
    }
  }
}

This JSON example shows tokens for colors, sizing, and shadows. These tokens are consumed by various tools and platforms, such as CSS preprocessors, JavaScript frameworks, and native mobile applications.

Design Tokens and Tailwind CSS

If you use Tailwind CSS, you're already familiar with design tokens. The theme object in tailwind.config.js acts as a set of design tokens.

module.exports = {
    theme: {
        colors: {
            primary: {
                lighter: 'oklch(62.3% 0.214 259.815)',
                DEFAULT: 'oklch(54.6% 0.245 262.881)',
                darker: 'oklch(37.9% 0.146 265.522)',
            },
            // ...
        },
        spacing: {
            xs: '0.5rem',
            sm: '0.75rem',
            // ...
        },
    },
};

Keys in the theme object (e.g., colors.primary.DEFAULT, spacing.sm) are the design tokens, and their values are the design properties.

Design Tokens in Hyvä

Hyvä offers the hyva-tokens tool for streamlined design token management. It lets you use a dedicated design token file (e.g., from Figma) as the single source of truth for your theme's styling.

hyva-tokens processes your design token file to generate a CSS file with custom properties (variables). Use these variables in your theme for a consistent and maintainable design system.