| name | spatial-luminous-design |
| description | Spatial depth systems, luminosity techniques, glassmorphism tiers, material surface reference (glass, metal, paper, fabric), atmospheric color, and animated mesh gradients — the vocabulary for premium three-dimensional UI. Use proactively when assigning z-axis layers and shadow depth tokens to interface elements, implementing glassmorphism at the correct tier, applying luminosity effects (ambient glow, neon, rim lighting), choosing material surfaces as design tokens, or building atmospheric color and animated mesh gradients. |
| version | 1.0.0 |
| tags | ["design","spatial","depth","luminosity","glass","material","atmosphere","gradient","light"] |
| when_to_use | ["Assigning z-axis layers and shadow depth tokens to interface elements","Implementing glassmorphism at the correct tier for context","Applying luminosity effects — ambient glow, neon, rim lighting","Choosing material surfaces (glass, metal, paper, fabric) as design tokens","Building atmospheric color and animated mesh gradients"] |
Spatial & Luminous Design
Depth, light, and material systems that elevate interfaces from flat to three-dimensional. These techniques separate premium products from generic ones.
Purpose
- Provide a consistent 5-layer spatial model for z-axis depth
- Define luminosity techniques with specific CSS values
- Give production-ready glassmorphism across three tiers
- Reference material surfaces as design tokens
- Guide atmospheric color and mesh gradient usage
1. Spatial Depth System (5-Layer Model)
Every element belongs to exactly one layer. Elements never skip layers.
| Layer | Z-Index Range | Parallax Speed | Purpose | CSS Techniques |
|---|
| Background | 0 | 0.3× scroll | Environment, atmosphere | Fixed or slow-scroll gradient, ambient tint |
| Ground | 1–10 | 1× scroll (normal) | Content foundation | Cards, surfaces, main content |
| Floating | 11–100 | 1.05–1.1× scroll | Active elements | Dropdowns, tooltips, selections |
| Overlay | 101–1000 | Fixed | Focused attention | Modals, lightboxes, drawers |
| Foreground | 1001+ | Fixed | Persistent UI | Navigation, FAB, toasts |
Layer rules:
- Each layer has a consistent shadow depth token (e.g.,
--shadow-ground, --shadow-floating)
- Parallax ratios create natural depth perception — heavier layers move slower
- Background layer anchors the atmosphere; changing it shifts the entire page mood
Shadow depth tokens:
:root {
--shadow-ground: 0 1px 3px rgba(0,0,0,0.12), 0 1px 2px rgba(0,0,0,0.08);
--shadow-floating: 0 4px 16px rgba(0,0,0,0.12), 0 2px 4px rgba(0,0,0,0.08);
--shadow-overlay: 0 20px 60px rgba(0,0,0,0.20), 0 4px 16px rgba(0,0,0,0.12);
--shadow-foreground: 0 8px 32px rgba(0,0,0,0.24);
}
2. Luminosity Techniques
Ambient glow (behind focal elements):
.focal-element {
box-shadow: 0 0 60px 20px rgba(120, 80, 255, 0.20);
}
Backlit text (dark backgrounds):
.hero-heading {
text-shadow: 0 0 40px rgba(120, 80, 255, 0.30);
}
Neon effect (3-layer technique):
.neon {
box-shadow:
0 0 7px #7850ff,
0 0 20px #7850ff,
0 0 60px rgba(120,80,255,0.3);
}
Rim lighting (overhead light source suggestion):
.dark-card {
box-shadow: inset 0 1px 0 rgba(255, 255, 255, 0.10);
}
Brightness hierarchy rule:
The brightest element = highest attention priority. Use filter: brightness() or direct color lightness to control visual hierarchy intentionally.
3. Glassmorphism (3 Tiers)
| Tier | Background | Blur | Border | Use Case |
|---|
| Subtle | rgba(255,255,255, 0.05–0.10) | backdrop-filter: blur(8px) | 1px rgba(255,255,255, 0.10) | Floating cards, secondary panels |
| Medium | rgba(255,255,255, 0.15–0.25) | backdrop-filter: blur(16px) | 1px rgba(255,255,255, 0.20) | Navigation, toolbars, active panels |
| Immersive | rgba(255,255,255, 0.30–0.40) | backdrop-filter: blur(24px) | 1px rgba(255,255,255, 0.30) | Modal backgrounds, hero overlays |
Implementation pattern:
.glass-medium {
background: rgba(255, 255, 255, 0.18);
backdrop-filter: blur(16px);
-webkit-backdrop-filter: blur(16px);
border: 1px solid rgba(255, 255, 255, 0.20);
border-radius: var(--radius-lg);
}
Mandatory rules:
- MUST maintain 4.5:1 text contrast ratio over the blurred background — test on varied backgrounds
- Always add border for edge definition (without it, elements float directionlessly)
- Light source direction must match the elevation system
- Dark glassmorphism: swap white rgba for dark rgba values — do not just invert, redesign
4. Material Reference Library
| Material | CSS Implementation | Token Name |
|---|
| Glass | backdrop-filter: blur(Xpx); background: rgba(R,G,B, 0.1–0.3) | --surface-glass |
| Metal | background: linear-gradient(135deg, hsl(0,0%,22%), hsl(0,0%,18%)); box-shadow: inset 0 1px 0 rgba(255,255,255,0.15) | --surface-metal |
| Paper | background: var(--color-surface) + noise overlay pseudo-element at 0.5–1.5% opacity | --surface-paper |
| Fabric | background: repeating-linear-gradient(0deg, transparent, transparent 1px, rgba(0,0,0,0.02) 1px, rgba(0,0,0,0.02) 2px) | --surface-fabric |
| Liquid | Multi-point radial gradients + morphing SVG shapes + slow transform animation (20–40s cycle) | --surface-liquid |
Noise texture (Paper material):
.paper::after {
content: '';
position: absolute;
inset: 0;
background-image: url("data:image/svg+xml,...");
opacity: 0.015;
pointer-events: none;
}
5. Atmospheric Color
Ambient tint:
Full-page overlay at 2–5% opacity of brand primary. Creates environmental cohesion and brand presence without competing with content.
body::before {
content: '';
position: fixed;
inset: 0;
background: var(--color-brand-primary);
opacity: 0.03;
pointer-events: none;
z-index: 0;
}
Content-responsive tinting:
Extract dominant color from hero image via canvas getImageData(), apply as page ambient tint. Technique used by Apple Music, Spotify.
Color temperature depth (spatial use):
- Warm colors (red, orange, yellow) → advance toward viewer
- Cool colors (blue, purple, teal) → recede from viewer
- Use intentionally to reinforce z-axis depth, not just for decoration
Chromatic shadows (not pure black/gray):
.card {
box-shadow: 0 4px 16px rgba(80, 40, 120, 0.25);
}
Time-aware theming (optional, delightful):
- After 6pm: subtle warm shift (hue rotate +5deg, saturation +3%)
- Morning: cool shift (hue rotate -3deg, brightness +2%)
- Implement via CSS custom property update on schedule or user preference
6. Mesh Gradient Patterns
CSS implementation:
.mesh-bg {
background:
radial-gradient(ellipse at 20% 20%, rgba(120,80,255,0.4) 0%, transparent 50%),
radial-gradient(ellipse at 80% 20%, rgba(255,80,120,0.3) 0%, transparent 50%),
radial-gradient(ellipse at 50% 80%, rgba(80,200,255,0.3) 0%, transparent 50%),
radial-gradient(ellipse at 80% 80%, rgba(255,200,80,0.2) 0%, transparent 50%);
}
Construction rules:
- Place gradient points at grid intersections (3×3 or 4×4 grid)
- 4–6 color stops per point
- Saturation delta between adjacent stops: 3–5% (subtle variation, not jarring)
Animated mesh:
@keyframes mesh-drift {
0%, 100% { transform: translate(0, 0); }
33% { transform: translate(-20px, 10px); }
66% { transform: translate(10px, -20px); }
}
.mesh-point {
animation: mesh-drift 30s ease-in-out infinite;
will-change: transform;
}
- Animation cycle: 20–40s (longer = more atmospheric, less distracting)
- Always set
will-change: transform on animated gradient containers
Stripe's approach: WebGL noise functions via fragment shaders for GPU-rendered organic gradients with minimal CPU cost. Use for high-performance, complex mesh needs.
Anti-Patterns
| Anti-Pattern | Why It Fails |
|---|
| Heavy blur killing text readability | Always verify contrast OVER the blurred background, not against a solid |
| Frosted glass without border | Edges disappear; elements float without spatial context |
| Shadows inconsistent with light source | Elements casting shadows in different directions feel physically wrong |
| Flat single-tone backgrounds | Misses the depth and atmosphere that elevates premium products |
| Noise texture above 2% opacity | Reads as gritty and industrial, not refined premium |
| Gradients with > 20% saturation jumps between stops | Jarring, not luminous |
| Black (#000) in shadows | Feels heavy and dead — use tinted dark values instead |
| Glassmorphism on glassmorphism | Stacked blur layers collapse depth, create visual noise |
| Same ambient glow color everywhere | Loses intentionality; glow should reflect the element's own hue |
Validation Checklist
