Card links do not have a discernible name (accessibility issue)

[bertiewooster]

Describe the bug

context
When I use cards on a Sphinx site, with Furo theme

expectation
I expected the card link to have a discernible name so people using screen readers can tell what the link leads to

bug
But instead the link has no discernible name
Here's the warning from Lighthouse's accessibility checker:

Links do not have a discernible name
Link text (and alternate text for images, when used as links) that is discernible, unique, and focusable improves the navigation experience for screen reader users.

problem
This is a problem for people using screen readers because they will not be read a name for the link that will help them decide if they should follow the link.

Reproduce the bug

Here is a page built using cards. Here is the corresponding accessibility report from Lighthouse.

List your environment

MyST-parser: latest (0.18.0)
Furo theme: latest (2022.06.21)
Sphinx: 4.5.0

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[chrisjsewell]

I expected the card link to have a discernible name

Hey @bertiewooster, I'm afraid I don't know exactly what this means.
Card links are simply constructed as regular nodes.reference docutils nodes, so it should not act differently to any other sphinx link?

It would perhaps be really helpful, if you could post what the current generated HTML is, for a minimal card example, and what the desired HTML would be?

[bertiewooster]

Hi @chrisjsewell, thanks for your response.

Current generated HTML

Hopefully this pre-existing example will clarify the accessibility issue.

With a card

The first card link (anchor) is

<a class="sd-stretched-link reference internal" href="[install.html#installation](view-source:https://output.circle-artifacts.com/output/job/9bb30655-e91f-4697-be3a-02655c6616d6/artifacts/0/doc/_build/html/install.html#installation)"><span class="std std-ref"></span></a>

There is no name for the link (link text) indicating the topic of the link: If you were to put this HTML in a web page absent its context, nothing would be presented to the user because there is no text (or image) within the anchor element. Therefore, a screen reader will not be able to speak a useful name to a visitor, so they will now know if they want to follow this link.

Without a card

Contrast this with the same link without using cards

<a class="reference internal" href="[install.html#installation](view-source:https://docs.sympy.org/dev/install.html#installation)"><span class="std std-ref">Installation</span></a>

where the link text is Installation, which a screen reader will speak to the visitor, who can then decide if they want to follow this link.

Desired HTML

Naive, sub-optimal approach

If the link text Installation were simply added inside the card anchor, it would

• address the accessibility issue because it would be spoken by a screen reader, but
• appear twice when viewed on a screen: once for the link text and once for the card.

Approach which should work for both visual display and screen readers

I found the recommendation to include aria-label and aria-hidden="true" so for example I believe this HTML would work:

<a class="sd-stretched-link reference internal" href="[install.html#installation](view-source:https://output.circle-artifacts.com/output/job/9bb30655-e91f-4697-be3a-02655c6616d6/artifacts/0/doc/_build/html/install.html#installation) "aria-label="Installation" aria-hidden="true"><span class="std std-ref"></span></a>

I checked that making such a modification does not cause Installation to appear twice on a screen. It would be best to verify that a screenreader speaks Installation (as the aria-label).

An expert in accessibility and HTML might have a better solution.

[chrisjsewell]

Thanks for the explanation @bertiewooster 😄 I'll see what I can do about achieving this

[chrisjsewell]

See #89, for what I felt was the simplest solution. Thoughts welcome?