> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

# Import design tokens

> Import design tokens from your design system into Contentful using the CLI.

Design tokens provide a shared styling vocabulary (colors, spacing, typography, borders) that editors apply to Design Properties in Contentful. By importing tokens from your local codebase, you maintain a single source of truth for styling values so updates flow from code to experiences without manual re-entry.

## Prerequisites

You import design tokens using the same `experiences` CLI used for component import.

You also need a **raw token source file**. The CLI uses an AI coding agent to classify this file into [W3C Design Token Community Group (DTCG) format](https://www.designtokens.org/tr/drafts/format/). The following formats are supported:

* SCSS (`.scss`).
* CSS variables (`.css`).
* JavaScript / TypeScript token exports (`.js`, `.ts`).
* Style Dictionary source files.
* Tailwind config files.
* Plain JSON in any structure.

## Import tokens with the TUI

If you are running `experiences import` for your design system, the TUI prompts you for a token file during the flow:

```bash
experiences import
```

During the import flow, the wizard displays a **Design tokens** step where you can:

* Provide the path to your raw token file (absolute, relative, or `~`-prefixed).
* Skip the tokens step and import components only.

![Design tokens step showing the prompt "Token path (file or directory)" with an explainer that the AI agent will classify the input into DTCG format, and legend hints for submitting, skipping, or clearing the input.](/developers/docs/_fern-img/fe12681531355d1f7e95bde53ec165d4c0d07e528fdf80b9435870bcf5de33c4.webp)

To skip the prompt entirely, pass the source file up-front:

```bash
experiences import --raw-tokens ./tokens.scss
```

If you provide a token file, the wizard classifies, generates, previews, and pushes tokens alongside your components — no additional commands are needed. Tokens are recorded in run history alongside components, so `experiences import --push-from-run <id>` and `--modify <id>` cover tokens as well.

## Import tokens with individual commands

When using the step-by-step CLI commands instead of the TUI, token generation and push require explicit flags.

### 1. Generate DTCG tokens from raw input

```bash
experiences generate tokens --agent claude --raw-tokens /path/to/raw-tokens.json
```

The `--agent` flag is required. This invokes the AI agent to analyze your raw token file, identify token types, and convert the values into DTCG format. The CLI stores results in the session database. Replace `claude` with `codex`, `opencode`, or `cursor` to use a different coding agent.

Additional options:

* `--model <name>` — Override the default model for the selected agent.
* `--no-cache` — Bypass cached results and regenerate all tokens.
* `--verbose` — Display detailed agent output.
* `--print-prompt` — Print the generate prompt to stdout and exit. `--dry-run` still works with a stderr deprecation notice.

### 2. Export tokens to a file

```bash
experiences print tokens --out tokens.json
```

This writes the generated DTCG tokens from the session database to a JSON file. The file is used in subsequent steps.

### 3. Validate tokens (optional)

```bash
experiences print validate --tokens tokens.json
```

This validates your token file against the DTCG schema and reports any structural issues before you push to Contentful.

### 4. Preview changes

```bash
experiences apply preview \
  --space-id $CONTENTFUL_SPACE_ID \
  --environment-id $CONTENTFUL_ENVIRONMENT_ID \
  --tokens tokens.json
```

This displays a diff of what tokens will be created or updated in your Contentful space without making any changes.

### 5. Push tokens to Contentful

```bash
experiences apply push \
  --space-id $CONTENTFUL_SPACE_ID \
  --environment-id $CONTENTFUL_ENVIRONMENT_ID \
  --tokens tokens.json
```

This sends your generated tokens to Contentful in a single batch operation.

Additional options:

* `--yes` — Skip the interactive confirmation prompt.
* `--verbose` — Display detailed push output.
* `--force` — Skip confirmation for breaking changes (for CI pipelines).

> **Info**
>
> Running `apply push` again after updating your token values creates or updates
> existing tokens. Tokens that you remove from the source file are not deleted
> by default. To opt into deletion, pass `--allow-deletions` to `experiences
>   apply push`.

## Include tokens with component generation

When generating component definitions, pass your tokens file so the AI agent can resolve token-linked properties:

```bash
experiences generate components --agent claude --tokens tokens.json
```

This allows the agent to map component design properties to specific token values (for example, a `backgroundColor` property that accepts tokens from the `color` group).

## Verify in Contentful

Design tokens are surfaced on the components that reference them.

1. Log in to the [Contentful web app](https://app.contentful.com).
2. Navigate to your space and environment.
3. Go to **Design system > Components** and open a component — the tokens it references appear on its design properties (color, spacing, typography, and so on).

## Token format

The CLI produces tokens in [W3C Design Token Community Group (DTCG) format](https://www.designtokens.org/tr/drafts/format/) — a JSON structure that organizes tokens into nested groups with `$value` and `$type` fields:

```json
{
  "color": {
    "primary": {
      "$value": "#1890ff",
      "$type": "color"
    },
    "text": {
      "heading": {
        "$value": "#262626",
        "$type": "color"
      }
    }
  }
}
```

Each token has a type that determines which Design Properties it can be applied to in the experience editor.

## Supported token types

The CLI validates tokens against the [W3C DTCG specification](https://www.designtokens.org/tr/drafts/format/#types) type system. The following types are supported:

| **Type**      | **Description**                                                                               |
| ------------- | --------------------------------------------------------------------------------------------- |
| `color`       | Any color value (hex, rgb, hsl)                                                               |
| `dimension`   | Size values with units (spacing, sizing, radii)                                               |
| `fontFamily`  | Font family names                                                                             |
| `fontWeight`  | Font weight values (numeric or named)                                                         |
| `duration`    | Time values for animations and transitions                                                    |
| `cubicBezier` | Cubic bezier easing curves                                                                    |
| `number`      | Unitless numeric values                                                                       |
| `strokeStyle` | Border/stroke style keywords                                                                  |
| `border`      | Composite border values (width + style + color)                                               |
| `transition`  | Composite transition values (duration + delay + easing)                                       |
| `shadow`      | Box shadow values                                                                             |
| `gradient`    | Gradient values                                                                               |
| `typography`  | Composite typography values (fontFamily + fontSize + fontWeight + lineHeight + letterSpacing) |