+ 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. +
+)); + export const infoAndExamples = create(({ Markup }) => ( <>Content must be visible without having to scroll both vertically and horizontally.
diff --git a/src/content/test/contrast/index.ts b/src/content/test/contrast/index.ts index 027676294a1..afcd8f79b04 100644 --- a/src/content/test/contrast/index.ts +++ b/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, diff --git a/src/content/test/contrast/ui-components.tsx b/src/content/test/contrast/ui-components.tsx index 8b625c2f231..19c2114a260 100644 --- a/src/content/test/contrast/ui-components.tsx +++ b/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 }) => ( +
+ 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
Visual information used to indicate states and boundaries of active UI Components must have sufficient contrast.
diff --git a/src/content/test/focus/focus-order.tsx b/src/content/test/focus/focus-order.tsx index 385564aa17c..6c179751cec 100644 --- a/src/content/test/focus/focus-order.tsx +++ b/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(() => ( ++ 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. +
+)); + export const infoAndExamples = create(({ Markup }) => ( <>Components must receive focus in an order that preserves meaning and operability.
diff --git a/src/content/test/focus/index.ts b/src/content/test/focus/index.ts index 12d2542c739..636788651fd 100644 --- a/src/content/test/focus/index.ts +++ b/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'; diff --git a/src/content/test/headings/heading-level.tsx b/src/content/test/headings/heading-level.tsx index bb390c4b4d9..a20be641e85 100644 --- a/src/content/test/headings/heading-level.tsx +++ b/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(() => ( ++ 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. +
+)); + export const infoAndExamples = create(({ Markup, Link }) => ( <>A heading's programmatic level must match the level that's presented visually.
diff --git a/src/content/test/headings/index.ts b/src/content/test/headings/index.ts index d7d9f8ff4dc..0891cd7244d 100644 --- a/src/content/test/headings/index.ts +++ b/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, diff --git a/src/content/test/headings/no-missing-headings.tsx b/src/content/test/headings/no-missing-headings.tsx index 9c988e378dd..540a503ccea 100644 --- a/src/content/test/headings/no-missing-headings.tsx +++ b/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(() => ( ++ 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. +
+)); + export const infoAndExamples = create(({ Markup, Link }) => ( <>Text that looks like a heading must be coded as a heading.
diff --git a/src/content/test/images/image-function.tsx b/src/content/test/images/image-function.tsx index 7cb91d06c97..bc33fa0675e 100644 --- a/src/content/test/images/image-function.tsx +++ b/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(() => ( ++ 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. +
+)); + export const infoAndExamples = create(({ Markup }) => ( <>Every image must be correctly coded as either meaningful or decorative.
diff --git a/src/content/test/images/index.ts b/src/content/test/images/index.ts index 9a22c732e34..7bcb82907b6 100644 --- a/src/content/test/images/index.ts +++ b/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 = { diff --git a/src/content/test/keyboard/index.ts b/src/content/test/keyboard/index.ts index a2d298090a5..f90391d8873 100644 --- a/src/content/test/keyboard/index.ts +++ b/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'; diff --git a/src/content/test/keyboard/keyboard-navigation.tsx b/src/content/test/keyboard/keyboard-navigation.tsx index c3bf9ad969d..2dabf0772fe 100644 --- a/src/content/test/keyboard/keyboard-navigation.tsx +++ b/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(() => ( ++ 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. +
+)); + export const infoAndExamples = create(({ Markup, Link }) => (Users must be able to navigate to all interactive interface components using a keyboard.
diff --git a/src/content/test/links/index.ts b/src/content/test/links/index.ts index 05450880ade..37d70287658 100644 --- a/src/content/test/links/index.ts +++ b/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, diff --git a/src/content/test/links/link-purpose.tsx b/src/content/test/links/link-purpose.tsx index 271c428009a..5442b0eaa06 100644 --- a/src/content/test/links/link-purpose.tsx +++ b/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(() => ( ++ 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. +
+)); + export const infoAndExamples = create(({ Markup }) => ( <>A link's purpose must be described to users.
diff --git a/src/content/test/native-widgets/index.ts b/src/content/test/native-widgets/index.ts index 3bf41ee9d02..fcba174e19c 100644 --- a/src/content/test/native-widgets/index.ts +++ b/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 = { diff --git a/src/content/test/native-widgets/instructions.tsx b/src/content/test/native-widgets/instructions.tsx index 8b14437c3bc..68553553360 100644 --- a/src/content/test/native-widgets/instructions.tsx +++ b/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(() => ( ++ 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. +
+)); + +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 }) => ( <>If a native widget has a visible label or instructions, they must be programmatically determinable.
diff --git a/src/content/test/repetitive-content/bypass-blocks.tsx b/src/content/test/repetitive-content/bypass-blocks.tsx index df5086f4826..15e4d339182 100644 --- a/src/content/test/repetitive-content/bypass-blocks.tsx +++ b/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(() => ( ++ 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. +
+)); + export const infoAndExamples = create(({ Markup }) => ( <>A page must provide a keyboard-accessible method to bypass repetitive content.
diff --git a/src/content/test/repetitive-content/index.ts b/src/content/test/repetitive-content/index.ts index 604534b8d3f..4cc18f420f7 100644 --- a/src/content/test/repetitive-content/index.ts +++ b/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'; diff --git a/src/tests/end-to-end/tests/content/__snapshots__/guidance-content.test.ts.snap b/src/tests/end-to-end/tests/content/__snapshots__/guidance-content.test.ts.snap index d8e82195691..b5b4deaf0dd 100644 --- a/src/tests/end-to-end/tests/content/__snapshots__/guidance-content.test.ts.snap +++ b/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 `; -exports[`Guidance Content pages test/adaptableContent/reflow/infoAndExamples matches the snapshot 1`] = ` +exports[`Guidance Content pages test/adaptableContent/reflow matches the snapshot 1`] = `