feat(medium-pass-2): Add "why it matters" content for quick assess re…

…quirements (#6317)

#### Details

This PR adds content that will appear in the "Why it matters" gray box
for Quick Assess requirements.

##### Motivation

Feature work 🚀 

##### Context

This PR just adds the new content. A later PR will display this content
for quick assess requirements.

#### Pull request checklist
<!-- If a checklist item is not applicable to this change, write "n/a"
in the checkbox -->
- [n/a] Addresses an existing issue: #0000
- [x] Ran `yarn fastpass`
- [x] Added/updated relevant unit test(s) (and ran `yarn test`)
- [x] Verified code coverage for the changes made. Check coverage report
at: `<rootDir>/test-results/unit/coverage`
- [x] PR title *AND* final merge commit title both start with a semantic
tag (`fix:`, `chore:`, `feat(feature-name):`, `refactor:`). See
`CONTRIBUTING.md`.
- [n/a] (UI changes only) Added screenshots/GIFs to description above
- [n/a] (UI changes only) Verified usability with NVDA/JAWS

Co-authored-by: madalynrose <[email protected]>

src/assessments/types/requirement.ts

@@ -33,6 +33,8 @@ export interface Requirement {
     howToTest: JSX.Element;
     addFailureInstruction?: string;
     infoAndExamples?: ContentPageComponent;
+    whyItMatters?: ContentPageComponent;
+    helpfulResourceLinks?: HyperlinkDefinition[];
     isManual: boolean;
     // This is for semi-manual cases where we can't present a list of instances like an assisted
     // test would, but can infer a PASS or FAIL state. If not specified, acts like () => UNKNOWN.

src/content/test/adaptable-content/index.ts

@@ -4,7 +4,7 @@ import * as contrast from './contrast';
 import { guidance } from './guidance';
 import * as hoverFocusContent from './hover-focus-content';
 import * as orientation from './orientation';
-import * as reflow from './reflow';
+import { infoAndExamples as reflow } from './reflow';
 import * as resizeText from './resize-text';
 import * as textSpacing from './text-spacing';
 

src/content/test/adaptable-content/reflow.tsx

@@ -2,6 +2,15 @@
 // Licensed under the MIT License.
 import { create, React } from '../../common';
 
+export const whyItMatters = create(() => (
+    <p>
+        Having to scroll in two directions is difficult for everyone. Having to scroll in the direction of reading makes reading especially
+        difficult for people with certain disabilities, including people with low vision, who are more likely to need enlarged text in a
+        single column as well as people with reading disabilities that make it difficult to visually track long lines of text. It also
+        impacts people with motor disabilities who find scrolling difficult on the webpage.
+    </p>
+));
+
 export const infoAndExamples = create(({ Markup }) => (
     <>
         <p>Content must be visible without having to scroll both vertically and horizontally.</p>

src/content/test/contrast/index.ts

@@ -3,7 +3,7 @@
 import * as graphics from './graphics';
 import { guidance } from './guidance';
 import * as stateChanges from './state-changes';
-import * as uiComponents from './ui-components';
+import { infoAndExamples as uiComponents } from './ui-components';
 
 export const contrast = {
     guidance,

src/content/test/contrast/ui-components.tsx

@@ -2,6 +2,13 @@
 // Licensed under the MIT License.
 import { create, React } from '../../common';
 
+export const whyItMatters = create(({ Link }) => (
+    <p>
+        Most people find it easier to see and use UI Components when they have sufficient contrast against the background. People with low
+        vision, limited color perception, or <Link.Presbyopia /> are especially likely to struggle with controls when contrast is too low.
+    </p>
+));
+
 export const infoAndExamples = create(({ Markup, Link }) => (
     <>
         <p>Visual information used to indicate states and boundaries of active UI Components must have sufficient contrast.</p>

src/content/test/focus/focus-order.tsx

@@ -2,6 +2,15 @@
 // Licensed under the MIT License.
 import { create, React } from '../../common';
 
+export const whyItMatters = create(() => (
+    <p>
+        When users navigate through a web page, they expect to encounter controls and other content in an order that makes sense and makes
+        it easy to use the page's functionality. Poor focus order can be disorienting to people who use screen readers or screen magnifiers
+        and to people with reading disorders. Poor focus order can also make it difficult or even painful for people who use keyboards
+        because of mobility impairments.
+    </p>
+));
+
 export const infoAndExamples = create(({ Markup }) => (
     <>
         <p>Components must receive focus in an order that preserves meaning and operability.</p>

src/content/test/focus/index.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 import * as closingContent from './closing-content';
-import * as focusOrder from './focus-order';
+import { infoAndExamples as focusOrder } from './focus-order';
 import { guidance } from './guidance';
 import * as modalDialogs from './modal-dialogs';
 import * as revealingContent from './revealing-content';

src/content/test/headings/heading-level.tsx

@@ -2,6 +2,14 @@
 // Licensed under the MIT License.
 import { create, React } from '../../common';
 
+export const whyItMatters = create(() => (
+    <p>
+        Heading levels communicate the relative importance of headings within a page. People with good vision can infer heading levels
+        through visual cues—higher-level headings typically have greater visual prominence than lower-level headings. Users of assistive
+        technology rely on programmatic cues to perceive heading levels.
+    </p>
+));
+
 export const infoAndExamples = create(({ Markup, Link }) => (
     <>
         <p>A heading's programmatic level must match the level that's presented visually.</p>

src/content/test/headings/index.ts

@@ -2,8 +2,8 @@
 // Licensed under the MIT License.
 import { guidance } from './guidance';
 import * as headingFunction from './heading-function';
-import * as headingLevel from './heading-level';
-import * as noMissingHeadings from './no-missing-headings';
+import { infoAndExamples as headingLevel } from './heading-level';
+import { infoAndExamples as noMissingHeadings } from './no-missing-headings';
 
 export const headings = {
     guidance,

src/content/test/headings/no-missing-headings.tsx

@@ -2,6 +2,13 @@
 // Licensed under the MIT License.
 import { create, React } from '../../common';
 
+export const whyItMatters = create(() => (
+    <p>
+        People with good vision can quickly scan a page to identify headings based solely on their appearance, such as large or bold font,
+        preceding white space, or indentation. Users of assistive technologies can't find headings that aren't properly coded.
+    </p>
+));
+
 export const infoAndExamples = create(({ Markup, Link }) => (
     <>
         <p>Text that looks like a heading must be coded as a heading.</p>

src/content/test/images/image-function.tsx

@@ -2,6 +2,14 @@
 // Licensed under the MIT License.
 import { create, React } from '../../common';
 
+export const whyItMatters = create(() => (
+    <p>
+        Screen readers will ignore any image coded as decorative, even if it has an accessible name. Unless an image is coded as decorative,
+        screen readers will assume it's meaningful. In an attempt to communicate the image's meaning, they might announce the image's
+        filename.
+    </p>
+));
+
 export const infoAndExamples = create(({ Markup }) => (
     <>
         <p>Every image must be correctly coded as either meaningful or decorative.</p>

src/content/test/images/index.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 import * as captchas from './captchas';
 import { guidance } from './guidance';
-import * as imageFunction from './image-function';
+import { infoAndExamples as imageFunction } from './image-function';
 import * as imagesOfText from './images-of-text';
 import * as textAlternative from './text-alternative';
 export const images = {

src/content/test/keyboard/index.ts

@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 import * as characterKeyShortcuts from './character-key-shortcuts';
 import { guidance } from './guidance';
-import * as keyboardNavigation from './keyboard-navigation';
+import { infoAndExamples as keyboardNavigation } from './keyboard-navigation';
 import * as noKeyboardTraps from './no-keyboard-traps';
 import * as noKeystrokeTimings from './no-keystroke-timings';
 import * as onFocus from './on-focus';

src/content/test/keyboard/keyboard-navigation.tsx

@@ -2,6 +2,14 @@
 // Licensed under the MIT License.
 import { create, React } from '../../common';
 
+export const whyItMatters = create(() => (
+    <p>
+        Users must be able to navigate to all interactive interface components using a keyboard. Users can't access a web app's
+        functionality if they can't access its interactive interface components. Many people, including those who are blind or who have low
+        vision or hand tremors, rely on a keyboard (or keyboard alternate) to access those components.
+    </p>
+));
+
 export const infoAndExamples = create(({ Markup, Link }) => (
     <React.Fragment>
         <p>Users must be able to navigate to all interactive interface components using a keyboard.</p>

src/content/test/links/index.ts

@@ -3,7 +3,7 @@
 import { guidance } from './guidance';
 import * as labelInName from './label-in-name';
 import * as linkFunction from './link-function';
-import * as linkPurpose from './link-purpose';
+import { infoAndExamples as linkPurpose } from './link-purpose';
 
 export const links = {
     guidance,

src/content/test/links/link-purpose.tsx

@@ -2,6 +2,14 @@
 // Licensed under the MIT License.
 import { create, React } from '../../common';
 
+export const whyItMatters = create(() => (
+    <p>
+        Understanding a link's purpose helps users decide whether they want to follow it. When the link text alone is unclear, sighted users
+        can examine the surrounding context for clues about the link's purpose. Assistive technologies can similarly help non-sighted users
+        by reporting the link's programmatically related context.
+    </p>
+));
+
 export const infoAndExamples = create(({ Markup }) => (
     <>
         <p>A link's purpose must be described to users.</p>

src/content/test/native-widgets/index.ts

@@ -4,7 +4,7 @@ import * as autocomplete from './autocomplete';
 import * as cues from './cues';
 import * as expectedInput from './expected-input';
 import { guidance } from './guidance';
-import * as instructions from './instructions';
+import { infoAndExamples as instructions } from './instructions';
 import * as widgetFunction from './widget-function';
 
 export const nativeWidgets = {

src/content/test/native-widgets/instructions.tsx

@@ -1,7 +1,27 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
+import { HyperlinkDefinition } from '../../../common/types/hyperlink-definition';
 import { create, React } from '../../common';
 
+export const whyItMatters = create(() => (
+    <p>
+        People with good vision can identify a widget's label and instructions by visually scanning the page and interpreting visual
+        characteristics such as proximity. To provide an equivalent experience for people who use assistive technologies, a widget's label
+        and instructions must be programmatically related to it.
+    </p>
+));
+
+export const helpfulResourceLinks: HyperlinkDefinition[] = [
+    {
+        href: 'https://www.youtube.com/watch?v=bAFzL-dOzu0',
+        text: 'Short video on voice control',
+    },
+    {
+        href: 'https://www.youtube.com/watch?v=Mki-ZknCrB4',
+        text: 'Short video on form labels',
+    },
+];
+
 export const infoAndExamples = create(({ Markup, Link }) => (
     <>
         <p>If a native widget has a visible label or instructions, they must be programmatically determinable.</p>

src/content/test/repetitive-content/bypass-blocks.tsx

@@ -2,6 +2,16 @@
 // Licensed under the MIT License.
 import { create, React } from '../../common';
 
+export const whyItMatters = create(() => (
+    <p>
+        Web pages typically have blocks of content that repeat across multiple pages, such as banners and site navigation menus. A person
+        who uses a mouse can visually skim past that repeated content to access a link or other control within the primary content with a
+        single click. Similarly, a bypass mechanism allows keyboard users to navigate directly to the page’s main content without dozens of
+        keystrokes. People with limited mobility could find this task difficult or painful, and people who use screen readers could find it
+        tedious to listen as each repeated element is announced.
+    </p>
+));
+
 export const infoAndExamples = create(({ Markup }) => (
     <>
         <p>A page must provide a keyboard-accessible method to bypass repetitive content.</p>

src/content/test/repetitive-content/index.ts

@@ -1,6 +1,6 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
-import * as bypassBlocks from './bypass-blocks';
+import { infoAndExamples as bypassBlocks } from './bypass-blocks';
 import * as consistentIdentification from './consistent-identification';
 import * as consistentNavigation from './consistent-navigation';
 import { guidance } from './guidance';

src/tests/end-to-end/tests/content/__snapshots__/guidance-content.test.ts.snap

@@ -2905,7 +2905,7 @@ exports[`Guidance Content pages test/adaptableContent/orientation/infoAndExample
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/adaptableContent/reflow/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/adaptableContent/reflow matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"
@@ -5039,7 +5039,7 @@ exports[`Guidance Content pages test/contrast/stateChanges/infoAndExamples match
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/contrast/uiComponents/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/contrast/uiComponents matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"
@@ -10006,7 +10006,7 @@ exports[`Guidance Content pages test/focus/closingContent/infoAndExamples matche
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/focus/focusOrder/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/focus/focusOrder matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"
@@ -12055,7 +12055,7 @@ exports[`Guidance Content pages test/headings/headingFunction/infoAndExamples ma
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/headings/headingLevel/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/headings/headingLevel matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"
@@ -12286,7 +12286,7 @@ exports[`Guidance Content pages test/headings/headingLevel/infoAndExamples match
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/headings/noMissingHeadings/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/headings/noMissingHeadings matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"
@@ -13496,7 +13496,7 @@ exports[`Guidance Content pages test/images/guidance matches the snapshot 1`] =
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/images/imageFunction/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/images/imageFunction matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"
@@ -15536,7 +15536,7 @@ exports[`Guidance Content pages test/keyboard/guidance matches the snapshot 1`]
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/keyboard/keyboardNavigation/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/keyboard/keyboardNavigation matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"
@@ -20098,7 +20098,7 @@ exports[`Guidance Content pages test/links/linkFunction/infoAndExamples matches
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/links/linkPurpose/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/links/linkPurpose matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"
@@ -23619,7 +23619,7 @@ exports[`Guidance Content pages test/nativeWidgets/guidance matches the snapshot
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/nativeWidgets/instructions/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/nativeWidgets/instructions matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"
@@ -26631,7 +26631,7 @@ exports[`Guidance Content pages test/pointerMotion/pointerGestures/infoAndExampl
 </DocumentFragment>
 `;
 
-exports[`Guidance Content pages test/repetitiveContent/bypassBlocks/infoAndExamples matches the snapshot 1`] = `
+exports[`Guidance Content pages test/repetitiveContent/bypassBlocks matches the snapshot 1`] = `
 <DocumentFragment>
   <div
     class="content-container"