Merge branch 'main' of https://github.com/ScanGov/docs

lukefretwell · lukefretwell · commit b1bdc062de4e · 2025-02-13T14:55:00.000-08:00
diff --git a/_pages/a11y-aria.md b/_pages/a11y-aria.md
@@ -10,99 +10,99 @@ topics:
   - Accessibility
 ---
 
-These are opportunities to improve the usage of ARIA in your application which may enhance the experience for users of assistive technology, like a screen reader.
+You don't always need `aria-` attributes in your application for it to be accessible. When you do use `aria-` attributes follow these recommendations to make sure they are helpful.
 
 ## Contains
 
-### `[aria-*]` attributes match their roles
+## [aria-*] attributes match their roles
 
 Each ARIA `role` supports a specific subset of `aria-*` attributes. Mismatching these invalidates the `aria-*` attributes. [Learn how to match ARIA attributes to their roles](https://dequeuniversity.com/rules/axe/4.10/aria-allowed-attr).
 
-### Uses ARIA roles only on compatible elements
+## Uses ARIA roles only on compatible elements
 
 Many HTML elements can only be assigned certain ARIA roles. Using ARIA roles where they are not allowed can interfere with the accessibility of the web page. [Learn more about ARIA roles](https://dequeuniversity.com/rules/axe/4.10/aria-allowed-role).
 
-### `button`, `link`, and `menuitem` elements have accessible names
+## button, link, and menuitem elements have accessible names
 
 When an element doesn't have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn how to make command elements more accessible](https://dequeuniversity.com/rules/axe/4.10/aria-command-name).
 
-### ARIA attributes are used as specified for the element's role
+## ARIA attributes are used as specified for the element's role
 
 Some ARIA attributes are only allowed on an element under certain conditions. [Learn more about conditional ARIA attributes](https://dequeuniversity.com/rules/axe/4.10/aria-conditional-attr).
 
-### Deprecated ARIA roles were not used
+## Deprecated ARIA roles were not used
 
 Deprecated ARIA roles may not be processed correctly by assistive technology. [Learn more about deprecated ARIA roles](https://dequeuniversity.com/rules/axe/4.10/aria-deprecated-role).
 
-### Elements with `role="dialog"` or `role="alertdialog"` have accessible names.
+## Elements with role="dialog" or role="alertdialog" have accessible names.
 
 ARIA dialog elements without accessible names may prevent screen readers users from discerning the purpose of these elements. [Learn how to make ARIA dialog elements more accessible](https://dequeuniversity.com/rules/axe/4.10/aria-dialog-name).
 
-### `[aria-hidden="true"]` is not present on the document `<body>`
+## [aria-hidden="true"] is not present on the document <body>
 
 Assistive technologies, like screen readers, work inconsistently when `aria-hidden="true"` is set on the document `<body>`. [Learn how `aria-hidden` affects the document body](https://dequeuniversity.com/rules/axe/4.10/aria-hidden-body).
 
-### `[aria-hidden="true"]` elements do not contain focusable descendents
+## [aria-hidden="true"] elements do not contain focusable descendents
 
 Focusable descendents within an `[aria-hidden="true"]` element prevent those interactive elements from being available to users of assistive technologies like screen readers. [Learn how `aria-hidden` affects focusable elements](https://dequeuniversity.com/rules/axe/4.10/aria-hidden-focus).
 
-### ARIA input fields have accessible names
+## ARIA input fields have accessible names
 
 When an input field doesn't have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn more about input field labels](https://dequeuniversity.com/rules/axe/4.10/aria-input-field-name).
 
-### ARIA `meter` elements have accessible names
+## ARIA meter elements have accessible names
 
 When a meter element doesn't have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn how to name `meter` elements](https://dequeuniversity.com/rules/axe/4.10/aria-meter-name).
 
-### ARIA `progressbar` elements have accessible names
+## ARIA progressbar elements have accessible names
 
 When a `progressbar` element doesn't have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn how to label `progressbar` elements](https://dequeuniversity.com/rules/axe/4.10/aria-progressbar-name).
 
-### Elements use only permitted ARIA attributes
+## Elements use only permitted ARIA attributes
 
 Using ARIA attributes in roles where they are prohibited can mean that important information is not communicated to users of assistive technologies. [Learn more about prohibited ARIA roles](https://dequeuniversity.com/rules/axe/4.10/aria-prohibited-attr).
 
-### `[role]`s have all required `[aria-*]` attributes
+## [role]s have all required [aria-*] attributes
 
 Some ARIA roles have required attributes that describe the state of the element to screen readers. [Learn more about roles and required attributes](https://dequeuniversity.com/rules/axe/4.10/aria-required-attr).
 
-### Elements with an ARIA `[role]` that require children to contain a specific `[role]` have all required children.
+## Elements with an ARIA `[role]` that require children to contain a specific `[role]` have all required children.
 
 Some ARIA parent roles must contain specific child roles to perform their intended accessibility functions. [Learn more about roles and required children elements](https://dequeuniversity.com/rules/axe/4.10/aria-required-children).
 
-### `[role]`s are contained by their required parent element
+## [role]s are contained by their required parent element
 
 Some ARIA child roles must be contained by specific parent roles to properly perform their intended accessibility functions. [Learn more about ARIA roles and required parent element](https://dequeuniversity.com/rules/axe/4.10/aria-required-parent).
 
-### `[role]` values are valid
+## [role] values are valid
 
 ARIA roles must have valid values in order to perform their intended accessibility functions. [Learn more about valid ARIA roles](https://dequeuniversity.com/rules/axe/4.10/aria-roles).
 
-### Elements with the `role=text` attribute do not have focusable descendents.
+## Elements with the role=text attribute do not have focusable descendents.
 
 Adding `role=text` around a text node split by markup enables VoiceOver to treat it as one phrase, but the element's focusable descendents will not be announced. [Learn more about the `role=text` attribute](https://dequeuniversity.com/rules/axe/4.10/aria-text).
 
-### ARIA toggle fields have accessible names
+## ARIA toggle fields have accessible names
 
 When a toggle field doesn't have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn more about toggle fields](https://dequeuniversity.com/rules/axe/4.10/aria-toggle-field-name).
 
-### ARIA `tooltip` elements have accessible names
+## ARIA tooltip elements have accessible names
 
 When a tooltip element doesn't have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn how to name `tooltip` elements](https://dequeuniversity.com/rules/axe/4.10/aria-tooltip-name).
 
-### ARIA `treeitem` elements have accessible names
+## ARIA treeitem elements have accessible names
 
 When a `treeitem` element doesn't have an accessible name, screen readers announce it with a generic name, making it unusable for users who rely on screen readers. [Learn more about labeling `treeitem` elements](https://dequeuniversity.com/rules/axe/4.10/aria-treeitem-name).
 
-### `[aria-*]` attributes have valid values
+## [aria-*] attributes have valid values
 
 Assistive technologies, like screen readers, can't interpret ARIA attributes with invalid values. [Learn more about valid values for ARIA attributes](https://dequeuniversity.com/rules/axe/4.10/aria-valid-attr-value).
 
-### `[aria-*]` attributes are valid and not misspelled
+## [aria-*] attributes are valid and not misspelled
 
 Assistive technologies, like screen readers, can't interpret ARIA attributes with invalid names. [Learn more about valid ARIA attributes](https://dequeuniversity.com/rules/axe/4.10/aria-valid-attr).
 
-### ARIA IDs are unique
+## ARIA IDs are unique
 
 The value of an ARIA ID must be unique to prevent other instances from being overlooked by assistive technologies. [Learn how to fix duplicate ARIA IDs](https://dequeuniversity.com/rules/axe/4.10/duplicate-id-aria).
 
diff --git a/_pages/a11y-audio-video.md b/_pages/a11y-audio-video.md
@@ -10,11 +10,8 @@ topics:
   - Accessibility
 ---
 
-These are opportunities to provide alternative content for audio and video. This may improve the experience for users with hearing or vision impairments.
 
-## Contains
-
-### `<video>` elements contain a `<track>` element with `[kind="captions"]`
+## `<video>` elements contain a `<track>` element with `[kind="captions"]`
 
 When a video provides a caption it is easier for deaf and hearing impaired users to access its information. [Learn more about video captions](https://dequeuniversity.com/rules/axe/4.10/video-caption).
 
diff --git a/_pages/a11y-best-practices.md b/_pages/a11y-best-practices.md
@@ -10,19 +10,17 @@ topics:
   - Accessibility
 ---
 
-These items highlight common accessibility best practices.
+Accessibilty can be improved by passing the following tests:
 
-## Contains
-
-### The document does not use `<meta http-equiv="refresh">`
+## The document does not use <meta http-equiv="refresh">
 
 Users do not expect a page to refresh automatically, and doing so will move focus back to the top of the page. This may create a frustrating or confusing experience. [Learn more about the refresh meta tag](https://dequeuniversity.com/rules/axe/4.10/meta-refresh).
 
-### `[user-scalable="no"]` is not used in the `<meta name="viewport">` element and the `[maximum-scale]` attribute is not less than 5.
+## [user-scalable="no"] is not used in the <meta name="viewport"> element and the [maximum-scale] attribute is not less than 5.
 
 Disabling zooming is problematic for users with low vision who rely on screen magnification to properly see the contents of a web page. [Learn more about the viewport meta tag](https://dequeuniversity.com/rules/axe/4.10/meta-viewport).
 
-### Touch targets do not have sufficient size or spacing.
+## Touch targets do not have sufficient size or spacing.
 
 Touch targets with sufficient size and spacing help users who may have difficulty targeting small controls to activate the targets. [Learn more about touch targets](https://dequeuniversity.com/rules/axe/4.10/target-size).
 
diff --git a/_pages/a11y-color-contrast.md b/_pages/a11y-color-contrast.md
@@ -10,15 +10,13 @@ topics:
   - Accessibility
 ---
 
-These are opportunities to improve the legibility of your content.
+Content legibility can be improved by passing the following audits:
 
-## Contains
-
-### Background and foreground colors have a sufficient contrast ratio
+## Background and foreground colors have a sufficient contrast ratio
 
 Low-contrast text is difficult or impossible for many users to read. [Learn how to provide sufficient color contrast](https://dequeuniversity.com/rules/axe/4.10/color-contrast).
 
-### Links are distinguishable without relying on color.
+## Links are distinguishable without relying on color.
 
 Low-contrast text is difficult or impossible for many users to read. Link text that is discernible improves the experience for users with low vision. [Learn how to make links distinguishable](https://dequeuniversity.com/rules/axe/4.10/link-in-text-block).
 
diff --git a/_pages/a11y-language.md b/_pages/a11y-language.md
@@ -10,23 +10,21 @@ topics:
   - Accessibility
 ---
 
-These are opportunities to improve the interpretation of your content by users in different locales.
+Follow these recommendations to improve the experience for visitors who may take advantage of translations.
 
-## Contains
-
-### `<html>` element has a `[lang]` attribute
+## <html> element has a [lang] attribute
 
 If a page doesn't specify a `lang` attribute, a screen reader assumes that the page is in the default language that the user chose when setting up the screen reader. If the page isn't actually in the default language, then the screen reader might not announce the page's text correctly. [Learn more about the `lang` attribute](https://dequeuniversity.com/rules/axe/4.10/html-has-lang).
 
-### `<html>` element has a valid value for its `[lang]` attribute
+## <html> element has a valid value for its [lang] attribute
 
 Specifying a valid [BCP 47 language](https://www.w3.org/International/questions/qa-choosing-language-tags#question) helps screen readers announce text properly. [Learn how to use the `lang` attribute](https://dequeuniversity.com/rules/axe/4.10/html-lang-valid).
 
-### `<html>` element has an `[xml:lang]` attribute with the same base language as the `[lang]` attribute.
+## <html> element has an [xml:lang] attribute with the same base language as the [lang] attribute.
 
 If the webpage does not specify a consistent language, then the screen reader might not announce the page's text correctly. [Learn more about the `lang` attribute](https://dequeuniversity.com/rules/axe/4.10/html-xml-lang-mismatch).
 
-### `[lang]` attributes have a valid value
+## [lang] attributes have a valid value
 
 Specifying a valid [BCP 47 language](https://www.w3.org/International/questions/qa-choosing-language-tags#question) on elements helps ensure that text is pronounced correctly by a screen reader. [Learn how to use the `lang` attribute](https://dequeuniversity.com/rules/axe/4.10/valid-lang).
 
diff --git a/_pages/a11y-names-labels.md b/_pages/a11y-names-labels.md
@@ -10,59 +10,57 @@ topics:
   - Accessibility
 ---
 
-These are opportunities to improve the semantics of the controls in your application. This may enhance the experience for users of assistive technology, like a screen reader.
+Enhance your application's usability for visitors using screen readers by following these recommendations:
 
-## Contains
-
-### Buttons have an accessible name
+## Buttons have an accessible name
 
 When a button doesn't have an accessible name, screen readers announce it as "button", making it unusable for users who rely on screen readers. [Learn how to make buttons more accessible](https://dequeuniversity.com/rules/axe/4.10/button-name).
 
-### Document has a `<title>` element
+## Document has a <title> element
 
 The title gives screen reader users an overview of the page, and search engine users rely on it heavily to determine if a page is relevant to their search. [Learn more about document titles](https://dequeuniversity.com/rules/axe/4.10/document-title).
 
-### No form fields have multiple labels
+## No form fields have multiple labels
 
 Form fields with multiple labels can be confusingly announced by assistive technologies like screen readers which use either the first, the last, or all of the labels. [Learn how to use form labels](https://dequeuniversity.com/rules/axe/4.10/form-field-multiple-labels).
 
-### `<frame>` or `<iframe>` elements have a title
+## <frame> or <iframe> elements have a title
 
 Screen reader users rely on frame titles to describe the contents of frames. [Learn more about frame titles](https://dequeuniversity.com/rules/axe/4.10/frame-title).
 
-### Image elements have `[alt]` attributes
+## Image elements have [alt] attributes
 
 Informative elements should aim for short, descriptive alternate text. Decorative elements can be ignored with an empty alt attribute. [Learn more about the `alt` attribute](https://dequeuniversity.com/rules/axe/4.10/image-alt).
 
-### Image elements do not have `[alt]` attributes that are redundant text.
+## Image elements do not have [alt] attributes that are redundant text.
 
 Informative elements should aim for short, descriptive alternative text. Alternative text that is exactly the same as the text adjacent to the link or image is potentially confusing for screen reader users, because the text will be read twice. [Learn more about the `alt` attribute](https://dequeuniversity.com/rules/axe/4.10/image-redundant-alt).
 
-### Input buttons have discernible text.
+## Input buttons have discernible text.
 
 Adding discernable and accessible text to input buttons may help screen reader users understand the purpose of the input button. [Learn more about input buttons](https://dequeuniversity.com/rules/axe/4.10/input-button-name).
 
-### `<input type="image">` elements have `[alt]` text
+## <input type="image"> elements have [alt] text
 
 When an image is being used as an `<input>` button, providing alternative text can help screen reader users understand the purpose of the button. [Learn about input image alt text](https://dequeuniversity.com/rules/axe/4.10/input-image-alt).
 
-### Form elements have associated labels
+## Form elements have associated labels
 
 Labels ensure that form controls are announced properly by assistive technologies, like screen readers. [Learn more about form element labels](https://dequeuniversity.com/rules/axe/4.10/label).
 
-### Links have a discernible name
+## Links have a discernible name
 
 Link text (and alternate text for images, when used as links) that is discernible, unique, and focusable improves the navigation experience for screen reader users. [Learn how to make links accessible](https://dequeuniversity.com/rules/axe/4.10/link-name).
 
-### `<object>` elements have alternate text
+## <object> elements have alternate text
 
 Screen readers cannot translate non-text content. Adding alternate text to `<object>` elements helps screen readers convey meaning to users. [Learn more about alt text for `object` elements](https://dequeuniversity.com/rules/axe/4.10/object-alt).
 
-### Select elements have associated label elements.
+## Select elements have associated label elements.
 
 Form elements without effective labels can create frustrating experiences for screen reader users. [Learn more about the `select` element](https://dequeuniversity.com/rules/axe/4.10/select-name).
 
-### Skip links are focusable.
+## Skip links are focusable.
 
 Including a skip link can help users skip to the main content to save time. [Learn more about skip links](https://dequeuniversity.com/rules/axe/4.10/skip-link).
 
diff --git a/_pages/a11y-navigation.md b/_pages/a11y-navigation.md
@@ -10,23 +10,21 @@ topics:
   - Accessibility
 ---
 
-These are opportunities to improve keyboard navigation in your application.
+Improve accessibility by following these recommendations:
 
-## Contains
-
-### `[accesskey]` values are unique
+## [accesskey] values are unique
 
 Access keys let users quickly focus a part of the page. For proper navigation, each access key must be unique. [Learn more about access keys](https://dequeuniversity.com/rules/axe/4.10/accesskeys).
 
-### The page contains a heading, skip link, or landmark region
+## The page contains a heading, skip link, or landmark region
 
 Adding ways to bypass repetitive content lets keyboard users navigate the page more efficiently. [Learn more about bypass blocks](https://dequeuniversity.com/rules/axe/4.10/bypass).
 
-### Heading elements appear in a sequentially-descending order
+## Heading elements appear in a sequentially-descending order
 
 Properly ordered headings that do not skip levels convey the semantic structure of the page, making it easier to navigate and understand when using assistive technologies. [Learn more about heading order](https://dequeuniversity.com/rules/axe/4.10/heading-order).
 
-### No element has a `[tabindex]` value greater than 0
+## No element has a [tabindex] value greater than 0
 
 A value greater than 0 implies an explicit navigation ordering. Although technically valid, this often creates frustrating experiences for users who rely on assistive technologies. [Learn more about the `tabindex` attribute](https://dequeuniversity.com/rules/axe/4.10/tabindex).
 
diff --git a/_pages/a11y-tables-lists.md b/_pages/a11y-tables-lists.md
diff --git a/_pages/hidden.md b/_pages/hidden.md
diff --git a/package.json b/package.json
