I’m tagging in Evan, Aleksandr, and Ashlee. If y’all are comfortable with it, I’d love to learn how you got your start with blogging.

Broadly, I enjoy writing. Essays, for instance, were a schooltime forte of mine. I cut my teeth on technical writing during my internship at USAA, where I wrote wikis that were among the company’s earliest internal documentation for React and Redux, the web stack the company had recently pivoted to.

My time at USAA also led to my public-facing writing here on the blog in a few ways. The first was an assignment my manager gave my team to try our hands at writing whitepapers, topics of our choice. I decided to read up on U.S. case law surrounding digital accessibility. I later adapted parts of that whitepaper into my first post, as well as my first meetup talk.

One of my favorite parts of my USAA tenure was getting to be one of the instructors for USAA’s season-long new-hire web development training. There, I (re-)encountered the questions, challenges, and misconceptions that new web developers face… and occasionally, I found established resources unhelpful or unsatisfactory. I ended up writing the resources I wish I had been able to find.

That training program followed a React video course that today boasts hundreds of thousands of participants. I’d taken that course myself during my internship, and it was interesting to revisit with more experience while the students took the course fresh. To my surprise, the course was riddled with a pattern I’d since unlearned: using <div> with click handlers instead of <button>s. I took that and wrote my second blogpost: How (Not) to Build a Button. More and more blogposts came out of resources I needed for the training, such as my ARIA explainer or an introduction to lexical and dynamic scope.

This site is built with the Eleventy static site generator. I switched to Eleventy in 2020 after taking Andy Bell’s Learn Eleventy From Scratch course.

Eleventy is refreshingly focused on static pages, which has helped keep my blog lightweight and performant like I would like a blog to be. Any perf hurdles have been my mistake, rather than set by some minimum viable bundle size. I’ve found Eleventy to be neatly extensible where I’ve needed it to be. The focus on Markdown over more involved templating like MDX or Astro makes me feel more comfortable with the idea of being able to move away from Eleventy at some point in the future if I ever need without needing to totally rewrite old posts, but also, after almost five years (!!!) of this Eleventy-ified setup, I feel like my blog setup is only getting better and better, and I’m in no rush to move away from that for the time being.

I built the first version of this blog with Gatsby, and specifically, the gatsby-starter-blog template which I very poorly attempted to restyle. I moved away from Gatsby in large part because I felt like I was wrangling needless complexity any time I wanted to write a new post, especially any posts that required extending the site in some way. The tooling felt like overkill, and it was overkill that felt like it was getting in the way of writing.

For example, in a local editing tool, or in a panel/dashboard that’s part of your blog?

All in Markdown, all in my site’s repo, all in VS Code, all with Git.

I’ve never been particularly great at expressly writing and rewriting drafts for the sake of being drafts. Instead, I self-edit heavily as I go. As a result, I end up writing in what will be the end format and location for the posts anyways: Markdown files in my site’s codebase.

Writing within my codebase and running it locally gives me a better sense of what the post will look like in the end. Are my paragraphs running long? Am I mixing too many kinds of elements or styles too closely together? Additionally, I can go ahead and start embedding code demos (courtesy of Aleksandr Hovhannisyan’s eleventy-plugin-code-demo plugin) from the get-go, and edit it as I edit the post.

This said, I very rarely write linearly from the start of the post to the end. Instead, I often stub out the headings I think I’ll need, and then skip around from section to section to flesh them out as the mood hits. For instance, this is the first answer I actually completed.

Blogging inspiration tends to come more freely to me when I’m already teaching people, as a result of the questions or misconceptions that come up. Teaching new web developers at USAA was great for this, as was answering questions when I was streaming. My (now a little outdated) post about skip links came out of a question I was asked on stream! These days, I’m not really doing anything like that, so I don’t quite have my finger on the pulse of which questions need answering anymore.

In other cases, I’ve seen something get shared, and feel a need to correct the record. My most recent post, Don’t Use aria-label on Static Text Elements, was an example of this. In these cases, I try not to call out the original source, especially since by the time I’ve written something about it, the particular catalyst is usually just one example of many.

I know in the past, I’ve used this blog as a worry stone in times where I’ve felt more anxious about work. As I’ve progressed in my career, I’ve felt much less like I “need” to spend extracurricular time thinking and writing about web development, and I’ve replaced that time with more reading and spending time with friends (as an aside: I highly recommend seeking out your local theaters). Feeling less compelled to write as often is probably a good thing, then.

For some of my bigger accessibility posts, I will hold off on publishing for a day or two while some friends look it over and provide feedback. By the time people are reading it over, however, the bones of the post feel pretty set in stone for me, and I’m not likely to make substantial changes. I’m also just anxious to get the thing out — so drafts likely won’t simmer any longer than two days.

As will likely come as a surprise to no one, I mostly write about web accessibility. In particular, my hope is that I can provide accessibility guidance that feels tangible and applicable, and that readers can see their projects and scenarios represented in the guidance.

The most straightforward answer is that I’m writing for any web developer who wants to learn more about accessibility and inclusive design.

I also often feel like I’m writing for fellow accessibility advocates. This is in part because one outcome of writing about any technical niche is that the folks who find said writing are most likely to already be involved in that same niche. That’s okay because time and time again, I’ve experienced just how useful it is to be able to link to just the right post from another writer in my team review comments, chats with coworkers, documentation, new-hire training, and my own blogposts. Not only is it a huge time-saver, citing others from the within the industry can also lend an accessibility advocate some extra credence. Part of why I write is because I hope someone will be able to share something I’ve written as they make their case for more inclusive design.

At the moment, On the <dl> tops the list for me. It was a very fun exercise to showcase the versatility of a fairly simple, straightforward markup pattern. I don’t think any of my other posts have really given me the same kind of chance to just let loose with my examples, and I think demonstrating UI patterns that people have definitely seen in the wild goes a really long way towards making the post’s point.

I’m a Spotless Giraffe. is also up there for me, in that I put myself out there personally in a way that I don’t usually on this blog.

Maybe a redesign, a move to another platform, or adding a new feature?

I’d love to add some good search functionality; navigation feels like the site’s weakest spot right now. I know others in the Eleventy space have been toying with Pagefind as of late, and I should sit down sometime and figure it out.

I’ve quietly been adding some pages here and there that reflect more and more of my non-work, non-webdev interests (can I interest you in a catalog of my tabletop roleplaying game campaigns, perhaps?), and I’d like to keep making this site reflect more of me like that.

Originally posted on my blog, benmyers.dev, as Tag, You’re It: Blog Questions 2025

Too Long; Didn’t Read

Don’t use the aria-label or aria-labelledby attributes on <div>s, <span>s, or other elements representing static/noninteractive text-level semantics, such as <p>, <strong>, <em>, and so forth, unless those elements’ roles have been overridden with roles that expect accessible names.

That’s a bit of a mouthful, and I couldn’t fit it all in the title.

A very common accessibility bug involves applying the aria-label or aria-labelledby attributes to static, text-level semantics, especially <div>s and <span>s.

<!-- 🚨 The following examples are all invalid 🚨 -->

<span aria-label="Vegetarian">
	🌱
</span>

<div aria-labelledby="about">
	<h2 id="about">
		About
	</h2>
</div>

<div tabindex="-1" aria-label="Draggable item. Click, tap, or press Space to select. Drag, or use arrow keys to move.">
	<!-- … -->
</div>

However, aria-label and aria-labelledby aren’t permitted on these elements — at least, not without also changing those elements’ roles. This means that in most browser/screenreader combinations (we’ll get to a notable exception shortly), users generally won’t receive invalidly applied aria-labels or aria-labelledbys, making these accessibility “fixes” anything but.

The short, rule-of-thumb-friendly explanation here is that aria-label and aria-labelledby are generally intended for interactive elements (buttons, links, form controls) and landmark regions.

The longer, more precise explanation is that HTML elements are mapped to roles, which specify which kind of thing the element represents. Certain ARIA attributes are only permitted on certain roles. aria-label and aria-labelledby replace an element’s accessible name, which only some roles are permitted to have in the first place. The way aria-label and aria-labelledby are defined in the ARIA 1.2 spec, they are permitted on any role except the following: caption, code, deletion, emphasis, generic, insertion, paragraph, presentation, strong, subscript, and superscript — generally, your static, noninteractive, text-level semantics. At time of writing, the ARIA 1.3 draft spec, which browsers have taken a headstart in supporting, also prohibits aria-label and aria-labelledby on the definition, mark, none, suggestion, term, and time roles. This means that, per the specs, the following elements aren’t allowed an aria-label or aria-labelledby out of the box, until you start overriding roles:

This matters because browsers adhere to these specs when assembling accessibility trees for screenreaders to consume, and screenreaders are generally built around supporting these specs. It’s less that aria-label doesn’t “work” on static, text-level semantics, but that it’s not even intended to.^{[note 1]}

If a browser/screenreader combination does handle aria-label and aria-labelledby on static elements like it does permitted roles, that’s an exception to the rule. Which brings us to a common source of confusion:

It’s important to test changes with actual assistive technologies like screenreaders, but this can cause a footgun of its own if we test just one tool and assume that its behavior is representative of all similar tools.

We can see a solid example of this with the VoiceOver screenreader built into macOS. When it comes to aria-labels on generic elements, VoiceOver generally does announce the contents of the aria-label. If that’s the behavior you were expecting, then testing with VoiceOver alone would seem to suggest that this is a condoned, functioning pattern. In actuality, VoiceOver is doing what many user agents do in the face of invalid code: compensating for developers’ misguided intent so as to not penalize users. That aria-label “works” on generic elements in VoiceOver is a nonstandard remediation of noncompliant code, not an endorsement of a technique working as intended.

As WebAIM’s surveys of screenreader users have borne out, VoiceOver for macOS is severely overrepresented by developers and site/app testers compared to disabled day-to-day screenreader users.^{[note 2]} When relying on solely VoiceOver for macOS when testing, developers and testers are optimizing for a platform that few disabled users are actually on, with no sense of the expense caused to users on other platforms.

This isn’t to say you shouldn’t test on VoiceOver or consider the VoiceOver user experience… just that it should be one tool of many in your accessibility testing toolkit.

If we can’t put aria-label or aria-labelledby on static text elements, what should we do instead? It depends, but here’s how I’d approach a few different scenarios:

aria-label is a code smell — not necessarily inherently wrong, but often a sign that we might be going off the beaten path. In some cases, the aria-label might have been put in place to address a perceived problem that might not have been worth solving in the first place, or for which a solution could make things worse in other ways.

For instance, sometimes developers will attempt to use aria-label to micromanage screenreaders’ pronunciations of words. In attempting to fix pronunciations, the resulting markup hacks can often make the text completely inscrutable in braille output,^{[note 3]} and can complicate voice control usage as well. Meanwhile, pronunciation depends heavily on which text-to-speech engine is in use, and we’re assuming the mispronunciation is even a real, blocking problem in the first place.

On a similar token, sometimes aria-label is used to provide verbose, redundant, potentially off-base control hints, which we could opt to rip out.

These kinds of techniques often arise from incomplete understandings of how screenreader users navigate the web as well as unvalidated assumptions about how they would prefer to receive information, and so the best alternative just might be removing those aria-labels and aria-labelledbys.

In some cases, the aria-label was intended to serve as a sort of alternative text.

In the case of iconography, oftentimes we can opt to rework the design in favor of exposing the information as raw, visible, universal text. After all, if blind readers would benefit from some extra context or clarity, who’s to say sighted readers wouldn’t benefit from the same?

<!-- Instead of… -->
<span aria-label="Vegetarian">
	🌱
</span>

<!-- Try… -->
<span>🌱 Vegetarian</span>

<!-- Or maybe… -->
<span>
	<span aria-hidden="true">🌱</span>
	Vegetarian
</span>

Ah, the design remains firm, unbudging. We can’t clutter the experience with visible text, it would seem.

Another thing we could do then is a one–two punch of marking the visible contents as aria-hidden, and then using visually-hidden styles to provide an alternative for screenreaders to expose:

<!-- Instead of… -->
<span aria-label="Vegetarian">
	🌱
</span>

<!-- You could do… -->
<span aria-hidden="true">🌱</span>
<span class="visually-hidden">Vegetarian</span>

<div> doesn’t accept an aria-labelledby, but if we’re trying to apply one pointing it to a heading, then chances are good that we’re trying to mark out a region of the page, and what we really want is something more like a labeled <section> or <article> element instead.

<!-- Instead of… -->
<div aria-labelledby="about">
	<h2 id="about">
		About
	</h2>
	<p>…</p>
</div>

<!-- Let’s make a useful landmark -->
<section aria-labelledby="about">
	<h2 id="about">
		About
	</h2>
	<p>…</p>
</section>

This is especially true for interactive elements — reverse-engineering all of the accessibility requirements for interactive elements often just isn’t worth it.

In some cases, we actually might want to keep the aria-label or aria-labelledby, and just add an applicable role.

<!-- Instead of… -->
<span aria-label="Vegetarian">
	🌱
</span>
<span aria-label="Kaomoji table flip">
	(╯°□°)╯︵ ┻━┻
</span>

<!-- It might be more appropriate to expose these like images… -->
<span role="img" aria-label="Vegetarian">
	🌱
</span>
<span role="img" aria-label="Kaomoji table flip">
	(╯°□°)╯︵ ┻━┻
</span>

Originally posted on my blog, benmyers.dev, as Don’t Use aria-label on Static Text Elements

Captioning’s Moment

I’m profoundly deaf. I rely heavily on my hearing aid, and every time I can watch something with captions, I will without a second thought.

Anecdotally, it feels like captions have been having a moment the past few years, as awareness of them — and the expectation of their presence — grows. In a few short years, we’ve gone from Rikki Poynter’s No More CRAPtions campaign, a plea for YouTubers to invest in their videos’ closed captions at all, to the more recent breathless reporting over the evocative captioning in Stranger Things and the news that more than half of Gen Z and millennial viewers prefer to watch TV with subtitles.

Meanwhile, Ubisoft found that in Assassin’s Creed: Odyssey, which has captions on by default, 95% of players leave those captions on. This suggests, at minimum, that most of those players aren’t finding the captions intolerable and outright rejecting their presence. At A11yTO Conf 2023, I heard from several folks in the game development industry who said that this very revelation has absolutely emboldened accessibility efforts in many game studios, leading to better, more usable defaults for games going forward.

One throughline I’m seeing in the reporting about captioning’s current trendiness is that TikTok may have played a big part in normalizing the use of captions and subtitles for younger viewers. Again anecdotally, this would make sense to me. While I’m sure there’s plenty of algorithmic self-selection bias at play here, it seems like many videos come across my For You Page where the creator has done the work to burn in their own subtitles, even alongside TikTok’s own built-in closed captions feature. It’s pretty commonplace to see those burnt-in subtitles prefixed with [CC] — short for closed captions. This is technically inaccurate in several ways, as we’ll see pretty shortly, but I still think it’s really useful shorthand nonetheless. Even if it’s not technically right (and, honestly, saying anything in language is technically right is pretty fraught, given semantic drift), it absolutely signals the intent clearly enough.

In everyday language, terms like captions, closed captions, and subtitles all get used pretty interchangeably — and the [CC] abbreviation stands as shorthand for all of them. Within the professional transcription industry and amongst many deaf and hard-of-hearing consumers, however, these terms often have very particular meanings. Knowing the differences between them can help you pick, and better understand, the access tool that’s right for your content and your viewers.

Broadly speaking, the differences here fall along two axes:

• The difference between captions and subtitles is what I’d call the content axis.
• The difference between open and closed captioning is the technology axis.

While captions and subtitles are both transcriptions displayed synchronously with the audio, the difference between them is what content gets transcribed.

• Subtitles are synchronized transcriptions of just the dialogue.
• Captions are synchronized transcriptions of all meaningful audio — dialogue, laughter, applause, music, slammed doors, and more.

If a given video doesn’t really have any non-dialogue audio, then the captions and the subtitles would be one and the same.

Subtitles generally assume a user can hear, and thus make out any laughter, applause, music, slammed doors, and so forth, but for whatever reason, need a hand in making out specifically what’s being said. The most common use case for this is translation, although I also see subtitles crop up as a way to supplement poor audio. Because subtitles generally assume the user can hear, they might also omit elements that are more common in captions, such as speaker labels.

Captions, meanwhile, assume that the viewer can’t hear as well, and thus seek to transcribe any audio that the viewer would find meaningful for understanding the video. They often follow conventions for helping the viewer better make sense of the transcription, such as labelling when different people start speaking, and they might use certain formatting standards to indicate when speakers are off-screen or when the speech is provided as a voiceover.

To see the difference, check out these two versions of the movie trailer for the 1955 film Creature with the Atom Brain:^{[note 1]}

Here, both the captions and the subtitles are implemented as open captions, which we’ll get to shortly. If the videos didn’t load, or if you couldn’t watch the videos for any reasons, feel free to check out the captions’ text file and the subtitles’ text file instead.

When it comes to the dialogue, the two versions are identical. Where they differ is that the captions include notes about the background music, gunshots, choking sounds, mysterious bubbling substances, miscellaneous explosions, and inaudibly mouthed words, whereas these cues would instead be considered superfluous in the subtitles.

If you’ve ever wondered what makes closed captioning closed, or if there’s also an open captioning, then the technology axis is for you. The difference between open captioning and closed captioning comes down to how the synchronized transcription is provided/associated with the video:

• Open captioning is when the synchronized transcription is burned into the video — i.e., added to the actual pixels of the video using some video-editing software.
• Closed captioning is when the synchronized transcription is supplied as metadata for the video or sent as an additional file, which allows the captions to be turned on and off.

We can see the difference by revisiting our favorite creatures with atom rays of superhuman strength. In the second demo, you should be able to go into your video player’s controls and turn the captions on and off.

Between the two, closed captioning generally affords the viewer much more flexibility:

• Toggling them on/off: Any viewer can opt into captions if they find them helpful, or opt out of them if they find them distracting.
• Controlling their visual presentation: Depending on the video player, viewers may be able to select the fonts, colors, backgrounds, sizes, and placements that work best for their needs (whereas with open captioning, you might get stuck with captions that are incredibly small, tucked out of the way, placed against busy backgrounds, or which have horrendous color contrast — I’ve seen tiny captions in white text on a soft pink background on TikTok before, for instance)
• Switching languages: Multiple tracks for different languages’ subtitles can be provided via closed captioning technologies, letting users opt into the language they want.

Additionally, closed captions won’t fall victim to overzealous video compression, and video players can nudge the captions around to accommodate things like hiding and revealing other controls, ensuring the captions don’t get covered up. From a creator standpoint, closed captions are also generally easier to update after the fact, since updating them usually doesn’t require editing and reuploading a whole new video.

Open captions, edited into the pixels of the video itself, have their benefits, too, however:

• Necessary for platforms which don’t support closed captioning: Open captioning works anywhere that videos do, whereas not all platforms support uploading closed captions.
• Reshareability/portability: When viewers save videos, closed captions aren’t always guaranteed to save as well. If there’s a chance that the saved video gets reuploaded somewhere else, it would then be missing its captions — whereas open captions are guaranteed to remain part of the video, save for some serious editing out.
• Fault tolerance: If a platform supports closed captions but the support is particularly unreliable (such as during TikTok’s rollout of closed captions, where users’ ability to see or add captions regularly broke) or where added captions are somehow prone to disappearing, then it’s probably best to treat the platform like you would a platform that doesn’t support closed captioning in the first place.
• No tech know-how required to use: Since open captions don’t need to be turned on, viewers don’t have to navigate their video player or app to take advantage of them. This is especially helpful when your target audience is less comfortable with technology, or when your video player is more of a one-time experience rather than a regularly returned-to app.
• Mitigating poor audio quality: In some cases with poor audio quality where everyone would struggle to make out what’s being said, including many people who wouldn’t necessarily already have captions turned on, open subtitles can momentarily pop in to clarify the dialogue for everyone.

Closed and open captioning look a little different in the world of movie theaters. Deaf and hard-of-hearing patrons can request closed-captioning peripheral devices, such as glasses or readouts you stick in your cupholder. In practice, patrons often find these devices unreliable, poorly synchronized, connected to the wrong film, uncharged, or difficult to arrange in their field of view. Meanwhile, while such showings are rare, open-captioned showings of films project the captions along with the rest of the movie for everyone in the theater to see without needing any extra devices.

Ideally, don’t use this article as an excuse to start reaching out people who have prefixed their open subtitles with [CC] or anything like that. I don’t think that’s particularly helpful.

Instead, my hope for this article is to spark more curiosity and understanding for the world of captions, subtitles, and other transcription, as well as for the needs of deaf and hard-of-hearing viewers. If you’re creating videos, please transcribe them! Even in the midst of the generative AI hype cycle, manually curated transcriptions are still the best, most accurate experience, and they are invaluable for folks who need them.

If you’d like to learn more about making the best captions and subtitles for your viewers, here are some of my favorite resources:

• Meryl Evans blogs about accessibility, especially accessibility for deaf and hard-of-hearing people. I’d especially recommend her 10 Rules You Need to Create Great Captioned Videos.
• Rikki Poynter is a deaf YouTuber with a plethora of videos on the deaf experience, as well as a whole playlist on closed captioning advocacy.

Originally posted on my blog, benmyers.dev, as Subtitles, Closed Captions, and Open Captions: What's the Difference?

Bienvenue!

Internationalization and localization efforts have a lot in common with web accessibility. Both are domains of usability with the express goal of ensuring audiences are included by an interface, rather than excluded from it. Both benefit heavily from forethought and careful strategy, rather than attempts to retrofit improvements after the fact. Both are often worked on by people who are building outside of their own lived experiences.

At the intersection of internationalization/localization and web accessibility, we find multilingual web accessibility: ensuring disabled users can use a multilingual site regardless of which supported languages they speak. This entails preserving content clarity and approachability across languages, localizing interfaces to follow language/locale-specific conventions predictably, and ensuring that the site continues to support assistive technologies robustly across languages. At its core, multilingual web accessibility is about making sure that our accessibility efforts and internationalization/localization efforts alike don’t leave out disabled speakers of other languages than our own.

I’ve personally found it really difficult to find practical, useful guidance for multilingual web accessibility specifically — so let’s change that! Here are a few tips for multilingual web accessibility that I’ve picked up so far, largely from my experience as a developer. For these tips, I’m generally assuming you have a fair amount of control over, or input into, your site’s design, markup, styles, and scripts. Content management systems and site builders are their own cans of worms that I don’t have a lot of experience with, so I’ve opted not to cover them in this post. I’m also sure this won’t be a complete list, so please reach out on Mastodon if you think of something I’ve missed!

The lang attribute is used to specify the human language of a given element. It takes an ISO-defined code for the primary language, which can then be followed by additional subtags for specifying region and other possible variations — though to maximize compatibility with clients and assistive technologies, W3C recommends keeping your language tags as broad as possible, only using regional subtags or other variant subtags when they’re absolutely necessary to understand the content.

Declaring content’s language is especially useful for screenreaders and text-to-speech software, which use the lang attribute as a cue to load the right pronunciation rules. lang can improve the braille display experience, too; the JAWS screenreader uses language detection to load users’ language-specific braille profiles, for instance.

There are two main times we need to set the lang attribute: once when establishing the page’s primary language, and then again whenever elements or bits of text are set in some language other than the page’s primary language.

To set a page’s primary language, specify the lang attribute on your <html> element. For instance, this blog has <html lang="en"> to mark it as English. Specifying the correct language this way is incredibly low-hanging fruit and yet, it consistently shows up as a prevalent issue in WebAIM’s yearly report of the million most popular homepages’ accessibility.

One thing to watch out for: some site generators or boilerplate projects will prefill the page language with "en" by default, so if you’re using one of these tools to build your own site in some language other than English, be sure to update that, as leaving an inaccurate lang can have unfortunate consequences. Automatic accessibility scanners are just looking for the existence of a page-level lang attribute, so they’re not likely to flag inaccurate lang values for you.

For those playing WCAG Bingo at home, specifying the page’s primary language with <html lang> is pretty much the technique for meeting Success Criterion 3.1.1: Language of Page, which is a Level A requirement.

If the page contains a word, phrase, section, whatever in some language other than its primary language, then that secondary-language content should be wrapped in an element that has its own lang attribute. The cheerful Bienvenue! heading earlier has lang="fr" to mark it as French, for instance.

<h2 lang="fr">
	Bienvenue!
</h2>

Screenreaders and text-to-speech software that support the appropriate languages should switch between languages fairly seamlessly, adopting the right pronunciations at the right time.

Additionally, supplying the lang attribute is useful even when the screenreader or text-to-speech doesn’t support that language. For instance, if it doesn’t have a particular language installed, JAWS will announce the language name before garbling secondary-language text. This gives JAWS users a kind of troubleshooting step to remedy the situation; if they had wanted to read that secondary-language text as it was, they would need to install the appropriate language. If they opt not to (say, not downloading a language they don’t already understand), then at very least, they have context as to why their screenreader couldn’t announce certain content.

Don’t go overboard with this markup power, however. Well-understood loanwords, for instance, have become part of the primary language, and thus don’t need to be specially marked up. You wouldn’t need to mark up the word rendezvous as French, for example, because the word has already become pretty integrated into English.

Marking up phrases and elements in secondary languages with their own lang attributes is pretty much the way to meet Success Criterion 3.1.2: Language of Parts, which is a WCAG Level AA requirement.

A language’s writing direction has knock-on effects for the page layout as a whole. If you compare left-to-right site layouts with right-to-left site layouts, for instance, they’ll typically be horizontally mirrored inverses of each other. The stuff that was on the top left in one layout will usually be in the top right, and vice versa, when the writing direction is flipped.

This is especially noticeable in alternate language versions of the same site. Take Wikipedia, for example. Where English Wikipedia aligns navigational elements like the site logo and the table of contents to the left side of the page, Arabic aligns those elements to the right. Similarly, the supplemental infobox found on the right side of the English article is instead found on the left side of the Arabic article.

Following the layout conventions of a given language or locale will make your site’s visual hierarchy more familiar and predictable, even if someone’s never seen it before. Beyond being culturally cognizant, having a predictable visual hierarchy brings with it accessibility benefits. For one thing, familiar visual hierarchies reduce cognitive load for users with cognitive disabilities. For another, predictable placement of information and controls can benefit screen magnification users who can’t necessarily see the full layout at once by making it less tedious to find what they’re looking for. These benefits mean the inverse is also true, though: while unfamiliar layouts will be frustrating for anyone, they’ll be especially alienating and difficult for disabled users.

Fortunately, web technologies have gotten way more flexible at handling text direction thanks to CSS's logical properties and values. Logical properties and values let us define margins, padding, borders, text alignment, flex layouts, and more in ways that will automatically adapt to a language’s writing direction. For example, the margin-inline-start property is akin to margin-left in left-to-right languages, margin-right in right-to-left languages like Arabic and Hebrew, and margin-top or margin-bottom in vertical writing modes such as those sometimes used for Chinese, Japanese, Korean, and Mongolian text… all with one tidy CSS rule. Nifty!

Logical CSS isn’t a cure-all for every writing direction-based layout issue, however. There are still some spots where we’ll need an intentional content strategy. One scenario I’ve encountered is hero banners. For instance, if our hero banners involve overlaying some text on top of a splash image, take care that right-aligning the hero’s text doesn’t suddenly place it on top of the busy detail of the splash image, posing color contrast and general illegibility issues. Plan for right-to-left layouts from the get-go, whether by supplying right-to-left specific hero images; ensuring hero images are safe to mirror (i.e. lacking any text, symbols, or logos that would look amiss upon mirroring); or by redesigning the heroes to avoid overlaying altogether.

Responsive, fluid web design is critical to account for the wide spectrum of devices people may be using. From an accessibility perspective, following robust responsive web design techniques ensures that if, for instance, low-vision users need to zoom in or bump up the base font size in their browsers or operating systems to be able to read a webpage, they can do so without the page falling apart.

However, when multiple languages are involved, responsive techniques become even more critical because of the potential for text size expansion. Words and phrases that are short and tidy in the source language might balloon dramatically when the target language…

• …uses longer words in general
• …has wider characters
• …assembles long compound words that provide fewer natural line breaks (looking at you, German)
• …requires that abbreviations be written out in full instead

In one instructive example from the W3C Internationalization Activity, when translating their site into Italian, Flickr translated views, as in the number of times a given image had been seen, as visualizzazioni, going from just five characters in English to 15 in Italian, a 300% increase. And as the W3C Internationalization Activity goes on to note, this is par for the course: English text often doubles or triples in length when translated into Italian and other European languages.

Cramming this kind of text expansion into pixel-perfect layouts designed with anglocentric assumptions in mind is a recipe for disaster. In the Flickr example, we can imagine how, if a view counter had been tucked in the corner of some limited-width container like a card, the string “visualizzazioni” could cause some overflow issues, particularly if the design also tried to cram in other elements inline, too. Navbar items, too, will need to pack longer words and phrases into tight spaces. And bringing this back to accessibility, all of this is especially true if the user also needs to zoom in or bump up their browser’s base font size. Text expansion and the need to zoom/resize all but guarantee users will reach any dreaded overflow issues your layout might have sooner.

One common tactic for attempting to rein in overflow is text truncation. However, truncation poses its own accessibility issues and, to quote Karen McGrane, it’s infamously not a content strategy (⚠️ results may be NSFW). It’s usability’s way of throwing in the towel. We can do better, especially where navigation and pages’ critical functions are concerned.

Instead, tackle these issues at the root:

• Follow responsive web design best practices instead of striving for pixel-perfect layouts
• Avoid capping elements’ dimensions to maximum widths or heights
• Give your UI elements plenty of room to grow should they need to accommodate longer text
• Build layouts that anticipate text wrapping onto new lines
• Ensure design comps reflect the messy asymmetry of the real world from the get-go, rather than only demonstrating cases where content follows symmetrical, neat, tidy, elegant happy paths

Where text expansion in translation can cause problems by exacerbating possible overflow, text shrinking in translation causes problems by making elements too small to use. This is especially troublesome for links and buttons that lean on their text contents’ intrinsic lengths for their own sizing.

To borrow an example from Ahmad Shadeed, imagine we have a confirmation button that says Done in the English version of the site. This same button might read تم in the Arabic version. Yet, the difference in widths between these two buttons is stark:

Even with a little bit of added padding and typographic adjustments, the Arabic version of the button would be pretty fiddly, especially on touch devices. This can make the site harder to use for anyone with motor/mobility disabilities such as Parkinson’s that make hitting precise targets difficult. This is especially problematic in cases of primary action buttons (like submit buttons and confirmation buttons), navigation links, and call-to-action links.

Fortunately, we can use the defensive CSS technique of applying a minimum width. We could set it to something like 44px, to hit the minimum target size recommended by WCAG's Level AAA Success Criterion 2.5.5: Target Size (Enhanced), or we can go even wider if we want to give the control the proper oomph and gravitas of a primary action button or a call to action.

.button {
	min-width: 90px;
}

You can also similarly set a minimum height, especially if you plan to stack interactive controls. Just be sure to only set the minimum height and width this way; don’t cap controls like this to fixed dimensions.

The specifics of what legible typography entails for your design will depend heavily on which languages you support. Where possible, lean on the typographic conventions established for a given language or script. Here are some things to look for:

• Typefaces: Pick a typeface that has been intentionally designed for the particular language. When in doubt, consider leaning on system fonts: familiarity contributes heavily to legibility, and the performance boost won’t go amiss either.
• Font variations: Not all writing systems support capitalization, boldface, italics, or underlining like the Latin alphabet does. Inserting these western typographic conventions into writing systems that don’t traditionally support them can clutter the text, making it muddier and less legible.
• Font size: Writing systems with more intricate/complex characters often benefit from a larger font size.
• Tracking: Fixed-width/monospace writing systems like Chinese, Japanese, and Korean (CJK) characters can benefit from wider tracking (the spacing between characters), though you should first check whether your font has handled that tracking baked in already.
• Line height: Average character height, diacritics, ruby text, and more can all contribute to a line of text feeling crowded. Writing systems with these features usually benefit from larger line heights.
• Line length: Fixed-width/monospace writing systems may need fewer characters per line to stay readable.

For some concrete examples of some of these typographic differences and their requisite adjustments, I highly recommend reading through An Introduction to Writing Systems & Unicode: Typographic Differences by r12a.

Accessibility work often leans on strings of text that aren’t necessarily ever made visible. These include…

• Attributes that expose arbitrary text values, such as alt, aria-label, or title
• Visually-hidden (née “screenreader-only”) help text
• Live region announcements
• <title> and <desc> nodes within SVGs

Unseen as they are, these strings are more prone to getting missed in translation workflows. This means that swaths of the interface will still be rendered in a fallback language that’s unfamiliar to the reader. An aria-label="Close" on a dialog’s close button, for instance, won’t really do someone any good if they don’t speak English. Text meant to improve access instead introduces more barriers. (And if you’re relying on automatic translation as your internationalization strategy, be forewarned that there are many cases where attributes like aria-label won’t auto-translate)

To ensure a multilingual site is accessible across languages, it’s critical that hidden strings are included in whichever translation workflow your site uses, even if they’re hidden or buried inside attributes. Make a practice of never using a hardcoded string for user-facing content.

One gotcha I’ve especially noticed here is with dynamically generated text. While an English-only site might be content to build up strings using concatenation or template literals…

editButton.setAttribute('aria-label', 'Edit ' + title);
// or:
editButton.setAttribute('aria-label', `Edit ${title}`);

…these approaches don’t really carry over well to any sort of multilingual context, even if you translate the strings’ individual components…

editButton.setAttribute('aria-label', translate('edit') + ' ' + title);
// or:
editButton.setAttribute('aria-label', `${translate('edit')} ${title}`);

…because different languages have different word orders. German users, for instance, wouldn’t expect “Bearbeiten [title],” but rather, “[title] bearbeiten.” Instead, make sure that your translation methodology supports placeholders for interpolation, rather than trying to build up the individual bits and bobs of a longer string within the interface. This is just as much of a need for visible labels as it is for hidden text, but in my experience, this is easier to forget (and much harder to catch when it does happen!) for hidden strings.

Make sure every user-facing string gets translated is, for sure, far easier said than done. To that end, there are a few things you could do to reduce your reliance on hidden text that might get missed in localization:

• Where possible, use visible text labels, minimizing the use of hidden text. This will better surface any translation gaps and reduce the chances of discrepancies between the visible and aural user experiences.
• Lean on semantic elements and attributes, including ARIA attributes, to convey UI elements’ roles and states so that assistive technologies can fill in the user’s preferred localizations/translations.

Microcopy is all the little bits of text that appear throughout the site: the nav links, the sidebar headings, the form field labels, stuff like that. When microcopy is written and used consistently, the site layout becomes much more predictable, and users won’t have to guess as much about how the site functionality works, which in turn:

• Reduces the cognitive load of using the site, which especially benefits cognitively disabled users
• Increases confidence in a control’s functionality, even when someone can’t see any or all of the surrounding context
• Helps voice control users build up a mental model of the commands they can use to target their desired elements, without which, they’d need to resort to tedious workarounds

And speaking of voice control, there’s one especially pernicious kind of accessibility bug that can crop up as a result of inconsistent microcopy. Consider a site where a translator opts to translate Delete as Löschen in German. Later, a translator translates the string Delete file as Datei entfernen, opting to use a different verb this time. Generally, professional translators will avoid discrepancies like this, but given a large enough project with enough translators and over a long enough time, inconsistencies can happen.

While both of these may well be viable translations of these strings, a problem arises when, as a result, we localize this button:

<button aria-label="Delete file">
	Delete
</button>

as…

<button aria-label="Datei entfernen">
	Löschen
</button>

(Thanks to Moritz Rebbert for suggesting this particular example!)

Suddenly, the German version of our site has a Success Criterion 2.5.3: Label in Name (Level A) violation that the English version doesn’t. This can confuse sighted screenreader users, as well as make it much harder for voice control users to target this button in their commands. However, neither string alone is the issue. Rather, this issue emerges from trying to use these two strings together. What’s more, this isn’t the kind of issue that can be caught by spot-checking the source language version of the site, and it is exactly the kind of issue that can emerge as a web project grows in complexity.

From the translator side, inconsistent microcopy can be mitigated by adhering to detailed styleguides, regularly checking translation consistency tooling, and periodically reviewing older translations.

Designers and developers can prevent these kinds of Label in Name collisions in the first place by reworking the underlying design and implementation to not be so dependent on aria-label or other hidden text, and instead surfacing context through visible text. While I don’t think we can avoid aria-label entirely, we can pare down the chances something like this can come up.

You can invest a lot of effort into the above few tips, and it can all be dramatically undercut by introducing third-party code that hasn’t been so thorough.

If you use component libraries or other third-party scripts on your site or web application, it’s important to vet those third-party libraries for accessibility. However, if those third-party libraries aren’t also properly considering internationalization and localization, this can throw another wrench in the works. After all, just like your own code, a component library’s aria-label attributes or live region announcements are limitedly helpful to users if they’re all hardcoded in one language. Similarly, a beautiful UI component will stick out like a sore thumb if it doesn’t readily adapt to other writing directions. What’s more, fixing these gaps via issues or code contributions will generally be trickier and slower than it would have been to fix your own code.

Unless a third-party library happens to support all the same languages and locales that you do, with translations that you’re happy with, look for libraries that:

• Support you passing in your own (localized) strings for attributes, announcements, etc.
• Either provide their own styles for writing direction support or are easy enough for you to style yourself

Multilingual web accessibility is, in many ways, a stress test for both your accessibility standing and your internationalization/localization standing. Very few of these tips are truly specifically about the intersection of multilingual web accessibility. Rather, these are more like ways that the complexity of multilingual sites’ needs can exacerbate existing seams in inaccessible designs, and vice versa. An unresponsive layout is an unresponsive layout, for instance — switching to German’s long compound words just surfaces those issues faster. Fortunately, if accessibility and internationalization are both planned for from the get-go, it’s possible to tackle problems of multilingual web accessibility robustly.

I’m constantly in the process of learning new things, especially about accessibility and internationalization, and I’m sure this article is nonexhaustive. If there’s something I’ve missed, let me know on Mastodon!

• All articles from the W3C Internationalization Activity
• Translations of current W3C standards and drafts
• On Language Learning for Screen Reader Users, by Florian Beijers
• What they don’t tell you when you translate your app, by Eric Bailey
• CSS for internationalisation, by Chen Hui Jing
• The Most Comprehensive Guide to Web Typography in Japanese, by Masaharu Hayataki

Originally posted on my blog, benmyers.dev, as Lost in Translation: Tips for Multilingual Web Accessibility

At its heart, all a blogroll needs to be is a static list of links to other blogs. No further complexity is required beyond that point. You could absolutely hardcode such a thing directly in HTML. However, I wanted to try my hand at a more complicated design, featuring each site’s favicon and a link to their latest post.

What follows is how I built the finished product. My site is built with Eleventy, so this approach will definitely be Eleventy-flavored, but I’m sure bits and pieces of this approach could be adapted to any build tool or framework.

Eventually, we’ll be fetching RSS feeds and displaying each blog’s latest posts, but well before that point, we’ll need an approach to ensure those posts stay roughly up to date.

We have a few possible approaches we could take to ensure we’re showing the latest, greatest, up-to-datest posts:

• Do nothing special; let each rebuild update the posts. If you rebuild your site frequently, this will work well enough. If your site rebuilds less frequently, the “latest” posts will remain very stale for a long time.
• Schedule regular rebuilds. The blogroll page is still static and pregenerated, but automatically updating it, say, every day or so will make sure the latest posts never fall too far behind.
• Build the blogroll on each request. For an Eleventy site, this would entail using either Eleventy Serverless or Eleventy Edge to fetch each blog’s RSS feed and build the blogroll page anew whenever a user hits the page.
• Fetch RSS feeds with client-side scripts. This involves pushing a bunch of scripts to users, delays the latest-post information rendering, and will likely introduce the need to handle loading and error states.

In my case, my site was already set up to rebuild daily, something I’d put together in my Some Antics days to auto-update the YouTube thumbnail on the homepage without serving up YouTube’s heavyweight scripts to every user. I use a GitHub Action to schedule my daily Netlify builds; your stack may have a different approach for scheduling regular rebuilds.

The regular-rebuilds technique won’t be truly, immediately up-to-date, but for my needs, it’s up-to-date enough — especially given that this is the most robust and performant experience for the end user, who as far as their browser is concerned, is just pulling a standard-issue, prebuilt HTML file living on a server.

Next up, I opted to store a list of the blogs in Eleventy data. If I were going for a simple list of links to blogs with nothing added, I’d push for just hardcoding the markup directly, but since I planned to use this information to orchestrate fetching further information, I needed the blog list stored in data.

This data is only used on one page, the blogroll page, which means the blog list could sit pretty much anywhere in Eleventy’s data cascade. I opted to set it up as directory data so I could colocate the data with the upcoming template file, but there’s no reason I couldn’t have set it up as global data instead.

I created a src/blogroll/ directory in my project, and in there, I created a JSON file called blogroll.11tydata.json. The fact that the blogroll in the filename matches the directory name establishes this file within Eleventy as a directory data file.

Then I populated that JSON file:

{
	"blogs": [
		{
			"name": "Adrian Roselli",
			"url": "https://adrianroselli.com/",
			"feed": "https://adrianroselli.com/feed"
		},
		{
			"name": "Ashlee M. Boyer",
			"url": "https://ashleemboyer.com/",
			"feed": "https://ashleemboyer.com/rss.xml"
		},
		{
			"name": "Baldur Bjarnason",
			"url": "https://www.baldurbjarnason.com/",
			"feed": "https://www.baldurbjarnason.com/index.xml"
		},
		// ...
	]
}

Now, any template within src/blogroll/ will be able to access this list using the blogs data variable.

The details I’ve provided about each blog here are minimal, only the stuff I’m fine hardcoding. For your blogroll, you might opt to hardcode more details into this list — maybe a short description of each blog?

Now that we have the basic scaffold of information for each blog in our blogroll, we want to fetch each blog’s latest post and surface it within our Eleventy data.

Anytime we want to take some data that already exists (like our raw blog list) and act on it to expose some new data (like latest posts), Eleventy’s computed data feature comes in handy.

Here, I needed two libraries: rss-parser, which does what it says on the tin, and Eleventy Fetch, which handles caching fetched results for us whenever we run the dev server locally.

npm install --save rss-parser @11ty/eleventy-fetch

Then in src/blogroll/, I created a JavaScript directory data file called blogroll.11tydata.js. That data file looked like this:

const {AssetCache} = require('@11ty/eleventy-fetch');
const RssParser = require('rss-parser');

const rssParser = new RssParser({timeout: 5000});

/** Sorter function for an array of feed items with dates */
function sortByDateDescending(feedItemA, feedItemB) {
	const itemADate = new Date(feedItemA.isoDate);
	const itemBDate = new Date(feedItemB.isoDate);
	return itemBDate - itemADate;
}

/** Fetch RSS feed at a given URL and return its latest post (or get it from cache, if possible) */
async function getLatestPost(feedUrl) {
	const asset = new AssetCache(feedUrl);

	// If cache exists, happy day! Use that.
	if (asset.isCacheValid('1d')) {
		const cachedValue = await asset.getCachedValue();
		return cachedValue;
	}

	const rssPost = await rssParser
		.parseURL(feedUrl)
		.catch((err) => {
			console.error(feedUrl, err);
			return null;
		})
		.then((feed) => {
			if (!feed || !feed.items || !feed.items.length) {
				return null;
			}

			const [latest] = [...feed.items].sort(sortByDateDescending);

			if (!latest.title || !latest.link) {
				return null;
			}

			return {title: latest.title, url: latest.link};
		});

	await asset.save(rssPost, 'json');
	return rssPost;
}

module.exports = {
	eleventyComputed: {
		/** Augments blog info with fetched information from the actual blogs */
		async blogData({blogs}) {
			const augmentedBlogInfo = await Promise.all(blogs.map(async (rawBlogInfo) => {
				return {
					...rawBlogInfo,
					latestPost: rawBlogInfo.feed ?
						await getLatestPost(rawBlogInfo.feed) :
						null
				};
			}));
			return augmentedBlogInfo;
		}
	}
};

Whew. There’s a lot here. The long and short of this is that in addition to our scaffoldlike blogs data array, we now also have a blogData data array which looks similar, but wherein each blog object might also have a latestPost property. Additionally, each fetch response is stored in a cache (via Eleventy Fetch’s AssetCache) that persists for one day, which will ensure that our local development server doesn’t fire off spurious requests to each of these feeds every time we make a change to our site, so that our dev server isn’t bogged down and we’re not flooding our favorite blogs with swarms of unnecessary requests.

We’ll add more to our augmented blog data objects shortly, but first, let’s put some contents on an HTML page, just to make sure everything’s working so far.

Next up, I created a template file for the blogroll page. In practice, this template made use of some base layouts I already had, but I’ll omit that setup for the purpose of this blog.

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Blogroll</title>
</head>
<body>
	<main>
		<div class="blogroll-grid">
			{% for blog in blogData %}
			<article class="blogroll-card">
				<p class="blog-title">
					<a href="{{ blog.url }}">
						{{ blog.name }}
					</a>
				</p>
				{% if blog.latestPost and blog.latestPost.title %}
				<p class="latest-post">
					<b>Latest post:</b>
					<a href="{{ blog.latestPost.url }}">
						{{ blog.latestPost.title }}
					</a>
				</p>
				{% endif %}
			</article>
			{% endfor %}
		</div>
	</main>
</body>
</html>

This template iterates through our augmented blogData data array, and outputs an <article> for each entry. Each <article> contains a link to the blog and, if a latest post was found successfully, a link to that post.

If you run your project, you should now see this new template at /blogroll/. Each blog should be listed out alongside its latest post.

At this point, you can begin styling the page, but I had a few more enhancements I wanted to make.

Favicons are a lovely expression of each site’s personality, and showing them would go a long way towards giving each blog entry its own flair.

I explored a few options for getting a site’s favicons, but at the end of the day, the simplest option by far came from URL-based favicon fetching API services, including one from Eleventy project itself: Zach’s IndieWeb Avatar service. Given any site URL, you can get its favicon as a valid <img> src with just a quick transformation:

const encodedBlogUrl = encodeURIComponent(blog.url);
const src = `https://v1.indieweb-avatar.11ty.dev/${encodedBlogUrl}/`;

Easy enough!

This transformation from blog URL to its IndieWeb Avatar service URL could be achieved perfectly fine with Eleventy filters in your templates, but since I already had the computed data infrastructure, I opted to keep adding to it instead:

// … all your imports, getLatestPost, etc.

module.exports = {
	eleventyComputed: {
		/** Augments blog info with fetched information from the actual blogs */
		async blogData({blogs}) {
			const augmentedBlogInfo = await Promise.all(blogs.map(async (rawBlogInfo) => {
				const encodedUri = encodeURIComponent(rawBlogInfo.url);
				const favicon = `https://v1.indieweb-avatar.11ty.dev/${encodedUri}/`;

				return {
					...rawBlogInfo,
					favicon,
					latestPost: rawBlogInfo.feed ?
						await getLatestPost(rawBlogInfo.feed) :
						null
				};
			}));
			return augmentedBlogInfo;
		}
	}
};

Then in our templates:

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Blogroll</title>
</head>
<body>
	<main>
		<div class="blogroll-grid">
			{% for blog in blogData %}
			<article class="blogroll-card">
				<p class="blog-title">
					<img alt="" src="{{ blog.favicon }}" width="16px" height="16px" loading="lazy" decoding="async" />
					<a href="{{ blog.url }}">
						{{ blog.name }}
					</a>
				</p>
				{% if blog.latestPost and blog.latestPost.title %}
				<p class="latest-post">
					<b>Latest post:</b>
					<a href="{{ blog.latestPost.url }}">
						{{ blog.latestPost.title }}
					</a>
				</p>
				{% endif %}
			</article>
			{% endfor %}
		</div>
	</main>
</body>
</html>

Now, our blogroll shows some handy favicons, adding a pop of color and variety to each blog in the list!

It’s worth mentioning that if the IndieWeb Avatar service fails to get the blog’s avatar, it’ll use a fallback image of the Eleventy logo. This may or may not be your speed.

There are a number of other similar avatar services you could use instead, if you like, including those made by Google and DuckDuckGo. These all follow similar URL-based approaches. For more info, I recommend Jim Nielsen’s post on displaying favicons.

For my blogroll design, I wanted to show a cleaned up version of each blog’s URL. I did this with the normalize-url package, which I’d previously used on the Some Antics site to format guests’ personal sites.

We’ll first install normalize-url. In v7 of normalize-url, the package went ESM-only. Since, at time of writing, Eleventy doesn’t yet support ESM, we’ll need to install version 6 or lower. Other frameworks or build tools likely won’t have that stipulation.

npm install --save normalize-url@6

Like the avatar, we could probably set up a filter to handle this transformation for us, but since I already had the computed data approach set up to augment the data for each blog in the list, I just kept using that.

const normalizeUrl = require('normalize-url');

// … all of your other imports, getLatestPost, etc.

module.exports = {
	eleventyComputed: {
		/** Augments blog info with fetched information from the actual blogs */
		async blogData({blogs}) {
			const augmentedBlogInfo = await Promise.all(blogs.map(async (rawBlogInfo) => {
				const encodedUri = encodeURIComponent(rawBlogInfo.url);
				const favicon = `https://v1.indieweb-avatar.11ty.dev/${encodedUri}/`;

				return {
					...rawBlogInfo,
					cleansedUrl: normalizeUrl(
						rawBlogInfo.url,
						{stripProtocol: true}
					),
					favicon,
					latestPost: rawBlogInfo.feed ?
						await getLatestPost(rawBlogInfo.feed) :
						null
				};
			}));
			return augmentedBlogInfo;
		}
	}
};

And then we add this new data to the page in our template:

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<title>Blogroll</title>
</head>
<body>
	<main>
		<div class="blogroll-grid">
			{% for blog in blogData %}
			<article class="blogroll-card">
				<p class="blog-title">
					<img alt="" src="{{ blog.favicon }}" width="16px" height="16px" loading="lazy" decoding="async" />
					<a href="{{ blog.url }}">
						{{ blog.name }}
					</a>
				</p>
				<p class="blog-url">{{ blog.cleansedUrl }}</p>
				{% if blog.latestPost and blog.latestPost.title %}
				<p class="latest-post">
					<b>Latest post:</b>
					<a href="{{ blog.latestPost.url }}">
						{{ blog.latestPost.title }}
					</a>
				</p>
				{% endif %}
			</article>
			{% endfor %}
		</div>
	</main>
</body>
</html>

With that, you have the setup for a blogroll that updates daily for any Eleventy site. If you haven’t already, now’s the time to add your styles.

Other enhancements could absolutely be added to the blogroll — showing the blogs’ latest posts’ dates or their total post counts comes to mind, as does adding brief descriptions of each blog — but I was pretty happy with this state so far.

What does your blogroll look like?

Have you added anything exciting to yours? Let me know on Mastodon!

Originally posted on my blog, benmyers.dev, as Build a Blogroll with Eleventy

This post contains no AI-generated text or images, but does discuss experiments I’ve done in the past with AI art generators. For more info, read my statement on generative AI.

On July 31, 2023, Kipekee the reticulated giraffe was born at Brights Zoo in Tennessee. Kipekee is remarkable in that she has no spots. In fact, she seems to be only the fourth brown spotless giraffe in recorded history; the last known one was born in 1972. White spotless giraffes — who have what’s called leucism — are slightly more common, but still exceedingly rare.

I first learned about Kipekee from Janelle Shane’s AI Weirdness blog, where she asked some image recognition models about pictures of Kipekee. Although the models she chose were fairly highly regarded for their image recognition chops, they struggled to identify and comment on Kipekee’s spotlessness coherently or reproducibly. Kipekee’s spotlessness had thrown them for a loop.

Janelle attributes the image recognition models’ strugglebus to three main factors:

1. AI does best on images it’s seen before. We know AI is good at memorizing stuff; it might even be that some of the images in the examples and benchmarks are in the training datasets these algorithms used. Giraffe With No Spots may be especially difficult not only because the giraffe is unusual, but because it’s new to the internet.
2. AI tends to sand away the unusual. It’s trained to answer with the most likely answer to your question, which is not necessarily the most correct answer.
3. The papers and demonstration sites are showcasing their best work. Whereas I am zeroing in on their worst work, because it’s entertaining and because it’s a cautionary tale about putting too much faith in AI image recognition.

—– Janelle Shane, “AI vs a giraffe with no spots”

That second factor — AI tends to sand away the unusual — struck something of a chord. I wasn’t alone in this. Echoing that sanding factor on Mastodon, J. Rosenbaum, who researches AI's perceptions of gender, added:

Boom. 🎤 Now imagine that you are one of the edges that is sanded away.

—– J. Rosenbaum (@[email protected])

As someone who’s visibly physically disabled, I don’t have to imagine.

My arms are shorter than most, and my left is noticeably shorter than my right. My hands bend inwards at a 90° angle at the wrists, and I have no thumbs. I’ve got craniofacial differences, and a hearing aid implant to boot. Try making that with your character creation sliders, eh? I’m not exactly a stranger to being somewhat less than represented in digital representations of people and bodies.

Back in March, though, I had a thought: how easy would it be to get one of the more commonplace image generation models to generate me — or, at least, the parts of me that I’d never gotten a computer to faithfully reproduce? And so I set out to try and explain my arms and hands to DALL-E and Midjourney. Could other models have done better? I’m sure they could, especially months later, but I was aiming for some of the tools that were most commonplace and discussed, the tools that were in the hands of the masses the most at the time.

The results were, as you’ve probably guessed, disappointing. DALL-E surfaced standard-issue arms and hands. Midjourney showed veiny, muscular arms with hands that seemed painfully clasped together, but still, the anatomy was standard-issue. Thumbs, too, were inescapable. I tried again several times, rewording the prompts and making them more specific, all to no avail. If I was gonna make my arms happen, it certainly wasn’t going to come easily.

It’s easy to point to a technical reason for this experience. Bodies like mine are incredibly uncommon, and the probability that anyone who looks like me found their way into the AIs’ training data is very unlikely, let alone in a well-described, well-classified way. I am the spotless giraffe.

In theory, expanding the inclusion of less normative bodies in the training data would push the needle towards making it easier to create facsimiles of me.

…Except.

Tech is not neutral. It can’t be. It is always the sum total of human decisions, priorities, and tradeoffs, deployed to meet certain ends and desires, and particularly capitalistic interests. AI is far from being an exception to the rule. And in this case, any desire for image generation models to be able to represent me is going to butt heads with another incentive: the desire to avoid shocking users with body horror.

When DALL-E, Midjourney, and other image generation tools entered the scene, they were laughably bad at rendering human limbs. AI-rendered human bodies in general veered heavily into the uncanny valley, and generators produced straight-up body horror pretty often. And as it turns out, having a reputation for inaccurate anatomy and surprise shock value is bad for business!

Successive model retrainings have made rendering humans much more accurate, and tighter restrictions on prompts have made it much harder to generate body horror, even intentionally. As a consequence, non-normative bodies are also incredibly difficult to generate, even when the engine is fed hyperspecific prompts. When I’ve tried, I’ve gotten the sense the generators are pushing back against me. Still thinking about that a few months later, I posted:

One of these days, we’ll reckon with the fact that AI art generators’ anti-body-horror filters also make it downright impossible to generate a person that looks like me.

—– Ben Myers (@[email protected])

It’s not just that the training sets simply don’t have examples of people who look like me. It’s that the system is now explicitly engineered to resist imagining me.

…Hey, is now a good a time to mention that in an effort to create a welcoming and inclusive community for all users, the Midjourney Community Guidelines consider deformed bodies a form of gore, and thus forbidden?

It is something of an amusing curiosity that some AI models were perplexed by a giraffe without spots. But it’s these same tools and paradigms that enshrine normativity of all kinds, sanding away the unusual. As tech continues to charge headfirst into AI hype, this is going to have far-reaching, yet largely invisible to the mainstream, consequences to anyone on the wrong side of that normativity. Better hope you have spots.

Originally posted on my blog, benmyers.dev, as I'm a Spotless Giraffe.

Oh, hey! It’s a “how to write alt text” post. This is something of a rite of passage for accessibility bloggers. That said, I don’t rely on alt text in my day-to-day browsing. As such, this post is drawn less from my own lived experience and more from aggregating advice given by blind and low-vision people sharing their own lived experiences and preferences. To learn more, I’d especially recommend Veronica Lewis’s guides to writing useful alt text for further guidance.

Posting screenshots of code snippets has become something of a staple for programming educators and advocates on social media. Generally, these snippets are meant to serve as an eye-catching way to illustrate some technique being shared in the post. They can be literal screenshots from an editor or, quite commonly, they’re generated with tools such as Carbon.

However, oftentimes, these snippets are shared but their alt text leaves a lot to be desired. Sometimes, it’s missing altogether. Other times, it’s vague and unusable, like “Code snippet.” Either way, blind and low-vision programmers aren’t given the opportunity to meaningfully learn from the snippet.

What’s the best alt text to provide? Should the alt text just be a copy of the full code? As we’ll see, my answer is the classic accessibility mantra: It Depends™.

The goal of alt text is in its name: to provide a viable alternative, in text form, in place of an image. Someone who reads an image’s alt text should generally have the same takeaways as someone who saw the image directly. This is especially critical when the goal of an image is to educate. This means that for screenshots of text, reproducing the text verbatim is often the best alt text.

However, the more text there is to reproduce, the more tedious that wall o’ alt text becomes. Not all screenreaders afford their users the ability to pause an image’s alt text readout or to backtrack a few words. Those that do may also add extra clutter the longer the alt text gets. This makes images with very long alt text a commitment, and screenreader users can end up getting lost in the sauce halfway through, faced with the choice to either keep going, start the alt text all over again, or just nope out and skip the rest. This is why, even though screenreaders have no real character limit for alt text these days, it’s still important to keep your alt text succinct. Accessibility advocates sometimes suggest a max length of around 120 characters or so as a general rule of thumb, but context will impact how many characters you actually need.

This means your approach to writing alt text for those screenshots of code snippets will probably need to change depending on the length and focus of the snippet.

Aug 31, 2023 update

In a previous version of this post, I said that screenreaders in general don’t allow users to pause or traverse alt text. It’s since been brought to my attention that I was mistaken — JAWS and NVDA definitely do allow traversing alt text in all the same ways as regular text, but VoiceOver does not seem to. Thanks to Ramón on Twitter as well as Ryan and Roberto at work for pointing this out!

If your snippet is only a few short lines long (I’d say maybe five lines or fewer, but as always, It Depends™), and focused on a very particular syntax or technique, then I would reproduce the code exactly for the alt text; no more, no less.

For example, say our post demonstrates how one could use place-items: center to center an element’s children:

The snippet:

.centered-children {
	display: grid;
	place-items: center;
}

The alt text:

.centered-children { display: grid; place-items: center; }

Beautiful. Nice and tidy. As a sidenote, centering in CSS is awesome these days.

Medium-length snippets often establish the relevant syntax or technique in some wider context. This context can be useful to see how the technique would be used in the wild, but it also means that our alt text is veering towards being long enough to be considered a tedious commitment.

In these cases, I like to provide a brief preamble that describes what the snippet is and does, before launching into the code verbatim. Usually, this tends to follow this template or something similar:

[Language or framework name] snippet which demonstrates [relevant syntax or technique] to [provided context]

Then I reproduce the code in full.

This preamble gives screenreader users a handy way to make sense of the code that follows. Crucially, it gives them a handy off-ramp to skip the rest of the alt text if they just can’t be bothered.

For example, in a tweet about the <caption> element, I demonstrated <caption> being used inside of a (somewhat truncated) table:

The snippet:

<table>
	<caption>Leaderboard</caption>
	<thead>
		<tr>
			<th scope="col">Rank</th>
			<th scope="col">Contestant</th>
			<th scope="col">Score</th>
		</tr>
	</thead>
	<tbody>
		…
	</tbody>
</table>

It seemed perfectly sensible to me that a screenreader user might want to nope out after finding out that it depicted markup for a <table> with a <caption>, so I frontloaded the alt text with that context.

The alt text:

HTML snippet for a table with a caption that reads “Leaderboard.”

<table>
 <caption>Leaderboard</caption>
 <thead>
  <tr>
   <th scope=“col”>Rank</th>
   <th scope=“col”>Contestant</th>
   <th scope=“col”>Score</th>
  </tr>
 </thead>
 <tbody>
   …
 </tbody>
</table>

Long-form snippets contain a lot of text — often well above that general 120-character rule of thumb. In my experience, they’re less about demonstrating a specific syntax or technique and more about conveying some bigger-picture idea like a framework component or a full stylesheet. Reproducing the code snippet in full would make the alt text a very tedious slog to get through, with a high chance of the reader getting lost or giving up halfway through.

In these cases, I will generally go with a similar description as I would have for the medium-length snippets, without including the full code in the alt text.

For example, in one tweet, I shared a screenshot I’d found of some cursed Java code where the curly braces and semicolons had been indented to the far right side of the editor to make the code resemble Python’s bracelessness and semicolonlessness in an amusingly horrifying way.

public class Permuter																			{
	private static void permute(int n, char[] a)						{
		if (n == 0)																						{
			System.out.println(String.valueOf(a))								;}
		else																									{
			for (int i = 0; i <= n; i++)												{
				permute(n-1, a)																		;
				swap(a, n % 2 == 0 ? i : 0, n)										;}}}
	private static void swap(char[] a, int i, int j)				{
		char saved = a[i]																			;
		a[i] = a[j]																						;
		a[j] = saved																					;}}

In this case, what the code actually did or said didn’t matter all that much. It could have been any Java code, really. It just happened to be a Permuter class. Replicating the code in full wouldn’t have done the humor of the screenshot any justice. Instead, I kept the alt text very surface-level.

The alt text:

A Permuter class written in Java, but the semicolons and opening and closing braces for each line have been aligned to the far right.

This approach works fine if the code snippet is a little jokey or the exact contents don’t really matter. But what do we do if the contents do matter, but they’re just a little long?

At this point, lots of readers will be struggling with the size of the snippet. Overzealous image compression will make the code grainy and hard to read. Eager learners who want to try out the code for themselves will have to transcribe a veritable tome of source code by hand. And, of course, screenreader users will still care what the image has to say.

At this point, the most useful thing the poster can do is include a link to the screenshotted code as raw text — often as a GitHub gist — in the body of the post itself. This approach…

• Allows anyone to copy and paste the code into their own editor to give it a spin
• Enables screenreader and text-to-speech users to navigate through the code at their own pace
• Sidesteps the loss of readability that can come from image compression
• Lets users zoom in to read the code at a more pleasant font size
• Enables folks to use custom user styles and operating system settings such as forced colors mode to have the viewing/reading experience that works best for them

A picture might be worth a thousand words, but there’s a reason why actual raw text is the universal medium.

In cases where I link out to a gist or other text transcription of the code, I like to call it out in the alt text of the image itself, usually by appending something like Full code at the provided link after the aforementioned description of the code’s functionality. For example:

A React ThemeToggle component which uses the useTheme hook to switch between light and dark themes. Full code at the provided link.

If a screenreader user wants to access the full snippet, they have the means to get to it. On the other hand, if they don’t care, the alt text is now minimally intrusive. We’re striking a healthy balance between providng relevant and equivalent information and avoiding needless overwhelm. Nifty.

⚠️ Warning: URLs don't belong in alt text.

Sometimes, well-meaning posters (and some posters who’d rather the URL not count against their post’s character limit) will put the gist URL in the alt text itself. Don’t do this! For one thing, the URL won’t be actionable when it’s read out, so screenreader users won’t be able to navigate to it. It’ll pretty much just be cumbersome gobbledygook. For another, anyone else who wants to benefit from the raw text version of the code won’t be able to get to the link, save for some workarounds involving the social media platform’s bespoke alt text pop-ups.

This isn’t just about code snippets. Sharing screenshots of hefty bodies of text is absurdly common on social media — be it influencers sharing screenshotted apologies, politicians publishing screenshots of their official statements, or people clipping excerpts of news stories. Oftentimes, these screenshots go undescribed, and when alt text is provided, it’s nearly always so vague as to be useless.

Writing alt text that is meaningful and useful remains an artful balance. My hope is that by sharing some of the templates I use, as well as the heuristics and thought processes I run through, someone might get the inspiration they need to describe content they post with a little higher fidelity than “Code snippet.”

Chances are really good I’ve gotten something wrong or didn’t take something into account. If that’s the case, please reach out on Mastodon. I’d love to hear from you.

Originally posted on my blog, benmyers.dev, as How I Write Alt Text for Code Snippets on Social Media

In logic, if versus iff is a very meaningful distinction. To borrow an example from Wikipedia, if Madison will eat a fruit if it’s an apple, then she’ll definitely eat any apples she comes across, but bananas or oranges are still fair game. On the other hand, if Madison will eat a fruit iff (if and only if) it’s an apple, then she’ll still eat any apple she comes across, but bananas and oranges are off the menu. Mistaking an if for an iff here, or vice versa, can mean entirely misinterpreting what a formal logic statement is saying.

While developers might reach for approaches such as ARIA attributes or the ol’ “visible-but-aria-hidden node plus the visually-hidden, screenreader-friendlier alternative node” one–two punch to try to force a particular pronunciation, the conventional accessibility wisdom here is instead to not override screenreader pronunciations at all, for a number of reasons. These override attempts often make braille display output much harder to read, and they can make it much harder to use other assistive technologies such as voice control as well. Crucially, overrides usually come from a place of assuming (and generally vastly underestimating) screenreader users’ familiarity with their screenreader’s pronunciation quirks and their comfort with their screenreader’s verbosity settings and navigation modes.

Is iff a special case? Does the possible confusion with if necessitate markup hacks to try and force a different pronunciation? I don’t know, and I’m genuinely not here to say. I think only user testing can give that judgment call. Instead, I’d like to propose a few steps one could take before using markup hacks to override screenreader pronunciations. If you’re dealing with your own case where you think a pronunciation override might be best, consider whether one of these options could work for you instead.

For logicians who use screenreaders, your iff is probably not the first iff they’ve come across, and it certainly won’t be the last. The same goes for other mathematicians, programmers, and other professions that rely on special symbols to communicate meaning.

In many cases, screenreader users with expertise in these fields have approaches for making sense of these symbols already. This might be inferring meaning from context, retreading the confusing text letter-by-letter, ratcheting up their screenreader’s verbosity settings when they know they’re in a symbol-heavy context, or leaning on custom pronunciation rules they’ve added to their screenreader for such a situation.

It’s also worth evaluating how serious the pronunciation quirk really is. When I worked at USAA, it was an occasional topic of conversation that the JAWS screenreader would pronounce USAA as “oosa.” As much as USAA would have liked to be pronounced correctly for brand reasons (and maybe that can be a reality someday with CSS Speech), internal accessibility subject matter experts, including some who are blind, generally advised against markup hacks, in part because anyone who was hearing “oosa” would figure out what that meant pretty quickly anyways. It was no more harmful than a GPS mispronouncing a street name — you chuckle for a bit, and then you move on with your day.

All this to say, your readers who use screenreaders may very likely already have techniques for dealing with unusual symbols, abbreviations, or pronunciation quirks, or those quirks might not be as critical as you might think at first, and so there might not be anything you have to do at all.

The above might work just fine for someone who already has enough familiarity with a field to know how best to make sense of its text, but what about situations where someone might be coming in fresh such as a college course?

One option might be recommending your readers set up custom pronunciation rules in their own screenreaders. Here’s a few articles and tutorials you could point them to:

• Tutorial for using the JAWS Dictionary Manager
• Adding rules to NVDA's speech dictionaries
• Customizing VoiceOver on macOS
• Customizing VoiceOver pronunciations on your iPhone or iPad

It might be worth setting up a page where you provide guidance on adding custom pronunciation rules to one’s screenreader, along with a list of recommended rules for common confusing phrases you intend to use. From there, you’d just need to make sure that page is somehow discoverable, perhaps linked to from an accessibility statement. This has the advantage of fully empowering the reader to decide if and how to use the rules. Maybe they won’t add any rules at all — or maybe, they’ll decide that iff should be pronounced as “if F,” or “I F F,” or “if and only if.” Instead of you going through the work to hack the markup and slot users into whichever pronunciation you feel is right, you instead give readers the tools they can use to build whichever reading experience is best for them.

For what it’s worth, USAA has one such list of suggested custom pronunciation rules, which includes USAA, as well as abbreviations that are common in banking and insurance.

In some cases, you might be able to reword the text to avoid a contentious, confusing phrase altogether. In the case of iff, you might not be able to avoid it entirely in formal logic statements, but what about the surrounding prose? In many cases, it could be clearer to write out “if and only if” in full. In addition to being more explicit and not relying on pronunciation rules, verbosity settings, or markup hacks to get the point across, it’s also visually more distinct. If someone is scanning a page or reading quickly, iff is pretty easy to mistake for if, and that’s before adding low vision or dyslexia into the mix. In this case, the instinct to reach for a screenreader-specific hack could be a sign that this content is confusing or hard to read for lots of people in general.

Even if you can’t avoid all instances of the confusing text, you can still get some lift from rephrasing that minimizes the need for markup hacks elsewhere. Occasionally including the long form of an abbreviation alongside its short form, for instance, a la “intravenous (IV)” or the other way around, “iff (if and only if),” can be a subtle yet handy reminder to readers that possibly confusing abbreviations are in play, so they should be extra careful when reading the page. This is also a handy tactic for meeting the Web Content Accessibility Guidelines’ Success Criterion 3.1.4 Abbreviations (Level AAA).

Markup hacks meant to force a particular pronunciation in screenreaders often arise from incomplete understandings of how screenreader users navigate the web and unvalidated assumptions about how they would prefer to receive information, and they can shape a user experience at the expense of braille display users, voice control users, and more. Before reaching for a pronunciation hack, consider if it’s really necessary or worth the complexity you’re adding to your site, or if there are ways to rework the content or design to add clarity and avoid needing the hack in the first place.

Additionally, validate assumptions! If you can, get feedback from screenreader users. It may well be that they find leaving those phrases as they are really is confusing and untenable! I personally don’t believe we can avoid screenreader-specific hacks 100% of the time. If (and only if 😜) your user testing shows such hacks are necessary for comprehension, then by all means go ahead!

Originally posted on my blog, benmyers.dev, as The Curious Case of “iff” and Overriding Screenreader Pronunciations

Conventional ways to hide elements include the styles display: none or visibility: hidden, or using HTML's hidden attribute. When you use any of these approaches, the browser assumes no one is meant to access those elements, and it won’t expose that content to assistive technologies. This makes for a bit of a conundrum: what if you want to hide something visually, but still expose it to assistive technologies such as screenreaders? For instance…

• Controls such as skip links that we want to hide by default but reveal on focus for keyboard navigators
• Providing a cleaner or more usable alternative to markup or text that’s visually nice but less friendly to assistive technologies^{[note 2]}

  <span aria-hidden="true">
  	★★★☆☆
  </span>
  
  <span class="visually-hidden">
  	3 out of 5 stars
  </span>

• Nestling screenreader-friendly text inside of icon links or buttons, instead of relying on ARIA approaches which probably won’t auto-translate
• Hiding native form controls to provide custom controls that are still backed by semantic markup

Enter, the .visually-hidden utility class, which usually (foreshadowing!) looks something like:

.visually-hidden:not(:focus):not(:active) {
	border: 0;
	clip: rect(0 0 0 0); 
	clip-path: inset(50%);
	height: 1px;
	margin: -1px;
	overflow: hidden;
	padding: 0;
	position: absolute;
	white-space: nowrap; 
	width: 1px;
}

I’ve borrowed this particular set of rules from Kitty Giraudel’s .sr-only snippet. These rules make the applied element take up zero space, without triggering any of the heuristics browsers use to exclude elements from assistive technology output. To learn more about how these styles work, I recommend checking out James Edwards’s breakdown of .visually-hidden.

This snippet of styles works really well, and has been iterated upon and vetted by accessibility practitioners over the years. However, it would be a big win for the web to have a native HTML or CSS technique, no copypasta required, to visually hide elements while still exposing them to assistive technologies.

Or, at least, it feels that way.

After all, the very reason for these styles is to make an element as hidden as possible without also triggering browsers’ heuristics for hiding elements from assistive technologies. The various rules could each constitute a point of failure if browsers adjust their heuristics, whether through conscious decision or as a bug. If a browser, for instance, stopped exposing content obscured by overflow: hidden to assistive technologies, this ruleset would be toast. Ideally, browsers wouldn’t just break stuff like that — I don’t think there’s a big chance this would happen — but it would be safer not to rely on browser regression so much.

As my friend Evan noted, there’s not just one set of visually-hidden rules out there:

@ben there’s also more than one magical copy-pasta floating around out there, and I’m never entirely sure which one I should use.

—–Evan (@[email protected])

There have been lots of takes on visually hidden styles over the years. Some are homegrown, unvetted, and brittle, such as one I found recently which leaned in large part on color: transparent, which would be ignored in forced colors mode, causing invisible text to become visible again. Other approaches were once commonplace but are now discouraged — namely, an approach which put the contents very far off screen with absolute positioning or a large negative text-indent. This is discouraged nowadays because it caused issues for right-to-left content,^{[note 3]} people using screen magnifiers, sighted screenreader users who benefit from seeing their screenreader’s cursor, and mobile screenreader users who rely on touch.

While today, accessibility practitioners have landed on the clip-paths-and-hidden-overflows approach provided above, there are still iterations and variations on the theme, all attempting to deal with new quirks or contexts faced in the real world. For instance, Kitty Giraudel’s visually-hidden styles are pretty similar to those shared by Scott O’Hara, except that Kitty also removes the element’s border, padding, and margins. These additions make the visually-hidden styles more robust in edge-casier scenarios such as parents with overflow: auto.

Given that we’re still occassionally finding quirks that need to be accounted for, how do we know that the visually-hidden styles that have been sitting in our codebase for a few years (including those provided by third-party libraries and CSS frameworks) are the latest, greatest, up-to-datest iterations? How should accessibility practitioners communicate incremental updates to the webdev community at large?

Given there’s a market for visually hiding content while still exposing it to assistive technologies, the web would benefit greatly from providing a native, spec’d out CSS/HTML technique that doesn’t require copying and pasting a magic snippet. And for my money, the approach I’d most love to see is…

/* Hypothetical */
display: visually-hidden;

…defined as identical to display: none, except that this style doesn’t disqualify the element from being exposed to assistive technologies.^{[note 4]}

In the wild, this would probably lead to style declarations like:

.skip-link:not(:focus):not(:active) {
	display: visually-hidden;
}

And I think using it with Sass or CSS nesting would feel very clean:

.skip-link {
	/* Put your fancy styles for when the link is visible here */

	&:not(:focus):not(:active) {
		display: visually-hidden;
	}
}

Depending on how closely this hypothetical display: visually-hidden matches the behavior of display: none, this would have another leg up on the .visually-hidden styles in that text hidden this way wouldn’t show up in Ctrl+F in-page searches or get added to the clipboard, either of which could be unexpected and unintuitive for sighted users.

And why do I think display: visually-hidden is the way to go?

When I’ve asked about proposals for native visually-hidden on Twitter before, I’ve gotten a myriad of different potential implementations folks would like to see.

Some responses I’ve gotten propose adding some attribute or new attribute value to HTML.

In some cases, people suggested adding a new value to the hidden attribute (maybe something like hidden="visually"?), since hidden is no longer a simple boolean. I think this would be a dangerous route to go down (in my mind, a complete nonstarter), because the failure mode for a browser that doesn’t recognize the new value yet would be to exclude the content from assistive technology output altogether.

Additionally, in the early days of the hidden attribute, many stylesheets added this rule to be able to start using hidden earlier.

[hidden] {
	display: none;
}

This rule is still present on many sites, and in CSS resets and normalizers such as normalize.css. Sites with a rule like this would still prevent visually-hidden content from being exposed to assistive technologies.

This brings us to a larger point about putting this in HTML: even if we were to create some sort of brand new visuallyhidden attribute, browsers’ default styles for HTML elements and attributes are incredibly easy to override. All it takes is a well-meaning developer to write…

[visuallyhidden] {
	display: none;
}

…and the attribute is toast for a site in a way that most developers would totally miss.

Additional concerns I have around putting this in HTML are that:

• It doesn’t really facilitate responding to the viewport or container size without JavaScript (I could see wanting to use media queries or container queries to show/hide the text inside of an icon button at various viewport widths or container sizes, for instance)
• It doesn’t really facilitate responding to states such as hover or focus without JavaScript either (consider the visually-hidden skip link which appears when it receives keyboard focus)
• The notion of something being “visually” hidden is a very presentational, browser-centric idea, and I’m not sure how well these semantics would translate to other user agents

In my mind, if we’re going to have a native approach to visually hiding some element, it’s gotta be in CSS.

I could definitely live with this!

This would require a bit of bikeshedding on the name, because naming is hard, but for the purposes of this article, let’s say it looks something like:

/* Hypothetical */
element-visibility: visually-hidden;

This gives us something that we can use along with all of our media queries, container queries, pseudo-classes, and more!

/* Hypothetical */

.skip-link:not(:focus):not(:active) {
	element-visibility: visually-hidden;
}

@media only screen and (max-width: 600px) {
	button.icon-button > span {
		element-visibility: visually-hidden;
	}
}

This is absolutely a step in the right direction for me!

A weakness of a new property like this, however, is that it’s not entirely clear to me how this would resolve:

element-visibility: visually-hidden;
display: none;

Would the element still be hidden from assistive technologies because of the display: none?

Or what about this?

element-visibility: visually-hidden;
display: block;

Would the element be visually hidden here, or would the display: block unhide it? Could we articulate why that behavior is the way it is?

I’m sure the specs would settle on an order of precedence here, but I’m not sure that precedence could ever be completely intuitive to a developer. In my opinion, that just increases the risk that some content might not get exposed to assistive technologies that’s intended to be.

I think introducing a new property also comes with an education cost. CSS already has display, visibility, content-visibility, and other ways to hide an element, which is already a confusing jumble of similar names and functionality. If we introduce a new property, not only do we have to figure out how it interacts with the other CSS ways to hide something… we also add to the confusing jumble, which I feel would just make this wing of CSS just that much less approachable to newcomers.

If we want to avoid adding a new, similarly named CSS property to the pile and reduce how many other properties this could conflict with,^{[note 5]} then it seems to me that the way to go is to add a new value to a property that already exists. Since in my mind, the ideal functionality is like display: none except without hiding content from assistive technologies, a new display property makes the most sense to me. Hence, display: visually-hidden!

An addition like this would go through the CSS Working Group. Back in 2016, Sara Soueidan filed an issue recommending exactly this, but the conversation seems to have stagnated. If a display: visually-hidden seems appealing to you, give it a thumbs up and consider contributing to the conversation.

If display: visually-hidden ever does go through, I think it’s worth being strategic about how we start to incorporate it into our sites (given that “evergreen” doesn’t mean immediately available). For my money, the simplest and most robust approach would be to add the rule to our already-working .visually-hidden/.sr-only classes:

.visually-hidden:not(:focus):not(:active) {
	/* Hypothetical */
	display: visually-hidden;

	border: 0;
	clip: rect(0 0 0 0); 
	clip-path: inset(50%);
	height: 1px;
	margin: -1px;
	overflow: hidden;
	padding: 0;
	position: absolute;
	white-space: nowrap; 
	width: 1px;
}

…at least until our browser stack has reliably supported this value for some time.

While the .visually-hidden/.sr-only utility styles have proven incredibly useful, the web would absolutely benefit in the long run from enshrining a native approach into the web standards. Such a rule would be easier to teach and easier to incorporate with CSS‘s responsive and stateful features. It’d also discourage unvetted, homegrown approaches from popping up, and it’d ensure that developers wouldn’t need to update their projects’ styles every few years when an improvement is discovered.

March 21, 2023 update: Since publishing this article, a few people have published their responses! I’d especially recommend giving Scott O’Hara’s response a read. It goes into some of the problems that would emerge from enshrining the .visually-hidden technique into the standards, and pitches a few improvements the web could make that would mitigate the need for visually hiding in the first place.

This article is inspired in part by Dave Rupert’s CSS wishlist for 2023. Several other people have put out their own CSS wishlists, and you should give them a read!

• Manuel Matuzović’s wishlist, which includes a call for a native approach to visually hidden styles
• Mayank’s wishlist, which also includes a call for a native approach to visually hidden styles
• Stephanie Eckles’s wishlist
• Eric Meyer’s wishlist
• Ahmad Shadeed’s wishlist

Originally posted on my blog, benmyers.dev, as The Web Needs a Native .visually-hidden

⚠️ Warning: Deprecation Notice

As of October 31, 2023, Web Captioner has been sunset. I’ve left this article up, but unless someone hosts a fork of the original source code, this article won’t work anymore. If you find viable alternatives, please let me know on Mastodon!

Yesterday, I participated in a Twitter Space with JavaScript Jam to chat about accessibility and web standards. Ordinarily when I do this kind of speaking, I try to make sure there are, at minimum, automatic captions for the live event (yes, despite automatic captions’ serious limitations) and polished captions for any recordings afterwards. What I didn’t realize, until Nic Steenhout pointed it out, was that Twitter Spaces no longer provides captions. They used to, but Twitter’s new management has since disabled that, rolling back significant progress.

Ideally, live chats like this will happen on platforms that provide captions out of the box which are built directly into the interface. That will ensure the captions are discoverable, and that the user won’t have to leave the application window to get their captions. If you’re looking to ensure participants can get captions, this is where you should start: by seeking out platforms that explicitly support captions.

If you absolutely can’t get in-app captions to work or move to another platform, then what follows is the last-ditch fallback I ended up going with: using Web Captioner to generate a shareable link to automatic captions that you can pass along to participants in your Twitter Space, Discord voice chat, or other uncaptioned live audio.

Web Captioner is a website that uses Google Chrome’s built-in speech recognition to provide a simple speech-to-text display. Currently, that speech recognition functionality is only in Google Chrome, so Chrome is required for whoever is recording the audio.

Web Captioner seems largely designed for local use cases, such as a classroom setting, where you could show the transcription on a big screen. Web Captioner also has options to integrate with software like Zoom, OBS Studio, or vMix to provide true closed captions. Crucially for this jerry-rigged solution, Web Captioner also provides an experimental feature for creating shareable links to your captions.

The specifics of this step depend a lot on your operating system.

Web Captioner depends on Chrome’s ability to capture audio. As a result, while Web Captioner can pick up your microphone just fine, it won’t be able to transcribe the audio from anyone else on the call out of the box. If you want to transcribe the full call, you’ll need to set up Google Chrome to use the system’s entire audio output as an input.

To do this, you’ll need to install and set up some audio loopback software, since operating systems can get pretty weird about using audio outputs from some applications as inputs in others. Web Captioner themselves have some steps you can walk through for setting up some loopback software:

• Web Captioner’s steps for setting up VB-CABLE if you just want to caption another application’s audio, and aren’t worried about capturing your own microphone. This is useful if you have a second device you want to use just for listening/transcribing.
• Web Captioner’s steps for setting up loopback for other applications and your microphone, using Voicemeeter on Windows and Loopback on macOS. This is the way to go if you’re chatting and transcribing from the same device.

Audio loopback can get really messy, particularly if you also plan to use your own microphone, so where possible, I’d recommend using a two-device setup — one for your microphone, and one for listening — if you can get away with it.

If you already have audio loopback software set up (For instance, I use shinywhitebox’s SWB Audio App for streams, and I know of other people who use BlackHole) to provide device audio output as an audio input source, then you should be able to use that setup just fine.

Once you’ve set up your loopback software to provide device audio output as a new audio input source, we need to get Google Chrome to use that device audio in place of your microphone.

To set this, go to Chrome’s microphone settings at chrome://settings/content/microphone, and find the microphone dropdown. Choose the audio source you created during Step 1. On my Mac, it had “(Virtual)” at the end to make it easier to find. I’m not sure whether Windows would do the same thing.

If your device audio isn’t available from the dropdown, you might need to restart Chrome.

Time for the big moment of truth! Let’s make sure Web Captioner can accurately pick up your device audio now.

Go to Web Captioner, and click either of the bright blue Start Captioning buttons in the header:

This will take you to the mostly blank, black screen of the transcription interface:

Click the yellow Start Captioning button in the footer. In another tab, window, or application, play some audio with some dialogue. I used a YouTube video for this. Hop back to Web Captioner and confirm that Web Captioner is transcribing the audio. If you’re using Web Captioner on the same device you’re chatting from, try speaking into the mic to confirm whether your mic audio is also getting transcribed.

Assuming this worked, it’s all smooth sailing from here! ⛵

Next up, we’ll have Web Captioner generate a link to our live captions that we can share with participants.

You’ll need to be signed in to save settings and to generate the link. First, click the Settings menu icon in the very bottom right corner of the captioner’s interface, and then click Sign in. Follow the steps to authenticate into Web Captioner with an account.

Next, we’re going to enable the experimental Share feature. This experiment is currently hidden away, so to get to it, you’ll need to visit https://webcaptioner.com/captioner/settings/experiments?add=share directly. When you do, you’ll be greeted with a popup like this:

Check each checkbox provided, and then click the Add Experiment button to proceed.

Return to the captioner interface. Next to the Start Captioning button, there should be a new button with an icon that looks like a radio tower. Click it to open up a new popup:

Use these settings to configure your share link as needed. I wasn’t able to get the custom vanity link to work, but that could have just been a temporary issue. When you’re ready, click Get Link.

Before the live event starts, promote the captions link, making it as easy as possible to find. After all, these captions are only as useful as they are discoverable. You should also draw attention to the link during the event itself. I set up a memorable, intuitive redirect (benmyers.dev/captions) so I could mention the captions link on air without having to spell out the randomly-generated string of letters. For the purposes of the Twitter Space, we also pinned a tweet to the top of the Space with a link to the captions.

When the event starts, be sure to click Start Captioning to kick off the transcription.

After the event is done, you’ll want to return to Web Captioner and stop the captions. You should probably do this before you or any other hosts say something you don’t want broadcast to the world 😅

While in the Web Captioner interface, you can export a transcript! This is especially helpful if you plan to upload a recording of the event. To export your transcript, pop open the Settings menu in the bottom right corner of the captioner interface again, and click the button with the floppy disk Save icon:

From there, you’ll be able to export your transcript as both a text file and a Word document:

Using this transcript elsewhere?

If you’re planning to use this transcript alongside an upload of the event, please be sure to clean it up and correct it first. The exported transcript will have plenty of mistranscribed words, as well as weird mixes of prematurely cut off sentences alongside run-on sentences. You’ll also need to clearly indicate who’s speaking, and probably add in any non-dialogue audio cues as well.

Finally, you might want to put your Chrome instance back in its default microphone state, as well as disable any audio loopback software you have runnning, so that your audio experience for day-to-day app usage is back to normal.

If you can use a platform that supports captioning out of the box, please do so. It’ll be far more reliable than running finicky audio loopback software, depending on continued support for a hidden experimental feature inside Web Captioner, and requiring listeners to have a separate window up to follow the conversation. However, if you’ve exhausted other options, a shareable link like this could work in a pinch.

You may also be interested in /u/mossonrok’s Reddit post, where they go into using a similar approach on macOS, with a focus on Discord voice chats.

Originally posted on my blog, benmyers.dev, as Create Shareable Automatic Captions for Live Online Events with Web Captioner

Introduction

This week, Sen. Tammy Duckworth and Rep. John Sarbanes introduced a digital accessibility bill called the Websites and Software Applications Accessibility Act (or the #A11yAct, if you’re on Twitter) to Congress. If passed, it would build on the Americans with Disabilities Act, and lead to clearer regulations for digital accessibility requirements in the US.

• Read the bill (PDF)
• Section-by-section synopsis of the bill (PDF)
• FAQs for the bill (PDF)

I’m not a lawyer or legal expert, but a web developer with a focus on accessibility — so take this with a grain of salt — but here were some of my takeaways having read the bill.

Bottom Line Up Front

Legal stuff can be dry, so here’s what I think are the biggest takeaways from this bill if it gets enacted into law:

• Businesses’ sites and applications need to be accessible, period. Nexus (connection to a physical, brick-and-mortar place of accommodation) won’t be a factor.
• Web and application accessibility regulations would get updated every three years. This will help ensure accessibility law keeps up with technology.
• It’s still probably not a cure-all, but it’s a great start. This bill, if enacted, aims to build on and clarify laws we already have that businesses don’t always follow. That said, it gives disabled users a better position for legal recourse against inaccesssible products.

First of all, is a new law necessary? If so, why?

The Department of Justice has long held that the Americans with Disabilities Act applies to websites and other digital services. They issued an opinion on the matter in 1997, and have since reaffirmed their position several times, most recently in March 2022. And yet… going to court with a web accessibility case can be a mixed bag, as some courts hold that websites are required to be accessible, and some courts don’t. So what gives?

The Americans with Disabilities Act has had three major growing pains when it comes to digital accessibility:

1. A lack of rulemaking. Despite its affirmations that the ADA applies to websites, the Department of Justice still hasn’t published regulations for what standards websites will be held to and how those regulations will be enforced. There have been false starts, but right now, the best we’ve got is an advanced notice of proposed rulemaking for web accessibility regulations as they pertain to state and local government sites, with no clear indication of whether the Department of Justice has any plans to eventually do the same for public accommodations.
2. Tethering to physical locations. Much of the “does the ADA apply to websites?” debate in courts has centered around the question of whether websites count as public accommodations. Courts have differed on that front, but the more connected a website is to a physical, brick-and-mortar accommodation, the more likely the court is to rule the site must also be accessible. This is an idea called nexus, and it covers a lot of businesses, but it doesn’t really help when it comes to digital businesses.
3. Keeping up with the times. The Americans with Disabilities Act was intended to keep up with technology. When deliberating on the ADA, the House Committee on Education and Labor said it “should keep pace with the rapidly changing technology of the times.” That said, even though the ADA has been amended several times, it hasn’t really kept up. The applicability of the ADA to websites hasn’t been clarified in the law itself, let alone its applicability to mobile applications or smart devices.

The proposed Websites and Software Applications Accessibility Act is predominantly focused on those growing pains, ensuring that digital accessibility regulations are finally promulgated and that they’re reviewed on a regular, timely basis. Clear, updated guidance will also hopefully reduce the need for lawsuits in the first place.

With that in mind, let’s take a look at…

I think it makes sense to break the bill down into three parts:

1. How it affirms digital accessibility requirements
2. How it sets itself up to keep up with technology
3. The support structures it sets up

This bill provides the best definition I’ve ever seen for web and application accessibility:

“The term ‘accessible’ or ‘accessibility’, used with respect to a website or application, means a perceivable, operable, understandable, and robust website or application that enables individuals with disabilities to access the same information as, to engage in the same interactions as, to communicate and to be understood as effectively as, and to enjoy the same services as are offered to, other individuals with the same privacy, same independence, and same ease of use as, individuals without disabilities.”

There’s several things I love about this definition. For one, it’s pretty complete — I can definitely see myself using this definition in future accessibility presentations. For another, the reference to “perceivable, operable, understandable, and robust” means that the bill authors are borrowing language from the Web Content Accessibility Guidelines, the industry standard for web accessibility requirements. Thirdly, it’s reassuring that the definition of accessibility provided here calls out that sites and apps shouldn’t require disabled users to compromise on privacy or independence for access.

The new rules themselves… read pretty much how I’d expect!

• Employment entities (employers and labor organizations) can’t discriminate against applicants or employees via inaccessible sites or applications. This builds on Title I of the Americans with Disabilities Act.
• Public entities (that’s your state and local governments) can’t discriminate against disabled individuals or bar them from access to information, services, or programs via inaccessible sites or applications. This builds on Title II of the Americans with Disabilities Act.
• Public accommodations (those are your businesses/private entities) can’t bar disabled individuals from the full and equal enjoyment of goods and services via inaccessible sites or applications. This builds on Title III of the Americans with Disabilities Act.
• Testing entities (organizations that provide certifications or credentials) are grouped with public accommodations in this bill, and also can’t bar disabled individuals from goods and services via inaccessible sites or applications. I’m not sure why they get specific mention, but fair shout, I guess!
• Commercial providers (vendors who provide websites or applications for any of the above entities) can’t provide their clients with inaccessible websites or applications.

In a move to tackle the debate over whether public accommodations’ websites need a nexus to a physical, brick-and-mortar location, the bill clarifies that these requirements apply “regardless of whether the public accommodation or testing entity owns, operates, or utilizes a physical location for covered use.” In other words, if you’re a private entity and your website or application is part of how you offer goods and services, it must be accessible, regardless of whether you have a brick-and-mortar location. This is a huge move, since it’d tackle the biggest debate and source of confusion in current web accessibility litigation.

As with the Americans with Disabilities Act, these requirements have stipulations for if the effort to make the website or application accessible would pose an undue burden or would fundamentally alter the nature of the goods or services.

After a law is enacted, federal agencies put out regulations that describe how those laws will be implemented and enforced. One of the bigger conundrums around web accessibility litigation has been that the Department of Justice hasn’t put out any regulations for enforcing web accessibility according to the Americans with Disabilities Act, despite affirming several times since 1997 that the ADA applies to websites. This bill aims to address this lack of regulations around web accessibility, and also ensure that any digital accessibility regulations that come from this stay up to date with the pace of technology.

Once enacted into law, this act would set the following deadlines:

• Within a year of being enacted: The Attorney General must issue (on behalf of the Department of Justice) a notice of proposed rulemaking for accessibility regulations for public entities, public accommodations, and commercial providers. The Equal Employment Opportunity Commission (EEOC) must issue a notice of proposed rulemaking for accessibility regulations for employment entities.
• Within two years of being enacted: The Attorney General and the Equal Employment Opportunity Commission must issue their actual regulations.

From there, it’s a matter of keeping the regulations updated as technology advances. The bill sets up a process for periodically reviewing the state of accessibility litigation and a cadence for actually updating the regulations:

• Periodic reviews: For the first three years of the act and then every other year after that, the Attorney General and the Equal Employment Opportunity Commission will prepare a report on the state of enforcement and civil actions under the act, and will present said report to several Congressional committees.
• Updating regulations: Every three years after their initial regulations, the Attorney General and the Equal Employment Opportunity Commission will publish updated regulations.

This cadence for updating regulations is huge. It would allow federal agencies to include, for instance, the current version of the Web Content Accessibility Guidelines in their regulations, and then update to new WCAG versions in a relatively timely manner. From what I understand, three years is pretty fast as far as the law is concerned.

The bill, if enacted, would set up two organizations to serve as support structures.

The first would be a standing advisory committee on web and application accessibility. Excitingly, this committee would be required to be majority disabled individuals — living up to Nothing About Us Without Us. It must also contain other accessibility experts, and it may contain representatives from state/local governments, businesses, commercial providers, and other organizations the Attorney General and EEOC deem relevant. This committee would advise the Attorney General and EEOC on the implications of innovations in technology and accessibility.

The act would also require the Attorney General to fund a “technical assistance center,” which would collaborate with disability advocacy groups and with organizations such as the World Wide Web Consortium (W3C) to provide resources for organizations looking to make their sites and applications more accessible, as well as resources for disabled individuals looking to navigate sites and applications.

Additionally, it charges the National Council on Disability to do a study, due within five years of the act being enacted, on the effects of new, innovative technologies on disabled individuals, especially disabled individuals who are also impacted by other axes of marginalization.

I’m really, really excited for this bill, and I hope it gets enacted. It clears up a lot of turmoil in web accessibility litigation — namely the question of nexus — and it looks like a fairly promising way to ensure accessibility law doesn’t leave disabled individuals behind as technology advances. These are things that courts have tried to accomplish with the Americans with Disabilities Act, but this bill would make these expectations more explicit. This comes at a time where web accessibility court cases are still on the rise, and while we’re three years into a pandemic that has forced large parts of our lives online.

That said… an act like this wouldn’t be a cure-all, and that’s important to keep in mind. Taking a company to court is expensive and time-consuming, and it’s not a viable option for most people — especially when you consider the scale of digital experiences we encounter on a regular basis. The Department of Justice and many courts alongside it have held for a long time that the laws we already have apply to the web and digital experiences, and companies nonetheless resist that. It just might be that the best we can hope for out of this is that clear and effective regulations reduce the number of lawsuits necessary.

Even so, I think this act would be a positive step forward for the web, and at very least, it’s something for anyone invested in digital accessibility to keep an eye on.

Originally posted on my blog, benmyers.dev, as A First Look at the Websites and Software Applications Accessibility Act Bill

Introduction

In web development, we frequently need to style elements to visually indicate some state they’re in. We give form fields red outlines to indicate invalid values. We show disabled or inactive elements in gray. We use any number of colors, icons, borders, and more to indicate what kind of state an element is in. Behind the hood, those visual styles are often handled by toggling CSS classes.

And yet: screenreaders, for instance, don’t expose colors or borders or underlines or most of our other visual styles.^{[note 1]} They have no idea what our .is-invalid or .selected classes mean. This can pose an accessibility gap, since we have a discrepancy between visually-conveyed information and information conveyed via assistive technologies. If a state is important enough to indicate visually, it’s probably important enough to expose to assistive technologies.

Let’s take current page indicators for nav links, for instance. It’s a common practice to style the current page’s link in a navbar, maybe coloring it differently or giving it a different border. This usually accomplishes two things:^{[note 2]}

• It orients the user as to where they are in the site’s architecture (which is especially useful if they’ve come directly to that page from some external source like Google)
• It indicates that they probably don’t need to click that particular link lest they reload the page.

Often, you might end up with markup like this:

<nav>
	<a href="/about" class="current-page">About</a>
	<a href="/talks">Talks</a>
	<a href="/projects">Projects</a>
	<a href="/contact">Contact Me</a>
</nav>

There’s a problem here: that current page status would be super useful to screenreader users — after all, if a screenreader user reloads the current page, they might be flooded with announcements as the screenreader begins reading the page anew — and yet, screenreaders have no clue that this extra context exists.

We could address this with an ARIA state attribute — specifically, setting aria-current="page" on the link.^{[note 3]} When aria-current="page" is provided on a link, the screenreader will announce something like link, About, current page. The exact announcement may differ depending on which screenreader is used. Now, our markup looks like this:

<nav>
	<a href="/about" aria-current="page" class="current-page">About</a>
	<a href="/talks">Talks</a>
	<a href="/projects">Projects</a>
	<a href="/contact">Contact Me</a>
</nav>

We’ve introduced a new problem, though. Now we have to keep track of two things: the class and the ARIA attribute. In theory, everything should be fine, so long as we always remember to keep these two in sync. But what if they diverge, and we end up with a link that has the .current-page class but not aria-current="page"? It happens — sighted developers are much more likely to remember the visual indication and less so the semantic indication. Or, admittedly less likely, we remember to add aria-current="page" but we accidentally omit our .current-page class? We forget things. Bugs happen.

We can reduce the duplication and the risk of bugs, making impossible states impossible, by instead using the ARIA attribute as our selector:

a[aria-current="page"] {
	border-bottom: 7px solid yellow;	
}

Now, to get the desired visual indication, we have to provide the necessary semantics for assistive technology. We can’t get one without the other. I call this styling with stateful, semantic selectors. In my experience, it makes my code much more robust and ensures I don’t accidentally omit necessary accessible semantics.

There are many ways you can style with stateful, semantic selectors, but I’d like to show you a few more examples I love:

In this pattern, you have a button which, when clicked, will show or hide some content. Frequently, this button will have some visual indication of whether that content is currently being shown or not — often, it’ll have a caret that’s in one orientation when the content is expanded, and it’s rotated when the content is collapsed.

As before, we could toggle that caret state with a CSS class — let’s call it .is-expanded.

<button class="is-expanded">
	Additional Details
</button>

button::before {
	/* Text for demo's sake */
	/* This should be an SVG */
	content: '❯';
	display: inline-block;
	transition: transform 0.2s;
}

button.is-expanded::before {
	transform: rotate(90deg);
}

⚠️ Warning: Avoid using text contents in pseudo-elements like this.

I’ve used Unicode characters as pseudo-element text contents in these examples as quick, easy-to-understand demos. However, given that, among other reasons, screenreaders can announce pseudo-element text contents, you should probably use an SVG for your pseudo-elements or some similar technique instead.

If you were to try to use the above button with a screenreader, you’d have an issue. When you press the button, the caret will rotate, but your screenreader will remain silent. It has no context that the button has hidden or revealed some content, so it says nothing. As a screenreader user, you’re left without any feedback, and you may start to wonder whether you even clicked the button at all.

Fortunately, there’s an ARIA state attribute for this exact purpose, called aria-expanded! When a screenreader navigates to a button with aria-expanded="false", it’ll announce the button along with something like collapsed, such as button, Additional Details, collapsed. This tells screenreader users that the button controls toggling some content, and that content is currently hidden. When the attribute is toggled to aria-expanded="true", the screenreader announcement will update to include expanded (or something to that effect), and say something like button, Additional Details, expanded.

Our code might update to something like:

<button class="is-expanded" aria-expanded="true">
	Additional Details
</button>

button::before {
	/* Text for demo's sake */
	/* This should be an SVG */
	content: '❯';
	display: inline-block;
	transition: transform 0.2s;
}

button.is-expanded::before {
	transform: rotate(90deg);
}

Upon every click of the button, a script toggles the .is-expanded class and flips aria-expanded between "true" and "false". However… we’re once again doing two things where we could be doing just one thing, and we’re risking impossible states if aria-expanded and the .is-expanded class fall out of sync with each other.

Instead, let’s use aria-expanded as the source of truth for our styles:

<button aria-expanded="false">
	Additional Details
</button>

button::before {
	/* Text for demo's sake */
	/* This should be an SVG */
	content: '❯';
	display: inline-block;
	transition: transform 0.2s;
}

button[aria-expanded="true"]::before {
	transform: rotate(90deg);
}

Say you’ve got a sortable table, and you’d like to indicate which column the table is sorted by, and in which direction. No sweat — this time, we can use the aria-sort attribute.

The aria-sort attribute should be applied to at most one column header at a time. For most sortable tables (sor-tables?), you’ll want to apply aria-sort="ascending" to the sorted column’s table header when the column is sorted in ascending order, apply aria-sort="descending" to the sorted column’s table header when the column is sorted in descending order, and remove aria-sort from the table header altogether when the sort is cleared. When a screenreader user navigates to a table where a column header has aria-sort="ascending" or aria-sort="descending", their screenreader will tell them the name of the sorted column and its direction.

Assuming you have buttons inside each of the table headers to let the user sort, your markup might look something like this:

<table>
	<thead>
		<tr>
			<th scope="col" aria-sort="ascending">
				<button aria-describedby="sort-description">
					Title
				</button>
			</th>
			<th scope="col">
				<button aria-describedby="sort-description">
					Author
				</button>
			</th>
			<th scope="col">
				<button aria-describedby="sort-description">
					ISBN-13
				</button>
			</th>
		</tr>
	</thead>
	<tbody>
		…
	</tbody>
</table>

<p id="sort-description" hidden>Sort by column</p>

If we wanted to add some arrows inside the sorted column’s header’s button to indicate the current sort direction, the [aria-sort] attribute selector will see us through:

th[aria-sort="ascending"] button::after {
	/* Text for demo's sake */
	/* This should be an SVG */
	content: '↑';
}

th[aria-sort="descending"] button::after {
	/* Text for demo's sake */
	/* This should be an SVG */
	content: '↓';
}

(Simplified for the sake of demonstration. Check out Adrian Roselli’s sortable tables article for a much more thorough and robust approach)

These examples aren’t the only times stateful, semantic selectors could prove helpful. Here are just a few more I didn’t get into:

• The :disabled pseudo-class and the [disabled] attribute selector (or [aria-disabled], if you prefer) make great stateful, semantic selectors for disabled fields
• Depending on your markup, the :invalid pseudo-class or aria-invalid could be used to style form fields with invalid values
• aria-selected is a great style hook for the active tab in an ARIA tabs widget
• Heck, [role="tab"] could be a good style hook for ARIA tabs in general

In short, building with accessible semantics from the get-go can give you expressive, meaningful style hooks for free. Leaning on those style hooks in your CSS selectors lets you reduce the number of moving parts in your site or application, and it can prevent accessibility bugs from creeping in down the road.

As with any web development recommendation, use your best judgment. If you find yourself contorting an element’s semantics or markup to get the appearance you want, it’s a sign to take a step back and revisit. Maybe classes are your friend, or maybe you need to revisit your design and determine whether it still makes sense.

I’m definitely not the first to write about this approach. Here are a few other articles on the subject I’d recommend reading:

• User Facing State by Scott O’Hara on CSS Tricks
• Using CSS to Enforce Accessibility by Adrian Roselli
• Represent State with HTML Attributes, Not Class Names by Aleksandr Hovhannisyan

Originally posted on my blog, benmyers.dev, as Style with Stateful, Semantic Selectors

Last night, I was on a kick. I wasn’t happy with this site’s web performance. Lighthouse scans were scoring my homepage 48 out of a possible 100 points on performance. The Website Carbon Calculator was reporting that each load of my homepage emitted 7.8 grams of carbon dioxide, making it dirtier than 97% of the pages they had tested before. These scores seemed really, really surprising to me, especially given that this site doesn’t use any clientside frameworks, and is instead wholly pregenerated static assets built with Eleventy — it shouldn’t be that heavy or slow. There had to be some things I could do to improve the site’s performance.

The first piece of performance I chose to tackle was web font performance, since I hadn’t had any experience with it yet. Specifically, I figured I could improve the performance around my brand font Nexa, which I’m self-hosting.

To start, I looked for each variant of Nexa that was present on my site, as well as how much they weighed. Here’s what I found:

Each variant cost about 60 kilobytes. The browser was only downloading the variants present on a given page, but that usually meant only one or maybe two variants would be culled on a page load.

I found that one variant, Nexa 400 Regular, was only used for one thing: the date-posted stamps on each article. I opted to replace that with the Nexa 300 Regular, which was a quick 60 kilobytes saved.

To really cut down on font bundle sizes, I turned to subsetting, or removing unused glyphs from the font files themselves to serve only the glyphs you need. This is especially helpful to cut out alphabets of languages you aren’t writing in, as well as a bunch of other Unicode characters for things like arrows or mathematical symbols. Markos Konstantopoulos’s article on creating font subsets was hugely helpful here, and it guided me through using Zach Leatherman’s glyphhanger project to identify the character ranges I needed to include in my subsets, and through using pyftsubset to create subsets of my font files.

I chose a bare minimum subset (pretty much just the ASCII range) for the light Nexa 300 Regular and Italic subsets, since those variants are used in very particular pieces of the page. I chose more lenient subsets for the 700 and above variants, since those are used in headings, link text, and more. I could eke much more performance savings with more aggressive ranges there. As it stands, here are the current sizes with the subsets I’ve gone with:

All in all, this means the total size of Nexa downloads is now about 44% the size of the original, which I’m pretty happy with.

However, playing with font bundles alone didn’t seem to move the needle all that much for Lighthouse. It was a good learning experience, but more drastic improvements needed to be made.

When run against my homepage, the Lighthouse scans were pointing towards one major culprit: the YouTube playlist embed for my Some Antics streams. Lighthouse warned me that this embed alone seemed to be bringing my Time to Interactive up quite a bit, as well as messing with my contentful paint metrics.

I decided to check out Paul Irish’s lite-youtube-embed project. This project introduces a <lite-youtube> web component which renders an embed that looks an awful lot like the YouTube player, but “approximately 224× faster” by cutting out a lot of unnecessary and invasive scripts.

There was one hiccup: I had been using YouTube’s playlist embed, so that I was always highlighting the latest Some Antics stream. However, lite-youtube-embed doesn’t currently support playlists. I had to do some finagling with Eleventy global data (code below if you’re interested!) to get the latest stream’s video, and set up a GitHub Action to rebuild my site daily to regularly update the latest stream. This meant I was making a bit of a tradeoff between performance and immediately showing the latest stream. Since I only update the latest stream at most once per week, though, this was worth it to me.

const ytfps = require('ytfps');

module.exports = async function() {
	// Supply your playlist ID to ytfps
	const {videos} = await ytfps('PLZluKlEc91YzYor_ItAax4d2iXTXbFAFF');
	const [latest] = videos;
	return latest;
}

<lite-youtube videoid="{{ latestSomeAntics.id }}" playlabel="Play {{ latestSomeAntics.title }}"></lite-youtube>

This move away from YouTube’s proprietary embeds ended up being a huge lift for my performance, bringing my homepage’s Lighthouse performance score from a poor 48 up to a respectable 81 out of 100. I’d heard just how devastating third-party scripts and trackers can be for a site’s performance, and this change really hammered that home for me.

But there was more to do before I really felt comfortable with the score…

As it stands, my homepage has a lot of images, and none of them were particularly tiny. In one particularly embarassing case, I was serving a raw image hotlinked from Pexels that on its own cost an astounding 10.7 megabytes (oops… 😅). With time, maybe I’ll find a way to highlight my blogposts that doesn’t involve me needing to list out everything I’ve ever written on one page, cover images and all. In the meantimes, however, I wanted to tackle getting those cover images to an acceptable size.

I have been using the Cloudinary image CDN to host some of my images. As an image CDN, it’s able to serve up images in whichever format is optimal for the user’s device and browser, meaning it can serve up more performant image types in browsers that support them. Additionally, its URL transformations API enables you to apply transformations and adjust how the image renders by changing the image’s URL itself.

I opted for two URL-based transformations for the card cover images:

1. Specify f_auto to allow Cloudinary to choose the optimal image format for the user’s browser.
2. Specify q_20 to set the image’s quality level at 20 out of a possible 100. This does degrade the image quality, but from what I could tell, when applied to my own cover images as they appear in the cards, the effect wasn’t noticeable unless you were looking for it.

I wrote an Eleventy filter to insert those URL parameters for any cover image sources that pointed to Cloudinary (code below!), and migrated any cover images that weren’t already in Cloudinary into my Cloudinary media library.

module.exports = function (eleventyConfig) {
	eleventyConfig.addFilter('applyCloudinaryTransformations', (url) => {
		if (url && url.includes('res.cloudinary.com')) {
			return url.replace(
				'/image/upload/',
				'/image/upload/f_auto/q_20/'
			);
		} else {
			return url;
		}
	});
};

Just like refactoring the YouTube playlist embed, this change proved fruitful. My Lighthouse score on the homepage went from 81 to 97 (and even 100 in some tests!).

Looking at the images now in my Network tab, I’m being served WebP images on Chrome, and these are the differences in sizes between a handful of images from before and after. With the delightful exception of the Pexels outlier, most images came to about 16% of the size they originally were, with acceptable image degradation.

After applying these optimizations, the site is in a much healthier place. Depending on the environment and the particular page, I’m scoring 97 to 100 on my Lighthouse performance scores, and Lighthouse is starting to frame its recommendations as helpful suggestions rather than critical issues.

My carbon footprint is doing much better, too! Where previously, loading the homepage produced about 7.8 grams of carbon dioxide, faring worse than 97% of sites measured by the Website Carbon Calculator, the new results look much more promising! Now, homepage loads only produce about 0.18 grams, and the Website Carbon Calculator says it’s doing better than 83% of the sites it’s tested. Check out the latest Website Carbon Calculator results for yourself!

Originally posted on my blog, benmyers.dev, as How I Doubled My Lighthouse Performance Score in One Night

What if the web got better over six weeks?

The WebAIM Million report for 2022 identifies the six most common accessibility defects WebAIM found on the million most popular homepages:

1. Low-contrast text (you are here!)
2. Missing alternative text for images
3. Empty links
4. Missing form input labels
5. Empty buttons
6. Missing document language

In his blogpost What if… one day everything got better?, Dave Rupert proposes tackling spending some time tackling each of these issues, one per week, over the next six weeks until Global Accessibility Awareness Day. Once those six weeks are done, you’ll have cleared away some of the web’s most prominent barriers to access on your own sites.

I promised Dave he had my sword, and so this is Part 1 of six resources geared towards helping you make sense of the most common accessibility defects and what you can do about them.

The Web Content Accessibility Guidelines’ first principle of accessible content is that content must be perceivable. After all, you can’t access information or functionality if you can’t make out that it’s there! The most surefire way, it seems, to ensure users can’t make out your content is to set it in a color that doesn’t stand out from its background — in other words, to have a low color contrast.

People can struggle with low contrast for a variety of reasons — maybe there’s a glare from the sun reflecting off of their screen — but low-contrast text has an outsized impact on visually disabled users such as those with low vision or who are colorblind. On top of that, low-contrast text is everywhere. The WebAIM Million report for 2022 found that nearly 84% of the 1 million most popular homepages had at least one low-contrast violation, with an average of 31.6 distinct instances of low-contrast text per homepage. A 2021 report from Deque Systems (PDF) found that low-contrast text made up 30% of automatically detectable accessibility defects, making it the most common accessibility defect by far.

Remediating low-contrast text could go a long way towards making the web more usable. Let’s dive into how we can measure contrast, remediate low contrast easily, and build sufficient contrast into our sites going forward.

The easiest way to get started is with a color contrast checker. Tools such as the WebAIM Contrast Checker will take a pair of colors you give it and spit out a contrast ratio. Meanwhile, if you’ve already deployed your site and colors live for the world, you can use full-page accessibility scanning tools such as the axe DevTools extension, and they’ll perform color contrast operations for every bit of text and background on your page and identify specific elements on your page with insufficient contrast. Either way, you’ll get a color contrast ratio as a result.

These ratios take the format <some number>:1, ranging from 1:1 (no contrast — you’ve compared a color to itself) to 21:1 (maximum contrast, only obtainable by comparing black and white). The higher the first number is, the more contrast there is between the two colors.

This ratio isn’t really a score of how different the two colors are, per se, but rather a score of how discernible one color would be on top of the other. For instance, as someone who is not colorblind, the CSS colors tomato (#ff6347) and cornflowerblue (#6495ed) strike me as very different colors:

However, tomato and cornflowerblue have a very poor color contrast ratio together: only about 1.009:1. That’s barely better than comparing any color to itself! If we stack those colors on top of each other (apologies in advance!), we can see that this pair of colors is difficult, if not outright painful, to read together:

The current color contrast algorithms we use to get these ratios aren’t trying to give us the pure, mathematical difference between two colors, but rather describe a more subjective difference between the two colors based on human perception. Namely, the algorithms compare the two colors’ relative luminance — which essentially boils down to whether one color is lighter or brighter than the other. Here, tomato and cornflowerblue are pretty much equally bright, which is why they’re difficult to read together.

Now that we’ve got a sense of how we’re measuring the contrast between two colors, how do we know when the contrast is sufficient?

In Success Criterion 1.4.3 of the Web Content Accessibility Guidelines, the World Wide Web Consortium sets forth two key benchmarks you’ll need to remember:^{[note 1]}

• Most text needs a ratio of at least 4.5:1 against its background.

• The rules for larger text are a little more lax — large text only needs to meet a ratio of 3:1 against its background.

So you’ve measured your text and determined that it doesn’t meet color contrast requirements. What can you do about this without overhauling your design?

Typically, I approach color contrast remediation one of two different ways on a case by case basis:

1. Picking lighter and darker colors
2. Embiggening the text

Your main approach to remediating color contrast issues will be changing the underlying colors themselves.

Typically, however, you’ll find yourself limited in what you can do if you approach this by changing the colors’ hues. For one thing, brands usually have fairly strict color palettes, and changing hues will often create colors that can’t be found in the brand’s design systems. For another, as the tomato-and-cornflowerblue example from earlier showed, the colors’ hues often have a very minimal impact on the ratio between those two colors, especially if those colors have very similar brightnesses.

Instead, I tend to find that making one color lighter and/or the other color darker has a more profound impact on the contrast, all while feeling more consistent with the rest of the site’s design sensibilities.

Larger, thicker text tends to be far easier to read, even against low-contrast backgrounds, than smaller, thinner text. For instance, in the following example, both lines of text are the same color, but if you can discern the text at all, it’ll be easier to make out the top line of text, which is bigger and bolder:

This difference is why WCAG is a little more lenient for large text, which it defines as text that is at least 18pt or, alternatively, bold and at least 14pt. Remember that pt is a font size unit that’s defined by the user’s browser (much like rem) — in most browsers’ default settings, this means that the threshold is approximately 24px or both bold and about 19px. Text that meets this sizing criterion only needs to have a ratio of 3:1 against its background, according to WCAG.

In some cases, you can use this more lenient threshold to your advantage, as instead of needing to pick different colors, you might be able to bump up your font size or weight. If you’re purely using this approach to meet your minimum thresholds, this fix tends to be highly contextual and will likely only apply to things like headings. However, accessibility isn’t just about meeting thresholds. WCAG is the minimum bar to clear, but once you’ve cleared those minimum thresholds, you can use tactics like upping the font size, increasing the font weight, or picking a thicker typeface to provide a more readable experience, even though they won’t improve your contrast ratio score.

These approaches work fine for adding one-off colors to a page or for remediating low-contrast text surfaced by an audit, but it’s not very sustainable for large sites or organizations.

Many organizations are turning towards design systems to communicate their UI and UX practices, including their color palettes, as well as their institutional knowledge about when and how each color in said palettes should be used. These design systems are an excellent place to encode knowledge about acceptable color pairings. For instance, a design system might determine acceptable background colors and text colors for buttons, and these colors might have been chosen based on acceptable contrast ratios. Designers and developers can leverage these decisions without even really needing the full background context of how those colors were chosen — there’s a wide and easy pit of success.

I’ve also heard of design systems that get even more explicit in how they communicate accessible color pairings. One trick I learned from Mike Aparicio comes in how he names shades of a design system’s colorway. In his design systems, every shade of a color is given a number from 100 to 900, where 100 is the lightest shade, 600 is the “base” shade, 900 is the darkest shade, and the other colors are filled out in between as needed. His color scales are calculated such that the “200” and lighter colors are always light enough to contrast against the “600” base shade. This rule is easy enough for designers and developers to remember, ensuring they’re far more likely to pick acceptable pairings. You can hear him talk about this approach on Frontend Horse and on my own show Some Antics.

The current contrast ratio systems are pretty thoroughly vetted, but there are a few limitations, such as:

• Current algorithms don’t account for which color is the foreground and which is the background, even though in some color pairs such as brown and pink, one color is definitely more suitable as the foreground and not the background.
• Some typefaces’ bold fonts aren’t very bold, meaning you can meet the letter of the large text requirement without meeting the spirit of it.

A future version of the Web Content Accessibility Guidelines may use a different color contrast algorithm that uses more factors such as these, but it still requires more vetting. If you run into some of these limitations in your design and you feel like your design is just technically conformant, I encourage you to do some user testing if possible, preferably with visually disabled users, to verify whether your contents are or are not readable for real people.

Also, color can be a tricky thing to balance! If you’re finding it difficult to distinguish different content with colors, consider pulling different levers, and using tools such as icons or different font sizes to get your point across! This ensures you aren’t relying on color alone to convey meaning, and building redundant means of getting information into your design will almost always lead to a more accessible experience.

Color contrast issues are everywhere, and clearing them away would significantly reduce access barriers on the web. On a case-by-case basis, I find it simplest to remediate low contrast by adjusting the colors’ lightness or darkness, rather than their hue or saturation. In some cases (namely prominent text such as headings), you might be able to leverage font size and weight. Going forward, contrast should be addressed systemically, typically through codified design systems and ideally vetted with user testing.

Originally posted on my blog, benmyers.dev, as How to Fix Your Low-Contrast Text

While watching Bryan Robinson’s stream the other day, however, I had a moment of inspiration: what if I could build a Twitch chatbot that could let me input some search command, providing a few keywords, and it would return a link to the most relevant stream or article? And thus, SomeAnticsBot was born. Anyone can go to the Some Antics chat and send a !stream command or a !blog command to get a relevant stream or blogpost. I recommend trying it with these queries:

• !stream vite
• !stream generative
• !blog data cascade
• !blog dl
• !blog chatbot (Look familiar? 😉)

I think a bot like this is incredibly handy for any streamer with a backlog of handy content to link to, so I’m sharing how I built SomeAnticsBot with Algolia, Node.js, tmi.js, and Heroku.

Algolia is a service that lets us upload our content and then search through it quickly. It’s predominantly designed to support website searchbar experiences, but it’s what we’ll use to ensure our bot is capable of taking any number of keywords and returning the most relevant piece of content.

Before we can use Algolia to search through our content, we’ll need to tell Algolia what content exists. This entails uploading an index, a structured representation of our content (likely in a JSON format) with properties representing key attributes of our content such as the title, description, publish date, and body. If you’re indexing pages on your site, you’ll probably want a setup that’s integrated with your workflow for deploying new versions of your site, so that anytime you publish a new page, it automatically gets added to your Algolia index so your search results remain up to date.

Unfortunately, because the specifics of different kinds of content and their methods of deployment vary a lot, I can’t really give you The One True Way™ to set up your Algolia index and workflow. I apologize for this section being very “draw the rest of the owl,” but I’ll share some resources I ended up using to set up my index.

If you’re using Netlify to deploy your site, I highly recommend following Algolia’s quickstart for setting up a Netlify site with Algolia. This quickstart walks you through installing Algolia’s official plugin for Netlify, which will add Algolia’s site crawler to your build process and handle updating your index for you.

If you instead end up needing to manually create and deploy an index, I recommend reading through Raymond Camden’s guide to creating an Algolia index in Eleventy, which uses the algolia-indexing library to publish incremental updates to your index.

You’ll know everything’s working when your Algolia index says it has records!

You don’t have to create a new Twitch account specifically for your bot — you could use your own account that you broadcast from as the chatbot account. However, I recommend using a new account for your chatbot for two reasons.

1. It lets your audience more clearly delineate which messages are from you and which ones are from the bot. This is a less vital reason, but I tend to find clear delineations between humans and bots a better user experience for all involved.

2. It ensures that if anything happens to the bot, your channel is safe. I personally get a little uneasy about the possibility that platforms such as Twitch could crack down on even benign bots such as this, and I want to remove any possibility that my actual account could be a casualty of crackdowns on botlike behavior. Additionally, we will be using authorization tokens for this bot, and if those tokens were to leak, I’d vastly prefer a burner account’s tokens to leak than my own streamer account.

That in mind, go to Twitch and create a brand new account. I’d recommend picking a name that’s very explicit that this is a chatbot for your channel. For instance, my channel is “SomeAnticsDev,” and my bot is “SomeAnticsBot.”

Once you’re signed in as this new account, you’ll want to get credentials to use this account as a bot. Here’s how I did that (kudos to Colby Fayock for documenting these steps!):

1. While logged into Twitch as your chatbot account, go to Twitch Token Generator.
2. Select Bot Chat Token.
3. Authorize Twitch Token Generator with your chatbot’s Twitch account in the OAuth flow, and complete the captcha.
4. Copy the provided access token and save it for later.

Let’s spin up the beginnings of a repository for our chatbot project.

In your terminal, run the following commands:

mkdir twitch-chatbot
cd twitch-chatbot
git init
npm init -y

This creates a new Git repository, and initializes a Node project with a default configuration.

Next up, we’ll install our dependencies:

npm install algoliasearch dotenv tmi.js

In order, these dependencies will do the following for us:

• algoliasearch: Lets us query Algolia to get the most relevant results from our content
• dotenv: Lets us leverage environment variables locally while we develop to keep our secrets separate from our code
• tmi.js: Enables us to listen and respond to our Twitch chat

Installing like this will give you the latest versions of these dependencies. If you run into any issues with the following steps, you may be on a different version of a dependency than I am. The versions I used to get this working are:

• algoliasearch: 4.12.1
• dotenv: 14.3.2
• tmi.js: 1.8.5

We’ll need a script to run to kick off our project. In your package.json, add a "start" script:

{
	"name": "twitch-chatbot",
	"version": "1.0.0",
	"description": "",
	"main": "index.js",
	"scripts": {
		"start": "node index.js"
	},

Afterwards, we’ll tell Git to ignore our dependencies and the .env secrets file we’ll be creating shortly. Create a .gitignore file and add the following:

node_modules/
.env

Finally, we’ll create a .env file to contain our secrets. We’ll use the following environment variable keys:

ALGOLIA_APP_ID=
ALGOLIA_API_KEY=
ALGOLIA_INDEX_ID=
TWITCH_BOT_ACCESS_TOKEN=

Go to your Algolia index and the Twitch Token Generator and fill out the relevant secrets for each environment variables.

After three steps, our setup is done (😅) and we’re ready to start building a chatbot that interacts with Twitch (🥳)!

This section and any others concerning building and deploying a Twitch chatbot could not have been possible without Colby Fayock’s article about building Twitch bots! It’s a really well article, and if anything in this article is confusing, please go check out Colby’s!

In your project, create an index.js file and add the following:

const tmi = require('tmi.js');
require('dotenv').config();

const streamerUsername = 'YourStreamingChannelUsernameHere';
const botUsername = 'YourBotUsernameHere';

const client = new tmi.Client({
	connection: {
		secure: true,
		reconnect: true
	},
	channels: [streamerUsername],
	identity: {
		username: botUsername,
		password: process.env.TWITCH_BOT_ACCESS_TOKEN
	}
});

client.connect();

client.on('message', (channel, tags, message, self) => {
	console.log(channel, tags, message);
});

Don’t forget to replace the strings on lines 4 and 5 with your own accounts’ usernames!

This code uses tmi.js (short for Twitch Messaging Interface) to set up a connection to your Twitch chat. Then, it establishes a callback to execute whenever a message is sent to your channel’s chat — in this case, logging out the details received about that particular message.

Let’s go ahead and test this! In your terminal, run npm start. Then, go to your channel’s chatbox and send a few messages. Check your terminal and confirm that the message details are logged successfully.

We can now read the chat successfully. Let’s have our bot respond whenever anyone sends a message that starts with “!blog.”

Inside your 'message' callback, add the following:

const tmi = require('tmi.js');
require('dotenv').config();

const streamerUsername = 'YourStreamingChannelUsernameHere';
const botUsername = 'YourBotUsernameHere';

const client = new tmi.Client({
	connection: {
		secure: true,
		reconnect: true
	},
	channels: [streamerUsername],
	identity: {
		username: botUsername,
		password: process.env.TWITCH_BOT_ACCESS_TOKEN
	}
});

client.connect();

client.on('message', (channel, tags, message, self) => {
	if (message.startsWith('!blog')) {
		client.say(streamerUsername, 'Howdy!');
	}
});

Restart your bot in the terminal. Go back to your Twitch chat, and send a message starting with !blog. With any luck, your bot account should reply “Howdy!”

Now that our bot can communicate in your chat, let’s make sure it can take a search query and return a relevant result with Algolia!

Here, we’ll strip the message of the !blog command at the beginning, so that we’re left with just the query itself!

const tmi = require('tmi.js');
require('dotenv').config();

const streamerUsername = 'YourStreamingChannelUsernameHere';
const botUsername = 'YourBotUsernameHere';

const client = new tmi.Client({
	connection: {
		secure: true,
		reconnect: true
	},
	channels: [streamerUsername],
	identity: {
		username: botUsername,
		password: process.env.TWITCH_BOT_ACCESS_TOKEN
	}
});

client.connect();

client.on('message', (channel, tags, message, self) => {
	if (message.startsWith('!blog')) {
		const query = message.replace('!blog ', '');
	}
});

Next, we’re going to instantiate an Algolia client that can handle search operations on our behalf.

const tmi = require('tmi.js');
const algoliaSearch = require('algoliasearch');
require('dotenv').config();

const algoliaClient = algoliaSearch(
	process.env.ALGOLIA_APP_ID,
	process.env.ALGOLIA_API_KEY
);
const index = algoliaClient.initIndex(process.env.ALGOLIA_INDEX_ID);

const streamerUsername = 'YourStreamingChannelUsernameHere';
const botUsername = 'YourBotUsernameHere';
// …

index is now a programmatic representation of our Algolia index. We can use it to search the Algolia index for the chatter’s query. Let’s go back down to our 'message' callback:

const tmi = require('tmi.js');
const algoliaSearch = require('algoliasearch');
require('dotenv').config();

const algoliaClient = algoliaSearch(
	process.env.ALGOLIA_APP_ID,
	process.env.ALGOLIA_API_KEY
);
const index = algoliaClient.initIndex(process.env.ALGOLIA_INDEX_ID);

const streamerUsername = 'YourStreamingChannelUsernameHere';
const botUsername = 'YourBotUsernameHere';

const client = new tmi.Client({
	connection: {
		secure: true,
		reconnect: true
	},
	channels: [streamerUsername],
	identity: {
		username: botUsername,
		password: process.env.TWITCH_BOT_ACCESS_TOKEN
	}
});

client.connect();

client.on('message', (channel, tags, message, self) => {
	if (message.startsWith('!blog')) {
		const query = message.replace('!blog ', '');

		try {
			index.search(query, {
				attributesToRetrieve: ['url', 'title'],
				hitsPerPage: 1
			}).then(({hits} => {
				console.log(hits);
			}))
		} catch (error) {
			console.error(error);
		}
	}
});

Restart your bot in the terminal again. Go to your Twitch chat, and send a !blog command, this time adding a few words that should correspond to a piece of content in your index. Check your terminal, and confirm that the bot has logged an array with one object, and that object contains a title and url of the most relevant piece of content.

If we successfully get a piece of content, we want to send it back in the chat! We’ve previously used client.say() to send messages, so let’s do it again:

const tmi = require('tmi.js');
const algoliaSearch = require('algoliasearch');
require('dotenv').config();

const algoliaClient = algoliaSearch(
	process.env.ALGOLIA_APP_ID,
	process.env.ALGOLIA_API_KEY
);
const index = algoliaClient.initIndex(process.env.ALGOLIA_INDEX_ID);

const streamerUsername = 'YourStreamingChannelUsernameHere';
const botUsername = 'YourBotUsernameHere';

const client = new tmi.Client({
	connection: {
		secure: true,
		reconnect: true
	},
	channels: [streamerUsername],
	identity: {
		username: botUsername,
		password: process.env.TWITCH_BOT_ACCESS_TOKEN
	}
});

client.connect();

client.on('message', (channel, tags, message, self) => {
	if (message.startsWith('!blog')) {
		const query = message.replace('!blog ', '');

		try {
			index.search(query, {
				attributesToRetrieve: ['url', 'title'],
				hitsPerPage: 1
			}).then(({hits} => {
				if (!hits || hits.length === 0) return;

				const {title, url} = hits[0];
				const reply = `Check out "${title}" at ${url}!`;
				client.say(streamerUsername, reply);
			}))
		} catch (error) {
			console.error(error);
		}
	}
});

Moment of truth: let’s see if it works! Restart your bot, and then return to your Twitch chat. Run a !blog command with a search query again, and confirm that the Twitch bot replies with a handy link to your content!

At this point, you have a finished Twitch chatbot! There’s just one problem: it’s up to you to make sure it’s running whenever you’re live. Let’s deploy our chatbot to Heroku so it can be up 24/7 without us needing to run it ourselves.

Heroku runs processes in containers they call dynos. You can configure the kind of processes running in dynos with a file called Procfile.

In your code, create a file called Procfile, and add the following:

worker: npm start

This file tells Heroku that this project may want to use a worker dyno, which tends to be for long-running processes such as bots. That long-running process, in this case, is the process created by running npm start.

If you haven’t already, create a remote repository for your code on GitHub. Commit your code, and push it up.

The following files should be pushed up to GitHub:

• .gitignore
• index.js
• package.json
• package-lock.json
• Procfile

The following files should be ignored, and should not be pushed up to GitHub:

• The node_modules/ directory
• .env

If you haven’t already, create an account on Heroku. To run your worker dyno 24/7, you’ll need to give Heroku your billing details to get the extra free job minutes — you won’t have to pay for anything we’re doing here, but you will likely need these extra free minutes.

Log into Heroku and navigate to your dashboard. Now, we’ll create a new Heroku app:

1. In the top-right corner of your dashboard, click New.
2. In the dropdown, click Create new app.
3. Name your app something descriptive and unique.
4. Click Create app.
5. In the Deployment method section of your new app’s page, click the GitHub: Connect to GitHub option (If you haven’t used Heroku before, you may need to authenticate Heroku with GitHub).
6. Search for your bot’s repository, and click Connect.

Now, we need to configure our Heroku app to handle deploys, leverage our secrets, and run 24/7 as a worker dyno.

1. In the Automatic deploys section of your app’s page, click the Enable Automatic Deploys button.
2. At the bottom of this page, in the Manual deploys section, click the Deploy Branch button. This deploy will fail, since our project doesn’t have its secrets yet, but it will seed the Heroku app with some information we’ll need for some upcoming steps.
3. At the top of this page, click the Settings tab.
4. In the Config Vars section, click Reveal Config Vars.
5. Add each key–value pair from your .env file.
6. At the top of this page, click the Resources tab. This is where we’ll tell Heroku to use a worker dyno (as opposed to the default web dyno, which receives HTTP requests).
7. This page should list a (toggled on) “web” dyno and a (toggled off) “worker” dyno. If it doesn’t yet, go back to the Deploy tab and trigger another manual deploy again, and then return to this Resources tab.
8. Click the pencil button next to “web” to enable edit mode for your “web” dyno. Toggle the “web” dyno off, and click Confirm.
9. Similarly, turn the “worker” dyno on.
10. Navigate to the Deploy tab once more and manually redeploy this app.

Once your app redeploys successfully, return to your Twitch chat, and confirm that the !blog command works, even when your local bot process is shut down.

At this point, you have a fully functional Twitch chatbot, deployed 24/7 on Heroku, that can take an audience member’s search query and return the most relevant blogpost!

There’s tons of room to improve this, make it more robust, and to make it your own — but hopefully, this is a solid starting point!

Originally posted on my blog, benmyers.dev, as Build a Twitch Chatbot for Sharing Your Content Using Algolia Search

Read the original thread!

This blogpost started out as a Twitter thread. If you’d like to read through that instead and respond to those tweets, feel free!

👋🏻 Howdy! If we haven’t met yet, I blog here, albeit very sporadically. I also moderate the Lunch.dev and Frontend Horse Discord communities, both of which are full of content creators. I’d love to share what I’ve learned about technical blogging over the past few years, in the hopes that it could help you out as you consider blogging.

For many, maximizing readership is part of the blogging experience. This is especially true if your goals for blogging are to expand your reach and promote yourself. However, you don’t have to focus on that if that’s not what you’re about. Sharing what you’ve learned for others (or your future self!) to benefit from is reason enough to blog.

On that token, a lot of blogging advice is great, but assumes you’re trying to growth hack your readership. Follow that guidance if it fits, but you’re by no means obligated to if that’s not what you’re after.

If you’re just starting out, I think your goal should be to practice blogging and see if it’s something you enjoy. Blogging platforms like Dev.to and Hashnode handle the platform and audience parts for you, so you can cut directly to figuring out whether blogging is a good fit for you.

Some bloggers object here, stating you should own your own content rather than be beholden to a platform. I generally agree! However, I don’t think that that’s something a brand new blogger should be focusing on. Figure out whether blogging is right for you, then think about how you’ll own your content.

(And for what it’s worth, Dev.to gives you the tools you need to syndicate your own content down the road if that’s what you decide to do)

If you’re building your blog as a way to learn some tech, great! It can be really, really tempting to use a bunch of the hot whizzbang technologies du jour to build your blog exactly the way you want. But to paraphrase Flavio Copes in his post The pros of using a boring stack, if you’re focusing on creating content regularly, pick the tools you’ll finagle with the least.

Your disabled readers, RSS users, search engine results pages, and future self will thank you.

If you’re looking to maximize your readership, then okay, cadence is pretty important. And if your personal goals are to blog regularly, then great!

But if you’re blogging for fun, it’s totally fine not to stick to a cadence, I promise. It’s December as I write this, and my last blogpost was from August. I’ve tried a few times to stick to an every-two-weeks cadence, and I found that the cyclical nature and the pressure to write something, anything, was burning me out. Now, I mostly just write whenever inspiration strikes, and that works for me.

Regular cadences might encourage some writers, but they’re not for everyone.

Earlier this year, I wrote a post about skip links. I wrote it because I had thought that skip links were fairly common knowledge until I spoke to several web-savvy people who had never heard of them before. The post was shared more widely than I expected, too.

The curse of knowledge is such a real phenomenon in creating technical content, and few topics are “too” basic for someone to find helpful. You never know who will be one of today’s lucky 10,000 thanks to you.

A blogpost that makes 80% of a topic easy to understand is often more helpful and shareable than a 100% comprehensive guide that is confusing.

I struggle with this a lot. I don’t want to leave tidbits out of my blogposts, but I also don’t want my posts to become absolute behemoths.

There will always be caveats and extra context that you just don’t have room for in your posts. Trying to include every possible tangent so you can be 100% comprehensive can really detract from the core point you’re trying to make.

Accept corrections and suggestions gracefully, but also… not all feedback will fit the voice and scope you’re going for, and that’s okay!

I had this experience with a post I wrote recently. I asked some experts for feedback on my content. The post I had written was short and to the point, and glossed over a few things in favor of clarity. The feedback I received was largely about more tangents I could include to be 110% comprehensive.

These folks were very kind to lend me their feedback, but I realized that they really weren’t my target audience, and in many cases, I felt that integrating their feedback would make the post less clear for my target audience.

If you ask folks who are already familiar with the topic, be prepared for feedback that doesn’t align with your target audience. Consider it thoughtfully, but consider taking it with a grain of salt, too.

Originally posted on my blog, benmyers.dev, as Ben's Humane Guide to Technical Blogging

Introduction

The <dl>, or description list, element is underrated.

It’s used to represent a list of name–value pairs. This is a common UI pattern that, at the same time, is incredibly versatile. For instance, you’ve probably seen these layouts out in the wild…

Each of these examples shows a list (or lists!) of name–value pairs. You might have also seen lists of name–value pairs to describe lodging amenities, or to list out individual charges in your monthly rent, or in glossaries of technical terms. Each of these is a candidate to be represented with the <dl> element.

So what does that look like?

I’ve been saying “<dl>,” when really, I’m talking about three separate elements: <dl>, <dt>, and <dd>.

We start with our <dl>. This is the description list,^{[note 1]} akin to using a <ul> for an unordered list or an <ol> for an ordered list.

<dl>

</dl>

Fancy.

Next up, we want to add a name–value pair. We’ll use a <dt>, short for description term, for the name, and we’ll use a <dd>, short for description detail, for the value.^{[note 2]}

<dl>
	<dt>Title</dt>
	<dd>Designing with Web Standards</dd>
</dl>

To add another name–value pair to our list, we add another <dt> and <dd>:

<dl>
	<dt>Title</dt>
	<dd>Designing with Web Standards</dd>
	<dt>Publisher</dt>
	<dd>New Riders Pub; 3rd edition (October 19, 2009)</dd>
</dl>

But wait — what if I have a term that has multiple values? For instance, what if this book has multiple authors?

That’s fine! One <dt> can have multiple <dd>s:

<dl>
	<dt>Title</dt>
	<dd>Designing with Web Standards</dd>
	<dt>Author</dt>
	<dd>Jeffrey Zeldman</dd>
	<dd>Ethan Marcotte</dd>
	<dt>Publisher</dt>
	<dd>New Riders Pub; 3rd edition (October 19, 2009)</dd>
</dl>

There’s one last piece of the description list anatomy to look at for most basic use cases: what if I want to wrap a <dt> and its <dd>(s) for styling reasons?

In this case, the specs allow you to wrap a <dt> and its <dd>(s) in a <div>:

<dl>

	<div>
		<dt>Title</dt>
		<dd>Designing with Web Standards</dd>
	</div>

	<div>
		<dt>Author</dt>
		<dd>Jeffrey Zeldman</dd>
		<dd>Ethan Marcotte</dd>
	</div>

	<div>
		<dt>Publisher</dt>
		<dd>New Riders Pub; 3rd edition (October 19, 2009)</dd>
	</div>

</dl>

A wrapper <div> like this is the only element that can wrap those <dt>/<dd> groups.

And that’s it! That’s the anatomy of the description list, HTML's semantic way to mark up a list of name–value groups!

Before we learned about the <dl>, <dt>, and <dd> elements, my team used to use nested <div>s for this pattern all the time. It looked a lot like:

<div class="book-details">
	<div class="book-details--item">
		<div class="book-details--label">
			Title
		</div>
		<div class="book-details--value">
			Designing with Web Standards
		</div>
	</div>
	<div class="book-details--item">
		<div class="book-details--label">
			Author
		</div>
		<div class="book-details--value">
			Jeffrey Zeldman
		</div>
		<div class="book-details--value">
			Ethan Marcotte
		</div>
	</div>
	<div class="book-details--item">
		<div class="book-details--label">
			Publisher
		</div>
		<div class="book-details--value">
			New Riders Pub; 3rd edition (October 19, 2009)
		</div>
	</div>
</div>

This has all the information about the book, right? Why do we need semantics for a list of name–value groups in the first place if something like a series of nested <div>s could get the job done?

When determining whether a semantic element might be appropriate for a given pattern, I find it helpful to ask, “What benefits — even theoretical — could we get if computers could recognize this pattern?” In this case, what lift could we get if browsers could somehow recognize a list of name–value groups?

Answers to that question will be varied. I tend to spend a lot of time advocating for web accessibility, so my first thought tends to be how screenreaders could interpret the pattern. Off the top of my head, I can think of a couple of benefits screenreader users could get from their screenreaders recognizing this pattern:

1. The screenreader could tell the user how many name–value groups are in the list.
2. The screenreader could tell the user how far into the list they are.
3. The screenreader could treat the list as one block that the user could skip over if they’re uninterested in it.

All of these could make the list more usable than a series of nested <div>s, which would treat each name and value in the list as nothing more than a standalone text node.

If you can come up with a couple of even theoretical lifts from the user’s device recognizing a pattern, then there’s a good chance that the pattern is a strong candidate for having some associated semantics.

For what it’s worth, these screenreader experiences aren’t hypothetical — they’re benefits that screenreader users really get from using <dl> in most browser/screenreader combinations. Admittedly, however, support for the <dl> element is not yet universal. You may decide that screenreaders’ fallback experience — treating the list as standalone text nodes — isn’t sufficient for your use case, and instead opt for something like a <ul> until support improves.

My favorite example, the one that really takes the cake for me, is Dungeons & Dragons statblocks, which are really “Oops! All Name–Value Pairs!”

No, really: just how many candidates for <dl>s do you see in this statblock alone?

I counted five possible description lists, personally. Here’s how I chose to mark this up:

<div>
	<h1>Kobold</h1>
	<small>Small humanoid (kobold), lawful evil</small>

	<dl>
		<div>
			<dt>Armor Class</dt>
			<dd>12</dd>
		</div>
		<div>
			<dt>Hit Points</dt>
			<dd>5 (2d6 - 2)</dd>
		</div>
		<div>
			<dt>Speed</dt>
			<dd>30 ft.</dd>
		</div>
	</dl>

	<dl aria-label="Ability Scores">
		<div>
			<dt>STR</dt>
			<dd>7 (-2)</dd>
		</div>
		<div>
			<dt>DEX</dt>
			<dd>15 (+2)</dd>
		</div>
		<div>
			<dt>CON</dt>
			<dd>9 (-1)</dd>
		</div>
		<div>
			<dt>INT</dt>
			<dd>8 (-1)</dd>
		</div>
		<div>
			<dt>WIS</dt>
			<dd>7 (-2)</dd>
		</div>
		<div>
			<dt>CHA</dt>
			<dd>8 (–1)</dd>
		</div>
	</dl>

	<dl aria-label="Proficiencies">
		<div>
			<dt>Senses</dt>
			<dd>Darkvision 60 ft.</dd>
			<dd>Passive Perception 8</dd>
		</div>
		<div>
			<dt>Languages</dt>
			<dd>Common</dd>
			<dd>Draconic</dd>
		</div>
		<div>
			<dt>Challenge</dt>
			<dd>1/8 (25 XP)</dd>
		</div>
	</dl>

	<dl aria-label="Traits">
		<div>
			<dt>Sunlight Sensitivity</dt>
			<dd>
				While in sunlight, the kobold has disadvantage
				on attack rolls, as well as on Wisdom (Perception)
				checks that rely on sight.
			</dd>
		</div>
		<div>
			<dt>Pack Tactics</dt>
			<dd>
				The kobold has advantage on an attack roll against
				a creature if at least one of the kobold's allies
				is within 5 ft. of the creature and the ally
				isn't incapacitated.
			</dd>
		</div>
	</dl>

	<h2 id="actions">Actions</h2>
	<dl aria-labelledby="actions">
		<div>
			<dt>Dagger</dt>
			<dd>
				<i>Melee Weapon Attack:</i> +4 to hit, reach 5 ft.,
				one target. <i>Hit:</i> (1d4 + 2) piercing damage.
			</dd>
		</div>
		<div>
			<dt>Sling</dt>
			<dd>
				<i>Ranged Weapon Attack:</i> +4 to hit, reach 30/120 ft.,
				one target. <i>Hit</i>: (1d4 + 2) bludgeoning damage.
			</dd>
		</div>
	</dl>

</div>