---
title: Building Consistent UIs with Design Tokens
description: Design tokens allow developers to create maintainable UIs
type: article
authors: ["esther"]
publishedAt: "2024-11-24"
---

Design tokens allow developers to create maintainable, scalable, and easy to
manage user interfaces.

They create a shared language between designers and developers, allowing them to
reference standardized values instead of hard-coding specific styles. This way,
rather than updating styles individually across components, developers can
adjust token values, which are then applied globally.

In this article, I'll cover how you can leverage Chakra UI's built-in design
tokens to maintain consistency across all your applications.

## What Are Design Tokens?

Design tokens are key-value pairs that represent the visual properties and UI
elements of a design system, such as colors, typography, spacing and more. They
play a key role in allowing you to create scalable, cohesive, and consistent
user interfaces.

They serve as the foundation of a design system, allowing developers and
designers to implement consistent styles across components and projects
efficiently. By abstracting visual properties into tokens, design tokens create
a shared language between design and development teams, ensuring cohesive
designs.

In Chakra UI, these tokens fall into two main categories:

- **Core Tokens**: Fundamental properties such as colors, font sizes, spacing,
  and borders.
- **Semantic Tokens**: Higher-level tokens tied to themes that enable easy style
  updates across dark and light modes or other design contexts.

## Using Core Tokens for Scalability

Chakra UI's [core design tokens](/docs/theming/tokens) include foundational
properties like **colors**, **spacing**, **typography**, **radii**, **borders**
and more, which help you quickly set up your application's look and feel.

Here's how to use some of these tokens to streamline development:

- **Colors**: Chakra UI provides a wide palette of color tokens, ranging from
  `.50` to `.950` such as `gray.50`, `gray.300`, etc.

```jsx
<Box bg="gray.300" p={4}>
  Chakra Box with Core Color Token
</Box>
```

- **Spacing and Sizing**: Tokens for margin, padding and other sizing properties
  allow for consistent layout dimensions.

  By default, Chakra includes a comprehensive numeric spacing scale where the
  values are proportional. So, 1 spacing unit is equal to `0.25rem`, which
  translates to `4px` by default in common browsers.

  Using tokens like 4, 8, 12, etc., ensures a predictable layout behavior.

```jsx
<Box padding={4} margin={2}>
  Consistent Padding and Margin
</Box>
```

> This translates to a padding of `16px` and a margin of `8px`.

- **Typography**: Chakra provides font size and weight tokens, so your app's
  text elements maintain a uniform appearance. By specifying tokens like `lg`,
  `md`, or `xl` for font sizes, you reduce the likelihood of inconsistent text
  styling.

```jsx
<Text fontSize="lg" fontWeight="bold">
  Styled with Font Tokens
</Text>
```

## Customizing Core Tokens

To start [customizing tokens](/docs/theming/customization/colors#tokens), you
need to extend the Chakra theme by using Chakra's `defineConfig` function. This
function allows you to override Chakra's default tokens with your own values.

Let's look at how you can start by creating a custom `theme.ts` file. A design
token in Chakra UI consists of the following properties:

- value: The value of the token. This can be any valid CSS value.
- description: An optional description of what the token can be used for.

```ts
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"

const customConfig = defineConfig({
  theme: {
    tokens: {
      colors: {
        brand: {
          50: { value: "#e6f2ff" },
          100: { value: "#e6f2ff" },
          200: { value: "#bfdeff" },
          300: { value: "#99caff" },
          // ...
          950: { value: "#001a33" },
        },
      },
    },
  },
})

export const system = createSystem(defaultConfig, customConfig)
```

Now, you can utilize your custom token where needed, such as:

```jsx
<Box bg="brand.100">This Box uses a custom token</Box>
```

## Using semantic tokens for contextual styling

[Semantic tokens](/docs/theming/semantic-tokens) allow for context-based styling
and enables you to change the appearance of your app based on the theme or mode
(e.g., light or dark mode).

```jsx
<Button color="danger">Click me</Button>
```

In most cases, the value of a semantic token references to an existing token.

To reference a value in a semantic token, use the token reference `{}` syntax.

```ts
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"

const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        red: { value: "#EE0F0F" },
      },
    },
    semanticTokens: {
      colors: {
        danger: { value: "{colors.red}" },
      },
    },
  },
})

export default createSystem(defaultConfig, config)
```

## Customizing the semantic tokens

You can
[create your own semantic tokens](/docs/theming/customization/colors#custom-tokens)
by extending Chakra's theme. This flexibility enables you to customize semantic
tokens based on your brand's unique color scheme.

```jsx
import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"

const customConfig = defineConfig({
  theme: {
    semanticTokens: {
      colors: {
        "checkbox-border": {
          value: { _light: "gray.200", _dark: "gray.800" },
        },
      },
    },
  },
})

export const system = createSystem(defaultConfig, customConfig)
```

## Boost Collaboration with Design Tokens

Design tokens promote a unified approach to styling, which can drastically
improve collaboration between developers and designers. Here's how design tokens
in Chakra UI help:

- **Creating a Shared Visual Language**: Design tokens provide a standard set of
  values for developers and designers, ensuring everyone uses the same color
  palette, spacing, and typography values.

- **Efficiently Managing Global Design Changes**: Because design tokens are
  centrally managed, changing a token value updates all components using that
  token. For example, if you adjust a `primary.500` token to a new shade, every
  component using this token instantly reflects the change.

- **Enhanced Reusability and Maintainability**: With Chakra's tokens, components
  are designed to be reusable, enhancing your code's scalability. When you need
  to adjust a style across multiple components, you simply update the token
  rather than modifying each component individually.

## Conclusion

Whether you're implementing core tokens for standard styles or using semantic
tokens to adapt to theme changes, Chakra UI's design tokens make your interface
clean, efficient, and easier to maintain.

By using a shared set of values, you're not only speeding up your development
workflow but also ensuring your designs stay cohesive. Try it out in your next
project, and experience firsthand how design tokens can simplify your work and
improve collaboration across your team.
