python / python-docs-theme

Sphinx theme for Python documentation
Other
75 stars 58 forks source link

A11y: Increase the target area for single-letter index links #103

Closed hugovk closed 1 year ago

hugovk commented 1 year ago

Fixes https://github.com/python/cpython/issues/101109.

Sphinx auto-generates index pages for entries with .. index::.

At the top of these pages:

It generates a list of links to each index initial letter:

image

However, these links are narrow and have very small clickable target areas, most around 10-15 pixels wide, and "I" is only ~5 pixels wide:

image

They can be hard to click for those with physical issues that make small, precision movements difficult.

WebAIM say:

The danger in using single characters as links—or in using any sort of small link (such as a 10 pixel by 10 pixel graphic)—is that some users will have difficulty clicking on such a small area. Someone with cerebral palsy, for example, may be able to use the hands to manipulate a mouse, but may have difficulty with the precise movements and muscle control necessary to click on a small link. Authors can limit these issues by increasing the size of small links, increasing the font size of single character links, or making the target area larger by including whitespace (such as CSS padding) within small link. Additionally, small adjacent links should have adequate whitespace (such as link CSS margins) between them to minimize users inadvertently clicking the wrong link.

So let's improve accessibility and make:

the target area larger by including whitespace (such as CSS padding) within small link

Here's a demo with this PR:

image

Which gives us a width of around 25-30px for most and ~21px for "I":

image
hugovk commented 1 year ago

(Rebased to build RTD preview: https://python-docs-theme-previews--103.org.readthedocs.build/en/103/genindex.html)