diff --git a/docs/content/tables.md b/docs/content/tables.md
index 00f794693e..fc6a6b19b2 100644
--- a/docs/content/tables.md
+++ b/docs/content/tables.md
@@ -4,14 +4,16 @@ title: Tables
group: content
---
-Due to the widespread use of tables across third-party widgets like calendars and date pickers, we've designed our tables to be **opt-in**. Just add the base class `.table` to any `
`.
+Due to the widespread use of tables across third-party widgets like calendars and date pickers, we've designed our tables to be **opt-in**. Just add the base class `.table` to any ``, then extend with custom styles or our various included modifier classes.
## Contents
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
-## Basic example
+## Examples
+
+Using the most basic table markup, here's how `.table`-based tables look in Bootstrap.
{% example html %}
@@ -46,7 +48,7 @@ Due to the widespread use of tables across third-party widgets like calendars an
{% endexample %}
-## Inverse table
+You can also invert the colors—with light text on dark backgrounds—with `.table-inverse`.
{% example html %}
@@ -83,7 +85,7 @@ Due to the widespread use of tables across third-party widgets like calendars an
## Table head options
-Use one of two modifier classes to make ``s appear light or dark gray.
+Similar to default and inverse tables, use one of two modifier classes to make ``s appear light or dark gray.
{% example html %}
@@ -420,9 +422,6 @@ Use contextual classes to color table rows or individual cells.
-{% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %}
-{{ callout-include | markdownify }}
-
{% highlight html %}
...
@@ -441,6 +440,98 @@ Use contextual classes to color table rows or individual cells.
{% endhighlight %}
+Regular table background variants are not available with the inverse table, however, you may use [text or background utilities](/components/utilities/#contextual-colors-and-backgrounds) to achieve similar styles.
+
+
+
+
+
+ # |
+ Column heading |
+ Column heading |
+ Column heading |
+
+
+
+
+ 1 |
+ Column content |
+ Column content |
+ Column content |
+
+
+ 2 |
+ Column content |
+ Column content |
+ Column content |
+
+
+ 3 |
+ Column content |
+ Column content |
+ Column content |
+
+
+ 4 |
+ Column content |
+ Column content |
+ Column content |
+
+
+ 5 |
+ Column content |
+ Column content |
+ Column content |
+
+
+ 6 |
+ Column content |
+ Column content |
+ Column content |
+
+
+ 7 |
+ Column content |
+ Column content |
+ Column content |
+
+
+ 8 |
+ Column content |
+ Column content |
+ Column content |
+
+
+ 9 |
+ Column content |
+ Column content |
+ Column content |
+
+
+
+
+
+{% highlight html %}
+
+...
+...
+...
+...
+...
+
+
+
+ ... |
+ ... |
+ ... |
+ ... |
+ ... |
+
+{% endhighlight %}
+
+{% capture callout-include %}{% include callout-warning-color-assistive-technologies.md %}{% endcapture %}
+{{ callout-include | markdownify }}
+
## Responsive tables
Create responsive tables by wrapping any `.table` in `.table-responsive` to make them scroll horizontally on small devices (under 768px). When viewing on anything larger than 768px wide, you will not see any difference in these tables.