When you’re a single developer working on a project in your spare time, next to a full-time job, you’re going to have to make choices on where to invest your efforts. You can’t work out every feature at once, and some bugs get ignored.

Earlier this month, GitHub user @blindndangerous pointed me to the fact that HASS.Agent doesn’t play well with screenreaders at all. And he was of course absolutely right; none of the components were properly named and labeled (don’t mistake this for the object’s reference name like LblCommands, that’s just internal). And even though it wouldn’t really lead to new fancy features, this would be well worth focussing on - so I more or less dropped all other tickets.

Since I didn’t have any prior experience, I started reading up on some documentation. Microsoft’s actually been doing pretty well in this area thankfully. Some links that helped me:

General Info
Best Practices

Accessible Role
Accessible Name
Accessible Description
Accessible Events

They’ve even released a (free) tool which greatly helped me analyse HASS.Agent’s interface:

Accessibility Insights

For instance, this is an analysis of the commands label on the main window:



You can see that while it’s grouped properly, and has name and controltype set, it doesn’t yet have a access- or acceleratorkey set (optional, but recommended). When I run the automation test, I get the ‘all clear’ (which means that it can be properly used by accessibility tools as-is):


It doesn’t catch everything, for instance: you still have to make sure the tab indexes are set correctly so the user can easily tab through the controls, and you have to make sure there are logical keybindings for every form/control.

Practically, you have to go through every single control, and think about primarily these three values:


It’s a lot of manual labor with trial-and-error on what works. You also have to keep consistency in mind, and some basic rules (for instance, don’t add the control type to AccessibleName). Afterwards, you need to check the tab index and keybinding, and lastly run the Accessibility Insights automation-test.

As always, the best way to go is to implement this from day one!