[plan] Describe layout builder UI to assistive technology

Problem/Motivation

The layout builder UI, and details of the sections/regions/blocks currently arrangemed inside it, needs to be conveyed to assistive tech users.

Because before a user starts to add/move/delete blocks, they need to know what is there already.

Proposed resolution

Important: these ideas are not mutually exclusive. A balanced combination of all of them might be the most useful.
TODO: Any other approaches we can consider?

Idea 1 - ARIA group role(s) with associated label

This enables a screen reader user to understand what sort of group they have entered, when they are traversing the document using the screen reader in normal browse/read mode, or tabbing through interactive controls.

• Add <div role="group" aria-labelledby=""> grouping wrappers, to name the available sections and regions. Each layout region, and each layout section, gets a group role.
• The accessible name could derive from the *.layouts.yml layout plugin definitions. There are human-readable names for the layout itself (2 column 25%/75%), and the regions inside it (left, right).
• Sections don't have names, so we'll have to describe these using their number (position-in-set) to distinguish them, i.e. "Section 2."
• The layout plugin's name could also be used, but it may not be unique so we'd append it to the numbered section label, e.g.. "Section 2 - two-column layout 25%/75%". Not sure if that belongs in the section's accessible name, or an accessible description (see idea 2)
• Which ARIA container role should be used? Group, section, and region are all possibilities. Note that "region" means a landmark region, and "section" is equivalent to the HTML5 <section> element.

Idea 2 - headings associated with layout section, layout region, and layout block

This enables the layout builder to be navigated using the screen reader's document outline tools. Seriously useful, so a should-have triage.

1. A nested heading element inside each layout section, layout region, and layout block
2. Heading levels: section is H2, region is H3, block is H4.
3. For this stage, the accessible names of the role="group" container will ideally come from an aria-labelledby relationship to the heading element.
4. The headings could be hidden (display: none), .visually-hidden, or even visible (display: block). TODO: use cases for each?
5. Visible block names are necessary for #2959493: Allow Layout Builder live previews to be toggled to allow easier drag-and-drop. These could double as the block's H4, and the toggle would make them visible.
6. Allowing users to make section and region names visible could help in several circumstances. Colleagues discussing the layout, authors and themers who are interested in the responsive re-flow, and some screen magnifier users may use them as signposts in a restricted viewport. Some sketches of this were discussed with andrewmacpherson, tedbow, and the UC Berkely Web Access team. TODO: needs child issue, dig out these details.

Idea 3 - ARIA group role(s) with accessible description

Expanding on idea 2, we could add use aria-describedby to provide a brief summary of what's going on inside each layout section and/or layout region. This provides extra context. Triage as nice-to-have.

1. The summary could be granular, with a summary per section, per region, as well as one at the start of the entire layout builder UI.
2. Nest an hidden text summary inside the start of each layout section (and layout region), with some important summary information <div role="group" aria-labelledby="" aria-describedby="">
3. This summary information would be somewhat like the approaches for describing tables using caption and summary.
4. Layout plugin *.layouts.yml declarations also provide a human-readable "description" field property, but it is optional. Is this a good way to use the description? We could include this in a section's summary.
5. A description for the region group could state the number of blocks currently contained inside.
6. Example for a layout section: A section has an accessible name "Section 2", and the accessible description "3 column layout, 25%/50%/25%"
7. Example for a layout region: A region has an accessible name "Left region", and the accessible description "Contains 3 blocks."
8. Question: which information should go in the accessible name, versus the accessible description? For example the fact that section 2 has a 3 column, 25%/50%/25% layout.

Overall markup

If we combine all 3 ideas, we'll have something like this:

<div role="region" aria-labelledby="section-1-label" aria-describedby="section-1-desc">
  <h2 id="section-1-label" style="display:none;">Section 1</h2>
  <span id="section-1-desc" style="display:none;">2 column, 25% 50% 25%.</span>

  <div role="region" aria-labelledby="section-1-region-1-label" aria-describedby="section-1-region-1-desc">
    <h3 id="section-1-region-1-label" style="display:none;">left region</h3>
    <span id="section-1-region-1-desc" style="display:none;">contains 3 blocks</span>

    // ... blocks have h4
    
  </div><!-- /region -->
</div><!-- /section -->

Remaining Questions, Challenges, and Opportunities

1. Headings are commonly used as the main navigation method by screen reader users. If the layout builder UI makes use of visually-hidden headings, but the block content also contains headings, will these two sets of headings be working at cross-purposes?
   • Possible solution: allow screen reader users to hide the block content previews. In #2959493: Allow Layout Builder live previews to be toggled to allow easier drag-and-drop, we provide a way for users to hide the block content. The initial use case for this was to help sighted pointer users with drag/drop, where large blocks made drag/drop difficult. However it has the bonus effect of hiding the headings which are nested inside block content, so screen reader users can concentrate on the headings which describe the layout builder UI itself.
2. The terms "section" and "region" already have special meanings in HTML5 and ARIA, and they may be announced as roles by screen readers. Will this be a problem? Will it suffice if we choose our labels carefully, like "Layout section 1, left region".
3. Verbosity - how much of this is necessary, vs. nice-to-know, vs. way too much?
4. The ARIA 1.1 roledescription may eventually be useful here, to override role="group". However it is leading-edge feature, not broadly implemented yet. For example we might eventually be able to say <div role="group" roledescription="Layout region">
5. Are the accessible name and description intended solely for assistive tech, or should all users be able to access them somewhere?
6. Should modules be allowed to alter the accessible description? Is an alter hook warranted for that? This might be a bit like the hook_field_formatter_settings_summary_alter()

Remaining tasks

Get opinions from screen reader users in the community, and/or expert advice (walk-throughs, prior art) from wider a11y community.
Implementation.

User interface changes

Markup changes, primarily hidden (and/or visually hidden, not clear which yet...) labels and descriptions for screen readers. No visual changes required to support screen readers, but see other accessibility issues which may toggle these between hidden (or maybe visually-hidden) and visible.

API changes

TBD

Data model changes

TBD