> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://contentful.com/developers/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server.

# Getting started

> End-to-end walkthrough of a happy-path design system import — setup, project extraction, design tokens, review, and push.

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

```bash
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:

```bash
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:

```bash
experiences setup
```

## Step 3: Start the import wizard

From any directory, run:

```bash
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.](/developers/docs/_fern-img/4bec19141d1910f2a114b36d7bb043f9e54f73af5e9a4e831efbdfc78df8ef66.webp)

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.](/developers/docs/_fern-img/fe12681531355d1f7e95bde53ec165d4c0d07e528fdf80b9435870bcf5de33c4.webp)

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](https://www.designtokens.org/tr/drafts/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.](/developers/docs/_fern-img/3ee5b6b8de9f9d7f23f5240cc2794152277a99f2e74edc3e9488c583dcaa03a1.webp)

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.](/developers/docs/_fern-img/6d74418b89f50321d859e8f7c1db49195ff0782697f1b504cedefed243a17533.webp)

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.](/developers/docs/_fern-img/34894f4a7de8320da9aabd1470c2cad2cf00d4327e8142efe5d9f51903d48ada.webp)

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.](/developers/docs/_fern-img/71d87fb14fa6e0c74230237e5f54123c6ef2fa79f522cf4b8d09d7417c42b525.webp)

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).](/developers/docs/_fern-img/5f7162df10e1443a11151f269458108fc1e3ff6ce0c4e7e6b7539ad1f22177d8.webp)

> **Warning**
>
> 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](https://app.contentful.com).
2. Navigate to your space and environment.
3. Go to **Design system > Components** to see the imported components.

## What next

* **[Import components](/experience-orchestration/import-components)** — Deep-dive on the wizard's flow, the scope gate, and the Final review step.
* **[Import design tokens](/experience-orchestration/import-design-tokens)** — Details on token formats and the token classification step.
* **[Coded components](/experience-orchestration/coded-components)** — Preserve embedded-component hierarchies with composite mode.
* **[Run history and replay](/experience-orchestration/run-history)** — Push a recorded run again, or re-open one for edits.
* **[Command reference](/experience-orchestration/command-reference)** — Every flag on every subcommand.
* **[FAQ](/experience-orchestration/faq)** — Behaviors that surprise operators the first time through.