1 of 60

Implementing an accessibility-focused design system in Drupal

Amy M. Drayer

jen neveau

Gabe Ormsby

2 of 60

University of Minnesota campus

3 of 60

Why is this statement important?

4 of 60

“This is how bad design makes it out into the world. Not due to malicious intent, but having no intent at all.”

-Mike Monteiro

I am a User Interface Developer, so my primary focus is building usable websites. I consider accessibility to be the foundation of usability because usability isn’t truly usability unless it includes everyone. And if people are using assistive technology to get to the content, the website first needs to actually work for those multiple modalities before we can begin improving the experience.

So when I began working at the University of Minnesota, my scope of work applied to the theme of the website, primarily the homepage, the header, navigation, and footer of the sites. Once those were more accessible, we began expanding accessibility audits to other top pages of the site. But this moved into content, which was outside my authority.

At the time, we had one WYSIWYG content box per page, and folks could add what they wanted but had little support for complex components like accordions. What we needed was for everyone to understand the impact and importance of content accessibility and structure. To share our fundamental groundings in ways that were supportive and not overwhelming. Not from a place of blame, but from one of learning and improving.

As Mike Monteiro said in a 2013 presentation,

[click] “This is how bad design makes it out into the world. Not due to malicious intent, but having no intent at all.”

5 of 60

Design with intent

Putting principles into action

Project goals and vision

This became the vision, to [click] design intentionally to meet our values, and [click] putting those principles into action.

To set the stage, a challenge that many libraries face is creating a seamless online experience across the multitude of vended products we use as well as multiple research projects with websites as product outputs.

In 2019, I was forming the principles when our Health Sciences Library came due for a Drupal upgrade. I proposed a principled web design approach that aligned with their redesign goals. With their approval, we built a design system that documented the principles, content guidelines, and code patterns for Drupal implementation. The design system allows us to address accessibility at all levels of site creation and maintenance.

Once the site launched, we set our sights on the main library website. The main site is much larger: more content, more stakeholders, and more authors. We were able to take the foundational work from the health sciences site and build up from that.

6 of 60

(Universally) Accessible

Honest

Inclusive

Mindful

Private

Simple

Sustainable

7 of 60

(Universally) Accessible

Deliver content and services where barriers to access are removed for all people to use regardless of technology, format, or methods of delivery.

Avoid building to one way of doing or being. Build to be understandable, in a way that allows us to be human and make errors.

8 of 60

Honest

Be transparent.

Provide only accurate content written with non-biased language and clearly identify opinionated content. Fight disinformation, or the act of intentionally deceiving in content and algorithms.

9 of 60

Inclusive

Lead with person-first design, designing with people, not for them. Be aware of our own biases and assumptions, and recognize we are not the user.

Embrace people as complex beings, where average doesn’t exist.

10 of 60

Mindful

Make decisions that prioritize user wellbeing, don’t build to steal attention, and avoid deceptive and manipulative patterns.

11 of 60

Private

Promote and ensure privacy through security and personal data ownership. Provide these tenets in systems and services to the best of our ability and be transparent where we cannot.

12 of 60

Simple

Simple is challenging; it’s curating and cultivating the message concisely and clearly.

It’s discovering the most elegant semantic technical solution, and the intentional use of the resources available.

13 of 60

Sustainable

Factor in energy source and consumption for optimizations, from server to client side. Just as people do not deserve a reduced experience, our planet does not deserve to suffer the consequences of bad design and web delivery.

Sustainability is as much about our planet’s wellbeing as it is our own, as they are intertwined.

14 of 60

U Libraries Design System

15 of 60

(Universally) Accessible

Honest

Inclusive

Mindful

Private

Simple

Sustainable

16 of 60

Accessibility is aesthetic.

simplify code

simplify selectors #this-one #that-thing .this-button span�:not, ~, +, :first-child, :only-child, :nth-child(), :first-of-type, :last-of-type, :nth-of-type(), [att=value]

honor user settings to improve accessibility

mind high CPU styles for sustainability

border-radius
box-shadow and text-shadow
opacity
transform
filter
position: fixed

An example of this

Accessibility is aesthetic.

There’s an argument that accessible design cannot be aesthetic. I’m going to debunk that; accessible design can be aesthetic. I’ve found accessibility and sustainability are strongly linked, so could a similar argument be made about sustainable design? I have to admit having both accessibility and sustainability in mind can make design surprisingly challenging for a modern feel, though more from sustainability reductions. But that is a challenge worth accepting.

CSS can do so much more today, but it’s also easy to fall into performance traps that can detract from inclusiveness and sustainability.

[click] Simplify code. We often write rules over rules, or don’t remove obsolete CSS. To help organize the code, consider using partial files but avoid using “@import” since each of these is a resource request. Rather, mash the partials through a build management tool like Gulp or amalgamate and cache server side using a content management system. Avoid “!important” unless for utility classes, print stylesheets, or debugging. And if you have a build process, be sure to include an uglification step for production. Follow the progress of new CSS features @container and @layer, which will give us much more control over style specificity.

[click] Simplify selectors. If you have code like #this-one #that-thing .this-button span, your code may need a clean up. Remove IDs from selectors. Instead, identify components and focus on using a parent class and children of that class. Use fun features like :not, the ~ for siblings, the + for adjacent siblings, :first-child, :only-child, :nth-child(), :first-of-type, :last-of-type, :nth-of-type(even), specifying based on attribute existence or a match on an attribute value, which you’ll have more of if coding accessibly... there’s not much need for granular classes anymore.

Use modern layout techniques. Flexbox and grid are amazing. You can create a complex intrinsic web design layout with CSS3 grid in a few short lines of code. Similarly with flexbox.

CSS does animation! But as with any animation, it requires the client’s CPU to process. If the animation must be there, keep it brief, set a finite time, provide some control to the user, and honor reduced motion settings to improve [click] accessibility.

Other [click] properties that can cause significant CPU computations include [click] border-radius, [click] box-shadow, text-shadow, [click] opacity, [click] transform, [click] filter, and [click] position: fixed. When we use these, the computer is handling all the math behind it, and repainting can see higher power usage. Use these mindfully.

17 of 60

Why is this statement important?

Making it work in Drupal

Provide a web components-based editing system for content contributors
Theme using web components provided by the design system

18 of 60

Why is this statement important?

The editing experience for content contributors

19 of 60

Why is this statement important?

Removing options...

Prevents layout and content choices that are counterproductive (break the intent of the design system)
Saves the content contributor from having to think about irrelevant choices

20 of 60

Why is this statement important?

Setting constraints

No Layout Builder
No In Place Editing
Minimal WYSIWYG toolbar configurations, tailored to specific content (Inline elements, lists, larger-scoped components)

Ensuring that our content fits with our design system goals in found us working against some current Drupal trends:�- The design system's promotion of focused, usually linear content suggested that extremely limited layout options should be available, and layout should be an expression of the content. The remaining demands for layout could be addressed in our theme using Drupal's older "regions" tooling. Layout Builder was removed completely.�- The authoring interface (more on that shortly) and the pattern library provided by the design system promotes carefully-constructed content, and I felt the In-Place editing tooling would undercut this focus on content structure. Also reduced development time without having to support it.�- We created three different WYSIWYG editor configurations, each with the minimal necessary options for its use case. The most basic one was tailored to inline-only content, thus only allowed links, emphasised, or strong text.

21 of 60

Why is this statement important?

Keep the Design System in mind

Editing interface matches Design System language for each web component
Field-level help text links back to Design System for details and rationale
Staff training similarly references both Design System components and Drupal implementation

22 of 60

Design System-to-Drupal

The Design System gives us web components and the canonical markup for them.

23 of 60

24 of 60

Why is this statement important?

Applying the abstract web components to Drupal

25 of 60

Why is this statement important?

Paragraphs as building blocks

https://drupal.org/project/paragraphs
Design system components were implemented as Paragraphs
Allows for nesting of elements (cards in card decks, text paragraphs inside sections)
Each type contains fields for content and also for editor-accessible settings.

26 of 60

Example paragraph types

27 of 60

Page body as Paragraphs

28 of 60

Content section

fields

29 of 60

The editing experience in summary

The "blob of body text" and wealth of rich text options is gone.
Content editors think structurally about how their content fits into available components.
Formatting options are tightly constrained to those that make sense within a given component and which meet accessibility requirements.
Fields are mostly for displayed content, but some turn into configuration as the theme processes them.

30 of 60

Theming (the Paragraphs) to fit the design system

31 of 60

Theme flow as a 3-step process

Catch: Hook into the theming process where Drupal would normally go -- The Twig files

For Paragraphs, paragraph--paragraph-type.html.twig

Tweak: Manipulate inbound data where needed to work with design system expectations -- Twig or theme hooks
Redirect: Send tweaked data to theme's design system components

32 of 60

Theme flow

Step 1: Catch�

33 of 60

[...]����

<section class="color-block hero" id="homepage">�[...]

Catch: Standard Drupal template behavior

34 of 60

"Catch" just means create a template where Drupal is going to look. For a specific example:

Our design system component: Content section

Implemented as: A paragraph of type ds-content-section

Catch the theming process at: our-theme/templates/paragraphs/� paragraph--ds-content-section.html.twig

Let's dig into that Twig file for the next two steps...

35 of 60

Excerpt 1: paragraph--ds-content-section.html.twig

{#�/**� * This template passes final rendering off to a design system pattern template� * in theme's templates/components/ directory. Here, we munge the data just� * enough to fit the expectations of the abstract DS pattern. That means:� [...]� * This approach will allow other Drupal Paragraphs, Block or Views, to also� * rely on the component templates, by ensuring a consistent 'inbound'� * vocabulary.� */�#}

36 of 60

Excerpt 2: paragraph--ds-content-section.html.twig

{% set section_classes = content.field_ds_section_classes|render|striptags|trim|split(' ') %}

{% set section_id = content.field_ds_section_id|render|striptags|trim|split(' ')|first ?: 's-' ~ paragraph.id() %}

This is Step 2...Tweak!

37 of 60

Why tweak? Paragraph data is not necessarily Component data

Stuff that makes sense for an editor to enter may not perfectly map to stuff a design system component needs
We alter existing data and add new data when sending a Paragraph to a Component
Easy stuff can happen in Twig
Complicated stuff happens in umnlib.theme, mostly preprocess and alter hooks -- 2,000 lines worth (maybe 50% comments)
Recall the Paragraph entry form for a content section...

38 of 60

Part of the form for a content section paragraph

39 of 60

Excerpt 2 (again): paragraph--ds-content-section.html.twig

{% set section_classes = content.field_ds_section_classes|render|striptags|trim|split(' ') %}

{% set section_id = content.field_ds_section_id|render|striptags|trim|split(' ')|first ?: 's-' ~ paragraph.id() %}

40 of 60

Excerpt 3: paragraph--ds-content-section.html.twig

{% embed '@components/section/section.html.twig' with {� content: content.field_section_items,� heading: content.field_ds_section_heading,� heading_element: content.heading_element,� subtitle: content.field_section_subtitle,� section_classes: section_classes,� section_id: section_id,� classes: classes,� back_to_top: content.back_to_top,�} %}�{% endembed %}

...And here is Step 3: Redirect. What's going on here?

41 of 60

The "redirect" step relies on the Components module

https://drupal.org/project/components
"The Components module makes it easier for a theme to organize its components. It allows themes (and modules) to register Twig namespaces and provides some additional Twig functions and filters for use in Drupal templates."
Rephrased, allows us to define a special templates directory for components in our theme.info.yml file and use `@components` in Twig to reference that directory.

42 of 60

Excerpt of umnlib.info.yml

...

components:� namespaces:� components: templates/components�...

43 of 60

What's in�templates/�components?

44 of 60

Excerpt 3 (again): paragraph--ds-content-section.html.twig

{% embed '@components/section/section.html.twig' with {� content: content.field_section_items,� heading: content.field_ds_section_heading,� heading_element: content.heading_element,� subtitle: content.field_section_subtitle,� section_classes: section_classes,� section_id: section_id,� classes: classes,� back_to_top: content.back_to_top,�} %}�{% endembed %}

45 of 60

That was the theme template for the content section paragraph type.

Let's go look at the theme template for the content section web component.

46 of 60

Excerpt 1: templates/components/section/section.html.twig

[...]�/**� * Available variables:� * - content: The content items within the article. Optional.� * - heading: The heading for the article. Required.� * - heading_element: The appropriate level heading. Required.� * - subtitle: Extension to heading, not included in side navigation. Optional.� * - back_to_top: Boolean flag indication whether to include a 'back to top' \� link. Optional.� * - section_classes: Array. Class options from paragraph type. Optional.� * - section_id: String. ID attribute value. Optional.� * - classes: Classes array passed by parent theme or module.�[...]

47 of 60

Excerpt 2: templates/components/section/section.html.twig

[...]�* This file may be used via twig 'embed' by any number of theme templates for�* Views, Blocks, or Paragraphs. The calling template is responsible for�* altering source data to fit the pattern's expected variables.�*�* See this theme's templates/paragraphs/paragraph--ds-content-section.html.twig�* for a sample implementation.�*/�[...]

48 of 60

Excerpt 3: templates/components/section/section.html.twig

<section{{ attributes.addClass(section_classes).setAttribute('id', section_id) }}>�{% if subtitle.0 %}� <{{heading_element}}>� {{ heading }} <span class="subtitle">{{ subtitle }}</span>� </{{heading_element}}>�{% else %}� <{{heading_element}}>{{ heading }}</{{heading_element}}>�{% endif %}�{% if content|render %}� {{ content }}�{% endif %}�{% if back_to_top %}� <p><a href="#top">Back to top</a></p>�{% endif %}�</section>

49 of 60

Recap: Implementing our Design System in a Drupal theme

Use the default paragraph--paragraph-type.html.twig files to catch the theme flow
Tweak data available to the paragraph type right in the twig template or through theme alter or preprocess functions to fit design system component needs
Redirect rendering to a web component template with the help of the Component Libraries module and Twig embed functionality
The same approach works with Views, Blocks, and other templates

50 of 60

Tweaking revisited: Fixing a thing that's bugged me since 2008

Remember this from our component template section.html.twig?

<{{heading_element}}>{{ heading }}</{{heading_element}}>�

51 of 60

umnlib_get_heading_level():

A helper function in our theme that finds the appropriate heading level for any heading-like field.

We know what fields are used for headings and we know what paragraph types they are in (card decks and content sections)
Instead of hard coding "<h2>" or "<h3>" in a twig template and hoping it works, we use "$heading_element"
Probably rather expensive, but we have Varnish caching in front.

52 of 60

Why is this statement important?

Accessible content

53 of 60

Content strategy

“The University of Minnesota Libraries’ website prioritizes the support of users new to our site and services, and by doing so, supports all users in their goal to find and access our resources and apply them to their work, and our goal to engage and inspire our diverse community of users.”

That process began by writing a core strategy statement — a tool to guide content creators through evaluating existing content along with how and when to create new content. It does this by identifying the audience and tying their needs to business goals.

Our Web Content Management Committee used a Madlibs-like method, developed by Sara Wachter-Boettcher, to collectively author our strategy statement. Everyone on the team took an individual pass at it, and then we brought the results together, identified themes, and landed on the following.

“The University of Minnesota Libraries’ website prioritizes the support of users new to our site and services, and by doing so, supports all users in their goal to find and access our resources and apply them to their work, and our goal to engage and inspire our diverse community of users.”

54 of 60

Why is this statement important?

Content guidelines

55 of 60

Why is this statement important?

Content guidelines

Use descriptive headings and links
Use sentence casing
Write for a 8th grade or lower literacy level
Use short sentences and paragraphs
Use bulleted lists

- Use descriptive headings, links, and buttons. Group related ideas together using descriptive headings and subheadings using Drupal’s content sections. Keep headings concise and easy to scan. For links, use concise text that describes where a person will go or what content will load when they activate a link.

- Use sentence casing. Many readers, particularly on the web, rely heavily on scanning. Because most of the text we read is in sentence casing, it is the most predictable and scannable way to relay information. This is particularly impactful for people with language-based learning disorders who may rely on the shape of the word more than the letters themselves.

- Write for below the 8th grade level. Simplified writing makes content more accessible to people of all literacy levels, people for whom English is a second language, people using text-to-audio and braille displays, and to people with learning disorders and cognitive impairments.

Use short sentences, aiming for a maximum of 50-20 words, and short paragraphs with a maximum of 3-5 sentences.

Use bulleted lists where appropriate, rather than listing items in long, comma-delimited paragraphs. And use Drupal’s list paragraph type to ensure that the lists are properly structured for the ease of screen readers and other assistive technology.

The guidelines also include recommendations around punctuation, voice, tone, and terms and phrases to avoid.

56 of 60

Why is this statement important?

Content audit and remediation

From there, we went through and audited every single page on the site, identifying what needed to be revised, combined, moved, or left behind in the migration. This involved looking at content through the lens of our content strategy statement, remediating content based on our content guidelines, and evaluating our content for R.O.T., which is to say content that is redundant, outdated, or trivial.

This was a long process. Some of those revisions started happening in 2019. But it was worth it. We knew from the beginning that we couldn’t just copy everything over and hope for the best. By touching every piece of content, and migrating only content that was reviewed and edited with those guidelines and principles in mind, we ensured that we were fulfilling the promise made in our core strategy statement.

57 of 60

Why is this statement important?

Content governance and workflow

Draft > Pending WCMC review > Published

Pending deletion or Archived

Up next? Content governance.

The content of our previous web presence reflected a de facto distributed model, organically derived from the siloed nature of its creation over time. Subject matter expertise, writing, voice, and style were all handled differently by individual departments. This resulted in a lot of really great content, presented really differently, and sometimes inaccessibly.

We needed to make sure that all of the auditing and remediation work we’d just done had a lasting impact. To make sure we didn’t drift back into that siloed content creation culture, we shifted to a centralized, co-design model, wherein a central team (WCMC) oversees the content, and works closely with subject matter experts to ensure consistent, quality content delivery across our websites, as well as other systems and platforms as appropriate. This meant changes to the way we create and maintain our content on a day to day basis.

Drupal’s workflow system provided the tools to make this happen. This helped ensure that the carefully considered standards for content and design were applied. And by using this approach for content oversight, we’re able to efficiently monitor those critical content creation elements that couldn’t be encapsulated by our Drupal paragraph types.

“**Draft**” is the default for content authors, in which they could repeatedly save, iterate, and review.

When authors are satisfied with their draft, they change the state to “**Pending WCMC review**”, triggering an email to the Web Content Management Committee to review the content based on our established guidelines and appropriate use of the structured Drupal formatting, before it’s set to **Published**.

We also included two removal states, “**Pending deletion** and **Archived**, to differentiate between content that just needed to be removed, vs. content that might be reused or repurposed at a later date, for example, seasonal content.

By making decisions about accessible, simplified content, and building the structures in Drupal to support it, we ensure that the benefits of that work are felt by all users.

58 of 60

Lessons learned

Content first development worked! (mostly)
The shift away from WYSIWYG authoring was hard.
Ongoing communication is key.
Workflow is important, but keep it simple.
Real content doesn’t always fit.

So what did we learn?

**Content first development worked … mostly.**

Taking a content first approach was really effective and efficient from a development standpoint. Because we approached content with a strategy and a known structure, there wasn’t any time wasted experimenting with modules that wouldn’t get used, or designing something that wouldn’t fit our needs.

And we knew from the pilot with the Health Sciences Library that that was going to take some time, both because we were moving from a relatively freeform environment to the more structured paragraphs model, and because we knew how much content needed to be reviewed and rewritten with our principles in mind.

But! Some of our content authors really struggled to write content when they didn’t know what that container was going to look like; it created a conceptual barrier that made the process feel more fraught than it was, and coaching them through that was an unanticipated time cost.

**The shift away from WYSIWYG authoring was hard.**

We moved away from basically one or two text fields into a nesting doll of a system. While the system produced easily readable, scannable content for the user, editing took some digging. In some cases, all of the structuring we did had the opposite effect, where folks chose to put everything in one paragraph component instead of engaging with a system they felt was overly granular or complicated. Creating a thoughtful set of guides helped! But we’re still working to fully normalize this mode of work. To which…

**Ongoing communication is key.**

This was a big culture shift, and change doesn’t happen overnight. We communicated throughout the development process really actively, sharing updates via email, and presentations both at all staff meetings, as well as targeted outreach to individual departments and service areas. But we failed to really keep that communication up, which means the messaging was missed by incoming staff (of which we’ve had a lot!), or forgotten by folks that don’t do a lot of editing in Drupal. Even though the system isn’t that complicated, it _is_ that different, which means we need to keep communication in the forefront, even now that the change is “complete.”

**Workflow is important, but keep it simple.**

Our initial workflow included the redirection of content pending review to Web Content Management Committee members by subject or service area, anticipating needing that expertise to navigate content issues with content creators. But what we found was that the volume of edits was really pretty low, and the heaviest users of the site adapted very quickly. While updates from infrequent users often requires a closer look, most updates went straight to published, so distributing the work was kind of overkill. Instead, we pulled back, and one person monitors the moderation queue, and just tags other subject matter experts or reviewers in as needed.

**Real content doesn’t always fit.**

When it came to creating our information architecture, or as we wound up calling them, our content buckets, as well as the structure for our modeled content, we knew there were going to have to be compromises. Say we had buckets labeled apples, oranges, and bananas. Pears? Sure, put ‘em in with apples. Grapefruit? Orange bucket it is. Broccoli? Well, bananas was always kind of a catchall. Sure. But what the heck do I do with this box of 500 paperclips?

A structured system is great, when the content you’re working with either fits the structure, or can be reworked to do so. But it presents a real challenge when you encounter content that just doesn’t fit the mold, and requires some difficult choices about investing resources in potentially one-off workarounds.

And last, but certainly not least….

59 of 60

Lessons learned

It paid off!

60 of 60

Thank you.

Amy Drayer adrayer@umn.edu�jen neveau jneveau@umn.edu �Gabe Ormsby gormsby@umn.edu