Depth & shadows

Overview

OKLCH elevation tokens map to utilities (.shadow-xs … .shadow-xl, .shadow-inset) and to components (cards, menus, snackbars). Sources and overrides:

Prerequisites

• PimentCSS installed, Installation (shadow utilities ship in the default bundle).
• Semantic surfaces, readable panels from Colors (--surface-elevated, borders).
• Stacking, combine shadows with z-index on overlays (dropdowns use z-index: 100 in component SCSS).

Canonical tokens

Edit tokens/depth.css for OKLCH shadow stacks. Dark mode overrides live under [data-theme="dark"] and prefers-color-scheme: dark.

:root {
  --shadow-lg: 0 12px 28px oklch(40.3% 0.03 262 / 0.22),
    0 4px 12px oklch(40.3% 0.03 262 / 0.14);
  --shadow-xl: 0 20px 48px oklch(40.3% 0.03 262 / 0.28),
    0 8px 20px oklch(40.3% 0.03 262 / 0.18);
}

[data-theme="dark"] {
  --shadow-lg: 0 14px 32px oklch(0% 0 0 / 0.68),
    0 6px 16px oklch(0% 0 0 / 0.5);
  --shadow-xl: 0 22px 50px oklch(0% 0 0 / 0.78),
    0 10px 24px oklch(0% 0 0 / 0.58);
}

Elevation scale

All levels share one stage so you can compare blur and spread. LG and XL use a second shadow layer (XL is wider and stronger). In dark mode, tiles sit on the same muted preview surface as the layered demo below so black shadows stay visible.

Preview is documentation-only (.pdoc-depth-*). In your app, apply .shadow-* on real surfaces.

Inset shadow

Recessed surfaces (wells, pressed tracks). Utility: .shadow-inset · token --shadow-inset.

<div class="shadow-inset p-4" style="border-radius: var(--border-radius-8); background: var(--surface-elevated)">Recessed track</div>

Layered UI

Stack surfaces in order: page, elevated card, then dialog overlay. Increase shadow with each layer; manage focus and use role="dialog" + aria-modal="true" on the top layer.

<article class="card card--elevated">
  <div class="card__body">…</div>
</article>

Components using shadows

Prefer component classes before ad-hoc utilities so elevation stays aligned with the design system. .card--elevated sets outer padding to 0: wrap content in .card__body (or header/footer) so spacing comes from the card API. For custom panels, use spacing utilities (.p-3, .gap-2, see Layout).

Utility classes

Apply on any element. Use .shadow-none to clear shadows when switching variants.

<div class="shadow-md p-4" style="background: var(--surface-elevated); border-radius: var(--border-radius-8)">Custom panel</div>

Customize (Sass)

1. 01

   Override shadow stacks

   Pass !default variables when importing PimentCSS. Keep OKLCH alpha low enough for AA contrast on adjacent text.
   theme.scss

   @use "pimentcss-design-system" with (
     $shadow-sm: 0 4px 12px oklch(40% 0.04 262 / 0.18),
     $shadow-md: 0 12px 24px oklch(40% 0.04 262 / 0.2),
   );

2. 02

   Rebuild CSS

   Regenerate dist/pimentcss.min.css after token edits.
   Terminal

   npm run build:css

See Customization for partial imports (pimentcss-design-system/core includes depth tokens).

Accessibility (RGAA / WCAG)

Next steps