ej-html-css-bug-fix

name: ej-html-css-bug-fix description: EJ's structured HTML/CSS debugging workflow emphasizing systematic root cause analysis, visual inspection, and cross-browser testing. Use when fixing layout issues, CSS not applying, flexbox/grid problems, z-index stacking issues, responsive breakpoints, overflow/spacing bugs, or cross-browser inconsistencies in HTML and CSS code.

HTML/CSS Bug Fix Workflow

A systematic approach to debugging layout and styling issues that prioritizes understanding over quick fixes.

Bug Categories

Identify which category first:

Process

1. Reproduce & Isolate

• Identify which browsers and viewport sizes are affected
• Hard refresh (Ctrl+Shift+R) to rule out caching
• Test in incognito mode (extensions can interfere)
• Use DevTools responsive mode to find exact breakpoint

2. Identify Root Causes (minimum 2)

Propose at least two possible causes before investigating.

Use DevTools systematically:

• Elements tab: inspect the problem element
• Computed tab: see final calculated values
• Box Model diagram: check margin/padding/border
• Toggle CSS rules on/off to isolate the culprit

3. Confirm with User

Present findings and get agreement on root cause before proceeding.

4. Propose Solutions (minimum 2)

For the confirmed root cause, propose at least two fix approaches. Evaluate trade-offs: browser support, maintainability, side effects.

5. Risk Assessment

Before applying any fix:

• Could this break other components?
• Cross-browser implications? (check caniuse.com)
• Mobile/tablet impact?

Present: Risks | Before state | After state

6. Apply & Verify

• Test across browsers (Chrome, Firefox, Safari, Edge)
• Test responsive breakpoints
• If testing not possible, provide manual verification steps

Quick Diagnosis by Category

Box Model Issues

Element larger/smaller than expected

• Check: box-sizing (content-box vs border-box)
• Fix: * { box-sizing: border-box; }

Margins collapsing

• Check: Adjacent vertical margins combine (30px + 20px = 30px, not 50px)
• Fix: Use padding, flexbox, or overflow: hidden on parent

Content overflowing

• Check: Fixed width/height on container
• Fix: Use min-height, max-width, or overflow property

Flexbox Issues

Items not wrapping

• Check: flex-wrap (default is nowrap)
• Fix: flex-wrap: wrap;

Item won't shrink below content

• Check: min-width defaults to auto
• Fix: min-width: 0; or overflow: hidden;

Unexpected stretching

• Check: align-items (default is stretch)
• Fix: align-items: flex-start; or align-self on item

Content overflow in flex item

• Check: flex-basis and width interaction
• Fix: flex: 1 1 0%; min-width: 0;

Grid Issues

Items stacking instead of columns

• Check: display: grid set? grid-template-columns defined?
• Fix: grid-template-columns: repeat(3, 1fr);

Items in wrong position

• Check: Explicit vs auto placement
• Fix: Use grid-column/grid-row or named areas

Gap not working

• Check: Older browser? (gap in flexbox is newer)
• Fix: Use margin fallback or check browser support

Z-index / Stacking Context

z-index has no effect

• Check: Is element positioned? (needs relative/absolute/fixed)
• Fix: Add position: relative;

High z-index still hidden

• Check: Parent's stacking context (z-index, transform, opacity, filter)
• Fix: Move element outside parent OR raise parent's z-index

Modal behind overlay

• Check: Each creates own stacking context
• Fix: Use isolation: isolate; on containers, or restructure DOM

Stacking context triggers:

• position + z-index (not auto)
• opacity < 1
• transform, filter, backdrop-filter
• will-change
• isolation: isolate

Specificity Issues

Style not applying

• Check: Computed tab - is it crossed out? By what selector?
• Fix: Increase specificity or use same selector level

!important not working

• Check: Another !important with higher specificity
• Fix: Refactor to avoid !important wars

Specificity order (low to high): element < .class < #id < inline < !important

Responsive Issues

Media query not firing

• Check: Viewport meta tag present?
• Fix: <meta name="viewport" content="width=device-width, initial-scale=1">

Layout breaks at specific width

• Check: Fixed widths, non-wrapping flex, large images
• Fix: Use max-width: 100%; flex-wrap; relative units

Horizontal scroll on mobile

• Check: Elements with fixed width > viewport
• Fix: overflow-x: hidden on body (temporary); find culprit element

DevTools Cheatsheet

Browser Extensions

• CSS Stacking Context Inspector: visualize z-index issues
• VisBug: visual debugging for spacing and colors
• Responsive Viewer: test multiple viewports simultaneously

Common Gotchas