Skip to content

Carbon Design System: IBM's open source components, themes and kits

Better Design

Direct answer

The Carbon Design System is IBM's open source design system: React and web components, Sass styles, design tokens, icons and Figma kits, built on the IBM Design Language. This guide covers its principles, components and patterns, accessibility, themes, grid, charts and setup, from Carbon's own site and GitHub repository.

A hand-drawn browser window with Carbon Design System written in it and a short list of what it does.

Carbon is IBM's open source design system for products and digital experiences

Carbon is built on the IBM Design Language. It includes working code, design tools and resources, human interface guidelines and a community of contributors. IBM funds and develops it for its own business needs, and makes it open source for anyone to use and contribute to. The main repository is licensed under Apache 2.0.

The name comes from the element. Carbon forms complex structures from simpler compounds, and in the same way simple components combine into complex designs.

Carbon is not a single library. It is a foundation that several systems extend. Carbon Core provides foundations, components, patterns and code, with guidance on how to design and build with them. Carbon for Products adds components, styling and guidance for IBM software products, all built with React. Every expression shares the IBM Design Language, universal components and accessibility standards.

Five principles guide every Carbon component

Carbon's About page lists five guiding principles:

  • Carbon is open. Its users are also its makers, and everyone is encouraged to contribute.
  • Carbon is inclusive. It is designed and built to be accessible to all, regardless of ability or situation.
  • Carbon is modular and flexible. Components work with each other in whatever combination the user needs.
  • Carbon puts the user first. It rests on research into what real users need.
  • Carbon builds consistency. Every element was designed from the ground up to work together, for cohesive user experiences.

Carbon's main packages

@carbon/react
What it holds

React components and styles

Use it for

Building a React app with Carbon

@carbon/web-components
What it holds

Standards-based web components

Use it for

Any framework or plain HTML

@carbon/styles
What it holds

Sass styles for Carbon components

Use it for

Styling web components or your own markup

@carbon/themes
What it holds

Theme tokens for the color systems

Use it for

White, Gray 10, Gray 90 and Gray 100

@carbon/icons
What it holds

Icon assets and framework packages

Use it for

Icons in React, Vue or SVG

@carbon/grid
What it holds

Layouts built on Carbon's grid

Use it for

Page layout

@carbon/layout
What it holds

Layout units and spacing scale tokens

Use it for

Consistent spacing

@carbon/type
What it holds

Type tokens

Use it for

Type that pairs with IBM Plex

@carbon/motion
What it holds

Productive and expressive motion curves

Use it for

Animation timing

Components solve one UI problem each, and patterns combine them

Each Carbon component is designed and coded to solve one specific UI problem, such as a list of options, a form submission or user feedback. The components are designed to work together as parts of a greater whole. The catalog runs from Accordion, Button and Checkbox to Data table, Date picker, Modal, Notification, Tabs, Tile, Tree view and the UI shell. It also has an AI label for AI-generated content.

Patterns are different. A component is already designed, coded and ready to import. A pattern is a best-practice way to reach a user goal, and it usually combines several components with extra design decisions. Because a pattern can be built many ways, Carbon gives example code for only some of them. Its universal patterns include:

  • Dialogs, notifications and loading, for urgent input and system feedback.
  • Forms, filtering and search, for entering data and finding it.
  • Empty states, disabled states and read-only states, for screens and fields with nothing to act on.
  • Global header, which uses the UI shell for navigation within and between products.
  • Login, disclosures, common actions and the text toolbar.

Accessibility is built into Carbon's components and color themes

Carbon components follow the IBM Accessibility Checklist. That checklist is based on WCAG AA, Section 508 and European standards. The Carbon team aims for patterns that every user can perceive, operate and understand, including people who use a screen reader or other assistive technology.

Carbon's color themes aim to comply with the WCAG 2.1 AA guidelines for contrast. If you use the palette correctly, you avoid contrast issues. The accessibility guide also explains how blind, low-vision, color-blind, deaf, physically disabled and cognitively disabled users experience an interface, and what designers should check for each group.

Accessible components are only part of an accessible product. Carbon points teams to the IBM Equal Access Toolkit and the Stark Figma plugin to test the whole experience.

Themes and design tokens change every component at once

Carbon ships four themes: White, Gray 10, Gray 90 and Gray 100. When you install @carbon/react, components use the White theme by default.

A theme is a set of values assigned to tokens. A token is a role-based name, such as $text-primary or $background, that never changes across themes. Only the value changes. For example, $background is White in the White theme and Gray 100 in the Gray 100 theme. Tokens come in four categories: color, spacing, typography and global.

To make another theme the default, configure the Sass theme module with with:

SCSS
@use '@carbon/react/scss/themes';
@use '@carbon/react/scss/theme' with (
  $theme: themes.$g100
);

Make a custom theme by overriding token values

The default theme is a starting point. Change one, some or all of its token values and you get a new theme. You can also add your own tokens in the same map:

SCSS
@use '@carbon/react/scss/theme' with (
  $theme: (
    background: #e2e2e2,
    text-primary: #161616,
    custom-token-01: #000000,
  )
);

The 2x Grid builds every layout from an 8-pixel mini unit

The IBM 2x Grid is the geometry under Carbon's layouts, type and icons. Its base unit is an 8-pixel square called the mini unit. Fluid grids divide space by two, and fixed grids multiply a box size by two. Padding is 16 pixels at all standard breakpoints. Type in @carbon/type is designed to pair with IBM Plex.

Small
Width

320 px (20 rem)

Columns

4

Medium
Width

672 px (42 rem)

Columns

8

Large
Width

1056 px (66 rem)

Columns

16

X-Large
Width

1312 px (82 rem)

Columns

16

Max
Width

1584 px (99 rem)

Columns

16

Carbon Charts covers data visualization

Carbon's data visualization library is Carbon Charts. It groups chart types by intent. Simple charts include area, bar, boxplot, donut, gauge, line, pie, scatter and treemap. Flow charts include alluvial, network and tree diagrams. Spatial charts include circle pack and maps.

Some chart types, such as parallel coordinates and the choropleth map, are marked design only on the overview page. Carbon Charts has its own GitHub repository, a demo site and a Figma kit. Its getting-started tutorials cover vanilla JavaScript, React, Angular and Vue.

Set up Carbon in a React project

IBM maintains React components in @carbon/react. Components need a build pipeline, such as Next.js, Vite, Parcel or Webpack. Install the package, and install Dart Sass too if you compile Carbon styles yourself:

Terminal
npm install @carbon/react
npm install sass

Import the styles, a component and an icon

Add @use '@carbon/react'; to your global stylesheet to include all Carbon styles, or @use '@carbon/react/scss/components/button'; for one component. Then import components from the package, and icons from @carbon/react/icons. TypeScript declarations are included.

React
import { Button } from '@carbon/react';

function MyComponent() {
  return <Button>Example usage</Button>;
}

Carbon Design System in four steps

The four steps, in the order you take them.

A hand-drawn four-step path for Carbon Design System: Install @carbon/react, Import the styles, Pick a theme, Build with components.
  1. Step 1: Install @carbon/react
  2. Step 2: Import the styles
  3. Step 3: Pick a theme
  4. Step 4: Build with components

Use web components with any framework, or with no build step

@carbon/web-components ships standards-based web components as ES modules or through a CDN. They work with other frameworks such as Angular or Ember. With a bundler, install the package with npm i @carbon/web-components, import a component module, and use it like a native HTML tag:

HTML
<cds-dropdown trigger-content="Select an item">
  <cds-dropdown-item value="all">Option 1</cds-dropdown-item>
  <cds-dropdown-item value="cloudFoundry">Option 2</cds-dropdown-item>
  <cds-dropdown-item value="staging">Option 3</cds-dropdown-item>
  <cds-dropdown-item value="dea">Option 4</cds-dropdown-item>
  <cds-dropdown-item value="router">Option 5</cds-dropdown-item>
</cds-dropdown>

Angular, Svelte and Vue packages come from the community

Outside React and web components, the Carbon repository points to community-maintained packages for Angular, Svelte and Vue. The wider Carbon ecosystem also has community packages for IBM teams: Carbon for Cloud, Carbon for AEM for IBM.com and marketing sites, Carbon for IBMer Experience for internal tools, Carbon for Salesforce and Carbon React Native for mobile apps.

Carbon for AI marks AI-generated content

Carbon for AI extends Carbon to give AI features in IBM products a distinct look and behavior. It adds guidelines, new color and style tokens, and components such as the AI label, an AI chat framework and AI variants of Carbon Core components. Its goal is transparency and explainability.

Carbon also offers Carbon MCP. It lets AI applications and agents query Carbon for colors, typography, component details and usage guidelines. Designers work in Figma, where IBM maintains the Carbon design kits.

Things to know before you adopt Carbon

  • Install the peerDependencies of @carbon/react, or you get errors.
  • Components use the White theme until you configure another one in Sass.
  • The Angular, Svelte and Vue packages are community-maintained, not part of the main repository.
  • @carbon/react collects de-identified metrics through IBM Telemetry. Installing it means you agree to that collection, and its README explains how to opt out.
  • Carbon is the digital expression of the IBM brand. Custom tokens change the look, but the system stays built on the IBM Design Language.

Steal this workflow

Run this guide in your own assistant. The prompt carries the guide link and the workflow summary, so the assistant can adapt it to your project.

Read the guide "Carbon Design System: IBM's open source components, themes and kits" at https://better-design.com/blog/carbon-design-system and help me apply it to my project.

The Carbon Design System is IBM's open source design system: React and web components, Sass styles, design tokens, icons and Figma kits, built on the IBM Design Language. This guide covers its principles, components and patterns, accessibility, themes, grid, charts and setup, from Carbon's own site and GitHub repository.

Start by asking what I am building and which tools I use. Then walk me through the workflow step by step, adapted to my answers.

Claude and ChatGPT open with the prompt filled in. Gemini copies the prompt to your clipboard first, so paste it when the app opens.

Questions

Who makes the Carbon Design System?

IBM. Carbon is IBM's open source design system, licensed under Apache 2.0, with a community of contributors.

Which frameworks does Carbon support?

IBM maintains React and web components. Community packages cover Angular, Svelte and Vue.

What themes does Carbon have?

Four: White, the default, plus Gray 10, Gray 90 and Gray 100. You can override token values to make your own.

Is Carbon accessible?

Carbon components follow the IBM Accessibility Checklist, which is based on WCAG AA, Section 508 and European standards. Its color themes aim for WCAG 2.1 AA contrast.

Does Carbon have charts?

Yes. Carbon Charts provides simple, flow and spatial chart types, with tutorials for vanilla JavaScript, React, Angular and Vue.

Where these Carbon Design System facts come from

Each fact comes from the pages listed here, read on November 15, 2026. Products change, so check those pages for the current version.

Build the interface in your own code instead

A coding agent such as Claude Code, Cursor or Codex can build your interface in your own code. Better Design gives that agent a design system, interface principles and review rules, so the result looks designed.