adds captions and scop col on thead th (#23755)

1 files changed, 112 insertions, 73 deletions

diff --git a/docs/4.0/content/tables.md b/docs/4.0/content/tables.md
index 515b9b19b..59bdb6373 100644
--- a/docs/4.0/content/tables.md
+++ b/docs/4.0/content/tables.md
@@ -16,10 +16,10 @@ Using the most basic table markup, here's how `.table`-based tables look in Boot
 <table class="table">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -51,10 +51,10 @@ You can also invert the colors—with light text on dark backgrounds—with `.ta
 <table class="table table-dark">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -88,10 +88,10 @@ Similar to tables and dark tables, use the modifier classes `.thead-light` or `.
 <table class="table">
   <thead class="thead-dark">
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -119,10 +119,10 @@ Similar to tables and dark tables, use the modifier classes `.thead-light` or `.
 <table class="table">
   <thead class="thead-light">
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -156,10 +156,10 @@ Use `.table-striped` to add zebra-striping to any table row within the `<tbody>`
 <table class="table table-striped">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -189,10 +189,10 @@ Use `.table-striped` to add zebra-striping to any table row within the `<tbody>`
 <table class="table table-striped table-dark">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -226,10 +226,10 @@ Add `.table-bordered` for borders on all sides of the table and cells.
 <table class="table table-bordered">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -264,10 +264,10 @@ Add `.table-bordered` for borders on all sides of the table and cells.
 <table class="table table-bordered table-dark">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -306,10 +306,10 @@ Add `.table-hover` to enable a hover state on table rows within a `<tbody>`.
 <table class="table table-hover">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -338,10 +338,10 @@ Add `.table-hover` to enable a hover state on table rows within a `<tbody>`.
 <table class="table table-hover table-dark">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -374,10 +374,10 @@ Add `.table-sm` to make tables more compact by cutting cell padding in half.
 <table class="table table-sm">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -406,10 +406,10 @@ Add `.table-sm` to make tables more compact by cutting cell padding in half.
 <table class="table table-sm table-dark">
   <thead>
     <tr>
-      <th>#</th>
-      <th>First Name</th>
-      <th>Last Name</th>
-      <th>Username</th>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
     </tr>
   </thead>
   <tbody>
@@ -442,10 +442,10 @@ Use contextual classes to color table rows or individual cells.
   <table class="table">
     <thead>
       <tr>
-        <th>Type</th>
-        <th>Column heading</th>
-        <th>Column heading</th>
-        <th>Column heading</th>
+        <th scope="col">Type</th>
+        <th scope="col">Column heading</th>
+        <th scope="col">Column heading</th>
+        <th scope="col">Column heading</th>
       </tr>
     </thead>
     <tbody>
@@ -493,10 +493,10 @@ Regular table background variants are not available with the dark table, however
   <table class="table table-dark">
     <thead>
       <tr>
-        <th>#</th>
-        <th>Column heading</th>
-        <th>Column heading</th>
-        <th>Column heading</th>
+        <th scope="col">#</th>
+        <th scope="col">Column heading</th>
+        <th scope="col">Column heading</th>
+        <th scope="col">Column heading</th>
       </tr>
     </thead>
     <tbody>
@@ -595,16 +595,16 @@ Responsive tables make use of `overflow-y: hidden`, which clips off any content
   <table class="table table-responsive">
     <thead>
       <tr>
-        <th>#</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
+        <th scope="col">#</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
       </tr>
     </thead>
     <tbody>
@@ -650,13 +650,13 @@ Responsive tables make use of `overflow-y: hidden`, which clips off any content
   <table class="table table-bordered table-responsive-lg">
     <thead>
       <tr>
-        <th>#</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
-        <th>Table heading</th>
+        <th scope="col">#</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
+        <th scope="col">Table heading</th>
       </tr>
     </thead>
     <tbody>
@@ -696,3 +696,42 @@ Responsive tables make use of `overflow-y: hidden`, which clips off any content
   ...
 </table>
 {% endhighlight %}
+
+
+## Captions
+
+A `<caption>` functions like a heading for a table. It helps users with screen readers to find a table and understand what it’s about and decide if they want to read it.
+
+{% example html %}
+<table class="table">
+  <caption>List of users</caption>
+  <thead>
+    <tr>
+      <th scope="col">#</th>
+      <th scope="col">First Name</th>
+      <th scope="col">Last Name</th>
+      <th scope="col">Username</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th scope="row">1</th>
+      <td>Mark</td>
+      <td>Otto</td>
+      <td>@mdo</td>
+    </tr>
+    <tr>
+      <th scope="row">2</th>
+      <td>Jacob</td>
+      <td>Thornton</td>
+      <td>@fat</td>
+    </tr>
+    <tr>
+      <th scope="row">3</th>
+      <td>Larry</td>
+      <td>the Bird</td>
+      <td>@twitter</td>
+    </tr>
+  </tbody>
+</table>
+{% endexample %}