CSS Debugging and Development Tools

/* CSS Layers Inspector (Chrome 99+):*/
<!-- View @layer cascade order -->
DevTools → Elements → Styles → Click layer badge
Shows: Layer name, order, specificity within layer

/* Container Query Badge (Chrome 106+):*/
<!-- Hover over @container rules -->
Shows: Container element, container size, query conditions
Click badge → Highlights container in page

/* CSS Nesting Visualization (Chrome 120+):*/
<!-- Nested selectors are indented -->
.card {
  & .title { /* Indented to show nesting */
    &:hover { /* Further indented */
    }
  }
}

<!-- Step 1: Isolate the problem -->
1. Identify affected element in DevTools
2. Check Computed styles for unexpected values
3. Verify box model (width/height/padding/margin)

<!-- Step 2: Check cascade -->
4. Styles panel: Which rules apply?
5. Are rules crossed out (overridden)?
6. Check specificity: id (1,0,0) > class (0,1,0) > element (0,0,1)

<!-- Step 3: Verify layout context -->
7. Is parent a flex/grid container?
8. Is element positioned (relative/absolute/fixed)?
9. Does element create stacking context?

<!-- Step 4: Test inheritance -->
10. Check inherited properties (color, font-size, line-height)
11. Verify if property is inheritable
12. Look for explicit 'inherit' or 'initial' values

<!-- Step 5: Browser/rendering issues -->
13. Test in different browsers (vendor prefixes needed?)
14. Check for typos in property names
15. Validate CSS syntax (missing semicolons, braces)

<!-- Bug: Margin collapse -->
<!-- Problem: Vertical margins merge unexpectedly -->
.parent { 
  padding-top: 1px; /* Or border-top, or overflow: auto */
}
/* Prevents first child's margin from collapsing with parent */

<!-- Bug: Flexbox item not shrinking -->
.item { 
  min-width: 0; /* Or min-height: 0 for vertical flex */
}
/* Default min-width: auto prevents shrinking below content */

<!-- Bug: Z-index not working -->
.element { 
  position: relative; /* Or absolute/fixed/sticky */
  z-index: 10;
}
/* Z-index only works on positioned elements */

<!-- Bug: 100vh causing overflow on mobile -->
.fullscreen {
  height: 100dvh; /* Dynamic viewport height */
  /* Or: height: 100svh for small viewport height */
}

<!-- Bug: Text overflowing container -->
.container {
  overflow-wrap: break-word;
  word-break: break-word;
  hyphens: auto;
}

<!-- Bug: Grid items overlapping -->
.grid {
  grid-auto-rows: minmax(100px, auto);
  /* Or: grid-auto-flow: dense; for masonry effect */
}

{
  "extends": "stylelint-config-standard",
  "rules": {
    "indentation": 2,
    "string-quotes": "double",
    "no-duplicate-selectors": true,
    "color-hex-case": "lower",
    "color-hex-length": "short",
    "color-named": "never",
    "selector-max-id": 0,
    "selector-combinator-space-after": "always",
    "selector-attribute-quotes": "always",
    "declaration-block-trailing-semicolon": "always",
    "declaration-colon-space-after": "always",
    "declaration-colon-space-before": "never",
    "property-no-vendor-prefix": true,
    "value-no-vendor-prefix": true,
    "number-leading-zero": "always",
    "function-url-quotes": "always",
    "font-weight-notation": "numeric",
    "comment-whitespace-inside": "always",
    "rule-empty-line-before": ["always", {
      "except": ["first-nested"]
    }]
  }
}

module.exports = {
  plugins: [
    require('autoprefixer')({
      overrideBrowserslist: ['last 2 versions', '> 1%', 'not dead']
    }),
    require('postcss-preset-env')({
      stage: 3,
      features: {
        'nesting-rules': true,
        'custom-properties': true,
        'custom-media-queries': true
      }
    }),
    require('cssnano')({
      preset: ['default', {
        discardComments: { removeAll: true },
        normalizeWhitespace: true,
        minifyFontValues: true
      }]
    })
  ]
};

<!-- Usage -->
npx postcss src/styles.css -o dist/styles.css

<!-- purgecss.config.js -->
module.exports = {
  content: ['./src/**/*.html', './src/**/*.js', './src/**/*.jsx'],
  css: ['./src/**/*.css'],
  safelist: {
    standard: ['active', 'show', 'fade'],
    deep: [/^modal-/, /^dropdown-/],
    greedy: [/^data-/]
  },
  defaultExtractor: content => content.match(/[\w-/:]+(?<!:)/g) || []
};

<!-- CLI usage -->
purgecss --config ./purgecss.config.js --output dist/

<!-- Result: 80-95% size reduction typical -->

{
  "id": "css_regression_test",
  "viewports": [
    { "label": "phone", "width": 375, "height": 667 },
    { "label": "tablet", "width": 768, "height": 1024 },
    { "label": "desktop", "width": 1920, "height": 1080 }
  ],
  "scenarios": [
    {
      "label": "Homepage",
      "url": "http://localhost:3000",
      "selectors": ["document"],
      "delay": 1000,
      "misMatchThreshold": 0.1
    },
    {
      "label": "Button Hover State",
      "url": "http://localhost:3000",
      "selectors": [".btn-primary"],
      "hoverSelector": ".btn-primary",
      "delay": 500
    }
  ],
  "paths": {
    "bitmaps_reference": "backstop_data/bitmaps_reference",
    "bitmaps_test": "backstop_data/bitmaps_test",
    "html_report": "backstop_data/html_report"
  },
  "engine": "puppeteer",
  "report": ["browser", "CI"]
}

<!-- Commands -->
backstop reference  # Create baseline screenshots
backstop test       # Compare current vs reference
backstop approve    # Update reference with current

// tests/visual.spec.js
import { test, expect } from '@playwright/test';

test('homepage visual regression', async ({ page }) => {
  await page.goto('http://localhost:3000');
  
  // Wait for fonts and images to load
  await page.waitForLoadState('networkidle');
  
  // Take full-page screenshot
  await expect(page).toHaveScreenshot('homepage.png', {
    fullPage: true,
    maxDiffPixels: 100
  });
});

test('responsive layout', async ({ page }) => {
  await page.setViewportSize({ width: 375, height: 667 });
  await page.goto('http://localhost:3000');
  await expect(page).toHaveScreenshot('mobile.png');
  
  await page.setViewportSize({ width: 1920, height: 1080 });
  await expect(page).toHaveScreenshot('desktop.png');
});

test('dark mode theme', async ({ page }) => {
  await page.emulateMedia({ colorScheme: 'dark' });
  await page.goto('http://localhost:3000');
  await expect(page).toHaveScreenshot('dark-mode.png');
});

<!-- Test checklist for visual regression -->

1. **Responsive Breakpoints**
   - Test at 320px, 375px, 768px, 1024px, 1440px, 1920px
   - Verify no horizontal scroll at any breakpoint
   - Check text doesn't overflow containers

2. **Interactive States**
   - :hover, :focus, :active, :disabled states
   - Form validation states (error, success, warning)
   - Loading states, skeleton screens

3. **Theme Variations**
   - Light mode vs dark mode
   - High contrast mode (forced-colors)
   - Custom theme configurations

4. **Typography**
   - Font loading (FOIT vs FOUT)
   - Line wrapping at different widths
   - Text scaling at 200% zoom (WCAG)

5. **Browser Quirks**
   - Test in Chrome, Firefox, Safari
   - Check vendor prefix fallbacks
   - Verify CSS feature support detection

6. **Performance**
   - Above-fold content rendering
   - Layout shift (CLS) measurements
   - Animation smoothness (no jank)

<!-- Step-by-step CSS performance audit -->

1. **Open DevTools Performance Panel**
   - F12 → Performance tab
   - Click record (⚫) button
   - Perform user interaction (scroll, click, hover)
   - Stop recording

2. **Analyze Flame Chart**
   - Look for yellow bars = JavaScript execution
   - Purple bars = Rendering (Recalculate Style, Layout, Paint)
   - Green bars = Painting
   - Find longest bars (bottlenecks)

3. **Check Specific Events**
   - **Recalculate Style:** Which selectors are slow?
     • Click event → Bottom-Up tab → Filter by "Recalculate Style"
     • Shows selector complexity cost
   
   - **Layout (Reflow):** Are you forcing layout?
     • Look for Layout after style change
     • Indicates read-then-write pattern (layout thrashing)
   
   - **Paint:** What's being repainted?
     • Large paint areas indicate expensive operations
     • Check if will-change or transform can help

4. **Enable Paint Flashing**
   - DevTools → More tools → Rendering
   - Enable "Paint flashing"
   - Green = repaint happening
   - Goal: Minimize green during scroll/animation

5. **Check Layer Composition**
   - Rendering → Layer borders (shows composited layers)
   - Orange borders = compositor layers
   - Too many layers = memory overhead
   - Too few = main thread bottleneck

<!-- Critical CSS extraction -->
<!-- Inline critical CSS in <head> -->
<style>
  /* Above-fold CSS only (~14KB max) */
  .header, .hero, .nav { /* ... */ }
</style>
<link rel="preload" href="styles.css" as="style" 
      onload="this.onload=null;this.rel='stylesheet'">

<!-- CSS loading strategies -->
<!-- 1. Blocking (default) - Delays render -->
<link rel="stylesheet" href="critical.css">

<!-- 2. Preload - Load async, apply when ready -->
<link rel="preload" href="non-critical.css" as="style">

<!-- 3. Media query - Only load when needed -->
<link rel="stylesheet" href="print.css" media="print">
<link rel="stylesheet" href="large.css" media="(min-width: 1200px)">

<!-- Selector performance -->
/* ❌ Slow - Right-to-left matching */
div div div p { color: red; }
* { margin: 0; } /* Universal selector is slow */
[type="text"] { } /* Attribute without element is slow */

/* ✅ Fast - Single class */
.text-red { color: red; }
.paragraph { }
input[type="text"] { }

<!-- Optimize animations -->
/* ❌ Causes layout/paint on every frame */
@keyframes slide {
  from { left: 0; }
  to { left: 100px; }
}

/* ✅ Uses compositor (GPU) */
@keyframes slide {
  from { transform: translateX(0); }
  to { transform: translateX(100px); }
}

<!-- Prevent layout thrashing -->
// ❌ Bad: Read-write-read-write
elements.forEach(el => {
  const height = el.offsetHeight; // Read (forces layout)
  el.style.height = height + 10 + 'px'; // Write
});

// ✅ Good: Batch reads, then batch writes
const heights = elements.map(el => el.offsetHeight); // Batch reads
elements.forEach((el, i) => {
  el.style.height = heights[i] + 10 + 'px'; // Batch writes
});

<!-- Contain property isolates rendering -->
.widget {
  contain: layout style paint;
  /* Browser won't check outside this element for layout/style/paint */
}

.sidebar {
  contain: size layout;
  /* Size won't depend on children, layout is isolated */
}

.comment-list {
  contain: content;
  /* Shorthand for layout + style + paint */
}

<!-- content-visibility for lazy rendering -->
.long-article section {
  content-visibility: auto;
  contain-intrinsic-size: 0 500px;
  /* Browser skips rendering off-screen sections */
  /* Huge performance win for long pages */
}

<!-- Results -->
Without content-visibility: 2000ms initial render
With content-visibility: 400ms initial render (5x faster!)

<!-- will-change for animation optimization -->
.modal {
  will-change: transform, opacity;
  /* Creates compositor layer before animation starts */
}

/* ⚠️ Remove will-change after animation completes */
.modal.animating {
  will-change: transform;
}
.modal:not(.animating) {
  will-change: auto; /* Let browser optimize */
}