--- system: carbon category: design-md topic: DESIGN.md content_type: design-md status: latest version_label: "v11" retrieved: 2026-05-12 unofficial: true design_md_spec_version: alpha derived_from: - guidance/foundations/color-system@2026-05-12.md - guidance/foundations/typography@2026-05-12.md - guidance/foundations/themes@2026-05-12.md - implementation/getting-started@2026-05-12.md - assets/tokens/colors@2026-05-12.json - assets/tokens/white-theme@2026-05-12.json source_url: https://carbondesignsystem.com tags: [design-md, carbon, ibm, enterprise] --- # 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) 1. **Primitive palette** — `@carbon/colors` package; flat hex values per hue+step (e.g. `blue60`, `gray10`) 2. **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 ```bash npm install --save @carbon/react ``` ```scss // Include all Carbon styles in root stylesheet @use '@carbon/react'; ``` ```tsx import { Button } from '@carbon/react'; ``` **Build requirement:** Sass compiler required. Works with Next.js, Vite, Webpack, Parcel. **Theming at setup:** ```scss @use '@carbon/react/scss/themes'; @use '@carbon/react/scss/theme' with ( $theme: themes.$g100 // or $white, $g10, $g90 ); ```