docs(table): document table active variant in selectable rows section (#4097)

tmorehouse · web-flow · commit e35ad512f930 · 2019-09-18T11:16:15.000-03:00
diff --git a/docs/markdown/reference/color-variants/README.md b/docs/markdown/reference/color-variants/README.md
@@ -16,18 +16,18 @@
 - `dark` - <span class="text-dark">Dark</span>
 
 The base variants will translate to various Bootstrap v4 contextual class names based on the
-component (and variant purpose) where they are used.
+component (and variant purpose) where they are used. See the sections below for details.
 
 ## Background and border variants
 
 All the **base variants** plus:
 
 - `transparent`
 
-These translate to class names `bg-<variant>` for backgrounds and `border-<variant>` for borders.
+These translate to class names `bg-{variant}` for backgrounds and `border-{variant}` for borders.
 
-These variants are used by components (such as `<b-card>`, `<b-jumbotron>` and `<b-modal>`) that
-provide `bg-variant`, `*-bg-variant`, `border-variant` and `*-border-variant` props
+These variants are used by components (such as `<b-card>`, `<b-jumbotron>`, `<b-modal>`, etc.) that
+provide `bg-variant`, `*-bg-variant`, `border-variant` and `*-border-variant` props.
 
 ## Text variants
 
@@ -37,10 +37,10 @@ All the **base variants** plus:
 - `white`
 - `black`
 
-These translate to class names `text-<variant>`
+These translate to class names `text-{variant}`
 
-These variants are used by components (such as `<b-card>`, `<b-jumbotron>` and `<b-modal>`) that
-provide `text-variant` and `*-text-variant` props
+These variants are used by components (such as `<b-card>`, `<b-jumbotron>`, `<b-modal>`, etc.) that
+provide `text-variant` and `*-text-variant` props.
 
 ## Component specific variants
 
@@ -51,22 +51,22 @@ Some Bootstrap v4 components require additional CSS styling, or additional pseud
 
 All the **base variants**
 
-These translate to class names `alert-<variant>`.
+These translate to class names `alert-{variant}`.
 
 ### Badge variants
 
 All the **base variants**
 
-These translate to class names `badge-<variant>`.
+These translate to class names `badge-{variant}`.
 
 ### Button variants
 
 All the **base variants** plus:
 
-- `outline-<base variant>`
-- `link` which renders the button with the look of a link but retains button padding and margins.
+- `outline-{base variant}` which generates an outline button version of the base variant
+- `link` which renders the button with the look of a link but retains button padding and margins
 
-These translate to class names `btn-<variant>` and `btn-outline-<variant>`.
+These translate to class names `btn-{variant}` and `btn-outline-{variant}`.
 
 Note the `link` variant does not have an outline version.
 
@@ -76,27 +76,30 @@ All the **base variants** plus:
 
 - `active`
 
-These variants translate to class names `table-<variant>`.
+These variants translate to class names `table-{variant}`.
 
-When the table has the `dark` prop set, the variants translate to the `bg-<variant>` classes.
+When the table has the `dark` prop set, the variants translate to the `bg-{variant}` classes.
+
+Note that the `active` variant is only applicable to `<tr>` elements within the `<tbody>`, and can
+not be applied to individual table cells or used as the `table-variant`.
 
 ### Popover variants
 
 All the **base variants**
 
-These translate to BootstrapVue custom class names `b-popover-<variant>`.
+These translate to BootstrapVue custom class names `b-popover-{variant}`.
 
 ### Tooltip variants
 
 All the **base variants**
 
-These translate to BootstrapVue custom class names `b-tooltip-<variant>`.
+These translate to BootstrapVue custom class names `b-tooltip-{variant}`.
 
 ### Toast variants
 
 All the **base variants**
 
-These translate to BootstrapVue custom class names `b-toast-<variant>`.
+These translate to BootstrapVue custom class names `b-toast-{variant}`.
 
 ## Using variant classes
 
diff --git a/src/components/table/README.md b/src/components/table/README.md
@@ -1525,11 +1525,18 @@ element. Rows that are selected rows will have a class of `b-row-selected` appli
 element.
 
 Use the prop `selected-variant` to apply a Bootstrap theme color to the selected row(s). Note, due
-to the order that the table variants are defined in Bootstrap's CSS, any row-variant may take
+to the order that the table variants are defined in Bootstrap's CSS, any row-variant _might_ take
 precedence over the `selected-variant`. You can set `selected-variant` to an empty string if you
 will be using other means to convey that a row is selected (such as a scoped field slot in the below
 example).
 
+The `selected-variant` can be any of the
+[standard (or custom) bootstrap base color variants](/docs/reference/color-variants), or the special
+[table `active` variant](/docs/reference/color-variants#table-variants).
+
+For accessibility reasons (specifically for color blind users), it is highly recommended to always
+provide some other visual means of conveying that a row is selected, as shown in the example below.
+
 ```html
 <template>
   <div>
@@ -1541,7 +1548,7 @@ example).
       ref="selectableTable"
       selectable
       :select-mode="selectMode"
-      selected-variant="success"
+      selected-variant="active"
       :items="items"
       :fields="fields"
       @row-selected="onRowSelected"
