Malevich

Backgrounds
& Surfaces

Every plane in a Malevich interface is a surface — from the page canvas to the scrim behind a modal. Five semantic surfaces, built from four primitives.

What is a surface?

A surface is any plane that holds content: the page background, a card, a popover, a modal scrim. Malevich names five — canvas, raised, float, overlay and bone — and orders them in a fixed z-stack. Content lives on the canvas; cards rise to raised; transient panels float; overlays cover everything with a dim scrim.

A surface is never one property. It is composed from four primitives — background (the fill), shape (corner radius), elevation (border, shadow and stacking order) and spacing (the padding within and the gaps between). The semantic tokens below bundle sensible defaults of these primitives for each role.

Semantic surfaces

Five role-based surfaces. Each previews in this page's dark scheme; per-scheme fills are in Background below.

ExampleCSS specsComponentsUsage for
background: canvasborder: noneshadow: flatradius: section · 0
The base page plane and lowest layer. Everything else stacks on top of it.
background: raisedshadow: raisedradius: card · 4pxborder: hairline
Cards, panels and blocks lifted one step off the canvas — the default content surface.
background: floatshadow: floatradius: tooltip · 4px
Transient surfaces that float above content — menus, popovers and toasts.
background: overlaycovers viewportz: top of stack
SheetDialog
The dim scrim behind modals — blocks the layer beneath and focuses attention.
background: boneborder: mutedradius: card · 4px
Card · feature
Warm, off-white editorial surface for emphasis blocks and feature cards.

Primitives

The four dimensions a surface is composed from. Change a primitive and you change the surface.

Background

The fill. Each surface resolves to a different value per color-scheme — light and dark shown side by side.

Light / DarkToken · valueComponentsUsage for
L
D
--color-surface-canvaslight · #FAFAFAdark  · #0A0A0A
The base page plane and lowest layer. Everything else stacks on top of it.
L
D
--color-surface-raisedlight · #FFFFFFdark  · oklch(0.160 0 0)
Cards, panels and blocks lifted one step off the canvas — the default content surface.
L
D
--color-surface-floatlight · #FFFFFFdark  · oklch(0.240 0 0)
Transient surfaces that float above content — menus, popovers and toasts.
L
D
--color-surface-overlaylight · rgba(10,10,10,0.65)dark  · rgba(0,0,0,0.85)
SheetDialog
The dim scrim behind modals — blocks the layer beneath and focuses attention.
L
D
--color-bonelight · #E8E2D5dark  · oklch(0.240 0 0)
Card · feature
Warm, off-white editorial surface for emphasis blocks and feature cards.

Shape

Corner radius. The scale runs from sharp sections to fully-round avatars; each token names the role it serves.

PreviewToken · valueComponentsUsage for
--radius-section0
Full-width sections and the page canvas — no rounding.
--radius-button2px
Standard buttons.
--radius-field2px
Form fields — input, select, textarea.
--radius-block4px
Internal blocks inside a section.
--radius-card4px
Cards and raised panels.
--radius-tooltip4px
PopoverTooltip
Tooltips and popovers.
--radius-dialog6px
SheetDialog
Dialogs, sheets and drawers.
--radius-tag16px
Tags, badges and chips.
--radius-pill9999px
Pill buttons, switches and toggles.
--radius-avatar9999px
Avatars — fully circular.

Elevation

How far a surface lifts off the page — expressed through shadow and border, not a z-index scale. Shadow previews use the light-scheme value on a light stage.

ShadowToken · value (light / dark)ComponentsUsage for
--shadow-flatlight · nonedark  · none
CanvasDivider
Flush with its parent — no lift.
--shadow-raisedlight · 0 1px 2px rgba(10,10,10,0.08)dark  · 0 1px 2px rgba(0,0,0,0.35)
Cards and raised blocks, one step off canvas.
--shadow-floatlight · 0 2px 8px rgba(10,10,10,0.12)dark  · 0 4px 12px rgba(0,0,0,0.45)
Floating menus, popovers and toasts.
--shadow-overlaylight · 0 8px 24px rgba(10,10,10,0.18)dark  · 0 12px 32px rgba(0,0,0,0.55)
SheetDialog
Modal surfaces above a scrim.

Border width

PreviewToken · valueComponentsUsage for
--border-width-hairline1px
All bordered surfaces
Default 1px edge on cards, fields and dividers.
--border-width-focus2px
All bordered surfaces
Focus ring thickness on interactive controls.
--border-width-emphasis2px
All bordered surfaces
Emphasised edges — strong borders, active rails.

Stacking order has no token scale: surfaces follow a fixed ladder — canvas → raised → float → overlay — and portal overlays (Dialog, Sheet, Popover, Toast) manage their own z-index at runtime.

Spacing

The padding within a surface and the gaps between surfaces, shown at the -m step. Each token also resolves to -s and -l variants on the same scale.

ScaleToken · valueComponentsUsage for
--space-inset-element-m8px
Padding inside atomic elements.
--space-inset-block-m24px
Padding inside cards and blocks.
--space-inset-section-m48px
Padding inside full-width sections.
--space-gap-elements-m8px
Gap between elements in a row.
--space-gap-blocks-m24px
Gap between blocks and cards.
--space-gap-sections-m64px
Gap between page sections.