Skip to navigation
Import design system

Getting started

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

Step 2: Run the setup wizard

experiences setup checks your Node.js and pnpm versions and lets you set your preferred coding-agent:

experiences setup

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’s component library’:

? Project path: ~/projects/my-design-system/src/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: Review the filtered components

Once extraction finishes, you can review AI-recommended exclusions, i.e. components that may be irrelevant to your Experiences. This is where you decide which components make it into Contentful.

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,and Portal for exclusion — component wrappers with no authorable UI. Review its call, override anything you disagree with, and confirm.

Step 6: 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 7: Save and push

The wizard prompts you to save components.json and tokens.json to disk, push to your Contentful space, or do both.

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.

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

What next