Import design system

Getting started

This page shows the shortest path from your codebase to components in Contentful. For details on each screen, see Import flow.

Prerequisites

  • Node.js 24+ and pnpm 10.27+
  • A coding agent that is installed and signed in. The CLI supports Claude Code, Codex, OpenCode, and Cursor.
  • A Contentful Management API (CMA) token. Create one in the Contentful web app under Settings > CMA tokens.
  • A component library. React, Vue, Astro, Stencil, and Web Components projects work.

Step 1: Install the CLI

Install the CLI globally so the experiences command works in any directory:

npm install -g @contentful/experience-design-system-cli

Step 2: Set up

Run the setup and follow the prompts. It checks your Node.js and pnpm versions, finds your coding agent, and saves your Contentful credentials.

experiences setup

To check your environment at any time, run experiences doctor.

Step 3: Run the import

Start the import:

experiences import

The import asks for the path to your components and, if you have one, a design tokens file.

The flags are optional. To skip the prompts, pass the paths yourself:

experiences import --project ./src/components --tokens ./tokens.scss
FlagWhat it does
--project <path>Path to your components. Defaults to the current folder.
--tokens <path>Path to a design tokens file (a file, not a folder).

Step 4: Follow the prompts

The import walks you through these screens:

  1. Review excluded components. The agent suggests components to leave out, such as DebugPanel or Portal. Change anything you disagree with, then confirm.
  2. Wait for generation. This takes 2 to 25 minutes, depending on how many components you import.
  3. Review the generated components. Check the properties and slots, and edit anything that looks wrong.
  4. Push. The import saves components.json. Check the summary of what will be created, updated, and skipped, then confirm.

Components that are in Contentful but not in your import are skipped, not deleted.

To learn what each screen does, see Import flow.

Step 5: Check the result in Contentful

Open the link printed at the end of the push. To find your components yourself:

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

Next steps

  • Import flow — Learn what each screen does, and how tokens are mapped to components.
  • Command reference — See every command and flag.
  • FAQ — Find answers to common questions.