thisisdano · May 10, 2023 · Oct 14, 2022 · Oct 21, 2022 · Oct 21, 2022 · Oct 21, 2022
diff --git a/_components/form/form.md b/_components/form/form.md
@@ -25,7 +25,7 @@ changelog:
 
 <div class="site-note"><strong>Note:</strong> If you are a building a form with multiple controls, also consider the <a href="{{ site.baseurl }}/form-templates/">accessibility guidelines on the “Form Templates” page</a>.</div>
 
-{% include accessibility.html %}
+{% include forms-guidance.html %}
 
 <div id="settings" class="usa-prose site-prose margin-top-5">
   <h3 class="usa-heading heading-margin-alt">Form settings</h3>

diff --git a/_data/changelogs/component-form.yml b/_data/changelogs/component-form.yml
@@ -1,3 +1,6 @@
+# Note: This changelog is used on multiple pages:
+# templates/form-templates
+# components/form
 title: Form
 type: component
 changelogURL:

diff --git a/_data/changelogs/template-form.yml b/_data/changelogs/template-form.yml
diff --git a/_includes/accessibility.html b/_includes/accessibility.html
diff --git a/_includes/forms-guidance.html b/_includes/forms-guidance.html
@@ -0,0 +1,59 @@
+<section class="usa-prose site-prose margin-top-5">
+  <h2 id="general-accessibility-guidance-for-forms">Accessibility guidance</h2>
+  <ul class="usa-content-list">
+    <li><strong>Don’t control element order with CSS.</strong> Display form controls in the same order in the HTML as
+      they appear on screen. Don’t use CSS to rearrange the form controls. Screen readers narrate form elements in the
+      order they appear in the HTML.</li>
+    <li><strong>Align validation with inputs.</strong> Visually align validation messages with the input fields so
+      people using screen magnifiers can read them quickly.</li>
+    <li><strong>Use proper markup.</strong> Group each set of thematically related controls in a fieldset element. Use
+      the legend element to offer a label within each one. The fieldset and legend elements make it easier for those who
+      use screen readers to navigate the form.</li>
+    <li><strong>Use legends.</strong> Use a single legend for fieldset (this is required). One common use of the
+      fieldset and legend elements is a question with radio-button options for answers. The question text and radio
+      buttons are wrapped in a fieldset, with the question itself being inside the legend tag.</li>
+    <li><strong>Embed multiple fieldsets and legends for more complex forms.</strong></li>
+    <li><strong>Use simple vertical layouts.</strong> Keep your form blocks in a vertical pattern. This approach is
+      ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.
+    </li>
+  </ul>
+  <h2 id="identifying-required-fields">Identifying required fields</h2>
+  <ul class="usa-content-list">
+    <li><strong>Show whether a field is required or optional.</strong> Mark required fields as required by using a red
+      asterisk (<abbr title="required" class="usa-hint--required">*</abbr>).</li>
+    <li><strong>Use text descriptions.</strong> Combine red asterisks (<abbr title="required"
+        class="usa-hint--required">*</abbr>) with a text description at the top of the form instructing the user of its
+      meaning. <br />
+      <em>Example:</em> “A red asterisk (<abbr title="required" class="usa-hint--required">*</abbr>) indicates a
+      required field.”
+    </li>
+    <li><strong>Use the <code>required</code> attribute.</strong> Add the <code>required</code> attribute to your form
+      elements to indicate that a field must be filled out before submitting the form.</li>
+    <li><strong>Mark optional fields as "optional."</strong> Label optional fields with the word “optional” placed in
+      parentheses. <br />
+      <em>Example:</em> (optional)
+    </li>
+    <li><strong>Let users know if there is an error.</strong> Use a message or <a
+        href="{{ site.baseurl }}/components/alert">alert</a> to notify the user if a field that is required was not
+      completed, and indicate which field was not completed. Additionally, include an error notification in the page
+      title (<code>title</code> element) for screen readers.</li>
+    <li><em><strong>Note:</strong> One-field forms are the exception and do not need to be marked with a required label or symbol.</em>
+    </li>
+  </ul>
+
+  <h2 id="known-issues-with-screen-readers">Known issues with screen readers</h2>
+  <ul class="usa-content-list">
+    <li>VoiceOver on iOS currently does not support fieldset and legend elements for forms. You can address this issue
+      by using <code>aria-labelledby="for-attribute-of-label id-of-legend id-of-additional-info"</code> on each input in
+      the fieldset. Using <code>aria-labelledby</code> will overwrite the default text read by the screen reader, so it
+      is important to include all relevant information.</li>
+    <li>
+      VoiceOver on OS X offers partial support for <code>aria-describedby</code>. There's full support for conveying
+      description on text inputs, partial support for description changes when the text input is in focus, and no
+      support for <code>role="alert"</code>. Visit <a
+        href="https://a11ysupport.io/tech/aria/aria-describedby_attribute">a11ysupport.io</a> to view the full status of
+      support.</li>
+  </ul>
+  <div class="site-note"><strong>Note:</strong> These components have been designed to support a wide range of screen
+    readers, but they may not work with all versions.</div>
+</section>
diff --git a/_templates/form-templates/form-templates.md b/_templates/form-templates/form-templates.md
@@ -17,7 +17,7 @@ subnav:
   - text: Latest updates
     href: '#changelog'
 changelog:
-  key: template-form
+  key: component-form
 ---
 
-{% include accessibility.html %}
+{% include forms-guidance.html %}
diff --git a/css/_uswds-theme-custom-styles.scss b/css/_uswds-theme-custom-styles.scss
@@ -66,6 +66,10 @@ img {
   @include typeset("lang");
 }
 
+abbr[title="required"] {
+  text-decoration: none;
+}
+
 // ========================================
 // 2. Site layout
 // ----------------------------------------