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.

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
| Package | What it holds | Use it for |
|---|---|---|
@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:
@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:
@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.
| Breakpoint | Width | Columns |
|---|---|---|
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:
npm install @carbon/react
npm install sassImport 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.
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.

- Step 1: Install @carbon/react
- Step 2: Import the styles
- Step 3: Pick a theme
- 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:
<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.
- Carbon: carbondesignsystem.com
- Carbon: About Carbon
- Carbon: Themes overview
- Carbon: React framework
- Carbon: Web components
- Carbon: Accessibility
- Carbon: Components overview
- Carbon: Patterns overview
- Carbon: 2x Grid
- Carbon: Data visualization
- Carbon: Designing overview
- GitHub: github.com/carbon-design-system/carbon
- GitHub: @carbon/react README
- GitHub: Carbon Charts
Related
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.