npm package: @grafana/design-tokens
Description: Design Tokens for Grafana
Author: Grafana Labs
Latest version: 0.0.35

# Design Tokens

A proof of concept for a Source of Truth for Design Tokens across Grafana Labs
products, using [Style Dictionary][1].

## Architecture

This Design Tokens package has several primary goals:

1. Provide a Source of Truth for Design Tokens used across all Grafana
   applications
2. Apply and document a layer of _semantics_ to small, discrete design decisions
   which can be used to inform _product design_ decisions made by both humans
   and AI tools.
3. Provide a convenient API for exposing these tokens in a framework-agnostic
   format, allowing them be consumed directly within other libraries.
4. To be independent of pre-existing Grafana interface libraries (e.g. `@grafana/data` and
   `@grafana/ui`), to aid with decoupling and adoption.
5. To facilitate the migration of existing Grafana UI to any future visual
   refresh of the product.

## Source of Truth

The Design Tokens that live within `src/tokens/` follow the [Design Tokens
Format community proposal][2] JSON format, with three distinct types of token,
broken up as follows:

- Primitives
- Semantic
- Components

### Primitive Tokens

Primitive tokens represent _abstract_ values, absent context about how they are
intended to be used. For example, a color token of `blue-50` might have a value
of `#0000cc`. Primitive tokens are usually then referenced by the _semantic_
tokens.

### Semantic Tokens

Semantic tokens define the relationship between a given token and its usage —
usually mapping to a primitive (or other semantic) token. For example, you might
have a token of `primary.color` which maps to `blue-50`. Additionally, multiple
semantic tokens with the same name might exist for different color modes (light
and dark).

### Component Tokens

Component tokens are tokens that map specific properties of a component
implementation to a semantic tokens, for example `linkColor` could map to
`primary.color`.

### Legacy Tokens

Since facilitating migration of existing Grafana UI is one of the primary goals
of this package, the API provided by the library also provides a convenience
wrapper to the existing _legacy_ design tokens, using a structure mirroring the
existing API of `useTheme2()` provided by `@grafana/ui`. An example of how to
migrate existing calls is given further below.

## `getDesignTokens()`

The utility function `getDesignTokens()` exposes all of the tokens defined
within the `src/tokens/` directory.

```ts
import { getDesignTokens } from '@grafana/design-tokens';

const { primitives, semantic } = getDesignTokens({ mode: 'dark' });
```

As well as the new semantic design tokens, the function also exposes equivalent
legacy tokens to those in `@grafana/data`’s `createTheme()` function. These
provide a mechanism for retrieving design token values in an API-compatible
structure, to allow them to be dropped in in place of the existing
implementations:

```ts
// createTheme.ts
import { getDesignTokens } from '@grafana/design-tokens';

export function createTheme(options: NewThemeOptions = {}): GrafanaTheme2 {
  const {
    name,
    colors: colorsInput = {},
    spacing: spacingInput = {},
    shape: shapeInput = {},
    typography: typographyInput = {},
    visualization: visualizationInput = {},
  } = options;

  const { legacy } = getDesignTokens({ mode: colorsInput.mode });

  const colors = {
    ...createColors(colorsInput),
    ...legacy.colors,
  };
  ...
}
```

Colocating the legacy tokens along with the new tokens will aid in the
transition for existing component implementations.

### Migrating from `useTheme2()`

For a component that currently uses CSS in JS to build its styles with
`useTheme2()`, you can migrate this to use `getDesignTokens()` instead.

First, ensure you’re importing `getDesignTokens` from the package:

```ts
import { getDesignTokens } from '@grafana/design-tokens';
```

Then, when building the styles to apply to your component, update the style
getter function:

```diff
export function getStyles(theme: GrafanaTheme2) {
+  const { legacy } = getDesignTokens({ mode: theme.colors.mode });

  return {
-    color: theme.colors.primary.text,
+    color: legacy.colors.primary.text,
-    borderColor: theme.colors.border.strong,
+    borderColor: legacy.colors.border.strong,
  };
}
```

This API is intended to facilitate _migration_ of components until such time as
an equivalent and comprehensive set of semantic tokens is available, at which
point the legacy API will be deprecated. In the interim, migrating to using the
legacy tokens API will allow you to reduce or remove your dependence on the
`useTheme2()` API without any UI breakage.

## Building & Publishing

At present a temporary publish workflow exists using GitHub Actions. To publish
a new version of this package, you simply need to merge to the `main` branch,
ensuring that the version number (following semver) in `package.json` has been
incremented.

_Future improvements_

1. Automatically increment the version using semver based on semantic commits
2. Deploy the static CSS resources to a CDN

[1]: https://styledictionary.com/
[2]: https://www.designtokens.org/tr/2025.10/format/