Color system // Surface depth
Layered surfaces read as depth without breaking contrast.
Tonal stacking defines how nested containers inherit and shift surface values so modals above cards above pages still read as a single coherent material system rather than separate panes.
Nesting safe
WCAG contrast
Theme aware
Act I // Layer model
Each nest level shifts luminosity by a calibrated delta.
Instead of picking arbitrary surface colors, the stacking system increments lightness in OKLCH space. This keeps contrast ratios predictable no matter how deep the nesting goes.
Stacking rule
Never skip a tonal tier.
Jump from base to elevated without passing through surface creates a visual crack in the depth model.
Act II // Nesting rules
Rules keep the stack readable at any nesting depth.
Each card applies the next luminosity step in the sequence. Borders and focus rings auto-adjust because they reference the same tonal delta relative to their container.
/* Tonal stacking — one luminosity step per nesting level */
.section { background: var(--vl-bg-main); }
.section > .panel { background: var(--vl-bg-surface); }
.panel > .card { background: var(--vl-bg-elevated); }
.card > .chip { background: var(--vl-bg-float); }
/* Borders automatically track the same delta */
.card { border: 1px solid var(--vl-border-subtle); }
.modal { border: 1px solid var(--vl-border-elevated); }
The delta between tiers is fixed in OKLCH lightness, so each nested surface maintains safe contrast without manual overrides.
Act III // Accessibility
Every stack level maintains WCAG AA contrast.
The OKLCH lightness delta is tuned so that text on any tier passes 4.5:1 contrast against its surface. Focus indicators remain visible even when nested three levels deep.
stacking.contrast
--vl-bg-main: oklch(10% 0.012 145);
--vl-bg-surface: oklch(14% 0.015 145);
--vl-bg-elevated: oklch(18% 0.018 145);
--vl-text-primary: oklch(92% 0.005 145);
contrast ratios
text/main: > 15:1 ✓
text/surface: > 12:1 ✓
text/elevated: > 9:1 ✓
Act IV // Applied system
Stacking connects surface tokens to real component nesting.
Modals, drawers, dropdown menus and nested cards all consume the same stacking rules. The token system ensures that adding a new layer never breaks the ones underneath.