DESIGN.md — Carbon Design System (IBM)

Design System

Name: Carbon Design System Maintainer: IBM Version: v11 (current) Target platforms: Web (React primary; also Web Components, Angular, Vue community libs) Audience: Enterprise product teams; IBM digital products

Color

Color model: IBM Design Language palette (flat step scale per hue, 10–100) Themes: 4 built-in — White, Gray 10 (light); Gray 90, Gray 100 (dark) Default theme: White

Primary action color: Blue 60 (#0f62fe) — used for interactive elements, focus rings, links Background model: Neutral gray dominant; blue accent; alert colors (red, orange, yellow, green) used sparingly

Token naming convention

$background               → page background
$layer-01                 → first layered surface above background
$layer-02                 → second nested layer
$text-primary             → primary body text
$text-secondary           → labels and supporting text
$border-subtle            → light dividers
$border-strong            → pronounced borders
$interactive              → interactive default (= blue-60)
$focus                    → focus ring (= blue-60)
$support-error            → error state (= red-60)
$support-success          → success state (= green-50)
$support-warning          → warning state (= yellow-30)
$support-info             → info state (= blue-70)

Layering model

Light themes alternate White ↔ Gray 10 per layer. Dark themes step one shade lighter per layer (Gray 100 → 90 → 80 → 70).

Interaction states

Hover tokens exist as "half-step" values between adjacent palette steps (e.g. $layer-hover). States: hover, focus, active, selected, disabled. Disabled states use opacity (text 38%, bg 12%) rather than separate palette values.

Typography

Typeface: IBM Plex (open source)

Sans: 'IBM Plex Sans', 'Helvetica Neue', Arial, sans-serif
Serif: 'IBM Plex Serif', Georgia, Times, serif
Mono: 'IBM Plex Mono', Menlo, 'DejaVu Sans Mono', Courier, monospace

Type sets: Two parallel sets — Productive (fixed size, dense, task-focused) and Expressive (responsive, editorial). Body/utility styles shared; productive uses -01 suffix, expressive uses -02.

Type token categories:

Category	Token examples	Use context
Display	`display-01` – `display-04`	Hero / editorial largest type
Expressive Headings	`expressive-heading-01` – `06`	Responsive editorial headings
Productive Headings	`productive-heading-01` – `07`	Fixed-size product headings
Body	`body-short-01/02`, `body-long-01/02`	Running text
Label / Helper / Caption	`label-01/02`, `helper-text-01/02`, `caption-01/02`	Form support, captions
Code	`code-01`, `code-02`	Monospaced code

Each token defines: font-family, font-size, font-weight, line-height, letter-spacing.

Spacing

Scale: Spacing01–Spacing13 (2px to 96px base-2 progression)

spacing-01: 2px
spacing-02: 4px
spacing-03: 8px
spacing-04: 16px
spacing-05: 24px
spacing-06: 32px
spacing-07: 40px
spacing-08: 48px
spacing-09: 64px
spacing-10: 80px
spacing-11: 96px
spacing-12: 160px
spacing-13: 192px

Container and icon size tokens also provided (container-01 – container-05, size-xsmall – size-2xlarge, icon-size-01/02).

Shape

No dedicated shape token system (Carbon does not use a named border-radius scale). Components use hardcoded corner values:

Most components: 0px (square by default)
Buttons: 0px (square)
Tags / pills: full radius (9999px)
Modals: 0px
Notifications: 0px
Tooltips: 2px

If adapting Carbon for a branded system, border-radius customization is done at the component level via Sass overrides, not a centralized shape token.

Token Architecture

Tiers: 2 tiers (not 3)

Primitive palette — @carbon/colors package; flat hex values per hue+step (e.g. blue60, gray10)
Semantic/role tokens — @carbon/themes package; maps primitives to roles per theme (e.g. $layer-01 = gray10 in White theme)

No component-tier tokens in the sense of M3's component system — component-specific tokens exist but are defined in the component source, not a published component token layer.

Implementation: Sass $variable tokens (prefix $). CSS custom properties exposed as --cds-* via the compiled stylesheet.

Component Model

Primitive component library: @carbon/react Component API: Prop-based; no slot/composition model like Web Components State handling: Interactive states handled via Sass token mixins; no runtime CSS-in-JS Icon system: @carbon/react/icons — ~2500+ icons from the IBM iconography set

Component categories

Navigation: Header, Side Nav, Breadcrumb, Tabs, Pagination
Forms: Text Input, Search, Select, Dropdown, Checkbox, Radio, Toggle, Date Picker, File Uploader, Slider, Number Input
Actions: Button, Link
Notifications: InlineNotification, ToastNotification, ActionableNotification
Overlays: Modal, ComposedModal, Popover, Tooltip, Overflow Menu
Data: DataTable (sortable, expandable, selectable), StructuredList, Accordion
Media: ProgressBar, Loading, SkeletonText, SkeletonPlaceholder
Content: Tile, ClickableTile, ExpandableTile, Tag, Badge

Installation

npm install --save @carbon/react

// Include all Carbon styles in root stylesheet
@use '@carbon/react';

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

Build requirement: Sass compiler required. Works with Next.js, Vite, Webpack, Parcel.

Theming at setup:

@use '@carbon/react/scss/themes';
@use '@carbon/react/scss/theme' with (
  $theme: themes.$g100   // or $white, $g10, $g90
);