Accordions: Eight patterns in Civi markup – reduce & make more accessible?
At present Civi docs recommends making an accordion interface element with
.crm-accordion-wrapper. There's at least another seven ways accordions are implemented in Civi, as seen in #56. Some of these look/behave differently, and maybe have to be different, but perhaps some could be merged.
Furthermore, none of these use the basic aria-labels recommended in the Bootstrap3 method (which remains in Bootstrap5), for letting screen-readers know if an accordion is open or closed, and which contents should be read or not. This is a long-standing issue - core#3294 - raised by the late accesibility expert Rachel Olivero (the Olivero theme is named after her). Sidenote: Bootstrap's accordion pattern (
.collapse) doesn't seem to be used anywhere in Civi.
can we reduce the number of accordion markup patterns that a theme must support from 7 to anything less?
can we amend the recommend accordion markup (and in turn civi's accordion implementations) to be more accessible (+ modern/responsive)?
.crm-accordion-wrapper- as recommended in the docs UI reference guide
.crm-dashlet-header- as seen on the home dashboard. Looks the same but only the expand icon (e.g. arrow) is clickable as the rest of the header needs to be a drag-gable region.
.crm-collapsible- notably used on the field groups on the contact record main tab - it has no background for the header or body
.crm-collapsibleon a fieldset - as seen on event signup pages
.collapsedin a table - as seen on the extensions listing page
- using the
.crm-ui-accordionangular directive. This is a shorthand to generate the
.crm-accordion-wrappertype accordion top.
.af-collapsibleon a FormBuilder element - as seen in forms generated by Form Builder - a new JS/CSS/markup pattern added in 2022
- there's another Jquery/Angular fieldset accordion used in Searchkit builder that's not in ThemeTest yet.
Range of characteristics
These eight variations cover 5 different visual/interaction patterns:
- click on full header to expand/close
- click only on expand/close icon to expand/close
- shaded background for header and body
- transparent background for header and body
- expand a region outside of the parent accordion wrapper (5 - maybe soon to be replaced with SK/FB)
Initial thought is that with a bit of extra css and a tiny bit of rewriting, all of these could be done with two patterns - one based on the current recommended
wrapper > header + body, with the full header clickable and the icon added entirely in css; and one based on an icon wrapped in an tag that toggles the visibility of another region, as seen in patterns 2 and 5 above (while 5 may soon be replaced and 2 is one-off)..
- A utility class like
crm-accordion-clearcould be applied next to
.crm-accordion-wrapperto provide 1) above with the same UI as 3)
- Likewise two new CSS selectors could allow the same pattern to be applied to 4) & 8) . Both these changes are demonstrated in a new ThemeTest branch: Proposals
- I'm not sure why in 7) + 8) the new SK/FB Angular accordions diverged in markup/js/css from Civi's recommend accordion - maybe needs @colemanw to feed in.
- The extensions page 5) will be rewritten with FB/SK at some point so can maybe ignore.
- That leaves 2) - an accordion where only the icon triggers an expand/close so the rest the header is a dragable region. I think that making this use the same markup/css pattern as the others would require rewriting all the others, so it might be safest to leave this an exception for now. There is an attempt to merge the patterns in Proposals but the header is doing a lot - dragging and right-floated icons. A toggle behavior is more compelling than an accordion, even if it should look like an accordion.
- But even with keeping 2), then potentially only 2 patterns left out of 8.
Thoughts on accessibility
Work has been done to implement JQuery Accessible Accordion Aria into Civi (demo of the plugin - https://a11y.nicolas-hoffmann.net/accordion/). Not sure if that is still a promising path, or there's a JQuery free methods now.
The current recommended pattern could be made more accessible with something like the following, based on Bootstrap3's collapse. There's fewer ARIA labels than the JQuery plugin, but it makes clear if the accordion is open or not, and links the header to the expand region with an id, two recommendations of this walkthru on accessible accordions.
<div class="crm-accordion-wrapper collapsed">
<div class="crm-accordion-header" aria-expanded="false" aria-controls="uniqueID">
Accordion Title here
<div class="crm-accordion-body" id="uniqueID">
<div class="crm-block crm-form-block crm-form-title-here-form-block">
Accordion Body here
This would require two changes - a unique ID added to every unique accordion on a page, and an
aria-expanded="false" attribute that toggles true/false.
- why did the new angular accordions take another approach? Speed of development or something practical?
- is it worth trying to reduce these down to two recommended patterns, by swapping out the new angular patterns and adding a few new css classes into core? Or better to wait and flag this for the future?
- what's the easiest way to make civi accordions more screen reader friendly?