# IBM Carbon — Design System
> IBM's open-source design system. Dense, accessibility-first, IBM Plex type family. The reference for enterprise software.
- **Canonical:** https://uiuxskills.com/library/carbon
- **Source:** https://carbondesignsystem.com
- **Category:** Developer Tools & IDEs
- **Compatible tools:** claude, cursor, lovable, figma-make
- **Coverage:** 81%
- **License:** Apache-2.0
- **Last updated:** 2026-06-09T23:10:58.689Z

---

---
version: alpha
name: Carbon Design System
tagline: Carbon is IBM’s open source design system for products and digital experiences.
description: >-
  IBM's open-source design system for products and digital experiences, built on the IBM Design
  Language.
tone: professional
color-scheme: light
colors:
  primary: "#0F62FE"
  secondary: "#009D9A"
  background: "#F4F4F4"
  surface: "#FFFFFF"
  surface-container: "#E8DAFF"
  surface-bright: "#D0E2FF"
  on-primary: "#FFFFFF"
  on-surface: "#161616"
  outline: "#00B0E0"
  error: "#DA1E28"
  divider: "#E0E0E0"
  link: "#6929C4"
typography:
  display-lg:
    fontFamily: IBM Plex Sans
    fontSize: 3rem
    fontWeight: 600
    lineHeight: "1.25"
    letterSpacing: "-0.02em"
  display-md:
    fontFamily: IBM Plex Sans
    fontSize: 2.25rem
    fontWeight: 600
    lineHeight: "1.25"
    letterSpacing: "-0.01em"
  headline-lg:
    fontFamily: IBM Plex Sans
    fontSize: 1.875rem
    fontWeight: 600
    lineHeight: "1.3"
    letterSpacing: 0em
  headline-md:
    fontFamily: IBM Plex Sans
    fontSize: 1.5rem
    fontWeight: 600
    lineHeight: "1.3"
    letterSpacing: 0em
  headline-sm:
    fontFamily: IBM Plex Sans
    fontSize: 1.25rem
    fontWeight: 600
    lineHeight: "1.4"
    letterSpacing: 0em
  body-lg:
    fontFamily: IBM Plex Sans
    fontSize: 1.5rem
    fontWeight: 400
    lineHeight: "1.5"
    letterSpacing: 0em
  body-md:
    fontFamily: IBM Plex Sans
    fontSize: 1rem
    fontWeight: 400
    lineHeight: "1.5"
    letterSpacing: 0em
  body-sm:
    fontFamily: IBM Plex Sans
    fontSize: 0.875rem
    fontWeight: 400
    lineHeight: "1.5"
    letterSpacing: 0em
  label-md:
    fontFamily: IBM Plex Sans
    fontSize: 0.875rem
    fontWeight: 600
    lineHeight: "1.4"
    letterSpacing: 0.01em
  label-sm:
    fontFamily: IBM Plex Sans
    fontSize: 0.75rem
    fontWeight: 600
    lineHeight: "1.4"
    letterSpacing: 0.02em
rounded:
  sm: 0px
  md: 2px
  lg: 4px
  xl: 8px
  full: 9999px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
  2xl: 48px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-md}"
    width: auto
  button-primary-hover:
    backgroundColor: "#0353e9"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-md}"
    width: auto
  button-secondary:
    backgroundColor: "{colors.on-surface}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-md}"
    width: auto
  card:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.sm}"
    borderColor: "{colors.divider}"
  card-elevated:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.sm}"
  card-container:
    backgroundColor: "{colors.surface-container}"
    rounded: "{rounded.sm}"
  input-field:
    backgroundColor: "{colors.background}"
    rounded: "{rounded.sm}"
    borderColor: "{colors.divider}"
  input-field-focus:
    backgroundColor: "{colors.background}"
    rounded: "{rounded.sm}"
    borderColor: "{colors.outline}"
  link:
    textColor: "{colors.link}"
    typography: "{typography.body-md}"
  link-hover:
    textColor: "{colors.primary}"
    typography: "{typography.body-md}"
  badge:
    backgroundColor: "{colors.surface-bright}"
    textColor: "{colors.primary}"
    typography: "{typography.label-sm}"
    width: auto
  badge-error:
    backgroundColor: "{colors.error}"
    textColor: "{colors.on-primary}"
    typography: "{typography.label-sm}"
    width: auto
  divider:
    backgroundColor: "{colors.divider}"
    height: 1px
  swatch-secondary:
    backgroundColor: "{colors.secondary}"
    rounded: "{rounded.sm}"
    size: 32px
  swatch-outline:
    backgroundColor: "{colors.outline}"
    rounded: "{rounded.sm}"
    size: 32px
motion:
  duration-short: 200ms
  duration-medium: 300ms
  easing-standard: cubic-bezier(0.4, 0, 0.2, 1)
elevation:
  sm: 0 1px 3px rgba(0, 0, 0, 0.1)
  md: 0 2px 4px rgba(0, 0, 0, 0.1)
  lg: 0 4px 6px rgba(0, 0, 0, 0.1)
---

## Overview

Carbon Design System is a highly structured, professional, and functional design system engineered for enterprise-scale software. It establishes a robust, predictable, and technically precise user experience that prioritizes clarity and extreme accessibility. The visual tone is clean, geometric, and digital-first, instilling confidence and efficiency in complex enterprise workflows.

## Colors

Carbon's color palette is systematically structured to support high-contrast, accessible, and functional user interfaces. The system relies on a clean light theme base with targeted, high-visibility accent colors to guide user interactions and establish visual hierarchy.

*   `colors.primary` (#0F62FE): IBM Blue, used for primary actions, active states, and key brand highlights.
*   `colors.secondary` (#009D9A): Teal accent color used for secondary highlights, status indicators, and interactive elements.
*   `colors.background` (#F4F4F4): The default light background color for page layouts and structural containers.
*   `colors.surface` (#FFFFFF): Pure white used for cards, input fields, and elevated content containers.
*   `colors.surface-container` (#E8DAFF): A soft purple-tinted container background used to group related content blocks.
*   `colors.surface-bright` (#D0E2FF): A bright blue-tinted container background used for hero sections and prominent callouts.
*   `colors.on-primary` (#FFFFFF): High-contrast white text used on top of primary blue elements.
*   `colors.on-surface` (#161616): Nearly black dark gray text used for body copy and primary headings on light surfaces.
*   `colors.outline` (#00B0E0): A bright cyan outline color reserved for focus rings and accessibility indicators.
*   `colors.error` (#DA1E28): A high-visibility red used for error states, destructive actions, and critical alerts.
*   `colors.divider` (inferred) (#E0E0E0): A subtle gray border color used to separate content sections and table rows.
*   `colors.link` (#6929C4): A distinct purple color used exclusively for inline text links.

## Typography

Typography in Carbon is built entirely on IBM Plex Sans, a highly legible grotesque sans-serif typeface designed to balance technical precision with human warmth. The typographic scale is strictly structured to handle dense technical documentation and complex data-driven layouts.

*   `typography.display-lg` (inferred): Used for large marketing headlines and hero section titles.
*   `typography.display-md` (inferred): Used for secondary marketing headlines and landing page section headers.
*   `typography.headline-lg` (inferred): Used for major section titles within documentation and dashboards.
*   `typography.headline-md` (inferred): Used for standard content headers and card titles.
*   `typography.headline-sm`: Used for small sub-headers and group titles.
*   `typography.body-lg`: Used for introductory paragraphs and high-priority body copy.
*   `typography.body-md`: The standard body copy size for documentation, articles, and general text.
*   `typography.body-sm`: Used for secondary body copy, captions, and dense UI metadata.
*   `typography.label-md` (inferred): Used for form labels, table headers, and button text.
*   `typography.label-sm` (inferred): Used for tiny badges, tags, and micro-copy.

## Layout

*   Carbon utilizes a highly structured grid system based on a 4px base unit, leveraging spacing tokens from `spacing.xs` (4px) to `spacing.2xl` (48px) to align layouts strictly to columns and rows.
*   The observed page section order flows top-to-bottom: `nav`, `hero`, `features`, `libraries`, `news`, and `footer`.
*   The hero composition pattern features a split layout with a prominent left-aligned headline and description on a light blue background, paired with a highly structured, grid-based technical illustration on the right.
*   Layouts are fully responsive, employing a collapsible left-hand navigation drawer on mobile viewports and a fluid grid system that adapts seamlessly across standard breakpoints.

## Elevation & Depth

Carbon relies on subtle, low-opacity single-layer shadows to convey depth, prioritizing flat color contrast and borders over heavy shadows.

*   `elevation.sm`: Used for subtle card lift and low-level interactive elements.
*   `elevation.md`: Used for medium-level overlays such as dropdowns and popovers.
*   `elevation.lg`: Used for high-priority floating elements like modals or drawer overlays.

## Shapes

Carbon is famous for its sharp, geometric aesthetic, heavily prioritizing square corners to convey technical precision and structural stability. Most interactive elements, including standard buttons, input fields, and tabs, strictly use a border radius of `rounded.sm` (0px).

Slight rounding is applied sparingly to specific UI components to distinguish them from structural layout blocks. For example, cards and containers use `rounded.sm` (0px) or `rounded.md` (2px) to maintain a clean digital-first appearance, while badges and tags may utilize `rounded.full` (9999px) for pill-shaped styling.

## Components

> **Note:** This spec was generated from a website scrape and contains visual approximations.
> For production use, add a deep reference to each component pointing to its authoritative
> source (Storybook story, metadata file, or component spec):
> `→ Deep reference: src/components/Button/metadata.ts`


### button-primary
The primary button uses `{colors.primary}` for its background and `{colors.on-primary}` for text, styled with `{typography.label-md}` and a sharp `{rounded.sm}` edge. It transitions to `button-primary-hover` on hover, changing the background to a deeper blue. Use this component for the single most important call-to-action on a page or form.

### button-secondary
The secondary button features a background of `{colors.on-surface}` with `{colors.on-primary}` text, maintaining a sharp `{rounded.sm}` border radius. It provides a strong, high-contrast alternative to the primary action without competing for visual dominance. Use this component for secondary actions like "Cancel" or "Go Back" in forms and modals.

### card
The standard card is built with a `{colors.surface}` background, a `{rounded.sm}` corner radius, and a `{colors.divider}` border. It can transition to `card-elevated` using `{elevation.sm}` for interactive states, or sit on a `{colors.surface-container}` background as a `card-container` to group related content. Use this component to organize content, features, or articles into distinct, scannable blocks.

### input-field
The input field features a `{colors.background}` container with a `{colors.divider}` border and a sharp `{rounded.sm}` radius. When focused, it transitions to `input-field-focus`, highlighting the border with `{colors.outline}` to ensure high accessibility. Use this component for text inputs, search bars, and form fields.

### link
The link component uses `{colors.link}` text styled with `{typography.body-md}` for inline text links. On hover, it transitions to `link-hover`, shifting the text color to `{colors.primary}` to indicate interactivity. Use this component exclusively for inline text navigation and external references.

### badge
The standard badge uses a `{colors.surface-bright}` background with `{colors.primary}` text styled with `{typography.label-sm}`. For critical alerts or errors, the `badge-error` variant utilizes a `{colors.error}` background with `{colors.on-primary}` text. Use badges to highlight statuses, categories, or metadata in dense UI layouts.

### divider
The divider is a thin, 1px horizontal or vertical line colored with `{colors.divider}`. It provides clean, structural separation between layout sections, table rows, or content blocks. Use this component to maintain structure and readability in dense, data-rich interfaces.

### swatch-secondary
The secondary swatch is a 32px by 32px square block utilizing `{colors.secondary}` and a `{rounded.sm}` corner radius. It represents the secondary brand color in color-picking or theme-selection interfaces. Use this component to display secondary accent color options.

### swatch-outline
The outline swatch is a 32px by 32px square block utilizing `{colors.outline}` and a `{rounded.sm}` corner radius. It is used to display the accessibility focus ring color within design system documentation or color pickers. Use this component to represent the system's focus indicator color.

## Do's and Don'ts

| Do | Don't |
| --- | --- |
| Use `{colors.primary}` for primary call-to-actions to ensure high visibility. | Never apply rounded corners like `{rounded.xl}` to `{components.button-primary}` as it violates Carbon's geometric design language. |
| Apply `{rounded.sm}` (0px) to all standard buttons and input fields to maintain the brand's sharp, geometric identity. | Do not use `{colors.secondary}` for primary actions; reserve it for secondary highlights and status indicators. |
| Ensure all inline links use `{colors.link}` to distinguish them from body text. | Avoid using `{colors.surface-container}` as a primary background; it should only be used for grouping related content blocks. |
| Use `{colors.outline}` for focus rings to meet strict accessibility standards. | Avoid using custom colors for focus states; always default to `{colors.outline}`. |
| Separate dense layout sections using a 1px `{components.divider}` to maintain structure. | Never use `{typography.display-lg}` for standard body copy or dense UI metadata. |
| Apply `{typography.body-md}` for standard documentation paragraphs to ensure optimal readability. | Do not mix multiple shadow styles; stick to the defined `{elevation.sm}`, `{elevation.md}`, and `{elevation.lg}` scale to maintain depth consistency. |
| Use `{colors.error}` exclusively for critical alerts and destructive actions. | Do not use `{colors.primary}` for error states or destructive actions. |
| Style secondary actions with `{components.button-secondary}` using `{colors.on-surface}` to provide a strong contrast. | Do not use `{colors.surface-bright}` for standard body text as it lacks the required contrast against light surfaces. |

## Content Style

*   **CTA Style**: Call-to-action labels must be direct, action-oriented, and concise. They should utilize active verbs in sentence case (e.g., "Start contributing", "Learn about Carbon") to guide users clearly.
*   **Heading Tone**: Headlines must be clear, informative, and highly structured. The tone focuses strictly on utility and technical clarity, completely avoiding marketing fluff or hyperbolic language.
*   **Copy Density**: The copy layout is designed for high density but remains highly scannable. It utilizes short paragraphs, bulleted lists, and a strict typographic hierarchy to organize complex technical information efficiently.

## Imagery & Icons

Carbon employs a mixed imagery style that combines clean, technical vector illustrations with precise grid lines, geometric shapes, and IBM's signature stroke-based icons. Diagrams and illustrations frequently feature a blueprint or grid aesthetic to emphasize structure, engineering, and technical precision. Photographic assets, when used, are kept minimal and clean, aligning perfectly with the system's rigid grid layouts.