From 0fe8f920b76fcf523bfa08bb43eac4f487858c12 Mon Sep 17 00:00:00 2001
From: "Patrick H. Lauke" <redux@splintered.co.uk>
Date: Wed, 23 Dec 2015 22:09:33 +0000
Subject: [PATCH 1/2] Docs: reintroduce aria-describedby advice for help text

Based on v3 http://getbootstrap.com/css/#forms-help-text, adapted to
make examples more "real life"
---
 docs/components/forms.md | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/docs/components/forms.md b/docs/components/forms.md
index f40904f8ec..ee001a4730 100644
--- a/docs/components/forms.md
+++ b/docs/components/forms.md
@@ -517,19 +517,33 @@ Wrap inputs in grid columns, or any custom parent element, to easily enforce des
 
 No official help text classes exist in Bootstrap 4 (previously we had `.help-block` in v3), but thanks to our utility classes like `.text-muted`, you can create much more flexible help text as you need it.
 
+{% callout warning %}
+#### Associating help text with form controls
+
+Help text should be explicitly associated with the form control it relates to using the `aria-describedby` attribute. This will ensure that assistive technologies – such as screen readers – will announce this help text when the user focuses or enters the control.
+{% endcallout %}
+
 Inline text can use any typical inline HTML element (be it a `<small>`, `<span>`, or something else).
 
 {% example html %}
-<small class="text-muted">
-  Some inline text with a small tag looks like this.
-</small>
+<form class="form-inline">
+  <div class="form-group">
+    <label for="inputPassword4">Password</label>
+    <input type="password" id="inputPassword4" class="form-control" aria-describedby="passwordHelpInline">
+    <small id="passwordHelpInline" class="text-muted">
+      Must be 8-20 characters long.
+    </small>
+  </div>
+</form>
 {% endexample %}
 
 Block help text—for below inputs or for longer lines of help text—can be easily achieved with a `<p>`.
 
 {% example html %}
-<p class="text-muted">
-  A block of help text that breaks onto a new line and may extend beyond one line.
+<label for="inputPassword5">Password</label>
+<input type="password" id="inputPassword5" class="form-control" aria-describedby="passwordHelpBlock">
+<p id="passwordHelpBlock" class="text-muted">
+  Your password must be 8-20 characters long, contain letters and numbers, and must not contain spaces, special characters or emoji. 
 </p>
 {% endexample %}
 

From e9ccb573efb240a88ca6b4e7594746faacf8d1d1 Mon Sep 17 00:00:00 2001
From: "Patrick H. Lauke" <redux@splintered.co.uk>
Date: Thu, 24 Dec 2015 10:11:33 +0000
Subject: [PATCH 2/2] Add aria-describedby to main form controls example

---
 docs/components/forms.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/components/forms.md b/docs/components/forms.md
index ee001a4730..a4e0addc40 100644
--- a/docs/components/forms.md
+++ b/docs/components/forms.md
@@ -21,8 +21,8 @@ Remember, since Bootstrap utilizes the HTML5 doctype, **all inputs must have a `
 <form>
   <fieldset class="form-group">
     <label for="exampleInputEmail1">Email address</label>
-    <input type="email" class="form-control" id="exampleInputEmail1" placeholder="Enter email">
-    <small class="text-muted">We'll never share your email with anyone else.</small>
+    <input type="email" class="form-control" id="exampleInputEmail1" aria-describedby="emailHelp" placeholder="Enter email">
+    <small id="emailHelp" class="text-muted">We'll never share your email with anyone else.</small>
   </fieldset>
   <fieldset class="form-group">
     <label for="exampleInputPassword1">Password</label>
@@ -54,8 +54,8 @@ Remember, since Bootstrap utilizes the HTML5 doctype, **all inputs must have a `
   </fieldset>
   <fieldset class="form-group">
     <label for="exampleInputFile">File input</label>
-    <input type="file" class="form-control-file" id="exampleInputFile">
-    <small class="text-muted">This is some placeholder block-level help text for the above input. It's a bit lighter and easily wraps to a new line.</small>
+    <input type="file" class="form-control-file" id="exampleInputFile" aria-describedby="fileHelp">
+    <small id="fileHelp" class="text-muted">This is some placeholder block-level help text for the above input. It's a bit lighter and easily wraps to a new line.</small>
   </fieldset>
   <div class="radio">
     <label>