Import design tokens

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. If you have not set up the CLI, start with Installation.

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. 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:

$
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.

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

$
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

$
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

$
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)

$
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

$
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

$
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).

Include tokens with component generation

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

$
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.
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 — a JSON structure that organizes tokens into nested groups with $value and $type fields:

1
{
2
  "color": {
3
    "primary": {
4
      "$value": "#1890ff",
5
      "$type": "color"
6
    },
7
    "text": {
8
      "heading": {
9
        "$value": "#262626",
10
        "$type": "color"
11
      }
12
    }
13
  }
14
}

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 type system. The following types are supported: