Import design system

Getting started

This guide walks you through a full design system import with the interactive wizard, from a fresh machine to seeing your components and design tokens in the Contentful web app. It assumes you have a component library on disk and a Contentful space with Experiences enabled.

If you get stuck at any step, see the FAQ page.

Prerequisites

Before you start, make sure you have:

  • Node.js 24+ and pnpm 10.27+ — Installed on your machine.
  • A coding agent — Installed and authenticated. experiences setup detects Claude Code, OpenAI Codex, OpenCode, and Cursor on your PATH, and offers to install Claude Code, OpenAI Codex, or OpenCode for you if none are found. Cursor must be installed manually.
  • A Contentful Management API (CMA) token — Generate one in the Contentful web app under Settings > API keys > Content management tokens.
  • A component library on disk — Any React, Vue, Astro, Stencil, or Web Components project works. This guide assumes a TypeScript + React library with roughly 10 components, plus a design tokens file.

Step 1: Install the CLI

Clone the SDK and build from source:

$git clone https://github.com/contentful/experience-design-system-sdk-public.git
$cd experience-design-system-sdk-public
$pnpm install
$pnpm build

Link the CLI globally:

$cd packages/experience-design-system-cli
$pnpm link --global

Verify it runs:

$experiences --version

For more detail, see Installation.

Step 2: Run the setup wizard

experiences setup walks you through Node.js and pnpm checks, dependency install, coding-agent detection, credentials, and optional preferences:

$experiences setup

Terminal output from experiences setup showing all six steps completed: Node.js and pnpm checks, install and build, coding-agent detection, Contentful credentials confirmation, and Step 6 optional preferences (auto-filter, EDS_EXTRACT_CONCURRENCY, custom skill prompts, debug logging, NO_COLOR), ending with a "Setup complete" summary.

When prompted for credentials, paste your CMA token and enter your target space ID and environment ID. Setup saves them to ~/.config/experiences/credentials.json so you don’t have to re-enter them on future runs.

Step 3: Start the import wizard

From any directory, run:

$experiences import

The wizard greets you and asks for the path to your component library:

Wizard welcome screen showing the 5-step overview (Extract, Review, Generate, Review generated, Push) and a prompt for the project path.

Point it at your project root:

? Project path: ~/projects/my-design-system

This walkthrough imports components as a flat list, which is the default. If your components embed other components and you want that nesting preserved in Contentful, restart with experiences import --composite. See Coded components.

Step 4: Provide your design tokens

Immediately after you select the project, the wizard prompts for a raw token source file (SCSS, CSS variables, JS/TS, Style Dictionary, or Tailwind config). This is optional — you can skip it 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.

For this walkthrough, provide the path to your tokens file:

? Token path (file or directory): ~/projects/my-design-system/tokens.scss

The wizard classifies the raw variables into W3C DTCG format and includes them in the push alongside your components.

Step 5: Confirm the file scan

The CLI scans your source directory and lists the file types it found. Confirm to start extraction:

Extraction summary: the CLI scanned the project, listed 31 files by type (14 .tsx, 1 .ts, 14 .json design tokens, 2 other ignored), and asks the operator to confirm before starting extraction.

Step 6: Review the scope gate

Once extraction finishes, the wizard shows a scope gate with two sections: AI-recommended exclusions (with the AI’s reasoning shown inline) and Components. This is where you decide which components make it into the manifest.

Scope gate screen with an "AI recommended exclusions" section listing components the agent flagged (DebugPanel, FocusTrap, Portal, SrOnly) alongside its rationale, and a "Components" section listing the remaining candidates with accept/reject markers.

The AI flags things like DebugPanel, FocusTrap, Portal, and SrOnly for exclusion — infrastructure wrappers with no authorable UI. Review its call, override anything you disagree with, and confirm.

Step 7: Enter your Contentful credentials

If experiences setup already saved your credentials, the wizard pre-fills them and you can press Enter to accept. Otherwise, enter your space ID, environment ID, and CMA token.

Generation prefetches in parallel with credential entry, so the credentials step and the generation step overlap.

Step 8: Review the generated components

The wizard opens the Final review step and displays each generated component with its properties and slots. Walk through the list to inspect what the AI produced and tweak property names, types, defaults, or allowed values before push:

Final review field editor for the Card component. The FIELDS panel lists five properties (bordered, elevation, imageUrl, subtitle, title) with their type, category, and required flags, plus one slot (default, required). The elevation row is expanded and shows its enum values (low, high, none). The bottom legend indicates keys to cycle field values, cycle field focus, and exit the row.

For any component in the list, you can also open the AI’s rationale, the raw generated JSON, or the extracted source snippet. A preview banner at the top of the screen tracks what will change in your Contentful space; open the removed-list overlay to see which components will be deleted from Contentful on push:

Final review screen for a Card component. The preview banner at the top summarizes 1 new, 7 changed, 1 removed, 0 breaking. A pop-up overlays the top of the screen showing the removed-components list (CallToAction) that opens when the operator presses [d]. Below, the left sidebar lists all generated components; the main panel shows the component-level rationale explaining why props and slots were kept or excluded.

When you’re satisfied, finalize the review.

Step 9: Save and push

The wizard prompts you to save components.json and tokens.json to disk, push to your Contentful space, or do both. Save-and-push is the default:

Push-decision screen offering three options: Save AND push (default, highlighted), Push only, and Save only.

Before the push commits, the wizard shows a diff summary of what will be created, updated, and removed:

Diff summary at Step 5 of 5, listing 1 component to be created (Button), 7 to be updated (Badge, Card, FocusTrap, Hero, Layout, LoadingSpinner, Section), and 1 to be removed (CallToAction).

Components absent from your manifest are deleted from Contentful on push. Confirm the list of removals in the diff before pushing.

Confirm the push. The wizard reports progress and prints a link to view the result in the Contentful web app:

Success screen showing 1 component created, 7 updated, 1 removed, a server-side confirmation of 9/9 succeeded, the target space and environment, and a link to view the components in the Contentful web app. The wizard also prints the run ID plus copy-ready commands to push or modify this run again later.

Step 10: Verify in Contentful

Follow the URL the wizard printed at the end of the push to jump directly to your imported components. To navigate there manually instead:

  1. Log in to the Contentful web app.
  2. Navigate to your space and environment.
  3. Go to Design system > Components to see the imported components.

Design tokens are surfaced on the components that reference them — open a component to see the tokens it uses on its design properties.

What next