Skip to content

Elevation & Depth ​

How AdminVora communicates layering — and why dark mode needs a completely different technique.


The elevation ladder ​

Six levels. Each has a defined purpose; do not invent intermediate values.

LevelTokenUsed by
0nonePage background, flush panels, table rows
1--av-shadow-xsInput fields, subtle separation
2--av-shadow-smCards (default)
3--av-shadow-mdHovered cards, sticky headers, dropdowns
4--av-shadow-lgPopovers, floating sidebar, command palette
5--av-shadow-xlModals, offcanvas drawers
6--av-shadow-2xlFull-screen overlays, spotlight surfaces

Two-layer shadows ​

A single blurry shadow reads as cheap. Real depth uses two layers:

scss
--av-shadow-md:
  /* Contact shadow — tight, dark, defines the edge and grounds the object */
  0 2px 4px -2px oklch(var(--av-shadow-color) / .06),
  /* Ambient shadow — soft, wide, provides the sense of lift */
  0 4px 12px -2px oklch(var(--av-shadow-color) / .10);

The full ladder:

scss
@layer tokens {
  :root {
    /* Tinted with the neutral hue, never pure black — pure black looks dirty on tinted surfaces */
    --av-shadow-color: 258 0.04 12%;

    --av-shadow-xs:  0 1px 2px 0 oklch(var(--av-shadow-color) / .05);

    --av-shadow-sm:  0 1px 2px -1px oklch(var(--av-shadow-color) / .06),
                     0 1px 3px  0   oklch(var(--av-shadow-color) / .10);

    --av-shadow-md:  0 2px 4px -2px oklch(var(--av-shadow-color) / .06),
                     0 4px 12px -2px oklch(var(--av-shadow-color) / .10);

    --av-shadow-lg:  0 4px 6px -4px oklch(var(--av-shadow-color) / .05),
                     0 10px 24px -4px oklch(var(--av-shadow-color) / .12);

    --av-shadow-xl:  0 8px 10px -6px oklch(var(--av-shadow-color) / .05),
                     0 20px 40px -8px oklch(var(--av-shadow-color) / .14);

    --av-shadow-2xl: 0 32px 64px -12px oklch(var(--av-shadow-color) / .22);

    --av-shadow-inner: inset 0 2px 4px 0 oklch(var(--av-shadow-color) / .05);
  }
}

Why the negative spread ​

Negative spread values pull the shadow inward at the top, so it does not halo above the element. Without it, a card appears to be lit from below.


Dark mode: shadows do not work ​

On a neutral-950 background there is nothing darker to cast onto. A black shadow is invisible; a stronger one just creates a dirty smudge.

Dark elevation uses three techniques together:

1. Lighter surface at higher elevation ​

scss
[data-bs-theme="dark"] {
  --av-surface-base:    var(--av-neutral-950);   /* page      */
  --av-surface-sunken:  var(--av-neutral-925);   /* wells     */
  --av-surface-raised:  var(--av-neutral-900);   /* cards     */
  --av-surface-overlay: var(--av-neutral-850);   /* dropdowns */
  --av-surface-float:   var(--av-neutral-800);   /* modals    */
}

2. A 1px inner top highlight ​

Simulates light catching the raised top edge — the strongest single cue for depth on dark UI.

scss
[data-bs-theme="dark"] {
  --av-shadow-sm:
    0 1px 2px 0 oklch(0% 0 0 / .40),
    inset 0 1px 0 0 oklch(100% 0 0 / .04);

  --av-shadow-md:
    0 4px 12px -2px oklch(0% 0 0 / .50),
    inset 0 1px 0 0 oklch(100% 0 0 / .06);

  --av-shadow-lg:
    0 12px 28px -4px oklch(0% 0 0 / .55),
    inset 0 1px 0 0 oklch(100% 0 0 / .07);

  --av-shadow-xl:
    0 24px 48px -8px oklch(0% 0 0 / .60),
    inset 0 1px 0 0 oklch(100% 0 0 / .08);
}

3. Borders carry more weight ​

scss
[data-bs-theme="dark"] .av-card {
  border: 1px solid var(--av-border-subtle);     /* neutral-800 */
}

In light mode a card border is optional. In dark mode it is doing most of the work.


Surfaces ​

Four planes, referenced by role rather than colour.

TokenLightDarkUse
--av-surface-baseneutral-50neutral-950Page background
--av-surface-raisedwhiteneutral-900Cards, panels, table backgrounds
--av-surface-overlaywhiteneutral-850Dropdowns, popovers, modals, tooltips
--av-surface-sunkenneutral-100neutral-925Code blocks, wells, inset areas, table headers

Note the inversion: in light mode raised surfaces are lighter than the page; in dark mode they are lighter too. Elevation always moves toward light. This is physically intuitive and is why "just invert the colours" produces a broken dark theme.


Borders ​

TokenLightDarkUse
--av-border-subtleneutral-200neutral-800Card edges, dividers
--av-border-defaultneutral-300neutral-750Inputs, table cells
--av-border-strongneutral-400neutral-600Hovered inputs, emphasis

Border width is 1px almost everywhere. 2px is reserved for focus rings and selected states, so that thickness carries meaning.

scss
/* Hairline borders at high DPR — a 1px border can look like 0.5px on retina */
.av-divider {
  border-block-start: 1px solid var(--av-border-subtle);
}
@media (-webkit-min-device-pixel-ratio: 2) {
  .av-divider { border-block-start-width: 0.5px; }
}

Focus ring elevation ​

The focus ring must be visible on every surface, including on top of a coloured button.

scss
:where(:focus-visible) {
  outline: var(--av-focus-width) solid var(--av-focus-color);
  outline-offset: var(--av-focus-offset);
}

/* On a brand-coloured surface, invert so the ring does not vanish */
.btn-primary:focus-visible,
[data-av-on-brand] :focus-visible {
  --av-focus-color: var(--av-neutral-0);
  outline-offset: 2px;
  box-shadow: 0 0 0 4px oklch(from var(--av-color-primary) l c h / .35);
}

The extra box-shadow halo guarantees ≥ 3:1 against both the button and the page behind it — WCAG 2.4.11 (Focus Appearance) requires the indicator to contrast with adjacent colours.


Glass surfaces ​

Backdrop blur is a real tool with real costs. It is opt-in.

scss
// src/scss/utilities/_glass.scss
@layer utilities {
  .av-glass {
    --av-glass-blur: 16px;
    --av-glass-opacity: .72;
    --av-glass-saturate: 180%;

    background: oklch(from var(--av-surface-raised) l c h / var(--av-glass-opacity));
    backdrop-filter: blur(var(--av-glass-blur)) saturate(var(--av-glass-saturate));
    border: 1px solid oklch(from var(--av-neutral-0) l c h / .18);
    box-shadow:
      var(--av-shadow-lg),
      inset 0 1px 0 0 oklch(from var(--av-neutral-0) l c h / .22);
  }

  .av-glass--strong { --av-glass-blur: 28px; --av-glass-opacity: .55; }
  .av-glass--subtle { --av-glass-blur: 8px;  --av-glass-opacity: .85; }

  /* Fallback: opaque surface where backdrop-filter is unsupported */
  @supports not (backdrop-filter: blur(1px)) {
    .av-glass { background: var(--av-surface-raised); }
  }
}

When glass is appropriate ​

✅ Use❌ Never use
Auth screens over imageryData tables
Sticky topbar over scrolling contentForm panels
Floating action barsAnything containing small text
Modal over a dimmed pageLong-form reading surfaces
Marketing/pricing surfacesThe sidebar (it scrolls constantly — GPU cost)

Costs: backdrop-filter forces a new compositing layer and re-blurs on every scroll frame. On a page with a large scroll area this measurably drops frame rate on integrated GPUs. Never apply it to an element larger than roughly a quarter of the viewport.

Contrast: text on glass must still meet 4.5:1 against the worst-case backdrop. Test over a white image and a black image. If it fails, increase --av-glass-opacity, do not reduce the blur.


Depth utilities ​

scss
@layer utilities {
  .shadow-none { box-shadow: none !important; }
  .shadow-xs   { box-shadow: var(--av-shadow-xs) !important; }
  .shadow-sm   { box-shadow: var(--av-shadow-sm) !important; }
  .shadow-md   { box-shadow: var(--av-shadow-md) !important; }
  .shadow-lg   { box-shadow: var(--av-shadow-lg) !important; }
  .shadow-xl   { box-shadow: var(--av-shadow-xl) !important; }

  /* Hover elevation — guarded so touch devices do not stick */
  @media (hover: hover) and (pointer: fine) {
    .av-lift {
      transition: box-shadow var(--av-duration-fast) var(--av-ease-standard),
                  transform  var(--av-duration-fast) var(--av-ease-standard);
      &:hover { box-shadow: var(--av-shadow-md); transform: translateY(-2px); }
    }
    @media (prefers-reduced-motion: reduce) {
      .av-lift { transition: none; &:hover { transform: none; } }
    }
  }

  /* Coloured glow — dark mode only, CTAs only */
  .av-glow {
    box-shadow: 0 0 0 1px oklch(from var(--av-color-primary) l c h / .3),
                0 8px 32px -8px oklch(from var(--av-color-primary) l c h / .45);
  }
}

!important on utilities is intentional and is the only place it is allowed — see CSS Architecture.


Gradient borders ​

A 1px gradient border cannot be done with border-image and a radius. Use two backgrounds:

scss
.av-border-gradient {
  --av-bg-from: var(--av-color-primary);
  --av-bg-to:   var(--av-violet-500);

  position: relative;
  background:
    linear-gradient(var(--av-surface-raised), var(--av-surface-raised)) padding-box,
    linear-gradient(135deg, var(--av-bg-from), var(--av-bg-to)) border-box;
  border: 1.5px solid transparent;
  border-radius: var(--av-radius-lg);
}

Works with any radius, any theme, and no pseudo-element.


Spotlight hover ​

A pointer-tracking radial highlight. Used on pricing and feature cards.

html
<div class="av-card av-spotlight">…</div>

The runtime binds every .av-spotlight and writes the pointer position into --av-spotlight-x and --av-spotlight-y as percentages; the highlight is a ::before gradient that fades in on hover. It defaults to the card's centre, so it is correct before the first pointer event and on a device that never sends one. The card's children are lifted above the highlight so it washes under the text, not over it.

A stat card is lit the same way without the class: the runtime binds every .av-stat-card too.


Print ​

Shadows do not print. _print.scss replaces them with borders:

scss
@media print {
  * { box-shadow: none !important; backdrop-filter: none !important; }
  .av-card, .av-panel { border: 1px solid #ccc !important; }
  .av-glass { background: #fff !important; }
}

Read next: Motion.

Documentation for @creativeigniter/adminvora