rarouš.w3b

Tech's empiricism problem

2026-03-15T06:36:23Z

The tech industry has extreme difficulty integrating information that doesn't have its source in an overtly rationalist process. In practice, this means that we tend to think that if you can't give a logical chain of deductions that proves that something is the case, your information is worthless. The issue with this is that day-to-day, in the tech world and outside of it, the vast bulk of the information we use to make decisions isn't this kind of information.

Nobody Gets Promoted for Simplicity

2026-03-07T05:55:29Z

“Simplicity is a great virtue, but it requires hard work to achieve and education to appreciate. And to make matters worse, complexity sells better.” — Edsger Dijkstra

I think there’s something quietly screwing up a lot of engineering teams. In interviews, in promotion packets, in design reviews: the engineer who overbuilds gets a compelling narrative, but the one who ships the simplest thing that works gets… nothing.

This isn’t intentional, of course. Nobody sits down and says, “let’s make sure the people who over-engineer things get promoted!” But that’s what can happen (and it has been, over and over again) when companies evaluate work incorrectly.

Picture two engineers on the same team. Engineer A gets assigned a feature. She looks at the problem, considers a few options, and picks the simplest. A straightforward implementation, maybe 50 lines of code. Easy to read, easy to test, easy for the next person to pick up. It works. She ships it in a couple of days and moves on.

Engineer B gets a similar feature. He also looks at the problem, but he sees an opportunity to build something more “robust.” He introduces a new abstraction layer, creates a pub/sub system for communication between components, adds a configuration framework so the feature is “extensible” for future use cases. It takes three weeks. There are multiple PRs. Lots of excited emojis when he shares the document explaining all of this.

Now, promotion time comes around. Engineer B’s work practically writes itself into a promotion packet: “Designed and implemented a scalable event-driven architecture, introduced a reusable abstraction layer adopted by multiple teams, and built a configuration framework enabling future extensibility.” That practically screams Staff+.

But for Engineer A’s work, there’s almost nothing to say. “Implemented feature X.” Three words. Her work was better. But it’s invisible because of how simple she made it look. You can’t write a compelling narrative about the thing you didn’t build. Nobody gets promoted for the complexity they avoided.

Complexity looks smart. Not because it is, but because our systems are set up to reward it. And the incentive problem doesn’t start at promotion time. It starts before you even get the job.

Think about interviews. You’re in a system design round, and you propose a simple solution. A single database, a straightforward API, maybe a caching layer. The interviewer is like: “What about scalability? What if you have ten million users?” So you add services. You add queues. You add sharding. You draw more boxes on the whiteboard. The interviewer finally seems satisfied now.

What you just learned is that complexity impresses people. The simple answer wasn’t wrong. It just wasn’t interesting enough. And you might carry that lesson with you into your career. To be fair, interviewers sometimes have good reasons to push on scale; they want to see how you think under pressure and whether you understand distributed systems. But when the takeaway for the candidate is “simple wasn’t enough,” something’s off.

It also shows up in design reviews. An engineer proposes a clean, simple approach and gets hit with “shouldn’t we future-proof this?” So they go back and add layers they don’t need yet, abstractions for problems that might never materialize, flexibility for requirements nobody has asked for. Not because the problem demanded it, but because the room expected it.

I’ve seen engineers (and have been one myself) create abstractions to avoid duplicating a few lines of code, only to end up with something far harder to understand and maintain than the duplication ever was. Every time, it felt like the right thing to do. The code looked more “professional.” More engineered. But the users didn’t get their feature any faster, and the next engineer to touch it had to spend half a day understanding the abstraction before they could make any changes.

Now, let me be clear: complexity is sometimes the right call. If you’re processing millions of transactions, you might need distributed systems. If you have 10 teams working on the same product, you probably need service boundaries. When the problem is complex, the solution (probably) should be too!

The issue isn’t complexity itself. It’s unearned complexity. There’s a difference between “we’re hitting database limits and need to shard” and “we might hit database limits in three years, so let’s shard now.”

Some engineers understand this. And when you look at their code (and architecture), you think “well, yeah, of course.” There’s no magic, no cleverness, nothing that makes you feel stupid for not understanding it. And that’s exactly the point.

The actual path to seniority isn’t learning more tools and patterns, but learning when not to use them. Anyone can add complexity. It takes experience and confidence to leave it out.

So what do we actually do about this? Because saying “keep it simple” is easy. Changing incentive structures is harder.

If you’re an engineer, learn that simplicity needs to be made visible. The work doesn’t speak for itself; not because it’s not good, but because most systems aren’t designed to hear it.

Start with how you talk about your own work. “Implemented feature X” doesn’t mean much. But “evaluated three approaches including an event-driven architecture and a custom abstraction layer, determined that a straightforward implementation met all current and projected requirements, and shipped in two days with zero incidents over six months”, that’s the same simple work, just described in a way that captures the judgment behind it. The decision not to build something is a decision, an important one! Document it accordingly.

In design reviews, when someone asks “shouldn’t we future-proof this?”, don’t just cave and go add layers. Try: “Here’s what it would take to add that later if we need it, and here’s what it costs us to add it now. I think we wait.” You’re not pushing back, but showing you’ve done your homework. You considered the complexity and chose not to take it on.

And yes, bring this up with your manager. Something like: “I want to make sure the way I document my work reflects the decisions I’m making, not just the code I’m writing. Can we talk about how to frame that for my next review?” Most managers will appreciate this because you’re making their job easier. You’re giving them language they can use to advocate for you.

Now, if you do all of this and your team still only promotes the person who builds the most elaborate system… that’s useful information too. It tells you something about where you work. Some cultures genuinely value simplicity. Others say they do, but reward the opposite. If you’re in the second kind, you can either play the game or find a place where good judgment is actually recognized. But at least you’ll know which one you’re in.

If you’re an engineering leader, this one’s on you more than anyone else. You set the incentives, whether you realize it or not. And the problem is that most promotion criteria are basically designed to reward complexity, even when they don’t intend to. “Impact” gets measured by the size and scope of what someone built, which more often than not matters! But what they avoided should also matter.

So start by changing the questions you ask. In design reviews, instead of “have we thought about scale?”, try “what’s the simplest version we could ship, and what specific signals would tell us we need something more complex?” That one question changes the game: it makes simplicity the default and puts the burden of proof on complexity, not the other way around!

In promotion discussions, push back when someone’s packet is basically a list of impressive-sounding systems. Ask: “Was all of that necessary? Did we actually need a pub/sub system here, or did it just look good on paper?” And when an engineer on your team ships something clean and simple, help them write the narrative. “Evaluated multiple approaches and chose the simplest one that solved the problem” is a compelling promotion case, but only if you actually treat it like one.

One more thing: pay attention to what you celebrate publicly. If every shout-out in your team channel is for the big, complex project, that’s what people will optimize for. Start recognizing the engineer who deleted code. The one who said “we don’t need this yet” and was right.

At the end of the day, if we keep rewarding complexity and ignoring simplicity, we shouldn’t be surprised when that’s exactly what we get. But the fix isn’t complicated. Which, I guess, is kind of the point.

The Frontend Treadmill

2026-03-05T19:30:10Z

A lot of frontend teams are very convinced that rewriting their frontend will lead to the promised land. And I am the bearer of bad tidings.

If you are building a product that you hope has longevity, your frontend framework is the least interesting technical decision for you to make. And all of the time you spend arguing about it is wasted energy.

I will die on this hill.

If your product is still around in 5 years, you’re doing great and you should feel successful. But guess what? Whatever framework you choose will be obsolete in 5 years. That’s just how the frontend community has been operating, and I don’t expect it to change soon. Even the popular frameworks that are still around are completely different. Because change is the name of the game. So they’re gonna rewrite their shit too and just give it a new version number.

Product teams that are smart are getting off the treadmill. Whatever framework you currently have, start investing in getting to know it deeply. Learn the tools until they are not an impediment to your progress. That’s the only option. Replacing it with a shiny new tool is a trap.

I also wanna give a piece of candid advice to engineers who are searching for jobs. If you feel strongly about what framework you want to use, please make that a criteria for your job search. Please stop walking into teams and derailing everything by trying to convince them to switch from framework X to your framework of choice. It’s really annoying and tremendously costly.

I always have to start with the cynical take. It’s just how I am. But I do want to talk about what I think should be happening instead.

Companies that want to reduce the cost of their frontend tech becoming obsoleted so often should be looking to get back to fundamentals. Your teams should be working closer to the web platform with a lot less complex abstractions. We need to relearn what the web is capable of and go back to that.

Let’s be clear, I’m not suggesting this is strictly better and the answer to all of your problems. I’m suggesting this as an intentional business tradeoff that I think provides more value and is less costly in the long run. I believe if you stick closer to core web technologies, you’ll be better able to hire capable engineers in the future without them convincing you they can’t do work without rewriting millions of lines of code.

And if you’re an engineer, you will be able to retain much higher market value over time if you dig into and understand core web technologies. I was here before react, and I’ll be here after it dies. You may trade some job marketability today. But it does a lot more for career longevity than trying to learn every new thing that gets popular. And you see how quickly they discarded us when the market turned anyway. Knowing certain tech won’t save you from those realities.

I couldn’t speak this candidly about this stuff when I held a management role. People can’t help but question my motivations and whatever agenda I may be pushing. Either that or I get into a lot of trouble with my internal team because they think I’m talking about them. But this is just what I’ve seen play out after doing this for 20+ years. And I feel like we need to be able to speak plainly.

This has been brewing in my head for a long time. The frontend ecosystem is kind of broken right now. And it’s frustrating to me for a few different reasons. New developers are having an extremely hard time learning enough skills to be gainfully employed. They are drowning in this complex garbage and feeling really disheartened. As a result, companies are finding it more difficult to do basic hiring. The bar is so high just to get a regular dev job. And everybody loses.

What’s even worse is that I believe a lot of this energy is wasted. People that are learning the current tech ecosystem are absolutely not learning web fundamentals. They are too abstracted away. And when the stack changes again, these folks are going to be at a serious disadvantage when they have to adapt away from what they learned. It’s a deep disservice to people’s professional careers, and it’s going to cause a lot of heartache later.

On a more personal note, this is frustrating to me because I think it’s a big part of why we’re seeing the web stagnate so much. I still run into lots of devs who are creative and enthusiastic about building cool things. They just can’t. They are trying and failing because the tools being recommended to them are just not approachable enough. And at the same time, they’re being convinced that learning fundamentals is a waste of time because it’s so different from what everybody is talking about.

I guess I want to close by stating my biases. I’m a web guy. I’ve been bullish on the web for 20+ years, and I will continue to be. I think it is an extremely capable and unique platform for delivering software. And it has only gotten better over time while retaining an incredible level of backwards compatibility. The underlying tools we have are dope now. But our current framework layer is working against the grain instead of embracing the platform.

This is from a recent thread I wrote on mastodon. Reproduced with only light editing.

A GitHub Issue Title Compromised 4,000 Developer Machines

2026-03-05T19:15:27Z

esc to close

Five steps from a GitHub issue title to 4,000 compromised developer machines. The entry point was natural language.

On February 17, 2026, someone published cline@2.3.0 to npm. The CLI binary was byte-identical to the previous version. The only change was one line in package.json:

"postinstall": "npm install -g openclaw@latest"

For the next eight hours, every developer who installed or updated Cline got OpenClaw - a separate AI agent with full system access - installed globally on their machine without consent. Approximately 4,000 downloads occurred before the package was pulled¹.

The interesting part is not the payload. It is how the attacker got the npm token in the first place: by injecting a prompt into a GitHub issue title, which an AI triage bot read, interpreted as an instruction, and executed.

The full chain

The attack - which Snyk named "Clinejection"² - composes five well-understood vulnerabilities into a single exploit that requires nothing more than opening a GitHub issue.

Step 1: Prompt injection via issue title. Cline had deployed an AI-powered issue triage workflow using Anthropic's claude-code-action. The workflow was configured with allowed_non_write_users: "*", meaning any GitHub user could trigger it by opening an issue. The issue title was interpolated directly into Claude's prompt via ${{ github.event.issue.title }} without sanitisation.

On January 28, an attacker created Issue #8904 with a title crafted to look like a performance report but containing an embedded instruction: install a package from a specific GitHub repository³.

Step 2: The AI bot executes arbitrary code. Claude interpreted the injected instruction as legitimate and ran npm install pointing to the attacker's fork - a typosquatted repository (glthub-actions/cline, note the missing 'i' in 'github'). The fork's package.json contained a preinstall script that fetched and executed a remote shell script.

Step 3: Cache poisoning. The shell script deployed Cacheract, a GitHub Actions cache poisoning tool. It flooded the cache with over 10GB of junk data, triggering GitHub's LRU eviction policy and evicting legitimate cache entries. The poisoned entries were crafted to match the cache key pattern used by Cline's nightly release workflow.

Step 4: Credential theft. When the nightly release workflow ran and restored node_modules from cache, it got the compromised version. The release workflow held the NPM_RELEASE_TOKEN, VSCE_PAT (VS Code Marketplace), and OVSX_PAT (OpenVSX). All three were exfiltrated³.

Step 5: Malicious publish. Using the stolen npm token, the attacker published cline@2.3.0 with the OpenClaw postinstall hook. The compromised version was live for eight hours before StepSecurity's automated monitoring flagged it - approximately 14 minutes after publication¹.

A botched rotation made it worse

Security researcher Adnan Khan had actually discovered the vulnerability chain in late December 2025 and reported it via a GitHub Security Advisory on January 1, 2026. He sent multiple follow-ups over five weeks. None received a response³.

When Khan publicly disclosed on February 9, Cline patched within 30 minutes by removing the AI triage workflows. They began credential rotation the next day.

But the rotation was incomplete. The team deleted the wrong token, leaving the exposed one active⁴. They discovered the error on February 11 and re-rotated. But the attacker had already exfiltrated the credentials, and the npm token remained valid long enough to publish the compromised package six days later.

Khan was not the attacker. A separate, unknown actor found Khan's proof-of-concept on his test repository and weaponised it against Cline directly³.

The new pattern: AI installs AI

The specific vulnerability chain is interesting but not unprecedented. Prompt injection, cache poisoning, and credential theft are all documented attack classes. What makes Clinejection distinct is the outcome: one AI tool silently bootstrapping a second AI agent on developer machines.

This creates a recursion problem in the supply chain. The developer trusts Tool A (Cline). Tool A is compromised to install Tool B (OpenClaw). Tool B has its own capabilities - shell execution, credential access, persistent daemon installation - that are independent of Tool A and invisible to the developer's original trust decision.

OpenClaw as installed could read credentials from ~/.openclaw/, execute shell commands via its Gateway API, and install itself as a persistent system daemon surviving reboots¹. The severity was debated - Endor Labs characterised the payload as closer to a proof-of-concept than a weaponised attack⁵ - but the mechanism is what matters. The next payload will not be a proof-of-concept.

This is the supply chain equivalent of confused deputy: the developer authorises Cline to act on their behalf, and Cline (via compromise) delegates that authority to an entirely separate agent the developer never evaluated, never configured, and never consented to.

Why existing controls did not catch it

npm audit: The postinstall script installs a legitimate, non-malicious package (OpenClaw). There is no malware to detect.

Code review: The CLI binary was byte-identical to the previous version. Only package.json changed, and only by one line. Automated diff checks that focus on binary changes would miss it.

Provenance attestations: Cline was not using OIDC-based npm provenance at the time. The compromised token could publish without provenance metadata, which StepSecurity flagged as anomalous¹.

Permission prompts: The installation happens in a postinstall hook during npm install. No AI coding tool prompts the user before a dependency's lifecycle script runs. The operation is invisible.

The attack exploited the gap between what developers think they are installing (a specific version of Cline) and what actually executes (arbitrary lifecycle scripts from the package and everything it transitively installs).

What Cline changed afterward

Cline's post-mortem⁴ outlines several remediation steps:

Eliminated GitHub Actions cache usage from credential-handling workflows
Adopted OIDC provenance attestations for npm publishing, eliminating long-lived tokens
Added verification requirements for credential rotation
Began working on a formal vulnerability disclosure process with SLAs
Commissioned third-party security audits of CI/CD infrastructure

These are meaningful improvements. The OIDC migration alone would have prevented the attack - a stolen token cannot publish packages when provenance requires a cryptographic attestation from a specific GitHub Actions workflow.

The architectural question

Clinejection is a supply chain attack, but it is also an agent security problem. The entry point was natural language in a GitHub issue title. The first link in the chain was an AI bot that interpreted untrusted text as an instruction and executed it with the privileges of the CI environment.

This is the same structural pattern we have written about in the context of MCP tool poisoning and agent skill registries - untrusted input reaches an agent, the agent acts on it, and nothing evaluates the resulting operations before they execute.

The difference here is that the agent was not a developer's local coding assistant. It was an automated CI workflow that ran on every new issue, with shell access and cached credentials. The blast radius was not one developer's machine - it was the entire project's publication pipeline.

Every team deploying AI agents in CI/CD - for issue triage, code review, automated testing, or any other workflow - has this same exposure. The agent processes untrusted input (issues, PRs, comments) and has access to secrets (tokens, keys, credentials). The question is whether anything evaluates what the agent does with that access.

Per-syscall interception catches this class of attack at the operation layer. When the AI triage bot attempts to run npm install from an unexpected repository, the operation is evaluated against policy before it executes - regardless of what the issue title said. When a lifecycle script attempts to exfiltrate credentials to an external host, the egress is blocked.

The entry point changes. The operations do not. grith was built to catch exactly this class of problem - evaluating every operation at the syscall layer, regardless of which agent triggered it or why.

Container queries and units in action

2026-03-05T06:07:52Z

Published: October 23, 2025

One of the goals when writing CSS is to build component parts that will adapt well to different (and unexpected) contexts. Ideally, a component can be placed inside any "container" element without it feeling broken or out of place. How can you accomplish this in a complex layout like a store where the primary component—the "product"—has to fit into a variety of list layouts, including the sidebar?

Responsive typography with `cqi` units

The first step is to define some basic sizing variables that could be reused across the project—starting with whitespace sizes. But before creating any custom properties, the browser provides some useful named values as CSS units:

1em: the current font size.
1rem: the font size on the :root (html) element.
1lh / 1rlh: the current and root line heights.
1vw: the viewport width.
1vi: the viewport "inline" size (for English, this is the same as vw).
1cqi: the inline size of the nearest "container" (defaulting to the viewport).

You can think of these units as common variables provided by the browser, with a shorthand syntax for multiplication. If you wanted half of a --line-height custom property in CSS, you would need to write the entire calculation calc(0.5 * var(--line-height)), but with the lh unit, you can ask for 0.5lh instead.

Custom properties like --brand-color and --button-background have different meanings and serve a different purpose, even when they result in the same deepPink color (another browser-provided variable). Similarly, 1em might sometimes be equal to 16px, but that's not a stable relationship. Like any other variable, units should be used to express a relationship, rather than an expected value.

Both 1em and 1lh are font-relative units that could be used for spacing, but only one of them has a reliable relationship to the current line height. If this page involved a lot of elements with prose in them—paragraphs and lists, for example—the lh unit would work well for spacing between them:

p, ul, ol {
  margin-block: 1lh;
}

That will maintain a consistent baseline rhythm, without any extra work. But this page has almost no prose. Instead of spacing within a flow of text, this layout requires spacing to push text away from the edge of a card, and spacing between columns and rows in a grid or stacked layout. In this case there are several things to consider:

Multiples (or fractions) of 1lh may still be useful for maintaining vertical rhythm across the page.
The cqi unit would account for the amount of available space in a given context.

By combining these two units in a round() function, the --gap variable is based primarily on the container size, but rounded up to a multiple of quarter-lines:

html {
  --gap: round(up, 2cqi, 0.25lh);
}

If the line-height is 20px, then the --gap will be multiples of 5px—but the exact multiple will depend on available space. If either the line-height or available space change, the --gap variable will adapt to its new context. To make the --gap consistent across the entire design, you could replace the container-relative cqi units with viewport-relative vi units.

The same approach is useful when establishing "fluid" font sizes that respond to available space. This --body-text variable is based on the user-provided font preference, with some range to adapt based on the container. In this case, clamp() ensures the font will be at least as large as the user's preference, can grow some as the container size increases, but will stop growing at some point:

html {
  --body-text: clamp(1rem, 0.875rem + 0.5cqi, 1.25rem);
}

The range is clamped between 1rem and 1.25rem, to stay near the user-selected font size.
The cqi value determines how fast the font will grow or shrink in relation to available space, which is added to a rem value to offset that growth based on the user-selected size.

Keeping the central rem value near 1 and the added cqi value low ensures that users still have significant control when zooming in or out. You can adjust those two values, and then use browser zoom to see how they interact. The closer you get to 100cqi, and the farther you fall below 1rem, the less influence user font preferences will have—and the less font sizes will respond to zooming in or out.

The --item-title variable is slightly larger and more responsive, and the --list-title size responds to the viewport size (using vi) rather than the immediate container size. That way item headings respond to their context, but the main list headings all match in size no matter where they show up.

Defining containers to measure in context

At this point, container query units have been used to create adaptive typography on a web page, but new containers haven't been defined.

By default, 1cqi (1/100 container query inline size) is the same as 1svi (1/100 small viewport inline size) because the "small" viewport acts as the initial container for any web page. In order to take full advantage of the cqi unit, you need to define additional "containers" within the page. The primary layout containers on this page are the product-list and shopping-cart—so they are set to expose their inline-size.

product-list,
shopping-cart {
  container-type: inline-size;
}

Container query units—including cqi—aren't able to measure the element that they are used on. If you set the width of shopping-cart to 25cqi, it would be a paradox to determine the container's width based on its own width! Instead, the result will be based on the next ancestor container in the tree hierarchy that contains shopping-cart.

The product-detail cards are part of a product-list grid that can be changed by the user. The list layout option displays each card at full width. In that case, referring to the parent container size is useful, but both the small-grid and large-grid options cause the card to grow and shrink depending on how many columns fit into the container. Even when the container is quite large, the cards can remain tightly packed into smaller grid cells.

There's currently no way to declare those grid cells as "containers" directly. Instead, an extra element is needed to measure within each cell. That's why each product-detail instance has an <article> element nested directly inside. product-detail > article is the card to be styled, while product-detail itself is used only as a container to measure. That allows the cqi-based text and spacing calculations previously defined to be recalculated for the space available to each card.

Explicit container queries

Container units are powerful, but sometimes it's useful to make more dramatic changes in a component layout when the available size crosses a threshold. These are often called breakpoints—since the fix is applied at the point when a given layout begins to break. You may already be familiar with using @media to add breakpoints based on the viewport size:

main {
  display: grid;
  grid-template:
    'controls' auto
    'cart' 1fr
    'list' auto
    / minmax(min-content, 1fr);

  @media (width > 30em) {
    grid-template:
      'controls controls' auto
      'list cart' 1fr
      / 2fr 1fr
    ;
  }
}

Here, shopping-cart appears above the main product-list on small screens—but at a certain point, there's more horizontal space, and a sidebar makes more sense. Since that shift depends on the overall viewport, a media query is used to handle the change. However, the product-list and product-detail components might appear in different contexts, somewhat independent of the viewport size. When the viewport grows wider than the sidebar breakpoint, the shopping-cart component suddenly becomes smaller, providing less space for products inside. This is where container queries become necessary. The syntax is nearly identical to a media query, but uses @container rather than @media at the start of the rule:

article {
  display: grid;
  grid-template:
    'image' auto 'title' auto
    'summary' auto
    'button' auto / auto
  ;

  @container (inline-size > 40ch) {
    --image-ratio: 1;
    grid-template:
      'image title' auto
      'image summary' 1fr
      'image button' auto
      / minmax(50px, min(20%, 500px)) 1fr
    ;
  }

  @container (inline-size > 50ch) {
    grid-template:
      'image title title' auto
      'image summary button' 1fr
      / minmax(50px, min(20%, 500px)) 1fr fit-content(20%);
  }
}

The initial goal of this post is that components should be able to respond to any context. To make that work, each component defines its own internal behavior, without explicit knowledge of the surrounding components. Container queries help us accomplish that. The product-list and product-detail components don't need to be aware of why they have more or less space in a given context, they only need to know how much space is currently available.

Transition grid templates and visibility

With a layout that's changing often based on container queries, how do we smooth out all of the transitions? When using grids for layout, it's possible to animate the size of a column or row, as well as the gap between columns and rows. In this case, the cart area and gap are expanded from 0 width when the cart is opened. In order to animate grid templates like this, two things are required:

The initial and end states must have the same number of tracks (columns or rows).
The animated tracks must use comparable units.

While it would be possible to change from a one-column grid to a two-column grid when the sidebar is hidden, the empty sidebar column is instead resized to 0, and the column-gap is also set to 0. When the cart is open in the sidebar, the 0-width column transitions to calc(15em + 1cqi). Since the calculation results in a normal length value, the transition can be animated from length 0. The gap also animates from one length to another—from 0 to var(--gap)—which was defined earlier:

main {
  transition: grid-template 250ms, gap 250ms;
}

Non-Baseline animation enhancements

The shopping-cart and product-detail components are also animated when hidden or shown, and this is done using two recent features that are not yet Baseline, but work as progressive enhancements for browsers that do have support:

Applying interpolate-size: allow-keywords allows transitioning element dimensions from 0 to auto. This is used for transitioning the products to and from a block-size of 0 when they are added or removed from the cart. Since the interpolate-size property inherits, that only needs to be defined once on the <html> element, and it is available to every other element on the page. This is only supported in Chrome-based browsers (Chrome, Edge, and others), but can be used as a progressive enhancement. The fallback works as expected, just without the animated transition.
"Discrete" properties like display can now be transitioned as well, even though there are no intermediate values between grid and none. Instead the transition is applied at the start or end of the duration provided. To achieve that, allow-discrete is added to the transition-behavior property. While transition-behavior is otherwise Baseline, animating the display property is not yet supported in Firefox. But again, this works well as a progressive enhancement.

There are many situations where container queries and units can be used to replace media queries and viewport units, and that's great when it helps you express the intent of a design more clearly. But one is not meant to replace the other, and there's not a better query or unit that will work in every situation. CSS works best when the relationships established in code match the goals and purpose of the design. When you want text and spacing that is relative to immediate context, container queries provide that functionality, but when you want consistent sizing relative to the overall viewport, media queries and viewport units are still an excellent option. Most websites will likely involve a mix of both.

CSS @scope: An Alternative To Naming Conventions And Heavy Abstractions

2026-03-05T06:04:42Z

CSS `@scope`: An Alternative To Naming Conventions And Heavy Abstractions

Prescriptive class name conventions are no longer enough to keep CSS maintainable in a world of increasingly complex interfaces. Can the new @scope rule finally give developers the confidence to write CSS that can keep up with modern front ends?

When learning the principles of basic CSS, one is taught to write modular, reusable, and descriptive styles to ensure maintainability. But when developers become involved with real-world applications, it often feels impossible to add UI features without styles leaking into unintended areas.

This issue often snowballs into a self-fulfilling loop; styles that are theoretically scoped to one element or class start showing up where they don’t belong. This forces the developer to create even more specific selectors to override the leaked styles, which then accidentally override global styles, and so on.

Rigid class name conventions, such as BEM, are one theoretical solution to this issue. The BEM (Block, Element, Modifier) methodology is a systematic way of naming CSS classes to ensure reusability and structure within CSS files. Naming conventions like this can reduce cognitive load by leveraging domain language to describe elements and their state, and if implemented correctly, can make styles for large applications easier to maintain.

In the real world, however, it doesn’t always work out like that. Priorities can change, and with change, implementation becomes inconsistent. Small changes to the HTML structure can require many CSS class name revisions. With highly interactive front-end applications, class names following the BEM pattern can become long and unwieldy (e.g., app-user-overview__status--is-authenticating), and not fully adhering to the naming rules breaks the system’s structure, thereby negating its benefits.

Given these challenges, it’s no wonder that developers have turned to frameworks, Tailwind being the most popular CSS framework. Rather than trying to fight what seems like an unwinnable specificity war between styles, it is easier to give up on the CSS Cascade and use tools that guarantee complete isolation.

Developers Lean More On Utilities #

How do we know that some developers are keen on avoiding cascaded styles? It’s the rise of “modern” front-end tooling — like CSS-in-JS frameworks — designed specifically for that purpose. Working with isolated styles that are tightly scoped to specific components can seem like a breath of fresh air. It removes the need to name things — still one of the most hated and time-consuming front-end tasks — and allows developers to be productive without fully understanding or leveraging the benefits of CSS inheritance.

But ditching the CSS Cascade comes with its own problems. For instance, composing styles in JavaScript requires heavy build configurations and often leads to styles awkwardly intermingling with component markup or HTML. Instead of carefully considered naming conventions, we allow build tools to autogenerate selectors and identifiers for us (e.g., .jsx-3130221066), requiring developers to keep up with yet another pseudo-language in and of itself. (As if the cognitive load of understanding what all your component’s useEffects do weren’t already enough!)

Further abstracting the job of naming classes to tooling means that basic debugging is often constrained to specific application versions compiled for development, rather than leveraging native browser features that support live debugging, such as Developer Tools.

It’s almost like we need to develop tools to debug the tools we’re using to abstract what the web already provides — all for the sake of running away from the “pain” of writing standard CSS.

Luckily, modern CSS features not only make writing standard CSS more flexible but also give developers like us a great deal more power to manage the cascade and make it work for us. CSS Cascade Layers are a great example, but there’s another feature that gets a surprising lack of attention — although that is changing now that it has recently become Baseline compatible.

The CSS `@scope` At-Rule #

I consider the CSS @scope at-rule to be a potential cure for the sort of style-leak-induced anxiety we’ve covered, one that does not force us to compromise native web advantages for abstractions and extra build tooling.

“The @scope CSS at-rule enables you to select elements in specific DOM subtrees, targeting elements precisely without writing overly-specific selectors that are hard to override, and without coupling your selectors too tightly to the DOM structure.”

— MDN

In other words, we can work with isolated styles in specific instances without sacrificing inheritance, cascading, or even the basic separation of concerns that has been a long-running guiding principle of front-end development.

Plus, it has excellent browser coverage. In fact, Firefox 146 added support for @scope in December, making it Baseline compatible for the first time. Here is a simple comparison between a button using the BEM pattern versus the @scope rule:

The @scope rule allows for precision with less complexity. The developer no longer needs to create boundaries using class names, which, in turn, allows them to write selectors based on native HTML elements, thereby eliminating the need for prescriptive CSS class name patterns. By simply removing the need for class name management, @scope can alleviate the fear associated with CSS in large projects.

Basic Usage #

To get started, add the @scope rule to your CSS and insert a root selector to which styles will be scoped:

So, for example, if we were to scope styles to a <nav> element, it may look something like this:

This, on its own, is not a groundbreaking feature. However, a second argument can be added to the scope to create a lower boundary, effectively defining the scope’s start and end points.

This practice is called donut scoping, and there are several approaches one could use, including a series of similar, highly specific selectors coupled tightly to the DOM structure, a :not pseudo-selector, or assigning specific class names to <a> elements within the <nav> to handle the differing CSS.

Regardless of those other approaches, the @scope method is much more concise. More importantly, it prevents the risk of broken styles if classnames change or are misused or if the HTML structure were to be modified. Now that @scope is Baseline compatible, we no longer need workarounds!

We can take this idea further with multiple end boundaries to create a “style figure eight”:

Compare that to a version handled without the @scope rule, where the developer has to “reset” styles to their defaults:

Check out the following example. Do you notice how simple it is to target some nested selectors while exempting others?

See the Pen @scope example [forked] by Blake Lundquist.

Consider a scenario where unique styles need to be applied to slotted content within web components. When slotting content into a web component, that content becomes part of the Shadow DOM, but still inherits styles from the parent document. The developer might want to implement different styles depending on which web component the content is slotted into:

In this example, the developer might want the <user-card> to have distinct styles only if it is rendered inside <team-roster>:

More Benefits #

There are additional ways that @scope can remove the need for class management without resorting to utilities or JavaScript-generated class names. For example, @scope opens up the possibility to easily target descendants of any selector, not just class names:

And they can be nested, creating scopes within scopes:

Plus, the root scope can be easily referenced within the @scope rule:

The @scope at-rule also introduces a new proximity dimension to CSS specificity resolution. In traditional CSS, when two selectors match the same element, the selector with the higher specificity wins. With @scope, when two elements have equal specificity, the one whose scope root is closer to the matched element wins. This eliminates the need to override parent styles by manually increasing an element’s specificity, since inner components naturally supersede outer element styles.

Conclusion #

Utility-first CSS frameworks, such as Tailwind, work well for prototyping and smaller projects. Their benefits quickly diminish, however, when used in larger projects involving more than a couple of developers.

Front-end development has become increasingly overcomplicated in the last few years, and CSS is no exception. While the @scope rule isn’t a cure-all, it can reduce the need for complex tooling. When used in place of, or alongside strategic class naming, @scope can make it easier and more fun to write maintainable CSS.

Your skip link targets don't need tabindex=-1 to work properly

2026-03-04T19:44:49Z

Your skip link targets don't need tabindex=-1 to work properly

posted on 04.03.2026

Recently, someone posted on LinkedIn that skip links are often broken because their target elements are missing a tabindex attribute. I was really surprised to see that because I thought that was an issue of the past. That's why I decided to test it.

The original problem

The author explained in their post that when you use a keyboard and press Enter on a skip link, the page scrolls down to the target, but focus stays on the link. When you press Tab, focus doesn't jump to the target; it jumps to the next focusable element after the skip link. He calls that a “phantom jump”.


<a href="#content">Jump to content</a>
<nav>
    <!-- A bunch of links -->
</nav>
<main id="content">
</main>

They explain that the problem is that the main element is not an interactive element and thus cannot be focused. That's why their proposed solution is adding a tabindex attribute.

<a href="#content">Jump to content</a>
<nav>
    <!-- A bunch of links -->
</nav>
<main id="content" tabindex="-1">
</main>

What the author describes was a problem… a long time ago. As Sara Higley reconstructs, Firefox was the first browser to fix it in 2013, followed by Internet Explorer, and finally Chrome in 2016. I don't know about Safari, but it was long enough ago that I can't remember anymore.

The solution

The fix browsers implemented is a feature called “sequential focus navigation starting point (SFNSP)”. Rob Dodson defines it well in his post “Remove headaches from focus management”.

The 'sequential focus navigation starting point' feature defines where we start to search for focusable elements for sequential focus navigation (Tab or Shift-Tab) when there is no focused area.

Prior to that, there were only two possible starting points.

If there is no other starting point, it's the document or, if available, the currently active dialog.
If an element is focused, it's also the starting point

With SFNSP, there can now be more starting points.

Navigating to a page fragment, e.g., by clicking a skip link, sets the starting point.
Clicking any element on the page, interactive or not, sets the starting point.
If an element that was the starting point is removed from the DOM, its parent becomes the starting point.

That was a necessary addition because it fixed several fundamental accessibility issues. As mentioned, it's been available in all major browsers for many years and works well. Nevertheless, I want to back that with actual tests. In this blog post, I want to focus only on the scenario where navigating to a page fragment sets the starting point.

Testing

For my test, I created a simple page. My goal was to confirm three outcomes:

After pressing Enter on the skip link, then pressing Tab, I would land on the “Content” button using a keyboard.
After pressing Enter on the skip link, then pressing Tab, I would land on the “Content” button using a keyboard with a screen reader.
After pressing Enter on the skip link, I would use the virtual cursor with a screen reader to move to the next element and land on the “Content” button or the h2.

<header>
  <a href="#content">Skip</a>
  <button>1</button>
  <button>2</button>
  <button>3</button>
  <button>4</button>
  <button>5</button>
</header>

<main id="content">
  <h2>Main content</h2>
  <button>Content</button>
</main>

I was able to confirm all three scenarios in all tested browsers.

Keyboard, Firefox 157, macOS 26.3
Keyboard, Chrome 145, macOS 26.3
Keyboard, Safari, macOS 26.3
Keyboard Windows 11, Chrome 145
Keyboard Windows 11, Edge 145
Keyboard, Windows 11, Firefox 147
Tab key / Virtual cursor, VoiceOver, macOS 26.3, Safari
Tab key / Virtual cursor, JAWS 2026, Windows 11, Chrome 145
Tab key / Virtual cursor, NVDA 2025.3.3, Windows 11, Firefox 147
Tab key / Virtual cursor, NVDA 2025.3.3, Windows 11, Chrome145
Tab key / Virtual cursor, Narrator, Windows 11, Edge/Chrome 145
Talkback, Android 16, Chrome 145

Styling

Navigating to a non-interactive page fragment doesn't reveal the element's focus styling, because it's not focused, it's only a starting point. We still have options to style a targeted element in CSS.

:target {
  outline: 2px solid #ccc;
}

Conclusion

Unless I'm missing something (please let me know), I would say it's safe to remove tabindex="-1" from your skip link targets.
I didn't link to the post on LinkedIn because I didn't want to callout the author. It's not about them being wrong, but about the fact that browsers and screen readers receive frequent updates. That's why it's important that you reevaluate the best practices you've been following for years every now and then and check if they still apply. Often, things that were true a couple of years ago aren't true today.

Claude is an Electron App because we’ve lost native

2026-03-04T18:58:07Z

Claude is an Electron App because we’ve lost native

In “Why is Claude an Electron App?” Drew Breunig wonders:

Claude spent $20k on an agent swarm implementing (kinda) a C-compiler in Rust, but desktop Claude is an Electron app.

If code is free, why aren’t all apps native?

And then argues that the answer is that LLMs are not good enough yet. They can do 90% of the work, so there’s still a substantial amount of manual polish, and thus, increased costs.

But I think that’s not the real reason. The real reason is: native has nothing to offer.

API-wise, native apps lost to web apps a long time ago. Native APIs are terrible to use, and OS vendors use everything in their power to make you not want to develop native apps for their platform. That explains the rise of Electron before LLM times, but it’s also a problem that LLMs solve now: if that was a real barrier to developing native apps, it doesn’t exist anymore.

Then there’re looks and consistency. Some time ago, maybe in the late 90s and 2000s, native was ahead. It used to look good, it was consistent, and it all actually worked: the more apps used native look and feel, the better user experience was across apps (which we used to call programs).

These days, though, native is as bad as the web, if not worse. Consistency is basically out the window. Anything can look like anything, buttons have no borders, contrast doesn’t exist, and neither do conventions. Apple, for example, seems to place traffic lights and corner radius by vibes rather than by any measurable guidelines.

Maybe the server should round the corners?

Looks could be good, but they also can be bad, and then you are stuck with platform-consistent, but generally bad UI (Liquid Glass ahem). It changes too often, too: the app you made today will look out of place next year, when Apple decides to change look and feel yet again. There’s no native look anymore.

Computer UIs also degrade over time

Theoretically, native apps can integrate with OS on a deeper level. This sounds nice, but what does that mean in practice? There are almost no good interoperable file formats; everything is locked inside individual apps, most services moved to the web, and OSes dropped the ball for making a good shared baseline. You can integrate with OS-provided calendar, but you can’t do it with web calendar. Well, you can, of course, but it’s easier on the web; native doesn’t help with it at all.

Web pages only lead to more web pages

Finally, the last hope of people longing for native is performance. They feel that native apps will be faster. Well, they can, but it doesn’t mean they will. Web apps can be faster, too, but in practice, nobody cares. There’s no technical reason why Slack needs to load 80 MiB just to show 10 channel names and 3 messages on a screen. The web is not the problem here! It’s a choice to be bad. What makes you think it’ll be different once the company decides to move to native?

Don’t get me wrong: writing this brings me no joy. I don’t think web is a solution either. I just remember good times when native did a better-than-average job, and we were all better for using it, and it saddens me that these times have passed.

I just don’t think that kidding ourselves that the only problem with software is Electron and it all will be butterflies and unicorns once we rewrite Slack in SwiftUI is not productive. The real problem is a lack of care. And the slop; you can build it with any stack.

Your car’s tire sensors could be used to track you

2026-03-02T07:21:01Z

Your car’s tire sensors could be used to track you

Researchers at IMDEA Networks show standard tire sensors can expose drivers’ movements, raising privacy concerns

25 February 2026

Researchers at IMDEA Networks Institute, together with European partners, have found that tire pressure sensors in modern cars can unintentionally expose drivers to tracking. Over a ten-week study, they collected signals from more than 20,000 vehicles, revealing a hidden privacy risk and highlighting the need for stronger security measures in future vehicle sensor systems.

Most modern cars are equipped with a Tire Pressure Monitoring System (TPMS), mandatory since the late 2000s in many countries for their contribution to road safety. This system uses small sensors in each wheel to monitor tire pressure and sends wireless signals to the car’s computer to alert the driver if a tire is underinflated.

However, the researchers found that these tire sensors also send a unique ID number in clear, unencrypted wireless signals, meaning that anyone nearby with a simple radio receiver can capture the signal, and recognize the same car again later. Most vehicle tracking today uses cameras that need clear visibility and line-of-sight to a car. TPMS tracking is different: tire sensors automatically send radio signals that pass through walls and vehicles, allowing small hidden wireless receivers to capture them without being seen. Because each sensor broadcasts a fixed unique ID, the same car can be recognized repeatedly without reading a license plate. This makes TPMS-based tracking cheaper, harder to detect, and more difficult to avoid than camera-based surveillance, and therefore a stronger privacy threat.

To test how serious this risk is, the team built a network of low-cost radio receivers, located near roads and parking areas. The necessary equipment costs only $100 per receiver. In total, they collected more than six million tire sensor messages from over 20,000 cars.

“Our results show that these tire sensor signals can be used to follow vehicles and learn their movement patterns,” says Domenico Giustiniano, Research Professor at IMDEA Networks Institute. “This means a network of inexpensive wireless receivers could quietly monitor the patterns of cars in real-world environments. Such information could reveal daily routines, such as work arrival times or travel habits.”

The researchers also developed methods to match signals from the four tires of a car. This allowed them to increase the accuracy of specific vehicles arriving, living, or following regular schedules. The study showed that signals can be captured from moving cars and from distances greater than 50 meters, even when sensors are inside buildings or hidden locations. This makes covert tracking technically feasible.

Additionally, TPMS signals include tire pressure readings, which may reveal the type of vehicle or whether a car or truck is carrying heavy loads. This could allow more advanced forms of surveillance.

“As vehicles become increasingly connected, even safety-oriented sensors like TPMS should be designed with security in mind, since data that appears passive and harmless can become a powerful identifier when collected at scale,” highlights Dr. Alessio Scalingi, former PhD student at IMDEA Networks and now Assistant Professor at UC3M, Madrid.

Despite these risks, current vehicle cybersecurity regulations do not yet specifically address TPMS security. The researchers warn that without encryption or authentication, tire sensors remain an easy target for passive surveillance.

“TPMS was designed for safety, not security,” adds Dr. Yago Lizarribar, former PhD student at IMDEA Networks during the research study, and now Researcher at Armasuisse, Switzerland. “Our findings show the need for manufacturers and regulators to improve protection in future vehicle sensor systems.”

Therefore, the research team urges the manufacturers and policymakers to strengthen cybersecurity in future cars, so that safety systems do not become tools for tracking the population.

The paper, titled “Can’t Hide Your Stride: Inferring Car Movement Patterns from Passive TPMS Measurements,” has been accepted for publication at IEEE WONS 2026.

Source(s): IMDEA Networks Institute

Please, please, please stop using passkeys for encrypting user data

2026-02-27T19:10:04Z

Why am I writing this today? Because I am deeply concerned about users losing their most sacred data.

Over the past year or two, I’ve seen many organizations, large and small, implement passkeys (which is great, thank you!) and use the PRF (Pseudo-Random Function) extension to derive keys to protect user data, typically to support end-to-end encryption (including backups). I’ve also seen a number of influential folks and organizations promote the use of PRF for encrypting data.

The primary use cases I’ve seen implemented or promoted so far include:

encrypting message backups (including images and videos)
end-to-end encryption
encrypting documents and other files
encrypting and unlocking crypto wallets
credential manager unlocking
local account sign in

Why is this a problem?

When you overload a credential used for authentication by also using it for encryption, the “blast radius” for losing that credential becomes immeasurably larger.

Imagine a user named Erika. They are asked to set up encrypted backups in their favorite messaging app because they don’t want to lose their messages and photos, especially those of loved ones who are no longer here. Erika is prompted to use their passkey to enable these backups.

There is nothing in the UI that emphasizes that these backups are now tightly coupled to their passkey. Even if there were explanatory text, Erika, like most users, doesn’t typically read through every dialog box, and they certainly can’t be expected to remember this technical detail a year from now.

A few months pass, and Erika decides to clean up their credential manager. They don’t remember why they had a specific passkey for a messaging app and deletes it.

Fast forward a year: they get a new phone and set up the messaging app. They aren’t prompted to use a passkey because one no longer exists in their credential manager. Instead, they use phone number verification to recover their account. They are then guided through the “restore backup” flow and prompted for their passkey.

Since they no longer have it, they are informed that they cannot access their backed up data. Goodbye, memories.

Here’s a few examples of what a user sees when they delete a passkey:

Example: deleting a passkey in Apple Passwords

Example: deleting a passkey in Google Password Manager

Example: deleting a passkey in Bitwarden

How is a user supposed to understand that they are potentially blowing away photos of deceased relatives, an encrypted property deed, or their digital currency?

We cannot, and should not, expect users to know this.

At this point, you may be asking why PRF is part of WebAuthn in the first place. There are some very legitimate and more durable uses of PRF in WebAuthn, specifically supporting credential managers and operating systems.

A passkey with PRF can make unlocking your credential manager (where all of your other passkeys and credentials are stored) much faster and more secure. Credential managers have robust mechanisms to protect your vault data with multiple methods, such as master passwords, per-device keys, recovery keys, and social recovery keys. Losing access to a passkey used to unlock your credential manager rarely leads to complete loss of your vault data.

PRF is already implemented in WebAuthn Clients and Credential Managers, so the cat is out of the bag. My asks:

To the wider identity industry: please stop promoting and using passkeys to encrypt user data. I’m begging you. Let them be great, phishing-resistant authentication credentials.
To credential managers: please prioritize adding warnings for users when they delete a passkey with PRF (and displaying the RP’s info page when available)
To sites and services using passkeys: if you still need to use PRF knowing these concerns, please:
1. add an informational page to your support site explaining how you’re using passkeys for more than authentication
2. list that page URL in the Well-Known URL for Relying Party Passkey Endpoints (prfUsageDetails)
3. provide as much warning as possible up front to users when enabling it

Thanks for reading! 🙏🏻

(and thanks to Matthew Miller for reviewing and providing feedback on this post)

How "Liquid Design" Broke the iPhone and Forced Apple’s Great Reset

2026-02-25T10:57:40Z

The launch of iOS 26 was heralded as a “Spatial Awakening.” Apple’s design team, led by the high-concept vision of Alan Dye, promised to bridge the gap between our physical reality and our digital tools through a language called Liquid Glass.

It was marketed as an interface that breathes—a hyper-dynamic, translucent, and motion-heavy UI that used real-time refraction to make your apps look like they were floating in a physical pane of crystal.

But six months into the lifecycle of iOS 26, the verdict is in from power users, developers, and accessibility advocates alike: Liquid Glass is a usability catastrophe.

It is the most arrogant piece of software Apple has ever shipped—a system that demands you admire its beauty while it actively hinders your ability to use your phone. It is a house of mirrors built on the bones of a once-efficient operating system, and its failure has forced the most radical leadership shakeup in Cupertino since the departure of Jony Ive.

The Death of Legibility: A Low-Vision Nightmare

The most fundamental job of a user interface is to be readable. Liquid Glass fails this at a level that would get a first-year design student expelled. By prioritizing “refractive realism,” Apple replaced solid containers with semi-transparent, light-bending “panes.”

The problem is that the real world is messy. When your notification center is refracting a high-detail photo of a forest or a bright sunset, the text “loses the fight” for your attention. This has created a Contrast Crisis.

Apple’s AI tries to dynamically shift text color based on the background, but it frequently fails on busy images, leading to a “muddy” effect where text becomes functionally invisible.

For users with visual impairments—or even just tired eyes—the constant shifting of translucent layers creates a barrier to entry. We are now in an era where “Reduce Transparency” isn’t just an accessibility option; it is a mandatory setting for anyone who wants to read their messages in direct sunlight.

The Performance Penalty: GPU-Driven Ego

Liquid Glass treats the iPhone UI like a AAA video game. Every time you swipe, the system calculates real-time ray-traced reflections and “chromatic aberration” on the edges of your app icons. It is a staggering waste of compute power that has introduced a level of friction we haven’t seen in years.

Even on the powerhouse iPhone 17 Pro, the interface suffers from “micro-stutters.” The moment the GPU throttles due to heat or background tasks, the “liquid” illusion breaks, leaving the user with a laggy, disconnected experience.

Furthermore, the Battery Tax has been devastating. Data suggests a 10–15% reduction in real-world screen-on time because the phone is effectively running a physics engine just to show you your calendar. We are using 3-nanometer chips—miracles of human engineering—to render “shimmers” on icons that were perfectly functional as flat squares.

The Uncanny Valley of Physics

In 2013, iOS 7 killed skeuomorphism because we no longer needed digital objects to look like leather or felt. Liquid Glass is a return to a different kind of realism—Digital Skeuomorphism. Apple tried to make us believe we are touching floating panes of glass, but when the physics don’t match the tactile reality, it falls into an uncanny valley.

The “wobbly” sliders and “floaty” icons lack the weight and intent that made the original iPhone feel like a precision tool. When you move a slider in the Control Center and it stretches like digital gelatin, it feels flimsy and unserious.

It is “Barbie-fied” tech—glossy, plastic, and fundamentally performative. As critic John Gruber noted, Apple spent billions making the thinnest hardware in the world only to put a UI on it that looks like a Windows Vista fever dream.

The Alan Dye Departure and the Internal Revolt

The departure of Alan Dye to Meta in late 2025 was the ultimate confirmation that the “Liquid” experiment had reached its dead end.

Reports from within Apple Park suggest that Dye’s team frequently brushed aside warnings from accessibility and performance engineers to maintain the “purity” of the aesthetic.

When Dye left, he left behind a UI that looked stunning in a 4K keynote presentation but felt “restless and needy” in the hands of a real person. The fact that Apple had to rush out iOS 26.2 with an “Opaque Mode” was a silent admission of failure.

Apple doesn’t add “undo” sliders to its core vision unless that vision is actively breaking the user experience.

The Rescue Mission: Stephen Lemay and “Solid Design”

The keys to the iPhone’s soul have now been handed to Stephen Lemay, a 26-year veteran of the original Aqua design era. Lemay’s mission for iOS 27 is reportedly a “Snow Leopard” style intervention—a radical “taming” of the interface focused on three pillars:

The Return of Opacity: Moving away from high-refraction backgrounds to solid, high-contrast containers that prioritize legibility.
GPU Idle Recovery: Targeting a 40% reduction in baseline GPU activity by stripping away real-time physics from static screens.
Edge Definition: Reintroducing high-contrast borders and “Physical Depth” to ensure the eye never has to “hunt” for a button.

The shift under Lemay is philosophical. Under Dye, Apple design became performative—it wanted you to look at the glass. Under Lemay, the goal is for the design to disappear again.

Conclusion: Form Follows Nothing

Liquid Glass failed because it forgot why people buy iPhones. We don’t buy them to look at a digital art gallery; we buy them to get things done. By turning the interface into an obstacle course of reflections and blurs, Apple traded utility for vanity.

It was a beautiful mistake, a technical marvel that served no master other than the ego of the designers who built it.

As we look toward the “Solid Design” of iOS 27, Liquid Glass will likely be remembered alongside the “butterfly keyboard”—a time when Apple got so caught up in how they could build something, they forgot to ask if they should.

Noah Davis is an accomplished UX strategist with a knack for blending innovative design with business strategy. With over a decade of experience, he excels at crafting user-centered solutions that drive engagement and achieve measurable results.

Precompressed HTML at the Edge: Eleventy Meets Cloudflare Workers

2026-02-25T10:50:42Z

Introduction

Jump to section titled: Introduction

In 2025, I wrote a series of web performance optimisation blog posts focussing on some of the key fundamental's of Frontend Web Performance:

Caching

Jump to section titled: Caching

Asset fingerprinting and the preload response header in 11ty

Summary

The blog post describes how the I enhanced web performance on my 11ty-built site by combining asset fingerprinting with the HTTP preload hint.

It explains that preload tells the browser to fetch critical resources earlier, but hashed filenames make this difficult to manage manually.

The solution was to generate preload Link headers automatically during the 11ty build. A custom script locates the fingerprinted CSS file and injects the correct preload header into the Cloudflare Pages _headers file.

This speeds up CSS delivery, removes the need for manual updates, and allows the use of long-lived Cache-Control header values such as max-age=31536000 and immutable.

Compression

Jump to section titled: Compression

Cranking Brotli up to 11 with Cloudflare Pro and 11ty.

Summary

The blog post explains how I improved the performance of my 11ty-powered blog after migrating to Cloudflare Pages by using Brotli compression at the highest level (11) for static assets. I also describes the difference between Brotli and gzip, outline how Cloudflare’s Pro plan typically applies a moderate Brotli level (4), and then show how to pre-compress JavaScript files to Brotli level 11. Lastly, serve them correctly both locally and via Cloudflare, and configure Cloudflare’s compression rules so that all assets benefit from the stronger compression to reduce file sizes and improve load performance.

Concatenation

Jump to section titled: Concatenation

Using an 11ty Shortcode to craft a custom CSS pipeline

Summary

While not strictly about concatenation, it covers related ideas. The post explains how I built a custom CSS pipeline for my 11ty site using a bespoke short code rather than the default bundle plugin.

It details how I preserved local live reload, added content-based fingerprinting for long-term caching, minified CSS with clean-css package, enabled Brotli compression, and used disk and memory caching to prevent unnecessary work.

The build also generates hashed filenames and matching HTML link tags, ensuring production serves fully optimised, cache friendly CSS automatically.

More compression

Jump to section titled: More compression

In this blog post, I’m going to take the compression a little further. I already have CSS and JavaScript Brotli compressed to the highest level (11) and served from Cloudflare Pages. But what about the third and final core technology of the web? Arguably the most important too… The HTML. In this post, I will look at how to compress your HTML to 11 during the 11ty build phase, and what modern technologies you need in order to make this work (it’s not as straightforward as I thought!)

Why HTML Brotli matters?

Jump to section titled: Why HTML Brotli matters?

Before we dive into the details, let’s discuss why Brotli compression is important for HTML. Well, to summarise Brotli compression in one sentence:

Brotli compression reduces file size by intelligently identifying repeated patterns in data and encoding them more efficiently using a combination of modern compression techniques.

This is fantastic for anything with repeating patterns as the bytes saved over the network can be huge! The great thing about HTML is that it has a tonne of repeating patterns (e.g. Markup)! This reduction in file size could potentially equate to:

Improved Web Performance

Jump to section titled: Improved Web Performance

Every kilobyte saved here multiplies across your traffic volume.

At scale, cost savings add up

Jump to section titled: At scale, cost savings add up

Let’s assume you are serving a high traffic website, say the BBC, Google, or GOV.UK. Imagine how much bandwidth could be saved by simply compressing your HTML. Any percentage saving on millions of requests per day is going to mean:

Less bandwidth
Lower CDN egress
Lower cloud costs
Lower carbon footprint

This is a win both commercially and environmentally!

Improved performance on slow and unstable mobile networks

Jump to section titled: Improved performance on slow and unstable mobile networks

Brotli 11 improves the web for users where they need it the most:

3G connectivity
High latency rural connections
Congested public networks
International access

HTML blocks everything else. If you shrink it aggressively, you unblock the page faster, meaning users get a better experience.

This is a real-world performance gain.

It indirectly improves Core Web Vitals

Jump to section titled: It indirectly improves Core Web Vitals

Smaller HTML means:

Faster DOM construction
Earlier CSS discovery
Earlier JS discovery
Reduced main thread idle gaps

This is especially important for server rendered pages or hybrid Server-side Rendered apps.

Compression cost is paid once for static assets

Jump to section titled: Compression cost is paid once for static assets

Yes, level 11 compression is expensive to compute. But this cost is paid back over time. You pay for the CPU time once. Users benefit forever assuming:

the HTML is static and cacheable at the Content Delivery Network (CDN) using long-life caching headers
you automate and pre-compress the HTML at build time

Compression Size Examples v1

Jump to section titled: Compression Size Examples v1

Let’s have a look at a huge HTML page on the web. My go-to for this is either the W3C HTML5 Specification page OR NASA’s Astronomy Picture of the Day Archive.

Rather than choose, let’s just compress both!

W3C HTML5 Specification (Single Page)

Jump to section titled: W3C HTML5 Specification (Single Page)

That’s an 88 percent reduction in bytes over the network when compressing the HTML with Brotli 11. Not bad for something that takes just over 10-seconds to run.

And yes, that’s 4.7 MB of HTML alone. It’s an absolute beast of a page.

For perspective, that would take around 12 to 15 minutes to download on a 56k modem in the late 90s. Just for the HTML. I might be showing my age here 😭

Nasa’s Astronomy Picture of the Day Archive

Jump to section titled: Nasa’s Astronomy Picture of the Day Archive

We’ve taken it from roughly a third of a megabyte down to just 53 KB. That is a pretty substantial reduction!

This means faster page loads, lower data usage, and a much smoother experience for anyone on a limited data plan or dealing with patchy connections. A very positive impact, right where it matters most for users.

How is this different from my other compression posts?

Jump to section titled: How is this different from my other compression posts?

So how is this different from the Brotli compression I have mentioned in the previous blog posts?

In Cranking Brotli up to 11 with Cloudflare Pro and 11ty I used a combination of:

Brotli CLI (e.g.brew install brotli)
bash scripts (compress.sh, compress-directory.sh)

In this post, I override the Cloudflare Dashboard's "Compression Rules” (which dynamically compresses HTML at Brotli level 4). The CDN is compressing the HTML on-the-fly when the user’s browser requests it.

What this blog post describes is pre-compression to Brotli 11 at 11ty build time. To do this the workflow is:

Apply Brotli level 11 pre-compression to HTML during the 11ty build on Cloudflare Pages.
_helpers/html-compression.js runs after the site is written to _site.
Each HTML file gets a matching .br file
Use the built-in Node zlib module, so no manual setup, CLI tools, scripts, Cloudflare configuration, or extra dependencies are required.
Take advantage of Cloudflare Pages Functions, which run on Cloudflare Workers. This is a great opportunity to use a modern, fast evolving platform that opens the door to powerful edge capabilities.

What’s the point?

Jump to section titled: What’s the point?

Well, that’s a great question. As some readers may know by default Cloudflare compresses HTML at compression level 4. Now, if we compare this level to the compression level 11 above, let’s have a look at the difference:

URL: https://apod.nasa.gov/apod/archivepix.html
Uncompressed size: 314 KB
Brotli (Level 4): 66 KB (79%)
Compression Time (Level 4): 0.011 seconds
Brotli (Level 11): 53 KB (83% saving)
Brotli (Level 11): 0.743 seconds

It’s worth noting that I used Paul Calvano's fantastic Compression Tester Tool, to help with this basic analysis.

What you will likely notice is that even for large HTML files the size difference between compression level 4 and compression level 11 isn’t huge, only 12 KB in the W3C HTML5 Specification example. The real difference comes in computation time. Level 4 0.149 seconds verses 11.717 seconds! That’s a 7764% increase in time between Level 4 and Level 11! Although this is an extreme example, you can probably see why Level 11 isn’t used by Cloudflare for on-the-fly compression of HTML assets. Level 4 gives a good balence between file compression versus compression speed. I’m betting countless smart people were involved in the analysis of using Level 4 by default! When you are a company that is literally serving billions of requests per second, this decision really makes a difference in terms of processing power infrastructure and power usage!

Thankfully, the way that I have implemented level 11 compression on my blog, processing time doesn’t really matter. All the HTML is being compressed at 11ty build time. As I said above, the cost of this additional CPU time is paid back over time by users getting a better experience (even if only slightly). Furthermore, remember there’s a slight reduction in storage required on the CDN. From my perspective, if it is low effort after setup, it feels like the right move to implement it.

Problems

Jump to section titled: Problems

As I found out during implementation it isn’t just as simple as compressing the HTML to 11 and setting a static Content-Encoding header for HTML in the _headers file (trust me, I tried it!)

Problem 1: URL Path vs Actual File Path Mismatch

Jump to section titled: Problem 1: URL Path vs Actual File Path Mismatch

When serving static assets like CSS, JS, or images, there is usually a simple one-to-one relationship between the URL and the file on disk. A request to /css/site.css maps directly to _site/css/site.css. No extra logic is required because the URL path matches the file path exactly. I had no idea, but I soon found out that HTML pages behave differently. A request to / or /blog/post/ does not correspond to a literal file at that path. Instead, the server applies a convention and serves index.html inside that directory. So /blog/post/ actually maps to blog/post/index.html on disk. This mapping happens automatically when Cloudflare serves uncompressed HTML through its very efficient static asset layer.

The problem appears when serving pre-compressed Brotli files. You cannot simply request the same URL and expect the .br file to resolve. Instead, the Cloudflare Function must manually translate the directory style URL into the real file path before appending .br.

For example, / becomes /index.html.br, /blog/post/ becomes /blog/post/index.html.br, and /404.html becomes /404.html.br.

In short, HTML requires explicit path translation because the browser sees a directory style URL while the actual file stored on disk is index.html. The Cloudflare Function must bridge that gap to correctly serve the Brotli 11 compressed version, rather than the uncompressed HTML version.

It actually makes sense now that I think about it, I’ve always just taken the automatic appending of index.html to a URL Path for granted! The fact that as a user on the web doesn’t even have to think about that small detail, shows how well it works! As Dieter Rams once said:

Good design is as little design as possible.

Problem 2: A page full of Wingdings

Jump to section titled: Problem 2: A page full of Wingdings

I’m showing my age again, but for readers who don’t remember early versions of Windows (e.g. 3.1), it came bundled with a font called Wingdings. This True Type font contains many largely recognised shapes and gestures as well as some recognised world symbols.

Wingdings were an early symbol font that experimented with pictographic digital symbols, that would later lead on to ASCII emoticons like :-) & ¯\_(ツ)_/¯, which in turn would progress to the modern world of Emoji’s!

Essentially, what was happening the Cloudflare server was serving raw Brotli compressed HTML files to the browser, expecting it to understand what these (now binary, not text) files were, and how to read and understand them. I was essentially serving the HTML without the following headers:

Content-Type: text/html; charset=UTF-8
Content-Encoding: br
Vary: Accept-Encoding

Here’s a brief explanation of these headers:

Content-Encoding: br: This is telling the browser “What I’m sending you is a Brotli compressed file, you are going to need to decode it before you understand it”.
Content-Type: text/html; charset=UTF-8: This tells the browser what character set ('charset') it should use after decompression, this is essential as this is key to the browser parsing the HTML correctly.
Vary: Accept-Encoding only affects caching (e.g. Content Delivery Networks). It’s basically saying to the cache to store separate versions of this file depending on the Accept-Encoding header.

The result of the above gave me a homepage that looked like the image below (interesting but not exactly readable!):

My Approach

Jump to section titled: My Approach

Step 1: Build-time compression

Jump to section titled: Step 1: Build-time compression

After the site is generated, it moves into a final preparation stage before going live.

During this stage, the system goes through all the finished HTML pages and creates highly compressed versions of them. These compressed files sit alongside the originals and are ready to be served immediately.

Because this happens as part of the 11ty build process, every release automatically includes freshly optimised files. This means the live site can deliver pages faster, with smaller file sizes and no need to compress anything on the fly (e.g. what Cloudflare does with its HTML compression to Brotli level 4).

The result is better performance for users, with no extra overhead once the site is hosted and running on Cloudflare pages.

Step 2: Cloudflare Pages Function for content negotiation

Jump to section titled: Step 2: Cloudflare Pages Function for content negotiation

When someone visits a page on the site, a lightweight Cloudflare Function (via a Cloudflare Worker) checks whether a users browser supports modern compression.

If it does, the system serves the Brotli 11 pre compressed version of the page. This keeps file sizes small and pages loading quickly.

If the browser does not support this compression, or if a compressed version is not available, the system simply serves the standard uncompressed version of the HTML instead.

No extra processing happens at this stage. The edge layer (Cloudflare Function + Worker) is only deciding which version of the already prepared files to send. All optimisation work has already been done earlier in the 11ty build process.

The final result is fast delivery, efficient bandwidth use, and a simple, reliable build setup. Everyone wins!

Step 3: The Eleventy build uses Node.js zlib, for seamless integration

Jump to section titled: Step 3: The Eleventy build uses Node.js zlib, for seamless integration

As mentioned earlier, this Brotli implementation differs from others I have used. Instead of relying on bash scripts such as compress.sh or compress-directory.sh, it uses Node.js’s built in zlib module. Because zlib is part of Node.js core, it is stable, well maintained, and requires no external dependencies. It has been available since the earliest Node.js releases, so it is a sensible default choice. I may even revisit the other build process in future and consider replacing the remaining bash scripts with a fully Node.js based approach.

Implementation

Jump to section titled: Implementation

Next, let’s stop the waffling and get onto the actual implementation, I assume that’s what readers are here for after all!

Core compression utility

Jump to section titled: Core compression utility

Here is the main compression file that is used to compress the HTML to Brotli 11:



import { brotliCompressSync } from 'zlib';


export const BROTLI_LEVEL = 11;


export function brotliCompress(input, level = BROTLI_LEVEL) {
	const buffer = Buffer.isBuffer(input) ? input : Buffer.from(input);
	return brotliCompressSync(buffer, { level });
}

I appreciate that not everyone prefers heavily commented code, so there is also a version in this Gist with minimal comments and improved readability.

HTML compression post-build

Jump to section titled: HTML compression post-build

The post-build HTML compression file:



import fs from 'fs';
import path from 'path';

import { brotliCompress, BROTLI_LEVEL } from './compression.js';


function findHtmlFiles(dir, acc = []) {
	const entries = fs.readdirSync(dir, { withFileTypes: true });
	for (const entry of entries) {
		const fullPath = path.join(dir, entry.name);
		const relPath = path.relative('./_site', fullPath);
		if (entry.isDirectory()) {
			findHtmlFiles(fullPath, acc);
		} else if (entry.isFile() && entry.name.endsWith('.html')) {
			acc.push(relPath);
		}
	}
	return acc;
}


export function compressHtmlFiles() {
	const startTime = Date.now();
	console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
	console.log('🚀 PRODUCTION POSTBUILD: Starting HTML Brotli compression');
	console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');

	const siteDir = path.join('./_site');
	if (!fs.existsSync(siteDir)) {
		console.log('⚠️  _site directory not found, skipping HTML compression');
		return;
	}

	const htmlFiles = findHtmlFiles(siteDir);
	if (htmlFiles.length === 0) {
		console.log('⚠️  No HTML files found, skipping compression');
		return;
	}

	let compressedCount = 0;
	let skippedCount = 0;
	let totalOriginal = 0;
	let totalCompressed = 0;
	const errors = [];

	for (const relPath of htmlFiles) {
		const inputPath = path.join(siteDir, relPath);
		const outputPath = `${inputPath}.br`;

		try {
			
			if (fs.existsSync(outputPath)) {
				const inputStats = fs.statSync(inputPath);
				const outputStats = fs.statSync(outputPath);
				if (outputStats.mtime >= inputStats.mtime) {
					skippedCount++;
					continue;
				}
			}

			const fileContent = fs.readFileSync(inputPath);
			const originalSize = fileContent.length;

			const brotliBuffer = brotliCompress(fileContent, BROTLI_LEVEL);
			const compressedSize = brotliBuffer.length;

			fs.writeFileSync(outputPath, brotliBuffer);
			compressedCount++;
			totalOriginal += originalSize;
			totalCompressed += compressedSize;
		} catch (error) {
			errors.push(`❌ ${relPath}: ${error.message}`);
		}
	}

	const totalTime = Date.now() - startTime;
	const savedPercent = totalOriginal > 0 ? ((1 - totalCompressed / totalOriginal) * 100).toFixed(1) : '0';

	console.log(`✅ Compressed ${compressedCount} HTML file(s) (${skippedCount} skipped, up-to-date)`);
	if (compressedCount > 0) {
		console.log(
			`   ${(totalOriginal / 1024).toFixed(1)} KB → ${(totalCompressed / 1024).toFixed(1)} KB (${savedPercent}% smaller)`
		);
	}
	console.log(`   Finished in ${totalTime}ms (${(totalTime / 1000).toFixed(2)}s)`);

	if (errors.length > 0) {
		console.error('\nErrors:');
		errors.forEach(e => console.error(`  ${e}`));
	}

	console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
}

A version with minimal comments and much improved readability is available in a Gist here.

Cloudflare Pages Function for content negotiation

Jump to section titled: Cloudflare Pages Function for content negotiation

Here we have the Cloudflare Function file that runs in the Cloudflare Worker. It is located in the /functions directory in the root of the repository so it can be detected when Cloudflare Pages builds.



async function handleHtmlWithBrotli(request, env) {
	const url = new URL(request.url);
	const pathname = url.pathname;

	
	
	
	
	const isHtmlDocument = pathname === '/' || pathname.endsWith('/') || pathname === '/404.html';

	if (!isHtmlDocument) {
		return env.ASSETS.fetch(request);
	}

	const acceptsBrotli = request.headers.get('Accept-Encoding')?.includes('br') ?? false;

	if (!acceptsBrotli) {
		return env.ASSETS.fetch(request);
	}

	
	
	
	const brPath =
		pathname === '/' ? '/index.html.br' : pathname === '/404.html' ? '/404.html.br' : `${pathname}index.html.br`;

	const brUrl = new URL(brPath, url.origin);
	const brResponse = await env.ASSETS.fetch(brUrl.toString());

	if (!brResponse.ok) {
		return env.ASSETS.fetch(request);
	}

	
	
	const headers = new Headers(brResponse.headers);
	headers.set('Content-Encoding', 'br');
	headers.set('Content-Type', 'text/html; charset=UTF-8');
	headers.set('Vary', 'Accept-Encoding');
	
	headers.set('Cache-Control', 'public, max-age=31536000, no-transform');

	return new Response(brResponse.body, {
		status: brResponse.status,
		headers,
		
		
		encodeBody: 'manual',
	});
}

export const onRequestGet = async ({ request, env }) => {
	return handleHtmlWithBrotli(request, env);
};

export const onRequestHead = async ({ request, env }) => {
	return handleHtmlWithBrotli(request, env);
};

A version with minimal comments and much better readability is available in a Gist here.

Build lifecycle wiring

Jump to section titled: Build lifecycle wiring

This is the main build file I use to build my 11ty blog for production on Cloudflare Pages.



import env from '../_data/env.js';
import { clearCssBuildCache } from '../_helpers/css-manipulation.js';
import { generatePreloadHeaders } from '../_helpers/header-generator.js';
import { compressHtmlFiles } from '../_helpers/html-compression.js';
import { compressJavaScriptFiles } from '../_helpers/js-compression.js';
import { minifyJavaScriptFiles } from '../_helpers/js-minify.js';


export function registerBuildEvents(eleventyConfig) {
	if (env.isLocal) {
		return;
	}

	
	
	eleventyConfig.on('eleventy.before', () => {
		clearCssBuildCache();
	});

	eleventyConfig.on('eleventy.after', async () => {
		console.log('\n═══════════════════════════════════════════════════════════════════════════════');
		console.log('🚀 PRODUCTION POSTBUILD PHASE: Beginning postbuild operations');
		console.log('═══════════════════════════════════════════════════════════════════════════════\n');
		generatePreloadHeaders();
		await minifyJavaScriptFiles();
		compressJavaScriptFiles();
		compressHtmlFiles();
		console.log('\n═══════════════════════════════════════════════════════════════════════════════');
		console.log('✅ PRODUCTION POSTBUILD PHASE: All postbuild operations completed');
		console.log('═══════════════════════════════════════════════════════════════════════════════\n');

		
		
		console.log('🔧 Forcing cleanup of HTTP connections and timers...');
		await new Promise(resolve => setTimeout(resolve, 100));

		try {
			const http = await import('http');
			const https = await import('https');

			if (http.globalAgent) {
				http.globalAgent.destroy();
				console.log('✅ Destroyed HTTP global agent');
			}
			if (https.globalAgent) {
				https.globalAgent.destroy();
				console.log('✅ Destroyed HTTPS global agent');
			}
		} catch (error) {
			console.warn('⚠️  Could not destroy HTTP agents:', error.message);
		}

		await new Promise(resolve => setTimeout(resolve, 50));
		console.log('✅ HTTP connection cleanup completed');

		
		
		if (env.isProd) {
			console.log('🏁 Production build complete - forcing process exit in 2 seconds...');
			setTimeout(() => {
				console.log('👋 Forcing clean exit now');
				process.exit(0);
			}, 2000);
		}
	});
}

A version with minimal comments and much improved readability is available in a Gist here.

Other Technical details worth mentioning

Jump to section titled: Other Technical details worth mentioning

Here are 4 other small technical details worth explaining as part of the implementation:

Why encodeBody: 'manual' is required

Jump to section titled: Why encodeBody: 'manual' is required

The content we send back to the user's browser is already compressed using Brotli. It is being loaded from a file that has already been compressed in advance.

If we don't tell Cloudflare to leave it alone, it may assume the content is not compressed and try to compress it again. Compressing something that is already compressed can cause problems and may result in a broken or unreadable output, plus it is a waste of CPU time and resources.

By setting encodeBody: ‘manual', we are telling Cloudflare to send the content exactly as it is, without changing it. This ensures the pre-compressed file is delivered correctly to the user's browser.

Why Vary: Accept-Encoding and Cache-Control: no-transform matter

Jump to section titled: Why Vary: Accept-Encoding and Cache-Control: no-transform matter

These 2 response headers are critical for making the pre-compression work. I've given details as to why that is below:

Vary: Accept-Encoding: This notifies browsers and CDNs that the response can change depending on what kind of compression the browser supports.

For example, if a browser says it supports Brotli, the cache will store and return the Brotli version for those requests. If another browser doesn't support Brotli, the cache will store and return a different version, such as an uncompressed version. This prevents the wrong format being sent to the wrong browser.

Cache-Control: no-transform: This informs caches and other systems between the server and the user's browser not to modify the content. It asserts that the response should not be compressed again or altered in any way.

Without this setting, a proxy might try to compress the content again, which can cause errors and waste processing power. With this header in place, the already compressed file is stored and delivered exactly as intended.

Incremental build optimisation (runtime check to skip unchanged files)

Jump to section titled: Incremental build optimisation (runtime check to skip unchanged files)

After the Eleventy build finishes, the post-build step recursively scans through the output folder, such as the _site directory, and checks each HTML file.

Before compressing a file, it checks whether a matching .br file already exists and whether it is up-to-date. If the .br file is the same age or newer than the original file, it is skipped. If the page is new or has been updated, a fresh compressed version is created.

This avoids pages that have not changed being needlessly recompressed, keeping the post build step fast. When only a few pages are updated, the need for recompression is limited.

Why we need a Cloudflare Function instead of just the `_headers` file for HTML Brotli?

Jump to section titled: Why we need a Cloudflare Function instead of just the _headers file for HTML Brotli?

1. `_headers` can only change headers, not the file itself

Jump to section titled: 1. _headers can only change headers, not the file itself

The _headers file lets us add or modify (but not remove) response headers. It doesn't control which file is actually sent back to the browser.

So, when someone visits / or /blog/post/, Cloudflare Pages automatically serves index.html or blog/post/index.html.

If we want to serve the Brotli version of the HTML, we need to send index.html.br instead. But the _headers file has no way to switch the file being served.

2. Setting the header alone is not enough

Jump to section titled: 2. Setting the header alone is not enough

Even if you add Content-Encoding: br in the static _headers file, the actual file being sent would still be the normal uncompressed version of the HTML.

The browser would see this Brotli header and try to decompress the response. Since the content being sent isn't compressed, it would simply fail and the page would break.

Results

Jump to section titled: Results

Looking at my build logs I can now see that compressing the HTML to Brotli 11 has had the following results:

📊 HTML Brotli 11 total savings: 123.4 KB (75.2% reduction)

That’s not too bad a saving considering how simple it is to set up and integrate into the 11ty build process! Thankfully, now that it’s done I can just “set it and forget it!”. Let's examine the results from the DevTools Network panel below:

Jump to section titled: DevTools Before

Jump to section titled: DevTools After

DevTools After Page Reload

Jump to section titled: DevTools After Page Reload

Curiously, when reloading the page with DevTools open, the HTTP status code changes from 200 to 304 and the Brotli compression in the Content-Encoding: br disappears. The reason for this is because either:

The reload request doesn’t contain an Accept-Encoding: br header so the Cloudflare Worker is simply returning the uncompressed version of the HTML file as is expected.
The 304 has no response body, so there’s nothing to show as being compressed.

Summary

Jump to section titled: Summary

By pre-compressing this blog’s HTML during the 11ty build phase, I have reduced the number of bytes sent on each page load. While the savings are small for a low traffic site like mine, at scale across millions of users and billions of requests per day, this approach could deliver meaningful bandwidth reductions and incremental performance improvements. This is especially true where network speed and stability vary globally.

Thank you for reading, I hope you found it useful. Edge Workers are an incredibly powerful technology. I genuinely look forward to using them again in the future.

I always open to feedback and corrections. If you spot anything that needs fixing or is incorrect, please let me know. I will credit you in the post changelog below.

Post changelog:

21/02/26: Initial post published.

Research is leadership, and code can help (but only in the right places)

2026-02-23T06:16:43Z

Open your favorite thought leadership page and scroll for a few seconds. Chances are, you’ll quickly find some screed about how the reality of software development is changing and we have to adapt to it.

Well, I have news for you. The reality of software development changed decades ago, and we still haven’t adapted. Today’s teams are using LLMs to push black-box code they don’t understand into production — but between plentiful open-source libraries and StackOverflow copy-pasting, they were already doing that.

Code hasn’t been the real limit on productivity any time in this century, and yet all of our work processes are structured as though it is.

The social systems of work are coming apart

What was (is) the limit? Getting signal from customers.

You don’t need high fidelity to learn that you are barking up the wrong tree. The easier coding becomes — and the more you produce before showing it to a user — the more effort you end up investing into being wrong. It’s no surprise that while HBR has found that AI intensifies work instead of reducing it, execs forecast an anemic 1.4% productivity growth over the next 3 years.

Alas! It turns out that all the other people in the office with you aren’t merely decorative. Work is a social system and productivity improvements localized to a part of the workflow that was already completely unblocked are not going to reflect in the bottom line.

Rather than help, the presence of AI is actually making it worse.

❝

If there is a productivity crisis in the knowledge economy, it is the fault of management for failing to retain mid-level people in positions where they might feel consistently supported to help make the projects they sponsor do well.

An atomized team is the antithesis of UX

It’s easy to pretend that continuity isn’t important, as long as you can get your deliverables over the line every two weeks. But is that really what you want to write in your promo doc, or on your resume? No one cares about your story point velocity. Managers want to see impact and ownership. And without engaging with work-as-a-system, you will never achieve either of those.

❝

If you don't understand the structural incentives, the social context of decision-making, and the individual perspectives, you will be continuously confused by watching your organization make obviously bad choices over and over and over while ignoring your recommendations.

Long before AI rolled onto the scene, the “build to learn” ideology had already done irreparable harm to people’s ability to understand this system, through the simple means of convincing them to pretend that the system does not exist.

But no matter how hard you try to ignore it, the system is there. You can’t just build your way into PMF. You have to do all the uncomfortable, squishy work around the software. Like research.

Unfortunately, research means talking to people, which means that research can only ever happen at a human pace. It can be tempting to skip that research by relying on heuristics (for example assuming that efficiency is always good, and optimizing for that) but that approach is always going to burn you. The state of the art moved past simple time-and-motion optimization in the 1960s, and it’s time to get on board.

Good user research, not output velocity, unblocks productivity

It’s easy to assume that someone else already talked to users, and figured out what they wanted. Even the Agile manifesto carefully excludes the work required to actually compile requirements. And in the decades since it was written, the situation has only gotten worse: tooling has helped us deliver more quickly, but it has done nothing to help us learn what to deliver.

This perverse incentive has led a lot of people to foolishly use AI to counterfeit research data (which is often sold to low-maturity teams under the moniker of “synthetic” research) just so they can get back to shipping deliverables, which is easier and smoother and less complicated. And also provides zero actual value.

There are many excuses for not doing real user research. But if you want to anchor your work in real data instead of sparkling assumptions, you’re going to have to get over those excuses. Once you’re ready to do so, Stephanie Walter has made it easy with a comprehensive guide to user interviews that will get you started even if you’re not an expert.

Which brings us back to the thing about code. Why doesn’t the ability to reach high fidelity faster accelerate our learning? Because the “blockiness” of our research artifacts is actually a beneficial property. Good research isn’t looking for a yes or no; it’s creating a dialogue with the participant, and low fidelity leaves the possibility space open as wide as possible.

And when you’re finally ready to write working code? We’ve known for ten years that testing by launching a viable product is foolish. Good research will not only give you answers, but also let you develop a sense of what data is convincing enough, and which assumptions actually warrant testing in prod.

— Pavel at the Product Picnic

A Broken Heart

2026-02-11T16:33:21Z

Or, getting a 100x speedup with one dumb line of code.

You always know it’s a good bug when your first reaction is, “How could this even happen?”

The other day, I was refining the dashboard of a web app we’re working on – as you do – and I noticed it was taking forever to load. Like, it had been loading in a single second, but now it was taking ten seconds. Something fishy was going on.

Naturally, I blamed React.

I mean, sure, in a modern web app there are many potential causes of a performance problem: third-party JavaScript, overburdened servers, bloated assets, missing database indexes – a list as long as your arm. But decades of building for the web told me that this was a frontend problem. I could just smell it. The page looked janky while loading. And despite being the least-bad approach for web frontends today, the React ecosystem is lousy with ways for a codebase to get tangled, slow, and fishy.

So to prove my theory, I explained to Claude that the dashboard was loading slowly, that it surely had some React problems, and to analyze it and rank them from most to least serious. And sure enough, Claude found a bunch of React fishiness – unnecessary re-renders, missing memoizations. We still weren’t on React Compiler, which I hadn’t realized. So I had Claude do a first pass on the easiest and most serious React issues, and…

It made almost no difference? Maybe it wasn’t React after all.

So, I rolled up my sleeves, and started investigating properly.

Maybe the server really is slow? A little, but it’s not blocking the frontend.
Was the problem in all browsers? No. It was somehow specific to Safari?
Ah, it must be third-party JavaScript then. Intercom? No. PostHog? No.
Okay, let’s really dig in to the performance timeline.

Now, the Safari performance inspector has diverged from the Chromium one over the years, and has gotten (on this page at least) rather flaky. But it painted a pretty clear picture: It wasn’t spending 7+ seconds parsing JavaScript, calculating styles, or loading from the network. It was using 94% of an M1 Max CPU on… Layout?

Digging into the details, it showed multiple Layout passes taking more than 1600ms each. For reference, that’s roughly 100x slower than it should be, so something was seriously wrong with how our page was being laid out. Flexbox can get a little slow, but not this slow.

Time to tear things apart

At that point, I reached for an age-old tool that has gotten more useful in the modern age: binary search. That is, you explain the symptom to your coding agent. Then you have it repeatedly remove stuff from your code that might be causing the problem, and see if that fixes it. When you find something that fixes it, you iteratively re-add everything until you have a minimal change that indicates the underlying issue, and thus a workaround.

This is especially fast if the agent can see the problem itself, but I didn’t have a command-line Safari perf analysis tool on hand. Still, after only 10 minutes of telling Claude whether a given change did or didn’t fix the issue, coaching it through how to think about what we’d just learned with each step, we’d found the culprit!

A heart emoji. ❤️

If we removed the emoji in our Send Feedback button (which I’d recently added), then Safari could lay the page out in 2 milliseconds. If we re-added it, the page took 1600ms for each layout, of which there were multiple.

Now, I like to use emoji in early prototype interfaces. They’re trivial to add, and load faster than images. Right? A single character of a font should not take 100x longer to render (or, according to Safari, “Layout”) than the rest of a dynamic React web app. Seems like I’d hit a Safari bug.

This is generally the “okay now I need a drink” moment in a Weird Bug Hunt. But it was still before noon, so I went to get another coffee instead.

When you find something that looks to be a bug in the browser, you want to submit that bug. To submit a bug, though, you can’t just attach your whole project. “Hey if you run this whole production app, Safari has a problem.” You’re meant to produce a minimal reproduction case: “Here’s a simple file that triggers the issue. Load it and see.” Even better, this means you’ll fully understand the problem, and can likely find a better workaround than “never use emoji in this app again”.

Making a minimal repro sample is a huge barrier for submitters, though, since fully boiling a full-fledged app containing proprietary stuff down to the minimal repro case is a ton of tedium.

Or, it used to be a ton of tedium! Related to their bug-isolating capabilities, coding agents are also particularly well-suited to producing minimal test cases. They can edit a lot of code at once, and it usually doesn’t take much creativity – you’re just iteratively removing as much as you can without making the bug stop triggering.

So, before long, I had a very simple repro case for the Safari team. And, in looking at the minimal repro code, it became very clear what the real culprit was. On my Mac, Safari 26.2 takes 1600ms to “Layout” the following HTML.

<!DOCTYPE html>
<html>
<head>
  <link href="https://fonts.googleapis.com/css2?family=Noto+Color+Emoji" rel="stylesheet">
  <style>
    body { font-family: "Noto Color Emoji"; }
  </style>
</head>
<body>
  💔
</body>
</html>

Curse you, Noto Color Emoji.

Fonts can have colors now!

Traditionally, fonts were just shapes. It would display in black, or white, or whatever color you chose. But in 2008, Apple shipped Apple Color Emoji in iPhone OS 2.2, and brought it to Mac OS X in 2011. Emoji’s rise in popularity led to demand for fonts that have intrinsic color.

Originally, Apple’s Color Emoji were basically a hack. They just stuck PNG images in a font, which was neither standardized nor resolution-independent. Outside a certain size range, they looked like butt. This led to four competing color font standards (from Apple, Mozilla, Google, and Microsoft) all being submitted to OpenType 1.7. According to Wikipedia, Microsoft and Apple added support for these different approaches, and that’s that.

But that – as it so often is – was not that.

You see, Noto Color Emoji is a Google font that is helpful in that it gives you consistent emoji rendering across platforms. We’d included it earlier to get decent emoji rendering on Linux (where we do some HTML-to-video rendering in the cloud, a technique that sounds horrifying but can be pretty useful). However, the font relies on COLRv1, a spec Google advises will make your apps load faster because it results in smaller emoji than bitmaps – and can fall back to supplying SVG for other browsers.

“Other browsers”, in this case, is Safari. And, I guess, “falling back to SVG” means spending 1600ms of “Layout” for a single character. If you’d like to see what this looks like scaled up, you can try loading the Google Fonts page that attempts to showcase all of the Noto Color Emoji glyphs on iPhone. (As of iOS 26.2, it goes poorly.)

After I mentioned the bug in a Slack, Daniel Jalkut filed it in the Safari bug tracker, and Simon Fraser on the webkit team has already commented, noting the slowness seems to be within CoreSVG. Chances are this will get fixed!

In the meantime, I’d like to contribute this humble finding to the search corpus: don’t use Noto Color Emoji on Apple platforms – list “Apple Color Emoji” first. At least, until the bug is fixed and the resulting Safari release is widespread.

I’d also like to come clean on a little secret. As profoundly helpful as Claude was in debugging this – I surely fixed this problem 10x faster than I would have without it – I must admit, it was Claude that tipped us off to the existence of Noto Color Emoji in the first place. I suspect that, without the coding agent, we would have solved the Linux emoji problem in a more boring way (using an icon library) and not ended up with a weird slow emoji implementation.

It seems more true every month: these coding agents are very much like a power saw. Profoundly useful, and proportionately dangerous.

So, I suppose, here’s to Claude. The cause of – and solution to – all of startups’ problems.

AI Makes the Easy Part Easier and the Hard Part Harder for Developers

2026-02-10T05:43:41Z

A friend of mine recently attended an open forum panel about how engineering orgs can better support their engineers. The themes that came up were not surprising:

Sacrificing quality makes it hard to feel proud of the work. No acknowledgement of current velocity. If we sprint to deliver, the expectation becomes to keep sprinting, forever.

I've been hearing variations of this for a while now, but now I'm also hearing and agreeing with "AI doesn't always speed us up".

"AI did it for me"

Developers used to google things. You'd read a StackOverflow answer, or an article, or a GitHub issue. You did some research, verified it against your own context, and came to your own conclusion. Nobody said "Google did it for me" or "it was the top result so it must be true."

Now I'm starting to hear "AI did it for me."

That's either overhyping what happened, or it means the developer didn't come to their own conclusion. Both are bad. If someone on my team ever did say Google wrote their code because they copied a StackOverflow answer, I'd be worried about the same things I'm worried about now with AI: did you actually understand what you pasted?

Vibe coding has a ceiling

Vibe coding is fun. At first. For prototyping or low-stakes personal projects, it's useful. But when the stakes are real, every line of code has consequences.

On a personal project, I asked an AI agent to add a test to a specific file. The file was 500 lines before the request and 100 lines after. I asked why it deleted all the other content. It said it didn't. Then it said the file didn't exist before. I showed it the git history and it apologised, said it should have checked whether the file existed first. (Thank you git).

Now imagine that in a healthcare codebase instead of a side project.

AI assistance can cost more time than it saves. That sounds backwards, but it's what happened here. I spent longer arguing with the agent and recovering the file than I would have spent writing the test myself.

Using AI as an investigation tool, and not jumping straight to AI as solution provider, is a step that some people skip. AI-assisted investigation is an underrated skill that's not easy, and it takes practice to know when AI is wrong. Using AI-generated code can be effective, but if we give AI more of the easy code-writing tasks, we can fall into the trap where AI assistance costs more time than it saves.

Hard part gets harder

Most people miss this about AI-assisted development. Writing code is the easy part of the job. It always has been. The hard part is investigation, understanding context, validating assumptions, and knowing why a particular approach is the right one for this situation. When you hand the easy part to AI, you're not left with less work. You're left with only the hard work. And if you skipped the investigation because AI already gave you an answer, you don't have the context to evaluate what it gave you.

Reading and understanding other people's code is much harder than writing code. AI-generated code is other people's code. So we've taken the part developers are good at (writing), offloaded it to a machine, and left ourselves with the part that's harder (reading and reviewing), but without the context we'd normally build up by doing the writing ourselves.

Sprint expectations and burnout

My friend's panel raised a point I keep coming back to: if we sprint to deliver something, the expectation becomes to keep sprinting. Always. Tired engineers miss edge cases, skip tests, ship bugs. More incidents, more pressure, more sprinting. It feeds itself.

This is a management problem, not an engineering one. When leadership sees a team deliver fast once (maybe with AI help, maybe not), that becomes the new baseline. The conversation shifts from "how did they do that?" to "why can't they do that every time?"

My friend was saying:

When people claim AI makes them 10x more productive, maybe it's turning them from a 0.1x engineer to a 1x engineer. So technically yes, they've been 10x'd. The question is whether that's a productivity gain or an exposure of how little investigating they were doing before.

Burnout and shipping slop will eat whatever productivity gains AI gives you. You can't optimise your way out of people being too tired to think clearly.

Senior skill, junior trust

I've used the phrase "AI is senior skill, junior trust" to explain how AI coding agents work in practice. They're highly skilled at writing code but we have to trust their output like we would a junior engineer. The code looks good and probably works, but we should check more carefully because they don't have the experience.

Another way to look at it: an AI coding agent is like a brilliant person who reads really fast and just walked in off the street. They can help with investigations and could write some code, but they didn't go to that meeting last week to discuss important background and context.

Ownership still matters

Developers need to take responsible ownership of every line of code they ship. Not just the lines they wrote, the AI-generated ones too.

If you're cutting and pasting AI output because someone set an unrealistic velocity target, you've got a problem 6 months from now when a new team member is trying to understand what that code does. Or at 2am when it breaks. "AI wrote it" isn't going to help you in either situation.

How can AI make the hard part easier?

The other day there was a production bug. A user sent an enquiry to the service team a couple of hours after a big release. There was an edge case timezone display bug. The developer who made the change had 30 minutes before they had to leave to teach a class, and it was late enough for me to already be at home. So I used AI to help investigate, letting it know the bug must be based on recent changes and explaining how we could reproduce. Turned out some deprecated methods were taking priority over the current timezone-aware ones, so the timezone was never converting correctly. Within 15 minutes I had the root cause, a solution idea, and investigation notes in the GitHub issue. The developer confirmed the fix, others tested and deployed, and I went downstairs to grab my DoorDash dinner.

No fire drill. No staying late. AI did the investigation grunt work, I provided the context and verified, the developer confirmed the solution. That's AI helping with the hard part.

untitled

2026-02-06T12:02:58Z

Web Dev | Front-End Engineer | UX Designer

Explicit resource management in JavaScript

3 min read

684 views

Writing JavaScript that opens something (a file, a stream, a lock, a database connection) also means remembering to clean it up. And if we’re being honest, that cleanup doesn’t always happen. I know I’ve missed it more than once.

JavaScript has always made this our problem. We reach for try / finally, tell ourselves we’ll be careful, and hope we didn’t miss an edge case. It usually works, but it’s noisy and easy to get subtly wrong. It also scales poorly once you’re juggling more than one resource.

That’s finally starting to change. Explicit resource management gives JavaScript a first-class, language-level way to say, “This thing needs cleanup, and the runtime will guarantee it happens.”

Not as a convention or a pattern, but as part of the language.

We’re bad at cleanup (and the language doesn’t help)

This pattern should look familiar:

const file = await openFile("data.txt");

try {
  // do something with file
} finally {
  await file.close();
}

This is fine, but also:

Verbose
Repetitive
Easy to mess up as complexity grows, especially during refactors

Now add another resource:

const file = await openFile("data.txt");
const lock = await acquireLock();

try {
  // work with file and lock
} finally {
  await lock.release();
  await file.close();
}

Now order matters. Error paths matter. You can reason through all of this, but the mental overhead keeps creeping up. And once it’s there, bugs tend to follow.

Other languages solved this years ago. JavaScript is (slowly) catching up.

`using`: cleanup, but make it the runtime’s job

At a high level, using declares a resource that will be automatically cleaned up when it goes out of scope.

Conceptually:

using file = await openFile("data.txt");

// do something with file

// file is automatically closed at the end of this scope

No try. No finally. No “did I remember to close this?”

The key shift is that cleanup is tied to lifetime, not control flow.

How cleanup actually works

Resources opt in by implementing a well-known symbol:

Symbol.dispose for synchronous cleanup
Symbol.asyncDispose for asynchronous cleanup

For example:

class FileHandle {
  async write(data) {
    /* ... */
  }

  async [Symbol.asyncDispose]() {
    await this.close();
  }
}

Once a value has one of these methods, it can be used with using.

And importantly, using doesn’t magically close files, it just standardizes cleanup instead of every library inventing its own.

When you need `await using`

If cleanup is asynchronous, you’ll typically use await using:

await using file = await openFile("data.txt");

// async work with file

When the scope ends, JavaScript will await disposal before continuing.

Synchronous resources (locks, in-memory structures) can use plain using. It may feel odd at first, but it matches how JavaScript already draws the line between sync and async elsewhere. What matters is that cleanup happens at scope exit.

Stacking resources without the headache

This is where things really improve.

Instead of:

const file = await openFile("data.txt");
const lock = await acquireLock();

try {
  // work
} finally {
  await lock.release();
  await file.close();
}

You write:

await using file = await openFile("data.txt");
using lock = await acquireLock();

// work

Cleanup happens automatically, in reverse order, like a stack:

lock is released
file is closed

No extra syntax. Errors don’t short-circuit disposal, and cleanup happens in a defined order.

Scope is the point

A using declaration is scoped just like const or let:

{
  await using file = await openFile("data.txt");
  // file is valid here
}

// file is disposed here

This pushes you toward tighter scopes and makes lifetimes explicit, something JavaScript has historically been bad at expressing. Once you start seeing lifetimes in the code itself, it’s hard to unsee.

When `using` isn’t enough

Not every resource fits neatly into a block. Sometimes acquisition is conditional, or you’re refactoring older code and don’t want to introduce new scopes everywhere.

That’s where DisposableStack and AsyncDisposableStack come in:

const stack = new AsyncDisposableStack();

const file = stack.use(await openFile("data.txt"));
const lock = stack.use(await acquireLock());

// work with file and lock

await stack.disposeAsync();

You get the same safety as using, with more flexibility. If using is the clean, declarative case, stacks are the escape hatch.

This isn’t just a back-end feature

At first glance this can feel like a server-side concern, but it applies just as much on the front end and in platform code:

Web Streams
navigator.locks
Observers and subscriptions
IndexedDB transactions

Anyone who’s written subscribe() / unsubscribe() or open() / close(), this should at least make you pause.

This isn’t just about correctness. It’s about making lifetimes visible in the code instead of hiding them in conventions and comments.

What’s the catch?

As of early 2026, Chrome 123+ and Firefox 119+ support all of these features. Node.js 20.9+, too. Safari support is still pending, but it’s on their radar.

For now, it’s something to experiment with and maybe start designing APIs around, especially if you maintain libraries or platform-level abstractions. Even if you’re not using using tomorrow, the model it introduces is worth paying attention to.

A better default for cleanup

Explicit resource management doesn’t replace try / finally. You’ll still use it when you need fine-grained control.

What it does give us is a better default: less boilerplate, fewer leaks, clearer intent, and code that just reads better. As JavaScript takes on more systems-like responsibilities, features like this feel less like nice-to-haves and more like table stakes.

JavaScript

Please enable JavaScript to view the comments powered by Disqus.

Anti-frameworkism: Choosing native web APIs over frameworks

2026-02-02T07:41:45Z

Today’s browsers can handle most of the problems that frontend frameworks were originally created to solve. Web Components provide encapsulation, ES modules manage dependencies, modern CSS features like Grid and container queries enable complex layouts, and the Fetch API covers network requests.

Despite this, developers still default to React, Angular, Vue, or another JavaScript framework to address problems the browser already handles natively. That default often trades real user costs –page weight, performance, and SEO – for developer convenience.

In this article, we’ll explore when frameworks are genuinely necessary, when native web APIs are enough, and how often we actually need a framework at all today.

Frameworkism vs anti-frameworkism

“Frameworkism” and “anti-frameworkism” aren’t formal terms or established movements. They’re shorthand for two competing defaults in how developers approach new projects. At its core, the divide is about where you choose to start.

Frameworkism follows a framework-first mindset. A framework – most often React – is selected upfront and treated as the baseline. This approach assumes fast devices and reliable networks, starts heavy by default, and relies on optimization later if performance issues show up.

Anti-frameworkism takes the opposite approach. It starts with zero dependencies and adds only what’s necessary. Frameworks are tools for specific problems, not the default solution. Developers lean on native browser capabilities first and introduce frameworks only when they hit real limitations. This mindset makes fewer assumptions about user conditions, accounting for slower devices and imperfect networks from the start.

A technical comparison

Cross-browser compatibility is largely a solved problem today. Internet Explorer is no longer in the picture, and even Safari supports most modern web APIs, with only a few caveats. Many of the platform gaps that originally drove the adoption of frameworks like React have since been closed.

The web platform has evolved significantly over the past few years. For a large number of everyday use cases, vanilla JavaScript is more than sufficient.

Below are some of the most important capabilities the platform provides.

Web Components

Web Components are built on three core technologies:

Custom Elements for defining new HTML elements
Shadow DOM for encapsulation
Template elements for reusable markup

Together, these APIs provide a component-based architecture without relying on a framework. Below is a simple example of a Web Component (and here are some more advanced ones):

class TodoItem extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: 'open' });
  }

  connectedCallback() {
    this.shadowRoot.innerHTML = `
      <style>
        :host { display: block; padding: 10px; }
        .completed { text-decoration: line-through; }
      </style>
      <div class="${this.hasAttribute('completed') ? 'completed' : ''}">
        <slot></slot>
      </div>
    `;
  }
}

customElements.define('todo-item', TodoItem);

The component above has encapsulated styles and lifecycle methods (constructor() creates the shadow root, while connectedCallback() runs when the element is added to the DOM).

You can add it to your HTML page like a regular HTML tag:

 
<todo-item>Learn Web Components</todo-item> 

 
<todo-item completed>Pick UX over DX</todo-item>

There’s no transpilation step (such as converting JSX to JavaScript), no virtual DOM abstraction, and no required build step—though you can still use build tools if you want. The code runs directly in the browser and starts instantly because there’s no framework to initialize.

On the other hand, Web Components don’t provide built-in reactivity. Unlike frameworks such as React, where you describe the UI and the framework automatically handles updates, Web Components are imperative. You need to manage DOM updates and respond to attribute or state changes manually, unless you introduce a library like Lit.

Ideal use case: Leaf components

Self-contained leaf components – such as emoji pickers, date selectors, and color pickers—work particularly well as Web Components. They live at the edges of the component tree and don’t contain nested children. Because of that, they avoid much of the complexity around server-side rendering and passing content across multiple shadow DOM boundaries.

Static content with some interactivity

Native approaches shine when dealing with mostly static content that needs a small amount of interactivity. Most websites are still just HTML documents with occasional dynamic behavior, which can be added through progressive enhancementusing vanilla JavaScript.

For example, here’s how you might enhance a basic contact form with asynchronous submission using the Fetch API:

document.querySelector('form').addEventListener('submit', async (e) => {
  e.preventDefault();
  const formData = new FormData(e.target);

  const response = await fetch('/api/submit', {
    method: 'POST',
    body: formData
  });

  if (response.ok) {
    e.target.innerHTML = '<p>Thanks, your message has been sent!</p>';
  }
});

Other web platform features

Beyond Web Components and basic interactivity, the web platform now covers most of the responsibilities frameworks were originally designed to handle. Native ES modules and dynamic imports support dependency management and code splitting, import maps simplify working with third-party libraries, and the Fetch API handles network requests. On the styling side, modern CSS features such as animations, container queries, and custom properties make complex, responsive layouts possible without JavaScript-heavy abstractions.

Maintenance

Long-term maintenance tends to favor native approaches. Vanilla JavaScript, written a decade ago, still runs today, while framework-based applications often require substantial rewrites with each major release. Native web APIs don’t depend on external tooling or package ecosystems, and they maintain backward compatibility far more consistently. As a result, the knowledge you invest in the platform stays relevant for years, not just for a few release cycles.

Server-side rendering

Server-side rendering once depended heavily on frameworks, but the web platform has made significant progress here as well. Declarative Shadow DOM, now supported across all major browsers, lets you define shadow roots directly in HTML using the shadowrootmode attribute, without relying on JavaScript.

In the example below, the component renders immediately instead of waiting for JavaScript to execute, improving initial paint times. The CSS also responds to attributes – the completed state applies a strikethrough purely through the :host([completed]) selector.

<todo-item completed>
  <template shadowrootmode="open">
    <style>
      :host { display: block; padding: 10px; }
      :host([completed]) div { text-decoration: line-through; }
    </style>
    <div><slot></slot></div>
  </template>
  Pick UX over DX
</todo-item>

<script> 
class TodoItem extends HTMLElement { 
  constructor() { 
    super(); 
  } 
} 

customElements.define('todo-item', TodoItem); 
</script>

AI defaults to frameworks

AI coding tools reinforce the framework-first default by generating React and other popular framework-based solutions, often paired with tools like Tailwind. This isn’t because these are always the best choices, but because framework-heavy code dominates their training data. Paul Kinlan described this AI-driven effect as dead framework theory. While his claim that React has permanently won and alternatives are “dead on arrival” may be overly pessimistic, the core observation holds.

An experiment: what it reveals about vibe coding, output quality, and framework weight?

To see whether this theory shows up in practice, I ran a small experiment using Claude to generate a memory game. Different tools may behave differently, so this should be treated as a single data point rather than a universal result.

With a very generic prompt (“create a memory game”), Claude defaulted to React and Tailwind
With slightly more specificity (“create a simple memory game”), it still chose React, but switched from Tailwind to vanilla CSS written inside the component
With a highly specific prompt that defined the technology (“create a simple HTML memory game”), Claude relied only on native web platform features

In the table below, you can see the key findings:

	V1 (React + Tailwind)	V2 (React)	V3 (No framework)
Prompt	“Create a memory game”	“Create a simple memory game”	“Create a simple HTML memory game”
Prompt specificity	Low (minimal guidance)	Medium (no tech specified)	High (HTML specified)
Functionality	Card matching, flip animations, move counter, win detection, reset	Card matching, flip animations, move counter, win detection, reset	Card matching, flip animations, move counter, win detection, reset
Frameworks	React, ReactDOM, Tailwind CSS, lucide-react	React, ReactDOM, lucide-react	None
Fonts	Google Fonts (Space Mono)	Google Fonts (Fredoka)	System font (Arial)
Icons	lucide-react (UI icons: Sparkles, RotateCcw) + UTF-8 emoji for cards	lucide-react (8 card icons: Sparkles, Star, Heart, Zap, Sun, Moon, Cloud, Flame)	UTF-8 emoji ()
Core bundle (min + gzip)	65.62 KB	63.63 KB	2.16 KB
Demo links	Demo v1 (React + Tailwind)	Demo v2 (React)	Demo v3 (No framework)
Screenshot of demo
Bundle size (VSCodium)

Google Fonts load at runtime (~ 15-30 KB). They’re not included in the core bundle, but they show up in the Network tab in DevTools
See GitHub repo for reference

As you can see above, the memory game functionality is identical across all versions, and the aesthetics are just slightly better in the framework-based versions, thanks to React Lucide (however, note that you can add Lucide icons as inline SVG without React). Yet v1 and v2 are both about 30× larger than the vanilla one, with 95% of the bundle being framework overhead. React and Tailwind didn’t make the output noticeably better; they just made it heavier.

This also demonstrates dead framework theory in action. Without specific guidance, AI defaults to React indeed. You can fight this by increasing prompt specificity, but since most people using AI tools won’t do that, this remains a huge win for frameworkism.

The DX vs UX trade-off

Frameworks introduce real performance overhead. In the memory game example above, the React versions are roughly 30× larger than the native JavaScript implementation.

In larger production applications, that overhead grows well beyond the initial ~60 KB as routing, state management, UI libraries, and other utilities are added. A typical React application with a full ecosystem can easily ship 150–300 KB of framework-related code.

Vanilla applications also grow in size as complexity increases, which makes proportional comparisons harder. Even so, frameworks add a fixed layer of overhead that exists regardless of application scale.

Lower page weight and faster load times are clear UX wins for an anti-frameworkist approach, but they come with trade-offs in developer experience. Writing Web Components by hand can be verbose. Passing props, handling events, and managing updates requires more manual work than in most frameworks, and state management across many components becomes difficult without established patterns.

What’s next? Prioritize users, stay in reality

Web platform features work at scale. When Netflix replaced React with vanilla JavaScript on its landing page, load time and Time to Interactive dropped by more than 50 percent, and the JavaScript bundle shrank by roughly 200 KB. GitHubrelies heavily on custom Web Components through Catalyst, its open-source library for reducing boilerplate. Adobe moved Photoshop to the web using Lit-based Web Components. These aren’t edge cases – they show that the web platform is production-ready.

The job market, however, is messier. Resume-driven development is a well-documented reality, and React still dominates job listings. To stay employable, you’ll almost certainly need to learn React. But the job market reflects what companies already use, not what’s technically best for new projects. To become excellent – not just employable – you need to understand native web APIs and know when each approach makes sense.

Anti-frameworkism isn’t about rejecting tools. It’s about starting from the problem instead of the trend, weighing real-world impact before convenience, and choosing the technology that best serves your users.

Reducing FOUC with Web Components

2026-02-01T04:56:33Z

The Problem

One of the best things about web components is that they are wicked fast, but one of the common complaints I hear is that, because they are a client-side technology, there can be a delay between when the page renders and the components are defined and rendered. This can result in a flash of unstyled content (FOUC) and page content shifts - that jarring moment when your carefully crafted layout suddenly jumps around before your users' eyes. Not exactly the first impression we're going for.

The Old Solution

Here's the solution that's been making the rounds for ages:

:not(:defined) {
  visibility: hidden;
}

What's happening?

This CSS selector targets any custom element that hasn't been defined yet and visually hides it from view. Once the JavaScript defines the custom element, the browser marks it as :defined, the selector no longer matches, and the component becomes visible.

Pros

Performant and simple: Just drop it in a CSS reset or theme file, and you're done.
Zero setup required: Developers using your components don't need to do anything special - it just works out of the box.

Cons

Layout shifts: Because this only hides the component visually (the element still takes up space in the layout). The element initially renders as an unstyled HTMLUnknownElement, which has no intrinsic size. As components load and apply their styles, it can result in content jumps as the page reflows.
Silent failures: If a component fails to define (network issues, JavaScript errors, etc.), it will never be shown. This might be acceptable in some cases, but it's problematic if you're using custom elements for progressive enhancement or mixing defined and undefined custom elements in your application.
Accessibility issues: Using visibility: hidden; can remove the content from the accessibility tree, which means screen readers and other assistive technologies can't access it. Your content is invisible to both sighted users and accessibility tools, which can affect initial focus.

Solving it with JavaScript

In a previous article I wrote, I show how to use native JavaScript APIs to improve upon the original solution:

<style>
  /* Visually block initial render as components get defined */
  body:not(.wc-loaded) {
    opacity: 0;
  }
</style>
<script type="module">
  (() => {
    // Select all undefined custom elements on the page and wait for them to be loaded.
    // Once they are all loaded, add the `wc-loaded` class to the body to make it visible again.
    Promise.allSettled(
      [...document.querySelectorAll(":not(:defined)")]
        .map((component) => {
          return customElements.whenDefined(component.localName);
        })
    ).then(() => document.body.classList.add("wc-loaded"));

    // Add fallback to add the `wc-loaded` class to the body to make it visible after 200ms. 
    // This prevents the user from being blocked from using your application in case a component fails to load
    // or other undefined elements are being used on the page.
    setTimeout(() => document.body.classList.add("wc-loaded"), 200);
  })();
</script>

What's happening?

This approach waits for all custom elements to be defined before revealing the page. Here's how it works:

Hide the body: We set opacity: 0 on the body until it gets the wc-loaded class. Unlike visibility: hidden, this keeps content in the accessibility tree - screen readers can still access it.
Query for undefined elements: document.querySelectorAll(":not(:defined)") finds all custom elements that haven't been defined yet.
Wait for definition: For each undefined element, we use customElements.whenDefined(), which returns a Promise that resolves when that custom element gets defined.
Wait for all components: Promise.allSettled() waits for all those Promises to complete (whether they succeed or fail), then adds the wc-loaded class to make everything visible.
Fallback timeout: The setTimeout ensures that even if something goes wrong, users aren't staring at a blank page forever. After 200ms, we show the page regardless.

Here is a demo you can play with.

Pros

Accessibility-friendly: By using opacity instead of visibility: hidden, the page content remains available to assistive technologies. Users with screen readers aren't left in the dark.
Graceful degradation: Provides a fallback in case components fail to load or if undefined custom elements are also being used on the page. Your users will see something rather than nothing.
Very performant: Modern browsers handle opacity changes efficiently, and the JavaScript overhead is minimal.
Future-proof: By adding a class instead of directly manipulating styles, you avoid issues where new components added after page load might cause the opacity to flash in and out.

Cons

Setup required: Depending on your architecture, this might need to be included in your base template or injected into every page. It's not quite as "set it and forget it" as a CSS-only solution.
JavaScript dependency: Requires JavaScript to execute on the page before content is visible. If JS is disabled or fails to load, users see nothing (though the timeout helps mitigate this).
Module timing: The script needs to run as a module, which means it's deferred and runs after the DOM is loaded. This can introduce a small delay compared to inline scripts or CSS-only solutions.
Potential failure point: If JavaScript is disabled or fails to load the script, it could prevent the page from loading properly.

Solving it with CSS

What if we could have the best of both worlds - a solution that's easy to set up, lightweight, doesn't require additional JavaScript to run, and provides a fallback if components fail to load? Here's a CSS-only approach:

body:has(:not(:defined)) {
  opacity: var(--wc-loaded, 0);
  animation: showBody 0s linear 100ms forwards;
}

@keyframes showBody {
  to {
    --wc-loaded: 1;
  }
}

What's happening?

This solution uses modern CSS features to handle component loading. Here's the breakdown:

The :has() selector: This checks if the body contains any elements matching :not(:defined). If it finds undefined custom elements, the styles apply.
Initial hiding: opacity: 0 makes the body invisible while undefined components are present.
Animation-based timeout: We set up an animation with 0 seconds duration but a 100ms delay. This animation's purpose is to set opacity: 1.
Automatic reveal: As soon as all custom elements become defined, the :has(:not(:defined)) selector no longer matches, the animation is removed, and the browser resets to the default opacity: 1.
Built-in fallback: If components fail to load or take too long, the animation completes after 100ms anyway, forcing opacity: 1.
Prevent flashes: The --wc-loaded sets the state moving forward, which will prevent the opacity from flashing when new undefined components are added to the page.

Here is a demo you can play with.

Pros

Pure CSS solution: No JavaScript required! This means it works even in environments where JS is disabled or fails to load, and it executes immediately without waiting for the DOM or module loading.
Automatic fallback: The animation delay provides a built-in timeout. If components fail to define, the page still becomes visible after 100ms. No need for manual setTimeout calls.
Lightweight: Just a few lines of CSS - no extra scripts, no DOM queries, no Promise wrangling.
Reactive: The :has() selector automatically updates when elements become defined.
Easy to customize: Want a longer timeout? Change the animation delay. Want to target specific containers instead of the whole body? Adjust the selector. Timeouts and animation timing can be made configurable using CSS variables. It's flexible without being complicated.
Accessibility-friendly: Like the JS solution, this uses opacity rather than visibility, keeping content available to assistive technologies.

Cons

Browser support: The :has() selector is relatively new. It's supported in all modern browsers, but may not be supported in older versions. The good news is that if something is not supported, it will gracefully fail rather than crash your app.

Wrapping Up

These solutions will continue to evolve, but FOUC doesn't have to be a necessary evil of using web components. With these techniques in your toolkit, you can provide smooth, accessible experiences for your users and boost those Core Web Vitals scores without sacrificing the benefits of web components.

My Opinionated CSS Reset

2026-01-22T11:28:45Z

As years have stretched on, browser user-agent styles have grown somewhat estranged from how many developers use the web platform. I am no exception to this rule and find my own needs at odds with the predefined user-agent stylesheets of major browsers:

As such, I, like many others, have a CSS reset that I apply to many projects as part of an effort to ensure comfortable development. ‘Reset’ is perhaps not quite the correct diction, as much of this is opinionated and not purely returning to a clean slate. We’re mostly past the days of rogues like Internet Explorer, and browsers are mostly consistent with their styling.

Despite ‘reset’ not being the most accurate term, the more correct title of ‘Preferred CSS defaults and user-agent overrides’ just doesn’t come with quite the same panache.

Here is my complete unabridged reset:

@layer {
	*,
	*::before,
	*::after {
		box-sizing: border-box;
		background-repeat: no-repeat;
	}

	* {
		padding: 0;
		margin: 0;
	}

	html {
		-webkit-text-size-adjust: none;
		text-size-adjust: none;
		line-height: 1.5;
		-webkit-font-smoothing: antialiased;
        hanging-punctuation: first allow-end last;
	}

	body {
		min-block-size: 100%;
	}

	img,
	iframe,
	audio,
	video,
	canvas {
		display: block;
		max-inline-size: 100%;
	}

	svg {
		max-inline-size: 100%;
	}

	svg:not([fill]) {
		fill: currentColor;
	}

	input,
	button,
	textarea,
	select {
		font: inherit;
	}

	textarea {
		resize: vertical;
	}

	fieldset,
	iframe {
		border: none;
	}

	p,
	h1,
	h2,
	h3,
	h4,
	h5,
	h6 {
		overflow-wrap: break-word;
	}

	p {
		text-wrap: pretty;
		font-variant-numeric: proportional-nums;
	}

	h1,
	h2,
	h3,
	h4,
	h5,
	h6 {
		font-variant-numeric: lining-nums;
	}


	input,
	label,
	button,
	h1,
	h2,
	h3,
	h4,
	h5,
	h6 {
        line-height 1.1;
    }

	math,
	time,
	table {
		font-variant-numeric: tabular-nums lining-nums slashed-zero;
	}

	code {
		font-variant-numeric: slashed-zero;
	}

	table {
		border-collapse: collapse;
	}

	abbr {
		font-variant-caps: all-small-caps;
		text-decoration: none;

		&[title] {
			cursor: help;
			text-decoration: underline dotted;
		}
	}

	sup,
	sub {
		line-height: 0;
	}

	:disabled {
		opacity: 0.8;
		cursor: not-allowed;
	}

	:focus-visible {
		outline-offset: 0.2rem;
	}
}

Breakdown

The first thing you may notice in my reset is that it is entirely contained within an anonymous layer. Placing the reset on an anonymous cascade layer using the @layer at-rule gives every declaration a low specificity.

*,
*::before,
*::after {
	box-sizing: border-box;
	background-repeat: no-repeat;
}

I find content-box to be unintuitive and confusing. I much prefer border-box’s inclusion of an element’s padding and border in the width and height as a default.

Backgrounds repeating has always seemed to me like an unreasonable default that is overwritten more often than not, so I disable it.

* {
	padding: 0;
	margin: 0;
}

When working with custom CSS, I find browser default margins and paddings to be a hindrance rather than a help. They provide somewhat of a reasonable default when working with unstyled documents but get in the way more often than not when writing my own styling.

html {
	-webkit-text-size-adjust: none;
	text-size-adjust: none;
	line-height: 1.5;
	-webkit-font-smoothing: antialiased;
	hanging-punctuation: first allow-end last;
}

text-size-adjust stops mobile browsers from trying to adjust text sizes for mobile, which is more harm than help when already designing with mobile in mind. Kilian Valkhof covers it nicely in Your CSS reset needs text-size-adjust (probably).

The user-agent default line-height is just too small. It makes text cramped and difficult to read.

-webkit-font-smoothing is a very specific fix to the way macOS renders fonts. Adding it stops type from appearing thicker than it should on macOS.

Hanging punctuation just looks better. At time of writing no browsers support it, but they will one day, and I’ll be ready.

body {
	min-block-size: 100%;
}

Stops the body from collapsing, which is useful if the content is less than it takes to fill the viewport.

img,
iframe,
audio,
video,
canvas {
	display: block;
	max-inline-size: 100%;
}

svg {
	max-inline-size: 100%;
}

The vast majority of the time when using media, I don’t intend for it to display inline (SVGs being the exception). I also very rarely wish for content to be larger than the container, so a max-inline-size is a reasonable method of addressing inline overflows.

svg:not([fill]) {
	fill: currentColor;
}

It is reasonable for the fill colour of an SVG to default to the current colour rather than black if there is no fill already defined.

input,
button,
textarea,
select {
	font: inherit;
}

Input elements should not use different font styling by default. It makes them immediately feel out of place.

textarea {
	resize: vertical;
}

textareas usually only need vertical resizing, not horizontal.

fieldset,
iframe {
	border: none;
}

Fieldsets are good for grouping, but the border is ugly. I personally always opt for another method of visual clustering, so I default to removing the border. I used to manually remove the border on a case-by-case basis but eventually realised that cases of me keeping it were outliers.

iframes are usually presented to integrate with a page, not stand out. Thus, I think no border is a more reasonable default.

p,
h1,
h2,
h3,
h4,
h5,
h6 {
	overflow-wrap: break-word;
}

A common cause of horizontal overflows – especially given the rave popularity of large font sizes – it is only reasonable to break them.

p {
	text-wrap: pretty;
	font-variant-numeric: proportional-nums;
}

Not very well supported, but I’m a typography snob, and any improvement helps.

proportional-nums enables numerals whose widths vary naturally instead of all taking up the same fixed width.

h1,
h2,
h3,
h4,
h5,
h6 {
	font-variant-numeric: lining-nums;
}

I like to make sure that I don’t have oldstyle-nums in my headings, as they always look out of place. As an aside, I really am looking forward to :heading.

I don’t set any further rules on my headings as I configure them on a per-project basis. text-wrap: balance; is a common addition.

input,
label,
button,
h1,
h2,
h3,
h4,
h5,
h6 {
    line-height 1.1;
}

Headings and inputs should have smaller line heights. Headings so that they don’t appear split, and inputs because there is such a small amount of text it offends legibility. While this is a reasonable default, if large ascenders/descenders are present on a heading font, it may need to be re-evaluated.

math,
time,
table {
	font-variant-numeric: tabular-nums lining-nums slashed-zero;
}

code {
	font-variant-numeric: slashed-zero;
}

When clarity is necessary, such as with times, maths, or code, some typographical changes are always necessary. tabular-nums and lining-nums keep numbers aligned and consistent, making data easier to read.

Slashed zeros (0) remove visual ambiguity.

table {
	border-collapse: collapse;
}

Non-collapsed borders feel very 90s and are visually overwhelming.

abbr {
	font-variant-caps: all-small-caps;
	text-decoration: none;

	&[title] {
		cursor: help;
		text-decoration: underline dotted;
	}
}

<abbr> is an odd element, really. The title attribute aspect isn’t well exposed and is only really usable with a pointer. I still like to cover it, but this should be kept in mind.

sup,
sub {
	line-height: 0;
}

Superscript and subscript annoyingly meddle with line heights, which I dislike. This overrides that behaviour.

:disabled {
	opacity: 0.8;
	cursor: not-allowed;
}

Firefox is the only major browser that doesn’t reduce the opacity of disabled elements, so I reduce it for parity. I also apply a not-allowed cursor for some further clarity. Care must be taken here, as this could cause text to have insufficient contrast.

:focus-visible {
	outline-offset: 0.2rem;
}

Focus outlines are good, but when they’re too close, they’re often difficult to see. A slight offset helps address this.

Understanding the fundamentals of CSS Layout

2026-01-23T08:44:16Z

When developers say that CSS is hard, they're usually talking about CSS layout. What often gets omitted though is that developers are assumed to understand and effectively use CSS without being taught how it works in the first place.

I think this is because the syntax of CSS is simple, especially compared to JavaScript and even to HTML.

select-thing-here {
  guess-a-property: give-it-a-value;
  
}

It leads to the impression that all you need to write CSS is to understand the syntax and have a reference for the properties and values.

That, of course, is not true.

Imagine if you were assumed to learn JS by just looking at its syntax. How would you ever learn what this refers to, or how closures work, or how prototypal inheritance works? It would make no sense!

CSS is no less deserving of understanding its underlying concepts, so let's build that foundation.

Prefer video?

This article is a written version of a talk by Kilian Valkhof, Polypane's creator. You can watch the video here:

VIDEO

Interested in having this talk at your conference or meetup? Get in touch!

Gall's law

When you look at CSS as a whole, it's a complex system that is hard to understand. But it's also a system that works.

We have a programming principle that covers that:

All complex systems that work, evolved from simple systems that worked.

This is known as Gall's law, and it applies to CSS layout as well. At its core, CSS layout is built on a few fundamental concepts that work together to create the complex layouts we see on the web today.

CSS Layout started out with a single layout algorithm called normal flow.

Normal flow has a few basic rules, which all subsequent layout algorithms built upon. Indeed, that's the first lesson:

CSS has multiple layout algorithms.

Specific properties in CSS let you opt into different layout algorithms, each with their own rules and behaviors.

Once you understand the foundation of normal flow, you can start to understand how other layout algorithms like positioning, Flexbox, and Grid build upon it.

In other words, this article will help you go from this:

…to this:

Are you ready?

Everything is a box

The most fundamental concept in CSS is that everything is a box. Every element creates a rectangular box, and the x and y position of the box, along with it's width and height create the combined layout on the page.

CSS is:

A bunch of boxes,
placed on the screen,
according to layout algorithms.

This might seem like an obvious statement, but it's important to understand: before screens became ubiquitous, the idea of a "live" layout algorithm wasn't really needed. Boxes didn't interact with each other. They were put in a place and then just ...stayed there.

Print pages are laid out of course, and have been for centuries, but that didn't really happen in real time by a system of rules, an algorithm.

So, CSS is a bunch of boxes. The initial layout algorithm that places them on the screen is:

Normal flow

Normal flow is the default layout algorithm in CSS. It's what you get when you don't explicitly opt into any other layout algorithm.

It comes from when the web was made for document sharing, and "normal flow" refers to the way text flows across a page: from left to right, from top to bottom (for western languages).

From left to right is the inline direction, from top to bottom is the block direction. So text characters will be inline, side by side, and wrap to the next line. Paragraphs and headings are block, and they stack vertically.

Browsers ship with a default stylesheet that dictates which elements are block and which are inline: <p> is block, but <em> is inline.

So that's why, if you write semantic HTML, the browser already makes your page look like a document.

Non-western languages

Not all languages are written left to right, top to bottom. Some languages are written right to left (like Arabic and Hebrew), and some are written top to bottom (like traditional Chinese and Japanese).

This is why CSS has a writing-mode property that lets you change the inline and block directions to fit the language you're using.

Along with that writing mode, many of the explicit directional and sizing properties, like "left" or "height" now have logical equivalents. Instead of left, which for western languages is the start of inline text, the property name is inset-inline-start. Instead of height, which is the size in the block direction, the property name is block-size.

Writing CSS with these logical properties makes them more portable. For this article though, we'll stick to the physical properties like left and width for simplicity.

Formatting context and anonymous boxes

Block and inline tell you how a given element lays out in comparison to the elements around it. This state of being block or inline is called the formatting context, and each element has a formatting context.

But not everything is an element. Consider this HTML:

<p>This is <em>emphasized</em></p>

<p> is a block element and <em> is inline.

But what about the words "This is"? How does that work?

Earlier I wrote that in CSS, everything is a box, and that's also how normal flow solves this. The browser creates something called an anonymous box around that text. In this case because <em> is an inline box, the anonymous box will also be inline: it will be an anonymous inline box.

<p>This is <em>emphasized</em></p>

With that, the browsers now has two inline boxes, and it knows what do to with that. It can lay them out next to each other.

If the code was this though:

<div>
  This is
  <p>a new paragraph</p>
</div>

Both the <div> and <p> are block-level, so the anonymous box generated for "This is" will be an anonymous block box, and the browser can lay out the two boxes on top of each other:

<div>
  This is
  <p>a new paragraph</p>
</div>

Whitespace and anonymous boxes

This anonymous box generation is why some things you might expect to work don't. Take this example.

<div>
  <div class="half">First</div>
  <div class="half">Second</div>
</div>

.half {
    display: inline-block;
    width: 50%;

    background: hotpink;
}
.half + .half {
    background: dodgerblue;
}

Both divs are 50% wide, but they don't sit on the same line. Even though 50% + 50% is 100%.

This is caused by an anonymous inline box created by the newline, the whitespace, between the two divs. That inline box takes up space (the width of a single space character) to the right of the first div, and so the second div no longer fits on the same line:

It would be great if we can select that anonymous box and hide it but unfortunately that's not something we can do with CSS.

We can only target named boxes.

Solving the whitespace issue

We can solve this whitespace problem in several ways:

Remove the whitespace

Remove the character space between the two divs, and the anonymous box is never created (...until you run prettier on your code).

<div>
  <div class="half">
  </div><div class="half">
  </div>
</div>

Disable wrapping

.container {
  white-space: nowrap;
}

When you disable wrapping, you force both divs on the same line regardless of the width of the container. Notice that there is still that space between the two divs, they don't sit flush against each other and that the second div overflows the container.

Since the total width is still 50% + the width of a space character + 50%, the second div overflows the container.

Set the font-size to 0

.container {
  font-size: 0;
}
.container > div {
  font-size: 16px; 
}

If you set the font-size of the parent to 0, the anonymous box will still be created, but it won't have any width since the width of a space at font-size 0 is 0.

If your child elements have text in them, you will need to reset the font size in them or your text won't show up either.

White-space-collapse: discard (in the future!)

.container {
  white-space-collapse: discard;
}

To show you how much CSS is still being worked on, white-space-collapse is part of the newest CSS specification, text level 4.

The value we mention above, 'discard', isn't even supported in any browser as of January 2026. So this is a feature for the future and doesn't work yet.

Even normal flow, which has been around since literally the beginning of CSS, is still being worked on!

The box model

We're not done talking about boxes interact by a long shot, but for the next few concepts we need to understand how boxes themselves are built up. For that we need to talk about the box model.

You have probably seen a version of this diagram before. A box in CSS actually consists of a few distinct areas.

The center area is where you content is, the text or child elements. This content is pushed inwards by the padding. The edge of a box is called the border, and outside of the border is the margin which pushes a box away from other boxes.

For stupid browser reasons there are two models when it comes to determining the size of a box when you give it a width: content-box and border-box.

One of those is the default in browsers, and the other one makes sense.

Content-box

The default is content-box. In that model, width is applied to the content-box, and padding and borders are added to it for the final rendered width.

Actual width = width + padding + border

This is confusing because when you set width: 200px, the actual rendered width might be 250px after padding and borders.

Border-box

To improve this situation, most modern CSS resets include the following CSS

* {
  box-sizing: border-box;
}

With border-box, the width you set is applied to the border-box of the element, so it includes the border and padding layers. The space for the content is width minus padding minus border.

This means that when you see width: 200px in your CSS, you know the element is actually 200px wide regardless of the padding and border. It's much easier to work with.

Try editing the values in the example below to see how content-box and border-box differ. Notice that both boxes have the same width value (200px), but the content-box is physically larger because padding and borders are added outside the content width.

<div class="content-box">Content Box</div>
<div class="border-box">Border Box</div>

div {
  width: 200px;
  padding: 20px;
  margin-bottom: 1rem;
}
.content-box {
  box-sizing: content-box;
  border: 5px solid blue;
  background: lightblue;
}
.border-box {
  box-sizing: border-box;
  border: 5px solid green;
  background: lightgreen;
}

With this understanding of the box model, we can go back to talking about how boxes interact.

How inline boxes work

Everything in CSS is a box, but "box" isn't always what you expect.

A block box makes sense: the element is a rectangle, and the border sits on all edges.

But inline elements can wrap to the next line without becoming a block element, and so the box around an inline element is split up and looks, well, kind of broken:

The top and bottom borders are drawn for each line the element spans, while the inline borders and padding (left and right) are only drawn at the very start and very end.

That looks really broken, doesn't it? Browsers render an inline element as one, long, single line (it's inline after all), and then they slice that up into different line segments where it wraps. Thinking about it in that way makes it a bit easier to visualize what is happening and why it's happening. The box is sliced up into different parts.

Decorations

If you have "decorations" (which is what borders and padding are called) on an inline element, you probably expect those to be applied to each line segment.

Luckily, we can tell browsers how to treat each broken-up line with box-decoration-break. The default value is slice, which is quite literally slicing up the box into different parts.

But you can also tell the browser to treat each line as its own box with clone. Each line becomes its own box with borders and padding on all sides.

span {
  box-decoration-break: clone;
}

Placement of inline elements

Some things like vertical margins, explicit widths and height don't apply to inline elements. This is because when an element is "in line", it's placement on the page is determined by the line it's in. So we know text is "in line", but what's a line?

Lines and baselines

Browsers started out as a way to lay out lines of text. The inline text inside a box is laid out in a number of lines, and these lines are laid out based on the line-height:

What are lines in browsers?

Within each of these lines there is a baseline. The baseline is determined by the font you use, and it's the bottom of your text characters (except for descenders, which go below the baseline).

What are lines in browsers?

What you should understand here is that:

Inline elements are laid out in lines
Each line has a baseline
The baseline is determined by the font
All inline elements align with the baseline by default.

IF you want your text to be in a different place (vertically) in the line, you can change the vertical alignment of an inline element with vertical-align.

span {
  vertical-align: baseline; 
  vertical-align: top;
  vertical-align: middle;
  vertical-align: bottom;

  vertical-align: text-top;
  vertical-align: text-bottom;
}

The top and bottom values are determined by the line height you set on the element:

The text-top and text-bottom are determined by the font. Text-top will align the x-height with the top of ascenders (the parts of letters like b, d, f, h that extend above the x-height), and text-bottom will align the bottom of normal letters with the bottom of descenders.

text-topBaseline

text-bottom

Lastly, middle is weird.

It's calculated from a combination of the font metrics and the line-height, and that causes it to not always mean the exact middle of the line:

middle = baseline + (x-height / 2)

In the example below, you can see that the word "middle" is actually closer to the bottom of the line than to the top.

I'd like to apologize for that on behalf of CSS.

For practical purposes, just know it exists but might not behave exactly as you expect.

From the explanation above, what you need to remember is that, by default, all inline elements sit on the baseline.

Inline elements sit on the baseline

With that knowledge, does the following situation already make sense?

If you now find this obvious, then good job! The inline image is sitting on the baseline, and that's why there is 'unexpected' whitespace below it.

In the past, you might have fixed that by setting display: block on the image, but this has other layout effects too:

The whitespace is gone, but the image now also no longer sits inline with any text, nor does it follow the text align.

Another way you could have fixed this is by setting line-height: 0 on the parent:

If the line-height is 0, then the space below the baseline is also 0, so the whitespace is gone. If you have other text in the parent, that text will also be affected and could even start overlapping.

'Fixing' images

The easiest 'fix' in this case it to simply move the image off the baseline, for example by aligning it to the top or bottom of the line instead:

img {
  vertical-align: top; 
}

The bottom of the image no longer sits on the baseline, so there is no longer whitespace reserved below it!

Now that we have discussed inline behaviour and understand how layout happens inside boxes when they're in normal flow, lets move outside the box and see how the space between boxes works.

Margin behavior

Margins are outside of an element and you can use them to push boxes away from each other.

For block elements, this happens in all directions. For inline elements, as we previously mentioned, it's the line they sit on that determines their placement. Adding margin to inline elemens will only apply in the inline direction (left and right).

Margin collapse

When there are two block elements with margins stacked vertically and there are no other box parts (like border or padding) between them, the larger margin of the two is picked and they 'collapse' into each other.

.hotpink {
  margin-bottom: 1rem;
}
.dodgerblue {
  margin-top: 2rem;
}

We've made the margins semi-transparent here so you can see how they actually overlap, or 'collapse', rather than add up.

This happens when any two elements in the same formatting context (remember that one?) have margins that interact.

Margin collapse between parents and children

Elements and their children also share a formatting context, and that is why you also get margin collapse between parents and children.

You might add a margin to the first element inside a parent with the idea of pushing that element down from the top of the parent element, but due to margin collapse that margin is applied outside of the parent, rather than pushing down the first element.

.parent {
  margin-top: 1rem;
}

You'll frequently want to prevent this, and while there is no explicit margin-collapse: none property, You can instead prevent margin collapse or create a new formatting context.

Firstly, adding a padding or a border, no matter how small, to the parent element will prevent margin collapse since the margins are no longer adjacent.

.parent {
  margin-top: 1rem;
  padding-top: 1px;
}
.child {
  margin-top: 3rem;
}

And while this works, you can see that 1px of padding is affecting the layout. This might matter, or it might not.

another way is to use overflow: auto (or hidden) on the parent element. This creates a new formatting context inside the element, and now the element and the child element are in different formatting contexts, which prevents margin collapse.

.parent {
  overflow: auto;
}
.child {
  margin-top: 3rem;
}

Overflow auto will prevent other elements from being shown outside of the parent element, and when you have restrictions on the width or height of the element, it will show a scrollbar when the content overflows.

The explicit option is to define the parent as a new formatting context, which you can do with display: flow-root.

.parent {
  display: flow-root;
}
.child {
  margin-top: 3rem;
}

flow-root is a bit of a magical property that creates a new block formatting context without affecting other layout aspects of the element. It's a great way to prevent margin collapse without side effects.

Negative margins

Margins can also be negative. When you use negative margins you're not adding space between element, but you're changing the position of the element itself in a way that no longer interacts with the elements around it.

.top {
  margin-bottom: 1rem;
}
.overlap {
  margin-top: -2rem;
}

The way they get calculated is by taking the margin value, which can also be collapsed, see how the two margins overlap, then subtracting the negative value and starting the new element there.

Negative margins exist, but you're better off ignoring them and using positioning instead for overlapping layouts. (More on positioning later.)

Centering block elements with margin: auto

You can use margins to center elements horizontally by setting the left and right margins to auto:

.block {
  width: 200px;
  margin-left: auto;
  margin-right: auto;
}

This element gets centered because the layout for horizontal margins uses a constraint-based layout when either width or margin is set to auto.

A constraint-based layout means that there is a formula that gets solved to determine the layout. The rule is:

total width = margin-left + border-left + padding-left + width + padding-right + border-right + margin-right

Because borders and paddings are fixed values we can leave them out and instead simplify it to this:

available space to fill out = margin-left + width + margin-right

Let's see what happens when we plug in different values for the width and margins into this formula.

Case 1: everything is set to auto

When all three values are set to auto, the width takes up all available space, and both margins are set to 0.

.block {
  margin-left: auto;
  margin-right: auto;
  width: auto;
}

This is because the "preferred width" of a block element is 100%. So the equation becomes:

total width = 0 + 100% + 0

Case 2: the width is auto

If you have values for both margins but aren't defining with, then the width takes up all remaining space between the two margins.

.block {
  margin-left: 2rem;
  margin-right: 2rem;
  width: auto;
}

This is because the preferred width is still 100%, and the constraint then makes this formula:

total width = 2rem + (100% - 4rem) + 2rem

Case 3: the width is fixed

When the width is fixed and both margins are set to auto, the remaining space is divided equally between the two margins.

.block {
  width: 50%;
  margin-left: auto;
  margin-right: auto;
}

This is because the equation becomes:

total width = 25% + 50% + 25%

Case 4: width and one of the margins are fixed

When the width is fixed and one of the margins is also set to a fixed value, the other margin is set to the remaining space.

.block {
  width: 200px;
  margin-right: 50px;
  margin-left: auto;
}

The equation becomes:

total width = (100% - 250px) + 200px + 50px

The browser calculates the remaining space as 100% - 250px and adds it to the left margin, and so even though block elements normally start at the left edge of their container, this one is pushed to the right even though it doesn't have a specific value for margin-left.

Inline-block: The hybrid

There's one last trick normal flow has: display: inline-block.

Given all the time we spent figuring out the differences between inline and block elements and how their specific behavior differs, what even is inline-block?

Inline-block tells the browser that an element behaves as inline for the formatting context around it, but is &rendered as a block box, creating its own formatting context.

.tag {
  display: inline-block;
  padding: 5px 10px;
  margin: 5px;
  background: dodgerblue;
  width: 250px;
}

text text text

We have a bunch of text that wraps across lines.

More text text text

You can see that the element sits inline with the rest of the text and you can even see that the text is placed on the same baseline, but the element itself behaves as a block element, since it has a width, padding on all sides and the content inside of it wraps to multiple lines.

The CSS specification calls this behavior "shrink-to-fit". Before Flexbox, this was a great way to render things like a list of tags or navigation items:

.nav-item {
  display: inline-block;
  padding: 5px 10px;
  margin: 5px;
  background: dodgerblue;
}

Display values: outer and inner

The display property can have two parts: an outer and an inner value. inline-block as a value is from before this was introduced, but in "modern" CSS it's equivalent to:

display: inline flow-root;

The outer value is how the element behaves in relation to other elements, so inline, and the inner value is how the element behaves in relation to its own content. We want that to have a block formatting context. You don't set that with "block", but with flow-root. Think of it as "a new 'normal flow' starting point".

When you set a single item, that item is either for the inner or outer value depending on the value: some are inherently outer values, and some are inherently inner values. For example display: grid creates a grid for the content, and the outer value is inferred to be block, making it the same as display: block grid. display: inline on the other hand is inherently an outer value, so the inner value is inferred to be flow, making it the same as display: inline flow.

flow-root and flow are the two new keywords here and they are roughly equivalent to block and inline, but only for the inner value.

That's Normal Flow

CSS's simplest layout algorithm! Would you have expected that there was so much behind something that you can essentially describe as "text goes from left to right, top to bottom"?

The good news is that all other layout algorithms build upon these concepts. In fact, unless you explicitly take an element "out of flow", elements are still considered "in flow" regardless of what other layout algorithm you use, and the normal flow algorithm is used in addition to it.

Key takeaways for normal flow

Block elements stack vertically (↓)
Inline elements flow horizontally (→)
Everything is a box
Anonymous boxes get created for text outside of elements
Margins collapse vertically
All inline elements sit on the baseline

Other layout algorithms

To get any other layout algorithm, you need to opt into them. There are three main layout algorithms in CSS:

Positioning (relative, absolute, fixed, sticky)
Flexbox
Grid

There's a few more, like table layout, floats and multi-column, but the first two are hacks that we haven't needed in well over a decade, and multi-column is too niche for this already long article (and indeed, might soon be replaced by the masonry-style grid layout algorithm).

A small detour: sizes in percentages

Before we dive into the other layout algorithms, we need to talk about percentages. When you use a percentage value for a size or a margin, padding etc, what is that percentage based on?

div {
  width: 50%;
  height: 25%;
  margin: 10% 5%;
  padding: 5% 2.5%;
}

Well, for width and height (and their min and max and logical equivalents), percentages are based on the size of the containing block. So 50% width is 50 percent of the width of the containing block, and 25% height is 25% of the height of the containing block.

Hold up, containing block?

So we have offset parents, stacking contexts and now also "containing block".

The containing block is the box that contains the element. For most elements, this is the content-box (remember the box model) of the first parent element that is display: block.

For position: absolute elements, it's the padding-box of the closest stacking context, and for position: fixed elements, it's the viewport.

Those last two are exceptions but in practical use those exceptions actually result in elements sizing in ways you would expect.

Percentages for margin and padding

For margins and paddings, percentages are always based on the width of the containing block, even for margin-top and padding-bottom.

That's a bit confusing, but it's because of how the rest of CSS works. Most elements have a vertical size that changes based on their content: the more lines of text you add to a paragraph, the taller it gets.

If you were able to add a padding-top based on a percentage of the height, then that would increase the absolute height of the element, which in turn would increase the padding-top's absolute value, which would then update the height of the element and so on: it would create an infinite loop.

Instead, having percentages for vertical margins and paddings based on the width of the containing block gives you a predictable value that doesn't change when it causes the height of an element to increase.

Positioning schemes

With positioning, we can tell the browser how to place an element either in relation to its calculated flow position, or explicitly take it out of normal flow. It's also where the third dimension is introduced with z-index. That concept doesn't exist in normal flow, and adding z-index to an element without a position does nothing.

Elements by default have position: static, which means no explicit positioning. To activate the positioning layout algorithm, pick a different value:

static (the default)
relative
absolute
fixed
sticky

Each of these are their own little layout algorithm, so let's go through them one by one.

Position: relative

relative is the basic value that lets you opt in to positioning layout. A relatively positioned element has a box placed in the same spot as normal flow, but you can move the element away from that box using top, left, bottom, and right, which are called inset properties. There's also a inset shorthand property that lets you set all four inset properties at once.

.box {
  position: relative;
  top: 40px;
  left: 40px;
}

text text text

Notice that the original box is the one that takes up space and pushes the text away, but the element itself is elsewhere. The original box is used for the rest of the layout.

This pushing away of the element from it's original box is something you'll rarely want, or need. What you mainly use position: relative for is to make an element an offset parent for absolutely positioned children. Before we get into what an offset parent is, let's explain position: absolute.

Position: absolute

Where elements with position: relative are still in normal flow, position: absolute elements are not. This means they do not interact with other elements: they don't take up space and don't push other elements out of the way.

Inset properties don't move them away from their initial box like relative, they instead position the element in relation to the offset parent.

.box {
  position: absolute;
  top: 40px;
  right: 40px;
}

text text text

The offset parent

The offset parent is the first element in the list of ancestors that is itself also positioned (any position value other than static). By default, the body is the only offset parent. So position: absolute; top: 0; will place an element at the top of the page.

If you add positioning to any parent element, it becomes an offset parent, and now top: 0 no longer means the top of the body element, but of that parent element.

Any element that is positioned will become an offset parent, so you can have many offset parents inside of other offset parents. You're always positioning against the nearest offset parent up the DOM tree.

Finding the offset parent

Layout issues where your absolutely positioned element isn't where you expect it are almost always because what you think the offset parent is is different from what the browser thinks.

To find the offset parent in Chrome, Safari, Firefox etc

Find the element in the element inspector
Switch to the console panel
Type $0.offsetParent and hit enter

In Polypane, you can see the offset parent directly in the element inspector's debug panel.

Find the element in the element inspector
Switch to the debug tab
See Offset parent under "contexts"

Learn more about that in our dedicated article on Offset parent and stacking context (more on that second one later).

Position: fixed

position: fixed is a lot like absolute. Elements are taken out of the normal flow, but in this scheme, the offsetParent is always the viewport, and inset properties are used to position from the edge of it.

.header {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
}

That means that while absolutely positioned elements scroll along with the rest of the page, fixed elements will always stay in view.

Position: sticky

The last scheme is position: sticky. It was added to CSS much later than the other ones, and it's for elements that you like to keep in view for some part of the time, but still want to scroll along with their offset parent.

With position:sticky, the element will be placed the same way as position: relative, but the top/left/bottom/right values don't move the element. Instead they determine where an element gets stuck relative to the scrolling context, which is usually the viewport.

.sticky-header {
  position: sticky;
  top: 50%;
}

Scroll down to see me stick

As an element scrolls it will behave like a relatively positioned element, until it hits that inset value where it gets stuck.

Then it will stay stuck, until the offset parent's bottom catches up with it, at which point the element will get unstuck and continue scrolling with it's offset parent.

A tricky thing here is that it will only get stuck if the browser determines it can get stuck. To learn more about debugging sticky positioning, check out our article: Getting stuck: all the ways position sticky can fail

Overview of positioning schemes

So to compare the different positioning schemes, here's a quick overview:

Position	In Flow?	Offset Parent
static	Yes	Not applicable
relative	Yes	Nearest positioned
absolute	No	Nearest positioned
fixed	No	Viewport
sticky	Yes*	Scrollport

* until it gets stuck, then it becomes like fixed.

The stacking context

Remember how I said that with positioning, we introduce the third dimension? Well we haven't talked about that yet.

While the offset parent tells you how an element is positioned in the x and y directions, the stacking context tells you how it's positioned in the third dimension, the z-axis. Or in other words, how close it is to the "front of the screen". And like offset parents, you have stacking contexts inside stacking contexts.

The default stacking context is not the body element, but the html element. So all elements are stacked in relation to the html element by default.

Default stacking order

Elements by default have a stacking order that's the same as source order andz-index lets you reorder them.

div::before {
  background: hotpink;
  z-index: 1;
}
div::after {
  background: rebeccapurple;
  z-index: -1;
}


div::before {
  z-index: -1;
}

div::after {
  z-index: 1;
}

Reordering happens inside the stacking context

In the example below, the purple element has a z-index of 99, which is (much) higher than the blue element's z-index of just 2. So you'd expect the purple element to be in front of the blue one. However, because the purple element is inside of the pink element with a z-index of 1, it's stuck inside the stacking context of the pink element.

.first {
  background: hotpink;
  z-index: 1;

  .inner {
    background: rebeccapurple;
    z-index: 99;
  }
}

.second {
  background: dodgerblue;
  z-index: 2;
}

So instead of 99 being more than 2, you should actually think of it as (1,99) which is less than 2. No matter how high your z-index is, it will never win from elements in a stacking context with a higher z-index than the stacking context you're currently in.

Creating a stacking context

There's just a few CSS properties that can create a stacking context:

position of fixed or sticky
z-index other than auto (with a position other than static or when in a flex or grid layout)
opacity less than 1
mix-blend-mode other than normal
filter, backdrop-filter, transform, perspective, clip-path, mask, mask-image or mask-box-image other than none
isolation set to isolate
container-type set to size or inline-size (so any container element)
will-change property set to mix-blend-mode, filter, transform, perspective, clip-path, mask, mask-image or mask-box-image
contain set to layout, paint, strict or content

… This makes offsetParent sound easy right? It's quite a lot if you list them all out. Most of these properties aren't used very often though.

The most common ones are:

position
z-index
opacity
transform

Explicit stacking context

Out of the entire list, isolation: isolate is the most explicit way of indicating in your CSS that you're creating a new stacking context:

.container {
  isolation: isolate;
}

A practical stacking context example

Here's a practical example, a simple block quote design with a decorative quote mark. After positioning the quote mark correctly in the X and Y axis we can now see that the quote mark is in front of the text. Because the text itself isn't an element (it's an anonymous box), we can't bring it forward using z-index.

blockquote {
  
  position: relative;
}

blockquote span {
  position: absolute;
  top: 0;
  left: 0;
}

<blockquote>
  <span>&ldquo;</span>
  Lorem ipsum dolor sit...
</blockquote>

“Lorem ipsum dolor sit amet consectetur adipisicing elit. Tempora tenetur molestias consequatur, quidem nam ipsum minima aliquid recusandae delectus enim.

Instead, we need to bring the quote backwards with z-index: -1:

blockquote span {
  position: absolute;
  top: 0;
  left: 0;
  z-index: -1;
}

“Lorem ipsum dolor sit amet consectetur adipisicing elit. Tempora tenetur molestias consequatur, quidem nam ipsum minima aliquid recusandae delectus enim.

When you do that however, the quote mark disappears behind the background of the blockquote. That's because the current stacking context is still the HTML element. So we need to make the parent element the stacking context.

blockquote {
  isolation: isolate;
}

“Lorem ipsum dolor sit amet consectetur adipisicing elit. Tempora tenetur molestias consequatur, quidem nam ipsum minima aliquid recusandae delectus enim.

The blockquote is now a new stacking context, and the quote mark can no longer go behind the background. Instead, it sits at the beginning of the stacking context inside the blockquote: behind the text but in front of the background.

Finding the stacking context

Finding the stacking context of an element is not as easy as finding the offset parent. Unlike element.offsetParent, there is no element.stackingContext property.

That's why we built a debug panel into Polypane that not only shows you the offset parent, but also the stacking context of the selected element, along with whether the element itself creates a stacking context. It's very neat, and you can learn more about it in our article on Offset parent and stacking context.

The Polypane debug panel

The top section in the debug panel shows you CSS attributes that commonly cause issues, like display, position and z-index.

Below that, it shows the different contexts that the element is in: the offset parent, the containing block and the stacking context.

Lastly, it shows whether the element itself is an offset parent, containing block or stacking context.

These three sections make it very easy to figure out what's going on with the layout of an element, and really speed up your CSS layout debugging.

Grid and Flexbox

That leaves Grid and Flexbox. I'm not going to spend any time on the syntax or specific features of either layout algorithm, instead focusing on how they interact with the previous layout algorithms and concepts like offset parent and stacking context.

For Flexbox, check out Every Layout by Heydon Pickering and Andy Bell or Flexbox Simplified by Kevin Powell. For Grid, check out Grid by Example by Rachel Andrew.

Both Flex and Grid are significantly different from the layout algorithms that came before. That's because they were developed not as a way to lay out web documents, but as a way to lay out web apps.

The key differences

When you look at Flex and Grid, they each approach layout from a different direction.

Flexbox is "bottom up"

Get a bunch of elements
Order them in a row or column
Distribute them according to rules you provide

Grid is "top down"

Create a bunch of areas
Determine their sizes and positions of those areas according to rules you provide
Place elements inside those areas

So Flexbox starts with the elements you have and distributed them, while Grid starts with defining the available spaces and then adding the elementes to them.

Additionally, Flex is fundamentally one-dimensional (though it can wrap to a next line) while Grid is two-dimensional.

Flex and Grid versus normal flow

Both are replacements of sorts for normal flow. They reason about the distribution of multiple elements in a specific way, rather than the positioning of a single element in relation to other elements.

A very big difference between Flex and Grid on one hand and previous positioning on the other hand is that Flex and Grid no longer depend on font properties. The layouts you make and their alignment are based on the generated boxes, not on the font properties of the elements.

This makes a lot of things much simpler.

Both also try to make sure that regardless of the elements inside of them, the layout will be adhered to. In Flexbox this means that if an element has a fixed width, but that width doesn't fit in the space the Flex container has available for it, the elements size will be overwritten to make it fit the Flex layout. In Grid, an elements width and height are constrained by the grid area they're placed in.

Flex and Grid combined with positioning

Both flex and grid are display properties, separate from the position property. This means that the way to determine offset parents and stacking contexts doesn't change.

You can take an element out of a flex or grid layout with position: absolute or position: fixed. Likewise, each element inside a flex or grid container, including the container itself, can be made an offset parent with position: relative or a stacking context with isolation: isolate.

What not being dependent on font properties means

Unline vertical-align: middle which uses the line-height and font properties (as mentioned above) to determine the middle of a line, both flex and grid align based on the boxes they create.

align-items: center in both layout algorithms will align the boxes of the elements in the middle of the flex or grid boxes, regardless of the font properties or line height of the elements.

.grid,
.flex {
 align-items: center;
}

This new type of alignment logic is the same in Flex and grid and it worked so well that it was actually added to display: block as well.

The align-content property lets you vertically center content in block elements, as long as they have a determined height. It was added to CSS Box Alignment level 3 and works across browsers.

.block {
  align-content: center;
}

<div class="block">
  <div>1</div>
  <div>2</div>
  <div>3</div>
</div>

-items and -content

Flex and grid both have align-items, align-content and justify-content properties. Grid also has justify-items. So what is items and what is content?

*-items properties align the individual items, for example inside a grid area.
*-content properties align the items as a group (usually as a row or column).

In the example below, we have a simple grid that has repeating rows of 50px high, and three 1fr columns. In the first/left example, we have align-items: end which aligns the items to the end of their grid area. In the second example, we set align-content: end. This keeps the items the full size of their grid area, but aligns the entire group of items to the end of the container

Grid and position: sticky

Though the way to determine offset parents and stacking contexts doesn't change with Flex and Grid, when you combine Grid and position: sticky, that won't work as you might expect.

The reason for that is the default value that grid has for align-items, which is stretch. That means that the element with position: sticky already is as tall as the grid area and that means that when it reaches that inset value to get stuck, the bottom of the element is already at the bottom of the grid area and so it never gets stuck.

It's easy to miss that, because elements in a grid area without a background or border look like they are not filling the entire area.

An element doesn't have to fill the entire grid area though. You can set align-items: start on the grid container to have all items align to the start of their grid area instead of stretching to fill it, or align-self: start on the element itself

.grid-container {
  
  align-items: stretch;

  div {
    position: sticky;
    top: 50%;
  }

  .start {
    align-self: start;
  }
}

Check out our article: Getting stuck: all the ways position sticky can fail for more on this.

The final boss: centering a `<div>`

An age old joke about CSS is that it's impossible to center a <div> vertically.

Now that you know the fundamentals, you know that's not true.

The reason vertical centering is 'hard' is because CSS is built on normal flow, where the height of elements is determined by their content.

If the height is determined by the content, and the content is a single line of text, then the height of the element is the height of that line of text. It's already vertically centered, it's just not the height you want.

With that knowledge, there are actually dozens of ways to vertically center a <div>. But modern CSS gives us one way that's definitely the simplest: place-content.

place-content is a shorthand for the combination of align-content and justify-content and as we mentioned earlier in the article, that works in Flex, Grid and Block elements. For it to work, your element does have to have a defined height (because if not, the contents define the height).

.container {
  height: 400px;
  place-content: center;
}

That's all it takes. Vertically centering is trivial.

Things we left out

The purpose of this article is to explain the fundamentals of CSS layout, but there are more concepts that can help you understand your layouts that we didn't cover:

Content sizing: how min-content, max-content and fit-content work, and how intrinsic sizing works.
Container queries: how they create new layout contexts.
Aspect-ratio: how it affects sizing of elements.
Subgrid: how it works and how it relates to grid.
Honestly, a deeper dive into both Flexbox and Grid.

Each of these topics deserve their own article and we might cover them in the future.

Conclusion

When you get started with CSS layout, it can feel overwhelming. There are a lot of concepts to learn, beyond the mere syntax and available properties. If you don't take the time to understand those concepts, you'll end up always fighting or guessing your way around designing pages.

CSS is built on a set of small, logical concepts that each are easy to understand, from "text goes left to right, top to bottom" to "everything is a box" to "elements can be taken outside of flow". Each layout algorithm builds upon these concepts, adding new ways to position and align elements to handle more and more complex situations. But the building blocks remain the same.

Understanding these building blocks of layout makes it easier to reason about CSS, to visualize how the browser is going to lay out your page and how to fix layout issues when they arise.

rarouš.w3b

Tech's empiricism problem

Nobody Gets Promoted for Simplicity

The Frontend Treadmill

A GitHub Issue Title Compromised 4,000 Developer Machines

The full chain

A botched rotation made it worse

The new pattern: AI installs AI

Why existing controls did not catch it

What Cline changed afterward

The architectural question

Container queries and units in action

Responsive typography with cqi units

Defining containers to measure in context

Explicit container queries

Transition grid templates and visibility

Non-Baseline animation enhancements

CSS @scope: An Alternative To Naming Conventions And Heavy Abstractions

Developers Lean More On Utilities #

The CSS @scope At-Rule #

Basic Usage #

More Benefits #

Conclusion #

Further Reading #

Your skip link targets don't need tabindex=-1 to work properly

Your skip link targets don't need tabindex=-1 to work properly

The original problem

The solution

Testing

Styling

Conclusion

Claude is an Electron App because we’ve lost native

Claude is an Electron App because we’ve lost native

Your car’s tire sensors could be used to track you

Your car’s tire sensors could be used to track you

Researchers at IMDEA Networks show standard tire sensors can expose drivers’ movements, raising privacy concerns

Please, please, please stop using passkeys for encrypting user data

How "Liquid Design" Broke the iPhone and Forced Apple’s Great Reset

The Death of Legibility: A Low-Vision Nightmare

The Performance Penalty: GPU-Driven Ego

The Uncanny Valley of Physics

The Alan Dye Departure and the Internal Revolt

The Rescue Mission: Stephen Lemay and “Solid Design”

Conclusion: Form Follows Nothing

Precompressed HTML at the Edge: Eleventy Meets Cloudflare Workers

Introduction

Caching

Compression

Concatenation

More compression

Why HTML Brotli matters?

Improved Web Performance

At scale, cost savings add up

Improved performance on slow and unstable mobile networks

It indirectly improves Core Web Vitals

Compression cost is paid once for static assets

Compression Size Examples v1

W3C HTML5 Specification (Single Page)

Nasa’s Astronomy Picture of the Day Archive

How is this different from my other compression posts?

What’s the point?

Compression Size Examples v2

W3C HTML5 Specification (Single Page)

Nasa’s Astronomy Picture of the Day Archive

Problems

Problem 1: URL Path vs Actual File Path Mismatch

Problem 2: A page full of Wingdings

My Approach

Step 1: Build-time compression

Step 2: Cloudflare Pages Function for content negotiation

Step 3: The Eleventy build uses Node.js zlib, for seamless integration

Implementation

Core compression utility

HTML compression post-build

Cloudflare Pages Function for content negotiation

Build lifecycle wiring

Other Technical details worth mentioning

Why encodeBody: 'manual' is required

Why Vary: Accept-Encoding and Cache-Control: no-transform matter

Incremental build optimisation (runtime check to skip unchanged files)

Responsive typography with `cqi` units

The CSS `@scope` At-Rule #

Why we need a Cloudflare Function instead of just the `_headers` file for HTML Brotli?

1. `_headers` can only change headers, not the file itself

`using`: cleanup, but make it the runtime’s job

When you need `await using`

When `using` isn’t enough