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

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

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

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

Include tokens with Component Type generation

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

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