---
title: Carbon MCP
tabs: ['Overview', 'Onboarding and setup', 'Prompts', 'Token conservation']
description: User prompt guidance and best practices
---

<PageDescription>

Use the guide below to write effective user prompts to improve AI outcomes for
code generation use cases.

</PageDescription>

<AnchorLinks>
  <AnchorLink>Overview</AnchorLink>
  <AnchorLink>Best practices</AnchorLink>
  <AnchorLink>Prompt starter template</AnchorLink>
  <AnchorLink>Sample prompts</AnchorLink>
</AnchorLinks>

## Overview

A "prompt" is a way to communicate with an AI system using natural language.
Modern AI systems allow for two-way communication between a user and AI. Each
user prompt and corresponding AI response is a "turn".

The size of a prompt (and an AI response) is measured in "tokens" (1 token ≈ 4
characters of English text, including spaces and punctuation). The usage cost
for an AI system is usually in "cost per token".

[Prompt engineering](https://www.ibm.com/think/prompt-engineering) is the act of
communicating with an AI in a way that _minimizes_ the number of tokens and
turns, while _maximizing_ the quality of the code that is generated by the AI.

This guide provides best practices for writing user prompts when using an AI
system that is connected to Carbon MCP.

## Best practices

### Carbon MCP prompt writing — DOs

#### Do clearly describe what you want:

- UI goal + purpose
- Framework: Carbon React v11 / Carbon Web Components v11
- Libraries needed (Core, IBM Products, icons, pictograms)
- Full component list (Grid, Header, Button, Tile, Form, etc.)
- Layout (columns, spacing, alignment, breakpoints)
- Sample data
- Exact file list to output

#### Do tell the AI to use MCP first:

- "Before writing code, call `code_search` for APIs + `docs_search` for usage,
  tokens, accessibility."
- "Before writing code specifically for charts call `get_charts`."

#### Do ask for "high reasoning":

- "Plan step-by-step, validate imports/props, anticipate errors, then output
  final code."

#### Do enforce Carbon fidelity:

- Use Carbon Grid (`Grid`/`Column` or `cds-grid`/`cds-column`)
- Semantic HTML (`h1`, `h2`, `p`, lists) + Carbon typography
- IBM Plex fonts via tokens
- Carbon spacing tokens (`$spacing-03`, `$spacing-05`, etc.)
- Explicitly require necessary SCSS imports

#### Do require accessibility:

- "Apply WCAG 2.2 and Carbon accessibility guidance."
- Keyboard nav, focus order, visible focus, ARIA, high contrast, reduced motion

#### Do conserve tokens:

- "After tool calls, do not restate results. Say 'Received the necessary
  context.'"
- Stop after emitting requested files

#### Do enforce non-negotiables:

- Use `code_search` + `docs_search` first
- For charts use `get_charts` first
- Only Carbon tokens, no ad-hoc values
- Props/variants must exist per `code_search`
- No Tailwind / utility frameworks
- No inline token styles
- Imports must resolve; code must compile on first attempt

### Carbon MCP prompt writing — DON'Ts

#### Don't be vague

- Never say "build a dashboard" without components, layout, data, and files

#### Don't skip MCP calls

- Never let the AI guess props, tokens, or patterns

#### Don't allow non-Carbon styling

- No hard-coded colors or random spacing
- No Tailwind or similar frameworks

#### Don't use inline token styles

- No `style={{ margin: '$spacing-05' }}` or `style="margin: $spacing-05"`

#### Don't restate MCP tool output

- Don't echo `code_search` / `docs_search` results

#### Don't generate extra files

- No tests, no README, no extras unless explicitly requested

#### Don't accept invented APIs

- Components, props, and variants must come from `code_search` only

## Prompt starter template

Below is a prompt starter template with fill-in-the-blank placeholders that
embodies Carbon MCP prompt best practices. The placeholders are defined as:

- `FRAMEWORK`: A precise name and version of the desired UI stack (e.g., "Carbon
  React v11 (Core only)" or "Carbon Web Components v11 with Carbon for IBM
  Products").
- `APP_DESCRIPTION`: A short but specific description of the UI and purpose
  (e.g., "a single-page MCP marketing landing screen with a hero, three feature
  tiles, and a contact form").
- `COMPONENT_LIST`: The complete list of Carbon components expected in the final
  UI (e.g., "Grid, Column, Header, UIShell, ClickableTile, Button, TextInput,
  Form, ActionBar").
- `FILE_LIST`: The exact minimal set of files that should be generated, with
  names and roles (e.g., "package.json, index.html, src/main.jsx, src/App.jsx,
  src/styles.scss, and nothing else").

```markdown
Mandatory: Use Carbon MCP and the carbon-builder skill to perform the specified
task. Read and confirm the skill protocol before proceeding.

TASK:

You are an expert developer using <FRAMEWORK>. Build <APP_DESCRIPTION> using
<COMPONENT_LIST>.

I. Carbon Design System fidelity:

Before generating code, call the attached Carbon MCP server `code_search` for
<COMPONENT_LIST> used in <FRAMEWORK>. Retrieve variants, required props, and
Storybook links. Then call `docs_search` for usage guidance, tokens,
accessibility requirements, and content patterns. Map all visual and structural
decisions to Carbon tokens (spacing, color, type, motion). Use only tokens
explicitly present in the MCP tool results, with no ad-hoc values. When writing
code, ensure:

- Responsive layout using Carbon's grid system
- Clean, maintainable code with clear separation of concerns
- Include all required peer dependencies for the chosen Carbon components
- Use IBM Plex font via Carbon typography tokens and classes
- All text uses proper semantic HTML (`h1`, `h2`, `h3`, `p`, lists) with Carbon
  typography applied
- **Always include these required SCSS imports in your stylesheet**:
  `@use '@carbon/styles/scss/themes' as *; @use '@carbon/styles/scss/theme' with ($theme: $white); @use '@carbon/styles'; @use '@carbon/styles/scss/spacing' as *; @use '@carbon/styles/scss/type' as *;`
- **Do not use inline style props** with token strings such as:
  - React: `style={{ margin: '$spacing-05' }}`
  - Web Components: `style="margin: $spacing-05"`
- **Instead**, when layout spacing or alignment is required:

  a. Create small utility classes in `src/styles.scss` (for example,
  `.page-section { padding-block: $spacing-07; }`,
  `.tiles-row { gap: $spacing-05; }`).

  b. Use only Carbon spacing tokens (`$spacing-03`, `$spacing-05`,
  `$spacing-07`, etc.).

  c. Apply these classes using `className` in React or `class` in Web
  Components.

- This ensures spacing and alignment are driven strictly by **Carbon tokens and
  SCSS**, never ad-hoc inline values.
- When implementing UI Shell Header, always import and use the Content component
  to wrap all page content below the header. This prevents the fixed-position
  header from overlapping page content.

II. Use "high reasoning":

- Plan the implementation step-by-step (structure, imports, accessibility, token
  usage).
- Cross-check component usage with `code_search` and guidance from
  `docs_search`.
- Anticipate compile/runtime errors and preemptively resolve them.
- Only then output the final, build-ready code once all reasoning steps are
  complete.

III. Token and cost conservation:

- After calling `code_search` or `docs_search`, do not restate or summarize
  results—this increases token usage.
- After tool calls, simply state: **"Received the necessary context."**
- Generate only <FILE_LIST>, with no additional files (no tests, README, or
  extra configs).
- Stop after emitting the requested files.

IV. Fully accessible & WCAG 2.2 compliant:

- From `docs_search`, obtain accessibility and content patterns.
- Apply WCAG 2.2 and Carbon accessibility guidance: keyboard support, logical
  focus order, visible focus, screen reader roles/states, name/role/value
  semantics, adequate hit targets, error messaging, and reduced-motion
  fallbacks.
- Use valid color contrast via Carbon tokens only.

V. NON-NEGOTIABLES:

- Use `code_search` + `docs_search` first, then write code
- Tokens must match `docs_search` guidance; no arbitrary values
- Props and variants must exist per `code_search`
- Only Carbon tokens; minimal overrides
- WCAG 2.2 baked in from the beginning
- No Tailwind or utility frameworks
- All required Carbon SCSS imports included
- Imports must resolve and code must run on first attempt
```

## Sample prompts

Use the sample user prompts below as inspiration, or as a starting point for
customization for your specific AI code generation task.

<InlineNotification kind="info">
  It is helpful to be as **detailed** as possible in your user prompts when
  describing the code you want generated.
</InlineNotification>

<Accordion>
  <AccordionItem title="Example 1: Generating code with Carbon React (Core) components">

```markdown
Mandatory: Use Carbon MCP and the carbon-builder skill to perform the specified
task. Read and confirm the skill protocol before proceeding.

TASK:

You are an expert front-end developer using Carbon React v11. Build a **minimal
runnable project** that renders a small **UI Shell header** and **three
clickable tiles** in a simple grid. Each tile should have a short heading and
one realistic placeholder line. Each tile should be the same height and should
discuss a benefit of the MCP protocol. Above the tiles should be a header "MCP
(Model Context Protocol)". Add adequate space between the topmost header and the
tiles. Under the tiles, add a "Request more information" form that captures
pertinent information for the user. Add a **primary button** to "learn more".
The tiles should be on the same row and be of equal height. The tiles should not
span more than 15 columns, and the form should not span more than 10 columns.
The headers, button, and form fields should all be left aligned to match the
left alignment of leftmost tile, and have adequate space between fields and the
button. Use appropriate padding, spacing, etc.

a. Output only the minimal files needed to run locally with **Vite** (no
narration):

- **package.json** with dependencies: `react`, `react-dom`,
  `@carbon/react`,`@carbon/styles`, `sass`, `vite`. Provide `"scripts"` for
  `"dev"`, `"build"`, `"preview"`.
- Ensure the package.json includes all dependencies needed for the components to
  compile without errors.
- **index.html** with a root `<div id="root"></div>`
- **src/main.jsx** that mounts `<App />` to `#root` and imports `./styles.scss`.
- **src/App.jsx** that renders components in a simple responsive grid (e.g.,
  Carbon `Grid`/`Column` or a lightweight flex container)
- **src/styles.scss** that uses Carbon Sass (no precompiled CSS). Set a default
  theme and include Carbon styles.

b. Sass rules for **src/styles.scss** (no other CSS files):

@use '@carbon/styles/scss/themes' as _; @use '@carbon/styles/scss/theme' with
($theme: $white); @use '@carbon/styles'; @use '@carbon/styles/scss/spacing' as
_;

I. Carbon Design System usage:

Before generating code, call the attached Carbon MCP server `code_search` for
Carbon React components (`ClickableTile`, `Button`), and `UI Shell` header
components (`Header`, `HeaderName`, `Content`) in Carbon Core. Retrieve
variants, required props, and Storybook links. Then call `docs_search` for
usage, tokens, and content patterns. Map all visual choices to Carbon tokens
(spacing, color, type, motion). Use only tokens explicitly present in the search
results, without ad-hoc values. When writing code, ensure:

- Responsive layout using Carbon's grid system
- Clean, maintainable code with separation of concerns
- Include all required peer dependencies for Carbon React components, including
  icons, pictograms, etc.
- Use IBM Plex font via Carbon typography tokens and classes
- All text must use proper semantic HTML (`h1`, `h2`, `h3`, `p`) with Carbon
  typography applied
- **Always include these required SCSS imports in your stylesheet**:
  `@use '@carbon/styles/scss/themes' as *; @use '@carbon/styles/scss/theme' with ($theme: $white); @use '@carbon/styles'; @use '@carbon/styles/scss/spacing' as *; @use '@carbon/styles/scss/type' as *;`
- **Do not use inline style props** with string token names such as
  `style={{ margin: '$spacing-05' }}` for React, or
  `style="margin: $spacing-05"` for Web Components
- **Instead**, when layout spacing or alignment is required (e.g., to align
  tiles, headers, or forms): a. Create small utility classes in
  `src/styles.scss` (e.g., `.page-section { padding-block: $spacing-07; }`,
  `.tiles-row { gap: $spacing-05; })` b. Use only Carbon spacing tokens
  (`$spacing-03`, `$spacing-05`, `$spacing-07`, etc.) inside these classes c.
  Apply those classes via `className` in React (or `class` in Web Components)
- This ensures alignment and spacing are achieved **with Carbon tokens and SCSS,
  not ad-hoc inline values**
- When implementing UI Shell Header, always import and use the Content component
  to wrap all page content below the header. This prevents the fixed-position
  header from overlapping page content.

II. Use "high reasoning":

- Plan the implementation step-by-step (structure, imports, accessibility,
  tokens).
- Cross-check component usage with `code_search` and design guidance from
  `docs_search`.
- Anticipate compile or runtime errors and fix them preemptively.
- Only then output the final, build-ready code once reasoning is complete.

III. Token and cost conservation:

- After querying `code_search` or `docs_search` for context, don't restate or
  summarize what was returned from the Carbon MCP tool as this drives up the
  cost of usage.
- Upon successfully receiving the needed context that you queried for, simply
  state "Received the necessary context", and make use of the context as
  necessary.
- Do not write extra files (no tests, no README).
- Stop after emitting the files.

IV. Fully accessible & WCAG 2.2 compliant:

- From `docs_search`, get accessibility guidance and content patterns.
- Apply WCAG 2.2 and Carbon accessibility guidance to create an accessible
  implementation. Ensure keyboard support, screen reader support, focus order,
  visible focus, ARIA roles, states, name/role/value, hit targets, error
  messaging, and motion-reduction fallbacks, etc. Use valid color contrast via
  Carbon tokens.

V. NON-NEGOTIABLES:

- Use `code_search` + `docs_search` first, then write code
- Tokens match `docs_search` guidance; no arbitrary values
- Props/variants exist per `code_search`
- Carbon tokens only; minimal overrides
- WCAG 2.2 baked in
- No Tailwind or utility class frameworks; include Carbon SCSS imports
- Imports resolve; code compiles on first run
```

</AccordionItem>

<AccordionItem title="Example 2: Generating code with both Carbon React (Core + IBM Products)">

```markdown
Mandatory: Use Carbon MCP and the carbon-builder skill to perform the specified
task. Read and confirm the skill protocol before proceeding.

TASK:

You are an expert front-end developer using Carbon React v11 (Core) and Carbon
for IBM Products. Build a small, yet complete Carbon React "Hello world" landing
page for a bank that demonstrates:

- Proper use of Carbon React components (e.g., `Grid`, `Header`, etc.)
- Proper use of Carbon for IBM Products React components (e.g., `ActionBar`,
  `ComboButton`, etc.)
- Realistic placeholder data for accounts, transactions, and user profile

a. Output only the minimal files needed to run locally with **Vite** (no
narration):

- **package.json** with dependencies: `react`, `react-dom`, `@carbon/react`,
  `@carbon/styles`, `sass`, `vite`. Provide `"scripts"` for `"dev"`, `"build"`,
  `"preview"`.
- Ensure the package.json includes all dependencies needed for the components to
  compile without errors.
- **index.html** with a root `<div id="root"></div>`
- **src/main.jsx** that mounts `<App />` to `#root` and imports `./styles.scss`.
- **src/App.jsx** that renders components in a simple responsive grid (e.g.,
  Carbon `Grid`/`Column` or a lightweight flex container)
- **src/styles.scss** that uses Carbon Sass (no precompiled CSS). Set a default
  theme and include Carbon styles.

b. Sass rules for **src/styles.scss** (no other CSS files):

@use '@carbon/styles/scss/themes' as _; @use '@carbon/styles/scss/theme' with
($theme: $white); @use '@carbon/styles'; @use '@carbon/styles/scss/spacing' as
_;

I. Carbon Design System usage:

Before generating code, call the attached Carbon MCP server `code_search` for
Carbon React components (`ClickableTile`, `Button`) and `UI Shell` header
components (`Header` `HeaderName`, `Content`) in Carbon Core. Retrieve variants,
required props, and Storybook links. Then call `docs_search` for usage, tokens,
and content patterns. Map all visual choices to Carbon tokens (spacing color,
type, motion). Use only tokens explicitly present in the search results, without
ad-hoc values. When writing code, ensure:

- Responsive layout using Carbon's grid system
- Clean, maintainable code with separation of concerns
- Include all required peer dependencies for Carbon React components, including
  icons, pictograms etc.
- Use IBM Plex font via Carbon typography tokens and classes
- All text must use proper semantic HTML (`h1`, `h2`, `h3`, `p`) with Carbon
  typography applied
- **Always include these required SCSS imports in your stylesheet**:
  `@use '@carbon/styles/scss/themes' as *; @use '@carbon/styles/scss/theme' with ($theme: $white); @use '@carbon/styles'; @use '@carbon/styles/scss/spacing' as *; @use '@carbon/styles/scss/type' as *;`
- **Do not use inline style props** with string token names such as
  `style={{ margin: '$spacing-05' }}` for React, or
  `style="margin: $spacing-05"` for Web Components
- **Instead**, when layout spacing or alignment is required (e.g., to align
  tiles, headers, or forms): a. Create small utility classes in
  `src/styles.scss` (e.g., `.page-section { padding-block: $spacing-07; }`,
  `.tiles-row { gap: $spacing-05; })` b. Use only Carbon spacing tokens
  (`$spacing-03`, `$spacing-05`, `$spacing-07`, etc.) inside these classes c.
  Apply those classes via `className` in React (or `class` in Web Components)
- This ensures alignment and spacing are achieved **with Carbon tokens and SCSS,
  not ad-hoc inline values**
- When implementing UI Shell Header, always import and use the Content component
  to wrap all page content below the header. This prevents the fixed-position
  header from overlapping page content.

II. Use "high reasoning":

- Plan the implementation step-by-step (structure, imports, accessibility,
  tokens).
- Cross-check component usage with `code_search` and design guidance from
  `docs_search`.
- Anticipate compile or runtime errors and fix them preemptively.
- Only then output the final, build-ready code once reasoning is complete.

III. Token and cost conservation:

- After querying `code_search` or `docs_search` for context, don't restate or
  summarize what was returned from the Carbon MCP tool as this drives up the
  cost of usage.
- Upon successfully receiving the needed context that you queried for, simply
  state "Received the necessary context", and make use of the context as
  necessary.
- Do not write extra files (no tests, no README).
- Stop after emitting the files.

IV. Fully accessible & WCAG 2.2 compliant:

- From `docs_search`, get accessibility guidance and content patterns.
- Apply WCAG 2.2 and Carbon accessibility guidance to create an accessible
  implementation. Ensure keyboard support, screen reader support, focus order,
  visible focus, ARIA roles, states, name/role/value, hit targets, error
  messaging, and motion-reduction fallbacks, etc. Use valid color contrast via
  Carbon tokens.

V. NON-NEGOTIABLES:

- Use `code_search` + `docs_search` first, then write code
- Tokens match `docs_search` guidance; no arbitrary values
- Props/variants exist per `code_search`
- Carbon tokens only; minimal overrides
- WCAG 2.2 baked in
- No Tailwind or utility class frameworks; include Carbon SCSS imports
- Imports resolve; code compiles on first run
```

</AccordionItem>
<AccordionItem title="Example 3: Generating code with Carbon Web components (Core)">

```markdown
Mandatory: Use Carbon MCP and the carbon-builder skill to perform the specified
task. Read and confirm the skill protocol before proceeding.

TASK:

You are an expert front-end developer using Carbon Web Components (Core). Build
a small, yet complete Carbon Web Components "Hello world" landing page for a
bank that demonstrates:

- Proper use of Carbon Web Components (e.g., `grid`, `heading`, `button`,
  `tile`, etc.)
- Realistic placeholder data for accounts, transactions, and user profile
- Accessibility aligned with Carbon guidance (keyboard/focus order, labels/ARIA,
  contrast via tokens)
- Proper use of native Web Components only (no commingling React, no
  frameworks).

a. Output only the minimal files needed to run locally with **Vite** (no
narration):

- **package.json** with dependencies: `@carbon/web-components`,
  `@carbon/styles`, `sass`, `vite`. Provide `"scripts"` for `"dev"`,`"build"`,
  `"preview"`.
- Ensure the package.json includes all dependencies needed for the components to
  compile without errors.
- **index.html** with a root `<div id="app"></div>` and
  `<script type="module" src="/src/main.js"></script>`.
- **src/main.js** that imports only the used Carbon Web Components and
  `./styles.scss`, then renders the landing markup (you may assign `innerHTML`
  for simplicity).
- **src/styles.scss** that uses Carbon Sass (no precompiled CSS). Set a default
  theme and include Carbon styles.

b. Sass rules for **src/styles.scss** (no other CSS files):

@use '@carbon/styles/scss/themes' as _; @use '@carbon/styles/scss/theme' with
($theme: $white); @use '@carbon/styles'; @use '@carbon/styles/scss/spacing' as
_;

c. Verify the correct Carbon Web Components grid structure by checking the
official documentation and code examples. Ensure cds-grid and cds-column are
used correctly without cds-row (which doesn't exist in Web Components v11).
Include proper container max-width constraints and test the layout renders
correctly.

I. Carbon Design System usage:

Before generating code, call the attached Carbon MCP server `code_search` for
Carbon React components (`ClickableTile`, `Button`) and `UI Shell` header
components (`Header` `HeaderName`, `Content`) in Carbon Core. Retrieve variants,
required props, and Storybook links. Then call `docs_search` for usage, tokens,
and content patterns. Map all visual choices to Carbon tokens (spacing color,
type, motion). Use only tokens explicitly present in the search results, without
ad-hoc values. When writing code, ensure:

- Responsive layout using Carbon's grid system
- Clean, maintainable code with separation of concerns
- Include all required peer dependencies for Carbon React components, including
  icons, pictograms etc.
- Use IBM Plex font via Carbon typography tokens and classes
- All text must use proper semantic HTML (`h1`, `h2`, `h3`, `p`) with Carbon
  typography applied
- **Always include these required SCSS imports in your stylesheet**:
  `@use '@carbon/styles/scss/themes' as *; @use '@carbon/styles/scss/theme' with ($theme: $white); @use '@carbon/styles'; @use '@carbon/styles/scss/spacing' as *; @use '@carbon/styles/scss/type' as *;`
- **Do not use inline style props** with string token names such as
  `style={{ margin: '$spacing-05' }}` for React, or
  `style="margin: $spacing-05"` for Web Components
- **Instead**, when layout spacing or alignment is required (e.g., to align
  tiles, headers, or forms): a. Create small utility classes in
  `src/styles.scss` (e.g., `.page-section { padding-block: $spacing-07; }`,
  `.tiles-row { gap: $spacing-05; })` b. Use only Carbon spacing tokens
  (`$spacing-03`, `$spacing-05`, `$spacing-07`, etc.) inside these classes c.
  Apply those classes via `className` in React (or `class` in Web Components)
- This ensures alignment and spacing are achieved **with Carbon tokens and SCSS,
  not ad-hoc inline values**
- When implementing UI Shell Header, always import and use the Content component
  to wrap all page content below the header. This prevents the fixed-position
  header from overlapping page content.

II. Use "high reasoning":

- Plan the implementation step-by-step (structure, imports, accessibility,
  tokens).
- Cross-check component usage with `code_search` and design guidance from
  `docs_search`.
- Anticipate compile or runtime errors and fix them preemptively.
- Only then output the final, build-ready code once reasoning is complete.

III. Token and cost conservation:

- After querying `code_search` or `docs_search` for context, don't restate or
  summarize what was returned from the Carbon MCP tool as this drives up the
  cost of usage.
- Upon successfully receiving the needed context that you queried for, simply
  state "Received the necessary context", and make use of the context as
  necessary.
- Do not write extra files (no tests, no README).
- Stop after emitting the files.

IV. Fully accessible & WCAG 2.2 compliant:

- From `docs_search`, get accessibility guidance and content patterns.
- Apply WCAG 2.2 and Carbon accessibility guidance to create an accessible
  implementation. Ensure keyboard support, screen reader support, focus order,
  visible focus, ARIA roles, states, name/role/value, hit targets, error
  messaging, and motion-reduction fallbacks, etc. Use valid color contrast via
  Carbon tokens.

V. NON-NEGOTIABLES:

- Use `code_search` + `docs_search` first, then write code
- Tokens match `docs_search` guidance; no arbitrary values
- Props/variants exist per `code_search`
- Carbon tokens only; minimal overrides
- WCAG 2.2 baked in
- No Tailwind or utility class frameworks; include Carbon SCSS imports
- Imports resolve; code compiles on first run
```

</AccordionItem>
</Accordion>