Accessibility Errors in FreeCodeCamp's Technical Documentation Project Implementation and Instructions

Composed Monday, December 16, 2024

Introduction

What is FreeCodeCamp?

FreeCodeCamp is pretty universally recommended as a great resource for new programmers looking to dip their toes into the basics of HTML, CSS, and Javascript, among other things. Folks can learn the basics of Responsive Design and receive a Responsive Design Certificate after going through a series of modules and completing a handful of projects.

As an aspiring accessibility professional with little technical expertise, I have used FreeCodeCamp to learn HTML, CSS, and Responsive design. I was particularly excited to learn that FreeCodeCamp had gone through their material to try to emphasize accessibility. They even have a module, titled 'Learn Accessibility by making a Quiz,' dedicated to accessible webpages.

And let me rip off the bandaid now. Nobody has double-checked that the accessibility advice they give is any good. It often is not good, and accessibility continues to be underemphasized across all of the material that I've seen so far.

The Technical Documentation Project

We'll explore this thesis of mine in the Technical Documentation Project, the third project that one needs to complete in order to receive their Responsive Design Certification. This project does not dispense bad accessibility advice inasmuch as it simply forgets about the concept altogether. It makes some very elementary web accessibility mistakes.

They are so obvious that I bet you too can spot them. If you like, you can read the Technical Documentation Project Instructions for yourself, and view FreeCodeCamp's Demo.

I do encourage you to take a look, as the rest of this article depends on that as context.

You can read the rest of this article either on this current page, or on my completed technical documentation project. Dark Mode is not supported on this project.

Landmarks Best Practices

According to Deque, you ought to limit the amount of <header> elements you use. You should also limit the number of <footer> and <main> landmarks you use to basically one per page.

Understand that the semantic role of these landmarks are primarily there to serve screen reader technologies. Within the WAI-ARIA specification that provides ways to create these landmarks in separate ways using the aria roles, role="banner", role="content-info" and role="main", the specification specifically prescribes only one use of these roles per page.

If there is more than one, these landmarks become rather redundant. It is for this reason that the HTML elements ought to be similarly treated. While not explicitly forbidden in the HTML5 specification, it just makes sense if we want to preserve the functional role these play.

FreeCodeCamp asks us to implement no less than a minimum of six <header> elements into our technical documentation project, alongside an enormous amount of <section> elements.

Note that the FreeCodeCamp technical documentation project seems to rely on the <header> role to provide headings. This is not the element they should have relied on for this.

Semantic Headings

They instead only needed to rely on semantic hierarchical headings: <h1> and <h2> and etc.

In my implementation of this project, I have marked my headings up semantically. FreeCodeCamp doesn't do this, and thus fails SC 1.3.1 Info and Relationships.

None of the content that is visually styled to be a header are announced as headings in FreeCodeCamp's version of the technical documentation site. Instead, they are read out just as any other text.

This is also inconvenient for screen-reader users when they are navigating through a page. Screen-reader users very often browse content by semantic headings. I have heard anecdotes that headings are used more often to browse than landmark regions are.

While it seems the FreeCodeCamp team has taken it upon itself to use more landmarks for the benefit of screen-reader users, they ultimately end up ridding themselves entirely of another mechanism that can accomplish the exact same task.

Another thing that I've done in my implementation is organizing the sub-navigation links into a formal list. There is general agreement in the accessibility world that this is nice to have.

Page Title

FreeCodeCamp's implementation also misses some very basic web accessibility freebies.

To meet SC 2.4.2 Page Titled, one only needs to provide a meaningful page title. One does so by adding a <title> element in the <head> element. Ideally, you would provide both the name of the website and the name of the specific subpage, but that is merely a best practice and not necessary.

The most important thing is to provide a title. However, FreeCodeCamp's <head> element within their sample page only contains a <link> element to their stylesheet.

I can understand having a sparse page in order to not give the learner too many hints, and to make academic misconduct slightly harder. But at least make your sample project accessible, please.

Additionally, having a valid title attribute is not one of the instructions provided in the technical documentation project's instructions. In not modelling good accessible practices, and in not requesting the learner to implement them, I am sure that many implementations of this project will simply neglect it.

Page Language

The second freebie missed results in a failure of SC 3.1.1 Language of Page. They miss the lang attribute in their own implementation, and do not require the learner to implement it into their own implementation.

The lang attribute is important because it informs the screen reader what pronounciation rules it should load. Especially in cases where the screen reader's default pronounciation ruleset is something other than English, the lang attribute is useful. The same rationale holds for refreshable Braille displays. Different languages are encoded into Braille differently, and the refreshable Braille display must be notified which Braille standard it should be using.

Including the language of a page is also a valuable practice within internationalization. Here's a non-exhaustive list of why the lang attribute is important, taken from the W3C Internationalization Working Group.

Accessible Scrolling Areas

Finally, FreeCodeCamp doesn't properly account for accessibility when implementing their responsive design. They have their document navigation sidebar collapse into a vertical scrolling ares.

Their implementation is not unusable. As the scrolling area only consists of interactive components, the scrolling area is usable by keyboard-only users and users of technology that rely on keyboard-only functionality. If the scrolling area consisted primarily of non-interactive content, some extra care might have to be deployed in order to accomodate scrolling functionality for all users.

However there still is another problem. The scrolling area itself will be treated as an interactive component by some browsers, which means that it needs an accessible name. This is required to meet SC 4.1.2 Name, Role, Value. In this project, I've assigned one via aria-labelledby.

<h2 id="toc">Table of Contents:</h2> <ul aria-labelledby="toc" role="list">

The role of list there accounts for a weird behaviour in Safari that happens when list-style-type is set to none.

This increases the verbosity of this scrolling area across the board, even when it is in the responsive mode that doesn't scroll. I used aria-hidden=true on the tag used for aria-labelledby but some might not like that I've chosen that approach. I simply prefer it aesthetically.

For a robust explanation on accessible keyboard scrolling areas, please read Keyboard-Only Scrolling Areas by Adrian Roselli.