IBM Carbon Design System Layering System & Surfaces
Authoritative architectural guide, token reference, and live specimens for IBM Carbon v11 contextual layering across Cards, Tiles, and UI items.
IBM Carbon v11 Contextual Layering Architecture
The IBM Carbon Design System v11 Layering Model introduces contextual surface elevation and hierarchical contrast. Instead of hardcoding fixed tokens (such as ui-01 or layer-01), components dynamically query contextual tokens that automatically adapt to their nesting depth.
1. Contextual Layer Hierarchy & Token Map
Carbon v11 distinguishes between the root canvas and three contextual layer depths:
| Layer Level | DOM Selector | White Theme (Light) | G100 Theme (Dark) | Contextual CSS Custom Properties |
|---|---|---|---|---|
| Layer 0 (Canvas) | :root, body, .carbon-layout | #ffffff | #161616 | --cds-background |
| Layer 1 | .cds--layer-one, <cds-layer level="0"> | #f4f4f4 (Gray 10) | #262626 (Gray 90) | --cds-layer--cds-layer-hover--cds-layer-accent--cds-field--cds-border-subtle--cds-border-tile |
| Layer 2 | .cds--layer-two, <cds-layer level="1"> | #ffffff (White — alternates!) | #393939 (Gray 80 — elevates!) | --cds-layer--cds-layer-hover--cds-layer-accent--cds-field--cds-border-subtle--cds-border-tile |
| Layer 3 | .cds--layer-three, <cds-layer level="2"> | #f4f4f4 (Gray 10 — alternates!) | #525252 (Gray 70 — elevates!) | --cds-layer--cds-layer-hover--cds-layer-accent--cds-field--cds-border-subtle--cds-border-tile |
2. Interactive 3-Level Layer Nesting Specimen
Observe how nested <cds-layer> containers automatically alternate in light mode and progressively elevate luminance in dark mode:
Level 1 Layer (Default Surface)
Sitting directly on the canvas. Contextual token --cds-layer resolves to Layer 1.
Card in Layer 1
Level 2 Layer (Nested Surface)
Nested inside Layer 1. Contextual token --cds-layer resolves to Layer 2.
Card in Layer 2
#ffffff. In Dark theme, it elevates to #393939.Level 3 Layer (Deepest Surface)
Triple-nested container. Contextual token --cds-layer resolves to Layer 3.
Card in Layer 3
3. Product & Expressive Card Suite
Carbon v11 cards support multiple variants and color accents:
Standard Contained vs Outlined vs Elevated Cards
Contained Standard Card
var(–cds-layer), subtle border, and interactive hover elevation.Outlined Card
var(–cds-layer-hover) on hover.Elevated Drop-Shadow Card
–cds-shadow-01 lifting to –cds-shadow-03).4. Carbon Color Accent Cards
Cards can feature authoritative top accent stripes corresponding to IBM Carbon color families:
Blue Accent Card
Green Success Card
–cds-support-success).Red Critical Card
–cds-support-error).5. Metric & Stat Cards
Total API Requests
System Uptime
6. Tiles Suite across Layers
Carbon Tiles (<cds-tile>, <cds-clickable-tile>, <cds-expandable-tile>, <cds-selectable-tile>) automatically adapt to the active layer:
Read-Only Informational Tile
Foundational layout primitive sitting on var(--cds-layer).
Clickable Navigation Tile
Expandable Specification Tile
Selectable Tile
Interactive selectable state with Carbon checkmark indicator.