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 <head>:
<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
@carbon/react 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)
npm install @carbon/react sassimport { Button } from '@carbon/react';
// Styles: @use '@carbon/react'; in root SCSSRequires Dart Sass. All styles, components, icons ship in the single @carbon/react 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 | #ffffff | Default light |
| g10 | #f4f4f4 | Subtle light |
| g90 | #262626 | Dark |
| g100 | #161616 | High-contrast dark |
Primary action: Blue 60 #0f62fe. See references/tokens.md 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: cds--grid, cds--row, cds--col, cds--col-sm-N, cds--col-md-N, cds--col-lg-N.
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:
references/tokens.md
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:
cds--white,cds--g10,cds--g90, orcds--g100 - Correct prefix:
cds--(v11). Neverbx--(v10 legacy) - Grid layout:
cds--grid>cds--row>cds--col-* - 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
<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
<div class="cds--g100"><!-- dark header --></div>
<div class="cds--white"><!-- light body --></div>Data Dashboard
Combine cds--tile containers for metric cards with cds--data-table for tabular data, all within the 2x grid.
Anti-Patterns
- Non-IBM Plex fonts
bx--prefix (v10; usecds--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