Skip to main contentCarbon Design System

Carbon MCP

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

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 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.”

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
  • 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”).
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

Sample prompts

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

It is helpful to be as detailed as possible in your user prompts when describing the code you want generated.

  • 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
  • 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.)
  • 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
Edit this page on GitHub
Previous
Carbon MCP: Onboarding and setup
Next
Developing: Developer resources