Appearance
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.
| Level | Token | Used by |
|---|---|---|
| 0 | none | Page background, flush panels, table rows |
| 1 | --av-shadow-xs | Input fields, subtle separation |
| 2 | --av-shadow-sm | Cards (default) |
| 3 | --av-shadow-md | Hovered cards, sticky headers, dropdowns |
| 4 | --av-shadow-lg | Popovers, floating sidebar, command palette |
| 5 | --av-shadow-xl | Modals, offcanvas drawers |
| 6 | --av-shadow-2xl | Full-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.
| Token | Light | Dark | Use |
|---|---|---|---|
--av-surface-base | neutral-50 | neutral-950 | Page background |
--av-surface-raised | white | neutral-900 | Cards, panels, table backgrounds |
--av-surface-overlay | white | neutral-850 | Dropdowns, popovers, modals, tooltips |
--av-surface-sunken | neutral-100 | neutral-925 | Code 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
| Token | Light | Dark | Use |
|---|---|---|---|
--av-border-subtle | neutral-200 | neutral-800 | Card edges, dividers |
--av-border-default | neutral-300 | neutral-750 | Inputs, table cells |
--av-border-strong | neutral-400 | neutral-600 | Hovered 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 imagery | Data tables |
| Sticky topbar over scrolling content | Form panels |
| Floating action bars | Anything containing small text |
| Modal over a dimmed page | Long-form reading surfaces |
| Marketing/pricing surfaces | The 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.