Dark Overlay Architecture
Dark overlays create depth and separation in the UI through shadows, modal backdrops, dimming effects, and depth indicators.Copy
+---------------------------------------------------------------------------------+
| DARK OVERLAY VISUAL HIERARCHY |
+---------------------------------------------------------------------------------+
| |
| ELEVATION SYSTEM |
| ================ |
| |
| +----------------------------------------------+ |
| Level 4 (30%) | MODAL DIALOG | |
| Topmost | +----------------------+ | |
| | | Dialog Content | | |
| | +----------------------+ | |
| +----------------------------------------------+ |
| ^ |
| | overlay-dark-4 (30% black) |
| | |
| +----+---------------------------------------------+ |
| Level 3 (20%) | DROPDOWN MENU | |
| High elevation | +--------------------+ | |
| | | Option 1 | | |
| | | Option 2 | | |
| | +--------------------+ | |
| +--------------------------------------------------+ |
| ^ |
| | overlay-dark-3 (20% black) |
| | |
| +----+---------------------------------------------+ |
| Level 2 (10%) | SIDEBAR | |
| Medium elevation | File Explorer | |
| | Project Files | |
| +--------------------------------------------------+ |
| ^ |
| | overlay-dark-2 (10% black) |
| | |
| +----+---------------------------------------------+ |
| Level 1 (5%) | CONTENT | |
| Base elevation | Main editor/terminal area | |
| +--------------------------------------------------+ |
| |
+---------------------------------------------------------------------------------+
Why Black for Dark Overlays?
Unlike light overlays which derive from theme text color, dark overlays use a fixed black value.Copy
+---------------------------------------------------------------------------------+
| WHY BLACK FOR DARK OVERLAYS |
+---------------------------------------------------------------------------------+
| |
| LIGHT OVERLAYS DARK OVERLAYS |
| ============== ============= |
| |
| Source: Theme text color Source: Black (fixed) |
| Adapts to theme Universal behavior |
| |
| REASONS FOR FIXED BLACK: |
| ======================== |
| |
| 1. UNIVERSAL DARKENING |
| Black works to darken any background |
| |
| 2. NO HUE SHIFT |
| Pure black does not introduce unwanted color |
| |
| 3. PREDICTABLE BEHAVIOR |
| Same shadow appearance across themes |
| |
| 4. PERFORMANCE |
| No variable resolution needed |
| |
+---------------------------------------------------------------------------------+
Dialog Shadow System
Dialogs need prominent shadows to establish elevation.Copy
+---------------------------------------------------------------------------------+
| DIALOG SHADOW LAYER ANALYSIS |
+---------------------------------------------------------------------------------+
| |
| LARGE DIALOG SHADOW |
| =================== |
| |
| 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 |
| opacity: 40% Heavy but not solid |
| |
| +---------------------------------------------------------------------+ |
| | | |
| | +-----------------------------------+ | |
| | | | | |
| | | DIALOG CONTENT | | |
| | | | | |
| | +-----------------------------------+ | |
| | .................................... | |
| | .................................. | |
| | .............................. | |
| | .......................... | |
| | .................... | |
| | .......... | |
| | | |
| | . = Shadow blur area (48px radius, 40% opacity) | |
| | | |
| +---------------------------------------------------------------------+ |
| |
+---------------------------------------------------------------------------------+
| |
| SMALL POPOVER SHADOW |
| ==================== |
| |
| offset-y: 4px Small offset (subtle elevation) |
| blur-radius: 12px Tight blur (crisp edges) |
| opacity: 15% Subtle appearance |
| |
| Use case: Tooltips, dropdowns, small popovers |
| |
+---------------------------------------------------------------------------------+
Modal Backdrop: The 70% Standard
Modal backdrops use 70% black opacity - an industry standard.Copy
+---------------------------------------------------------------------------------+
| MODAL BACKDROP PSYCHOLOGY |
+---------------------------------------------------------------------------------+
| |
| 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 |
| |
+---------------------------------------------------------------------------------+
| |
| 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
Copy
+---------------------------------------------------------------------------------+
| BACKDROP VS DARK OVERLAY COMPARISON |
+---------------------------------------------------------------------------------+
| |
| MODAL BACKDROP DARK OVERLAY-4 |
| ============== =============== |
| |
| 70% opacity 30% opacity |
| |
| 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) | |
| | | |
| +---------------------------------------------------------------------+ |
| |
+---------------------------------------------------------------------------------+
Focus and Hover State Hierarchy
Interactive states progress through increasing overlay opacity.Copy
+---------------------------------------------------------------------------------+
| FOCUS AND HOVER STATE HIERARCHY |
+---------------------------------------------------------------------------------+
| |
| STATE PROGRESSION: |
| ================== |
| |
| Normal --> Hover --> Focus --> Active --> Selected |
| 0% 8% 12% 16% 20% |
| |
+---------------------------------------------------------------------------------+
| |
| NORMAL STATE |
| Background: transparent (0%) |
| ................................................................ |
| |
| HOVER STATE |
| Background: overlay-light-1 (8%) |
| #............................................................... |
| |
| FOCUS STATE |
| Background: overlay-light-2 (12%) |
| + Border ring for accessibility |
| ##.............................................................. |
| |
| ACTIVE/PRESSED STATE |
| Background: overlay-light-3 (16%) |
| ###............................................................. |
| |
| SELECTED STATE |
| Background: 20% of primary color (not neutral) |
| Uses primary color instead of neutral overlay |
| ####............................................................ |
| |
+---------------------------------------------------------------------------------+
Transparent Border System
Borders can use transparency for adaptive appearance.Copy
+---------------------------------------------------------------------------------+
| TRANSPARENT BORDER SYSTEM |
+---------------------------------------------------------------------------------+
| |
| DARK BORDER: 20% black + transparent |
| ======================================== |
| |
| Result: 20% black semi-transparent border |
| Adapts to ANY background - darkens by 20% |
| |
| +--------------------------------------------------------------------+ |
| | On light background: ................ (visible as light gray) | |
| | On dark background: ################ (visible as dark line) | |
| | Always visible, always appropriate | |
| +--------------------------------------------------------------------+ |
| |
| ADAPTIVE DIVIDERS |
| ================= |
| |
| Theme text color at 15% - adapts automatically |
| |
| Dark theme: 15% of light gray on dark background |
| Light theme: 15% of near-black on light background |
| |
+---------------------------------------------------------------------------------+
Light Theme Shadow Adjustments
Light themes need less shadow intensity because dark-on-light is more visible.Copy
+---------------------------------------------------------------------------------+
| DARK VS LIGHT THEME SHADOW COMPARISON |
+---------------------------------------------------------------------------------+
| |
| DARK THEME LIGHT THEME |
| ========== =========== |
| |
| 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% |
| |
| KEY INSIGHT: |
| ============ |
| |
| In light theme, "light overlays" actually use BLACK with lower opacity |
| The semantic meaning is "interaction highlight" not "add white" |
| |
| Light themes need LESS intensity to achieve the same visual effect |
| because dark-on-light is naturally more visible than light-on-dark |
| |
+---------------------------------------------------------------------------------+
Shadow and Overlay Design Principles
Copy
+---------------------------------------------------------------------------------+
| SHADOW AND OVERLAY DESIGN PRINCIPLES |
+---------------------------------------------------------------------------------+
| |
| 1. ELEVATION CORRELATES WITH SHADOW INTENSITY |
| Higher elements cast stronger shadows |
| Level 1: 5% -> Level 2: 10% -> Level 3: 20% -> Level 4: 30% |
| |
| 2. MODAL BACKDROPS USE FIXED 70% OPACITY |
| Industry standard for focus attention |
| Strong enough to separate, not so dark as to feel oppressive |
| |
| 3. DARK OVERLAYS USE BLACK (UNIVERSAL) |
| Unlike light overlays which adapt to theme text color |
| Black works universally for darkening |
| |
| 4. CONTEXT MENUS USE SOLID BACKGROUNDS |
| Not transparent - ensures readability |
| Elevation communicated through shadow, not transparency |
| |
| 5. THEME-SPECIFIC SHADOW INTENSITY |
| Light themes need LESS shadow intensity |
| Dark-on-light is more visible than light-on-dark |
| |
+---------------------------------------------------------------------------------+
Summary: Shadow Pattern Reference
Copy
+---------------------------------------------------------------------------------+
| SHADOW PATTERN REFERENCE |
+---------------------------------------------------------------------------------+
| |
| PATTERN TRANSPARENT OPACITY USE CASE |
| ------- ----------- ------- -------- |
| |
| overlay-dark-1 95% 5% Subtle shadows |
| overlay-dark-2 90% 10% Light shadows |
| overlay-dark-3 80% 20% Medium shadows |
| overlay-dark-4 70% 30% Heavy shadows |
| overlay-backdrop 30% 70% Modal backdrop |
| |
| SHADOW OFFSET BLUR OPACITY USE CASE |
| ------ ------ ---- ------- -------- |
| |
| dialog-shadow 12px 48px 40% Dialog elevation |
| dialog-shadow-sm 4px 12px 15% Small popover |
| |
+---------------------------------------------------------------------------------+
State Transitions
Learn about hover, active, and disabled state derivations