uswds · annepetersen · Oct 4, 2024 · Aug 11, 2024 · Aug 11, 2024 · Aug 12, 2024
diff --git a/_data/changelogs/component-form.yml b/_data/changelogs/component-form.yml
@@ -5,6 +5,12 @@ title: Form
 type: component
 changelogURL:
 items:
+  - date: 2024-10-04
+    summary: Added guidance discouraging most uses of disabled form inputs.
+    summaryAdditional: We also added guidance on the rare instances when disabled inputs improve usability.
+    affectsGuidance: true
+    githubPr: 2776
+    githubRepo: uswds-site
   - date: 2024-03-11
     summary: Added color contrast checks for disabled tokens.
     summaryAdditional:  On compilation, USWDS will test disabled element color contrast and provide a fallback color if minimum contrast is not met. If the fallback does not meet minimum requirements, USWDS will provide a warning in the terminal.
@@ -15,7 +21,7 @@ items:
     versionUswds: 3.8.0
   - date: 2023-08-23
     summary: Fixed a bug that caused some form inputs to show disabled styles when in forced colors mode.
-    summaryAdditional: 
+    summaryAdditional:
     affectsStyles: true
     affectsAccessibility: true
     githubPr: 5397

diff --git a/_includes/forms-guidance.html b/_includes/forms-guidance.html
@@ -17,6 +17,30 @@ <h2 id="general-accessibility-guidance-for-forms">Accessibility guidance</h2>
       ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.
     </li>
   </ul>
+  <h2 id="disabled-states-for-components-in-forms">Disabled states for components in forms</h2>
+   <ul class="usa-content-list">
+     <li><strong>Avoid disabled states, especially for text inputs.</strong> Disabled states have low color contrast, 
+       do not offer meaningful feedback to screen reader users, and keyboard navigators can’t focus on them. 
+       These states can also be generally confusing to users. Instead, keep form elements enabled. 
+       Offer contextual helper text, tooltips, <a href="https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html">helpful error messages</a> 
+       and inline validation to help people correct mistakes and move through the form.</li>
+     <li><p><strong>If you <i>must</i> use disabled states, follow best practices.</strong> Some disabled states can prevent errors 
+       by telling users that a system is loading or processing (for example, to prevent multiple form 
+       submissions). In specific cases, such as an unavailable date in appointment scheduling, a disabled 
+       state may be helpful to show users that an option exists but is currently unavailable.</p>
+       When using disabled states, be very clear:
+       <ul>
+         <li>Explain why an element is disabled, using helper text or tooltips </li>
+         <li>Use inline validation to minimize errors in real time</li>
+         <li>Support screen reader users and keyboard navigators by using <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-disabled">aria-disabled=true</a> instead of the <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/disabled">disabled</a> attribute
+           to indicate the presence of a disabled element</li>
+         <li>Use JavaScript to programmatically disable the element to prevent clicks</li>
+       </ul>
+      <p>For more detail, you can read 
+        USWDS’s <a href="https://github.com/uswds/uswds/wiki/Disabled-States-Research-Findings-2023">2023 
+        literature review on disabled states</a>.</p> 
+     </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
@@ -56,4 +80,4 @@ <h2 id="known-issues-with-screen-readers">Known issues with screen readers</h2>
   </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>
+</section>