Backgrounds
Background and surface tokens. Every layer of a UI maps to one of these values.
Background
Token
Value
Use for
--source-color-background
var(--source-color-bg)
Page canvas, the base layer behind all content
Surfaces
Token
Value
Use for
--source-color-surface
var(--source-neutral-0)
Cards, sidebars, panels. One step above background.
--source-color-surface-raised
var(--source-neutral-100)
Dropdowns, modals, tooltips. Floats above content.
--source-color-surface-default
var(--source-color-surface)
Status subtle backgrounds
Token
Value
Use for
--source-color-success-subtle
var(--source-success-50)
Inline alerts, banners, and feedback containers.
--source-color-warning-subtle
var(--source-warning-50)
Inline alerts, banners, and feedback containers.
--source-color-info-subtle
var(--source-info-100)
Inline alerts, banners, and feedback containers.
--source-color-danger-subtle
var(--source-danger-50)
Inline alerts, banners, and feedback containers.
Accent subtle background
Token
Value
Use for
--source-color-accent-subtle
theme-dependent
Selected tabs/chips, accent badges, and highlighted surfaces that should follow
data-source-theme.
Layer order
Token
Layer
Examples
--source-color-background
Base layer, the page canvas
html, body, empty page area
--source-color-surface
Layer 1, sits on background
Cards, sidebars, panels, tables
--source-color-surface-raised
Layer 2, floats above content
Dropdowns, modals, popovers, tooltips
When to use each layer
Do
Use layers in order: background → surface → surface-raised
Use surface-raised only for elements that appear in front of regular content (overlays)
Pair surface backgrounds with a
--source-color-border border to define the edge of the layer
Don't
Skip layers. A card on top of a modal should use surface-raised, not surface
Use raw hex values. If a new layer is needed, add a semantic token
--source-color-surface: var(--source-neutral-0);
--source-color-surface-raised: var(--source-neutral-100);
--source-color-background: var(--source-color-bg);
--source-color-surface-default: var(--source-color-surface);