System messages should be accessible

Makes sense to me:

https://w3c.github.io/html-aria/#index-aria-status
A container whose content is advisory information for the user but is not important enough to justify an alert, often but not necessarily presented as a status bar.

https://w3c.github.io/html-aria/#index-aria-contentinfo
A large perceivable region that contains information about the parent document.

I just discovered this issue while looking at Claro — https://www.drupal.org/project/drupal/issues/3079738#comment-13249979 — which also uses contentinfo for status messages. It looks like this has been open for some time. Is there a reason that I'm not aware of that we are still using contentinfo when we should be using status?

I have updated the status message templates for the basic and test themes by changing the role of contentinfo to region and adding a wrapper with role status around the warning and status messages.

# The tests are failing because of the role change I gues.

Well I have tried to modify the tests cases, but it seems that there are still two erros, that I don't know how to solve.

Please review the patch.

Thanks!

With aria-label="Status message" & <h2 class="visually-hidden">Status message</h2> being used, won't the "Status message" message be said twice to AT that supports ARIA?

EDIT: I realize this is repeating what we did previously for D8.

EDIT2: More examples to look at here
https://www.davidmacd.com/test/using-wai-aria-in-html.html#rec-legend
https://www.smashingmagazine.com/2015/04/its-alive-apps-that-feed-back-a...
https://developer.paciellogroup.com/blog/2014/03/screen-reader-support-a...

Also if we use role="status" we might also need to add aria-live="polite".

I'm in the midst of comparing a great many examples of government status messages at the moment. There isn't a great general consensus on this.

@andrewmacpherson,

I saw the previous patch got failed. I have rerolled the patch.

Thanks!

A duplicate of this issue was created a few months ago. I closed that one as there as there's more context here, but it may be worth consulting the most recent patch to see how the test failures in #15 can be avoided: #3159933: Status Message in Claro on theme install should have role="status" or similar instead of contentinfo

Reroll and test failures fix of patch #15

Thanks @bnjmnm for pointing out the duplicate where I've shamelessly copied carefully crafted the fixes from...

Added Needs issue summary update-tag to address #18

Might need an issue summary update, following #5, to keep the proposed resolution up to date.

Because of that, keeping this at Needs work although we have a working and green patch.

Note: I think we don't need extra tests for this since we altered 4 tests covering this already.
Then again, I've been very wrong about tests before...

New patch is a re-roll of #23 for 9.3.x and adds the fix to Olivero's status-messages.html.twig file

Updated patch in #27 to fix custom command failures. Retaining status as "Needs work" for issue summary update as mentioned in #24 , thanks!

Updating issue summary's proposed resolution per #5, with a couple of alterations:

1. I like the idea of keeping messages as a landmark role for discoverability, but I don't think each message type warrants its own landmark region. I've updated the proposal in comment #5 to bundle all messages within a role="region" with aria-label="Status messages".
2. In my opinion, warnings and errors belong bundled within the role=alert, but without a clear rule or set of examples, I'm deciding to maintain the pattern we currently have where only error messages are given the alert role. mgifford suggested we add aria-live="polite" in #19, but I don't think that's necessary as the drupal.message API uses drupal.announce to announce new JS-based messages to users.

Tagging this as a WCAG 1.3.1 issue.

Crosslinking, there is definitely an effort duplication between this issue and linked.

Re-rolled for the latest 9.3.9 (9.3.x)

+          <div class="messages__content">
+            {% if messages|length > 1 %}
+              <ul class="messages__list">
+                {% for message in messages %}
+                  <li class="messages__item">{{ message }}</li>
+                {% endfor %}
+              </ul>
+            {% else %}
+              {{ messages|first }}
+            {% endif %}

Is it a good idea to use UL and LI with role="generic" when only one message needs to be printed? That would simplify styling as the markup is not changing.

I was unable to apply patch #34. It was rejected in the Olivero theme.

Re-rolled patch for 9.5.x.

Re-rolled pacth #29 in Drupal 10.1.x

Trying to fix CCF issue with patch #42

Rerolled for 10.1. Applies cleanly.

#46 it's not working

Tests might fail and they will require extra work

Back to NR for the new patches.

Solving failed test cases and rerolling for 11.x

Caused massive test failures.

Was previously tagged for issue summary, has that been completed.

Rerolling to 11.x from #49.

Submitting Patch for 11.x and raising the MR as well.

Thank you.

Large number of failures.

Also was previously tagged for issue summary update.

@Prashant.c there's no interdiff added what did you do different from #55

I opened MR 6112 as patches don't seem to be testing properly. Most of the 1800+ test failures in #55 and #58 do not seem to have anything to do with the code changes. Among other things there are "missing composer.lock" messages, and that file is not touched in either patch. The MR I created is failing ~3 tests, so those will need to be addressed, but that should be straightforward compared to the unexpectedly huge fail count that suddenly appeared (and not at all the fault of @Prashant.c or @Hardik_Patel_12)

@bnjmnm, I have observed similar challenges in several other issues. When using the patch method, it leads to significant unrelated failures for the composer and other components, similar to the problems described in issues #55 and #58. However, the Merge Request (MR) method is functioning properly.

Bug in core's spellcheck step is blocking tests. #3418207: Spell-checking job fails with "couldn't find remote ref refs/heads/11.x" when 11.x branch does not exist in fork

Submitting a re-roll of patch #58 to allow for a clean application to 10.3.x. Some syntax and line number changes.

the 65-11.x.patch is a reroll to cleanly apply patch #58 to 10.3.x

The role="contentinfo" is wrong. This role is for a landmark region, equivalent to HTML , with the extra proviso that there can only be one contentinfo landmark per document, and it must be a top-level landmark. I'm not sure how we ended up with role="contentinfo", but perhaps the idea was to make the messages easy to find using landmark regions. I like that idea, and we can use <div role="region"> instead, and it will count as a landmark region, as long as it has an ARIA label.

Agreed that there should not be more than one contentinfo per page.

Within any document or application, the author SHOULD mark no more than one element with the contentinfo role.

https://www.w3.org/TR/wai-aria-1.2/#contentinfo

How about just using complementary role. Status, Error or Notice is often (not always) related to the page you are on.

https://www.w3.org/TR/wai-aria-1.2/#complementary

The complementary role indicates that contained content is relevant to the main content. If the complementary content is completely separable from the main content, it may be appropriate to use a more general role.

Complimentary also supports header and footer, which might be useful.

Looking at output from Claro, I think that they have it about right. i.e. one message per notice.

Markup is output in a single region.

<div class="region region-highlighted">
<div class="messages-list" data-drupal-messages="">
<div class="messages__wrapper">
<div class="messages messages--status messages-list__item" role="status" aria-labelledby="status-104584368505794-title" data-drupal-message-id="status-104584368505794" data-drupal-message-type="status">
    <div class="messages__header">
      <h2 id="status-104584368505794-title" class="messages__title">
        Status message
      </h2>
    </div>
    <div class="messages__content">
      Antibot (system_clear_cache): disabled
    </div>
  </div><div class="messages messages--status messages-list__item" role="status" aria-labelledby="status-263254492006824-title" data-drupal-message-id="status-263254492006824" data-drupal-message-type="status">
    <div class="messages__header">
      <h2 id="status-263254492006824-title" class="messages__title">
        Status message
      </h2>
    </div>
    <div class="messages__content">
      Caches cleared.
    </div>
  </div><div class="messages messages--status messages-list__item" role="status" aria-labelledby="status-288152668342968-title" data-drupal-message-id="status-288152668342968" data-drupal-message-type="status">
    <div class="messages__header">
      <h2 id="status-288152668342968-title" class="messages__title">
        Status message
      </h2>
    </div>
    <div class="messages__content">
      Antibot (system_performance_settings): disabled
    </div>
  </div>
</div>
</div>
</div>

In theory I see no issue in giving messages__wrapper or messages-listthe role contentinfo

One challenge here is css frameworks like bootstrap use a single role for all types of notifications. i.e. role=alert

here is an example for warning.

<div class="alert alert-warning alert-dismissible fade show" role="alert">
  <strong>Holy guacamole!</strong> You should check in on some of those fields below.
  <button type="button" class="close" data-dismiss="alert" aria-label="Close">
    <span aria-hidden="true">&times;</span>
  </button>
</div>

To colour can also be changed. Here are some examples.

<div class="alert alert-primary" role="alert">
  A simple primary alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-secondary" role="alert">
  A simple secondary alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-success" role="alert">
  A simple success alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-danger" role="alert">
  A simple danger alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-warning" role="alert">
  A simple warning alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-info" role="alert">
  A simple info alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-light" role="alert">
  A simple light alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>
<div class="alert alert-dark" role="alert">
  A simple dark alert with <a href="#" class="alert-link">an example link</a>. Give it a click if you like.
</div>

Certainly in Drupal, I would like to see the alerts beyond the standard status, warning and error. This would be useful for theming.

e.g. https://www.drupal.org/project/drupal/issues/3437924

Updated example of Olivero.

So it appears that notifications are grouped together for Olivero theme. This is different from Claro that has separate notifications.

Ok so it turns out message are displayed differently depending if big pipe is enabled.

If Big pipe is enabled messages are output in a group separately

If Big Pipe is disabled, messages are output separately as a group

With Big Pipe enabled if there is a single message (claro) outputs role=contentinfo

With Big Pipe enabled
If message is single than one output is role=contentinfo
If output is more than one, output is role=status

I think error messages may be treated slightly differently.

Just wanted to share how out looks with big pipe enabled in Drupal 10.2.7 (it's quite rare to see all types on a single page - see attached)

<div class="messages-list__wrapper">
                      
      <div role="contentinfo" aria-labelledby="message-error-title" class="messages-list__item messages messages--error">
                  <div role="alert">
                              <div class="messages__header">
                              <h2 id="message-error-title" class="messages__title">
                  Error message
                </h2>
                          </div>
                    <div class="messages__content">
                          One or more problems were detected with your Drupal installation. Check the <a href="/admin/reports/status">status report</a> for more information.
                      </div>
                  </div>
              </div>
                                  
      <div role="contentinfo" aria-labelledby="message-status-title" class="messages-list__item messages messages--status">
                              <div class="messages__header">
                              <h2 id="message-status-title" class="messages__title">
                  Status message
                </h2>
                          </div>
                    <div class="messages__content">
                          Antibot (system_themes_admin_form): disabled
                      </div>
              </div>
                                  
      <div role="contentinfo" aria-labelledby="message-warning-title" class="messages-list__item messages messages--warning">
                              <div class="messages__header">
                              <h2 id="message-warning-title" class="messages__title">
                  Warning message
                </h2>
                          </div>
                    <div class="messages__content">
                          No update information available. <a href="/admin/reports/status/run-cron?destination=/admin/appearance&amp;token=QJoWTyS5Bcf8KP_gvhmjUwm-s1rlrvSqL3XHgVsxEKQ">Run cron</a> or <a href="/admin/reports/updates/check?destination=/admin/appearance&amp;token=CBZRlulFTH8gW_6DOzzFPvANhv3hgZZGZgPlEhP9noY">check manually</a>.
                      </div>
              </div>
                  </div>

AFAICT messages are also grouped by type even with big pipe disabled.

Notice how there are multiple uses of role="contentinfo" on a single page which is obviously wrong.

In 10.3 I believe behaviour has changed slightly depending on whether big pipe is enable or not.

Rerolling patch #65 for Drupal 10.3.8. Line number updates and removal of edits to a template file where changes were addressed.

In addition to the role, we should also change the `h2` element to a `div` element. Looking at Olivero on a stock Drupal install, the error message renders before the `h1` thereby breaking the heading order.

Is it better to loose the semantics by dropping the H2 or to retain the heading order? I'm not sure.

My inclination is to keep the h2s.

• Having h2s prior to a page's h1 is not a big deal. In the case of messages, they're not really sub-sections of the page's topic anyway, right?
• If the messages are contained within a named landmark (e.g. div role="region" aria-label="System messages", there's already semantics present that are useful for navigation. However, surveys show headings are used far more than landmarks by screen reader users for navigation.

I'd vote to keep the H2. Sub-themes might place this block in other regions.

Having h2s prior to a page's h1 is not a big deal. In the case of messages, they're not really sub-sections of the page's topic anyway, right

Failing WCAG checks is the current issue I'm facing, so from that point of view, it's problematic. An element with role=status already gets announced as if it were aria-live=polite which makes the h2 overkill.

From Google search summary:

When a heading is not necessary
If the role="status" area provides a short, simple update that doesn't require further breakdown or organization (like a progress bar), a heading might be redundant or even disruptive to the user experience, according to MDN Web Docs.

When a role="status" message is intended to be self-contained and not part of a larger, navigable section, a heading might not be necessary, says the W3C.

@kthull failing an automated test isn't the end of the world. There are often false positives. Of course it is easier if the automated tests pass.

Interesting to consider though if role=status would be sufficient substitution. Worth looking into a bit more. Thanks!

Maybe I misunderstood something foundational, but as I see it, Drupal messages are generated on the server-side, and because of that, a whole page reload occurs before they are displayed. And reloading the page is "change of context" even if the "same" page is reloaded, isn't it?

So if this behaviour is "change of context", then it is totally irrelevant to use role="status" because

There are two main criteria that determine whether something meets the definition of a status message:

• the message "provides information to the user on the success or results of an action, on the waiting state of an application, on the progress of a process, or on the existence of errors";
• the message is not delivered via a change in context.

(Source: the same page I linked above)

Besides the content of the technical definition, it is also important what happens in practice: when the page reloads, a screen reader just goes "back" to the beginning of the page and handles it as new content. This situation requires a different approach: the focus should be automatically/programmatically shifted to the message (which is not a "Status message" by definition).

Of course, messages can be added with AJAX, or JavaScript.

For JS, we have Drupal.announce – that should be used.

In case of AJAX, the current suggestion (define two separate containers with "status" and "alert") roles may be correct, as I understand. But it is important that these containers must exist when the page loads, and they should not be generated together with the message only! (Maybe this is how it is meant to be already, but it was not clear to me from the current issue definition/discussion.)

A small note on role="error"* role="alert". This WCAG page says:

The purpose of this technique is to notify Assistive Technologies (AT) when an input error occurs.

Highlight from me. I'm not sure how serious "input error" is and what we can mean by "input error", but it is worth noting.

*There is no role="error" – I wrote this wrong initially. Adjusted based on comment #89.

And reloading the page is "change of context" even if the "same" page is reloaded, isn't it?

Hrmm. I'm not sure that any reloading of a page is in fact a "change of context," especially when it's the same page reloaded. From https://www.w3.org/WAI/WCAG21/Understanding/status-messages#dfn-changes-... , there are multiple reasons why it might not constitute a change in context:

major changes that, if made without user awareness, can disorient users who are not able to view the entire page simultaneously

A Drupal page reload resulting in a new status message *is* made with user awareness, since it would be triggered by a user action.

A change of content is not always a change of context. Changes in content, such as an expanding outline, dynamic menu, or a tab control do not necessarily change the context

The above seems more along the lines of a status message showing on the page, whereas the following example of a change in context does not sound like a status message showing on the page:

Opening a new window, moving focus to a different component, going to a new page (including anything that would look to a user as if they had moved to a new page) or significantly re-arranging the content of a page are examples of changes of context.

So it does seem that the Drupal status message meets the two criteria of the definition of a status message.

Thanks for your reply, Mark!

I was thinking about these too. And you may be right, and it is not a context change, reloading a page by the definition.

But that is why I did not end my comment with that.

When the page reloads, the browser rebuilds it from scratch (including the accessibility tree), right? If so that is a new page, new context even it contains the same things as before. Or am I wrong?

Anyway, it is just theory yet. :)

I have not seen any comments about testing the newer, suggested versions in practice with screen readers.

I have not done that myself either yet, but I plan to do it.

So I have not tested any of the patches above. Instead of that, I have updated the block--system-messages-block.html.twig template by adding <div role="status" aria-atomic="true"> around its content. Then I checked it with a screen reader (VoiceOver + Safari on Mac).

The results:

When the page was reloaded before displaying the Status message the screen reader did NOT announce the message.

When the Status message was added by AJAX (the Frontend Editing contrib module's toggle switch does that) the screen reader DID announce the status message.

(Of course, more detailed testing with more tools would be fine, but these results support what I wrote before.)

When a page reloads (browser makes a page request and the server returns a page with the same URL), due to a form submission, following a link, etc. I would classify it as a change in context because focus changes, it's moved to the beginning of the page. Users expect a change in context when submitting a form or using a link.

@thamas Regarding your template update, role="status" implicitly has `aria-live="polite"` and `aria-atomic="true"` so neither attribute needs to be explicitly on the element. Also, correcting a previous message, there is no "error" role, that was meant to be "alert;" I think most messages classified as errors on Drupal are not input errors, certainly not the ones that only appear on page reload.

The purpose of role="status" is to create an ARIA live region, it's not meant to convey the nature of its contents or to aid in page navigation, other roles, like Landmark roles are for that. According to the ARIA specifications, status contents are not meant to be announced on page load, only when the live region contents change. I've found this to be the case in my testing. Navigating the page contents element-by-element, NVDA (with Chrome and Firefox) did not announce when a role="status" element was entered, exited, or even it was focused (even when the element had a name). When navigating using macOS 15.7.2 VoiceOver + Safari 26.1 it does choose to announce when the element was entered and exited when it had a name. Neither behavior is right or wrong, they're just different.

According to the ARIA specifications, `role="alert"` contents on page load should be announced but in practice I found they often aren't. macOS VoiceOver + Safari did not, NVDA + Firefox did not, NVDA + Chrome did, iOS 18.7.2 VoiceOver + Safari did but only the second alert when there were two alerts on the page (role="alert" is implicitly aria-live="assertive" which stops whatever a screen reader is saying to announce its contents, separate alerts are not queued).

Thanks for the information about real-world testing results @cwilcox808!

So, because the existing content of a live region is not announced after page reload (as that is not a content change of an existing page) I was thinking how it should be managed.

As I wrote before, when the page reloads before displaying itself, with the added message: "This situation requires a different approach: the focus should be automatically/programmatically shifted to the message (which is not a "Status message" by definition)."

I do not like that. And I was thinking: what if Drupal displayed all status messages with AJAX (even when the page needs a reload for any other reason)? This way, the message would be a content change of an existing page that can be handled by screen readers when it happens inside a live region (what is automatically created defining role="status").

Related feature in core: https://www.drupal.org/node/3086403 New MessageCommand allows adding messages from an Ajax response

(There used to be a contrib module forAJAX messages too: https://www.drupal.org/project/ajax_msgs)

What do you think about it?

Addition to my previous comment: TIL that htmx is now in Drupal core. So if my AJAX suggestion above is the way, it can be built on htmx.

Some notes to my "AJAX/htmx" messages idea by my teammate Artem Dmitriiev ("a.dmitriiev" here):

In Drupal 7 times, there was no lazy loading of blocks, but now there is starting with Drupal 8, and therefore the message are loaded separately from the main page already in case Big Pipe is enabled. But it is still doing it after page is loaded. There is another problem about messages with ajax, is that the actions the trigger the messages. If it is a form submission, and the form is not using ajax, there will be a page reload anyway, disregarding how message is retrieved.

So time to update Drupal.announce()?

https://www.a11y-collective.com/blog/aria-live/

Just a general observation around system messages. There is often a bit of a delay showing the notification and when it does appear there can be a bit of jump. If there are multiple notifications being shown this is more noticeable depending on your network connection, speed of the server, web browser etc.

I stumbled on these issues when looking at the admin theme too https://www.drupal.org/project/drupal/issues/3587678

I like how the USWDS has done this:
https://designsystem.digital.gov/components/alert/

The UK has an issue in their issue queue from 2024 to implement something like this.

Thanks for the updates @mgifford. This topic is quite complex – but it would be nice to see some progress on it!