Accessibility Issues in home-assistant.io

Feedback

While looking to find information about installing Home Assistant Container, I had trouble reading the links in the right side of the page and even I saw contrast issues in the menu bar. I'm going to start with the home page.

Before I get started listing issues, I am using a browser extension called axe DevTools, which is developed by Deque (pronounced "D Q"). axe DevTools is very good at finding issues, but it only covers about 50% of the WCAG standards. The other 50% such as missing keyboard support (2.1.1), videos lacking captions, fake headings, fake lists, issues with custom widgets,, etc. will be covered in manual testing, but I'm going to focus on automated testing for now, as manual-testing can be a time-consuming process. This is true for focus outlines and due to my visual disability, some focus-able elements do make it difficult for me to see dotted focus outlines.

Note that I will probably not test every page, as that can also be a time-consuming process as well, so I'm only going to list pages that I found issues on while using axe.

Main Page URL: https://www.home-assistant.io/

Automated testing:

Elements must meet minimum color contrast ratio thresholds (31): Standards: WCAG 1.4.3 (AA) HTML:

<a href="/getting-started/">Getting started</a>
<a href="/docs/">Documentation <i class="icon icon-caret-down"></i></a>
<a href="/integrations/">Integrations</a>
<a href="/blog/">Blog</a>
<a href="/help/">Need help?</a>
<a href="/blog/2024/06/05/release-20246/">Release notes</a>
<a href="/blog/2024/06/13/zbt1-annoucement/">Home Assistant SkyConnect becomes Connect ZBT-1</a>
<a href="/blog/2024/06/12/roadmap-2024h1/">Roadmap 2024 Midyear Update: A home-approved smart home, peace of mind, and more!</a>
<a href="/blog/2024/06/12/roadmap-introduction/">A roadmap for Home Assistant</a>
<a href="/blog/2024/06/07/ai-agents-for-the-smart-home/">AI agents for the smart home</a>
<a href="https://community.home-assistant.io">Forums</a>
<a href="/join-chat/">Chat</a>
<a href="/newsletter/">Newsletter</a>
<a href="/cloud/" aria-label="Learn more about use Alexa to control Home Assistant">LEARN MORE</a>
<a href="/cloud/" aria-label="Learn more about use Google Assistant to control Home Assistant">LEARN MORE</a>
<a class="button" href="/integrations">EXPLORE INTEGRATIONS</a>
<a class="button" href="/docs/automation">EXPLORE AUTOMATIONS</a>
<a class="button" href="/addons">EXPLORE ADD-ONS</a>
<a class="button" href="https://companion.home-assistant.io/" target="_blank"> DOWNLOAD APPS </a>
<a class="button" href="/home-energy-management/" aria-label="Learn more about Home Energy Management"> LEARN MORE </a>
<a href="https://alerts.home-assistant.io">Home Assistant Alerts</a>
<a href="https://developers.home-assistant.io">Developers</a>
<a href="https://data.home-assistant.io">Data Science</a>
<a href="https://community.home-assistant.io">Community Forum</a>
<a href="mailto:hello@home-assistant.io">Contact</a>
<a href="/security/">Security Vulnerabilities</a>
<a href="/privacy/">Privacy</a>
<a href="https://status.home-assistant.io">System Status</a>
<a href="https://www.openhomefoundation.org/">Home Assistant is part of the Open Home Foundation</a>
<a href="https://jekyllrb.com/">Jekyll</a>
<a href="https://github.com/coogie/oscailte">Oscailte theme</a>

Issues:

Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 10.5pt (14px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 10.5pt (14px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 10.5pt (14px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 10.5pt (14px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 10.5pt (14px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 13.5pt (18px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 13.5pt (18px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 13.5pt (18px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 13.5pt (18px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 13.5pt (18px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.18 (foreground color: #1abcf2, background color: #fefefe, font size: 13.5pt (18px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.62 (foreground color: #ffffff, background color: #03a9f4, font size: 10.5pt (14px), font weight: bold). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.62 (foreground color: #ffffff, background color: #03a9f4, font size: 10.5pt (14px), font weight: bold). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.62 (foreground color: #ffffff, background color: #03a9f4, font size: 10.5pt (14px), font weight: bold). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.62 (foreground color: #ffffff, background color: #03a9f4, font size: 10.5pt (14px), font weight: bold). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.62 (foreground color: #ffffff, background color: #03a9f4, font size: 10.5pt (14px), font weight: bold). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.2 (foreground color: #1abcf2, background color: #ffffff, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1

Links must have discernible text (2): Standards: WCAG 2.4.4 (A), WCAG 4.1.2 (A) HTML:

<a href="/blog/2024/04/24/state-of-the-open-home-2024/" class="material-card picture-promo" style=" background-image: url(/images/frontpage/state-of-the-open-home-2024.png); background-size: cover; padding-top: 55%; "></a>
<a href="/voice_control/worlds-most-private-voice-assistant/" target="_blank" class="material-card picture-promo" style=" background-image: url(/images/frontpage/promo-private-voice-assistant.png); background-size: cover; padding-top: 45%; "></a>

Issues: To solve this problem, you need to fix at least (1) of the following:

Element does not have text that is visible to screen readers
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element has no title attribute

And fix the following:

Element is in tab order and does not have accessible text

<li> elements must be contained in <ol>, or <ul> (4): Standards: WCAG 1.3.1 (A) HTML:

1. <li class="post" style="display: grid; font-size: 16px">
<a href="/blog/2024/06/13/zbt1-annoucement/">Home Assistant SkyConnect becomes Connect ZBT-1</a>
<small class="blog-date">June 13, 2024</small>
</li>
2. <li class="post" style="display: grid; font-size: 16px">
<a href="/blog/2024/06/12/roadmap-2024h1/">Roadmap 2024 Midyear Update: A home-approved smart home, peace of mind, and more!</a>
<small class="blog-date">June 12, 2024</small>
</li>
3. <li class="post" style="display: grid; font-size: 16px">
<a href="/blog/2024/06/12/roadmap-introduction/">A roadmap for Home Assistant</a>
<small class="blog-date">June 12, 2024</small>
</li>
4. <li class="post" style="display: grid; font-size: 16px">
<a href="/blog/2024/06/07/ai-agents-for-the-smart-home/">AI agents for the smart home</a>
<small class="blog-date">June 7, 2024</small>
</li>

Issues: To solve this problem, you need to fix the following:

List item does not have a <ul>, <ol> parent element

Notes: Screen readers have different keyboard commands that allow them to navigate websites in a very efficient manner. For example, without list items that go inside either <ol> or <ul>, screen readers won't see it as a list and users of screen readers will announce "there are no lists in this page" if they attempt to press the L and Shift+L keys in order to navigate between lists. Shift+H and H key navigates between headings, shift+T and T navigates between tables, shift+K and K navigates between links, and so on and so forth.

Getting Started: URL: https://www.home-assistant.io/getting-started/

Links must have discernible text (2): Standards: WCAG 2.4.4 (A), WCAG 4.1.2 (A) HTML: <a href="#feedback_section" class="title-link" name="feedback_section"></a> Issues: To solve this problem, you need to fix at least (1) of the following:

Element does not have text that is visible to screen readers
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element has no title attribute

Note that I do not repeat the issues regarding color contrast, although some of the elements I saw in the Getting Started page do have contrast issues such as "Edit," "Provide Feedback," and "View given feedback." These links are well below 4.5:1. Note also that 4.49999:1 does not meet the minimum threshold.

Installation URL: https://www.home-assistant.io/installation/

Images must have alternate text (8): Standards: WCAG 1.1.1 (A) HTML:

<img src="/images/installation/green.jpg">
<img src="/images/installation/rpi.jpg">
<img src="/images/installation/yellow.jpg">
<img src="/images/installation/odroid.jpg">
<img src="/images/installation/x86.jpg">
<img src="/images/installation/linux.svg">
<img src="/images/installation/macos.svg">
<img src="/images/installation/windows.svg">

Issues: To solve this problem, you need to fix at least (1) of the following:

Element does not have an alt attribute
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element has no title attribute
Element's default semantics were not overridden with role="none" or role="presentation"

Notes: If these images are considered "decorative" (meaning these images can be removed without any loss of content for screen readers), these images can have an empty alt="" attribute. A null/empty alternate text tells screen readers to ignore the images. Only use null/empty alternate text if it is not enclosed in links (<a></a>).

Elements must meet minimum color contrast ratio thresholds (3): HTML:

Difficulty Level <span class="label easiest">Easiest</span>
Get (Insert Product Name) <a href="/green" class="button accent">Get Home Assistant Green <svg viewBox="0 0 24 24"><path d="M8.59,16.58L13.17,12L8.59,7.41L10,6L16,12L10,18L8.59,16.58Z"></path></svg></a>
View Tutorial <a href="https://green.home-assistant.io" class="button" target="_blank">View tutorial <svg viewBox="0 0 24 24"><path d="M8.59,16.58L13.17,12L8.59,7.41L10,6L16,12L10,18L8.59,16.58Z"></path></svg></a>

Issues:

Element has insufficient color contrast of 2.29 (foreground color: #04b154, background color: #e8e6f0, font size: 12.0pt (16px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.77 (foreground color: #ffffff, background color: #34b155, font size: 10.5pt (14px), font weight: bold). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 2.62 (foreground color: #ffffff, background color: #03a9f4, font size: 10.5pt (14px), font weight: bold). Expected contrast ratio of 4.5:1

Notes: I do not need to repeat the same issues again for the difficulty level, "get product" button, and the "view tutorial" button. What gets fixed for the three elements can get fixed in the rest of the page, especially the "get tutorial" buttons. (Actually, structurally those are links but are styled as buttons.)

Links must have discernible text (15): Standards: 2.4.4 (A), 4.1.2 (A) HTML:

<a class="title-link" name="plug-and-play-with-home-assistant-green" href="#plug-and-play-with-home-assistant-green"></a>
<a class="title-link" name="home-assistant-green" href="#home-assistant-green"></a>
<a class="title-link" name="diy-with-raspberry-pi" href="#diy-with-raspberry-pi"></a>
<a class="title-link" name="install-home-assistant-on-raspberry-pi" href="#install-home-assistant-on-raspberry-pi"></a>
<a class="title-link" name="extend-with-home-assistant-yellow" href="#extend-with-home-assistant-yellow"></a>
<a class="title-link" name="home-assistant-yellow" href="#home-assistant-yellow"></a>
<a class="title-link" name="install-on-other-hardware" href="#install-on-other-hardware"></a>
<a class="title-link" name="install-home-assistant-on-odroid-devices" href="#install-home-assistant-on-odroid-devices"></a>
<a class="title-link" name="install-home-assistant-on-x86-64-machines" href="#install-home-assistant-on-x86-64-machines"></a>
<a class="title-link" name="advanced-installation-methods" href="#advanced-installation-methods"></a>
<a class="title-link" name="install-home-assistant-on-linux" href="#install-home-assistant-on-linux"></a>
<a class="title-link" name="install-home-assistant-on-macos" href="#install-home-assistant-on-macos"></a>
<a class="title-link" name="install-home-assistant-on-windows" href="#install-home-assistant-on-windows"></a>
<a class="title-link" name="install-home-assistant-on-other-systems" href="#install-home-assistant-on-other-systems"></a>
<a href="#feedback_section" class="title-link" name="feedback_section"></a>

Issues: To solve this problem, you need to fix at least (1) of the following:

Element does not have text that is visible to screen readers
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element has no title attribute

Home Assistant Green URL: https://www.home-assistant.io/green

Elements must meet minimum color contrast ratio thresholds: Standards: WCAG 1.4.3 (AA) HTML:

<span class="span-white">Plug it in. </span>
<span class="span-white">Use the app. </span>
<div class="stats-number large">1.8 GHz</div>
<div class="stats-number large">4 GB</div>
<div class="stats-number large">32 GB</div>

Issues:

Element has insufficient color contrast of 1.83 (foreground color: #18bcf2, background color: #ddedf0, font size: 11.5pt (15.4px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 1.83 (foreground color: #18bcf2, background color: #ddedf0, font size: 11.5pt (15.4px), font weight: normal). Expected contrast ratio of 4.5:1
Element has insufficient color contrast of 1.87 (foreground color: #14cc9e, background color: #f2f4f9, font size: 45.0pt (60px), font weight: bold). Expected contrast ratio of 3:1
Element has insufficient color contrast of 1.87 (foreground color: #14cc9e, background color: #f2f4f9, font size: 45.0pt (60px), font weight: bold). Expected contrast ratio of 3:1
Element has insufficient color contrast of 1.87 (foreground color: #14cc9e, background color: #f2f4f9, font size: 45.0pt (60px), font weight: bold). Expected contrast ratio of 3:1

Links must have discernible text (1): Standards: 2.4.4 (A), 4.1.2 (A) HTML: <a href="/green" id="w-node-f82aa316-050e-d74a-ecac-509973726292-3f61e7c1" class="brand w-nav-brand"><img src="/images/green/HA%20Green%20Logo.svg" loading="lazy" height="" alt="" width="300" class="image-brand"></a>

Issues: To solve this problem, you need to fix at least (1) of the following:

Element does not have text that is visible to screen readers
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element has no title attribute

Notes: I'm not sure why an image of text (WCAG 1.4.5) is used. A regular text that says "Home Assistant Green" should satisfy Success Criterion 2.4.4 and 4.1.2.

Home Assistant Green - View Tutorial URL: https://green.home-assistant.io/

Images must have alternate text (5): HTML:

<img src="/images/green_getting-started_prereq.png">
<img src="/images/green_connect_ethernet.webp">
<img src="/images/green_connect_power.webp">
<img src="/images/green_yellow_heartbeat.webp">
<img src="/images/getting_started_04.png">

Issues: To solve this problem, you need to fix at least (1) of the following:

Element does not have an alt attribute
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element has no title attribute
Element's default semantics were not overridden with role="none" or role="presentation"

Frames must have an accessible name (1): Standards: WCAG 4.1.2 (A) HTML: <iframe width="650" height="365" src="https://youtube.com/embed/u8sk6B8_Qkc?start=33" title="" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen=""></iframe> Issues: To solve this problem, you need to fix at least (1) of the following:

Element has an empty title attribute
aria-label attribute does not exist or is empty
aria-labelledby attribute does not exist, references elements that do not exist or references elements that are empty
Element's default semantics were not overridden with role="none" or role="presentation"

<ul> or <ol> must only directly contain <li>, <script, or <template> Standards: 1.3.1 (A) HTML: <ul> Issues: List element has direct children that are not allowed: br

The rule of thumb is that if there are any new widgets that I have not seen before, I list it here. What can be fixed in one page can get fixed in other pages except for widgets that are specific to the page.

I would like to go over the Installation page, but I have work to do, so I will come back later and list any additional issues I can find after work. Please note that my accessibility testing and my findings are of my own, so I only found issues voluntarily. I'm not sure if that's the proper way to make a disclaimer here, but I'm only doing this on my free time.

Update: Okay, looks like I'm going to have to clean up the formatting issues after work...

Update 2: I think I might have encountered a bug with Markdown where back ticks are used to surround the HTML and it seems certain HTML code must have mangled up with the formatting. So my workaround is to use 3 back ticks for multi-line code and that should solve the problem with Markdown.

Update 3: I found more issues in more web pages, but I'm going to take a break and come back at a later time.

URL

https://www.home-assistant.io/

Version

N/A

Additional information

No response

home-assistant / home-assistant.io