🎨 CSS — Code-First Engineering Reference
A 22-chapter deep-dive reference for mid-to-senior engineers. Each chapter is structured around annotated production code: complex implementations, anti-pattern→correct pairs, performance tips, and edge cases. Minimal prose, maximum code. DevTools is the REPL.
How to Use This Reference
- Read sequentially (01 → 22) for a structured engine-deep path.
- Jump to a chapter when you hit a concept in production — every chapter is self-contained.
- Skim the anti-pattern → correct pairs — they're the highest-signal sections.
- Read the 🧠 Spot the Bug at the end of each chapter before checking the answer.
Prerequisites
- A modern browser (Chrome, Firefox, Safari, Edge). DevTools (
Cmd+Opt+I). - A code editor (VS Code recommended).
- Working HTML knowledge.
- Comfort reading CSS — this is a reference, not a beginner tutorial.
Curriculum
Part I — Engine Foundations
| # | Topic | Why It Matters |
|---|---|---|
| 01 | CSS Engine Internals & Production Setup | Parse → box tree → cascade → layout → paint → composite. @layer architecture from line one. |
| 02 | Selectors, Specificity & the Cascade Algorithm | Right-to-left matching, the 4-tuple specificity, cascade layers as the precedence primitive. |
| 03 | The Box Model: Formatting Contexts & Margin Collapse | box-sizing, BFC, margin-collapse rules, the min-width: auto flex/grid killer. |
| 04 | Color Spaces, Units & the Fluid Math of CSS | OKLCH perceptual uniformity, em/rem compounding, calc/min/max/clamp, color-mix. |
| 05 | Typography Engine: Font Loading & Text Overflow | font-display strategies, variable font axes, unitless line-height, single/multi-line truncation. |
Part II — Layout Algorithms
| # | Topic | Why It Matters |
|---|---|---|
| 06 | Display, Position & the Containing Block | Formatting contexts, the five position schemes, the transform-ancestor trap that breaks fixed. |
| 07 | Flexbox: One-Dimensional Layout & the flex Algorithm | grow/shrink/basis resolution, min-width: auto, gap, the app-layout pattern. |
| 08 | CSS Grid: Two-Dimensional Layout & Track Resolution | fr distribution, minmax(0, 1fr) overflow fix, auto-fit vs auto-fill, grid-template-areas, subgrid. |
| 09 | Responsive Design: Media Queries, Container Queries & Fluid CSS | Mobile-first, fluid clamp/auto-fit, container queries, prefers-* media features. |
| 10 | Floats, z-index & the Stacking Context Model | Stacking-context creation rules, the ancestor-z-index trap, isolation: isolate, clip-path. |
Part III — Visual Compositing
| # | Topic | Why It Matters |
|---|---|---|
| 11 | Backgrounds & Gradients: Layering & the Shorthand Reset Trap | Multiple layers, background-size / syntax, background-clip: text, conic-gradient pie charts. |
| 12 | Borders, Shadows, Outlines & Focus States | Layered elevation, outline vs border (layout shift), :focus-visible, the overflow-clips-shadow trap. |
| 13 | Animations & Transitions: The Compositor Pipeline | GPU vs layout-triggering properties, cubic-bezier overshoot, the height: auto trap, grid-template-rows. |
| 14 | Filters, Blend Modes & Masking: Compositing Pipeline | drop-shadow vs box-shadow, backdrop-filter translucency, mix-blend-mode contexts, mask soft fades. |
Part IV — Modern CSS Primitives
| # | Topic | Why It Matters |
|---|---|---|
| 15 | CSS Variables: Custom Properties as the Theming Engine | Cascade/inheritance, invalid-value semantics, runtime theming, JS setProperty bridge. |
| 16 | Logical Properties & Writing Modes: i18n-Ready CSS | inline/block axes, logical equivalents, vertical-rl, the logical/physical mixing trap. |
| 17 | Modern CSS (2023+): Nesting, | Native nesting, :has(), @layer, container style queries, color-mix, scroll-driven animations. |
| 18 | Architecture: BEM, OOCSS, ITCSS, Atomic & Cascade Layers | Flat-specificity naming, structure/skin separation, @layer as the native architecture primitive. |
Part V — Production Engineering
| # | Topic | Why It Matters |
|---|---|---|
| 19 | CSS Performance: Render Path, Containment & GPU Layers | Critical CSS, layout thrashing, content-visibility: auto, contain, will-change memory cost. |
| 20 | Browser Compatibility: Prefixes, @supports & Progressive Enhancement | Autoprefixer/browserslist, @supports feature detection, the Safari -webkit- laggard trap. |
| 21 | Preprocessors & Build Tools: Sass, PostCSS, Vite & CSS Modules | @use vs deprecated @import, compile-time vs runtime variables, PostCSS chains, CSS Modules. |
| 22 | Exercises & Projects: Production CSS Systems | 7 projects: layered reset, navbar, grid dashboard, glassmorphism, tooltips, loaders, capstone. |
Learning Path Suggestions
Mid-level developer moving to senior
Read 01 (engine + @layer), 02 (cascade algorithm), 07–08 (flex/grid algorithms — the min-width and minmax(0,1fr) traps), 13 (compositor pipeline — what animates at 60fps), 17 (:has(), @layer, container queries), 19 (render path + content-visibility), 18 (architecture).
Coming from a framework (React/Vue/Tailwind)
Read 02 (specificity — you've been insulated), 06 (containing block — the fixed + transform trap), 08 (grid track resolution), 13 (which properties animate on GPU), 15 (CSS variables as the JS↔CSS bridge), 18 (BEM + @layer vs utility-first).
Senior frontend engineer
Skim 01–05. Read closely: 10 (stacking contexts — the cage model), 13 (compositor pipeline), 14 (compositing gotchas), 16 (logical properties for i18n), 17 (2023+ features), 19 (content-visibility, contain, GPU layers), 21 (Sass vs CSS variables, build pipeline).
Performance-focused
Read 13 (compositor-only properties), 19 (render path, content-visibility: auto, contain, will-change), 11 (shorthand reset trap), 05 (font loading, font-display), 09 (fluid CSS vs media queries).
Companion Resources
- MDN CSS Docs — the definitive reference.
- Can I Use — browser compatibility tables. Check Safari specifically.
- web.dev CSS — Google's CSS learning material.
- CSS Tricks — practical guides and almanac.
- Josh W. Comeau's CSS Tutorials — intuitive explanations.
- CSS Gradient Generator — visual gradient tool.
Tooling
# VS Code extensions: Live Server (hot reload), CSS Peek (jump to definition), Tailwind IntelliSense (if Tailwind)
# Browser DevTools: Cmd+Opt+I → Elements/Inspector. Coverage tab (unused CSS), Rendering tab (paint flashing, CLS), Layers panel (GPU layers).
License
These notes are yours to use, share, and modify.