HTMHell

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.

datalists are more powerful than you think

2024-12-29T00:00:00Z

by Alexis Degryse

I think we all know the <datalist> element (and if you don’t, it’s ok). It holds a list of <option> elements, offering suggested choices for its associated input field.

It’s not an alternative for the <select> element. A field associated to a <datalist> can still allow any value that is not listed in the <option> elements.

Here is a basic example:

Pretty cool, isn't it? But what happens if we combine <datalist> with less common field types, like color and date:

<label for="favorite-color">What is your favorite color?</label>
<input type="color" list="colors-list" id="favorite-color">
<datalist id="colors-list">
  <option>#FF0000</option>
  <option>#FFA500</option>
  <option>#FFFF00</option>
  <option>#008000</option>
  <option>#0000FF</option>
  <option>#800080</option>
  <option>#FFC0CB</option>
  <option>#FFFFFF</option>
  <option>#000000</option>
</datalist>

Colors listed in <datalist> are pre-selectable but the color picker is still usable by users if they need to choose a more specific one.

  <label for="event-choice" class="form-label col-form-label-lg">Choose a historical date</label>
  <input type="date" list="events" id="event-choice">
  <datalist id="events">
    <option label="Fall of the Berlin wall">1989-11-09</option>
    <option label="Maastricht Treaty">1992-02-07</option>
    <option label="Brexit Referendum">2016-06-23</option>
  </datalist>

Same here: some dates are pre-selectable and the datepicker is still available.

Depending on the context, having pre-defined values can possibly speed up the form filling by users.

Please, note that <datalist> should be seen as a progressive enhancement because of some points:

For Firefox (tested on 133), the <datalist> element is compatible only with textual field types (think about text, url, tel, email, number). There is no support for color, date and time.
For Safari (tested on 15.6), it has support for color, but not for date and time.
With some screen reader/browser combinations there are issues. For example, suggestions are not announced in Safari and it's not possible to navigate to the datalist with the down arrow key (until you type something matched with suggestions). Refer to a11ysupport.io for more.

Find out more

Boost website speed with prefetching and the Speculation Rules API

2024-12-28T00:00:00Z

by Schepp

Everybody loves fast websites, and everyone despises slow ones even more. Site speed significantly contributes to the overall user experience (UX), determining whether it feels positive or negative. To ensure the fastest possible page load times, it’s crucial to design with performance in mind. However, performance optimization is an art form in itself. While implementing straightforward techniques like file compression or proper cache headers is relatively easy, achieving deeper optimizations can quickly become complex.

But what if, instead of solely trying to accelerate the loading process, we triggered it earlier—without the user noticing?

One way to achieve this is by prefetching pages the user might navigate to next using <link rel="prefetch"> tags. These tags are typically embedded in your HTML, but they can also be generated dynamically via JavaScript, based on a heuristic of your choice. Alternatively, you can send them as an HTTP Link header if you lack access to the HTML code but can modify the server configuration. Browsers will take note of the prefetch directives and fetch the referenced pages as needed.

In addition to <link rel="prefetch">, Chromium-based browsers support <link rel="prerender">. This tag is essentially a supercharged version of <link rel="prefetch">. Known as "NoState Prefetch," it not only prefetches an HTML page but also scans it for subresources—stylesheets, JavaScript files, images, and fonts referenced via a <link rel="preload" as="font" crossorigin> — loading them as well.

The Speculation Rules API

A relatively new addition to Chromium browsers is the Speculation Rules API, which offers enhanced prefetching and enables actual prerendering of webpages. It introduces a JSON-based syntax for precisely defining the conditions under which preprocessing should occur.

Here’s a simple example of how to use it:

<script type="speculationrules">
{
  "prerender": [{
    "urls": ["next.html", "next2.html"]
  }]
}
</script>

The above list-rule specifies that the browser should prerender the URLs next.html and next2.html so they are ready for instant navigation. The keyword prerender means more than fetching the HTML and subresources—it instructs the browser to fully render the pages in hidden tabs, ready to replace the current page instantly when needed. This makes navigation to these pages feel seamless.

Prerendered pages also typically score excellent Core Web Vital metrics. Layout shifts and image loading occur during the hidden prerendering phase, and JavaScript execution happens upfront, ensuring a smooth experience when the user first sees the page.

Instead of listing specific URLs, the API also allows for pattern matching using where and href_matches keys:

<script type="speculationrules">
{
  "prerender": [{
    "where": { "href_matches": "/*" }
  }]
}
</script>

For more precise targeting, CSS selectors can be used with the selector_matches key:

<script type="speculationrules">
{
  "prerender": [{
    "where": { "selector_matches": ".navigation__link" }
  }]
}
</script>

These rules, called document-rules, act on link elements as soon as the user triggers a pointerdown or touchstart event, giving the referenced pages a few milliseconds' head start before the actual navigation.

If you want the preprocessing to begin even earlier, you can adjust the eagerness setting:

<script type="speculationrules">
{
  "prerender": [{
    "where": { "href_matches": "/*" },
    "eagerness": "moderate"
  }]
}
</script>

Eagerness values:

immediate: Executes immediately.
eager: Currently behaves like immediate but may be refined to sit between immediate and moderate.
moderate: Executes after a 200ms hover or on pointerdown for mobile devices.
conservative (default): Speculates based on pointer or touch interaction.

For even greater flexibility, you can combine prerender and prefetch rules with different eagerness settings:

<script type="speculationrules">
{
  "prerender": [{
    "where": { "href_matches": "/*" },
    "eagerness": "conservative"
  }],
  "prefetch": [{
    "where": { "href_matches": "/*" },
    "eagerness": "moderate"
  }]
}
</script>

Limitations and Challenges

While the Speculation Rules API is powerful, it comes with some limitations:

Browser support: Only Chromium-based browsers support it. Other browsers lack this capability, so treat it as a progressive enhancement.
Bandwidth concerns: Over-aggressive settings could waste user bandwidth. Chromium imposes limits to mitigate this: a maximum of 10 prerendered and 50 prefetched pages with immediate or eager eagerness.
Server strain: Poorly optimized servers (e.g., no caching, heavy database dependencies) may experience significant load increases due to excessive speculative requests.
Compatibility: Prefetching won’t work if a Service Worker is active, though prerendering remains unaffected. Cross-origin prerendering requires explicit opt-in by the target page.

Despite these caveats, the Speculation Rules API offers a powerful toolset to significantly enhance perceived performance and improve UX. So go ahead and try them out!

I would like to express a big thank you to the Webperf community for always being ready to help with great tips and expertise. For this article, I would like to thank Barry Pollard, Andy Davies, and Noam Rosenthal in particular for providing very valuable background information. ❤️

Misleading Icons: Icon-Only-Buttons and Their Impact on Screen Readers

2024-12-27T00:00:00Z

by Alexander Muzenhardt

Introduction

Imagine you’re tasked with building a cool new feature for a product. You dive into the work with full energy, and just before the deadline, you manage to finish it. Everyone loves your work, and the feature is set to go live the next day.
A few days later, you receive an email from a user who can’t access the new feature. The user points out that they don’t understand what the button does. What do they mean? You review your code, locate the button, and start digging into the problem.

<button>
  <i class="icon">📆</i>
</button>

The Problem

You find some good resources explaining that there are people with disabilities who need to be considered in these cases. This is known as accessibility. For example, some individuals have motor impairments and cannot use a mouse. In this particular case, the user is visually impaired and relies on assistive technology like a screen reader, which reads aloud the content of the website or software. The button you implemented doesn’t have any descriptive text, so only the icon is read aloud. In your case, the screen reader says, “Tear-Off Calendar button”. While it describes the appearance of the icon, it doesn’t convey the purpose of the button. This information is meaningless to the user. A button should always describe what action it will trigger when activated. That’s why we need additional descriptive text.

The Challenge

Okay, you understand the problem now and agree that it should be fixed. However, you don’t want to add visible text to the button. For design and aesthetic reasons, sighted users should only see the icon. Is there a way to keep the button “icon-only” while still providing a meaningful, descriptive text for users who rely on assistive technologies like screen readers?

The Solution

First, you need to give the button a descriptive name so that a screen reader can announce it.

<button>
  <span>Open Calendar</span>
  <i class="icon">📆</i>
</button>

The problem now is that the button’s name becomes visible, which goes against your design guidelines. To prevent this, additional CSS is required.

.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

<button>
  <span class="sr-only">Open Calendar</span>
  <i class="icon">📆</i>
</button>

The CSS ensures that the text inside the span-element is hidden from sighted users but remains readable for screen readers. This approach is so common that well-known CSS libraries like TailwindCSS, Bootstrap, and Material-UI include such a class by default.

Although the text of the buttons is not visible anymore, the entire content of the button will be read aloud, including the icon — something you want to avoid.

In HTML you are allowed to use specific attributes for accessibility, and in this case, the attribute aria-hidden is what you need. ARIA stands for “Accessible Rich Internet Applications” and is an initiative to make websites and software more accessible to people with disabilities.

The attribute aria-hidden hides elements from screen readers so that their content isn’t read. All you need to do is add the attribute aria-hidden with the value “true” to the icon element, which in this case is the “i”-element.

<button>
  <span class="sr-only">Open Calendar</span>
  <i class="icon" aria-hidden="true">📆</i>
</button>

Alternative

An alternative is the attribute aria-label, which you can assign a descriptive, accessible text to a button without it being visible to sighted users. The purpose of aria-label is to provide a description for interactive elements that lack a visible label or descriptive text. All you need to do is add the attribute aria-label to the button. The attribute aria-hidden and the span-Element can be deleted.

<button aria-label="Open Calendar">
  <i class="icon">📆</i>
</button>

With this adjustment, the screen reader will now announce “Open calendar,” completely ignoring the icon. This clearly communicates to the user what the button will do when clicked.

Which Option Should You Use?

At first glance, the aria-label approach might seem like the smarter choice. It requires less code, reducing the likelihood of errors, and looks cleaner overall, potentially improving code readability.

However, the first option is actually the better choice. There are several reasons for this that may not be immediately obvious:

Some browsers do not translate aria-label
It is difficult to copy aria-label content or otherwise manipulated it as text
aria-label content will not show up if styles fail to load

These are just a few of the many reasons why you should be cautious when using the aria-label attribute. These points, along with others, are discussed in detail in the excellent article "aria-label is a Code Smell" by Eric Bailey.

The First Rule of ARIA Use

The “First Rule of ARIA Use” states:

If you can use a native HTML element 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.

Even though the first approach also uses an ARIA attribute, it is more acceptable because aria-hidden only hides an element from screen readers. In contrast, aria-label overrides the standard HTML behavior for handling descriptive names. For this reason, following this principle, aria-hidden is preferable to aria-label in this case.

Browser compatibility

Both aria-label and aria-hidden are supported by all modern browsers and can be used without concern.

Conclusion

Ensuring accessibility in web design is more than just a nice-to-have—it’s a necessity. By implementing simple solutions like combining CSS with aria-hidden, you can create a user experience that is both aesthetically pleasing and accessible for everyone, including those who rely on screen readers. While there may be different approaches to solving accessibility challenges, the key is to be mindful of all users' needs. A few small adjustments can make a world of difference, ensuring that your features are truly usable by everyone.

Cheers
Alex

Resources / Links

The underrated <dl> element

2024-12-26T00:00:00Z

by David Luhr

The Description List (<dl>) element is useful for many common visual design patterns, but is unfortunately underutilized.

It was originally intended to group terms with their definitions, but it's also a great fit for other content that has a key/value structure, such as product attributes or cards that have several supporting details.

Developers often mark up these patterns with overused heading or table semantics, or neglect semantics entirely. With the Description List (<dl>) element and its dedicated Description Term (<dt>) and Description Definition (<dd>) elements, we can improve the semantics and accessibility of these design patterns.

The <dl> has a unique content model:

A parent <dl> containing one or more groups of <dt> and <dd> elements
Each term/definition group can have multiple <dt> (Description Term) elements per <dd> (Description Definition) element, or multiple definitions per term
The <dl> can optionally accept a single layer of <div> to wrap the <dt> and <dd> elements, which can be useful for styling

Examples

An initial example would be a simple list of terms and definitions:

<dl>
	<dt>Compression damping</dt>
	<dd>Controls the rate a spring compresses when it experiences a force</dd>
	<dt>Rebound damping</dt>
	<dd>Controls the rate a spring returns to it's extended length after compressing</dd>
</dl>

A common design pattern is "stat callouts", which feature mini cards of small label text above large numeric values. The <dl> is a great fit for this content:

<dl>
	<div>
		<dt>Founded</dt>
		<dd>1988</dd>
	</div>
	<div>
		<dt>Frames built</dt>
		<dd>8,678</dd>
	</div>
	<div>
		<dt>Race podiums</dt>
		<dd>212</dd>
	</div>
</dl>

And, a final example of a product listing, which has a list of technical specs:

<h2>Downhill MTB</h2>

<dl>
	<div>
		<dt>Front travel:</dt>
		<dd>160mm</dd>
	</div>
	<div>
		<dt>Wheel size:</dt>
		<dd>27.5"</dd>
	</div>
	<div>
		<dt>Weight:</dt>
		<dd>15.2 kg</dd>
	</div>
</dl>

Accessibility

With this markup in place, common screen readers will convey important semantic and navigational information. In my testing, NVDA on Windows and VoiceOver on MacOS conveyed a list role, the count of list items, your position in the list, and the boundaries of the list. TalkBack on Android only conveyed the term and definition roles of the <dt> and <dd> elements, respectively.

If the design doesn't include visible labels, you can at least include them as visually hidden text for assistive technology users. But, I always advocate to visually display them if possible.

Wrapping up

The <dl> is a versatile element that unfortunately doesn't get much use. In over a decade of coding, I've almost never encountered it in existing codebases. It also doesn't appear anywhere in the top HTML elements lists in the Web Almanac 2024 or an Advanced Web Ranking study of over 11.3 million pages. The next time you're building out a design, look for opportunities where the underrated Description List is a good fit.

To go deeper, be sure to check out this article by Ben Myers on the <dl> element.

Preloading fonts for web performance with link rel="preload"

2024-12-25T00:00:00Z

by Alistair Shepherd

Web performance is incredibly important. If you were here for the advent calendar last year you may have already read many of my thoughts on the subject. If not, read Getting started with Web Performance when you’re done here!

This year I’m back for more web performance, this time focusing on my favourite HTML snippet for improving the loading performance of web fonts using preloads. This short HTML snippet added to the head of your page, can make a substantial improvement to both perceived and measured performance.

<link
  rel="preload"
  href="/nova-sans.woff2"
  as="font"
  type="font/woff2"
  crossorigin="anonymous"
>

Above we have a link element that instructs the browser to preload the /nova-sans.woff2 font. By preloading your critical above-the-fold font we can make a huge impact by reducing potential flashes of unstyled or invisible text and layout shifts caused by font loading, like here in the following video:

Recording of a page load illustrating how a font loading late can result in a jarring layout shift

How web fonts are loaded

To explain how preloading fonts can make such an impact, let’s go through the process of how web fonts are loaded. Font files are downloaded later than you may think, due to a combination of network requests and conservative browser behaviour.

In a standard web page, there will be the main HTML document which will include a CSS file using a link element in the head. If you’re using self-hosted custom fonts you’ll have a @font-face rule within your CSS that specifies the font name, the src, and possibly some other font-related properties.

In other CSS rules you specify a font-family so elements use your custom font.

Once our browser encounters our page it:

Starts streaming the HTML document, parsing it as it goes
Encounters the link element pointing to our CSS file
Starts downloading that CSS file, blocking the render of the page until it’s complete
Parses and applies the contents of that file
Finds the @font-face rule with our font URL

Okay let’s pause here for a moment — It may make sense for step 6 to be “Starts downloading our font file”, however that’s not the case. You see, if a browser downloaded every font within a CSS file when it first encountered them, we could end up loading much more than is needed. We could be specifying fonts for multiple different weights, italics, other character sets/languages, or even multiple different fonts.

If we don’t need all these fonts immediately it would be wasteful to download them all, and doing so may slow down higher priority CSS or JS.

Instead, the browser is more conservative and simply takes note of the font declaration until it’s explicitly needed. The browser next:

Takes a note of our @font-face declarations and their URLs for later
Finishes processing CSS and starts rendering the page
Discovers a piece of text on the page that needs our font
Finally starts downloading our font now it knows it’s needed!

So as we can see there’s actually a lot that happens between our HTML file arriving in the browser and our font file being downloaded. This is ideal for lower priority fonts, but for the main or headline font this process can make our custom font appear surprisingly late in the page load. This is what causes the behaviour we saw in the video above, where the page starts rendering but it takes some time before our custom font appears.

A waterfall graph showing how our custom ‘lobster.woff2’ font doesn’t start being downloaded until 2 seconds into the page load and isn’t available until after 3 seconds

This is an intentional decision by browser makers and spec writers to ensure that pages with lots of fonts aren’t badly impacted by having to load many font files ahead of time. But that doesn’t mean it can’t be optimised!

Preloading our font with a link

<link
  rel="preload"
  href="/nova-sans.woff2"
  as="font"
  type="font/woff2"
  crossorigin="anonymous"
>

The purpose of my favourite HTML snippet is to inform the browser that this font file will be needed with high priority, before it even has knowledge of it. We’re building our page and know more about how our fonts are used — so we can provide hints to be less conservative! If we start downloading the font as soon as possible then it can be ready ahead of when the browser ‘realises’ it’s needed.

Looking back at our list above, by adding a preload we move the start of the font download from step 9 to step 2!

Starts streaming the HTML document, parsing it as it goes
Encounters our preload and starts downloading our font file in the background
Encounters the link element pointing to our CSS file
Continues as above

Taking a closer look at the snippet, we’re using a link element and rel="preload" to ask the browser to preload a file with the intention of using it early in the page load. Like a CSS file, we provide the URL with the href attribute.

We use as="font" and type="font/woff2" to indicate this is a font file in woff2. For modern browsers woff2 is the only format you need as it’s universally supported.

Finally there’s crossorigin="anonymous". This comes from the wonderfully transparent and clear world of Cross Origin Resource Sharing. I jest of course, CORS is anything but transparent and clear!

For fonts you almost always want crossorigin="anonymous" on your link element, even when the request isn’t cross-origin. Omitting this attribute would mean our preload wouldn’t be used and the file would be requested again. But why?

Browser requests can be sent either with or without credentials (cookies, etc), and requests to the same URL with and without credentials are fundamentally different. For a preload to be used by the browser, it needs to match the type of request that the browser would have made normally. By default fonts are always requested without credentials, so we need to add crossorigin="anonymous" to ensure our preload matches a normal font request.

By omitting this attribute our preload would not be used and the browser would request the font again. If you’re ever unsure of how your preloads are working, check your browsers’ devtools. In Chrome the Network pane will show a duplicate request, and the Console will log a warning telling you a preload wasn’t used.

Screenshot showing the Chrome devtools Console pane, with warnings for an incorrect font preload

Result and conclusion

By preloading our critical fonts we ensure our browser has the most important fonts available earlier in the page loading process. We can see this by comparing our recording and waterfall charts from earlier:

Side-by-side recording of the same page loading in different ways. ‘no-preload’ shows a large layout shift caused by the font switching and finishes loading at 4.4s. ‘preload’ doesn’t have a shift and finishes loading at 3.1s.

Side-by-side comparison of two waterfall charts of the same site with font file `lobster.woff2`. For the ‘no-preload’ document the font loads after all other assets and finishes at 3s. The ‘preload’ document shows the font loading much earlier, in parallel with other files and finishing at 2s.

As I mentioned in Getting started with Web Performance, it’s best to use preloads sparingly so limit this to your most important font or two. Remember that it’s a balance. By preloading too many resources you run the risk of other high-priority resources such as CSS being slowed down and arriving late. I would recommend preloading just the heading font to start with. With some testing you can see if preloading your main body font is worth it also!

With care, font preloads can be a simple and impactful optimisation opportunity and this is why it’s my favourite HTML snippet! This is a great step to improving font loading, and there are plenty of other web font optimisations to try also!

The search input: They almost got it right

2024-12-24T00:00:00Z

by Steve Frenzel

This example is a classic - in a bad way - and can cause quite some confusion for users of assistive technology (AT). But it's also very easy to fix! It's the <input> element missing its dear friend, the <label>... 😭

Bad code

<input placeholder="Search" />

It's not relevant for this article, but here's the "button" to submit the content of the <input>:

<div class="_icon_1f3oz_44">
  <span title="" class="gl-icon__wrapper" role="img">
    <svg class="gl-icon">
      <use xlink:href="#search"></use>
    </svg>
  </span>
</div>

The cherry on top: It's not even wrapped inside a <form> element, so it's very likely that the submit is handled via JavaScript. 🍒

So what's the issue with this <input> element? In theory, having a placeholder instead of a <label> element is only a temporary solution! Once you've typed something, the placeholder gets replaced with whatever you've typed.

This could be a big issue for screen reader users. Let's check how different screen readers handle this kind of situation with different browsers.

You can do it yourself here: The search input: They almost got it right (bad code example)

What I checked was if the placeholder value still gets announced after typing something. I tested with macOS Sequoia 15.1.1 on December 1, 2024 using the latest versions of screen readers and browsers.

	Google Chrome	Mozilla Firefox	Microsoft Edge	Apple Safari
JAWS	Yes	Yes	Yes	n/a
NVDA	Yes	Yes	Yes	n/a
Narrator	Yes	Yes	Yes	n/a
VoiceOver	No	Yes	No	No

Only VoiceOver had issues announcing announcing the placeholder attribute (except when using Firefox), which might be a bug! This issue has been mentioned back in 2017 for iOS at WebKit Bugzilla and I wonder how long it's been present again on MacOS since then...

Advantages of using `<label>` instead of `placeholder`

Even though almost all screen readers in this list seem to handle a missing <label> and a present label attribute well, there are still many reasons why you should do it the other way around:

Reduce cognitive load

Having a form with many inputs, no labels and only placeholders will make it very hard to remember the required information. This lacking clarity can place a huge burden on people having trouble to recall many things at once.

It will also make it harder to check against the requirements of the inputs, as the placeholder acting as a hint has been replaced with what you've typed. Therefore errors will be harder to fix, as you can't easily check against the requirement anymore.

Using a descriptive <label> can avoid these issues, as it's persistent.

Some older browsers might hide the placeholder text once the input is focused. And as you read earlier, some screen readers might have issues with a placeholder instead of a <label>.

Using a descriptive <label> can avoid these issues, as it has great browser support and will be recognized by screen readers as well.

Increase touch target size

A placeholder is inside the text input. When using a mouse, this will be the only area you can click to focus this input. People with tremors might have a hard time doing that, depending on the size of the inputs and how close they're to each other.

Using a descriptive <label> can avoid these issues, as clicking it will focus the input.

For more reasons why, check out Adam Silver's article listed under Further reading.

Enough of the theory, let's check out some working examples! You can find them here: The search input: They almost got it right (good code examples)

1. Good code with explicit label

<label for="search-input">Search:</label>
<input id="search-input" name="search" type="search" />

This common approach provides a visual cue for the <input> element and can be processed by AT.

The <input> is now of type="search", which should expose it as "searchbox" in the accessibility tree.

Clicking the label will also focus the input. This is a nice helper for sighted users and people with motor disabilities, as the target area for clicking has been increased.

Additionally, you can target this input now with CSS! This way you can check yourself that you implemented semantic and accessible HTML:

input[type="search"] {
  /* Your code */
}

for="search-input" of <label> is referencing id="search-input" of <input>, so they're now "connected", if you will. AT should always announce the label of this input, no matter what you've typed.

The name attribute is useful when submitting the form, so you know which <input> contains what information.

If, for whatever reason, you don't want to show the visual label, you could also do it this way:

2. Good code using `aria-label`

<input aria-label="Search" id="search-input" name="search" type="search" />
<button type="submit">Search</button>

There's no direct connection between <input> and <button>, but it is still of type="search" and has the accessible name "Search", which should give enough clues for AT users.

However, the only visual clue here is the button. So make sure it's close to the input, in order for people to make the mental connection. Not a fan of it though, as I would rather connect the two elements with each other:

3. Good code using `aria-labelledby`

<input aria-labelledby="search-input" name="search" type="search" />
<button id="search-input" type="submit">Search</button>

Still no visual cue, but whenever we change the <button> name, the accessible name of the <input> will change accordingly. The power of the aria-labelledby attribute! 💪 There's one more approach:

4. OK code with implicit label

<label>
  Search:
  <input type="search" name="search" />
</label>

As the <input> is wrapped inside the <label> element, they are both connected now. However, AT support for this solution might not be as good as an explicit label (see Associating labels implicitly).

Going the extra mile using landmarks

To make it even easier for AT users to access the search functionality on your website, you could add role="search" to your <form> element, or wrap it inside the <search> landmark:

<form role="search">
  <label for="search-input">Search:</label>
  <input id="search-input" name="search" type="search" />
</form>

This should announce the container as "search" in the accessibility tree, same goes for this approach:

<search>
  <label for="search-input">Search:</label>
  <input id="search-input" name="search" type="search" />
</search>

When people are traversing the DOM using landmarks, this could help them find the search input on your website much quicker. And even if it's not announced as "search", you'd still have a very descriptive <label> element and a user input of type="search".

Conclusion

All in all, this wasn't a very complex or time consuming fix and it will help people a lot to locate and use the search input on your website. Different approaches are possible, like using an implicit or explicit label, or even no visual label at all!

I personally like to use an explicit label, as it's a common pattern AND it's something you could target with CSS. Don't use an <input> element without a <label> or aria-label, as it comes with plenty of benefits for you and your users.

And wrapping an input inside a <form role="search"> or the <search> landmark will provide an extra hint for them, which could make it even easier to get there. So don't forget to always pair <input> with a <label>, they belong together and are the ultimate couple! ❤️

The devil is in the <details>

2024-12-23T00:00:00Z

by J. Pedro Ribeiro

Not too long ago, building an accordion component would require you to use a combination of JavaScript and CSS. If you've been around for as long as I have, you might have used a library like jQuery or Mootools.
If you went "vanilla", your code would look something like this:

<div class="my-js-accordion">
  <span>Learn more about accordions</span>
  <p class="hidden">Accordions encapsulate content under a heading.</span>
</div>

.hidden {
  display: none; 
}

document.querySelectorAll(".my-js-accordion").forEach((accordion)=>{
  accordion.querySelector("span").addEventListener("click", (e)=>{
    accordion.querySelector("p").classList.toggle("hidden");
  });
});

And it would work as you expected:

→ Learn more about accordions

→ This one was built with JS and CSS

→ Each accordion on this example works independently

The more adventurous would hack together some input and label elements together. With the help of :checked and some clever
CSS selectors, you could achieve the same visual representation as the one above but without the need for JavaScript.

<div class="my-css-accordion">
  <input type="checkbox" id="accordion1">
  <label for="accordion1">→ Learn more about accordions</label>
  <p>Accordions encapsulate content under a heading.</p>
</div>

.my-css-accordion input[type="checkbox"],
.my-css-accordion p {
  display: none;
}

.my-css-accordion input[type="checkbox"]:checked + label + p {
  display: block;
}

And it would be visually the same as the previous example:

→ Learn more about accordions

Accordions encapsulate content under a heading.

→ This one was built without JavaScript

Only CSS and HTML!

→ Same looks, same behaviour

However, the code is slightly harder to maintain

These techniques work but there have some disadvantages: not only they're hard to maintain, they're also not accessible, and their reliance on JavaScript makes them not the ideal candidate for a modern web application.
In summary, another case of HTMLHell.

Here comes a new challenger

Since 2020, all major browsers support the <details> and its companion <summary> elements. Combined, they replace the need for JavaScript and CSS hacks to create an accordion component.
We use the following syntax:

<details>
  <summary>Your heading goes here</summary>
  <p>Any content you like goes below the summary tag.</p>
  <p>As many elements as you need.</p>
</details>

And it will work just like the previous examples, but with some added benefits:

Less code ✅
Fully accessible ✅
Works without JavaScript ✅
No need for hacks ✅
Fully stylable ✅

As seen below:

Your heading goes here

Any content you like goes below the summary tag.

As many elements as you need.

This is the second heading

Any content you like goes below the summary tag.

As many elements as you need.

And the third entry it's here

Any content you like goes below the summary tag.

As many elements as you need.

On the example above, each <details> element works independently of each other. But what if you want them to behave like true accordions, where only one can be opened at a time?

One More Thing... Exclusive Accordions

Not too long ago, the name attribute was added to the details element.
Similarly to the usage in the radio input, it allows you to group multiple elements together. This means we can have exclusive accordions: when only one can be opened at a time.

Here is an example of the usage:

<details name="my-accordion-group">...</details>
<details name="my-accordion-group">...</details>
<details name="my-accordion-group">...</details>

Give the same name attribute to all the details elements you want to group together and they'll work as expected:

3 separate entries

First block content.

End of first block.

Only one can be opened at a time

Second block content.

End of second block.

Still, no JS needed!

Third block content.

End of third block.

Note: It's worth highlighting that exclusive accordion come with some drawbacks, including poor UX on keyboard navigation and reduced usability for screen readers. Eric Eggert wrote about these issues, offering some solutions and insights that are worth reading.

Take it to the next level

Recently, Chrome 131 added support to new ways you can style both <details> and <summary> elements. Still early days but the future looks bright!
Combine these features with some creative styling and you can create really complex components with accessibility and scalability built-in.

Further reading and examples:
Code snippets | MDN | Can I use | web.dev

PSA: Stop using the title attribute as tooltip!

2024-12-22T00:00:00Z

by Daniela Kubesch

It's almost 2025, so it's time to stop using the title attribute everywhere. Images, text, buttons, ... you name it, devs really like to put it on any element in sight. Most of the time, people actually want to create a tooltip. You know, that little bubble of information designed to clarify the purpose of otherwise unclear elements, that pops up attached to an element when its receives focus or a user hovers their mouse over it.

The identifying thing about tooltips is that they contain no interactive elements (aka. only plain text), and are always attached to existing interactive elements.
Whenever you want to add interactive elements inside your information bubble, it's not called tooltip, but toggletip. Toggletips can contain semantic markup, rich content and interactive elements, and usually only appear when an element is clicked. The great thing about toggletips is that they're accessible on touchscreens and easier to find and recognise for users with low vision.

So depending on your use case, you need to implement a tooltip or a toggletip.

But let's circle back to the title attribute. Often, people use it to create a tooltip. However, this is not the recommended way to go.

But why, I love my `title`!?

It's simple. The title attribute is inaccessible. Users of mobile phones and tablets, users of assistive technologies, and keyboard only users cannot interact with it.
If you want a tooltip, a much better, and accessible, option is using the popover attribute.

Note: The only place where you should (& must) use the title attribute is on an iframe! See Steve Faulkner's post for more information.

How to use `popover`

Firstly, before we get started, it is always better to display clear, permanently visible information. So, if space permits, do not use tooltips. Instead, provide clear labels and sufficient text. This is particularly important for forms!

However, if you wanna go down that path, the popover attribute provides a starting point for building popover-like interactions on the web. Its purpose is simply to add 'popover/tooltip behaviour'. So we'll use it to create our custom plain-text tooltip.

To start, we just need an interactive element (like a button) which is used to trigger the tooltip, even when navigating with a keyboard only, and a <div> containing the tooltip content.

The <button> is linked to the tooltip with aria-describedby.
The <div> receives the popover attribute and an id.
As the popover attribute just adds behaviour, not semantics, we need to add our own role when it makes sense. Therefore we add role='tooltip' to the <div>.

<p>
  There is a
  <button type="button" aria-describedby="tooltip">secret</button> to accessible
  HTML!
</p>

<div popover role="tooltip" id="tooltip">
  <div>a div is not a button ✨</div>
</div>

Let's make it interactive

If we would want to create a toggletip, which opens onClick, we could simply add popovertarget="ID" to the <button>, with the id of the toggletip.

There is a 
<button type="button" aria-describedby="toggletip" popovertarget="toggletip">
  secret
</button>
to accessible HTML!

<div popover id="toggletip">
  <div>a div is not a button ✨</div>
</div>

There is a to accessible HTML!

However, if we want our tooltip, that is triggered when the interactive element is hovered or focused, we need JavaScript.
We can display the tooltip by using .hidePopover() and .showPopover().
If showPopover() is called on an element with the popover attribute that is currently hidden, the element is added to the top rendering layer.

A tooltip usually disappears when hitting the Escape key or when the mouse is moved away from the interactive element.
But it's also important to make sure that the tooltip content is reachable with the mouse pointer. That way, users can copy the text or read it with magnification software.
That's why, with the help of JavaScript, we show the tooltip on mouseover of the interactive element and keep it visible when the tooltip itself is hovered (by also listening to mouseover).
With mouseout we can hide the tooltip as soon as the mouse leaves either the tooltip or the interactive element that triggered it.

To open or close the tooltip with keyboard navigation, we must listen to the focusin and focusout events of the button.
The tooltip must be easy to dismiss (e.g. by pressing the Escape key).
It's also worth noting that tooltips don't actually get the focus themselves. The focus stays on the element that triggered the tooltip.
However, it's content is still read to screen reader users and is accessible by the screen readers virtual cursor.
But remember, in general, if we're showing content automatically when an element receives focus, it's important not to suddenly change context and confuse users.

Wait, is this new attribute supported?

Good news! The popover attribute is supported by all modern browsers with versions released between mid-2023 and 2024 (starting with Safari 17.0, Firefox 125, Chrome 114 and Edge 114).

Looks bad though

That's why the last thing to do is use CSS to style the tooltip.
If you want to change how the tooltip looks when it's displayed, you can use the :popover-open pseudo-class.

We also need to make sure the tooltip is correctly positioned.
We can use position-anchor and position-area for Chrome and Edge, but they're still in the experimental phase, so we need an alternative for other browsers. The simplest option would be to use a library like Floating UI.

There is a to accessible HTML!

And that's it, you just created a custom tooltip!
Find the detailed code in this CodePen.

Grouping form fields

2024-12-21T00:00:00Z

by Matthias Kittsteiner

When I first stumbled upon fieldset and legend, I didn’t know much about HTML and especially not about accessibility. Everything I noticed was the special way a legend is displayed inside a fieldset – or rather: alongside the border of a fieldset.

Fast forward to (kind of) today: while working on a contact form, I first could get my hands on this element and learned more about it.

What is a `fieldset`?

Every so often I’m surprised how well chosen names in HTML are. fieldset is no exception here. It’s basically a list of form fields (inputs, selects, textareas). It groups all fields inside of it, and makes it a set of fields. And the legend is used as caption of the fieldset (and ultimately it becomes a caption for all of the grouped form fields).

A simple example of a fieldset looks like this:

<fieldset>
  <legend>Date</legend>
  <label for="date-month">Month</label>
  <input name="date[month]" type="number" id="date-month">
  <label for="date-day">Day</label>
  <input name="date[day]" type="number" id="date-day">
  <label for="date-year">Year</label>
  <input name="date[year]" type="number" id="date-year">
</fieldset>

Which results in this:

In the image you see the default design for a fieldset: It has a border, that is partly interrupted by the legend. Something, that is not the easiest to achieve with other elements with CSS only. However, in the wild, you won’t often see it like this.

Why does it matter?

While for users capable of browsing websites visually, a fieldset often stays hidden, since the default styling usually is changed. Only the legend is visible as caption for a group of fields. For screen reader users, it’s a whole different story if they use it to navigate through the content via keyboard. For every field inside the fieldset, the screen reader announces that it is part of a group as well as the caption. It makes sure that the user is always aware of the context of the group and that the current active field is part of a specific group.

VoiceOver for example will announce the fieldset as “Date, group”:

When navigating to the first form field “month”, VoiceOver will announce it as “Month, incrementable edit text number field, Date, Date, group”

Additionally, by using the disabled attribute, you can easily disable a whole group of fields within the fieldset. Feels a little bit like magic. Such disabled fields are neither editable (they ignore user inputs completely), nor will they be submit in a form.

One note though: think about it first before using it. That is also true for a fieldset as a whole.

Ensure fields inside a fieldset are actually connected to each other and even require an identical context. Otherwise, it just makes the announcement more verbose as it should be, since the value of the legend will always be announced to screen reader users (in case of VoiceOver users often even twice). Use it only if the connected fields are not self-explaining if they are used alone, if you can’t properly edit a field the right way without knowing about the context of the group. While connecting multiple fields to enter a date with month/day/year actually will tell you (by a properly set legend) that you’re about to fill out a date, connecting two fields for first and last name won’t have any positive effect, since they can be filled correctly by their own without knowing that the other field exists.

Usage examples

Having multiple choice questions, e.g. in a survey, is an ideal example in grouping form fields. You can use the legend as question and radio buttons as the answers:

<fieldset>
	<legend>When did you hear about fieldsets the first time?</legend>
	
	<input type="radio" id="before-2000" name="eyes-opened" value="before 2000" />
	<label for="before-2000">Before 2000</label><br />
	
	<input type="radio" id="between-2000-2009" name="eyes-opened" value="2000 – 2009" />
	<label for="between-2000-2009">Between 2000 and 2009</label><br />
	
	<input type="radio" id="between-2010-2019" name="eyes-opened" value="2010 – 2019" />
	<label for="between-2010-2019">Between 2010 and 2019</label><br />
	
	<input type="radio" id="today" name="eyes-opened" value="2020 – today" />
	<label for="today">Between 2020 and today</label><br />
</fieldset>

It could also be used to connect fields for a day, a month and a year for individual input fields to select a specific date (as seen in the first example), as well as hours and minutes to select a time (if native date and time pickers aren't an option). Or you could have different fields for a credit card number by splitting them into four digits each. You see, there are many possibilities to use fieldset elements, just don’t overuse them – because with many possibilities comes great responsibility – or so.

Make also sure to always test your fieldset elements with a screen reader to see whether adding a context in such a way is useful. This will make it easier to distinguish whether you should use a fieldset or better use non-connected single form fields.

My favourite colour is Chuck Norris red

2024-12-20T00:00:00Z

by Declan Chidlow

Setting the colour of text on a webpage is usually a simple affair involving whipping it out the good ol' CSS color property. But this is HTMHell, dammit. None of that wishy-washy CSS nonsense here. No siree. We use HTML as the good lord intended and shalln't stray into the sins of cascading sheets lest we end up some non-HTML variant of hell where they define page structure with JavaScript vars.

But HTML isn't great for defining styles -- or at least, it isn't anymore. If we wind back the clocks a few years to HTML versions of old, we find the colour attribute. If you've been around for a while, you've no doubt seen it. Something like this:

<font color="#d72b2b">HTMHell rules!</font>

HTMHell rules!

If we render that in a browser, we get some text in the lovely HTMHell red. That's great. That's what we'd expect. Next we'll choose another colour. Something a bit different. Let's try 'chucknorris'.

<font color="chucknorris">But... Chuck Norris isn't a colour.</font>

But... Chuck Norris isn't a colour.

If you go through the effort of loading that up in a browser, you might notice it makes the text red. Why?

Some funny character parsing

HTML generally doesn't have an error state, at least not one akin to what would happen if writing something like invalid JavaScript. Browsers are very forgiving when parsing HTML (which explains how people have gotten away with the crimes documented throughout this website) and generally do their best to make up for user error. If you leave a dangling <div>, the browser will do its best to close it up and render it out.

This forgiveness is the reason behind the funkiness. Browsers simply try to forge ahead with the invalid value and hope it'll work. In the past web browsers all handled invalid values a bit differently, but now it's all outlined in the "rules for parsing a legacy color value" part of the HTML spec. A surmised version of the parsing outlined there is as follows:

Initial Cleanup:
- If an octothorpe (#) is located at the start of the value, it's removed.
- The colour attribute only accepts hexes, so there isn't a point keeping it.
- Example: "#FF0000" becomes "FF0000".
Replace Invalid Characters:
- Any non-hexadecimal characters (anything not 0-9 or A-F/a-f) are removed and replaced with '0'.
- Example: 'abcxyz123' becomes 'abc000123'.
Standardise Length:
- While the string's length is 0 or not divisible by 3, append '0'.
- Examples:
  - "F" becomes "F00" (padded to length 3).
  - "FFFF" becomes "FFFF00" (padded to length 6).
  - "FFFFFF0" becomes "FFFFFF000" (padded to length 9).
Split into Red, Green, and Blue:
- The first third becomes the red value.
- The second third becomes the green value.
- The last third becomes the blue value.
- Example: "FFFFFF000" becomes ["FFF", "FFF", "000"].
Handle Length:
- If any component is longer than 8 characters, remove the characters from the left until it's 8 characters long.
  - Example: "123456789" → "23456789"
- While the length is greater than 2, and all components start with '0', remove the leading '0' from each component.
  - Example: ["000F", "000F", "000F"] becomes ["00F", "00F", "00F"] which then becomes ["0F", "0F", "0F"].
- If length is still greater then 2 keep only the first 2 characters of each component.
  - Example: ["ABC", "DEF", "123"] becomes ["AB", "DE", "12"].
Putting It Together:
- Get the final red, blue, and green components, then put them together in that order to create the colour.
- Example: ["AB", "DE", "12"] becomes ABDE12.

I've written a small tool over on CodePen that will take any inputted value, break down the processing step by step, and output the colour as it would be handled. Go have a bit of fiddle!

See the Pen Legacy HTML Colour Parsing Demo by Declan Chidlow (@OuterVale) on CodePen.

Some fun examples

So, we know this happens and why. The next task is obviously to have some fun with it. Finding words whose computed colours correlate with them is great fun. For example, 'Sonic' gives us a lovely blue like the hedgehog. I've put together a little table of some of these coincidental match ups:

See the Pen Word Correlations With HTML Colour Parsing by Declan Chidlow (@OuterVale) on CodePen.

Interesting parsing in the modern era

So, that's all well and good, but it's old news. The color and bgcolor attributes that permitted our parsing adventures are relics of HTML 4. They're obsolete (though still in active use on a disturbingly high number of websites). That isn't to say quirks like that have disappeared completely though. CSS has its own set of fascinating peculiarities when it comes to handling invalid colour values. Most modern browsers will clamp values rather than reject them outright -– throw rgb(300, -50, 1000) at a browser and it won't fail; it'll helpfully transform it into rgb(255, 0, 255).

The web's foundational principle of forgiveness -– the inherent flexibility that allows "chucknorris" to be parsed as red, even though the reason it does so is old, silly, and unsupported –- hasn't gone anywhere. Modern browsers still bend over backward to make our code work, even when we throw nonsense at them. It doesn't take long to see this forgiveness in action within the cursed examples held within the pages of HTMHell. Each horrifying snippet, each questionable hack, each "it works but why" moment exists because browsers simply refuse to give up on rendering our 'mistakes'.

The web is built on this foundation of resilience, both in technology and ethos. It's what allows a website from 1996 to still render in a modern browser. It's what lets a page load even when half the CSS is invalid. It's what makes it magic.

I've heard people quip that browsers should be less forgiving and enforce perfection. That allowing jank makes the web somehow 'bad'. I think a perfect web would be a boring web. I certainly wouldn't be here writing were it 'perfect'. It's about making the web work, no matter what we throw at it, and I wouldn't have it any other way.

After all, in a perfect web, "chucknorris" would just be another error message -– and where's the fun in that?

Resources

Getting Oriented with HTML Video

2024-12-19T00:00:00Z

by Scott Jehl

A couple years back, I was in a window seat on a flight from Amsterdam to New York. The weather was gray and drizzly as the plane took off, but as it punched through the clouds a very different scene revealed itself. Out my window, it looked like a Maxfield Parrish painting brought to life. And the plane's speed made it appear to scroll by with this uncanny effect, like a parallax effect that used the wrong easing function. Mesmerizing! I pulled out my phone and recorded a couple of videos.

One in landscape:

And one in portrait:

I didn't realize at the time that those video orientations would come in handy for a little post on this website.

Let's jump ahead a year to mid 2023. For years, many of us had been advocating for a simple, HTML-based way to serve video files in different sizes and formats using media queries—essentially how the picture element handles images. I won't rehash the entire history here, but that concept wasn't new or mine to claim. In fact, we once had exactly such a feature. It was a web standard, supported by all browsers, and it even inspired the design of the picture element—not the other way around. However, just as picture was on track to land, the video features that inspired it were removed from the HTML spec and supporting browsers (except WebKit). Many of us believed this was a mistake, as it left developers without an HTML-only solution to serve responsive, art-directed video content. Finally, sometime mid 2023, representatives from Chrome and Firefox agreed and expressed interest in reintroducing the feature, and "responsive video" was back on the standards track.

Jump forward to today: responsive video is once again part of the HTML standard and built back into browsers as well (I was able to contribute the commits to Firefox)! Now that it's back, we can use media attributes on HTML source elements within HTML video, which allow us to describe the conditions in which a particular version or format of a static video file should be downloaded and displayed. It's not meant to solve every video use case, but it's nice for many of them; particularly if you just want to serve an appropriate video file and can't be bothered (or aren't able) to set up HLS streaming.

In today's post, I want to show you how to use this feature to deliver my airplane video so that it's optimized for any viewport it happens to land on.

Let's start with the HTML: a video element with some sources. Below, I'm offering one video orientation or the other using media queries (check those media attributes on the source elements)!

<video autoplay controls playsinline muted loop>
  <source media="(orientation: landscape)" src="sunset-landscape-1080.mp4">
  <source src="sunset-portrait-1080.mp4">
</video>

Nice. We can do better, though. A 1080px-wide video is a large file to send smaller screens and mp4 isn't the smallest format we can offer for a high-quality video of any resolution. Let's use more media queries to offer some smaller video sizes for each orientation and a webm format for each source too, which I put first so that supporting browsers will pick it over the heavier mp4 alternative.

<video autoplay controls playsinline muted loop>
    <source media="(min-width:721px) and (orientation: landscape)" type="video/webm" src="sunset-landscape-1080.webm">
    <source media="(min-width:721px) and (orientation: landscape)" src="sunset-landscape-1080.mp4">
    <source media="(min-width:721px) and (orientation: portrait)" type="video/webm" src="sunset-portrait-1080.webm">
    <source media="(min-width:721px) and (orientation: portrait)" src="sunset-portrait-1080.mp4">

    <source media="(min-width:481px) and (orientation: landscape)" type="video/webm" src="sunset-landscape-720.webm">
    <source media="(min-width:481px) and (orientation: landscape)" src="sunset-landscape-720.mp4">
    <source media="(min-width:481px) and (orientation: portrait)" type="video/webm" src="sunset-portrait-720.webm">
    <source media="(min-width:481px) and (orientation: portrait)" src="sunset-portrait-720.mp4">

    <source media="(orientation: landscape)" type="video/webm" src="sunset-landscape-480.webm">
    <source media="(orientation: landscape)" src="sunset-landscape-480.mp4">
    <source media="(orientation: portrait)" type="video/webm" src="sunset-portrait-480.webm">
    <source media="(orientation: portrait)" src="sunset-portrait-480.mp4">
</video>

Nice! That's a hefty chunk of HTML to be fair, but it does demonstrate the power we're afforded through these features. The video below uses that exact markup, so depending on the size and shape of your viewport when you load this page, you'll be delivered an appropriate video:

It's worth reiterating a caveat here: responsive video works as you'd expect when you first load the page, but it does not reevaluate sources again after that, so you won't see sources adapt as you resize your browser for example. This is intentional: unfortunately, this first pass of reinstated responsive video support needed to match the behavior it formerly had, which only selected an appropriate video source at page load time. As far as I'm concerned, this is a bug that should be addressed. I've written about it and a few others here if you're interested.

Anyway, for now the native implementation falls a little short, but it handles the hard parts and we can make it a little better if we want to anyway!

Below, I'm wrapping the video in a little HTML Web Component I made called responsive-video, which will cause the browser to reevaluate its sources when media conditions change, and also keep the video timecode sync'd properly should a source video change. Markup-wise, it works like this, by wrapping the video and referencing a script:

<responsive-video>
    <video>
    ...sources go here
    </video>
</responsive-video>
<script type="module" src="responsivevideo.js"></script>

And here it is in action!

With that little helper component, our video adapts its size and orientation not only at load, but continuously through a session. Somebody tell YouTube Shorts and TikTok!

So now you know how to serve a video in portrait or landscape orientation declaratively with HTML. Happy Holidays.

Microdata for books

2024-12-18T00:00:00Z

by Alan Dalton

Dive into marking up books

Books are the best Christmas presents, especially for us web geeks. (I hope you’ll find a Web Accessibility Cookbook in your Christmas stocking, gentle reader.) Unfortunately, A Book Apart closed this year. Fortunately, the authors reacquired the rights to their books.

To track the authors’ preferred ways of making their books available, I created an “Authors Apart” webpage. For the HTML, I recalled the “‘Distributed,’ ‘Extensibility,’ & Other Fancy Words” chapter of Mark Pilgrim’s seminal Dive Into HTML5, which explains HTML’s microdata features. Mark wrote that article 13 years ago with a focus on Google Rich Snippets, and so I also referred to his unofficial guide to migrating Google Rich Snippets to schema.org and the more recent “Book” schema from Schema.org. Armed with that knowledge, here’s how I structured the HTML for each book to convey the name, URL, author’s name, author’s URL, original publishing date, date when the book was updated (if any), and whether it’s available for free:

<li itemscope itemtype="https://schema.org/Book">
	<div itemprop="name">
		<a itemprop="url" href="https://html5forwebdesigners.com/"><abbr title="HyperText Markup Language">HTML</abbr>5 for Web Designers</a>
	</div>
	<div itemprop="author" itemscope itemtype="https://schema.org/Person">
		<span itemprop="name">
			<a itemprop="url" href="https://adactio.com/">Jeremy Keith</a>
		</span>
	</div>
	<div itemprop="author" itemscope itemtype="https://schema.org/Person">
		<span itemprop="name">
			<a itemprop="url" href="https://x.com/rachelandrew/">Rachel Andrew</a>
		</span>
	</div>
	<time itemprop="datePublished">2010</time>, 
	<time itemprop="dateModified">2016</time>
	<div itemprop="isAccessibleForFree" content="true">🆓</div>
</li>

Why I like this HTML

I like this HTML because it conveys so much programmatically determinable information — check out the structured data! — using only 13 elements, and without compromising accessibility. In 2022’s Modern HTML as a foundation for progressive enhancement, Gaël Poupard asked, “What if we could improve the HTML stack […], making the markup step more resilient?” I consider microdata, like WAI-Aria, a valuable enhancement to HTML.

Mark’s article asked the reader to pay attention to each word in this sentence: “Microdata annotates the DOM with scoped name/value pairs from custom vocabularies.” The annotation is the enhancement: microdata won’t interfere with your usual best practices for HTML, and — as Doug Abrams explained in Mind The (Remediation) Gap — “The vast majority of accessibility lives in the markup.” Getting the name/value pairs right can involve some trial and error, but Mark’s book includes a helpful table that shows where microdata property values come from. You can probably spot those pairs in the HTML above. For example, itemprop="url" and href="https://html5forwebdesigners.com/" specify the URL for the HTML5 for Web Designers book, inside the a element. Notice how nicely this microdata plays with the existing HTML: I was also able to include an abbr element to explain the HTML abbreviation. For whatever content your webpage includes, you can probably find a useful schema in the surprisingly comprehensive full schema hierarchy. Schema.org’s Getting started with schema.org using Microdata is a useful, concise guide, and that site’s validator will instantly show you the structured data that you’ve added to your webpage with microdata.

A brief note on laziness

Christmas is a time for relaxing. Programming Perl names laziness, impatience, and hubris as the three great virtues of a programmer, and this code offers us a good opportunity to practice those. Using microdata schemas from Schema.org means that you probably won’t need to spend time thinking up class names or IDs to use in your CSS; instead, you can just write attribute selectors based on the microdata that you’ve added, like so:

[itemtype="https://schema.org/Book"] > [itemprop="name"] {
font-weight : bold;
font-size : large;
margin-bottom : 1em;
}

How microdata could help your users

I got ahead of myself there; the HTML design principles say to “consider users over authors”. So, here are some ways in which microdata can benefit your users:

Microdata could help users when they search the web

Mark Pilgrim’s “‘Distributed,’ ‘Extensibility,’ & Other Fancy Words” chapter concluded with a hypothetical search result in which the search engine shows not only an excerpt of the text from the webpage, but also some of the microdata that he added. That does seem useful: it lends some credibility to the search result, and so should allow users to more easily find what they’re looking for. This has persisted: Google Search Central’s Introduction to structured data markup in Google Search says that “Adding structured data can enable search results that are more engaging to users and might encourage them to interact more with your website […]”. To prove the point, Google Search Central’s case studies show how well-known organisations have used these techniques to improve search experiences for their users. However, the search engines may or may not show your webpage’s microdata. It doesn’t seem to have happened for my “Authors Apart” webpage yet, and I’m not suprised; Mark qualified his hypothetical example by saying, “And here (modulo the whims of Google, the phase of the moon, and so on and so forth) is what my review might look like in a search result listing”.

Microdata could help users when they use Artificial Intelligence tools

Similarly to Mark’s point about the whims of Google, Jono Alderson’s recent What if Schema.org is just… Labels? describes Google’s use of microdata as feeling “limited, selective, inconsistent, and often frustratingly opaque”. Jono goes on to highlight how the relationships that we define through microdata can help users who use AI tools. Of course, you might not consider this to be a net benefit: Molly White’s AI isn't useless. But is it worth it? weighs up the costs and benefits of these new tools.

Microdata could help your users by making HTML more prevalent

This is my favourite benefit of using microdata, even if it’s indirect. See, personally, I agree with the National Center on Disability and Access to Education’s Principles of Accessible Design when they said in 2007, “HTML is still the most accessible format for almost every type of content”. So, it seems to me that the more we use HTML, the more accessible our content is for our users. My favourite recent example of this is Knut Hühne’s microdata-enhanced HTML Webcomponent for Leaflet. (Leaflet is “an open-source JavaScript library for mobile-friendly interactive maps”.) In a nice piece of progressive enhancement, Knut uses microdata to mark up geographical data from an API, so that basic address information is available to everyone on every browser, and graphical maps are available too.

To quote Mark Pilgrim one more time, “Angle brackets don’t impress me much, but I have to admit, that’s pretty cool.’

How I gained a new perspective on ARIA

2024-12-17T00:00:00Z

by Marco Bretschneider

Can you remember the day you first learnt about ARIA? Maybe the first fact you learnt about ARIA was the first rule “Don't use ARIA, use native HTML instead“ - and so did I.

As someone who has been able to speak native HTML for many years, I always thought that ARIA is not relevant for a developer like me.
How incredibly wrong I was...

My “Wait a minute” moment

With the entry into force of the European Accessibility Act, accessibility has also become more important in our products, which are mainly used internally by banks.
For this reason, we have subjected our products to an accessibility audit.
One thing that really surprised me was that the auditor found fault with the following code.

<nav>
  <ul>
    <li>
      <a href="#">First navigation link</a>
    </li>
    <li>
      <a href="#" class="active">Second navigation link</a>
    </li>
    <!-- more navigation links -->
  </ul>
</nav>

.active {
  /* Highlight the selected navigation entry */
}

When it comes to supporting people with visual impairments, it is our job as developers to convey as much information as possible that we also display to sighted people.
People with visual impairments usually use a screen reader to consume the information on a page or application. A screen reader in turn obtains its information from the accessibility tree, which - together with the DOM tree - is generated in the browser.

The code example above represented in the accessibility tree

The information that the second entry in the navigation references the currently active page is not transported - unlike for sighted people.

A better approach

By using ARIA, we can influence how the browser builds the accessibility tree. Specifically, ARIA provides the aria-current attribute for highlighting the currently active page.

<nav>
  <ul>
    <li>
      <a href="#">First navigation link</a>
    </li>
    <li>
      <a href="#" aria-current="page">Second navigation link</a>
    </li>
    <!-- more navigation links -->
  </ul>
</nav>

[aria-current="page"] {
  /* Highlight the selected navigation entry */
}

Now, the information that the second navigation entry references the currently displayed page is also transferred to the accessibility tree and can be used by screen readers.

In addition, the aria-current attribute can also be used as a CSS hook for styling for sighted users. The active class initially used for this has therefore become obsolete.

Other examples

There are other examples where we can enrich the accessibility tree using ARIA attributes, such as error messages for form fields.

<label for="email">E-Mail</label>
<input type="e-mail" id="email" class="error">
<div>Enter a valid e-mail address</div>

The class error is used here to indicate fields that have been filled in incorrectly. For sighted users, the field is then styled accordingly using the class. Unfortunately, this information is not available in the accessibility tree.
There is also an error message, but it is only visually linked to the input field and not programmatically (e.g., the label is linked to the input field).
Unfortunately, we cannot enhance the accessibility tree with pure HTML. With ARIA, however, we can.

<label for="email">E-Mail</label>
<input type="e-mail" id="email" aria-invalid="true" aria-describedby="e-mail-error">
<div id="e-mail-error">Enter a valid e-mail address</div>

In the accessibility tree, we can see that the input field is marked as invalid and a relation to the error message is created.
Once again, we can use the aria-invalid attribute as a CSS hook for styling. An error class is not required anymore.

Conclusion

By using ARIA, we can influence the accessibility tree and enrich it with information that the browser cannot derive from native HTML. Screen reader vendors can use the information to create a better user experience for people who rely on assistive technologies.

The accessibility tree is built up of nodes that are typified by ARIA roles. The WAI ARIA specification recognises around 90 different ARIA roles. They were defined because there is a sensible use for each of them. By using native HTML, however, only half of these roles are met. We can use the role attribute to influence the types of the nodes in the accessibility tree and achieve the entire spectrum - if it is appropriate for the use case. Ignoring ARIA and ‘only’ using native HTML means that we are only using just under half of the richness that the accessibility tree provides.

I still don't know exactly when I heard about ARIA for the first time. But I can name the exact day when I had my wait a minute moment. Today, I know that the first rule of ARIA is often abbreviated and a crucial detail of the rule is lost. Certain things cannot be expressed semantically in HTML at all and if ARIA offers a possibility here, we should make use of it.

Perhaps we should see ARIA as a counterpart to CSS. While we use CSS to enrich our HTML document for sighted users (progressive enhancement), we can use ARIA to enrich the accessibility tree for non-sighted users.

You don’t need the isOpen class

2024-12-16T00:00:00Z

by Maureen Holland

Don’t get me wrong. You can keep it if you like it. But you don’t need it.

A class selector can allow us to visually show or hide content for disclosure widgets, like a custom select component or dropdown navigation menu. But a disclosure widget is made of two parts:

A button that controls show/hide behaviour
Related content that is shown or hidden depending on the button state

Whether the isOpen class is applied or not, a screenreader would announce this button as "Click me!, button".

<button>Click me!</button>
<p class="isOpen">Content that displays depending on a conditionally applied class.</p>

One of the principles of web accessibility is to be perceivable. That means not relying exclusively on one sense, like sight, to provide information. In the above case, if I can’t see the content being shown or hidden, how do I know my button click did anything?

We need a corresponding semantic update to indicate what happened. This is what the aria-expanded attribute provides.

The following button would read: "Click me!, expanded, button".

<button aria-expanded="true">Click me!</button>
<p>Content that displays depending on button's expanded state.</p>

This one would be "Click me!, collapsed, button".

<button aria-expanded="false">Click me!</button>
<p>Content that displays depending on button's expanded state.</p>

The aria-expanded attribute also provides a ready-made CSS selector for collapsed and expanded states. So, we don’t need to add an isOpen class at all.

If you’ve used the :checked pseudo-class before, you’ll be familiar with the idea of styling scoped to a particular state. It’s a good idea. As a bonus, you get a mini accessibility test in your CSS! The styles only apply if the semantics are correct.

button[aria-expanded="false"] + * {
 /* collapsed content styles here */
 display: none;
}

button[aria-expanded="true"] + * {
 /* expanded content styles here */
 display: block;
}

I first learned of this technique through Heydon Pickering’s Inclusive Components and have been using it ever since. It’s simple, effective, and a great way to keep accessibility in mind at every stage of development.

Note: You will not need aria-expanded on the HTML details element. Stateful information is automatically provided through its open attribute. See Scott O’Hara for more details on details.

The Gift You Do NOT Want: A Div in a Button's Clothing

2024-12-15T00:00:00Z

by Corina Murg

With the right CSS makeup and a click event, almost anything can pretend to be a button. In accessibility work, we spot these fakes and fix them, but teaching others why and how to do it is just as important. It’s not just about correcting a single mistake; it’s about introducing developers to accessibility concepts and approaches that they can comfortably return to and reuse across all their projects. More importantly, it encourages them to think beyond the sighted user with a mouse and consider the needs of those who rely on assistive technologies.

Really, How Bad Can a Fake Button Be?!

So, how do we answer this question? I used to demo the problems using a screen reader, but I've found that it can be overwhelming for developers new to accessibility. I prefer now a different approach, using simpler tools: the keyboard and the accessibility tree. They are easy to pick up and give developers a good feel for what’s really going on.

No, the message is not to avoid screen readers, but to start with tools that have a gentler learning curve. The tree itself gives developers plenty of clues about how each node may (or may not!) be recognized by assistive tech like screen readers or voice recognition software. And for whatever the tree can’t reveal, keyboard testing can fill in some of the gaps.

Of course, no tool is perfect, and the accessibility tree does have its limitations. It’s important that we remind developers of them as well. So, what exactly does this approach entail?

Build a Genuine Button with a `<button>`

<button type="button" class="button one">
    Change Color ONE
</button>

function changeColor(event) {
    const element = event.currentTarget; 
    const currentColor = getComputedStyle(element).backgroundColor;
    element.style.backgroundColor = currentColor === 'rgb(0, 128, 0)' ? 'rgb(58, 58, 242)' : 'rgb(0, 128, 0)';
}

const buttonOne = document.querySelector('.button.one');
buttonOne.addEventListener('click', changeColor);

First, we create a genuine button using the <button> tag, and then examine how it appears in the accessibility tree. We focus on the attributes and properties exposed for this node, discussing what each one means in terms of interaction with assistive technologies. At every step, we also test with a keyboard.

Note: I regularly work on a Windows computer and am familiar with the accessibility tree in both Firefox and Chromium browsers. For this exercise, I’ll mostly use Firefox since it offers some clues about the shortcomings of fake buttons.

So, what is the view from the accessibility tree revealing?

The node has the role button, which comes with some privileges: it will be announced as a button by a screen reader, and since buttons support name from content, its text becomes its accessible name. So, a screen reader will announce it as Change Color ONE, button. Users relying on voice recognition software can activate it by voice command, such as saying Click Change Color One.
The states array shows that the button is focusable, so we know we can reach it via the tab key.

But where does the keyboard come in? It helps us confirm the focusable property by allowing us to navigate to the button with the tab key. Plus, it confirms that we can activate the button using the Enter key or the Space bar, another built-in perk of genuine buttons that is not immediately obvious from the accessibility tree.

Next step: build a fake button.

Build a Fake Button with a `<div>`

<div class="button two">
    Change Color TWO
</div>

const buttonTwo = document.querySelector('.button.two');
buttonTwo.addEventListener('click', changeColor);

We simply attach a click event to a div, and with nearly the same CSS as we’d use for a genuine button, we create something a sighted user will recognize as a button.

Here’s the view from Firefox’s accessibility tree:

What should we be looking or testing for? The same attributes and behaviors we found for the genuine button:

role,
name,
focusable property, and
keydown and keyup events.

The node’s role defaults to generic since the building block is a div. It also remains unnamed because generic nodes don’t have naming privileges, despite containing text. Keyboard users will not reach it, let alone activate it, and we don’t even have to test with a keyboard to prove it. We simply notice that the states array does not list the focusable property.

Once we make it focusable by adding a tabindex="0" we notice something else: we can't activate it with the Enter key or the Space bar. Is this lack of functionality reflected in the accessibility tree as well? Sort of. The genuine button lists a Press event under the actions property, while the fake button only shows Click. But more on that later.

Firefox is also explicitly warning us about the lack of focus and "interactive semantics", and it's connecting us to MDN for more information. So, what are we still missing? We need:

a keydown event for activation via Enter,
a keyup event for activation via Space, and
a button role to have it announced properly by screen readers, and also to assign it a name based on its content.

Here's what the HTML would look like with all the additions:

<div class="button two" role="button" tabindex="0">
    Change color TWO
</div>

while the JavaScript would have to include the following as well:

buttonTwo.addEventListener('keydown', function(event) {
    if (event.key === 'Enter') {
        event.preventDefault();
        changeColor(event);
    }
});

buttonTwo.addEventListener('keyup', function(event) {
    if (event.key === ' ') {
        event.preventDefault();
        changeColor(event);
    }
});

For developers it might seem tempting to add these missing features one by one. The advice, of course, is that the simpler and more robust solution is to replace the <div> with a <button>. However, for the sake of exploring what the accessibility tree reveals — or fails to! — and the importantce of manual testing, we’ll go ahead and add all the necessary code to make this div fully functional.

The Accessibility Tree Can Only Do So Much

Is the retrofitted div recognized as a button now? Yes. It has the role button, it has a name, and it's focusable.

Is the retrofitted button's tree view different in any way from the one of the genuine button? Yes again.

First, the DOMNode property reminds us that we started with a div. Next, something curious happens within the actions array.

Since we’ve added the keydown and keyup events we would not expect any differences between the actions arrays of the two buttons, right? Wrong. The updated view still shows Click instead of Press. It seems that manually adding the keyboard events does not change the action keyword. But is this a Firefox oversight, or just a subtle dig at fake buttons? Just kidding!

It's worth noting that the Chromium browsers also take the approach of differentiating between the two buttons. They do not display this information as part of the accessibility tree, but separately, under the Event Listeners tab in DevTools. For the genuine button, their keyword of choice is click and not Press, but then, just like Firefox, they treat the div button differently. When keyboard events are explicitly added, Chromium’s event listeners include click along with keydown and keyup.

The Chromium behavior makes sense: when we attach a click handler to a native button, it automatically works for all input methods (mouse, touch, keyboard). That's why it only shows one click listener linking to one particular function. For the div button, since we manually added separate keyboard handlers, DevTools shows links to all three function implementations - one for click and two for keyboard events.

But enough nerding over keywords and browser inconsistencies, as interesting as this detective work might be. The point to make is that on keyboard interactions the browsers send mixed signals, and that testing, in this case keyboard testing, is irreplaceable. (Is this my subtle way of turning your attention away from the fact that I don't have (yet!) an explanation about these inconsistencies? Totally! I've spent time poking around the Firefox and Chromium codebases, but so far the answer remains a mystery.)

Let's end with a keyboard interaction anomaly that only keyboard testing could reveal: while theoretically both buttons are now fitted with proper keyboard support, there's an important difference in how they handle the keyup event. The benefit of a keyup event is that the user can cancel the action on a button. They can press Space, change their mind, move focus away with Tab, and release Space without triggering the button. When we build our own button from a div, we need extra code to track whether the Space key was initially pressed while focused on that button. Without this check, it would incorrectly activate when receiving focus while Space is being released, even if Space was originally pressed on a different element. And while we add more code to our creation, the browsers will, of course, take good care of the genuine button and gracefully ignore Space keyup events that don't belong to it.

Takeaways for Developers

Semantic HTML is powerful. Always consider it first.
No tool is perfect, and the accessibility tree and the DevTools in general are no exception. Testing is key. In our particular case, testing with the keyboard is enough, but in other scenarios testing with a screen reader will be necessary. In general, accessibility requires a holistic approach and that we select tools and tests based on the specific functionality we are assessing.

Wrapping Up

Does this approach work? At the minimum, it introduces developers to the accessibility tree and reinforces the usefulness of a familiar tool, the ubiquitous keyboard. If it ends with "Now I know I shouldn't just add a click event to a div" then yes, it does work.

From experience, it can sometimes make developers nervous about their ability to choose the right tools or worry about overlooking crucial details. This is still a win. It shows that they care. If you've had any accessibility mishaps in your past, this might be actually a good moment to reveal them, and prove that progress is possible. If you've had none, feel free to use one of mine: before I started using screen readers, I used to add a tabindex to headings.

What should we encourage developers to focus on, no matter their initial reaction? Know their HTML, consider the needs of different types of users, lean into testing. And ask questions.

Page by Page: How Pagination Makes the Web Accessible

2024-12-14T00:00:00Z

by Kristin Rohleder

Imagine you’re reading a book that seems perfect for cozy winter evenings. But as soon as you turn the page, you suddenly find yourself somewhere else, rather than on the next page of the story. Now, you have to painstakingly search through the book to find where the story continues — as if someone had bound the pages in the wrong order.
Would you keep reading? Or recommend the book to others?

For about 16% of the world’s population (roughly the population of China), the web often feels like a maze. People who rely on assistive technologies experience the web like a poorly bound book, one they must tediously navigate page by page rather than simply moving to the next relevant section.

Another example: imagine you're searching on Google and find the answer on page 2. However, to get there, you first need to enter the Konami Code to unlock the link. Such obscured navigation elements are, unfortunately, a daily reality for many web users.
On some websites, pagination links are hidden behind inaccessible images without labels, or they use faulty ARIA attributes that make navigation difficult for screenreader users.

While an accessible pagination doesn't make the entire web accessible, it does ensure that everyone, whether reading a book or browsing the web, can seamlessly turn from page to page and easily find the next part of the story.

Pagination I

Let’s start with a simple example — a pagination that’s perfect for smaller blog pages or product overviews with a limited number of items.

<nav aria-label="More Christmas cookie recipes">
  <ul>
    <li>
      <a role="link" aria-disabled="true">Previous</a>
    </li>
    
    <li>
      <a href="#" aria-current="page">1</a>
    </li>
    
    <li>
      <a href="/2/">2</a>
    </li>
    
    <li>
      <a href="/3/">3</a>
    </li>
    
    <li>
      <a href="/4/">4</a>
    </li>
    
    <li>
      <a href="/5/">5</a>
    </li>
    
    <li>
      <a href="/2/" aria-label="Next, Page 2">Next</a>
    </li>
  </ul>
</nav>

Clear Page Structure

The <nav> element with a descriptive aria-label provides orientation for screenreader users and makes the page structure immediately recognizable.
If <nav> cannot be used, the root element of the pagination can be assigned role="navigation" to ensure assistive technologies interpret the navigation correctly.
Distinct aria-labels (e.g. "Pagination of product listings" or "More cookie recipes") help differentiate between navigation areas and provide additional context for the links.

Using <ul> or <ol> for Flexibility

A list can improve the user experience for screenreader users. However, screenreaders interpret <ul> and <ol> differently, which can lead to confusion depending on the context:
- With a <ul> element, a link to the second page might be read as "Bullet, Link, 2," signaling that the pages are considered equal and no strict order is implied.
- With an <ol> element, the same link might be read as "3, Link, 2," because the position within the list (in this case, the third <li> element) is also announced. This can be confusing when the announced number doesn’t match the actual page number in the link, such as in paginations that begin with additional links like “Previous.”
For small, sequential navigation, such as a multi-page news article, an <ol> is a good choice. Here, the announced order matches the page structure, helping assistive technologies convey the context. For non-linear content, where order doesn’t matter—like pages with multiple Christmas cookie recipes—a <ul> can be the better option.

Proper Deactivation

A disabled link, such as “Previous” to the first page, should not have an href attribute. Since the disabled attribute only applies to form controls like <button>, aria-disabled="true" is used instead.
Additionally, the role="link" attribute should be added to explicitly define the element’s role as a link. An <a> element without an href attribute does not have a specific default role and is treated inconsistently by assistive technologies. The combination of aria-disabled="true" and role="link" ensures that the link is correctly perceived as disabled without being mistakenly interpreted as “clickable.”
Alternatively, a <span> element can replace the link, e.g. <span>Previous</span>. This method is considered a best practice because it simplifies the code and minimizes the use of ARIA attributes. This aligns with the principle that native HTML elements and semantic structures should be preferred to improve code maintainability and clarity. Both approaches are valid as long as they are implemented correctly.

Intuitive Navigation

The aria-current="page" attribute indicates which page is currently open. Screenreaders interpret this as “Current page, Link, 1” or similar. This helps users quickly orient themselves and easily identify which page they are on.

Clear Link Descriptions

A visible link text such as “2” for the second page is sufficient for assistive technologies and their users to interpret the link correctly. However, if an additional aria-label="Page 2" were added, the link would be announced by screenreaders as “Page 2”.
Sighted users relying on voice control might attempt to activate the link by saying “2” because they see that number. The voice control software, would not find the link because the link name (accessible name) does not match the visible text. To avoid this, the visible text should always be identical to the accessible name.
Furthermore, the aria-label of the surrounding <nav> element (e.g. aria-label="More pages of product listings") already provides the necessary context that the links are for pagination.
An exception can be made if the visible link text is integrated at the beginning of the aria-label, such as aria-label="next, page 2". Here, “next” comes first to describe the function of the link, while “page 2” provides additional context. This structure is helpful as it emphasizes where the link leads.

Pagination II

Let’s look at a pagination that’s particularly suited for blog pages with many entries or product listing pages with extensive products. This advanced pagination allows users to skip multiple pages in the display while maintaining a clear structure.

This pagination builds on the principles of the simple pagination. The same recommendations for using <nav>, <ul>, aria-label, aria-current, and aria-disabled apply here as well.

/* styles for elements that are only relevant for screenreader users */
.sr-only {
	position: absolute;
	width: 1px;
	height: 1px;
	padding: 0;
	margin: -1px;
	overflow: hidden;
	clip: rect(0, 0, 0, 0);
	white-space: nowrap;
	border-width: 0;
}

<nav aria-label="More Christmas cookie recipes">
  <ul>
    <li>
      <a href="/1/">
        <span class="sr-only">First Page</span>
        <svg role="presentation" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24">
          <path d="M14 18l-6-6 6-6L12.59 4 6.59 10 12.59 16 14 18z" />
          <path d="M20 18l-6-6 6-6L18.59 4 12.59 10 18.59 16 20 18z" />
        </svg>
      </a>
    </li>

    <li>
      <a href="/7/">
        <img src="previous-page-icon.png" alt="Previous Page, Page 7" />
      </a>
    </li>

    <li>
      <span>...</span>
      <span class="sr-only">skipping pages 1 to 6</span>
    </li>

    <li>
      <a href="/7/">7</a>
    </li>

    <li>
      <a href="#" aria-current="page">8</a>
    </li>

    <li>
      <a href="/9/">9</a>
    </li>

    <li>
      <span>...</span>
      <span class="sr-only">skipping pages 10 to 12</span>
    </li>

    <li>
      <a href="/9/">
        <img src="next-page-icon.png" alt="Next Page, Page 9" />
      </a>
    </li>

    <li>
      <a href="/12/">
        <span class="sr-only">Last Page, Page 12</span>
        <svg role="presentation" xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24">
          <path d="M10 6l6 6-6 6 1.41 1.41L18.41 12 11.41 4.59 10 6z" />
          <path d="M4 6l6 6-6 6 1.41 1.41L12.41 12 5.41 4.59 4 6z" />
        </svg>
      </a>
    </li>
  </ul>
</nav>

Using SVGs

Icons should always have descriptive text to make their function clear for screenreader users. Instead of describing the SVG itself (e.g. “Double arrow pointing left”), the purpose should be communicated (e.g. “First page”).
Using a <span> element with the screenreader-only class .sr-only can be a practical approach. This class hides the text visually for sighted users but makes it accessible to screenreaders. In certain cases, it may have an advantage over using an aria-label on the <a> element because screenreaders read the text with the correct language and pronunciation preferences.
- Tested Behavior: When using NVDA (Version 2024.4) with Chrome (Version 130) and German as the language preference, English text in an aria-label was read with a German voice and pronunciation. However, when the text was provided via the .sr-only class, it was read correctly with an English voice. This behavior also has been documented in NVDA GitHub Issue #16285.
- With VoiceOver on macOS, no difference between the two methods was observed.
- Note: This has not been tested with JAWS or other screenreaders and may vary depending on the browser and screenreader combination.
The role="presentation" attribute should be added to SVG elements to prevent some screenreaders from announcing them as standalone elements (e.g. “Link, Image, First page”). This ensures they are interpreted as purely decorative and not announced (e.g. “Link, first page”).

Using Images

When an <img> element is the only child of a link, the text of the alt attribute is automatically read by screenreaders as the link text. Therefore, the alt attribute should include a descriptive text that clearly conveys the function of the link (e.g. alt="Next Page, Page 9"). This method is a best practice as it is natively supported by screenreaders and requires no additional effort.
If it is not possible to modify the alt attribute of the image due to technical constraints, an aria-label on the <a> element can be used instead to describe the function of the link. However, this solution should only be applied in exceptional cases.

Skipping Multiple Pages

In reading mode, screenreaders typically do not announce ellipses (“...”) used to indicate skipped pages. Instead, the list item is often read as an empty bullet, which can confuse users as it does not explain why no additional information is provided at that point.
To ensure that skipping pages is clearly communicated, an explanatory text such as “skipping pages 10 to 12” should be added using the screenreader-only class .sr-only. This text will be read by screenreaders but remain invisible to sighted users. An aria-label is not a suitable alternative here, as it cannot be applied to generic elements like <span> or <div>.
This approach is particularly helpful when page skipping occurs in the middle of pagination, as it provides screenreader users with context and prevents confusion about why navigation jumps from one page (e.g. page 2) to another (e.g. page 7). The additional context improves orientation and reduces potential misunderstandings.

The final chapter

Accessible pagination is more than just a design detail—it provides orientation, simplifies navigation, and greatly improves the user experience, especially for those relying on assistive technologies.

The semantic HTML elements and ARIA attributes presented here create an accessible structure that remains easy to use across all devices, from desktop to smartphone.

Accessible pagination ensures that all users can navigate the web without "getting lost as if reading a book with pages bound out of order." This makes the web not only more inclusive but also more accessible for everyone looking to find content efficiently and directly.

Testing and validation

To ensure the proposed solutions deliver on their promise, I conducted tests in different environments:

HTML Validation: The code was tested using the W3C HTML Validator with no errors or warnings found.
Tested on AssistivLabs, a platform for remote testing of assistive technologies:
- Screenreader: NVDA (Version 2024.4)
- Browser: Chrome (Version 130)
Tested on a real device:
- Operating System: macOS 15.1.1
- Screenreader: VoiceOver
- Browsers: Chrome (Version 131) and Firefox (Version 133)

However, additional testing with other screenreader and browser combinations is recommended to ensure compatibility across a wider range of devices and tools.

Improving User Experience for Multilingual Web Browsing

2024-12-13T00:00:00Z

by Anastasiia Batarei

Today, I’d like to talk about the experience of browsing websites where content is fully or partially in a language different from the user’s native one. This situation is common for users navigating government portals or local service providers in a country where they don't speak the language well, and for international marketplaces, where essential information might appear in unfamiliar language. Or just a user has a different language preference set in their browser because it's convenient for them. In these cases, users often rely on the browser’s auto-translate feature, which many modern browsers offer by default. When you open a page in a different language from your preferred setting, the browser will prompt you to translate it automatically.

Browser auto-translation relies on the lang attribute set on the HTML element:

<html lang="en"></html>

However, automatic translations can sometimes be inaccurate or misleading, especially when it comes to proper and branded names, or technical terms that should remain untranslated.

For example, let’s see what happens when a user’s name, like Joke (a Dutch feminine name pronounced [ˈjoːkə]), is displayed on an English page that is then auto-translated into Dutch:

<!-- Original content in English -->
<p>Name: Joke</p>

<!-- Translated content in Dutch -->
<p>Naam: Grap</p>

The Dutch word “Grap” means “joke” — a thing said to cause amusement — turning the name into something unintended and causing confusion.

To prevent such misinterpretations, we can use the translate attribute, which indicates whether an element content should or should not be translated. The attribute can appear on any element, and it takes just two values: yes or no. In our case, we need to use the value no to disable automatic translation for specific pieces of content:

<!-- Original content in English -->
<p>Name: <span translate="no">Joke</span></p>

<!-- Translated content in Dutch -->
<p>Naam: <span translate="no">Joke</span></p>

Translation in Context

Translation engines have improved significantly over time and can often understand whether certain content, like email addresses or well-known names (e.g., Pain au chocolat), should be translated or not. However, it's still crucial to manually test your content to avoid unexpected issues. For instance, email addresses that appear as part of a search results page might be wrapped in additional HTML tags, which can cause translation errors. Let’s compare these two examples:

<!-- Original content in English -->
<p>E-mail: joke@example.com</p>
<p>E-mail: <mark>joke</mark>@example.com</p>

<!-- Translated content in Dutch -->
<p>E-mailadres: joke@example.com</p>
<p>E-mailadres: <mark>grap</mark>@voorbeeld.com</p>

The issue can be easily avoided by using the translate="no" attribute to ensure that the email address stays untranslated:

<!-- Original content in English -->
<p>
  E-mail: <span translate="no"><mark>joke</mark>@example.com</span>
</p>

<!-- Translated content in Dutch -->
<p>
  E-mailadres: <span translate="no"><mark>joke</mark>@example.com</span>
</p>

With this adjustment, the display remains accurate across languages, preventing incorrect translations and enhancing user trust. Misleading translations can create uncertainty and may cause users to double-check information unnecessarily, impacting accessibility, usability, and overall experience. Ideally, users should navigate with confidence, and as developers, we can do this small trick to make their experience smoother.

Non-standardized approach

Before the translate attribute was part of the HTML specification, translation engines offered similar tools. For example, Google and Microsoft’s translation engines support the class notranslate, which worked similarly:

<p>Name: <span class="notranslate">Joke</span></p>

However, using the translate="no" attribute, which is now part of the HTML specification, is a more robust and reliable approach, ensuring consistency across current and future translation APIs and localization standards.

Note: All examples were tested in Chrome Version 129.0.6668.103 (Official Build, x86_64).

HTML and CSS I didn't even know about before I started creating content in Japanese

2024-12-12T00:00:00Z

by Julia Undeutsch

Since I started to create content in Japanese, I also wanted to learn about traditional setups, like having Japanese text flow from top to bottom, right to left, like you’d see in newspapers or novels. That's when I discovered CSS properties like writing-mode: vertical-rl and HTML tags like <ruby>, which add furigana (phonetic guides) over kanji characters.

Honestly, I’d never used these properties before and almost forgot they even existed! But now that I’ve dived into them, I’ll break down how you can implement them step-by-step to get that traditional Japanese look.

That's the text we'll work with. It means "Example of vertical text. Japanese culture is very rich.":

縦書(たてが)きのテキストの例(れい)

日本(にほん)の文化(ぶんか)はとても豊(ゆた)かです。

Step 1: Setting Up Vertical Text with CSS

First up, we’ll make the text flow vertically from right to left, top to bottom. The CSS property writing-mode: vertical-rl is perfect for this. It’s how you make Japanese text look like it’s traditionally printed.

.vertical-text {
  font-size: 2rem; /* Adjust font size as needed */
  letter-spacing: 0.2em; /* Ensures legibility */
  line-height: 1.5; /* Adjust line height for spacing */
  text-orientation: mixed; /* Allow for mixed orientation (e.g., hiragana and kanji) */
  writing-mode: vertical-rl; /* Set writing mode to vertical, right to left */
}

縦書(たてが)きのテキストの例(れい)

日本(にほん)の文化(ぶんか)はとても豊(ゆた)かです。

writing-mode: vertical-rl: This property turns the text to vertical, flowing from the top to bottom, starting on the right side of the page.

text-orientation: mixed: This keeps kanji and other characters readable. Japanese text often mixes different character types, so mixed is generally the best setting here.

font-size, letter-spacing and line-height: Adjust these to make the text readable and nicely spaced.

Step 2: Adding Margins for Better Spacing

When working with vertical text, you can add spacing between blocks with margin-block. This CSS property acts like margin-top and margin-bottom for horizontal text, and margin-left and margin-right for vertical text.

ruby rt {
  font-size: 0.7rem;
  margin-block: 1px; /* Adds some space between text and ruby text */
}

The property comes in very handy when working with multiple languages on your website, because it adjusts spacing based on the flow direction of the text.

Step 3: Adding Furigana with `<ruby>`

In Japanese, furigana (small hiragana or katakana text) is often placed above kanji characters to show pronunciation. We can add furigana with the <ruby> and <rt> tags, which are specifically meant for this purpose.

Here’s how to add furigana:

<div class="vertical-text">
  <ruby>日本<rp>(</rp><rt>にほん</rt><rp>)</rp></ruby>
  の<ruby>文化<rp>(</rp><rt>ぶんか</rt><rp>)</rp></ruby> はとても<ruby
    >豊<rp>(</rp><rt>ゆた</rt><rp>)</rp></ruby
  >
  かです。
</div>

縦書(たてが)きのテキストの例(れい)

日本(にほん)の文化(ぶんか)はとても豊(ゆた)かです。

<ruby>: Wraps around the kanji characters.

<rt>: Contains the furigana, displayed above the kanji.

<rp>: Provides fall-back parentheses for browsers that do not support display of ruby annotations.

Step 4: Putting It All Together

Now, let’s combine everything in a full HTML example. This includes vertical text styling, spacing, and furigana for a traditional Japanese feel:

<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="UTF-8" />
    <title>Vertical Japanese Text Example</title>
    <style>
      * {
        margin: 0;
      }

      body {
        display: flex;
        justify-content: flex-end;
        padding: 25px;
      }

      .vertical-text {
        font-family: "Noto Sans JP", sans-serif;
        font-size: 1.5rem;
        letter-spacing: 0.2em;
        line-height: 1.5;
        text-orientation: mixed;
        writing-mode: vertical-rl;
      }

      h1 {
        font-size: 2.5rem;
        margin-block: 10px;
      }

      ruby rt {
        font-size: 0.7rem;
        margin-block: 1px;
      }
    </style>
  </head>
  <body>
    <div class="vertical-text">
      <h1>
        <ruby>縦書<rp>(</rp><rt>たてが</rt><rp>)</rp></ruby>きのテキストの<ruby
          >例<rp>(</rp><rt>れい</rt><rp>)</rp></ruby
        >
      </h1>
      <p>
        <ruby>日本<rp>(</rp><rt>にほん</rt><rp>)</rp></ruby>の<ruby
          >文化<rp>(</rp><rt>ぶんか</rt><rp>)</rp></ruby
        >はとても<ruby>豊<rp>(</rp><rt>ゆた</rt><rp>)</rp></ruby>かです。
      </p>
    </div>
  </body>
</html>

And there you have it! With just a few CSS properties and HTML tags, you can transform your text to reflect a more traditional Japanese reading style.

実験を楽しむ！

Enjoy experimenting!

See the Pen Japanese Example by Julia Undeutsch (@YuriDevAT) on CodePen.

Resources

Makeshift hot reload

2024-12-11T00:00:00Z

by Evan Hahn

In short: put <meta http-equiv="refresh" content="1"> in your <head> element to refresh your page every second. This is a makeshift "hot reload" for development. It's not perfect, but it can be a quick solution!

Hot reloading automatically reloads parts of your page while you're working. Change some HTML and see your work instantly! Tweak some CSS and the results are right there! Gone are the days of repeatedly switching to your browser to refresh, because hot reload takes care of it.

It's called "hot" reloading because it's hot. It's powerful. Everyone loves it.

But here's the problem: hot reload requires fancy build tooling. It's built into tools like Vite, Parcel, and various editor plugins. But what if you aren't using one of these? What if you're writing HTML the way God intended: by editing some damn files on disk? In other words, without a build tool?

Can you still get that hot, hot reloading?

Home-grown hot reload

You can create a makeshift hot reload by putting this somewhere in your <head> tag:

<!-- Reload the whole page every second. -->
<meta http-equiv="refresh" content="1">

Adding this will make the whole page reload every second.

Now, when you edit some HTML, you'll only have to wait a second before you see your changes. When you tweak your CSS, you'll see the results promptly.

This simulates the Refresh HTTP response header, instructing browsers to reload the page after a certain number of seconds. You can change the duration if it's reloading too often for your taste; I find that 2 seconds is my sweet spot.

When you're all done, you should remove this tag so that the page doesn't reload for your users.

This isn't as powerful as hot reloading, to be sure. This primitive solution has a lot of drawbacks:

It's usually slower than real hot reloading.
It can't intelligently swap out parts of your app, and instead brutally reloads the whole page.
It can mess with any state you've set up, such as scroll position.
It also refreshes the browser's developer tools, making them difficult to use.
If you use a screen reader, it's likely that this constant reloading will mess things up.

Despite the disadvantages, this solution has one big plus: it's a single line of HTML that doesn't require any additional tooling. This minimal solution can be useful if you just need something simple. And that's hot.

Submit to the Quirks of HTML

2024-12-10T00:00:00Z

by Felix Hessenberger

It was on a cold February evening. I had been working on a client project, building an order item list—nothing out of the ordinary. To adjust an item’s quantity, the user would open a popup form with a single input field, type a number, and hit enter.

<form>
  <label>
    Quantity
    <input type="number">
  </label>
</form>

Everything worked as intended when suddenly, a new requirement came in: add another input field to also set a bulk quantity. I did what I was told, but to my horror, the form wouldn’t submit anymore with the new field displayed! 😱

I checked the browser console for any JavaScript errors and double-checked my markup, but to no avail. A quick detour to Stack Overflow shed light on the situation: according to the HTML 2.0 spec, it's a feature, not a bug:

When there is only one single-line text input field in a form, the user agent should accept Enter in that field as a request to submit the form.

Some Web archeology later, I found myself pretty deep down the rabbit hole about whether a form will submit on enter:

Single-line text input: YES!, according to the discussion linked above, this was seen “as a convenient way to submit simple queries”.
Other input types: YES!, number, email, password, search, tel, and url all are regarded as single-line text inputs; input types not recognized by the browser (e.g. month in Firefox at the time of writing), are treated like single-line text inputs.
One single-line text input together with any other fields that are not a single-line text input: YES!, you can add any other form elements including input types like date or color, even a textarea) and the form will still submit on enter (when the focus is on the text field).
A second single-line text input in a different form: YES!, it’s not about how many inputs are on the page; each form is considered individually.
More than one single-line text input in the same form: NO! of course not! 😅 This is, according to the discussion mentioned above, aimed at “reducing the risk, on a complex form, of prematurely submitting it while trying to fill it in.“.

Try the above examples on CodePen

The reason I didn’t encounter this behavior before seems to be that I’ve never built a form with only one text field; even in a simple chat component, there typically is at least a submit button to send the message. And indeed, adding a submit button magically solves the problem:

<form>
  <label>
    Quantity
    <input type="number">
  </label>
  <label>
    Bulk quantity
    <input type="number">
  </label>
  <input type="submit" hidden>
</form>

To extend on the list above:

<input type="submit">: YES!, a submit button enables submit on enter in forms with more than one text input.
<input type="submit" hidden>/<input type="submit" style="display: none;">: YES!, the button may be hidden (which I did above to preserve the original appearance).
<button>: YES!, the button element works as well. (type="submit" is the default for buttons within a form.)
<button disabled>: NO!, disabling the submit input/button also disables submitting on enter.
<button type="button">: NO!, it may look the same, but now there is no way to submit the form anymore.

Try the above examples on CodePen

All points listed in this article are the same across browsers; interestingly, the behavior of the submit button isn’t defined anywhere in the HTML spec—it was initially just copied from Internet Explorer and Netscape for consistency (like discussed in this 23 year old (and still open) Firefox issue). However, as outlined in this article, the behavior can effectively be derived from combining the WCAG’s recommendation that all forms should include a submit button and the HTML spec’s rule that the enter key should submit the form implicitly.

Bonus fact: The default keyboard on Android has a button that looks like an enter key, but it only submits the form when the last text field in the form is focused—otherwise, it moves focus to the next text field. It doesn’t move the focus to any other form inputs.

This is a nice example that even after more than a decade of working with HTML, I still sometimes encounter unexpected quirks that, after a bit of digging, often turn out to be well-thought-out gems (for the most part).

Native HTML light and dark color scheme switching

2024-12-09T00:00:00Z

by Vadim Makeev

It’s getting dark early in Berlin in the winter. It’s not even close to evening, but my OS and all apps have already switched to dark mode. Well, not all of them, unfortunately. And that’s the thing: dark mode has become a quality-of-life feature for many users, and I often try to avoid using apps or websites that haven’t implemented it, especially in the evening. They literally hurt my eyes!

When it comes to color scheme implementations, they range from rather useless ones that require a page reload to more sensible ones that query the prefers-color-scheme media feature and apply changes in CSS on the fly:

body {
  background-color: #ffffff;
  color: #000000;

  @media (prefers-color-scheme: dark) {
    background-color: #000000;
    color: #ffffff;
  }
}

This approach is already a good start. But it only covers the simplest case and doesn’t allow users to choose a different color scheme for this specific website. Just like light color schemes hurt my eyes in the evening, many people are not comfortable with dark schemes or with particular ones that aren’t good for them. So, it’s all about user choice.

Currently, there’s no way to directly override a user’s OS preference if you want to offer a scheme selector on your page. Fortunately, in the CSS Media Queries Level 5 spec, there’s a PreferenceManager interface that will solve this problem. Meanwhile, the most popular solution these days is to use JavaScript to set an attribute like <html data-scheme="dark"> reflecting the forced scheme and use it in CSS:

body {
  background-color: #ffffff;
  color: #000000;

  [data-scheme='dark'] & {
    background-color: #000000;
    color: #ffffff;
  }
}

This approach always seemed hacky to me. However, if you know HTML well enough, there are a few much more convenient native options available.

Setting the CSS color-scheme

If you ever fall into the dark scheme rabbit hole, the first thing you’ll learn is the color-scheme CSS property. It’s essential for setting the scene for everything else. Most importantly, it turns on the browser’s default dark scheme support. Which, unfortunately, browsers can’t enable by default for backward compatibility reasons.

:root {
  color-scheme: light dark;
}

The light dark value means that we’re choosing to support both light and dark schemes in our code. The property will be inherited down the document tree, and the browser will enable some default styling for built-in primitives when needed. Thank you, browser!

Default browser dark styles enabled by the color-scheme: light dark property.

When switching your schemes, it’s important to switch the value of this property, too: set color-scheme: light on the root along with light styles and the other way around for the dark ones. Remember this, it’ll come in handy later.

And somewhere along these lines, you’ll probably read that you can also set this mode right in HTML using the <meta> element. Why would you do that? Oh well, who knows? Maybe you don’t use CSS or whatever. So silly, right?

<meta name="color-scheme" content="light dark">

It turns out that it’s not just a flag for the browser but a tool you can use to force color schemes using JavaScript! But only if you use the fairly new light-dark() CSS function.

Switching the HTML color-scheme

Remember the earlier example with media queries and ‌prefers-color-scheme?

body {
  background-color: #ffffff;
  color: #000000;

  @media (prefers-color-scheme: dark) {
    background-color: #000000;
    color: #ffffff;
  }
}

You can also express the same idea like this:

body {
  background-color: light-dark(#ffffff, #000000);
  color: light-dark(#000000, #ffffff);
}

Here’s the three-position switch I often use. Along with “light” and “dark” options that force a certain scheme, there’s also the “auto” option that gives the control over the color scheme back to the OS, selected by default.

<section aria-label="Color scheme switcher">
  <button aria-pressed="false" value="light">
    Light
  </button>
  <button aria-pressed="true" value="light dark">
    Auto
  </button>
  <button aria-pressed="false" value="dark">
    Dark
  </button>
</section>

And to make it all work, a simple script that takes the button’s value and sets it to the <meta name="color-scheme">:

const colorScheme = document.querySelector('meta[name=color-scheme]');
const switchButtons = document.querySelectorAll('button');

switchButtons.forEach(button => {
  button.addEventListener('click', () => {
    const currentButton = button;

    switchButtons.forEach(
      button => button.setAttribute(
        'aria-pressed', button === currentButton
      )
    );

    colorScheme.content = button.value;
  });
});

As you can see, once we set content="dark" the browser switches to the last value in the light-dark() function and the other way around with the light one. This HTML’s color-scheme turned out not so silly after all!

To make it work properly, you’ll need to decide where to store your global color-scheme value, so the script can force it. In this example, I chose to use the HTML one, so I removed the color-scheme property from CSS. But you can also keep it in CSS and force it via JavaScript like so:

<html style="color-scheme: dark">

Meta color-scheme switcher in action. Open in a new tab

One of the downsides of this approach is the browser support: the light-dark() CSS function has been available in all modern browsers since May 2024, which makes it “newly available” on the Baseline scale. It will become “widely available” only around November 2026 or 30 months later. You can transpile it for older browsers using Lightning CSS or PostCSS plugin, but make sure you check the output and test it in an older browser. It might be a bit tricky at times.

As for the other major downside, the light-dark() function accepts only colors for now. Trust me, I tried to use it with other values, and it didn’t work. So, what’s the problem? You might need to change not just colors but images or font properties that work better with the dark scheme.

In this case, there’s another HTML solution for you!

Linking a CSS scheme

You all know the most common way of linking CSS to a page: it’s a stylesheet linked from a file.

<link rel="stylesheet" href="index.css">

But did you know that you can also set the media attribute to conditionally load and apply CSS based on user preferences? Sure you can! But first, you’d need to split your files into light and dark styles:

<link
    rel="stylesheet"
    href="light.css"
    media="(prefers-color-scheme: light)"
>
<link
    rel="stylesheet"
    href="dark.css"
    media="(prefers-color-scheme: dark)"
>

It doesn’t look too convenient this way. A much better approach would be to split your styles into three parts! Yes, I’m serious. Hear me out!

The main file, called index.css, will contain all your styles and use CSS variables for anything you need to change depending on a color scheme.
The light.css file will contain only CSS variables with values set to everything that makes sense for the light scheme.
The dark.css, you guessed it, will have everything dark.

Remember to set the appropriate color-scheme property values in each color scheme file to help the browser: color-scheme: light and color-scheme: dark, respectfully.

Interestingly enough, the file that doesn’t fit user preferences will still be loaded by the browser but with lower priority. I went into much greater detail about this in my other “Conditionally adaptive CSS” article if you’re curious.

So, this three-file CSS architecture now has all the inconveniences and no benefits compared to the previously discussed solution with media queries. What now? Don’t you worry, it was just the first step. Now, to the switching.

Switching linked CSS schemes

When you’re linking your much simpler single-file styles, there’s something else you’re implicitly setting: the media attribute. If it’s not explicitly set, it means that you want your styles to apply to all media types. So, it defaults to all:

<link rel="stylesheet" href="index.css" media="all">

There are techniques using media="print" for lazy-loading CSS, but since we’ve learned that the media attribute can take not only media types but complex media queries, you can negate it as not all and it won’t be applied to any media.

<link rel="stylesheet" href="index.css" media="not all">

But why would you need not to load your styles? Now you see where it’s going. We can use it to switch between color schemes and force user preferences.

Let’s take the same three-position switch from the previous example but change the auto button’s value to auto to better match what it does. Our JavaScript function becomes a bit bigger, but the idea stays the same. The only difference this time is that we’re changing the media attribute’s value:

const styleLight = document.querySelector('link[rel=stylesheet][media*=prefers-color-scheme][media*=light]');
const styleDark = document.querySelector('link[rel=stylesheet][media*=prefers-color-scheme][media*=dark]');

function switchScheme(scheme) {
  let lightMedia;
  let darkMedia;

  if (scheme === 'auto') {
    lightMedia = '(prefers-color-scheme: light)';
    darkMedia = '(prefers-color-scheme: dark)';
  } else {
    lightMedia = (scheme === 'light') ? 'all' : 'not all';
    darkMedia = (scheme === 'dark') ? 'all' : 'not all';
  }

  styleLight.media = lightMedia;
  styleDark.media = darkMedia;
}

In short, if we force the dark scheme, the dark.css gets media="all" instead of the prefers-color-scheme and the light.css one gets ‌media="not all", and the other way around for the light scheme. Once the user chooses the “auto” option, we stop forcing and restoring all previous prefers-color-scheme media values.

Link media switcher in action. Open in a new tab

Given that scheme files containing only variables are relatively small, and browsers download all CSS files anyway (only the priority differs), the switching happens seamlessly. You can check this method in action on my website. And if you happen to use Safari or Vivaldi browsers, you might notice something else changing while you switch the schemes.

One more thing

There’s the theme_color key in the web manifest that sets the installed app’s chrome color. You can also set it via HTML and even use the media attribute to apply different theme colors depending on the color scheme:

<meta
  name="theme-color"
  content="#c1f07c"
  media="(prefers-color-scheme: light)"
>
<meta
  name="theme-color"
  content="#9874d3"
  media="(prefers-color-scheme: dark)"
>

I bet you saw that coming: you can also force the theme color while switching the color scheme using all and not all values via the same script. How cool is that?

Different top panel colors using the theme-color meta element.

Homework

As all of us did, I learned most of what I know from other people’s posts and articles. I want to say a special thank you to Thomas Steiner for his early articles on color scheme switching: Prefers-color-scheme: Hello darkness, my old friend and Improved dark mode default styling with the color-scheme. Please also have a look at Darin Senneff’s Progressively-enhanced dark mode and Sara Joy’s Come to the light-dark() side articles for a different perspective on the matter. And let’s dream about a better future for color scheme switching while reading Bramus’ What if you had real control over light mode / dark mode on a per-site basis? article.

Past HTML, Future HTML?

2024-12-08T00:00:00Z

by Jens Oliver Meiert

Consider the following HTML document:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 1996-01//EN">
<html>
  <head>
    <title></title>
  </head>
  <body>
    <p class="Author">
    <h1></h1>
    <P>
    <P>
    <H2></H2>
    <P>
    <UL>
      <LI>
      <LI>
      <LI>
    </UL>
    <P>
    <!-- … -->
  </body>
</html>

You will notice a few things:

The unusual doctype
The inconsistencies in element case (most notably, <p> vs. <P>)
The inconsistencies in omitting optional tags (like dropping </p> and </li> end tags, but keeping </body> and </html>)

Yet in some respects, this document structure is better than the code we find on many modern websites (and that is sites, not even apps).

Why? What’s to like about this kind of code?

It’s valid. If you run this and the respective original page’s code through an HTML conformance checker like the W3C markup validator, the code will validate. This is basic professional work that we don’t see often anymore.
It’s focused. There’s close to no superfluous code. While there’s a little bit more optional markup to be removed, as well as perhaps the Author class, one might rather add code, like the style sheet reference that’s conspicuously missing.
It’s… open-minded. These inconsistencies, they may rub us, and we likely prefer a consistent formatting. But that shouldn’t distract from the fact that the code is valid (which includes uppercase tag names), and that it represents legitimate ways of writing HTML (which in this case means HTML–HTML, and not XHTML–HTML).

So where is this code from? It’s from T.V. Raman’s documentation on style sheets for spoken renderings, published on February 12, 1996. The 1990s and 2000s are behind us in many areas, and yet in some, they may still be ahead:

We could learn from this code and take it into the future, because XHTML–HTML may have long been dead if it wasn’t kept on eternal life support by frameworks and tools that do not use any of the features that HTML (and that is, don’t mind the repetition, HTML–HTML) offers us. The future of HTML—it could embrace more of the HTML of the past.

Almost, but not quite, entirely unlike...

2024-12-07T00:00:00Z

by Léonie Watson

Can you give me the HTML for an accessible button please?

It was a simple enough question. Or it would have been, had I been asking another person. As it was, I was asking ChatGPT, and so of course there was nothing simple about it.

For the briefest of moments, I caught myself thinking even ChatGPT couldn't get this wrong. The <button> element is probably the most talked about HTML element in accessibility. Literally all you have to do is use it, give it an accessible name, attach some JavaScript to get it to do something if it isn't part of a form, and you don't even need to think about keyboard accessibility because the browser takes care of all that for you.

Then reality kicked me in the shins and told me to snap out of it, and, as if to prove reality's point, ChatGPT burbled:

Absolutely! Here’s an accessible button in its simplest form, following best practices to ensure compatibility with screen readers and keyboard navigation.

OK, I thought to myself, that doesn't sound too terrible. I sat up a little straighter and read on as ChatGPT presented me with:

  <button type="button" class="accessible-button" aria-label="Submit form">
    Submit
  </button>

I stared at my screen for a while and wondered where it had all gone wrong.

At first glance it looks like a perfectly reasonable bit of HTML. Well, except it isn't just HTML, but we'll come back to that in a minute.

It's clearly supposed to be a button for submitting a form. It says so right there, twice in fact. So why then does it have type="button" and not type="submit"?

When the type attribute has a value of "submit" it causes the browser to submit form data. When the type attribute has a value of "button", it tells the browser to do nothing when the button is pressed - but a bit of JavaScript to listen for the button's events is all that's needed for the button to do something useful when pressed.

I checked my question. No, definitely no mention of a submit button. Not even any mention of what I wanted the button for. "Fine" I thought. I'll ask it what it thinks it's up to:

Why do I need the type attribute?

Without missing a beat, ChatGPT told me:

The type attribute in the <button> element is important because it determines how the button behaves, especially in the context of forms. Without specifying the type, the browser applies a default behavior that might not align with your intentions.

It went on:

type="submit" (default behavior):

If you don’t explicitly set a type, the button defaults to submit. This means that if the button is inside a form, clicking it will submit the form.

Use case: When you want the button to submit the form data to the server or trigger a form submission.

type="button":

This type ensures that the button does not submit the form when clicked. Instead, it is just a clickable button that you can use for custom actions (e.g., toggling content, triggering JavaScript functions).

Use case: When you want the button to perform an action other than submitting a form.

[…]

I set down my teacup and put my face in my hands. “Right” I said, finally looking up and channelling my inner Basil Fawlty:

So, why did you give me an example of a submit button with a type attribute set to "button"?

There was an almost infinitesimal pause before ChatGPT chirped:

You're absolutely right to point out the inconsistency! In the example I gave, the button was labelled "Submit" and intended to suggest a submission action, but I set the type="button", which prevents it from submitting the form. This could definitely be confusing since "Submit" usually implies that the button should submit a form.

I closed my eyes and contemplated my life choices.

When I opened them again, nothing much seemed to have changed, so I took a deep breath and in the kind of slow and careful voice that hasn't been heard since Joyce Grenfell in the Nursery School sketch, I asked:

OK, never mind the type attribute, why did you use the aria-label attribute when the <button> has a perfectly good accessible name already?

I narrowed my eyes as ChatGPT brightly informed me:

You're absolutely right again! The `aria-label` attribute is not needed when the button already has a clear, visible text label. The visible text content of a <button> element is automatically accessible to screen readers and other assistive technologies, so there's no need for `aria-label` unless you want to provide an alternative or additional description that's not visible.

Suddenly I knew exactly how Arthur Dent felt, dealing with the Nutrimatic Drinks Dispenser in The Hitchhiker's Guide to the Galaxy. Just like the cup of tea it dispensed to Arthur, the code provided by ChatGPT was, to paraphrase, almost, but not quite, entirely unlike the HTML for an accessible button.

If ChatGPt hadn't been trained by indiscriminately hoovering up everything on the web, and if humans hadn't spent the last 30 years creating so many inaccessible buttons for it to hoover up in the first place, then the answer it gave me should have gone a little something like this:

To create an accessible button in HTML (outside of a form), you can use the <button> element like this:

<button>Accessible name</button>

This element works well with a keyboard: you can focus it using the Tab key and activate it with either the Spacebar or Enter key. When triggered this way, the browser will run any JavaScript tied to the button’s click event. Just make sure to style the button so that its appearance changes when it gets focus, providing clear feedback to users.
For users relying on screen readers or other assistive technologies, the button element is automatically recognized as a button. Just remember to replace "Accessible name" with a descriptive label that fits your button’s function—such as "Search" or "Play."

aria-labelledby = self

2024-12-06T00:00:00Z

by Weston Thayer

An accessible name is how UI components are identified to assistive tech. Having a good accessible name is important. If not, negative effects may include screen reader users missing out on vital information, voice control users struggling to interact, and any number of other issues with the assistive technologies that rely on it.

By default, accessible name is computed from an element's own contents. That's part of the spec'd algorithm that browsers implement.

<a href="/updates">
  Latest updates
</a>

A link with the accessible name "Latest updates".

There are many ways to change that behavior. The aria-labelledby attribute is one which can be used to point the algorithm somewhere else in the DOM. Or not.

<h2 id="heading">Latest updates</h2>

<a href="/updates" aria-labelledby="heading">
  <svg>…</svg>
</a>

A link with the accessible name "Latest updates".

What happens if aria-labelledby points within?

Purgatory

<a href="/updates" aria-labelledby="contents">
  <span id="contents">Latest updates</span>
</a>

A link, still with the accessible name "Latest updates".

Testing

The above snippet should be equivalent to <a href="/updates"><span>Latest updates</span></a>. Are there any issues besides being unnecessarily verbose code (and breaking the first rule of ARIA)?

Technically, the WAI-ARIA spec does not limit the DOM location of the element you point to.

I also checked how each major browser computes the element's accessible name via their developer tools (for example, Chrome's DevTools):

Chrome (129) ✅
Edge (129) ✅
Firefox (131) ✅
Safari (18.1) ✅

I did only test those browsers on macOS, and I didn't test with different assistive technologies. But I trust that if the browser's tools show an accessible name of "Latest updates", screen readers and voice control will have that value too.

Judgement

As is, I'd feel like I was nitpicking by requesting the unnecessary aria-labelledby to be removed.

But imagine this is in a large codebase with many developers working on it. Consider how easy it would be for someone tasked with adding a notification badge to the link, for example, to miss the implications of aria-labelledby:

<a href="/updates" aria-labelledby="contents">
  <span id="contents">Latest updates</span>
  <span class="notification-badge">{{ updates.length }}</span>
</a>

A link, still with the accessible name "Latest updates".

Now the count of updates is not part of the link's accessible name. Screen readers will not announce it. macOS Voice Control users will not be able to say "click Latest updates three" (you would need to omit the "three", macOS Voice Control requires you to say the accessible name exactly). macOS Hover Text will miss the count as well.

And it's a failure of WCAG SC 2.5.3 Label in Name to boot.

So put this link on a heavenly path and drop the aria-labelledby! Your future self will thank you.

Caveats

There are good reasons to point aria-labelledby within an element. For example, to give an accessible name to a region based off of the heading within it.

<dialog aria-labelledby="heading">
  <h1 id="heading">Save changes?</h1>
  <p>Do you want to save your work?</p>
  <button>Cancel</button>
  <button>Save</button>
</a>

A dialog with the accessible name "Save changes?".

I tend to only be wary when the element with aria-labelledby is an interactive control (link, button, etc).

Forced Colors Mode Futility

2024-12-05T00:00:00Z

by Matthias Zöchling

Are you aware of Forced Colors Mode? If not, there are some resources at the end. If so, did you also know that this accessibility feature can be used as an entry-level debugging tool?

From left to right: The HTMHell Advent Calendar 2024 in its intended theme, when viewed in Windows 11 contrast theme “Night Sky”, and “Desert”.

Note: I’ve created a CodePen with all the upcoming examples, so you can follow along.

Premise

When the forced colors feature is turned on, colors will be replaced with CSS System Colors. Elements like buttons and links get special colors assigned, so wherever improper elements are used, things will fall out of place.

Bad advice

Okay, surely there’s a way around this, in true HTMHell.dev spirit‽

Warning: Sarcasm ahead! Don’t try this at home!

Let’s use a <div> to create a button, and <u> to create a link. By doing the latter, our links are already underlined, but we avoid this pesky menu on right-click that feels out of place in our carefully crafted user interface.^[1]

<div class="button">“Button”</div>
<u data-href="https://example.com/very-bad">“Link”</u>

Thanks to the data-href on the link we know where to go. And yes, this means a little JavaScript will be needed to actually go there. Most likely we anyhow have a Single Page Application, so we’ll stay put.

Now all that is left to be done is style our buttons and add color to our links.^[2]

.button {
  border: .125rem solid; /* etc. */
}
u {
  color: light-dark(oklch(0.43 0.3 264.05), oklch(0.69 0.17 281.16));
}

All good? Sadly no, I’m sure the accessibility police will soon be all over the place.

Fine, let’s make our elements interactive. For brevity, I’m not gonna talk about all the JavaScript required, but rest assured to make things accessible we’ll need a metric fuckton of it.^[3]

To fix the HTML, I asked artifical “intelligence”, and several prompts later I learned that we need to sprinkle some ARIA roles and tabindexes on top.

<div role="button" tabindex="0" class="button">“Button”</div>
<u role="link" tabindex="0" data-href="https://example.com/bad">“Link”</u>

We’re good? Again, no, this is where Forced Colors Mode comes in. No amount of ARIA turns our elements into their semantic counterparts. As such, they all will be displayed in plain CanvasText color.

Alright, let’s manually add those colors, but inside a media query, so they won’t leak into our regular theme.

@media (forced-colors: active) {
  .button {
    color: ButtonText;
    background-color: ButtonFace;
  }
  u {
    color: LinkText;
  }
}

I was about to ask “Is this it?”, but I just realized we need a database to keep track of all the links that have already been clicked, so we can visually indicate them as .visited, ... — I’m gonna stop myself right there.

Good advice

Enough of the Sisyphean labor. Let’s do the following instead.

<button type="button">Button</button>
<a href="https://example.com/good">Link</a>

For styling, all you have to do is inherit the font for buttons, which is what your CSS reset might do anyhow for all form controls.

In Forced Colors Mode, things just work, buttons and links will be shown in proper CSS system colors. Semantics for the win!^[4]

The accompanying CodePen in “Night Sky” (top) and “Desert” (bottom) contrast theme.

So do we have an entry-level debugging tool? Well, unless someone goes all the way like we did in the last step of our bad example (highly unlikely!), in Forced Colors Mode you don’t need to be a developer to recognize real buttons and links. Unless the theme prevents it: Buttons are yellow and regular text is white in the “Night Sky” theme, but in “Desert” the difference is way too subtle. No need to stick to the defaults tough, you can create your own theme instead.

Full disclosure

I didn’t need to write this article, because common sense exists, right? Then again, there’s a reason why HTMHell.dev exists. (BTW, thanks for having me, it’s been an honor to be part of the 2024 Advent Calendar among all those talented people.)

Initially I wrote something else, but it ended up being too long for a calendar entry. The original article is now available on my blog. If you are up for actual Forced Colors Mode advice, may I suggest you read it, and then consider joining my movement to make December the least colorful time of the year.

Resources

Forced colors explained: A practical guide, 18min read by Kilian Valkhof
Forced colors and CSS, 16min video by Kevin Powell
Windows High Contrast Mode, Forced Colors Mode And CSS Custom Properties, 11min read by Eric W. Bailey
Forced Colors Mode Strategies, 14min read by yours truly

Footnotes

Some even argue underlined links go against an app-like feel, but let’s not go there. ↩︎
Look at those CSS functions our Fancy Pants author uses to add color to a link. ↩︎
And it’s very likely that we’ll still fail to do so. ↩︎
Mmm 🤤, semantics! If you wanna dig deeper, here’s a CodePen with HTML elements (unstyled, and with CSS system colors for reference) for you to view in Forced Colors Mode. Bonus points if you explore the differences between browers. ↩︎

Control the Viewport Resize Behavior on mobile with `interactive-widget`

2024-12-04T00:00:00Z

by Bramus

Viewports units on mobile have been a problem for a long time. Using 100vh is most likely not exactly what you initially expected it to be. To fix this, the CSS Working Group came up with more units over time for you to use. The dynamic viewport units got introduced, which include svh and lvh which represent 1% of the small and large viewport height respectively.

Two mobile browser visualizations positioned next to each other. One has an element sized to be 100svh (left, green) and the other 100lvh (right, blue). The blue dashed outline represents the Layout Viewport.

While these units are fairly interoperable at the time of writing – there are still some interop issues, mainly related to webviews – there is one big gripe that a lot of people have with it: when the Virtual Keyboard gets shown, these units do not take the presence of that Virtual Keyboard into account. Depending on what you are building, you might want to have these units get resized when the Virtual Keyboard is shown.

The default viewport resize behavior

When the Virtual Keyboard gets shown on mobile, it gets laid over the content. As a result, the Visual Viewport gets resized but the Layout Viewport - the one that is used to position out position: fixed elements – remains unchanged.

Visualization of a mobile browser with the virtual keyboard opened. The elements that have a height of 100svh and 100lvh are not affected by the virtual keyboard’s presence.

Because the Layout Viewport does not change, the Viewport Units also don’t change. The only thing that changes is the size of the Visual Viewport, wich represents only the visual part that you see on screen.

Note: Prior to Chrome 108, Chrome on Android used to resize the Layout Viewport when the Virtual Keyboard was shown. To align with MobileSafari, Chrome adjusted its behavior to resize only the Visual Viewport instead. Firefox did the same with the release of Firefox 132.

What sometimes also happens is that browsers shift the Layout Viewport upwards (or the Visual Viewport downwards depending on how you look at it) in order to keep the focused input at the center of the screen.

Visualization of the Visual Viewport (orange dotted outline) on a page with the Virtual Keyboard shown. On the right, the Layout Viewport (blue dashed outline) got shifted up so that the focused input is centered on the screen.

Intermezzo

If you want to know all the details about Viewports, check out this HTTP 203 episode:

The relevant part for you to know here is that the size of the Initial Containing Block (ICB) is based on the Layout Viewport – more specifically the Small Layout Viewport – and that the Viewport Units are based on the size of the ICB.

Visualization of the Initial Containing Block or ICB for short (red dashed outline). It’s size is taken from the Small Layout Viewport.

If you prefer reading, there are also a bunch of explainers for you to review.

The `interactive-widget` keyword in the viewport meta tag

To control the viewport's size and shape there is the viewport meta tag. Most likely you have used the following before:

<meta name="viewport" content="width=device-width, initial-scale=1" />

In the content there are two properties listed, each with their own value:

width: Sizes the width of the ICB. The value device-width indicates that it should be size in relation to the device’s width.
initial-scale: Sets the zoom level when the page is first loaded. It is set to 1, which is also the default (in most cases).

Other keywords that you might have used before include height, minimum-scale, maximum-scale, and user-scalable.

A fairly new keyword that you can use in the viewport meta tag is interactive-widget. It allows you to specify how the various viewports should behave when “interative widgets” such as the Virtual Keyboard get shown.

resizes-visual: Resize only the Visual Viewport but not the Layout Viewport.
resizes-content: Resize both the Visual Viewport and Layout Viewport.
overlays-content: Do not resize any viewport. This is similar to using the Virtual Keyboard API with overlaysContent set to true.

The impact of the various values for interactive-widget. The orange dotted box is the Visual Viewport. The blue one is the Layout Viewport. Both resize differently depending on the value of interactive-widget.

By setting interactive-widget to resizes-content, you can have the Layout Viewport resize. As a result the ICB will also resize, and therefore the Viewport units will also yield different values.

Visualization of the impact of setting interactive-widget to resizes-content. When that’s the case and the Virtual Keyboard is shown, the ICB resizes and the Viewport Units get adjusted.

interactive-widget is supported in Chrome 108+ and Firefox 132+. If you would like to see this become available in WebKit/Safari, please go give https://github.com/WebKit/standards-positions/issues/65 a thumbs up.

Summary

Use the interactive-widget keyword in the viewport meta tag to control the viewport resize behavior when the Virtual Keyboard gets shown. By default the Visual Viewport resizes. To also have the Layout Viewport resize, set the value of interactive-widget to resizes-content.

<meta name="viewport" content="width=device-width, initial-scale=1.0, interactive-widget=resizes-content">

To not resize any of those viewports, set its value to overlays-content.

The interactive-widget keyword is supported in Chrome 108+ and Firefox 132+.

Smooth Multi-Page Experiences with Just a Few Lines of CSS

2024-12-03T00:00:00Z

by John Allsopp

A single line of CSS can enable slick multi-page transitions for web applications (and web sites for those who maintain there's a difference), opening up new possibilities for web app architectures, and website experiences. So let’s take a look at View Transitions, why we might want them, and how to get started with just that single line of CSS.

The Web's Long Legacy of Native App Envy

The launch of the iPhone coincided with (and likely ignited) a resurgence of the web. After years of stagnation under the dominance of Internet Explorer, competition and innovation were rekindled by Safari for Mac and Firefox. The iPhone’s killer feature (hard as it might be to believe now) was the “full Safari” on a mobile device.

The Safari team introduced native CSS features like gradients, rounded corners, web fonts, transitions, animations, and transforms. Slick interactive experiences were now a reality on the web.

Then native iPhone apps arrived—with their smooth, animated state transitions between views, panels and widgets sliding in and out, and satisfying, physics-driven responses to user interactions. The web's traditional multi-page architecture was no match; moving from one page to another was clunky, with screens going blank as new pages loaded over sluggish 3G networks. Rendering engines struggled on 2010-era chips.

The common refrain was that native apps were inherently better than web apps. In terms of UI slickness, it was hard to argue otherwise.

The nadir perhaps came in August 2010, when the then-bible of the technology industry, Wired, proclaimed on its front cover:

The Web Is Dead. Long Live the Internet

Two decades after its inception, the World Wide Web has been eclipsed by Skype, Netflix, peer-to-peer, and a quarter-million other apps.

The Web Is Dead. Long Live the Internet

The problem wasn’t just the lack of engaging transitions. Web apps also lacked access to platform APIs, such as address books, cameras, and Bluetooth—features leveraged by native apps to create viral growth and novel experiences. But the absence of smooth UI transitions certainly didn’t help.

The web survived, but the struggle to match native apps remains. A significant response to this challenge was the Single Page App (SPA) architecture.

Single Page Apps: A Solution with Costs

SPAs sidestepped the need to download each state as a separate page and the associated clunky transitions by running the entire application in a single page. Now, transitions from one state to the next could be accomplished with CSS transitions and animations. However, SPAs carried their own set of challenges that we still grapple with today.

First, an entire app essentially needed to be downloaded before it could be used. This was acceptable for apps from an app store, but it conflicted with the web’s “instant-on” philosophy. Long load times were particularly detrimental on mobile. This not only presented a UX challenge but also a cost one—mobile data was far from cheap a decade ago, and for many people, it still is expensive. Plus, all that app logic had to be served up potentially many times for every user.

The SPA hydration model (downloading an application shell and then rendering the bulk of the app with JavaScript) put significant burdens on device performance. The web's offline and caching capabilities at the time were poor, often requiring the entire app to be downloaded every time it was used. As we learned over time, SPAs also come with SEO challenges, complex codebases, accessibility issues, and maintenance headaches—all stemming, in part, from trying to emulate the native app experience.

It was not entirely in jest that SPAs have been called a "zero-interest rate phenomenon.”

A New Hope: View Transitions

But now, or very soon, we'll be able to create multi-page apps with View Transitions. It’s taken well over a decade for the Web platform to respond, but View Transitions, coupled with the experimental Speculation Rules API, promise drastically simplified architectures and reduced complexity.

Today, I want to provide a brief overview of what’s coming (and in some cases, already here) and give you the single line of CSS that can add View Transitions to your app or site. As of October 2024, View Transitions are supported in Chrome and Safari’s Technology Preview.

Introducing View Transitions

The View Transition API enables:

Animating between DOM states in SPAs.
Animating the navigation between documents in multi-page apps (MPAs). Or "web sites" as we used to call then.

Now View Transitions can get complex, as they enable sophisticated animations, but let’s start simply.

A Simple Page Transition

Take this classic page transition — quick and clean, thanks to the use of CSS's aspect-ratio and the lazy loading of images. But it’s abrupt. Now, let’s add the magic line of CSS to smooth things out:

@view-transition {
  navigation: auto;
}

Alright, I cheated; it’s three lines. But you could write it as a single line (CSS isn't Python afterall)!

Here it is in action (as supported in Chrome and Safari Tech Preview). The transition is smoother, less abrupt. No JavaScript, libraries, or dependencies—just lovely progressive enhancement. If you want to see it live, visit Conffab, where this effect is used for every page transition.

There’s no reason not to add this to any website today. And more and more visitors will experience nicer transitions over time, at almost no cost to you as the technology becomes more widely supported.

Adding Dynamic Transitions

We can also make transitions more dynamic with just a bit more CSS.

Here's a before and after video. First, how browsers traditionally rendered page transitions

And now how Chrome renders this new transition we'll detail below.

I hope you'll agree it's a much more engaging effect. So, how do we achieve this?

In our main page, where we have links to individual sessions, we have one end of the transition that looks like these:

<section id="speaker-marco-rogers" style="view-transition-name: marco-rogers-hero"></section>
<section id="speaker-maria-farrell" style="view-transition-name: maria-farrell-hero"></section>

Then in the target pages, we have elements like these:

<section id="session-details" style="view-transition-name: marco-rogers-hero"></section>
<section id="session-details" style="view-transition-name: maria-farrell-hero"></section>

Notice how the two ‘ends’ of the transition have matching view-transition-name values. This tells the browser which DOM elements to transition between.

Inline styles aren’t always ideal, but in this case, it was the easiest solution given the existing codebase. You could alternatively apply the style with CSS, if the endpoints can be uniquely selected on a page (since view-transition-name values must be unique on any given page so the browser knows which elements to create a transition from and to).

Currently, this more complex example may have issues in Safari 18's Tech previews, but I’m confident they’ll be resolved soon. Above all, it’s great to see Safari investing in this feature!

What's Next?

First, add the simple one-liner to all your sites for smoother page transitions.

Then, explore adding more specific transitions like in the second example. For generated pages, adding view-transition-name attributes may not present much challenge, and depending on your HTML structure, you could add them with just a bit of CSS.

Now, animation effects can cause difficulties for some users, such as those with vestibular disorders, so we should take our user's preferences about motion into account. Doing that for View Transitions is very straightforward. We add

@media (prefers-reduced-motion: reduce) {
  @view-transition {
    navigation: none;
  }
}

Add this after our original @view-transition rule. Now, if the user's preferences are set to reduced motion, no view transitions will be triggered on page navigation.

Finally, take a deeper look at what else the View Transition API can do—this is just the beginning.

Starting off right: Where autofocus shines

2024-12-02T00:00:00Z

by Kilian Valkhof

Focus is where the user is on your website. It's what makes it possible to navigate your site with the keyboard or other assistive technologies, and it's how a browser knows which form element you're typing in. It's vital to get right if you want to build good websites.

Whenever you're dealing with code that can “steal” focus you have to be aware of how that affects your visitor. So it's not strange that many folks will tell you to leave focus alone, to stay away from tabindex and autofocus.

All of that advice is good advice: you should be careful when moving the focus away from where it would normally be and where the user would expect it to be, or you'll quickly find yourself in a world of accessibility issues.

But if you start off on the right foot, managing focus is a delightful HTML detail that makes your site a joy to use.

Autofocus

The autofocus attribute can be added to any element to make it automatically focused on page load, skipping over any other elements that might have been focused before. Any element that can be focusable can also have autofocus applied to it, like buttons, links, and form elements.

As mentioned above, you'll rarely want to use autofocus. Messing with people's focus usually doesn't make them want to use your website more. It will probably make them want to use it less, so don't autofocus your purchase button or search field.

But there's a place where autofocus shines: On single-purpose pages containing forms.

...which is a bit of an obtuse way to say “login pages”, “signup pages”, “password reset pages” and “Two-factor authentication (2FA) pages”, you get the idea.

Adding Autofocus

Your login page has one purpose: to get the user to log in.

The user has one goal: to log in.

So why not make it as easy as possible for them?

<form method="post">
  <label for="username">Username</label>
  <input id="username" type="text" autofocus />

  <label for="password">password</label>
  <input id="password" type="password" />
</form>

Add autofocus to the first field and your visitor can start typing as soon as the page loads. No need to click or tab or search for forms on the page.

If the user uses assistive technology, it will announce the label and the field, and then announce that the field is focused.

Similarly, your password reset page (single field) and signup page (single purpose) will have the same structure and will likewise benefit from having the first field focused.

If your login page is followed by a 2fa page, then that autofocus is vital.

Few things are as "throw pc out of the window"-frustrating as frantically typing in that 2fa code as the last few seconds tick away, only to find the field wasn't focused. And now you have to do it all over again.

Argh!

Some things just get to me.

When not to use autofocus on single-purpose pages

Even if you have a page with a single purpose, you might not want to add autofocus.

If you have a login form but people can also use social logins (Google, GitHub, and the like) and you don't know which one they'll use don't add an autofocus.

Instead, keep track of what they use to log in. As soon as you know which one they're using you can store that in a cookie (or localStorage) and focus on the field or button they need to interact with the next time they visit.

Conclusion

So let's get back to the point: autofocus is a great way to make your forms more user-friendly, as long as you use it in the right place.

Are you building a page that has:

A single purpose
A single form
No other choices available

Then autofocus is your and your visitor's friend.

So go ahead and use it on your login pages, your signup pages, your password reset pages, and your 2fa pages. Your users will thank you for it.

A link on a logo in the header, what should the alt-text be?

2024-12-01T00:00:00Z

by Rian Rietveld

It's a common pattern to use a logo in the header as a link to the homepage.
But what should be the alt-text of that image?
"the site name" or "homepage" or "logo" or "IMG_123"? Does it even matter?

Fun fact: the alt text of the image inside a link, will be added to the link text.

The problem with linking a logo is that it serves 2 purposes:

a logo, that tells you which site you are visiting;
a link, that leads to the homepage.

So add both that info in the alt text. Explain what's on the image and where the link leads to: "Site name logo, to the homepage".

Note: Start the alt text with the visible text, then the link will be easier to target for people using voice recognition software.

Let's take as example the logo of my home town Leidschendam-Voorburg.

In code (simplified):

<a href="/">
  <img 
    alt="Leidschendam-Voorburg logo, to the homepage" 
    src="logo-lv.svg" 
  />
</a>

Generated HTML:

VoiceOver in Safari will announce this as:
"Link, image, Leidschendam-Voorburg logo, to the homepage".

All info is there.

There is an advantage of using the alt text instead of an aria-label solution. When the connection is slow, the alt text will show up before the image does and already informs all users of the site name and link destination. It's quite robust.

Discussion

Do I need the word logo? Isn't that redundant, like the word image or picture?

Yes, in this case the fact that this is a logo tells important info.

Not only for blind users, but for all screenreader users. If you are visually impaired but not totally blind, you may see the image vaguely. With the addition of the word logo, you also know what the image is.

The site name is required, but the logo gives extra context.

Isn't this a violation of 2.5.3 Label in Name?

No, the visible name is in the alt text, which becomes the accessible name of the link. Adding extra context to the link is common practice.

Compare this with the notorious "Read more" link in a card. A common pattern is to use a sr-only CSS class (or equivalent) with additional text:
<a href="url">Read more<span class="sr-only"> about cute kitten</span></a> .

You see Read more.
You hear Read more about cute kitten.

In our case:

You see the site name and logo; the visual position tells the link destination.
You hear the site name, the fact it's a logo and the link destination.

The whole visible text should be in the accessible name, but extra information, like the meaning of the image and link destination can be added for context. That way the purpose of the link is explained.

Why didn't you use an aria-label?

Of course there are other and also valid solutions. By using plain simple HTML I want to honor the first rule of ARIA:

If you can use a native HTML element 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.

Happy Holidays!

Never underestimate HTML

2023-12-24T00:00:00Z

by Lara Aigmüller

“HTML is easy.”, “Frontend development is easier than backend development.”, “Updating the UI should be a simple task once the backend is ready.”—these and other similar statements reached my ears time and again during my career as a web developer.

Very often, these made me sad. 🥲

The reason is that I spend most of my working hours writing frontend code including HTML, CSS, and JavaScript (JS) (actually, TypeScript most of the time). When somebody tells me, that my job is “easy”, I feel like my skills are nothing special and another developer could replace me anytime…

What follows now is an article about thoughts that came to my mind in the last couple of years when working together with different people from different teams with different backgrounds in HTML and frontend technologies in general. This is an article about the many “whys” in my head and possible answers…

Why do people think HTML is easy?

What is meant by “easy” anyway? Whether something is easy or not is usually in the eye of the beholder. When I know a technology or programming language well, it’s easier for me than somebody new to the field and inexperienced.

Some people tend to make assumptions about the complexity of frontend development and in my experience those people are the ones not working with frontend technologies and especially HTML on a daily basis. Here are a few reasons I can think of why this happens:

The HTML syntax is not that hard to learn. Put together some angle brackets, tag names and key-value pairs (a.k.a. attributes) and you’re good to go!
The HTML syntax is machine and human readable, which was one of the ideas behind XML-like languages.
Once you’ve written a couple of lines of code in a .html file, no compilation or build steps are required to see the result of your work immediately when you open the same file in a browser.
HTML has a low barrier of entry. In some WYSIWYG editors there is an option to switch to the “code” view, and you can fiddle around with the HTML version of your text, no matter if you know what you’re doing or not. (You have a preview available, what could possibly go wrong?)
Browsers are great and forgive a lot of mistakes (J. David Eisenberg described this in a pretty old article about “forgiving” browsers, that contains some thoughts that are still valid today.). When you open a syntactically broken HTML page the chances are high that the browser still renders something. You forgot to close a tag? No problem. You added an unknown tag or attribute? The browser just ignores it. Compared to a programming language where the whole app crashes because of a missing semicolon, yes, this feels “easy”.

Let’s go one step further and think about why people tend to compare web technologies or contrast frontend with backend development.

Why do people think frontend development is easy?

Programming the backend of a website or application is the hard part, creating the frontend an easy one. Right? Sometimes, it feels to me that this is the common opinion among many developers.

And again, I’m looking for the answers to the “why” and came up with the following thoughts:

Users and project stakeholders are often not confronted with the business logic and backend code at all, but only with the user interface (UI). Adding thoughts about where to put which button or piece of information and how the UI should work in general is easier because it’s just more tangible than complex database queries or nested for-loops and if-statements. The backend is a black box that does its magic and spits out data for the frontend. The frontend developer “just” needs to display this data, add colors, and build a layout (using CSS) and the work is done.

Luckily, there are many frontend component libraries that can be used. Put together some (predefined) views, fill the data in there, and you don’t even need to think about colors and layouts anymore – isn’t that great? So, with this amount of help, almost anyone can build great frontends without too much HTML/CSS knowledge!

</sarcasm>

Frontend built by “non-frontend” developers

I made the experience that people who thought programming the frontend was the easy part of web development (and would never call themselves “frontend developer” but rather “full-stack developer”) made the biggest mistakes in their frontend code (even with help of frameworks and libraries).

Heydon addressed this topic in “Reluctant Gatekeeping: The Problem With Full Stack” where he wrote:

[...] if you put someone in charge of all of these things and more [...] it’s highly likely they are going to be much weaker in some areas than others. [...] In my experience, men especially earn kudos for their knowledge of JavaScript or Python, but little from CSS skills. CSS, which makes things look ‘pretty’, is considered feminine.

Some of the mistakes mentioned above were actual syntax errors, others were problems with semantics, performance, accessibility, etc. In prototype presentations or during testing, often they aren’t noticed because the browser forgives them (see above), performance is usually good on the developer’s machine, no accessibility tests are being made… The result is: it works, the browser displays what’s expected, everything seems to work fine and can be shipped to production.

Why is broken HTML code a problem?

Once the code is deployed to production, the first problems might come up. Users who were not part of the development process interact with the product for the first time and run into issues, some of which may be caused by broken HTML code, impairing the user experience.

Bad user experience

Let’s have a look at problems based on bad HTML code the end-user might stumble upon:

frustrating forms (here’s an article of mine about bad user experience when using forms on the web with some examples)
performance problems (here’s a talk on YouTube by Harry Roberts about what can go wrong in your HTML document’s “head” – Get your “head” straight)
wrong usage of headlines (h1-h6) or missing text alternatives for non-text content, which is bad for people using a screen reader
wrong/no usage of interactive elements (“A div is not a button!”) or a confusing tab order of elements, which is bad for people using the keyboard for interaction
basically everything you can find on htmhell.dev
broken HTML code which leads to broken JavaScript and thus broken functionality

Bad developer experience

Not only the users of your sites and applications might have a hard time using your product when the HTML/frontend code isn’t correct, also your fellow developers could have their “facepalm moments”, because…

…when HTML code is badly structured, it’s harder to write good CSS code for it. To put it differently: HTML code often has to be adjusted once CSS comes into play. When you have experience in writing both languages, the chances are high that your HTML and your CSS code turn out great and maintainable.
…when HTML code of your project’s UI components isn’t flexible, you might not be able to reuse them or scale the project at all without required refactoring when a new feature is requested.
…when developers are not working with the platform but try to reinvent the wheel and not taking browsers’ capabilities into account (like using JavaScript to navigate from one page to another instead of just using a link), bugs might be more likely and fixing them without breaking another part of the application gets harder.

Why should we care?

As mentioned above, browsers are great and forgive a lot of mistakes; websites might work for many people, even if they are not accessible or performant or even if parts of them break. Maintaining these websites might also be done by good-hearted/ill-fated developers who don’t mind working on a smelly codebase.

But I’m sure we can do better. 💪

The goal should be that websites (and web applications) work for most, no, for all people browsing the web and we as developers should build products respecting the needs of all our (potential) users. Writing scalable and maintainable code leads not only to accessible, fast, and usable websites but also to happy developers.

It’s not only about writing HTML

I’ve met people who started learning web development by diving head-first into the newest frameworks and then built a simple website using Angular without learning the basics first. The problem: without basic HTML (or CSS or JS) knowledge, the most popular framework doesn’t help you succeed; on the contrary. You’re using a sledgehammer to crack a nut. No matter which tools you use, the code that gets shipped to the browser is HTML, CSS, and JavaScript and knowing how these languages work is required to build great applications—no matter which newfangled technology you’re throwing at your problems.

Writing HTML in itself isn’t that hard, no.

But: building user interfaces by elegantly composing this language’s features with CSS, creating pleasant designs and user experiences worth remembering requires experience and skills that should not be underestimated. Neither should HTML; it’s one of the languages—if not the most important one of them all—that shape the web.

Related thoughts about the value of (expertise in) web frontend development were shared by

Christian Heilmann, who defended frontend development as a full-time job
Jeremy Keith, who is worried that we might have “reached a state where the more complex over-engineered approach is viewed as the default”
Andy Bell, who describes that front-end is so much more than building designs

Let’s stop comparing web technologies and their values. Let’s not discuss what’s easier/harder to do or more/less important. Let’s work in teams, listen to and learn from people with expertise, no matter whether they shine in writing HTML, CSS, TypeScript, PHP, Python, {add-your-favorite-language-here}… let’s make the web a great place together and value people who work on the front of the frontend more!

P.S.: Thanks to Felix for always proofreading my articles and expanding my English vocabulary. Thanks to Manuel for maintaining HTMHell and creating this inspiring advent calendar.

The devil is in the details: a look into a disclosure widget markup

2023-12-23T00:00:00Z

by Cristian Diaz

Disclosure widgets are one of the most common component patterns you can find on the web. It consists of a button that can hide or show information when you click it. It's also one of the straightforward components to make from a technical standpoint.

Just a quick note: this article will focus on the most basic form of it to show or hide content. A navigation menu can be considered as a disclosure widget but it has other features that won’t be the main focus of this article.

This component pattern has two approaches: the first one is creating a <button> element with the attribute aria-expanded that will toggle between true and false when you want the content to be shown or hidden. Additionally, you want to create a relationship between those two elements with aria-controls to indicate the button controls the presence of this element, like this:

<button aria-expanded="false" aria-controls="accordion">What are cephalopods?</button>
<div id="accordion">
  <p>A cephalopod is any member of the molluscan class <i>Cephalopoda</i> such as a squid, octopus, cuttlefish, or nautilus.</p>
</div>

This approach requires JavaScript to modify the aria-expanded attribute. However, we can pair it with a pure CSS’ n ext-sibling combinator to control showing and hiding the disclosure’s content.

button[aria-expanded="false"] + div {
  display: none
}

const button = document.querySelector("button")

button.addEventListener("click", (element) => {
  const isExpanded = element.target.getAttribute("aria-expanded")
  if (isExpanded === "true") {
    element.target.setAttribute("aria-expanded", "false")
  } else {
    element.target.setAttribute("aria-expanded", "true")
  }
})

Creating a disclosure widget that requires JavaScript also means you should work on a progressively enhanced version of it in case JavaScript doesn't load. There are multiple approaches to this, a very common one is using heading instead of buttons, and when JavaScript loads, replacing the header with a button:

<h3>What are cephalopods</h3>
<div>
  <p>A cephalopod is any member of the molluscan class <i>Cephalopoda</i> such as a squid, octopus, cuttlefish, or nautilus.</p>
</div>

All of this sounds like quite some work for a relatively simple component pattern, it'd be cool if we had a native option to make a disclosure widget... Oh, wait, we have one! This is where our second approach enters, and that's using the <details> and <summary> elements. Let's come back to our initial markup and let's modify it with this approach.

<details>
  <summary>What are cephalopods?</summary>
  <p>A cephalopod is any member of the molluscan class <i>Cephalopoda</i> such as a squid, octopus, cuttlefish, or nautilus.</p>
</details>

And that's it! This disclosure widget works, and it's accessible, so I guess the answer would be using this one instead of using the first approach, right? Well, as usual, the reality is more nuanced than that. As much as I'd prefer to use native options for component patterns, the answer to that question is a definitive “It depends”.

When picking a disclosure widget markup, the author needs to balance the strengths and limitations of each approach, and consider what content it will contain. This article will talk about those nuances you should keep in mind about choosing one markup approach or another, mostly focusing on screen reader accessibility because both of them meet the requirements of keyboard navigation with no problem at all.

Experience across different browsers

The first factor to keep in mind is consistency. When you use a progressively enhanced button approach, you know that it'll be the same for screen readers. Both markup approaches will read them as a button and will read the aria-expanded attribute similarly. But with <details> and <summary> things change quite a bit when you start taking into consideration different screen readers and browsers.

When you use <details> and <summary>, NVDA and JAWS both narrate it as a button in Chrome, and they'll mention if the element is collapsed or expanded. But when you use the same markup in Firefox, they narrate the marker (that is, the visual indicator is being used to indicate the element is collapsed or expanded) as well. My previous example will be read as “Filled right pointing small triangle, what are cephalopods, button, collapsed”. And when we start talking about mobile, the experiences vary a lot.

This is not bad per se, but in some browsers, mentioning the marker can feel a bit like noise, but buttons on the other hand offer a cleaner more consistent experience.

The key point in this section is that you should ask yourself this question: am I okay with letting the screen reader experience be different between different screen readers and browsers? If you're all right with this, use <details> and <summary>, but if you'd prefer a more consistent experience all around, use a progressively enhanced <button>.

Wait, I can modify this default marker, right?

By default <details> and <summary have this triangle arrow that will change when it is expanded or collapsed. Maybe you have a design that has a different indicator, can you modify that? The answer is yes, but there is a huge caveat here:

As Manuel mentions in his article details/summary inconsistencies, you can modify the default arrow by using those CSS rules:

summary {
  list-style: none;
}

This will hide the arrow in all browsers except Safari, so you’ll need an additional CSS rule:

summary::-webkit-details-marker {
  display: none;
}

This deletes the indicator in all browsers, but this brings a big problem: as Manuel's tests in the same article show, some combination of screen readers and browsers will use the arrow indicator as part of the accessible name, and if you remove them, it'll stop indicating its state once the user press the <summary> element.

This behavior is particularly notorious with VoiceOver and Firefox because when you remove the marker, it'll indicate nothing when the user expands the content.

For this reason, my suggestion here is that if the design has a different indicator for the expanded/collapsed states than the default option, you should use a progressively enhanced <button> approach. On the other hand, if you are ok with the default marker, you can stick with <details> and <summary>.

Browser's in-page search

Those previous points are making look <details> and <summary> as an unreliable option, but there is something that those elements add to the table that a progressively enhanced button option can't.

As Manuel mentions in his article the details element and in-page search, Chromium-based browser in-page search option can look for content even when the <summary> element is collapsed. This is an important factor to keep in mind because this improves usability for someone who uses the in-page search.

As a side note, do you remember when I said I would not focus on disclosure widget variants like a navigation menu? Well, between the different ways a screen reader displays this component and now taking into consideration the in-page search option, makes <details> and <summary> unsuitable for a navigation menu.

So, the key point of this section: if you think letting the user find a keyword using the browser in-page search is important, stick with <details> and <summary>, otherwise, use a progressively enhanced button.

Do I need to always hide the content?

The main selling point of <details> and <summary> is that they'll hide the disclosure widget’s content always, even where there is no JavaScript involved. This is something really important in some scenarios.

The first example that comes into my mind is a content warning if it's visible, can cause legitimately bad experiences or trigger a PTSD (Post traumatic stress disorder) episode for a person.

You could use a progressively enhanced button, but if JavaScript doesn't load, there is a risk, and depending on the context, it can be critical to hide this content even in those scenarios. Kitty Giraudel created a content warning component using only <details> and <summary> in her article, A content warning component.

My key point here is that you need to consider how critical is to hide the content as an initial state, no matter what. If it's necessary, consider using <details> and <summary>, otherwise, using a progressive enhanced button is a good option.

Use of headings

There is quite an interesting thing you can do with a disclosure widget made with the progressively enhanced <button>, and that's adding headings on them. This makes it easier for screen reader users to navigate to this part of the content. The process changes a bit depending on what approach you want to use. For this approach, the markup would look like this:

<h3>
  <button aria-expanded="false" aria-controls="accordion">
    What are cephalopods?
  </button>
</h3>
<div id="accordion">
  <p>A cephalopod is any member of the molluscan class <i>Cephalopoda</i> such as a squid, octopus, cuttlefish, or nautilus.</p>
</div>

There is a catch though: the <button> is now inside the heading, so it’ll be undetected by the next-sibling combinator. There are two options: we can use to solve this issue:

Modifying our script: We can make a slight modification in our script and making the adjacent container have the hidden attribute .Then, we toggle it when the <button> has the proper aria-expanded value, like this:

const button = document.querySelector("button");
const accordionElement = document.querySelector("[data-content]");

button.addEventListener("click", (element) => {
  const isExpanded = element.target.getAttribute("aria-expanded");

  if (isExpanded === "true") {
    accordionElement.setAttribute("hidden", "");
    element.target.setAttribute("aria-expanded", "false");
  } else {
    accordionElement.removeAttribute("hidden");
    element.target.setAttribute("aria-expanded", "true");
  }
});

:has(): The other option is using the (relatively) new CSS :has() selector like this:

h3:has([aria-expanded="false"]) + div {
  display: none;
}

The problem with :has() is its browser support. At the moment of writing this article, Firefox just shipped it in the latest version (121), so browser support may make use of this selector not robust enough to be reliable (for now!).

Can you do that with <details> and <summary>? Yes, do I recommend it to do it? No, it has some inconsistent and even buggy behaviors when you use a screen reader to activate them.

Let's start with checking how it is “possible”, first, we add our heading inside <summary> like this:

<details>
  <summary><h3>What are cephalopods?</h3></summary>
  <p>A cephalopod is any member of the molluscan class <i>Cephalopoda</i> such as a squid, octopus, cuttlefish, or nautilus.</p>
</details>

Keep in mind you need to add the <summary> element as the direct child of <details>, otherwise, it’ll not be recognized as our disclosure’s trigger. Now, There is one detail, this is how it'd look:

What are cephalopods?

A cephalopod is any member of the molluscan class Cephalopoda such as a squid, octopus, cuttlefish, or nautilus.

The title “What are cephalopods?” is just below the arrow marker when it should be at its side

Then, we'd need to use CSS to put the heading at the same level, but if you do it with, for example, display: flex, it'll not show the marker, and as we saw before, this will affect screen reader experience for some combinations of screen reader and browser. My approach here was making the heading inline, and that worked well, like this:

summary h3 {
  display: inline;
}

Why I don't recommend doing that with <details> and <summary>? With both approaches, you can use screen reader shortcuts to navigate directly to a heading, but there is a caveat here:

With the <button> approach there will be no problem: the button is inside the heading and if the screen reader's virtual cursor is over the heading, you can control the button by pressing the Enter or Space keys. This is useful when you use screen reader’s shortcuts to navigate to a heading (like using the H key).

There catch here comes with <details> and <summary> because it has way less consistent results. To prove that, I decided to test each disclosure with heading markup next to each other. You can take a look at the example I used right here:

See the Pen Untitled by Cristian Diaz (@ItsCrisDiaz) on CodePen.

CodePen

This test used the next combinations of screen readers and browser:

NVDA and JAWS with both Chrome and Firefox.
Narrator with Edge
VoiceOver with Safari, Chrome and Firefox

And those are the results:

NVDA works perfectly with both browsers, you can navigate using the key shortcuts and you can activate them with Enter or Space.
With JAWS you can’t navigate to a heading inside the <summary> element, making this feature not advisable.
Narrator with Edge is surprisingly buggy, it read both headings at the same time as if they were just one, and it didn’t let me to activate any of them. However, once I removed the <details> element it worked normally, so it’s safe to say adding a heading inside <summary> is not advisable.
With VoiceOver, you can navigate to a heading using the key shortcuts, however, you can’t activate the <summary> element that way. You can activate it navigating with the Tab key but for some reason, if VoiceOver visual cursor is on the heading itself, it can’t be activated. This can create confusion for screen reader users because they found a heading, but they will not find extra content below it because it's a disclosure widget.

So, key point of this section: if you think adding heading navigation to your disclosure widget improves the user experience for screen reader users, you'd be better using a <button> element, otherwise, use <details> and <summary>.

Wrapping up

Having a native way to make a disclosure widget is great! But as usual, things are not that easy because browsers' implementation tend to vary in details that you need to take into consideration. It's not the first HTML element that has inconsistencies among browser (As an example, just look at Manuel's article O dialog focus, where art thou? to check how browsers implement keyboard focus with the <dialog> element) and it certainly won't be the last.

In my mind, there is no doubt that browser’s implementation of <details> and <summary>will be more consistent in the future and this article might end up being a thing of the past. But for now, there are important considerations you need to keep in mind before deciding to use one markup approach or another.

ARIA Live Regions

2023-12-22T00:00:00Z

by Andrea de Souza

ARIA stands for Accessible Rich Internet Applications. It is a set of roles and attributes that makes web page elements accessible to users who require assistive technology, like screen readers, when native HTML alone is not enough. One of these sets of roles and attributes is aimed at defining live regions.

Live regions are areas that, when dynamically updated, trigger screen readers to announce their new content. They are commonly used for notifications that do not receive focus when the new content is added to the page. For example: form errors, loading spinners, search results that appear on dynamic search, and toasts.

Here is a practical example. On an e-commerce website, the notification “product added to cart” displays momentarily whenever the “add to cart” button is pressed. The new content is added to the page, but doesn't receive focus. While sighted users would be able to see it, screen-reader users would not know that somewhere on the page an updated happened. Adding a live region to the parent element that displays this type of notification allows it to be announced by screen readers.

Creating Live Regions

There are two ways widely used to implement a live region in an HTML element: adding the aria-live attribute or adding a role that has an implicit live region.

A third option for specific scenarios is to use the native HTML <output> element, which has the implicit role="status" property. However, there are accessibility issues associated with it, as described in detail by Scott O’Hara.

`aria-live` Attribute

The aria-live attribute on an HTML element creates the behaviour of a live region by defining a "politeness setting", which indicates when dynamic updates should be announced to users of assistive technology. This attribute needs to be declared using one of three possible values:

off: This is the default value. No changes will be announced, unless if the user is focused on the region where the update happens.
polite: The screen reader will announce the changes when it has a chance. For example, when the user is idle or once the task being performed at the moment of the notification ends. This option should be used for low priority updates that don’t require immediate attention from the user.
assertive: The screen reader will interrupt whatever it is reading to announce the content update. This option should only be used for time-sensitive, critical information.

Going back to the e-commerce website example, the “product added to cart” message may have an aria-live="polite" attribute.

<div aria-live="polite">
	<p>Product added to cart.</p>
<div>

However, if the user is on a news website and there's a weather alert or an emergency broadcast, then this notification has a high degree of priority and should have an aria-live="assertive".

Please note that those are generic examples. The aria-live attribute value will depend on different factors. A good way to determine the politeness setting required is to ask directly the users that will be the recipients of the message. One important aspect to keep in mind is that the assertive level is disruptive for screen-reader users and should only be used when absolutely required.

There are other ARIA attributes that, in theory, should provide greater control of how ARIA live regions should behave. But, in practice, they have only partial support and/or their behaviour varies between different screen reader/browser combinations.

aria-busy: When set to true, it indicates that the element is not yet ready to be announced because it’s still being modified. It also means that screen readers MAY want to wait before announcing the changes (W3C). The partial support for this attribute happens when it's set to true, according to a11ysupport.io. The default value is false. An example that may apply this attribute is to set area-busy="true" while a page is still loading and change it to false once all elements are loaded.
aria-relevant: Specifies the updates that are relevant to be announced, which can be either: the addition of new nodes (aria-relevant="additions"); text content, text alternative, or node removal (aria-relevant="removals"); or the addition of text content or text alternative (aria-relevant="text"). The shorthand all includes the three values. Multiple space-separated values can also be used. For example, additions text, which is the default value. Please note that the values removals and all should be used carefully, since only in specific scenarios it's relevant to announce the removal of content. One example would be when a user leaves a chat room. According to W3C, aria-relevant is an optional attribute and represents a suggestion to assitive technologies. The partial support for this attribute is documented by a11ysupport.io.
aria-atomic: Specifies if the whole live region should be announced (aria-atomic="true") or only the content that has changed (aria-atomic="false") based on the value of aria-relevant. For example, with default value false and the default aria-relevant="additions text", only the updated nodes and the addition of text content or text alternative will be announced. When set to true, the entire live region will be announced. In this case, screen readers MAY choose to combine multiple changes and present the whole region at once (WAI ARIA - aria-atomic). Depending on the application, this attribute may be important, but make sure to test the behaviour with different browser/screen reader combinations. Test results for this attribute can be found at a11ysupport.io and at Paul J. Adam's website.

Live Region Roles

The ARIA specification lists five live region roles, according to the type of notification that they announce:

alert: Time-sensitive notifications that require immediate attention, like form errors.
status: Notifications that are not as important as an alert, nor time-sensitive.
log: The order in which the notifications are added have meaning, as in a log, and old information may disappear.
marquee: The information is non-essential, changes often, and the order is not meaningful.
timer: The notification is the amount of elapsed time from a starting point or the remaining time until an end point of a numerical counter.

Each live region role has an implicit aria-live attribute:

role="alert" has aria-live="assertive"
role="status" has aria-live="polite"
role="log" has aria-live="polite"
role="marquee" has aria-live="off"
role="timer" has aria-live="off"

MDN recommends adding a redundant aria-live attribute to the alert, status, and log roles to maximize compatibility.

Please keep in mind that role="status" and role="alert" are the only two live region roles that have good browser/screen reader support.

`aria-live` Attribute vs Live Region Role

So, what is the difference between using aria-live and a live region role? aria-live is an attribute that creates the behaviour of a live region by defining the “politeness” level of how the notification should be announced. A live region role not only creates the behaviour of a live region, but also provides semantic meaning to screen readers. It has an implicit aria-live property.

For example, an element with role="alert" has an implicit aria-live="assertive" property and should inform the screen reader that the notification in that area is really an alert. While the aria-live="assertive" attribute by itself will inform the screen reader that it should interrupt whatever it is reading to announce that notification.

Another difference is that live region roles allow to define an accessible name, which may be important when having more than one live region in the same page. For example:

<div role="status" aria-labelledby="[id-of-an-element]"><div>

While the definition with aria-live wouldn't allow the addition of an accessible name:

<div aria-live="polite"><div>

One last difference specific to live regions defined with role="alert" or role="status" is the implicit aria-atomic="true" property.

“Robust” live regions

Unfortunately, live regions don’t behave consistently in all browser/screen reader combinations, even if all roles and attributes are added according to the specification. However, there are a few recommendations that can be followed to make the implementation as robust as possible:

First: Insert the live region

The element that contains the aria-live attribute or live region role should be in the DOM, empty, before the update happens. Ideally, on page load or as close as possible to it. This is important because live regions need to be in the accessibility tree in order to be announced. The accessibility tree is a subset of the DOM tree. It provides information from the DOM in a way that can be understood by screen readers and other assistive technologies.

For example, the div below can be part of the initial HTML markup and, later on, used for a dynamic notification:

<div role="status"><div>

Having an element with a live region declared, as the example above, will not trigger any announcement by screen readers. It's only when an update in the content inside the live region happens that the it will trigger screen readers to announce the new content.

If the element with the live region role is dynamically injected in the DOM at the same time as the notification happens, it may not be correctly announced. For example, if an element with a live region is in the HTML, but has the CSS property display: none:

<div role="status" style="display:none;"><div>

Using the CSS properties display: none or visibility: hidden hides the content from users, but also removes it from the accessibility tree. And if the live region is not in the accessibility tree, then it cannot be tracked by screen readers. Although these properties can be dynamically changed with JavaScript to display: block or visibility: visible, it should not be done at the same time as the content update.

Second: Add dynamic content

The dynamic content should be added to descendants of the element that has the aria-live attribute or live role region. Adding to the previous example, the dynamic content can be added as:

<div role="status">
	<p>Product added to cart.</p>
<div>

When not to use a live region

Although a live region may seem like the ideal solution to announce a dynamic content update, it is not always the best approach. Here are a few examples when not to use it:

If there is an option to replace the live region with static instructions, then do it. It will probably be a better experience for screen-reader users to read additional content than to be interrupted with a notification. For example, a <select> element updates another area of the page according to the option value. Instead of using a live region for the area that will be updated, it's possible to have static text saying that the content will be updated according to the option selected.
Focus change and live regions firing at the same time are prone to conflicts. If there is a focus change to the element being updated, then a live region is not needed. Going back to the "add to cart" example, instead of having the "product added to cart" message, we can have a "cart flyout" (modal dialog) opening on the side of the screen. Focus may go the modal close button, an interactive element. In this example, there's no need for a live region, but the user should be informed of the new context.
Don’t use live regions to announce state changes that can be communicated through an ARIA state. For example, if using an accordion, use the attribute aria-expanded to indicate if it’s opened or closed. If using a toggle button, use aria-pressed.
Don’t use live regions for visual UIs that change constantly. Sarah Higley suggests to provide a separate interface in some scenarios. This will keep the live region concise by announcing only relevant information. A practical example would be a search box in which the results update every time the user types a character. Wrapping the element in an ARIA live region would be too verbose because every single change would be announced.

Tips to improve the user experience

There are a few tips that can improve the user experience:

Live region notifications should be concise. Remember that screen-reader users have no control over it. And since the notification is only announced once, there’s no possibility to go back and review it, according to Sarah Higley - The Many Lives of a Notification.
Notifications should be easy to understand. Screen readers will read everything as plain text. Even if the text has headings, bold content, or any interative content (links or buttons, for example), everything will be read as one block of text. Try reading out loud your notifications and ask yourself if they make sense.
Don’t use special characters (anything other than letters and numbers). For example, always use "and" instead of ampersand (&). Use correct grammar. For punctuation, use only commas and periods.
If the live region contains a notification specific for screen-reader users that does not appear visually, it is recommended to remove it shortly after it shows up. This is important to avoid screen readers announcing old updates that are not relevant anymore. According to Sarah Higley, a notification doesn’t need to stay long in the DOM. Even half a second is enough because the screen reader is watching the live regions for updates, so it will announce any new content, even if it’s removed right after. Please note that this recommendation does not apply to notifications that communicate user-facing state and status that other ARIA cannot. It is only for content that can become obsolete.
Don’t add too many live regions to the same page. It may cause conflicts if more than one fires at the same time. For example, a "polite" notification may not be announced if an "assertive" notification also happens around the same time. According to W3C, the politeness level is an ordering mechanism and "user agents or assistive technologies MAY choose to clear queued changes when an assertive change occurs".

Keep in mind that if a live region can be avoided, take that route. If possible and if it makes sense for your application, move focus and don’t add a live region. However, focus should only move if it’s because of a user action. Also, depending on the scenario, adding clear instructions may be enough, instead of using a live region.

Taking Control

Screen readers allow users to control how they navigate a web page. For example, they can go first through all the headings of a page before deciding to read a full section. They can also go back and read a specific content again.

But when an element has a live region, the control is taken away from the screen-reader user. They will be forced to hear the notification, either in a polite or assertive way, and that announcement only happens once.

Therefore, developers should use caution when implementing live regions. They can negatively impact a screen-reader user experience if poorly implemented or if there are too many of them, providing non-stop notifications.

If the element requires a live region, then make sure to test the implementation with screen readers to ensure that it works as intended.

Testing

It is crucial to test live regions with different browser/screen reader combinations. And, whenever possible, get your page tested by a real screen-reader user.

If you need help to get started with screen readers, Sara Soueidan has an article with detailed instructions on setting up a screen reader testing environment on your computer. The article also suggests the following pairings for testing based on usage and compatibility:

JAWS on Chrome
NVDA on Firefox
Narrator on Edge
VoiceOver on Safari for macOS,

You will probably notice that the same implementation will not behave the same way across the board. This is because support for live regions vary between how browsers and screen readers are paired together. Since this can result in a poor experience for some users, it's essential to test thoroughly to uncover potential issues and fix them.

Wrapping up

Live regions provide a solution for announcing dynamically added content that would otherwise be missed by screen readers, but their behaviour is not consitent across different browser/screen reader combinations. If adding a live region to your page, follow the specification to implement it in the most robust way possible. Don’t add too many live regions to the same page and only make them assertive if it’s absolutely necessary. Remember to test your live regions thoroughly and re-test often to confirm that they still work as intended. Even better, have your page tested by a real screen-reader user.

Useful links and references

The Implied Web

2023-12-21T00:00:00Z

by Halvor William Sanden

People don’t need call-to-action buttons. Interface elements made to get attention and herd people towards clicks increase cognitive effort because they obscure themselves and reduce interfaces to clickable surfaces.

The implied web is based on the idea that people read interfaces through the glasses of their needs combined with previous web platform experiences. Driven by tasks, they are open to clues about solutions and need clear communication to comprehend and actively move through the interface. In short, people must recognise elements so they can act accordingly.

To better understand how to work with the implied web, we will look at signifier mishmash, intent through HTML and the dynamics of roles.

The impossible element

Interface elements tasked with explicitly communicating clickability make things more complicated because clicking is neither a defining nor a driving factor in the interface; it’s just the mundane way things work.

We make such click-focused elements by taking visual affordance indicators from elements we perceive as communicating clickability, usually the link and the button, and we mash them together. Affordance indicators are aspects of an element that communicate what kind of element they are. They can also indicate state and even hint at actions available to the user in the capacity of what they are. When we make a combined clickable style, maybe as part of a design system, we tend to reapply it to any relevant element. At the same time, we end up removing those elements’ native affordances.

The problem is that there are no affordance indicators or signifiers unique to the click, and HTML has no click element. In other words, it’s impossible to communicate clickability as a standalone concept, and with good reason, telling people to click is a sign of inferior communication.

Action isn’t functionality

What signifies clickability for a link is not the same as for a button or a select. Signifiers belong primarily to elements; they are clues to the functionality of the element, not the action the user can take. The link’s functionality, for instance, is to point to somewhere, not to be clicked. If we apply its underline and pointer cursor to other elements, we communicate that those are also links or share some functionality instead of being the “click here” we wanted to convey.

Elements that don’t share default affordances, conventions and functions end up being too similar. It becomes difficult, if not impossible, to tell them apart.

Countering attention

When we approach elements as communicators of action, we also start adding weight to them based on how much attention we think they should get. Elements we want people to click, or think they would like to click, are made to draw attention to themselves. This comes at the cost of the surrounding elements. It can disrupt the order and make it harder to follow the flow of the interface.

As a countermeasure, we attempt to create a scale of clickability and a system of attention instead of an information hierarchy. We invent our own flavour of interface disconnected from HTML, web platform conventions and actual content or data. We end up with elements that don’t come across as anything in particular; we have effectively diverged communication into visuals and code.

No click here

We cannot work with the action and attention approaches in code. We must work with the meaning and state of elements and roles.

Even though there are ways to steal focus with code, there isn’t a “click me!” HTML element, and no attribute can create an attention hierarchy. What people can do is cycle through element types in various means of interaction, like keyboard navigation or screen readers. Still, attention can only be in one place at a time.

Also, action isn’t one thing. A click is not a click because an element is not an element; they have different functionality. For instance, a link can be alt-clicked, a label click activates its input, and a text input activates itself and enables the actual input functionality.

Meaning through HTML

Programming web interfaces is communication work. It’s not the code’s job to give life to a visual; it’s the visual’s job to reflect the meaning already there.

While HTML doesn’t have a visual side, we can safely talk about an element’s base visual properties as defined by conventions that make them reasonably similar across browsers’ default CSS. They may have different styles, but most of the same affordance indicators are present, such as borders, underlines, hover changes and colours. We shouldn’t disregard an element’s conventions or break them without consideration because there is a direct link between the intentional use of the HTML element and its visuals.

Much of HTML’s meaning comes through roles, and disregarding them means working without the meaning that the web platform provides. In other words, we should work from the HTML elements, their conventions and default styles to bring the affordance indicators into the process. Then, we can consciously override them when necessary.

When the reason behind an HTML element lies in the users’ needs, and not a sketch, we go from writing valid code to writing correct code.

Roles

Central to picking the correct HTML element is its role; that’s where a lot of meaning comes from.

Many HTML elements have implicit roles, and we don’t have to do anything but use the elements. Some roles can also change depending on non-ARIA attributes and ancestor element types. The mapping is done through HTML Accessibility API Mappings (HTML-AAM). A role can be relevant for any means of consumption or interaction, even though the wide range of assistive tech perhaps comes to mind first.

Elements that have no implicit role are generic. That doesn’t mean we can use the elements anywhere; all HTML has designated usage areas. But some don’t need a role, and others cannot have one because the usage wouldn’t work well with things like assistive tech. For instance, div, span and i all have the generic role but different use cases and default visual properties. It would also be fairly annoying to have every div and span announced.

We cannot set the generic role, but we can set the role to presentation or none. In contrast to generic, the two are not exposed in accessibility APIs or accessibility trees.

We can also use the role attribute to communicate meaning HTML doesn’t have by default, though the role would no longer be implicit. Reasons to do this can be because the element is versatile, and it would be impractical to have a default role, or because we need to give an element a role different from its default. We should not explicitly set the same role already implied by the element.

Examples of implicit and indirect roles

The following examples are a few selected elements that demonstrate roles and how some can be affected by surrounding or related code.

header has the role of banner, and footer has the role of contentinfo. When we place them inside article, aside, main, nav or section, or elements that have set the role to article, complementary, main, navigation or region, their role becomes generic.

<!-- header and footer with banner and contentinfo roles -->
<body>
  <header></header>
  <main></main>
  <footer></footer>
</body>

<!-- header and footer with the generic role -->
<article>
  <header></header>
  <footer></footer>
</article>

section has a generic role. When we give it an accessible name, typically using the aria-label attribute, it gets the role of region. Beware that over-use of named sections can cause clutter, but there can be other reasons to write code with these elements than exposing their roles.

<!-- section with the generic role -->
<section></section>

<!-- section with the region role -->
<section aria-label="changelog"></section>

img with an empty alt attribute has the role of presentation. img with text inside the alt attribute has the role of img. img without the alt attribute should be avoided, it has the role of img but it will not have an accessible name.

<!-- img with the presentation role -->
<img alt="" src="/" />

<!-- img with the img role -->
<img alt="horse with beard" src="/" />

<!-- img with the img role but without an accessible name – avoid! -->
<img src="/" />

select has the role of combobox, but if we give it the multiple attribute or a size attribute greater than one, the role changes to listbox

<!-- select with the combobox role -->
<select></select>

<!-- select with the listbox role -->
<select multiple></select>
<select size="3"></select>
<select multiple size="2"></select>

strong and em have the roles of strong and emphasis. Strong is for important, serious or urgent, while emphasis is for just that. Both are misused to a level where their code semantics are no longer useful to screen readers and they are practically just a way to achieve bold and italic like the i and b elements. There can be other software that differentiates between them, so they are still relevant. Markdown and WYSIWYG editors are commonly not in that group and output only strong and em by default, further contributing to the misuse. And we can’t really blame WYSIWYG editors, seeing as they are more WYSIWYGIYCS – what you see is what you get if you can see. The biggest contributor to misuse is probably the microscopic typographic difference. Leaving bold and strong for another article, we typically set things like titles in italic, while emphasis is used potentially to affect the meaning of an entire sentence.

<!-- The author implies that something other than the movie is a better Elvis resource. -->
<i>Elvis</i> is the best <em>movie</em> about Elvis.

<!-- The author implies that other Elvis movies have other leading qualities, such as length or truth. -->
<i>Elvis</i> is the <em>best</em> movie about Elvis.

small, u, i, b, q, pre are some of the elements with generic role, just like span. We should still use them as intended and not interchangeably, as they mostly have different default styling and layout behaviours.
menu has the role of list. It does not have the role of menu or toolbar. It’s identical to ul; there is no inherent reason to use menu except if we want to separate the two in code. If we want to indicate navigation, chances are we already have a nav element with an aria-label. Additionally, the menu element can only have list items inside while nav element can hold complete lists and other elements like headings. The possible mixup with WAI-ARIA’s menu role is reason enough not to use the menu element. The menu role is less about navigation and more about choices and actions like we find in toolbars.
Many specific input types, such as color, date, file and password have no implicit ARIA role. Inputs should have labels and attributes indicating the type and don’t need an additional role to convey meaning.
label has no role and cannot be given an aria-label attribute since it is already a label for another element and cannot be anything else.
Setting aria-label or aria-labelledby is not allowed on several elements such as a without the href attribute, div, p, abbr, address, body, caption and code. Elements that cannot have aria-label or aria-labelledby can be given those if they change role, granted that they can change role. Even though the language might not allow something, it doesn’t mean browsers ignore it. Still, using labels on the mentioned elements could be a sign that another more specific element should be used instead or that something like a heading is missing.

<!-- not allowed -->
<div aria-label="news"></div>
<a aria-label="crows">Crows</a>

<!-- allowed -->
<div role="article" aria-label="news"></div>
<a href="crows.png" aria-label="crows">Crow picture</a>

Implied platform

While a button might be the desired destination of a page, clicking it doesn’t complete anyone’s task as long as the rest of the form is blank. People’s tasks lie at the single input asking for an email address, the form with a well of input types or a table heavy with data; that’s what we must communicate, the path and the information enabling people to walk it, not only the destination.

The implied web is not about avoiding being explicit; it’s about leaning on the platform to tell browsers how it should work for people. Conventions and external consistency enable them to move across different services and domains more easily, and how we make our services should regard that.

Knowing about roles means knowing a central communication capability of the web. We can use it to help people read and comprehend the interface. We can use it to avoid rehashed elements, and we can use it to work with code, visuals and function simultaneously. It’s the direction in which the web moves, again.

Sources and resources

The HTML spec
ARIA in HTML W3C recommendation
Screen Readers support for text level HTML semantics by Steve Faulkner

Design pattern for custom tooltips

2023-12-20T00:00:00Z

by Jan Hellbusch

Should we use tooltips to convey information? Hints and descriptions are often included on web pages through tooltips – but not everyone has access to them.

A tooltip is a short text that usually appears as a popup when a user hovers a mouse pointer over an element. Tooltips can be attached to any HTML element using the title attribute. There are only a few exceptions when a tooltip created with a title attribute will not be displayed (e.g., a title attribute on an iframe element).

In this article, we’ll first take a look at the title attribute in HTML and point out to a few accessibility issues. Then we’ll make a few general suggestions about how to use tooltips. In the third part, we’ll build two accessible custom tooltips with HTML and ARIA, then look at two different CSS solutions and finally add an event handler in accordance with accessibility guidelines. Both tooltips can be previewed:

In example 1, you’ll find a nested tooltip with a basic design using the z-index property.
In example 2, you’ll find a tooltip using the new anchor positioning technique.

Accessibility issues for the title attribute

The title attribute is not particularly accessible. As Steve Faulkner puts it:

If you want to hide content from mobile and tablet users as well as assistive tech users and keyboard-only users, use the title attribute.

https://www.tpgi.com/using-the-html-title-attribute-updated

Assistive technologies include screen readers and screen magnifiers. In terms of accessibility, title attributes lack support for the following user groups:

Keyboard users.
Because keyboard users are only able to focus active elements such as links or forms, browsers can only reveal tooltips for focusable elements. Even then, browsers do not display the content of title attributes on keyboard focus (there were some exceptions for forms on Internet Explorer some time ago).
Screen reader users.
For active elements, browsers will process the content of a title attribute as an “accessible description” when an active element such as a link is focused with the tab key. Usually, the accessible description is suffixed to the link name. That can be helpful in certain situations, but screen reader users won’t necessarily navigate by tab key, because non-focusable content will be skipped. A title attribute can nevertheless be discovered on links, forms and other active elements in a screen reader.
Screen magnification users.
Using a screen magnifier can make tooltips impossible to read. Tooltips included with a title attribute will only be displayed when the mouse pointer is hovering over the triggering element. Using screen magnification, the enlarged portion of the viewport that is actually visible can reduced significantly. In this situation, users will have to move the pointer to pan the tooltip to read the full text. However, as soon as the pointer hovers over the tooltip, browsers will hide the tooltip.

Also take a look at the HTML Standard. HTML discourages the use of the title attribute:

Relying on the title attribute is currently discouraged as many user agents do not expose the attribute in an accessible manner as required by this specification (e.g., requiring a pointing device such as a mouse to cause a tooltip to appear, which excludes keyboard-only users and touch-only users, such as anyone with a modern phone or tablet).

https://html.spec.whatwg.org/multipage/dom.html#the-title-attribute

Best practice: do not use the title attribute to create a tooltip.

Reconsidering using tooltips?

If you are still considering using tooltips on your web pages, be restrictive when using them. There are plenty of guidelines on the web about when to use tooltips and when not, for example:

Do not include crucial information in a tooltip. Information required to finish a task must always be accessible to all users.
Do not include repetitive or obvious text in a tooltip. At best, those kinds of tooltips are distracting.
Keep tooltips short. Tooltips can be a reminder or a brief rewording to a short label.
Tooltips should not cover other relevant content. For example, the tooltip should not cover the label in a form field.

Most importantly, tooltips should only provide descriptive and non-essential text, giving slightly more detailed text for active elements such as links and form controls. Ultimately, they provide expendable text which is already on the web page.

The following code shows a form field with an additional text to be shown as a tooltip:

<p>
	<label for="foo">Full name</label>
	<input type="text" autocomplete="name" id="foo">
	<span class="tooltip" hidden>Enter your first name followed by your surname</span>
</p>

The hidden text is intended to be displayed when the form field is focused. The hidden text is the first step in creating a custom, accessible tooltip as an alternative to the title attribute. The CSS properties to disclose and hide the tooltip will be discussed in Step 2 below.

Best practice: provide only expendable information in a tooltip.

Tooltip accessibility

Make sure your tooltips are accessible. That will include keyboard users and users of assistive technology. An accessible tooltip will have to fulfil the following requirements:

Use correct semantics (HTML and ARIA).
Make sure the tooltip can be displayed by keyboard.
Ensure all users can lightly dismiss the tooltip.

Note that there is more to accessible custom tooltips than just these three aspects. For example, tooltips must also satisfy contrast requirements or adapt to text resizing.

Step 1: HTML and ARIA

If you’re starting from scratch, it is always best to begin with HTML. A tooltip for a link can be set up as follows:

<p>
	<a href="https://www.example.com">
		link text
		<span class="tooltip" hidden>helpful, but non-essential tooltip</span>
	</a>
</p>

The tooltip does not have to be nested within the active element. What you need to consider in HTML is:

Assistive technology must be able to determine the correct reading sequence. The tooltip must immediately follow the triggering component or its label.
You will need to position the tooltip. Nesting the tooltip within the link simplifies CSS positioning.

Note: Users should never be able to focus something within a tooltip. If, for whatever reason, the popup requires focus, then you should be using a dialog element with the showModal() or show() methods. Alternatively, you might need a popovertarget attribute for the triggering element.

Best practice:

When building a custom tooltip, first make sure the HTML makes sense in a screen reader.
Ensure the triggering element can be focused by keyboard.

In our code example, the relationship between link and tooltip seems obvious, but the conveyed relationship must also be determinable by assistive technology. The places to check possible requirements are the ARIA Authoring Practices Guide (APG) or the ARIA specification, if the APG does not provide guidance for whatever you are coding. For tooltips, the APG suggests the following:

The element that serves as the tooltip container has a tooltip role.
The element that triggers the tooltip references the tooltip element with aria-describedby. To this end, the element with the tooltip requires an ID.

Basically, with the aria-describedby attribute we are telling the link what its tooltip is and turning the tooltip into an accessible description for the link. Accessible descriptions for links are exposed to assistive technology users when the link is focused by tab key.

<p>
	<a href="https://www.example.com" aria-describedby="me">
		link text 
		<span id="me" class="tooltip" hidden>helpful, but non-essential tooltip</span>
	</a>
</p>

How useful the tooltip role is when implementing custom tooltips is unclear. Currently, it makes no difference in assistive technology whether the tooltip has role="tooltip" or not. The relationship between link and tooltip is conveyed solely by the aria-describedby attribute. The role has purposely been omitted. You’ll find more on this subject on GitHub.

Best practice: use ARIA only when it is useful to assistive technology.

Explicitly referencing a tooltip from its triggering element is even more important for form controls. Tooltips will not be nested within a component. To better position the tooltip, you might add a span element with a class as in the following snippet:

<p>
	<label for="foo">Full name</label>

	<span class="tooltipWidget">
		<input type="text" autocomplete="name" id="foo" aria-describedby="bar">
		<span id="bar" class="tooltip" hidden>Enter your first name followed by your surname</span>
	</span>
</p>

Step 2: Displaying and hiding the tooltip

For a tooltip to be accessible, displaying a tooltip must not only be possible for mouse users, but also for keyboard and touchscreen users. There are generally two approaches for displaying a tooltip with a keyboard:

Automatically displaying the tooltip when the triggering element receives focus.
Providing a keyboard shortcut to open the tooltip for the focused element.

The first approach makes tooltips easily discoverable for keyboard users, but if a webpage includes many tooltips, the continuous displaying of expendable information can become distracting. The advantage of the second approach to open the tooltip is that users can display the tooltip only on request. But the second approach also comes with some disadvantages:

It is impossible to tell whether the tooltip will show supplemental (helpful) or expendable information. Hitting keyboard shortcuts to display (and hide) tooltips seems to be an unnecessary burden.
There is no standardized keystroke for displaying a tooltip. If you choose this technique, you should use a keystroke common to different platforms for invoking interaction such as space key using JavaScript.
Components with tooltips will require a visual affordance to indicate the presence of a tooltip.
Note: the visual affordance is for sighted users only and should not be accessible to screen readers. Screen readers access the tooltip through the aria-describedby attribute.

We will take the first approach. This seems closer to the expected behavior for a tooltip.

There are two specific accessibility aspects to consider for your CSS:

If tooltips appear on hover or keyboard focus, they must remain visible until hover or focus is removed by the user. Some users will have difficulty reading or even perceiving the displayed content, if the tooltip is hidden after a short time.
Especially users who use a screen magnifier with high magnification can only view small portions of the screen. In order to get an overview of the content, users must be able to pan the viewport, with the magnified portion following the mouse pointer. The tooltip must be displayed as long as the pointer is hovering on the triggering element as well as on the tooltip. See the second condition for success criterion 1.4.13 in the Web Content Accessibility Guidelines (WCAG) 2.2.
Note: the magnification levels vary greatly and 20x, 30x or even higher magnification is quite possible. The higher the magnification level, the smaller the screen portion.

Basic CSS for displaying and hiding a tooltip is fairly straightforward using a nested tooltip. The following CSS declarations create custom tooltips for the link and the input field for example 1. You can use the position property to place the tooltip next to the triggering element:

a:has(.tooltip), .tooltipWidget:has(.tooltip) {
  position: relative;
}

.tooltipWidget:focus-within .tooltip, 
.tooltipWidget:hover .tooltip,
.tooltipWidget .tooltip:hover,
a:focus .tooltip, 
a:hover .tooltip, 
a .tooltip:hover {
	display:block;
	position: absolute;
	left:0;
	top:1em; 
	padding:0.5em 0.75em; 
	background:#334E58;
	color: white;
	border:solid #334E58 2px; /* for contrast mode */
	width:10em;
	z-index:1;
}

See example 1 on CodePen

Best practice: make sure to extend the hover state to the tooltip to allow users to move the pointer over the tooltip without the tooltip disappearing.

There is a lot more to consider when displaying tooltips, for example:

Where should the tooltip be shown – above, below or to one side of the triggering element?
What is to be done if the tooltip is cut off by the viewport?
Can we display tooltips using CSS or do we need JavaScript?
Do you need some kind of package to create your custom tooltips?

As this article deals with the accessibility of tooltips, we won’t go down a rabbit hole to provide answers to these questions. The bottom line is that as soon as you need a flexible presentation of tooltips (e.g., displaying tooltips below the triggering element, unless the triggering element is at the bottom of the viewport, in which case the tooltip should be displayed above the triggering element), you are dependent on JavaScript. You may need to exchange classes for repositioning or redimensioning your tooltip, depending on viewport size and other factors. Your code can get quite complicated. See some assessments on: Tether elements to each other with CSS anchor positioning.

But fortunately, there is something new in CSS that will help solve these issues.

The new CSS feature is anchor positioning. Currently, it will work in Chrome Canary with experimental mode switched on, but it will take some time before it is found in mainstream browsers.

Anchor positioning promises flexible positioning of your tooltips based on CSS and your guidance. First of all, you are not dependent on nesting your tooltips to easily position them. You can rearrange your HTML, but remember that you still need to consider the reading order. The input field from example 1 could be adapted to the following (example 2):

<p class="form-element">
	<label for="foo">Full name</label><br>
	<input type="text" autocomplete="name" id="foo" aria-describedby="bar">
</p>

<span id="bar" class="tooltip" hidden>
	Enter your first name followed by your surname
</span>

With anchor positioning, the example could be adapted to display the tooltip to the right or below the anchor (triggering element), depending on where the anchor is in the viewport:

@supports (anchor-name: --anchor-foo) {
	* {
		box-sizing: border-box;
	}

	input {
		position: relative;
		width: 200px;
		border: 1px solid #334e58;
		anchor-name: --anchor-foo;
	}
	
	input:hover,
	input:focus {
		border: 2px solid #334e58;
		padding: 0.5rem 0.75rem;
		outline: none;
	}
	
	.form-element {
		position: relative;
	}
	
	.form-element:hover ~ .tooltip,
	.form-element ~ .tooltip:hover,
	.form-element:focus-within ~ .tooltip {
		display: block;
	}
	
	.tooltip {
		margin-right: 20px;
		color: white;
		background: #334e58;
		border: 2px solid #334e58; /* for contrast mode */
		position: absolute;
		min-width: anchor-size(
			--anchor-foo width
		); /* Reposition a little bit earlier */
		anchor-default: --anchor-foo;
		position-fallback: --left-to-bottom;
	}

	@position-fallback --left-to-bottom {
		@try {
			bottom: anchor(bottom);
			left: calc(anchor(right) + 0.5rem);
		}
		@try {
			top: calc(anchor(bottom) + 0.5rem);
			left: anchor(left);
			width: anchor-size(--anchor-foo width);
		}
	}
}

See example 2 on CodePen

There are numerous further properties provided in anchor positioning. You can find an introduction by Sebastian Weber on: How to use CSS anchor positioning.

Step 3: Tooltip dismiss

Light dismiss is a term used in the HTML Standard. Light dismiss means that clicking outside of a popover of any sort will close the popover. For keyboard users, light dismiss is equivalent to pressing the Escape key.

Above, we mentioned the second condition in success criterion 1.4.13 in WCAG 2.2. The success criterion has a total of three conditions. When applied to tooltips, the first condition must also be met for the tooltip to be considered accessible:

A mechanism is available to dismiss the additional content without moving pointer hover or keyboard focus, unless the additional content communicates an input error.

Keyboard users also using some form of magnification need a way to clear their viewport from unwanted tooltips. Because of the magnification, tooltips and corresponding triggers can fill a major part of the viewport. They must be able to hide the tooltips by keyboard, for example by pressing the Escape key. Simply moving focus forwards and backwards won’t help.

To prevent interference through tooltips, there are two possible techniques:

The tooltip is positioned so that it does not cover any other content.
You provide a mechanism to dismiss the tooltip by keyboard.

Even if a tooltip does not obscure any other content, it is desirable for the second technique to be applied. In other words, the tooltip must stay visible as long as hover or focus is on the triggering element and the user has not explicitly dismissed it. Only error messages may be non-dismissible (e.g., when remedial action is necessary).

For keyboard users, pressing the Escape key while focus is on the triggering element should hide the tooltip again. We can go back to both of the examples and add the following two event handlers to do that:

let tooltips = document.querySelectorAll("[aria-describedby]");
tooltips.forEach((tooltip) => {
	tooltip.addEventListener("keydown", function (event) {
		if (event.key == "Escape") {
			document.getElementById(
				tooltip.getAttribute("aria-describedby")
			).style.display = "none";
		}
	});

	tooltip.addEventListener("blur", function (event) {
		document
			.getElementById(tooltip.getAttribute("aria-describedby"))
			.removeAttribute("style");
	});
});

Note: by hiding the tooltip directly in the DOM, the style property remains persistent, meaning the tooltip will not be displayed a second time. To prevent that from happening, the style property is removed when the triggering element is not focused anymore.

Best practice: ensure a custom tooltip can be dismissed by keyboard.

Acknowledgements and links

Thanks to Nicolai Schwarz and Tessa Hellbusch for their support.

Links referenced in the article:

Using the HTML title attribute – updated March 2020 (Steve Faulkner)
https://www.tpgi.com/using-the-html-title-attribute-updated/
HTML Standard, 3.2.6.1 The title attribute (WHATWG)
https://html.spec.whatwg.org/multipage/dom.html#the-title-attribute
ARIA Authoring Practices Guide (W3C)
https://www.w3.org/WAI/ARIA/apg/
Accessible Rich Internet Applications (WAI-ARIA) 1.2 (W3C)
https://www.w3.org/TR/wai-aria-1.2/
Clarify the use of role=tooltip
https://github.com/w3c/aria/issues/979
Understanding Success Criterion 1.4.13: Content on Hover or Focus (W3C)
https://www.w3.org/WAI/WCAG22/Understanding/content-on-hover-or-focus
Tether elements to each other with CSS anchor positioning (Jhey Tompkins)
https://developer.chrome.com/blog/tether-elements-to-each-other-with-css-anchor-positioning/
CSS Anchor Positioning (W3C)
https://www.w3.org/TR/css-anchor-position-1/
How to use CSS anchor positioning (Sebastian Weber)
https://blog.logrocket.com/use-css-anchor-positioning/

Boosting testing efficiency: how semantic HTML transforms End-to-End testing

2023-12-19T00:00:00Z

by Stefania Mellai

Semantic and accessible HTML serves as a powerful tool, enhancing not only human interaction but also the efficiency of software systems. For instance, when users fill out forms with clear labels and accessible input fields, this reduces errors and ensures sending accurate data to the backend and databases. You may also have heard about how a well structured web page is fundamental for search engine optimization (SEO).
Creating crafts that are accessible and easy to use for everybody should be the top concern of every developer. The good thing is that prioritizing this aspect can also have a positive side effect: it enables seamless interactions between your website and other software components.
Let's explore in particular how to improve your testing processes and save valuable time.

The Connection Between Semantic HTML, Accessibility, and Testing

This topic was beautifully explored by Rita Castro, in her talk a11y and TDD: A Perfect Match. While Rita mainly focuses on unit tests, it's worth mentioning how these principles can be applied to end-to-end testing as well, and for the same reasons.

The End-to-End Testing Dilemma

End-to-end testing, goes beyond checking individual parts of a website. It tries to act like a real user in a real web browser, testing the whole webpage as it would appear to someone using it for real.

Let's imagine we are writing a unit test for a list item component, that produces the following HTML:

<li>
  A description for this item
  <button type="button">Pick this item</button>
</li>

And the unit test can target the button like this:

screen.getByRole('button')

This approach is great for testing the component in isolation, which is what "unit" means. It simplifies testing by not worrying about other possible buttons on the page and by ignoring context.

However, unit tests can't fully replicate real-life scenarios. For instance, they can't ensure that clicking the button saves some data for the current user and navigates to another page.

Now, consider our list item used in a full web page, with a topbar that contains buttons and other sections beyond the list container. The list in the page wasn't built with semantics and accessibility in mind, so it looks like this (taken from real production web application page):

<body>
  <div id="root">
    <div>
      <div>
        <div>
          <div>
            <div>
              <!-- topbar -->
            </div>
            <div>
              <div>
                <header>
                  <div>
                    <h1>Page Title</h1>
                    <h3>Page subtitle</h3>
                  </div>
                </header>
                <div>
                  <!-- a form for filtering the list -->
                  <hr />
                  <div>
                    <div>
                      <div>
                        <div>
                          <div>
                            <p>A description for this item</p>
                          </div>
                        </div>
                      </div>
                      <div>
                        <button>
                          <span> Pick this item </span>
                        </button>
                      </div>
                    </div>
                    <div>
                      <div>
                        <!-- second item -->
                      </div>
                      <!-- ... -->
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  </div>
</body>

Most end-to-end testing tools can record your actions as you interact with a webpage and then use those actions for automation. They save selectors to automatically identify the items you interact with.
We want to test the click of the button in the first element in the list. I have to confess I simplified a bit the HTML in the example, and the real selector produced by the tool looks like this:

//*[@id="root"]/div/div/div/div/div/div/div[3]/div/div/div[2]/div[1]/div[2]/button

Whenever you tweak your HTML, even adding or removing only one of the div wrappers, your test suite can easily get messed up in this situation. End-to-end tests aren't something you update every day because they are slow and need lots of resources. So, figuring out why a test failed can be time-consuming and take you away from more important tasks.

Testing tools are getting more and more better at identifing targets, but the algorithms are not bulletproof and can't react to page structure changes with 100% reliability. That's why it is important that targets can be recognized without ambiguity. One of the techniques more common to obtain this clarity is adding unique ids, test-ids or other selectors to the HTML elements, but it's not a best practice, for a bunch of reasons:

Separation of Concerns: Mixing testing concerns with your application's business logic violates the principle of separation of concerns. You are coupling two distinct and indipendent objects and a person working in one of the sides may be totally unaware that something is used and necessary on the other side. This person can also be the same person that didn't work on one of the parts for some time and lose the context in the meanwhile.
Maintainability: Test IDs may need to change or evolve as your application grows and changes. When you embed these IDs directly in your code, you may need to make widespread changes throughout your codebase whenever test requirements change. This can be time-consuming and error-prone.
Code Clutter: Embedding test-related identifiers in your source code can clutter the codebase and make it less readable for developers.
Accessibility: Adding test IDs actively misses the opportunity to incorporate accessibility testing for free. If my test suite explicitly looks for a button, it also ensures that the target keeps being an accessible button, and it's not refactored to unsemantic div later.

The Power of Semantic HTML in Testing

Now, envision a different scenario where your list is built with clean, semantic HTML. We don't use the automatic targeting algorithm and we add a manual selector for the first item in the list like this:

//*li[1]/button

Regardless of any HTML changes you make to the sourrounding structure around the list item, your test remains rock-solid. To recap:

Relying on automatic targeting algorithm may result in flakyness and, in best case scenario, you need to regenerate the target. If your tests require adjustements every time you change the underlying structure of your markup, they may not authentically simulate a user journey but instead are too closely tied to implementation details.
Using arbitrary ids or other unique selectors is a bad practice.
Having semantic HTML enables easy manual targeting that is more resilient against changes. It should also help detecting actions that may break the accessibility of your UI.

Why It Matters

So, why should you care about semantic HTML and accessibility in testing?

Developer and QA Bliss: Life becomes easier for developers and QA engineers. Writing tests becomes a breeze when you can work with straightforward, semantic code.
Mimicking Real Users: Your tests better mimic real user behavior. Real users don't look for divs and spans in your web application; they look for headings, buttons, links, and familiar interface elements with clear labels.

Reliability and Time Savings: Your tests become more reliable and won't break with every deployment for arbitrary reasons. Say goodbye to countless hours spent tweaking tests and hello to more productive work.

In conclusion, embracing semantic HTML and accessibility in your development process isn't just about adhering to best practices; it's a game-changer for testing. It streamlines your testing efforts, makes your tests more realistic, and ensures they stand the test of time—saving you precious hours and frustration. So, don't underestimate the power of clean code; it could be your testing superhero in disguise.

The road to HTMHell is paved with semantics

2023-12-18T00:00:00Z

by Vadim Makeev

HTML semantics is a nice idea, but does it really make a difference? There’s a huge gap between HTML spec’s good intentions and what browsers and screen readers are willing to implement. Writing semantic markup only because the good spec is a spec, and it is good, and it’s a spec is not the worst approach you can take, but it might lead you to HTMHell.

Simple days

Like most people involved in the front-end, I started my journey into Web development from HTML. It was simple enough, close to a natural language, and easy to use: you type some tags, save a text file, and reload the browser to see the result. And it would almost never fail if I made a mistake!

Back then, I considered HTML a simple set of visual building blocks. It was too late for purely visual <font> elements (the CSS has replaced them), but the general idea stayed pretty much the same: if you wrap your text into <h1>, it becomes big and bold, if you have two <td> cells in a row, that’s your two-column layout. Easy! I learned tags to be able to achieve certain styles and behaviors. Remember <marquee>?

<marquee
  behavior="alternate"
  scrollamount="7"
></marquee>

That was just the beginning: soon, I needed calendars, popups, icons, etc. It turned out I had to code them myself! And so I did, mainly using divs, spans, and some CSS. Back in the mid-2000s, there weren’t any particular “logical” tags or functional widgets, only the ones you’d find on a typical text editor panel.

But at some point, a trend called “web standards” emerged: it suggested to stop using HTML as a set of visual blocks and start thinking about the meaning of the content and wrapping it into appropriate tags: <table> only for tabular data, not layout; <blockquote> only for quotes, not indentation, etc. The people bringing the web standards gospel were convincing enough, so I joined the movement.

Semantics

Following the trend, we started studying the HTML 4 spec to learn the proper meaning of all those tags we’ve already known and many new ones we’ve never heard about. Suddenly, we’ve discovered semantics in HTML, not just visual building blocks.

<b> and <i> weren’t cool anymore: the proper stress and emphasis could only be achieved with <strong> and <em>.
<ul> and <ol> weren’t only for bulleted/numbered lists in content anymore, but for all kinds of UI lists: menus, cards, icons.
<dl>, <dt>, <dd> were accidentally discovered in the spec and extensively used for all kinds of lists with titles.
<table> was banned from layout usage mainly because it wasn’t meant for that by the spec, but later, we also discovered rendering performance reasons.

Why? Because we started paying attention to the spec, and it was semantically correct to do so. Every decision we make would have to be checked to determine whether it’s semantic enough. And how would we do that? By reading the spec like it’s a holy book that gives you answers in challenging moments of your life. On top of that, there was the HTML Validator’s seal of approval.

But then came the Cambrian explosion that changed everything: HTML 5.

A new hope

Just after the failed promise of XHTML, HTML 5 brought us new hope. Many new elements were added based on existing naming conventions to pave the cow paths. The new spec has challenged browsers for years ahead, from supporting the new parsing algorithm to default styles and accessibility mappings.

For the Web standards believers of the old spec, the new one was just a promised land:

Landmarks to mark logical parts like headers, footers, asides, navigations, sections, and articles.
Variety of new form elements other than the text ones: dates, emails, numbers, ranges, and colors.
Media and interactive elements for video, audio, and graphics.

There was even a logo for semantics in the HTML 5’s design!

Apart from extending the list of functional building blocks, the spec added several semantic elements that didn’t even come with any styling, just meaning. But not only that! Some old, purely visual elements were lucky enough not to be deprecated but redefined. For example, <b> and <i> became cool again, though no one could explain the use cases, apart from rather vague taxonomy and emphasis ones and… naming ships. You think I’m kidding? Check the spec!

<i>Boaty McBoatface</i>

Don’t get me wrong, I think HTML 5 significantly advanced the Web, but it has also detached us from reality even further. Especially the idea of an outline algorithm and multiple nested <h1> elements that would change the level based on nesting. It was never implemented by any browser but existed in the spec for a long, long time until finally removed in 2022.

<section>
    <h1>Please</h1>
    <section>
        <h1>Don’t use</h1>
        <section>
            <h1>This code!</h1>
        </section>
    </section>
</section>

⚠️ Please don’t use the code above. It’s wrong and harmful.

Personally, I’ve wasted too many hours arguing about the difference between <article> and <section> for purely theoretical reasons instead of focusing on good user experience.

Drunk on semantics

Although the spec would provide examples, it primarily focused on marking up content, not UI. Even examples themselves were often purely theoretical with a kind of usage that would be semantically correct, not always practically useful. There’s another whole story about the difference between the W3C and WHATWG spec versions, but the W3C’s examples were usually better.

I’ve seen a lot of weird stuff and did it myself, too. People would often look at the HTML spec as a dictionary, looking up a word in the list of elements for an idea they had in mind. Try to read the following examples through the eyes of a beginner, giving a shallow look at the spec. They totally make sense!

<menu> for wrapping the navigation menus.
<article> for the content of an article.
<input type="number"> for a phone number.
<button> for everything that looks like a button.

I haven’t seen the <slot> element used on a casino website to mark up a slot machine, but maybe only because I’m not into gambling. But the rest of the examples are real.

At the same time, a lot of people would read the spec carefully and use <footer>, <header>, <main>, and other semantic elements properly. But the reason for that won’t be any different: they would also aim for semantically correct markup only because the spec says so. And if it does, the smartest of us would think it should be good for users, search engines, etc. Right?

It turned out that the spec could be wrong, and semantically correct markup wouldn’t guarantee good practical results.

I don’t blame people who gave up on following the spec altogether and became cynical enough to use <i> for icons instead of naming damn ships. Fortunately, I didn’t go this way. I found another reason to keep caring about markup: user experience and accessibility.

Good intentions

Unlike many other languages, HTML is a user-facing one. It means that our decisions directly affect users.

Fortunately, it doesn’t matter how we format our markup, but our selection of elements matters a lot. So when I hear “this markup is semantic,” it often means that it’s correct according to the spec but not exactly good for actual users. Even though both can be true at the same time, the focus is in the wrong place.

It seems to me that we decided to trust the spec’s recommendations at some point without checking whether they were true. I firmly believe that the spec authors’ intentions are always good, and I know many smart people working on the HTML spec. But when it comes to implementation in browsers or screen readers, these intentions don’t always survive the reality.

There are usually three main obstacles:

Product priorities: you probably know that already, but accessibility isn’t always a number one priority for various reasons, including complexity and the lack of people who know the area.
Different points of view: for the same reason, automated testing won’t save you from accessibility issues, different user agents might have other points of view on certain platform features.
Actual user experience: browsers call themselves “user agents” for a reason. When a specific platform feature or how developers use it hurts the users, browsers tend to intervene.

For example, the following list won’t be exposed as a list to VoiceOver in Safari only because you decided to disable default bullets and implement custom ones via CSS pseudo-elements.

<ul style="list-style: none">
    <li>Item</li>
    <li>Item</li>
</ul>

You can force the usual behavior by adding role="list" to every list you style, but how convenient is that? Not at all for you as a developer. But Safari has probably had some reasons, most likely to improve their users’ experience by ignoring all semantically correct lists we started using so much outside of content.

As for the screen readers, Steve Faulkner’s “Screen Readers support for text level HTML semantics” article might open your eyes to the actual value of those tags we’re so passionately arguing about.

No browsers expose <strong> or <em> element role semantics in the accessibility tree.

Again, you can force some semantics via ARIA roles, but should you? That’s an open question. The answer depends on the value you’re trying to bring your users.

Does it mean we should immediately stop using semantic elements if they don’t bear any value for the users? I don’t think so. But I stopped using a semantics argument when talking about good markup. Just like tabs and spaces, semicolons, or quotes, semantics sometimes is a stylistic preference.

There’s also a future-proofing argument that suggests using semantic markup with the hope that someday, browsers will start supporting all those elements they choose to ignore now. I wouldn’t rely on it too much and prefer to focus on what’s important right now.

I used to be among those people who’d judge the quality of a website based on the number of divs it’s built of. We’d say, “Nah, too many divs, it’s not semantic.” Now I know that what’s inside of those divs matters the most. Enough landmarks, headings, links, and buttons would make it good, even if the divs/semantic elements ratio is 1000 to 10. We are divelopers, as Chris Coyier once said. Don’t be ashamed of this, wear this name with pride.

Training wheels

Following spec’s recommendations with semantic markup is still a good start, especially when you treat it as not just the list of available elements. I mostly agree with this idea often expressed by accessibility experts:

If you write semantic markup, it will be mostly accessible.

But to me, it sounds like a simple answer to a complex question. The HTML spec might be a good set of training wheels, but at some point, you’ll have to take them off. Not everything can be solved by semantic markup, for example, you’ll need to learn ARIA to create any modern interactive UI. There’s just not enought semantic elements for everything!

There are many simple answers waiting for you in the spec or articles praising semantics as the only thing you need. There are even more compromises made in modern frameworks in the name of better developer experience. And they aren’t all wrong! But if you keep your focus on the user experience, on the actual quality of the user interface, you’ll be able to make the right decisions.

And you know what? It doesn’t matter if you agree with me on the value of semantics. I’m sure you’ll be fine. After all, you’ve just read a big rant on HTML in the HTMHell advent calendar.

Revisiting Fundamentals - Semantic lists for Improved Accessibility

2023-12-17T00:00:00Z

by Winnie Bosibori

Lists are one of the fundamental semantic HTML configurations that, when implemented appropriately can enhance accessibility.

HTML Lists Refresher

Whenever I visit any website, I have formed the habit of checking for any accessibility issues and delving deeper into the HTML code structure. One apparent thing is that a large number of sites are characterized by non-semantic code structures that result in inaccessible sites.
One common culprit that I constantly come across is poorly marked-up list structures. From having list elements made with the paragraph elements to having headings, div, or span elements as direct children of <ul>, <ol>, or <dl> elements.

As developers or designers, we may sometimes overlook and deem lists as insignificant HTML constructs. However, Without lists, it will be difficult for people to follow content or information on a site. This is because they facilitate grouping related pieces of information, so they are associated with each other and make it easy to read and understand. In addition, people who use assistive technologies such as screen readers may be able to easily interact with a page using keyboard shortcuts.

In this article, we are going to not only point out some of the bad practices that result from non-semantic lists but also provide best practices for creating accessible and inclusive lists. This article focuses exclusively on unordered and ordered lists.

Unordered List

An unordered list is used to represent data or content whose order or hierarchy is not important. The items are commonly displayed in bullet form. A use case scenario for implementing an unordered list includes grouping related hyperlinks or a to-do list. Below is a code sample that demonstrates how to create an unordered list.

<h2> Shopping List </h2>
<ul>
  <li> Apples </li>
  <li> Pears </li>
  <li> Oranges </li>
</ul>

Ordered Lists

The ordered list is used to represent data or content whose order or hierarchy is important. The items are indexed and commonly displayed as a numbered list, in alphabet letters, or in Roman numerals. Some of the use case scenarios for implementing an ordered list include but are not limited to a food recipe guide, a list of instructions for an online registration process, or multiple-choice tests. Below is a code sample demonstrating an ordered list.

<h2> Online Conference Registration Process </h2>
<ol>
  <li>Go to the conference's official website and find the registration section.</li>
  <li>Select the appropriate registration category.</li>
  <li>Complete the online form with personal and professional details, and choose sessions if available.</li>
  <li>Make a secure payment to confirm your registration.</li>
  <li>Check emails for any conference updates and preparations.</li>
</ol>

Semantic HTML lists and Accessibility

Semantic HTML entails the use of HTML tags to convey the meaning of a site’s content. Regarding lists, this refers to the use of lists for structuring or grouping related content, organizing information by importance, and conveying a particular order for processes or procedures.

For sighted users, identifying items organized as lists, including the type of list and the total number of items, is usually straightforward. This is due to their reliance on visual formatting cues like markers and indentation. However, for people using screen readers, the experience differs significantly. Screen readers, when encountering poorly marked-up lists, may fail to announce content as list items or specify the number of items present. Instead, they announce information based on the content's code structure. For example, if paragraph tags are utilized instead of list tags, the screen reader will present the content as paragraphs. This can hinder users' understanding and expectations, as they remain unaware of the actual number of items on the perceived 'list'.

<p>
  • Apples
  <br>
  • Pears
  <br>
  • Oranges
</p>

Bad practice: A paragraph disguised as a list

The use of semantic lists is crucial for people relying on screen readers. They are notified they are interacting with a list, the index of the current item (in the case of ordered lists), the number of items, and the end of a list (NVDA will announce "out of list"). For instance, in the unordered list example, the NVDA screen reader on Windows will announce the following: "List with 3 items: Bullet Oranges, Bullet Pears, and Bullet Oranges". With this announcement, the users are communicated with semantic information (a list), the number of items (3), and the prepended bullet point markers to indicate an unordered list.
Having such information upfront provides people using screen readers with an understanding of what to expect from the content. This is particularly beneficial in situations where establishing appropriate expectations is key to preparing them to interact with the content, enabling them to decide whether or not to go through the list.

Screen readers also provide several navigation techniques that ensure people are navigating seamlessly on a webpage. This is especially important for a web page that features several lists or a large list item. They include: jumping from one list to another, jumping from one list item to another, and in some screen readers getting out of the list. These navigation techniques are aligned with the keyboard to provide shortcut keys for accessing any list content present on a webpage. This resource provides keyboard shortcuts to how other screen-readers interact with lists. The table below provides a summary of the navigation techniques and keyboard shortcuts for navigating lists with NVDA (NonVisual Desktop Access, version 2023.2) screen reader.

List navigation technique	Keyboard shortcut
Jump to next list	L
Jump to the previous list	Shift + L
Jump to next list item	I
Jump to the previous list item	Shift + I
To exit a list	, (comma)

Semantic lists hugely contribute to content readability. This is especially important for people with cognitive and learning disabilities. Large blocks of content can be difficult to read and understand. List facilitates breaking content into comprehensible chunks making it easier to read and understand the structure of the content. This is in addition to highlighting important points that might otherwise be lost when presented in a paragraph. For instance, the use of an ordered list for a food recipe demonstrates that the process has several sequential steps for its preparation.

In summary, lists provide the following benefits for accessibility:

Improved readability
Highlight important points
Provide the total number of items in a list
May announce the current index of an item (in the case of ordered lists)
Provide shortcuts to navigate between lists
Provide shortcuts to navigate between list items

Common Mistakes and how to avoid them:

Here are some common mistakes associated with the implementation of semantic HTML lists.

Using the Wrong List Type

This entails implementing unordered lists when the order is important and vice versa. The key emphasis is if the order of your content or items is not relevant, implement an unordered list <ul> otherwise implement an ordered list <ol>. Below is a code sample demonstrating the relevance of using an ordered list.

Do not:

<h2> Cake Recipe </h2>
<ul>
  <li>Preheat your oven to 350°F (175°C).</li>
  <li>Grease and flour two 9-inch round cake pans.</li>
  <li>In a medium bowl, sift together the flour, baking powder, baking soda, and salt.</li>
 </ul>

Do:

<h2> Cake Recipe </h2>
<ol>
  <li>Preheat your oven to 350°F (175°C).</li>
  <li>Grease and flour two 9-inch round cake pan.</li>
  <li>In a medium bowl, sift together the flour, baking powder, baking soda, and salt.</li>
 </ol>

While both unordered and ordered lists present information sequentially, their implications differ significantly, especially in languages like English which are read from left to right and top to bottom. An unordered list, despite lacking explicit indexing, still suggests a sequence. In contrast, an ordered list emphasizes a specific, often chronological, sequence. By indexing the list items, people are directed to follow the information in a particular order, which is crucial for understanding instructions or processes, as illustrated in the example of the ordered list code. This difference matters in various contexts such as instructional or procedural information, where the order of steps can affect how well they are understood and done.

Using Lists for Non-List Content

HTML lists can sometimes be misused by authors who wish to achieve a particular visual effect on a webpage. This can involve manipulating the typical structure and presentation of lists for reasons unrelated to their intended purpose. One common example is wrapping entire paragraphs of text within <li> tags when the content is not itemized or part of a sequence. This could make the text harder to read and understand for everyone including people relying on screen readers, as it suggests a list structure where there isn't one. Instead, authors should use tags semantically, to reflect the type of content they are communicating. In this case, a paragraph <p></p> constructs are appropriate.

Creating ‘fake’ lists.

This involves implementing items in a way that they are visually recognized as lists. Often, some authors use divs, spans, or paragraphs, decorating them with hyphens, emojis, images, or numbers to simulate list formatting. While this approach might seem adequate for sighted users due to the presence of markers, it falls short for people who rely on screen readers. This is because screen readers announce the content based on its code structure, not on how the lists appear visually.

Don't:

<h2> To-do List </h2>
<div>*Clean</div>
<div>-Exercise </div>
<div>⭐Meal Prep </div>

Do:


<h2> To-do List </h2>
<ul>
  <li>Clean</li>
  <li>Exercise</li>
  <li>Meal Prep</li>
 </ul>

In the first code sample, a screen reader will only announce the text content of the divs. People relying on screen readers will not know that this is a list or how many items are present. However, in the second example, the screen reader will announce the items as a list and provide the context of the number of items, which is three.

Implementing invalid list structure.

Implementing invalid list structures is another common issue on the web. Using divs, p, and spans as direct children-ordered lists <ol> or unordered lists <ul> is not valid. According to the Web Hypertext Application Technology Working Group (WHATWG), it disallows other elements as direct children on <ul> or <ol> constructs as outlined in their HTML specifications. This ensures that content is structured and presented consistently and accessible across various platforms such as web browsers and assistive technologies like screen readers, making it usable for everyone.

Don't:

<h2> My Favorite Fruits </h2>
<ul>
  <li> Orange</li>
  <div> Apple</div>
  <li> Banana </li>
</ul>

Do:

<h2> My Favorite Fruits </h2>
<ul>
  <li>Orange</li>
  <li> Apple</li>
  <li> Banana </li>
 </ul>

Screen readers interpret and announce lists based on the code's structure. Consider the two above code samples with NVDA (screen reader). In the first code sample, a non-list child element is included within a list. This results in a confusing output. Although the screen reader recognizes three items in the list, it fails to correctly identify 'apple' as a separate item. Instead, it announces 'apple' as plain text, seemingly part of the 'Orange' item, leading to an output like 'Bullet Orange apple'. In addition, this creates confusion because the screen reader announces the presence of three items, but effectively only two are clearly announced. In the second code sample, the list is structured correctly with valid items. The screen reader accurately announces the number of items, along with each item's context, providing clarity and understanding of the list items.

Conclusion

Lists, when implemented semantically, are great. They facilitate the visual conveyance of relationships between items, ensuring that information is easier to consume and understand. Assistive technologies such as screen readers can also present information accurately. Let's aim to implement semantic HTML lists so that we can continue creating meaningful structures and content for everyone.

Thank you for reading!

Resources for Further Reading

On the <dl> by Ben Myers
The Unordered List element by MDN (Mozilla Developer Network)
The Ordered List element by MDN
The Description List element
ARIA Lists: Jump to Native ul and ol announcements

Swallowing camels

2023-12-16T00:00:00Z

by Ida Franceen

I don't like how the screen reader pronounces these numbers and I've been experimenting with different kinds of markup to get it to read better, like injecting spans to force it to make proper pauses…

Reflecting on my tendency to obsess over small, but maybe not so important details has led me to write this article. I want to share my experiences and the lessons learned from past projects where I may have lost sight of what is actually important.

The biggest problem

When I'm actively trying to improve the accessibility of a website it's easy to start with the first issue I come across. Maybe the color contrast of the icons in the footer is not good enough, making it hard for people to see them. Let's fix this!
But contrast might not be the biggest and most critical issue. To identify the biggest problem we need to pinpoint the core functionality. Are there any issues there? If yes, I need to fix them first. But what is the core functionality?

Well, if I'm selling things then the core functionality is probably people being able to buy things. However, if I'm focused on getting a screen reader to read prices in a preferred way, and my checkout is broken due to missing form labels, it's a problem. This situation makes it hard for some people to enter their addresses and in the end unable to make a purchase. In this case, I'm definitely focusing on the wrong thing. In other words, I'm straining mosquitoes from my drink while swallowing camels.

100% accessible

I've always wanted to make the websites I'm working on perfect. But there is no such thing. Especially when it comes to accessibility. Websites are either more accessible or less accessible. They are never 100% accessible because we live in an evolving world where there will always be new barriers. This means that while striving for 100% accessibility is a good thing, it will remain an ongoing process of improvement rather than a fixed endpoint.

If my core functionality has big issues then my website is less accessible. Trying to fix it all and I will probably end up just fixing a few of the not-so-important things. If I want to move fast towards being more accessible I need to focus on fixing the core issues. There needs to be priorities.

It's not about me

As a developer, it's straightforward to have a so-called “definition-of-done” where things work properly when I test it on my computer. I know there are other devices and other ways of using the web but I constantly need to remind myself of this. It is really easy to get caught up in details like how a screen reader pronounces things. But it's probably not the most important thing for me to care about.

Yes, of course really bad pronunciation may be an indicator that something is missing. Maybe a proper language attribute? Or maybe my screen reader is not set up properly?

The point is that I need to move away from my priorities and what I find annoying or interesting and consider what might be the biggest obstacle for other people.

Take a step back

So, if I find myself arguing whether an extra div makes it too tricky for people to apply custom CSS it's time to take a pause. Or if I'm spending too much time thinking about whether a description list might be better off as an unordered list then I should take a step back. I need to check the core functionality and make sure that I didn't just swallow another camel.

The Ghosts of Markup Past

2023-12-15T00:00:00Z

by Thomas A. Powell

As a well-seasoned web developer, a clear euphemism for my age, I reminisce about the early days of markup through the haze of strong emotional glasses. I see the past from an extreme nostalgic fondness for the simplicity of the time when a basic text editor and the ability to view source was all you needed. Yet it can just as easily go to a secret shame and embarrassment of admitting that we hacked around with invisible pixels, nested tables, and all manner of quirky presentational elements.

This post attempts to map those extremes and the space between them. The ultimate outcome would be to encourage you to personally explore the history of the web to unearth things that could be rediscovered, recycled, or recast for the modern web as well as learn from past mistakes. So let’s get going, and I promise we will tread a path that isn’t as annoying as a scolding about the innovation of the <blink> tag.

Searching for Markup Ghosts

Before we get started with our naughty, nice, and best never spoken again list of markup from years prior let’s take a moment to address the source of these historical gems. There are basically three sources for much of HTML’s early innovation.

The various proprietary introduced by browser vendors, particularly during the so-called browser wars of the late 1990s. Many of these elements eventually became part of the standard in time.
The W3C HTML specifications, especially those which didn’t see uptake like HTML 3
Use case specific markup to support the web on devices like WebTV and early smart phones

Let’s quickly explain each source and provide a brief commentary to temper what you find in our list of markup relics.

Spoils and Victims of the Browser Wars

The browser wars of the late 1990s were mainly a two-way battle between Netscape and Microsoft. They eventually ended with the dominance of Internet Explorer and a period of relative stagnation of web development in the early 2000s. However, during this warring period, we experienced tremendous markup innovation, some excellent, some misguided and some a foreshadowing of the challenges we currently address.

Interestingly, many unusual markup elements and attributes live on from that time so you can use them in your modern browser of choice. Others will require you to find an old browser likely running on an operating system circa that time period. For those we aim to understand the mistake or idea of the markup.

HTML 3 - The Spec That Would Never Be

Another place to mine for interesting thoughts about markup was the ill-fated HTML3 specification. An interesting source for this lost specification was a book by Dave Raggett I still have in my collection. I hope you marvel how for a moment we almost had footnotes (<fn>) for the web, a collection of common dingbats, many more semantic tags, and even relative measurement units in a few places.

The specification is filled with all sorts of interesting tidbit that likely deserves an article series of its own. Alas, most of these lost specification elements never found their way to browsers. You might be interested in them to have a more nuanced view of the time period or even as inspiration for what you might implement as a custom element or web component.

Early Devices - WebTV and More

Lastly, an interesting place to find ancient innovation is to see what was implemented to support WebTV, the first broadly used web appliance. WebTV added many features that will seem familiar in intent to what we do today to support mobile devices. Interestingly, I’ll also briefly talk about the existence and influence of wireless-focused markup in WML (Wireless Markup Language).

Note: If you really want to experience WebTV the best route is to watch videos like this one on YouTube.

The Web Ancients Sometimes Had Wisdom And Sometimes Didn’t

As someone who worked in, taught, and wrote about web tech last century, many things have not only stood the test of time in terms of value, but have largely been reinvented in modern times out of ignorance. I may allude to such points wherever possible, but for now, I present a view of overarching themes we’ll encounter in many places.

Some Best Practices Are Forever

WebTV and Wireless Markup Language (WML) exposed a constraint focused approach to web development that should ring true for best practices and performance minded developers today. For example,

WebTV encourages that pages should be smaller than 250K

Source: WebTV Developer’s Guide

Apparently they wanted you to consider a performance budget. The also encourage developers to use simple forms, write concise text, and test on the actual hardware! Hmmm…apparently good advice is quite timeless!

Encourage Medium Restriction

The constraints of device based Web at the time was quite severe. To address this WebTV both encouraged developers with advice like

…WebTV-based systems in North America and Japan (both use the NTSC television standard) display Web pages in a fixed 544 x 372 screen space. Pages may scroll vertically but not horizontally. Pages that are wider than 544 pixels will be scaled to fit that width.

We should acknowledge that the idea of scaling pages is not dissimilar to what we do to address phones these days with appropriate <meta> viewport, relative measurements, and responsive design.

Convert and Constraint the Rest

Besides encouraging developers to do the right thing, many web capable devices of that time period relied upon converting proxies to convert unsupported content. For example, WebTV would transform frames into equivalent layouts using tables and transcoding images for more performant situations. These folks weren’t the first doing such things AOL had already been doing it for years when they started gatewaying to the open Internet.

The TV-based web wasn't the only place where device constraints and conversion thinking were employed. Early smart(er) feature phones often did cellular carrier-level conversions. You'll also see that an HTML subset/superset in strict XML was popular in the late 90s and early 2000s called WML. WML’s strictness was required because implementing a permissive and sprawling browser on the phone wasn't feasible. This markup language adopted a different, less page-oriented mindset, opting for a <card> style metaphor to allow users to move through screens. Many of these ideas would seem not too dissimilar to Google's AMP (Accelerated Mobile Pages), implemented nearly two decades later.

Let’s Go Already

So enough of the broad themes, let’s get going already and I promise I won’t throw too many random things like the fun fact that WebTV supported something called JellyScript which was their version of JavaScript! Sure it sounds weirdly tasty, but it’s time to get to the list of arcane markup.

Note: Much of this content comes from my personal collection of books from the time period, including my own books like HTML: The Complete Reference.

Where possible, I try to reference information via archive.org, but some are lost to time and poor search. This is not an excuse, but it reminds us of the sad state of online information preservation. Because of this, I must admit to relying on my error-prone human memory. If you, too, were present during this time and have corrections or better pointers to active resources, please add them to the comments below.

My Incomplete List of Arcane Markup

<audioscope> dance party - WebTV introduced a graphical display of a current playing sound over time. Yes, that is an odd description. Maybe watch this YouTube video to get the idea of something you’d be hard-pressed to experience today.

<au> for authors - This HTML 3 semantic element was used to set the page author’s name like so <au>Thomas A. Powell</au>. Not a bad element, but the name was certainly not gold, I would prefer something like <author> if we are going to revive it.

<banner> useful and unimplemented - This was an unimplemented HTML 3 element to display a non-scrolling region at the top of a page like <banner>Check out our new tags!</banner>. Such things are done today with a <div>, other semantic block elements, or even a web component. Interestingly these and other elements from HTML3 will work in the Lynx browser!

<bgsound> be gone - This Internet Explorer introduced element allowed for Midi, Wav, and other audio format files of the time to be played on a page background and even looped. Why link to a video when you can <bgsound src="never-gonna-give-you-up.wav" loop="infinite"> an unsuspecting visitor. The best part of this ancient Rick Roll is that you can’t modify the volume level or stop the playback. You’d think they’d blast that tag if only they had Devtools, which came years later with Firebug and eventually native browser tools. Today, we have <audio> if you must perform such a gag on your friends or enemies.

<blackface> NSFW? - A WebTV addition used to set double-weight boldface. This jargon is from typographical tradition, but an article-skimming reader might worry about racial insensitivity. It's here as a warning that markup is a language, too, and as such, beliefs and norms can and do change. It’s a good thing nobody uses this platform or element anymore!

<blink> returns? - The tag so many love to hate and one of the few relatively possibly degradable tags that got fully deprecated. Don’t worry though, if you pine for the old days just add a custom element and emulate away!

<body> attribute bonanza - Netscape, Microsoft, WebTV, and even very esoteric browsers like Oracle's proprietary browsers threw all sorts of attributes on the <body>, from common things like setting background colors (bgcolor) and images (background), to lesser-known attributes on WebTV to define page credits, logos, background attachment, link colors, scroll speed, margins, and more. This element always required significant revisions for each edition of my book as it was in constant flux. Most of the color and basic layout features still work, so don't be surprised if you spot some of these attributes in the wild today. (Demo)

<center> evil and easy

The <center> tag was a powerful tool back in the day. For modern web devs who have fought floats, auto, flex, and finally reached a simple solution with CSS grid it almost feels like we are back to where we started.

Color attributes galore - Devs broadly chanted “Grey grey, grey go away, bring us color every day!” when Netscape introduced color for the page on <body> with bgcolor and text, tables, and for the <font> tag. Understand that Netscape, not Microsoft, was initially responsible for a significant amount of the presentational ideas mixed into HTML. Don't blame them too much, the developers of the time really wanted them!

Data binding had promise - Starting with IE4 the idea of data binding was introduced via the datasrc attribute to point to a data source to populate into a tag like <table datasrc="URL of data">. For example, we might use this technology to point at a data source or an internal data island using Microsoft’s <xml> tag to embed some non-rendered data in a page not too dissimilar to how <script src="some-other-type"> or <template> is used today for creating data islands. Once data was fetched, then the table rows would be dynamically rendered.

To implement data binding, output control is needed, so various tags such as table cells (<td>), <div>, and <span> were extended in Microsoft browsers to support a datafld attribute to select the field and the dataformatas to specify to treat the retrieved content as text or HTML.

Today, this form of client-side data binding is broadly implemented using JavaScript frameworks. Still, using web components, you could certainly implement a modern form of data binding even with remote REST sources. We implemented this very thing in my product ZingGrid, and I have observed many people employing similar ancient IE-like data binding ideas themselves. The concept clearly was useful, just too early.

Dingbat icons - HTML 3 had a very interesting concept to have HTML provide a standard set of dingbats that could be included in pages. Between emojis, extended Unicode entities, icon fonts and scalable SVGs we handle this quite differently today, but back then we might have had &new; to insert a small new icon or a clock icon with &clock; and so on. Interestingly many HTML 3 elements supported the dingbat attribute such as <ul dingbat="new">.

A funny thing is just how time period these were as they include binhex files, diskettes, CDs, 3270 terminals, and even a Gopher server! Take a look at the figure to see some examples from the HTML 3 book.

<font> had more - A <font> tag is up there in terms of elements people frown upon, but at the time, it really was the only choice we had unless we wanted to put text in an image! The syntax isn’t that unfamiliar to many, but you might be surprised besides the face, color, and size attributes we saw in WebTV effects like emboss, shadow, and transparency. Furthermore, from Netscape 4.x and Internet Explorer 4.x we had custom font support. Albeit, it was using odd formats and wasn’t ready for use. Before we got to the custom fonts we enjoy today, things got even worse using hacks with Flash like SiFR. Today all these approaches to typefaces on the web have been thrown in the dustbin of history where they belong.

Footnotes almost happened - Footnotes are still missing from HTML today which is pretty odd considering the amount of academic content we put online. Obviously you can simulate such a construction, but HTML 3 provided the <fn> tag like <fn id="arcance_markup">The Ghosts of Markup Past</fn> and link to it as you might any standard target. While the element name isn’t great this probably deserves a revisitation in future HTML explorations.

Form fields for devices - Many changes (<input>, <textarea> and more) for non-computer browsers - WebTV foreshadows how data entry on a device other than a standard computer can be difficult. The device supported a showkeyboard attribute to help you enter data most notably useful for <textarea> and eerily predictive of today's inputmode and others for assisting form fill-out on mobile. WebTV also experimented with attributes to format (allcaps and autocaps), avoid interactions (autoactivate and autosubmit) and various controls to fit the display such as color and images for fields.

<frameset> and <frame> - Sure, Jakob Nielsen’s famous screed Why Frames Suck (Most of the Time) from 1996 scared many off from this feature which was actually part of the W3C HTML 4 specification. They still secretly work in almost every browser and when leveraged properly exhibit better performance and usability than most modern JavaScript solutions. Interestingly, a fallback with <noframes> has always been available. Do you dare explore them? I hope not.

<iframe> - What’s this known element doing on the list? Well, believe it or not, at first, this was the non-standard element not <frameset> and <frame> which are in the specification. Initially introduced by Microsoft IE3 this element avoids deprecation because of its containment usage, but a fun arcane fact is that it wasn't officially part of a markup standard until HTML5!

<img lowsrc> for slow loading images - Many browser vendors implemented the lowsrc attribute to display an image first as the main one loads. Today we reinvent this and call them low-quality image placeholders (LQIPs) executed with JavaScript and CSS. Sometimes the old ways should have lived on!

<img dynscrc> to support animations and movies - Somehow predicting the return of animated GIFs or movies instead of images, Microsoft and WebTV supported the dynsrc attribute to load a dynamic asset as opposed to a static image. You could add playback buttons with the controls attribute. The desire to improve <img> to support videos to avoid the performance abuse of animated GIFs is an open topic today. The dynsrc attribute is yet another old idea that might have helped us out of our current troubles.

<input type="scribble"> was a weird idea - HTML 3 really got innovative, if that is the appropriate word when proposing this extension to <input>. It’s not as if that element isn’t already overloaded, but there was the idea of <input type="scribble" src="chart.gif" value="Annotate this chart"> which, as the example implies, would allow you to scribble on the image. Oddly, the value attribute wasn’t for instructions but rather described fallback text. The whole thing seems extremely under-specified and was never implemented, like most of the new elements introduced by HTML 3.

<layer> might be a relief from

madness

- Maybe this positioning and layering focused box element wasn’t really such a bad idea since we have just have abused <div> every since anyway. Oh and don't forget <ilayer> it's lesser known relative tag for inflow positioning. These elements certainly didn’t live on, but I am sure if you wanted to simulate them with a custom element you could! Please don’t, really don’t.

<link> power unrealized - HTML 3 had common ideas like loading a stylesheet setting document relationships (next), but it also appears they had a limited inclusion format. For example, you could keep an external message in a file referenced on pages like so <link rel="banner" href="announcement.html">. This tag touches on the need for native fragment inclusions within HTML that has yet to materialize, but I still hold out hope that someday they might.

Lists had images and more - HTML 3 proposed the use of dingbats and images on many tags, most notably unordered lists (<ul>). The idea was you could both set an image <ul src="images/star.gif"> as well as a dingbat (<ul dingbat="new">). The WebTV platform wasn’t nearly as aggressive with its special list features, but it added support for <ul type="triangle">. Why you might ask? Simple, CRT monitors of the day were so low resolution that a circle and square bullet type pretty much looked the same at small size!

<marquee> lives on - Microsoft’s response to Netscape’s <blink> is actually quite involved and still supported. It is just as annoying, but for some reason doesn't have the same level of hate. There is lots you can do with a <marquee> tag like control the direction, the repeat, the speed and even use presentational attributes and nest content to keep the 1990s web alive in my silly demo and recall last years advent entry on marquee as well!

maxlines far ahead of its time - The maxlines attribute was added to tags like <td> and others to clip content on a space constrained WebTV display. It's a great example of ideas like content clipping and overflow that didn't come to CSS until much later, but interestingly were present in some corners of early web dev.

<multicol> a bad idea then and now - Unless you kept fixed to the viewport a multiple column layout is quite a bad idea usability wise. It certainly didn't stop us from implementing multiple layout natively in CSS! The element had basic attributes to control columns (cols) and spacing (gutter), but like most presentation HTML it was far from enough and CSS wins the day.

<note> should have stayed because we make these anyway - One of my personal favorites in HTML 3 is the callout ideas using a note element. The role of the note referred to often as admonishments was set by the class attribute defining the role of the enclosed text. For example, <note class="warning">None of these tags were implemented</note>.

The written record suggests that “HTML 3 aims to provide the author with ready-made styles for purpose" so there clearly were different thoughts about class use than we have today. If you really must explore this Lynx does support it as you can see here as well as the previously mentioned footnote (fn) element.

<person> yet another semantic element - Another HTML 3 semantic addition this element might be used to define an index of people, maybe for a directory like so <person>George Washington</person>. Seems like this is better handled by a <meta> element or micro-data using a data-* attribute, but the intention seemed roughly correct. Using a rel attribute on <a> is another approach to personal data and is covered in a great entry from last year's calendar.

<select> early innovations - Making menus with <select> has been the thorn in the side of many web developers to this day. Interestingly the web ancients had thoughts. First, WebTV solved a problem we still face and solve with JavaScript via a showempty attribute to handle an empty select list and a default message. Second, HTML 3 even wanted to include images and shapes in menus with some odd image map like construct. It's not worth explaining something so utterly bonkers, but it does make me wonder if the upcoming <selectlist> will really be any better?

<sidebar> it’s like frames, but easier - WebTV had lots of limitations and they were quite creative with how they addressed them. The <sidebar> element allowed you to pin a non-scrolling region to the left side of the screen. Obviously useful for navigation bars and the like, it was in some sense a way to have a frame like experience when they couldn’t support frames.

<shadow> emerges - Before CSS introduced them, you could make a text shadow at least on WebTV without using an image. This <shadow>drop</shadow> example would drop a small black shadow down and to the right on that platform. Clearly something that doesn't belong in markup, but a fun lesser known example of ancient presentational HTML.

<spacer> made layout hacks easy - When Creating Killer Web Sites why add an invisible pixel to your page? Netscape 4 innovates a tag <spacer type="block" width="100" width="100"> that does just the same!

<tab> or spaces please no for HTML - This element will make your presentation mixed into semantic markup warning meter go to 11. HTML 3 proposed that we have <tab>, <tabstop> and even <tab to t8> which was some weird attribute without an assignment to get to a particular tab level. It even had an align attribute to tab from different directions. I acknowledge that layout on the web was hard in the early days, but revisiting this "solution” was even was probably the worst part of my markup historical tour.

<table> Layout Simplicity? - Many modern web developers will clown on the idea of using tables stacked or nested as some ancient way as they nest <div> tags like fiends. Interestingly it was quite possible using a combination of relative units in percentage and fixed values to provide variable flexible layouts. Add in some colors and rudimentary alignment with <center> and more and away you go. Try the demo and resize it. I used upper case and more to have some real 1990s fun that still works in your browser.

Transitions - Both WebTV and Microsoft Internet Explorer had some interesting thoughts about inter-page transitions. While Microsoft used a very strange ActiveX powered mechanism for filtering and transition effects, WebTV’s syntax was a simple as <a href="page" transition="slideleft">Load Page</a>. If you squint hard, you'll see the emerging MPA transitions ideas from the View Transitions API being played with almost 25 years ago!

VRML - To round out this list, let us reminisce about VRML(Virtual Reality Markup Language). Being that I am associated with UC San Diego, which is significantly responsible for this technology, I can bear some sliver of responsibility for this technology. I only conclude our list with this technology as it seems appropriate with the recent introduction of <model> and likely many more ideas like WebXR that will become real with the arrival of the Apple Vision Pro. The past really did predict the future, albeit at a much lower rez!

Back to the Markup Future?

There’s a lot more I could have revealed in this historical markup tour including hacking with expected HTML bugs documented in my book as well as others, various interesting HTML 3 ideas with checksums, list control, and even incredibly esoteric browsers with their special elements. The point of this list was to expose enough of the ancient ideas to help us get ready for the future.

As a language, HTML really isn’t done as languages rarely finalize. However, it’s been stagnating for some time. Looking at the new things landing in the last year or two, clearly, this is no longer the case, and it is nearly certain we will see many new markup elements this decade. Some are in the pipeline due to new devices, emerging web access modes such as AR and VR, and the desire to standardize UI elements via (open-ui.org). However, if market competition heats up due to browser-related regulatory action, you can almost guarantee we will see a back-to-the-future moment in web technology with all sorts of new features introduced as browser vendors try to capture or retain market position. Hopefully, these arcane blasts remind you that this has all happened before, and it will happen again and again and again…

Getting started with Web Performance 🚀

2023-12-14T00:00:00Z

by Alistair Shepherd

Carefully observing websites in the wild

As the murderous tortoises start to converge on Ryūji’s hideout, they pull out their phone. It’s a cheap, older device but it’s survived the toils of the tortoise-ageddon well so far. Thankfully the internet still exists, although a bit slower, so they’re able to search online for how to scare tortoises away. The first result looks promising so they quickly tap through to find the information they need. But as the loading bar moves at barely a crawl, Ryūji realises with horror that this website is loading far too slowly—20 seconds have passed and it’s still just a white screen! They look up and realise they’ve run out of time, poor website performance was Ryūji’s downfall.

As Ryūji discovered, web performance really matters, and is about making websites fast. I hope that most of us don’t encounter as drastic circumstances as they have! For the rest of us a well performing website is more accessible to people, offers a more enjoyable experience, and may even encourage more views, shares or sales.

But web performance is also quite tricky! Let us go through some of the reasoning, jargon, metrics, tools, and some top tips on how you can improve the performance of websites you look after. Whether you’re a practised performance prophet, dipping your toes into the river of load times, or are desperately hoping someone will explain what an FCP is and why Google wants one, let’s all dig into web performance together!

We’ll be diving into the river of load times and exploring what web performance is, why it’s important, how to measure it and finally my click-baity “Ten Wild Web Performance Tips! You’ll be saving number 5 for later!”. If you already know your CLS’ from your FCPs, lab from field data, and are well familiar with Lighthouses (not the ones with big lights) then you can jump straight to the tips.

Before we start getting into it, there’s one thing I want to make super clear especially if you haven’t spent a lot of time with web performance: Web performance can be pretty tricky. I mention this so you don’t get demoralised if you hit a wall or struggle to identify an issue as we’re going to fill your performance toolbox with some great metrics, strategies, tools, and tips. These will help you make some real improvements, but know that even with years of experience some things are still a challenge to find! With our toolbox you’ll find that developers, designers, and even managers can each make a meaningful impact on website performance without necessarily being crowned Speed Supremo.

Why web performance is important, why should we care?

Web performance can often be overlooked, and that’s generally a big mistake. It’s easy to put it on the backlog, assume your development tooling is solving it for you, or think that modern hardware and networks remove the need completely.

But performance is just as important as it ever has been, perhaps even more so! More people than ever are online, relying on the web for crucial services, yet the gap in hardware between the best iPhone and cheapest smartphone has never been more extreme. For that reason, web performance isn’t just a tech problem to solve, it’s a social issue. Our societies require people to use websites, yet we serve 10MB poorly-optimised JavaScript-heavy ‘apps’ via metered connections to a $30 smartphone—that’s never going to work!

Phew, I got a bit serious there! To reiterate, building a website that performs well is important not just for SEO and sales, but also to open the web to more people making it more inclusive and accessible to all.

On a personal level, I travel on trains quite a bit and there’s nothing like free train WiFi or spotty 3G or 4G in rural areas for showing up websites with poor performance (at least in the UK!). When one site takes 5 seconds to load and another takes 50 seconds, I know which one I’d prefer to use.

If you need more convincing, web performance can often be directly correlated to business metrics like traffic, conversions, and sales. WPO Stats lists fantastic performance-related Case Studies if you need material to send to your boss or client. Google is also using web performance as a ranking factor in its algorithms—I’ve seen performance improvements increase impressions from Google Search by 300%. That’s nothing to scoff at!

What does web performance look like?

Simply put, web performance is how fast a website loads and feels, and how fast it feels while using it.

There are a few different factors that we’ll get into, but a website that takes a second to go from clicking the link to a fully complete page is pretty quick. On the other hand a slow page might have a long loading screen, parts missing for ages after load, or take a second to react to every click.

Video description

The video shows two websites loading side-by-side, with a timer below each of them. The page they're loading is visually identical at the end, but they load differently.

The page itself features the HTMHell logo, a title of "HTMHell's Handsome Hat House", a couple of 'article' images, some placeholder content and a large image of hats filling half of the page.

On the left the page loads in with unstyled text after 1 second. As images slowly load in top-to-bottom, they move the other page content around. After 13 seconds the headings increase in size and change style, which after a further 2 seconds is replaced with a custom font. The page finishes loading at 15 seconds.

On the right the page loads in a lot faster, and without any images moving content around. The images and font load in significantly earlier, and the page has finished loading at 4.8 seconds.

Full size video

Performance science with Metrics

Now we know what web performance feels like! Unfortunately feeling is notoriously a not great™ way of comparing things, and humans unfortunately haven’t evolved the ability to instinctively determine web performance just yet. I have been trying to hone my sense of Time To First Byte but am yet to see positive results.

There’s some good news though, the web performance and development community have come up with some fantastic tests, metrics, and analysis methods to help us measure, understand, and compare performance. These make it easy to quantify improvements, set measurable goals and find out where websites can be improved.

I am back with the bad news though: there’s bloody loads of them. They’re a mixture of meaningless jargon and 3 or 4 letter initialisms that will leave you extremely confused and wondering if you’re reading a sci-fi novel. Just take a look at some of this mess:

If you know your web perf and questioned PES and THWIMP, pat yourself on the back. Those ones aren’t real and I’m pulling your leg. PES is obviously Parakeets Eat Seeds and a THWIMP is obviously this cutie from Super Mario World:

In all seriousness however, there are loads of metrics, definitions, and jargon that are so easy to forget or get confused about. I’m going to simplify this down, and give you a glossary and description of only the metrics you really need to know. For the moment this will be a summary, we’ll get into the tips on how to fix them later!

Core Web Vitals and the Chrome User Experience report

If you’ve used Google’s Pagespeed Insights or Search Console then you may have already heard of Core Web Vitals or the Chrome User Experience report.

Core Web Vitals, initialised to CWV, is a collection of metrics that help to measure web performance in a way that emulates how a user may feel about performance. Google collects and analyses these metrics and a few others to know how fast a website performs. These results can then be used in their search algorithms to reward well-performing websites.

How do they collect those metrics? People navigating with Google Chrome have the performance of the websites they visit anonymously recorded and sent to Google. That’s where the Chrome User Experience Report (CRUX) comes in. CRUX consists of a giant database of the real-world performance of all websites that are visited by a statistically significant number of Chrome users.

You can access CRUX data through Pagespeed Insights, Google Search Console, Google developer APIs, and using various other tools. You can also query the database itself using Google’s BigQuery, but watch out as that can get expensive quickly!

The three metrics used in Core Web Vitals are some of the best we have to understand how fast a website is for real people, and so those metrics will be what we focus on. You can find lots more information about these metrics and many more at web.dev, I’d recommend checking that out for more technical info.

LCP — Largest Contentful Paint

“Wow this website is taking a long time to load” we may say, as we click on a link and are left with a blank or sparse screen for what feels like an age. What we’re seeing here is a slow Largest Contentful Paint.

Video description

The video shows two pages loading side-by-side, with a timer below each of them. The page they're loading is visually identical at the end, but they load differently. The page itself features the HTMHell logo, a title of "HTMHell Horticultural Heuristics", some placeholder content and a background image of some house plants. Both pages load the logo, title and content similarly within 3.5 seconds. The page on the right loads a background image in relatively quickly, appearing all at once at 4 seconds in. The page on the left takes significantly longer to load the image, doing it from top-to-bottom and taking 15.7 seconds before it's completed.

Full size video

LCP measures how long it takes for the largest single piece of content to appear when loading the page. That piece of content could be an image, heading, video, or graphic. For most websites it ends up being a large ‘hero’ image at the top of the page, although this varies per-site.

The goal of LCP is to understand when the main parts of the page load—the parts that the visitor will be most interested in. Your goal should be to load those elements as fast as possible. Aim for an LCP of 2.5 seconds or less.

INP — Interaction to Next Paint

Imagine we’re browsing a website and click a button or link. We expect it to react instantly but instead we’re left waiting. Did it work? Maybe it didn’t go through? Should we click it again? Turns out it was just very slow at reacting to clicks. We’ve encountered poor Interaction to Next Paint in the wild.

Video description

The video shows a page with HTMHell logo, a title of "HTMHell Humour Hobbies" and a set of accordions.

The recording shows a user trying to interact with the accordion buttons, but it takes a second or two after clicking before the accordion responds, making it a bit confusing as they seemingly randomly open/close.

The accordion titles are a bit silly:

What are the HTMHell Humour Hobbies?
Is this entire thing complete nonsense?
Am I good at coming up with placeholder content for demos?
No it appears that I'm probably not actually

Full size video

How a website appears is a major part of performance, but if everything appears quickly yet takes a second for any of the buttons or links to respond that’s pretty frustrating! Interaction to Next Paint measures the time it takes between the user interacting with a page and the website something on the screen in response.

Websites with lots of JavaScript running in the background or heavy tasks (like network requests) running on clicks may take longer to ‘react’ to a button press. Your goal should be to make sure interactions are as snappy and responsive as you can. Ideally this will be as fast as you can make it, but you should aim for at least within 200ms.

Note: Interaction to Next Paint is not yet in Core Web Vitals—it’ll replace the similar First Input Delay (FID) in March 2024. I would recommend focusing on INP already though, you’ll be getting ready and very likely improving FID at the same time!

CLS — Cumulative Layout Shift

We’re buying a new Microwave online, have just gone through the full checkout process and are about to click confirm. Oh silly us, we’ve accidentally added 10 Microwaves! We go to click the Cancel button, but suddenly an advert appears, shifting the “Confirm” button to where we clicked! Disaster! That’s Cumulative Layout Shift, one of the trickiest and most frustrating performance metrics.

Video description

The video shows a page with HTMHell logo, a title of "HTMHell Hamburger Heating Hardware", and a product page for a microwave. There's an image of a generic microwave, a title of "Microwave", description "A very good microwave I'm sure" and "Selected quantity ×10". Below are two buttons, one saying "Pay now — $6,000" and another saying "I don't need that many microwaves".

The recording shows a mouse cursor reviewing the page and highlighting the quantity line. They then go and hover over the "I don't need that many microwaves", but just before they click an advert appears above the two buttons. The advert says "YOU NEED MORE BARBECUES BUY BARBECUES AD" and shifts the two buttons down so the user has instead accidentally clicked on the "Pay now — $6,000" button. It changes to "Loading...", the user highlights things in frustration and then the buttons and ad are replaced with a message saying "Success! Enjoy your microwaves".

Full size video

Cumulative Layout Shift measures the amount the page shifts around in an unexpected way. Our Microwave example is particularly drastic, where someone ends up doing something they didn’t want to do based on the page shifting. In addition to interactive elements shifting under someone’s cursor, CLS can create extremely frustrating reading experiences where sentences jump around whilst you’re reading them.

CLS is trickier to quantify than LCP and FID. Throughout the user’s visit, every content shift will be given a score based on how much it moved and added up for a ‘cumulative’ total. Lower is better here, so a single small shift may be 0.04 units, whilst a huge advertisement loading late, and pushing content out of the way would be higher at 0.5. You should aim for absolutely no CLS, but less than 0.1 at least.

Some bonus metrics if you’re keen

There are plenty more metrics, and a few others that are very handy to know!

Bonus Metrics: FCP, TTFB, SI and FID

First Contentful Paint (FCP) is similar to Largest Contentful Paint (LCP), but whilst LCP measures the largest piece of content rendered on the screen, FCP measures the first content shown. I guess it is in the names.

Your FCP could be triggered just by a small amount of text, leaving the page still looking mostly incomplete until the titles, graphics and images appear after. It doesn’t really suggest how fast the site feels, but it is helpful to understand how quickly something is shown, even if this is not the main content of the page.

Time to First Byte (TTFB) is a very simple metric: How long does it take from the very beginning of the request to zoom off to the server and come back with data? TTFB doesn’t tell you anything about what that data is and how long it will take to fully load or appear on the screen, but it can give you some insight into how fast or far away your server is.

Speed Index (SI) is a really handy general metric that provides a rough idea of performance, but doesn’t really tell you any specific information. It measures how quickly a page is visually complete above-the-fold (what is visible on first visit without scrolling). It’s a bit older but still handy for comparison and ongoing tracking.

First Input Delay (FID) is similar to Interaction to Next Paint, but uses a slightly different measurement method and only considers the first input. Interaction to Next Paint is likely more useful especially once adopted by CWV but FID can give you a good impression of responsiveness.

Testing 101

There are lots of fantastic tools and services that help you to measure and check the performance of websites. Each provides you with access to at least some of the metrics we’ve discussed above, and many will also make it easy to see where improvements can be made. These vary in depth, functionality, and difficulty so try them out and see what works best for you! Most of these tools are free, but there are some bonus paid ones.

One distinction to keep in mind is that not all kinds of tests are the same when it comes to web performance. There are two main types, lab tests and field tests.

Lab tests are run in a controlled environment, like a laboratory! They go off and do some experimentation on your website and report the result. This might be run on your computer or on a remote server. They’re very good at giving you controlled, somewhat consistent results with lots of debug information and suggestions.
Field tests are real-world testing, including the Core Web Vitals we mentioned previously. The data they report comes from real users and is a better representation of how your website performs ‘in the wild’. They’re best for knowing how your website performs on real devices, on real networks and for your audience.

Google’s Page Speed Insights is a handy tool that combines running a lab test with Core Web Vitals to gain some simple field test data. By entering a URL, you’ll get average scores across the Core Web Vitals, alongside a few other metrics from CRUX. It will also run a lab test from a Google server giving you those metrics along with some more in-depth info and suggestions. Page Speed Insights is a fantastic place to start with performance, as it makes it really easy to get the information you need and some tips on what you can improve. Don’t take the improvement times as gospel though, you will likely see some improvement but unlikely as much as it says!

Screenshot of a PageSpeed Insights result for developer.mozilla.org

Lighthouse is a lab test that is built into Google Chrome and most Chromium-based browsers. It’s actually what powers the Page Speed Insights lab test and gives you the same information, but because this runs from your computer you have a little more control over the test conditions. You can access it by opening the browser developer tools with F12 and going to the “Lighthouse” or “Audit” tab. It’s a very easy and handy way to quickly check a page you’re working on.

Screenshot of a Lighthouse report for htmhell.dev

I really like GTMetrix for performance tests also, and similar to Page Speed Insights and Lighthouse it’s extremely easy to use and gives you direct feedback and suggestions you can look into. It’s based on a lab test, reports all of the common metrics and has suggestions on improvements that are helpfully categorised by “Impact” which makes prioritising improvements a bit easier.

Screenshot of GTMetrix performance report for htmhell.dev

WebPageTest is amazing, and is where we start to get into the more technical and powerful tools for performance testing. It runs a lab test that is extremely configurable and returns a huge amount of data that you can then analyse. Although it does give you some suggestions, its real power is exposing data about the full loading cycle to you in a way that you can really dig into. For example, did a specific third-party script delay the loading of other assets? When you need to really analyse a website in a repeatable way with as much data as possible WebPageTest is ideal.

Screenshot of a very small part of the WebPageTest report for htmhell.dev. There is much, much more and a lot more depth that the summary you see here

In addition to Lighthouse, Chromium-based browsers have some very handy performance tools built into the development tools. The Network pane is handy for seeing the full list of requests made by the browser, where they came from and how long they took. This is ideal for checking request order, caching behaviour, and what third-parties are being connected to. The Performance pane gives you even more information about how the browser is performing, including JavaScript call stacks, frame counts, tasks in the event loop, and more. These are pretty advanced tools but very powerful.

Screenshot of the Performance tab within the Chrome developer tools. The first things you would look at here are Network, Timings, Frames and Main

Firefox and Safari also have handy performance tools built-in. Safari has the Timelines tab which records a page load and provides screenshots and a huge amount of detail on Network Requests, Layout & Rendering, JavaScript & Events, and CPU usage. Firefox’s Network tab works similarly to Chrome’s with the addition of a quick “Performance Analysis” which reports details about content types, weights, and caching.

We’ve discussed the Chrome User Experience Report a few times already, and a couple of methods of getting that data. One way you can access that data, particularly when looking at how average measurements have changed over time, is by using the CRUX History API. There are a few tools for accessing this, but my favourite is through the CRUX History API notebook on Google Colab. By inserting a URL and a free CRUX API key you’ll be able to see graphs of how CRUX metrics have changed over time.

Those are the main free tools which I use regularly for testing, but there are a few others that may cost money or are a bit more specific:

Calibre — automated lab testing and monitoring
Speedcurve — automated lab and field testing, and monitoring
Speedlify — open-source tester and aggregator of web performance and accessibility
Treo — automated lab testing and core web vitals analysis
Open-source tools based on Lighthouse — there are a ton of open-source tools that use lighthouse for whole-site crawling and testing and more

Ten Wild Web Performance Tips! You’ll be saving number 5 for later!

Okay, now it’s time for the section we’ve all been waiting for, unless you skipped here from the links in the intro. If you did, you missed some real great stuff up there and at least three jokes that I should have never committed to writing.

On these specific tips, they are some of the most common issues and fixes for websites I encounter. Not every site has all of them, but generally at least a handful. Going into the exact code and details for each will put everyone to sleep, but they’ll give you somewhere to start looking!

1. Test! Test! Test!

Tools like the ones above can make it easy to see a simple summary of web performance and give you tips on what to focus on. Run some lab tests after major changes to confirm you’ve actually improved performance, or to check you haven’t caused a regression.

Also consider setting up automated performance monitoring to monitor performance over time, alert you to regressions, and to flag issues on specific pages before lots of visitors are affected.

2. Optimise images, optimise them again, and then once more for good luck

Unless you already have perfectly optimised images, they are always the first place to look for performance improvements. In most websites the Largest Contentful Paint element is an image, and generally a huge amount of the total ‘weight’ of pages are images.

There are a few different things you can and should do when optimising images:

Compress images to reduce file size at the cost of quality. If a 85% quality image at 100kB looks identical to a 100% one at 2MB it’s an easy choice
Convert to more recent image formats like WebP, AVIF or JpegXL. These formats may make certain images a lot smaller than their JPEG and PNG counterparts
Resize images to the exact size you need them, and use responsive images with srcset to offer smaller sizes. This way a browser doesn’t download a huge image it doesn’t need

Manual processing tools like squoosh.app make it easy to convert, resize, and optimise images by hand. A CMS may also have partial or full automatic optimisation, or you could consider an image CDN like Cloudinary, Imgix or CloudImage to help optimise and resize images on request.

You can also use loading="lazy" on your image elements to wait until they’re in view and needed before downloading them, and Priority Hints with fetchpriority="high" to ask the browser to prioritise downloading your LCP image sooner.

3. As little JavaScript as possible

JavaScript is the most expensive resource in terms of performance on the web, and is a really common bottleneck when used too much.

Where you can implement something in HTML or CSS then do, and make sure your pages can start rendering without JavaScript.

Avoid large JS libraries where you can and instead use built-in JavaScript APIs, progressive enhancement, or smaller and more performant libraries.

4. Watch out for third-parties

Third-party code, tag managers, analytics tools, embeds, and more can have a huge impact on performance. Where it’s possible, consider removing these, or at least take measurements to make sure everyone is aware of their impact!

You’ll be amazed at the number of marketing departments that ask you to “fix their site speed” despite having seven tag managers enabled.

5. Cache me if you can

If someone has visited your site and their browser has downloaded all the resources once before, should they really need to do so again?

You can use caching headers to make repeat and subsequent visits a huge amount faster by reusing static assets like CSS and JavaScript instead of having to re-download them frequently.

6. Be bold, optimise your fonts

One of the biggest culprits for Cumulative Layout Shift issues is due to web fonts. With a poorly optimised web font you may find your website loading almost entirely with a fallback font or invisible text, and then the entire page shifting as the font kicks in at a different size.

In an ideal performance world you could consider using a system font to avoid loading web fonts at all. In most cases though we can keep the web font but optimise it to make it load faster and more smoothly!

Serve the font from your origin/domain instead of a third-party
Limit the number of font files you need to load by reducing the number of weights you use. Do you really need a regular, medium and a semibold?
Use font-display:swap; within @font-face to smooth the switch from fallback to custom fonts
Subset fonts to just the characters you need with a tool like glyphhanger. If you have a website in only ASCII characters you can reduce your font sizes by up to 50%!
Variable Fonts combine multiple font weights and styles into a single font file. Whilst it may be larger than a single non-variable font, it’ll generally be smaller than 3 traditional fonts. Go variable it if you can!
Preload the most important font or two using <link rel="preload" as="font">

Depending on the licence of your font you may not be able to do all of the above — particularly subsetting or loading from your server — so make sure you double-check the font licence first. As Google Fonts are open-source you can do all of the above!

Zach Leatherman and Harry Roberts have some fantastic further reading for font optimisation.

7. Server side speed shenanigans

This is one for the full-stackers, back-enders, all-rounders, and devops!

If your website relies on a single, slow server then you may have bottlenecked your site performance on your server speed. If it takes 2 seconds before the browser receives the HTML to render then no matter how much you do on the front-end that’s going to be your limit. You can get an idea of this by looking at the Time to First Byte on a fast connection close to the server. It depends on the systems and work being done but you want to be as close to 0ms as possible, definitely under 500ms.

You can improve this by optimising your servers and code, using a CDN like Bunny CDN or Fastly to cache HTML that’s the same for every user, or by speaking to your web host.

8. Stop sharding, or too many origins

Back in the day it was good advice to split up your assets across multiple origins/domains to deal with connection limits in HTTP 1, and to use public CDNs for shared caching. That hasn’t been good advice for a long time now since HTTP/2. It’s time to get everything on one origin!

Put as many assets on your main domain as possible. HTTP/2 or 3 can easily handle those resources and it avoids extra connections to new domains which takes valuable time.

Browsers used to allow websites to re-use a cached resource with the same URL across different domains. This provided a way to track users however so all browsers now separate the cache of each origin. Using a public CDN no longer gives any benefit to resource caching.

9. Split that code

If you have some CSS or JavaScript that runs on only a single page, consider loading that separately only when needed, rather than across the entire website. It will improve the speed of all other pages, and avoid the extra cost of downloading something that a user might never use!

10. Consider preloads, but here be dragons

Preloads are a way of having more control over how the browser loads resources. You can use them to ask for certain assets to be downloaded in advance of when they’re needed, or to make the browser prioritise one asset over another.

Be careful with them however, preloading one asset will always delay the loading of something else so it can be very easy to accidentally make things worse!

Preloads are particularly handy for font files, where the browser won’t start downloading them until the CSS has downloaded and rendering has begun. It can also be used for images or other assets that you’re finding are discovered too late.

Web.dev has an article about preloading critical assets.

What next?

Now my friends, go forth and make fast websites! I hope that you’ve gained more knowledge, confidence, understanding, and resources to test, diagnose and make websites perform better.

This is just the beginning, and there are loads of fantastic resources and people to follow to further your journey to Practised Performance Prophet!

Courses

Lightning Fast Web Performance by Scott Jehl
Everything I Have Done to Make CSS Wizardry Fast by Harry Roberts

Books

Responsible JavaScript by Jeremy Wagner — Book
Image Optimization by Addy Osmani — Book

Blogs

HTML: The Bad Parts

2023-12-13T00:00:00Z

by Mayank

You've probably heard statements along the lines of "HTML is already accessible by default" or "You don't need to reinvent this perfectly fine HTML control". I consider these to be more of general claims rather than universal truths. It's extremely important for web developers to recognize gaps in the platform. To that end, I've decided to collect a few instances where HTML falls short, through accessibility issues or usability issues.

This is not a comprehensive list, and it does not include gaps in ARIA. I wanted to find a balance between widely known issues and more frequently encountered (but lesser known) ones, while making sure to include some things that we take for granted. In each section, I will include its severity, alternate suggestions, and links where you can find more detailed information.

`<select multiple>`

Let's start with an easy one. The multiple attribute on <select> should pretty much never be used. It's like the polar opposite of single <select>, where instead of universal familiarity, it has universal unfamiliarity. Perhaps its only saving grace is that I have yet to encounter this attribute in any codebase.

To quote a screen-reader user (from Sarah Higley's excellent article linked below):

This is a broken listbox. This is entirely broken, I don’t see any way of doing anything with this.

Impact: High. There is a good chance most of your users will not know how to navigate this monstrous control.

What to use instead: A list of checkboxes is a totally fine alternative; or you could build a custom multi-selectable listbox.

Further reading: <select> your poison part 2: test all the things (article by Sarah Higley).

`<i>` (for icon)

Let's do another easy one to warm up. The <i> element is semantically insignificant, so it's not necessarily “bad” if used for regular text content. More frequently though, it is used for icon fonts.

I wouldn't even normally include this in the list, since this is more of a developer error than a platform issue. However, it is 2023 and I still regularly encounter the <i> element being used with something like FontAwesome. This is problematic mainly because it involves using a web font to visually substitute text characters (which may have one meaning) with icons (which are completely unrelated to the text characters). As a result, the text characters, even though they are generated in CSS, are part of the page's content and will be included in the accessibility tree by default. In addition to that, it looks bad, breaks often (and in hilarious ways 🐴), and leads to other accessibility issues. You can learn more about all of these issues in Tyler Sticka's post linked below.

Impact: Low to medium. You could make it less inaccessible by excluding it from the accessibility tree (using aria-hidden) and providing a text alternative (using visually hidden text), but it will still remain problematic.

What to use instead: SVGs! They are well supported, and better in many important ways. Unlike icon fonts, SVGs are properly designed to display graphics, so they will not result in unexpected text being added to the accessibility tree. There are tons of different ways to use them too, so you can have your pick, whether you like inlining, using sprites, or keeping it within CSS (using mask).

When using <svg> elements, a reliable pattern is to use aria-hidden alongside an additional text alternative (which may be visually hidden if needed). For example, the markup for a button might look like this:

<button>
	<svg aria-hidden="true"><use href="#heart" /></svg>
	<span>Favorite</span>
</button>

Further reading: Seriously, Don't Use Icon Fonts (article by Tyler Sticka)

`<ul>` and `<ol>`

I can't make a list (heh!) of problematic HTML and not include lists in there.

I'm not going to say “don't use lists”; lists are very useful in many scenarios. But developers have a tendency to overuse lists, often just to remove list styles anyway. Sometimes we may even slap an ARIA role on it (thus overriding the list semantics), or worse, add non-<li> children for styling purposes or otherwise (thus producing invalid markup). In all of these scenarios, we are losing any benefit provided by list elements, and potentially introducing new issues.

Safari has noticed this overuse of lists, dubbing it "list-itis", and has started removing list semantics in certain cases; lists that are outside a nav and are styled with list-style: none are not considered to be lists by Safari. While this change was surely done with good intentions, it has the unfortunate effect of making even legitimately styled lists purely presentational.

In addition to all of this, ordered lists have their own oddities. Browsers consider the item numbers to be "presentational", so when selecting and copying a list, the numbers are not included in the plain-text clipboard entry. This breaks user expectations, especially when the numbers are important, as in the case of legal documents.

Impact: Low to medium. I think it's totally fine to let Safari/VoiceOver do its thing; in fact, their users are likely used to it and may even expect an almost list-free web. The clipboard issue with ordered lists can be quite serious, but there are workarounds.

What to use instead: If you really need to preserve list semantics, role="list" can be added to <ul>. If you're already using a different role, then plain <div>s should work fine. <dl> is another potential alternative for key-value pairs.

<ul role="list">
	<li>…</li>
	<li>…</li>
	<li>…</li>
</ul>

If the list item numbers are important, consider using unordered lists where the numbers are part of the text content.

Further reading: "Fixing" Lists (article by Scott O'Hara), Twitter thread by Apple's James Craig, and "I Blame the W3C's HTML Standard for Ordered Lists" (article by Sibylla Bostoniensis).

`title` attribute

The title attribute is the one that frustrates me the most, particularly because of its long history. It is so bad that the HTML spec explicitly warns against using it. And yet I've seen this attribute used in almost every codebase I've worked with.

Some of the many issues with title include:

Sighted keyboard users have absolutely no way to access the title content.
Touch-screen users also cannot access the title content.
The default tooltip styling cannot be changed in any way.
The trigger needs to be hovered for an arbitrarily long delay before it appears.
The tooltip cannot be dismissed without moving the pointer, and therefore can obscure other parts of the page.
The tooltip cannot be hovered over, meaning the mouse needs to keep hovering the trigger element. As a result, the tooltip could become obscured by the mouse pointer, its text will not be selectable, and screen-magnifier users may find it impossible to view it.
The text inside the tooltip does not scale with the user's zoom level.
Long text inside the tooltip cannot be made to wrap; in some browsers, it will become as wide as the screen itself (even escaping the browser window bounds) before it starts wrapping.
There is no way to indicate if the title content should be part of the element's accessible name or description (or neither).
Screen-readers do not consistently announce the title content on all elements.

Impact: High. By relying on this attribute, you are making the intentional choice of leaving out a large percentage of your users.

What to use instead: In many cases, including the text as part of the element's content can suffice; this text could be visually-hidden if necessary. In other cases, aria-labelledby or aria-describedby will work better than title. One exception is iframes, which need to be labeled using title.

In almost all cases, a custom tooltip, in addition to the techniques described above, would also work better than title. However, tooltips come with their own set of problems, so an even better solution would be to redesign the interface to avoid needing tooltips altogether. For example, you could always show the text or use a disclosure pattern.

Further reading: The Trials and Tribulations of the Title Attribute (article by Scott O'Hara), and Using the HTML title attribute (article by Steve Faulkner).

`<datalist>`

At first, the datalist element sounds like a promising alternative to custom comboboxes. The more you use it though, the more disappointed you'll find yourself.

This element has very questionable default styling.
- On Chrome desktop, it appears as a weirdly offset popover that can drastically shift its position while the user is typing; at the same time, it becomes detached from the input when the user scrolls away.
- On Chrome Android, it appears above the virtual keyboard (rather than on the page) and only in portrait mode.
Its appearance cannot be customized at all. It does not even respect the color-scheme.
It does not respect the user's font size or zoom level.
It generally has good support on desktop screen-readers, but on mobile it requires navigating to the very end of the page to interact with any options.
It does not work on Firefox Android at all!

Impact: Medium to high. At best, this element can be useful as an optional hint for input fields that would still be perfectly usable without the added help from autocompleting options.

What to use instead: <select> or a custom combobox. 🤷

Further reading: Under-Engineered Comboboxen? (article by Adrian Roselli)

`<input placeholder>`

Placeholder text is intended to help the user by providing a hint when an input is empty. In practice, it often ends up doing the opposite.

Placeholder text is usually prone to color contrast issues. If you try fixing color contrast, it may end up looking indistinguishable from real input values. If you put important information in it (like password requirements, or god forbid, the label itself), the input value will hide this important information as soon as the user starts typing.

Impact: Medium to high. At best, it may be ignored. At worst, it may frustrate your users and impact your revenue.

What to use instead: Nothing? A prominently visible label may be sufficient. If you do need hint text, consider placing it outside the input, and associating it using aria-describedby.

<label for="phone">Phone number</label>
<input id="phone" aria-describedby="phone-hint" />
<div id="phone-hint">Example: 123-456-7890</div>

Further reading: Don't Use The Placeholder Attribute (article by Eric Bailey)

`<input type=number>`

Let's cut to the chase: number inputs will increment/decrement when using scroll wheel or gesture or arrow keys, making it extremely prone to accidents. Yikes!

And that's in addition to its other accessibility, consistency, and styling issues.

Some browsers will silently discard non-numeric user input without any feedback.
Other browsers will allow entering arbitrary numbers but fire events with empty values, thus losing user-entered data.
The "spin" buttons are extremely small and difficult to click.
The "spin" buttons cannot be styled (beyond simple color scheme).

Impact: High. The scrolling issue alone is enough to make this a dealbreaker, as users could enter the wrong number without even realizing.

What to use instead: <input inputmode="numeric" pattern="[0-9]*">. The inputmode attribute helps show a nicer keyboard on touchscreen devices, and the pattern attribute helps with validation.

Further reading: Why the GOV.UK Design System team changed the input type for numbers

`<input type=date>`

Native date pickers have many browser inconsistencies, with some parts of them being inaccessible.

On Chrome desktop, the calendar button cannot be tabbed to.
On Safari desktop, the date picker cannot be closed using keyboard.
On Safari desktop, the date picker is minuscule and cannot be scaled up.
On Chrome and Firefox Android, the date input cannot be typed into, forcing the use of the clunky calendar UI even if the date is familiar to the user.

In all environments, the date format is shown as placeholder text which, as we've already established above, is problematic. The browser determines the date format, and it may choose something strange (like the US date format), leading to unnecessary confusion.

Impact: High. These inconsistencies are not just minor differences, they introduce real barriers to access.

What to use instead: Honestly, use simple text inputs, or even selects in some cases.

You can also use separate inputs for date/month/year and group them with a fieldset. This fieldset could even be styled to look like one contiguous form field. If you choose to hide the input labels though, I would also suggest showing the date format outside the inputs (as part of the legend or below the inputs).

Custom date pickers are notoriously hard to get right, so if you choose to one, it should be optional and in addition to the text inputs.

Further ~~reading~~ watching: What makes an accessible date picker? Is it even possible? (talk by Russ Weakley)

`<menu>`

Just don't. Whatever you expect this element does… it probably doesn't. The <menu> element was originally intended to be a "context menu" but it never got anywhere, and now it is replaced by <ul>.

Impact: Low. <menu> is simply remapped to <ul>.

What to use instead: Because the term “menu” is so overloaded, it depends on what you're trying to accomplish. Some alternatives include:

<ul>(or role="list") when you have a list.
role="menu" when you have a desktop-like menu.
role="listbox" when you have something resembling a custom <select>.
<dialog> or role="dialog" when you have a generic popover (perhaps with a role="list" inside).

Do note that some of these roles require custom JavaScript interactions to be wired up.

Further reading: Be Careful Using 'Menu' (article by Adrian Roselli)

`<button disabled>`

Disabled buttons are strangely overused, perhaps due to their familiarity. Two common scenarios for disabled buttons include:

when an action is temporarily unavailable, perhaps due to requiring some prerequisite task (such as selecting an item or filling a form correctly).
when submitting a form, to prevent duplicate submissions.

However, the disabled attribute does more than just prevent clicks. It also prevents hover and focus capabilities. This has many negative ramifications. Disabled buttons cannot show tooltips (which may be important for explaining why the button is disabled). Keyboard users cannot Tab to disabled buttons. If a button suddenly becomes disabled (e.g. when submitting a form), focus could get lost and create a confusing experience. Additionally, disabled buttons are exempt from color contrast requirements, increasing the likelihood that it will have poor contrast.

Impact: High. Disabled buttons selectively serve a small percentage of your user-base (and not very well either).

What to use instead: Use aria-disabled="true" and manually disable clicks. If possible though, consider reworking the design to avoid needing disabled buttons altogether.

Further reading: Making Disabled Buttons More Inclusive (article by Sandrina Pereira)

`<video>`

The native video player still has many accessibility and usability issues. For keyboard users, focus is a recurring issue across browsers, because not all controls can be reached, and the controls disappear once the video starts playing. For screen reader users, the experience is lacking in some areas, especially for more "advanced" features like picture-in-picture mode.

I highly recommend checking out Adrian's article below for a deep-dive on support across various browsers and screen-reader pairings.

Impact: Medium to high.

What to use instead: Unsure. Maybe a custom video player, if it's built with accessibility in mind. Regardless of what you use, please include captions and a transcript, and provide a way to download the video for offline viewing in the user's player of choice. Oh and please for the love of your users, do not use autoplay.

Further reading: Browser Video Players Review (article by Adrian Roselli)

Link protocols (`tel:`, `mailto:`)

Links on the web can have a non-http protocol like mailto: or tel:. These protocols are commonly used as a supposed way to help the users (or spammers) send an email or dial a number. However, this makes a very bold assumption is that the user is visiting the webpage on the same device that will be used to send the email or dial a number and wants to use the default application to do so. This can lead to frustration when the user is just looking for a way to copy the number or dial it from a different device. To make it worse, the actual address/number often gets hidden underneath the link, instead displaying something useless like "Email me".

Impact: Low to medium. It's confusing and annoying, but not the end of world I suppose. Users will (reluctantly) find workarounds.

What to use instead: Just show the actual email address or phone number. It is trivial to copy or manually transfer it over to the desired device. Additionally, many devices will automatically display a prompt when selecting text that can be recognized as an email/number.

Further reading: tel:me.about.it. (article by Brian Kardell)

Wrapping up

In closing, I just want to reiterate that accessibility is not as simple as "just use HTML". Even with best intentions and pristine HTML source, we may end up with inaccessible UIs if we don't do our due diligence.

I'm sure this list will look different (hopefully shorter) 10 years from now. As more people start to take interest in these things, it will create more awareness. It will push standards bodies and browser vendors to improve the platform and get us closer to a more "accessible by default" web. You can personally help move the needle by opening new bugs or by commenting on existing ones:

Chrome/Blink: https://bugs.chromium.org/p/chromium/
Firefox/Gecko: https://bugzilla.mozilla.org/
Safari/WebKit: https://bugs.webkit.org/

Test-driven HTML and accessibility

2023-12-12T00:00:00Z

by David Luhr

When I started writing unit tests and following a test-driven development (TDD) workflow, I was stoked with the immediate feedback and confidence I gained in every line of JavaScript I wrote.

TDD improved my software design with simpler, more predictable code. It saved me countless hours of manual debugging by reporting errors directly in failing tests. And with solid test coverage, it allowed me to add new logic and functionality while keeping everything in an always-working state.

I followed the process of Red, Green, Refactor, meaning I wrote a failing test, wrote just enough code to make the test pass, and then freely cleaned up my code, knowing everything was working. My JavaScript code had never been better.

Then one day, I wrote a UI-oriented test that used document.querySelector(). Before the test even finished running, it errored and revealed that JavaScript tests run outside of the browser in Node, where no document object model (DOM) exists. Since the focus of my career is evaluating, designing, and developing accessible user interfaces, primarily with HTML and CSS, I wanted to apply TDD techniques to HTML and accessibility. But it seemed like my dream testing setup wasn't possible.

Months passed of continuing to enjoy TDD with JavaScript, while wishing I could do more to test my accessible markup. Most of my research pointed to slow, flaky approaches like scripting an entire headless browser just to check if an HTML element rendered or if a menu opened on click.

Other testing libraries use synthetic (faked) interactions by dispatching DOM events that might lead to false positives in tests if they don't accurately replicate real user interaction. Plus, these libraries don't have the necessary DOM events for all interactions. I wanted to write small, focused, fast unit tests that provided trustworthy, immediate feedback with every change I made.

Then I came across a tool called Web test runner from the team behind Open Web Components. Instead of running JavaScript tests in Node, Web Test Runner executes tests directly in the browser.

This is a big deal for multiple reasons:

Tests run your production JavaScript code in the production environment—the browser
Tests have access to the real DOM, unlocking the ability to write tests for HTML, accessibility, and even CSS
Tests can send native interactions, such as actual mouse clicks and keyboard input, instead of faking them with DOM events
And it's even possible do things like set the viewport dimensions to test responsive design

Shift accessibility feedback earlier

With this approach, I write tests to capture my expectations around semantic markup and accessibility upfront, then get instant feedback on whether my code meets those expectations.

Let's say I expect paragraph (<p>) elements shouldn't be empty. I can write the following test, which gets all <p> elements, loops over them, and expects each one doesn't have empty text content:

describe("paragraphs", () => {
	const docAllParagraphs = Array.from(document.querySelectorAll("p"));

	it("have text content", () => {
		docAllParagraphs.forEach((paragraph) => {
			expect(paragraph.textContent).to.not.equal("");
		});
	});
});

With access to the real DOM in tests, I can continuously check if I'm using heading levels, ARIA, and landmark regions correctly. I can build custom UI patterns and ensure they respond to keyboard input and manage focus as expected. And as I add new features or refactor my code, my tests re-run with every change to make sure I don't harm accessibility as the project evolves.

Accessibility-focused linters give feedback as you code, but have limited awareness outside of very specific violations. Automated accessibility audits and most manual review happens after you write the code. Test-driven accessibility is about providing continuous feedback before, during, and after you write the code.

Using all these forms of accessibility testing together provides the most value. Unit testing HTML allows me find, fix, and prevent accessibility issues as I'm working. It also allows me to focus my manual accessibility reviews on more holistic evaluations, such as navigating through a page with a screen reader to asses the user experience.

This test-driven approach makes something possible that I've been striving for in my work: an accessibility-first workflow. With an accessibility-first mindset, we plan for and preserve accessibility from the beginning of a project instead of leaving it as an afterthought. If I could achieve one thing in my career, it would be to make accessibility-first a foundational practice alongside usability, responsive design, performance, and security.

Evolve code with confidence

In addition to getting feedback upfront and continuously thereafter, having tests allows us to change our code freely as features and user needs evolve.

The downside of automated accessibility testing tools and manual review is they can't be performed continuously, and often focus on the current page in the browser. We either have to manually re-test with each change we make exhaustively across all pages, or we depend on getting feedback after batches of changes.

With tests in place, we can keep our code (and accessibility) in an always-working state. Every time we make a change, our tests run across the entire codebase. If our tests pass, we can more confidently and frequently deploy our changes to users.

The setup

To begin testing our HTML in the browser, we first install our dependencies:

npm i --save-dev @web/test-runner @web/test-runner-mocha @esm-bundle/chai @web/test-runner-commands @web/test-runner-playwright

We need Web test runner to run tests in the browser, Web Test Runner's implementation of Mocha for directly testing HTML files, Chai for test assertions, Web Test Runner commands for sending native interactions (click, keyboard, etc.) to our UI elements, and Web Test Runner's implementation of Playwright for headless browsers to run the tests in.

With this setup, we run our tests in Chromium, Firefox, and WebKit all at once to make sure our code works across the major browsers. This happens super quickly in the background and works in different operating systems.

Even through browser cross-compatibility continues to improve, this testing setup reveals discrepancies that would be incredibly difficult to otherwise detect. For example, I recently found that getting the value of an element's role attribute with Element.role was failing only in Firefox, and using Element.getAttribute("role") was the fix. I'm not sure if or how I would have found that issue without tests that run directly in each of the browsers.

Next, we add a couple scripts to our package.json to run tests either in a single pass or in watch mode:

"scripts": {
  "test": "web-test-runner \"/**/*.test.js\" --node-resolve --playwright --browsers chromium firefox webkit",
  "test:watch": "web-test-runner \"/**/*.test.js\" --node-resolve --playwright --browsers chromium firefox webkit --watch"
},

Last, we can run our watch mode script as we work. This will run all tests, then detect any file changes and re-run only the impacted tests:

npm run test:watch

If our website is made with simple HTML pages, we can run the tests directly in the HTML files (with a <script> tag) to test specific markup. If our HTML is rendered with JavaScript, as is the case with web components and many other approaches, then we can test the rendering in JS files alongside any logic or functionality that we'd usually unit test. We'll compare the tradeoffs of these two options at the end of this article.

Writing tests

To demonstrate the value of this setup, let's write tests to prevent some of the most common (non-visual) WCAG 2 failures found in the annual WebAIM Million study:

Low contrast text
Missing alt text
Empty links
Missing form input labels
Empty buttons
Missing document language

Writing tests for low contrast text is possible but too involved for this post. So let's focus on tests for the remaining most common failures.

First, we'll create a test file called example.test.js with the required imports:

import { runTests } from "@web/test-runner-mocha";
import { expect } from "@esm-bundle/chai";
import { sendKeys } from "@web/test-runner-commands";

runTests(() => {
  // TODO: Write tests here
});

runTests allows us to directly test HTML files, which makes this setup quick and easy for static HTML. @web/test-runner-commands provides native interaction utilities, such as sendKeys, that we'll use in a later example.

Then we'll create an example HTML file called example.html with the usual boilerplate and link to the test file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Our test file</title>

    <script type="module" src="example.test.js"></script>
  </head>
  <body>
    <!-- TODO: Write markup here -->
  </body>
</html>

Missing alt text

In example.test.js, let's write a test to check for missing image alt text:

// ...
runTests(() => {
  describe("images", () => {
    const docAllImages = Array.from(document.querySelectorAll("img"));

    it("have an alt attribute", () => {
      docAllImages.forEach((image) => {
        expect(image.getAttribute("alt"), image.outerHTML).to.exist;
      });
    });
  });
});

This test gets all images in the DOM, loops over them, and checks to make sure each one has an alt attribute.

Error messages in JavaScript include the line and character numbers to help quickly locate and fix errors, but we don't have access to this with HTML elements. By passing image.outerHTML as the second argument of our expect() function, we can include the element in the error message to make finding and correcting the offending element easier. We'll use this for custom error messages any time we're checking all instances of an element.

If this is too verbose or noisy for more complex elements, we could instead only include the element's opening tag, or assign all elements unique data-test-id values to identify them directly in test error messages.

In our example.html file, let's add an image without an alt attribute to get a failing test:

<img src="/example.jpg" />

Web Test Runner reports the following in the command line:

❌ images > have an alt attribute
	AssertionError: <img src="/example.jpg">: expected null to exist
		at example.test.js:9:41

Chromium: 1 failed
Firefox: 1 failed
Webkit: 1 failed

Our test fails as expected. To get the test to pass, we simply need to add an alt attribute, either as an empty string "" for decorative content or with a useful description for meaningful content.

The neat thing about this test is it passes if no <img> elements exist, but fails if they exist and don't have an alt attribute. So, this test can be used from the beginning of any project without creating irrelevant noise.

Let's write tests for other common WCAG 2 failures.

Empty links

We'll add another test in example.test.js:

runTests(() => {
  // ...
  describe("links", () => {
    const docAllLinks = Array.from(document.querySelectorAll("a"));

    it("have a non-empty href attribute", () => {
      docAllLinks.forEach((link) => {
        const hrefValue = link.getAttribute("href");
        expect(hrefValue, link.outerHTML).to.exist;
        expect(hrefValue, link.outerHTML).to.not.equal("");
      });
    });

    it("are not empty", () => {
      docAllLinks.forEach((link) => {
        expect(link.textContent, link.outerHTML).to.not.equal("");
      });
    });
  });
});

Similar to the previous test, we get all links from the DOM, loop over them, and check that their text content is not empty. We're also checking that links have a non-empty href attribute, just as an example of other HTML validation we'd like to do.

Missing form input labels

Time for another test suite:

runTests(() => {
  // ...
  describe("form inputs", () => {
    const docAllFormInputs = Array.from(
      document.querySelectorAll("input, textarea, select")
    );

    it("have a dedicated label", () => {
      docAllFormInputs.forEach((formInput) => {
        const inputId = formInput.id;
        expect(inputId, formInput.outerHTML).to.exist;

        const inputLabel = document.querySelector(`label[for="${inputId}"]`);
        expect(inputLabel, formInput.outerHTML).to.exist;
        expect(inputLabel.textContent, formInput.outerHTML).to.not.equal("");
      });
    });
  });
});

In this test, we get all form input elements, loop over them, and assert multiple things:

Each form input element needs an id attribute
We expect to find a <label> element with a for attribute that has the corresponding input's id as the value
We expect the <label> element to not be empty

It's possible to provide an accessible name for form inputs with other techniques, such as aria-label or aria-labelledby, but I'm being opinionated here because I prefer actual <label> elements and text content. Testing for an accessible name through other means is just as easy.

Empty buttons

This is nearly identical to our empty links test:

runTests(() => {
  // ...
  describe("buttons", () => {
    const docAllButtons = Array.from(document.querySelectorAll("button"));

    it("are not empty", () => {
      docAllButtons.forEach((button) => {
        expect(button.textContent, button.outerHTML).to.not.equal("");
      });
    });
  });
});

Missing document language

Let's write a test for the final common WCAG 2 failure:

runTests(() => {
  // ...
  describe("document", () => {
    it("has a set language", () => {
      const languageValue = document.querySelector("html").getAttribute("lang");

      expect(languageValue).to.equal("en");
    });
  });
});

This one is the most straightforward, but valuable nonetheless. If your site has internationalization, you'd want to check the lang value matches the current locale and updates based on user preference.

Testing heading levels

We're starting to build a universal test suite that will preserve accessibility across our projects.

Let's add some further assertions around heading levels, which are a common source of errors in accessibility audits:

runTests(() => {
  // ...
  describe("headings", () => {
    const docAllHeadings = Array.from(
      document.querySelectorAll("h1, h2, h3, h4, h5, h6")
    );

    it("have <h1> element as the first heading", () => {
      expect(
        getHeadingLevel(docAllHeadings[0]),
        docAllHeadings[0].outerHTML
      ).to.equal(1);
    });

    it("have a single <h1>", () => {
      docAllHeadings.forEach((heading, index) => {
        // Don't fail the test if the first heading on the page is `<h1>`
        if (index === 0 && getHeadingLevel(heading) === 1) {
          return;
        }

        expect(getHeadingLevel(heading), heading.outerHTML).to.not.equal(1);
      });
    });

    it("don't skip heading levels", () => {
      docAllHeadings.forEach((heading, index) => {
        let previousHeadingLevel = 0;
        const currentHeadingLevel = getHeadingLevel(heading);

        if (index !== 0) {
          previousHeadingLevel = getHeadingLevel(docAllHeadings[index - 1]);
        }

        expect(currentHeadingLevel, heading.outerHTML).to.be.lessThanOrEqual(
          previousHeadingLevel + 1
        );
      });
    });
  });
});

function getHeadingLevel(heading) {
  return +heading.tagName.toLowerCase().replace("h", "");
}

With these tests, we can ensure heading levels are used properly in our page. We should only have a single <h1> heading. This heading should also be the first heading on the page. Lastly, headings should never skip levels, such as <h2> followed by <h4>. We make use of small utility function, getHeadingLevel(), to keep our code more concise and mistake-proof.

Although these tests enforce correct heading logic, they can't evaluate if heading levels are appropriate for the content they describe. That always requires thoughtful consideration. Tests free the developer to spend more time on wider UX considerations like this.

Testing user interaction

So far, we've made simple assertions about our static HTML to make sure it's valid and not causing common accessibility failures. But as we create interactive patterns in our UI, the accessibility considerations become much more complex. We need to use HTML and ARIA to create custom semantics. We need to handle click, tap, and keyboard events. And we need to display and hide content, all while updating multiple attributes in concert.

Let's follow the Red, Green, Refactor workflow as we build a custom disclosure (show/hide) pattern.

We'll start with our tests in example.test.js to make sure our initial HTML and ARIA are correct:

runTests(() => {
  // ...
  describe("disclosure", () => {
    const docDisclosureToggle = document.querySelector(
      `[data-component="disclosureToggle"]`
    );
    const docDisclosureContent = document.querySelector(
      `[data-component="disclosureContent"]`
    );

    it("has a toggle button", () => {
      expect(docDisclosureToggle).to.exist;
      expect(docDisclosureToggle.tagName).to.equal("BUTTON");
    });

    it("has a toggle button with the expected ARIA attributes", () => {
      expect(docDisclosureToggle.getAttribute("aria-expanded")).to.exist;
      expect(docDisclosureToggle.getAttribute("aria-expanded")).to.equal(
        "false"
      );
      expect(docDisclosureToggle.getAttribute("aria-controls")).to.exist;
      expect(docDisclosureToggle.getAttribute("aria-expanded")).to.not.equal(
        ""
      );
    });

    it("has a content panel with the corresponding controls ID", () => {
      expect(docDisclosureContent).to.exist;
      expect(docDisclosureContent.id).to.equal(
        docDisclosureToggle.getAttribute("aria-controls")
      );
    });

    it("has a hidden content panel by default", () => {
      expect(docDisclosureContent.getAttribute("hidden")).to.exist;
    });
  });
});

These tests will fail, meaning we're in the "Red" stage. Now, we can author our initial HTML in example.html to get our tests to pass:

<button
  type="button"
  aria-expanded="false"
  aria-controls="disclosureContent"
  data-component="disclosureToggle"
>
  Open disclosure
</button>

<div id="disclosureContent" data-component="disclosureContent" hidden>
  <p>Disclosure content</p>
</div>

Our tests now pass, so we're in the "Green" stage. I'd make a Git commit at this point. If there are any improvements we'd like to make, we can make them with confidence as long as our tests are passing, and commit again each time we're in a working state.

Let's write a failing test to begin interacting with our disclosure in example.test.js:

runTests(() => {
  // ...
  describe("disclosure", () => {
    // ...
    it("opens the disclosure on keyboard Enter press", async () => {
      docDisclosureToggle.focus();

      await sendKeys({
        down: "Enter",
      });

      expect(docDisclosureToggle.getAttribute("aria-expanded")).to.equal(
        "true"
      );
      expect(docDisclosureContent.getAttribute("hidden")).to.not.exist;

      // TODO: Reset the disclosure
    });
  });
});

With this test, we move focus to our toggle button, then use the sendKeys function from Web Test Runner commands to send a native keyboard Enter key press. We're checking that our toggle button gets updated attributes, and that our disclosure content is no longer hidden. We'd want similar tests for mouse click and the keyboard Space press, as well as testing that the disclosure closes on these interactions if it's already open.

We're in the "Red" stage again, but I'll leave the rest of the work to you to add the remaining tests and get them to pass. A cool thing is that the functionality needed for this component to work also creates some handy utility functions for our tests, such as resetting the disclosure at the end of each test to create a consistent starting point for other tests. And these utilities are easy to unit test with this approach as well.

Wrapping up

This workflow for test-driven HTML and accessibility provides so much value in my daily work, and I hope teams can adopt this technique to create a more responsible and usable web for everyone. I've used this setup extensively in large projects with complex UI patterns and it has scaled gracefully with several hundred tests running at all times.

With this setup, we can write unit tests that have access to the real DOM across major browsers, which allows us to check our HTML for validity, interactivity, and accessibility. We can run these tests in multiple browsers at once with every change, and preserve accessibility from the very start of our project. These expectations are permanently captured in our code, so we can freely refactor our work and add new features without introducing regressions.

The examples in this post assume a static HTML file that we directly linked our tests to. This is the fastest and most direct way to test our HTML, but we don't want our test file to load in production. As a result, we'd need to remove the <script> tag before deploying to the web. To make this approach more convenient, it'd be good to do this automatically with a build command that creates a /dist folder or something similar.

Most projects probably won't just have static HTML files, and instead render components with JavaScript. In this case, we create standalone .test.js files that import corresponding JavaScript modules and call render functions or methods directly. From there, the workflow and benefits are all the same, but there may be a little more effort in setting up specific UI situations to test vs. having HTML ready to go.

As a final consideration, this testing technique enhances, not replaces, other forms of accessibility testing and shifts a lot of the feedback earlier in the process. Using accessibility-focused code linters, automated accessibility testing tools, and manual accessibility review together provides the most value.

Many of the examples we covered in this post are checks we would otherwise have to make manually, either through code review or running accessibility audit tools. By writing unit tests for accessibility, we can discover and fix more issues as they arise. And we free more capacity to manually evaluate other aspects of accessibility, such as using assistive technology to evaluate the flow of a page or automated testing tools to check color contrast.

Automated tools cover about 30% of the WCAG success criteria and detect about 57% of overall issues, leaving the rest for manual evaluation. With this approach, unit tests can increase coverage, particularly with interactive UI patterns. Even with more automated test coverage, manual review remains the most effective accessibility testing technique for finding issues and building empathy.

My long-term goal with this work is to build a robust, universal accessibility test collection that can be used across projects. As we explored with our disclosure example, it's also possible to create test suites for custom UI patterns such as accordions, menus, tooltips, and others.

Let me know if you'd be interested in using this test collection or if you'd like to collaborate. Together, we can make test-driven accessibility and accessibility-first development a reality.

The hidden attribute in HTML

2023-12-11T00:00:00Z

by Ahmad El-Alfy

The hidden attribute allows us to hide HTML elements from the page. When it was introduced, it worked in a very simple way: it set the CSS display property to none.

Many people voiced concerns because here we are, mixing styles with markup again. To be fair, this was at a time before the rise of frameworks and the change in people's mindsets where separation of concern became a less debatable issue. There were also others who opposed the attribute because it can be easily overridden by CSS. A solution to avoid hidden elements from showing unintentionally is adding this snippet to your stylesheet to ensure it overrides other rules used on the same element.

[hidden] {
  display: none !important;
}

There are differing opinions on using the !important declaration, as some authors considered it code smell. Later, the use of !important in utility classes became more accepted.

A modern way to mitigate the use of !important is the use of CSS Cascade Layers. CSS layers is implemented by using the @layer directive, allowing us to define specific layers for our styles. This allow us to control the specificity and ordering of the CSS rules without resorting to !important. This approach promotes a more maintainable and scalable codebase, reducing the reliance on !important declarations and making it easier to manage styles across different components and elements. All we need to do is to add the previous snippet in the utility layer and moving that layer to be the last. This way we can ensure that their styles take precedence without the need for !important.

Let's take an example where we need to toggle the display of an element. We can do that by setting its display property to none using JavaScript and inline CSS. This is a common approach that many follow to hide an element instantly. To show the element again we can change the display back to whatever value we want.

// Hide the element
el.style.display = 'none';

// Show the element again by setting the display to another value
el.style.display = 'block';

The problem with setting the display to something other than none is that we could be dealing with an element that has different display values according to the media size for example (e.g. block, flex ... etc). In that case, setting it to a specific value can introduce some troubles if the display types don't match.

Another approach would be to use the removeProperty method, available on the elements style property, which removes specific inline styles.

// Show the element again by removing the inline declared property
el.style.removeProperty('display');

One argument in favor of the hidden attribute is its semantic value. It clearly indicates that an element using the attribute is intended to be hidden from display. Another argument is that we can hide content in HTML without needing CSS. So without having to set inline styles, we can add and remove the attribute on the element as we want.

// Hide the element
el.hidden = true;
// We can also use addAttribute
el.setAttribute('hidden', '');

// Show the element
el.hidden = false;
// We cal also use removeAttribute
el.removeAttribute('hidden');

The future of `hidden` attribute

Initially, the hidden attribute was considered a boolean attribute. If the attribute was present on an HTML element, it would be effective regardless of its value:

<div hidden>This element will be hidden</div>
<div hidden="hidden">This element is also hidden</div>
<div hidden="false">This one is hidden as well</div>

The specification has changed recently, and the hidden attribute is now an enumerated attribute. This means it can have specific named values. The new value introduced in the specification is until-found, which triggers a new state called the "Until Found" state.

If the hidden attribute is present without a value, or with any value other than until-found, it will behave as it did before. However, if the value is until-found, the element will be in the "Until Found" state. In this state, the element will be hidden until it is found by the user agent.

The hidden until found state

The hidden until found state was created to solve a common problem. Let's look at tabs and accordions for example. These UI components contain elements that are undiscoverable until a certain action is done (e.g clicking a button). This makes the content unavailable to screen readers, search engines, and the built-in find-in-page feature in browsers.

Unlike the standard "hidden" state, which completely hides the content by setting its display property to none, the "hidden until found" state uses the content-visibility property to hide content while still making it discoverable by search engines, find-in-page functionality, and linking. Consider the following example (currently only supported in Chrome and Edge).

See the project Hidden Attribute on LiveCodes.

In this example, try using the browser's search feature (find-in-page) and type the word "banana." After the first result is highlighted, attempting to navigate to the next result will reveal the "Introduction" section. Following that, the subsequent sections will become visible in sequence. Note that after an element is revealed, the attribute is removed keeping the element visible. Clicking the "Reset Display" button will hide the sections again, enabling you to retry the process. Additionally, clicking any of the links will automatically display the corresponding sections.

Note that this example doesn't rely on JavaScript, except for the functionality used to reset the display. Instead, the behavior is achieved purely with HTML. As the corresponding sections are "found," the hidden attribute is automatically removed from the elements, triggering their visibility.

Browser support

Presently, this functionality is accessible in Chrome and Edge. While Firefox has expressed an intention to incorporate it, there are no indications of similar developments from Safari yet. Currently, the feature is marked as "Experimental," indicating that its functionality may undergo changes in the future.

Wrapping up

The anticipated enhancements to the hidden attribute are poised to positively influence and enhance the user experience for those utilizing the find-in-page feature in browsers. The behavior showcased in this demo by Joey Arhar aligns with our expectations when searching for keywords that match content on a page, reinforcing the potential benefits of these improvements.

Resources

Special thanks

Many thanks to Saptak Sengupta and Eric Bailey for their invaluable reviews of this post; their insightful feedback greatly enhanced the final result. A special acknowledgment goes to Manuel Matuzovic for accepting my contribution to this year's Advent calendar and his patient support until I completed this blog. Thanks for offering a platform where we can share our thoughts and discussions about HTML.

Template for accessibility guidelines

2023-12-10T00:00:00Z

by Steve Frenzel

Foreword

This template is opinionated and intended as a starting point for those who want to define how accessibility is dealt with in their company. It does not matter whether your title is developer, designer, project manager or something else.

I created it based on my experience working with a very small start-up, a digital agency with more than 250 employees and a monolithic company with very fixed structures.

When creating this template, I had the six most common WCAG failures in mind, but also what processes take place when you collaborate with other people. Nothing is set in stone and it should be adapted in consultation with your colleagues, because accessibility is a group effort! More on that in Prependix.

As a reference, I refer to the Web Content Accessibility Guidelines (WCAG) 2.2, as they are popular and well documented. However, you are free to include a different one or more in this template, depending on your location and the requirements that need to be met.

With all that being said, let's have a look at the template! 👀

Prependix
Design
2.1 Color contrast
2.2 Font size
2.3 Touch target size
2.4 Conveying meaning
2.5 Focus behaviour
2.6 Media controls
2.7 User flow
2.8 Landmarks & annotations
2.9 Handover
Development
3.1 Semantic HTML
3.2 Skip link
3.3 Heading levels
3.4 Typography
3.5 Buttons & anchors
3.6 Alternative text
3.7 Operability
3.8 Preference detection
Testing
4.1 Browsers
4.2 Browser extensions
4.3 Screen reader
4.4 Pipeline integration
4.5 Other apps & tools
Appendix

1. Prependix

To ensure that our products are usable and accessible, we comply with level AA success criteria of the Web Content Accessibility Guidelines (WCAG) 2.2. For a better understanding of these guidelines, check out the following resources:

WCAG, but in language I can understand by tempertemper
WCAG 2.2 Map by Intopia
Accessibility Not-Checklist by Intopia

Accessibility is a group effort and not a one-person show. It goes beyond leaving it to designers or developers. Being aware and curious about it will not only help you, but also the people around you.

It is not possible to create a product that is 100% accessible. However, this is no reason to give up or to not start at all. “Progress over perfection” is our approach, because every little improvement counts and will make someone’s life easier.

You're never done with accessibility. Wether you're just starting your journey, or maintaining a current project: People (and their needs) are constantly changing, as well as technology, so you'll need to pay attention and adapt accordingly. If you want to get a better understanding of this particular topic, check out Microsoft Inclusive Design.

2. Design

Whenever possible, we want to not only meet the minimum for level AA success criteria, but also go beyond that. It is therefore possible that there is no direct WCAG recommendation for some of our requirements.

2.1 Color contrast

Color contrast must be level AA, if possible level AAA compliant. If text is in front of an image, provide a layer in between.

Related WCAG recommendation: Success Criterion 1.4.3 Contrast (Minimum)

2.2 Font size

Font size is at least 14 pixels, preferably 16 pixels.

No related WCAG recommendation, this is based on real life experience.

2.3 Touch target size

Touch target size should be at least 44 x 44 pixels, preferably more.

Related WCAG recommendation: Success Criterion 2.5.5 Target Size (Enhanced)

2.4 Conveying meaning

Convey meaning not only through colors or icons. If possible, add a descriptive label to the element in question.

Related WCAG recommendation: Success Criterion 1.4.1 Use of Color

2.5 Focus behaviour

All interactive elements have a clearly visible focus state. It might be a change of background and font color, or a focus ring. If the latter, it should have a width and offset of at least 2 pixels.

Related WCAG recommendations:

2.6 Media controls

When creating components such as carousels (sometimes called sliders) or any sort of media player, make sure it has controls to:

Navigate to the next or previous item
Stop and start the media
Show or hide captions (if applicable)

Related WCAG recommendation:

2.7 User flow

When visualising how users interact with a certain feature or component, keep in mind they will not only use a mouse. They might also use a keyboard, screen readers or other assistive technologies. So ask yourself: Can this (thing I'm working on) be used by anyone at any time? Is there something that might exclude certain people?

Related WCAG recommendation: Operable

2.8 Landmarks & annotations

Provide a version of your design with landmarks and accessibility annotations. This will help communicating with developers and improve accessibility across all browsers. You can find plenty of resources regarding this topic (and much more) in Stephanie Walter's Designer’s Guide to Documenting Accessibility & User Interactions.

2.9 Handover

A design is only ready for development, if it has been approved by at least one other member of your team (Note by the author: This could be a developer, another designer, quality assurance, accessibility expert, or whoever else might be responsible). Before moving on, all open issues must be resolved.

(Note by the author: All things mentioned are supposed to help you avoid the most common accessibility mistakes but this list isn't extensive and there's much more to consider. Again, this template is supposed be a starting point. Feel free to extend it however you want!)

3. Development

Putting the following rules into practice will ensure a robust, easy-to-use UI which will not only improve accessibility, but in certain cases might also be benfecial for SEO.

3.1 Semantic HTML

Use semantic HTML wherever possible to leverage native browser behavior. If progressive enhancement is needed, apply it with CSS and / or JavaScript.

Related MDN documentation: Progressive enhancement

Add a skip link so keyboard users can jump straight to the main content. This also requires a <main> element present in the DOM. Related links:

3.3 Heading levels

Heading levels should be used appropriately and not be skipped. Also do not use heading elements simply for the sake of styling! If a heading needs to look a certain way, apply a CSS class instead.

Related MDN documentation: The HTML Section Heading elements
Related WCAG recommendation: Success Criterion 2.4.10 Section Headings

3.4 Typography

For typography, use a relative unit like rem instead of px. This will give users the ability to adjust the font size to their needs. Also install fonts locally instead of fetching them from an external source to improve performance.

3.5 Buttons & anchors

Make sure you use the right element when deciding between a button and a link (actually called anchor). A button does something, an anchor element changes the URL in the browser. There are exceptions though, for example an anchor with the email or tel attribute. Both elements should have an accessible name for optimal screen reader support and search engine optimisation.

Related MDN documentation:

Related article:

Button versus links

3.6 Alternative text

Images must have descriptive alternative text. If they are purely decorative, use alt="". Otherwise provide a sufficient image description. If you must provide an icon-only interaction, make sure it has an accessible name by using aria-label.

Related WCAG recommendation: Success Criterion 1.1.1 Non-text Content

3.7 Operability

Interactive elements can be operated by mouse, keyboard, screen reader and other assistive technology. If such an element must consist only of an icon or color (which it should not), provide an accessible name with aria-label.

3.8 Preference detection

Some people have a preference for how content should be displayed on their devices. For example, they may have a dark theme activated on their operating system, or a high contrast mode. It is also possible that they prefer motion or transparency to be reduced. To respect all these scenarios, the following media queries can be applied:

4. Testing

Whether you work in design, development or quality assurance: Testing is an essential part of the job and happens during the process and before you ship anything.

4.1 Browsers

Use different browsers to test what you are working on. Google Chrome (Chromium engine) and Mozilla Firefox (Gecko engine) can be used on any operating system, except Apple iOS. When using MacOS, use Apple Safari (WebKit engine) as well.

4.2 Browser extensions

Browser extensions are a free and quick way to run accessibility scans. Most of them are based on the axe-core library and a mix of the following will cover enough ground. However, there are many more extensions out there worth exploring and testing.

axe DevTools
Stark (To generate reports)
WAVE

A screen reader will help you to understand the structure of a page or element. It will also show you a different way of user interaction. On Windows you can use JAWS (paid) or NVDA (free). VoiceOver is available on all Apple devices for free. For Android you can use Talkback. Related link: Guides to browsing and navigating content with a screen reader by Sara Soueidan

4.4 Pipeline integration

Integrating accessibility checks into the deployment pipeline is another great way to ensure requirements are met. For example a push or merge will not be possible if there are linting errors or a failed unit test. Related links:

4.5 Other apps & tools

To check WCAG conformance of color contrast, use the app Colour Contrast Analyser by TPGi. You can also check the color contrast in the browser using WebAim Contrast Checker.

When using Figma, there are a couple of great plugins to check for accessibility. Stark has a great UI and the free version offers contrast check, adding landmarks and vision simulator. Another noteworthy plugin is A11y - Focus Order.

5. Appendix

This is a dynamic document and may be subject to change over time. If content or links are no longer up-to-date, please contact [name of colleague] via [communication tool of your choice] or reach out via e-mail at [fake@email.com].

What the slot?

2023-12-09T00:00:00Z

by Egor Kloos (aka dutchcelt)

Web Components. The discussion seems to pop up more than it used to.

Web Components offer nifty features for creating components using JavaScript, CSS, and HTML. They have been available in all major web browsers since 2017. That’s long enough to start using them in production.

Web Components consist of three things that are intended to work together.

The great thing is that you can use each of these on their own. For HTMHell and fun, let’s take a closer look at Slots and the <slot> element.

What are slots?

For slots to do their thing, we need a Shadow DOM. MDN on what the Shadow DOM is:

A set of JavaScript APIs for attaching an encapsulated "shadow" DOM tree to an element — which is rendered separately from the main document DOM — and controlling associated functionality. In this way, you can keep an element's features private, so they can be scripted and styled without the fear of collision with other parts of the document.

Slots only exist in the Shadow DOM and are a way to get content from the document (i.e. a web page).
We have, in effect, two types of DOM. A Light DOM (the document) and the Shadow DOM attached to a Custom Element or a basic set of HTML elements.

Yes, you can have a Shadow DOM associated with a <div>, a <section> element, or a <main>!
Slots are rather magical and can prove very useful in bridging these two DOMs.
The best way to explain what a slot is is to show you. This basic example uses slots and a <div> element.

See the Pen Attach a Shadow DOM to a DIV by Egor Kloos (@dutchcelt) on CodePen.

Here is another example

Let’s say you wanted to use a <slot> with a Custom Element and a <template>. For brevity’s sake, I only show the two HTML parts, not the entire Custom Element setup.

Custom element markup

This is the HTML you would write on your web page.

<card-component>
  <h2 slot="heading">A heading passed to the named slot 'heading'.</h2>
  <blockquote>This will be passed on to the unnamed slot. Lorem ipsum dolor...</blockquote>
</card-component>

Template for your Shadow DOM

The Template is ‘appended’ to the Shadow DOM inside the Custom Element, and the <slot> pulls the content in. The Custom Element now renders the template with the content from the page.

<template>
  <a id="linkheader">
    <slot name="heading"></slot>
  </a>
  <div id="content">
    <slot></slot>
  </div>
</template>

The key is that you can place your <slot> into a more elaborate markup provided by the template.

The crispy bits

Here is a short list of what makes slots great:

Content inside the Shadow DOM is not always as accessible as on a normal web page. Slots allow your content to exist in both. The content remains on the page, and the Shadow DOM can access and enhance it.
Slots can be placed in any order. Especially with named slots, as we can see in the Codepen above. In the document source, the ‘heading’ is the first element but displayed as the second element through the template.
It is easy for machines to index (i.e. search engines and crawlers like chatGPT) because the content is still on the web page. Note: Most search engines now index the Shadow DOM’s content.
Content changes on the page are passed on to the Shadow DOM. Slots are live; Ummm, I mean reactive!
You don’t need to style the slotted elements as the web page styling already styles them. Styles are passed along with the content.

This all sounds very tasty. But before we choke on an unclosed <article> let’s see what’s whiffy about slots.

The soggy bits

This part requires a bit more explanation of the behaviour of Shadow DOM. Namely, it’s Encapsulation.
CSS-Tricks has an introduction to Web Components and contains a useful part about Shadow Dom

… the shadow DOM works sort of like an <iframe> where the content is cut off from the rest of the document; however, when we create a shadow root, we still have total control over that part of our page, but scoped to a context.

For me, this is the killer feature of Web Components. Nothing goes in or out—script contexts, IDs, styles, etc. Everything is nicely contained and controlled.
But wait, isn’t one of the positives of slotted elements that they ~~smuggle~~ bring their given styles from the document with them to the Shadow DOM? Houston! We have a problem!

So maybe we don’t want those pesky styles from the document. But hey, at least we can just override them in the Shadow DOM. Right!?

Yes, we can! … Sometimes. — Note to reader: Feel free to insert random expletives —

Slotted elements have weak specificity by design. Let me demonstrate with yet another Codepen.

See the Pen Slotted elements are weak by Egor Kloos (@dutchcelt) on CodePen.

In this example, we can’t style the slotted element. This is because the document already applies a style to them. (See the CSS tab in Codepen)
We can force it to work when we add an !important to the ::slotted rule. Even if the document style also adds an !important the ::slotted style still holds up.

/* Light DOM style */
h2 {
  color: green !important;
}

/* Shadow DOM slotted styling */
::slotted(h2) {
  color: navy !important; /* The colour is navy */
}

Well, that’s great, I mean GROSS!
It's not as bad as you might think as this is a use-case where you do want to reverse the cascade using !important.

However, this means that styling slotted content from within the Shadow DOM always requires !important for each property. Remember that the initial style could matter so be very careful, especially if you don't have control over the content in the document.
For most situations, you should accept that slotted elements keep the styling they're given. Only override when you really need to.

But what if I want to have my cake and eat it?

We effectively only have 1 way to override the style of slotted content for the Shadow DOM in a clean and inclusive way. Select both the shadowed element and the slotted elements from within the document and style it from there.

.card-demo h2 {
  color: navy;
}

I confess adding these additional styles to the document is a bit weird. However, bundling these with the main styles is fine in most situations. This also allows document authors to explicitly apply an override when they need to.
Before you do this, you should ask yourself again if you need these additional overrides. You may find, with some consideration, that you can make do without the added complexity.

An alternative

I have a work-a-round specific to my use case with Design System component libraries using Web Components. In this scenario, I have no control nor insight into the web page the library components are loaded. So I sometimes add some extra CSS to strengthen the slotted elements.

Because the component is explicitly being loaded anyway, I can directly insert Constructable Stylesheets to the document—no need to require a separate instruction to the developer to load additional styling. The Web Component can do it for you.

This Codepen demonstrates how you can add overrides to the document using adoptedStyleSheets.

// Overriding the document styling
const sheet = new CSSStyleSheet();
sheet.replaceSync(`
  #demodiv {
    & h2 {
      color: navy;
    }
    & p {
      color: purple;
    }
    & [slot="subheading"] {
      color: steelBlue;
      font-size: 1.3333rem;
      font-weight: 300;
    }
  }
`);
document.adoptedStyleSheets.push(sheet);

This is rather extreme, and I wouldn't necessarily recommend it. However, it is an interesting approach using new techniques like Constructable Stylesheets.

Slots, I love them, and I hate them. I also wouldn't want to go without them.

Regardless if you’ll use Shadow DOM in the future, I hope slots are now a little less of a mystery.

Update (December 10th, 2023):
Initially the described behaviour of !important was incorrect and has been corrected.

The hidden depths of the input element

2023-12-08T00:00:00Z

by Phil Nash

The <input> element is the most fascinating element in HTML.

Most elements behave the same way regardless of their attributes, the type attribute of the <input> element can take 1 of 22 different values that gives it not only different behaviour, but a different visual appearance too (many of which are hell to style, of course).

The <input> element is responsible for everything from text input, through checkboxes and radio buttons, to a button that resets all other elements in the form. I want to look beyond the various types that the <input> can embody, to the attributes you may not know about. Attributes that tweak the behaviour of the <input> to make it more usable, more accessible, and more applicable to various situations. Let's dig in.

Keyboard control

On a mobile device, focusing a text input will bring up the default virtual keyboard. But what if the input you are expecting is numerical or some other format? In this case the inputmode attribute can help to optimise the keyboard for the input you are expecting.

If the expected input is an email address, you can set the inputmode to “email” and the @ symbol will surface on the main keyboard. If, however, you're looking for a number, then you can set the inputmode to “numeric” or “decimal” and the number keypad will appear. This is useful in cases where your input is a number, but the input type of number isn't appropriate, for example with a one time password or a credit card number.

<input type="text" inputmode="numeric" />

The full list of inputmode values that you can use are listed below with their keyboard appearance on iOS. Android will display different variations.

none: stops virtual keyoards appearing for when you want to implement your own keyboard (you probably don't want this)
text: the default
numeric: just numbers
decimal: numbers and a decimal point
tel: numbers and other dial pad characters
url: the normal keyboard, with a period, forward slash and ".com" in place of the space bar
email: the normal keyboard, with a small space bar, an "@" symbol and a period
search: the normal keyboard, with a slightly smaller space bar, a period and a highlighted button that says "go" rather than the normal "return"

inputmode is also supported on <textarea>s and any element in contenteditable mode.

Get the right keyboard and your users will thank you as they input their data.

Inactive inputs

If you need to display an <input> element, but you don't want a user to be able to change the contents or you intend to change the contents in some other programmatic way, you might think that enabling the disabled attribute will help. However, disabled input elements are removed from the accessibility tree and thus disappear for users of assistive technologies. The contents of disabled inputs are also not submitted with the form.

An alternative to disabled is the readonly attribute. It makes the field inert, but the content remains accessible and will be submitted with the rest of the inputs within the form.

<label for="input">The label</label>
<input type="text" value="You can't change this" readonly id="input" />

Note by Manuel: Not all screen readers announce the field as “read only”. You may want to test it first and decide whether to support it with an additional description.

You can also target readonly elements in CSS with the pseudoclass :read-only. Elements that can be read and written can be targeted with the :read-write pseudoclass.

readonly only works on <input>s that behave like text controls and is also supported on <textarea> elements.

Choosing whether to use readonly over disabled on an element is about choosing whether an element is usable on the page. Don't forget to consider this.

Lights, camera, action

You might think the only way to have a user access the camera on their mobile device and take pictures or video is via JavaScript and the getUserMedia API. But camera access is also available declaratively. On a file upload <input> you can specify the capture attribute, which will direct the element to trigger the device camera.

Sadly this is a feature that is limited to the mobile versions of supporting browsers, on a desktop it will work like a regular file upload field.

For devices with front and back cameras, you can even provide hints for which camera to use. So if you are asking your user to take a selfie, you can set capture="user" to prefer the front-facing camera. If you are more interested in pictures of the surroundings, you can set capture="environment" to hint that you'd prefer the rear facing camera. The device can override these hints if, for example, it doesn't have a user facing camera available.

You can also use the accept attribute to hint at the type of content you want from the camera. If you accept image types, then the camera will be primed to take pictures, but if you hint that you want video then the camera will set up to record instead.

So, using the following HTML will produce the result below.

<label for="input">Cheeeeese</label>
<input type="file" capture="user" accept="image/jpeg,image/png" id="input" />

This is a great way to capture an avatar for a user with no need for JavaScript, just HTML.

Spellbound

The spellcheck attribute is a generic attribute that can be used on any element. It's used to trigger the browser's spellchecking capability on elements where you also set contenteditable="true". It also works on <input> elements and is definitely something you should consider.

Different browsers treat <input> elements differently. Firefox and Safari on the desktop will not spellcheck <input> elements without the attribute, but Chrome and Safari on iOS will. To get consistent behaviour across browsers, you should set the spellcheck attribute to "true" or "false" depending on the contents of the <input>.

For regular text, help your users out with spellcheck="true". For identifiers, like usernames, email addresses, URLs, or other things that you would not expect to find in a dictionary, set spellcheck="false".

One other thing to consider, how spellchecking is implemented is left to the browser. Chrome and Edge have been known to send the contents of <input> elements to a spellchecking service over the network, exposing whatever was in the field. If your <input> elements are capturing sensitive data, like personally identifiable information, like names or birth dates, or passwords, then you should set spellcheck="false" to avoid sharing it.

<label for="input">Name</label>
<input type="text" spellcheck="false" id="input" />

Note that a <input> with type of "password" won't leak its value, but if you implement a show password feature that sets the type to "text" then this opens the field to be spellchecked.

Getting your spellcheck settings consistent helps your users as they input data into your forms and being aware of the risks of spellcheck helps you protect your users' data.

Automatic Shift

The default behaviour for an <input> on a mobile device is to capitalise the first word and make all other characters lowercase. This is fine when writing a sentence, however things like names and addresses expect all words to be capitalised. Other inputs, like airline ticket identifiers and UK postcodes expect their input to be in all capitals.

The autocapitalize attribute is your friend in this case and saves your users having to use the shift key to produce text in the format you want it.

Capitalise the first letter of every word with autocapitalize="words" and capitalise every letter with autocapitalize="characters".

<label for="input">Name</label>
<input type="text" name="full-name" autocapitalize="words" id="input" />

One thing to note, the autocapitalize attribute does not have an effect where it doesn't make sense, like on <input> elements with type of "email", "url", and, most importantly, "password".

Getting autocapitalisation right will make entering data on mobile devices much easier for your users.

Less typing is always better

Last but not least, my absolute favourite <input> attribute is the autocomplete attribute.

It provides hints for the browser to fill in input fields with data it already knows. The autocomplete attribute can take an enormous number of values that associate an <input> with many things the browser knows or can find out.

For things like registration or logging in, you can set autocomplete to values like "username" or "email". For passwords, you can use the value "new-password" to prevent a browser from autocompleting an existing password and to suggest a secure new password. Or you can use the value "current-password" to indicate that the browser or password manager should autocomplete the field with the user's password.

You can autocomplete a user's address with values like "street-address", "country-name" and "postal-code". For ecommerce applications you can combine the values with additional identifiers to separate between "billing" and "shipping" addresses.

<label for="input">Address</label>
<input type="text" autocomplete="street-address shipping" name="street-address" id="input" />

For one time passwords sent over SMS, you can use the value "one-time-password" to indicate that the browser should look at recently received messages and extract the OTP for autocomplete.

And if you're implementing passkeys, you can use the autocomplete value "webauthn" to help implement passkey autofill.

Correctly using the autocomplete attribute is even a sufficient technique to fulfill the WCAG level AA rule "identify input purpose". Providing fine-grained hints to the browser for the type of content the input fields are expecting means that they can be filled in saving time and typing for all users.

Conversely, there are times you might want to disable autocomplete entirely. Using autocomplete="off" will stop the browser remembering what was entered in an input. This is useful for fields that expect different input each time, like a text CAPTCHA.

Getting the right autocomplete attributes helps all users fill in inputs with the least amount of effort.

Picking the right attributes

Designing and developing forms that work for all users is hard. The <input> element has many options that you can choose to use to make your forms more usable and accessible.

For controlling the available virtual keyboards use inputmode. To control whether an <input> can be updated, but also still read and submitted, choose readonly over disabled. You can trigger the camera on mobile devices using capture. Use the spellcheck attribtue to control whether spellchecking is activated on an input, and remember to set it to "false" on sensitive inputs. Save users time by using autocapitalize to control the capitalisation of text in an input. And finally, use autocomplete to help the browser fill in the contents of an input and save your users typing.

All of these attributes, when deployed correctly will help your users fill in your forms with the least amount of effort.

Security Headers using <meta>

2023-12-07T00:00:00Z

by Saptak S

Various HTTP headers are sent between the user and the server of a website in the request-response cycle. Some of these HTTP response headers sent by the server to the browser help enhance the security and privacy of the website's users. These sets of headers are often commonly known as security headers. These can range anywhere from forcing the browser to always visit your website through https (Strict-Transport-Security) to preventing Cross Site Scripting and Clickjacking attacks on the website's user. You can check how well the security headers are set for your website using securityheaders.com.

These security headers (or any HTTP response headers) are usually set through the server configuration, i.e., nginx config, Apache config, or similar. However, in certain scenarios, like hosting a static website using GitHub Pages, the developers don't have a lot of control over the HTTP response headers. In such scenarios, the ability to add security headers declaratively through HTML itself can be helpful. The <meta> HTML tag helps in setting up two such security headers - Referrer Policy and Content Security Policy.

Referrer Policy using `<meta name>`

One of the most common ways a <meta> HTML tag is used is with a name and content attribute. The HTML standard allows the <meta> element to have name="referrer" that gets delivered as a Referrer-Policy header. The content attribute defines the value of the Referrer-Policy header. For example,

<meta name="referrer" content="no-referrer">

will create the HTTP response header: Referrer-Policy: no-referrer. This will ensure that any visitor of your website, if they click on a link in your website, the Referer information of the visitor is not shared with the link. So the visited link will not know which previous URL the user has clicked the link from and helps protect the privacy of the user. There are a few different Referrer-Policy values that allow varied levels of information to be shared in the Referer header to the navigating link or subresources.

There are a few other ways that HTML allows setting up Referrer-Policy on individual links -

referrerpolicy attribute
rel="noreferrer".

The referrerpolicy attribute can be used like this:

<a href="http://example.com" referrerpolicy="origin">

This means when the user clicks on this particular anchor tag, only the origin information of the current website is sent to https://example.com. The referrerpolicy attribute can also be set on elements like <img> or <iframe> to control their Referrer-Policy.

Adding rel="noreferrer" to an anchor tag ensures that no referrer information of the current webpage is sent to the visiting webpage.

Content Security Policy using `http-equiv`

Another way of using <meta> tags is using the http-equiv attribute instead of the name attribute. The http-equiv attribute is used by servers to create various HTTP response headers. One such header is the Content-Security-Policy. Content Security Policy (CSP) is used to determine whether a content being loaded in the page is from a trusted source or not. CSP is versatile in controlling all different kinds of content from which script gets loaded to what a form target can be set to through its various directives, and hence protects your users from a wide range of attacks such as clickjacking attacks and cross-site scripting attacks.

The way to add a CSP using http-equiv is:

<meta http-equiv="Content-Security-Policy" content="script-src 'self'; form-action 'none'">

The above line creates an equivalent HTTP response header

Content-Security-Policy: "script-src 'self'; form-action 'none';"

The script-src directive in the above example ensures that URLs loaded in <script> element are from the same origin as the current webpage, and disallows any inline-scripts or script URLs from other websites. The form-action directive ensures that no form submission is allowed from the current webpage. These both help in preventing cross-site scripting attacks.

Caution: One very important thing to note is using this method, report-uri, frame-ancestors, and sandbox directives cannot be set for a CSP. They are removed from the policy before the policy is enforced if they are added using <meta> tag.

Invalid security headers in `<meta>`

One of the issues with adding security headers using <meta> tag is developers often assume that any of the HTTP security response headers can be added through this method. This is not true and can often lead to a false sense of security since any invalid security header will be ignored by the browser. It is important to remember that even though http-equiv helps in defining HTTP response headers, it is an enumerated attribute. Hence, it can only help in delivering a fixed set of HTTP header and any other HTTP header that is set using this method will be ignored.

In Web Almanac 2022, it was seen that 0.08% of the websites visited over the desktop had an invalid security header. So in conclusion, delivering Referrer-Policy and Content-Security-Policy security headers using the <meta> element can be really useful and protect your user's security and privacy, but it is also important to be aware of the limitations of this method.

Web Components FTW!

2023-12-06T00:00:00Z

by Chris Ferdinandi

Web Components are a collection of technologies that you can use to create reusable custom elements, with built-in interactivity, automatically scoped (or encapsulated) from the rest of your code.

They have a wide range of features and functionality (some good, some bad, some ugly), but today, we're going to look at how to create your first Web Component using the most cliche of examples: the counter button.

We'll learn how this...

<counter-button></counter-button>

Automagically becomes somethings like this under-the-hood...

<button onclick="increase()">Clicked 0 Times</button>
<script>
	let count = 0;

	function increase (event) {
		count++;
		event.target.textContent = `Clicked ${count} Times`;
	}
</script>

Let's dig in!

Creating a custom element

First, we'll create a custom element.

You can name it anything you want, but it must include at least one dash (-). Single-word web components are not allowed (those are reserved for native elements).

Let's uncreatively name ours counter-button.

<counter-button></counter-button>

Next, we need to register our custom element with JavaScript.

We do that with the customElements.define() method. We'll pass in the name of our custom element as the first argument, and a Class that extends the HTMLElement API as our second.

When our page loads, this will automatically find any custom elements with the name we provided and instantiate a new instance of our Class on them.

customElements.define('counter-button', class extends HTMLElement {
	// Stuff will happen here!
});

Inside the class, we'll add the constructor() method. This runs when a new instance of the Class is created.

In it, we'll user the super() operator to make sure we have access to the parent class (in this case, the HTMLElement object) properties.

customElements.define('counter-button', class extends HTMLElement {

	/**
	 * The class constructor object
	 */
	constructor () {

		// Always call super first in constructor
		super();

	}

});

Next, we'll add a property to track the number of clicks: this.count. You can think of this like Component state in your favorite JS library or framework.

(In a JavaScript Class, the this keyword refers to the current instance of the Class.)

customElements.define('counter-button', class extends HTMLElement {

	/**
	 * The class constructor object
	 */
	constructor () {

		// Always call super first in constructor
		super();

		// Track the count
		this.count = 0;

	}

});

Finally, we'll use the innerHTML property to render a button into the custom element (this), with our count state displayed as part of the text.

customElements.define('counter-button', class extends HTMLElement {

	/**
	 * The class constructor object
	 */
	constructor () {

		// Always call super first in constructor
		super();

		// Track the count
		this.count = 0;

		// Render HTML
		this.innerHTML =
			`<button>Clicked ${this.count} Times</button>`;

	}

});

Now, a <button> is automatically rendered into the UI wherever we include our custom element. It looks like this in the HTML.

<counter-button>
	<button>Clicked 0 Times</button>
</counter-button>

Adding interactivity

Web Components have "lifecycle functions" that run when various things happen.

The constructor() method is run when the element is created, before its injected into the UI.
The connectedCallback() method is run when the element is injected into the DOM, and again whenever it's moved or appended elsewhere.
The disconnectedCallback() method is run whenever the element is removed from the DOM.

When the <button> is clicked, we want to increase our count by 1 and update the UI.

We don't need to listen for clicks until the element is loaded into the DOM, so we'll use connectedCallback() method to add a click event listener.

Inside our Web Component Class, this is the custom element (<counter-button>).

We'll attach a click event listener to this. Inside the event handler function, we'll increase our count by 1, then render new text into the firstElementChild, the <button> element.

customElements.define('counter-button', class extends HTMLElement {

	/**
	 * The class constructor object
	 */
	constructor () {
		// ...
	}

	/**
	 * Runs each time the element is appended to the DOM
	 */
	connectedCallback () {
		this.addEventListener('click', function () {
			this.count++;
			this.firstElementChild.textContent = `Clicked ${this.count} Times`;
		});
	}

});

Now, whenever the button is clicked, the count and UI are automatically updated.

If you have multiple <counter-button> elements on a page, each one is self-contained and encapsulated. Updating the count on one doesn't affect the UI of the other.

Here's a demo.

Detecting attribute changes

The web component lifecycle includes an additional function, attributeChangedCallback(), that runs when attributes on a custom element are added, removed, or changed in value.

You can use it to detect attribute changes and run code in response.

For example, imagine if you wanted to let third-party JavaScript update the count on a <counter-button> by setting a count attribute, like this...

let counter = document.querySelector('counter-button');
counter.setAttribute('count', 42);

First, we need to create a static getter method named observedAttributes().

This function needs to return an array of attributes to watch. For performance reasons, only attributes listed in this array will be observed by the attributeChangedCallback() function.

We'll return an array with the count attribute.

/**
 * Create a list of attributes to observe
 */
static get observedAttributes () {
	return ['count'];
}

Next, we'll add an attributeChangedCallback() function.

It accepts three arguments: the name of the attribute that's been changed, its oldValue, and its newValue.

/**
 * Runs when the value of an attribute is changed on the component
 * @param  {String} name     The attribute name
 * @param  {String} oldValue The old attribute value
 * @param  {String} newValue The new attribute value
 */
attributeChangedCallback (name, oldValue, newValue) {
	console.log('changed', name, oldValue, newValue, this);
}

At this point, if we set or update the count attribute on our counter-button element, the attributeChangedCallback() will log some stuff into the console.

let counter = document.querySelector('counter-button');

// Nothing will happen here, because we're not watching this attribute
counter.setAttribute('hello', 'you');

// logs "changed" "count" null 42
counter.setAttribute('count', 42);

If we were observing more than one attribute, we would want to first check what the name was before doing anything in the attributeChangedCallback() function.

/**
 * Runs when the value of an attribute is changed on the component
 * @param  {String} name     The attribute name
 * @param  {String} oldValue The old attribute value
 * @param  {String} newValue The new attribute value
 */
attributeChangedCallback (name, oldValue, newValue) {

	// If the [count] attribute
	if (name === 'count') {
		// ...
	}

}

For this web component, though, the function only runs for the count attribute, so we don't have to check the name, nor do we have to worry about the oldValue.

First, we'll pass the newValue into the parseFloat() method to make sure its to a number. We'll also check if it's Not a Number (isNaN()).

Then, we'll update the count property, and render the new count into the firstElementChild (the <button>).

/**
 * Runs when the value of an attribute is changed on the component
 * @param  {String} name     The attribute name
 * @param  {String} oldValue The old attribute value
 * @param  {String} newValue The new attribute value
 */
attributeChangedCallback (name, oldValue, newValue) {

	// Make sure the new value is a number
	let num = parseFloat(newValue);
	if (isNaN(num)) return;

	// Update the count and render the UI
	this.count = num;
	this.firstElementChild.textContent = `Clicked ${this.count} Times`;

}

Now, whenever the count attribute is set or updated on our custom element, the count and UI are updated to match.

Here's another demo.

The Shadow DOM

The Shadow DOM is a special DOM, whose contents are separate and often isolated from the main DOM.

Web Components can use the Shadow DOM to encapsulate their child elements, and avoid the naming collisions and unintended side effects that sometimes happen when code is used by teams or across projects.

For example, with our current Web Component, someone could (hopefully accidentally!) wipe out all of the content inside the element.

let counter = document.querySelector('counter-button');
counter.innerHTML = '';

With the Shadow DOM, content inside the custom element cannot be accessed or modified with outside JavaScript or CSS.

<counter-button>
	#shadow-root (closed)
		<button>Clicked 0 Times</button>
</counter-button>

Inside our constructor, immediately after running the super() method, we can use the Element.attachShadow() method to create a shadow DOM for our web component.

It accepts an object of options. The only one we need to specify is the mode.

If we use open as the value, JavaScript from outside of our web component can access the DOM nodes. With a value of closed, only JavaScript inside the web component itself can access the Shadow DOM.

The Element.attachShadow() method returns to the ShadowRoot object. To easily access it in our methods, we'll assign it to the root property for our instance.

/**
 * The class constructor object
 */
constructor () {

	// Always call super first in constructor
	super();

	// Creates a shadow root
	this.root = this.attachShadow({mode: 'closed'});

	// ...

}

Now, instead of injecting content into the web component itself (this), we'll use the ShadowRoot (this.root).

/**
 * The class constructor object
 */
constructor () {

	// Always call super first in constructor
	super();

	// Creates a shadow root
	this.root = this.attachShadow({mode: 'closed'});

	// Track the count
	this.count = 0;

	// Render HTML
	this.root.innerHTML =
		`<button>Clicked ${this.count} Times</button>`;

}

Here's a demo of our Web Component with the Shadow DOM.

Opinion: do not use the Shadow DOM by default

While the Shadow DOM protects your code from unintentional side-effects and interactions, but also introduces some of its own challenges.

One of the biggest ones is around styling. Shadow DOM elements do not inherit global styles like elements in the main DOM do. There are a few techniques for styling elements in the Shadow DOM, but they're all a bit clunky and require more work from you as a developer.

There are also some accessibility challenges related to the Shadow DOM. Manuel has documented many of them here.

Unfortunately, some of Web Components best features (like template and slot) require the Shadow DOM.

But in my opinion, the tradeoffs and challenges with using the Shadow DOM outweigh the benefits it provides in most cases. It has its place, but the Light DOM (ie. the "regular" DOM) should be the default approach in most instances.

Why use web components?

You don't need web components to create a counter button... or any component, for that matter. So why use them?

First, they make it a lot more obvious what complex components are in your UI. An element called loading-icon is a lot more obvious than a set of empty nested div elements with a .loading-ring class on it.

<!-- This is clear -->
<loading-icon></loading-icon>

<!-- This is clunky -->
<div class="visually-hidden" role="status">
	Waiting to load...
</div>
<div class="loading-ring">
	<div></div>
	<div></div>
	<div></div>
	<div></div>
</div>

If you're working with a team of developers or creating a design system, web components provide a handful of additional benefits.

First, because the web component generates all of the behind-the-scenes HTML, you don't need to worry about developers forgetting something important.

<!-- This is the wrong class -->
<div class="loading-rings">
	<div></div>
	<div></div>
	<div></div>
	<div></div>
</div>

<!-- This one is missing a div -->
<div class="loading-ring">
	<div></div>
	<div></div>
	<div></div>
</div>

If you fix a bug or update your component, you don't have to manually update a bunch of HTML everywhere the component is used. You only need to update the JavaScript.

For example, imagine that the original version of your loading icon component did not include an ARIA live region to announce when the content was loaded to screen readers. You realize the mistake and update the component.

With a traditional HTML component, any developer who uses it will need to update their HTML, JavaScript, and CSS files to include the fix. With web components, they only have to update the JavaScript file.

<!-- 
	No changes needed
	The component handles the HTML for you
-->
<loading-icon></loading-icon>

<!-- This is the only change needed -->
<script src="loading-icon.v2.js"></script>

To summarize, the benefits of web components include...

Clarity and readability
A simpler and less error prone developer experience
Ease of updating components
Scoping and encapsulation

Learn more!

This article only scratched the surface on Web Components and what they're capable of.

You can learn more over at MDN. I also have a standalone course and a project-based workshop on Web Components as part of my Lean Web Club.

The Hellish History of HTML: An incomplete and personal account

2023-12-05T00:00:00Z

by Jason Cranford Teague

Timeline of HTML from 1990–2024

Note: HTML standards are developed first in browsers, so the version might have already became the de facto standard before the official standard document is released.

The story so far:

In the beginning Tim Berners-Lee created the World Wide Web. This has made a lot of people very angry and — putting all of humanity in constant contact with each other — been widely regarded as a bad move.

This would be called the Hypertext Transfer Protocol, but you probably see it every day as http://. Although initially intended as a way to share scientific papers, Berners-Lee quickly realized it would do a lot more than that:

I designed it for a social effect — to help people work together — and not as a technical toy.

His vision has led us to today, where the Web is now the predominant information platform for the planet Earth, and the language he created to create documents, HTML, is used by billions.

Unlike other systems at the time that were making use of the growth of home computers and modems — like AOL and Compuserve — Berners-Lee provided the World Wide Web as a free and open standard:

The web is for everyone. It should be accessible to people with disabilities and be available in whatever language they speak.

Tim Berners-Lee (left) did not invent the Internet. He did invent the Web and HTML. Vinton G Cerf (right) did not invent the Web. He and Robert Kahn did invent the Internet.

HTML: The Early Years (1990 – 1991)

In 1990, the Web was at best an “alpha” version of what it would become. Until then, computer networks were generally limited to a local area (LAN) and required a good deal of computer knowledge to use, much less create. There were other contenders at the time that allowed wider area networks (WAN) that could communicate with computers around a country or around the World. Most notable of these was the Internet. My favorite (and arguably the most popular) way of traveling the Internet in the early 1990s was Gopher. Gopher was (and technically still is) a way to retrieve documents from the Internet stored on a server. However, it quickly fell out of favor after HTTP arrived on the scene. This is, probably for the best. Can you imagine if we were all surfing the Gopher today?

What HTTP had going for it was HTML. Every single web page ever created uses the Hypertext Markup Language. Tim based HTML off of Standard Generalized Markup Language (SGML) which was already in common use at CERN, mostly by just adding the <a> tag for hypertext links.

In the early 1990s, HTML was pretty limited. In fact it didn’t include <img> tags, and its design capabilities were sub-par even when compared to even the clunky word processors of the day. So web pages of the time at best looked like poorly formatted text files.

What the Web did offer, though, was the seemingly magical ability to click a link on one web page and instantly (ok, quickly) load another web page created by anyone else located anywhere in the world.

In 1990, this was big stuff!

HTML“1” & HTML+: The Wild Frontier (1991 – 1995)

The first public mention of HTML was an informal CERN document in 1991, listing just 18 tags. There are now around 140. The Web in those early years was just an academic curiosity used by Universities… well, used by tech geeks at a few universities. The HTML tags were so informal that they were really defined more by whatever the person who wrote the Web browser code wanted them to be and they could (and did) just make up their own.

Although there were a few web browsers available, there was one that rose to popularity amongst the tech geeks of the time. Mosaic, released in 1993, was co-created by a (at the time) idealistic and starry eyed student by the name of Marc Andreessen atttending the University of Illinois at Urburna-Champaign. Marc decided it was such a good idea that, in 1994, he released Netscape Navigator as a consumer product. Free from academic constrains, Netscape could add features and functionality to appeal to non-academics as well as add whatever tags they felt appropriate. These tags were referred to as HTML+.

This freedom led to a lot of growth in what the Web could do with tags for greater styling (remember, CSS is still several years off) and structure. Added during this time were tags we take for granted like tables, forms, and inline images.

This freedom also led to a few really terrible tags, for example Netscape introduced <blink>, which, in case you can’t tell, caused the enclosed content to blink on and off. No, you couldn’t control the speed. No, you couldn’t make it stop. The text just blinked on and off… on and off… on and off… and would keep doing that until you left the page.

WHATEVER YOU DO, DON’T BLINK!

Unfortunately, this also meant that if you used tags recognized by one browser there was no guarantee they would be implemented or even included by another. This lead to problems when your web page didn’t display the way you intended. Fortunately, HTML is a very forgiving language, and if the browser didn’t recognize a tag it was supposed to just ignore it completely but should still display the content as if there was no tag. Still, imagine if you had set up a data table for your web page. If the user’s browser didn’t recognize the <table> tag, all that information becomes an unintelligible mess.

Another problem on the horizon was that there was no guarantee that the different browser makers would agree on what each tag specifically did or even what to call them. One browser might display a <p> with the first line indented, while another could require you to add an extra <p> or <br><br> to add a space between paragraphs. Interestingly, what we did at the time out of necessity — no indent and an extra space between paragraphs — has became the editorial norm we still use today.

There was obviously a need for some kind of standard for HTML if the Web was going to grow out of its infancy.

In 1994, Tim started The World Wide Web Consortium, at first to create standards for HTML that could be agreed upon and used by anyone creating browsers and websites.

Netscape would rule the early web until Microsoft, seeing the threat to their desktop market, ignited the bitter struggle known to legend as The Browser Wars.

These buttons were ubiquitous in the 1990s World Wide Web, often accompanied a message reading “Built for Netscape” or “Built for Internet Explorer”

My Own Private HTMHell: Slammin’ Ps

I was first introduced to the Web and HTML in the fall of 1994, when I started at Rensselaer Polytechnic Institute (RPI) for my Masters in Communication. I’d heard some rumbling about this new fangled Web thingy earlier in the year while working computer tech at another University, but I had my Gopher and that was good enough for me.

At RPI, I fell in with a rowdy crowd of Communication PhD and Master students, one of whom had co-authored the first book about the web, The World Wide Web Unleashed.

John December, for that was his name, had also started what was, arguably, the first online only magazine, called Computer Mediated Communications, a few months before I got there. There was no real design to it beyond the basic HTML, so he brought me in to be the first designer.

At the time, being able to display images was still pretty new, and background images could only be applied to the web pages entire background and had to tile vertically and horizontally without stopping. Good enough to add a bit of color or texture, but not much else.

To create web pages required you to code them using a command line prompt in a terminal. I still get hives at the very mention of using a command line, but I was determined to learn HTML. So, despite my trepidation, I tucked into command line editing.

To code and write the pages you had to go back and forth between code mode and text mode. In code mode you could add tags but not text. In text mode you could add text but any code would be treated as text. Switching between these modes could take up to 30 seconds to load each time.

If you forgot to add the <p> in code mode or thoughtlessly added them in text mode (which happened painfully often), you had to go back, delete all of the <p>s in text mode and reinsert them in code mode which could take a lot of time as the system lumbered between modes — you added the tag and then switched back to go to the next spot to add the next tag. I spent many hours doing that at first.

To speed production, we would set up our basic web page code structure and then simply add a bunch of <p> tags (there wasn’t a close paragraph tag at the time) and start writing an article, skipping over the next <p> to start a new paragraph.

We referred to this process as “Slammin’ P’s”.

HTML2: The Standards Rise (1995 – 1997)

Realizing that all of these different browsers needed to agree on exactly what tags were available in HTML and at least a rough guideline on how they should present the content, Tim started The World Wide Web Consortium.

The W3C would become the recognized body for setting Web technology standards, including (amongst many others) HTML, CSS, SVG, XML, and Web Accessibility. The one exception to this is JavaScript, which is controlled by ECMA International.

HTML2 attempted to make order out of the chaos that HTML had quickly become. Although not introducing any particularly exciting features, it codified the existing features to give everyone a level playing field to work on.

I just want to reiterate that at this point in the Web, CSS (which today does the lion’s share of actual visual design on the Web) and JavaScript (which does the lion’s share of interactivity on the web) were both new technologies that even if implemented had a lot of cross-browser inconsistencies. JavaScript caught on fast, but it would be the turn of the century before CSS would become the default way to add a visual layer to HTML code.

My Own Private HTMHell: Color Me unimpressed

In the 1990s most color monitors were limited to just 216 colors. Let me make this clear, since we live in a world of monitors that can display millions of colors: A single pixel on the overwhelming majority of computer monitors in the 1990s could only display one of 216 colors at a time. This limited the color palette for web designs to what became referred to as the Web Safe Colors, which, today, we call just Web Colors. Although other colors could be simulated by placing two different colors together and letting the viewers eye blend them (like a pointillism painting), the effect was never satisfying, and drop shadows and gradients were never smooth. Entire books were devoted to using Browser Safe Colors most effectively. I even kept a poster on my office

When I would try to sneak a drop shadow into a design (I had a high-end monitor that could display thousands of colors!), my creative director would (metaphorically) slap me on the wrist and tell me to cut it out.

In my day we only had 216 colors to design with and we liked it!

HTML3.2: Short and Sweet (1997)

Although it didn’t last long as a standard, HTML3, brought the standard fully under the control of the W3C. Despite working on it for almost two years, HTML 3.0 was never released as a standard. According to the W3C, the difference between HTML 2.0 and HTML 3.0 was, “so large that standardization and deployment of the whole proposal proved unwieldy” and was eventually dropped.

Instead of starting from scratch, the W3C worked to refine the 2.0 standard, releasing HTML 3.2 (code named wilbur for reasons no one is sure of) in January of 1997 HTML4 was released a little less than twelve months later in December.

By 1997, the Web was beginning to take off as a commercial platform. HTML 3.2 standardized features we take for granted today like tables, text flow around images, and inputs. Crucially, HTML 3.2 was backwards compatible with HTML 2, meaning that older Web pages could be displayed, something that still holds true to today.

Although some tags were depreciated — most notably <blink> and <marque> to the celebration of many — it secured HTML’s future as a stable standard that could be relied on. In fact, the one serious attempt to move away from the principle of backwards compatibility ended in time waisting disgrace. But we’ll talk more about XHTML2 in a bit.

Although short lived, the HTML 3.2 recommendation set the stage for keeping the standard free and open, so that no one company could monopolize or privatize it. Instead, the W3C the took public input and invited experts and company representatives to help guide its development and approve the final recommendations, another principal the W3C still follows.

Sometime around 1996–97, the Web began to quickly gain in popularity as more and more people saw its usefulness. There were publications moving online making news instant, online stores that could undersell their brick-and-mortar competitors (thanks Amazon), and much improved web search capabilities (thanks Google). Oh, and there were apparently some photographs of scantily clad men and women… ummm… exercising together.

This was a time known as the Dot-com Boom.

My Own Private HTMHell: On the Table

Before CSS introduced the float element, and long before the flex and grid standards, we used tables to create web page layouts. The <table> tag was not conceived for this purpose (it was for presenting tabular information and data) but web designers quickly realized they could repurpose it to create columns and rows for design grids. This allowed us a lot more flexibility and spurred a lot of design innovation.

But tables were far from perfect. Although you could turn off the table cell borders and collapse gaps between them, many people didn’t. So Web design from that time is often typified by clunky ridged gray borders and pixelated background images.

HTML4: Boom Goes the Web (1997 – 2014)

It was the best of times, it was the worst of times. The HTML4 standard was released and JavaScript and CSS, despite browser inconsistencies, were being adapted to create better designs for a more dynamic Web.

HTML4 improved tables and forms, introduced support for CSS and JavaScript, allowed better accessibility features and internationalization, you could embed external content with the <iframe> tag (the much maligned <frame> tag was deprecated), and plugins like Flash could be added using the <embed> tag.

A gold rush began, with start-up companies springing up like weeds. This period was know as the Dot-Com Boom. Everybody and their brother had an idea for how to make money out of the Web, and they all needed someone who knew HTML. Jobs quickly flourished for Information Architects, Visual Designers, and Programmers. The good times of free gourmet meals at work, video arcade break rooms, and corporate parties on cruise lines seemed like it would never end.

At the same time, two different Web browsers were vying for the hearts and minds of the Web viewing public. This was a time known to Web lore as “The Browser Wars” as Microsoft Internet Explorer and Netscape Navigator battled it out. Maybe we should really call this The First Browser War or The Great Browser War or Browser War I or maybe even WWWWAR I. As we shall see, another browser war was less than ten years away and another one may be going on now.

The Dot-com boom turned out to be a bubble and the bubble began to burst in late 2000. I will not dwell too long on this sad chapter in Web history, only to say that it had a profound effect on the burgeoning Web professionals of the day. Many were unceremoniously dumped from their first job — their dream job — crying over stock options that went from millions to pennies on the dollar all while watching the entire industry seemed to be imploding around them.

That said, the Dot-com bust cleared the way for a rethinking of how the web would work. Just a few years later, there was an explosion of new sites that were finally realizing the promise of the Web. Although Web 2.0 is often thought of as starting in the early 2000s, the power that drove it had been around since the mid-1990s when Cascading Style Sheets and Javascript (the duo technologies often referred to together at the time as DHTML or Dynamic HTML) became standards adopted by Web browsers.

What had held the development back was the technical debt of how the web was started and inconsistencies in how browsers displayed the Core Web Standards (HTML, CSS, JavaScript). What would look great in Netscape might fall apart in Internet Explorer, so we developed a lot of work arounds and kludges or just limited designs for cross-browser compatibility.

For better or worse, by 2001 Microsoft came out on top, and Web designers could begin to rely on a consistent, if lack luster in its standards adherence, Web browser to create for. Web2.0 could now actually take off.

After that, things simmered down for a bit in a period I refer to as “Pax Web”, and Flash, although not an open standard like HTML, was quickly adapted to bring more video and interactive content to the Web. Flash was easy enough for designers to use without having to learn a lot of code, and allowed for dynamic and highly interactive designs, something we struggle to recreate on the Web even today after Flash’s demise at the hands of the Apple iPhone.

My Own HTMHell: Internet Explorer 6

Ask any Web designer or developer working in the 2000s what it was that woke them up screaming in the middle of the night in panic and rage, the answer will likely be Internet Explorer 6. Launched in 2001 and preinstalled on every Windows computer as the default browser, it became the Internet to many people.

While talking to a class of fourth graders in the mid-2000s about the Web, I wanted to use their class computer to show some examples and asked the teacher if they had a Web browser. Her response was, “No, we just have the Internet,” and pointed to the Internet Explorer Icon.

Despite being the window to the web for billions (at its height, IE6 had something like around 80% of the world browser market), it had spotty, incomplete, inconsistent and buggy Web standards implementations. This made the job of creating Web sites difficult at the best of times, especially if you wanted to stick to standards and maintain cross-browser support.

I spent many, many, MANY hours during that time adjusting and re-adjusting my HTML, CSS, and JavaScript, using arcane kludges — like playing a sadistic whack-a-mole where whacking one guarantees another five popping up — and often just having to settle for the lowest common denominator to get what I wanted to display the way I wanted it to display the same way on every browser.

XHTML1: Strict Machine (2000 – 2008)

Although HTML4 solidified the Web, there were those who thought it too loose-goose to be considered a real solution for data mark up. HTML was very forgiving. It didn’t require that you follow proper syntax and anything the browser didn’t understand it would just throw out. That is browsers except IE6, of course, which would just choke (more HTMHell).

In 2000, the W3C released XHTML 1.0 as a reformulation of HTML using XML syntax. Extensible Markup Language (XML) had been around for a while as a markup language used to structure and organize data. The W3C decided to establish a competing standard to provide easier integration with XML code. XHTML aimed to combine the best of HTML and XML, providing stricter rules for markup and enabling interoperability with XML-based technologies.

XHTML was stricter than simple HTML, meaning that syntax couldn’t be fudged, but creating a page using XHTML was compatible with and little different than creating one in HTML4. However, it did force developers to be more semantic, consistent, and accessible with their code, something still important today.

XHTML2: Look Back in Anger (DOA)

The idea behind XHTML2 was bold, brave, and completely ineffective. Rather than simply evolve HTML and XHTML, XHTML2 sought to start over and create a stricter and more modular version the Web markup language. It was heavily based on XML and eliminated all presentation elements in favor of CSS. The idea was to force the complete separation of structure from presentation thus allowing for the code to be device independent.

There was just one problem: XHTML2 would not be backwards compatible.

HTML had, since its beginning, been backwards compatible, meaning that older Web pages could display even in browsers using newer HTML standards. XHTML2 would have quite literally broken the Web. In addition, the new language was far more complex, and stricter enforcement of syntax and structure made creating Web pages much more difficult without a programming background.

Development of XHTML2 was eventually abandoned in 2009 as interest in a more promising standard was catching on.

HTML5: A New Hope (2014 – Now)

Core Web Technologies: HTML 5, JavaScript, and CSS 3

Although not officially released as a standard until 2014, HTML5 had already become the de facto standard in Web browsers starting around 2010. Coupled with a developing CSS3 and a mature JavaScript, the Web was poised for a new phase. The rise of mobile devices being used to surf the Web meant that we had to start thinking more and more about how Web pages would look on small screens. Rather than creating a site for desktop/laptop and one for mobile, CSS could be used to change the layout of the HTML in response to the screen size. This became most commonly known as Responsive Web Design.

HTML5 made an accessible and semantic Web its priority. Semantic HTML code simply means that it is well structured and that every item on the page has a clearly defined purpose. So structural HTML tags such as <nav>, <section>, article, and <figure> were added. New input types were added as well, so that the data could be more easily differentiated (if only developers would use them properly!).

While XHTML2 was discontinued, the idea of combining HTML and XML syntax continued to be explored leading to XHTML5. Like XHTML1, XHTML5 allows developers to write web pages using the stricter rules of XML while still benefiting from the features and compatibility of HTML5.

Because Internet Explorer was languishing without updating to modern standards (IE 7 improvements came too little too late in 2006 and took years to replace IE6), Chrome was at the forefront of implementing HTML5 and CSS3. The upstart browser quickly caught on and rapidly grew in popularity.

The beginning of the end of WWWWar II came in 2012 when Chrome unseated Internet Explorer as the top browser world wide and IE never recovered after that. Although IE was still a major player for several years, by 2015, seeing that Internet Explorer was too tech debt laden to compete, Microsoft launched a completely new Web browser: Edge. Internet Explorer would finally be discontinued in 2022, but there are signs that Microsoft is gearing up for another fight.

In 2012, Google Chrome passed Microsoft Internet Explorer as the most popular web browser in the world. The WWW would never be the same.

Two other huge advances in Web design happened around 2009. First was that CSS Level 3 had become a de facto — if not finalized — standard. This revised and expanded styling standard was quickly adapted by browser makers eager to push their browsers as the most standard compliant. Almost as importantly, and long overdue, was the ability to use downloadable font files to use virtually any typeface in Web designs. This push, led the way by Safari was quickly introduced into Chrome and finally a few years later begrudgingly by Internet Explorer.

Additionally, since Apple refused to support Flash on its extremely popular iPhone, Flash quickly fell out of favor as a way of delivering video and interactive content. Fortunately, HTML5 included new (and old) standards for embedding video, and Scalable Vector Graphics (SVG), an old Web standard many had all but given up on, saw a resurgence in popularity to replace Flash’s vector capabilities.

The explosion of typography on the web, the new capabilities in CSS3, and the resuscitation of SVG led to a renaissance in Web design in the 2010s. Designers, having to move away from Flash so that they could support mobile devices, were now also expected to create designs that would work just as well on devices from a few hundred to a few thousand pixels wide. In effect, we were looking at an entirely new Web by the end of the 2000s.

When an evolutionary change like this happened in the early-2000s, we called it Web 2.0. I would argue that the period from roughly 2009 – 2016 should be referred to as Web 3.0. Despite the terms Web3 and Web 3.0 being in common usage today to describe a decentralization of the Web (the term was first used sometime in the mid to late 2010s, but is still little more than a marketing buzzword) we missed an entire phase where the Web evolved off the desktop and became mobile, leading to a need to radically rethink our approach to Web design as “Mobile First” strategies developed.

The Future of HTML?

So, where are we now? Are we already living in a Web3 world already? Maybe.

We hear a lot of discussion about the next web phase being “Web 3” but many others are less than thrilled by the prospect. There is little doubt that user’s control of their data has eroded to the point of non-existence in the last thirty years. At the heart of Web3 (beyond cryptocurrency and blockchain) is a desire to bring back a decentralized Web with greater individual user control. While this is unlikely to affect the HTML standard, it may radically alter the way we use it.

To complicate matters further, we appear to be heading into a new Browser War, with Microsoft recently launching several shots across the bow of Google—oh, excuse me, I mean “Alphabet”—leveraging Windows OS to push users towards a newly revitalized Edge Browser and away from Chrome.

Despite all of this, HTML5 is not going anywhere soon. Unlike previous versions, HTML5 is modular. That is, rather than rereleasing the entire standard as a single document, new capabilities are added to the existing standard. Older standards are rarely, if ever, changed.

That said, the W3Cs Open UI Group is addressing a long standing problem with HTML: user interface control appearance and behavior.

Most complex web projects today need far more than what HTML5 form and UI controls provide.

Currently, web developers will use a lot of CSS and Javascript to add capabilities that would be better handled by built in HTML components, but there are only limited ways to style these elements and none for how they function without resorting to scripting. Although still in its infancy, Open UIs goal is to web developers more control to style and extend web UI components without changing the underlying HTML code.

In a little more than 30 years, the Web has gone from being a Wild Frontier to becoming an essential utility humanity relies on to communicate, and HTML will always be the core of the Web.

Back to Basics: 5 HTML attributes for improved accessibility and user experience

2023-12-04T00:00:00Z

by Daniela Kubesch

In the fast-paced world of web development, it's easy to get caught up in the latest frameworks, libraries and cutting-edge technologies. But sometimes, the most impactful improvements come from revisiting the fundamentals.

In this blog post, I'll guide you through five HTML attributes that not only improve accessibility but also enhance the overall user experience. Whether you are an experienced developer or just starting, let's explore the potential of these elements to create a more inclusive web experience.

1. hreflang

The hreflang attribute specifies the language of a linked resource on an <a> or <link> element. It works like the lang attribute but is specifically used for links.

Why use `hreflang`?

You can improve the user experience and SEO by using hreflang for both internal and external site links.
Using hreflang on internal website links provides a way to tell search engines about different variations of a page for other languages or regions. This means that English speakers would receive the English version of the site, while Swedish speakers would receive the Swedish version. There is no need for manual switching on the user's end, resulting in a smoother experience.

How to use `hreflang`

Add the hreflang attribute with the needed ISO language code to your <a> element. For an English website, this would be en.

<a href="https://example.com" hreflang="en">English Website</a>

You can also be more specific with the language code and use regional variations. For example, we can add en-GB for British English.

<a href="https://example.at" hreflang="en-GB">English Website</a>

If your website is available in multiple languages, you can use hreflang to specify the language and region of a document associated with a specific URL. Adding the attribute will help search engines understand the language and regional targeting of different web page versions.

Add hreflang with the required language code to each link. One link should act as the default fallback version, identifiable by adding hreflang="x-default" instead of the language code. Lastly, set the value of the rel attribute to "alternate" for each link in the language switcher to indicate that the linked pages are alternatives to the present page.

<link href="https://example.com" rel="alternate" hreflang="x-default" />
<link href="https://example.com/de" rel="alternate" hreflang="de" />

You can also use hreflang in your language switcher.

<a href="https://example.com" hreflang="x-default">English</a>
<a href="https://example.com/de" hreflang="de">German</a>

Sometimes, language switchers use link text in the language they are switching to. You can indicate this by additionally using the lang attribute.

<a href="https://example.com" hreflang="x-default">English</a>
<a href="https://example.com/de" hreflang="de" lang="de">Deutsch</a>

Note: Adding the lang attribute is particularly important for assistive technology users. For instance, screen readers alter their voice and pronunciation based on the language attribute.

An additional way to enhance accessibility is to include aria-current="true" to the presently active link.

<a href="https://example.com" hreflang="x-default" aria-current="true">English</a>
<a href="https://example.com/de" hreflang="de" lang="de">Deutsch</a>

2. translate

The translate attribute is used to indicate whether an element should be translated or not.

Why use `translate`?

Most website text is translatable by default (with some exceptions such as text on images or within SVGs). Translation tools, such as Google Translate, may suggest translation of page contents if the site's defined language differs from the browser's default language. However, there may be instances where this behaviour is unwanted.
Specific terms like company names, e-mail addresses or code examples should generally not be translated to avoid confusion. Automated translations are not always completely accurate, particularly with niche or technical words.

How to use `translate`

You can use translate on any HTML element. Assign an empty string ("") or yes for translation and no to avoid translation.

<!-- Original German text -->
<p>
  <span>Wien<span> 
  ist (wieder) die lebenswerteste Stadt der Welt!
</p>
<p>
  <span translate="no">Wien<span> 
  ist (wieder) die lebenswerteste Stadt der Welt!
</p>

<!-- What it would look like translated into English -->
<p>
  <span>Vienna<span> 
  named world's most liveable city (again)!
</p>
<p>
  <span translate="no">Wien<span> 
  named world's most liveable city (again)!
</p>

3. reversed

The reversed attribute is used to reverse ordered lists (<ol>) in the opposite order.

Why use `reversed`?

Using the reversed attribute keeps the order of visual and semantic list items the same, but they are numbered from highest to lowest. This means adding this attribute to your ordered list (<ol>) will not reverse the list items but only the list numbers. For instance, this behaviour is helpful if you want to count down your top five desserts. However, the reversed attribute does not affect unordered lists (<ul>).

Note: The reversed attribute does not affect unordered lists (<ul>).

How to use `reversed`

Add the reversed attribute to your list element.

<ol reversed>
  <li>Cookies</li>
  <li>Crema Catalana</li>
  <li>Tiramisu</li>
  <li>Pastel de Nata</li>
  <li>Sacher cake</li>
</ol>

This will result in the following reversed list:

Cookies
Crema Catalana
Tiramisu
Pastel de Nata
Sacher cake

Note: Screen readers announce the list in DOM order along with the correct number: "5. Cookies, 4. Crema Catalana, etc.".

4. controls

The controls attribute instructs the browser to show the standard video or audio controls.

Why use `controls`?

Including playback controls on your video and audio content is essential for optimal user experience, accessibility and usability. These controls enable users to stop or adjust video/sound playback and assist those who may experience motion sickness or distraction while browsing your website.
The default controls include the playback essentials such as play, pause, seek (moving position) and volume, as well as fullscreen toggle, captions/subtitles and track for video content only.

Note: The browser controls provided as defaults should be used with caution. Sometimes keyboard-based navigation can cause problems, such as loss of focus, forcing the user to reposition themselves. Consider implementing custom controls or integrating an external media player equipped with accessibility features. However, it is still preferable to include controls than not to.

How to use `controls`

You can add the controls attribute to the <video> or <audio> element.

<video controls>
  <source src="movie.mp4" type="video/mp4">
  <source src="movie.ogg" type="video/ogg">

  <track kind="captions" src="sampleCaptions.vtt" srclang="en" />
  <track kind="subtitles" src="sampleSubtitles_en.vtt" srclang="en" />
  <track kind="subtitles" src="sampleSubtitles_de.vtt" srclang="de" />

  Your browser does not support the video tag.
</video>

Note: The default controls cannot be styled with CSS.

5. autocomplete

The autocomplete attribute enables the browser to complete form values automatically and can be applied to the <form>, <input>, <select>, and <textarea> elements.

Why use `autocomplete`?

With the autocomplete attribute present, a browser can suggest a previous user's input for a form field's value, meaning a user does not have to remember or manually enter personal information. This results in significant benefits for individuals with cognitive impairments, reduced mobility, attention deficits, low vision, or blindness. Some people may find reduced manual input in forms particularly beneficial by lowering the need for extensive typing.

The autocomplete attribute improves the usability and efficiency of an HTML form for users by informing browsers and assistive technologies about the intended use of a specific form field. Screen readers use these autocomplete values to understand the nature of input fields and help users enter information more efficiently. For example, if a user's browser has saved information for a particular field (such as their name or e-mail), the screen reader will prompt them to fill in that information automatically.

How to use `autocomplete`

You can assign different values to autocomplete.

If you choose off, the browser cannot automatically enter or select a value for this field.

<label for="email">E-Mail</label>
<input name="email" id="email" type="email" autocomplete="off" />

Note: Many password managers may still prompt the user to save information or use previously stored data.

If you choose on, the browser will complete the input automatically. However, since no further information concerning the expected data is given, the browser may use its own judgement.

<form action="/" autocomplete="on">
  <label for="firstname">First Name</label>
  <input type="text" name="firstname" id="firstname" />

  <label for="lastname">Last Name</label>
  <input type="text" name="lastname" id="lastname" />

  <label for="email">Email</label>
  <input type="email" name="email" id="email" />
</form>

The optimal solution is to specify distinct values for the required data by opting for the corresponding value from a list of available input purposes.

Your form could look like this:

<form action="/" autocomplete="on">
  <label for="firstName">First Name</label>
  <input autocomplete="given-name" name="firstName" id="firstName" type="text" />
  
  <label for="lastName">Last Name</label>
  <input autocomplete="family-name" name="lastName" id="lastName" type="text" />
  
  <label for="email">Email</label>
  <input autocomplete="email" name="email" id="email" type="email" />
</form>

Note: The absence or incorrect use of an autocomplete attribute in an input field can cause inconvenience to users, particularly those with cognitive disabilities. Browsers cannot suggest accurate values, making it difficult for individuals to provide the expected input. Please make sure you choose the correct value.

Conclusion

I hope the exploration of these attributes has sparked your interest. When you embark on your next project, remember the significance of prioritising usability, accessibility and simplicity.

The Form Attribute - Enhancing Form Layout Flexibility

2023-12-03T00:00:00Z

by Alexander Muzenhardt

Consider a scenario where you have a login form containing two input fields with corresponding labels, alongside a submit and a reset button. If you submit the form, the action of the form gets triggered, and you can work with the formData.

The layout looks nice as well (let’s imagine we have added some fancy CSS).

<form action="/login" method="get">
  <div>
    <label for="username">Username</label>
    <input type="text" name="username" id="username" required />
  </div>
  
  <div>
    <label for="password">Password</label>
    <input type="password" name="password" id="password" required />
  </div>
  
  <div>
    <button type="reset">Reset</button>
    <button type="submit">Submit</button>
  </div>
</form>

The Challenge

Now, let's delve into a new requirement presented by your client. They want a revamped layout with the buttons placed elsewhere. This redesign, however, leads to a problem.
The buttons are no longer within the form element which causes the buttons to lose their association to the form.

<main>
  <form action="/login" method="get">
    <div>
      <label for="username">Username</label>
      <input type="text" name="username" id="username" required />
    </div>
    
    <div>
      <label for="password">Password</label>
      <input type="password" name="password" id="password" required />
    </div>
  </form>
  
  <!-- Because of the new layout, we have to move the buttons 
  outside of the form -->
  <div>
      <button type="reset">Reset</button>
      <button type="submit">Submit</button>
  </div>
</main>

If you try to submit or reset the form, nothing will happen.

These buttons must be within the form element to be functionally associated with it.
Unfortunately, the client insists on the new layout and to move the buttons outside the form element is the only option you have.

The Solution

If you read the button element’s specification, there is an interesting attribute called form. This is very helpful in your situation and will solve your problem. You can add the form attribute to each button and assign a name to it. The name can be whatever you want. A good name would be form-login.
With that change, you just have to add an id attribute to the form element itself. The value of the attribute has to be the same as in the form attribute. That's it!

<main>
  <form action="/login" method="get" id="form-login">
    <div>
      <label for="username">Username</label>
      <input type="text" name="username" id="username" required />
    </div>
    
    <div>
      <label for="password">Password</label>
      <input type="password" name="password" id="password" required />
    </div>
  </form>
  
  <!-- Because of the new layout, we have to move the Buttons outside the form -->
  <div>
      <button type="reset" form="form-login">Reset</button>
      <button type="submit" form="form-login">Submit</button>
  </div>
</main>

With these adjustments, your form works like before but with the freedom of positioning your buttons as you want.

A Word on Practicality

The same approach can be applied to the input, textarea, select and other form elements as well. You can check the MDN or the HTML spec to see if an element accepts this attribute.
With that approach elements are no longer required to be children of the form element. You are able to place your elements as you wish in the DOM, and they are always associated with the form element.

Accessibility concerns

With this approach, you will get a lot of freedom with your layout. However, it is crucial to maintain an order in the DOM that still makes sense to users. Otherwise, it can be confusing and frustrating.

For example, if the position of the button in the DOM in the previous example is not close to the rest of the form elements, screen-reader or keyboard user may have difficulty locating the button and understanding its relation to rest of the form.

Browser compatibility

The form attribute is well-supported, with Internet Explorer being an exception.
For detailed browser compatibility information, refer to caniuse.

Conclusion

With the form attribute you are no longer restricted to position your inputs and buttons inside the form element boundaries. This approach enriches the potential for more flexibility and creative form designs.

You don't need JavaScript for that

2023-12-02T00:00:00Z

by Kilian Valkhof

Hello, my dear friend of RSS! This post contains interactive demos. You may want to read it on the website.

Please don't feel antagonised by the title of this article. I don't hate JavaScript, I love it. I write bucketloads of it every single day. But I also love CSS, and I even love ~~JSX~~ HTML. The reason I love all three of these technologies is something called:

The rule of least power

It's one of the core principles of web development and it means that you should Choose the least powerful language suitable for a given purpose.

On the web this means preferring HTML over CSS, and then CSS over JS. JS is the most versatile language out of the three because you're the one describing how the browser should act, but it can also break, it can fail to load and it takes extra resources to download, parse and run. It is also very easy to exclude keyboard users and people using assistive technologies with it.

In contrast to JS, which is imperative, HTML and CSS are declarative. You tell the browser what to do, not how to do it. That means the browser gets to choose how to do it, and it can do it in the most efficient way possible.

Because HTML and CSS features are handled by the browser they can be more performant, more native, more adaptable to user preferences and in general, more accessible. That doesn't mean it will always be (especially when it comes to accessibility) but when the browser does the heavy lifting for you, your end users will generally have a better experience.

But I need JS for that!

You might be thinking “All the things I use JS for, I need JS for”. That might be true, but it's good to know that both browser makers and specification writers have been porting a lot of functionality over to CSS and HTML that up to a few years ago needed JS. And that's what this article is about.

The tricky thing with the web is that once you learn how to build something there is never a reason to have to learn it again. That's the contract we have: the web is backwards compatible. (Very few exceptions apply, but the first web page still runs fine in all modern browsers.)

That also means that the solution you learned once becomes part of your toolbox, and you can keep re-implementing it and everytime it will still work. So the examples I'm going to give below are cool (that's why I'm listing them) but what I want you to take away from this article is that just because you know something needs JavaScript, doesn't mean it still does. You can make better websites if you test those assumptions every now and then.

Custom Switches

We'll start this article off with something we've all had to implement at some point, custom switches. Instead of using a regular checkbox, the design calls for a nice looking switch. Instead of reaching for a JS solution with divs, onclick handlers and internal state, we're going to make use of a regular checkbox and the :checked pseudo class. Here's ther HTML we're going to use:

<label>
  <input type="checkbox" />
  My awesome feature
</label>

There's a label element, and inside it a checkbox. The nice thing about this is that the browser is already doing things for us. Because the input is inside the label, the browser has associated them and now we can click anywhere on the label to toggle the checkbox, no onclick handler in sight. The browser gives us this for free. Feature-wise, we're done.

My awesome feature

Of course, designers may not like the way this looks and we want to create a great looking custom switch. So let's add a bunch of CSS:

input {
  appearance: none;
  position: relative;
  display: inline-block;
  background: lightgrey;
  height: 1.65rem;
  width: 2.75rem;
  vertical-align: middle;
  border-radius: 2rem;
  box-shadow: 0px 1px 3px #0003 inset;
  transition: 0.25s linear background;
}
input::before {
  content: "";
  display: block;
  width: 1.25rem;
  height: 1.25rem;
  background: #fff;
  border-radius: 1.2rem;
  position: absolute;
  top: 0.2rem;
  left: 0.2rem;
  box-shadow: 0px 1px 3px #0003;
  transition: 0.25s linear transform;
  transform: translateX(0rem);
}

All the specifics of the styling here don't matter as much, but I want you to take a look at that first rule: appearance: none.

Form elements, along with images, are something called "replaced content". That means they're not really part of your HTML, but supplied by the browser. When the browser renders your HTML and finds replaced content, it leaves a box for it, and then replaces that box with the actual content. This is why, for example, images and form elements can't have pseudo-elements: they get replaced when the browser replaces the entire element.

appearance is a way of telling the browser to stop doing that. It tells the browser: "Thanks, but I want to style my own form control". And that then allows is to use the ::before pseudo-element. The input itself is now the background of our switch, and the ::before pseudo-element is the little dot inside of it that does the toggling.

My awesome feature

Clicking this still checks and unchecks the checkbox, but because we replaced the element we need to do the work of making that visible ourselves. That's where the :checked pseudo-class comes in:

:checked {
  background: green;
}
:checked::before {
  transform: translateX(1rem);
}

When you click the checkbox, that :checked pseudo-class starts to match and that causes the styling to update.

My awesome feature

So we have a great looking custom switch using native HTML elements and a bit of CSS, but we're not done yet. While for mouse users it's really clear which form control they're interacting with (since they're pointing at it and clicking), for people using a keyboard that's not so easy.

I'm sure you're familiar with this bit of CSS. To get rid of that ugly, dotted, boxy outline.

input:focus {
  outline: none;
}

If you're reading this, know that's not a good idea. But how do we make it look, well, nicer? Here too browsers have updated to make things better for us. The outline now follows the border-radius of an element, and we can also offset it away, or inside of, the element:

input:focus-visible {
  outline: 2px solid dodgerblue;
  outline-offset: 2px;
}

Now, when a user interacts with an element using the keyboard (you can try pressing the spacebar after clicking it, or tabbing to it), :focus-visible will match (it won't when using a mouse) and they get a good looking, blue outline slightly around the element.

My awesome feature

Lastly, I want you to replace that outline: none with something else:

input:focus {
  outline-color: transparent;
}

This will have the same result: Instead of the outline not being visible because it's hidden, it's not visible because it's transparent. For users that have high contrast mode (also called forced colors) turned on however, that outline becomes visible again because in high contrast mode, that transparent color gets replaced with a color the user chose, helping them see what they're interacting with even if they use a mouse.

This article isn't long enough to also go into what forced-colors does but if you want to learn more check out my article forced colors explained.

Datalist, a native autosuggest

Instead of installing $your-framework-autosuggest, try out datalist in your next project. Datalist is the browsers built-in way of showing a list of options as a user types into an input.

<input list="frameworks" />

<datalist id="frameworks">
  <option>Bootstrap</option>
  <option>Tailwind CSS</option>
  <option>Foundation</option>
  <option>Bulma</option>
  <option>Skeleton</option>
</datalist>

To use it, you add a datalist element with an ID and a set of options to your HTML. Don't worry, the element won't be visible. Then you use the list attribute on an input to associate the two.

As a user now types into the input, the browser will show the datalist as a dropdown, automatically filtering the options as the user types. Because it's a regular input though, users still have the option to type in their own value. Lastly, they can see all of the options by selecting the input and using the arrow keys to navigate the list, or clicking the dropdown icon the browser adds.

A color picker that does more

There are a ton of good looking color pickers out there, with nice canvas UIs and sliders that are built with 100s of lines of JavaScript. But did you know that you can also use a native color picker?

<label> <input type="color" /> Color </label>

This single line of HTML also give you a color picker with a nice UI, already saving you a bunch of JS. But because we're letting the browser handle it, we actually get more functionality for free. In Chromium browsers, that native color picker also lets you pick a color, not just from your own site but from anywhere on the screen. Pretty neat!

Color

A quick note here is that even though browsers show a nice color picker, your users might not all be able to use it. So offering a different way of picking a color (like a regular text input) is still a good idea.

Accordions

Accordions are a great way of making a page with a lot of content more structured and uncluttered by keeping content out of the way until a user needs it. And browsers give them to you for free with the details and summary elements:

<details>
  <summary>My accordion</summary>
  <p>My accordion content</p>
</details>

My accordion

My accordion content

By default everything inside a details element is hidden except for the summary. Then when a user clicks the summary element the browser will show the rest of the content.

What you'll often see is that one of the accordion items is already open, and the rest are closed. You can do that with the open attribute:

<details open>
  <summary>My accordion</summary>
  <p>My accordion content</p>
</details>

My accordion

My accordion content

If you come from the React world, you might look at this code and think “Well that's great, now it has the open prop and isn't going to close anymore“ but luckily, that's not the case. That open attribute is only the starting state, and will update when a user interacts with the accordion.

When it comes to styling, the details element also has you covered. That little triangle (that your designer will want to replace the instant they see it) is a ::marker pseudo-element that you can style:

summary::marker {
  font-size: 1.5em;
  content: "📬";
}
[open] summary::marker {
  font-size: 1.5em;
  content: "📭";
}

My accordion

My accordion content

Keep in mind that changing the content can affect how assistive technologies announce your accordion. Read Manuels article on that here: details/summary inconsistencies. In addition, for Safari you'll have to use the ::-webkit-details-marker pseudo-element.

The marker pseudo-element can't be styled as extensively as other elements (many CSS properties do not work on it, like positioning it in a completely different place), but you can replace its content, for example with emoji, or set a background color or image and change it's font size.

With the open attribute you can easily give it different styling from the closed state.

Lastly, we want to do something about that summary element. It's clickable, but unlike a link it doesn't get a pointer cursor, and unlike a button it, well, doesn't look like a button. So I think we should add a hover and focus state to it and help our visitors realise that it's clickable:

summary:hover,
summary:focus {
  cursor: pointer;
  background: deeppink;
}

My accordion

My accordion content

I'm sidestepping the “only links should have pointer cursors” discussion here, the main point I'm making is that you need to do something.

Dialog modals

Sometimes you need to inform the user about something, or ask them something or get them to confirm something. In JavaScript, that's what alert(), prompt() and confirm() do. But they have a pretty big downside: they lock the main thread, meaning your page can't do anything else. They're also browser-native, so you can't style them to work with your design.

Building your own dialog is also asking for trouble: you need to keep the focus inside the dialog for accessibility, announce it's modal-ness, make sure users can't exit it accidentally, and you'll have to fight with whatever chat widget occupied the z-index of 2147483647 (if you know you know).

So that's why browsers now come with a native dialog element:

<dialog>
  <form method="dialog">
    <h3>This is a pretty dialog</h3>
    <button type="submit">Close</button>
  </form>
</dialog>

This element isn't shown by default and, for now, this is where I'm going to cheat a little and use JavaScript:

document.querySelector("button").addEventListener("click", () => {
  document.querySelector("dialog").showModal();
});

Now there's changes in the works that will let you open dialogs without JavaScript, but they're not fully specced yet, let alone implemented. So for now, we need to use JavaScript to open the dialog. But that's it, the rest is all native HTML and CSS.

The dialog element has a showModal() function that it exposes and with it, you open the dialog. This dialog is opened on something called the top-layer, which is a new concept in browsers. For a primer, check out the explainer on MDN: Top layer.

The top layer is a new layer that's separate from your HTML, and you can "promote" elements to it. That means that elements on the top layer will always be above everything else, regardless of the z-index of an element and stacking context nesting.

Now that it's open though, you might notice that the browser doesn't give you any UI. The dialog is pretty much a div (not a button!) and it's up to you to provide the UI for closing. That's what the form in the code above does. You might've noticed it has a method of "dialog". When this form gets submitted, the browser takes that as a signal to close the dialog again.

With that, you can also create confirmation dialogs by providing two buttons, each with each own values:

<dialog>
  <form method="dialog">
    <p>Tabs or spaces?</p>
    <button type="submit" value="wrong">Tabs</button>
    <button type="submit" value="correct">Spaces</button>
  </form>
</dialog>

The button that a user clicked can be found by listening to the close event on the dialog and reading it's 'returnValue' property:

dialog.addEventListener("close", function () {
  console.log(dialog.returnValue);
});

If you have any other form data in there you can also read that as formData.

Because the dialog is essentially a div as far as styling it concerned, you can style it however you want. The browser will automatically place it in the middle of the screen for you, but everything else is up to you.

Dialog also comes with a new pseudo-element called ::backdrop. That's the layer that sits between the dialog and the rest of the page, and you can style it to e.g. dim the rest of the page or otherwise direct a users attention to the dialog. For example, you can overlay a white layer and blur the page:

dialog::backdrop {
  background: #fff5;
  backdrop-filter: blur(4px);
}

Just like the dialog element itself, the backdrop is positioned by the browser, so you won't need to worry about scrolling, fixed elements and browser resizing. It's all handled for you by the browser.

In closing

I hope you found a few things in this article that made you realise you can use a little bit less javascript in your next project. Whenever you change a known battle-tested implementation to something new it's good to test it, especially when it comes to accessibility, to make sure that you're not excluding anyone.

There are dozens more examples I could've added into this article, here are just some you can look into:

Native smooth scrolling with scroll-behavior: smooth (but only when prefers-reduced-motion: no preference matches!),
Native carousels with scroll-snap,
"In-view" elements with position: sticky
…Not to name the whole concept of container queries.

And if we look into the future, we're getting even more cool things:

Scroll driven animations
Masonry layouts without masonry.js but with grid-template-rows: masonry
A fully stylable select with the new selectlist element (where you can style each part of a select without destroying all the native functionality it comes with)
The :has() selector that's going to eliminate a whole class of JS selection

This article is an adaption of a conference talk I gave that goes into more detail on these and other topics, and you can watch it here: Stop Using JavaScript for That: Moving Features from JS to CSS and HTML.

So let me re-iterate the main point of this article:

Just because you know something needs JavaScript, doesn't mean it still does. You can make better websites if you test those assumptions every now and then.

The UX of HTML

2023-12-01T00:00:00Z

by Vasilis van Gemert

Recently when I gave a coding assignment — an art directed web page about a font — a student asked: does it have to be semantic and shit? The whole class looked up, curious about the answer — please let it be no! I answered that no, it doesn’t have to be semantic and shit, but it does have to be well designed and the user experience should be well considered. Relieved, all of my students agreed. They do care about a good user experience.

The joke here is, of course, that a well considered user experience starts with well considered HTML.

Somehow my students are allergic to semantics and shit. And they’re not alone. If you look at 99% of all websites in the wild, everybody who worked on them seems to be allergic to semantics and shit. On most websites heading levels are just random numbers, loosely based on font-size. Form fields have no labels. Links and buttons are divs. It’s really pretty bad. So it’s not just my students, the whole industry doesn’t understand semantics and shit.

Recently I decided to stop using the word semantics. Instead I talk about the UX of HTML. And all of a sudden my students are not allergic to HTML anymore but really interested. Instead of explaining the meaning of a certain element, I show them what it does. So we look at what happens when you add a label to an input: The input and the label now form a pair. You can now click on the label to interact with a checkbox. The label will be read out loud when you focus on an input with a screenreader. When you hover over a label, the hover state of the connected input is shown. My students love stuff like that. They care about UX.

I show them that a span with an onclick-event might seem to be behaving like a link, but that there are many layers of UX missing when you look a bit closer: right-click on this span, and a generic context menu opens up. When on the other hand you right-click on a proper link like this one a specialised context menu opens, with all kinds of options that are specific to a link. And I show them that proper links show up when you ask your screen reader to list all the links on a page, yet spans with an onclick-event don’t. Moreover, a span doesn’t receive focus when you tab to it. And so on. My students see this and they get it. And they love the fact that by being lazy they get much more result.

So when I teach about HTML I always start with the elements that are obviously interactive. I show them the multitude of UX layers of a link, I show them the layers and layers of UX that are added to a well considered form. I show them what happens on a phone when you use an input with a default text type instead of the proper type of email. They get this, and they want to know more. So I show them more. I show them the required attribute which makes it possible to validate not only form fields, but also fieldsets and forms. They love this stuff.

Then I go on and show the details element with a summary. Whoah! No JavaScript!

These interactive things are the most important parts of HTML. These are the things that truly break or make a site. If you don’t use these elements properly, many people are actively excluded and the UX degrades in many ways. The interactive elements are what makes the web the web.

The old focus on semantics

Every time I come home from a web conference I hang the lanyard with the badge on a doorknob. There are at least 35 lanyards there. The oldest is more than fifteen years old, the newest just a few months. On most of these conferences there was someone telling us about the importance of using proper semantic HTML. And they all talked about the importance of heading levels. So for at least 15 years we’ve been telling the web design and web development community that heading levels are very important. Yet after all these years, and after all these conferences there are almost no websites that do it right.

Later, when HTML5 was introduced the talks about semantics were still mostly about creating a proper document outline, but this time with sectioning elements in combination with headings. Unfortunately this idea was never properly implemented by browsers. And it turned out that these sectioning elements are very hard to understand. For years I’ve tried to explain the difference between a section and an article, and almost nobody gets it. And of course they don’t, because it’s very, very complicated theory. And above all: There’s no clear UX feature to point at. The user experience doesn’t change dramatically if you use a section instead of an article. It’s mostly theoretical. So nowadays, next to divitis, we also have sectionitis.

Understanding how heading levels work is hard. And understanding how sectioning elements work is really hard. And explaining these things is even harder. What’s the use for theoretical purity if the end result is the same?

Yes, I know that some sectioning elements actually have some UX attached to it. But not that much UX if you compare it to the real interactive elements. Not getting your heading levels right is not at all as destructive as using divs instead of links.

Now, I’m not saying that we should stop teaching people about heading levels and sections. We shouldn’t. Heading levels and sections do things as well. But we should think about when we teach these more complicated and subtle parts of HTML. First we need to get people exited about HTML by showing all the free yet complex layers of UX you get when you use the interactive elements properly. And then, when they do understand the interactive elements, when they’re really excited and they ask for more, show them the more obscure UX patterns. You need a good idea of what UX is before you can understand things like the option to nagivate through the headings on the page with a screen reader. Without an idea of what UX means you cannot understand what landmarks do. First start with the obvious, then show the details.

I am very much looking forward to 15 more years of web conferences and publications. I look forward to seeing inspiring talks about the UX of HTML. Talks about the incredible radio button and its wonderful indeterminate state! Talks about validating forms in a friendly way with just HTML and some clever CSS. Talks about the different context menus that appear on different elements. In other words, talks about what HTML does, and much less about what it means in theory. Let’s talk about user experience, and let’s stop talking about semantics and shit.

Preventing form submission with zero Javascript

2022-12-24T00:00:00Z

Want to trigger an action? Use a button element. They’re great.

Want to also prevent form submission when someone clicks that button? Put down the JavaScript, friend. I have a better suggestion:

<button type="button">
	Button action goes here
</button>

And that’s it! No preventDefault() or no overwrought dependencies that will stop working without notice. Just good ol’ reliable HTML and a humble attribute.

Okay, cool, thanks!

PS from Manuel: Thank you so much to all authors for this wonderufl series of articles and thank you to all readers for reading, sharing, and commenting! Merry christmas and a happy new year! 🖤

Enforcing better HTML markup with Eleventy

2022-12-23T00:00:00Z

While what we mean is usually very clear to us, others may decode our messages differently from what we intended. This is especially true on the web, where there are many ways to consume content. The language, browser type, device model, using a screen reader, navigating with or without a mouse - all of these factors can influence how information is experienced on the web.

And the glue that can better aid all these factors might be developing with semantic HTML which helps in describing content more accurately. In this article, we will explore common issues related to incorrect HTML markup and how you can enforce good practices to fix them.

Introduction

Web experiences should be fast, accessible, and tailored to the capabilities of users and the devices they own. A premise we could all agree on, as we have all have suffered from poorly designed web experiences. And if you are a web developer, you might have once followed practices that led to such experiences.

Still, building for a wide range of users you know nothing about is far from being a straightforward process. Fortunately, most of the research have extensively been done and made available sets of proven practices that when followed can ensure that what we build does not exclude groups of people arbitrarily. So how can we develop interfaces that create such experiences? To first understand that, we have to understand the role of semantics.

Semantics in spoken languages

Something we usually agree on in society is how important it is to define things. Without mutual understanding, we wouldn't be able to communicate effectively.

If I ask you to define what a cup of coffee is, you might provide an answer resembling: “a drink made from coffee beans”, whereas the internet might go for “the juice of a plant that gives life and suppresses the urge for murder”, or you might have your own definition not too far from these two. This mutual understanding of different concepts helps to communicate with each other. Whenever you buy a cup of coffee, you will expect what you receive to reflect this definition. You can even go a step further and adjust your words based on who you are talking to and how that person might feel at the moment.

For instance, you could find yourself speaking louder to someone hard of hearing, avoid technical words with a young person, or even adding gestures to illustrate what would otherwise be too abstract. Such adjustments are done unconsciously and aim to increase the likelihood that every exchange is done efficiently. The last thing you want is to have to persistently repeat something over and over to a person who simply does not understand what you are saying instead of adjusting once.

Semantics on the web

So what about on the web? Are semantics still as important and is it possible to adjust our message to the circumstances of others?

Communicating did indeed go past the face-to-face interactions and has reached the internet, in the form of blogs, websites, or social media. Even if the medium differs, I would argue that the idea of helping others better understand your content remains the same. Whether you are a company seeking profit through selling a product, a creator promoting his content or someone who occasionally post blog articles, there is surely a benefit in having a more reachable content. In that aspect, the need for semantics on the web is very close to that of spoken languages.

Specifically, for people with disabilities, they point assistive technology at what stuff is, so there is a bit of responsibility, a big responsibility that we have as Web developers, to make sure we point machines and assistive tech into the right direction and show them exactly what stuff is and what we mean by stuff in our user interfaces.

(Hidde de Vries, Semantics and How to Get Them Right)

Taking accountability as a web developer

Harry Potter and the Sorcerer's Stone (2001).
An orphaned boy enrolls in a school of wizardry, where he learns the truth about himself, his family and the terrible evil that haunts the magical world.

Without context you might have understood from this small excerpt that “Harry Potter and the Sorcerer's Stone” corresponds to the title of a media published in “2001”. That’s the kind of extra meaning you can explicitly attach to content on the web through HTML elements and attributes.

<section>
	<h1>Harry Potter and the Sorcerer's Stone</h1>
	<time datetime="2001">2001</time>
	<p>An orphaned boy enrolls in a school of wizardry, where he learns the truth about himself, his family and the terrible evil that haunts the magical world.</p>
</section>

This would then be conveyed as if you were saying “Hey device, present ‘Harry Potter and the Sorcerer's Stone’ as the title, this number value as the year of a date, and the remaining text as a paragraph.” By understanding the inherent meaning of such content, devices are able to convey it more accurately to a wide number of people, regardless of how they decide to experience it.

As someone responsible for building interfaces, not only are you trying to make your content understandable, you also have to make sure that content is accurately conveyed to their devices.

Helping users create their own ideal experience

In reality how does this help? In the same way that someone hard of hearing would have difficulties understanding what you say, there are situations that can prevent users from effectively consuming content.

And because you can’t adjust in real time, the idea is to provide all the hints you can to help users help themselves. Maybe the person browsing has a limited monthly internet package, and would sometimes prefer a low fidelity version of your website with only text content? Or that person has low vision, and would benefit from reading bigger text sizes? Perhaps said person is currently browsing while engaging in a phone call and could benefit from only using the keyboard to navigate? Such circumstances are intrinsic to the person, but often are reflected to their devices through preferences or apps aimed at supporting them.

As a developer, the HTML markup you write leads to an interface that users can view on their devices. Not only are your users diverse, but so are the devices they use. You may write sentences that are semantically valid, but the information may not be correctly displayed by your interface if you do not develop semantically. By utilizing the appropriate HTML elements to wrap your content, you can provide cues to devices browsing your interface about the way your content should be described.

When you start from scratch, it can be a tedious process to write good semantic HTML. As the complexity of your project increases, you may end up writing the same HTML patterns over and over again.

The sooner you can identify these patterns and establish a system for reusing them, the easier the development process will be. Having highlighted the role of semantics, let's look at the most common problems related to HTML markup and how you can avoid them.

Common HTML markup issues

Here are common issues encountered on the web that stems from bad HTML markup.

Each form field is not associated with its own label.
The heading structure is not respected.
Missing alternative text on images.
The opening HTML tag does not specify the main language.
The HTML code is not valid.

Sources

Designing a system for writing better HTML in Eleventy

Solid, accessible HTML should be the base of any web stack. If everything fails (and it will), your users still get the core content.

(Trys Mudford, Unyfying with Jamstack)

We are trying to implement a low configuration system that outputs HTML without adding a huge library or framework around it. We can achieve this by using a static site generator for addressing the need for reusable patterns. With the right foundations, it can support the implementation of robust and accessible HTML markup. Here we will explore how Eleventy, a static site generator, can help us in this regard.

Eleventy provides multiples ways to create reusable components. We will implement patterns that follow good practices and, by using them consistently we can ensure that the overall project does not deviate from our goal.

Enforcing better HTML markup in Eleventy

When you design a system, or a language, then if the features can be broken into relatively loosely bound groups of relatively closely bound features, then that division is a good thing to be made a part of the design. This is just good engineering.

Tim Berners Lee, Principles of Design

Reusable components with Nunjucks macros

Templating in Eleventy is what allows us to control how pages are rendered. It makes it possible to generate variables, loop over an array or run a custom plugin to generate data. Eleventy can handle a dozen different language models such as Nunjucks which we are going to use.

Nunjucks macros

Nunjucks has this feature called macros that hit all the boxes for building reusable components. It is similar to a function in a programming language and accepts arguments. The method for defining components macro is inspired by Trys Mudford detailed article on the subject.

For instance, we could create a button macro that takes in a label and output the markup for a tag component.

{% macro button(label, type="button", status='success') %}
	<button type="{{type}}" class="tag-{{status}}">
		{{label}}
	</button>
{% endmacro %}

Now button is available to be called like a normal function:

{{ button(label='Disconnect', status='alert') }}

{# Output #}
<button type="button" class="tag-alert">Disconnect</button>

The only catch is that all macro parameters are optional by default and not providing one will not prevent our component from being rendered. Since we try to enforce specific parameters within our components to make them more accessible, we would rather be informed whenever a critical parameter is not provided. So how can we achieve this?

Building filter to enforce required parameters inside macros

We can take advantage of another Eleventy feature to do this, namely filters. In Eleventy, filters are JavaScript functions that accept content, modify it, and then return it to be displayed instead of the original.

This sounds a lot like macros, you might say, and that would be true. The only difference is that filters are best used to transform data rather than generate snippets of content.

We can start by creating a filter that throws a generic error when the value it receives is undefined.

eleventyConfig.addFilter("enforced", function(value) {
	if(value === undefined){
    throw new Error("A parameter is missing");
	}
	return(value);
});

By applying this filter to the parameters of the macros we can make them mandatory.

{% macro button(label,type="button", status='success') %}
	<button type="{{ type }}" class="tag-{{ status }}">
		{{ label | enforced }}
	</button>
{% endmacro %}

We can then use it inside our component definition to flag parameters we want as required.

<button type="{{ type }}">{{ label | enforced }}</button>

Using this button component without providing a label parameter would throw an error which is what we want.

{# Throws an error because the label is not provided #}

{{ button(status='alert') }}

And now, by combining Nunjucks macros and a filter, we can create reusable components and set up rules to make sure they meet our criteria. The Front End Checklist or the Web Quality Assurance Checklist are both great resources to find ideas of criteria for writing better HTML markup. In the following sections we will address common HTML markup issues by utilizing this method.

How to enforce labels inside form fields?

To enable users with disabilities to access form fields, it is essential to identify them. That way, screen reader users could scan the form fields by name or use keyboard shortcuts to quickly navigate from one field to another.

Criteria

A label must be associated with each input form element.
Asterisks should not be used to mark required fields. Research suggests that they're not necessary and they can make users anxious and less likely to complete the form. Instead, the word optional should be added to non-required fields.
For security reasons, the spellcheck attribute should be set to false for password fields.

These criteria would lead to the following result for a password field.

<label for="password">
	  Password
</label>
<input type="password" spellcheck="false" id="name" name="password" required>

The associated component could be built using the following Nunjucks macro:

<label for="{{ inputId | enforced }}">
    {{ label | enforced }}
    {% if not required %}
        <span aria-hidden="true">(Optional)</span>
    {% endif %}
</label>
<input 
		type="{{ inputType or 'text' }}" 
		id="{{ inputId | enforced }}" 
		name="{{ inputName | enforced }}" 
		{% if spellcheck%} spellcheck="{{ spellcheck}}" {% endif %}
		{% if required %} required {% endif %}
>

Sources

How to allow flexible headings inside components?

For screen reader users, headings describe the relationships between sections and subsections and — where used correctly — provide both an outline and a means of navigation.

Heydon Pickering

A common challenge you may face when building with a component-first approach is to settle for a single heading level. Yet, components should not be tied to a single situation, otherwise they will lose their primary benefit of being reusable. As such, it would not be appropriate to specify in advance a heading level which you cannot change according to the context.

Having a flexible way of setting the heading of a component can make it easier to respect correct heading structures while keeping the benefits of components. We can achieve that flexibility by passing the heading element as a parameter inside our macro and it just works.

Here we will build a post card component. The heading level should be provided depending on the context.

Criteria

Headings should be flexible

<article class="card">
    {%if imageUrl%}
        <img src="{{imageUrl}}" alt="{{imageAlt | enforced}}"/>
    {%endif%}

    <{{headingElement | enforced }}>
        <a href="{{ url | enforced }}">
            {{ title | enforced }}
        </a>
    </{{headingElement}}>

    {%if description %}
        <p>{{description}}</p>
    {%endif%}

    {%if time %}
        <time datetime="{{time}}">{{ time }}</time>
    {% endif %}
</article>

Inside a template we can use the card component while passing the correct heading element.

<section>
	<h2>Card components</h2>
	  {{ component(
			"card", {title: "About", url: "/about", headingElement: "h3", description: "Links and attributions"}
		)}}
</section>

{# Output #}
<section>
	<h2>Card components</h2>
	<article class="card">
      <h3><a href="/about">About</a></h3>
      <p>Links and attributions</p> 
	</article>
</section>
{# Output #}

Sources

How to enforce missing alternative text on images?

In the context of visuals, alternative text is a textual description for people who cannot process information visually. In an effort to maintain a comparable experience for everyone, we can add these descriptions to visual contents. If you are interested you can find a thorough guide on how to write an image description. If the image is purely decorative, a null (empty) alt text should be provided (alt="") so that they can be ignored by assistive technologies, such as screen readers.

<img src="horizontal-wiggly-line.png" alt="">

In the post card component created previously, an image is included to illustrate posts. By using the enforced filter we can enforce an alternative text on these images.

{%if imageUrl%}
  <img src="{{imageUrl}}" alt="{{imageAlt | enforced}}"/>
{%endif%}

Separation of concerns

In Nunjucks you define variables with the set keyword. For a more convenient use, we unpack each arguments from the params object.

As shown in the following code snippet we could retrieve the value and enforce it at the top of the macros.

{% set imageAlt = params.imageAlt | enforced %}
{% set url = params.url | enforced %}
{% set headingElement = params.headingElement | enforced %}
{% set title = params.title| enforced %}
{% set imageUrl = params.imageUrl %}

<article>  
    {%if imageUrl%}
        <img src="{{imageUrl}}" alt="{{imageAlt}}"/>
    {%endif%}
		<!-- -->
    <{{headingElement}}>
        <a href="{{ url }}">
            {{ title }}
        </a>
    </{{headingElement}}>
		{%if description %}
			<p>{{description}}</p>
		{%endif%}
</article>

This separation enables us to separate the logic from the template.

Addressing redundant content

In a card, the alternative text is supposed to describe the content of the image, and that content usually refers to the same content. As a result, the alternative text might be similar to the heading, which would create a duplicate. To prevent this, we may want to include more logic that detects a matching alternative text to the heading and throws out an error. First, we have to improve the filter so it throws an error when the force is set to true.

eleventyConfig.addNunjucksFilter("enforced", function(value, force) {
    if(value === undefined ){
        throw new Error("A parameter is missing") 
    }
    if( force === true ){
        throw new Error(`An error occured: ${value}`);
    }
    return(value);
    });

The inside the macro component we can throw an error if the heading title is similar to the image description.

{# Advanced #}
{% set check_redundancy = "The title is redundant with alt text" | enforced(true) if title === imageAlt %}

How to enforce the language of the page?

Specifying the language will enable text to speech tools to pronounce the content with the appropriate accent for the language used. It can also help translation tools. At the root of the project we can create a _data folder that will hold Eleventy global data files. Global data files allow you to store data in a single file and reference it in all of your templates.

By creating a global data file we can apply the correct language attribute across the entire project. Here we are adding this attribute inside a site.js global data file.

module.exports = {
	title: "HTML Practices",
  description: "Enforcing HTML best practices in Eleventy",
  language: "en",
}

We can the reference the language attribute in the HTML opening tag of templates.

<!DOCTYPE html>
<html lang="{{site.language }}">
    <head><!-- Head content --></head>
    <body><!-- Body content --></body>
</html>

Validating the HTML code

There is a limit to what you can achieve by manually testing your websites. And even by “enforcing” good practices into your workflow, you are bound to miss something once in a while. To limit such occurrences you can use an automated tool for validating HTML markup. Inside Eleventy we can use Evaluatory , an open-source tool for website validation. It tests a website for accessibility and markup issues. We can use Evaluatory to automate checks on save inside our project.

Wrapping Up

Writing good HTML markup is one step towards providing a better web experience. And as long as this foundation is sturdy, you can effectively provide a better experience overall. You can explore this Github repository to find all the implementations mentioned in this article.

What is the Difference Between Alternative Text, Long Description, and Caption?

2022-12-22T00:00:00Z

When it comes to adding images on the web, you need to consider how to make them accessible and understandable to everyone.

Which means you need to include text alternatives to describe the image information or function.

Three options are:

Alternative Text
Long description
Caption

But how do you know which one to use? And when? Here's info to help you make that decision.

Alternative Text

Alternative text is a concise image text alternative for screen reader users. It's not shown to sighted users unless the image doesn't load.

Which can happen when someone has turned off images on their email application. Or they're using a slow connection.

<img src="flickr.svg" alt="Flickr">

Long Description

Long descriptions are longer text alternatives for complex images, which are shown to both sighted and screen reader users.

An expand/collapse accordion below an image is one example of a long description. Another example is a text description below the image.

Note: don't confuse the longdesc attribute with long description. Longdesc is a deprecated/obsolete and should no longer be used. It doesn't work on VoiceOver or mobile screen readers.

<img src="remote-workforce-infographic.jpg" alt="The Benefits of a Remote Workforce infographic with text description below">
<p>Text Version</p>

Caption

An image caption is visible to all users and typically displays below the image.

It's used to convey additional information about the image; it doesn't describe the image directly.

Image captions are optional and should never be the same as alternative text.

<figure role="figure" aria-labelledby="figcaption">
  <img src="detroit-parade-clown.jpg" alt="Clown with bright red hair and multicolored costume hands out purple bead necklace to young child">
  <figcaption>Detroit Thanksgiving Day Parade 2022</figcaption>
</figure>

Thanks to Paul Adams for helping me learn the differences between alternative text, long desciption, and caption.

Additional Resources

A Theory of Web Relativity

2022-12-21T00:00:00Z

The rel attribute has the potential to take the Internet to the next level… and yet, we usually forget about it.

Imagine a city where people guided themselves by the landmarks and the stores, where there were no directional signs, and where streets and neighborhoods had no names. It may sound like a U2 song, but it is the current state of the web.

The Internet is a vast network of related pages and nodes, but the connections between the elements are void of meaning by default. They lack semantics. A link may connect pages A and B, but what is the relationship between the two? Why are they related? Wouldn’t it be great if there was a way of expressing the relationship between the Internet nodes? Then we wouldn’t have just data; we would have meaningful information. It would take the Internet to a whole new level.

Fortunately, it is possible. Thanks to the rel attribute.

The rel attribute

The rel attribute defines a relationship between the linked resources (one being the document it appears on). And it provides that relationship with meaning, creating a semantic network where the different pieces have a role and a purpose. This detail may go unnoticed by most browser users, but not for the browser itself, assistive technologies, and web crawlers, which can take advantage of this attribute to provide a better experience. Also, savvy web developers can use it to make friendlier sites–we’ll see some examples in the following sections.

The rel attribute is valid in elements that link the document with another resource: <link>, <a>/<area>, and <form>. For simplicity purposes, when talking about <a>, it will include both <a> and <area>.

The supported values and how the browser treats them depend on the element in which the rel attribute appears. This is logical because the relationship can be a how or a what, and it not always makes sense to provide the “how” in some links.

Also, some rel values can be combined to generate more options and provide a more extended experience.

Link Types

Author’s Note: in this article, I will refer to the values/types defined in the IANA link relationship registry and the microformats wiki, but the main focus will be on the values listed in the HTML Living Standard.

I tried to group the types in categories depending on their function and the relationship they express. These are made-up categories to organize my work and they are not official in any way.

Meta types

“Meta links” provide information relevant to the document they appear in: meta information. Things like who’s the author? Where can we find an alternative version of the document? What is the license? Because of their nature, they can appear on <a> or <link> (although sometimes not on both) and never on a <form> tag.

alternate

The “alternate” relationship usually specifies an alternative version of the document itself, but some exceptions exist. It will be the most complex of all the rel meta values because the meaning it provides is heavily conditioned to the context in which it is presented.

If it appears along with the **stylesheet** keyword, the linked file is an alternative stylesheet. It won’t be applied to the document, but it will be ready for when we need it. For example:

<link rel="stylesheet" href="main-styles.css" />
<link rel="stylesheet alternate" href="dark.css" title="dark mode" />

When using `stylesheet` with `alternate`, the `` must have a `title` attribute with a short (and non-empty) description.

In this case, the “dark-styles.css” file is loaded asynchronously and not applied to the document. This way, the styles will be available whenever we want to apply them, without having to wait for network or traffic. Some browsers, like Firefox, allow switching between styles, facilitating the process for users:

If it appears with a type attribute that has the value application/rss+xml or application/atom+xml, then the alternate keyword creates a hyperlink referencing a syndication feed (in RSS or Atom respectively), which is useful for crawlers to find more content. In this case, it is not an exact alternative for the document, but it provides additional information about it, making it great for autodiscovery.

It can work both in <link> and <a>, and the meaning is the same in both:

<!doctype html>
<html>
  <head>
    ...
    <link rel="alternate" type="application/rss+xml" href="feed.rss" />
    <link rel="alternate" type="application/atom+xml" href="atom.xml" />
    ...
  </head>
  <body>
    ...
    <a href="feed.rss" rel="alternate" type="application/rss+xml">
      Subscribe to my feed and never miss a blog!
    </a>
    ...
  </body>
</html>

This combination doesn’t impact our site’s visitors, but it provides us with control over how or what we want web crawlers to process our site. If there are multiple linked resources of this type, the first one is considered the main/default one, so the order would be important in that scenario.

In any other case, the alternate keyword indicates that the linked element is an alternative version of the current document. But it doesn’t end there: the attributes that accompany the rel will provide additional information about the linked resource.

media: can be used to specify the target devices (mobile, print, etc.) for the alternative version.
type: used to identify what format (PDF, XML, etc.) the linked alternative version is available on.
hreflang: defines which language (English, Spanish, etc.) the linked resource is in.

This opens a world of combinations and possibilities. Again, maybe not so much for the browser users, but definitely for bots and crawlers that need to process the information as accurately as possible.

<!doctype html>
<html>
  <head>
    ...
    <!-- alternative document versions in German, Spanish, and French -->
    <link href="/de" rel="alternate" hreflang="de" />
    <link href="/es" rel="alternate" hreflang="es" />
    <link href="/fr" rel="alternate" hreflang="fr" />
    <!-- alternative document version in Spanish in PDF, specific for printing -->
    <link href="/es/print/" rel="alternate" hreflang="es" type="application/pdf" media="print" />
    ...
  </head>
  <body>
    ...
    <p>
      Thanks for checking out my online resume, feel free to download a
      <a href="resume.pdf" rel="alternate" type="application/pdf">
        PDF version.
      </a>
    </p>
    <p>
      <a href="https://m.link-to-our-site.com" rel="alternate" media="handheld">
        Check out a mobile version of this site too!
      </a>
    </p>
    ...
  </body>
</html>

Remember: the order of the attributes is not important, but for some cases, the order of appearance of the tag may define which is more important or the default one.

author

This may seem like an easy one: the “author” rel is a hyperlink that will point to the author (it could be mailto: with an email). But there’s a catch, the author of what? the page? the content inside? what?

The answer to these questions will depend on where the author link appears: if it’s inside an <article>, then it will point to the author of the article, if it’s outside of an <article> then it applies to the document/page as a whole.

Let’s review it with an example:

<article>
  <!-- Article content -->
  <footer>
    Written by <a href="https://janedoe.com" rel="author">Jane Doe</a>.
  </footer>
</article>

<!-- rest of the page -->
<p>
  Site created by <a href="https://johndoe.com" rel="author">John Doe</a>.
</p>

The first link appears inside an <article> which let us know that the link is pointing to the author of the article (Jane Doe). While the second link is outside any <article>, which tells us that is the author of the whole page (John Doe). This could be convenient in sites with syndicated content (like blogs or newspapers), to set a difference between the article’s author and the site’s owner/author.

Another way of specifying the page’s author is having an actual <link> tag in the page’s <head> with the rel “author”. Then we know for sure that it applies to the whole page and not just to a part of it:

<!doctype html>
<html>
  <head>
    <link rel="author" href="https://alvaromontoro.com" />
    ...
  </head>
  ...
</html>

bookmark

This rel value can only appear in <a>/<area>. It identifies a permalink for the nearest ancestor <article> or section (which doesn’t necessarily have to be a <section> element). This last part can be confusing, let’s review it with an example:

...
<body>
  <h1>James Bond Movies</h1>
  <article>
    <h2 id="no-time-to-die">No Time To Die</h2>
    <p>
      The twenty-fifth movie in the James Bond series. Daniel Craig was 
      James Bond in this installment.
    </p>
    <p>
      <a href="no-time-to-die.html" rel="bookmark">Permalink</a>.
    </p>
  </article>
  <div>
    <h2 id="goldeneye">Goldeneye</h2>
    <p>
      A movie and an amazing Nintendo 64 videogame. The iconic Pierce
      Brosnan played the role of James Bond on this movie.
    </p>
    <p>
      <a href="goldeneye.html" rel="bookmark">Permalink</a>.
    </p>
  </div>
</body>
...

The first link with rel= “bookmark” (permalink for No Time To Die) is inside of an <article>, so it will apply to that article in particular. The second link with rel= “bookmark” (permalink for Goldeneye) is outside of an <article>, applying to the closest section, which will be defined by the earliest ancestor with a heading.

Notice how, if the bookmark link is not inside an <article>, it can be a bit tricky to identify what section it applies to. It is more important than ever to use the right markup.

canonical

A canonical link specifies the preferred version of the document. This is really helpful if we cross-post content online: while a search engine indexes the pages, it will be able to identify the original version and not penalize the author for having duplicated content.

Many blogging systems (e.g., Medium, DEV, Hashnode, etc.) allow for specifying a canonical URL for the articles, and placing a <link> element with rel="canonical" just like this:

<!doctype html>
<html>
  <head>
    ...
    <link rel="canonical" href="https://path-to-preferred-url-version" />
    ...
  </head>
...

According to the HTML standard, it is only allowed on a <link> element, but the microformats definition mentions it on the <a> elements too. In my opinion, it would make sense to allow rel="canonical" in an <a> tag, but it could be problematic for publications. Better to stick to the HTML standard and only use canonical inside a <link> in the <head>.

help

This keyword can be used in all the available elements: <link>, <a>, or <form>. In all of them, it identifies a resource that contains help, the difference will be the scope of that help:

In a <link>, it will link to a help resource related to the document as a whole.
In an <a>, it will be help related to the section that contains the anchor.
In a <form>, it specifies that the target contains information about the form and its contents.

In the following example, the help link applies to the section that contains the label and input:

...
<form>
  ...
  <div>
    <label for="phone">Phone number</label>
    <input id="phone" name="phone" />
    <a href="phone-help.html" rel="help">(Help)</a>
  </div>
  ...
</form>
...

Browsers and assistive technologies can use this link to provide a more standard computer behavior. For example: historically, pressing F1 opens the help functionality; So they could open the linked resource if the special key is pressed while on the section to which the help link applies.
Also, in some cases, browsers may style the cursor differently if a link has the rel="help". (And if they don’t, it may be a nice feature to add by developers.)

icon

This rel value can only be used within a <link>, usually in the <head>, and it should link to an image. That image will then be displayed for representing the page in the user interface.

The rel="icon" can be combined with other attributes such as type, media, or sizes which will help the browser pick the most adequate icon for the user.

<link rel="icon" href="fav.ico" />
<link rel="icon" href="favicon.png" type="image/png" />
<link rel="icon" href="small.ico" sizes="16x16 32x32 48x48" />
<link rel="icon" href="large.ico" sizes="128x128 512x512 1024x1024" />
<link rel="icon" href="iphone.png" sizes="57x57" type="image/png" />
<link rel="icon" href="bw.ico" media="screen and (max-color:2)" />

You might have found a rel value of shortcut icon (in that order) instead of just icon, that was the old way of writing it and browsers still support it for historical reasons, but there’s no reason to do that anymore.

Another thing that we find in the wild is a rel value of apple-touch-icon. This is a specific value for Safari, only supported on Apple devices. Feel free to use it if you want to provide specific icons for them, but remember that it is not a standard value.

license

The license value can be used in all the supported tags (<link>, <a>, and <form>) to create a hyperlink to the copyright license terms under which the main content is provided. Notice the term “main content” instead of “current document” that is used throughout the article. This is because the license applies to the content itself, and the page/template may have a different copyright or license.

The specification does not specify how to differentiate the main content from the rest of the content. The link with rel="license" must be presented in a way that makes it clear to the user what content it applies to.

The following example simulates a website with images/videos and the license hyperlink for one of the images:

...
<figure>
  <img href="image.jpg" alt="Image for this demo" />
  <figcaption>
    An demo image for the article. License:
    <a href="https://creativecommons.org/licenses/by/4.0/" rel="license">
      CC BY 4.0
    </a>
  </figcaption>
</figure>
...

The value copyright was accepted in the past as a synonym of license, and browsers still support it, but we should go with the standard license.

manifest

The manifest relationship can only happen in a <link>. It indicates that the linked resource is a manifest file with metadata related to the current document.

The manifest may contain information about the entry file to install the web application, the icons to use, the app’s name, theme colors… In this article, we won’t dig into how to use the manifest as our focus is exclusively on the rel attribute used to link it.

Here’s how you can link your manifest from the <head>:

<!doctype html>
<html>
  <head>
    ...
    <link rel="manifest" href="/manifest.json" />
    ...

s
Two important things to remember about this rel value:

Browsers will use the first <link> with rel="manifest" in the tree order, ignoring any other that may appear.
Browsers will execute the manifest when they consider it necessary, never assume that the entry point script will be executed.

pingback

A pingback is a method for authors to get notifications when their content is linked. With pingback, we can provide the address of the pingback server that handles the pingbacks to the current document:

<link rel="pingback" href="https://alvaromontoro.com/pingback" />

This can be useful, for example, to process the notification and add a note on the page (like WordPress does). It can also be helpful for SEO.

The pingback value can only be used in the <link> element.

search

The search keyword indicates that the linked resource provides a way of searching the document and its related resources. It redirects to a search page.

<p>
  Read more about this topic by <a href="/search" rel="search">searching this
  site</a> or <a href="https://google.com/search?q=rel+attribute" rel="search">
  checking on Google</a>.
</p>

Notice how it doesn’t have to be an internal search functionality. In the example above, one of the search links points to Google.

Some browsers allow adding plugins to their interfaces to provide custom searching features. If we have an OpenSearch plugin, we can link it using type="application/opensearchdescription+xml" alongside the search value to add the plugin easily to the browser.

tag

The linked resource contains information about a tag or keyword related to the current document. It can be a description, a list of other elements from the same category, etc. This rel value is only valid on a and area elements.

A practical use of the tag value could be seen on blogs or other sites where content can be categorized. StackOverflow is a great place to see links with rel="tag" working live. Or we could have something like this on our blog:

...
<article>
  <h1>The Definitive Guide of Colors in CSS</h1>
  ...
  <footer>
    <h2>Tags</h2>
    <ul>
      <li><a href="/tags?t=css" rel="tag">CSS</a></li>
      <li><a href="/tags?t=htm" rel="tag">HTML</a></li>
      <li><a href="/tags?t=webdev" rel="tag">Web Development</a></li>
    </ul>
  </footer>
</article>
...

The rel="tag" links apply to the whole page independently of where they appear within it. Even if they are located inside an article, they are not exclusive to the article itself.

Personal Types

They indicate a relationship between the author of the document/article and the linked resource (which should be an online profile). The HTML standard only has one of this type (“author”), but the XHTML Friends Network (XFN) defines many more:

author: see description in the meta types.
crush: the linked page represents a person you have a crush on.
date: the hyperlink is to a page about someone you are dating.
friend: the link identifies a friend.
me: this value became really popular with the rise of Mastodon. It is used to link to a page that represents the same person as the current document.
muse: a link that identifies a person who inspires the person.

As you may imagine, there are many more values that could be used. Quite often, just using the English word for the personal relationship will work as a valid rel: colleague, child, acquaintance, neighbor, parent… all good.

Here are some of these personal rel values in action:

<h1>Welcome!</h1>
<p>
  My name is <a href="profile.html" rel="me">Ross Geller</a>, thanks for 
  visiting my personal website!
</p>
<p>
  I live in NYC with my buddies <a href="j-man.html" rel="friend">Joey</a>
  and <a href="king-of-bad-thanksgivings.html" rel="friend">Chandler</a>. 
  In the same building block as famous cook (and my younger sister)
  <a href="monica.html" rel="sibling">Monica Geller</a>.
</p>
<p>
  Monica lives with <a href="rachel.html" rel="crush date">Rachel</a> and 
  renown musician <a href="regina-phalange" rel="muse friend">Phoebe</a>
  (author of the smash hit "Smelly Cat").
</p>

One last point about this personal type: only the “author” value is supported in a <link> tag, all the others are only allowed on <a>.

Processing Types

These types don’t indicate what the linked resource is or how it is related to the current document, instead, they tell the browser how the link should be treated or processed, creating a connection that may not be completely semantic but making it special.

All of these values are only accepted in the <link> element, they will normally appear in the <head>, and will mainly impact performance.

dns-prefetch

The dns-prefetch keyword indicates that the browser should preemptively perform DNS resolution for the specified domain. Basically, we are telling the browser that we will likely need some resources from the linked domain, so it will be beneficial and good for the user experience if it started resolving the address and getting ready to ask for files.

Using this type of rel reduces the latency when requesting an online resource and improves the overall performance, giving the impression that the content loaded faster (because some of the load work was done before it was actually needed.)

For example, if we are using Google Fonts, and we know that our page will at some point need the font, we can prefetch the CDN where Google hosts the fonts:

<link rel="dns-prefetch" href="https://fonts.googleapis.com">

If you have used Google Fonts before, you might have noticed that it doesn’t use rel="dns-prefetch" but rel="preconnect" (we will analyze it soon). This is because dns-prefetch only performs DNS resolution, while preconnect does DNS resolution and also establishes a connection to the server, making the process faster.

Which raises a fair question: why even use dns-prefetch if preconnect does more? Because network connections are “expensive”. If we need sources from many third-party domains, preconnecting to all of them may impact performance negatively. Instead, it would be better to preconnect only to the more “urgent” ones and do a dns-prefetch for the rest. There’s no risk in using both together (even for the same domains!) and if for some reason the browser doesn’t support them, it won’t impact our site at all (apart from having to load a couple more lines of code.)

modulepreload

JavaScript code is getting bigger and bigger, and it is becoming more important to split the code and organize it into simpler modules that can be run when needed. NodeJS and some frameworks have their own methods for module usage, and some browsers provide native module functionality too. This is where the modulepreload value is important.

We can use rel="modulepreload" to preload a module script and place it in the appropriate module map without evaluating it (that will happen when it is required). This optimizes the module load, making the process more efficient.

<!doctype html>
<html>
  <head>
    ...
    <link rel="modulepreload" href="app.mjs" />
    <link rel="modulepreload" href="record-player.mjs" />
    <link rel="modulepreload" href="trade.mjs" />
    <link rel="modulepreload" href="payment.mjs" />

    <script type="module" src="app.mjs"></script>
    ...

In the example above, we are preloading several scripts. The main module is executed (app.mjs), and the others will be available whenever they are needed (record-player.mjs, trade.mjs, payment.mjs).

modulepreload is basically a specialized version of the preload keyword (see below), as it applies specifically to one type of resource: script modules.

preconnect

As mentioned in the dns-prefetch section, with the preconnect keyword, we indicate to the browser that a resource from the linked domain will most likely be needed, and initiate a connection to its origin before the resource has even been found by the browser.

By doing so, we are increasing the network performance, because we are establishing a connection that will be ready when it’s needed, reducing the latency, and improving the user experience.

A practical example of preconnect can be found on Google Fonts: you may have noticed the code to embed fonts includes a couple of extra lines:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">

The first two <link> use preconnect while the third <link> imports a stylesheet which will bring the font. Those first two lines initiate a connection for loading content from the Google CDNs, so the browser is ready to download the files.

prefetch

With prefetch, we identify a resource that may be used by the subsequent pages, telling the browser that it should fetch that resource to deliver a faster response when the navigation to those pages actually happens. The browser will proceed to load the content into the cache for later use.
Prefetching some files for later use–an image, some script, and a song:

<link rel="prefetch" as="image" href="super-important-image.jpg" />
<link rel="prefetch" as="script" href="code.js" />
<link rel="prefetch" as="audio" href="https://somecdn.com/music.mp3" crossorigin />

The as attribute is optional, but highly recommended (see preload section for more details.)

Use prefetch carefully. It is a little bit of a “gamble”: we are fetching content that we presume the user will need soon, but if the user doesn’t navigate the way we expect it, we might have used bandwidth unnecessarily.

preload

With preload, we ask the browser to fetch some resources and process them as specified with the as attribute, because those files are important and we will need them on the current document.
In this example we will preload an image, a script file, and an audio file:

<link rel="preload" as="image" href="super-important-image.jpg" />
<link rel="preload" as="script" href="code.js" />
<link rel="preload" as="audio" href="https://somecdn.com/music.mp3" crossorigin />

Notice the as attribute because it is not trivial. It tells the browser what type of resource is being linked so it can process it adequately. Without it, the browser may end up fetching the content twice (the same thing with the crossorigin attribute.)

So, how are preload and prefetch different? While they seem to do the same, there’s a key difference: prefetch is used for “lower priority” resources that will be needed at a later time, and preload is for “higher priority” content that will be needed sooner (as on the same page, but that may have not been discovered by the browser yet.)

I will end this section by giving a piece of advice: do not preload everything. Quoting The Incredible’s supervillain Syndrome: “When everyone is super, no one will be.” If we preload every file that we will need, then there won’t be a real gain (and it may even be counterproductive). Be selective with the content to preload, and consider using prefetch or preconnect.

prerender

prerender works similarly to prefetch but at a larger scale. The linked resource may be a page, and it is not only prefetched but also processed (including its content) and rendered, caching the result until it’s needed.

Imagine that you created a multi-page form. You may want to prerender the next step because the user should logically navigate to it:

<link rel="prerender" href="form-step-2.html" />

As with prefetch, prerender could be a bit of a “gamble” (even more this time): if the user doesn’t navigate the site the way we expect or if they leave the site completely, we will have fetched and processed content unnecessarily.

stylesheet

Surprised to see this value as part of the processing types? I considered adding it to the meta types, but it fits here better.

The stylesheet indicates that the linked resource contains styles for the page, so it provides a little semantics; but it does much more: browsers know that stylesheets are a key part of the page’s presentation and, unless the alternate keyword shows up too, it also knows that it needs to process the styling file and apply it to the page. The stylesheet keyword is telling the browser how to treat the linked file.

Its basic use is simple: only in <link>, the rel="stylesheet", and an href pointing to the stylesheet file. We can also use other attributes (media) to change the default behavior and when the styles will be applied:

<!-- this file will be automatically downloaded and applied -->
<link rel="stylesheet" href="my-super-cool-styles.css" />

<!-- this one is downloaded but not applied -->
<link rel="stylesheet alternate" href="prototype.css" title="prototype" />

<!-- this one is downloaded but only applied when printing -->
<link rel="stylesheet" href="printer.css" media="print" />

Network Types

The “network types” specify the type of connection that the document and the linked resource have as well as the information that will be shared between them.

They don’t create a link, they annotate it, making it easier for crawlers and spiders to index the content appropriately. As they will have more information about the nature of the connection.

external

A resource is external if it is not part of the current site. We can easily identify them by adding a rel="external" to it, which is allowed on <a>/<area> or the target in a <form>, but never on a <link>.

<!-- on a personal blog -->
<a href="https://en.wikipedia.org/wiki/Cat" rel="external">Read about cats</a>

This doesn’t give much information to the browser (it is transparent for it), but it can be convenient for developers to use CSS attribute selectors and style these links differently:

/* add a small icon behind each external link */
a[rel="external"]::after {
  content: url(external-icon.svg);
  margin-left: 0.5rem;
  vertical-align: middle;
}

nofollow

A nofollow rel value on a link tells the crawlers to “ignore” the linked resource because it is not endorsed by the current document’s owner, or that it was included because of a commercial relationship.

It is an important value for Search Engine Optimization (SEO): if your page links to low-quality content, your site’s credibility (and its ranking in the search engines) may suffer. Using nofollow won’t penalize your site:

<a href="https://totallynotmischivieoussite.com" rel="nofollow">
  This is a link created by an user
</a>

Using rel="nofollow" in user-generated content and links is a must. You never know what they are going to share, and you don’t want to end up on the losing side of a spamming scheme.

noopener

A link may have access to the previous page by using window.opener depending on how it was opened (e.g. if it has target="_blank"). This is a potential security problem and it could lead to other issues like phishing attempts.

To avoid these situations, we can use noopener value in rel to open the new document without granting it access to the document that opened it:

...
<div class="comment">
  Check my <a rel="noopener" href="https://no-good-phishy-site.tk">site</a>
</div>
...

As with nofollow, the main target for this value will be user-generated content that we don’t want to provide with extra information.

noreferrer

noreferrer is really close to noopener. In fact, it does the same thing as noopener (it doesn’t grant access to the document) plus it tells the browser to omit the Referer header when opening the link. This way, the linked resource cannot access the referrer’s information (e.g., its address).

This provides an extra layer of anonymity and security. The linked resource will not see a referrer, looking like the request came from direct traffic to their site instead of from the originating link.

...
<div class="comment">
  Check my <a rel="noreferrer" href="https://no-good-phishy-site.tk">site</a>
</div>
...

noreferrer and nofollow are often used together, to ensure that one is applied in case the other one is not supported by the browser.

opener

This is effectively the opposite of noopener. It doesn’t add that extra layer of protection when following the link by allowing it to access the opener.

<a href="./help-page.html" rel="opener">You have access</a>

Sequential Types

These values indicate that the current document is part of a series or sequence and specifies the relationship of the linked resource with it. They have a big impact on user experience, accessibility, and SEO.

The HTML Living Standard only has two values related to sequences: “next” and “prev”, but there are some interesting ones defined in previous versions of the standard that are listed by IANA and microdata too:

next: indicates that the linked resource is the next in a series.
prev: refers to the linked document as the previous in a series.
previous: this value is a synonym of “prev”. It isn’t valid anymore, so we should avoid it, but browsers may still treat it as a “prev” for historical reasons.
first: identifies the linked document as the first in a series.
last: indicates that the linked resource is the last in a series.
contents: the linked document is a table of contents. Some agents may use the synonym toc too.
archives: links to a collection of records or materials of historical interest for the document.
up: refers to the parent/upper category of the current document. Not necessarily in a sequence, but it shows some hierarchy.

Here’s a practical example of how it could be used to create pagination:

<nav aria-label="course index">
  <ul>
    <li>
      <a href="toc.html" rel="contents">Table of Contents</a>
    </li>
    <li>
      <a href="lesson-1.html" rel="first">Lesson 1</a>
    </li>
    <li>
      <a href="lesson-2.html">Lesson 2</a>
    </li>
    <li>
      <a href="lesson-3.html" rel="up">Lesson 3</a>
    </li>
    <li>
      <a href="lesson-3.1.html" rel="prev">Lesson 3.1</a>
    </li>
    <li>
      <a href="lesson-3.2.html" aria-current="page">Lesson 3.2</a>
    </li>
    <li>
      <a href="lesson-3.3.html" rel="next">Lesson 3.3</a>
    </li>
    <li>
      <a href="lesson-4.html">Lesson 4</a>
    </li>
    <li>
      <a href="lesson-5.html">Lesson 5</a>
    </li>
    <li>
      <a href="lesson-6.html" rel="last">Lesson 6</a>
    </li>
    <li>
      <a href="glossary.html" rel="glossary">Glossary</a>
    </li>
  </ul>
</nav>

In this example, we have a navigation with eleven links to the table of contents, each of the six lessons (plus three “sub lessons”), and a glossary page. Many of those links have been extended using the rel attribute and provide helpful information to the browser and assistive technologies.

One perk of using “next” and “prev” with a <link> is that the browser may preload the linked documents to reduce the perceived load time, assuming that the user will most likely move forward/backward within the series.

<link rel="next" href="https://link-to-next-in-series" />
<link rel="prev" href="https://link-to-previous-in-series" />

In the past, Google used the “next” and “prev” links to index the pages accordingly, but that is no longer the case. This doesn’t mean you should stop using those values: they are still helpful for accessibility, and other search engines may index based on them. Google is dominant but not the only one.

Conclusion

As you may have noticed by this really long article, the rel attribute is anything but trivial. It plays an important role in providing meaning to the links, taking the Internet to the next level semantically, and boosting your site’s performance through the roof.

If you made it here (did I already mention that this article is really long?), take a few more minutes to check other resources with more details and better explanations (Addy Osmani’s article is simply amazing.)

Thanks for reading!

Bibliography

<a>: The Anchor element, on MDN Web Docs.
<area>: The Image Map Area element, on MDN Web Docs.
<form>: The Form element, on MDN Web Docs.
<link>: The External Resource Link element, on MDN Web Docs.
Existing rel values, on the microformats wiki.
HTML Attribute: rel, on MDN Web Docs.
Link Relations, on the Internet Assigned Numbers Authority (IANA).
Links, on the HTML Living Standard.
Pingback 1.0, by Ian Hickson.
Preload, Prefetch And Priorities in Chrome, by Addy Osmani on Medium.
Preload, Preconnect, Prefetch: Improve Your Site’s Performance with Resource Hints, by Niko Kaleev on Nitropack.
Resource Hints (Working Draft), by Ilya Grigorik on the W3C.
XFN 1.1 relationships meta data profile, on the GMPG.

HTMHell

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, ` `