Describe the problem
Whenever the text of the button for an expandable section introduces/summarizes the content it describes, the toggle is also functioning as a heading. In such cases, the user should use the detached variant of the expandable section and wrap the toggle button in a heading element.

This use case should be called out in the examples/documentation.

Expected behavior
The correct way to implement this is to surround the button with the heading tag. For example:

      <h3>
          <button type="button" aria-expanded="true" class="accordion-trigger" aria-controls="sect1" id="accordion1id">
             See more important stuff
              <span class="accordion-icon"></span>
          </button>
      </h3>
        <div id="sect1" role="region" aria-labelledby="accordion1id" class="accordion-panel">
            This is the important stuff that is hidden/shown by the button above
        </div>

The toggleText, 'toggleTextCollapsed, and toggleTextExpanded are typed as strings, but you can use the toggleContent to send a heading

For example:

 <ExpandableSection
      toggleContent={
        <h2>I am a heading</h2>
      }
      onToggle={onToggle}
      isExpanded={isExpanded}
    >
      This content is visible only when the component is expanded.
    </ExpandableSection>

The problem is that the heading tag, in this case, an h2, is a child of the button. This will lead many assistive technologies to tread the heading as presentational so they aren't picked up by the heading list. See: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/button_role#all_descendants_are_presentational

The OCM code base uses numerous expandable sections and new work will be adding additional expanding sections in the near future.

Any other information?

I'm an expert in mediating accessibility issues. Please feel free to contact me via the Internal Red Hat slack if you have questions or need assistance.