Skip to content

CSS Fundamentals — Street-Level Ops

Quick Diagnosis Commands

# Launch Chrome DevTools from command line (useful for headless debugging)
google-chrome --auto-open-devtools-for-tabs http://localhost:3000

# Check if a status page loads correctly (quick smoke test)
curl -s http://localhost:8080/status | grep '<link rel="stylesheet"'
# If no stylesheet link → page will render unstyled

# Validate CSS syntax from the command line
npx stylelint "src/**/*.css" 2>&1 | head -20

# Find CSS files in a project
find /path/to/project -name "*.css" -not -path "*/node_modules/*" | head -20

# Check if a CSS file is being served with correct MIME type
curl -sI http://localhost:8080/static/style.css | grep -i content-type
# Should be: content-type: text/css
# If wrong MIME type, browser silently ignores the stylesheet

# Count CSS rules (rough complexity gauge)
grep -c '{' /path/to/style.css
# > 500 rules in one file = time to split

# Find all !important declarations (code smell)
grep -rn '!important' /path/to/css/ --include="*.css"
# Many hits = specificity war in progress

One-liner: CSS debugging is 80% specificity wars and 20% box model confusion. Learn to read the Computed tab in DevTools and most CSS bugs become obvious.

Gotcha: Broken Layout After Deploying — Missing box-sizing

Symptom: Elements overflow their containers. A 300px-wide sidebar with 20px padding renders at 340px, breaking a grid layout that worked in development.

Rule: Always set box-sizing: border-box globally. Without it, padding and border add to the declared width, making layout math unpredictable.

/* Add this to the top of every project's base CSS */
*, *::before, *::after {
    box-sizing: border-box;
}

Debugging workflow: 1. Open DevTools → Inspect the overflowing element 2. Check the Computed tab → look at the box model diagram 3. If content + padding + border > expected width → box-sizing is content-box 4. Add the global reset above and verify

Gotcha: z-index Not Working

Symptom: You set z-index: 9999 on a modal overlay but it still renders behind a sidebar that has z-index: 2.

Rule: z-index only works on positioned elements (anything except position: static). And z-index is not global — stacking contexts create isolated z-index namespaces.

Remember: Properties that create new stacking contexts: z-index (on positioned elements), opacity < 1, transform, filter, will-change, isolation: isolate. Mnemonic: ZOTFWI — Z-index, Opacity, Transform, Filter, Will-change, Isolation. If your z-index is not working, one of these on a parent is trapping you.

/* Common cause: parent creates a stacking context */
.sidebar {
    position: relative;
    z-index: 2;
    /* opacity, transform, or filter also create stacking contexts */
    opacity: 0.99;  /* THIS creates a new stacking context */
}

/* Even z-index: 9999 inside .sidebar cannot escape its context */
.modal-inside-sidebar {
    z-index: 9999; /* still behind elements outside .sidebar's context */
}

Debugging workflow: 1. DevTools → Inspect the hidden element 2. Check if position is set (not static) 3. Walk up the DOM → look for ancestors with opacity, transform, filter, will-change, or z-index — these create stacking contexts 4. Move the modal element outside the stacking context in the DOM, or restructure z-index values

Gotcha: Margin Collapse Causing Unexpected Gaps

Symptom: Two stacked <div> elements each have margin: 20px. You expect 40px of space between them but see only 20px. Or a child's top margin "leaks" outside its parent container.

/* Margins collapse in these cases: */
/* 1. Adjacent siblings: larger margin wins */
.box1 { margin-bottom: 30px; }
.box2 { margin-top: 20px; }
/* Space between them: 30px (not 50px) */

/* 2. Parent-child: child margin leaks through parent */
.parent { /* no padding, border, or overflow set */ }
.child { margin-top: 20px; }
/* The 20px margin appears ABOVE .parent, not inside it */

/* Fix: give parent padding, border, or overflow */
.parent {
    padding-top: 1px;    /* or */
    overflow: hidden;     /* or */
    display: flow-root;   /* modern, cleanest fix */
}

Pattern: Emergency Status Page Styling

When you need to deploy a quick status page during an incident, use inline styles to avoid external CSS dependencies:

<!-- Self-contained incident status page — no external dependencies -->
<html>
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width">
<title>Service Status</title>
<style>
    * { box-sizing: border-box; margin: 0; padding: 0; }
    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
           max-width: 800px; margin: 2rem auto; padding: 0 1rem;
           background: #0d1117; color: #e6edf3; }
    h1 { margin-bottom: 1rem; }
    .status { padding: 1rem; border-radius: 8px; margin-bottom: 1rem; }
    .status-ok { background: #0d2818; border-left: 4px solid #22c55e; }
    .status-degraded { background: #2d2000; border-left: 4px solid #eab308; }
    .status-down { background: #2d0000; border-left: 4px solid #ef4444; }
    .timestamp { color: #8b949e; font-size: 0.875rem; }
</style>
</head>
<body>
    <h1>Service Status</h1>
    <div class="status status-down">
        <strong>API Gateway</strong> — Down since 14:23 UTC
    </div>
    <div class="status status-ok">
        <strong>Database</strong> — Operational
    </div>
    <p class="timestamp">Last updated: 2026-03-18 14:45 UTC</p>
</body>
</html>

Pattern: Debugging Grafana Custom Panel CSS

Grafana panels with custom HTML/CSS need inline styles or panel-scoped CSS. External stylesheets do not load in panel iframes.

/* Within a Grafana Text panel (HTML mode), scope everything */
.custom-panel {
    font-family: monospace;
    font-size: 14px;
}
.custom-panel table {
    width: 100%;
    border-collapse: collapse;
}
.custom-panel td, .custom-panel th {
    padding: 4px 8px;
    border-bottom: 1px solid rgba(255,255,255,0.1);
    text-align: left;
}
/* Use CSS variables for Grafana theme compatibility */
.custom-panel {
    color: var(--grafana-text-color, #e0e0e0);
    background: var(--grafana-background-color, transparent);
}

Pattern: Print-Friendly Documentation Pages

Internal docs and runbooks should be printable. Add print styles:

@media print {
    /* Hide navigation, sidebar, interactive elements */
    nav, .sidebar, .no-print, button, .search { display: none !important; }

    /* Reset colors for readability on paper */
    body { color: #000 !important; background: #fff !important;
           font-size: 11pt; line-height: 1.5; }

    /* Show URLs after links */
    a[href^="http"]::after { content: " (" attr(href) ")";
                              font-size: 0.8em; color: #666; }

    /* Prevent page breaks inside code blocks */
    pre, code, table { page-break-inside: avoid; }

    /* Force single column */
    .layout { display: block !important; }
    .content { width: 100% !important; max-width: none !important; }
}

Pattern: Responsive Dashboard Layout

/* Mobile-first dashboard grid */
.dashboard {
    display: grid;
    gap: 1rem;
    padding: 1rem;
    /* Single column by default (mobile) */
    grid-template-columns: 1fr;
}

/* Tablet: 2 columns */
@media (min-width: 768px) {
    .dashboard { grid-template-columns: 1fr 1fr; }
}

/* Desktop: sidebar + 2 content columns */
@media (min-width: 1200px) {
    .dashboard { grid-template-columns: 250px 1fr 1fr; }
}

/* Cards that work at any column width */
.card {
    background: var(--card-bg, #1e1e2e);
    border-radius: var(--radius, 8px);
    padding: 1rem;
    min-width: 0; /* prevents flex/grid overflow */
}

Default trap: Flex and grid children have an implicit min-width: auto, which prevents them from shrinking below their content size. This causes overflow in containers with long text or images. Always set min-width: 0 on flex/grid children that should be allowed to shrink.

/* Truncate long text in table cells */
.truncate {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
    max-width: 200px;
}

Useful DevTools Shortcuts

Browser DevTools (Chrome/Firefox):
  Ctrl+Shift+I       — Open DevTools
  Ctrl+Shift+C       — Inspect element picker
  Ctrl+Shift+M       — Toggle device/responsive mode

In the Elements panel:
  H                  — Toggle element visibility (display:none)
  Shift+Click color  — Cycle color formats (hex/rgb/hsl)
  Click box model    — Edit margin/padding/border visually

CSS debugging tricks (type in DevTools console):
  document.querySelectorAll('*').forEach(el =>
    el.style.outline = '1px solid red')
  // Outlines all elements — instantly reveals layout boundaries

  getComputedStyle(document.querySelector('.broken-element'))
  // Returns every computed CSS property for debugging