# CSS Z-Index & Overflow Clipping Debugging

## Symptom
A dropdown, tooltip, or popup renders but is cut off / hidden behind elements below it.

## Root Cause (almost always one of these)

1. **Parent `overflow: hidden`** — the dropdown's parent container clips it via CSS overflow
2. **Missing or broken z-index** — the dropdown has no z-index, or its z-index CSS variable is undefined
3. **Stacking context** — a parent creates a new stacking context (via `position: relative + z-index`, `opacity < 1`, `transform`, `filter`, `will-change`) which limits how high the child can stack
4. **Parent position / overflow conflicts** — `position: relative` on a grandparent with `overflow: hidden` blocks absolute children even with high z-index
5. **Sibling DOM ordering** — the header wrapper has no z-index, so its sibling (main content) paints on top by default

## Diagnosis Checklist

### 1. Check parent overflow
```bash
# Search for overflow:hidden on or near the dropdown's container
search_files("overflow-hidden", file_glob="*.html", path="src/")
search_files("overflow-hidden", file_glob="*.css", path="src/")
search_files("overflow.*hidden", file_glob="*.html", path="src/")
```

### 2. Check CSS variable definitions
```bash
# If the dropdown uses a CSS variable for z-index, verify it's defined
# e.g., `z-index: var(--z-critical) !important;` without `--z-critical: N;` in :root = broken
search_files("--z-", file_glob="*.css", path="src/")
search_files("var\(--z-", file_glob="*.html", path="src/")
search_files("var\(--z-", file_glob="*.js", path="src/")
```

A CSS variable referenced but never defined evaluates to `z-index: invalid` — effectively no z-index at all.

### 3. Check the element's actual z-index
In browser dev tools: inspect the dropdown → computed styles → z-index. If it says `invalid` or isn't listed, the variable isn't resolving.

### 4. Check the outer wrapper's position and z-index
Even when the dropdown and its immediate parent have high z-index, the **outermost header wrapper** may lack `position: relative`, allowing the next DOM sibling (main content) to paint on top.

Check: Does the `<div>` that wraps the entire header have `position: relative` and `z-index`?

## Fixes

### Fix 1: Ensure parent overflow is visible
On the dropdown's immediate positioned parent:
```css
overflow: visible !important;
```
Or remove `overflow-hidden` from the Tailwind class list if `overflow-visible-important` is already applied.

### Fix 2: Define undefined CSS variables
```css
:root {
    --z-critical: 999999;
}
```

### Fix 3: Set z-index on the header card
```css
.header-card {
    z-index: 100;
    position: relative;
}
```
This keeps the header above page content, so the dropdown (which is a child) can stack above content below the header.

### Fix 4: Remove conflicting Tailwind classes
If a div has both `overflow-hidden` AND a class that sets `overflow: visible !important`, remove `overflow-hidden` — the `!important` should win in theory, but mobile Safari and some browsers handle this inconsistently.

### Fix 5: Set z-index on the outer header wrapper (non-obvious)
Even with Fix 1-4, the dropdown can be covered by page content. This happens when the **outermost header div** doesn't create a stacking context:

```html
<div class="header-wrapper">           ← NEEDS position:relative + z-index
  <div class="header-card z-100">      ← Fix 3 applied
    <div id="user-dropdown" z-10001>   ← high z-index
  </div>
</div>

<div class="main-content">             ← SIBLING of header-wrapper
  ...                                  ← paints ON TOP without Fix 5
</div>
```

**Fix:** Add `position: relative; z-index: 1000;` to the outermost header wrapper div (not just the header-card inside it). A value of 1000 is enough to beat any content z-index below.

## Multi-Layer Verification

After fixing, check ALL pages that share the same component:
- Search for the same CSS classes/IDs across all HTML files
- Check if each page has its own `<style>` block that overrides the shared stylesheet
- Verify that shared stylesheet changes (e.g., `style.css`) apply to all pages

## Common Pattern: Header Dropdown Clipping

```
<div class="header-card overflow-hidden">   ← PROBLEM: clips children
  <div class="user-menu-container relative">
    <div id="user-dropdown">...</div>       ← gets clipped
  </div>
</div>
```

Fix: Remove `overflow-hidden` from `header-card`, add `z-index` to it, and ensure the dropdown has a defined high z-index. Add `.user-menu-container { overflow: visible !important; }` for safety. Then add `position: relative; z-index: 1000` to the outer header wrapper to beat sibling DOM ordering.