Fixed #36460 -- Improve accessibility and add new feature to column sorting in admin ChangeList. #19564

Antoliny0919 · 2025-06-14T05:21:16Z

Trac ticket number

ticket-36460

Branch description

I updated the design of the ChangeList column sorting to improve accessibility.

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.

sarahboyce · 2025-06-18T12:37:41Z

When the table column is small and the column is not sorted, the sorting icons overlap

Also when testing with a screen reader, the column header is not announced with the buttons
Perhaps this gives an example of what we might want to try and achieve: https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/sortable-table/

We also have no test coverage for generating screenshots with the change list which might be nice to add

Antoliny0919 · 2025-06-18T21:52:53Z

When the table column is small and the column is not sorted, the sorting icons overlap

Also when testing with a screen reader, the column header is not announced with the buttons Perhaps this gives an example of what we might want to try and achieve: https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/sortable-table/

We also have no test coverage for generating screenshots with the change list which might be nice to add

Thank you, sarahboyce. Even though I already referred to the article you provided and worked on it, reading it again made me realize that my work was lacking in many ways. I will do my best to review it carefully and redo the work.

Antoliny0919 · 2025-06-21T05:44:13Z

@sarahboyce I might be misunderstanding something, but I have a question...

When applying the approach where the column header is announced together with the button, it seems necessary to have only a single sort button inside each column (like in the W3C sortable table example).

If we adopt this method, the sort order would cycle like this: none → ascending → descending → none
I’m a bit concerned that it may reduce some of the flexibility we currently have such as being able to directly choose a sort direction from either state.

Do you think the benefit of having just a single sort button per column outweighs that trade-off?
Personally, I’m leaning toward keeping the current flexibility, but I’d love to hear your thoughts.

sarahboyce · 2025-06-23T07:58:13Z

When applying the approach where the column header is announced together with the button, it seems necessary to have only a single sort button inside each column (like in the W3C sortable table example).

I don't know if the @django/accessibility team has examples of accessible tables with multiple sort buttons.
It does seem quite a common pattern to have to click on a sort button multiple times to get the sort direction you want so I don't think adopting that is too big of an issue

Currently in this PR:

the buttons don't announce what they are sorting when I am focused on the button (not sure if this will be fixed via a single button or "aria-labelledby" etc)
the animation of the sort buttons is too much. I know they already had some "movement" but with the two sorts together this very distracting. I would be tempted to remove the animation and have a different way to indicate it's clickable if the color change is not enough
just noticed that in light mode the grey toggle icon against the selected column grey doesn't have sufficient color contrast
the aria-sort attribute would be good to add in

Antoliny0919 · 2025-06-23T11:04:53Z

I don't know if the @django/accessibility team has examples of accessible tables with multiple sort buttons. It does seem quite a common pattern to have to click on a sort button multiple times to get the sort direction you want so I don't think adopting that is too big of an issue

I agree. It is common to have only one sort button. I tried to preserve the existing structure as much as possible. 😅

the buttons don't announce what they are sorting when I am focused on the button (not sure if this will be fixed via a single button or "aria-labelledby" etc)

Yes, When the button is focused, information such as the item, sort direction, and priority should be announced.

the animation of the sort buttons is too much. I know they already had some "movement" but with the two sorts together this very distracting. I would be tempted to remove the animation and have a different way to indicate it's clickable if the color change is not enough

I believe it’s best if the visual cues can be understood through color changes alone. If possible, I feel it would be better to remove the animations (I also find the current animations to be quite cluttered).

the aria-sort attribute would be good to add in

As far as I know, the aria-sort attribute is recommended to be used on only one column.
Hmm... I’m not sure how to apply it in tables like ChangeList, where multiple columns can be sorting criteria.
I’ll have to ask the accessibility team about this...

Antoliny0919 · 2025-06-30T01:48:51Z

Changed...

Unsorted State

In an unsorted state, sortable columns are marked with the symbol "△".
This visual indicator makes it easy to identify which columns are sortable at a glance.

Sorted State

When columns are sorted, the symbols "▲" and "▼" are used to indicate the sorting direction.
Additionally, if two or more columns are sorted, the sorting priority is also displayed.

Sorting is performed in the following directions.
none -> ascending -> descending -> none

Screen reader

When a sortable header is focused, the sorting direction is announced.

none: toggle sorting ascending
ascending: toggle sorting descending
descending: toggle sorting remove

When multiple columns are sorted, indicate the sorting priority (for all sortable columns).

++ Additionally...

Information related to aria-sort is also provided.

Color Contrast

In dark mode, the color contrast of the column in a sorted state has been adjusted to meet the WCAG AA requirements.

Before

Admin

Color contrast

After

Admin

Color contrast

sarahboyce

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

The "no sort" icon appears to be bigger or misaligned to the sorted ascending/descending icons. I also think I prefer them to be right aligned to the column as this design pattern seems to be the most common

I will let the accessibility team give feedback on the approach 👍

Antoliny0919 · 2025-07-19T06:41:28Z

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

The "no sort" icon appears to be bigger or misaligned to the sorted ascending/descending icons. I also think I prefer them to be right aligned to the column as this design pattern seems to be the most common

I will let the accessibility team give feedback on the approach 👍

Sort priority and sort button were originally positioned on the right side of the column, and I’ve adjusted them to remain in the same position.
I’ve tested the sort button size across various environments, including mine, and didn’t notice any issues.
Would you mind sharing the environment you used for testing? 🥲

sarahboyce · 2025-07-21T07:56:24Z

Testing with Firefox 140.0.4 on Ubuntu

Antoliny0919 · 2025-07-26T11:18:49Z

Changed..

Light Mode

Sorted column(Name, Age)

bg(#447996)
fg(#ffffff)

Unsorted Column(Gender)

bg(#f8f8f8)
fg(#666666)

Dark Mode

Sorted Column(Name, Age)

bg(#30586e)
fg(#eeeeee)

Unsorted Column(Gender)

bg(#212121)
fg(#d0d0d0)

sarahboyce

Thank you for the updates!

sarahboyce · 2025-08-07T15:00:13Z

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

+table thead th.sortable:not([aria-sort]) div span:nth-last-child(2):after,
+table thead th.sortable[aria-sort="ascending"] div span:nth-last-child(2):after {
+    content: "▲";
 }


Suggested change

table thead th.sortable:not([aria-sort]) div span:nth-last-child(2):after,

table thead th.sortable[aria-sort="ascending"] div span:nth-last-child(2):after {

content: "▲";

}

table thead th.sortable:not([aria-sort]) div span:nth-last-child(2):after {

content: "⇅";

}

table thead th.sortable[aria-sort="ascending"] div span:nth-last-child(2):after {

content: "▲";

}

I think we need a different icon for the sortable column, as currently if I am hovering over the column and click through, it's hard to tell that there is 3 states

I really like the Unicode symbol you suggested :0
I think it would be great for indicating that sorting is available.
Thank you !!!

sarahboyce · 2025-08-07T15:04:04Z

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

-thead th.sorted {
-    background: var(--selected-bg);
+thead th.sorted,
+table thead th.sortable a:hover {


Suggested change

table thead th.sortable a:hover {

table thead th.sortable:hover {

This issue was pre-existing but it is more pronounced when the background is blue. Currently only the inner background changes on hover (and I don't like it personally)
This suggestion doesn't quite work because when you are on the th boarder, rather than the a tag, the text is grey and unreadable but hopefully you understand what I mean

You mean that in light mode, when you hover the pointer over the edge of a th, the background color of the th changes but the text color does not, making it hard to distinguish, right?
I think it should be fine to revert the background color back to the original 😁
(foreground color will be fixed to a single color.)

sarahboyce · 2025-08-07T15:13:27Z

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

+    --table-sorted-bg: #447996;
+    --table-sorted-fg: #fff;


I personally preferred using shades of grey for the sorted columns but that is just personal preference (not sure if we have any design spec around colors)

I agree.
In fact, the main reason I changed the background color was because I was trying to indicate sorting using only two characters("▲", "▼")

sarahboyce · 2025-08-07T15:15:13Z

django/contrib/admin/templatetags/admin_list.py

+            model_admin=cl.model_admin,
+            return_attr=True,
+        )
+        priority_description += "%s priority %d, " % (text, index + 1)


We should probably make all descriptions translatable and you might want to think how best to make this clear for translators

I've been thinking about this, and how about making it like this?
_("Next sort direction, %(direction)s, Sort priority, %(priority)s")

The sentence will probably be something like the following...
"Next sort direction, ascending, Sort priority, col_xx, col_yy, col_zz"
Could I get some advice on this part? 🥲

…umn sorting in admin ChangeList.

Antoliny0919 force-pushed the ticket_36460 branch from d1d302d to 9995f30 Compare June 14, 2025 05:23

sabderemane added this to django accessibility improvements Jun 15, 2025

github-project-automation bot moved this to New in django accessibility improvements Jun 15, 2025

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

Antoliny0919 force-pushed the ticket_36460 branch 5 times, most recently from e5422bb to 9eb02d4 Compare June 21, 2025 05:41

Antoliny0919 force-pushed the ticket_36460 branch from 9eb02d4 to 4a3a0de Compare June 21, 2025 05:46

Antoliny0919 force-pushed the ticket_36460 branch 2 times, most recently from 06d96e2 to 7fd300d Compare June 26, 2025 11:31

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

Antoliny0919 force-pushed the ticket_36460 branch 4 times, most recently from 45b28fa to 712cda0 Compare June 29, 2025 23:48

Antoliny0919 force-pushed the ticket_36460 branch from 712cda0 to e071317 Compare June 30, 2025 02:06

sarahboyce reviewed Jul 18, 2025

View reviewed changes

Antoliny0919 force-pushed the ticket_36460 branch from e071317 to 9769408 Compare July 19, 2025 06:36

Antoliny0919 force-pushed the ticket_36460 branch 4 times, most recently from 0af8137 to 1471861 Compare July 26, 2025 11:33

sarahboyce reviewed Aug 7, 2025

View reviewed changes

Fixed #36460 -- Improved accessibility and updated new feature to col…

f2a4638

…umn sorting in admin ChangeList.

Antoliny0919 force-pushed the ticket_36460 branch from 1471861 to f2a4638 Compare August 9, 2025 09:35

	table thead th.sortable a:hover {
	table thead th.sortable:hover {

Uh oh!

Fixed #36460 -- Improve accessibility and add new feature to column sorting in admin ChangeList. #19564

Are you sure you want to change the base?

Fixed #36460 -- Improve accessibility and add new feature to column sorting in admin ChangeList. #19564

Uh oh!

Conversation

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

Uh oh!

Trac ticket number

Branch description

Checklist

Uh oh!

sarahboyce commented Jun 18, 2025

Uh oh!

Antoliny0919 commented Jun 18, 2025

Uh oh!

Antoliny0919 commented Jun 21, 2025

Uh oh!

sarahboyce commented Jun 23, 2025

Uh oh!

Antoliny0919 commented Jun 23, 2025

Uh oh!

Antoliny0919 commented Jun 30, 2025

Changed...

Unsorted State

Sorted State

Screen reader

Color Contrast

Before

After

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 commented Jul 19, 2025

Uh oh!

sarahboyce commented Jul 21, 2025

Uh oh!

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

Uh oh!

Changed..

Light Mode

Sorted column(Name, Age)

Unsorted Column(Gender)

Dark Mode

Sorted Column(Name, Age)

Unsorted Column(Gender)

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

sarahboyce Aug 7, 2025

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Aug 9, 2025

Choose a reason for hiding this comment

Uh oh!

sarahboyce Aug 7, 2025

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Aug 9, 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!

sarahboyce Aug 7, 2025

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Aug 9, 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!

sarahboyce Aug 7, 2025

Choose a reason for hiding this comment

Uh oh!

Antoliny0919 Aug 9, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Antoliny0919 commented Jun 14, 2025 •

edited

Loading

Antoliny0919 commented Jul 26, 2025 •

edited

Loading

Antoliny0919 Aug 9, 2025 •

edited

Loading

Antoliny0919 Aug 9, 2025 •

edited

Loading