Dark Overlay Architecture
Dark overlays create depth and separation in the UI through shadows, modal backdrops, dimming effects, and depth indicators.┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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.┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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.┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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.┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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.┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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.┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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.┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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
┌─────────────────────────────────────────────────────────────────────────────────┐
│ 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