Dark Overlay Architecture
Dark overlays create depth and separation in the UI. They are used for:- Shadows cast by elevated elements
- Modal backdrops (scrims)
- Dimming effects on inactive areas
- Depth indicators in layered interfaces
/* Dark overlays (using color-mix in oklab) */
--color-overlay-dark-1: color-mix(in oklab, black, transparent 95%);
--color-overlay-dark-2: color-mix(in oklab, black, transparent 90%);
--color-overlay-dark-3: color-mix(in oklab, black, transparent 80%);
--color-overlay-dark-4: color-mix(in oklab, black, transparent 70%);
Dark Overlay Visual Hierarchy
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DARK OVERLAY VISUAL HIERARCHY │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ELEVATION SYSTEM │
│ ════════════════ │
│ │
│ ┌──────────────────────────────────────────────┐ │
│ Level 4 (30%) │ MODAL DIALOG │ │
│ Topmost │ ┌──────────────────────┐ │ │
│ │ │ Dialog Content │ │ │
│ │ │ │ │ │
│ │ └──────────────────────┘ │ │
│ └──────────────────────────────────────────────┘ │
│ ▲ │
│ │ --color-overlay-dark-4 (30% black) │
│ │ │
│ ┌────┴─────────────────────────────────────────────┐ │
│ Level 3 (20%) │ DROPDOWN MENU │ │
│ High elevation │ ┌────────────────────┐ │ │
│ │ │ Option 1 │ │ │
│ │ │ Option 2 │ │ │
│ │ └────────────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ ▲ │
│ │ --color-overlay-dark-3 (20% black) │
│ │ │
│ ┌────┴─────────────────────────────────────────────┐ │
│ Level 2 (10%) │ SIDEBAR │ │
│ Medium │ File Explorer │ │
│ elevation │ Project Files │ │
│ └──────────────────────────────────────────────────┘ │
│ ▲ │
│ │ --color-overlay-dark-2 (10% black) │
│ │ │
│ ┌────┴─────────────────────────────────────────────┐ │
│ Level 1 (5%) │ CONTENT │ │
│ Base elevation │ Main editor/terminal area │ │
│ │ │ │
│ └──────────────────────────────────────────────────┘ │
│ ▲ │
│ │ --color-overlay-dark-1 (5% black) or no shadow │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Why Black for Dark Overlays?
Unlike light overlays which derive from--color-text-primary (theme-dependent), dark overlays use a fixed black value because:
- Universal darkening: Black works to darken any background
- No hue shift: Pure black does not introduce unwanted color
- Predictable behavior: Same shadow appearance across themes
- Performance: No variable resolution needed
Dialog Shadow System
Dialog shadows create the illusion of elevation, making dialogs appear to float above the content./* Dialog Shadows & Overlay */
--dialog-shadow: 0 12px 48px rgba(0, 0, 0, 0.4);
--dialog-shadow-sm: 0 4px 12px rgba(0, 0, 0, 0.15);
--overlay-backdrop: rgba(0, 0, 0, 0.7);
Multi-Layer Shadow Analysis
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DIALOG SHADOW LAYER ANALYSIS │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ --dialog-shadow: 0 12px 48px rgba(0, 0, 0, 0.4) │
│ │
│ Breakdown: │
│ ├── offset-x: 0 No horizontal offset (centered shadow) │
│ ├── offset-y: 12px 12px below element (downward light source) │
│ ├── blur-radius: 48px Large blur for soft ambient shadow │
│ └── color: rgba(0,0,0,0.4) 40% black (heavy but not solid) │
│ │
│ Visual Effect: │
│ ┌───────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ ┌───────────────────────────────────┐ │ │
│ │ │ │ │ │
│ │ │ DIALOG CONTENT │ │ │
│ │ │ │ │ │
│ │ │ │ │ │
│ │ └───────────────────────────────────┘ │ │
│ │ .................................... │ │
│ │ .................................. │ │
│ │ .............................. │ │
│ │ .......................... │ │
│ │ .................... │ │
│ │ .......... │ │
│ │ │ │
│ │ . = Shadow blur area (48px radius, 40% opacity) │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────┘ │
│ │
│ ─────────────────────────────────────────────────────────────────────────── │
│ │
│ --dialog-shadow-sm: 0 4px 12px rgba(0, 0, 0, 0.15) │
│ │
│ Breakdown: │
│ ├── offset-x: 0 Centered │
│ ├── offset-y: 4px Small offset (subtle elevation) │
│ ├── blur-radius: 12px Tight blur (crisp edges) │
│ └── color: rgba(0,0,0,0.15) 15% black (subtle) │
│ │
│ Use case: Tooltips, dropdowns, small popovers │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Dialog Component Architecture
┌─────────────────────────────────────────────────────────────────────────────────┐
│ DIALOG COMPONENT ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ FULL VIEWPORT │ │
│ │ background: var(--overlay-backdrop) = rgba(0,0,0,0.7) │ │
│ │ │ │
│ │ ┌───────────────────────────────────────────┐ │ │
│ │ │ DIALOG CONTAINER │ │ │
│ │ │ box-shadow: var(--dialog-shadow) │ │ │
│ │ │ width: var(--dialog-width-md) = 520px │ │ │
│ │ │ │ │ │
│ │ │ ┌───────────────────────────────────┐ │ │ │
│ │ │ │ DIALOG HEADER │ │ │ │
│ │ │ │ Title + Close Button │ │ │ │
│ │ │ └───────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ ┌───────────────────────────────────┐ │ │ │
│ │ │ │ DIALOG BODY │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ │ max-height: 70vh │ │ │ │
│ │ │ │ (scrollable if needed) │ │ │ │
│ │ │ │ │ │ │ │
│ │ │ └───────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ │ ┌───────────────────────────────────┐ │ │ │
│ │ │ │ DIALOG FOOTER │ │ │ │
│ │ │ │ Cancel │ Confirm │ │ │ │
│ │ │ └───────────────────────────────────┘ │ │ │
│ │ │ │ │ │
│ │ └───────────────────────────────────────────┘ │ │
│ │ .................................... │ │
│ │ ........ dialog-shadow ........ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ LAYERING: │
│ 1. --overlay-backdrop (70% black) dims everything behind │
│ 2. Dialog container sits on top with large shadow │
│ 3. Shadow creates depth perception (12px offset, 48px blur) │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Modal Backdrop System
The modal backdrop dims the content behind a dialog, focusing user attention on the modal content.--overlay-backdrop: rgba(0, 0, 0, 0.7);
Backdrop Purpose and Psychology
┌─────────────────────────────────────────────────────────────────────────────────┐
│ MODAL BACKDROP PSYCHOLOGY │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ rgba(0, 0, 0, 0.7) = 70% black opacity │
│ │
│ PURPOSE: │
│ ════════ │
│ │
│ 1. FOCUS ATTENTION │
│ Darkening the background directs user focus to the modal │
│ 70% is dark enough to clearly separate layers │
│ │
│ 2. INDICATE MODAL STATE │
│ Users understand they must interact with the dialog │
│ Background becomes "unreachable" │
│ │
│ 3. REDUCE VISUAL NOISE │
│ Complex UI behind modal becomes muted │
│ Dialog content stands out │
│ │
│ 4. CONSISTENT EXPERIENCE │
│ Same backdrop across all modals │
│ Users develop expectations │
│ │
│ WHY 70%? │
│ ═════════ │
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ 50%: Too light - background still distracting │ │
│ │ 60%: Borderline - works but not strong │ │
│ │ 70%: OPTIMAL - clear separation without total blackout │ │
│ │ 80%: Acceptable - almost too dark │ │
│ │ 90%: Too dark - feels oppressive, hard to see context │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ 70% black is the industry standard for modal backdrops │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Backdrop vs Dark Overlay Comparison
┌─────────────────────────────────────────────────────────────────────────────────┐
│ BACKDROP VS DARK OVERLAY COMPARISON │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ --overlay-backdrop vs --color-overlay-dark-4 │
│ ═══════════════════ ═══════════════════════ │
│ │
│ rgba(0, 0, 0, 0.7) color-mix(in oklab, black, transparent 70%) │
│ 70% opacity 30% opacity │
│ Fixed rgba() value Uses color-mix() │
│ │
│ Used for: Used for: │
│ • Full-screen modal backdrops • Heavy shadows │
│ • Blocking overlays • Strong dimming effects │
│ • Focus lock indicators • Card elevation shadows │
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ 70% backdrop 30% overlay-dark-4 10% overlay-dark-2 │ │
│ │ ################ ========........ ...................... │ │
│ │ │ │
│ │ Modal backdrop Card shadow Subtle shadow │ │
│ │ (blocks content) (elevation cue) (light depth) │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Element Background Elevation
Element backgrounds create subtle elevation differences between UI components./* Element Background (UI elements like buttons, badges, dropdowns) */
/* Falls back to border colors if not defined in theme */
--color-element-bg-1: var(--color-border-primary);
--color-element-bg-2: var(--color-border-secondary);
--color-element-bg-3: var(--color-border-light);
Element Elevation System
┌─────────────────────────────────────────────────────────────────────────────────┐
│ ELEMENT BACKGROUND ELEVATION │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Dark Theme Values: │
│ ══════════════════ │
│ │
│ --color-border-primary: #151d26; (L ~ 8%) │
│ --color-border-secondary: #1f2a35; (L ~ 12%) │
│ --color-border-light: #2a3540; (L ~ 17%) │
│ │
│ Elevation Levels: │
│ ───────────────── │
│ │
│ BASE LEVEL 1 LEVEL 2 LEVEL 3 │
│ #000000 #151d26 #1f2a35 #2a3540 │
│ │
│ ########### ############## ################# #################### │
│ Pure Black Slight lift Medium lift Higher lift │
│ Terminal BG Input fields Buttons Dropdowns │
│ │
│ Each level increases lightness by ~4-5% in dark theme │
│ This creates subtle but perceivable depth │
│ │
│ ─────────────────────────────────────────────────────────────────────────── │
│ │
│ Light Theme Values: │
│ ═══════════════════ │
│ │
│ --color-border-primary: #e0e0e0; (L ~ 88%) │
│ --color-border-secondary: #d0d0d0; (L ~ 82%) │
│ --color-border-light: #c0c0c0; (L ~ 75%) │
│ │
│ INVERTED: Light theme element backgrounds are DARKER than base │
│ This provides proper elevation perception on light backgrounds │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Border Color Transparency
Transparent borders adapt to any background while providing consistent visual separation./* Border Colors (OKLCH + color-mix, ACSS pattern) */
--oklch-border-dark: color-mix(in oklch, black 20%, transparent);
--oklch-border-light: color-mix(in oklch, white 20%, transparent);
--oklch-divider: color-mix(in oklch, var(--color-text-primary) 15%, transparent);
Transparent Border Analysis
┌─────────────────────────────────────────────────────────────────────────────────┐
│ TRANSPARENT BORDER SYSTEM │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ --oklch-border-dark: color-mix(in oklch, black 20%, transparent) │
│ │
│ Interpretation: │
│ • Mix black at 20% with transparent at 80% │
│ • Result: 20% black semi-transparent border │
│ • Adapts to ANY background - darkens by 20% │
│ │
│ Visual Effect: │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ On light background: ................ (visible as light gray) │ │
│ │ On dark background: ################ (visible as dark line) │ │
│ │ Always visible, always appropriate │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ ─────────────────────────────────────────────────────────────────────────── │
│ │
│ --oklch-border-light: color-mix(in oklch, white 20%, transparent) │
│ │
│ Interpretation: │
│ • Mix white at 20% with transparent at 80% │
│ • Result: 20% white semi-transparent border │
│ • Adapts to ANY background - lightens by 20% │
│ │
│ ─────────────────────────────────────────────────────────────────────────── │
│ │
│ --oklch-divider: color-mix(in oklch, var(--color-text-primary) 15%, ...) │
│ │
│ Interpretation: │
│ • Uses theme's text color as base │
│ • 15% opacity - very subtle │
│ • Automatically adapts to dark/light theme │
│ │
│ Dark theme: 15% of #93a1a1 (light gray) on dark background │
│ Light theme: 15% of #1a1a1a (near black) on light background │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Scrollbar Transparency
Scrollbars use semi-transparent colors to remain visible without dominating the UI./* Scrollbar */
--color-scrollbar-thumb: rgba(100, 100, 100, 0.2);
--color-scrollbar-thumb-hover: rgba(100, 100, 100, 0.4);
Scrollbar Transparency Pattern
┌─────────────────────────────────────────────────────────────────────────────────┐
│ SCROLLBAR TRANSPARENCY SYSTEM │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Default State: rgba(100, 100, 100, 0.2) = 20% neutral gray │
│ Hover State: rgba(100, 100, 100, 0.4) = 40% neutral gray │
│ │
│ Color Choice: rgb(100, 100, 100) = #646464 │
│ • Mid-gray value (neither too dark nor too light) │
│ • Works on both dark and light backgrounds │
│ • Neutral - does not compete with content colors │
│ │
│ State Transition: │
│ ───────────────── │
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ DEFAULT (20%) HOVER (40%) DIFFERENCE │ │
│ │ ................ ================ +20% opacity │ │
│ │ │ │
│ │ Subtle presence Clear visibility 2x opacity │ │
│ │ Non-distracting Interactive cue Smooth │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ WHY DIRECT RGBA (not color-mix)? │
│ ═════════════════════════════════ │
│ │
│ 1. Performance: Scrollbars update frequently │
│ 2. Simplicity: Fixed neutral gray works universally │
│ 3. Cross-browser: rgba() has better support than color-mix() │
│ 4. No theme dependency: Same scrollbar in all themes │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
Light Theme Shadow Adjustments
Light themes require different shadow intensities because dark elements on white backgrounds are more visible.[data-theme="light"] {
/* Overlay/Transparency - Light Theme */
--color-overlay-light-1: rgba(0, 0, 0, 0.03);
--color-overlay-light-2: rgba(0, 0, 0, 0.05);
--color-overlay-light-3: rgba(0, 0, 0, 0.08);
--color-overlay-light-4: rgba(0, 0, 0, 0.12);
--color-overlay-dark-1: rgba(0, 0, 0, 0.05);
--color-overlay-dark-2: rgba(0, 0, 0, 0.1);
--color-overlay-dark-3: rgba(0, 0, 0, 0.15);
--color-overlay-dark-4: rgba(0, 0, 0, 0.2);
}
Theme-Specific Shadow Comparison
┌─────────────────────────────────────────────────────────────────────────────────┐
│ THEME-SPECIFIC SHADOW COMPARISON │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ DARK THEME LIGHT THEME │
│ ═══════════ ═══════════ │
│ │
│ "Light overlays" use "Light overlays" use BLACK │
│ --color-text-primary (dark on light background) │
│ (light gray on dark background) │
│ │
│ Overlay Light-1: 8% Overlay Light-1: 3% │
│ Overlay Light-2: 12% Overlay Light-2: 5% │
│ Overlay Light-3: 16% Overlay Light-3: 8% │
│ Overlay Light-4: 20% Overlay Light-4: 12% │
│ │
│ ┌───────────────────────────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ DARK THEME VISUAL LIGHT THEME VISUAL │ │
│ │ │ │
│ │ Background: #000000 Background: #ffffff │ │
│ │ │ │
│ │ #################### .................... │ │
│ │ #################### .................... │ │
│ │ ####..........###### ....==========.... │ │
│ │ #### Hover ...###### ....= Hover =.... │ │
│ │ ####..........###### ....==========.... │ │
│ │ #################### .................... │ │
│ │ │ │
│ │ Light overlay (8%) Dark overlay (3%) │ │
│ │ adds brightness removes brightness │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────────────────────┘ │
│ │
│ KEY INSIGHT: The name "light overlay" is semantic, not literal │
│ In dark theme: adds light (brightens) │
│ In light theme: adds darkness (same UX effect) │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
THE CENTER
How Shadows Communicate Information Flow
Connection to Core-Flow:
├── Elevation = information priority
├── Higher elements (more shadow) = more important
├── Modal backdrops block lower-priority content
└── Shadow intensity guides user attention
- No shadow: Base content, part of the flow
- Light shadow (5-10%): Slightly elevated, interactive elements
- Medium shadow (20%): Important UI components, dropdowns
- Heavy shadow (40%): Critical dialogs, high-priority interruptions
- Backdrop (70%): Modal state, blocking content
State Changes
Learn how colors flow through hover, active, and disabled states