Fixed #34041 -- Improve accessibility of admin page breadcrumbs area. #19492

Antoliny0919 · 2025-05-22T07:31:33Z

Trac ticket number

ticket-34041

Branch description

Continue farita1699's PR

I have improved the accessibility of the breadcrumb area in the admin page as follows.

I updated the breadcrumb links to be structured as <li> items within an <ol> list.

This change allows screen reader users to know how many items are present in the breadcrumbs area.

I added aria-current="page" to the element representing the current page in the breadcrumb area.

This change allows screen reader users to identify the current page by announcing it as the "current page" when navigating to the corresponding breadcrumb item.

I added an tag to the last item in the breadcrumbs.

This change makes the last breadcrumb item accessible via the "Tab key" when using a screen reader.

Checklist

This PR targets the main branch.
The commit message is written in past tense, mentions the ticket number, and ends with a period.
I have checked the "Has patch" ticket flag in the Trac system.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.
I have attached screenshots in both light and dark modes for any UI changes.

Antoliny0919 · 2025-05-22T07:36:18Z

django/contrib/admin/static/admin/css/base.css

Since the last breadcrumb item was changed to an tag, it now has an underline.
Should we remove the underline?
(The ticket mentioned that the existing design should be preserved as is.)
Additionally, removing the underline would likely require a selector with higher specificity. 🥲

As far as I understand the ticket, yes, the underline should be removed. There doesn't seem to be a utility class for that in the CSS so far, so you have to add something like:

.nolink { color: inherit !Important; text-decoration: none !Important; }

Antoliny0919 · 2025-05-22T07:39:07Z

django/contrib/admindocs/templates/admin_doc/template_detail.html

In admin-doc, there is no page like template_index for templates.
Therefore, when accessing the detail page, I set the href of the breadcrumb item labeled "template" to an empty string ("").
Is there a better way to handle this?

Antoliny0919 · 2025-05-22T07:43:15Z

django/contrib/admin/templates/admin/500.html

How about providing the breadcrumb separator "›" using CSS content?
If the separator is added via CSS content, screen readers won’t focus on elements like "›", which might improve accessibility.

The relevant example in ATAG also recommends to use CSS for this. However, I think CSS content will still show up in the accessibility tree. So maybe you have to use borders instead? I am not sure about this though, better test with a screen reader.

I saw this implemented with CSS on another site and tested it with a screen reader.
I'll try applying it myself and test it with a screen reader as well.

I found that when the ">" is implemented using content, it is accessible to screen readers. 😥
However, when content is used to render an image and a size is specified inside the content, screen readers do not recognize it.
If we actually want to apply this, using the mask property would allow for color customization as well.

You can add an alternative text to CSS-generated content. Since here it's decorative, the alternative should be empty. Like this:

.myclass::after { content: ">" / ""; }

Antoliny0919

I've left comments on a few parts where I had difficulty making decisions...

Antoliny0919 · 2025-05-22T07:46:29Z

Could you please review this work? @tut-tuuut 🥰

tut-tuuut · 2025-05-27T15:26:33Z

ooops sorry I did not see the mention, I will review soon!

django/contrib/admin/templates/admin/app_index.html

xi · 2025-05-28T15:23:22Z

I notice you used an unordered list <ul> while both the ticket and ATAG call for an ordered list <ol>. Was that an intentional change?

Antoliny0919 · 2025-05-28T22:07:47Z

I notice you used an unordered list <ul> while both the ticket and ATAG call for an ordered list <ol>. Was that an intentional change?

Thank you for the review @xi . I agree that using

Antoliny0919 · 2025-06-18T07:39:46Z

Using ">" as CSS content also resolves the issue where it was previously displayed incorrectly in RTL mode. 🙌🙌

Before

After

tut-tuuut · 2025-06-18T13:07:41Z

django/contrib/admin/static/admin/css/base.css

Adding alternative to hide the decoration from screen readers:

Suggested change

content: ' \203A ';

content: ' \203A ' / '';

Nice, I didn’t know this approach, now screen readers no longer access unnecessary elements like ">" !

sarahboyce

Thank you!
I think django/contrib/admin/templates/registration/logged_out.html still needs updating 👍

nitpick, make sure commit messages are in past tense (see https://docs.djangoproject.com/en/5.2/internals/contributing/committing-code/#committing-guidelines)

sarahboyce · 2025-06-24T07:46:06Z

django/contrib/admin/static/admin/css/base.css

I think you can also use the css for aria-current=page rather than last child logic here

sarahboyce · 2025-06-24T07:46:45Z

django/contrib/admin/templates/admin/500.html

Suggested change

<li><a href="" aria-current="page">{% translate 'Server error' %}</a></li>

<li><a href="#" aria-current="page">{% translate 'Server error' %}</a></li>

I think hashes are better to prevent a page reload on click

I referred to @thibaudcolas comment from the previous PR regarding this part.
I also agree that using # has its advantages.
Instead of changing the href, how about keeping it as is and applying pointer-events: none?
That way, regular users won’t experience any change on click, but screen reader users can still access the link via keyboard (tab).
What do you think about this approach?

++ This change would also include pagination ...

What you have currently is aligned with https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/examples/breadcrumb/ , so I think you're correct to use href="" and I don't think an update of css is needed 👍

Yes, I’ve reverted the CSS back to its original state.

tests/admin_views/test_nav_sidebar.py

sarahboyce

Thank you for the updates @Antoliny0919 ⭐
This looks good to me

Unfortunately the screen readers I test with do not support the aria-current attribute (https://a11ysupport.io/tech/aria/aria-current_attribute Narrator/Orca). This will need testing and approval from an accessibility team member 👍

…a-current attribute.

Antoliny0919 force-pushed the ticket_34041 branch from edfbf8f to 4d1f73b Compare May 22, 2025 07:32

Antoliny0919 commented May 22, 2025

View reviewed changes

Antoliny0919 force-pushed the ticket_34041 branch 2 times, most recently from e5f107b to 8dc9b31 Compare May 22, 2025 09:58

sabderemane requested a review from a team May 27, 2025 11:24

sabderemane added this to django accessibility improvements May 27, 2025

github-project-automation bot moved this to New in django accessibility improvements May 27, 2025

sabderemane moved this from New to To Review in django accessibility improvements May 27, 2025

xi reviewed May 28, 2025

View reviewed changes

django/contrib/admin/templates/admin/app_index.html Outdated Show resolved Hide resolved

Antoliny0919 force-pushed the ticket_34041 branch 4 times, most recently from 34c389d to 9deaa0b Compare May 31, 2025 01:05

Antoliny0919 mentioned this pull request Jun 8, 2025

Fixed #36127 -- Fixed to display whitespace in object str in admin. #19105

Open

6 tasks

Antoliny0919 force-pushed the ticket_34041 branch from 9deaa0b to 2e3fb7c Compare June 18, 2025 07:36

tut-tuuut reviewed Jun 18, 2025

View reviewed changes

Antoliny0919 force-pushed the ticket_34041 branch from 2e3fb7c to 70aa938 Compare June 18, 2025 21:29

sarahboyce added selenium Apply to have Selenium tests run on a PR screenshots 🖼️ labels Jun 24, 2025

sarahboyce reviewed Jun 24, 2025

View reviewed changes

Antoliny0919 force-pushed the ticket_34041 branch from 70aa938 to 4d82fa4 Compare June 25, 2025 02:41

sarahboyce reviewed Jun 25, 2025

View reviewed changes

Fixed #34041 -- Improved accessibility of admin breadcrumbs using ari…

611e8e9

…a-current attribute.

Antoliny0919 force-pushed the ticket_34041 branch from 4d82fa4 to 611e8e9 Compare June 25, 2025 09:04

thibaudcolas self-requested a review June 26, 2025 12:04

	<li><a href="" aria-current="page">{% translate 'Server error' %}</a></li>
	<li><a href="#" aria-current="page">{% translate 'Server error' %}</a></li>

Uh oh!

Fixed #34041 -- Improve accessibility of admin page breadcrumbs area. #19492

Are you sure you want to change the base?

Fixed #34041 -- Improve accessibility of admin page breadcrumbs area. #19492

Uh oh!

Conversation

Antoliny0919 commented May 22, 2025

Trac ticket number

Branch description

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 left a comment

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 commented May 22, 2025

Uh oh!

tut-tuuut commented May 27, 2025

Uh oh!

Uh oh!

xi commented May 28, 2025

Uh oh!

Antoliny0919 commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Antoliny0919 commented Jun 18, 2025

Before

After

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Jun 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Antoliny0919 commented May 28, 2025 •

edited

Loading

Antoliny0919 Jun 25, 2025 •

edited

Loading