Centrim Design System — a token-first, accessible React component system.
Elevation
Elevation communicates one thing only: how far a surface floats above the page. It is intentionally subtle, because hierarchy in this system comes from typography and space first.
What is this?
Four shadow steps plus none (--ds-shadow-xs through --ds-shadow-lg), paired with a surface layering model: background → surface → surface-raised → surface-overlay.
When to use it
- A surface genuinely floats: menu, popover, dialog, drawer, toast
- A resting card needs the lightest possible lift (xs)
- A sticky bar must separate from content scrolling beneath it
How to use it
- Match the shadow step to the layering token the surface uses
- Increase elevation only when the interaction becomes more temporary
- Let borders, not shadows, carry in-page structure
What to avoid
- Elevating static page content to make it feel important
- Stacking elevated cards inside elevated cards
- Blur or glass on anything that is part of the page flow
Shadow steps
Subtle only — four steps plus none.
shadow-none
shadow-xs
shadow-sm
shadow-md
shadow-lg
Layering model
| Layer | Surface token | Elevation |
|---|---|---|
| Page canvas | --color-background | shadow-none |
| Resting content | --color-surface | shadow-none or shadow-xs |
| Raised panel / sticky bar | --color-surface-raised | shadow-sm |
| Menu, popover, dropdown | --color-surface-overlay | shadow-md |
| Dialog, drawer, toast | --color-surface-overlay | shadow-lg |
The Soft Glass rule
Soft Glass belongs to floating surfaces only
The ds-glass-soft treatment — translucency plus backdrop blur — is reserved for surfaces that float above content and can be dismissed: dialogs, drawers, popovers, dropdown menus, the command menu and toasts.
Never apply it to page content, cards, table rows, headers that are part of the document flow, or any always-visible chrome. Blur on in-flow content degrades text rendering, costs compositing performance on long pages, and removes the layering cue that makes floating surfaces read as temporary.
Do & don't
Do
- Use shadow-xs for a resting card and let its border do most of the work.
- Raise elevation as an element becomes more temporary and more interruptive.
- Keep dark-mode elevation working through surface lightness as well as shadow.
- Use a divider instead of elevation when two regions simply need separating.
Don't
- Do not use shadow-lg on anything that stays on screen permanently.
- Do not nest elevated surfaces; flatten the composition instead.
- Do not apply backdrop blur to sticky page headers or sidebars.
- Do not simulate elevation with a coloured background.
Why it is designed this way
Shadows are unreliable as a hierarchy tool in dark themes, so this system keeps them quiet and expresses depth mainly through surface lightness and borders. That leaves elevation with one unambiguous job — signalling "this floats and can be dismissed" — which is why the Soft Glass rule is scoped so tightly.