I've built everything I've built with flexbox. Navs, cards, forms, whole page shells. It stretched to cover all of it, and because it kept working I kept not learning grid. It sat in the same folder in my head as service workers: real, useful, worth understanding one day.

Then I picked up a challenge that took the option away. Build a photo gallery, no flexbox for layout. Grid only. I got a fair way in by copying shapes from the brief, and then I hit the wall you hit when you're copying things you don't understand. The layout mostly worked. I couldn't have told you why. And the moment something looked off, I had no idea which property was lying to me.

So I stopped building and wrote this instead. It's not a tutorial, it's the notes I needed before I could go back and finish that gallery knowing what I was doing. If you're coming from flexbox, I'd guess the same things will trip you.

The assumption underneath all of it, the one I didn't know I was making: grid is flexbox with a second axis. It isn't. The two disagree about something basic, which is who gets to decide how big things are. Almost everything that confused me comes back to that. Every diagram below is a real grid, so move the controls and watch the CSS change.

Content-Out vs Layout-In

Here's the model I replaced it with, and I'm putting it first because the rest of this article is just it showing up in different places: flexbox is content-out, grid is layout-in.

In flexbox you describe how items should behave and let the content settle the result. You say "grow, shrink, don't go below your basis," and the text inside each item decides the actual widths. In grid you define the structure first, a set of tracks that exist whether or not anything is in them, and then you put items into it.

This is also why the usual advice never landed for me. Everyone says flexbox is one-dimensional and grid is two-dimensional, and that falls apart fast. Plenty of single-row layouts want grid. Plenty of wrapping flex rows look two-dimensional. The question that actually seems to decide it is who should control the size here, the content or the container?

They nest fine, and most real pages use both. Grid for the page skeleton and the gallery, flexbox inside each card. That's not a compromise, it's how they're meant to split the work. Hang on to content-out versus layout-in, because the next eight sections are all the same idea from different angles.

There Are Always Two Grids

The first thing that follows from layout-in thinking took me a few confused minutes to accept: there are always two grids, and the second one gets made for you.

The explicit grid is the one I write down, the tracks in grid-template-columns and grid-template-rows. The implicit grid is what the browser adds when there are more items than declared tracks. It makes rows on demand, and those rows are sized by grid-auto-rows, not by my template.

.grid {
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;  /* explicit: 3 columns */
  grid-auto-rows: 80px;                /* implicit: every invented row */
}

Give that nine items and you get three neat rows. Give it ten and the browser quietly makes a fourth row you never asked for. That's not a bug, that's the implicit grid doing its job. The reason it's worth knowing early: a row sized by grid-auto-rows ignores anything you write in grid-template-rows. So if a row is the wrong height and editing the template does nothing, you're looking at the other grid. Add items in the demo and watch the dashed rows show up.

1fr Is Not flex: 1

A track is a column or a row. You can size tracks with any normal unit, but grid adds one of its own: fr, a share of the leftover space. That word matters more than it looks. The browser lays out the fixed tracks first, takes off the gaps, and only then splits what's left. So 200px 1fr 1fr means "200 pixels, then split the rest in half." The two 1fr tracks match each other, but neither has any fixed relationship to the 200px.

Coming from flexbox this looks exactly like flex: 1, and that's the trap I walked into. Here's the difference: 1fr has a minimum size of auto, so the track won't shrink below whatever its content needs. One long unbroken string or a wide image puts a floor under the track, the track pushes the grid wider than its container, and the page starts scrolling sideways. The content wins, and you didn't know there was an argument.

grid-template-columns: 200px 1fr 1fr;      /* fixed, then split the rest */
grid-template-columns: minmax(0, 1fr) 1fr; /* the overflow fix */

minmax() and repeat()

minmax(min, max) gives a track a floor and a ceiling. minmax(200px, 1fr) reads as: never narrower than 200px, otherwise take a share of what's left. That one function is most of what makes grid responsive without media queries, as the next section shows.

repeat(3, 1fr) is shorthand for 1fr 1fr 1fr. It takes a count, or the more interesting option, the keywords auto-fill and auto-fit, which hand the count to the browser. Then there are the content-based ones: min-content is about as narrow as the longest word, max-content is how wide it would be with no wrapping at all, and auto acts like max-content but capped by the space available. Flipping between them in the demo is what made floors and ceilings click for me. Reading the definitions hadn't.

The Bug You Can Ship for Years

These two are where I expected a clear difference and found a sneaky one instead. In the docs auto-fill and auto-fit sound nearly the same, and in most examples you'll copy they behave the same. That's not a coincidence, it's how the difference stays hidden.

Both tell the browser to fit as many tracks as it can. They differ on exactly one thing: what happens to the tracks that end up empty.

• auto-fill keeps the empty tracks. They sit there at full width, holding space.
• auto-fit collapses empty tracks to zero width, and the items that are left stretch to fill the gap.

The difference only shows up when you run out of items, which is what the demo lets you force. Drop the item count below the track count and the two split apart straight away.

So which one do you want? Use auto-fit for a gallery or card list that should always look full-width. Use auto-fill when keeping a steady column rhythm matters more than filling the row, like a dashboard where one lonely card should stay card-sized instead of stretching across the whole screen.

Lines, -1, and the Trap Under It

Grid numbers the lines between tracks, not the tracks. Three columns means four vertical lines, numbered 1 to 4 from the left. This catches everyone once and it definitely caught me: grid-column: 1 / 3 doesn't mean "columns 1 through 3." It means "line 1 to line 3," which is two columns wide.

grid-column: 1 / 3;      /* line 1 to line 3 = 2 tracks wide */
grid-column: 1 / span 2; /* same thing, stated as a width  */
grid-column: span 2;     /* 2 tracks wide, auto-placed      */
grid-column: 1 / -1;     /* line 1 to the LAST line: full width */

Negative numbers count from the end, which makes -1 really handy: 1 / -1 spans the full width no matter how many columns there are. It looks like the answer to every full-bleed problem. Then there's a case where it quietly isn't, and that one took me a while to spot.

Named Lines: The Repair

Square brackets in a track list name a line, not a track. They don't add any size, they're just labels.

.gallery {
  grid-template-columns:
    [full-start] repeat(auto-fill, minmax(280px, 1fr)) [full-end];
}

.featured {
  grid-column: full-start / full-end;
}

Notice where the names sit: outside the repeat(). However many columns auto-fill ends up making, full-start is still the far-left line and full-end is still the far-right one. You can't do that with numbers, because you don't know the count.

This is the line I'd already copied into my own gallery without understanding it, and it's what sent me off to write this. Wanting a full-width item inside an auto-fill grid is a completely normal thing to want, and grid-column: 1 / -1, the obvious answer, is exactly the thing that doesn't work there. Named lines aren't a style choice in that situation. They're the only way to say it.

Drawing the Layout

If layout-in ever needed one piece of evidence, it's grid-template-areas. You draw the layout as ASCII art. Each string is a row, each word is a named cell, and the children never find out where they are.

.page {
  display: grid;
  grid-template-areas:
    "header header"
    "sidebar main"
    "footer footer";
  grid-template-columns: 220px 1fr;
  grid-template-rows: auto 1fr auto;
}

.page > header { grid-area: header; }

Two rules that are easy to trip over. Every row string needs the same number of columns, and an area has to be a solid rectangle. An L-shape is invalid, and when it's invalid the whole declaration gets dropped silently. That's the part worth remembering, because a typo here doesn't warn you, it just leaves you with a layout that stopped existing. Use . for a cell you want empty on purpose.

The real payoff is responsive work. Redraw the map in a media query and the whole layout rearranges without touching a single child rule:

@media (max-width: 700px) {
  .page {
    grid-template-areas: "header" "main" "sidebar" "footer";
    grid-template-columns: 1fr;
  }
}

dense Packing and Its Hidden Cost

Auto-placement walks items in DOM order, filling row by row. When a spanning item doesn't fit in what's left at the end of a row, the browser skips ahead and leaves a hole. grid-auto-flow: dense changes that: if a later, smaller item would fit in an earlier hole, it gets pulled back to fill it. The gaps disappear and the grid looks tidy.

This is the one I'd have switched on without thinking, because it reads like a free win. The cost is real and easy to miss: visual order stops matching DOM order. Keyboard focus follows the DOM, so someone tabbing through watches focus jump around the screen, and a screen reader reads out an order that doesn't match what's on screen. Nothing in the CSS warns you. It looks perfect right up until someone tabs through it.

Turn on the DOM order numbers in the demo and toggle dense. Watching the numbers scramble is the whole argument.

Six Properties, Two Questions

Alignment gets presented as six properties to memorise, and that framing nearly made me skip the section. It's really two questions crossed with three scopes, and once you see it that way there's nothing to memorise.

Which axis? justify-* is the inline axis, horizontal in English. align-* is the block axis, vertical. This is backwards from the flexbox habit, where the axes swap depending on flex-direction. In grid they stay put, which is one less thing to keep track of.

What moves? *-items moves the content inside every cell. *-self overrides that for one item. *-content moves the whole set of tracks inside the container, and it only does anything when your tracks are smaller than the container. That's why it looks broken on a grid of 1fr tracks that already fill the space. It caught me in the demo below before I worked out what it was for.

place-items, place-self and place-content are shorthands that take align then justify. So place-items: center is the entire centering problem in one line.

gap

gap is row-gap and column-gap together. It only applies between tracks, never on the outer edges, which is exactly why it beats margins here. No first-child or last-child exception to write. Percentage gaps resolve against the container's own size.

What I Do Not Know Yet

I wrote this while learning it, not after mastering it, so take the confident bits with a pinch of salt. I haven't lived with a grid layout long enough to know what it costs later, when the design changes, when the content turns out to be messy, when someone else has to edit it. That part's still ahead of me.

I also haven't shipped subgrid yet. It lets a nested grid borrow its parent's track lines instead of making its own. The usual example is a row of cards where every title, body and footer should line up across cards even though the text lengths don't match. Before subgrid that needed fixed heights or JavaScript. It's been available in the major browsers since late 2023, but check your own support floor rather than taking my word for it.

What did change is the question I ask before writing any layout. Not "is this one-dimensional or two-dimensional," but who should decide how big this is, the content or the container? Flexbox was never the wrong tool. It was just the only tool I had, so every problem turned into a content-out problem. Having the other half is the actual difference.

And I've got a gallery to finish. It's still sitting there half-built, except now I can read my own stylesheet and say what each line is doing, which was the whole point of stopping to write this. The build itself is its own write-up, once it's actually done.

Further Reading

I'm learning this, not authoritative on it, so here's where I checked myself and where you should check me. Browser-support claims especially, they go stale faster than anything else in CSS.

• MDN — CSS grid layout — the one I keep open while writing this, especially the guides on line-based placement and auto-placement.
• CSS Grid Layout Module Level 2 (W3C) — the spec, and the authority on track sizing and why 1fr has an auto minimum.
• MDN — minmax() — the details behind the minmax(0, 1fr) fix.
• MDN — subgrid — current Baseline status, which is the number to trust over any blog post including this one.
• Can I use — CSS Grid — for checking support against your own analytics rather than a general claim.

In the first challenge I used CSS Grid for the skills section. This time I forced myself to do everything with Flexbox — including a responsive 1/2/3-column card grid. It turns out Flexbox can handle multi-column layouts just fine when you understand flex-basis, flex-wrap, and calc(). I also tackled hover-reveal buttons, dietary badges, sticky navigation, :target highlighting, staggered card entrance animations, and a responsive footer — all with Flexbox as the sole layout mechanism.

What I Built

A single-page restaurant menu for La Bella Cucina, an upscale Italian restaurant. 15 menu items across 4 categories (Antipasti, Primi Piatti, Secondi Piatti, Dolci), each with a food photo inside <figure>/<figcaption>, Italian name, English description, and price. Cards lift on hover, images zoom, prices change color, and an "Add to Order" button fades in.

The page breaks down into these sections: a centered header with the restaurant name, decorative divider, and tagline. A sticky category nav with pill-shaped hover effects. Four menu sections each containing a flex-wrapped card grid. Each menu item card is both a flex item (of the grid) and a flex container (for its own content). And a dark footer that switches from column to row layout at the tablet breakpoint.

Here are the 12 Flexbox properties I used — and nothing else for layout:

Step 1 — Project Setup + Design Tokens

Two files: index.html and style.css. I loaded Google Fonts (Playfair Display for headings, Lato for body text) and defined every design token upfront. The reset includes scroll-behavior: smooth on html for the nav anchor links.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport"
          content="width=device-width, initial-scale=1.0" />
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com"
          crossorigin />
    <link href="https://fonts.googleapis.com/css2?family=Lato:wght@300;400;700&family=Playfair+Display:wght@400;600;700&display=swap"
          rel="stylesheet" />
    <link rel="stylesheet" href="style.css" />
    <title>La Bella Cucina</title>
  </head>
  <body>
    <!-- content in next steps -->
  </body>
</html>

:root {
  --color-primary: #8B0000;
  --color-cream: #FFF8E7;
  --color-charcoal: #2C2C2C;
  --color-gold: #D4A574;
  --color-olive: #556B2F;
  --color-white: #FFFDF7;
  --color-gold-light: #F5E6D3;
  --color-primary-dark: #5C0000;

  --font-heading: 'Playfair Display', Georgia, serif;
  --font-body: 'Lato', 'Helvetica Neue', Arial, sans-serif;

  --spacing-section: 4rem;
  --spacing-card: 1.25rem;
  --spacing-gap: 1.5rem;
  --spacing-gutter: 2rem;
  --spacing-header: 3rem;

  --shadow-card: 0 2px 8px rgba(44, 44, 44, 0.08);
  --shadow-hover: 0 8px 24px rgba(44, 44, 44, 0.15);

  --radius-card: 8px;
  --radius-btn: 4px;
  --radius-nav: 24px;
}

*,
*::before,
*::after {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

html {
  scroll-behavior: smooth;
}

body {
  background-color: var(--color-cream);
  font-family: var(--font-body);
  color: var(--color-charcoal);
  line-height: 1.6;
  -webkit-font-smoothing: antialiased;
}

img {
  display: block;
  max-width: 100%;
  height: auto;
}

a {
  color: inherit;
  text-decoration: none;
}

Step 2 — Restaurant Header

Three elements stacked vertically: the restaurant name, a decorative divider, and a tagline. flex-direction: column with align-items: center does the work. I used clamp() for fluid typography — the heading scales from 2rem to 3.5rem based on viewport width.

<header class="restaurant-header">
  <h1>La Bella Cucina</h1>
  <span class="header-divider">&mdash; Est. 1987 &mdash;</span>
  <p>Authentic Italian Cuisine Since 1987</p>
</header>

.restaurant-header {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  padding: var(--spacing-header) var(--spacing-gutter);
  background-color: var(--color-cream);
  text-align: center;
  border-bottom: 1px solid var(--color-gold-light);
}

.restaurant-header h1 {
  font-family: var(--font-heading);
  font-size: clamp(2rem, 5vw, 3.5rem);
  font-weight: 700;
  line-height: 1.1;
  letter-spacing: 0.02em;
  color: var(--color-charcoal);
}

.header-divider {
  display: block;
  font-family: var(--font-body);
  font-size: 0.875rem;
  font-weight: 400;
  letter-spacing: 0.2em;
  color: var(--color-gold);
  margin: 0.75rem 0;
  text-transform: uppercase;
}

.restaurant-header p {
  font-family: var(--font-body);
  font-size: clamp(0.875rem, 1.5vw, 1.125rem);
  font-weight: 300;
  line-height: 1.5;
  letter-spacing: 0.15em;
  color: var(--color-charcoal);
  opacity: 0.7;
  text-transform: uppercase;
}

Step 3 — Sticky Category Navigation

Four anchor links in a horizontal flex row. position: sticky; top: 0 makes the nav stick when you scroll past it. On small screens, overflow-x: auto lets it scroll horizontally instead of wrapping.

<nav class="category-nav">
  <ul>
    <li><a href="#antipasti">Antipasti</a></li>
    <li><a href="#primi">Primi Piatti</a></li>
    <li><a href="#secondi">Secondi Piatti</a></li>
    <li><a href="#dolci">Dolci</a></li>
  </ul>
</nav>

.category-nav {
  position: sticky;
  top: 0;
  z-index: 100;
  padding: 1rem var(--spacing-gutter);
  background-color: var(--color-gold-light);
  overflow-x: auto;
  -webkit-overflow-scrolling: touch;
  border-bottom: 2px solid var(--color-gold);
}

.category-nav ul {
  display: flex;
  gap: 0;
  list-style: none;
  margin: 0 auto;
  width: fit-content;
}

.category-nav ul li a {
  display: block;
  font-family: var(--font-body);
  font-size: 0.9375rem;
  font-weight: 600;
  line-height: 1;
  letter-spacing: 0.08em;
  text-transform: uppercase;
  color: var(--color-charcoal);
  padding: 0.5rem 1.25rem;
  border-radius: var(--radius-nav);
  transition: background-color 0.2s ease, color 0.2s ease;
  text-wrap: nowrap;
}

.category-nav ul li a:hover {
  background-color: var(--color-primary);
  color: var(--color-cream);
}

Step 4 — Main Container + Section Headings

Four menu sections, each with an id matching the nav anchors. The section headings use a ::after pseudo-element for the gold underline — purely decorative, so it belongs in CSS, not HTML.

<main class="menu-sections">
  <section id="antipasti" class="menu-category">
    <h2>Antipasti</h2>
    <ul class="menu-items">
      <!-- cards go here in Step 5 -->
    </ul>
  </section>

  <section id="primi" class="menu-category">
    <h2>Primi Piatti</h2>
    <ul class="menu-items"></ul>
  </section>

  <section id="secondi" class="menu-category">
    <h2>Secondi Piatti</h2>
    <ul class="menu-items"></ul>
  </section>

  <section id="dolci" class="menu-category">
    <h2>Dolci</h2>
    <ul class="menu-items"></ul>
  </section>
</main>

.menu-sections {
  max-width: 1200px;
  margin: 0 auto;
  padding: 0 var(--spacing-gutter);
}

.menu-category {
  padding: var(--spacing-section) 0 0;
  scroll-margin-top: 4rem;
}

.menu-category h2 {
  font-family: var(--font-heading);
  font-size: clamp(1.5rem, 3vw, 2.25rem);
  font-weight: 600;
  line-height: 1.2;
  letter-spacing: 0.01em;
  color: var(--color-primary);
  text-align: center;
  margin-bottom: 2rem;
  position: relative;
}

.menu-category h2::after {
  content: '';
  display: block;
  width: 60px;
  height: 2px;
  background: var(--color-gold);
  margin: 0.75rem auto 0;
}

Step 5 — Menu Item Cards (The Core)

This is the heart of the project. Each card is both a flex item (of the grid) and a flex container (for its own content). The grid container uses flex-wrap: wrap so cards flow to the next row. Each card starts at flex-basis: 100% (mobile-first, 1 column).

Here's the HTML pattern for one card — repeat it for each item using the content tables below:

<li class="menu-item">
  <figure>
    <img src="https://picsum.photos/seed/bruschetta/400/300"
         alt="Bruschetta al Pomodoro" />
    <figcaption>House Favorite</figcaption>
  </figure>
  <div class="item-header">
    <h3>Bruschetta al Pomodoro</h3>
    <span class="item-price">$12.95</span>
  </div>
  <p class="item-description">
    Grilled bread topped with fresh tomatoes,
    garlic, basil, and extra virgin olive oil
  </p>
</li>

Fill all 4 sections: Antipasti (4 items), Primi Piatti (4), Secondi Piatti (4), Dolci (3). Here's the full menu data:

All image URLs follow the pattern: https://picsum.photos/seed/{seed}/400/300

Now the CSS — this is where Flexbox does its heaviest lifting:

/* The flex grid container */
.menu-items {
  display: flex;
  flex-wrap: wrap;
  gap: var(--spacing-gap);
  align-content: flex-start;
  list-style: none;
}

/* Each card — flex ITEM of grid + flex CONTAINER for content */
.menu-item {
  display: flex;
  flex-direction: column;
  flex-basis: 100%;          /* Mobile: 1 column */
  flex-grow: 0;              /* Don't stretch wider */
  flex-shrink: 1;
  background: var(--color-white);
  border-radius: var(--radius-card);
  box-shadow: var(--shadow-card);
  overflow: hidden;
  transition: box-shadow 0.3s ease, transform 0.3s ease;
}

/* Figure + image */
.menu-item figure {
  position: relative;
  overflow: hidden;
}

.menu-item figure img {
  width: 100%;
  height: 220px;
  object-fit: cover;
  transition: transform 0.4s ease;
}

.menu-item figure figcaption {
  position: absolute;
  top: 12px;
  left: 12px;
  background-color: var(--color-olive);
  color: var(--color-cream);
  font-family: var(--font-body);
  font-size: 0.7rem;
  font-weight: 700;
  letter-spacing: 0.08em;
  text-transform: uppercase;
  padding: 0.3rem 0.7rem;
  border-radius: var(--radius-btn);
}

/* Name + price row */
.item-header {
  display: flex;
  justify-content: space-between;
  align-items: baseline;
  gap: 1rem;
  padding: 0.85rem var(--spacing-card) 0;
}

.item-header h3 {
  font-family: var(--font-heading);
  font-size: clamp(1rem, 1.5vw, 1.25rem);
  font-weight: 600;
  line-height: 1.3;
  color: var(--color-charcoal);
}

.item-price {
  font-family: var(--font-body);
  font-size: clamp(1rem, 1.2vw, 1.125rem);
  font-weight: 700;
  color: var(--color-primary);
  flex-shrink: 0;
  white-space: nowrap;
  transition: color 0.2s ease;
}

/* Description — flex-grow: 1 is KEY */
.item-description {
  flex-grow: 1;
  padding: 0.5rem var(--spacing-card) var(--spacing-card);
  font-family: var(--font-body);
  font-size: clamp(0.8rem, 1vw, 0.9375rem);
  font-weight: 400;
  line-height: 1.6;
  color: var(--color-charcoal);
  opacity: 0.8;
}

Step 6 — Card Hover Effects

Three things happen on hover: the card lifts up with a deeper shadow, the image zooms 8%, and the price changes from red to gold. All using transform (GPU-accelerated) instead of changing width/height (which triggers layout reflow).

.menu-item:hover {
  box-shadow: var(--shadow-hover);
  transform: translateY(-4px);
}

.menu-item:hover figure img {
  transform: scale(1.08);
}

.menu-item:hover .item-price {
  color: var(--color-gold);
}

Step 7 — Responsive Breakpoints (2-column, 3-column)

The base CSS is mobile-first (1 column). Media queries add complexity at larger sizes. The math for flex-basis accounts for the gap between cards.

/* Tablet: 2 columns */
@media (min-width: 640px) {
  .menu-item {
    flex-basis: calc(50% - var(--spacing-gap) / 2);
  }
}

/* Desktop: 3 columns */
@media (min-width: 1024px) {
  .menu-item {
    flex-basis: calc(33.333% - var(--spacing-gap) * 2 / 3);
  }

  .menu-item figure img {
    height: 200px;
  }
}

Step 8 — Footer

The footer is another flex container that switches direction at the tablet breakpoint — column on mobile, row on tablet+. The copyright uses flex-basis: 100% to force itself onto its own line in the wrapping row.

<footer class="site-footer">
  <div class="footer-address">
    <p>127 Via Roma, Greenwich Village, New York, NY 10012</p>
    <p>(212) 555-0187</p>
  </div>
  <div class="footer-hours">
    <p>Mon&ndash;Thu 5:00 PM &ndash; 10:00 PM</p>
    <p>Fri&ndash;Sat 5:00 PM &ndash; 11:00 PM</p>
    <p>Sun 4:00 PM &ndash; 9:00 PM</p>
  </div>
  <div class="footer-cta">
    <a href="#" class="reserve-btn">Reserve a Table</a>
  </div>
  <p class="footer-copyright">
    &copy; 2024 La Bella Cucina. All rights reserved.
  </p>
</footer>

.site-footer {
  display: flex;
  flex-direction: column;
  align-items: center;
  text-align: center;
  gap: 1.5rem;
  padding: var(--spacing-section) var(--spacing-gutter);
  margin-top: var(--spacing-section);
  background: var(--color-charcoal);
  color: var(--color-cream);
  font-family: var(--font-body);
  font-size: 0.9rem;
  line-height: 1.7;
}

.footer-address p,
.footer-hours p {
  opacity: 0.85;
}

.footer-hours {
  border-top: 1px solid rgba(255, 255, 255, 0.15);
  border-bottom: 1px solid rgba(255, 255, 255, 0.15);
  padding: 1rem 0;
}

.reserve-btn {
  display: inline-block;
  background-color: var(--color-primary);
  color: var(--color-cream);
  font-family: var(--font-body);
  font-size: 0.9375rem;
  font-weight: 700;
  letter-spacing: 0.08em;
  text-transform: uppercase;
  padding: 0.85rem 2rem;
  border-radius: var(--radius-btn);
  transition: background-color 0.2s ease, transform 0.1s ease;
}

.reserve-btn:hover {
  background-color: var(--color-primary-dark);
  transform: translateY(-1px);
}

.footer-copyright {
  font-size: 0.8rem;
  opacity: 0.5;
}

/* Tablet+: horizontal footer */
@media (min-width: 640px) {
  .site-footer {
    flex-direction: row;
    justify-content: space-between;
    align-items: center;
    text-align: left;
    flex-wrap: wrap;
  }

  .footer-hours {
    border-top: none;
    border-bottom: none;
    border-left: 1px solid rgba(255, 255, 255, 0.15);
    border-right: 1px solid rgba(255, 255, 255, 0.15);
    padding: 0 1.5rem;
  }

  .footer-copyright {
    flex-basis: 100%;
    text-align: center;
    margin-top: 0.5rem;
  }
}

Step 9 — Dietary Badges (V, GF)

Some dishes need dietary badges — V for Vegetarian, GF for Gluten Free. These go in the item-header between the name and price. The key is adding flex-wrap: wrap and adjusting the gap on item-header so badges can sit next to the dish name and the price pushes to the end.

Update the item-header HTML for dishes that have badges:

<div class="item-header">
  <h3>Bruschetta al Pomodoro</h3>
  <span class="badge badge-v">V</span>
  <span class="item-price">$12.95</span>
</div>

<!-- For items with multiple badges: -->
<div class="item-header">
  <h3>Burrata con Prosciutto</h3>
  <span class="badge badge-v">V</span>
  <span class="badge badge-gf">GF</span>
  <span class="item-price">$18.00</span>
</div>

/* Update item-header for badges */
.item-header {
  flex-wrap: wrap;
  gap: 0.25rem 1rem;
}

.badge {
  font-family: var(--font-body);
  font-size: 0.625rem;
  font-weight: 700;
  letter-spacing: 0.05em;
  text-transform: uppercase;
  padding: 0.15rem 0.4rem;
  border-radius: var(--radius-btn);
}

.badge-v {
  background-color: var(--color-olive);
  color: var(--color-cream);
}

.badge-gf {
  background-color: var(--color-gold);
  color: var(--color-charcoal);
}

Step 10 — Hover-Reveal Order Button

An "Add to Order" button at the bottom of each card that's invisible by default and fades in + slides up on hover. This uses opacity: 0 plus transform: translateY(4px) on the button, then the card's :hover state reveals it.

<!-- Add at the end of each <li class="menu-item">, 
     after the .item-description paragraph -->
<button class="order-btn">Add to Order</button>

.order-btn {
  margin: 0 var(--spacing-card) var(--spacing-card);
  padding: 0.5rem 1rem;
  font-family: var(--font-body);
  font-size: 0.8125rem;
  font-weight: 700;
  letter-spacing: 0.06em;
  text-transform: uppercase;
  background-color: var(--color-primary);
  color: var(--color-cream);
  border: none;
  border-radius: var(--radius-btn);
  cursor: pointer;
  opacity: 0;
  transform: translateY(4px);
  transition: opacity 0.25s ease,
             transform 0.25s ease,
             background-color 0.2s ease;
}

.menu-item:hover .order-btn {
  opacity: 1;
  transform: translateY(0);
}

.order-btn:hover {
  background-color: var(--color-primary-dark);
}

Step 11 — :target Highlighting + Smooth Scroll

When you click a nav link like "Antipasti," the URL becomes #antipasti and the :target pseudo-class matches that section. I used this to change the heading color to gold and expand the underline — a visual confirmation that navigation happened.

/* :target fires when the section's id matches the URL hash */
.menu-category:target h2 {
  color: var(--color-gold);
  transition: color 0.3s ease;
}

.menu-category:target h2::after {
  width: 120px;
  background: var(--color-primary);
  transition: width 0.3s ease, background 0.3s ease;
}

Step 12 — Card Entrance Animations

Cards fade in and slide up on page load with staggered delays. The first card appears immediately, the second after 0.1s, the third after 0.2s, and so on. This creates a cascading entrance effect.

@keyframes cardFadeIn {
  0% {
    opacity: 0;
    transform: translateY(20px);
  }
  100% {
    opacity: 1;
    transform: translateY(0);
  }
}

.menu-item {
  animation: cardFadeIn 0.6s ease both;
}

.menu-item:nth-child(1) { animation-delay: 0s; }
.menu-item:nth-child(2) { animation-delay: 0.1s; }
.menu-item:nth-child(3) { animation-delay: 0.2s; }
.menu-item:nth-child(4) { animation-delay: 0.3s; }

Acceptance Criteria

Here's the checklist I used to verify the build:

• Zero display: grid in the stylesheet
• Uses display: flex as the sole layout mechanism
• Uses flex-direction (both row and column)
• Uses justify-content with at least 2 values (center, space-between)
• Uses align-items with at least 2 values (center, baseline)
• Uses align-content: flex-start on the card grid
• Uses flex-wrap: wrap for responsive card layout
• Uses flex-grow: 1 on the description for equal-height cards
• Uses flex-shrink: 0 on the price
• Uses flex-basis with calc() for responsive columns
• Uses gap for spacing between cards
• Responsive: 1 col (< 640px), 2 col (640–1023px), 3 col (>= 1024px)
• All images use <figure> and <figcaption>
• 4 menu sections with 15 total items
• Hover effects: shadow lift, image zoom, price color change
• Sticky category nav with pill-shaped hover
• Dietary badges (V and GF) with flex-wrap on item-header
• Hover-reveal "Add to Order" button with opacity + transform transition
• :target highlighting on section headings
• Card entrance animations with staggered delays
• Footer switches from column to row at 640px
• All CSS values reference design token variables from :root
• Google Fonts loaded: Playfair Display + Lato

Flexbox Properties Used

Quick Reference: flex-grow, flex-shrink, flex-basis

justify-content vs align-items

justify-content controls spacing along the main axis (the direction items flow). align-items controls positioning along the cross axis (perpendicular). When flex-direction: row, main = horizontal and cross = vertical. When flex-direction: column, they swap. That's why align-items: center centers horizontally in the header (column direction) but vertically in the footer (row direction).

The flex-basis + calc() Pattern for Columns

I used to wrap everything in <div> tags. It works, but it tells the browser — and screen readers — nothing about the content. So I gave myself this constraint to learn the right element for each role. By the end, I used 7 semantic elements, 5 CSS selector types, CSS Grid for skills, :has() for dark mode, <meter> for skill proficiency bars, and a print stylesheet — all with zero JavaScript. Here's the full walkthrough — and the challenge for you to try it yourself.

What I Built

A centered profile card on a dark page — white rectangle, max-width 480px, rounded corners, shadow, animated entrance. It features a dark mode toggle (no JS), skill proficiency meters, link icons via ::before pseudo-elements, and a print stylesheet. Here's the final result:

I broke the card into these sections from top to bottom: a dark mode toggle using <details>. A header with the photo, name, and title. An About Me section with a short bio. A Skills section with a 4-column grid of icons, names, and <meter> proficiency bars. A Fun Fact callout box. A Contact section with icon-prefixed links. And a footer with copyright text.

I used these 8 semantic elements — no <div> anywhere:

Step 1 — Project Setup + CSS Reset

I started with two files: index.html and styles.css. The foundation — boilerplate every project starts with.

Challenge: Try writing the HTML boilerplate yourself — with lang="en", the viewport meta tag, and a linked stylesheet. Then check my version below.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport"
          content="width=device-width, initial-scale=1.0" />
    <link rel="stylesheet" href="styles.css" />
    <title>Document</title>
  </head>
  <body>
    <!-- content goes here in next steps -->
  </body>
</html>

Design Tokens

I defined every color, size, and spacing value as CSS custom properties upfront. This is the full design token block I used:

*,
*::before,
*::after {
  box-sizing: border-box;
  margin: 0;
  padding: 0;
}

:root {
  --color-bg: #1a1a2e;
  --color-card-bg: #ffffff;
  --color-text-primary: #16213e;
  --color-text-body: #4a4a68;
  --color-text-muted: #8888a0;
  --color-accent: #e94560;
  --color-accent-hover: #c81e45;
  --color-skill-bg: #f0f0f5;
  --color-aside-bg: #f8f8fc;
  --color-border: #e0e0e8;

  --card-padding: 2.5rem;
  --section-gap: 1.5rem;
  --card-radius: 16px;
  --photo-size: 160px;
}

Step 2 — Page Background + Card Centering

Next I needed the dark navy page with a white card centered in the middle. Flexbox does the heavy lifting here. I wrapped the content in <main> and <article> — no <div> needed.

<body>
  <main>
    <article class="profile-card">
      <!-- card content in next steps -->
    </article>
  </main>
</body>

body {
  min-height: 100vh;
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: var(--color-bg);
  font-family: "Segoe UI", Tahoma, Geneva, Verdana, sans-serif;
  font-size: 1rem;
  line-height: 1.6;
  color: var(--color-text-body);
  padding: 2rem;
}

article {
  position: relative;
  background-color: var(--color-card-bg);
  max-width: 480px;
  width: 100%;
  border-radius: var(--card-radius);
  padding: var(--card-padding);
  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.12);
  transition: box-shadow 0.3s ease;
  animation-name: fadeSlideUp;
  animation-duration: 1s;
}

Step 3 — Dark Mode Toggle + Card Header

I added a dark mode toggle using <details> — a native HTML disclosure widget. When it's open, CSS :has() detects the state and swaps all the design tokens. No JavaScript needed. Then the header with the circular photo, bold name, and muted job title.

<details class="theme-toggle">
  <summary>Toggle Dark Mode</summary>
</details>
<header>
  <figure class="profile-photo">
    <img src="https://imgcdn.stablediffusionweb.com/2024/12/7/d88a43ab-ab0d-4462-bfed-3ee4f1e76e78.jpg"
         alt="Sarah Chen" />
  </figure>
  <h1>Sarah Chen</h1>
  <p>Software Engineer and Web Developer</p>
</header>

/* Dark mode toggle */
.theme-toggle {
  position: absolute;
  top: 1rem;
  right: 1rem;
}

.theme-toggle summary {
  list-style: none;
  cursor: pointer;
  width: 2rem;
  height: 2rem;
  border-radius: 50%;
  background: var(--color-skill-bg);
  border: 1px solid var(--color-border);
  transition: background 0.2s ease;
  text-indent: -9999px;
  overflow: hidden;
  position: relative;
}

.theme-toggle summary::before {
  content: "\1F319";
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  display: flex;
  align-items: center;
  justify-content: center;
  text-indent: 0;
  font-size: 1.125rem;
}

.theme-toggle[open] summary::before {
  content: "\2600\FE0F";
}

.theme-toggle summary:hover {
  background: var(--color-border);
}

.theme-toggle summary::-webkit-details-marker {
  display: none;
}

/* Profile photo */
.profile-photo img {
  width: 160px;
  height: 160px;
  border-radius: 50%;
  object-fit: cover;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
}

/* Name and title */
.profile-card header h1 {
  font-size: 1.75rem;
  font-weight: 700;
  color: var(--color-text-primary);
  margin-top: 1rem;
}

.profile-card header p {
  font-size: 1rem;
  color: var(--color-text-muted);
}

Step 4 — About Section

A thematic grouping with a heading — exactly what <section> is for. I styled the heading as a small uppercase label to act as a section marker.

<section>
  <h2>About Me</h2>
  <p>
    I'm a full-stack developer based in Toronto
    with 5 years of experience building web
    applications. I specialize in React and
    Node.js ecosystems, with a focus on
    performance and accessibility. Previously, I
    worked at Shopify building merchant-facing
    tools. Currently, I'm exploring AI-powered
    developer tooling and contributing to open
    source.
  </p>
</section>

section h2,
nav h2 {
  font-size: 0.75rem;
  font-weight: 600;
  text-transform: uppercase;
  letter-spacing: 0.1rem;
  color: var(--color-text-muted);
  margin-bottom: 0.75rem;
  margin-top: 1rem;
}

Step 5 — Section Dividers (The + Combinator)

No extra HTML needed here. I used the adjacent sibling combinator in CSS to add borders between sections without giving the first section an unwanted top border.

/* Adjacent sibling combinator (+):
   targets an element that immediately follows
   another at the same nesting level */

section + section,
section + aside,
aside + nav {
  border-top: 1px solid var(--color-border);
  padding-top: var(--section-gap);
  margin-top: var(--section-gap);
}

section + aside {
  padding-top: 1rem;
  border-top: none;
}

Step 6 — Skills Grid (CSS Grid + <meter>)

This was a fun one — instead of simple pill badges, I used a 4-column CSS Grid with skill icons (emoji), names, and <meter> elements for proficiency bars. Each skill card has a hover effect that lifts it slightly.

<section>
  <h2>Skills</h2>
  <ul class="skills-list">
    <li>
      <span class="skill-icon" aria-hidden="true">&#9883;</span>
      <span class="skill-name">React</span>
      <meter min="0" max="100" value="90">90%</meter>
    </li>
    <li>
      <span class="skill-icon" aria-hidden="true">&#9881;</span>
      <span class="skill-name">Node.js</span>
      <meter min="0" max="100" value="85">85%</meter>
    </li>
    <li>
      <span class="skill-icon" aria-hidden="true">&#10094;&#10095;</span>
      <span class="skill-name">JavaScript</span>
      <meter min="0" max="100" value="95">95%</meter>
    </li>
    <li>
      <span class="skill-icon" aria-hidden="true">&#9998;</span>
      <span class="skill-name">HTML/CSS</span>
      <meter min="0" max="100" value="90">90%</meter>
    </li>
    <li>
      <span class="skill-icon" aria-hidden="true">&#128013;</span>
      <span class="skill-name">Python</span>
      <meter min="0" max="100" value="60">60%</meter>
    </li>
    <li>
      <span class="skill-icon" aria-hidden="true">&#128451;</span>
      <span class="skill-name">SQL</span>
      <meter min="0" max="100" value="70">70%</meter>
    </li>
    <li>
      <span class="skill-icon" aria-hidden="true">&#127811;</span>
      <span class="skill-name">MongoDB</span>
      <meter min="0" max="100" value="65">65%</meter>
    </li>
    <li>
      <span class="skill-icon" aria-hidden="true">&#9729;</span>
      <span class="skill-name">AWS</span>
      <meter min="0" max="100" value="55">55%</meter>
    </li>
  </ul>
</section>

.skills-list {
  list-style: none;
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  gap: 0.75rem;
}

.skills-list li {
  display: flex;
  flex-direction: column;
  align-items: center;
  text-align: center;
  gap: 0.375rem;
  background: var(--color-skill-bg);
  border: 1px solid var(--color-border);
  border-radius: 12px;
  padding: 0.75rem 0.5rem;
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}

.skills-list li:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
}

.skill-icon {
  font-size: 1.5rem;
  line-height: 1;
}

.skill-name {
  font-size: 0.6875rem;
  font-weight: 600;
  color: var(--color-text-primary);
}

/* Meter element styling */
.skills-list meter {
  width: 100%;
  height: 8px;
  border: none;
  border-radius: 3px;
  overflow: hidden;
}

/* Webkit (Chrome, Safari, Edge) */
.skills-list meter::-webkit-meter-bar {
  background: var(--color-border);
  border-radius: 3px;
  border: none;
}

.skills-list meter::-webkit-meter-optimum-value {
  background: var(--color-accent);
  border-radius: 3px;
}

/* Firefox */
.skills-list meter::-moz-meter-bar {
  background: var(--color-accent);
  border-radius: 3px;
}

Step 7 — Fun Fact Aside

I wanted a fun fact callout — content tangentially related to the main profile. <aside> is the semantic element for exactly this. Screen readers identify it as supplementary content that users can skip.

<aside>
  <p>
    I've contributed to 3 open-source projects
    with 500+ combined GitHub stars, and I spoke
    at ReactConf 2024 about building accessible
    component libraries.
  </p>
</aside>

aside {
  background: var(--color-aside-bg);
  border-radius: 8px;
  padding: 1rem 1.25rem;
  font-size: 0.875rem;
  color: var(--color-text-body);
  border-left: 3px solid var(--color-accent);
}

Step 8 — Contact Links (::before Icons + Attribute Selectors)

I styled links differently based on their href attribute — no extra classes needed. The email link turns red automatically using [href^="mailto:"]. I also added ::before pseudo-elements with icons for each link type — email gets ✉, LinkedIn gets 💼, GitHub gets 💻, Twitter gets 🌐.

<nav>
  <h2>Contact</h2>
  <li>
    <a href="mailto:sarah.chen@example.com">Email</a>
  </li>
  <li>
    <a href="https://linkedin.com/in/sarahchen"
       target="_blank">LinkedIn</a>
  </li>
  <li>
    <a href="https://github.com/sarahchen"
       target="_blank">GitHub</a>
  </li>
  <li>
    <a href="https://twitter.com/sarahchen"
       target="_blank">Twitter</a>
  </li>
</nav>

nav ul {
  list-style-type: none;
}

nav li {
  list-style-type: none;
  margin-bottom: 0.5rem;
}

nav a {
  text-decoration: none;
  color: var(--color-text-body);
}

/* ::before pseudo-elements for link icons */
nav a::before {
  display: inline-block;
  width: 1.5em;
  text-align: center;
  margin-right: 0.25em;
}

nav a[href^="mailto:"]::before {
  content: "\2709";   /* ✉ envelope */
}

nav a[href*="linkedin"]::before {
  content: "\1F4BC";  /* 💼 briefcase */
}

nav a[href*="github"]::before {
  content: "\1F4BB";  /* 💻 laptop */
}

nav a[href*="twitter"]::before {
  content: "\1F310";  /* 🌐 globe */
}

/* Attribute selector: mailto links in accent color */
nav a[href^="mailto:"] {
  color: var(--color-accent);
  font-weight: 500;
}

nav a:hover {
  color: var(--color-accent-hover);
  text-decoration: underline;
}

/* Focus: keyboard accessibility (WCAG 2.1) */
nav a:focus {
  outline: 2px solid var(--color-accent);
  outline-offset: 2px;
  border-radius: 2px;
}

Step 9 — Footer

<footer> isn't limited to the page bottom. It represents footer content for its nearest sectioning ancestor — here, the <article>. The card's copyright belongs inside the card's footer.

<footer>
  <p>
    &copy; 2023 Sarah Chen. All rights reserved.
  </p>
</footer>

footer {
  border-top: 1px solid var(--color-border);
  padding-top: var(--section-gap);
  margin-top: var(--section-gap);
  text-align: center;
  font-size: 0.8125rem;
  color: var(--color-text-muted);
}

Step 10 — Card Hover, Animation + Mobile

The finishing touches: a deeper shadow on hover (the transition was already set in Step 2), the @keyframes fadeSlideUp animation for the entrance, and responsive adjustments for mobile — the skills grid drops to 2 columns.

article:hover {
  box-shadow: 0 8px 40px rgba(0, 0, 0, 0.18);
}

@keyframes fadeSlideUp {
  0% {
    opacity: 0;
    transform: translateY(20px);
  }
  100% {
    opacity: 1;
    transform: translateY(0);
  }
}

@media (max-width: 767px) {
  body {
    padding: 1rem;
    align-items: flex-start;
  }

  article {
    padding: 1.5rem;
  }

  .profile-photo img {
    width: 120px;
    height: 120px;
  }

  .skills-list {
    grid-template-columns: repeat(2, 1fr);
  }
}

Step 11 — Dark Mode with :has()

This is the CSS that powers the dark mode toggle I added in Step 3. When the <details> element is open, body:has(details[open]) matches and swaps all the design tokens to dark colors. Every element that uses var(--color-*) updates automatically.

body:has(details[open]) {
  --color-bg: #0f0f1a;
  --color-card-bg: #1a1a2e;
  --color-text-primary: #e8e8f0;
  --color-text-body: #b0b0c8;
  --color-text-muted: #707088;
  --color-accent: #e94560;
  --color-accent-hover: #ff6b81;
  --color-skill-bg: #252540;
  --color-aside-bg: #20203a;
  --color-border: #2e2e4a;
}

Step 12 — Print Stylesheet

The final touch — a print stylesheet that strips out decorative elements and makes the card printer-friendly. The dark mode toggle is hidden, shadows become borders, the photo is removed, and all text turns black.

@media print {
  details {
    display: none;
  }

  article {
    box-shadow: none;
    border: 1px solid #00000025;
  }

  .profile-photo {
    display: none;
  }

  aside {
    border: 1px solid #00000020;
  }

  nav a {
    color: black;
  }
}

Acceptance Criteria

Here's the checklist I used to verify the build:

• Zero <div> tags in the HTML
• Uses all semantic elements: <main>, <article>, <header>, <details>, <section> (×2), <aside>, <nav>, <footer>, <figure>, <meter>
• Dark mode toggle works via :has(details[open]) — no JavaScript
• Skills displayed in a 4-column CSS Grid with icons and <meter> proficiency bars
• Contact links have ::before pseudo-element icons that align vertically
• Card has fadeSlideUp entrance animation
• Print stylesheet hides decorative elements
• Hover effects on card and skill items
• :focus styles on all links (keyboard accessible)
• All values use CSS custom properties from :root
• Responsive: skills grid drops to 2 columns on mobile, photo shrinks
• Valid HTML — passes W3C Validator

Quick Reference

CSS Units — When to Use What

CSS Selector Types Used

I've been writing JavaScript for a while now. Async code, Promises, setTimeout — I use them almost every day. I thought I understood how they work.

Then I went down a rabbit hole.

I was watching Philip Roberts' talk "What the heck is the event loop anyway?" and somewhere around the 15-minute mark, something caught me off guard. I had always assumed the event loop was part of V8 — the JavaScript engine. Turns out, it's not. V8 doesn't know what an event loop is. It just executes code and manages the call stack. The event loop is the runtime's job — the browser's, or Node's.

That one thing unraveled a bunch of assumptions I didn't even know I was carrying.

Like — I thought setTimeout(fn, 0) runs basically immediately after the current code. It doesn't. I thought Promise callbacks and setTimeout callbacks were in the same queue. They're not. I thought I had a clear mental model of how async JS works. I didn't.

Here's what my mental model looked like before:

So I decided to actually sit down, go through the resources properly, and write it all out — because the best way I know to solidify something is to explain it.

This is that attempt. If we've had the same fuzzy understanding, hopefully this helps.

So — What Actually Is the Event Loop?

Let me start with the thing that tripped me up first.

When I thought "event loop," I thought "V8." It felt like it should be part of the engine — the thing that runs JavaScript. But V8 is actually much more focused than that.

What V8 Actually Does

V8's entire job is to take our JavaScript, compile it, and execute it on the Call Stack. It also manages memory through the Heap. That's the full scope of what it does.

It doesn't know what setTimeout is. It doesn't know what fetch is. It has no concept of timers, network requests, or DOM events. If we ran V8 completely standalone, none of those APIs would exist.

Where the Runtime Takes Over

All of that comes from the runtime — the environment V8 is embedded in. In the browser, that runtime is managed by the browser itself (Chrome uses something called Blink alongside V8). In Node.js, the runtime is built on top of a C library called libuv, which handles all the async I/O and the event loop mechanics.

So the actual picture looks like this:

The Event Loop's only job is to watch the Call Stack. The moment it's empty, the Event Loop steps in and decides what runs next. And this is where the rule that governs all async JavaScript lives.

Microtasks (Promise callbacks, queueMicrotask) always get priority over macrotasks (setTimeout, setInterval, I/O callbacks). Always. Even if the macrotask was queued first.

This is why this code does what it does:

console.log('1');

setTimeout(() => console.log('2'), 0); // macrotask

Promise.resolve().then(() => console.log('3')); // microtask

console.log('4');

// Output: 1 → 4 → 3 → 2

setTimeout with 0ms delay feels like it should run right away. But "0ms" just means "queue it as soon as possible" — it still goes into the Macrotask Queue. The Promise callback, being a microtask, jumps ahead of it.

I had definitely written code that depended on the wrong mental model of this ordering without realizing it.

Macrotasks and Microtasks — They're Not the Same Queue

Once I understood that V8 and the runtime are separate, the next thing that clicked was that there isn't just one queue. There are two — and they have very different priorities.

The Macrotask Queue is where callbacks from setTimeout, setInterval, and I/O operations land after their async work completes.

The Microtask Queue is where Promise callbacks live — anything we chain with .then(), .catch(), .finally(), or write after an await. queueMicrotask() and MutationObserver callbacks go here too.

Step-by-Step Tracer

Let's trace through the example step by step. Click Play or step through manually:

Both setTimeout callbacks were queued before the Promise chain even resolved — yet the Promise callback ran first. Because microtasks always drain completely before any macrotask gets a turn.

And it's not just one pass through the microtask queue. If a microtask queues another microtask, that also runs before any macrotask. The event loop doesn't move to macrotasks until the microtask queue is completely empty.

The Starvation Problem

This has a consequence most people never think about. If a microtask keeps queuing another microtask, the macrotask queue never gets a turn:

// This will STARVE the macrotask queue
function keepGoing() {
  Promise.resolve().then(keepGoing);
}
keepGoing();

setTimeout(() => console.log('this never runs'), 0);

async/await is Just Microtasks

If we use async/await, we're already using microtasks — just with cleaner syntax. Everything after an await is the equivalent of a .then() callback:

async function run() {
  console.log('A');
  await Promise.resolve();
  console.log('B'); // this is a microtask
}

console.log('1');
run();
console.log('2');

// Output: 1 → A → 2 → B

'B' doesn't run immediately after 'A' even though the Promise resolves instantly. The await suspends run(), lets the synchronous code ('2') finish, and then 'B' runs as a microtask. Once we see await as "pause here, queue the rest as a microtask," the output becomes completely predictable.

Why Any of This Matters in Real Code

Understanding the event loop isn't an interview exercise. I've run into each of these in actual projects — and each time, having the right mental model was the difference between a 5-minute fix and two hours of confusion.

1. The Spinner That Never Spins

This one is classic. We want to show a loading indicator before running something expensive:

setIsLoading(true);
const result = heavyComputation(); // takes 2 seconds
setIsLoading(false);

The spinner never appears. We stare at it, add a console.log, confirm setIsLoading(true) is being called — and it is. So why doesn't it show?

Because the call stack never empties between those two lines. The browser only gets a chance to paint between macrotasks. Our heavy computation is blocking the single thread entirely, so the UI has no opportunity to reflect the state change.

The fix is to deliberately yield to the browser:

setIsLoading(true);
setTimeout(() => {
  const result = heavyComputation();
  setIsLoading(false);
}, 0);

That setTimeout(fn, 0) isn't really "run after 0ms" — it's "queue this as a macrotask, which lets the browser render first." Once we know how the event loop works, this stops being a weird trick and starts being an obvious tool.

2. async forEach — The Silent Bug

This one has caught a lot of developers off guard, including me:

[1, 2, 3].forEach(async (num) => {
  await fetch(`/api/${num}`);
  console.log(num);
});
console.log('done');

// 'done' logs first — forEach doesn't await anything

forEach doesn't know anything about the Promise our async callback returns. It calls the function, gets a Promise back, and immediately moves on — it never awaits it. Each await fetch(...) suspends that specific callback's microtask chain, but forEach has already finished by then.

If we need to wait for all operations:

await Promise.all([1, 2, 3].map(async (num) => {
  await fetch(`/api/${num}`);
  console.log(num);
}));
console.log('done'); // now this actually waits

3. Sequential await Is Silently Killing Our Performance

This is less of a bug and more of a habit that costs us without realizing:

// Sequential — total time: 3 seconds
const user = await getUser();      // 1s
const posts = await getPosts();    // 1s
const comments = await getComments(); // 1s

Each await suspends the function and queues the rest as a microtask after the Promise resolves. The next await doesn't even start until the previous one is completely done. If these three calls don't depend on each other, we're wasting time:

// Parallel — total time: 1 second
const [user, posts, comments] = await Promise.all([
  getUser(),
  getPosts(),
  getComments()
]);

Same result, a third of the wait time. This only clicks properly once we understand that await is just a microtask checkpoint — not a magic "go do this in the background" instruction.

4. Never Rely on setTimeout(fn, 0) Ordering

A subtle one. It's tempting to write something like:

setTimeout(() => console.log('this should run first'), 0);
setTimeout(() => console.log('this should run second'), 0);

In practice this usually works in order — but the moment we add Promises, or the browser is under any load, macrotask ordering between separate setTimeout calls isn't something we want to depend on architecturally. If order matters, make it explicit in our code structure, not in timing assumptions.

The One Thing to Take Away

If I had to compress everything in this article into a single rule:

When the call stack is empty — drain all microtasks first, then pick one macrotask, then repeat.

That's the entire event loop. Every async quirk, every surprising output, every "why isn't my spinner showing" bug — it all traces back to that one rule.

But here's the deeper insight that changes how we think about JavaScript entirely:

The JS Engine (V8) is single-threaded, synchronous, one thing at a time on the call stack. No exceptions.

The Runtime — the Web APIs it provides (like setTimeout, fetch) actually run outside the JS thread entirely. The browser handles them in its own internal threads (written in C++). So when we call fetch(), the actual network request is happening in the browser's networking layer — completely separate from our JS thread.

So it's not that the runtime makes JS parallel — our JS code never runs in parallel with itself. What the runtime does is offload the waiting part (waiting for a timer, waiting for a network response) to the outside world, and only brings the callback back into our JS thread when the call stack is free.

So the more precise conclusion is:

• JS execution — always single-threaded and synchronous
• The waiting/I/O work — offloaded to the runtime, runs outside JS
• The result — feels asynchronous, but our code itself never truly runs in parallel

Worth being precise about the word "parallel" — in interviews, that distinction matters a lot. And in debugging, it's the difference between understanding the bug and just staring at the screen.

What's Next

This is the first article in a series I'm writing as I go deeper into JS engine internals. Next up: how V8 actually compiles our JavaScript — parsing, the AST, Ignition, TurboFan, and why the code we write affects how well V8 can optimize it.

If that sounds interesting, follow along — I'm learning this in public and writing it up as I go.

Find me on Twitter, GitHub, or LinkedIn.

References

These two talks shaped my understanding more than anything else I've read. If you haven't watched them yet, start here:

• What the heck is the event loop anyway? — Philip Roberts (JSConf EU 2014). The talk that started it all for me. He built Loupe, an incredible visual tool to see the event loop in action.
• JavaScript Visualized — Event Loop, Web APIs, (Micro)task Queue — Lydia Hallie. Beautifully animated breakdown of microtasks vs macrotasks. Her visual style of explaining async JavaScript is unmatched.

Welcome to my little corner of the internet. I'm Ravi, a full-stack developer who loves building things for the web. This blog is my space for sharing the learnings, experiments, and random discoveries that come with writing code every day.

What This Space Is About

I've always believed that the best way to learn is to share. So here I'll be writing about the things I work on, the problems I run into, and how I solve them — from frontend patterns to backend architecture, from debugging nightmares to deployment wins.

No gatekeeping, no over-engineering the words. Just honest notes from someone who's constantly learning and building.

Let's Connect

If you want to talk shop, have feedback, or just want to say hi — find me on Twitter, GitHub, or LinkedIn.

More articles coming soon. Stay tuned.