Surfaces

Surfaces define the structural hierarchy of the interface. Use surface-canvas, surface-base, surface-raised, and surface-subtle to separate backgrounds, content containers, and elevated layers without relying on semantic colors. Each surface also establishes its corresponding contrast context so text and icons remain legible across light and dark themes.

Open ColorsOpen Theming Overview

Surface roles

Each surface token represents a different level of structural emphasis. Choose the token that matches the role of the layer, not the decoration you want to add.

surface-canvas

Use for the application background and the main viewport layer.

surface-base

Use for default content containers such as cards, panels, and primary sections.

surface-raised

Use for persistent or elevated UI layers that need clearer separation from the base surface.

surface-subtle

Use for light emphasis and supporting areas. Avoid using it as the dominant structural background of a page.

Contrast pairing

Surfaces are not background-only tokens. Each one is paired with a corresponding contrast color so foreground content remains readable in every theme.

When a layout uses surface-canvas, surface-base, surface-raised, or surface-subtle, text and icons inside that layer should follow the matching contrast context instead of assuming a fixed foreground color. Examples include surface-base with contrast-surface-base and surface-raised with contrast-surface-raised.

How to layer surfaces

Build layouts with a stable visual progression.

Default layering path

Use surface-canvas -> surface-base -> surface-raised -> surface-subtle as the default layering path. Start with the most structural layer and only move upward when the interface needs more separation or emphasis. Avoid jumping from surface-canvas directly to surface-subtle for the main hierarchy of a screen.