HTMHell Advent Calendar 2025

HTML Input Validation is (maybe) Good

2025-12-28T00:00:00Z

by Wes Goulet

I think of client-side validation as a progressive enhancement for your users. You have to validate user input on the server (you can't trust what comes from the client), but some validation on the client makes for a nice UX. But that doesn't have to mean lots of JS code or using some validation library on your client. You can get pretty far with the browser's built-in HTML input validation. And then you can layer a little bit of JS on top of that to make it even better.

Let's take a look at a text input. You can use pattern, minlength and maxlength to provide constraints. You can use title to provide error message. You can conditionally style invalid input with :user-invalid.

Example

<label for="program_name">Name of program</label>
<input
  type="text"
  id="program_name"
  minlength="3"
  maxlength="20"
  pattern="[a-zA-Z0-9]+"
  title="Only alphabetical and numerical characters are accepted"
  required
/>

input:user-invalid {
  border: 4px solid red;
}

When the user attempts to submit the form the browser takes care of validating and showing the message.

Example validation message on Chrome

Example validation message on Firefox

Example validation message on Safari

Example validation message on Safari on iOS

You can play with a live example at this CodePen.

BTW, I just noticed that Chrome and Firefox say "Please" but Safari doesn't 😃

Styling

You can't style the error popup, so if that's important to you then maybe you need to write your own error UI. A lot of times I don't mind leaning on browser UI when it's available (ie: most of the time I don't need my error messages in my website's overall brand/styling). Also, I think a lot of users have seen the browser's error UI before (from other sites that use native form validation), so there is some familiarity there for the user.

The Problem: Accessibility

Unfortunately, native form validation isn't very accessible.

I had assumed it was accessible, because most of the time when I lean on the browser to do something it handles accessibility much better than any userland code I would write. But after reading this excellent post from Adrian Roselli (an accessibility expert), I learned my assumption was wrong.

The main accessibility issues with native form validation are:

Error messages aren't associated with form fields - Screen readers don't reliably announce which field has an error, so users relying on assistive technology can't easily figure out what needs to be fixed.
Error messages disappear too quickly - The browser's error bubble might disappear before users can read it.
Error messages don't respect user text size/spacing preferences - The error bubble text doesn't resize with browser zoom settings or respect text spacing preferences.

Related to all this, a recent update to WCAG acknowledges these accessibility issues with native form validation.

Make it better with JS

I originally wrote this post to point out that native form validation is good enough (lean on the browser!) and that's all you need. But after reading about the accessibility issues, I think the right answer is using native form validation as the foundation, and then adding a bit of JS to make it more accessible.

We'll use the Constraint Validation API, which is the JavaScript interface for HTML form validation. It allows you to programmatically check if a form field is valid, get validation messages, and customize how errors are displayed to users. For example, you can check if an input is valid:

const element = document.getElementById("program_name");
console.log(element.checkValidity()); // returns true or false

You can also get the validation message:

const element = document.getElementById("program_name");
console.log(element.validationMessage); // returns the error message if invalid

We'll use the Constraint Validation API and follow WCAG input error guidance to create our own error messages that are properly associated with form fields. Here's a simple example:

<form id="my-form">
  <label for="program_name">Name of program</label>
  <input
    type="text"
    id="program_name"
    minlength="3"
    maxlength="20"
    pattern="[a-zA-Z0-9]+"
    title="Only alphabetical and numerical characters are accepted"
    required
    aria-describedby="program_name-error"
  />
  <span id="program_name-error" role="alert"></span>
</form>

const form = document.getElementById("my-form");
const input = document.getElementById("program_name");
const errorMessage = document.getElementById("program_name-error");

// IMPORTANT: set this attribute in JS, that way it's a
// progressive enhancement (ie: if JS isn't available the
// native form validation will still work).
form.setAttribute("novalidate", "");

function validateInput() {
  const isValid = input.checkValidity();
  errorMessage.textContent = isValid ? "" : input.validationMessage;
  if (isValid) {
    input.removeAttribute("aria-invalid");
  } else {
    input.setAttribute("aria-invalid", "true");
  }
}

// Validate on blur (when user leaves the field)
input.addEventListener("blur", validateInput);

// Clear errors as user types
input.addEventListener("input", () => {
  if (input.checkValidity()) {
    errorMessage.textContent = "";
    input.removeAttribute("aria-invalid");
  }
});

// Handle form submit
form.addEventListener("submit", (e) => {
  if (!form.checkValidity()) {
    e.preventDefault();
    // Update validation state for all fields
    validateInput();
  }
});

In this example:

The form has novalidate to turn off the browser's built-in validation (added via JavaScript so it degrades gracefully).
The error message is associated with the input using aria-describedby, so screen readers will announce it when the field is focused.
The error message has role="alert" so screen readers will announce it when it appears.
The input gets aria-invalid set appropriately, clearly marking it for assistive technologies.
Validation happens on blur (when the user leaves the field) and on form submit.
The error message stays visible, giving users time to read it.

You can play with a live example at this CodePen.

This post by Cloud Four spells out a more complete solution in detail. (If you mainly support evergreen browsers then I wouldn't worry too much about the first part "Removing invalid styles on page load for all browsers" since Chrome has shipped support for :user-invalid for a couple years now.)

So native HTML form validation is a good starting point, but it's not enough on its own due to accessibility issues. You can use the Constraint Validation API to layer on accessible error messages with a bit of JavaScript. That way you get the browser's validation working as a baseline, and then enhance it to be accessible when JS is available.

Thanks to Manuel for reviewing this post and pointing out the accessibility issues with native form validation.

Replacing JS with just HTML

2025-12-27T00:00:00Z

by Aaron T. Grogg

For many years now, JavaScript has been the workhorse of the web. If you wanted to do something that couldn't be done with just HTML and CSS, you could usually find a way to do it with JS.
And that is great! JS has helped push user experiences forward, and honestly helped push HTML and CSS forward!

But as time marches on, and the HTML and CSS methods gain traction, we need to start replacing the old JS methods that feel so comfy with new methods that require less JS.

Nothing against JS, but it has better things to do than setup and manage your accordions or offscreen navigation menus... Plus, JS needs to be downloaded, decompressed, evaluated, processed, and then often consumes memory to monitor and maintain features. If we can hand-off any JS functionality to native HTML or CSS, then users can download less stuff, and the remaining JS can pay attention to more important tasks that HTML and CSS can't handle (yet).

Below are a few examples; any you care to add?

Accordions / Expanding Content Panels

Description:

The details and summary HTML elements provide an HTML-only replacement to the typical JS accordion:

CopePen: Accordion / Expanding Content

Use cases:

Hiding/showing content
Expanding content sections

Basic implementation:

<details>
  <summary>Initially closed, click to open</summary>
  Content is initially hidden, but can be revealed by clicking the summary.
</details>

Add an open attribute to set the default appearance as "open":

<details open>
  <summary>Initially open, click to close</summary>
  Content is initially visible, but can be hidden by clicking the summary.
</details>

Use the same name attribute on all related details (like radio buttons) to restrict only one open panel at a time:

<details name="foo" open>
  <summary>Initially open, clicking others will close this</summary>
  Content is initially visible, but can be hidden by clicking the summary; only one panel can be open at a time.
</details>
<details name="foo">
  <summary>Initially closed, clicking will open this, and close others</summary>
  Content is initially hidden, but can be revealed by clicking the summary; only one panel can be open at a time.
</details>
<details name="foo">
  <summary>Initially closed, clicking will open this, and close others</summary>
  Content is initially hidden, but can be revealed by clicking the summary; only one panel can be open at a time.
</details>

You can also customize the appearance with CSS and trigger the open/close via JS.

Learn more about the details element in the previously-published “For the Love of <details>".

Resources:

Browser compatibility:

MDN details Browser Compatibility

Description:

Combining the HTML input and datalist elements can create a dropdown of options that autofilters as you type:

CodePen: Input with Autofilter Suggestions Dropdown

Use cases:

Site search
Product search or filter
Filter any list of data

Basic implementation:

<label for="browser">Browser</label>
<input type="text"
       list="browsers"
       id="browser" name="browser"
       size="50"
       autocomplete="off" />
<datalist id="browsers">
  <option value="Arc"></option>
  <option value="Brave"></option>
  <option value="Chrome"></option>
  <option value="DuckDuckGo"></option>
  <option value="Firefox"></option>
  <option value="Microsoft Edge"></option>
  <option value="Opera"></option>
  <option value="Safari"></option>
  <option value="Tor"></option>
  <option value="Vivaldi"></option></option>
</datalist>

You can also use other input types:

<label for="quantity">Quantity</label>
<input type="number" 
       list="quantity-options"
       id="quantity" name="quantity" />
<datalist id="quantity-options">
  <option value="1"></option>
  <option value="2"></option>
  <option value="5"></option>
  <option value="10"></option>
  <option value="20"></option>
  <option value="50"></option>
</datalist>

<label for="appointment">Appointment</label>
<input type="time" 
       list="appointments"
       id="appointment" name="appointment" />
<datalist id="appointments">
  <option value="12:00"></option>
  <option value="13:00"></option>
  <option value="14:00"></option>
</datalist>

Note that, at the time of this writing, Firefox was limited to only textual-based input types, so no date, time, range or color for now... :-(

Also note that, at the time of this writing, there are limitations on mobile, and accessibility concerns.

Resources:

Browser compatibility:

MDN datalist Browser Compatibility

Modals / Popovers

Description:

The popover and popovertarget attributes can replace the traditional JS-driven modal/popover/overlay:

CodePen: Modal / Popover

Use cases:

Hiding/showing side panels / additional information

Basic implementation

An auto popover (default) can be "light dismissed" (clicking outside of it or hitting the esc key). Opening an auto automatically closes any other auto popovers that were open. Clicking the button a second time will close the one it opened.

<button popovertarget="pop-auto">
   Toggle Popover
</button>
<dialog popover id="pop-auto">
   I'm an "auto" Popover!
</dialog>

A hint popover can also be "light dismissed". It does not close other hint popovers when opened. Clicking the button a second time will close the one it opened.

<button popovertarget="pop-hint">
   Toggle Popover
</button>
<dialog popover="hint" id="pop-hint">
   I'm a "hint" Popover!
</dialog>

Note that, at the time of this writing, Firefox and all iOS varieties do not support hint popovers.

A manual popover can not be "light dismissed". It does not close other manual popovers when opened. Clicking the button a second time will close the one it opened.

<button popovertarget="pop-manual">
   Toggle Popover
</button>
<dialog popover="manual" id="pop-manual">
   I'm a "manual" Popover!
</dialog>

Learn more about the opening and closing dialogs and popovers in the previously-published “Controlling dialogs and popovers with the Invoker Commands API".

Resources:

Browser compatibility:

MDN popover Browser Compatibility

Offscreen Nav / Content

Description:

The above Modal / Popover functionality can also be used to create an offscreen navigation that requires no JS:

CodePen: Offscreen Content

Use cases:

Hiding/showing navigation menus

Basic implementation:

<button popovertarget="menu">
   Toggle Menu
</button>
<nav popover id="menu">
   Nav Content
</nav>

#menu {
  margin: 0;
  height: 100vh;
  translate: -100vw;
}
#menu:popover-open {
  translate: 0;
}

I use a nav element to give it semantic value, but you can use any HTML element (div, section, aside, etc.).

A popover defaults to position: fixed per the User Agent Stylesheet, and is simply pushed off screen when closed, and pulled back onscreen when it is open. Note that margin: 0 is required if you want to override the User Agent center-alignment.

Clicking outside of the above menu closes it. You can force the panel to stay open, requiring a manual/explicit close, by using popover="manual".

You can also add a backdrop pseudo element and style it as you wish:

#menu::backdrop {
  background: rgb(190 190 190 / 75%);
}

Resources:

Browser compatibility:

MDN popover Browser Compatibility

Conclusion

While we all love the power and flexibility JS provides, we should also respect it, and our users, by limiting its use to what it needs to do.

There is so much more that has changed in recent years, including a ton of options that CSS now covers. If you are now hungry for more, have a look at [my longer article that covers those as well](https://aarontgrogg.com/blog/2023/05/31/replace-js-with-no-js-or-lo-js-options/.

Happy reducing!
Atg

Class names for content not design

2025-12-26T00:00:00Z

by Darice de Cuba

One of the first thing I learned when I started coding HTML, besides using div instead of tables for the layout, was naming classes. One of the core ideas being that with HTML and CSS we keep content separate from design. A website should have solid HTML and class names in such a way that you can redesign the website by only editing the CSS and maybe a little bit of the HTML.

But to do that, the class and id names need to be reusable. If you make the class names design and layout specific, you will have to edit your HTML files every time you want to change these elements their position or design, instead of only editing the CSS file.

Due to the use of frameworks, a lot of sites nowadays have become a div and class soup that makes the HTML code unreadable and hard to troubleshoot. Developers who never learnt to code HTML from scratch lack the basic understanding of a solid HTML layout with good class names.

Generic class names

Some example of bad class names are:

<h1 class="text-header-blue"> a better way is <h1 class="site-name"> and for articles <h1 class="post-title">
<nav class="top"> a better way is <nav class="main">
<li class="border-bottom"> a better way is <li class="selected">

Class names shouldn’t be design dependent, but specific to content. A text header won’t always be blue, but it will always be the site name. It also makes it easier to read your HTML code 3 months later and not be confussed about what is what.

Best practice is to never use, colours, spacing, marking, etc. as class names. Only generic names that are independent of how the layout and design looks like.

A basic weblog homepage can look like this:

<article>
    <div class="meta">
        <time class="date" datetime="2025-12-26T19:00"> December 26, 2025 </time>
        <span class="category">HTML</span>
    </div>

    <h1 class="post-title">
        <a href="https://www.htmhell.dev">How to HTML</a>
    </h1>

    <div class="intro">
        <p>
            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
            labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco
            laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in
            voluptate velit esse cillum dolore eu fugiat nulla pariatur.
        </p>
    </div>
    <a href="https:/www.htmhell.dev/adventcalendar/2025/26/" class="read-more">
        Read more 
        <span class="visually-hidden">
            about “How to HTML”
        </span></a>
</article>

The above HTML example is completely design and layout neutral. The layout and design can be edited only with CSS without having to change things in the HTML.

Conclusion

Keep your class and variable names generic. You want to avoid having to go through all your HTML and CSS code to change names to keep the code readable. There is nothing more painful than having to come back after each design or layout edit and be at lost what is what because <h1 class="serif-text-header-blue"> is not blue any more, but a sans font in bright pink.

Abbreviations done right: The <abbr> element and why not use it

2025-12-25T00:00:00Z

by Alexander Muzenhardt

Introduction

Abbreviations are great. They save time and space, make things efficient and tidy, and can even improve readability. But with the wrong technique, these abbreviations can turn into hell when it comes to accessibility.

The perfect element for abbreviations

So, the first thing you do: you look up “abbreviations in HTML” and land straight on MDN (Mozilla Developer Network), at the <abbr> element. <abbr> is the short form for abbreviation. The documentation shows exactly how to use it properly — and even has an accessibility section. It says that <abbr> helps people understand what an abbreviation means, especially when it is technical or industry jargon.

<p>The <abbr title="Mozilla Developer Network">MDN</abbr> is a documentation repository and learning resource for web developers.</p>

Perfect. Exactly what you were looking for. Semantic, accessible — what could go wrong?
So you start using <abbr> everywhere. However, after a while you get feedback from people asking what those abbreviations mean and an accessibility report complaining about … those very same abbreviations.

Why? According to MDN, you did everything right.

The problem with abbr

The biggest problem with the <abbr> element is that its title attribute behaves completely inconsistently across browsers, and some assistive technologies do not read parts of it at all.
Adrian Roselli has already run extensive tests on his blog article “Using abbr Element with title Attribute” showing that the title attribute on <abbr> elements is not announced by assistive technologies.

On top of that, the title attribute is a problem on touch devices — there is simply no way to access it on a smartphone. It only appears on hover, and hover does not exist on touchscreens.

No matter how you look at it, when you use <abbr>, at least one group of users will always miss out on information they need.

The simple solution we are all looking for

The easiest way to make abbreviations accessible is to spell them out the first time they appear, followed by the abbreviation in parentheses or vice versa.
After that, you can simply use the abbreviation throughout the rest of the text — it’s already been explained once.

This approach is also accepted by WCAG (Web Content Accessibility Guidelines) 2.2 as a “Sufficient Technique” under “G97: Providing the first use of an abbreviation immediately before or after the expanded form”.
And the best part: you do not even need to touch your HTML markup — you just make your text a bit clearer.

Examples

First example

In this example, the abbreviation comes first, followed by its full meaning in parentheses.
"The WAI (Web Accessibility Initiative) demonstrates the W3C (World Wide Web Consortium) commitment to accessibility."

Second example

The reverse is equally correct and accessible.
"The United Nations High Commissioner for Human Rights (UNHCR) was established in 1950 to provide protection and assistance to refugees."

The key is consistency: do not switch between the two styles on the same website. Pick one and stick with it.

The alternatives you may need

Below are three possible alternatives. They vary in complexity, and when implementing them, accessibility should always remain a priority. This is especially true for the third option — a dictionary search — where the input field and surrounding UI also need to be accessible.

I am intentionally leaving out implementation details here, as they would go beyond the scope of this article. These examples rely on other WCAG techniques that are not directly related to abbreviations. You will find plenty of examples online — and if you have questions about any of these approaches, feel free to reach out.

Linking to definitions

Of course, spelling out abbreviations is not the only option. You can also link an abbreviation to a page that explains it in detail. There are several ways to do this, all clearly outlined in “G55: Linking to definitions”.

Providing a glossary

Another option is to provide an internal or external glossary that lists and explains all abbreviations used on your website. You can either link to it or simply reference it when abbreviations appear.
Just like in books, glossaries can live at the end of a site or section — and readers can look up terms as needed.
A clear explanation of this approach can be found under “G62: Providing a glossary”.

Providing a function to search an online dictionary

A more elegant approach is to include a search feature on your site that queries an online dictionary for abbreviations and displays relevant results.
You can find more information on this technique in “G70: Providing a function to search an online dictionary”.

Conclusion

Skip the <abbr> element altogether.
Right now, it does not add any real value — it only creates a false sense that your abbreviations are truly accessible and understandable by all persons.

The best and by far simplest solution is to clearly spell out each abbreviation the first time you use it, and then stick to the short form for the rest of the text.

Cheers
Alex

Resources

Using abbr Element with title Attribute - by Adrian Roselli
THE ABBR ELEMENT - by Heydon Pickering
The HTML abbr-tag – Managing Abbreviations the Right Way (German) - by Ria Weyprecht
<abbr>: The Abbreviation element - by mdn
Understanding SC 3.1.4: Abbreviations (Level AAA) - by W3C
Technique G55: Linking to definitions - by W3C
Technique G62: Providing a glossary - by W3C
Technique G70: Providing a function to search an online dictionary - by W3C
Technique G97: Providing the first use of an abbreviation immediately before or after the expanded form - by W3C

The three semantics of HTML

2025-12-24T00:00:00Z

by Tomasz Jakut

There is always that one elephant in the room alongside HTML – semantics. You can ignore it for quite a while, but at the end of the day, you'll need to acknowledge that it's there, cluttering half of the space.

Our beloved elephant

So let's examine this exotic beast! According to Longman Dictionary of Contemporary English, semantics is the meaning of a word or expression. In our case, a word is an HTML element. And how can we check what the meaning of a word is? Well, we've already done that – we've checked the semantics of the semantics (inception!). Fortunately, there is also a dictionary for HTML – it's called HTML Living Standard. It even says it contains meanings:

Elements, attributes, and attribute values in HTML are defined (by this specification) to have certain meanings (semantics).

Detailed descriptions of all HTML elements are in chapter 4, called The elements of HTML.

Note: That's why I'm not keen on the semantic elements concept. For me, they are all semantic – even <div> – since their meanings are described in the specification.

But what if I told you there are actually three elephants in the room?

First semantics: for users

This is the most straightforward one of them all. That's the most basic role of semantics: to provide the end user with all the information necessary to correctly understand the content.

This type of semantics can be compared to formatting a text document in Word. You can always select some text and make it bigger and bolder, pretending it's a heading. But then you won't be able to generate a Table of Contents for your document with 100+ pages. The same is true for HTML – except it's the user that will suffer. Let's look at an example – my short bio:

<div>
  <div>Comandeer</div>
  <img src="comandeer.avif" alt="">
  <div>Proud HTML Expert</div>
</div>

It's still "semantic HTML" (because every HTML element has a meaning!), yet it's not especially useful. And yes, we can style it in any imaginable way (I bet we can even make it do the can-can with a bit of CSS magic) – but it's still just a bunch of <div>s without any intrinsic meaning:

The div element has no special meaning at all.

Just like this big, bold text in Word – if it's not a heading, it's not a heading.

Let's focus on raw HTML, forgetting about CSS. If we load the above code in the browser, it will look like this:

It's plain text. And in terms of HTML semantics, that's the truth – we used all these HTML elements to mark up plain text. Good job!

Fortunately, it can be easily fixed:

<article>
  <h1>Comandeer</h1>
  <img src="comandeer.avif" alt="A photo of a smiling Comandeer.">
  <p>Proud HTML Expert</p>
</article>

The wrapper <div> element was replaced with the <article> one – a bio can be treated as a complete, or self-contained, composition in a document.
The <div> element with my name was replaced with the <h1> element to indicate the purpose of the <article>.
The image got a descriptive alt attribute, describing its content.
The last <div> was replaced with the <p> element – after all, it's a paragraph of text.

If we open the document in the browser, it looks better:

In other words, we formatted our text!

Note: Each HTML element has its own default styles, used to display it when there are no stylesheets provided by the website owner. This is the purest achievable form of HTML in a browser.

But it isn't particularly useful on its own. After all, there's always some CSS to make things prettier – why should we care about choosing appropriate HTML elements? Because the Web should not be only visual. One of the main principles of Web Content Accessibility Guidelines (WCAG) is Perceivable:

Information and user interface components must be presentable to users in ways they can perceive.

In other words, if someone can't perceive visual information, it must be available for them in another form. A bunch of styled <div>s do not convey any meaning without their visuals. And that's problematic for assistive technology, like screen readers. Screen readers use an accessibility tree – a DOM-like structure, built from the page's HTML and containing information about roles and purposes of all HTML elements. Let's see what that tree looks like for the <div> version of the page:

It's just a text. More importantly, the image is missing, due to its empty alt attribute. The <article> version is much better:

Thanks to that, the screen reader can successfully transform the page content into voice or braille and inform the user where the articles, headings, and other elements are. It would not only allow the user to fully understand the page (similarly to how the non-screen-reader user perceived the visual version of the page) but also allow the screen reader to provide better ways of navigating the page, e.g., by jumping to headings.

In other words, caring about semantics is caring for the user!

Second semantics: for user agents

Semantics can also be used to provide additional information for user agents. And I deliberately use this term in quite a wide meaning, to mean any machine or software acting on behalf of its user. The most obvious example of a user agent is a browser (which is the term's typical meaning), but I would extend that name also to search engines. With a long history of SEO (Search Engine Optimization), it's not a mystery that search engines can and do understand HTML – just to mention everlasting discussions about the importance of heading elements. Also, browsers can use semantics to provide affordances for users, like using the <article> element to extract content in a reader mode. But there are also other ways to provide yet another layer of semantics just for machines.

The most ambitious take on semantics for user agents is Web 3.0. And no, I don't mean Web3, based on blockchain. Long before that, back in the 2000s, W3C imagined a new type of web, as they called it – Web of Data and Services, aka Semantic Web. The idea itself was quite simple yet ingenious: the Web is full of data, but there was no way to enable effective communication between different websites and apps. Back then, machines were also far worse at discovering and understanding data. So they needed us, humans, to mark up data for them. The most basic way of marking stuff up is using HTML. But several additional technologies were developed to allow embedding additional metadata into websites. One of the first was Resource Description Framework (RDF). It's a huge standard, divided into several specifications. Yet it has one, pretty serious, downside: it's not built on top of HTML, as it has its own syntaxes (yes, plural). That's why RDFa has been developed. It's a "lighter" version of RDF and can be used inside HTML via attributes:

<article vocab="https://schema.org/" typeof="Person">
  <h1 property="name">Comandeer</h1>
  <img src="comandeer.avif" property="image" alt="A photo of a smiling Comandeer.">
  <p>Proud <span property="jobTitle">HTML Expert</span></p>
</article>

The vocab attribute points to the vocabulary we want to use and the typeof one – a type of data we try to mark up. In our example, we want to spice up my bio with some additional metadata. Due to that, we decided to use the Person type (as I'm personally a person). Each property of, well, me is marked up with the property attribute, e.g., the heading with the name now has the property="name" attribute.

But of course, there is always more than one way to do something. HTML has its own way of marking up additional metadata, so-called microdata:

<article itemscope itemtype="https://schema.org/Person">
  <h1 itemprop="name">Comandeer</h1>
  <img src="comandeer.avif" itemprop="image" alt="A photo of a smiling Comandeer.">
  <p>Proud <span itemprop="jobTitle">HTML Expert</span></p>
</article>

It's pretty similar to RDFa. Instead of vocab + typeof attributes, it uses itemscope + itemtype ones, and the property one is replaced with itemprop one.

And if we want something more like RDF (so a separate thing from HTML), there is always JSON-LD – a way to express metadata in JSON. I also need to make one honorable mention – microformats. They are the OGs of metadata in HTML. They use the class attribute to provide additional info about the content:

<article class="h-card">
  <h1 class="p-name">Comandeer</h1>
  <img src="comandeer.avif" class="u-photo" alt="A photo of a smiling Comandeer.">
  <p>Proud <span class="p-job-title">HTML Expert</span></p>
</article>

The hCard microformat is used for marking up information about people. What I love about microformats is the fact that they are Just HTML™ without any fancy attributes.

Note: Personally, I'm a fan of the RDFa format, so I'll stick to it for the rest of the article.

But what are vocabularies? In short, they are catalogs of things that can be described, like people, events, books, and places. Each of these things has its own unique set of properties (people have names, places have addresses, events have dates…). Things can also be mixed together (events are organized by people, etc.). Thanks to that, even more complex pieces of reality can be described in a manner understandable by machines.

In our example, the Schema.org vocabulary is used. Schema.org is a community effort, founded by Google, Microsoft, Yahoo, and Yandex, with a goal to create an open standard for structured data on the Web. This data is then used by search engines to provide additional information about the websites' content. Google provides a gallery of how it uses the structured data to prepare more detailed search results.

The only problem with Web 3.0 is that it never happened. Granted, we have several great technologies to embed additional metadata. But at the end of the day, they're used mainly by search engines. The ambitious vision of the Web where machines talk to each other and exchange data to provide better services to their users is still just a vision.

Third semantics: for web developers

And finally, we can leave the vast land of user-centered semantics and enter the cozy territory of developer-centered semantics. Because an easily understandable HTML is also an easily maintainable HTML. And if we use HTML elements as intended (like creating lists with <ul> and <li> elements instead of <div>s), we're already halfway there!

But sometimes additional info is needed, e.g., a page contains several <article> elements and we want to easily distinguish between them. In that case, we can go back to webdev roots and use the class attribute.

<article vocab="https://schema.org/" typeof="Person" class="bio">
  <h1 property="name" class="bio__name">Comandeer</h1>
  <img src="comandeer.avif" property="image" alt="A photo of a smiling Comandeer." class="bio__image">
  <p class="bio__description">Proud <span property="jobTitle" class="bio__job-title">HTML Expert</span></p>
</article>

I'm using a BEM-like naming convention here to indicate that this particular <article> is a bio. Each of the elements inside the <article> also has its own class name, indicating its purpose.

Note: It can be argued that most of these classes are redundant, repeating the information already provided by RDFa. Yet I tend to treat BEM not as a naming convention but as a DSL (Domain Specific Language) for creating component-based applications. However, that's a story for another time.

There are also other ways to make HTML more developer-friendly. One of the better (at least in my opinion) is to use custom elements to replace plain old <div>s:

<div class="card"></div>
<!-- vs -->
<the-card></the-card>

We would also need to add a little bit of CSS:

:not(:defined) {
  display: block;
}

It ensures that custom elements are displayed as block elements (that is, like <div>s) because by default, they’re displayed inline (like <span>s).

Fourth semantics?

Yet another elephant looms on the horizon… There is no doubt that we live in the AI era. LLMs (Large Language Models) are everywhere around us, and they are yet another kind of machine that can understand HTML. But hey, they are language models, finally our technology has advanced enough to be able to fully grasp the beauty of Web 3.0!

Except it doesn't seem to be the case. Instead of using what we already have, new standards emerge [insert XKCD strip about standards here]. The most popular of them is the /llms.txt file. It's a Markdown file containing detailed instructions for LLMs on how to handle the website and where particular info is located.

It’s quite ironic that after years of striving toward a semantic Web, we finally have the technology capable of understanding it - and it still doesn’t work. Oh, well, maybe in another 20 years…

However, there is a glimpse of change! OpenAI recently released their AI browser, Atlas. Supposedly, it understands ARIA. In theory, the more accessible a site is, the more it's suitable for ChatGPT. In practice, it could make the Web far worse. ARIA should be the last resort when native HTML is not enough to express a complex UI pattern. Adding it solely to impress a machine sounds disturbingly similar to an ancient arcane of stuffing web pages with invisible links to fool crawlers. On the other hand, Atlas's reliance on ARIA could be a visible symptom of The Great Disease of the Web: LLMs are powerful enough to understand HTML semantics, but there is no semantics to be understood…

Managing the menagerie

Let me ask you a fundamental question: do you pay attention to HTML semantics?

If the answer is "yes", then good job, your elephants are happy and thriving 🐘!

However, if the answer is "no"… Don't make them sad, find a little bit of time and enhance your HTML. Throw away extraneous <div>s, add a couple of headings, embed some metadata! There is no need to do everything at once; do it step by step. Every little improvement matters and can make someone's day a little better. A screenreader user will be grateful for that additional heading, your fellow web developer will thank you for that extra class, and a crawler… Well, it won't feel anything, but hey, it will understand your content better!

If you do not know how to start, I suggest removing all distractions – including CSS – and focusing on the raw content. Copy it to your favourite word processor and think about the role of each element and its relationship with other elements. And then format all of them according to your findings. That's your content's semantics, waiting to be ported back to HTML!

Do it, for your users, for your fellow web developers (not necessarily for crawlers…), but most importantly – for the elephants!

For the Love of <details>

2025-12-23T00:00:00Z

by Justin Ferrell

When you list all the things HTML can do out of the box without the help of CSS or Javascript, it can seem like a short list. Headings and lists will come to mind. You will most likely think of things like images and video. Any good list of HTML elements will grow to include form elements like input and select, the original interactive elements, too. Recently, a lot of work and attention has turned to some of the lesser known semantic HTML elements too. The work of Heydon Pickering comes to mind, and his incredible effort to explain every HTML element in alphabetical order.

Among the lists and the images and the forms and the videos though, I think there is an unsung hero. There is a piece of semantic markup that exists at the intersection of SEO, accessibility, performance and interactivity.

I am talking of course about the <details> element and its partner, the <summary> element.

<details> Details

For the uninitiated, the <details> element acts as a disclosure widget. When I was getting my start in early 2011, the <details> element would have (incorrectly) been called an accordion if it existed at the time. It consists of an outer <details> element with a <summary> element nested directly beneath it. In its “closed” state, only the <summary> element is visible. When open (with an [open] attribute present on the <details> element) all of the content following the <summary> element is made visible.

See the Pen Basic Demo of <details> by Justin Ferrell (@developerjustin) on CodePen.

The most remarkable thing about the <details> element is that this disclosure functionality requires no dependencies of any kind. It requires zero CSS or Javascript of any kind, is keyboard navigable and accessible out of the box and is widely understood by search engines and web crawlers alike, making it a semantic choice for things like FAQ’s.

Put simply, <details> is one of the few semantic, interactive elements HTML gives us. That scarcity makes it special.

<details> Are Always in Style

If an element gives you so much for free, surely it must fight back when you try to style it, right?

Not the case!

The triangle disclosure icon that you see in a <details> element is actually the list-item marker of the <summary> element. In modern browsers, you can target it with the summary::marker pseudo-element. You can change the size, color, icon and even if the symbol is present at all.

Because the open state of the <details> element is marked using an [open] attribute, it’s possible to target the <details> element, the <summary> element and anything therein just by using an attribute selector.

See the Pen Untitled by Justin Ferrell (@developerjustin) on CodePen.

And using the ::details-content selector, you can target the inner content of the <details> element too! This ::details-content selector is particularly powerful when paired with the [open] attribute selector.

See the Pen Untitled by Justin Ferrell (@developerjustin) on CodePen.

Though browser support isn’t perfect, it’s even possible to tweak the animation and transition of a <details> element from its open state to its closed state.

The Devil and the <details>

Just like its Cascading Counterpart, Javascript is no stranger to the <details> element.

The <details> element fires a toggle event when opened or closed. You can attach an event listener to that just like you would with any other element.

See the Pen Scripted <details> Demo by Justin Ferrell (@developerjustin) on CodePen.

To really get at what makes the <details> element tick though, you can always set the open property of the element to true/false to open or close the widget respectively.

See the Pen Toggle <details> Demo by Justin Ferrell (@developerjustin) on CodePen.

Prevails Through <details>

The power of <details> does not stop with how you can style it and how you can interact with it via Javascript. The <details> element has additional capabilities via good old HTML that are arguably more powerful than anything you can do it with Javascript.

Deeping Linking

A handy feature of most modern browsers (looking at you, Safari) is that navigating to an anchor or fragment inside a closed <details> will automatically open it so the user can see the target.

Remarkably, on-page search supports the <details> element too! Browsers support varies but in most modern browsers, traditional "Command/Control + F" search will query the contents of the <details> element and expand them as needed.

See the Pen Untitled by Justin Ferrell (@developerjustin) on CodePen.

Exclusivity

Details elements support a name attribute to group them into an exclusive set (like radio buttons). If multiple <details> share the same name, opening one will automatically close any others in that group.

See the Pen Exclusive <details> Demo by Justin Ferrell (@developerjustin) on CodePen.

It's worth flagging the potential for accessibility issues related to this feature. Exclusive <details> elements are more likely to cause a higher cognitive load and make the comparison of details more difficult. Exclusive <details> elements are by nature more complicated to use with a keyboard and may also cause issues with visibility and screen readers.

"But her <details>!"

In 2025, <details> is well supported across major browsers, though some versions of Safari still have quirks like not auto-opening on anchor links. It’s pretty unlikely that you’ll run into meaningful issues but it’s always good to see what browsers your users are using.

In <summary>

While humble on the surface, the <details> element is an untapped treasure trove of interactivity. It can do so much out of the box but paired with some creative HTML and CSS, it’s easy to imagine dozens of uses for the <details> element that do not compromise on performance, accessibility or SEO visibility.

Here are 6 not-so-real world examples with a focus on accessibility and SEO.

Frequently Asked Questions (FAQs): This really is the gold standard for this element. It can help keep pages tidy while ensuring the content is fully indexable by search engines and completely accessible to screen readers without complex ARIA attributes.
Video & Audio Transcripts: A massive SEO and accessibility win. <details> allows you to include the full text of a podcast or video for keyword indexing and hearing-impaired users, without forcing users to scroll past a massive wall of text to reach the footer.
Product Specification Tables: <details> allows you to hide dense, technical rows (dimensions, materials, voltages) that are crucial for technical SEO rankings but visually overwhelming for the average shopper.
Table of Contents: Placing a collapsible "On this page" navigation widget at the top (or sticky side) of long articles helps bots understand page structure and helps users jump to relevant sections immediately.
Long-form Content "TL;DR": Placing an Executive Summary at the very top of a long article that expands for the full breakdown. This improves "Time on Page" metrics by letting users get the gist immediately rather than bouncing because the article looks too long.
Expanded Author Bios: Enhance your E-E-A-T (Experience, Expertise, Authoritativeness, and Trustworthiness) signals by including full credentials, past work, and social links in a bio that expands, rather than just a simple name and photo.

I hope you find even more uses for <details> in your own work!

The HTML Elements Time Forgot

2025-12-22T00:00:00Z

by Declan Chidlow

Last year I inflicted upon you the cursed knowledge of HTML's legacy colour parsing, a crime for which I'm still yet to pay. This year, I return with more unwanted and unrequested HTML knowledge of yore.

The truth is, HTML is getting old, folks. The initial release was 1993, 32 years ago. It certainly isn't decrepit, but it does have a storied past – a couple of missteps, tabloid scandals, and unflattering paparazzi photos. That's why I'm so glad you're joining us here today to peruse some of these bad haircuts of HTML's youth.

In the HTML Living Standard there are explicit considerations for what are called non-conforming features. To quote the standard, Elements in the following list are entirely obsolete, and must not be used by authors. Thus, I shall issue the disclaimer not to use these lest WHATWG show up at my door.

<marquee> is perhaps the most famous of all, second only to <blink>, which was never standardised. Daniela Kubesch wrote about the marquee tag and implementing it in a modern way previously, so I'll leave that to them.

But there are far more obscure tags which are perhaps less visually dazzling but equally or even more interesting. If you're younger, this might very well be your introduction to them. If you're older, this still might be an introduction, but also possibly a trip down memory lane or a flashback to the horrors of the first browser war. It depends.

bgsound

<bgsound> was a way to play sound in the background, because everyone loves web pages making sounds they didn't ask for at them. It was not standardised, and exclusively part of Internet Explorer. The <audio> tag is the much more courteous modern equivalent.

I find it endlessly humorous that the old HTML Wiki's example section for the tag simply states, 'No, really. Don't use it.'. Many of the old and obscure elements share the same detail.

Framesets

In the olden days, people used 'frames'. Not iframes mind you, just frames. You can think of their usage vaguely like the HTML imports we have now... Wait, what do you mean we still don't have HTML imports?

I digress. This was a time long before single-page applications (SPAs) or anything of that nature. Frames were widely used as a way to aid navigation without needing to reload the page. You could have a navigation frame that persisted while the content frame changed.

<frame> is more or less the same as our modern <iframe>, though we use iframes much more for embedding than page layout. <frameset> holds these frames, so you could write something like <frameset cols="50%, 50%"> to have two frames next to each other.

The frameset approach had quite a few problems. Accessibility was really poor, and because everything was a single page, it could be hard to link to a specific section. ~~Thankfully we've come a long way since then, and developers take great care with accessibility and ensuring their SPAs respect the web platform.~~

Similarly to how <noscript> is triggered if JavaScript isn't supported, <noframes> allows you to set content if frames aren't supported.

While they absolutely shouldn't be used anymore, unlike much of what this article covers, frames and framesets are still supported. They may have been deprecated in HTML5, but the web's backward compatibility keeps them going.

Code

<pre> and <code> aren't strangers to us. We're good friends, no matter the horrific scripts we may force them to hold. However, pre-<pre> and <code> there were plenty of other implementations in the wind.

The example element, <xmp>, is like our modern <pre>, but doesn't interpret special characters like <, >, or &. With <pre>, we often need to escape these values to avoid Unwanted Shenanigans™.

<listing> is yet another step in presenting code on a page. It aimed to display text exactly as the author wrote it, preserving whitespace and formatting, but never got proper support and became obsolete with HTML5. Modern browsers handle it the same as <pre>.

<plaintext> is a funny one. It does what it says on the tin – that is, tells the browser to interpret everything after it as plain text. Of course, this means that any potential closing tag is also interpreted as plain text and therefore not parsed by the browser. Once opened, you cannot close a <plaintext>. The rest of the file becomes plaintext for eternity and whatever comes after. It was deprecated in HTML 2 and made invalid in HTML 4, so most modern browsers just interpret it the same as a <pre>. The modern approach is to serve content with a MIME type of text/plain.

spacer

Before the modern days of flexbox and grid and even floats, we laid things out with tables. Like cavepeople.

Of course, sometimes with tables, you need a spacer. spacer.gif used to be popular – a simple 1px × 1px image that could be used to fill a space. But then Netscape got fancy with it and introduced the totally tubular <spacer> tag. You could write <spacer width="50" height="20"> on your website and get a little element that took up some space.

Pretty fly, though this was only a stop-gap implementation that didn't last long and was never standardised.

keygen

I hear keygen, and my mind goes to acquiring a copy of a video game or enterprise software in a less than scrupulous way. That isn't to say the <keygen> element had anything to do with software cracking, though, and unfortunately didn't come with sick tunes.

It was a way for browsers to generate public-private key pairs for form submissions, primarily used for certificate generation. The idea was to make cryptographic operations easier for users, but in practice, it had security concerns and inconsistent browser support. You can read a little bit of discussion from the time in this mailing list thread. It was deprecated and is now removed from all modern browsers.

nextid

<nextid> comes with the fun trivia of being the first tag to be eliminated from the official public DTD's of HTML versions. It was used by early HTML editors to generate unique identifiers but quickly became obsolete. It was part of those early days of HTML where the vision wasn't just viewing but also editing.

It is a hard element to get much info about, and it seems I'm not alone in thinking that, as the very interesting and well-worth-a-read document Working NEXTID Tag Element Example has this to say:

It is also probably one of the least understood of all of the early HTML elements, being poorly documented, not explained in any depth anywhere, and those who obviously understood how it worked couldn't be bothered to explain it to the rest of us.

isindex

<isindex> is a particularly interesting part of the old web because, perhaps more than any other tag shown here, it reflects a very different vision of HTML semantics. It was a way to define a search box that would submit queries directly to the server. You'd write something like:

<isindex prompt="Enter your search term here:">

This primitive search functionality was eventually superseded by proper form elements, giving developers much more control over how search interfaces worked.

dir

I'm talking about <dir>, not dir – the element, not the property indicating text direction. The purpose of <dir> was to serve as a container for files and directories. It wasn't just your bog-standard list, though, because the user agent could apply different styles and icons depending on the content type.

You could also give it the attribute compact to make the content take up less space in an effect similar to setting line-height. As you might imagine, the modern equivalent is to use a standard list with <ul> or <ol>.

Closing Tags

It is easy for us to look back from the year of our lord ${new Date().getFullYear()} and ridicule what obviously wasn't to be, but these stumblings have made HTML what it is today. No, they weren't perfect, but it is mistakes that we learn from.

These obsolete tags represent experiments in web development—some more successful than others. They're a reminder that the web platform we use today is the result of decades of trial, error, and evolution. And who knows? Maybe someday developers will look back at our current HTML practices with the same bemused affection.

We often think of the web as forever backwards compatible and never breaking, but that plainly isn't the case. As we've seen, there are plenty of elements that have been left behind in the march of progress. The web evolves, standards change, and what was once cutting-edge becomes a curious footnote in the platform's history.

Styling by Language: Using the lang Attribute for Multilingual Design

2025-12-21T00:00:00Z

by Julia Undeutsch

When East Meets West (on the Same Page)

If you’ve ever built a bilingual English – Japanese website, you know the struggle. English uses letters with ascenders, descenders, and varying widths. Japanese, on the other hand, mixes three scripts: kanji, hiragana, and katakana, each forming balanced, square-like characters.

Already last year, I told you about a special HTML element that you can use to style this scripts. Read my post HTML and CSS I didn't even know about before I started creating content.

This is not usually a big problem if the entire page is in one language. But when Latin letters are mixed with Japanese characters, as is increasingly the case, the font becomes more difficult to handle.

That means:

Japanese text usually needs more line height to breathe.
Kanji often appear denser and more detailed than Latin letters.
Western fonts can feel too “light” next to Japanese text.

This is where the lang attribute becomes your best friend. And he brings a plus one: CSS.

Let the Language Drive the Design

<p lang="en">Welcome to Starbucks.</p>
<p lang="ja">スターバックスへようこそ。</p>

:lang(en) {
  font-family: "Nunito Sans", sans-serif;
}

:lang(ja) {
  font-family: "Noto Sans JP" sans-serif;
}

Welcome to Starbucks.

スターバックスへようこそ。

Here, the English text uses Nunito, which has friendly, rounded shapes. The Japanese version pairs quite good with Noto Sans JP (Google Fonts), which was designed specifically as a typeface for all writing systems around the world. Since the content is separate, both fonts appear suitable and visually balanced.
Read more about the Noto: A typeface for the world project.

Font Weight and Visual Balance

However, when both writing systems are mixed together, which is common in the Japanese language today, typographical mismatches become noticeable. Meaning, When mixing languages, a font weight of 400 for Japanese might look visually heavier than 400 in Latin text because kana systems are more complex in shape.

<p lang="ja"><span lang="en">Starbucks</span>へようこそ。</p>

Starbucksへようこそ。

You can correct this by slightly adjusting weights between languages:

:lang(en) {
  font-weight: 400;
}

:lang(ja) {
  font-weight: 300;
}

Starbucksへようこそ。

This subtle change keeps both scripts visually balanced without the Japanese text looking darker. But if you look more closely and highlight the text, you will notice that the default line height of the whole text is slightly different, due to the different fonts used. And the whole thing becomes even more challenging when kanji characters are mixed in with the text.

Kanji: Density and Design

Kanji are logographic characters—each one carries meaning, not just sound. Because they’re compact but information-dense, large blocks of kanji can look heavier.

<h2 lang="en">Apple unveils the new iPhone 17 Pro.</h2>
<h2 lang="ja">
  <span lang="en">Apple</span>が新型<span lang="en">iPhone 17 Pro</span>を発表。
</h2>

Apple unveils the new iPhone 17 Pro.

Appleが新型iPhone 17 Proを発表。

You can help readability with

generous line-height (1.7–1.9)
slightly looser letter spacing (letter-spacing: 0.05em)
a not too heavy font-weight
avoiding all-caps Latin text near kanji — caps feel bulky by comparison

:lang(ja) {
  font-family: "Noto Sans JP", sans-serif;
  font-weight: 500;
  letter-spacing: 0.05em;
}

:lang(en) {
  font-family: "Noto Sans", sans-serif;
  font-size: 1.06em; /* +5% larger than Japanese */
  letter-spacing: 0;
  vertical-align: -0.03em; /* align baseline slightly */
}

Appleが新型iPhone 17 Proを発表。

When styled this way, the English and Japanese text sit naturally on the same line — adjusting the English spans with a slightly larger font size and a small vertical-align nudge raises their baseline just enough to match the Japanese characters. The result feels balanced in both weight and rhythm — one cohesive headline, not two scripts stitched together.

Bonus Tip: Variable Fonts! Google’s Variable Fonts make it even easier to fine-tune weight and width dynamically between scripts. If you use font-variation-settings, you can ensure text looks balanced across both languages at every viewport size.

Takeaway

Multilingual design isn’t just about translation — it’s about typographic empathy. English and Japanese each have their own rhythm, density, and shape language. Using the lang attribute with the right fonts helps you respect both, creating an experience that feels natural to all readers.

Next time you use different scripts on your page, don’t just think about switching words. Think about switching style, and let your typography speak both languages fluently.

Resources

The many lives of the page title

2025-12-20T00:00:00Z

by Katrin Kampfrath

The page title — together with its co-star, the favicon — appears on stage in the browser tab. It shows up in search results. It’s announced by screen readers when a page loads. And it even becomes the default name when you bookmark a page.

It lives in the <title> tag within in the <head> of the document, supposedly unseen and often overlooked. Most tips and tricks around the page title focus on SEO benefits. But that’s not all: it also plays a vital role in the user flow of navigating the web.

The user experience of a page title

Clicking a link and having a new page load is the defining usage pattern of the world wide web. How do we know we clicked the right link? How do we know to which tab to return to when we switched to another program?

For screen reader users the page title is among the first things announced. On page load, sighted users will most likely first notice the H1 heading. When coming from another application or browser tab, the page title helps us identify the right window or browser tab. A page title identifies or describes a page and as such reassures us that we are indeed on the chosen page.

The page title in complex user flows

One overlooked aspect of the page title is its use in more complex user flows, for example a multi-step form split across several screens.

I specifically use the term "screen" here — multi-step user flows are often built with JavaScript as multiple screens on one route (effectively, under one URL). From a developer's perspective, it is just one page. From a user's perspective, however, these are multiple pages.

Let's consider a few multi-step user flows with potential page titles:

A multi-step form is a very common user flow, such as a checkout process or an application form. A typical page title for all screens is "Checkout - site name". A more contextual title would be "Payment details - Checkout - site name".
Search results that are placed across several pages. A typical page title for all screens is "Search results - site name". A more contextual title would be "17 search results for {search term} - site name".
An online learning platform where each chapter consists of the learning content and related exercises. A typical page title for all screens is "{Name of chapter} - site name". A more precise title would be "Page 1 - {Name of chapter} - site name", "Exercise 1 - {Name of chapter} - site name", etc.
Profile pages with several settings tabs for appearance, notifications, activity and so on. A typical page title for all screens is "Profile - site name". A more precise title for each screen would be "Appearance - Profile – site name", "Notifications – Profile – site name", and so on.

In all examples, users benefit from a unique page title per screen, describing the specific content of what is currently displayed on the page.

Example: A multi-step form

Let us dive deeper with the example of a multi-step form. Say we're buying a bike insurance. First, we enter our name and address. Then the bike details, such as purchase price, serial number, and whether it's an e-bike. Then payment details. The design is one screen per block of information, with no other main content.

The user navigates through the form. They enter their name and address, click “Next,” and move on to the bike details. Then they realise they don’t remember the exact purchase price. They open their email app to check — and while they're there, another email catches their eye. They click a link, open another tab, and get distracted.

Returning to the insurance form should be as seamless as possible. Users likely scan all browser tabs first to find the right one. Clear page titles make it easy to identify where they left off.

Consider these two possible titles:

"Buy bike insurance - Company Name"
"Bike details - Step 2 of 4 · Buy bike insurance - Company Name"

The first one identifies the form, but doesn’t reinforce the user's progress. The second one stells the user exactly where they are in the process.

Relevant WCAG requirements

So far, we’ve looked at this from a user-experience point of view. Next, we look at what is needed from an accessibility compliance perspective.

In the Web Content Accessibility Guidelines (WCAG) there are two success criteria related to our topic:

Success Criterion 2.4.2 Page Titled checks whether a page title describes the topic or purpose of the current page.
Success Criterion 2.4.4 Link Purpose (In Context) concerns the links on a page.

With regard to accessibility and legal requirements, the WCAG (also included in the European standard EN 301549) states minimum requirements. Think of text-to-background color contrast: the ratio of 4.5:1 is the minimum, but stronger contrast is always better.

Going back to our bike insurance example, this is how we would audit this process at our company.

For Success Criterion 2.4.2 Page Titled we check:

Does each step have a unique URL? Then the page title needs to mention the specific topic of the current page in the page title, such as "Bike details" or "Bike details step 2 of 4".
If there are no unique URLs (i.e. the form always starts at step 1), the overall form process must be sufficiently reflected in the page title. "Buy bike insurance - company name" would pass the success criterion. In an audit, we would then add a recommendation to include the current step for user-experience reasons.

For Success Criterion 2.4.4 Link Purpose (In Context), things are a little less clear. The main intent of the success criterion is that "users understand what each link will do." The criterion focuses on the "read a link" part, so an accessibility audit will check the link texts on a given page to see if all links on one page are distinguishable from each other. This aspect is the minimum requirement.

Nonetheless, the user flow still plays a role. Recall the typical flow: read a link, click a link, have a new page load. In the WCAG understanding document for this criterion, it says:

Having the link and the title agree, or be very similar, is good practice and provides continuity between the link 'clicked on' and the web page that the user lands on.

Adding context about the current step in a flow or the current page in a set of pages helps all users stay oriented.

Conclusion

Give your page sufficiently unique page titles. What is sufficient depends on the implementation and design details of your website.

Keep the user flow in mind. The page title is a key element to reassure users they are indeed on the page they intended to be.

Developer experience is not the same as user experience. As developers we know how things work on a technical level, and we might easily forget how users perceive a website. Never assume people will visit your site only in one straightforward session with no distractions. Clear, contextual titles help people stay oriented when they return.

Resources

Web Content Accessibility Guidelines (WCAG) 2.2
MDN – Document.title property
Manuel Matuzović – Web Accessibility Cookbook, chapter "1.2 Describe the Document".
Heydon Pickering – Inclusive Design Patterns, chapter "The <title> Element".
Hidde de Vries – "Accessible page titles in a Single Page App"
Deque University – Page Title Checklist

Semantics beyond the tag name

2025-12-19T00:00:00Z

by Nathan Knowler

There is a terrible epidemic that plagues the web: divitis.

If you’re unfamiliar, divitis is a condition where a website uses an unholy amount of <div> elements. Some of the worst cases even include <div>s used as buttons—blasphemy!

<div class="site-header">
  <div class="site-title">divs r us</div>
  <div class="navigation">
    <div class="link">my favourite divs</div>
    <div class="link">moor divs</div>
  </div>
</div>
<div class="main">
  <div class="content">
    <div class="container">
      <div class="container-inner">
        <div class="card">
          <div class="card-inner">
            <div class="card-header">
              <div>i love div</div>
            </div>
            <div>all my friends are divs</div>
            <div class="card-footer">
              <div class="button">accept div as your lord and saviour</div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</div>
<div class="site-footer">
  <div class="div-webring">
    <div class="button">join the divitis webring</div>
    <div class="button next">next</div>
    <div class="button prev">previous</div>
  </div>
</div>

To avoid divitis, authors are often encouraged to use semantic HTML. As it turns out, HTML has over a hundred elements that are not named div or span. Semantic HTML elements describe what their content is.

Inspired by this newfound responsibility, authors open the lexicon of HTML elements and begin to compose… absolute gibberish.

<my-card>
  <header>
    <section>
      <h1>divs suck</h1>
      <h2>and so do classes</h2>
    </section>
  </header>
  <main>
    <section>who needs classes when you have semantic HTML. combine elements however you’d like to explore new possibilities.</section>
  </main>
  <footer>
    <section>
      <nav>
        <a href="/hell">
          <button>
            <label>I have no class</label>
          </button>
        </a>
      </nav>
    </section>
  </footer>
</my-card>

<my-card>
  <header>
    <section>
      <h1>replace all your divs with sections</h1>
      <h2>they’re so semantic</h2>
    </section>
  </header>
  <main>
    <section>whenever I don’t know what element to choose, section is there for me. section is my best friend forever.</section>
  </main>
  <footer>
    <section>
      <nav>
        <a href="/hell">
          <button>
            <label>become semantic with sections</label>
          </button>
        </a>
      </nav>
    </section>
  </footer>
</my-card>

Now, this might not seem like gibberish on the surface—it might actually seem like it makes a lot of sense. The problems will become more apparent throughout this post. We cannot simply use HTML elements based on their tag names and expect them to translate to anything actually meaningful.

To be fair, this is to be expected of anyone learning a new language. However, a problem on the web is that authors delude themselves into thinking that they are “writing semantic HTML,” therefore gaining all of the benefits that are understood to come with that like accessibility, and they never advance past that stage.

It’s like when my own child confidently declares, after learning a handful of words in Japanese, “I know Japanese.” It’s cute and I’m not going to argue with it, because they’re a child.

You’re likely not a child though, so I will tell it to you straight: this is not cute.

Once you’ve recovered from that devastating realization, we can proceed.

To actually write semantic HTML, we need to know what elements mean beyond just what we infer from their tag names and how to use them. So, how do we find that out?

Where HTML semantics come from

The HTML standard is what defines HTML elements. For example, we can find the definition of the <main> element in section 4.4.14:

The main element represents the dominant contents of the document.

Beyond the definition, the standard also includes rules and guidance for usage:

A document must not have more than one main element that does not have the hidden attribute specified.

A hierarchically correct main element is one whose ancestor elements are limited to html, body, div, form without an accessible name, and autonomous custom elements. Each main element must be a hierarchically correct main element.

From these descriptions, we can gather that using the <main> element for the main content of a card component, which can be used multiple times like the ones in the earlier “gibberish” example, would be incorrect:

<my-card>
  <header><!-- … --></header>
  <main><!-- first card main content --></main>
  <footer><!-- … --></footer>
</my-card>
<my-card>
  <header><!-- … --></header>
  <main><!-- second card main content --></main>
  <footer><!-- … --></footer>
</my-card>

Tag names are not enough for us to understand what an element is for. We need to adopt HTML’s own definitions for semantic elements.

Why follow the HTML Standard?

I’m not your god, and neither is the HTML Standard—but if you choose to use HTML elements for how you perceive them, things break in ways you can’t control. Assistive tech, legal requirements, user expectations... it all hinges on the platform’s actual definitions. Ignore them and, well, your documents might just end up in hell.

But what about ARIA? Can’t I just use that instead?

Accessible Rich Internet Applications, more commonly known by the acronym ARIA, is a set of roles and attributes that can be used in HTML to add accessibility related semantics to web content.

It can be tempting to think that we don’t need semantic HTML, instead we can just sprinkle our divitis with holy ARIA roles and attributes. Well, while this can improve the accessibility of that hoard of elements, we’re likely breaking the first rule of ARIA usage: don’t use ARIA if you don’t need to.

<div role=button>accept div as your lord and saviour</div>

Many semantic HTML elements have what’s called implicit ARIA semantics. These are ARIA roles and properties that the browser has mapped for us. Instead of needing to explicitly write out the ARIA semantics for an element each time you use it, we can use semantic HTML elements as a shorthand for these.

<button>This machine kills fascists</button>

Beyond simply being a shorthand for a set of ARIA semantics, built-in HTML elements also include the necessary functionality and presentation that would be expected of an element bearing such semantics. In many cases, this means that you don’t need to write any JavaScript for your HTML to work as expected. Using JavaScript in lieu of built-in HTML functionality is wasteful and error prone, degrading the usability of your website.

Now that we understand the folly of ignoring the first rule of ARIA usage, let’s turn our attention to implicit ARIA semantics and how they work in semantic HTML.

The implicit ARIA semantics of HTML

Along with the definitions for each element, the HTML standard includes accessibility considerations for both authors (i.e. you and I) and implementors (i.e. the people implementing the elements in browsers). The linked document for authors is called “ARIA in HTML” and the one for implementors is called “HTML Accessibility API Mappings” (HTML-AAM). The each of these links will jump to the relevant bits for the element in question.

Both of these include what the implicit ARIA semantics are for HTML elements and attributes. “ARIA in HTML” is more geared towards authors: it includes both rules and recommendations for ARIA attribute usage with HTML. HTML-AAM includes specifics of how elements should be mapped to various accessibility APIs including, but not limited to, ARIA.

Turning again to the <main> element, we can see that it has an implicit ARIA role of main.

If we look at heading elements like <h1> or <h2>, we see that they have an implicit ARIA role of heading along with an implicit aria-level of whatever number is a part of the tag name (i.e. HTML only includes six heading levels).

Beyond element tag names, there are three details I want to point out in these documents:

Both an element’s attributes and its context can effect its implicit ARIA semantics.
Some elements do not have implied semantics unless they are named.
Not all elements have significant implicit ARIA semantics. That’s not to say they never will, but this gives us a good idea of where we can prioritize our time.

Let’s dig into some examples.

Attributes affect implicit semantics

Consider the following elements:

<a>Anchor</a>
<a href=https://example.com>Anchor with an <code>href</code> attribute</a>

Are these both links?

No, they aren’t. The first is just an anchor element. It’s implicit ARIA role is generic which is not interesting for accessibility APIs. CSS also doesn’t even consider it a link as it will not match the :any-link or :link pseudo-class selectors.

Since the latter anchor element has an href attribute, it is considered a link, and therefore has the implicit ARIA role of link and can be matched by the above mentioned semantic pseudo-class selectors with CSS.

Naming affects implicit semantics

A popular favourite among those first starting out with semantic HTML is the <section> element. What is often never realized is that it has no valuable ARIA semantics if it is not named (i.e. its implicit role is generic). This makes it not much different than using a <div> (i.e. its implicit role is also generic).

<section>
  <h2>Insignificant section</h2>
</section>
<section aria-labelledby=section-label>
  <h2 id=section-label>Significant document region</h2>
</section>

With that said, please do not go name all of your <section> elements!

<section aria-labelledby=section-1-label>
  <h1 id=section-1-label>Top one hundred reason I love sections</h1>
  <p>…</p>
</section>
<section aria-labelledby=section-2-label>
  <h2 id=section-2-label>Section is whatever I want it to be</h2>
  <p>…</p>
</section>
<section aria-labelledby=section-3-label>
  <h2 id=section-3-label>Section is my friend</h2>
  <p>…</p>
</section>

A labelled <section> element will have the region ARIA role. This is what’s called a landmark. Landmarks are important sections of a document that a user might benefit from easy access to.

The problem here is that everything is a landmark, then nothing is a landmark.

It can be easy to think that labelling your <section> elements satisfies the requirement for using them, but that is not the case here. Both the meaning of the tag name and the HTML definition of a <section> element is way more generic than the region ARIA role. Before you label your <section> elements ensure they make sense as regions, otherwise, you’ll likely be making it more difficult to find what’s important on a page. If you’re already using a good heading structure throughout your document, that is good enough for what you’re likely trying to do.

Context affects implicit semantics

HTML elements can have different implicit ARIA semantics when used in different contexts.

For example, the <header> and <footer> elements have an important meaning for documents when used outside of the <main> element or any other sectioning content element.

<body>
  <header>Header content</header>
  <main>Main content of the document</main>
  <footer>Footer content</footer>
</body>

In this scenario, the <header> element’s implicit ARIA role is banner and the <footer> element’s implicit ARIA role is contentinfo. Documents should only have one of each of these landmarks.

That does not mean that you cannot use either of these elements in other places within your document. When we review the definition of a <header> element it says:

“The header element represents a group of introductory or navigational aids.”

That implies much broader usage than the definition of the banner role:

“A landmark that contains mostly site-oriented content, rather than page-specific content.”

Until 2025, when used inside of the <main> element or sectioning content, <header> and <footer> elements were mapped with a generic role which means they didn’t have any value for accessibility purposes. After relatively recent changes to the latest ARIA spec and HTML-AAM drafts, in these contexts they have been mapped to new ARIA roles: sectionheader and sectionfooter.

<body>
  <header>banner landmark role</header>
  <main>
    <article>
      <header>sectionheader role</header>
      <p>Article content</p>
      <footer>sectionfooter role</footer>
    </article>
  </main>
  <footer>contentinfo landmark role</footer>
</body>

As of writing, these changes have been implemented in Chromium-based browsers and Safari. Firefox has yet to implement them. With that said, as these roles are new, the support from assistive technologies will likely be non-existent or quite limited.

The <header> and <footer> elements are examples of context being an important factor for implicit ARIA semantics. At first, only specific usage was used for setting the landmark roles. Now, later on, the broader usage allowed of these elements in other contexts can be exposed semantically.

A combinations of these factors affect implicit semantics

Sometimes an element’s implicit semantics are informed by a combination of the factors that we’ve explored so far. Consider the <aside> element.

In the following situations, the <aside> element’s implicit role is complementary (a landmark) because it’s scoped to the <body> element or the <main> element:

<body>
  <main>
    <p>Main content.
  </main>
  <aside>
    <p>Complementary to the main content, but standalone.
  </aside>
</body>

<body>
  <main>
    <p>Main content
    <aside>
      <p>Complementary to the main content, but standalone.
    </aside>
  </main>
</body>

If you mark up your blog posts with an <article> element which is sectioning content, then unnamed <aside> elements have the generic role.

<article>
  <h1>Some article</h1>
  <p>Some content, blah, blah, blah…
  <aside>
    <p>Failed attempted at complementary.
  </aside>
</article>

The only way to make this element have the complementary role is to use aria-labelledby or aria-label. That could be a challenge if the content has no heading. You may need to be creative about wrapping part of the content to use as a label or introduce a visually hidden label if you want to avoid some of the translation pitfalls of aria-label.

<article>
  <h1>Some article</h1>
  <p>Some content, blah, blah, blah…
  <aside aria-labelledby=complementary-label>
    <p><span id=complementary-label>Failed attempt</span> at complementary.
  </aside>
</article>

All of this is not something someone could have inferred from the HTML standard alone. This is why documents like “ARIA in HTML” and HTML-AAM are invaluable for good semantic usage.

Custom elements can have implicit semantics too

Custom elements are an HTML feature that allow authors to define their own HTML elements. A tag name can be defined as a custom element using the window.customElements.define() method in JavaScript. Like built-in HTML elements, custom elements can have their own implicit ARIA semantics. This is set using the ElementsInternals API.

Here is an example of defining a custom element and setting an implicit ARIA role for it:

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

      const internals = this.attachInternals();

      internals.role = "button";

      // Continue implementing button functionality 🙈
    }
  }

  customElements.define("not-a-div", HellButtonElement);
</script>

<not-a-div>A div is not a button</not-a-div>

When you create custom elements, you become responsible for communicating their purpose to other authors. This should also include any implicit semantics you’ve set, as well as, what you consider good authoring practice to be when using them.

I highly recommend using HTML itself as a model for how you build custom elements. In many ways, that might mean thinking less like an author and more like an implementor or a specification writer. “How do I create elements for others to use?” Implicit semantics are an important part of that because they allow you to put other authors first.

Test, test, test

In the same way that you can spend a whole lot of time writing valid, semantic HTML that has no implicit ARIA semantics, you can also spend a whole lot of time on writing HTML according to the specifications that actually isn’t implemented in any browser or that is implemented incorrectly in browsers. This is why testing is vital.

Testing might look like checking what ARIA roles and properties are computed for elements in a browser’s developer tools (use the accessibility tree in Chrome/Edge and Firefox or Accessibility section of the Node Panel in Safari’s Web Inspector). It also might look like actually using assistive technologies such as screen readers or voice control. It is very helpful to understand how assistive technology users experience various elements and so seeking real feedback is invaluable to the testing process. Just make sure to show anyone you do involve that you value their time and labour.

Testing helps us understand what is valuable and what we should focus on. I can spend a whole lot of time trying to perfectly mark up all of my words using text-level semantics, but then realize through testing that I’ve delivered little to no semantic value to assistive technology users.

Courses such as Sara Soueidan’s Practical Accessibility or Marcy Sutton’s Testing Accessibility are great resources for those wanting to get started with testing various assistive technologies.

Go forth and actually write semantic HTML

We’ve learned that:

HTML tag names are not a reliable way of understanding what an element is for.
The HTML standard defines what semantic HTML elements are for.
Some semantic HTML elements also have implicit ARIA semantics, and in some cases that depends on what attributes are set, if the element has an accessible name, the context the element is used in, and even a combination of these things.
Custom elements can have implicit ARIA semantics too.
Don’t take anyone’s word for it: test it yourself.

Resources

The HTML Standard
Accessible Rich Internet Applications (WAI-ARIA)
ARIA in HTML
HTML Accessibility API Mappings (HTML-AAM)
Screen Reader HTML Support – Lookup
Tetralogical’s “Browsing with a desktop screen reader”
- The first in a series about browsing with various kinds of assistive technologies (linked within).
How People with Disabilities Use the Web

Forms are a badly designed part of HTML

2025-12-18T00:00:00Z

by Jens Grochtdreis

Forms were likely one of the reasons why browser vendors joined forces in the WHATWG in 2004. They felt that HTML standardization was heading into the wrong direction and wanted more practical relevance. While this may be an oversimplification, if true, it highlights the failure of the WHATWG (i.e., the browser vendors) and, subsequently, the W3C. Although the newly standardized form elements and features all point into the right direction, they are incomplete and unfinished. The fact that this is still the case, even more than ten years after HTML5 became a recommendation, is alarming. I will concentrate in this article on forms and especially on missing elements, inconsistent behaviour and the problems with styling.

New Form Elements

The WHATWG introduced several new form elements and attributes into the HTML specification, e.g. the email input, telephone input, date field, and range slider. Most of these are simply new types of the input element. This approach was clever — a great example of progressive enhancement. If a browser hasn’t implemented a particular input type yet, a plain text field serves as a fallback. Developers can then use JavaScript if needed. However, when the new elements are supported, JavaScript becomes unnecessary.

This progressive-enhancement model works well for simple inputs. So these new elements are intentionally very simple – essentially shortcuts for single-value fields. They combine regular expressions for validation, an ARIA role, and sometimes trigger a specialized virtual keyboard on mobile phones and tablets. They are similar to web components based on the input element, but are integrated directly into the browser, so no JavaScript is needed for the element to appear. And because they are standardized, the code is consistent across implementations.

Combinations of different form elements have unfortunately not been considered at all. As examples, I would like to mention the combobox and the range slider.

The Combobox

The combobox is a combination of a select and a search field. Fluent UI provides a combobox component, as does Ant Design. In both cases, only the search field is a form field. The select is simulated by a list in Fluent, while Ant Design uses a div. The selected options are displayed as (fake) buttons using span and svg elements. This has little to do with actual forms.

The combobox (called select-panel) from the Github-design system.

The combobox from the design-system of ant-design.

The Enhanced Range Element

The range element can unfortunately only represent a single value. The frequently needed range slider for two or more values (e.g. for shopping portals) does not exist. You'll have to build it yourself. The well-known noUiSlider simulates the slider for one or more values consistently with a div. At least ARIA attributes are used throughout. The same goes with the version by Quasar. No form elements were harmed. It’s a pity that this obvious use case was not standardized.

Built-in Validation

Standardizing validation in the browser was a smart idea. There are built-in regex rules for validation, which can be manually overridden. Validation is controlled via attributes and a standardized JavaScript API, which is great. In practice, however, you quickly run into details that aren’t flexibly solved. This leads to custom solutions using JavaScript.

There is no simple, built-in way to collect all error messages and display them at the top or bottom of the form without JavaScript. Nor is there a way to communicate the total number of errors to the user. Error messages at the element itself are shown via a popup, which cannot be styled or repositioned. For any improvements in usability and clearer communication, you'll need JavaScript. While this is done through a unified API, it still isn’t possible with plain HTML.

HTML needs better built-in options for handling errors. We should be able to control this with attributes, not JavaScript. The less JavaScript is needed, the faster the page will be.

Inconsistent browser support

Form elements don't have standardized, consistent capabilities or appearance. I don't know whether browser vendors weren't willing to align on this or simply didn't see the need. Either way, consistent usability, features, and appearance would help both users and developers. For example, browsers hook into the operating system's built-in color picker, which seems sensible – but these pickers can’t be styled and differ in functionality. Android and iOS replace the HTML date picker with their own native widget, which is great on mobile. But on desktop, each browser presents a completely different UI, and none of it is customizable.

The number input offers increment/decrement arrows in one browser but not in another. The usefulness of these arrows is debatable. The date field is only read aloud by the native screen reader on iOS) when a date is already present; it is not announced as a date field. The email input is announced as an email field only by Voice Over on MacOS. Other screen readers don't announce the semantics. If browser vendors are leading the standardization of these features, I expect better coordination and consistent implementation.

Semantic information needs to be exposed to screen readers. Without that, the new input type feels only half-baked – basically just a text input with built-in validation and a tailored onscreen keyboard. And both of those could have been achieved without introducing a dedicated email input.

Inconsistent behaviour and appearance may or may not irritate users. It mostly irritates developers, designers and their clients. Inconsistency is a nightmare if you want to provide a seamless and identical look and feel of your page/application through the differnet devices and browsers. It might as well irritate users if the form looks very different on a smartphone and a notebook.

Partially Miserable Styling Options

Styling form elements is a major challenge that often ends in failure. Developers frequently hide the native control and style the label instead – or hide the control entirely and replace it with a JavaScript-driven construction of divs or lists that can be freely styled.

Fundamentally, styling form elements is miserable. This is why 58% of participants in the "State of HTML 2024" survey identified styling as by far the biggest pain point with forms.

Browser vendors are currently more active in CSS than in HTML, so there’s a faint glimmer of hope on the horizon. Chromium has introduced the customizable select, based on an Open UI proposal, and Brecht deRuyte has dedicated a series of articles on the new, fantastic possibilities.

It’s a start, but the broader problem remains: all controls hidden inside the browser’s shadow DOM need consistent, standardized structure so they can be styled reliably. At CSSDay 2025, Tim Nguyen presented the Working Draft “CSS Form Control Styling Level 1” – early work, but promising. I hope it matures quickly and finds its way into browsers.

Without meaningful progress here, we’ll be stuck with JavaScript-based date pickers and other custom controls for the foreseeable future. What’s the point of having a native element if we have to replace it at the first opportunity because we can’t style it?

Interop 2025 didn’t include any focus on form controls. Hopefully some proposals make it into Interop 2026 once the selection process concludes (hopefully by the time this article is published).

Lack of Further Development

We are still missing important form elements, and developers have to simulate them with JavaScript. Standardizers could have addressed these gaps in recent years. They didn't. Could it be that they think that we already have all the "building blocks" needed – that developers can simply assemble new controls using JavaScript and Web Components?

Taken to its logical extreme, this argument would reduce HTML to a handful of primitive elements. Everything else would be rebuilt as custom components, each with its own attributes, ARIA wiring, and implementation quirks. That can’t seriously be the goal.

In my view, HTML elements are, in a sense, browser-specific web components, but with some crucial advantages: they do not require JavaScript, and they behave the same for all end users and devices. Non-standard controls, on the other hand, come in dozens of variations, built on different foundations, and with varying quality. Standardization exists precisely so we don’t all have to reinvent them.

Hope Is Rising

The lack of standardization leads to many different approaches to the same problem. What they have in common is that they have little or nothing to do with actual form elements.

Fortunately, practitioners have come together in the "Open UI" community group to advance the standardization of HTML and CSS. They describe several features that are missing as standards in HTML. For the combobox, Open UI has created a proposal. I hope it will be implemented in browsers and standardized soon.

The same applies to the range slider with more than one value. Open UI also offers a great idea for a long-overdue extension of the standard.

A New Wave of Innovation Is Needed

This article is a very rough overview of the state of forms. My main demands for innovation are:

We need more complex form fields as standard elements, such as a combobox.
We need a range input with multiple handles.
We need much better styling opportunities for every form element. The new stylable select shows the right direction.
Form validation should be controlled by HTML-attributes instead of JavaScript. It's styling should be easy and consistent between browsers.
Screenreaders should communicate form semantic without flaws.

The innovation of forms should be part of a much larger initiative. WHATWG and W3C demonstrated at the beginning of the millennium that this is possible. After two decades, it is time to revive this spirit and take HTML to a new level. We’ve seen hints of this recently – elements like <dialog>, the popover API, and renewed work on customizable form controls show that the platform can still evolve in meaningful ways. But these feel like isolated wins rather than part of a broader push.

Modern websites no longer fit the document-centric model HTML was created for. A typical news homepage mixes headlines, images, teasers, and interactive elements in ways the original spec never anticipated. The New York Times even present teasers without headlines at all. This diversity shows how little shared foundation there is for developers today – and why HTML needs a broader, more coordinated evolution beyond isolated improvements.

Modern Websites and especially Webapps need a new paradigm. They evolved far beyond the inventor's idea and it won't stop evolving. The W3C should respond with new elements and paradigms. The document analogy should stand alongside interactive applications as equals. The more that is standardized in this regard, the better it is for the industry. And end users will also benefit from consistently high-quality websites.

Don't leave the screen reader hungry

2025-12-17T00:00:00Z

by Geri Reid

Screen readers don’t always announce what’s visually on screen. This article explores that gap - through the medium of burritos.

The burrito you can't order

A customer complained they couldn't order a burrito. "The menu advertises burritos, but my screen reader won't let me order one!"

I was baffled. The menu was about as Mexican as a Yorkshire pudding. There was no mention of a burrito.

After a lot of searching, I discovered someone had dropped an emoji into the heading:

<h2>Sandwiches 🌯</h2>

Visually, it looked decorative and kind of like a sandwich. But screen readers don't read an emoji as decoration, they announce its Unicode character name. So screen reader users heard: "Sandwiches, Burrito."

That little emoji isn't just sitting in your markup looking pretty. It's making promises your website can't keep. One tiny flourish in your heading tag and suddenly your sandwich bar sounds like a taqueria.

What I'm highlighting here is screen readers don't consistently announce what you see visually on the screen. This article explores the gap between what HTML gives you for free and what you need to supply yourself.

I've made some quick reference tables to demonstrate how popular screen readers JAWS, NVDA, and VoiceOver handle elements, showing where HTML does the work and where you need to add stuff in addition.

Documenting and recording screen reader requirements is also problematic, so it sometimes falls through the gaps between design and code. I’ve got some ideas to help solve this.

You hungry?

Since you're probably craving Mexican food by now, we're going to frame this through the medium of burritos. Put your apron on, taquero - it's time to get cooking!

Let’s imagine the browser is your tortilla: it holds everything together. HTML adds some fillings by default. For a successful burrito, you need the right toppings. The trick is knowing which toppings to add and when to stop.

What you get for free (the fillings)

Like a burrito that comes with rice, beans and your choice of protein, semantic HTML automatically packs the essentials into your tortilla. Correctly marked-up headings, links, buttons, lists, form controls, and tables are announced by default. And like a burrito starts with a good tortilla, screen readers work best when paired with their preferred browser:

JAWS with Chrome on Windows
NVDA with Firefox or Chrome on Windows
VoiceOver with Safari on Apple

Here's how JAWS, NVDA and VoiceOver screen readers announce for me using their default settings (I've included my testing specs in the footer). Use this as a guide. Your announcements might differ slightly based on verbosity and device settings, browser and software version. The way you navigate also changes what you hear. For example, using a heading shortcut key may produce a different announcement than letting the screen reader read through linearly.

The exact announcement doesn't really matter.

What matters is knowing what you get for free and when you have to add something to get meaningful announcements.

Element	JAWS says	NVDA says	Mac OS VoiceOver says	Annotation
`<h1>Burritos</h1>`	“Burritos, Heading level 1”	“Burritos, Heading level 1”	“Heading level 1, Burritos”	No extras needed. Use correct heading levels for structure.
`<button>Checkout</button>`	“Checkout button”	“Checkout, button”	“Checkout, button”	No extras needed.
`<a href="burrito.html">Order burrito</a>`	“Order burrito, link”	“Order burrito, link”	“link, Order burrito”	No extras needed. Just make sure the link text makes sense out of context.
`<ul> <li>Burrito</li> <li>Taco</li> </ul>`	“List of 2 items. Bullet Burrito. Bullet Taco. List end”	“List with 2 items. Bullet Burrito. Bullet Taco. Out of list”	“List 2 items. Bullet Burrito, 1 of 2. Bullet Taco, 2 of 2. End of list.”	No extra needed.
`<label for=name">Name</label> <input id="name" type="text">`	“Name, edit”	“Name, edit”	“Name, edit text”	No extra needed.
`<input id="cheese" type="checkbox"> <label for="cheese">Extra cheese</label>`	“Extra cheese, check box, not checked”	“Check box, not checked, Extra cheese”	“Extra cheese, unticked, tick box”	No extra needed.
`<button disabled>Not taking orders</button>`	“Order, button, unavailable”	“Button unavailable, Order”	“Order, dimmed, button”	No extra needed. Visually appears disabled, not focusable.

What you must supply (the toppings)

Here’s where you roll up your sleeves. These elements stay silent or may not announce as you’d expect until you add the right toppings.

Element	JAWS says	NVDA says	Mac OS VoiceOver says	Annotation
`<img src="burrito.png">`	"Unlabelled graphic"	"Unlabelled graphic"	“Unlabelled image” or "burrito.png"	Add alt text describing the image. Or use `alt=""` if decorative.
`<button><svg>burrito svg icon</svg></button>`	“unlabelled button”	“button”	“button”	Add accessible name via `aria-label` or `aria-labelledby`.
`<iframe src="#"></iframe>`	“frame”, or “frame 2 of 4” if multiple	“frame”, or “frame 2 of 4” if multiple	“frame”	Add a descriptive `title` for context.

The trick: add the toppings that matter, but don't overload the burrito. An overstuffed burrito can fall into your lap, potentially ruining a first date.

Edge cases and oddities (HTMHell's Kitchen)

These ingredients look tasty but behave unpredictably under heat. Use with caution or your markup might fall apart.

Element	JAWS says	NVDA says	Mac OS VoiceOver says	Annotation
`<strong>Burrito!</strong>`	"Burrito"	"Burrito"	"Burrito"	Emphasis not reliably spoken on default verbosity settings. Don't rely on for meaning.
`<em>Spicy</em>`	"Spicy"	"Spicy"	"Spicy"	Emphasis not reliably spoken on default verbosity settings. Don't rely on for meaning.
`£8 <s>£10</s>`	"£8 strikethough deletion £10"	"£8 deleted £10"	"£8 £10" or "£8 deletion £10"	Strikeout not reliably announced.
`<sup>2</sup> / <sub>2</sub>`	"2, 2"	"2, 2"	"2, 2"	Not read as superscript or subscript.
`<hr>`	"separator"	"separator"	Silent	Don't rely on for meaning. Add `aria-label` if the separation needs context.
`<abbr title="Street Provisions In Corn-based Envelopes">SPICE</abbr>`	"SPICE, Street Provisions In Corn-based Envelopes"	"Spice"	"Spice"	Full title not reliably announced. Spell out abbreviation in text.
🌯	"Burrito"	"Burrito"	"Burrito"	Emojis announce their Unicode name. For decorative use, add `aria-hidden`.

Help! My burrito is busted!

If you're second-guessing what should announce, TetraLogical recently released a detailed guide to screen reader announcements along with an HTML Element test file you can run your screen reader over to test elements in isolation.
If you’re looking for video examples of how elements and components announce, check out the HTML section of atomica11y.
If you work on a Mac and need to test on Windows screen readers, try AssistivLabs or set up an emulator like UTM. You can run NVDA for free and JAWS has a free 40 minute developer mode which is sufficient for testing. 40% of the screen reader market uses JAWS so if you only test on VoiceOver you might miss issues.

If you're building a website, you need a consistent way to document screen reader announcements. Don't leave it up to chance. Current design tools don't have space for accessibility information and much of it is non-visual, so it easily gets overlooked during implementation.

Documenting with design annotation kits

Visual annotation kits for Figma, Sketch or Penpot offer a solution. There are plenty of excellent open-source examples shared in community files that you can tailor to your organisation's needs. If you're looking for inspiration, Jan Maarten and Daniel Henderson-Ede did a talk showcasing how different design teams annotate for accessibility at this year's Inclusive Design 24.

As a designer, I find it helpful to pair with an engineer and mark up design files together to capture all the accessibility requirements.

A problem with sticky note annotations is that they often die in design files once development begins. Developers don't revisit design files, designers move on and the accessibility details you've spent time documenting get lost. Even if they are used effectively in implementation, you end up rewriting a similar set of notes for subsequent projects.

Documenting with text

Text-based documentation in machine-readable formats (YAML, JSON, markdown tables, or structured specifications) solves this. Instead of static notes trapped in design files, if you record your annotations as text you can create queryable records that travel. Think of it like your restaurant having a digital ordering system instead of handwritten tickets. The kitchen gets the exact burrito order every time, with all the special instructions intact.

These formats also unlock AI integration through tools like RAG or MCP servers. When a developer asks an AI assistant about a component, it can surface the exact accessibility requirements. You could even structure these specs to generate automated test criteria.

The long game: shift to living documentation that can be queried on demand. Some clever folks like Nathan Curtis have already started to explore ways to record specs with data.

Let's wrap up! 🌯

HTML gives you a tortilla full of free fillings: headings, lists, buttons, form controls, tables. However, some elements require you to add a topping to make them meaningful.
Document which toppings are needed so they don't get lost between design and development. Without clear documentation, developers have to guess at the requirements or skip them entirely, leaving accessibility as an afterthought rather than an integral part of the build.

Remember that a good burrito, like good markup, is about knowing which toppings to add and when to stop. Get it right and your screen reader users get a memorable burrito. Get it wrong and they're left with a stain on their shirt.

About Geri Reid

Geri is an accessibility and design systems nerd from London. As design and accessibility lead on design systems at News UK and Lloyds Banking Group, she helped some of the UK’s largest media and banking brands to design at scale. She is currently Lead Accessibility Specialist at Just Eat Takeaway.

Blog: gerireid.com
Bluesky: @gerireid.com
LinkedIn: @gerireid

Screen reader testing on:

JAWS (2025) with Chrome Version 140.0.7339.128 (Official Build) (64-bit) on Windows 11
NVDA (2025) with Chrome Version 140.0.7339.128 (Official Build) (64-bit) on Windows 11
VoiceOver (2025) with Safari Version 26.0.1 on Mac, Sequoia 15.7.1

Giving pages a clear shape by using headings

2025-12-16T00:00:00Z

by Steve Barnett

We can make our pages easier to understand by using headings to give our pages a clear shape. Our users might visually scan the page, use an extension or bookmarklet to list the headings, navigate using assistive technology like a screen reader, or ask AI for a summary of the page. High quality headings can make things better for everyone.

In my day job as a Digital Accessibility Consultant, there are a couple of ways that I've seen things go a bit... wonky. Let's go through the three most common issues, and how to fix them.

Text should not be a heading

Ah, this one's a real classic! When we have some big and bold text, for Design Reasons, we sometimes take a bit of a shortcut and mark it up as a heading. Let's say an <h2>, because it seems about the right size, or that’s what it says in the design file. But here's the thing: this text doesn't introduce or describe the content that follows. It just "needs" to be big for the look of it.

This is an issue because when things are marked up as headings that are not headings, it makes the page harder to understand. Users of assistive technology like screen readers hear things read as headings of section that are not headings.

An example

Let's say we have a page explaining colours, RGB-style. We might have headings marked up as follows.

<h1>Colours
- <h2>Red
- <h2>Green
  - <h3>Make it pop!
- <h2>Blue

In this case "Make it pop!" is just some big text, designed to be eye-catching. It's not the start of a section of content.

How to fix it

Stop using HTML and start using CSS. Instead of using a heading element, using a <p> or <span> or <div> element and use CSS to make it big and bold.

Text should be a heading

Now let's come from the other side. We look at a design and see some bold text. Some big, some bigger, some biggest. Sweet! We fling down a bunch of <div> elements, add some styles and we're done. It looks just like the design, chef's kiss, and so on. But here's the thing: this text looks like a heading, but doesn't have any semantics.

This is an issue because when text is marked up as a heading even though it isn’t one, it makes the page harder to understand. People using bookmarklets or browser extensions to list headings won't see this text in the list of headings.

An example

Let's say we have a page explaining what the web is made of. We might have some big bold text marked up as follows.

<h1>The world wide web
- <h2>HTML
- <p>CSS
- <h2>JavaScript

In this case "CSS" isn't just a paragraph. It's the start of a section of content.

How to fix it

Stop using CSS and start using HTML. Instead of using a <p> or <span> or <div> element, use a heading element at the right level to give it semantic structure: from <h1> to <h6>. If we have some big and bold text that introduces or describes the content that follows, it should probably be a heading.

Headings do not reflect the content structure

Okay, we've sorted out text that should and shouldn't be a heading: only things that are structural headings are marked as headings. Hooray! There's one more snag that we might hit: when the headings are in a weird order. For example: let's say we have a page listing edible things. We mark up <h3>Fruit</h3> as a section, and then <h2>Apples</h2> as a sub-section of Fruit. Maybe we've done this because that's what the styles in the design file suggest. But here's the thing: it's wonky because the headings don't represent the hierarchical relationships.

This is an issue because users of assistive technology like screen readers use headings to understand how each section of the page relates to each other and the page as a whole. When the headings are wonky, the shape of the page is harder to understand.

How to fix it

Use HTML to give the headings the correct nesting and ordering. Use CSS to make them look appropriately sized and shiny.

I like to start from the page as a whole and work my way down.

What’s the topic or purpose of this page? That text should be in an <h1> element near the top of the page.
What are the sections of the page? The name of each section should be in an <h2> element, at the start of the section.
What (if any) are the subsections of each section? The name of each subsection should be in an <h3> element, at the start of the subsection.
What (if any) are the sub-subsections of each subsection? The name of each sub-subsection should be in an <h4> element, at the start of the sub-subsection.

And we keep going, down to an <h6> element. Although if you've reached an <h6> element, it might be worth reviewing the content and seeing if there's Too Much Stuff there!

The list of headings should read a bit like a table of contents for the page.

Other weird heading things

There are other aspects of wonkiness that may occur. Keep a watch for these too!

Heading text that doesn't describe the content that follows. The words of the heading must introduce the section. Ask your friendly Content writer for help!
<h1> shenanigans: no <h1> element, or multiple <h1> elements. Just one <h1> element, please! It should describe the topic or purpose of page.
Skipped heading levels, for example: jumping from an <h2> element to an <h4> element, without an <h3> between them. Keep the nesting and order correct: <h3> elements for subsections of a section with an <h2> heading.

Accessibility nerd corner

The big three issues we started with all fall under Web Content Accessibility Guidelines Success Criteria 1.3.1 Info and Relationships (A): "Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text."

The "Text should not be a heading" and "Text should be a heading" issues are about the information.
The "Headings do not reflect the content structure" issue is about structure and relationships.

When we spot these issue in the course of an Accessibility Assessment, we usually log them as Medium Severity: it causes problems or frustrations for users.

Headings that aren't descriptive fall under WCAG Success Criteria 2.4.6 Headings and Labels (AA). These are usually Medium Severity too.

Use your head(ings)

Using headings to give our pages a clear shape makes them easier to understand.

Make sure that:

text that functions as a heading is marked up as a heading
text that does not function as a heading is not marked up as a heading
headings reflect the content structure

Useful tools

Two of my favourite ways to visualise headings are:

the Headings bookmarklet at Accessibility Bookmarklets
the Headings toggle (in Ad hoc tools) of the Accessibility Insights for Web extension.

Both of them add annotation-like boxes and text, making it easier scroll through and visually spot weird heading things.

Them’s the Breaks

2025-12-15T00:00:00Z

by Tyler Sticka

On the web, it’s easy to take line breaks for granted.

We get them for free between our headings, paragraphs, list items, <div> elements and more. We display them as-is in our code snippets thanks to <pre>. And most magically of all, our browsers insert breaks automatically where lines of text (or other text-like “inline” elements) would otherwise outgrow their container.

But sometimes, that isn’t enough.

Some words are too long and continuous to break automatically. Some words can be “orphaned” onto their own, lonely line. Occasionally, our content demands an overt break; more often, our designs call for their addition or removal.

So it makes sense that HTML provides a few options for managing mid-content breaks. Some famously overused, others less known or understood:

The “break” element, <br>
The “word break opportunity” element, <wbr>
The “soft hyphen” character, 
The “non-breaking space” character,

Let’s “break” down (nyuk, nyuk) those techniques: What they do, when they’re appropriate, and alternatives to consider.

The “break” element, `<br>`

99% of the time, line breaks in text that are truly meaningful to your content will justify a new paragraph, list item, <div> or other block element.

The <br> (“break”) element is for those rare exceptions.

For example, a <br> can force a break between lines of poetry or song (apologies to Linkin Park):

<p>
  Everything you say to me<br>
  (Takes me one step closer to the edge)<br>
  (And I’m about to break)
</p>

Or within an address:

<address>
  Breakside Brewery<br>
  1570 NW 22nd Ave.<br>
  Portland, Oregon 97210
</address>

And… that’s pretty much it. As commonplace as <br> is, it’s rarely preferable to more semantic HTML.

The “word break opportunity” element, `<wbr>`

The <wbr> element is <br>’s less famous, more introverted cousin. It inserts a break only when the text will overflow and the browser can’t find a “break opportunity” (whitespace) of its own.

You wouldn’t want to use <wbr> for most text: There’s no hyphenation or anything to indicate where breaks occur. But it can be useful when a string has predictable breakpoints that aren’t spaces.

For example, the slashes in a URL or directory path:

https://htmhell.dev<wbr>/adventcalendar<wbr>/2025<wbr>/17<wbr>/index.html

Or dot notation in an object chain:

namespace<wbr>.class<wbr>.object<wbr>.property

<wbr> should only be used to signify clear break points: You should not attempt to auto-insert <wbr> elements willy-nilly as a form of general overflow avoidance. It is also a poor choice for any list-like content, such as breadcrumb navigation.

The “soft hyphen” character, ``

The (“soft hyphen”) character reference ( for the Unicode stans) functions a lot like <wbr>, except a hyphen is inserted just before the break:

anti&shy;dis&shy;establishmen&shy;taria&shy;nism

 is also surprisingly configurable via CSS. You can replace the hyphens with a character of your choice:

p {
  hyphenate-character: "⋯";
}

Or disable them entirely:

p {
  hyphens: none;
}

The hyphenation makes  more suitable for typical prose than <wbr>. That said, hyphenation in general is a bit of a minefield:

It doesn’t work well in every language.
Breaking up a word between two lines, hyphenated or not, can be challenging for many readers.
While hyphenation has a long and rich typographic history, its readability has always been highly dependent on the size, layout and justification of the overall text. Dynamic content and responsive containers make it that much tougher to get right.

I occasionally find  helpful when I’m writing and notice a word flowing in a particularly troublesome way. I’d consider frequent usage a signal to simplify my verbiage or tweak my design.

The “non-breaking space” character, ` `

Normally, whitespace characters are the most reliable indication of a line break opportunity. The   character openly defies that convention, applying a space that is, much like Kimmy Schmidt, unbreakable:

Keep&nbsp;it&nbsp;together

(The non-breaking space is just one of many whitespace characters that will prevent a string from breaking as you’d normally expect.)

As useful as that sounds,   and its cousins should be considered a last resort. They don’t play very well with other techniques for managing breaking and text flow, and they’re virtually impossible to style without additional selectors or truly epic hacks.

Gently Apply Your Breaks

If you’ve followed along to this point, you may notice a pattern: These techniques all have pretty limited use cases!

<br> for the rare break that’s actually part of the content (poems, addresses, etc.)
<wbr> for weird run-on strings
 for very occasional hyphenation in prose
  when you must avoid a break at all cost

For other mid-content break scenarios, your best bet is CSS!

With display, we can stack inline elements as if they were blocks:

<p style="display: grid;">
  <span>Ms. Boop Squanklin,</span>
  <span>Beloved Activist &amp; Icon</span>
</p>

Or flow block elements together:

<hgroup style="display: flex; flex-wrap: wrap; column-gap: 1ch;">
  <h1>Heading</h1>
  <p>Subtitle</p>
</hgroup>

Or keep key phrases wrapping as one:

<p>
  “Come Together” by
  <span style="display: inline-block;">
    The Beatles
  </span>
</p>

We can encourage long strings to wrap more aggressively with overflow-wrap:

p {
  overflow-wrap: anywhere;
  /* or */
  overflow-wrap: break-word;
  /* or */
  word-break: break-all;
}

Rescue typographic orphans with text-wrap:

p {
  text-wrap: balance;
  /* or */
  text-wrap: pretty;
}

Or micro-manage break behavior with white-space:

.yolo-single-line {
  white-space: nowrap;
}

(We can even apply hyphenation and truncation via CSS, but these present their own challenges. See my justified text explorations and some classic truncation wisdom from Karen McGrane.)

Content that calls for a semantic break is rare, but real: It’s good to understand your HTML options for that scenario. But once you’ve plopped in one quick <br>, its immediacy makes it tempting to overuse.

Resist the urge, write good markup, and embrace the accessibility, power and maintainability of CSS alternatives. Your audience and your project’s future maintainers will be happy you did!

The Wonderful World of Web Feeds

2025-12-14T00:00:00Z

by Maureen Holland

Web feeds are incredible! And a bit confusing! Why are the feed links often called “RSS”? And why is this “RSS” feed in an atom.xml file… hang on, what is feed.json for? What are they even feeding into anyway?

To start, web feeds are often referred to as “RSS” because RSS is the oldest format. RSS stands for Really Simple Syndication. It is an XML-based specification for web content syndication (including podcasts).

Syndication is the sale or licensing of material for publication or broadcasting by others. In broadcast syndication, networks sell reruns of their original shows to other platforms, where those shows might reach a larger audience. In web content syndication, feeds package web content into a format that can “rerun” on a feed reader application. A key difference is that feeds are not sold to feed readers. The “audience” for web feeds has a much more active role to play. They are subscribers, choosing what content they want to follow and what reader they want to follow it on.

Other web content syndication specifications include Atom (also XML-based) and JSON. If you’re interested, CSS Tricks has a breakdown of the technical distinctions between these formats. A web feed (even one that says it’s an “RSS” feed) could be any of these formats under the hood.

A very basic web feed looks like this: https://maureenholland.ca/magpie/feed.xml

Simplified example below:

<rss version="2.0">
	<channel>
		<atom:link href="https://maureenholland.ca/magpie/feed.xml" rel="self" type="application/rss+xml"/>
		<title>Magpie</title>
		<link>https://maureenholland.ca/magpie/</link>
		<description>
		Blog of writer and web developer Maureen Holland. Untidy nest of shiny things.
		</description>
		<language>en-ca</language>
		<item>
			<title>A Vanilla Personal Site</title>
			<link>
			https://maureenholland.ca/magpie/a-vanilla-personal-site
			</link>
			<guid isPermaLink="true">
			https://maureenholland.ca/magpie/a-vanilla-personal-site
			</guid>
			<pubDate>Tue, 18 Apr 2023 12:00:00 GMT</pubDate>
			<description>
			I rebuild my personal site every few years. This time, I decided I wanted to go as minimal as possible. It's been the most enjoyable iteration.
			</description>
		</item>
	</channel>
</rss>

This XML file includes general info about the feed (channel) and lists one item which contains a title, link, description, publication date (pubDate), and globally unique identifier (guid).

A feed reader, like Feedbin, NetNewsWire, or NewsBlur, is able to parse that information and serve it in a human-readable format that will look something like this:

It uses the unique identifier to determine if an item in the feed is new. It can do this for any number of feeds, constantly updating a reading list of your favourite web content.

Importantly, feed readers have no proprietary control over your feed list. If you are dissatisfied with your reader, you can export your feeds to an OPML (Outline Processor Markup Language) file and import them to a new reader later.

The Joy of Autodiscovery

Remember all that stuff about RSS and Atom and XML and JSON? Forget it!

A subscriber shouldn’t have to know any of that technical detail. This is where RSS Autodiscovery comes in.

You can implement autodiscovery with a single line of HTML in the head of your website (and if you’re using a blog platform, chances are it’s already there by default):

<link rel="alternate" type="application/rss+xml" title="Magpie" href="https://maureenholland.ca/magpie/feed.xml">

Now, no one has to hunt for your site’s subscribe link (or “RSS” link or whatever). They can copy/paste the website address into their feed reader and let the application do the work of finding the feeds.

If you want, you can also include separate links for different categories. WordPress, for example, automatically generates feeds for entries and comments. Ghost includes a main post index, author archive, and tag archive.

This is not required but can be helpful if your site has a lot of frequently updated content or a wide range of topics. Subscribers may prefer a subset of content (i.e. long form articles or short “Today I Learned” posts).

<link rel="alternate" type="application/rss+xml" title="Everything" href="https://example.com/feed.xml">
<link rel="alternate" type="application/rss+xml" title="Articles" href="https://example.com/articles.xml">
<link rel="alternate" type="application/rss+xml" title="TIL" href="https://example.com/til.xml">

Wrapping Up

I started subscribing to web feeds after reading Tim Kadlec’s Investing in RSS. When I’m online, at some point, I will be checking my feed reader for a bit of inspiration. It’s a form of self-care to step out of the daily grind and step into someone else’s brain for a while. As much as I’ve learned from the articles I’ve read, it’s the feeling I’ve had reading them that I remember most, that spark of connection or revelation. If I’ve been offline for a while, the unread notifications can pile up, so I also consider it a form of self-care to select “Mark all as read.”

If you’re already a fan of web feeds, check you’ve made it easy for others to find your feed with autodiscovery. If you’re new to web feeds, pick a reader and try it out for a month. Then switch to a different one, just because you can.

This post owes a lot to Matt Webb’s great work on https://aboutfeeds.com/.

Hell is other people's markup

2025-12-13T00:00:00Z

by Ian Lloyd (Lloydi)

HTMLHell started as a site that showed some of the finest, and by that I mean most awful, examples of crimes against markup the world has to offer (and how these crimes can be put right). We’ve all seen some shit, man. But somewhere along the line, Manuel started HTML Heaven, covering decent markup and clever techniques. It's a good mix of dark and light, yin and yang. And what I wanted to cover in my offering to this annual advent calendar sits firmly in the middle. I can't prevent you from witnessing markup that makes you want to gouge your eyes out with rusty soup spoons, but I may have a solution that helps you understand what you can see in the browser a little more easily.

Before I continue, it might be worth explaining a bit about what I do in my day-to-day role to provide context about why this all came about.

I carry out accessibility audits for multiple clients at TetraLogical (or assessments as we refer to them internally). When I encounter something that doesn't behave as it should when trying to navigate using a keyboard, or doesn't sound right when using a screen reader, the first thing I need to check is what is the markup (HTML) behind the elements with issues. Typically, that means right-clicking on the part of the screen where the problem exists and looking at the Elements tab in the browser's built-in DevTools feature. I'm also likely to need to check the Accessibility panel in DevTools to see what that markup exposes to assistive technology users.

Here's a supoer simple example of TetraLogical's website, showing details of the top navigation element:

What I hope to see whan I check the markup showing in DevTools: semantic markup that provides structure/meaning to what is rendered on the page (as in the example above).
What I increasingly find: non-semantic markup that is often heavily nested, stuffed full of attributes, and which usually requires multiple steps to expand each node to get the full picture.

A few years back, I created a tool that was very much borne out of frustration while doing an audit of a very well known web site. Everything that I checked was just an absolute WALL of attribute-laden markup.

The markup might have been structurally fine, but it really took some effort to discern that that was the case. I had to go through various passes to work out what I was actually looking at to be able to make sense of things. The frustration led me to create the HTML De-crapulator, a tool that I would use many, many times in audits that I carried out for years after. But ... I still felt it could be more useful.

The HTML De-Crapulator can provide many ways to simplify markup, such as:

Removing specific attributes
Abbreviating specific attributes
Removing empty tags
Removing framework-specific comment tags

Most of the time, pressing the 'Check (almost) all of the above' button did the bulk of what is needed to strip selected markup to its bare bones. Most of the time ... Inevitably, with each new site I had to check, I'd find a new collection of custom attributes or tagnames that the tool didn't have in its defaults, so I'd have to customise again and again. The tool does take out a lot of the manual work required to clean up the markup, but I was still finding it to not be as quick as it could be.
What do I want? I want to look at how a given part of the page is built, quickly. Yet this still doesn't feel all that speedy to me:

Right click on an element on the page
Select Inspect
Right click on the node revealed in the Elements panel in Dev tools
Copy the Outer HTML
Go to the HTML De-Crapulator and paste
Try the Check (almost) all of the above button and see what the results are
Get frustrated by the remnants still there that I really don't care about
Refine, refine, refine until I have the cleaned up markup just so

I just wanted to get the markup that matters, quickly. What do I mean by markup that matters?

Anything that exposes the role of an element to assistive technology users
Anything that exposes the state of an element to assistive technology users
Any attribute that may affect the focusability of an element

Anything else is just noise. With that in mind, a few months back I came up with the 1-Click De-Crapulator.

How does it work? You run the script (as a bookmarklet or you can use the version in the Chrome extension if you prefer) and then do the following:

Click on the thing you want to get simplified markup for
That's it. There is no step 2

OK, so there sort of is a step 2 ... if you need it, and that's to copy the markup that's presented. But essentially, with one click you can see the markup for the selected node in a super-simplified format, ready to copy and paste if you choose to.

At a glance, you can understand the structure of the item that you selected. All classes and trivial attributes are jettisoned. Only those that may have an impact on how the page is exposed to assistive technology users remain (text alternatives, states, ARIA-* attributes, id attributes ... but only where something else is referencing that element and needs it otherwise all the ids are stripped).

Went too far? You can also quickly switch between the original markup with all attributes intact, should you want to make a quick comparison.

Didn't go far enough? Perhaps you're seeing endless levels of <div> nesting that really isn't contributing to meaning or structure? You have the option of flattening it. Here's the before version:

And here is the after:

Of course, you really are messing with the original markup here, but for the noble reasons of making it understandable and simplified. To save you having to explain each and every time that you simplified the markup when writing up an issue, the tool also wraps the output with Markdown block code backticks and an explanatory phrase that should work for almost every scenario: "Simplified HTML (with some attributes/features removed for clarity)".

As with the original full-fat HTML De-Crapulator, this won't address the root of the problem: namely, developers producing shoddy markup. But if you spend much of your day trying to decipher and remediate other people's markup, which can be hell, this tool can save you a lot of fuss and bother in getting to the bottom of the issue.

A11y Considerations in Math on the Web

2025-12-12T00:00:00Z

by Manuel Sánchez

Maybe it has happened to you that you wanted to write some formulas in HTML to display on a website, and even though there are multiple ways to do it, accessibility is often not considered in the process. How the formula is read by screen readers is crucial to ensure that we don't leave anyone behind. And the main assistive technologies are in different stages, as we will see.

The web is full of many different and interesting approaches for representing formulas. To name a few, we have TeX/LaTeX source rendered in the browser in different ways, like MathJax or KaTeX, we can use Unicode math, Canvas/WebGL or even simple PNG/JPG or SVG pictures. However, using native MathML is usually one of the best options for this task, even if it wasn’t initially designed for the web. Some of its advantages are that it has its own syntax, MathML, which provides various elements that give the correct semantics to the different parts of a formula, it has good screen reader support, works without JavaScript dependencies, and can be used beyond the browser, as in EPUB or braille/math speech tooling.

Let's take the famous Pythagorean Theorem as an example.

Pythagorean Theorem

The following example is a visual representation of the formula together with the MathML code.

a^{2} + b^{2} = c^{2}

<math xmlns="http://www.w3.org/1998/Math/MathML">
  <msup>
    <mi>a</mi>
    <mn>2</mn>
  </msup>
  <mo>+</mo>
  <msup>
    <mi>b</mi>
    <mn>2</mn>
  </msup>
  <mo>=</mo>
  <msup>
    <mi>c</mi>
    <mn>2</mn>
  </msup>
</math>

Unlike plain HTML with sup or span, which only describe presentation, MathML defines each role explicitly:

math represents the entire mathematical expression.
msup defines a superscript relationship (a base and an exponent).
mi is a mathematical identifier, typically a variable such as a, b, or c.
mn is a mathematical number, like 2.
mo is a mathematical operator, such as + or =.

Other alternatives, like the ones mentioned above, may offer similar capabilities, but they typically rely on an assistive or hidden MathML layer. In practice, MathML remains the only web-standard markup that expresses mathematical roles natively in the DOM.

With this approach, the accessibility tree shows good semantics and VoiceOver knows well what to do.

However, as we will see throughout the article, screen reader support for the math tag varies across assistive technologies. VoiceOver seems to be doing a pretty good job, JAWS also makes it easy for both speech and braille, and NVDA needs an add-on to make it work called MathCat because if not, the math tag will be ignored. A major pull request (#18323) was merged on 17 November 2025 which integrates MathCAT into NVDA core, meaning users won’t have to find/install a separate add-on to handle math.

How screen readers interpret the formula

NVDA + Firefox (Windows with MathCAT add-on)

region a squared plus b squared is equal to c squared space

VoiceOver + Safari (Mac)

a squared + b squared = c squared, with 5 items, maths

VoiceOver + Safari (iOS)

a squared plus b squared equals c squared, Math

Let's look at a more complicated case. Instead of just displaying the formula, let's see how to actually prove it and how screen readers will announce it.

<math display="block">
  <semantics>
    <mtable>
      <!-- Step one -->
      <mtr>
        <mtd>
          <msup>
            <mrow>
              <mo>(</mo>
              <mi>a</mi>
              <mo>+</mo>
              <mi>b</mi>
              <mo>)</mo>
            </mrow>
            <mn>2</mn>
          </msup>
        </mtd>
        <mtd>
          <mo>=</mo>
        </mtd>
        <mtd>
          <msup>
            <mi>c</mi>
            <mn>2</mn>
          </msup>
          <mo>+</mo>
          <mn>4</mn>
          <mo>⋅</mo>
          <mo>(</mo>
          <mfrac>
            <mn>1</mn>
            <mn>2</mn>
          </mfrac>
          <mi>a</mi>
          <mi>b</mi>
          <mo>)</mo>
        </mtd>
      </mtr>
      <!-- Step two -->
      <mtr>
        <mtd>
          <msup>
            <mi>a</mi>
            <mn>2</mn>
          </msup>
          <mo>+</mo>
          <mn>2</mn>
          <mi>a</mi>
          <mi>b</mi>
          <mo>+</mo>
          <msup>
            <mi>b</mi>
            <mn>2</mn>
          </msup>
        </mtd>
        <mtd>
          <mo>=</mo>
        </mtd>
        <mtd>
          <msup>
            <mi>c</mi>
            <mn>2</mn>
          </msup>
          <mo>+</mo>
          <mn>2</mn>
          <mi>a</mi>
          <mi>b</mi>
        </mtd>
      </mtr>
      <!-- Step three -->
      <mtr>
        <mtd>
          <msup>
            <mi>a</mi>
            <mn>2</mn>
          </msup>
          <mo>+</mo>
          <msup>
            <mi>b</mi>
            <mn>2</mn>
          </msup>
        </mtd>
        <mtd>
          <mo>=</mo>
        </mtd>
        <mtd>
          <msup>
            <mi>c</mi>
            <mn>2</mn>
          </msup>
        </mtd>
      </mtr>
    </mtable>

    <annotation encoding="application/x-tex">
      \begin{aligned} (a + b)^2 &= c^2 + 4 \cdot \left( \frac{1}{2} ab \right)
      \\ a^2 + 2ab + b^2 &= c^2 + 2ab \\ a^2 + b^2 &= c^2 \end{aligned}
    </annotation>
  </semantics>
</math>

\begin{matrix} {(a + b)}^{2} & = & c^{2} + 4 \cdot (\frac{1}{2} a b) \\ a^{2} + 2 a b + b^{2} & = & c^{2} + 2 a b \\ a^{2} + b^{2} & = & c^{2} \end{matrix}

This proof example just added several MathML elements that go beyond simple identifiers and operators. Each of these adds meaning to the expression, which is why assistive technologies can navigate the structure so precisely. For example:

mtable, mtr and mts: these directly mirror HTML's table, tr and td but are math-specific. They tell the accessibility tree: "this is a mathematical table with aligned steps," not just a generic layout table. Screen readers can move row-by-row, so each step of the proof becomes navigable.
mrow: groups expressions together. For example (a + b) is wrapped in an mrow to indicate that the parentheses and the interior form a single unit before exponentiation.
mfrac: defines an actual mathematical fraction, not just text with a slash. This allows speech engines to say "one half" instead of "one over two" depending on preferences and locale.
semantics: this is key. It wraps the expression and lets you attach alternative meanings or encodings. Assistive technologies prefer the first child (your visual MathML), but can fall back to the annotation if needed.
annotation: stores auxiliary information. In this case, the TeX version of the proof. It does not affect the visual rendering in the browser. Instead, it's metadata for tools that consume MathML, like converters, EPUB readers, or braille translators.

Check out how this is announced by different screen readers!

How screen readers interpret the proof

NVDA + Firefox (Windows with MathCAT add-on)

3 lines line 1 left parenthesis a plus b right parenthesis squared is equal to c squared plus 4 times 1 half a b

line 2 a squared plus 2 a b plus b squared is equal to c squared plus 2 a b

line 3 a squared plus b squared is equal to c squared

VoiceOver + Safari (Mac)

Table start, Row 1, Column 1, ( a + b ) squared, Row 1, Column 2, =, Row 1, Column 3, c squared + 4 · ( fraction start, 1 over 2, end of fraction, a b ), Row 2, Column 1, a squared + 2 a b + b squared, Row 2, Column 2, =, Row 2, Column 3, c squared + 2 a b, Row 3, Column 1, a squared + b squared, Row 3, Column 2, =, Row 3, Column 3, c squared, table end, maths

VoiceOver + Safari (iOS)

1 table, table start, Row 1, Column 1, a plus b squared, Row 1, Column 2, equals, Row 1, Column 3, c squared plus 4 dot fraction start 1 over 2, end of fraction, a b, Row 2, Column 1, a squared plus 2 a b plus b squared, Row 2, Column 2, equals, Row 2, Column 3, c squared plus 2 a b, Row 3, Column 1, a squared plus b squared, Row 3, Column 2, equals, Row 3, Column 3, c squared, table end, Math

Note: If you want to deepen your understanding in the topic, MDN has a very detailed page about proving the Pythagorean theorem with MathML.

We could enhance this by adding an aria-label to a wrapper that provides some information about the following formula, especially when it's a well-known one. By using a section with an aria-label or aria-labelledby together with another element giving the accessible name, we automatically insert a region into the accessibility tree.

<section aria-labelledby="section-1-heading">
  <h2 id="section-1-heading">Pythagorean Theorem</h2>
  <math xmlns="http://www.w3.org/1998/Math/MathML"> ... </math>
</section>

Also, for users who zoom the browser up to 400%, we might want to add a max-width: 100% and overflow-x: auto, so that the formula remains readable, does not break the page and we allow horizontal scrolling only inside the math block, and not at the entire page level.

Conveying mathematical meaning with ARIA

We also have the math role from the ARIA specification. With that, we can communicate the mathematical semantics even when we rely on images or non-semantic HTML. However, it does not give good results with VoiceOver on macOS, for example.

As shown on the MDN page for the math role, we could have:

<div role="math" aria-label="a^{2} + b^{2} = c^{2}">
  a<sup>2</sup> + b<sup>2</sup> = c<sup>2</sup>
</div>

Markup with a div with the math role and how screen readers interpret it

Markup

a² + b² = c²

NVDA + Firefox (Windows with MathCAT add-on)

just announces the text

VoiceOver + Safari (Mac)

not read, just announces "with 6 items, maths"

VoiceOver + Safari (iOS)

a caret left curly bracket 2 right curly bracket plus b caret left curly bracket 2 right curly bracket equals c caret left curly bracket, Math

<img src="pythagorean_theorem.png" alt="a^{2} + b^{2} = c^{2}" role="math" />

Markup with a img with the math role and how screen readers interpret it

Markup

NVDA + Firefox (Windows with MathCAT add-on)

just announces the text

VoiceOver + Safari (Mac)

not read, just announces "maths"

VoiceOver + Safari (iOS)

a caret left curly bracket 2 right curly bracket plus b caret left curly bracket 2 right curly bracket equals c caret left curly bracket, Math

In practice, using the math role helps assistive technologies understand that the content is mathematical, but it still doesn’t provide enough semantic detail for them to announce the expression as accurately as MathML does.

The future of MathML

TL;DR: MathML Core is what browsers implement today; MathML 4 is the broader language evolving around it.

As I mentioned at the beginning, the origin of MathML was not the web, it was more of a general-purpose specification for browsers, office suites, computer algebra systems, EPUB readers, and LaTeX-based generators, as stated on MDN. MathML Core arose from the need to make it work with web standards, including HTML, CSS, DOM, and JavaScript. Historically, the full MathML spec was broad and partly underspecified for browsers, which led to uneven or incomplete implementations across engines. MathML Core therefore narrows the language to the subset that can be precisely defined on top of the Web Platform, improving testability and cross-browser interoperability. Since June 2025, MathML Core has been a Candidate Recommendation Snapshot. On another note, at the time of this writing, there is a Working Draft for MathML 4, the next version of MathML. This version aims to be the next "full" spec that extends Core. It keeps the larger feature set (e.g., Content MathML) and adds, among others, the intent attribute so authors can guide screen-reader speech. With it, we'll be able to do something like this:

<math>
  <mrow intent="equals(power(a,2)+power(b,2),power(c,2))">
    <msup>
      <mi>a</mi>
      <mn>2</mn>
    </msup>
    <mo>+</mo>
    <msup>
      <mi>b</mi>
      <mn>2</mn>
    </msup>
    <mo>=</mo>
    <msup>
      <mi>c</mi>
      <mn>2</mn>
    </msup>
  </mrow>
</math>

Conclusion

As browser support for MathML continues to evolve, previous fallback solutions like mathml.css are no longer necessary. MathML Core, and soon MathML 4, allow us to express both the visual and semantic meaning of mathematical content without sacrificing accessibility along the way.

Screen-reader support is also steadily improving. Each assistive technology handles MathML in its own way, but the overall trajectory is positive. VoiceOver offers consistent navigation and speech for many common patterns across macOS and iOS. JAWS, especially when paired with Fusion, provides rich support for both speech and braille. And NVDA, which historically required an add-on, is now moving toward a built-in MathCAT integration, making MathML speech and braille support more accessible out of the box for Windows users.

How HTML changes in ePub

2025-12-11T00:00:00Z

by Robin Whittleton

ePub is the W3C standard for ebooks. It lets you take your knowledge of the web, and use it to produce little self-contained sets of documents that can be freely distributed as a single file ready for reading on extremely low-power devices, and they even reflow to fit any screen.

Yet while I said that you can use your knowledge of the web to build ePubs, the technology in use is twisted in unforeseen ways, and you might have to unlearn the things you think you knew. Prepare yourself…

HTML, sort of

ePubs, at their core, use HTML, just like the websites we build every day. Except, well, there’s a big asterisk after that. Let’s dive into the differences.

A few decades ago XML emerged from the pit. XML – an extensible standard for expressing marked up data – could be used for documents, data transfer, and a bunch of other things, and people genuinely liked it (or, much like AI today, pretended to for job security). They liked it so much that a concerted effort was started to take HTML and rebuild it on top of XML. This project had a name you might have heard of: XHTML.

XHTML didn’t work out, for a number of reasons. The extensibility of XML turned out to not be useful when browsers didn’t support even common extensions. Then there was the problem of fragility: any syntax problems with your XHTML and your users would get a blank screen. If those two problems weren’t enough, XHTML was slower in practice because the browser needed to wait to download the entire document before doing anything else.

But there is one place where XHTML still rules the roost: ePub. ePub books are, at their heart, a collection of XHTML documents (now using the XHTML flavour of the HTML Living Standard). This means that:

Valid, syntactically correct XML markup is needed. Without that, your e-reader will complain. This means self-closing tags, correct namespaces, XML attributes in the XML namespace (xml:lang), and so on.
Other XML languages can be included directly into XHTML by adding namespaces.
The epub namespace is unlocked, which adds additional functionality to your ePub in e-readers.

We’ll come back to that…

CSS, sort of

So HTML is actually XHTML in ePub. Is CSS some sort of XCSS? Actually, no: CSS is broadly the same as you know it, but with a few quirks.

First up, e-readers and e-reader software are, compared to our normal evergreen browsers, typically really basic. They can run on underpowered hardware, people often keep their e-readers for over a decade, and the engines they use can be positively historic. To put it another way, I’m wary of using :not() in ePub CSS for a widely distributed title. While I might be overly cautious here, don’t expect nowadays normal pseudoclasses like :is() to have wide support. Luckily, layout tends to be simpler in a document-focused format, and progressive enhancement is possible with @supports.

Next, as our markup is now namespace aware, our CSS needs to follow. For example, if you wanted to style a piece of text in a different language that you’ve marked up like:

<p>As Jean-Paul Sartre said, <q xml:lang="fr">L’enfer, c’est les autres</q>.</p>

Then you can’t simply use an attribute selector like q[lang], you need to define your namespaces and reference them in your selectors using the | separator:

@namespace xml "http://www.w3.org/XML/1998/namespace";

q[xml|lang] { … }

Strange extensions

As mentioned earlier, namespace support means that other XML-compatible markup languages can be incorporated directly into your XHTML document. These could be just additional semantic attributes, or even new elements. Obviously to get anything useful out of them you need e-reader support, but that’s present in a few cases. Let’s take a look at a couple.

You might actually be familiar with MathML, as it’s supported in HTML5. The way you use it in HTML is that there’s a broad agreement that the contents of the MathML spec will just work when used in HTML. Adding a basic MathML equation using standard MathML tags (math, mi, mo, mn, and so on) to your normal HTML document ends up looking something like $n + 1$ .

But in XHTML (because it’s an XML language) there’s a standard integration process for any XML language you want to bring in. First, you define your MathML namespace against the root element:

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:m="http://www.w3.org/1998/Math/MathML">

Then the MathML elements are available to use inside the document under that namespace:

<m:math alttext="n + 1">
  <m:mi>n</m:mi>
  <m:mo>+</m:mo>
  <m:mn>1</m:mn>
</m:math>

Same goes for SVG: in HTML it’s just allowed to be included with standard SVG tags; using svg, title and path can get you something like . But in XHTML you’ll need to declare the SVG namespace and use that with your images:

<html xmlns="http://www.w3.org/1999/xhtml" xmlns:svg="http://www.w3.org/2000/svg">

<svg:svg viewBox="0 0 452 452">
  <svg:title>the HTMHell logo</svg:title>
  <svg:path d="M198.2.94c-28.6 3.3-61.4…"/>
</svg:svg>

Of course, we’re talking about ePub here. There’s a W3 ePub specification (currently at version 3.3) that defines the structure and metadata of an ePub document, and gives us the epub:type attribute. This attribute (in conjunction with the Structural Semantics Vocabulary specification) can be used in a few ways to improve your collection’s usability within an e-reader. Let’s look at an example.

One thing books often have is endnotes, but there’s no easy way of expressing that semantic state in HTML. In ePub’s vocabulary though we find the noteref attribute value. If we use this on a link then readers know to pull in a fragment from another place and typically display then this inside a modal that can be dismissed to return to the existing place. This looks something like:

<p>ePub is hellish.<a href="endnotes.xhtml#note-1" id="noteref-1" epub:type="noteref">1</a></p>

And in your collection of endnotes:

<li id="note-1" epub:type="endnote">
  <p>…unless you read HTMHell. <a href="page.xhtml#noteref-1" epub:type="backlink">↩</a></p>
</li>

Note: epub:type is gradually being deprecated in favour of the role values defined in the Digital Publishing WAI-ARIA spec, but currently that functionality is either unimplemented or only available in the latest systems. For example, the above endnotes functionality doesn’t yet work in Apple Books (generally a good e-reader) if you use role="doc-noteref" and role="doc-endnotes".

As well as these ePub semantic vocabulary, we also have things like the Z39.98-2012 Structural Semantics Vocabulary. This extends the base ePub spec, and takes the form of z3998-namespaced attribute values, which definitely looks odd if you’re not used to it. You can use these to express even more fine-grained semantic values, for example Roman numerals (<span epub:type="z3998:roman">DCLXVI</span>) or parts of letters. Broad support for extracting any functionality from these is extremely lacking, but when did that ever stop us front-end developers from going over the top?

Want to try this all out?

Writing an ePub isn’t exactly hard, but there’s some scaffolding necessary to get to a workable structure. You need a container.xml file in a META-INF directory that points at a package file. The package file contains a bunch of metadata about your ePub, including a manifest of the XHTML files in your book (for example, different chapters), and a spine describing the order they should be shown to the reader. You then add your XHTML files, reference them in the manifest and spine, and finally zip the whole directory up into a single archive and rename it to a .epub.

To get you started, I’ve prepared a copy of this blog post as an ePub ready for your favourite e-reader (assuming it’s modern: I haven’t included any compatibility hacks). To inspect the contents we just need to unzip it; try renaming the file to have a .zip at the end and opening it with your favourite unarchiver. The markup can be found in src/epub/text.

If you want to create your own ePubs I’d personally recommend starting with the Standard Ebooks toolset: it can create unbranded ePubs and has a bunch of compatibility tooling built in. Once installed, you can create a directory with the requisite scaffolding with se create-draft --white-label, and then build that into an ePub with se build.

I hope you have fun putting your own ebooks together! It’s a useful new skill that reuses a lot of your existing knowledge.

a11y freedom beaver

2025-12-10T00:00:00Z

by Steve Faulkner

♿☮️🦫 sez: Know your Standards

1st Rule of ARIA

The first rule originally appeared in 2012 Notes on using ARIA, it was then moved to a new home Using ARIA.

It's not really a rule in any formal sense; I just made it up. It has remained unchanged for 14 years but remains relevant today.

First Rule of ARIA Use

If you can use a native HTML element HTML or attribute with the semantics and behavior you require already built in, instead of re-purposing an element and adding an ARIA role, state or property to make it accessible, then do so.

Under what circumstances may this not be possible?

If the feature is available in HTML but it is not implemented or it is implemented, but accessibility support is not

If the visual design constraints rule out the use of a particular native element, because the element cannot be styled as required

If the feature is not currently available in HTML

source: Using ARIA

Reasons to be cheerful (about not having to use ARIA so much)

the feature is available in HTML but it is not implemented or it is implemented, but accessibility support is not

When I first wrote the first rule there were many new features in HTML, many of which had not had their accessibility support (or support in general) wired up. Which is why I started documenting support for new features back in 2010 (HTML5Accessibility.com WayBack Machine snapshot October 2010). Last time I checked back in August 2020, things were looking much better. So these days there is little to no need to use ARIA to supplement native HTML semantics, the browsers do it for you mostly. In fact the unecessary use of ARIA is a HTML conformance error as defined in the ARIA in HTML specification.

visual design constraints rule out the use of a particular native element, because the element cannot be styled as required

In 2025 the opportunity for a front end developer to craft visual UI that meets the needs of their bosses is much improved. CSS and browser implementations continue to be enhanced to make it possible.

the feature is not currently available in HTML

This is still a valid reason for building stuff from HTML elements that carry little or no semantics, then adding ARIA to convey meaning robustly and interoperably to people that make use of assistive technology to render web content understandable. But valid less so as many of the features that are routinely foisted upon users are now available as native HTML, for example, dialogs and disclosures

What ARIA does not do

The good thing about using HTML elements is they have operability built in: ARIA does not.
For example, a <button>-element is automatically included in the focus order and will have event listeners attached, an element with role="button" will not have those characteristics by default.
Please read What ARIA still does not do for details.
A popular use case for ARIA is custom elements, to appreciate what you need to do to make them accessible, the Web Components punch list may be helpful.

Last words

We already know:

Increased ARIA usage on pages was associated with higher detected errors. The more ARIA attributes that were present, the more detected accessibility errors could be expected.

Do not introduce more ARIA into your code in an effort to please the knowledge ghouls of OpenAI and their new browser. Although you wouldn't know it from the bumpf OpenAI published - It is not needed.

and a merry fucking xmas to all!

Discover Dialog

2025-12-09T00:00:00Z

by Sara Joy

Suffering modal woes? Positioning, backdrops, focus trapping, z-index — Oof.

Just as I was, some of you may have been coding a lot of these functions into a <div> by hand with CSS and JavaScript, or using a library to handle them for you.

Either way, things are getting simpler and more declarative all the time - and when we're so busy working, we don't always realise how much has changed! Maybe this will help you shave off some lines of code or remove some dependencies from your codebase.

To those of you new to building on the web, this is for you too, as you lucky things get to skip the old ways :)

Meet

The dialog element has been available across browsers since March 2022, and allows you to pop a little overlay on your page - a common variant is known as a modal - and it has a whole bunch of abilities built in, with further useful facets still being added.

<dialog id="meetDialog">
  <p>
    Hello 👋
    <br />Nice to meet you!
  </p>
  <form method="dialog">
    <button>Close</button>
  </form>
</dialog>

We're probably more familiar with the modal variety of dialog, intended to (hopefully only briefly) stop you interacting with the page under it. But there are also plenty of non-modal dialogs to be seen around the web, for example notifications.

The dialog element gives us both modal and non-modal variants, depending on how we open them. In the case of more than one dialog being opened (assuming no close action happening on the previous dialogs), the most recently opened dialog will appear on top.

Opening with JS

To open a dialog, we use one of two JavaScript functions on a dialog element:

.show()
.showModal()

Likely based on the click of a button, you will run something like the following (you will likely use a much more specific querySelector):

document.querySelector("dialog").show();
// or
document.querySelector("dialog").showModal();

💡 There is a declarative method available to invoke dialogs, but for now I will stick to what is currently available across the main browsers.

In the CodePen below, both kinds of dialog opening method are available. You'll notice that you can still interact with the Open Modal button after having opened the dialog, but not vice-versa. The modal can be closed with the Esc key, the non-modal dialog cannot.

See the Pen Dialogs! by Sara (@sarajw) on CodePen.

Closing dialogs

You'll also not see any JS for the closure of the dialogs. Pop into the HTML tab in the demo, and you might spot the method="dialog" in the <form> element wrapping the <button>. Here I'm only using it to close the dialogs with said button. If you include more inputs here, method="dialog" will send a submit event and close the dialog, but not actually submit any data anywhere.

<form method="dialog">
  <button>Close</button>
</form>

Dialogs can also be closed without using this form method, instead by activating some JS (maybe also with a button):

document.querySelector("dialog").close();
// or
document.querySelector("dialog").requestClose();

This requestClose() is a newly available addition, allowing access to the cancel event, otherwise thrown before the close event when exiting a modal with the Esc key. This may be useful to create "are you sure?" type interactions. (Please do so with care if you must! We'll have no deceptive patterns here..)

Light dismissal

You're probably already trying to close the dialogs by clicking outside of them, which is a common pattern and is often referred to as light dismiss.

This isn't available by default, but can be coded in with CSS and JS.

With thanks to Chris Ferdinandi and Konnor Rogers for the inspiration, I find the following code works well for modal dialogs only, through the magic of the ::backdrop:

/* disallow pointer events on the backdrop, so they
   don't register as clicks on the dialog itself */
dialog::backdrop {
  pointer-events: none;
}

document.addEventListener("click", (event) => {
  // find any open modal dialogs
  const openDialogs = document.querySelectorAll("dialog[open]:modal");
  // return if none open
  if (!openDialogs) return;

  // check for clicks on documentElement, passed through the backdrop
  if (event.target === document.documentElement) {
    // close the open dialogs
    openDialogs.forEach((dialog) => dialog.close());
  }
});

See the Pen Dialogs with light dismiss (JS) by Sara (@sarajw) on CodePen.

💡 You may have spotted we selected dialog[open] in the JS above.

Yes, open dialogs do get open added as an attribute, and it is possible to toggle this to open and close a dialog, but it is not recommended. It will always open as a non-modal dialog when done in this way, and may lead to confused or missing close events.

I am selecting :modal dialogs only in the code and demonstration above - but you can omit this if you want the click-away to also close any non-modal dialogs that happen to be open at the same time.

To achieve light dismiss on non-modal dialogs alone is trickier unfortunately, as they have no backdrop to play with...

But there is some light at the end of the dismiss tunnel with the closedby property, which is very nearly available across the big browsers - so please feel free to poke any friendly Safari developers you might know! Then it could look as simple as the below:

See the Pen Dialogs with light dismiss (closedby) by Sara (@sarajw) on CodePen.

(Some) styling built in

Apart from limiting the piratey lorem ipsum column width and centering it, no other custom styling has occurred in the CodePen demos.

By default, the non-modal dialog has no backdrop, while the modal dialog's ::backdrop has a subtle transparent grey, and the dialog itself is centered vertically as well as horizontally on the page.

I am going to stand on the shoulders of giants here, and suggest some places you can go to look at amazing dialog CSS styling and animation:

Scrollin', scrollin', scrollin'...

That by default the website under your modal is still scrollable may or may not bother you. It bothers me!

There are ways and means to stop that happening, thankfully.

A classic and elegant way made possible with the sort-of-new-but-well-supported :has() pseudo-class and scrollbar-gutter property is the following:

/* Check whether any modal dialogs are open */
html:has(dialog[open]:modal) {
  /* Poof! No more scrolling! */
  overflow: hidden;
  /* keep the scrollbar width */
  scrollbar-gutter: stable;
}

The scrollbar-gutter property keeps the text on the page from reflowing with a jerk, when it suddenly becomes one scrollbar-width wider as the rest of the page beyond the viewport is hidden.

💡 If you have both non-modal and modal dialogs on your page, be sure to use :modal in your selector so this only triggers on open modal dialogs.

See the Pen Modal dialog with scroll-stop by Sara (@sarajw) on CodePen.

You may have noticed - if you can see a scrollbar - that the scrollbar gutter isn't taking on the backdrop style. Yeah. Go ahead and comment out the scrollbar-gutter: stable; line in the CSS, open/close the modal a few times, and see whether the scrollbar appearing and disappearing bothers you more. It might not - but it bothers me!

Reinstate scrollbar-gutter: stable;, then scroll down a little in the CSS of the above CodePen and uncomment the following:

dialog[open]::backdrop {
  background-color: transparent;
  backdrop-filter: blur(0.25rem);
}

Here I've dropped the default shading of the ::backdrop and applied a blur instead - meaning the gutter blends in, assuming the gutter and page are both the same colour. You might even have some fun seeing how the scrollbars change with color-scheme...

Honestly though, different browsers and OSes and dark and light modes and device types make scroll bars look different all over the place.

On a MacBook whether you even see the scrollbar when you're not actively scrolling depends on whether you have an external pointing device connected or not! So many people now browse the web with mobile devices, where the scrollbars and gutters are largely hidden - so it likely isn't worth spending too much effort trying to "fix" this. Trust me. Don't waste your time on it, I've wasted enough for both of us!

Accessibility

As it opens, by default the focus will land on either the whole dialog, or if it has one, the first focusable element (whether it's a close button or not). A sighted user with a pointing device will probably not tend to notice where the focus lands - but it's very important as a screen reader user, as the focus determines where in a document the reader lands and begins reading from.

In case of needing the focus to land somewhere specific for your use case, I heartily recommend reading Where to Put Focus When Opening a Modal Dialog by Adrian Roselli to help you decide where the focus will land on your dialog. Then read O dialog focus, where art thou? to help you consistently get it where you want it.

If you read the MDN page on dialogs and are bothered by this warning about tabindex on <dialog>, you may either take Adrian or Manuel's word that it's OK, or you can enjoy Manuel's deep dive into What's an interactive element?. Enjoy!

Dialogs discovered

I hope this has been enough to convince you that it's worth using dialogs, if you aren't already, or maybe you've found a couple of interesting tidbits you otherwise weren't aware of.

HTML is still changing and improving - it's not at all archaic or just there to provide <div>s into which we can inject all the things with JavaScript (though of course you can still do that, just please inject accessible elements)!

Feel free to contact me on the social medias to start a, uh, dialog.

What's wrong with this HTML, and is it valid?

2025-12-08T00:00:00Z

by Patrick Brosset

Behold this magnificient HTML document:

<html>
  <body marginheight=150 marginwidth=300 bgcolor=black text=white>
    <marquee>
      <b>Hello <i>HTML</b> World!</i>
    </marquee>

To try it in your browser, copy the following line and paste it into the address bar of your browser:

data:text/html,<html><body marginheight=150 marginwidth=300 bgcolor=black text=white><marquee><b>Hello <i>HTML</b> World!</i></marquee>

What's wrong with it?

Everything? I mean, this HTML looks like it was written in 1998!

The document is in quirks mode because it lacks a proper DOCTYPE preamble.

If you've never heard of quirks mode, then you're probably lucky enough to have started your web development career after it was an important thing to know about. Suffice to say it's weird. Here are some of the ways quirks mode impacts (or impacted) HTML documents:
- The box model used to behave differently in older browsers, which affected layout and spacing. For example, in quirks mode, Internet Explorer included the padding and borders in the element's total width and height. Today, all browsers apply width and height to the content box of an element by default, unless you change the box-sizing CSS property.
- Font sizes don't inherit on table elements.
- Certain inline elements, such as images, don't vertically align the way you think they should when they're the only element inside a block-level container.
You can see a live example of some of these quirks on my site at Quirks mode vs Standards mode.
The <head> tag is missing, which means the document has no <title> either, which is bad for accessibility and UX in general

A common thing that assistive technology users do is read the title of a page first to know if they want to spend more time reading the page's content. Without a descriptive title, folks are forced to start reading more of the content to know if that's what they were looking for in the first place, which is time-consuming and potentially confusing.

In addition, a title is also useful for SEO purposes, is displayed in browser tabs, used when bookmarking pages, and more.
The <body> tag uses deprecated attributes: marginheight, marginwidth, bgcolor, and text.

These attributes are obsolete and discouraged by the spec itself.
The <marquee> tag is obsolete and should be avoided in favor of CSS animations.

Plus, if you really must animate scrolling text, then please use the prefers-reduced-motion media query to respect user preferences.
The <b> and <i> tags look like they're used for styling. That's wrong, right?

More on that later.
The <b> and <i> tags are improperly nested. The nesting is <b><i></b></i> which is out of order.
The closing </body> and </html> tags are missing.

Is this valid HTML?

Well, yes and no:

No: if you send this to the W3C HTML validator, it'll be pretty angry at you and will list the errors I mentioned earlier.
But also, yes: the resulting page just loads and works fine in browsers. See for yourself:

Before discussing each point in details, don't you think this is just beautiful? HTML is so self-correcting that making a browser fail only by using HTML is really hard to achieve, and HTML that looks like it was written two decades ago still works! I mean, take a look at spacejam.com, this old bar website, or even the very first web page that was ever created.

Now let's go over the list of issues I mentioned earlier one more time, but this time, let's talk about why they're not actually causing any problems:

Sure, quirks mode can lead to weird rendering issues if you don't know that you're using it, but it's still implemented in browsers and perfectly ok to use.

Even if quirks mode was added for historical reasons, to support web pages that were made before the CSS specification was fully fleshed out, the code in browser engines, which detects the document mode and renders it accordingly, is here to stay.

There really is no reason for browsers to ever remove it, unless one day, all quirks mode documents were to disappear from the web. This seems highly unlikely though. Judging by Chrome's QuirksModeDocument usage metric, about 30% of all page loaded in Chrome still use quirks mode! A bunch of the sites that are listed on that usage metric page appear to be using it from iframes created to display ads. Still, that's a lot of page loads.

If you're encountering weird rendering issues that you can't explain, double check that you have a DOCTYPE in your HTML document. You can also run the following line of code in the browser console: document.compatMode. If it returns BackCompat, then you're in quirks mode.
The <head> tag can definitely be omitted. Neither the HTML specification, nor browser implementations require the tag to be present.

It's bad for accessibility reasons if you omit it, again because you probably also won't have a <title> tag, but it still works.

In fact, you can also omit <html> and <body> tags too. Personally, I commonly use this to quickly test things out in the browser. Instead of creating a new HTML file on my computer, which takes a bit more time, I just type some HTML in the address bar directly. For example: data:text/html,<div>something. No <html>, no <head>, no <body> elements.
marginheight, marginwidth, bgcolor, or text are deprecated presentational attributes. But, even if they're deprecated and discouraged, they're still implemented in browsers, for backward compatibility reasons.

In fact, here are other similar attributes: bgColor, fgColor, linkColor, alinkColor, and vlinkColor.

If you're as old as I am, you might have used these attributes a long time ago, perhaps when creating sites in FrontPage or Dreamweaver.

Anyway, these presentational attributes act as 0-specificity CSS properties, which means that any CSS property you set in a stylesheet will override them.
The <marquee> element still animates text in browsers. In fact, if you want to go crazy with it, try nesting two <marquee> elements, like this:
```
<marquee
   direction="down"
   width="200"
   height="200"
   behavior="alternate">
   <marquee behavior="alternate">This text will bounce</marquee>
 </marquee>
```
Take a look at the example on codepen.

For an accessible alternative, see Daniela Kubesch's article Get that marquee ✨AeStHeTiC✨.
Using <b> and <i> is perfectly valid. They used to be meant for making the text bold and italic, hence their names. But they were deprecated in HTML4, and the meaning of the tags was changed to mean something else. The <b> tag now means bring attention and the <i> tag now means idiomatic text.

<b> is now used to mark up keywords, product names, or other spans of text whose typical presentation would be boldfaced, but not including any special importance.

<i> is now used to mark up text that is set off from the normal prose for readability reasons.

More semantic tag names have since been invented too: <strong>, <em>, or <mark>, which convey slightly different semantics.

If there's no semantic aspect to the piece of text you want to make bold or italic, don't use <b> or <i>, use CSS font-weight and font-style instead.
Misnested tags can sometimes happen in HTML, and when it does, the page doesn't break!

That's the beauty of HTML once again. If you're coming from an XML background, you might be surprised by the forgiveness of HTML. But, in the vast majority of cases, HTML parsers just figure things out on their own and get you what you want.

In our example, the markup is <b><i></b></i>, which feels obviously wrong because the closing </b> tag should appear after the closing </i> tag, to respect nesting. This particular markup creates the following DOM tree:

This behavior is actually specified in the HTML spec, and called the adoption agency algorithm. I think we owe it to Chris Wilson for thinking about this in the first place. Chris, if you ever find traces of old discussions about this, or care to write the backstory, I would be very interested!

Of course, I'm not saying you should do this. It's still important to create correctly nested HTML markup. But there are historical reasons for things like this to work. Back in the early days, browser engines didn't always agree on how to parse and render HTML. So, in order to ensure that as much of the web as possible was supported across all browsers, it was sometimes easier to just support how other browsers did things. And that's how things like misnested tags ended up being supported.
Missing end tags are fine. The HTML parser is able to close most of them on its own.

For example, a list item doesn't need to be closed if what follows is another list item or the end of the list. So, this works fine:
```
<ul>
  <li>Item 1
  <li>Item 2
  <li>Item 3
</ul>
```
The same is true for paragraphs. You can omit the closing </p> tag if what follows is another paragraph, a heading, a list, and a whole lot of other elements:
```
<section>
  <p>This is a paragraph
  <p>This is another paragraph
  <h2>This is a heading</h2>
  <p>This is yet another paragraph
</section>
```
You can find out more about these examples, and others, in the Optional tags section of the HTML spec.

Also, think about it, you're probably already using this without realizing it. Have you ever closed a <img>, <input>, or <link> tag? Probably not, and that's fine. The HTML spec defines a whole lot of elements which don't require closing tags: <base>, <link>, <meta>, <hr>, <br>, <source>, <img>, <input>, and others.

XHTML attempted to change this by requiring all tags to be closed, and conforming to XML syntax rules, but that never really caught on. Sure, HTML is weird, but it's also what powers billions of web pages today. There isn't really a reason to try and change te nature of HTML.

So, what's the moral of the story?

HTML can be very forgiving, and browsers implement things that may seem obscure or weird, but they do so for a very good reason: backward compatibility!

The web is the only platform where sites that were written years ago can still work fine today. This isn't to say that things never get removed though, they do, and probably more often than you realize. Remember AppCache, WebSQL, module import assertions, or special rules that apply to the font-size of <h1> elements when nested inside certain elements?

This is both a blessing and a curse. The fact that so much of the languages we use are so forgiving and time-enduring made the web what it is today: a welcoming platform that doesn't take so much effort to get used to, and kind of just works. But, this also means that old features and bad practices can linger on for a long time and, if they're used by many sites and users, can't really ever be removed.

Controlling dialogs and popovers with the Invoker Commands API

2025-12-07T00:00:00Z

by Aubrey Sambor

The Invoker Commands API adds new attributes to the <button> element to control interactive elements on the page such as popovers and modal dialogs without having to write JavaScript. Dialogs have been available in all modern browsers since March 2022, and the Popover API is available in all modern browsers as of January 2025.

Until now, users wanting to implement the <dialog> element needed to write their own JavaScript to power the show and hide functionality using the HTMLDialogElement interface, while the Popover API and Invoker Commands API for popovers work identically by using HTMLElement attributes to show, hide, or toggle the popover.

Why should you use this new API, and what benefits does it bring?

Dialogs vs Popovers

First, let's go over the difference between a dialog and a popover. Hidde de Vries wrote a blog post in 2022 detailing the differences, but in short:

Dialogs usually contain an action to take, such as agreeing to text or choosing an option. Popovers usually display short-lived information such as a date picker or toast notification.
By default, dialog must be explicitly closed, either by taking an action within the dialog or closing via a close button. A popover can be lightly dismissed by clicking outside of the popover.
A dialog can either be modal or non-modal, while a popover is always non-modal by design. As of late 2025 the Invoker Commands API only has a built-in command for a modal dialog, so I will be focusing on modal dialogs only in this post.
Dialogs have a built in backdrop functionality to tint the background a different color, while popovers shouldn't use a backdrop in most cases.
A dialog is an HTML element with a role of dialog, while a popover is considered an attribute and needs a role to be added depending on the popover's context. See Hidde de Vrie's post on popover semantics to learn more about potential roles to add to your popover!

The `command` and `commandfor` attributes

The Invoker Commands API introduces two new attributes to the <button> element—command and commandfor. The commandfor attribute acts as a connector between the <button> controlling the functionality and the element that the command acts upon, while command contains the action that should be taken on the element.

As of late 2025 the following commands are supported within the API, which right now can only be used for <dialog> or <div role="dialog"> elements or on elements with the popover attribute. These commands are:

show-modal: Shows a <dialog> element as a modal. If you're familiar with the underlying API to show a <dialog> as a modal, this is equivalent to the HTMLDialogElement.showModal() method.
close: Closes a <dialog> element. This is equivalent to the HTMLDialogElement.close() method.
request-close: This command works similarly to the close command, but before the <dialog> can be closed, a cancel event is triggered first to cancel the closure of the dialog if required actions do not occur, such as selecting required options within the <dialog>. This is equivalent to the HTMLDialogElement.requestClose() method. This concept is a little tricky, so I'll show an example later in the post.
show-popover: Shows a popover element. This is equivalent to both the popoveraction="show" attribute and the HTMLElement.showPopover() method.
hide-popover: Hides a popover element. This is equivalent to both the popoveraction="hide" attribute and the HTMLElement.hidePopover() method.
toggle-popover: Toggles a popover element; if the popover is hidden, it will be shown, and if the popover is shown, it will be hidden. This is equivalent to both the popoveraction="toggle" attribute and the HTMLElement.togglePopover() method.
Custom values: This is where The Invoker API really shines! A user can provide a custom value, prefixed by two hyphens (--) to create a custom command event. This event is usually written in JavaScript and provided by the user to add new functionality. The possibilities are endless!

Examples

The Invoker Commands API with a `<dialog>` element

This is a basic example of how to use the Invoker Commands API with a <dialog> element. One button fires the show-modal command when it is clicked, and within the <dialog>, another button fires the close command to close the dialog. No JavaScript necessary, it's all built in for you!

<button commandfor="my-fancy-dialog" command="show-modal">Open dialog</button>
<dialog id="my-fancy-dialog">
  <p>Dialog content</p>
  <button commandfor="my-fancy-dialog" command="close">Close dialog</button>
</dialog>

The `request-close` command on a `<dialog>` element

To use the request-close command, a bit of JavaScript is needed. First, use the same code as above, but change the command on the button inside the <dialog> from close to request-close:

<button commandfor="my-fancy-dialog" command="show-modal">Open dialog</button>
<dialog id="my-fancy-dialog">
  <p>Dialog content</p>
  <button commandfor="my-fancy-dialog" command="request-close">Close dialog</button>
</dialog>

Now, since a cancel event is fired on the <dialog> element (as that's the element that can be closed), an event listener needs to be added to capture the cancel event when request-close is called. In this example, an alert displays when the close button is clicked, and then, when the user clicks 'OK', the alert closes and then the dialog closes. This causes the user to have to perform an action before the dialog is closed.

const myFancyDialog = document.getElementById("my-fancy-dialog");

myFancyDialog.addEventListener("cancel", (event) => {
  window.alert(
    "A cancel event gets fired when using the 'request-close' command."
  );
});

Commands for the popover attribute also exist in the Invoker Commands API. The new show-popover, hide-popover, and toggle-popover commands are equivalent to the show, hide, and toggle values on the popovertargetaction attribute in the Popover API. The popover attribute still needs to be added to the popover's container, but the Invoker Commands API handles the rest of the popover's functionality.

<button commandfor="mycommandpopover" command="toggle-popover">Toggle popover</button>
<div id="mycommandpopover" popover>Popover content</div>

The Invoker Commands API with a custom command

This is where the Invoker Commands API gets fun! You can add your own custom commands if the command you wish to run does not exist. Since a mechanism for opening and closing <details> elements does not yet exist as a command, I wrote a custom --toggle-details command to open and close the <details> element when the <button> element is clicked.

<button class="my-fancy-button" commandfor="my-fancy-details" command="--toggle-details">Open details element</button>
<details id="my-fancy-details">
  <summary>This is a details element</summary>
  <p>Here is the text inside the details element, opened by a custom command!</p>
</details>

const detailsElement = document.querySelector("details");

detailsElement.addEventListener("command", (event) => {
  if (event.command === "--toggle-details") {
    detailsElement.open = !detailsElement.open;
  }
});

Looking ahead

The Invoker Commands API is not widely supported across all modern browsers just yet—as of late 2025, the Invoker Commands API is available in Chrome and Edge as of version 135, Opera as of version 120, Firefox as of version 144, and Safari Technology Preview. However, if older browsers need to be supported, you're in luck as there's a polyfill created by the API author.

To learn what's coming next for the Invoker Commands API, the authors have created an explainer document with potential future enhancements to the API, including commands to open, close, or toggle a <details> element, a command to open a native HTML date picker, and commands to play, pause, and mute HTML <audio> and <video> elements. Users can also submit an issue to add other commands that are not yet implemented—go forth and add your ideas!

Accessible by Design: The Role of the 'lang' Attribute

2025-12-06T00:00:00Z

by Todd Libby

When starting a project, whether it is an application, a mobile app or site, or just a website in general I still see an alarming number of examples where the language attribute is not included in the <html> element. Not the !DOCTYPE, but the element directly after the DOCTYPE.

I have audited many sites and many frameworks in the past, I have noticed an alarming omission right from the outset when developers are building sites or applications. Especially in the mobile space and let's face it, in web development we focus on making things for ourselves and if it works on our computer, it must work everywhere! Right?

I see it more prevalent these days. There are surveys out and the issue of accessibility education in university or boot camps still lacks. New developers entering the field who aren't aware, framework authors that just don't know, understand, or they just don'make their work accessible.

I am here to discuss the importance of the language attribute in your code.

The Attribute and the Importance of the Language Used

Sometimes, a tiny detail can make or break the experience for millions of users. One of these tiny, powerful details is the lang attribute in your HTML.

The lang attribute is a simple piece of code that tells web browsers and screen readers what human language your page is written in. For example:

<html lang="en"> means the page is in English.
<html lang="es"> means the page is in Spanish.

When you forget this attribute, you're not just missing a semantic tag—you're creating a major accessibility barrier. If you don't tell the computer what language you're using, assistive tools won't know how to read your content correctly.

There Is Data Here and You Should Read It

The WebAIM Million Report is an accessibility report done by WebAIM every year and it's an accessibility evaluation of the top one million homepages on the internet. 2025 marked the seventh year this has been done and the results are not surprising.

Let's show the data for the language attribute.

For the seventh year in a row, a missing document language made the list.

As with the rest of the items in the data, it has been a common theme the last seven years. Missing language attribute has always been the last item on the repeating list of common failures. So what are the implications?

A numerical look shows the data is still trending to the same six problems in the report. So why is it that these issues are the ones that stay in the top six?

The WebAIM Million Report showing low contrast of text at 79.1% followed by missing alternative text for images at 55.5%, missing form input labels at 48.2%, empty links at 45.4%, empty buttons at 29.6%, and finally missing language attribute at 15.8%.

What Happens When the Language is Missing? The Wrong Voice Problem

The main group affected by a missing lang tag is the screen reader user. Screen readers are essential tools that read web content aloud. They're mainly used by people who are blind, have low vision or for those that use text-to-speech. They are also used by people that find reading difficult for other reasons, this is a common practice with people with ADHD (Adult attention-Deficit/Hyperactivity Disorder).

Screen readers don't just use one voice; they use specialized software packages for each language. This software knows the pronunciation rules, rhythm, and stress for English, French, Japanese, etc.

When your page is missing the lang attribute, the screen reader has to guess the language. It usually guesses based on the user's computer settings (for example, if the user lives in Germany, the screen reader will try to use the German voice).

Example: English Text Read by a German Voice

Imagine your entire website is in clear English. If a German screen reader tries to read it, it will apply German pronunciation rules.

“The” might sound like “Tee-hay.”

or;

“Data” might be pronounced with a hard ‘A’ sound instead of a soft one.

The result is garbled, unnatural, and often unintelligible speech. The text is still on the page, but for the screen reader user, the content is lost. They cannot understand your article, buy your product, or use your service.

This single small mistake transforms your helpful website into a frustrating, unusable experience.

It's a Rule, Not a Suggestion (WCAG)

Using the lang attribute isn't just a friendly suggestion; it's a core requirement for making your website accessible.

The Web Content Accessibility Guidelines (WCAG) are the international standard for web accessibility. WCAG Success Criterion 3.1.1 (Language of Page) states that the language of the page must be clear to the computer. This is a level ‘A’ requirement, which means it's mandatory for basic accessibility.

If your website fails this check, it is officially considered inaccessible.

How It Affects Other Tools

The lang attribute helps more than just screen readers:

1. Braille Displays

A refreshable braille display translates text into small patterns of raised bumps. Different languages use different contraction rules in braille (called Grade 2 braille). If the language is not set, the braille translator might use the wrong rules, turning clear text into meaningless gibberish for the braille reader.

2. Automated Translation

When a user relies on tools like Google Translate or a browser's built-in translation feature, telling the tool the source language (the language you wrote it in) ensures a much more accurate translation. If the source language is unclear, the translation quality drops sharply. An example can be found here.

3. Quotation Marks

The lang attribute helps the browser and other user agents select the correct typographical glyphs for quotation marks, especially when it comes to when the <q> and <blockquote> elements are used (when styled using CSS generated content such as content: open-quote). For example:

In English lang="en", quotes are typically “double quotes”.
In German lang="de", they are often rendered as „low-9 quotes‟.
In French lang="fr", they use « guillemets ».

While less related to visual quotation marks, providing the correct language helps assistive technologies pronounce the surrounding text accurately, ensuring a fluid and comprehensible reading experience.

Not providing the correct language may cause browsers to default to the user's system language or a neutral setting for quotation marks which may not match the document's language which results in incorrect or confusing typography (e.g., using English quote marks for German language).

Without a declared language, a screen reader may attempt to read the text using incorrect phonetic rules, voice, and accent. Which makes the content sound like gibberish and can make it incomprehensible for users who rely on audio output.

4. Hyphenation

Proper hyphenation is entirely language-dependent. Hyphenation rules can be complex and unique to each language. when CSS is used, hyphens: auto, the browser or user agent relies on the lang attribute to load the appropriate hyphenation dictionary and apply correct linguistic rules which can improve text flow and readability. Especially in justified or narrow columns.

For example, a long compound word in German, lang="de", will be broken according to German rules such as Rechtsschutzversicherungsgesellschaften (which means, insurance companies providing legal protection).

Most browsers do not provide automatic hyphenation if the language is not declared. This can not only lead to unsightly text blocks with excessive white space between words, but also horizontal scrolling or overflow on mobile devices which severely impacts readability and layout stability.

If the browser attempts to guess the language or uses the wrong default, it could apply the incorrect hyphenation rules, which breaks words in places that are linguistically wrong, which, in turn, confuses the reader.

What About Pages with Two Languages?

What if your page is mostly English but includes a quote in Spanish? If you don't do anything, the screen reader will read the Spanish quote using the English voice, again leading to mispronunciation.

You can fix this instantly by adding the lang attribute to the specific element that changes language:

<p lang="en">
    The artist once said, "Always remember this phrase:
    <span lang="fr">Je ne regrette rien.</span>" I think that sums up his career.
</p>

In this code, the screen reader switches to the French voice for the quote and then immediately switches back to the English voice for the rest of the sentence. This small change ensures all users hear the content exactly as intended.

How to Set the Language in Modern Web Frameworks

In modern websites built with tools like React, Vue, or Angular, you usually don't touch the main HTML file very often. Since these tools mostly control the content inside the <body> tag, you have to know where to find the root template file to set the lang attribute correctly. for example,

React uses the file, public/index.html. Therefore you would directly place the attribute in the <html> tag in that file.

Here's a simple guide for the most popular frameworks:

Framework	What File to Edit	Where to Put the Code
React	public/index.html	Directly on the `<html>` tag in that file.
Next.js	app/layout.tsx (or similar root file)	Set the lang in the JSX for the root `<html>` element.
Vue	public/index.html	Directly on the `<html>` tag in that file.
Nuxt	nuxt.config.ts	Inside the app.head.htmlAttrs setting in your config file.
Angular	src/index.html	Directly on the `<html>` tag in that file.
Svelte/SvelteKit	index.html or src/app.html	Directly on the `<html>` tag in the main template file.

Example: Setting the Language in a Static Template

For most simple apps (React, Angular, plain HTML), you will open your main index.html file and change the first line like this:

<!DOCTYPE html>
<!-- Change the line below from <html> to the correct language code -->
<html lang="en">
<head>
    <!-- ... -->
</head>
<body>
    <!-- Your app code loads here -->
</body>
</html>

Conclusion

The lang attribute is a tiny line of code that provides universal access to your content. It's arguably the easiest, fastest, and most impactful accessibility fix you can make on any website.

By correctly setting the language, you ensure that everyone has equal access to your content. Regardless of whether they use a screen reader, braille display, or translation tool to do so, their tools have the fundamental information they need to do their jobs correctly. It's a simple commitment that makes the web better for everyone.

Don't let a missing two-letter code turn your content into a foreign language for your users and don't be afraid to use it or add it in!

IDREFs: What they are and how to use them

2025-12-05T00:00:00Z

by Kilian Valkhof

Take the following HTML for example:

<label>
  Email address
  <input type="email" />
</label>

Here, the <label> element is associated with the <input> element because the input is nested inside of the label, and the browser now knows to offer additional behavior: when the user clicks on the label, the input will be focused. That's not behavior that you had to specify with an onclick handler, the browser just infers it from the relationship between the elements.

But what if it can't infer the relationship? While your Firefox, Chrome or Polypane browser can all figure this out, some assistive technologies can't. Both Dragon Naturally Speaking and VoiceOver on macOS have trouble associating labels with inputs when they are nested, according to a11ysupport tests. So while clicking the label will focus the input, giving the voice command "Focus Email address" might not work. That said, support might have improved since the tests were last conducted: My editor Zoë tested this in Safari 26.0.1 on macOS 15.7.1 where it now works. Make sure to test before relying on this behavior!

Additionally, this association only works when the input is nested inside the label. If you wanted to have the label and input be siblings, for example for styling purposes, then that implicit association is lost.

To solve this, we can use the IDREF you probably already know, the for attribute on the <label> element:

<label for="email-input"> Email address </label>
<input type="email" id="email-input" />

Now we're explicitly associating the label with the input, by referencing the input's id from the label's for attribute. That's all an IDREF really is: a reference to another element's id.

Note, there's also nothing keeping you from using the for attribute and nesting both at the same time:

<label for="email-input">
  Email address
  <input type="email" id="email-input" />
</label>

Now you know what an IDREF is! In HTML there are many other places where you can use IDREFs to create explicit relationships between elements, many of which are ARIA attributes that help with accessibility and with describing more complex relationships than HTML can express. We'll get to those in a bit, because there's more to be said about IDREFs themselves.

IDs need to be unique

In a well-structured HTML document, each id is only used once. This is important for IDREFs to work properly, since the browser or assistive technology needs to be able to find the single right element when following an IDREF. If there are multiple elements with the same id, this can lead to unexpected behavior.

Making sure IDs are unique can be tricky: you might have multiple forms on a page that reuse the same naming, or another repeated structure that requires ARIA attributes. When that happens, consider a programmatic way to generate unique IDs, for example by prefixing them with the component name.

IDs need to exist

This might seem obvious, but the majority of issues that occur around IDREFs is that the referenced ID simply doesn't exist in the document. This can happen when you make a typo in the id or IDREF, or when you remove an element but forget to update the references to it.

Linters and validators can help catch these issues, as can browser developer tools that highlight broken references. In Polypane, for example, broken IDREFs are highlighted in the Element panel, making it easy to spot and fix them.

In other browsers you can check for missing IDs using this little console snippet that gathers all for attributes on labels and checks if the referenced ID exists:

document.querySelectorAll("[for]").forEach((label) => {
  const id = label.getAttribute("for");
  if (!document.getElementById(id)) {
    console.error(
      `Label with for="${id}" has no matching element with that ID.`,
      label
    );
  }
});

Other HTML IDREF attributes

HTML has quite a few attributes that use IDREFs to create relationships between elements, including some very new ones.

The `for` attribute on `<label>` elements

As we've seen above.

A neat trick that for has: you can link as many labels as you want to a single input:

<label for="email-input"> Email address </label>
<input type="email" id="email-input" />
<label for="email-input"> required </label>

These will all focus the same input, and their combinined text will be used as the accessible name for the input: Email address required. Of course, that's the theory. In practice, support for inputs with multiple labels is inconsistent. Some assistive technologies will use all labels but some only use the first or the last one (see this research done by Deque). So while it's valid HTML, you're better off sticking to a single label per input for now.

The `form` attribute on form-associated elements

You can add a form attribute to form-associated elements like <input>, <button>, <select>, <fieldset> and <textarea> to associate them with a specific <form> element on your page, even if they are not nested inside that form:

<form id="signup-form">...</form>

<button form="signup-form">Sign up</button>

Something to keep in mind is that the form atttribute only works for the current element, not its children. If you have a <fieldset> with a form attribute, the inputs inside it will not be associated with the form unless they also have a form attribute.

Another thing to keep in mind is that you can remove an element from a form by giving it a form attribute that points to a different form, or to no form at all (by giving it an empty string). Here's an example from MDN:

<form id="externalForm"></form>
<form id="internalForm">
  <label for="username">Username:</label>
  <input form="externalForm" type="text" name="username" id="username" />
</form>

Even though the label will focus that input, the input will be submitted with externalForm and not for internalForm.

Like the advice for labels, keeping form-associated elements inside their forms is generally easier to manage. The above might be useful design-wise when you have a wizard across multiple steps that each have their own form, but you want a submit button that's always visible across the steps.

The `list` attribute on `<input>` elements

If you have an <input> element, you can use the list attribute to associate it with a <datalist> element that contains predefined options for that input to have it show a dropdown and autocomplete with those options:

<input list="browsers" name="browser-choice" id="browser-choice" />
<datalist id="browsers">
  <option value="Chrome"></option>
  <option value="Firefox"></option>
  <option value="Safari"></option>
  <option value="Polypane"></option>
</datalist>

This works on desktop browsers, but you should not depend on it: mobile browsers often don't show the datalist options at all, and assistive technologies may not announce them either. So while it's a nice enhancement, make sure your form works well without it too.

The `headers` attribute on `<td>` and `<th>` elements

When you have complex tables where header cells might have subheaders, you can use the headers attribute on data cells (<td>) and header cells (<th>) to explicitly associate them with the relevant header cells:

<table>
  <tr>
    <th id="name" colspan="2">Name</th>
  </tr>
  <tr>
    <th id="first">First</th>
    <th id="last">Last</th>
  </tr>
  <tr>
    <td headers="first name">Kilian</td>
    <td headers="last name">Valkhof</td>
  </tr>
</table>

And here we also introduce the concept of multiple IDREFs in a single attribute. Some IDREF attributes can reference multiple IDs by separating them with spaces. In this case, the first data cell is associated with both the "First" and "Name" headers. When browsers now announce the cell, they can include the text of both headers in the announcement.

New HTML `IDREF` attributes: `popovertarget`, `commandfor`, `anchor` and `interestfor`

HTML is in the process of getting several new functionalities that make it easier to create declarative interactive components like popups and tooltips. To help with those, new IDREF attributes are being added.

popovertarget can be added to a button to associate it with a popup element that has the popover attribute. That way the popover is shown when the button is activated. For a more in-depth explanation, check out PSA: Stop using the title attribute as tooltip! from last year's advent calendar.

The default action for popovertarget is to toggle the popover when the button is activated, but you can use the popovertargetaction attribute to change that behavior. The default value is toggle, but you can also set it to show or hide to always show or hide the popover when the button is activated.

<button popovertarget="my-popover" popovertargetaction="show">
  Show popover
</button>

<div id="my-popover" popover>
  This is a popover!
  <button popovertarget="my-popover" popovertargetaction="hide">Close</button>
</div>

commandfor does the same as popovertarget, but can also be used to open and close <dialog> elements declaratively with show-modal and close as command values.

<button commandfor="my-dialog" command="show-modal">Open dialog</button>

<dialog id="my-dialog">
  This is a dialog!
  <button commandfor="my-dialog" command="close">Close</button>
</dialog>

Lastly, interestfor is similar to commandfor, but is used when a user "expresses interest" in an element, for example by hovering over it or focusing it. The use case here is to show tooltips or hint popovers when the user hovers or focuses an element.

<button interestfor="my-tooltip">I'm a button!</button>

<div id="my-tooltip" popover="hint">The button does nothing.</div>

For more on interestfor, check out the OpenUI explainer on interest invokers.

popovertarget works in all browsers, while commandfor is still lacking support in Safari. interestfor is still very new and only supported in Chromium 142 and newer.

To learn more about these, keep an eye on upcoming articles in this advent calendar!

Lastly, the anchor attribute will let you declaratively specify which element a popover or tooltip should be anchored to. Currently this is something you have to specify with CSS, but it can be much easier to reference an ID instead. Unfortunately it's not supported yet.

ARIA IDREF attributes

All of which brings us to ARIA. ARIA is a set of attributes designed to add semantics, relationships and behaviors to HTML where the native elements and attributes fall short. They're not the first thing you should reach for, but there are many things where HTML alone can't express what you need.

Many ARIA attributes are IDREF attributes that allow you to create explicit relationships between elements.

Descriptive relationships

A common use case for ARIA is to make sure that elements have an accessible name and/or description. Often you'll see this done with aria-label:

<button aria-label="Move to trash">
  <span aria-hidden="true" class="icon">🗑</span>
</button>

This works, but aria-label comes with some downsides. For example, it's easy to miss: a common issue accessibility auditors find is that a button's HTML is copied for another purpose, but the original aria-label is not updated to reflect the new purpose. Browsers also have issues with automatic translations of aria-labels, since they are not part of the visible text on the page.

<button aria-label="Move to trash">
  <!-- oops! -->
  <span aria-hidden="true">🔃 Revert</span>
</button>

It is often better to use aria-labelledby to give an element its accessible name. aria-labelledby gives elements an accessible name by referencing other elements that contain the relevant text. Indeed, aria-labelledby can reference multiple IDs, allowing you to combine text from different elements into a single accessible name:

<div class="photo">
  <button aria-labelledby="trash-label photo-label">
    <span aria-hidden="true" class="icon">🗑</span>
    <span id="trash-label" class="visually-hidden">Delete</span>
  </button>
  <span id="photo-label">IMG_0512.jpg</span>
  <img src="IMG_0512.jpg" alt="Sydney Opera House at sunset" />
</div>

The above button's accessible name will be "Delete IMG_0512.jpg", combining the text from both referenced elements and making it clear that the button deletes, and which photo it deletes.

Sometimes elements might have an accessible name, but you still want to have an additional description to give more info. Visually that is easy to do, think of the word "required" below an <input> element. That association is not always clear to assistive technologies. To make that association explicit, you can use aria-describedby and reference IDs of elements that contains the description.

Again, MDN gives us a nice example:

<button aria-describedby="trash-desc">Move to trash</button>
<p id="trash-desc">
  Items in the trash will be permanently removed after 30 days.
</p>

The button's accessible name "Move to trash" is understandable on its own, but the description provides additional context about what happens when you move something to the trash.

Complex relationships

ARIA also has many attributes that help express more complex relationships between elements: aria-controls, aria-owns, aria-activedescendant and aria-flowto.

aria-controls is used to indicate that an element controls another element, for example a button that shows or hides a section of content. This can help assistive technologies understand the relationship between the button and the content it controls:

<button aria-controls="submenu" aria-expaned="false">Open menu</button>
<nav id="submenu" hidden>...</nav>

Here, the button is indicating that it controls the visibility of the nav element with the ID submenu. You can then combine this with aria-expanded on the button to indicate whether the submenu is currently visible or hidden.

To account for even more complex structures, aria-controls can also reference multiple IDs, allowing a single control to manage several elements at once.

aria-activedescendant is used to indicate which element within a composite widget is currently active. An example of a composite widget is a combobox: a UI component that combines a text input with a list of options: You can type in the text input to filter the options, fill in freeform content or use the arrow keys to navigate the options. For a reference implementation look at the combobox in the WAI-ARIA Authoring Practices. Getting a combobox right is tricky, so make sure to read that guide if you're building one!

You can use aria-activedescendant (in combination with aria-controls) on the input to indicate which option in the listbox is currently selected:

<input
  type="text"
  role="combobox"
  aria-autocomplete="list"
  aria-haspopup="listbox"
  aria-expanded="false"
  aria-controls="options-list"

  aria-activedescendant="option-2"
/>
<ul id="options-list" role="listbox" aria-label="options">
  <li id="option-1" role="option">Option 1</li>
  <li id="option-2" role="option">Option 2</li>
  <li id="option-3" role="option">Option 3</li>
</ul>

aria-owns is used to create a parent-child relationship between elements that are not nested in the DOM. When for some reason your DOM can't be structured in a way that makes sense visually or semantically (for example, you need to use a "portal" in some Javascript frameworks),aria-owns will let you "rewrite" the accessibility tree as if the elements were nested. Any elements that are inside the element are listed first, and then the elements you refernece in aria-owns are added as children after that.

Keep in mind that when you use aria-owns, all the regular rules about HTML still apply: You can't nest an interactive element inside another interactive element, and some elements can only have specific types of children. Because of this, giving a specific example for aria-owns will always feel a little contrived. I'm going to try anyway.

Here's how you would structure a combobox where the list of options needs to be elsewhere in the DOM, for example to break out of a container with overflow:hidden:

<label for="combobox-input">Choose an option:</label>
<div aria-owns="floating-list">
  <input
    id="combobox-input"
    type="text"
    role="combobox"
    aria-autocomplete="list"
    aria-haspopup="listbox"
    aria-expanded="false"
    aria-controls="floating-list"
    aria-activedescendant=""
  />
</div>

<!-- elsewhere in the dom to avoid stacking context clipping -->
<ul id="floating-list" role="listbox" aria-label="options">
  <li role="option" id="option-1">Option 1</li>
  <li role="option" id="option-2">Option 2</li>
  <li role="option" id="option-3">Option 3</li>
</ul>

Note that we use both aria-controls and aria-owns here. aria-controls indicates that the div controls the listbox, while aria-owns indicates that the listbox should be a child of the div in the accessibility tree. aria-owns describes a structural relationship, while aria-controls describes a functional relationship.

aria-owns on its own doesn't change the browser's default behavior, where the tab order follows the DOM structure. Assistive technologies can instead use the aria-flowto relationships to offer the user a way to navigate content in the suggested order.

In other words, aria-flowto is used to indicate a logical reading order between elements that doesn't follow the visual ordering of elements. That can happen when they're in different places in the DOM, or when you've changed the visual order with the order CSS property, or by absolute positioning elements. Using aria-flowto can help assistive technologies navigate the content in a way that makes sense.

aria-flowto can also reference multiple IDs. In that case, the assistive technology can give the user a choice of which element to navigate to next.

As with all things ARIA, aria-flowto is a last resort: it's better to structure your HTML in a way that follows a logical reading order without needing to override it with ARIA. This is doubly true for aria-flowto because support in browsers and assistive technologies is limited: only the JAWS screen reader supports it at the moment.

Do you need ARIA IDREFs?

As you can see from the descriptions above, the ARIA attributes get increasingly more esoteric and complex. Things like aria-labelledby and aria-controls can be useful in many situations, but others like aria-owns and aria-flowto are only needed for specific use cases. When you think you need ARIA it's often better to take a step back and consider if you can achieve your goal with native HTML elements and attributes.

It's also important to note that none of these ARIA attributes bring any behavior on their own: they only describe relationships. This can help assistive technologies understand the structure of your page, but you'll still have to implement the actual behavior. For example, <button aria-expanded="false" aria-controls="my-menu"> will not automatically show and hide that menu element or move the focus into it. You have to implement the show/hide behavior and focus management. The ARIA attributes just tell the browser that this button controls that menu and whether it's expanded or not.

IDREFs and how to use them

IDREFs let you create explicit relationships between elements in your HTML where they otherwise might not exist. Some of them give you additional behaviors, like how the for attribute on a label makes clicking the label focus the input, or how the list attribute on an input shows a dropdown of options from a datalist.

Other IDREF attributes, especially in ARIA, are used to describe relationships that help assistive technologies understand the structure and purpose of your content better. If you also want those to show certain behaviors, it's your job to implement those.

Whenever you use IDREFs, make sure that the referenced IDs exists, and that you test their usage with the browsers and assistive technologies your users use.

Referencing HTML elements inside Shadow DOM

2025-12-04T00:00:00Z

by mehm8128

Web Components is the web standard way for creating reusable components like React or Vue components.

While Web Components have matured significantly, it still has some missing pieces to make accessible components easily using Shadow DOM.
Today I'll introduce one of these difficulties and the proposed solution to resolve it. Part of this solution is already available in Chrome Canary.

Problems with referencing HTML elements inside the Shadow DOM

First, let's consider a case where we create a checkbox component using custom elements and Declarative Shadow DOM.
In this example, we want to reference the internal <input> element by referencing id="checkbox" on <fancy-checkbox>. Elements inside the Shadow DOM are encapsulated, that's why we cannot reference the input field directly.

<script>
  customElements.define(
    "fancy-checkbox",
    class FancyCheckbox extends HTMLElement {}
  );
</script>

<div>
  <label for="checkbox">I agree with the terms and conditions</label>
  <fancy-checkbox id="checkbox">
    <template shadowrootmode="open">
      <input type="checkbox" id="inner-checkbox" />
    </template>
  </fancy-checkbox>
</div>

The problem with this approach is that the <input type="checkbox"> is failing to be associated with the <label>:

Clicking the label doesn't focus on the checkbox.
The checkbox doesn't have an accessible name.

This is the missing piece that this article addresses. It is not easy to make Web Components fully accessible using Shadow DOM.

I'll introduce the proposed solutions to address these problems.

Solutions

The proposal divides the work into two phases to simplify the problems.
Phase 1 only deals with targeting a single element in Shadow DOM.
Phase 2 addresses targeting multiple elements.

For the initial release, only Phase 1 will be shipped.

Phase 1

Let's consider an "enclosing element" concept. An "enclosing element" wraps another element and extends it with extra features and HTML elements.
For example, when we create a <fancy-checkbox> component using the Shadow DOM, this becomes the "enclosing element" for <input type="checkbox">. This allows us to encapsulate and make reusable components with custom styling and additional functionality.

To enable referencing the <input type="checkbox"> element inside the Shadow DOM from <label>, Phase 1 introduces the shadowRootReferenceTarget attribute. This attribute specifies which element should be referenced as the target of <label for="checkbox">.

<div>
  <label for="checkbox">I agree with the terms and conditions</label>
  <fancy-checkbox id="checkbox">
    <template shadowrootmode="open" shadowRootReferenceTarget="inner-checkbox">
      <input type="checkbox" id="inner-checkbox" />
    </template>
  </fancy-checkbox>
</div>

Now, when <label for="checkbox"> tries to reference <fancy-checkbox id="checkbox">, it automatically references <input id="inner-checkbox" because shadowRootReferenceTarget attribute designates its mapping. Finally, the label can reference the checkbox and provide the accessible name "I agree with the terms and conditions" for it. Users can also focus on it by clicking <label for="checkbox">.

This also enables the use of ARIA attributes, as shown in the following example using aria-labelledby. The same applies to popovertarget, commandfor, and interestfor.
What attributes are in scope is not completely decided. Whether aria-owns should be included will be discussed and all other IDREF attributes are likely to be in scope.

<div>
  <input type="text" aria-labelledby="label" />
  <fancy-label id="label">
    <template shadowrootmode="open" shadowRootReferenceTarget="inner-label">
      <label id="inner-label">Type your name.</label>
    </template>
  </fancy-label>
</div>

Phase 1 is available in Chrome Canary with the "Experimental Web Platform features" flag enabled.

Mozilla set their position to "positive" in September, and this feature is proposed as part of Interop 2026. I hope this will become available across all major browsers.

Let's take a look at Phase 2 for multiple elements reference support.

Phase 2

Phase 2 enables referencing multiple elements or other complicated references.
As one of the solution for phase 2, I introduce shadowRootReferenceTargetMap attribute, but other solutions are discussed so it's unclear what solution will be adopted for complicated reference.

Let's consider creating a combobox using aria-controls and aria-activedescendant.

<input
  role="combobox"
  type="text"
  aria-controls="animals"
  aria-activedescendant="animals"
/>
<animals-listbox id="animals">
  <template
    shadowrootmode="open"
    shadowRootReferenceTargetMap="aria-controls: listbox,
                                  aria-activedescendant: opt1"
  >
    <div role="listbox" id="listbox">
      <div role="option" id="opt1">Otter</div>
      <div role="option" id="opt2">Opossum</div>
      <div role="option" id="opt3">Ocelot</div>
    </div>
  </template>
</animals-listbox>

The first part of the value of the shadowRootReferenceTargetMap attribute, aria-controls: listbox, means when aria-controls references <animals-listbox> with the id animals, it should reference an element inside the Shadow DOM with the id listbox. That's <div role="listbox" id="listbox"> here. aria-activedescendant: opt1 works the same way.

This provides the flexibility to reference HTML elements inside the Shadow DOM, but some concerns are under discussion.

Please check out these issues if you're interested in learning more.

Conclusion

Reference Target for Cross-root ARIA enables us to reference HTML elements inside the Shadow DOM. This makes developing accessible Web Components easier, especially for UI component libraries and design systems. OpenUI is working on The OpenUI Design System, and this feature will be valuable for that project.

I recommend trying this feature in Chrome Canary and providing feedback to the Web Components CG.

Speculation rules improvements

2025-12-03T00:00:00Z

by Barry Pollard

The Speculation Rules API allows you to speed up future navigations by prefetching or even prerendering URLs in advance of a user actually clicking a link. When the link is clicked, the speculation is used, and the user experiences a faster load than if no speculation was used.

Schepp covered the API in last year's post and discussed the eagerness value which allowed you to, for example, hover over a link to speculatively prerender it with the simple addition of this rule to your HTML:

<script type="speculationrules">
{
  "prerender": [{
    "where": { "href_matches": "/*" },
    "eagerness": "moderate"
  }]
}
</script>

This hover technique is a common functionality offered by libraries, plugins, and frameworks, but now this is baked right into the browser. Chromium-based browsers only for now, but it is being worked on by Safari and Firefox, and as a progressive enhancement, nothing is broken on non-supporting browsers — they just don't benefit from the performance improvement.

Using mouse hover as a signal works well on desktop, but what about mobile, where "hover" is not really a thing? At least in browser terms — I'm sure many of us have hovered over a link with our fingers, but as that is not detected by the browser as an event, we can't act upon it.

Well, solving that is just one of many improvements the API has seen in the last year that we'll cover in this post.

Improved mobile viewport heuristics

Since hover does not exist, we have updated the eagerness: moderate on mobile to instead look at the following heuristics:

Anchor links within 30% vertical distance from the previous pointer down.
Anchor links at least 0.5× as big as the largest anchor in the viewport.
The browser waits 500 milliseconds after the user stopped scrolling.

The aim is to avoid, as much as possible, over-speculating links that users are less likely to click. For example, because they are still scrolling, or they are very small links (terms and conditions and the like!).

You can see this in action in the following video where the Web Almanac prerenders same-origin links with moderate eagerness:

An example of scrolling down a mobile page triggering speculations.

In the video, you can see that as you scroll down the page, links are being successfully prerendered, ready for the user to browse to the page.

Note: Speculating has a cost. To both your users and for sites with potential increased traffic and resulting infrastructure usage. Always weigh those costs against the benefit to the user. Additionally, the are risks for more complex sites for speculating. See the Guide to implementing speculation rules for more complex sites for more information.

To conserve memory, Chrome keeps up to two speculations in memory at a time. As the user scrolls further and new links — which are more likely to be clicked on — enter the viewport, the old prerenders are cancelled. These links can be re-speculated, for example, when the user scrolls back up, in which case they can be fetched from the HTTP cache. That way, they prerender even faster.

`eager` eagerness improvements

The eager value has also been changed. It now offers an option somewhere between immediate, where links are speculated as soon as possible, and moderate.

On desktop, moderate rules trigger after a 10 millisecond hover. On mobile, we consider all links in the viewport after the user has stopped scrolling for 100 milliseconds, rather than the more restrictive set of heuristics above.

One common technique is to prefetch the HTML document with eager value as that is often relatively cheap. Then upgrade this prefetch to a full prerender on moderate when you have more signals that the users may click on the link, and so think it's worthwhile to speculatively start to render the page in full, as prerender has more costs including downloading subresources and using memory and CPU needed to render the page.

<script type="speculationrules">
{
  "prefetch": [{
    "where": { "href_matches": "/*" },
    "eagerness": "eager"
  }],
  "prerender": [{
    "where": { "href_matches": "/*" },
    "eagerness": "moderate"
  }]
}
</script>

In addition you can also restrict the links considered for speculating using the where object.

Further improvements to the API

I'll close out with a sneak peek into the future, as one further improvement being worked on is a middle ground between the prefetch and prerender. This is useful for those sites concerned with any unintended consequences with fully prerendering a page.

Executing JavaScript may trigger analytics, change state, or cause other changes that should not happen until the page is actually viewed. While it is possible to make JavaScript prerender-aware, or holdback scripts until the page is navigated to, this can involve a lot of efforts, particularly for large sites with lots of dependencies managed by many teams.

To help with this, a new Prender Until Script option is currently available behind a flag in Chrome (chrome://flags/#prerender-until-script). As its name suggests, it will start prerendering a page, but pause when it encounters a synchronous <script> element. Scripts with the async or defer attribute (or module scripts which are defer by default) will be downloaded but not executed until the page is navigated to.

This means:

Pages without any JavaScript can be fully prerendered.
Pages with only async/deferred JavaScript can be fully prerendered, with JavaScript executed on navigation.
Pages with only sync <script> JavaScript can start prerender, but pause before any <script> causes any intended consequences. They will continue to download subresources (thanks to the preload scanner), so they still have a significant performance benefit over prefetch.

After enabling the flag, you can use this new mode in exactly the same way as prefetch and prerender:

<script type="speculationrules">
{
  "prerender_until_script": [{
    "where": { "href_matches": "/*" },
    "eagerness": "moderate"
  }]
}
</script>

This enhancement should be released next year. In the meantime, have a play and let me know how you get on!

Conclusion

The Speculation Rules API continues to improve with new options and features to help site owners deliver fast, HTML-driven websites!

We've even added speculation rules to this site. As a light, static, HTML-driven site, it's the perfect type of site for this API. It was already a very fast site, but the addition of this API should make it even faster, especially on slower networks.

Finally, with our first signs of cross-browser adoption of the API, I'd speculate (boom! boom!) 2026 will be another bumper year for the API and for users of sites that implement it.

Using the Ancient Evils for Debugging

2025-12-02T00:00:00Z

by Manuel Strehl

Deep down in the dark voids of HTML specs long gone sleeps a terrifying thing. Imagine, if you will, a DOM node so mighty, that it can change the content-type of parts of the document. An HTML element that makes the parser tremble and withdraw, and that cannot be stopped even by its own end tag.

The wise people of W3C try to keep the knowledge of this terror away from the mere mortals’ eyes to spare us the danger of its madness. They advise us not to use the magic tag name that is the incantation for this ancient malice.

We will, of course, do exactly this today. We’ll take a deep look at the

<plaintext>

element and what fun things we can use it for.

A Quick Warning

This being said, I’d like to point out one important thing: Do not use this element in production. The HTML living standard is quite clear about this:

Elements in the following list are entirely obsolete, and must not be used by authors: [...] plaintext

So, what does <plaintext> do that earned it its place on HTML’s list of deprecated elements? In a nutshell, it ends the HTML parser and instructs the browser to interpret everything following as plain text.

That is to be taken literally. Really everything, including any closing </plaintext> or </html>, will be printed as if a rogue, unclosed <pre> would suddenly go haywire and slurp up the rest of the page. By the way, this makes <plaintext> the only non-empty element that has no end tag at all.

What Do We Use this Power For?

On first sight that sounds like a really stupid superpower. On second sight, it still does. We look into how that element became part of HTML below. But now we will use it for one specific purpose: debugging server-side code.

Of course, specialized debuggers like XDebug for PHP or built-in error pages in frameworks like Django take over the heavy lifting here. And even the good ol’ print "<script>console.log('here!')</script>" is often helpful. Those tools should be high up in your utility belt.

But imagine this: You are deep in your code, chasing an elusive bug that affects only part of the HTML output, and you want to spot on the rendered page exactly where it shows up. The fastest way is to put a quick <plaintext> close to the offending place, reload the page, and presto! Just scan down to where the markup starts to show through.

This is especially useful to access formatted debugging output. A var_dump() in PHP, for example. Or an error.stack stack trace in NodeJS. Slap a <plaintext> in front of it before writing it to the HTML output, so that the string is immediately readable:

<?php
# TODO delme!
echo '<plaintext>'; var_dump($strange_variable);

If you’re working on an expressJS application, it could look like this:

try {
    some_method();
} catch (error) {
    response.send(`<plaintext>${error.stack}`);
}

The History behind this Evil

How ended this seemingly fringe feature up in all mainstream browsers? It was indeed there from the very beginning of HTML as this historic W3C document from 1992 proves:

Plaintext

This tag indicates that all following text is to be taken litterally [!], up to the end of the file. Plain text is designed to be represented in the same way as example XMP text, with fixed width character and significant line breaks. Format:
<PLAINTEXT>

This tag allows the rest of a file to be read efficiently without parsing. Its presence is an optimisation. There is no closing tag.

This also tells us the reason for its invention. Back at the time Sir Tim Berners-Lee’s high-end NeXT PC that he used to write the first web browser had a quarter of the power of a hand-me-down 2009 smartphone. It was important to optimize wherever you could.

Given that the early WWW was meant as a place to share scientific information, having a large blob of plain text as part of your fancy new HTML page was relatively common. The possibility to end the costly HTML parser and fall back to simply printing the remainder of the file as plain text was a powerful tool.

Screenshot: This is a rendering of a 1992 example for the use of the <plaintext> element by an emulation of the very first web browser at CERN. (I had to trick it a bit, though, because the file that the emulator would try to access returned a 404 error.)

Such a feature isn’t unique to HTML, either. For example, the programming language Perl uses a special marker to tell the Perl parser to stop processing the remainder of the file:

print 'this is Perl code';
__END__
cout << 'this isn’t anymore';

(Perl programmers use this not for performance reasons but to embed additional data into their programs.)

Of course, nowadays, in the face of multi-megabyte JS payloads, this optimization has become completely unnecessary.

How Safe Are We?

But the element is still looming in all browsers, so it's worth keeping a bit of a working knowledge of it at the back of our minds.

To give you an example of how this feature could be mis-used, assume a comment function on a blog, where the commenter was able to smuggle in the string <plaintext>. As good developers we know never to trust users’ input, so we put the comment through a sanitizer. Let’s take a look at where things can go south from here.

We use the test string

<p><b>hello<plaintext>world!</plaintext></b></p>

to check how several sanitizer libraries react to it.

There Goes the Sanity!

We run each sanitizer in the most minimal configuration that produces any output. This is by design: sanitizers are security products. They should produce safe output by default.

The results are quite surprising, though. (Click on a library’s name below to reveal the horrifying details.) You will notice that no two libraries (apart from the Sanitizer API and DOMPurify, where the former was directly inspired by the latter) agree on how to sanitize our test string.

The new HTML Sanitizer API as implemented in Firefox

developer.mozilla.org/en-US/docs/Web/API/Document/parseHTML_static

Code:

console.log(Document.parseHTML(TEST_STRING).body.innerHTML);

The approach of this API is to somehow get the nesting correct again according to the HTML5 parser spec. That is, close the <p> and <b> tags, then re-open the <b> tag as the spec suggests. The API does not deal with the special semantics of <plaintext> at all, though.

Result:

We end up with a string that has the <plaintext> element and its content stripped away:

<p><b>hello</b></p>

Poor man’s DOM sanitizing

Code:

const div = document.createElement('div');
div.innerHTML = TEST_STRING;
console.log(div.innerHTML);

For this test we set the test string via HTMLElement.innerHTML = test_string and read it again via .innerHTML. Chrome and Firefox show the same result. This does not really sanitize anything. But we include it in the list, because it demonstrates what the JS engine will do to the test string when interpreting it as HTML.

Result:

The result is a mangled version of the original, which will have double-encoded content in the still retained <plaintext> element.

<p><b>hello</b></p><plaintext><b>world!&lt;/plaintext&gt;&lt;/b&gt;&lt;/p&gt;</b></plaintext>

NB: We can trick the Sanitizer API into producing this output, too, if we’re careless with its configuration:

Document.parseHTML(TEST_STRING, { sanitizer: { removeElements: []}}).body.innerHTML

HTML Tidy

www.html-tidy.org/

Code:

echo -n "$TEST_STRING" | tidy

Result:

The venerable Tidy replaces the <plaintext> with a <pre>. This is creative.

<p><b>hello</b></p>
<pre><b>world!</b></pre>

xss

jsxss.com/

Code:

import xss from 'xss';
console.log(xss(TEST_STRING));

Result:

A well-known JavaScript-based sanitizer with special focus on XSS prevention escapes only the <plaintext> tags and leaves everything else in place.

<p><b>hello&lt;plaintext&gt;world!&lt;/plaintext&gt;</b></p>

DOMPurify

github.com/cure53/DOMPurify

Code:

import { JSDOM } from 'jsdom';
import DOMPurify from 'dompurify';

const purify = DOMPurify(new JSDOM('').window);
console.log(purify.sanitize(TEST_STRING));

Result:

The classic JS sanitizer chooses to remove the <plaintext> and all its “content”. (I put content in quotes, because technically everything after the start tag would’ve been the <plaintext>’s content.) DOMPurify sees to it that the elements are properly closed. The result is identical to that of the Sanitizer API.

<p><b>hello</b></p>

HTML Purifier

htmlpurifier.org/

Code:

<?php
$config = HTMLPurifier_Config::createDefault();
$purifier = new HTMLPurifier($config);
printf($purifier->purify(TEST_STRING));

Result:

The top dog in the PHP world takes a slightly different approach. It removes only the element itself. (Note the “world!” remaining intact.)

<p><b>helloworld!</b></p>

Symfony HtmlSanitizer

symfony.com/html-sanitizer

Code:

<?php
use Symfony\Component\HtmlSanitizer\HtmlSanitizer;
use Symfony\Component\HtmlSanitizer\HtmlSanitizerConfig;

$config = (new HtmlSanitizerConfig())->allowSafeElements();
$sanitizer = new HTMLSanitizer($config);
printf($sanitizer->sanitize(TEST_STRING));

Result:

Symfony’s sanitizer has a fascinating way of moving tags around. Interesting, but at least we’ve got all elements properly closed, including the uncloseable plaintext.

<p><b>hello</b></p><plaintext>world!</plaintext>

xmllint

gnome.pages.gitlab.gnome.org/libxml2/xmllint.html

Code:

echo -n "$TEST_STRING" | xmllint --html -

Result:

This libxml-based tool produces a warning about an “invalid tag plaintext” but keeps the markup completely unchanged:

<p><b>hello<plaintext>world!</plaintext></b></p>

Mozilla Bleach

github.com/mozilla/bleach

Code:

import bleach
print(bleach.clean(TEST_STRING))

Result:

Python developers who reach for this library will have everything but the <b> escaped.

&lt;p&gt;<b>hello&lt;plaintext&gt;world!&lt;/plaintext&gt;</b>&lt;/p&gt;

OWASP Java HTML Sanitizer

github.com/OWASP/java-html-sanitizer/

Code:

import org.owasp.html.PolicyFactory;
import org.owasp.html.Sanitizers;

public class Sanitize {
    public static void main(String[] args) {
        PolicyFactory policy = Sanitizers.FORMATTING.and(Sanitizers.LINKS);
        String safe = policy.sanitize(TEST_STRING);
        System.out.println(safe);
    }
}

Result:

The staple HTML sanitizer in the Java world escapes everything and does strange things to the end tags, but at least the <plaintext> is gone.

<b>helloworld!&lt;/plaintext&gt;&lt;/b&gt;&lt;/p&gt;</b>

Ammonia as configured by nh3

github.com/rust-ammonia/ammonia, nh3.readthedocs.io/

Code:

import nh3
print(nh3.clean(TEST_STRING))

This Rust-based sanitizer advertises its speed and conformance with the HTML spec.

Result:

The result is close but still different to what browsers will do. In this case, it’s the <b> tag that would not extend over the content of the <plaintext> element.

<p><b>hello</b></p><b>world!&lt;/plaintext&gt;&lt;/b&gt;&lt;/p&gt;</b>

With 11 sanitizing methods we managed to produce 10 different outputs!

Just to be crystal clear here: we are not criticizing the result of any of these libraries. Each one has a good reason to do what they do. And each one serves a slightly different purpose.

But it emphasizes the point that one should be absolutely sure about the aim of a chosen sanitizer and the extent as to which it will change its input. Is the library for removing only potentially dangerous things but keeping as much HTML intact as possible? Is it to scrape all HTML off the string, or to only escape HTML-special characters? The results will differ tremendously.

We enter the danger zone when mixing several tools together without taking a cautious look first.

For example, look at how DOMPurify and HTML Purifier would interact in a potentially hazardous way. DOMPurify would remove any <plaintext> including its content. A later check for any malicious payload would be negative. HTML Purifier on the other hand just strips the <plaintext> tag, while its content remains on the page. If we’d trust the previous DOMPurify result, we’d be surprised by sudden new content being placed verbatim in the HTML code.

If one library is used for input validation and another one for output quoting, that’s a cross-site scripting disaster waiting to happen, unless we know exactly what we’re doing.

Letting the Evil Sleep Again

In the case of <plaintext> itself we are most likely in a safe place. Since <plaintext> has built-in HTML escaping, doing something dangerous with it is severely limited. It takes quite rare a constellation of errors and oversights to appear together in order to run malicious code.

For the sake of the argument, let’s create such a constellation. Assume that you embed a Content-Security Policy on your site in a <meta> element instead of an HTTP header:

<meta http-equiv="Content-Security-Policy" content="script-src 'self'">

This prevents loading 3rd party scripts sufficiently. If an attacker finds a possibility to load HTML prior to this element, they can nullify the CSP:

<script src="https://example.com/malicious.js"></script>
<plaintext>
<meta http-equiv="Content-Security-Policy" content="script-src 'self'">

But again, for this to really have any effect, several things must come together:

The attacker must be able to place HTML in the <head> (because CSP meta tags can only be used there)
The CSP is not set via HTTP
The complete remainder of the page is converted to text/plain, which makes this definitively not a stealthy attack

So we can conclude: It is important to know about <plaintext>. But if we follow tried and tested security rules (for example the OWASP Application Security Verification Standard), we will remain safe from this ancient evil.

I’d like to thank Tom Schuster, Christian Vogl, and Daniela Strehl for valuable input to this article and Elise Hein for an extremely helpful review.

Top layer troubles: popover vs. dialog

2025-12-01T00:00:00Z

by Stephanie Eckles

Have you ever tried to set z-index: 9999 to solve element layering issues? If so, you’ve been fighting a fundamental CSS concept of stacking contexts.

The stacking context defines the order things are placed in the third dimension, or the “z” axis. Think of the z-axis as layers of DOM elements between the root of the stacking context within the viewport, and you, the user, looking through the browser viewport.

An element can only be re-layered within the same stacking context. While z-index is the tool to do it, the failure happens due to a change in stacking contexts. This can happen in a few ways, such as a fixed or sticky positioned element, or combining position absolute or relative along with a z-index, among others as listed on MDN.

A modern web feature is the “top layer,” which is guaranteed to be the top-most layer above any other stacking context. It spans the entire viewport, although elements existing in the top layer may have smaller visible dimensions.

Promoting an element to the top layer breaks it free of any stacking context it may otherwise exist within.

Although the top layer directly addresses a CSS-related issue, there is currently no property available to promote an element to the top layer. Instead, certain elements and conditions gain access to the top layer, including native dialogs via showModal() and elements designated as popovers.

The Popover API is a newly available HTML feature that enables you to create declarative non-modal overlay elements. The ability to escape any stacking context by gaining top layer access is usually a desirable feature of choosing the Popover API. However, there’s a sneaky potential conflict to be aware of before hastily opting for this native upgrade.

Setting the scene

Picture this, the web, 2025: your web app includes a notification service that displays via “toast” messages. You know, those pop-up messages that usually appear in a corner or other location with a lower likelihood of obstructing any other UI.

Usually these toast notifications are for real-time alerts of things like a successful save, or errors such as a failed form submit. They are sometimes time limited, or include a dismissal mechanism like a close button. Sometimes they include an additional action, such as to “Retry” for re-submitting a failed workflow.

Since your app is hip to the times, you’ve recently decided to upgrade the toasts to use the Popover API. This enables you to place the toast component anywhere in the app structure, and not have to hack around stacking context issues. After all, toasts absolutely must appear over everything else, so the top layer access afforded via popovers makes sense!

You ship the enhancement, proud of your work.

Later that week, you get an urgent bug report. Not just any bug report, but an accessibility violation.

Because your app is hip, you also had previously upgraded to native HTML dialogs. That was an incredible upgrade because you got to reduce a JavaScript dependency in favor of a native web feature. That’s another reason you were excited to enhance your toasts to use popover as well.

So, what was the bug? A keyboard user was in a workflow that involved a dialog. While the dialog was open, a background process caused a toast notification to trigger. The notification was for an error, and required user interaction.

The bug occurred when the keyboard user tried to tab into the toast, which they were able to visually see above the dialog backdrop. Unfortunately, their focus never successfully entered the toast, and instead seemed to skip over it, jumping unexpectedly to the browser UI instead.

You can experience this error yourself in this CodePen, where by using the tab key, you too will never be able to access the toast. You can also try it out using a screen reader, and notice that the virtual cursor is also unable to get into the toast.

See the Pen conflicting by Stephanie Eckles (@5t3ph) on CodePen.

If you are able to click on the popover, you may think it’s at least working with that method. But shortly we’ll learn that thing aren’t always as they seem.

While top layer allows beating out standard stacking contexts, items that exist within the top layer are still affected by layering order. The most recently added top layer item appears over previous top layer items. This is why the toast was visually appearing over the dialog’s backdrop.

So if the popover is visually available, why is it unreachable via keyboard or a screen reader’s virtual cursor?

The reason has to do with the popover competing with a modal dialog. When the native HTML dialog is launched via showModal(), the page outside of the dialog becomes inert. The state of inert is a necessary accessibility behavior, which results in isolating the dialog contents, and prevents both tab and virtual cursor access to the background page.

The bug is due to the toast popover being part of the background page’s DOM. This means it has been made inert due to being outside of the DOM boundary of the dialog.

But, due to top layer order, since it was created after the dialog was opened, it is confusingly sitting visually over the dialog.

If you thought clicking the popover was working, it’s in fact not, even though the popover does dismiss. What is really happening is that you are triggering the light dismiss behavior of the popover. This means it is closing because you are technically clicking outside of it’s boundaries, since the dialog is capturing the click instead.

So, while the popover was dismissed, the “Retry” button was not actually clicked, meaning any associated event listener was not triggered.

Even if you created an automated test to check your alert functionality specifically when a dialog was open, the automated test may have had a false positive because it triggered a programmatic click on the toast button. That pseudo click was falsely getting around the issue created from the dialog causing the page to be inert.

The solve is two-fold:

move the popover physically inside the DOM of the dialog
ensure use of popover="manual" to prevent clicks inside the dialog from prematurely triggering light dismiss on the popover

Once we’ve done both of those things, the popover is now both visually available and fully interactive via any method.

See the Pen conflicting by Stephanie Eckles (@5t3ph) on CodePen.

Learnings and additional considerations

What we’ve learned is that you will need to work out a mechanism to launch popovers from within dialogs if your website or app has the possibility of both displaying at once, and they have independent timelines.

Alternatively, you could opt to suppress background page popovers until the dialog closes. This may not be ideal if notifications require timely interaction, or if the dialog contents have the potential to trigger a toast.

Another issue you may need to handle for, besides visibility and interactivity, is if the popover needs to outlive the dialog. As in, it needs to remain open - perhaps to keep waiting for the user to take action - once the dialog is closed.

While I am a huge proponent of using native platform features, and I think popover in particular is an incredible feature, sometimes conflict points can’t be entirely avoided. In fact, you may have already had to contend with a similar conflict against the inert behavior of a modal dialog. So, this article may mostly be a warning to not entirely rip out your previous custom popover architecture if you have this potential issue of displaying background popovers and modal dialogs simultaneously.

If this is an issue that currently, or may in the future affect your work, keep an eye on this HTML issue where solutions are being discussed.

HTMHell Advent Calendar 2025

HTML Input Validation is (maybe) Good

Example

Styling

The Problem: Accessibility

Make it better with JS

Replacing JS with just HTML

Table of Contents:

Accordions / Expanding Content Panels

Description:

Use cases:

Basic implementation:

Resources:

Browser compatibility:

Input with Autofilter Suggestions Dropdown

Description:

Use cases:

Basic implementation:

Resources:

Browser compatibility:

Modals / Popovers

Description:

Use cases:

Basic implementation

Resources:

Browser compatibility:

Offscreen Nav / Content

Description:

Use cases:

Basic implementation:

Resources:

Browser compatibility:

Conclusion

Class names for content not design

Generic class names

Conclusion

Abbreviations done right: The <abbr> element and why not use it

Introduction

The perfect element for abbreviations

The problem with abbr

The simple solution we are all looking for

Examples

First example

Second example

The alternatives you may need

Linking to definitions

Providing a glossary

Providing a function to search an online dictionary

Conclusion

Resources

The three semantics of HTML

Our beloved elephant

First semantics: for users

Second semantics: for user agents

Third semantics: for web developers

Fourth semantics?

Managing the menagerie

For the Love of <details>

<details> Details

<details> Are Always in Style

The Devil and the <details>

Prevails Through <details>

Deeping Linking

Exclusivity

"But her <details>!"

In <summary>

The HTML Elements Time Forgot

bgsound

Framesets

Code

spacer

keygen

nextid

isindex

dir

Closing Tags

Styling by Language: Using the lang Attribute for Multilingual Design

When East Meets West (on the Same Page)

Let the Language Drive the Design

Font Weight and Visual Balance

The “break” element, `<br>`

The “word break opportunity” element, `<wbr>`

The “soft hyphen” character, ``

The “non-breaking space” character, ` `