Alloy GitHub
Articles

The checkbox TalkBack couldn't find

On Tuesday I posted Alloy on Hacker News. It's a CSS kit where menus, dialogs and tabs work with JavaScript off, and the link was one HTML file, an invoicing screen. A few people said it didn't look accessible. I asked what they'd tried, and lopis gave me a real one: tick an invoice and a "Selected invoices" bar appears with a Download button, and a screen reader user never hears about it.

They were right. Fixing it took two days, four releases and one test page, and along the way I found a worse bug that no tool had flagged. This is what happened.

The bar nobody heard

The bar shows with CSS. While any checkbox in the area is ticked, :has() shows it. No script, so nothing tells a screen reader that something new is on the page.

The fix is a live region. A screen reader watches a role="status" element and reads out what appears inside it:

<div role="status">
  <div class="show-when-on">
    Selected invoices
    <button type="button">Remind</button>
    <button type="button">Download</button>
  </div>
</div>

The one rule: the role="status" box has to be on the page from the start, and only what's inside it shows and hides. If the status element itself is hidden at load, the screen reader never registers it, and it says nothing when it appears.

Easy. Then I turned on TalkBack on my phone to check it, and I couldn't tick a checkbox at all.

The 1px checkbox

With TalkBack on you explore by touch. You hold a finger on something, it reads it out, and a double tap uses it. I could hold on the invoice number and hear it. I could hold on the amount and hear it. I held on the checkbox and got nothing.

Alloy's checkboxes are a real <input>, hidden, with an empty <i> after it that draws the box. The input was hidden like this:

.check-fill input {
  position: absolute;
  width: 1px;
  height: 1px;
  opacity: 0;
  pointer-events: none;
}

A keyboard reaches it fine, and so does swiping from item to item. But TalkBack by touch asks the browser what's under your finger, and under my finger was a 20px drawing with no name. The real checkbox was a 1px dot at the edge.

And every automated check passed. I run axe on all 614 pages of the templates, in three themes and at phone width, and it was green the whole time. It checks that the input has a name and a role, and it did. It can't check whether a finger can land on it.

Two tries

First try: make the input as big as its label. I tested it, pushed it, picked up my phone. Still nothing.

The input was the right size now but still underneath the drawing, and pointer-events: none meant taps went straight through it. Chrome tells TalkBack whatever a tap would hit, and that was still the drawing. Second try: take the input out from under it.

.check-fill {
  position: relative;
}
.check-fill input {
  position: absolute;
  inset: 0;
  width: 100%;
  height: 100%;
  margin: 0;
  opacity: 0;
  z-index: 1;
}

It's still invisible, and it sits on top of the box and takes the tap. Clicking still ticks it once. The same change went into radios, switches, tabs and the toggle, which were all hidden the same way.

Still nothing on my phone.

Four boxes

At that point I stopped guessing. I made a page with four checkboxes and no text next to them, each built a different way:

  • A: the new Alloy one, invisible and on top
  • B: the same, at opacity: 0.01 instead of 0
  • C: the browser's own checkbox, made big
  • D: the usual "visually hidden" 1px clip a lot of sites use

A, B and C worked. D didn't, which is close to what Alloy had before. So the fix was right. Which meant the invoice page should work too, and it didn't.

It was the cache

The example loaded the CSS from jsDelivr as @alloyhtml/css@1, meaning the newest 1.x. jsDelivr tells browsers they can keep that file for seven days. I'd been testing in a normal tab, and I assumed a reload gets the latest file. It doesn't, not for the stylesheet. My phone had kept the broken one through both releases.

I opened a fresh incognito tab, held on the checkbox, double tapped, and heard "Selected invoices, Remind, Download". I'm not going to type what I said.

The example now loads its exact version, @1.0.12, so a new release is a new address and nobody gets an old copy. For your own site @1 is still the right choice, since you get fixes without changing anything. Just know a fix can take a week to reach someone who already visited.

What I took from it

Automated checks are the floor. Anyone could have caught this bug by turning on their phone's screen reader for five minutes, and I hadn't done that on a phone.

When a fix doesn't work twice, build the smallest page that answers one question. Four boxes told me more than two releases did.

And there's still a gap I know about: tabs read as radio buttons, not a tab list, because that's what they are. Someone asked in the thread whether real screen reader users have tested Alloy. They haven't yet. If you use one every day and have twenty minutes, I'd really like to hear what breaks: [email protected].

The invoicing page is at alloyhtml.com/example.html. Turn on TalkBack or VoiceOver and try it. The CSS is Alloy, free and MIT, and these fixes are in 1.0.12.