01 — CSS Engine Internals & Production Setup

/* A "rule" = selector list + declaration block.
   The engine tokenizes, parses into CSSOM, then matches. */
@layer reset, base, components, utilities;  /* layer order declared FIRST → fixes precedence for the whole sheet */

@layer reset {
  /* Universal selector: specificity (0,0,0,0). Cheap to match,
     but forces a style recalc on every element. Keep resets tiny. */
  *, *::before, *::after {
    box-sizing: border-box;   /* width includes padding+border → math matches design specs */
    margin: 0;                /* nuke UA margins so spacing is a deliberate token, not inherited chaos */
    padding: 0;
  }
}

/* At-rules (@media, @keyframes, @supports, @layer, @import) are
   processed at parse time. @import MUST precede all other rules
   except @charset — put it later and the engine silently drops it. */
@supports (display: grid) {   /* feature detection at parse time, not UA sniffing */
  @layer base {
    :root { --layout: grid; } /* custom property: registered on :root, inherits to every descendant */
  }
}

/* ❌ ANTI-PATTERN — unlayered, ad-hoc, specificity will spiral */
* { margin: 0; }                      /* reset mixed with no ordering */
#header .btn { color: red; }          /* ID selector → (0,1,1,0), unoverridable by classes */
.btn { color: blue; }                 /* (0,0,1,0) → loses to the ID above forever */
.btn { color: blue !important; }      /* arms race: now every override needs !important */

@import url("theme.css");             /* ❌ placed AFTER rules → engine IGNORES it. Also serial+render-blocking */

/* ✓ PRODUCTION — explicit layer order, flat specificity, no @import */
@layer reset, base, components, utilities;

@layer reset {
  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
}
@layer base {
  /* ID never used for styling → specificity stays (0,0,1,0) max across the codebase */
  .btn { color: var(--btn-fg, blue); }     /* token with fallback: survives missing theme */
}
@layer components {
  .btn--cta { color: var(--cta-fg, white); }  /* later layer beats base regardless of specificity */
}
@layer utilities {
  .u-text-cta { color: var(--cta-fg); }   /* utilities layer always wins → one-off overrides are safe */
}

<!-- 1. External <link> — cached, parallel (HTTP/2), the only production choice for non-critical CSS -->
<link rel="stylesheet" href="/assets/app.[hash].css">

<!-- 2. Critical CSS inlined in <head> — bytes that block first paint go here; everything else async -->
<style>
  /* above-the-fold rules only; inlined to remove a render-blocking round trip */
  :root{--bg:#fff;--fg:#333}
  body{background:var(--bg);color:var(--fg)}
</style>
<!-- non-critical CSS: preload without blocking, swap to stylesheet onload -->
<link rel="preload" href="/assets/app.[hash].css" as="style" onload="this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="/assets/app.[hash].css"></noscript>

<!-- 3. Inline style="" — specificity (1,0,0,0). Only for JS-driven dynamic values. -->
<div style="--x: 42px; transform: translateX(var(--x))"></div>

<!-- ❌ (1,0,0,0) specificity → no stylesheet rule without !important can override it; not cached; mixes concerns -->
<p style="color:red;font-weight:bold">Warning</p>

// ✓ Inline style is a *bridge for runtime values*. Set a custom property, let CSS do the rest.
el.style.setProperty('--x', `${pointerX}px');   // CSS: transform: translateX(var(--x))
// The custom property cascades; the transform logic lives in the stylesheet, overridable by classes.

# Coverage tab: Cmd+Shift+P → "Coverage" → load page.
#   % unused per file → purge targets. Shipping 80% unused framework CSS shows here.
# Rendering tab: Cmd+Shift+P → "Rendering" →
#   Paint flashing (repaint regions), Layout Shift Regions (CLS), FPS meter.
# Layers panel: shows compositor layers → each will-change/transform creates one (RAM cost).

/* ============================================================
   app.css — single entry. Layer order is the architecture.
   Order = precedence: later layers win at EQUAL specificity,
   and utilities always beat components regardless of specificity.
   ============================================================ */
@layer reset, tokens, base, components, utilities;

@layer tokens {
  :root {
    /* Design tokens: the only place raw values live. Everything else var()s. */
    --font-sans: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; /* native UI font, 0KB */
    --space-1: .25rem;  --space-2: .5rem;  --space-3: 1rem;  --space-4: 2rem; /* modular scale */
    --color-bg: #fff;   --color-fg: #333;   --color-primary: #3498db;
    --radius: 8px;
    /* OKLCH: perceptually uniform → 50% lightness looks equal across hues (HSL does NOT) */
    --color-primary-oklch: oklch(0.62 0.18 245);
  }
  /* Dark theme redefines the SAME tokens → every consumer updates in one paint, no cascade walk */
  @media (prefers-color-scheme: dark) {
    :root { --color-bg: #1a1a1a; --color-fg: #eee; --color-primary: #5dade2; }
  }
  [data-theme="dark"] { --color-bg: #1a1a1a; --color-fg: #eee; } /* manual toggle override */
}

@layer base {
  body {
    font-family: var(--font-sans);
    /* clamp(min, preferred, max): fluid, no media query, bounded for a11y */
    font-size: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
    line-height: 1.5;            /* unitless → recomputes per-element (px/em inherit as-is → overlap bug) */
    background: var(--color-bg);
    color: var(--color-fg);
  }
  /* :focus-visible = keyboard only, not mouse click. outline doesn't affect layout. */
  :focus-visible { outline: 2px solid var(--color-primary); outline-offset: 2px; }
}

@layer utilities {
  .u-stack > * + * { margin-block-start: var(--space-3); }  /* lobotomized owl: adjacent siblings only */
}

p {
    color: blue
    font-size: 18px;
}