gh-anthemflynn-ccmp-plugins-website-debug/skills/website-debug/references/css-debug.md

CSS Debugging Reference

Advanced CSS debugging workflows and patterns for frontend development.

Quick Diagnostics

Check Element Visibility

# Is element visible?
./browser-eval.js '(() => {
  const el = document.querySelector(".target");
  const s = getComputedStyle(el);
  return {
    display: s.display,
    visibility: s.visibility,
    opacity: s.opacity,
    hidden: el.hidden,
    height: s.height,
    width: s.width,
    overflow: s.overflow
  };
})()'

Element Not Showing?

Common causes and checks:

# Check display property
./browser-eval.js 'getComputedStyle(document.querySelector(".target")).display'
# If "none" - element is hidden by CSS

# Check visibility
./browser-eval.js 'getComputedStyle(document.querySelector(".target")).visibility'
# If "hidden" - element takes space but invisible

# Check opacity
./browser-eval.js 'getComputedStyle(document.querySelector(".target")).opacity'
# If "0" - element is transparent

# Check dimensions
./browser-eval.js 'document.querySelector(".target").getBoundingClientRect()'
# If width/height is 0 - element has no size

# Check if off-screen
./browser-eval.js '(() => {
  const r = document.querySelector(".target").getBoundingClientRect();
  return {
    inViewport: r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth,
    position: { top: r.top, left: r.left }
  };
})()'

Layout Issues

Flexbox Debugging

# Check flex container
./browser-eval.js '(() => {
  const el = document.querySelector(".flex-container");
  const s = getComputedStyle(el);
  return {
    display: s.display,
    flexDirection: s.flexDirection,
    justifyContent: s.justifyContent,
    alignItems: s.alignItems,
    flexWrap: s.flexWrap,
    gap: s.gap
  };
})()'

# Check flex items
./browser-eval.js '[...document.querySelectorAll(".flex-container > *")].map(el => {
  const s = getComputedStyle(el);
  return {
    flexGrow: s.flexGrow,
    flexShrink: s.flexShrink,
    flexBasis: s.flexBasis,
    alignSelf: s.alignSelf
  };
})'

Grid Debugging

# Check grid container
./browser-eval.js '(() => {
  const el = document.querySelector(".grid-container");
  const s = getComputedStyle(el);
  return {
    display: s.display,
    gridTemplateColumns: s.gridTemplateColumns,
    gridTemplateRows: s.gridTemplateRows,
    gap: s.gap,
    gridAutoFlow: s.gridAutoFlow
  };
})()'

Box Model

# Full box model breakdown
./browser-eval.js '(() => {
  const el = document.querySelector(".target");
  const s = getComputedStyle(el);
  const r = el.getBoundingClientRect();
  return {
    content: { width: r.width, height: r.height },
    padding: { top: s.paddingTop, right: s.paddingRight, bottom: s.paddingBottom, left: s.paddingLeft },
    border: { top: s.borderTopWidth, right: s.borderRightWidth, bottom: s.borderBottomWidth, left: s.borderLeftWidth },
    margin: { top: s.marginTop, right: s.marginRight, bottom: s.marginBottom, left: s.marginLeft },
    boxSizing: s.boxSizing
  };
})()'

Positioning Problems

Z-Index Stacking

# Find all positioned elements with z-index
./browser-eval.js '[...document.querySelectorAll("*")].filter(el => {
  const s = getComputedStyle(el);
  return s.position !== "static" && s.zIndex !== "auto";
}).map(el => ({
  selector: el.tagName + (el.id ? "#" + el.id : "") + (el.className ? "." + el.className.split(" ")[0] : ""),
  position: getComputedStyle(el).position,
  zIndex: getComputedStyle(el).zIndex
})).sort((a, b) => parseInt(b.zIndex) - parseInt(a.zIndex))'

Fixed/Sticky Elements

# Find fixed/sticky elements
./browser-eval.js '[...document.querySelectorAll("*")].filter(el => {
  const pos = getComputedStyle(el).position;
  return pos === "fixed" || pos === "sticky";
}).map(el => ({
  tag: el.tagName.toLowerCase(),
  id: el.id,
  class: el.className,
  position: getComputedStyle(el).position
}))'

Responsive Issues

Media Query Testing

# Test different breakpoints
./browser-resize.js --mobile && ./browser-screenshot.js --output=/tmp/mobile.png
./browser-resize.js --tablet && ./browser-screenshot.js --output=/tmp/tablet.png  
./browser-resize.js --desktop && ./browser-screenshot.js --output=/tmp/desktop.png

Check Current Viewport

./browser-eval.js '({
  viewport: { width: window.innerWidth, height: window.innerHeight },
  screen: { width: screen.width, height: screen.height },
  devicePixelRatio: window.devicePixelRatio
})'

Typography Issues

Font Not Loading

# Check computed font
./browser-eval.js 'getComputedStyle(document.querySelector(".text")).fontFamily'

# Check if webfont loaded
./browser-eval.js 'document.fonts.check("16px YourFontName")'

# List all loaded fonts
./browser-eval.js '[...document.fonts].map(f => ({ family: f.family, style: f.style, weight: f.weight, status: f.status }))'

Text Overflow

# Check text overflow settings
./browser-eval.js '(() => {
  const el = document.querySelector(".truncated-text");
  const s = getComputedStyle(el);
  return {
    overflow: s.overflow,
    textOverflow: s.textOverflow,
    whiteSpace: s.whiteSpace,
    width: s.width,
    maxWidth: s.maxWidth
  };
})()'

Color & Visual

Check Colors

# Get all colors used on element
./browser-eval.js '(() => {
  const el = document.querySelector(".target");
  const s = getComputedStyle(el);
  return {
    color: s.color,
    backgroundColor: s.backgroundColor,
    borderColor: s.borderColor,
    outlineColor: s.outlineColor
  };
})()'

Find Elements by Color

# Find all elements with a specific background
./browser-eval.js '[...document.querySelectorAll("*")].filter(el => 
  getComputedStyle(el).backgroundColor === "rgb(255, 0, 0)"
).map(el => el.tagName + (el.id ? "#" + el.id : ""))'

Performance Concerns

Large DOM Check

./browser-eval.js '({
  totalElements: document.querySelectorAll("*").length,
  deepestNesting: (() => {
    let max = 0;
    document.querySelectorAll("*").forEach(el => {
      let depth = 0, node = el;
      while (node.parentElement) { depth++; node = node.parentElement; }
      if (depth > max) max = depth;
    });
    return max;
  })()
})'

Reflow Triggers

Watch for properties that cause layout recalculation:

• offsetTop/Left/Width/Height
• scrollTop/Left/Width/Height
• clientTop/Left/Width/Height
• getComputedStyle()
• getBoundingClientRect()

Animation Debugging

Check Animations

./browser-eval.js '(() => {
  const el = document.querySelector(".animated");
  const s = getComputedStyle(el);
  return {
    animation: s.animation,
    animationName: s.animationName,
    animationDuration: s.animationDuration,
    animationTimingFunction: s.animationTimingFunction,
    animationDelay: s.animationDelay,
    transition: s.transition
  };
})()'

Force Animation State

# Pause all animations
./browser-eval.js 'document.querySelectorAll("*").forEach(el => el.style.animationPlayState = "paused")'

# Resume animations
./browser-eval.js 'document.querySelectorAll("*").forEach(el => el.style.animationPlayState = "")'

Common CSS Fixes

Overflow Scroll Not Working

Check these in order:

1. Parent has defined height
2. overflow is set to scroll or auto
3. Content is actually taller than container

Element Behind Another

1. Check z-index values
2. Ensure positioned (relative/absolute/fixed)
3. Check stacking context (transform, opacity < 1, etc. create new contexts)

Flexbox Not Centering

1. Container has height
2. align-items for vertical, justify-content for horizontal
3. Check flex-direction - swaps main/cross axis