feat(adaptive-cards): add richCardTitleAsHeading styleOption to opt out of role=heading on rich card titles (#5839)

* feat(adaptive-cards): add richCardTitleAsHeading styleOption to opt out of role=heading on rich card titles

Today the title of hero/thumbnail/audio/video/animation/receipt cards is

rendered with Adaptive Cards style: 'heading', which the Adaptive Cards SDK

exposes as role='heading' + aria-level. This was originally requested in

issue #4327 and shipped in 4.15.3.

Subsequent a11y audits (e.g. for hosts where these cards appear inside a

chat transcript) flag the same heading as 'Unnecessary heading level is

programmatically defined for Title' under MAS 1.3.1 / WCAG 1.3.1, because

card titles inside a chat are not page-level headings and break document

outline tools.

Reconcile the two by making the behavior configurable via

styleOptions.richCardTitleAsHeading. Default is true so existing

consumers (including the original #4327 reporter) keep today's behavior;

consumers can pass false to drop the heading style.

Adds a sibling test heroCard.noHeading.html to the existing

heroCard.heading.html that asserts no .ac-textBlock[role='heading'] is

rendered when richCardTitleAsHeading is false.

* address review comments from automated reviewer

1. heroCard.noHeading.html: scope queries to the hero card activity

   container instead of querying the whole document. Match the title

   text block by its expected text so future text blocks elsewhere on

   the page do not make the test flaky.

2. AdaptiveCardsStyleOptions.ts: drop the incomplete 'reverse request'

   bullet that had no link; keep the @see link to #4327 only.

3. AdaptiveCardBuilder.ts: add https:// prefix to the #4327 URL so

   tooling auto-links it.

* code-review: drop 'as const', narrow doc comment to actual code paths

1. AdaptiveCardBuilder.ts: drop 'as const' on the conditional 'style: heading'.

   AGENTS.md says 'Avoid as'; the original code wrote 'style: heading'

   without any cast because addTextBlock takes Partial<TextBlock>, and

   TextBlock.style accepts string. Same here.

2. AdaptiveCardsStyleOptions.ts: tighten the doc-comment to match the

   actual call graph instead of listing card types.

   Cards that flow through addCommonHeaders today:

     - hero (via addCommon)

     - OAuth (direct)

     - thumbnail no-image branch (via addCommon)

     - animation/audio/video (via CommonCard -> addCommon)

   Cards that DON'T (their titles use direct addTextBlock w/o style:heading):

     - receipt

     - thumbnail with images

     - signin

* trim verbose comments and changelog entry to match repo style

* address review: snapshot both heroCard heading tests + fix changelog format

- heroCard.noHeading.html: add host.snapshot('local') and wait for allImagesLoaded so the captured snapshot is stable.
- heroCard.heading.html: bring the default-styling test to parity with the noHeading test - scope queries to the hero card activity, assert role='heading' on the title text block, and add host.snapshot('local') so both behaviors can be visually compared (per OEvgeny).
- CHANGELOG.md: rewrite the entry in the repo's standard '<verb> <desc>, in PR [#NNNN](url), by [@author](url)' single-line form (per compulim).

* test: commit image snapshot baselines for heroCard heading/noHeading

Generated by running the docker compose / selenium / jest stack from a clean WSL Ubuntu build:

  npm install && npm run build
  docker compose -f docker-compose-wsl2.yml up --detach --scale chrome=2
  ./node_modules/.bin/jest --ci=false --forceExit --runInBand --testPathPattern=heroCard -u

Both snapshots are visually identical (as expected - the only difference is the role='heading' attribute on the title text block, which has no visual styling). The behavioural difference is asserted via the role assertions in each test's JS.

* test: visually highlight [role=heading] in heroCard snapshots

Per OEvgeny: add custom CSS so the role='heading' attribute is visually visible in image snapshots. Adds a small heading-indicator.css (yellow background + dashed red outline on any [role='heading'] element, following the focus-indicator.css pattern), linked from both heroCard.heading.html and heroCard.noHeading.html.

Result: heroCard.heading.html.snap-1.png now shows the highlighted title; heroCard.noHeading.html.snap-1.png stays unhighlighted, so reviewers can visually confirm the role=heading semantics from the snapshots alone.

* Reverse styleOptions so default is falsy

---------

Co-authored-by: Christopher Jennison <cjennison@microsoft.com>
Co-authored-by: Eugene <EOlonov@gmail.com>
Co-authored-by: William Wong <compulim@users.noreply.github.com>

Author: 4 people

CHANGELOG.md

@@ -19,6 +19,11 @@ Legends:
 
 ## [Unreleased]
 
+### Added
+
+- Added `styleOptions.richCardTitleOmitHeadingRole` (default `false`) to opt out of `style: 'heading'` on rich card titles, in PR [#5839](https://github.com/microsoft/BotFramework-WebChat/pull/5839), by [@cjennison](https://github.com/cjennison)
+
+
 ## [4.19.1] - 2026-06-09
 
 ### Changed

__tests__/html2/accessibility/attachment/heading-indicator.css

@@ -0,0 +1,4 @@
+[role='heading'] {
+  background-color: yellow !important;
+  outline: dashed 2px Red !important;
+}

__tests__/html2/accessibility/attachment/heroCard.heading.html

@@ -2,6 +2,7 @@
 <html lang="en-US">
   <head>
     <link href="/assets/index.css" rel="stylesheet" type="text/css" />
+    <link href="heading-indicator.css" rel="stylesheet" type="text/css" />
     <script crossorigin="anonymous" src="/test-harness.js"></script>
     <script crossorigin="anonymous" src="/test-page-object.js"></script>
     <script crossorigin="anonymous" src="/__dist__/webchat-es5.js"></script>
@@ -21,12 +22,21 @@
 
         await pageObjects.sendMessageViaSendBox('herocard', { waitForSend: true });
         await pageConditions.minNumActivitiesShown(2);
+        await pageConditions.allImagesLoaded();
         await pageConditions.scrollToBottomCompleted();
 
-        expect(document.querySelector('.ac-textBlock[role="heading"]')).toHaveProperty(
-          'innerText',
-          '\u200BDetails about image 1\u200B'
+        const heroCardActivity = Array.from(webChatElement.querySelectorAll('.webchat__basic-transcript__activity')).find(
+          (activity) => !!activity.querySelector('.ac-textBlock')
         );
+        expect(heroCardActivity).toBeTruthy();
+
+        const titleTextBlock = Array.from(heroCardActivity.querySelectorAll('.ac-textBlock')).find(
+          (block) => block.innerText === '\u200BDetails about image 1\u200B'
+        );
+        expect(titleTextBlock).toBeTruthy();
+        expect(titleTextBlock.getAttribute('role')).toBe('heading');
+
+        await host.snapshot('local');
       });
     </script>
   </body>

__tests__/html2/accessibility/attachment/heroCard.heading.html.snap-1.png

@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en-US">
+  <head>
+    <link href="/assets/index.css" rel="stylesheet" type="text/css" />
+    <link href="heading-indicator.css" rel="stylesheet" type="text/css" />
+    <script crossorigin="anonymous" src="/test-harness.js"></script>
+    <script crossorigin="anonymous" src="/test-page-object.js"></script>
+    <script crossorigin="anonymous" src="/__dist__/webchat-es5.js"></script>
+  </head>
+  <body>
+    <main id="webchat"></main>
+    <script>
+      run(async function () {
+        const store = testHelpers.createStore();
+        const directLine = WebChat.createDirectLine({ token: await testHelpers.token.fetchDirectLineToken() });
+        const styleOptions = { richCardTitleOmitHeadingRole: true };
+        const baseProps = { directLine, store, styleOptions };
+        const webChatElement = document.getElementById('webchat');
+
+        WebChat.renderWebChat(baseProps, webChatElement);
+
+        await pageConditions.uiConnected();
+
+        await pageObjects.sendMessageViaSendBox('herocard', { waitForSend: true });
+        await pageConditions.minNumActivitiesShown(2);
+        await pageConditions.allImagesLoaded();
+        await pageConditions.scrollToBottomCompleted();
+
+        const heroCardActivity = Array.from(webChatElement.querySelectorAll('.webchat__basic-transcript__activity')).find(
+          (activity) => !!activity.querySelector('.ac-textBlock')
+        );
+        expect(heroCardActivity).toBeTruthy();
+
+        const titleTextBlock = Array.from(heroCardActivity.querySelectorAll('.ac-textBlock')).find(
+          (block) => block.innerText === '\u200BDetails about image 1\u200B'
+        );
+        expect(titleTextBlock).toBeTruthy();
+
+        expect(titleTextBlock.getAttribute('role')).toBe(null);
+        expect(heroCardActivity.querySelector('.ac-textBlock[role="heading"]')).toBe(null);
+
+        await host.snapshot('local');
+      });
+    </script>
+  </body>
+</html>

__tests__/html2/accessibility/attachment/heroCard.noHeading.html

@@ -25,6 +25,14 @@ type StrictAdaptiveCardsStyleOptions = {
    * Enable title (and subtitle) wrapping
    */
   richCardWrapTitle: boolean | undefined;
+
+  /**
+   * Cards: Rich Cards
+   * When `true`, omits `style: 'heading'` from the title so the rendered TextBlock has no
+   * `role="heading"` / `aria-level`. Defaults to `false` (existing behavior keeps the heading
+   * style; see issue #4327).
+   */
+  richCardTitleOmitHeadingRole: boolean | undefined;
 };
 
 type AdaptiveCardsStyleOptions = Partial<StrictAdaptiveCardsStyleOptions>;

__tests__/html2/accessibility/attachment/heroCard.noHeading.html.snap-1.png

@@ -119,11 +119,11 @@ export default class AdaptiveCardBuilder {
   }
 
   addCommonHeaders(content: ICommonContent) {
-    const { richCardWrapTitle } = this.styleOptions;
+    const { richCardTitleOmitHeadingRole, richCardWrapTitle } = this.styleOptions;
     this.addTextBlock(content.title, {
+      ...(richCardTitleOmitHeadingRole ? {} : { style: 'heading' }),
       color: TextColor.Default,
       size: TextSize.Medium,
-      style: 'heading',
       weight: TextWeight.Bolder,
       wrap: richCardWrapTitle
     });

packages/bundle/src/adaptiveCards/AdaptiveCardsStyleOptions.ts

@@ -5,6 +5,7 @@ const ADAPTIVE_CARDS_DEFAULT_STYLE_OPTIONS: Required<AdaptiveCardsStyleOptions>
   cardEmphasisBackgroundColor: '#F9F9F9',
   cardPushButtonBackgroundColor: '#0063B1',
   cardPushButtonTextColor: 'White',
+  richCardTitleOmitHeadingRole: false,
   richCardWrapTitle: false
 };