Navbar logos not exposing empty alt text

[BenDMyers]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

When an image is truly decorative (i.e., it doesn't add additional context or information), we can apply alt="" (distinct from not supplying an alt attribute at all). This removes it from screenreader output, reducing clutter. This is especially pertinent for logos inside of links that also contain other link text, such as the typical navbar brand link. W3C's Web Accessibility Initiative's guidance on alt text for functional images includes an example just like this, where they recommend:

In this example, the W3C logo is used to supplement text within a link that leads to the W3C home page. The image does not represent different functionality or convey other information than that already provided in the link text, so a null (empty) value is applied, (alt=""), to avoid redundancy and repetition. In effect the image is a decorative adjunct or visual cue to the link text…

Prior work (#3352 and #3817) enabled Docusaurus users to provide empty strings for these alt properties in their configs. However, when they do so, the logos are provided alts anyways, populated with the site title. As a result, Docusaurus users are not able to meaningfully mark their logos as decorative to reduce screenreader clutter.

Reproducible demo

https://stackblitz.com/edit/github-rvbfnk?file=docusaurus.config.js

Steps to reproduce

1. Navigate to repro on StackBlitz
2. Check docusaurus.config.js, specifically the config for the navbar logo, which should have an alt: '' property.
3. Inspect markup for navbar logo in the preview. Verify that the image has an alt attribute of "My Site", instead of the empty string.
4. Navigate to navbar brand link with a screenreader. Verify that the link is announced as "My Site My Site," because of the alt text duplication.

Expected behavior

If the user supplies an empty string for the logo's alt (distinct from not providing an alt at all, or providing undefined or null), the logo should apply alt="", marking it as decorative for assistive technologies. Screenreaders won't announce the logo, and navigating to the brand link should just announce the site title once.

Actual behavior

When the user supplies an empty string for the logo's alt config, the alt attribute is being populated with the site title. This means that screenreader announcements are cluttered with redundant duplication.

Your environment

Latest versions as used on the StackBlitz playground.
See repro on StackBlitz

Self-service

• I'd be willing to fix this bug myself.

[Josh-Cena]

We should be using ?? instead of || here:

docusaurus/packages/docusaurus-theme-classic/src/theme/Logo/index.tsx

Line 35 in fd87afd

alt={logo.alt || navbarTitle || title}

[BenDMyers]

Found that as well - PR coming very shortly

[Josh-Cena]

Sweet!

Not sure about the navbarTitle || title part, though. If there's alt: undefined, and navbarTitle is empty string (nothing gets rendered), I think we should rightfully use the site title.

[BenDMyers]

So (logo.alt ?? navbarTitle) || title?

[BenDMyers]

Wait, no, that'll have the same issue. It's (logo.alt || navbarTitle) ?? title we want.

[BenDMyers]

Nope, that's not it either. logo.alt ?? (navbarTitle || title) should do it, I think. Booleans are weird.

[Josh-Cena]

1. If logo.alt is ""—we definitely want to obey that and render alt="".
2. If logo.alt is undefined—we infer based on navbarTitle and title. If there's navbarTitle, we use that (that's the current behavior, but as we agreed in Docs: Navbar logo has extra decorative "TypeScript ESLint logo" narration typescript-eslint/typescript-eslint#5213, it leads to duplicate announcements, so we can rethink about it as well).
3. If navbarTitle is falsy (so nothing gets rendered), we have to announce something for the link, so we use title instead.

So yes, logo.alt ?? (navbarTitle || title) is correct.

[BenDMyers]

More context in the discussions on #7659, but we ultimately decided to get a little more opinionated on logo alt text. The new flow is:

1. Has the user supplied any logo alt text (including an empty string)? Use that.
2. If not, has the user supplied a navbar title? If so, the logo complements the navbar title within the link, and so it's decorative. Set the alt to the empty string.
3. If no logo alt or visible navbar title have been provided, provide a fallback alt of the site title.