I’m excited to run my first masterclass in July ’26 when Athlyticz launches and needed to look something up in a {pkgdown} website, only to discover the search results aren’t keyboard navigable.
That sucks. Not just for me when navigating a site quickly but it also means pkgdown websites fail WCAG and POUR-CAF accessibility requirements. So I took a hot minute to fix it.
The issue and associated PR are on GitHub, and the fixes are minute changes to the .scss you could implement yourself
Getting to the issue
I opened up Claude in Positron and asked it to look at the repo and suggest a fix to make the search navigable. If I’d have stuck with the one shot it would have made a huge number of changes:
The Algolia Autocomplete 0.38 library (a jQuery plugin) generates the DOM structure, then fires events. The cleanest way to add the missing ARIA without patching the library is:
Post-render hook: after the autocomplete fires its autocomplete:updated / autocomplete:shown events, walk the .aa-suggestion divs and add role=“option” + aria-selected=“false” + a unique id to each one aria-activedescendant + aria-expanded management: on autocomplete:cursorchanged update the input’s aria-activedescendant to the active suggestion’s id, and toggle aria-expanded on autocomplete:shown/autocomplete:closed
CSS: add .aa-suggestion.aa-cursor (the class Algolia adds for keyboard-active item) to the existing hover rule in pkgdown.scss
Does this approach look right to you, or would you prefer to patch it differently (e.g., wrap the suggestion template to inject role=“option” inline)?
I know the current UN advice is to not add pleasantries () but I am over correcting from a very strong anti-AI stance. So I asked,
Okay. Just before we make those changes let’s make sure that we are making the minimal possible changes and not adding unnecessary complexity.
Well, wouldn’t you know! Algolia has a CSS class for that .aa-cursor. All the .scss required was that class to be added.
Claude then went through 3 iterations of mistakes that were entirely due to using aacursor. It had greped away the hyphen. A perfectly understandable solution. Except it’s not.
If you train a junior dev and they make a mistake with a grep they’ll learn and improve after a few times. But an LLM? It’ll sycophantically apologise to you and then commit the exact same error for millions of users again and again, potentially without ever actually being fixed.
Fixing it
I could have finished up at this point. But I took an extra moment to check the colour contrast of the selected search item and the active link background colour in the navbar. Both of these failed the 3:1 ratio. I’ve been out the game for a while, but at least before the `25 agentic apocalypse that’s two separate issues which is why you’ll find the ultimate solutions in two PR: #2998 and #3000.