Skip to main content
Luminescent UI provides a depth effect system that smoothly transitions between flat and elevated appearances using the --lum-depth variable.

​
The —lum-depth Variable

The depth system uses a single variable that controls multiple visual properties: 
--lum-depth: 0;  /* Default: flat appearance */
--lum-depth: 1;  /* Elevated: shadows visible, borders hidden */
--lum-depth works as a multiplier from 0 to 1. Values between 0 and 1 create partial effects.

​
How Depth Works

Depth simultaneously affects two properties:

​
1. Border Transparency

Borders fade to transparent as depth increases:
Implementation
border-color: color-mix(
  in oklab,
  var(--border-color),
  transparent calc(var(--lum-depth) * 100%)
);
Result:
  • --lum-depth: 0 → Border fully visible
  • --lum-depth: 0.5 → Border 50% transparent
  • --lum-depth: 1 → Border fully transparent

​
2. Dynamic Box Shadows

Shadows scale with depth for a “lifted” effect:
Implementation
box-shadow:
  inset 0 calc(1px * var(--lum-depth)) calc(2px * var(--lum-depth)) var(--border-color),
  0 calc(1px * var(--lum-depth)) calc(2px * var(--lum-depth)) rgba(0, 0, 0, 0.05),
  0 calc(1px * var(--lum-depth)) calc(3px * var(--lum-depth)) rgba(0, 0, 0, 0.1);
Result:
  • --lum-depth: 0 → No shadows (flat)
  • --lum-depth: 1 → Full shadows (elevated)

​
Shadow Composition

Three layered shadows create the depth effect: 
inset 0 calc(1px * var(--lum-depth)) calc(2px * var(--lum-depth)) var(--border-color)
  • Purpose: Inner highlight for dimensional edge
  • Color: Uses mixed border color
  • Offset: 1px down (at full depth)
  • Blur: 2px

​
Using Depth Effects

​
Basic Usage

Add depth to any element with lum-bg-* utilities: 
<div class="lum-bg-blue-500 [--lum-depth:1]">
  Elevated element
</div>

<div class="lum-bg-purple-600">
  Flat appearance with border
</div>

​
With Components

Apply depth to component utilities:
Cards
<div class="lum-card [--lum-depth:1]">
  <h2>Elevated Card</h2>
  <p>This card appears to float above the background.</p>
</div>
Buttons
<button class="lum-btn lum-bg-green-600 [--lum-depth:1]">
  Elevated Button
</button>
Inputs
<input type="text" class="lum-input [--lum-depth:1]" placeholder="Elevated input" />

​
Gradient Backgrounds

Depth works seamlessly with gradients: 
<div class="lum-grad-bg-indigo-600 [--lum-depth:1] [--lum-gradient-angle:135deg]">
  Elevated gradient
</div>

​
Interactive Depth

Create dynamic depth changes on interaction:

​
Hover Depth

<div class="lum-bg-red-500 hover:[--lum-depth:1] transition-all duration-300">
  Elevates on hover
</div>
Add Tailwind transition utilities for smooth depth animations.

​
Focus Depth

<button class="lum-btn focus:[--lum-depth:1]">
  Elevates when focused
</button>

​
Active Depth

<button class="lum-btn lum-bg-blue-600 active:[--lum-depth:0] [--lum-depth:1]">
  Presses down when clicked
</button>

​
Combined States

<button class="
  lum-btn lum-bg-emerald-600
  hover:[--lum-depth:1]
  active:[--lum-depth:0.3]
  transition-all duration-200
">
  Interactive depth button
</button>

​
Depth Presets

Create reusable depth classes:
styles.css
@layer components {
  .depth-flat {
    --lum-depth: 0;
  }
  
  .depth-subtle {
    --lum-depth: 0.3;
  }
  
  .depth-medium {
    --lum-depth: 0.6;
  }
  
  .depth-elevated {
    --lum-depth: 1;
  }
  
  .depth-interactive {
    --lum-depth: 0;
    transition: box-shadow 0.2s, border-color 0.2s;
  }
  
  .depth-interactive:hover {
    --lum-depth: 1;
  }
}
Usage: 
<div class="lum-card depth-elevated">
  Card with preset depth
</div>

<button class="lum-btn lum-bg-blue-600 depth-interactive">
  Interactive button
</button>

​
Advanced Techniques

​
Layered Depth

Create depth hierarchy with multiple elements: 
<div class="lum-bg-gray-800 [--lum-depth:0.3] p-8">
  <div class="lum-card [--lum-depth:0.6] mb-4">
    <h2>Mid-level card</h2>
  </div>
  <button class="lum-btn lum-bg-blue-600 [--lum-depth:1]">
    Top-level button
  </button>
</div>

​
Animated Depth Transitions

<div class="
  lum-bg-violet-600
  [--lum-depth:0]
  hover:[--lum-depth:1]
  transition-[box-shadow,border-color]
  duration-300
  ease-out
">
  Smooth depth transition
</div>

​
Depth with Custom Shadows

Override shadow colors for themed depth: 
<style>
  .custom-depth {
    --lum-depth: 1;
  }
  .custom-depth:where(.lum-bg-cyan-500) {
    box-shadow:
      inset 0 1px 2px theme(colors.cyan.300 / 30%),
      0 1px 2px theme(colors.cyan.900 / 20%),
      0 1px 3px theme(colors.cyan.950 / 30%);
  }
</style>

<div class="lum-bg-cyan-500 custom-depth">
  Cyan-themed depth shadows
</div>

​
Depth with Superellipse Borders

Depth effects work with superellipse corners: 
<div class="
  rounded-lum
  lum-bg-pink-600
  [--lum-depth:1]
  [--lum-border-superellipse:0.8]
  p-8
">
  Elevated superellipse
</div>
Superellipse corner-shape requires browser support. Shadows will still apply with standard border-radius fallback.

​
Performance Considerations

​
Use Transitions Wisely

Only transition the properties that change:
Good
<div class="transition-[box-shadow,border-color] duration-300">
  Transitions only depth-related properties
</div>
Avoid
<div class="transition-all duration-300">
  Transitions everything (less performant)
</div>

​
Reduce Motion Support

Respect user preferences:
styles.css
@media (prefers-reduced-motion: reduce) {
  .depth-interactive {
    transition: none;
  }
}
Or use Tailwind’s motion-safe:: 
<div class="motion-safe:transition-[box-shadow,border-color] hover:[--lum-depth:1]">
  Respects reduced motion preference
</div>

​
Depth Best Practices

  1. Establish hierarchy - Use different depth values to show element importance
  2. Be consistent - Stick to a small set of depth values (e.g., 0, 0.5, 1)
  3. Combine with scale - Pair depth changes with scale-* utilities for stronger feedback
  4. Consider context - Higher depth works better on darker backgrounds
  5. Animate smoothly - Use 200-300ms transitions for depth changes
Complete Example
<div class="bg-gray-950 p-12">
  <div class="
    lum-card
    lum-grad-bg-blue-600
    rounded-lum
    [--lum-depth:0.5]
    hover:[--lum-depth:1]
    hover:scale-102
    motion-safe:transition-all
    duration-300
    ease-out
    cursor-pointer
  ">
    <h2 class="text-2xl font-bold mb-2">Interactive Card</h2>
    <p class="text-lum-text-secondary">Hover to see depth effect with scale.</p>
  </div>
</div>

Build docs developers (and LLMs) love

Get started for freeTalk to us