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
Copy
/* 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
Copy
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.Copy
/* 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
Copy
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
Copy
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.Copy
--overlay-backdrop: rgba(0, 0, 0, 0.7);
Backdrop Purpose and Psychology
Copy
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
Copy
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.Copy
/* 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
Copy
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.Copy
/* 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
Copy
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%, transparent)
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.Copy
/* Scrollbar */
--color-scrollbar-thumb: rgba(100, 100, 100, 0.2);
--color-scrollbar-thumb-hover: rgba(100, 100, 100, 0.4);
Scrollbar Transparency Pattern
Copy
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.Copy
[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
Copy
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
Copy
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