SPEC 3 — Accessibility

Hi all, I’m thinking about co-authoring SPEC for accessibility! I’ll be focusing on my experience with NumPy, and Isabela will talk about hers later. We’re starting with this opening post so that everyone can add their input and questions!

First, what is accessibility? Accessibility is about making technology accessible to the full range of human experience, which includes disabilities. The rest of this post will focus on implementing accessibility. If you’d like deeper dive into what accessibility means for NumPy specifically, watch out for an upcoming blog post.

In my experience, there are three big problems in implementing accessible technology:

  1. Information overload
  2. Accessing the scope
  3. Individual tweaks for each project

1) Information Overload

The guidelines most referred to are set by W3, the ‘Web Accessibility Initiative of the World Wide Web Consortium’, the main international standards organization for the Internet. It is primarily focused on web pages, but there are many applicable guidelines for non-web UX/UI interfaces as well.

There are three ‘levels’ we can achieve in each area.
In this example, there are different contrast ratios between text and the page background color. A greater contrast ratio helps people with visual disabilities better read text.

People without visual disabilities are also probably struggling to read the first example with 2:1 contrast ratio!

This seems like a simple fix- change the color of the text! However, if you wish to understand more, upon opening the W3 page for visual contrast, it’s easy to feel overwhelmed.

Scrolling down the page, the Key Term section is very extensive. There are many details, numbers and new terms such as ‘relative luminance’.

However this high level of detail is suitable for this page, as this page would be equivalent to reference documentation. It is purposely extensive as it contains guidelines on how to fulfill nearly every occurrence of text on a page.

For more visual examples and less jargon-filled explanation, we can refer to resources that are not from W3, but closely refer to the W3 guidelines. One example would be from WebAIM.
Here is the WebAIM page for visual contrast.

WebAIM still refers to the ‘relative luminance’ guidelines, but begins in a more familiar way, focusing on webpage text styling.

By referring to these guidelines, we can start to access the scope and understand where our projects are falling short.

2) Accessing the Scope

There are a variety of ways to access our projects. There are automated tools, manual testing, CI testing, paying for audits and asking disabled users for their feedback. Factors include time, cost and human cost.

There is a good, quick-glance review every project can make right now. Using an automated accessibility tool, we can to get a tally and grouping of the met and unmet guidelines for your project’s web page.
wave extension
In the above example, we used the WAVE tool, provided by the above-mentioned WebAIM. We put in numpy.org into this page. I’ve also used the WAVE browser extension to compare issues across the site.

These automated tools are great as a quick review. To get a more comprehensive and long-term review, projects can integrate CI testing such as with the open-source pa11y CI test. There are also many companies that provide audits for a fee. At this time, NumPy has not paid for an audit so I cannot comment or provide any recommendations.

3) Individual tweaks for each project

Each project has different needs and sometimes the standard guidelines aren’t sufficient. One example would be the guidelines on providing ‘alt-text’ for mathematical diagrams in the NumPy documentation.

The general guidelines for writing ‘alt-text’ is for visual, subject-based images.

Most guidelines recommend only writing relevant information and being succinct, usually less than 120 characters in total.

However, what is ‘relevant information’ in this histogram made with NumPy and Matplotlib? Is it enough to say ‘A histogram’? ‘A bell-shaped histogram’? ‘A bell shaped histogram that peaks in the center’? Do I need to provide the X and Y axis variance? The number of bins? And how do I fit all this in 120 characters?

We had to do more digging for 1) guidelines for mathematical diagrams 2) alt-text that is longer than 120 characters.

After some more digging, we found an extremely useful resource, the Diagram Center which provides full examples for geographic maps, Venn-diagrams, chemistry and more. We looked their example for bar graphs, understand what would be considered relevant information and adjust it for histograms.

The second problem was that providing all the relevant information would take more than 120 characters. What do we do?

After doing some reading, we found out why 120 characters is recommended in the first place. It is not a hard limit. Instead, it is a courtesy to time of screen-reader users. A very long alt-text may be perfect when the user wants to dig into the information, but unnecessary when quickly scanning a page.

The solution we decided on was having a ‘short-description’ that summarized the overall trend in the diagram, and a separate, optional ‘long-description’ that a user can expand for the full details.
Short-description: A normalized histogram that peaks at (2.0, 0.8).
Long-description: A normalized histogram with 1000 normal deviates with a variance of 0.5^2 and mean 2. It has 50 bins. It is bell-shaped and centered in the middle of the X axis, peaking at (2.0, 0.8).

These tweaks are focused on documentation and web-pages, since NumPy is a library used inside a code editor. In comparison, Spyder is interfaced through its application interface.

One recent step forward Spyder did take was the recent UI/UX overhaul to Spyder 5, which included making clearer, consistent icons. UX/UI works in tandem with accessibility, as clearer interfaces reduce mental overhead and allow everyone to use the technology.

Understanding what a project needs require an understanding why guidelines exist, who they serve and the scope of what can be improved.

Similarities across all projects

Despite these differences, all projects can move towards more accessible

  • websites
  • documentation
  • UX/UI where relevant

Some of these similarities can fixed all at once. For example, NumPy and Pandas both use the PyData Spinx Theme, which has some color-contrast issues.This has been reported upstream. Additionally, the PyData Spinx team is currently implementing CI testing, so that these issues can be flagged and corrected. This way, no-one is re-inventing the wheel- instead we all share a shiny new wheel!

Making the disabled community feel welcome

Open-source project are community-supported, and we need to honesty ask ourselves if we are sufficiently supporting the disabled community. Not just meeting guidelines, but creating a cultural shift.

Each project will best understand what approach to take. For NumPy, we want to create a culture where the disabled community feel welcomed, where they can see that a project is already taking the first step. I’ll expand on this approach in a blog post and post it here once it’s done.

Open to discussion

This is certainly not the final written SPEC. We learnt a lot from other projects, but I mostly covered NumPy here. Let us know of any other tools, audits, community approach, high-priority guidelines, quick fixes, etc. :slight_smile:


Thanks for starting this, Mars!

I’m the aforementioned Isabela. For context, I spend most of my time in the Jupyter (mainly JupyterLab) and Spyder communities and have been talking with the NumPy documentation team about accessible documentation practices. Even across only three communities I’ve found a lot of overlap in accessibility needs and lack of community members with knowledge about accessibility, so I think a SPEC could be a good way to start filling in the gaps and give projects actionable accessibility guidelines (more tailored but based on WCAG).

I’ll write up more specific input in the near future. Thanks for your patience!


Recently a few of us in the Jupyter and NumPy community have been ‘crowd-sourcing’ adding alt-text to images! We are hosting 1-hour workshops where people make low-code contributions using the recent Github Suggestion feature. This removes the barrier of learning git, making it easier for more people to contribute and thus distribute the work across more people.

See the Suggestion feature in action! From a recent NumPy Newcomer’s Hour meeting: ttps://github.com/melissawm/numpy/pull/27

We had first-time contributors and reached a new age group: high schooler.

We’d love to share this approach to more projects! This post will be updated the point person who will help set up the workshop and guidelines once those are ready.


Mars’ summary is great! I think these events have been going well and are going to continue in a few projects (and we’d love to branch out if more projects are interested in this or a similarly scoped topic).

I’ve also been advised to start linking things we’re working on to give context and possible examples of what we think could work across projects. You might notice a bit of a documentation focus in this; it has seemed like a good place to start because it has more overlap and can usually take advantage of existing accessibility tools more than things that might not exist simply as web content.

A (probably incomplete) list of high-level accessibility work across communities:

On another note I’ve been thinking about reasonably scoped SPECs for a team to write, for a team to review, and for a project to implement. I think accessibility as a whole might be too big to be helpful as a single SPEC on its own even if we do want to end up with comprehensive accessibility recommendations long term. To make it easier to manage for all parited, I imagine this could be broken up in a few possible ways like by

  • Type of accessibility technique (like alt text, automated testing, manual testing)

  • Type of interaction needs (similar to WCAG)

  • Type of content (like the needs of code, text, images)

  • Type of typical open source content (like documentation needs, package needs, ui-heavy software needs)



I wanted to bring up a small accessibility issue in displaying MyST-NB directives in the Jupyter interface:

When you define a directives in a Jupyter notebook or MyST-NB notebook, they look fantastic in the final rendered HTML pages, but if you launch the notebook it displays the directive as rendered HTML in the markdown cell.

This makes creating alt-text for a matplotlib figure difficult to accomplish. The best alt text is to create a plot directive and write a detailed alt-text, but then users that open the notebook in a Jupyter interface are shown the alt-text directive.

I’m not sure what the best path forward is, but maybe it could be a combination of adding features to Jupyter + Matplotlib generated plots?


Hi Ryan (cooperrc), thanks for bringing that up! In our recent workshops where contributors help add alt-text, there were also similar question of adding alt-text to images or graphs that are dynamically created and not in static file formats such as the usual JPG or PNG. It seems like this is a re-occurring issue across projects.

Regarding Isabela’s suggestion, I can see how a single SPEC on accessibility could be broken down to help a team implement its many aspects! Perhaps the first SPEC on this topic could provide an overview and have a longer section of what we (in the NumPy and Jupyter space) have experienced, which so far is focused on images, text, basic UI interaction and testing. As we see more of what other projects need, more SPECs could be written, such as specifically for package needs.

Additionally, if you’d like deeper dive into what accessibility means for NumPy specifically, check out this blog post! The content similar to my initial SPEC post, but with a focus on NumPy’s journey in 2021.

1 Like