Merge pull request #2162 from uswds/al-component-audit-fixes-2

USWDS-Site: Fix component pages from audit (Phase 2)

_components/file-input/guidance/accessibility.md

@@ -1,2 +1,2 @@
-- **Use proper labels and attributes.** Each file input should have a `<label>`. Associate the two by matching the `<label>`’s for attribute to the `<input>`’s `id` attribute.
-- **Use as a progressive enhancement.** The file input component should be a progressive enhancement of `<input type="file" />`. If the component doesn't initialize, it should still work and appear like a standard `file` input.
+- **Use proper labels and attributes.** Each file input should have a `label` element. Associate the label to your input by defining the value of the label’s `for` attribute with the input’s `id`.
+- **Use as a progressive enhancement.** The file input component should be a progressive enhancement of `<input type="file" />`. If the component doesn't initialize, it should still work and appear like a standard `file` input.

_components/file-input/guidance/implementation.md

@@ -1,5 +1,5 @@
 - **Initialization properties.**  JavaScript will create most elements for file input. To get a file input to initialize, add the class name `usa-file-input` to `<input type="file" />`.
 - **Interaction.** When a user selects or drags documents to the file input, the file name and a thumbnail preview are listed.
-- **Using the `accept` attribute.** You can allow certain files by placing an accept attribute on the `<input/>`. If a file type is not accepted, the file will not be attached and the file input will display a message. [Learn more about the accept attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept) [mozilla.org].
-- **Internet Explorer/Edge.** These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.
+- **Limit accepted file types with the `accept` attribute.** Add the `accept` attribute to the `input` element when you want to limit the types of files your input can accept. If a user selects a file that does not match the specified type, the file will not be attached and the file input will display an error message. [Learn more about the accept attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#accept) [mozilla.org].
+- **Internet Explorer and older versions of Edge.** These browsers do not support dragging items to a file input. Instructions to drag files are removed for these browsers.
 - **Customizing the error message.** Add the data attribute `data-errorMessage` to `usa-file-input` to include a custom error message.

_components/file-input/guidance/usability.md

@@ -1,3 +1,3 @@
 - **Allow multiple file formats.** Not everyone has access to the same software. Be flexible with file types to avoid unnecessary software requirements.
-- **Prefer one file per input.** Some users might not know how to select multiple files in a file browser. Additionally, iOS does not allow multiple-file selection using the Files app.
-- **Highlight input restrictions.** Use `usa-hint` to be clear about any file restrictions, such as document types or file size.
+- **Prefer one file per input.** Some users might not know how to select multiple files in a file browser.
+- **Use hint text to highlight input restrictions.** Create an element with the `usa-hint` class to explain any file restrictions, such as document types or file size.

_components/file-input/guidance/when-to-consider-something-else.md

@@ -1,3 +1,3 @@
 - **Documents are optional.** Avoid asking users to provide documents if you don't require them.
-- **Asynchronous upload.** The file input component doesn't support asynchronous uploading. Files are POSTed only on form submission.
-- **Asking for large files.** Be mindful that some users might have limited connectivity or data plans.
+- **Asynchronous upload.** The file input component doesn't support asynchronous uploading. Files will `POST` only on form submission.
+- **Asking for large files.** Be mindful that some users might have limited connectivity or data plans.

_components/footer/footer.md

@@ -28,9 +28,9 @@ tags:
 title: Footer
 type: component
 variants:
-  - variant: usa-footer--big
+  - variant: "`.usa-footer--big`"
     description: A multi-column footer that expands and collapses on mobile.
-  - variant: usa-footer--slim
+  - variant: "`.usa-footer--slim`"
     description: A compact version of the footer.
 changelog:
   key: component-footer

_components/header/header.html

@@ -34,14 +34,8 @@
   key: component-header
 in_page_nav: false
 ---
-
 <h2>When to use a header component</h2>
 <ul class="usa-content-list">
-  <li>
-    <strong>Use the gov banner on all federal websites.</strong> We recommend
-    that all federal government websites include the “official government website”
-    banner and a logo or site name.
-  </li>
   <li>
     <strong>Most websites require header navigation.</strong> Most websites
     require some form of navigation to help users find the information they
@@ -99,85 +93,52 @@ <h2>Header usability</h2>
 <h2 class="usa-heading heading-margin-alt">Header accessibility</h2>
 <ul class="usa-content-list">
   <li>
-    Include skip navigation links to allow users with screen readers to bypass
-    long navigation lists. Make sure you include an id at the beginning of your
-    main content and that it matches the skipnav link. Find more <a href="http://webaim.org/techniques/skipnav/">information on these links</a> at WebAIM.
-
+    <strong>Add a skip navigation link before the header.</strong> Include skip navigation links to allow those using
+    screen readers to bypass long navigation lists. Make sure you include an <code>id</code> at the beginning of your
+    main content and that it matches the skip navigation link. Find more <a
+      href="http://webaim.org/techniques/skipnav/">information on skip navigation links</a> at WebAIM.
   </li>
   <li>
-    Include tab focus for all top-level navigation navigation items — this feature will
-    allow keyboard-reliant users to easily navigate interactive items.
+    <strong>Ensure your horizontal navigation is keyboard compatible.</strong> Test to make sure
+    users can use <code>Tab</code> to navigate and <code>Space</code> (or <code>Enter</code>) to open pages.
   </li>
   <li>
-    Ensure your horizontal navigation is keyboard compatible; test to make sure
-    users can use Tab to navigate and Space (or Enter) to open pages.
+    <strong>Include tab focus for all top-level navigation navigation items.</strong> This feature will
+    allow keyboard-reliant users to easily navigate interactive items.
   </li>
   <li>
-    Avoid using hover to expand dropdown lists. Hover is difficult for some
+    <strong>Avoid using hover to expand dropdown lists.</strong> Hover is difficult for some
     users and won't work on touch screens. Dropdowns should expand on click or
     with keyboard navigation.
   </li>
   <li>
-    The Design System uses semantic header and nav elements with
-    <code>role="banner"</code> and <code>role="navigation"</code> respectively.
-    <code>role="banner"</code> is your masthead.
-  </li>
-  <li>
-    You can use multiple nav elements for groups of navigation links, but you
-    should only use one <code>role="navigation"</code> for the main nav of a
-    page.
+    <strong>Add context by labelling your nav element.</strong> If your page has more than one
+    <code>nav</code> element, use the <code>aria-label</code> attribute to help assistive technology users understand the purpose of the navigation.
   </li>
   <li>
-    Use lists for your nav links — doing so enables screen readers to decipher
-    header contents.
+    <strong>Use list elements for your navigation links.</strong> This helps screen reader users
+    navigate header content.
   </li>
   <li>
-    If you’re using a logo that’s an image rather than text, make sure you
-    include alternative text for screen readers.
+    <strong>Add alt text to your logo image.</strong> If you’re using a logo that’s an image rather than text, make sure
+    you include alternative text for screen readers.
   </li>
   <li>
-    If you’re using a logo that’s text, use an <code>em</code>, not an
+    <strong>Don't use an H1 for your logo.</strong> If you’re using a logo that’s text, use an <code>em</code>, not an
     <code>h1</code>, unless it’s the homepage. Find more information here:
-    <a href="http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/"
-      >http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/.</a
-    >
+    <a
+      href="http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/">http://csswizardry.com/2010/10/your-logo-is-an-image-not-a-h1/.</a>
   </li>
 </ul>
 
-<h2>The “official government website” banner</h2>
-<p>
-  We recommend that all federal government websites include the “official
-  government website” banner and a logo or site name. The banner clearly
-  identifies your website as part of the United States government, while a logo or
-  site name helps visitors understand who you are and what you do.
-</p>
-<h3>Building with HTTPS</h3>
-<p>
-  <a
-    href="https://18f.gsa.gov/2014/11/13/why-we-use-https-in-every-gov-website-we-make/"
-    >HTTPS is a best practice</a
-  >
-  for all websites: It’s secure, private, and fast, and search engines prefer
-  encrypted sites. But it’s especially important for government websites. The
-  .gov in government websites carries a lot of weight. The public expects the
-  contents of .gov websites to be official and accurate, and they expect any
-  information they submit to that website to be private. The U.S. CIO provides
-  guidance to implementing HTTPS for government websites at
-  <a href="https://https.cio.gov/">https://https.cio.gov/.</a>
-</p>
-
 <h2>Further reading</h2>
 <ul>
   <li>
-    <a href="https://www.nngroup.com/articles/menu-design/"
-      >https://www.nngroup.com/articles/menu-design/</a
-    >
+    <a href="https://www.nngroup.com/articles/menu-design/">https://www.nngroup.com/articles/menu-design/</a>
   </li>
   <li>
     <a
-      href="https://www.usertesting.com/blog/site-navigation-tree-testing"
-      >https://www.usertesting.com/blog/site-navigation-tree-testing</a
-    >
+      href="https://help.usertesting.com/hc/en-us/articles/115003372331-What-is-Tree-Testing">https://help.usertesting.com/hc/en-us/articles/115003372331-What-is-Tree-Testing</a>
   </li>
 </ul>
 

_components/icon-list/guidance/accessibility.md

@@ -1,6 +1,6 @@
 - **Don't rely on the icons alone to convey meaning.** Use text and context to establish the meaning of your list, and use the icon to reinforce that meaning as a progressive enhancement.
 - **Use colors with accessible contrast.** While the icons in an icon list might be considered decorative progressive enhancement, aim for accessible AA contrast. This assures legibility on printed pages as well.
-- **Hide most icons from screen readers.** This component uses the `aria-hidden="true"` and `role=”img”` because the icon used solely as visual progressive enhancement. It's meaning should be redundant with the list content.
+- **Hide most icons from screen readers.** This component uses the `aria-hidden="true"` and `role=”img”` attributes because the icons are used solely as a visual progressive enhancement. The icon's meaning is redundant with the list content.
 - **If you wish to expose icons to screen readers:**
   - Provide descriptive text for each icon.
   - Remove the `aria-hidden="true"` attribute and add a `aria-labelledby` attribute with a value that matches the `id` of a title element added inside the svg.

_components/icon-list/icon-list.md

@@ -22,7 +22,7 @@ title: Icon list
 type: component
 variants:
   - variant: "`.usa-icon-list--[color]`"
-    description: Change the color of all the list's icons by updating [color] to any one of the theme colors listed on the [color utilities](/utilities/color) page.
+    description: Change the color of all the list's icons by updating [color] to any [theme](/design-tokens/color/theme-tokens/) or [state](/design-tokens/color/state-tokens/) color token.
   - variant: "`usa-icon-list--size-[size]`"
     description: "Change the size of the text and icon by updating [size] to a [font size token](/design-tokens/typesetting/font-size/)."
   - variant: "`[responsive_variant]:usa-icon-list--size-[size]`"

_components/icon/guidance/accessibility.md

@@ -1,20 +1,23 @@
 - **Hide decorative icons from screen readers.** Use the `aria-hidden="true"` and `role="img"` attributes if the icon is redundant and used solely as visual progressive enhancement as in the following code:
-```html
-<a href="https://twitter.com/uswds">
-  <svg class="usa-icon" aria-hidden="true" role="img">
-    <use xlink:href="/assets/img/sprite.svg#arrow_forward"></use>
-  </svg>
-  USWDS' Twitter account
-</a>
-```
+
+  ```html
+  <a href="https://twitter.com/uswds">
+    <svg class="usa-icon" aria-hidden="true" role="img">
+      <use xlink:href="/assets/img/sprite.svg#arrow_forward"></use>
+    </svg>
+    USWDS' Twitter account
+  </a>
+  ```
+
 - **Provide descriptive text if a standalone icon has semantic meaning.** If you need to expose an icon to screen readers, remove the `aria-hidden="true"` attribute and add an `aria-labelledby` attribute with a value that matches the `id` of a `<title>` element added inside the SVG as in the following code:
-```html
-<a href="https://twitter.com/uswds">
-  <svg aria-labelledby="twitter-title" role="img">
-    <title id="twitter-title">USWDS' Twitter account</title>
-    <use xlink:href="/path/to/sprite.svg#twitter"></use>
-  </svg>
-</a>
-```
+
+  ```html
+  <a href="https://twitter.com/uswds">
+    <svg aria-labelledby="twitter-title" role="img">
+      <title id="twitter-title">USWDS' Twitter account</title>
+      <use xlink:href="/path/to/sprite.svg#twitter"></use>
+    </svg>
+  </a>
+  ```
 - **Check for good color contrast.** Make sure that the icon has a minimum contrast ratio of 3:1 against its background. See [WCAG 2.1 Techniques: Ensuring that a contrast ratio of 3:1 is provided for icons](https://www.w3.org/WAI/WCAG21/Techniques/general/G207) for more information.
 - **Place icons inside links.** If icons accompany a text link, place the icon inside the link to prevent the screen reader from announcing the link twice.

_components/identifier/guidance/implementation.md

@@ -1,5 +1,5 @@
 - **Except where noted, use the entire component without deletions or additions.** With rare exceptions, if you use the identifier, include the entire identifier. That is, don't delete sections or required links or change any link text beyond the customizations mentioned in the implementation section.
-- **Use a background color darker than that of the footer.**  color to anchor the identifier to the bottom of the page and distinguish it from other site content. Use primary or base family background colors of grade `80` or higher, or `black`.
+- **Use a background color darker than that of the footer.** Anchor the identifier to the bottom of the page and distinguish it from other site content by adding a background color that is darker than the footer. Use primary or base family background colors of grade `80` or higher, or `black`.
 - **Use an SVG logo if possible.** Ensure the logo is high resolution. We recommend using the SVG version of any logo if you have one. Otherwise, use an image that's at least 120 pixels tall.
 - **Use logos intended for dark backgrounds if possible.** The identifier has a dark background. If your agency has a version of its logo intended for dark backgrounds, use that version.
 - **Update the required links to point to the proper URLs.** The identifier includes links required of any federal website, and these links are specific to a department, agency, or website. We've linked each section below to the guidance on Digital.gov to provide further context.
@@ -31,6 +31,6 @@
 
     Example: [https://www.dhs.gov/privacy-policy](https://www.dhs.gov/privacy-policy)
 
-- **Use the Spanish version if for Spanish-language sites.** If you have an official Spanish-language website, use the Spanish version of the identifier.
+- **Use the Spanish version for Spanish-language sites.** If you have an official Spanish-language website, use the Spanish version of the identifier.
 - **Duplicate the logo element if using multiple logos.** If you're using multiple logos, duplicate the `usa-identifier__logo` element and link the image to your image source.
 - **If applicable, include any taxpayer disclaimer after the standard text.** If the organization must provide a taxpayer expense disclaimer, include it following the "Official website" text, as a separate sentence. For example, "An official website of [Department]. Produced and published at taxpayer expense."

_components/identifier/guidance/usability.md

@@ -1,5 +1,5 @@
 - **Use the identifier component for required links.** If your site already includes the federally required links in its site footer, remove them in favor of the links in the identifier. This assures that site visitors find the required links in a consistent location from site to site.
 - **Display the parent agency logo, not the product logo.** The identifier is meant to identify a website's parent agency as a complement to the site footer. Site-specific logos, like a product logo, should be in the site footer, not the identifier.
-- **Display multiple parents and logos in hierarchical order.** If a site has more than one parent agency, you may display a reference and a logo for each parent in hierarchical order, highest first. For example,"An official website of [Grandparent Department] and [Parent Agency]".
+- **Display multiple parents and logos in hierarchical order.** If a site has more than one parent agency, you may display a reference and a logo for each parent in hierarchical order, highest first. For example, "An official website of [Grandparent Department] and [Parent Agency]".
 - **Avoid distraction.** The identifier appears on every page of your site. Choose background colors that fit with your site theme and avoid color combinations that draw excessive attention to the identifier.
 - **Keep the text up-to-date.** Use the most current version of the identifier.

_components/input-prefix-suffix/guidance/implementation.md

@@ -1,5 +1,5 @@
-- **Placement.** Place the `.usa-input-prefix` before `.usa-input` and `.usa-input-suffix` after the `.usa-input`. Both elements are placed inside `.usa-input-group`.
+- **Placement matters.** Place the `.usa-input-prefix` element _before_ the `.usa-input` element, and place the `.usa-input-suffix` element _after_ `.usa-input`. Both elements should be placed inside `.usa-input-group`.
 
 - **Use text or icons.** Input prefixes and suffixes can accept either plain text or [icons]({{ site.baseurl }}/components/icon/).
 
-- **Validation.** Place input validation classes on `usa-input-group`.
+- **Use validation styles.** Place [input validation classes](#component-variants-input-prefix-suffix) on `usa-input-group`.

_components/input-prefix-suffix/input-prefix-suffix.md

@@ -28,9 +28,11 @@ tags:
 title: Input prefix or suffix
 type: component
 variants:
-  - variant: "`usa-input-group--error`"
+  - variant: "`.usa-input-group--error`"
     description: Displays an input group error state.
-  - variant: "`usa-input-group--[width]`"
+  - variant: "`.usa-input-group--success`"
+    description: Displays an input group success state.
+  - variant: "`.usa-input-group--[width]`"
     description: Displays an input group at a specific width. Accepts `2xs` (5ex), `xs` (9ex), `sm` or `small` (13ex), `md` or `medium` (20ex), `lg` (30ex), `xl` (40ex), and `2xl` (50ex).
 changelog:
   key: component-input-prefix-suffix