Carbon Design System
Build UIs conforming to IBM's Carbon Design System v11. Carbon provides a token-based, accessible, enterprise-grade component library.
Rendering Context
Determine the output target before writing code.
HTML Artifacts (no build pipeline)
Use pre-built CSS via CDN. Add to
:
html
<link rel="stylesheet" href="https://unpkg.com/@carbon/styles/css/styles.css" />
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans:wght@300;400;600&family=IBM+Plex+Mono:wght@400;600&display=swap" />
Apply Carbon classes to HTML elements. See
references/html-classes.md
.
React Artifacts
is not in Claude's default artifact environment. For React artifacts, load the CDN CSS above and apply Carbon class names to standard HTML/JSX elements. The visual output is identical.
Full Projects (file creation)
bash
npm install @carbon/react sass
jsx
import { Button } from '@carbon/react';
// Styles: @use '@carbon/react'; in root SCSS
Requires Dart Sass. All styles, components, icons ship in the single
package.
Design Foundations
Typography
Always use IBM Plex. Never substitute.
| Role | Family | Weights |
|---|
| Body, UI | IBM Plex Sans | 300, 400, 600 |
| Code | IBM Plex Mono | 400, 600 |
| Editorial | IBM Plex Serif | 300, 400, 600 |
Color Themes
| Theme | Background | Context |
|---|
| White | | Default light |
| g10 | | Subtle light |
| g90 | | Dark |
| g100 | | High-contrast dark |
Primary action: Blue 60
. See
for full palette.
Spacing
8px base grid, 2px mini-unit. Component spacing: 2, 4, 8, 12, 16, 24, 32, 40, 48 px. Layout spacing: 16, 24, 32, 48, 64, 96, 160 px.
2x Grid
| Breakpoint | Width | Columns | Margin |
|---|
| sm | 320px | 4 | 0 |
| md | 672px | 8 | 16px |
| lg | 1056px | 16 | 16px |
| xlg | 1312px | 16 | 16px |
| max | 1584px | 16 | 24px |
Grid classes:
,
,
,
,
,
.
Motion
| Token | Duration | Use |
|---|
| fast-01 | 70ms | Micro-interactions |
| fast-02 | 110ms | Toggle, expand |
| moderate-01 | 150ms | Buttons, fields |
| moderate-02 | 240ms | Modal, dropdown |
| slow-01 | 400ms | Page transitions |
| slow-02 | 700ms | Complex choreography |
Standard easing:
cubic-bezier(0.2, 0, 0.38, 0.9)
. Entrance:
cubic-bezier(0, 0, 0.38, 0.9)
. Exit:
cubic-bezier(0.2, 0, 1, 0.9)
.
References
- Component HTML classes and usage:
references/html-classes.md
- Full design token values:
Read the appropriate reference when building specific components or when exact token values are needed.
Implementation Checklist
- IBM Plex loaded (Sans minimum; Mono for code)
- Theme class applied: , , , or
- Correct prefix: (v11). Never (v10 legacy)
- Grid layout: > >
- Spacing from scale only — no arbitrary pixel values
- Focus states preserved — 2px blue outline
- Color by role via tokens, not raw hex
- Icons at Carbon sizes: 16, 20, 24, 32px
Common Patterns
Page Shell
html
<div class="cds--white" style="min-height:100vh">
<header class="cds--header" role="banner">
<a class="cds--header__name" href="#">[App Name]</a>
</header>
<div class="cds--grid" style="padding-top:3rem">
<div class="cds--row">
<div class="cds--col-lg-3"><!-- Side nav --></div>
<div class="cds--col-lg-13"><!-- Content --></div>
</div>
</div>
</div>
Theme Nesting
html
<div class="cds--g100"><!-- dark header --></div>
<div class="cds--white"><!-- light body --></div>
Data Dashboard
Combine
containers for metric cards with
for tabular data, all within the 2x grid.
Anti-Patterns
- Non-IBM Plex fonts
- prefix (v10; use for v11)
- Arbitrary border-radius (Carbon: 0px default, 4px for tags/pills only)
- Drop shadows on components that lack them in spec
- Overriding focus ring styles
- Colors outside the Carbon palette
- Spacing values not on the scale