The lucky ones learn about it through a helpful code review or a proactive security lint rule. The diligent ones learn about it during a security audit that catches a vulnerability before it hits production.

Then, there are the scarred ones. They learn about it when a live exploit hits their site. When an attacker injects a script that steals session tokens from localStorage, hijacks cookies, or redirects users to a phishing site. I personally joined the “scarred” club back in 2005, when an embedded Flash signature in a forum I owned turned into a security nightmare… but that’s a story for another time.

In this article, we’re going to explore how the browser is finally taking the burden of sanitization off our shoulders with the new HTML Sanitizer API.

The Problem with innerHTML

To understand the solution, we have to look at the danger. In the early days of the web, innerHTML was the magic wand that turned strings into DOM elements.

const container = document.getElementById('content');
const userInput = '<img src="x" onerror="alert(\'XSS\')">';
container.innerHTML = userInput;

The moment that code runs, the browser tries to load a non-existent image, fails, and executes the onerror script. Congratulations, you’ve just been XSS’d.

The snippet above is a classic example of how unsanitized user input can lead to XSS vulnerabilities. Attackers usually ship payloads like this through several vectors:

• User-generated content: Comments, reviews, or any form of user input that gets rendered on the page. Usually, these inputs are stored in a database and rendered later. If the application doesn’t sanitize this input, it can lead to stored XSS vulnerabilities.
• URL parameters: Attackers can craft URLs with malicious payloads in query parameters. If the application reflects these parameters back into the page without proper sanitization, it can lead to reflected XSS vulnerabilities. For example, a search page that takes a query parameter and displays it on the page without sanitization can be exploited.

Historically, we solved this by pulling in DOMPurify. It’s the de facto library for sanitizing HTML in JavaScript. It works by parsing the input string, removing any dangerous elements or attributes, and returning a safe version of the HTML.

import DOMPurify from 'dompurify';

const container = document.getElementById('content');
const userInput = '<img src="x" onerror="alert(\'XSS\')">';
const sanitizedInput = DOMPurify.sanitize(userInput);

container.innerHTML = sanitizedInput;

Or if you were using React, you might have done something like the following, using dangerouslySetInnerHTML to render sanitized content:

import DOMPurify from 'dompurify';

function Comment({ content }) {
    const sanitizedContent = DOMPurify.sanitize(content);
    return <div dangerouslySetInnerHTML={{ __html: sanitizedContent }} />;
}

DOMPurify is a fantastic tool that excels at sanitization, but not without caveats. It ships ~23.3 kB minified (~8.71 kB gzipped), requires maintenance, and essentially repeats parsing HTML which is what the browser is already designed to do.

That last point is critical. DOMPurify-style libraries have always been a fragile approach. The parsing APIs exposed to the web don’t always map cleanly to how the browser actually renders a string as HTML in the “real” DOM. Worse, these libraries have to chase the browser’s evolving behavior over time because things that were once safe can turn into time-bombs the moment a new platform feature ships. That puts the maintainers in a permanent race against every browser release, and once a library reaches the size and reach of DOMPurify, that race turns into a full-time job. I imagine the maintainers will be quietly thrilled the day they get to wind it down. The browser, on the other hand, knows exactly when and how it’s going to execute code. Putting sanitization inside the browser means it stays in sync with the parser by definition.

The new HTML Sanitizer API

The web platform now includes new APIs that make parsing and sanitizing HTML much safer. The spec introduces safer ways to insert HTML into the DOM, beyond the old innerHTML approach.

The API gives us six methods, split into two families:

• Safe methods: Element.setHTML(), ShadowRoot.setHTML(), Document.parseHTML(). These always strip XSS-unsafe content, no matter what configuration you pass.
• Unsafe methods: Element.setHTMLUnsafe(), ShadowRoot.setHTMLUnsafe(), Document.parseHTMLUnsafe(). These do exactly what you tell them to, including allowing dangerous content if your config says so.

Let’s walk through them.

setHTML: The Safe Way to Insert HTML

The setHTML method is a new addition to the DOM API that allows developers to set HTML content in a way that is safe from XSS vulnerabilities. When you use setHTML, the browser automatically sanitizes the input, removing any potentially dangerous elements or attributes. It is safe by default. You still can configure it, but any configuration you pass will still not allow dangerous content to be rendered. It will always remove unsafe elements like <script> and on* attributes. It effectively overrides your settings if you try to be “too permissive”.

The simplest possible usage doesn’t even need to be configured. Just call setHTML with a string:

const maliciousInput = '<img src="x" onerror="alert(\'XSS\')">';
document.getElementById('content').setHTML(maliciousInput);

// Result: <img src="x"> the onerror attribute is stripped out, preventing the XSS attack.

That’s it. The script in the onerror attribute is gone because the browser handled the sanitization logic during the parsing phase, using its built-in default safe configuration. If you’re curious about exactly which elements and attributes the default config allows, MDN has the full default sanitizer configuration documented.

Configurable Sanitization

When you need more control, the spec lets us define a configuration object to specify which elements and attributes are allowed or blocked. It can be a bit tricky to get the configuration right as you can accidentally specify an element in both allow and block lists, or list an attribute multiple times. The API is strict about this: if you pass an invalid configuration object, it will throw a TypeError. This is to ensure that developers are aware of any contradictions or redundancies in their configuration.

Let’s take a look at an allow-list configuration:

const config = {
  elements: ["em", "strong", "b", "i", "ul", "li"],
  attributes: ["id"],
  replaceWithChildrenElements: ["span", "div"],
};
const customSanitizer = new Sanitizer(config);

The configuration above only allows a specific set of elements and attributes. Anything not in the allow list is stripped out. The replaceWithChildrenElements option lets you specify elements that should be replaced with their children instead of being removed entirely. So if a <div> shows up in the input, the <div> itself is dropped but its content stays.

Now a block-list configuration:

const config = {
  removeElements: ["span", "script"],
  removeAttributes: ["lang", "id", "class", "style"],
  comments: false,
};
const customSanitizer = new Sanitizer(config);

This configuration specifies elements and attributes that should be removed from the input. The comments option controls whether HTML comments are preserved. In this example, they’re removed.

You cannot have both elements and removeElements in the same configuration object, as they serve opposite purposes. The same applies to attributes and removeAttributes. If you try to include both, the API throws a TypeError. You can combine elements with removeAttributes, or removeElements with attributes, just not opposing pairs at the same level.

Notice that in both examples, we didn’t have to worry about dangerous attributes like inline event handlers (on*). This is what “safe by default” means. Even if you configure setHTML to allow certain elements or attributes, it will still block anything that could lead to an XSS vulnerability.

setHTMLUnsafe: The Escape Hatch

setHTMLUnsafe is the unsafe sibling. The cleanest way to think about the difference is this:

• With setHTML, your config is a further restriction on top of safe defaults. Unsafe stuff is always stripped, even if you explicitly allow it.
• With setHTMLUnsafe, your config is the complete rule. If you say allow onclick, onclick stays. Pass no config at all, and nothing is sanitized.

There are two main reasons to reach for it:

1. Declarative shadow roots. setHTML strips them as part of its safe defaults, so if you need them, setHTMLUnsafe is currently the only way.
2. Allowing specific “unsafe” attributes intentionally. Sometimes you genuinely need an inline handler or similar, and you want to opt in to exactly that one thing while still cleaning up the rest.

Here’s the contrast in code:

const input = "<img src=x onclick=alert('onclick') onerror=alert('onerror')>";

// setHTMLUnsafe with a custom config: onclick is allowed, onerror is still stripped
// (because we didn't list it in the config, not because the API enforces safety).
const lessSafeConfig = new Sanitizer({
  attributes: ["onclick"],
});
document.getElementById('output').setHTMLUnsafe(input, { sanitizer: lessSafeConfig });

onerror is removed because our allow-list doesn’t include it, not because setHTMLUnsafe enforces any safety on its own. If we’d written attributes: ["onclick", "onerror"], both would have made it through. With setHTML, that wouldn’t matter. onerror would be stripped regardless.

parseHTML and parseHTMLUnsafe: Sanitize Without Inserting

Sometimes you don’t want to insert HTML immediately. You want to parse it, inspect it, maybe transform it, and only then decide what to do with it. That’s what Document.parseHTML() and Document.parseHTMLUnsafe() are for.

const untrustedHTML = '<p>Hello <script>alert("xss")</script>world</p>';

// Returns a sanitized Document you can inspect, walk, or extract from
const doc = Document.parseHTML(untrustedHTML);
console.log(doc.body.innerHTML); // <p>Hello world</p>

parseHTML follows the same rules as setHTML; XSS-unsafe content is always stripped. parseHTMLUnsafe is its counterpart and behaves like setHTMLUnsafe; no sanitization unless you pass a sanitizer.

This is particularly useful for things like building a sanitized DocumentFragment once and reusing it, or running checks on the sanitized output before deciding whether to render it at all.

Real-World Use Cases

First, let’s be clear that even with the new API, backend sanitization is non-negotiable. Client-side sanitization is for the user’s experience and immediate safety. Anyone with sufficient knowledge can easily bypass your client-side code by calling your API directly. This is exactly like how we validate user input on the client for better UX, but still validate on the server for business logic and security.

In ShopTalkShow, episode 704, Dave Rupert and Chris Coyier invited Frederik Braun from Mozilla to talk about the HTML Sanitizer API. They discussed using Sanitizer API for Optimistic UI; the hot pattern in frontend development.

In a comment section, when a user hits “Post”, we usually rely on the backend to sanitize the comment, return it back to the browser, then render the response. This takes time and creates a less-than-optimal experience. Trusting raw user input and rendering it immediately can be risky, but with the new API, we can safely render the comment immediately while the backend is still processing. The result is a much smoother UX without compromising security.

import React, { useState, useRef, useEffect } from 'react';

type Comment = { id: number; content: string };

const sanitizerConfig = { elements: ["b", "i", "em", "ul", "li"] };
const sanitizer = new Sanitizer(sanitizerConfig);

function CommentItem({ html }: { html: string }) {
  const ref = useRef<HTMLLIElement>(null);

  useEffect(() => {
    if (!ref.current) return;
    if ('setHTML' in ref.current) {
      ref.current.setHTML(html, { sanitizer });
    } else {
      // Fallback for browsers without the API yet, ship DOMPurify,
      // or render a loading indicator until the sanitized response
      // comes back from the server.
      ref.current.textContent = html;
    }
  }, [html]);

  return <li ref={ref} />;
}

const CommentSection = () => {
  const [comments, setComments] = useState<Comment[]>([]);

  const handleSubmit = (userInput: string) => {
    // 1. Optimistic update - render immediately, safely
    const newComment = { id: Date.now(), content: userInput };
    setComments((prev) => [...prev, newComment]);

    // 2. Post to backend (still the source of truth)
    postComment(userInput);
  };

  return (
    <ul>
      {comments.map((comment) => (
        <CommentItem key={comment.id} html={comment.content} />
      ))}
    </ul>
  );
};

A few things worth calling out in that example:

• The Sanitizer is constructed once at module scope, not inside the component. Constructing it on every render is wasteful.
• The actual setHTML call is wrapped in a useEffect with feature detection, so the component degrades gracefully on browsers that haven’t shipped the API yet.
• We hand the <li> over to imperative DOM via the ref instead of mixing dangerouslySetInnerHTML with React’s diffing. That combo tends to cause hydration headaches.

This is the kind of place setHTML really shines. You can’t dangerouslySetInnerHTML an unsanitized string without inviting an XSS, and the API gives you a path that’s both ergonomic and safe.

There are plenty of other places where the API earns its keep:

• WYSIWYG editors. Users routinely write content in word processors and paste it in, dragging along massive, dirty HTML and inline styles. Listening to the paste event and running it through setHTML cleans things up before insertion.
• Live Markdown previews. When the input never even leaves the browser, you still want to sanitize the rendered HTML before showing it.
• External feeds. RSS, syndicated content, embedded snippets and anything coming from outside your origin should be sanitized before it touches the DOM.

Wrapping Up

The HTML Sanitizer API is a significant step forward in making web development safer and more efficient. It moves security from a “library concern” to a “platform primitive”. With that, we get better performance, smaller bundle sizes, and a more secure default behavior.

At the time of writing (May 2026), browser support is still early. Firefox 148 shipped the standardized API in February 2026 becoming the first browser to do so. Chrome has it in Canary behind a flag, and Safari hasn’t started implementation work yet, though the team has signaled a positive position. The feature is not yet Baseline, which means production usage today still needs feature detection and a fallback (DOMPurify is still the right backup).

The live status of the feature is shown below.

Thankfully, the web has always allowed us to use features before they become fully standardized or available. Use it as a progressive enhancement now, and keep an eye on the support tables. The day this becomes Baseline is the day a lot of bundles get a little smaller and a lot of apps get a little safer.

Recently, I’ve been losing my mind to hardcoded timeouts. Silent, arbitrary, unconfigurable time limits baked into tools by developers who apparently have never had to wait more than 200ms for anything in their lives.

Let me tell you about my week.

The skills Package and the 60-Second Clone

Now that coding agents are everywhere, everyone is using skills. The popular way to add them is through packages developed by vercel-labs, and the go-to collection is awesome-copilot, a curated set of skills sitting at 30K+ stars at the time of writing. Except I can’t use it. The repository is too big, and the npx skills installer just chokes and dies.

There’s an open issue about this since February #278 on the vercel-labs/skills repo and no one has responded. I’d be happy to send a PR and fix it myself. I just need someone to acknowledge it exists.

Is there a configuration option? A --timeout flag? An environment variable? No, there is nothing.

The workaround I found? Clone the repo manually first, then install from the local copy. It works, mostly. Except now skills-lock.json points to a path on my machine. My colleagues cannot use it. I also have to update my copy everytime I want update my skills. One workaround creates a lot of other problems.

Docker Gordon and the 2-Minute Death Timer

Then came Docker Gordon, the AI-powered debugging assistant baked into Docker. Useful concept. I was stepping through a container build issue, the kind that requires iteration: tweak, rebuild, inspect, repeat. I’ve never used Gordon but when the error manifested itself, it came with a suggestion to try Gordon and so I did.

Except Gordon has a hard limit: if your container doesn’t finish building within two minutes, it gives up. The session dies. You start over.

A two-minute build might sound like plenty if you’re in a fast environment with warm caches and pulled base images. But if you’re pulling a fresh base image over a slower connection? Debugging a multi-stage build with several heavy layers? Forget it. Gordon has already moved on.

There is no way to configure this. No GORDON_TIMEOUT=600 env var. No --build-timeout flag. Nothing. The tool just assumes that two minutes is forever, and if you need more, that’s your problem.

The Pattern That’s Driving Me Crazy

Developers often working on fast machines, in offices or homes with gigabit connections, in cities with world-class infrastructure. They build tools with timeout defaults that reflect their own experience. And then they ship those tools to the whole world, with no knobs to turn.

The thing is, timeouts need to exist. Infinite waits are bad. Hanging processes are bad. I’m not arguing against timeouts. I’m arguing against unconfigurable timeouts. Against the implicit message that says: if you can’t do this in 60 seconds, your environment is wrong, not my assumption.

A timeout should be:

• A safe default for the common case
• Clearly documented so users know it exists
• Overridable via a flag, an environment variable, a config file, something

This isn’t hard. It’s respect for your users.

The World Isn’t a Data Center in Virginia

I’m writing this from Cairo. My internet is decent, better than many places in the world. But it’s not 1 Gbps symmetric fiber. It’s not co-located next to an npm registry mirror. A git clone of a large repo takes time. Pulling a Docker image takes time. These are not failures. They are physics.

When your tool dies silently after 60 seconds without any way to change that limit, you haven’t built a tool for the world. You’ve built a tool for your office.

And this matters more than most developers acknowledge. The global developer community isn’t located in San Francisco or Amsterdam or London. It’s in Lagos, in Karachi, in Cairo. It’s people on 4G connections, on shared broadband, on connections that have real latency because the nearest CDN edge is 50ms away instead of 5.

When you assume a fast connection, you’re not making a neutral technical decision. You’re making a statement about whose experience matters.

A Note to Tool Authors

I don’t think anyone is doing this maliciously. I think it’s a blind spot. Your internet is fast, so a 60-second timeout feels generous. Your machines are powerful, so a 2-minute build window seems like plenty.

But please: before you ship a timeout, ask yourself:

• What if the user is on a slower connection?
• What if their repo is larger than mine?
• What if they’re debugging something slow, and that’s the whole point?

And then add a config option. One environment variable. One flag. That’s all it takes to go from “this tool doesn’t work for me” to “this tool works for me.”

As Bruce Lawson once said: it’s the World Wide Web, not the Wealthy Western Web.

The web and the tools we build on top of it are for everyone. Let’s start acting like it.

/* https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+css-extras+markdown+scss+sql&plugins=line-highlight+line-numbers+autolinker */

I had completely forgotten about this. I clicked the URL, and it was the PrismJS download page with every checkbox, dropdown, and option pre-selected to match my exact configuration. Themes chosen. Languages selected. Plugins enabled. Everything, perfectly reconstructed from that single URL.

It was one of those moments where something you once knew suddenly clicks again with fresh significance. Here was a URL doing far more than just pointing to a page. It was storing state, encoding intent, and making my entire setup shareable and recoverable. No database. No cookies. No localStorage. Just a URL.

This got me thinking: how often do we, as frontend engineers, overlook the URL as a state management tool? We reach for all sorts of abstractions to manage state such as global stores, contexts, and caches while ignoring one of the web’s most elegant and oldest features: the humble URL.

In my previous article, I wrote about the hidden costs of bad URL design. Today, I want to flip that perspective and talk about the immense value of good URL design. Specifically, how URLs can be treated as first-class state containers in modern web applications.

The Overlooked Power of URLs

Scott Hanselman famously said “URLs are UI” and he’s absolutely right. URLs aren’t just technical addresses that browsers use to fetch resources. They’re interfaces. They’re part of the user experience.

But URLs are more than UI. They’re state containers. Every time you craft a URL, you’re making decisions about what information to preserve, what to make shareable, and what to make bookmarkable.

Think about what URLs give us for free:

• Shareability: Send someone a link, and they see exactly what you see
• Bookmarkability: Save a URL, and you’ve saved a moment in time
• Browser history: The back button just works
• Deep linking: Jump directly into a specific application state

URLs make web applications resilient and predictable. They’re the web’s original state management solution, and they’ve been working reliably since 1991. The question isn’t whether URLs can store state. It’s whether we’re using them to their full potential.

Before we dive into examples, let’s break down how URLs encode state. Here’s a typical stateful URL:

For many years, these were considered the only components of a URL. That changed with the introduction of Text Fragments, a feature that allows linking directly to a specific piece of text within a page. You can read more about it in my article Smarter than ‘Ctrl+F’: Linking Directly to Web Page Content.

Different parts of the URL encode different types of state:

1. Path Segments (/path/to/myfile.html). Best used for hierarchical resource navigation:
   • /users/123/posts - User 123’s posts
   • /docs/api/authentication - Documentation structure
   • /dashboard/analytics - Application sections
2. Query Parameters (?key1=value1&key2=value2). Perfect for filters, options, and configuration:
   • ?theme=dark&lang=en - UI preferences
   • ?page=2&limit=20 - Pagination
   • ?status=active&sort=date - Data filtering
   • ?from=2025-01-01&to=2025-12-31 - Date ranges
3. Anchor Fragment (#SomewhereInTheDocument). Ideal for client-side navigation and page sections:
   • #L20-L35 - GitHub line highlighting
   • #features - Scroll to section
   • #/dashboard - Single-page app routing (though it’s rarely used these days)

Common Patterns That Work for Query Parameters

Multiple values with delimiters

Sometimes you’ll see multiple values packed into a single key using delimiters like commas or plus signs. It’s compact and human-readable, though it requires manual parsing on the server side.

?languages=javascript+typescript+python
?tags=frontend,react,hooks

Nested or structured data

Developers often encode complex filters or configuration objects into a single query string. A simple convention uses key–value pairs separated by commas, while others serialize JSON or even Base64-encode it for safety.

?filters=status:active,owner:me,priority:high
?config=eyJyaWNrIjoicm9sbCJ9==  (base64-encoded JSON)

Boolean flags

For flags or toggles, it’s common to pass booleans explicitly or to rely on the key’s presence as truthy. This keeps URLs shorter and makes toggling features easy.

?debug=true&analytics=false
?mobile  (presence = true)

Arrays (Bracket notation)

?tags[]=frontend&tags[]=react&tags[]=hooks

Another old pattern is bracket notation, which represents arrays in query parameters. It originated from early web frameworks like PHP where appending [] to a parameter name signals that multiple values should be grouped together.

?tags[]=frontend&tags[]=react&tags[]=hooks
?ids[0]=42&ids[1]=73

Many modern frameworks and parsers (like Node’s qs library or Express middleware) still recognize this pattern automatically. However, it’s not officially standardized in the URL specification, so behavior can vary depending on the server or client implementation. Notice how it even breaks the syntax highlighting on my website.

The key is consistency. Pick patterns that make sense for your application and stick with them.

State via URL Parameters

Let’s look at real-world examples of URLs as state containers:

PrismJS Configuration

https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript&plugins=line-numbers

The entire syntax highlighter configuration encoded in the URL. Change anything in the UI, and the URL updates. Share the URL, and someone else gets your exact setup. This one uses anchor and not query parameters, but the concept is the same.

GitHub Line Highlighting

https://github.com/zepouet/Xee-xCode-4.5/blob/master/XeePhotoshopLoader.m#L108-L136

It links to a specific file while highlighting lines 108 through 136. Click this link anywhere, and you’ll land on the exact code section being discussed.

Google Maps

https://www.google.com/maps/@22.443842,-74.220744,19z

Coordinates, zoom level, and map type all in the URL. Share this link, and anyone can see the exact same view of the map.

Figma and Design Tools

https://www.figma.com/file/abc123/MyDesign?node-id=123:456&viewport=100,200,0.5

Before shareable design links, finding an updated screen or component in a large file was a chore. Someone had to literally show you where it lived, scrolling and zooming across layers. Today, a Figma link carries all that context like canvas position, zoom level, selected element. Literally everything needed to drop you right into the workspace.

E-commerce Filters

https://store.com/laptops?brand=dell+hp&price=500-1500&rating=4&sort=price-asc

This is one of the most common real-world patterns you’ll encounter. Every filter, sort option, and price range preserved. Users can bookmark their exact search criteria and return to it anytime. Most importantly, they can come back to it after navigating away or refreshing the page.

Frontend Engineering Patterns

Before we discuss implementation details, we need to establish a clear guideline for what should go into the URL. Not all state belongs in URLs. Here’s a simple heuristic:

Good candidates for URL state:

• Search queries and filters
• Pagination and sorting
• View modes (list/grid, dark/light)
• Date ranges and time periods
• Selected items or active tabs
• UI configuration that affects content
• Feature flags and A/B test variants

Poor candidates for URL state:

• Sensitive information (passwords, tokens, PII)
• Temporary UI states (modal open/closed, dropdown expanded)
• Form input in progress (unsaved changes)
• Extremely large or complex nested data
• High-frequency transient states (mouse position, scroll position)

If you are not sure if a piece of state belongs in the URL, ask yourself: If someone else clicking this URL, should they see the same state? If so, it belongs in the URL. If not, use a different state management approach.

Implementation using Plain JavaScript

The modern URLSearchParams API makes URL state management straightforward:

// Reading URL parameters
const params = new URLSearchParams(window.location.search);
const view = params.get('view') || 'grid';
const page = params.get('page') || 1;

// Updating URL parameters
function updateFilters(filters) {
  const params = new URLSearchParams(window.location.search);

  // Update individual parameters
  params.set('status', filters.status);
  params.set('sort', filters.sort);

  // Update URL without page reload
  const newUrl = `${window.location.pathname}?${params.toString()}`;
  window.history.pushState({}, '', newUrl);

  // Now update your UI based on the new filters
  renderContent(filters);
}

// Handling back/forward buttons
window.addEventListener('popstate', () => {
  const params = new URLSearchParams(window.location.search);
  const filters = {
    status: params.get('status') || 'all',
    sort: params.get('sort') || 'date'
  };
  renderContent(filters);
});

The popstate event fires when the user navigates with the browser’s Back or Forward buttons. It lets you restore the UI to match the URL, which is essential for keeping your app’s state and history in sync. Usually your framework’s router handles this for you, but it’s good to know how it works under the hood.

Implementation using React

React Router and Next.js provide hooks that make this even cleaner:

import { useSearchParams } from 'react-router-dom';
// or for Next.js 13+: import { useSearchParams } from 'next/navigation';

function ProductList() {
  const [searchParams, setSearchParams] = useSearchParams();

  // Read from URL (with defaults)
  const color = searchParams.get('color') || 'all';
  const sort = searchParams.get('sort') || 'price';

  // Update URL
  const handleColorChange = (newColor) => {
    setSearchParams(prev => {
      const params = new URLSearchParams(prev);
      params.set('color', newColor);
      return params;
    });
  };

  return (
    <div>
      <select value={color} onChange={e => handleColorChange(e.target.value)}>
        <option value="all">All Colors</option>
        <option value="silver">Silver</option>
        <option value="black">Black</option>
      </select>

      {/* Your filtered products render here */}
    </div>
  );
}

Best Practices for URL State Management

Now that we’ve seen how URLs can hold application state, let’s look at a few best practices that keep them clean, predictable, and user-friendly.

Handling Defaults Gracefully

Don’t pollute URLs with default values:

// Bad: URL gets cluttered with defaults
?theme=light&lang=en&page=1&sort=date

// Good: Only non-default values in URL
?theme=dark  // light is default, so omit it

Use defaults in your code when reading parameters:

function getTheme(params) {
  return params.get('theme') || 'light'; // Default handled in code
}

Debouncing URL Updates

For high-frequency updates (like search-as-you-type), debounce URL changes:

import { debounce } from 'lodash';

const updateSearchParam = debounce((value) => {
  const params = new URLSearchParams(window.location.search);
  if (value) {
    params.set('q', value);
  } else {
    params.delete('q');
  }
  window.history.replaceState({}, '', `?${params.toString()}`);
}, 300);

// Use replaceState instead of pushState to avoid flooding history

pushState vs. replaceState

When deciding between pushState and replaceState, think about how you want the browser history to behave. pushState creates a new history entry, which makes sense for distinct navigation actions like changing filters, pagination, or navigating to a new view — users can then use the Back button to return to the previous state. On the other hand, replaceState updates the current entry without adding a new one, making it ideal for refinements such as search-as-you-type or minor UI adjustments where you don’t want to flood the history with every keystroke.

URLs as Contracts

When designed thoughtfully, URLs become more than just state containers. They become contracts between your application and its consumers. A good URL defines expectations for humans, developers, and machines alike

Clear Boundaries

A well-structured URL draws the line between what’s public and what’s private, client and server, shareable and session-specific. It clarifies where state lives and how it should behave. Developers know what’s safe to persist, users know what they can bookmark, and machines know whats worth indexing.

URLs, in that sense, act as interfaces: visible, predictable, and stable.

Communicating Meaning

Readable URLs explain themselves. Consider the difference between the two URLs below.

https://example.com/p?id=x7f2k&v=3
https://example.com/products/laptop?color=silver&sort=price

The first one hides intent. The second tells a story. A human can read it and understand what they’re looking at. A machine can parse it and extract meaningful structure.

Jim Nielsen calls these “examples of great URLs”. URLs that explain themselves.

Caching and Performance

URLs are cache keys. Well-designed URLs enable better caching strategies:

• Same URL = same resource = cache hit
• Query params define cache variations
• CDNs can cache intelligently based on URL patterns

You can even visualize a user’s journey without any extra tracking code:

graph LR
  A["/products"] --> |selects category| B["/products?category=laptops"]
  B --> |adds price filter| C["/products?category=laptops&price=500-1000"]

  style A fill:#e9edf7,stroke:#455d8d,stroke-width:2px;
  style B fill:#e9edf7,stroke:#455d8d,stroke-width:2px;
  style C fill:#e9edf7,stroke:#455d8d,stroke-width:2px;

Your analytics tools can track this flow without additional instrumentation. Every URL parameter becomes a dimension you can analyze.

Versioning and Evolution

URLs can communicate API versions, feature flags, and experiments:

?v=2                   // API version
?beta=true             // Beta features
?experiment=new-ui     // A/B test variant

This makes gradual rollouts and backwards compatibility much more manageable.

Anti-Patterns to Avoid

Even with the best intentions, it’s easy to misuse URL state. Here are common pitfalls:

“State Only in Memory” SPAs

The classic single-page app mistake:

// User hits refresh and loses everything
const [filters, setFilters] = useState({});

If your app forgets its state on refresh, you’re breaking one of the web’s fundamental features. Users expect URLs to preserve context. I remember a viral video from years ago where a Reddit user vented about an e-commerce site: every time she hit “Back,” all her filters disappeared. Her frustration summed it up perfectly. If users lose context, they lose patience.

Sensitive Data in URLs

This one seems obvious, but it’s worth repeating:

// NEVER DO THIS
?password=secret123

URLs are logged everywhere: browser history, server logs, analytics, referrer headers. Treat them as public.

Inconsistent or Opaque Naming

// Unclear and inconsistent
?foo=true&bar=2&x=dark

// Self-documenting and consistent
?mobile=true&page=2&theme=dark

Choose parameter names that make sense. Future you (and your team) will thank you.

Overloading URLs with Complex State

?config=eyJtZXNzYWdlIjoiZGlkIHlvdSByZWFsbHkgdHJpZWQgdG8gZGVjb2RlIHRoYXQ_IiwiZmlsdGVycyI6eyJzdGF0dXMiOlsiYWN0aXZlIiwicGVuZGluZyJdLCJwcmlvcml0eSI6WyJoaWdoIiwibWVkaXVtIl0sInRhZ3MiOlsiZnJvbnRlbmQiLCJyZWFjdCIsImhvb2tzIl0sInJhbmdlIjp7ImZyb20iOiIyMDI0LTAxLTAxIiwidG8iOiIyMDI0LTEyLTMxIn19LCJzb3J0Ijp7ImZpZWxkIjoiY3JlYXRlZEF0Iiwib3JkZXIiOiJkZXNjIn0sInBhZ2luYXRpb24iOnsicGFnZSI6MSwibGltaXQiOjIwfX0==

If you need to base64-encode a massive JSON object, the URL probably isn’t the right place for that state.

URL Length Limits

Browsers and servers impose practical limits on URL length (usually between 2,000 and 8,000 characters) but the reality is more nuanced. As this detailed Stack Overflow answer explains, limits come from a mix of browser behavior, server configurations, CDNs, and even search engine constraints. If you’re bumping against them, it’s a sign you need to rethink your approach.

Breaking the Back Button

// Replacing state incorrectly
history.replaceState({}, '', newUrl); // Used when pushState was needed

Respect browser history. If a user action should be “undoable” via the back button, use pushState. If it’s a refinement, use replaceState.

Closing Thought

That PrismJS URL reminded me of something important: good URLs don’t just point to content. They describe a conversation between the user and the application. They capture intent, preserve context, and enable sharing in ways that no other state management solution can match.

We’ve built increasingly sophisticated state management libraries like Redux, MobX, Zustand, Recoil and others. They all have their place but sometimes the best solution is the one that’s been there all along.

In my previous article, I wrote about the hidden costs of bad URL design. Today, we’ve explored the flip side: the immense value of good URL design. URLs aren’t just addresses. They’re state containers, user interfaces, and contracts all rolled into one.

If your app forgets its state when you hit refresh, you’re missing one of the web’s oldest and most elegant features.

This decision, which was made hastily and without proper discussion, would later cost us hours spent on optimization.

The problem wasn’t the URLs themselves. It was that we treated URL design as a UX decision when it’s fundamentally an architectural decision with cascading technical implications. Every request to the application triggered two backend API calls. Every bot crawling a malformed URL hit the database twice. Every 404 was expensive.

This article isn’t about URL best practices you’ve read a hundred times (keeping URLs short, avoiding special characters, or using hyphens instead of underscores). This is about something rarely discussed: how your URL structure shapes your entire application architecture, performance characteristics, and operational costs.

The Deceptive Simplicity of “Clean URLs”

Flat URLs like /summer-collection or /running-shoes feel right. They’re intuitive, readable, and align with how users think about content. No technical jargon, no hierarchy to remember. This design philosophy emerged from the SEO community’s consensus that simpler URLs perform better in search rankings.

But here’s what the SEO guides don’t tell you: flat URLs trade determinism for aesthetics.

When your URL is /leather-jacket, your application cannot know whether you’re requesting:

• A product named “Leather Jacket”
• A category called “Leather Jacket”
• A blog post titled “Leather Jacket”
• A landing page for a “Leather Jacket” campaign
• Nothing at all (a 404)

This ambiguity means your application must ask rather than know. And asking is expensive.

The CMS Advantage: URL Resolution Tables

Many traditional CMSs solved this problem decades ago. Systems like Joomla, WordPress (to some extent), and Drupal maintain dedicated SEF (Search Engine Friendly) URL tables which are essentially lookup dictionaries that map clean URLs to their corresponding entity types and IDs.

When you request /leather-jacket, these systems do a single, fast database lookup:

SELECT entity_type, entity_id FROM url_rewrites WHERE url_path = 'leather-jacket'

One query, instant resolution, minimal overhead. The URL ambiguity is resolved at the database layer with an indexed lookup rather than through sequential API calls.

But not every system works this way. In our case, Magento’s API architecture didn’t expose a unified URL resolution endpoint. The frontend had to query separate endpoints for products and categories, which brings us to our problem.

When “Clean” Becomes “Costly”

In a structured URL system (/product/leather-jacket), the routing decision is instant:

path = "/product/leather-jacket"
prefix = path.split("/")[1]  // "product"
// Route to product handler immediately

In a flat URL system, you need a resolver:

path = "/leather-jacket"
slug = path.split("/")[1]

// Now what? We have to ask the database...
isProduct = await checkIfProduct(slug)
if (isProduct) return renderProduct()

isCategory = await checkIfCategory(slug)
if (isCategory) return renderCategory()

return render404()

This might seem like a minor difference, a few extra database queries. But let’s see what this actually costs at scale.

The Two-Request Problem

Our stack for this particular client consisted of a Nuxt.js frontend (running in SSR mode) and a Magento backend. Every URL that hit the application went through this flow:

The Original Architecture

User requests: /nike-air-zoom. Then, Nuxt SSR Server would query Magento API twice to confirm what the slug represented. If neither existed, it returned a 404.

sequenceDiagram
    participant User
    participant Nuxt as Nuxt SSR Server
    participant Backend as Magento API

    Note over User,Backend: Every Request (Product, Category, or 404)

    User->>Nuxt: GET /running-shoes

    Note over Nuxt: Check both endpoints concurrently
    par Product Check
        Nuxt->>Backend: getProductBySlug("running-shoes")
        Backend-->>Nuxt: Not found (404)
    and Category Check
        Nuxt->>Backend: getCategoryBySlug("running-shoes")
        Backend-->>Nuxt: Category found!
    end

    Nuxt-->>User: Rendered category page
    Note over Nuxt,Backend: Total: 2 concurrent backend calls (~50ms)

    rect rgb(255, 200, 200)
        Note over User,Backend: Invalid URL Example
        User->>Nuxt: GET /invalid-page
        par Product Check
            Nuxt->>Backend: getProductBySlug("invalid-page")
            Backend-->>Nuxt: Not found (404)
        and Category Check
            Nuxt->>Backend: getCategoryBySlug("invalid-page")
            Backend-->>Nuxt: Not found (404)
        end
        Nuxt-->>User: 404 page
        Note over Nuxt,Backend: Total: 2 backend calls for nothing!
    end

The diagram makes the inefficiency obvious:

• Every valid page required 2 backend lookups (one fails, one succeeds)
• Every invalid URL triggered 2 backend lookups (both fail)
• Every crawler generated 2 database queries per attempt

The Math: Why This Compounds

Let’s say we have:

• 100,000 page views per day
• 30% of traffic is bots/crawlers hitting invalid URLs
• Average API latency: 50ms per call

This will be translated to:

• Daily backend calls: 100,000 × 2 = 200,000 requests
• Bot overhead: 30,000 × 2 = 60,000 wasted requests
• Added latency per request: 100ms (2 × 50ms)

Now scale this during a traffic spike, say Black Friday or a major product launch. Our backend autoscaling would kick in, spinning up new instances to handle what was essentially artificial load created by our URL design.

Real Impact

We observed:

• Latency: P95 response times during peak traffic reached 800ms-1.2s
• Compute costs: Backend infrastructure costs were 40% higher than projected
• Vulnerability: During bot attacks or crawler storms, the 2x request multiplier meant we were essentially DDoSing ourselves

The kicker? This wasn’t a bug. This was the architecture working exactly as designed.

The Collision Problem

There’s another subtle issue: in systems without slug uniqueness constraints, a product and category could both use the same slug. Now your resolver doesn’t just need to check what exists. It needs to decide which one to serve. Do you prioritize products? Categories? First-created wins? This ambiguity isn’t just a performance problem; it’s a business logic problem. If a user comes from a marketing email expecting a product but lands on a category page instead, that’s a conversion lost.

Do You Have This Problem?

You might be experiencing this issue if:

• Your application serves multiple entity types (products, categories, pages, posts) from flat URLs
• You’re using a headless/API-first architecture without unified URL resolution
• Your APM/monitoring shows 2+ similar backend queries per page request
• 404 pages have similar latency to valid pages (they shouldn’t)
• Bot traffic causes disproportionate backend load
• Backend autoscaling triggers don’t correlate with actual user traffic patterns

If you checked 3 or more of these, keep reading. Your URLs might be costing you more than you think.

How we solved that problem

Faced with this problem on a platform with 100k+ SKUs, we had to choose a solution that balanced performance gains with implementation reality. URL restructuring with 301 redirects would be a massive undertaking. Maintaining redirect maps for that many products, ensuring no SEO disruption, and coordinating the migration was simply too risky and resource-intensive.

Instead, we implemented a two-part solution that leveraged what we already had and made smart optimizations where it mattered most.

Part 1: Server-Side Resolution (First Load)

We realized the Nuxt server already cached the category tree for building navigation menus. Categories don’t change frequently, so this cache was stable and reliable. We modified the URL resolver to:

1. Check cached categories first - If the slug matches a cached category, route directly to category handler (in-memory lookup, ~1ms)
2. Query products if not a category - Only make one API call to check if it’s a product
3. Return 404 if neither - No entity found, render 404 page

Result: We went from 2 backend calls per request to just 1 for product pages, and 0 additional calls for category pages (they already hit the cache). Categories resolved instantly, products required only one API call instead of two.

Part 2: Client-Side Routing (Internal Navigation)

Here’s the key insight: when users navigate within the application, we already know what they clicked on. A product card knows it’s linking to a product. A category menu knows it’s linking to a category.

We updated all internal links to include a simple query parameter:

<!-- Product card -->
<NuxtLink :to="{ path: `/product.slug`, query: { t: 'p' } }">
  Product Name
</NuxtLink>

<!-- Category menu -->
<NuxtLink :to="{ path: `/category.slug`, query: { t: 'c' } }">
  Category Name
</NuxtLink>

Then in the route middleware:

export default defineNuxtRouteMiddleware((to) => {
  const type = to.query.t

  if (type === 'p') {
    // Fetch product data directly on client-side
    return fetchProductData(to.params.slug)
  } else if (type === 'c') {
    // Fetch category data directly on client-side
    return fetchCategoryData(to.params.slug)
  }

  // No type hint - fallback to SSR resolution
  // (direct access, external links, shared URLs)
})

Result: Internal navigation happens purely on the client side with direct API calls. The server-side resolver is only used for:

• Direct URL access (user types URL or bookmarks)
• External links (social media, search engines, emails)
• First page load

Since most traffic after the initial landing is internal navigation, this reduced our server-side resolution load by approximately 70-80%.

The Combined Impact

Before optimization:

• Every request: 2 backend API calls
• Average response time: 800ms-1.2s (P95)
• Backend costs: 40% over projection

After optimization:

• Category pages (initial load): 0 additional backend calls (cached)
• Product pages (initial load): 1 backend call (50% reduction)
• Internal navigation: 0 server-side resolution (pure client-side)
• Average response time: 200-400ms (P95)
• Backend costs: Reduced by ~35%

Why This Worked for Us

This solution had several advantages for our specific context:

1. No URL changes - No redirects, no SEO impact, no user confusion
2. Leveraged existing infrastructure - The category cache was already there
3. Progressive enhancement - External/shared URLs still work perfectly (clean, no query params visible)
4. Low implementation effort - Mostly frontend changes, minimal backend work
5. Immediate impact - Deployed in one day. We didn’t have to wait for any changes to backend APIs.

The query parameter approach might seem inelegant, but remember: these parameters only appear during internal navigation within the SPA. When users share links or search engines crawl, they see clean URLs like /nike-air-zoom. The ?t=p only exists in the client-side routing context.

Here’s how requests are handled in our optimized system:

sequenceDiagram
    participant User
    participant Nuxt as Nuxt SSR Server
    participant Cache as Server Cache
    participant Backend as Magento API

    Note over User,Backend: Scenario 1: Initial Page Load (Direct Access)

    User->>Nuxt: GET /running-shoes
    Nuxt->>Cache: Check if slug exists in category cache

    alt Slug is cached category
        Cache-->>Nuxt: Category found
        Nuxt->>Backend: Fetch category data
        Backend-->>Nuxt: Category details
        Nuxt-->>User: Rendered category page
        Note over Nuxt: Total: 1 backend call
    else Slug not in cache
        Cache-->>Nuxt: Not found
        Nuxt->>Backend: Check if product exists
        alt Product exists
            Backend-->>Nuxt: Product details
            Nuxt-->>User: Rendered product page
            Note over Nuxt: Total: 1 backend call
        else Product doesn't exist
            Backend-->>Nuxt: Not found
            Nuxt-->>User: 404 page
            Note over Nuxt: Total: 1 backend call
        end
    end

    Note over User,Backend: Scenario 2: Internal Navigation (SPA)

    User->>Nuxt: Click product link
/nike-air-zoom?t=p
    Note over Nuxt: Query param indicates type
    Nuxt->>Backend: Fetch product data (client-side)
    Backend-->>Nuxt: Product details
    Nuxt-->>User: Rendered product page
    Note over Nuxt: Server-side resolver bypassed

Design Principles for New Projects

If you’re starting fresh, you have the luxury of making informed decisions before the first line of code. Here’s what we wish we’d known and what we now recommend to clients.

Principle 1: Start with Structure, Relax Later if Needed

Default to deterministic URLs unless you have a compelling reason not to. Good starting point:

/product/leather-jacket
/category/outerwear
/page/about-us

It’s far easier to remove structure later (with redirects) than to add it. Going from /product/shoes to /shoes is a simple 301. Going the other direction means updating every existing URL, redirecting old URLs, potential SEO turbulence, and user confusion with bookmarks.

Principle 2: Match URLs to Backend Capabilities

Before finalizing your URL scheme, ask:

Questions to answer:

• Does our backend provide unified URL resolution? (SEF tables, single endpoint)
• Can we query by slug across all entity types efficiently?
• What’s the database query cost for “does this slug exist?”

Decision matrix:

• Backend has SEF tables → Flat URLs viable
• Backend has separate endpoints → Structured URLs recommended
• Backend has no resolution → Build it or use structure

Principle 3: Budget for the Hidden Costs

When choosing flat URLs, explicitly budget for:

Infrastructure:

• Cache layer to store resolved slugs
• Additional backend capacity for resolution queries

Development time:

• Building resolution logic
• Maintaining slug uniqueness
• Implementing cache invalidation
• Debugging cache consistency issues

These aren’t failures. They’re the actual cost of flat URLs. If the business value (SEO, UX, brand consistency) exceeds these costs, great. But make the trade-off explicit rather than discovering it six months in.

Principle 4: Enforce Slug Uniqueness Across Types

If you do use flat URLs, make slug uniqueness a hard constraint at the database or application level. This prevents the slug collision problem entirely. Yes, it means occasionally appending numbers, using prefixes or rejecting slugs. It’s far better than ambiguous runtime behavior.

Principle 5: Document the Decision

Whatever you choose, document why using an Architecture Decision Record (ADR):

## URL Design Decision (2025-10-12)

**Choice:** Structured URLs (/product/{slug}, /category/{slug})

**Rationale:**
- Backend (Magento) has separate product/category APIs
- Expected traffic: 100k+ requests/day at launch
- Team familiarity: reduces onboarding complexity
- Caching: enables smart CDN rules

**Trade-offs accepted:**
- Slightly longer URLs

**Revisit when:**
- Backend adds unified resolution endpoint
- Traffic patterns justify optimization cost

Future developers (including future you) will thank you.

Final Thoughts

We should treat URL structure as a public API contract. Like any API, URLs:

• Define how clients (users, bots, search engines) interact with your system
• Create expectations that are expensive to break
• Have performance characteristics that affect the entire stack
• Must be versioned carefully (via redirects) if changed
• Should be designed with both current and future capabilities in mind

URL structure decisions are cheapest and most flexible at the start of a project (ideally in week one) when a quick discussion can define the architecture with little cost. Once development begins, changes require some rework but are still manageable. After launch, however, even minor adjustments trigger a chain reaction involving redirects, SEO checks, and cache updates. By the time scaling issues appear, restructuring URLs becomes a complex, time-consuming, and costly endeavor. Before finalizing URLs, bring together:

• Frontend team: What’s cleanest for users?
• Backend team: What can we resolve efficiently?
• DevOps: What are the caching implications?
• SEO/Marketing: What’s the measurable impact?

The takeaway: invest early in thoughtful URL design to avoid expensive fixes later.

“What the hell is this?” he asked. “What are all these generated class names? Did we just… cancel the cascade? Who made the web work this way?”

I laughed, but his confusion cut deeper than he realized. He remembered a web where CSS cascaded naturally, where the DOM was something you worked with, where the browser handled routing, forms, and events without twenty abstractions in between. To him, our modern frontend stack looked like we’d declared war on the platform itself.

He asked me to explain how we got here. That conversation became this essay.

A disclaimer before we begin: This is one perspective, shaped by having lived through the first browser war. I applied pngfix.js to make 24-bit PNGs work in IE6. I debugged hasLayout bugs at 2 AM. I wrote JavaScript when you couldn’t trust addEventListener to work the same way across browsers. I watched jQuery become necessary, then indispensable, then legacy. I might be wrong about some of this. My perspective is biased for sure, but it also comes with the memory that the web didn’t need constant reinvention to be useful.

Introduction

There’s a strange irony at the heart of modern web development. The web was born from documents, hyperlinks, and a cascading stylesheet language. It was always messy, mutable, and gloriously side-effectful. Yet over the past decade, our most influential frontend tools have been shaped by engineers chasing functional programming purity: immutability, determinism, and the elimination of side effects.

This pursuit gave us powerful abstractions. React taught us to think in components. Redux made state changes traceable. TypeScript brought compile-time safety to a dynamic language. But it also led us down a strange path. A one where we fought against the platform instead of embracing it. We rebuilt the browser’s native capabilities in JavaScript, added layers of indirection to “protect” ourselves from the DOM, and convinced ourselves that the web’s inherent messiness was a problem to solve rather than a feature to understand.

The question isn’t whether functional programming principles have value. They do. The question is whether applying them dogmatically to the web (a platform designed around mutability, global scope, and user-driven chaos) made our work better, or just more complex.

The Nature of the Web

To understand why functional programming ideals clash with web development, we need to acknowledge what the web actually is.

The web is fundamentally side-effectful. CSS cascades globally by design. Styles defined in one place affect elements everywhere, creating emergent patterns through specificity and inheritance. The DOM is a giant mutable tree that browsers optimize obsessively; changing it directly is fast and predictable. User interactions arrive asynchronously and unpredictably: clicks, scrolls, form submissions, network requests, resize events. There’s no pure function that captures “user intent.”

This messiness is not accidental. It’s how the web scales across billions of devices, remains backwards-compatible across decades, and allows disparate systems to interoperate. The browser is an open platform with escape hatches everywhere. You can style anything, hook into any event, manipulate any node. That flexibility and that refusal to enforce rigid abstractions is the web’s superpower.

When we approach the web with functional programming instincts, we see this flexibility as chaos. We see globals as dangerous. We see mutation as unpredictable. We see side effects as bugs waiting to happen. And so we build walls.

Enter Functional Programming Ideals

Functional programming revolves around a few core principles: functions should be pure (same inputs → same outputs, no side effects), data should be immutable, and state changes should be explicit and traceable. These ideas produce code that’s easier to reason about, test, and parallelize, in the right context of course.

These principles had been creeping into JavaScript long before React. Underscore.js (2009) brought map, reduce, and filter to the masses. Lodash and Ramda followed with deeper FP toolkits including currying, composition and immutability helpers. The ideas were in the air: avoid mutation, compose small functions, treat data transformations as pipelines.

React itself started with class components and setState, hardly pure FP. But the conceptual foundation was there: treat UI as a function of state, make rendering deterministic, isolate side effects. Then came Elm, a purely functional language created by Evan Czaplicki that codified the “Model-View-Update” architecture. When Dan Abramov created Redux, he explicitly cited Elm as inspiration. Redux’s reducers are directly modeled on Elm’s update functions: (state, action) => newState.

Redux formalized what had been emerging patterns. Combined with React Hooks (which replaced stateful classes with functional composition), the ecosystem shifted decisively toward FP. Immutability became non-negotiable. Pure components became the ideal. Side effects were corralled into useEffect. Through this convergence (library patterns, Elm’s rigor, and React’s evolution) Haskell-derived ideas about purity became mainstream JavaScript practice.

In the early 2010s, as JavaScript applications grew more complex, developers looked to FP for salvation. jQuery spaghetti had become unmaintainable. Backbone’s two-way binding caused cascading updates (ironically, Backbone’s documentation explicitly advised against two-way binding saying “it doesn’t tend to be terribly useful in your real-world app” yet many developers implemented it through plugins). The community wanted discipline, and FP offered it: treat your UI as a pure function of state. Make data flow in one direction. Eliminate shared mutable state.

React’s arrival in 2013 crystallized these ideals. It promised a world where UI = f(state): give it data, get back a component tree, re-render when data changes. No manual DOM manipulation. No implicit side effects. Just pure, predictable transformations.

This was seductive. And in many ways, it worked. But it also set us on a path toward rebuilding the web in JavaScript’s image, rather than JavaScript in the web’s image.

How FP Purism Shaped Modern Frontend

CSS-in-JS: The War on Global Scope

CSS was designed to be global. Styles cascade, inherit, and compose across boundaries. This enables tiny stylesheets to control huge documents, and lets teams share design systems across applications. But to functional programmers, global scope is dangerous. It creates implicit dependencies and unpredictable outcomes.

Enter CSS-in-JS: styled-components, Emotion, JSS. The promise was component isolation. Styles scoped to components, no cascading surprises, no naming collisions. Styles become data, passed through JavaScript, predictably bound to elements.

But this came at a cost. CSS-in-JS libraries generate styles at runtime, injecting them into <style> tags as components mount. This adds JavaScript execution to the critical rendering path. Server-side rendering becomes complicated. You need to extract styles during the render, serialize them, and rehydrate them on the client. Debugging involves runtime-generated class names like .css-1xbq8d9. And you lose the cascade; the very feature that made CSS powerful in the first place.

Worse, you’ve moved a browser-optimized declarative language into JavaScript, a single-threaded runtime. The browser can parse and apply CSS in parallel, off the main thread. Your styled-components bundle? That’s main-thread work, blocking interactivity.

The web had a solution. It’s called a stylesheet. But it wasn’t pure enough.

The industry eventually recognized these problems and pivoted to Tailwind CSS. Instead of runtime CSS generation, use utility classes. Instead of styled-components, compose classes in JSX. This was better, at least it’s compile-time, not runtime. No more blocking the main thread to inject styles. No more hydration complexity.

But Tailwind still fights the cascade. Instead of writing .button { padding: 1rem; } once and letting it cascade to all buttons, you write class="px-4 py-2 bg-blue-500" on every single button element. You’ve traded runtime overhead for a different set of problems: class soup in your markup, massive HTML payloads, and losing the cascade’s ability to make sweeping design changes in one place.

And here’s where it gets truly revealing: when Tailwind added support for nested selectors using & (a feature that would let developers write more cascade-like styles), parts of the community revolted. David Khourshid (creator of XState) shared examples of using nested selectors in Tailwind, and the backlash was immediate. Developers argued this defeated the purpose of Tailwind, that it brought back the “problems” of traditional CSS, that it violated the utility-first philosophy.

Think about what this means. The platform has cascade. CSS-in-JS tried to eliminate it and failed. Tailwind tried to work around it with utilities. And when Tailwind cautiously reintroduced a cascade-like feature, developers who were trained by years of anti-cascade ideology rejected it. We’ve spent so long teaching people that the cascade is dangerous that even when their own tools try to reintroduce platform capabilities, they don’t want them.

We’re not just ignorant of the platform anymore. We’re ideologically opposed to it.

Synthetic Events: Abstracting Away the Platform

React introduced synthetic events to normalize browser inconsistencies and integrate events into its rendering lifecycle. Instead of attaching listeners directly to DOM nodes, React uses event delegation. It listens at the root, then routes events to handlers through its own system.

This feels elegant from a functional perspective. Events become data flowing through your component tree. You don’t touch the DOM directly. Everything stays inside React’s controlled universe.

But native browser events already work. They bubble, they capture, they’re well-specified. The browser has spent decades optimizing event dispatch. By wrapping them in a synthetic layer, React adds indirection: memory overhead for event objects, translation logic for every interaction, and debugging friction when something behaves differently than the native API.

Worse, it trains developers to avoid the platform. Developers learn React’s event system, not the web’s. When they need to work with third-party libraries or custom elements, they hit impedance mismatches. addEventListener becomes a foreign API in their own codebase.

Again: the web had this. The browser’s event system is fast, flexible, and well-understood. But it wasn’t controlled enough for the FP ideal of a closed system.

Client-Side Rendering and Hydration: Reinventing the Browser

The logical extreme of “UI as a pure function of state” is client-side rendering: the server sends an empty HTML shell, JavaScript boots up, and the app renders entirely in the browser. From a functional perspective, this is clean. Your app is a deterministic function that takes initial state and produces a DOM tree.

From a web perspective, it’s a disaster. The browser sits idle while JavaScript parses, executes, and manually constructs the DOM. Users see blank screens. Screen readers get empty documents. Search engines see nothing. Progressive rendering which is one of the browser’s most powerful features, goes unused.

The industry noticed. Server-side rendering came back. But because the mental model was still “JavaScript owns the DOM,” we got hydration: the server renders HTML, the client renders the same tree in JavaScript, then React walks both and attaches event handlers. During hydration, the page is visible but inert. Clicks do nothing, forms don’t submit.

This is architecturally absurd. The browser already rendered the page. It already knows how to handle clicks. But because the framework wants to own all interactions through its synthetic event system, it must re-create the entire component tree in JavaScript before anything works.

The absurdity extends beyond the client. Infrastructure teams watch in confusion as every user makes double the number of requests: the server renders the page and fetches data, then the client boots up and fetches the exact same data again to reconstruct the component tree for hydration. Why? Because the framework can’t trust the HTML it just generated. It needs to rebuild its internal representation of the UI in JavaScript to attach event handlers and manage state.

This isn’t just wasteful, it’s expensive. Database queries run twice. API calls run twice. Cache layers get hit twice. CDN costs double. And for what? So the framework can maintain its pure functional model where all state lives in JavaScript. The browser had the data. The HTML had the data. But that data wasn’t in the right shape. It wasn’t a JavaScript object tree, so we throw it away and fetch it again.

Hydration is what happens when you treat the web like a blank canvas instead of a platform with capabilities. The web gave us streaming HTML, progressive enhancement, and instant interactivity. We replaced it with JSON, JavaScript bundles, duplicate network requests, and “please wait while we reconstruct reality.”

The Modal Problem: Teaching Malpractice as Best Practice

Consider the humble modal dialog. The web has <dialog>, a native element with built-in functionality: it manages focus trapping, handles Escape key dismissal, provides a backdrop, controls scroll-locking on the body, and integrates with the accessibility tree. It exists in the DOM but remains hidden until opened. No JavaScript mounting required. It’s fast, accessible, and battle-tested by browser vendors.

Now observe what gets taught in tutorials, bootcamps, and popular React courses: build a modal with <div> elements. Conditionally render it when isOpen is true. Manually attach a click-outside handler. Write an effect to listen for the Escape key. Add another effect for focus trapping. Implement your own scroll-lock logic. Remember to add ARIA attributes. Oh, and make sure to clean up those event listeners, or you’ll have memory leaks.

You’ve just written 100+ lines of JavaScript to poorly recreate what the browser gives you for free. Worse, you’ve trained developers to not even look for native solutions. The platform becomes invisible. When someone asks “how do I build a modal?”, the answer is “install a library” or “here’s my custom hook,” never “use <dialog>.”

The teaching is the problem. When influential tutorial authors and bootcamp curricula skip native APIs in favor of React patterns, they’re not just showing an alternative approach. They’re actively teaching malpractice. A generation of developers learns to build inaccessible <div> soup because that’s what fits the framework’s reactivity model, never knowing the platform already solved these problems.

And it’s not just bootcamps. Even the most popular component libraries make the same choice: shadcn/ui builds its Dialog component on Radix UI primitives, which use <div role="dialog"> instead of the native <dialog> element. There are open GitHub issues requesting native <dialog> support, but the implicit message is clear: it’s easier to reimplement the browser than to work with it.

When Frameworks Can’t Keep Up with the Platform

The problem runs deeper than ignorance or inertia. The frameworks themselves increasingly struggle to work with the platform’s evolution. Not because the platform features are bad, but because the framework’s architectural assumptions can’t accommodate them.

Consider why component libraries like Radix UI choose <div role="dialog"> over <dialog>. The native <dialog> element manages its own state: it knows when it’s open, it handles its own visibility, it controls focus internally. But React’s reactivity model expects all state to live in JavaScript, flowing unidirectionally into the DOM. When a native element manages its own state, React’s mental model breaks down. Keeping isOpen in your React state synchronized with the <dialog> element’s actual open/closed state becomes a nightmare of refs, effects, and imperative calls. Precisely what React was supposed to eliminate.

Rather than adapt their patterns to work with stateful native elements, library authors reimplement the entire behavior in a way that fits the framework. It’s architecturally easier to build a fake dialog in JavaScript than to integrate with the platform’s real one.

But the conflict extends beyond architectural preferences. Even when the platform adds features that developers desperately want, frameworks can’t always use them.

Accordions? The web has <details> and <summary>. Tooltips? There’s title attribute and the emerging popover API. Date pickers? <input type="date">. Custom dropdowns? The web now supports styling <select> elements with appearance: base-select and ::picker(select) pseudo-elements. You can even put <span> elements with images inside <option> elements now. It eliminates the need for the countless JavaScript select libraries that exist solely because designers wanted custom styling.

Frameworks encourage conditional rendering and component state, so these elements don’t get rendered until JavaScript decides they should exist. The mental model is “UI appears when state changes,” not “UI exists, state controls visibility.” Even when the platform adds the exact features developers have been rebuilding in JavaScript for years, the ecosystem momentum means most developers never learn these features exist.

And here’s the truly absurd part: even when developers do know about these new platform features, the frameworks themselves can’t handle them. MDN’s documentation for customizable <select> elements includes this warning: “Some JavaScript frameworks block these features; in others, they cause hydration failures when Server-Side Rendering (SSR) is enabled.” The platform evolved. The HTML parser now allows richer content inside <option> elements. But React’s JSX parser and hydration system weren’t designed for this. They expect <option> to only contain text. Updating the framework to accommodate the platform’s evolution takes time, coordination, and breaking changes that teams are reluctant to make.

The web platform added features that eliminate entire categories of JavaScript libraries, but the dominant frameworks can’t use those features without causing hydration errors. The stack that was supposed to make development easier now lags behind the platform it’s built on.

Routing and Forms: JavaScript All the Way Down

The browser has native routing: <a> tags, the History API, forward/back buttons. It has native forms: <form> elements, validation attributes, submit events. These work without JavaScript. They’re accessible by default. They’re fast.

Modern frameworks threw them out. React Router, Next.js’s router, Vue Router; they intercept link clicks, prevent browser navigation, and handle routing in JavaScript. Why? Because client-side routing feels like a pure state transition: URL changes, state updates, component re-renders. No page reload. No “lost” JavaScript state.

But you’ve now made navigation depend on JavaScript. Ctrl+click to open in a new tab? Broken, unless you carefully re-implement it. Right-click to copy link? The URL might not match what’s rendered. Accessibility tools that rely on standard navigation patterns? Confused.

Forms got the same treatment. Instead of letting the browser handle submission, validation, and accessibility, frameworks encourage JavaScript-controlled forms. Formik, React Hook Form, uncontrolled vs. controlled inputs; entire libraries exist to manage what <form> already does. The browser can validate <input type="email"> instantly, with no JavaScript. But that’s not reactive enough, so we rebuild validation in JavaScript, ship it to the client, and hope we got the logic right.

The web had these primitives. We rejected them because they didn’t fit our FP-inspired mental model of “state flows through JavaScript.”

What We Lost in the Process

Progressive enhancement used to be a best practice: start with working HTML, layer on CSS for style, add JavaScript for interactivity. The page works at every level. Now, we start with JavaScript and work backwards, trying to squeeze HTML out of our component trees and hoping hydration doesn’t break.

We lost built-in accessibility. Native HTML elements have roles, labels, and keyboard support by default. Custom JavaScript widgets require aria-* attributes, focus management, and keyboard handlers. All easy to forget or misconfigure.

We lost performance. The browser’s streaming parser can render HTML as it arrives. Modern frameworks send JavaScript, parse JavaScript, execute JavaScript, then finally render. That’s slower. The browser can cache CSS and HTML aggressively. JavaScript bundles invalidate on every deploy.

We lost simplicity. <a href="/about"> is eight characters. A client-side router is a dependency, a config file, and a mental model. <form action="/submit" method="POST"> is self-documenting. A controlled form with validation is dozens of lines of state management.

And we lost alignment with the platform. The browser vendors spend millions optimizing HTML parsing, CSS rendering, and event dispatch. We spend thousands of developer-hours rebuilding those features in JavaScript, slower.

Why This Happened

This isn’t a story of incompetence. Smart people built these tools for real reasons.

By the early 2010s, JavaScript applications had become unmaintainable. jQuery spaghetti sprawled across codebases. Two-way data binding caused cascading updates that were impossible to debug. Teams needed discipline, and functional programming offered it: pure components, immutable state, unidirectional data flow. For complex, stateful applications (like dashboards with hundreds of interactive components, real-time collaboration tools, data visualization platforms) React’s model was genuinely better than manually wiring up event handlers and tracking mutations.

The FP purists weren’t wrong that unpredictable mutation causes bugs. They were wrong that the solution was avoiding the platform’s mutation-friendly APIs instead of learning to use them well. But in the chaos of 2013, that distinction didn’t matter. React worked. It scaled. And Facebook was using it in production.

Then came the hype cycle. React dominated the conversation. Every conference had React talks. Every tutorial assumed React as the starting point. CSS-in-JS became “modern.” Client-side rendering became the default. When big companies like Facebook, Airbnb, Netflix and others adopted these patterns, they became industry standards. Bootcamps taught React exclusively. Job postings required React experience. The narrative solidified: this is how you build for the web now.

The ecosystem became self-reinforcing through its own momentum. Once React dominated hiring pipelines and Stack Overflow answers, alternatives faced an uphill battle. Teams that had already invested in React by training developers, building component libraries, establishing patterns are now facing enormous switching costs. New developers learned React because that’s what jobs required. Jobs required React because that’s what developers knew. The cycle fed itself, independent of whether React was the best tool for any particular job.

This is where we lost the plot. Somewhere in the transition from “React solves complex application problems” to “React is how you build websites,” we stopped asking whether the problems we were solving actually needed these solutions. I’ve watched developers build personal blogs with Next.js. Sites that are 95% static content with maybe a contact form, because that’s what they learned in bootcamp. I’ve seen companies choose React for marketing sites with zero interactivity, not because it’s appropriate, but because they can’t hire developers who know anything else.

The tool designed for complex, stateful applications became the default for everything, including problems the web solved in 1995 with HTML and CSS. A generation of developers never learned that most websites don’t need a framework at all. The question stopped being “does this problem need React?” and became “which React pattern should I use?” The platform’s native capabilities like progressive rendering, semantic HTML, the cascade, instant navigation are now considered “old-fashioned.” Reinventing them in JavaScript became “best practices.”

We chased functional purity on a platform that was never designed for it. And we built complexity to paper over the mismatch.

The Way Forward

The good news: we’re learning. The industry is rediscovering the platform.

HTMX embraces HTML as the medium of exchange. Server sends HTML, browser renders it, no hydration needed. Qwik resumable architecture avoids hydration entirely, serializing only what’s needed. Astro defaults to server-rendered HTML with minimal JavaScript. Remix and SvelteKit lean into web standards: forms that work without JS, progressive enhancement, leveraging the browser’s cache.

These tools acknowledge what the web is: a document-based platform with powerful native capabilities. Instead of fighting it, they work with it.

This doesn’t mean abandoning components or reactivity. It means recognizing that UI = f(state) is a useful model inside your framework, not a justification to rebuild the entire browser stack. It means using CSS for styling, native events for interactions, and HTML for structure and then reaching for JavaScript when you need interactivity beyond what the platform provides.

The best frameworks of the next decade will be the ones that feel like the web, not in spite of it.

Conclusion

In chasing functional purity, we built a frontend stack that is more complex, more fragile, and less aligned with the platform it runs on. We recreated CSS in JavaScript, events in synthetic wrappers, rendering in hydration layers, and routing in client-side state machines. We did this because we wanted predictability, control, and clean abstractions.

But the web was never meant to be pure. It’s a sprawling, messy, miraculous platform built on decades of emergent behavior, pragmatic compromises, and radical openness. Its mutability isn’t a bug. It’s the reason a document written in 1995 still renders in 2025. Its global scope isn’t dangerous. It’s what lets billions of pages share a design language.

Maybe the web didn’t need to be purified. Maybe it just needed to be understood.

I want to thank my friend Ihab Khattab for reviewing this piece and providing invaluable feedback.

But sometimes (more often than we’d like to admit) chasing the shiny new thing leads us down a rabbit hole that costs far more than it delivers. Let me tell you about how I almost fell into this trap, and how stepping back taught me an important lesson about knowing when not to fix what isn’t broken.

The Problem That Started It All

My blog has been running on Jekyll since 2013. It’s built on Ruby, it’s a static site generator, and honestly? It just works. The build time for my nearly 20 pages is under a second (literally). I write in Markdown, push to GitHub, and my content goes live. Simple, reliable, boring in all the best ways.

For years, I used Disqus for comments. Sure, I’d heard the privacy concerns, but the integration was dead simple: drop in a script tag and you have a full commenting system. It worked perfectly… until it didn’t.

Over time, the quality of Disqus ads became increasingly awful. We’re talking cheap scam-level bad. Usually featuring some questionable imagery that looked completely out of place on a technical blog. Imagine trying to discuss clean code architecture while the bottom of your blog displays what looks like a dating site gone wrong.

That’s when the thought crept in: Maybe it’s time to modernize everything.

Down the Rabbit Hole

Why stick with this old Jekyll stack when there are sexier static site generators out there? At work, we’ve been using Astro, and it’s fantastic. There are beautiful themes (free and commercial) with features I could only dream of back in 2013: dark mode, light mode, extended Markdown support, and those buttery-smooth ViewTransitions between pages.

I dove in. Downloaded Astro, found a gorgeous theme, and at first glance, it seemed like everything I needed. This was it. Time to join the modern web development world.

But then reality hit.

This wasn’t going to be a simple swap. It was an investment. A significant one:

• Markdown Migration: All my custom markdown hacks would need to be rewritten to use the theme’s extended features
• URL Structure: My existing URLs were different. I’d either need to dig deep into the theme’s internals or set up a complex redirect system
• Front Matter: The metadata structure had changed, requiring me to update every single post
• Content Audit: I’d need to test every page to ensure nothing broke in translation

For a blog where I publish once or twice a year (though I’m trying to change that habit), this was starting to look like a multi-week project.

The Moment of Clarity

I took a step back and had what I can only describe as a Walter White moment: “We had a good thing, you stupid son of a b*tch!”

Wait. What problem was I actually trying to solve? Bad Disqus ads. That’s it. I didn’t need a complete platform overhaul. I needed a better commenting system.

As I researched the Astro theme more carefully, I noticed their primary commenting integration was something called Giscus. Curious, I investigated.

Giscus is brilliant in its simplicity: it’s a GitHub app that turns your repository’s Discussions feature into a commenting system. Zero infrastructure on my end, no privacy concerns, and the setup is just configuring a script from their website.

I tried it on my existing Jekyll blog. It worked flawlessly.

The Real Cost of Shiny Object Syndrome

This experience crystallized something important about our relationship with technology. The allure of modern tools often blinds us to what we’re actually trying to accomplish.

Jekyll vs. Astro build times: Jekyll builds my entire site in under a second. The last time I used Astro on a project of similar size, it took over a minute. “Modern” doesn’t always mean better.

Maintenance overhead: My Jekyll setup has been rock-solid for over a decade. Every migration carries the risk of introducing new complexities, dependencies, and potential failure points.

Time investment: The hours I would have spent on migration could be better used creating content which is the actual purpose of having a blog.

A Framework for Fighting the Syndrome

Before you embark on your next “modernization” project, ask yourself these questions:

1. What specific problem am I solving? Write it down. Be precise. “The tech is old” isn’t a problem; it’s an observation.

2. What’s the smallest change that solves this problem? Often, the solution is much simpler than a complete rewrite.

3. What are the hidden costs? Migration time, learning curve, new dependencies, potential bugs, ongoing maintenance … etc.

4. Is my current solution actually causing problems? Performance issues? Developer friction? Or is it just not the trendy choice?

5. Where should my effort actually go? In my case, writing more content would benefit my blog far more than switching frameworks.

When Boring Is Beautiful

There’s something deeply satisfying about tools that fade into the background and let you focus on what matters. My Jekyll blog doesn’t win any architecture awards, but it lets me write without friction and publishes reliably.

Sometimes the most professional choice is sticking with what works. Your users don’t care if you’re using the latest framework; they care if your site loads fast and provides value.

The Bottom Line

As long as your tools are working (and I mean truly working, not just limping along) there’s often no compelling reason to change them. The energy you save by not chasing every shiny object can be redirected toward what actually moves the needle: solving real problems, creating better content, or building features that matter to your users.

The next time you feel that familiar pull toward the latest and greatest, pause. Ask yourself: am I solving a real problem, or am I just distracted by something shiny?

P.S. Since I just swapped out Disqus for Giscus, help me put this new commenting system to the test! Drop a comment below and let me know your experience with shiny object syndrome!

It started with a vulnerability report. Our Strapi-based platform had a classic security issue: the file uploader was allowing PDFs with embedded scripts; a pentester’s dream and our security nightmare. The fix seemed straightforward enough: block non-compliant PDFs by validating them against the PDF/A standard, which prohibits scripting and embedded content.

I dove into the technical challenge. After some research, I found veraPDF, a binary tool that could validate PDF/A compliance. Using Strapi’s webhook system, I hooked into the file upload process, ran the scanner, and threw an error for non-compliant files.

BINGO.

I was ready to celebrate. Running a binary from Node.js was new territory for me, and the JavaScript ecosystem had no good alternatives for PDF validation. The core functionality worked. Mission accomplished, right?

Not quite.

When “Working” Isn’t Good Enough

As I prepared my merge request, I took another look at the implementation. When a PDF failed validation, the system returned a generic “500 Internal Server Error.” That nagging feeling hit, the one every engineer knows but doesn’t always listen to.

This isn’t good enough.

A 500 error suggests the server broke, but this was actually a client input issue; a 4xx error. More importantly, users would have no idea why their upload failed. After digging into Strapi’s error handling, I found the ValidationError function and crafted a proper error response with a descriptive message.

Better, but still not done.

The Cascade of Edge Cases

Then I realized something else: when validation failed, the uploaded file was still sitting on the server. The error stopped the process, but left digital debris behind. A quick cleanup function solved that.

But wait, what if veraPDF isn’t installed on the server? I shared my branch with a colleague for testing, and sure enough, both compliant and non-compliant PDFs were failing validation. The binary wasn’t in his PATH.

Now I needed to distinguish between “PDF validation failed” (user error, 4xx) and “veraPDF unavailable” (server configuration issue, 5xx), with appropriate error messages for each scenario.

The Real Engineering Lesson

Here’s what struck me: the original requirement was simple “disallow PDFs with scripts.” My first implementation technically satisfied that requirement. But it would have been terrible in practice.

The engineering solution worked, but it took multiple iterations to make it right:

1. First iteration: Core functionality ✓
2. Second iteration: Proper error codes and messages ✓
3. Third iteration: File cleanup ✓
4. Fourth iteration: Graceful handling of missing dependencies ✓

None of these additional considerations came from the product team or the security testers. They emerged from thinking like a user, considering edge cases, and caring about the overall experience.

Why This Matters for Your Career

This experience reinforced something crucial: companies don’t just want engineers who can write code that works. They want engineers who think holistically about problems.

The difference between a junior and senior engineer isn’t just technical complexity. It’s the ability to:

• Think beyond the happy path: What happens when things go wrong?
• Consider the user experience: Even for internal tools and error states
• Anticipate deployment issues: What assumptions am I making about the environment?
• Write maintainable code: The next person (including future you) will thank you

This mindset—combining technical skills with product thinking and user empathy—is what makes engineers truly valuable. It’s what turns a feature request into a robust solution that actually solves the problem.

Breaking Down the Problem

What made this manageable was breaking down the problem into small, testable parts:

1. Can I run veraPDF from Node.js?
2. Can I integrate with Strapi’s file upload lifecycle?
3. Am I returning appropriate error codes and messages?
4. Am I cleaning up properly on failures?
5. Am I handling environment dependencies gracefully?

Each iteration built on the last, gradually transforming working code into production-ready code.

The Bottom Line

Technical skills will get you hired, but product thinking and user empathy will make you indispensable. The ability to see beyond the immediate technical requirement—to think about edge cases, user experience, and maintainability—is what separates good engineers from great ones.

Next time you’re tempted to ship that first working version, pause and ask: “What would make this not just work, but work well?”

Your users (and your future self) will thank you.

What’s a time when you went beyond the basic requirements to create a better user experience? I’d love to hear your stories in the comments.

What are Text fragments?

Text fragments are a powerful feature of the modern web platform that allows for precise linking to specific text within a web page without the need to add an anchor! This feature is complemented by the ::target-text CSS pseudo-element, which provides a way to style the highlighted text.

Text fragments work by appending a special syntax to the end of a URL; just like we used to append the ID after the hash symbol (#). The browser interprets this part of the URL, searches for the specified text on the page, and then scrolls to and highlights that text if it supports text fragments. If the user attempts to navigate the document by pressing tab, the focus will move on to the next focusable element after the text fragment.

How can we use it?

Here’s the basic syntax for a text fragment URL:

https://example.com/page.html#:~:text=[prefix-,]textStart[,textEnd][,-suffix]

Following the hash symbol, we add this special syntax :~: also known as fragment directive then text= followed by:

1. prefix-: A text string preceded by a hyphen specifying what text should immediately precede the linked text. This helps the browser to link to the correct text in case of multiple matches. This part is not highlighted.
2. textStart: The beginning of the text you’re highlighting.
3. textEnd: The ending of the text you’re highlighting.
4. -suffix: A hyphen followed by a text string that behaves similarly to the prefix but comes after the text. Aslo helpful when multiple matches exist and doesn’t get highlighted with the linked text.

For example, the following link:

https://developer.mozilla.org/en-US/docs/Web/URI/Fragment/Text_fragments#:~:text=without%20relying%20on%20the%20presence%20of%20IDs

This text fragment we are using is “without relying on the presence of IDs” but it’s encoded. If you follow this link, it should look like the following:

We can also highlight a range of text by setting the startText and the endText. Consider the following example from the same URL:

https://developer.mozilla.org/en-US/docs/Web/URI/Fragment/Text_fragments#:~:text=using%20particular,don't%20control

The text fragment we are using is “using particular” followed by a comma then “don’t control”. If you follow this link, it should look like the following:

We can also highlight multiple texts by using ampersands. Consider the following:

https://developer.mozilla.org/en-US/docs/Web/URI/Fragment/Text_fragments#:~:text=using%20particular&text=it%20allows

If you follow this link, it should look like the following:

One of the interesting behaviors about text fragments, is if you’re linking to hidden content that’s discoverable through find-in-page feature (e.g. children of element with hidden attribute set to until-found or content of a closed details element), the hidden content will become visible. Let’s look at this behavior by linking to this article from Scott O’Hara’s blog. The blog contains the details element that is closed by default.

If we linked to the text fragment inside the details element, it will open automatically:

https://www.scottohara.me/blog/2022/09/12/details-summary.html#:~:text=Oh%20hi%20there.%20Forget%20your%20summary,%20didja

Note that this behavior is only available in Google Chrome as it’s the only browser to support discoverable content.

Styling highlighted fragments

If the browser supports text fragments, we can change the style of the highlighted text by using the ::target-text pseudo-element

::target-text {
    background-color: yellow;
}

Note that we are only allowed to change the following properties:

• color
• background-color
• text-decoration and its associated properties (including text-underline-position and text-underline-offset)
• text-shadow
• stroke-color, fill-color, and stroke-width
• custom properties

Browser support and fallback behaviour

Text fragments are currently supported in all the browsers. The pseudo-element ::target-text is not yet supported is Safari but it’s now available in the Technology Preview version. If this feature is not supported in the browser, it will degrade gracefully and the page will load without highlighting or scrolling to the text.

The default style for the highlight is different based on the browser. The color of the highlight is different across the different browsers. The highlighted area is bigger in Safari spanning the whole line-height. In Firefox and Chrome, only the text is highlighted and the spaces between the lines are empty.

We can detect if the feature is supported or not using document.fragmentDirective. It will return an empty FragmentDirective object, if supported or will return undefined if it’s not.

Closing thoughts

My first encounter with text fragments was through links generated by Google Search results. Initially, I assumed it was a Chrome-specific feature and not part of a broader web standard. However, I soon realized that this functionality was actually built upon the open web, available to any browser that chooses to implement it.

I’d love to see this feature used more broadly, particularly by responsible generative AI systems. Imagine AI that can provide direct, context-sensitive links to the exact content you’re interested in, using text fragments for precise references. This would not only increase transparency but also improve the user experience when navigating AI-generated content.

Looking ahead, it would be fantastic if text fragments were more accessible to all users, not just those with technical knowledge. What if browsers offered built-in features that allowed non-technical users to highlight text and generate links to specific paragraphs with ease? This could be through a native browser feature or even a simple browser extension—either way, it would make deep linking a breeze for everyone.

Finally, I’d like to express my sincere thanks to Hannah Olukoye and Jens Oliver Meiert for the time they’ve taken to share their invaluable feedback and corrections.

Update, 20th Oct, 2024

It turns out that the ability to generate a link to a specific piece of text is already built into Chromium-based browsers, as Hosam Sultan clarified on X (formerly Twitter). If you’re using Chrome, simply highlight some text, right-click, and you’ll find the “Copy link to highlight” option in the context menu.

Additional resources

• URL Fragment Text Directives - W3C Draft Community Group Report
• Text Fragments: MDN
• Style Highlights: CSSWG Draft
• Support for Text Fragments: CanIUse

After the introduction of the :focus-within pseudo-class, we can now build dropdown menus that work better with keyboard navigation. This is because the :focus-within pseudo-class is triggered when an element or its child elements are focused. This means that when a user tabs to a child menu, the dropdown menu will be shown. This was a great improvement for accessibility and usability.

The problem

I recently had a thought about how we can make dropdown menus even more user friendly. This thought came to me after an encounter with a Wordpress administration panel that had a lot of dropdown menus. I heavily rely on the search-in-page feature in my browser. Wordpress dropdown menus are not hidden from the search-in-page feature because they are implemented with a positioning technique that puts them outside of the viewport. This means that the search-in-page feature will find the dropdown menu items, but the user will not see them. This caused me a lot of frustration as I was trying to juggle between the different results I was getting.

The solution

I have posted about the hidden attribute’s value until-found before on HTMHell Advent’s Calendar for 2023 and I thought that this could be a great solution for this problem. The hidden attribute with the value until-found will hide the element from the user until the user searches for the element. This means that the search-in-page feature will find the element, but the user will not see it until they search for it.

Note: At the time of writing this post, the hidden attribute with the value until-found is an experimental feature that’s currently supported on Chrome and Edge.

Let’s take a look at this basic dropdown menu. We will create a two-level dropdown menu using unordered lists. The second level will be hidden using the CSS property display: none;. We will then use the :hover pseudo-class and :focus-within to show the second level when the first level is hovered or focused.

<nav>
  <ul>
    <li><a href="#">Home</a></li>
    <li><a href="#">About</a></li>
    <li>
      <a href="#">Shop</a>
      <ul>
        <li><a href="#">Electronics</a></li>
        <li><a href="#">Fashion</a></li>
        <li><a href="#">Home & Furniture</a></li>
        <li><a href="#">Health & Beauty</a></li>
        <li><a href="#">Sports & Outdoors</a></li>
      </ul>
    </li>
    <li>
      <a href="#">Services</a>
      <ul>
        <li><a href="#">Web Design</a></li>
        <li><a href="#">Web Development</a></li>
        <li><a href="#">Graphic Design</a></li>
        <li><a href="#">Digital Marketing</a></li>
        <li><a href="#">SEO</a></li>
      </ul>
    </li>
    <li><a href="#">Contact</a></li>
  </ul>
</nav>

nav {
  min-width: fit-content;
}

nav ul {
  padding: 0;
  margin: 0;
  list-style: none;
}

nav li {
  position: relative;
  padding: 10px 20px;
}

nav a {
  color: #fff;
  text-decoration: none;
}

nav > ul {
  display: flex;
  justify-content: space-around;
  background-color: #333;
  border-radius: 5px;
}

nav > ul > li > ul {
  position: absolute;
  top: 100%;
  inset-inline-start: 0;
  background-color: #333;
  display: none;
}

nav > ul > li:hover > ul,
nav > ul > li:focus-within > ul {
  display: block;
}

nav > ul > li > ul > li:hover,
nav > ul > li > ul > li:focus-within {
  background-color: #555;
}

Moving your mouse over the “Shop” or “Services” menu items will show the second level of the dropdown menu.

Now let’s make a few changes to make that menu work using the new hidden attribute value until-found.

<nav>
  <ul>
    <li><a href="#">Home</a></li>
    <li><a href="#">About</a></li>
    <li>
      <a href="#">Shop</a>
      <ul hidden="until-found">
        <li><a href="#">Electronics</a></li>
        <li><a href="#">Fashion</a></li>
        <li><a href="#">Home & Furniture</a></li>
        <li><a href="#">Health & Beauty</a></li>
        <li><a href="#">Sports & Outdoors</a></li>
      </ul>
    </li>
    <li>
      <a href="#">Services</a>
      <ul hidden="until-found">
        <li><a href="#">Web Design</a></li>
        <li><a href="#">Web Development</a></li>
        <li><a href="#">Graphic Design</a></li>
        <li><a href="#">Digital Marketing</a></li>
        <li><a href="#">SEO</a></li>
      </ul>
    </li>
    <li><a href="#">Contact</a></li>
  </ul>
</nav>

We will have to modify the CSS as well. The way we’re hiding the second level of the dropdown menu is by setting the display property to none. This is how the hidden attribute works by default. With the new hidden attribute value until-found, the content is hidden using the content-visibility property. To understands the difference between the two, I recommend checking this awesome article on web.dev. Now that the hidden attribute is set, the content will be hidden by default. We will need to modify the CSS to show the content when the user move their cursor over the first level of the dropdown menu.

nav > ul > li > ul {
  position: absolute;
  top: 100%;
  inset-inline-start: 0;
  background-color: #333;
  /* Remove the following */
  /* display: none; */
}

nav > ul > li:hover > ul,
nav > ul > li:focus-within > ul {
  /* display: block; */
  content-visibility: visible;
}

Here is the modified version.

Now try to search for “Electronics” using the search-in-page feature in your browser. You will see that the dropdown menu will open spontaneously! This is all working without JavaScript, just by using the hidden attribute with the value until-found.

We will run into a little problem here. The elements displayed using the hidden attribute value until-found will be visible all the time. This isn’t like what we had earlier where the visibility state is toggled. Once the element is found, the hidden attribute will be removed and the element will be visible all the time. Watch the video below to see what happens when we search for items in two different menus.

Luckily, JavaScript can help us with this. The new feature for the hidden attribute comes with a JavaScript event called beforematch. This event is triggered when an element is found using the search-in-page feature. We can use this event to toggle the visibility of the other element. Let’s see how we can do this.

// Get all the items with submenu
const itemsWithSubmenu = document.querySelectorAll('nav > ul > li:has(ul)');

// A function we will use to hide all the submenus by setting their hidden attribute to until-found
function hideAllSubmenus() {
  itemsWithSubmenu.forEach(menuItem => {
    menuItem.querySelector(':scope > ul').setAttribute('hidden', 'until-found');
  });
}

// Loop over all the items with submenu
itemsWithSubmenu.forEach(menuItem => {
  // Add an event listener to the submenu to hide all the submenus when a new menu is found
  menuItem.querySelector(':scope > ul').addEventListener('beforematch', hideAllSubmenus);

  // Simulate the hover effect by hiding all the submenus when the mouse enters or leaves the menu item
  menuItem.addEventListener('mouseenter', hideAllSubmenus);
  menuItem.addEventListener('mouseleave', hideAllSubmenus);

  // Simulate the focus effect by hiding all the submenus when the menu item is focused
  menuItem.addEventListener('focusin', hideAllSubmenus);
  menuItem.addEventListener('focusout', hideAllSubmenus);
});

Notice that we added event listeners for mouseenter, mouseleave, focusin and focusout to simulate the hover effect and focus effects. This is because the beforematch event is only triggered when the element is found using the search-in-page feature. These events will help us hide the other submenus when the user moves their cursor over or focuses on other the menu items.

Here is a video demonstrating the full implementation:

We now have a dropdown menu that can work with a little help of JavaScript and is search-in-page friendly. This is a great improvement for usability.

Closing thoughts

In future iterations of this demo, we can use feature detection to make this demo work gracefully for older browsers. Additionally, evaluating the accessibility of this solution against established standards like WCAG and ARIA will be a crucial step to ensure inclusivity for all users.

The hidden attribute with the value until-found is a great addition to the web platform and I think we will be relying on it more and more in the future. If I may ask for more things, it would be great to have a way to toggle the visibility of the element if a new match is found and a way to find the parent element of the text element. I wanted to move focus directly to the match anchor tag but the beforematch event doesn’t have this kind of information. This way, we can build more user-friendly interfaces for our users.

Special thanks goes to Hatem Hosny and Konnor Rogers for their valuable feedback on this post. If you have any questions or suggestions, feel free to reach out to me on Twitter. Thanks for reading!

Additional resources

• The hidden attribute in HTML: HTMHell 2023 Advent Calendar
• Content visibility: web.dev
• HTML attribute: hidden: until-found value: caniuse.com

Source file basics

File name

File names must be all lowercase and may include dashes (-), but no additional punctuation. Follow the convention that your project uses. Filenames’ extension must be css or other preprocessor extensions (sass, less … etc).

File encoding: UTF-8

Source files are encoded in UTF-8. Encoding should be specified in the file header using the @charset directive. This should be added to the root file that include all the styles or to every other file that isn’t included in the root file.

@charset "UTF-8";

Structure

We follow the ITCSS methodology for writing CSS. ITCSS require the following directory structure:

1. settings: settings will be used across the project like color variables, the fonts that will be used … etc.
2. tools: globally used mixins and functions. It’s important not to output any CSS in the first 2 layers.
3. generic: reset and/or normalize styles, box-sizing definition, etc. This is the first layer which generates actual CSS.
4. elements: styling for bare HTML elements (like H1, A, etc.). These come with default styling from the browser so we can redefine them here.
5. objects: class-based selectors which define undecorated design patterns, for example media object known from OOCSS, the grid …etc.
6. components: specific UI components. This is where majority of our work takes place and our UI components are often composed of Objects and Components.
7. utilities: utilities and helper classes with ability to override anything which goes before in the triangle, eg. hide helper class.

We might need to include vendor styles (CSS specific to a UI library we are using), these ones are set between objects and components layers.

Each group of declarations should be written in a sepearate file. For example, to define the project’s box-model, we would write a file named box-model.css in the generic layer.

Note: One of the common mistakes developers do is that they put some rules in the wrong layer. For example, we might want to define the font that will be used in the website. Font is an inherited value so we usually write it using a body selector. Developers would create a file in the elements layer and put the font declaration there. This is wrong because that file is specific to the style we need to define on the body (like background-color, height … etc). Setting the used font should be done in the generic layer by creating a file called typography.css and putting the font declaration there.

@charset "UTF-8";

/* Settings – used with preprocessors and contain font, colors definitions, etc. */
@import "settings/fonts.css";
@import "settings/colors.css";

/* Tools – globally used mixins and functions. It’s important not to output any CSS in the first 2 layers. */

/* Functions */

/* Mixins */

/* Generic – reset and/or normalize styles, box-sizing definition, etc. This is the first layer which generates actual CSS. */
@import "generic/box-model.css";
@import "generic/typography.css";

/* Elements – styling for bare HTML elements (like H1, A, etc.). These come with default styling from the browser so we can redefine them here. */
@import "elements/anchor.css";
@import "elements/img.css";
@import "elements/body.css";

/* Objects – class-based selectors which define undecorated design patterns, for example media object known from OOCSS */
@import "objects/grid.css";
@import "objects/media.css";
@import "objects/pagination.css";

/* Vendor - These are resolved from node_modules by the postprocessors automatically */
@import "swiper/swiper-bundle.css";
@import "swiper/components/effect-fade/effect-fade.scss";

/* Components – specific UI components. This is where majority of our work takes place and our UI components are often composed of Objects and Components */
@import "components/header.css";
@import "components/footer.css";

/* Utilities – utilities and helper classes with ability to override anything which goes before in the triangle, eg. hide helper class */
@import "utilities/text-align.css";
@import "utilities/screen-reader.css";
@import "utilities/display.css";

Naming

We follow the BEM naming convention.

Formatting

Braces

Braces follow the Kernighan and Ritchie style as follow:

• No line break before the opening brace.
• Line break after the opening brace.
• Line break before the closing brace.

Indentation

Each time a new block is opened, the indent increases by one tab character. When the block ends, the indent returns to the previous indent level. The indent level applies to both code and comments throughout the block. Example:

@media screen and (min-width: 768px) {
  .selector {
    property: value;
  }
}

Using indentation is also encouraged in some cases where a value could be a list of tokens. Example:

/* Facilitate reading */
@font-face {
  font-family: "Open Sans";
  src: url("/fonts/OpenSans-Regular-webfont.woff2") format("woff2"),
       url("/fonts/OpenSans-Regular-webfont.woff") format("woff");
}

blockquote {
  padding: 20px;
  box-shadow: 0 -3em 3em rgba(0, 0, 0, 0.1),
              0 0 0 2px rgb(255, 255, 255),
              0.3em 0.3em 1em rgba(0, 0, 0, 0.3);
}

.header {
  background-image: url("/images/header-1.png"),
                    url("/images/header-2.png");
}

Declaration

One declaration per line

Each declaration is followed by a line-break.

/* Don't do this */
.selector {
  background: #000; font-size: 12px;
}

/* Do this */
.selector {
  background: #000;
  font-size: 12px;
}

Semicolons are required

Every declaration must be terminated with a semicolon. Even if it’s the last declaration within a selector.

/* Don't do this */
.selector {
  background: #000;
  font-size: 12px
}

/* Do this */
.selector {
  background: #000;
  font-size: 12px;
}

Whitespace

Vertical whitespace

A single blank line appears:

1. After the , character that separates between the selectors.
2. After the opening braces before the declaration block or other block structures like @media or @supports.
3. After the ; character that terminates a declaration.
4. After the closing braces } after the declaration block or other block structures like @media or @supports.
5. Between a declaration and the next one.
6. After the , character that separates between different values for the same property (see the example mentionned earlier in the indentation section).

Example:

/* Don't do this */
.selector-1, .selector-2 {
  background: #000;
  font-size: 12px;
}

.selector-1,
.selector-2 {
  background: #000; font-size: 12px;
}

/* Do this */
.selector-1,
.selector-2 {
  background: #000;
  font-size: 12px;
}

Exception:

/* If you have a single selector and a single declaration, it's OK to do both of the following */
.selector {
  background: #000;
}

.selector { background: #000; }

Horizontal whitespace

Horizontal whitespace is used to separate the different parts of a declaration to facilitate reading. These are the rules to follow:

1. Before the openning brace { of a declaration block.
2. After the : character that separates the property from the value.
3. Between the value and the !important keyword.
4. After the , character that is used to separate between some values like rgb() color`.
5. Between the selector combinators.

Note: in some cases, horizontal white space is required otherwise the whole declaration will be invalid like the spaces between the operands of a calc() function.

.selector-1 > .selector-2 {
  font-size: 2rem;
  line-height: 2 !important;
  background-color: rgba(0, 0, 0, 0.5);
  width: calc(100% - 10px);
}

Comments

Comments in CSS can only be written in a multi-line format (/* */). Some languages like Sass allow single-line comments (//). We usually don’t need to comment anything in CSS because it’s self descriptive, however, I find it valuable to document any magic numbers we may have.

/* Ambiguous, don't do this */
.selector {
  top: 197px;
}

/* Explain what does this value mean */
.selector {
  top: 197px; /* Represents the height of the header */
}

/* Even better use custom properties */
:root {
  --header-height: 197px;
}

.selector {
  top: var(--header-height);
}

If you’re using a preprocessor, note that the // comment doesn’t get compiled into the final output while the /* */ comment is preserved.

Quotes

The quotes we use in CSS are double quotes ".

Language features

Units

Use the unit that’s stuitable for what you’re doing. Examples:

• Percentage unit is stuiable when you define something related to its container.
• Pixel could be suitable when you really need a small value (1px, 2px … etc) instead of using rem and to avoid some bugs that happen with subpixel rendering.
• In most of the cases line-height is unitless to let the value be calculated according to the element’s font-size. Other units could lead to undesirable side effects or require modifiation to that value if we change the font-size. The only exception to use a unit is usually when we need to vertically align the text withing a container with a fixed height.
• Do not use any unit when the value is zero except when you define a time value.
• It’s usually a bad idea to use em for text generated from a WYSIWYG editor.

/* Don't do that */
.selector {
  padding: 0px; /* Zero is a unitless value */
  line-height: 18px; /* Better use a unitless value to allow the line-height to scale with the font-size changes */
  border-width: 0.1rem; /* 1px is enought */
  transition-delay: 0; /* This value is invalid as time requires a unit (eg `0s`) */
}

/* The following is a button that appears near the top right of a modal window.
   Usually the position of the button isn't related to the dimensions of the
   modal so using percentage units here is wrong. It should be replace with
   other values like pixels or ems
 */
.close-button {
  top: 2%;
  right: 1%;
}

Shorthand values

Generally, we prefer to use the shorthand values instead of the expanded ones as long as these values are intended to be set. For example:

/* Don't do this unless you intend to set the vertical margins to zero */
.container {
  margin: 0 auto;
}

/* Do this instead */
.container {
  /* if you're using post-processors or the intended browsers supports logical properties and values */
  margin-inline: auto;
  /* or you can do this */
  margin-left: auto;
  margin-right: auto;
}

Do not override a value with a shorthand value. For example:

a {
  padding-left: 10px;
  padding: 20px; /* Padding is overriding padding-left making it useless */
}

Do not write redundant shorthand values. For example:

/* Don't do this */
.selector {
  padding: 10px 10px 10px 10px; /* `padding: 10px` is enough */
  margin: 10px 20px 10px 20px; /* `margin: 10px 20px` is enough */
}

Selectors

Psuedo-classes (:hover, :focus, etc) should use the : prefix, pseudo-elements (::after, ::before, ::selection, etc) should use the :: prefix.

/* Don't do this */
.selector:after {
  content: "Whatever";
}

/* Do this */
.selector::after {
  content: "Whatever";
}

Try to order your blocks according to the specificity of the selectors from the least to the most specific.

/* Don't do this */
.selector-1 .selector-2 {
  color: #000;
}

.selector-1 {
  background: #fff;
}

/* Do this */
.selector-1 {
  background: #fff;
}

.selector-1 .selector-2 {
  color: #000;
}

Do not combine vendor specific selectors with standard ones because it will make the whole declaration invalid.

/* Don't do this, this will not work */
::-webkit-slider-runnable-track,
::-moz-range-track {
  background: #fff;
}

/* Do this */
::-webkit-slider-runnable-track {
  background: #fff;
}
::-moz-range-track {
  background: #fff;
}

These are the important as well:

• Try not to nest more than 3 levels deep.
• Avoid duplicating selectors, it makes it harder to read and maintain.
• Media queries should be defined close to the elements they affect.
• Be careful when you’re using the :not() pseudo-class because it affect the specificity of the selector. Read more about this here.

Properties and values

Do not write duplicated values for the same property. For example:

/* Don't do this */
.selector {
  padding: 20px;
  /* ... some styles you write */
  padding: 10px;
}

No empty blocks. For example:

/* Don't do this */
.selector {
}

If you’re using an autoprefixer, don’t add a vendor prefix to the property. Autoprefixer will determine if the property is supported by the browsers using browserslist and caniuse. If it’s not, it will add the vendor prefix. For example:

/* Don't do this */
.selector {
  -webkit-transition: all 0.5s ease;
  transition: all 0.5s ease;
}

In case you have to use a vendor prefix, write the prefixed version of the property before the unprefixed one. For example:

/* Don't do this */
.selector {
  transition: all 0.5s ease;
  -webkit-transition: all 0.5s ease;

/* Do this instead */
.selector {
  -webkit-transition: all 0.5s ease;
  transition: all 0.5s ease;
}

Do not use subpixel values. Subpixel values are not supported by all browsers and they can lead to inconsistent dimensions. For example:

/* Don't do this */
.selector {
  width: 187.5px;
}

/* Do this instead */
.selector {
  width: 188px;
}

Inheritance

Inheritance is one of the most powerful features in CSS. It allows you to reuse styles from a parent selector. It’s preferred to make use of inheritance whenever possible. For example, font-family is inherited from the parent element. If we use a generic selector we explicitly apply the font-family to each element. Applying it to the parent element is a better practice.

/* Don't do this */
* {
  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
}

/* Do this instead */
body {
  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
}

Using !important

The keyword !important shouldn’t be used or at best limited to very narrow cases. The only place where you can see !important being used frequently is within the utilities layer. For example:

/* You can do this */
@media (max-width: 767px) {
  .hidden-on-mobile {
    display: none !important;
  }
}

Features specific to CSS

Box Model

In almost all your work you will need to set the box-sizing propert to border-box. This will facilite the calculation of the dimensions of the elements. Some external libraries still use or assume that the box-sizing is set to content-box. To overcome this problem, We set it to border-box on the root element, then inherit it to all the elements. This allows us to override it at any parent and all its siblings whenever we need.

html {
  box-sizing: border-box;
}

*, *::before, *::after {
  box-sizing: inherit;
}

Fonts

When defining a custom font using the @font-face at-rule, take care of the following:

• Make sure you generate the fonts in the modern formats (woff2, woff, ttf) and load them in the same order.
• If you’re using different weights for the same font, make sure that:
  • The @font-face at-rules have the same name.
  • The font-weight property is set correctly.
  • The @font-face at-rules are ordered ascendingly according to the weight.
• Use font-display property and set its value to swap to ensure the users can see the contents soon enough with no flash of invisible text. If the font is used for custom icons, it should be set to block to avoid displaying unreadable text (like square or any odd glyphs).

/* Don't do this */
@font-face {
  font-family: "MyFont Light";
  src: url("myfont-light.woff2");
}

@font-face {
  font-family: "MyFont Regular";
  src: url("myfont-regular.woff2");
}

/* Do this */
@font-face {
  font-family: "MyFont";
  src: url("myfont-light.woff2");
  font-weight: 300;
}

@font-face {
  font-family: "MyFont";
  src: url("myfont-regular.woff2");
  font-weight: 400;
}

When you set font, always:

1. provide a generic font family name.
2. Enclose custom font names within double quotes.

/* Don't do this */
body {
  font-family: MyFont;
}

/* Do this */
body {
  font-family: "MyFont", sans-serif;
}

Always remember that some elements like input and textarea doesn’t inherit the font family from their parent selectors, hence you should always specify the font family for them (using the inherit keyword or by directly defining the desired font).

Colors

For color values that permit it, 3 character hexadecimal notation is shorter and more succinct.

/* Don't do this */
.selector {
  color: #ff0000;
}

/* Do this instead */
.selector {
  color: #f00;
}

Do not use keyword color values. Replace it with a hexadecimal notation. For example:

/* Don't do this */
.selector {
  color: red;
}

/* Do this instead */
.selector {
  color: #f00;
}

Use all lowercase characters in hexadecimal notation. For example:

/* Don't do this */
.selector {
  color: #FFE6D8;
}

/* Do this instead */
.selector {
  color: #ffe6d8;
}

Floats

In most cases where you want to use float, you should clear the float property using the popular old clearfix hack.

Overflow

Do not use overflow to hide scrollbars if that’s not the desired behavior. Fix the overflow problem by properly making sure the content doesn’t overflow. For example:

/* Don't do this */
body {
  overflow-x: hidden;
}

Custom properties / Variables

CSS custom properties are a way to define variables that can be used in CSS. The rules that apply to picking up a good variable name applies to nameing the custom properties (like being representative to the value it holds, not being too generic, etc).

When picking up names for our color variables, we follow the same methodology followed by the Material design and TailwindCSS. For more information about this, read this article.

/* Don't do this */
:root {
  --colorPrimary: #2196f3;
  --colorSecondary: #9e9e9e;
}

/* Do this instead */
:root {
  --red-300: #ff8a8a;
  --red-500: #ff4d4d;
}