A few months ago, my friends Jose and Arturo joined the Aguacatec community. Both are blind and experts in accessibility. Paradoxically, they opened my eyes to how useful technology is for them, how much Home Assistant can improve their daily lives, and how crucial it is for it to be fully accessible.
Although accessibility is one of the principles promoted by the project, unfortunately, this is not always the case. For this reason, we set out to compile some changes that would be very helpful for people with visual impairments.
Accessibility is a process; it must be considered at every stage of product development to ensure the result is as efficient as possible for everyone. Accessibility enhances peopleâs livesâit is technology for people. For some, it is essential; for others, it is helpful and radically improves their user experience.
Many elements have functionality but are not recognized by screen readers as actionable items (such as links, buttons, etc.). As a result, screen reader users would not know that these elements are clickable. Furthermore, users who do not rely on a mouse would also be unable to interact with them.
Here are some easy changes to implement:
In the Settings > Devices & Services > Entities section, there is a table with three columns that lack headers. Adding the appropriate headers and placing each value in its own separate column would make this content accessible.
The time selectors in the Logbook and History sections can only be used with a mouse. Therefore, they are not accessible for visually impaired users who rely on a keyboard.
Some dropdown menus can only be used with a mouse. For example, the one used to select days of the week in an automation or the one for selecting entities to sync with HomeKit. Therefore, they are not accessible for visually impaired users who rely on a keyboard.
There is also room for improvement in some of the add-ons:
In Zigbee2MQTT, the buttons are not labeled correctly. They have a label in the âtitleâ attribute, but not in the actual label.
In Zigbee2MQTT, there are unlabeled images, for example, in the âPowerâ column.
In Zigbee2MQTT, sometimes when adding a new device, a red percentage symbol flashes continuously (until it obtains the current battery value). This element is continuously verbalized by screen readers, making it impossible to perform any other task from that point onward. Proposed solution: make it a fixed element.
In Zigbee2MQTT, when there are many devices, the add-on becomes very slow, making it impossible to perform any actions. Proposed solution: paginate the items and include a button to refresh the data.
The official âTerminalâ add-on does not work with screen readers, making it inaccessible for visually impaired users. The text entered in the âinputâ editing box is not read, and the output of the command is not read either.
We hope this information is helpful for making changes that will make Home Assistant more accessible. It is important for experienced users who regularly use assistive technologies to actively collaborate in the different phases of development.
Thank you for this WTH â as a daily screen reader user (NVDA and Google TalkBack), I care deeply about Home Assistant reaching full accessibility. This really hits home for me. Iâve already reported several critical accessibility issues and can confirm the problems highlighted in this WTH are all too real.
Letâs talk specifics: the new dashboard editor with sections? An accessibility nightmare. Reading graphs, like those in the energy panel? Practically impossible without proper screen reader support. Missing headers and semantic structure across pages? A constant frustration. Oh, and the lack of unique <title> tags for configuration subpages? Thatâs not just a small oversight â itâs fundamental.
Now, about the add-ons. âTerminal & SSHâ is a total disaster for screen reader users. Sure, you can type commands into the input field, but after that? Radio silence. No feedback, no way to track whatâs happening. OCR? Come on, thatâs a workaround, not a solution. The âFile Editorâ isnât much better â hardly an accessibility role model.
So, dear HA team â developers, UI/UX designers â letâs prioritize accessibility. Familiarize yourselves with the guidelines and, more importantly, put them into practice. When accessibility is baked in from the start, thereâs nothing to fix later.
Right now, the handling of dashboards with sections feels like accessibility was an afterthought â or maybe not a thought at all. Thatâs not just weak. For the number one GitHub project, itâs embarrassingly weak. Letâs do better, shall we?
To be fair, as a developer, i believe that most of us are not aware of how important accesibility is (and, most of the time, how easy is to comply with It). I wasnât until Jose and Arturo explained to me how they work, and how we can help.
Also, i think is important to understand that It is a win-win game. Of course the point is to make It more accesible, but It means more users, more community, more social impact⌠And It totally makes sense with Home Assistant philosophy.
Again, i hope HA team donât take this as a simple request, but an offer to help, from users who had been working on accesibility for years.
I donât know how accesible is discord, especially when we are talking about a community with so many messages (again, we must think as a screen reader user).
However, i think it may be useful to have an âAccesibilityâ Channel, where we can share weak points and proposals for improvement, and frontend developers can pick them up, or ask us anything if needed.
The dev channels are open if youâve selected in the Discord onboarding that you are a developer or contributor; we provide support to developers in these channels and are not aimed at general issue reporting from users.
The WTH topic you raise is a bit tainted, as there is a lot of talk about third-party/non-WTH things happening here, such as add-ons and external software like Zigbee2MQTT, which are really out of our scope for WTH.
We do acknowledge your concerns; accessibility is definitely on our radar. We actually have a contributor in the frontend development team who is using a screenreader as well, who, in general, really helps us out by pointing out things.
The problem with this WHT topic is that this post is pretty âgeneralâ in terms of âI want stuff to be better on this major subject,â making it rather hard to action or complete.
To be fair, I think WTH is probably the worst place for moving issues like these forward, as this needs a âper item/little caseâ handling with a feedback loop. Therefore, Iâd love to invite you guys to the frontend issue tracker on GitHub (yeah, I know, thus defeats the purpose of WTH month), but it is the best tooling/method we have to actually resolve these issues step-by-step.
So, please feel free to raise issues regarding this on the frontend issue tracker:
Keep in mind that it is best if each issue only describes one small issue/thing that can be actioned; avoid stacking multiple things found in a single issue.
Iâm happy to help with organizing and labeling issues raised.
Sorry if this wasnât the best way to share our suggestion. Our goal is to help, not to create any trouble.
I feel like Iâm in the middle here since itâs easier for me to use tools that arenât always the most accessible for them (like this forum). I donât want to focus on whether we shared specific examples at the start of the thread or on the fact that there are GitHub issues already sent by them. We also understand that you donât control add-ons or external components. The examples, like a blinking icon, are just small ways to show how tiny details can become barriersâand these are usually easy to fix.
At the end of the day, whether this is the best place to bring it up or not, I think itâs important to try to talk directly with users and keep accessibility in mind from the start, rather than fixing things one by one later.
Please donât take this as being rude or ungrateful to the HA teamâI think your work is amazing, and i guess you have limited resources. But the point here is to understand the barriers that minorities face. Asking them to point out and explain how to fix accessibility issues every time we overlook them doesnât help; it just adds more hurdles for them.
Oh, donât get me wrong! It is great for sharing, but it is a complex subject that is hard to get moving with this post. Iâm merely trying to get it into actional bits/points, so we can actually make it a movable thing
Yes, I agree; Iâm trying to get that conversation moving in GitHub in that case. Solving specific issues that are currently there also helps with learning for the future.
Please note that the GitHub interface is extremely well-designed in terms of accessibility; I donât expect there to be any issue with participating in our issue trackers from that perspective.
The Home Assistant project runs iteratively, meaning we keep things moving and take small steps forward constantly. Solving existing issues is a nice first step that has an immediate effect.
Oh, I didnât take it as rude or ungrateful. Iâm mostly sorry that the experience with HA isnât up to par in this regard. The Home Assistant project has tons of resources but is mostly driven by the community. Not just in terms of wishes/supported/issue reports, but also in developers that contribute their time. For reference, we had 21,000 individual contributors in 2024;
Things I can do (and the help Iâm offering) is help and coordination in mapping out the issues that are there and looking at how we can address those for now and the future.
We truly appreciate your willingness to help, @frenck. Thatâs what we were looking for.
I agree, whatâs done is done, and we canât turn back time, but that doesnât prevent us from learning to do better in the future.
Iâd like to share this two issues submitted by Jose via GitHub that remain unresolved. Additionally, we want to reiterate our willingness to help in this matter and clarify any doubts.
feel free to raise issues regarding this on the frontend issue tracker: