Problem/Motivation

#3584347: Deprecate and replace system_admin_compact_mode() moved the logic which controls the visibility of descriptions from the backend to the frontend. The Hide descriptions / Show descriptions link was inherited from the previous design. The use of a link isn't ideal from an accessibility POV:

As per Curtis Wilcox on slack:

Importantly, the current control changes its name to convey the state, "Hide descriptions" / "Show descriptions"; a control should not use both attributes and name changes to convey state. Attribute changes are more reliably conveyed to screen reader users.

Steps to reproduce

  1. Install Drupal using the Standard profile.
  2. Apply or check out the merge request from #3584347.
  3. Sign in as a user with the Administer permissions permission.
  4. Visit /admin/people/permissions.
  5. Locate the Hide descriptions link above the permissions table.
  6. Inspect the control using browser accessibility tools or a screen reader.
  7. Confirm that it is exposed as a link, although it changes the state of the page rather than navigating somewhere.
  8. Activate the link using Enter.
  9. Confirm that:
  10. Permission descriptions are hidden.
  11. The control’s accessible name changes to Show descriptions.
  12. The control still exposes no programmatically determinable on/off state.
  13. With focus on the control, press Space.
  14. Confirm that Space does not activate it, despite the control behaving like a button or switch.

Actual result: The control is exposed as a link. Its name changes between “Hide descriptions” and “Show descriptions,” but its state is not programmatically conveyed. It also lacks the expected Space-key behaviour of a button or switch.

Expected result: The control uses appropriate toggle semantics, exposes its current state programmatically, and supports the standard keyboard interaction for its role. Its accessible name remains stable.

Show link

Proposed resolution

Curtis Wilcox further suggests:

Because there's no mixed state (there's no way a user could show only some of the descriptions), [...] a toggle switch could be implemented using <input type="checkbox" switch>; only Safari has shipped support for the HTML switch attribute but there's a robust polyfill for it.

I mainly suggest using that not because I think Safari's move to ship switch was good but because I know the polyfill has done a good job on all the design considerations and I know many others have not. For instance, the "thumb" part of the switch must be at the start position when it's off and the end position when it's on; in left-to-right languages like English, that's left for off, right for on.

The HTML might be something like this (I mildly prefer the input being visually before the label but either is fine):

<div class="compact">
  <input id="compact-switch" type="checkbox" switch>
  <label for="compact-switch">Hide Descriptions</label>
</div>

Remaining tasks

User interface changes

Introduced terminology

API changes

Data model changes

Release notes snippet

CommentFileSizeAuthor
#15 3593539-replace-compact-mode-link-with-switch-2.patch13.02 KBmgifford
#15 Slider-deselected.png293.58 KBmgifford
#15 Slider-selected.png300.12 KBmgifford
#14 3593539-replace-compact-mode-link-with-switch.patch14.37 KBmgifford
#13 Hide.png94.32 KBmgifford
#13 Show.png93.4 KBmgifford

Comments

znerol created an issue. See original summary.

znerol’s picture

znerol commented
Parent issue: #3584347: Deprecate and replace system_admin_compact_mode() »
Related issues: +#3584347: Deprecate and replace system_admin_compact_mode()
znerol’s picture

znerol commented
Title: Replace compact mode link with a switch for better accessibility » Replace compact mode link with a switch to improve accessibility
kentr’s picture

kentr commented

To me, it would be good to create a generic Switch element that can be used in other cases. The admin compact mode toggle could then use that.

Default admin already has some functionality related to this, used for general checkboxes. Perhaps some of it could be moved to central libraries (or removed, if the polyfill takes care of it).

kentr’s picture

kentr commented
Issue tags: +Accessibility, +Usability

I'm noting a discussion regarding the limitations of Safari's switch element: https://github.com/whatwg/html/issues/4180#issuecomment-1991750824

Ability to be styled might be a sticking point for using it along with the polyfill. I played around with the polyfill demo in Safari and haven't figured out how to style it yet.

I recall reading somewhere that Apple's stance on this is that some UI elements shouldn't change style between websites and native apps (I might be misremembering).

But I also know that difficulty with styling UI components has caused accessibility problems for us, such as with the color contrast ratio of placeholders in date / time fields (<input type="date">, for example).

Adding Accessibility and Usability tags.

alexpott’s picture

alexpott
he/they
Primary language English
Location 🇪🇺🌍
commented

To me, it would be good to create a generic Switch element that can be used in other cases.

+1,000,000

This would be fantastic. FWIW the experimental default_admin theme already converts single checkboxes to a switch so maybe we can look at bringing this into core and making it intentional instead of magical.

kentr’s picture

kentr commented
Title: Replace compact mode link with a switch to improve accessibility » [PP-1] Replace compact mode link with a switch to improve accessibility
Issue tags: +wcag412
Parent issue: » #3585823: [Meta] Improve the accessibility of the Default Admin theme

It seems that this will only be relevant when the behavior changes to JavaScript in #3584347: Deprecate and replace system_admin_compact_mode(), so postponing on that.

I think it will also be related to SC 4.1.2 Name, Role, Value (Level A) because the link role of the current markup will be incorrect when this control is a JavaScript toggle of any kind.

In the larger picture, I think that changing to switches will also apply in cases like the "Show / Hide all columns" button for responsive tables. I think the consistency will be better for UX.

I gave credit to @cwilcox808 for his help in Slack.

kentr’s picture

kentr commented
Status: Active » Postponed
kentr’s picture

kentr commented

Interesting that Adrian Roselli recommended against using the switch role and recommends using a button instead.

Generally I recommend against a control with a switch role. Scott O’Hara has tracked a bunch of issues with screen readers, so you can see that the experience is sub-par overall.

kentr’s picture

kentr commented

Followup to #9:

@cwilcox808 said in Slack that he thinks the current browser situation with regard to announcing the changes for role="switch" is fine.

That testing [by Scott O'Hara] is pretty old. Adrian Roselli has switch tests that are a bit newer but still somewhat dated.

Chrome + JAWS ✅
Edge + Narrator ✅
Firefox 105 + NVDA or Narrator ❌
Chrome 106 + TalkBack 13 ✅
Firefox 105 + TalkBack 13 :✅ (though it uses "checked" "not checked" instead of "on" "off")
iPadOS Safari 15.6 + VoiceOver ❌
macOS Safari 16 + VoiceOver ❌

However, Firefox 115 (July 2023) does convey the switch role and "on" "off" states and Safari+VoiceOver have worked since at least 17.4 (March 2024).
Using current versions of Windows 11 + Firefox, Narrator calls the control a "button" instead of a "switch" but it does say "on" and "off" so I think that's fine.

mgifford’s picture

mgifford
he/him
Primary language English
commented

Looking at CanIUse.com https://caniuse.com/wf-switch-control

it still looks like full support for "switch" only comes with Safari.

A possible pollyfill https://blog.tomayac.com/2026/01/12/a-polyfill-for-the-html-switch-element/

kentr’s picture

kentr commented

@mgifford, @cwilcox808 said the polyfill does a good job.

Followup to #5: It might by style-able by using appearance: none.

mgifford’s picture

mgifford
he/him
Primary language English
commented
Issue summary: View changes
StatusFileSize
new Show.png93.4 KB
new Hide.png94.32 KB

Adding steps (created by AI). Definitely helped me understand the issue better.

mgifford’s picture

mgifford
he/him
Primary language English
commented
StatusFileSize
new 3593539-replace-compact-mode-link-with-switch.patch14.37 KB

The patch (generated by AI) I need to test this tomorrow:

  • Replaces the link with .
  • Uses appearance: none, as @KentR suggested.
  • Keeps the stable label “Hide descriptions.”
  • Exposes state through the native checked state.
  • Supports Space and pointer activation without custom keyboard handling.
  • Preserves state in localStorage.
  • Handles RTL, focus visibility, reduced motion, and forced colours.
  • Updates kernel and functional JavaScript tests.
  • Updates template documentation that incorrectly described the control as a link.
mgifford’s picture

mgifford
he/him
Primary language English
commented
StatusFileSize
new Slider-selected.png300.12 KB
new Slider-deselected.png293.58 KB
new 3593539-replace-compact-mode-link-with-switch-2.patch13.02 KB

Better patch (there was a reference to a File to patch: core/themes/stable9/templates/admin/admin-page.html.twig in the other one for some reason).

Slider deselected

Works with space now. Screenshot included the voiceover text.

I haven't made a MR as this is still dependant on an upstream patch.