> This page is for Experience Orchestration.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful-staging.ferndocs.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful-staging.ferndocs.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 Type import. If you have not set up the CLI, start with [Installation](/experience-orchestration/installation).

You also need a **raw token file** — a JSON file containing your design token definitions in any structure. The CLI uses an AI coding agent to convert this file into W3C Design Token Community Group (DTCG) format.

## 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 TUI displays a **Design tokens** step where you can:

* Provide the path to your raw token file (absolute, relative, or `~`-prefixed).
* Press `s` to skip tokens and import only Component Types.

If you provide a token file, the TUI handles generation, preview, and push for tokens alongside your Component Types — no additional commands are needed.

## 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.
* `--dry-run` — Show what the agent would generate without writing to the session.

### 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).
* `--dry-run` — Show what would be pushed without making changes.

> **Info**
>
> Running `apply push` again after updating your token values creates or updates existing tokens. The CLI does not automatically delete tokens that you removed from the source file.

## Include tokens with Component Type generation

When generating Component Type 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 Type design properties to specific token values (for example, a `backgroundColor` property that accepts tokens from the `color` group).

## Verify in Contentful

After pushing, verify that your tokens appear in experiences:

1. Log in to the [Contentful web app](https://app.contentful.com).
2. Navigate to your space and select **Experiences**.
3. Go to an experience or create one.
4. In the editor, navigate to the **Design** sidebar — token-backed values are displayed as selectable options for properties like color, spacing, and typography.

## Token format

The CLI produces tokens in [W3C Design Token Community Group (DTCG) format](https://design-tokens.github.io/community-group/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://design-tokens.github.io/community-group/format/) 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) |