Documentation Index
Fetch the complete documentation index at: https://docs.monolex.ai/llms.txt
Use this file to discover all available pages before exploring further.
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