docs: update tag docs with interactive tags

src/pages/components/tag/style.mdx

@@ -1,75 +1,214 @@
 ---
 title: Tag
 description:
-  Tags are used for items that need to be labeled, categorized, or organized
-  using keywords that describe them.
+  The following page documents visual specifications such as color, typography,
+  structure, and size.
 tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 ---
 
+<PageDescription>
+
+The following page documents visual specifications such as color, typography,
+structure, and size.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Color</AnchorLink>
+<AnchorLink>Typography</AnchorLink>
+<AnchorLink>Structure</AnchorLink>
+<AnchorLink>Size</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
+
+</AnchorLinks>
+
 ## Color
 
-Tag uses component level tokens and values from the IBM Design Language
-[color palette](https://www.ibm.com/design/language/elements/color). In the
-light themes tags use color step 20 for the background and step 70 for the text.
-In the dark themes, tags use color step 70 for the background and step 20 for
-the text. For the list of token values, see
-[Carbon repo](https://github.com/carbon-design-system/carbon/blob/main/packages/themes/src/component-tokens/tag/tokens.js).
-
-| Tag color     | Color token                 |
-| ------------- | --------------------------- |
-| Default       | `$tag-background-gray`      |
-|               | `$tag-color-gray`           |
-|               | `$tag-hover-gray`           |
-| Red           | `$tag-background-red`       |
-|               | `$tag-color-red`            |
-|               | `$tag-hover-red`            |
-| Magenta       | `$tag-background-magenta`   |
-|               | `$tag-color-magenta`        |
-|               | `$tag-hover-magenta`        |
-| Purple        | `$tag-background-purple`    |
-|               | `$tag-color-purple`         |
-|               | `$tag-hover-purple`         |
-| Blue          | `$tag-background-blue`      |
-|               | `$tag-color-blue`           |
-|               | `$tag-hover-blue`           |
-| Cyan          | `$tag-background-cyan`      |
-|               | `$tag-color-cyan`           |
-|               | `$tag-hover-cyan`           |
-| Teal          | `$tag-background-teal`      |
-|               | `$tag-color-teal`           |
-|               | `$tag-hover-teal`           |
-| Green         | `$tag-background-green`     |
-|               | `$tag-color-green`          |
-|               | `$tag-hover-green`          |
-| Gray          | `$tag-background-gray`      |
-|               | `$tag-color-gray`           |
-|               | `$tag-hover-gray`           |
-| Cool gray     | `$tag-background-cool-gray` |
-|               | `$tag-color-cool-gray`      |
-|               | `$tag-hover-cool-gray`      |
-| Warm gray     | `$tag-background-warm-gray` |
-|               | `$tag-color-warm-gray`      |
-|               | `$tag-hover-warm-gray`      |
-| High contrast | `$background-inverse`       |
-|               | `$text-inverse`             |
+Read-only, dismissible, and operational tag variants of tag use component tokens
+with values from the IBM Design Language
+[color palette](https://www.ibm.com/design/language/color). Light themes use
+step 70 for text and icons, step 40 for borders, and step 20 for backgrounds.
+Dark themes use step 20 for text and icons, step 50 for borders, and step 70 for
+backgrounds. The only exception where
+[core tokens](https://carbondesignsystem.com/elements/color/overview/#core-tokens)
+are used are in high contrast and outline styles.
+
+The selectable tag variant only uses core tokens and does not use component
+tokens.
+
+| Variant         | Color         | Element    | Property         | Color token                    |
+| --------------- | ------------- | ---------- | ---------------- | ------------------------------ |
+| Read-only tag   | All colors    | Text       | text-color       | See all component color tokens |
+|                 |               | Icon       | icon-color       | See all component color tokens |
+|                 |               | Background | background-color | See all component color tokens |
+|                 | High contrast | Text       | text-color       | `$text-inverse`                |
+|                 |               | Icon       | icon-color       | `$icon-color`                  |
+|                 |               | Border     | border           | `$border-inverse`              |
+|                 |               | Background | background-color | `$background-inverse`          |
+|                 | Outline       | Text       | text-color       | `$text-primary`                |
+|                 |               | Icon       | icon-color       | `$icon-primary`                |
+|                 |               | Border     | border           | `$border-inverse`              |
+|                 |               | Background | background-color | `$background`                  |
+| Dismissible tag | All colors    | Text       | text-color       | See all component color tokens |
+|                 |               | Icon       | icon-color       | See all component color tokens |
+|                 |               | Background | background-color | See all component color tokens |
+|                 | High contrast | Text       | text-color       | `$text-inverse`                |
+|                 |               | Icon       | icon-color       | `$icon-color`                  |
+|                 |               | Border     | border           | `$border-inverse`              |
+|                 |               | Background | background-color | `$background-inverse`          |
+|                 | Outline       | Text       | text-color       | `$text-primary`                |
+|                 |               | Icon       | icon-color       | `$icon-primary`                |
+|                 |               | Border     | border           | `$border-inverse`              |
+|                 |               | Background | background-color | `$background`                  |
+| Operational tag | All colors    | Text       | text-color       | See all component color tokens |
+|                 |               | Icon       | icon-color       | See all component color tokens |
+|                 |               | Border     | border           | See all component color tokens |
+|                 |               | Background | background-color | See all component color tokens |
+| Selectable tag  |               | Text       | text-color       | `$text-primary`                |
+|                 |               | Icon       | icon-color       | `$icon-primary`                |
+|                 |               | Border     | border           | `$border-inverse`              |
+|                 |               | Background | background-color | `$layer` \*                    |
+
+<Caption>
+  * Denotes a contextual color token that will change values based on the layer
+  it is placed on.
+</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Read-only tag colors.](images/tag-style-color-read-only.png)
+
+</Column>
+</Row>
+
+<Caption>Read-only tag colors</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Dismissible tag colors.](images/tag-style-color-dismissible.png)
+
+</Column>
+</Row>
+
+<Caption>Dismissible tag colors</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Operational tag colors.](images/tag-style-color-operational.png)
+
+</Column>
+</Row>
+
+<Caption>Operational tag colors</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Selectable tag color.](images/tag-style-color-selectable.png)
+
+</Column>
+</Row>
+
+<Caption>Selectable tag color</Caption>
+
+### Interactive state color
+
+Read-only tag variants do not have interactive state colors because they do not
+have interactive functionality.
+
+Dismissible and operational tag variants use component tokens for hover states.
+They use core tokens for focus and disabled states.
+
+The selectable tag variant only uses core tokens and does not use component
+tokens.
+
+| Variant         | Color         | State    | Element    | Property         | Color token                    |
+| --------------- | ------------- | -------- | ---------- | ---------------- | ------------------------------ |
+| Dismissible tag | All colors    | Hover    | Background | background-color | See all component color tokens |
+|                 |               | Focus    | Border     | border           | `$focus`                       |
+|                 |               | Disabled | Text       | text-color       | `$text-disabled`               |
+|                 |               |          | Background | background-color | `$layer` \*                    |
+|                 | High contrast | Hover    | Background | background-color | `$background-hover`            |
+|                 |               | Focus    | Border     | border           | `$focus`                       |
+|                 |               | Disabled | Text       | text-color       | `$text-disabled`               |
+|                 |               |          | Background | background-color | `$layer` \*                    |
+|                 | Outline       | Hover    | Background | background-color | `$background-hover`            |
+|                 |               | Focus    | Border     | border           | `$focus`                       |
+|                 |               | Disabled | Text       | text-color       | `$text-disabled`               |
+|                 |               |          | Border     | border           | `$border-disabled`             |
+|                 |               |          | Background | background-color | `$background-disabled`         |
+| Operational tag | All colors    | Hover    | Background | background-color | See all component color tokens |
+|                 |               | Focus    | Border     | border           | `$focus`                       |
+|                 |               | Disabled | Text       | text-color       | `$text-disabled`               |
+|                 |               |          | Border     | border           | `$border-disabled`             |
+|                 |               |          | Background | background-color | `$layer` \*                    |
+| Selectable tag  |               | Hover    | Background | background-color | `$layer-hover` \*              |
+|                 |               | Focus    | Border     | border           | `$focus`                       |
+|                 |               | Disabled | Text       | text-color       | `$text-disabled`               |
+|                 |               |          | Border     | border           | `$border-disabled`             |
+|                 |               |          | Background | background-color | `$layer` \*                    |
+
+<Caption>
+  * Denotes a contextual color token that will change values based on the layer
+  it is placed on.
+</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Dismissible tag interactive colors.](images/tag-style-interactive-color-dismissible.png)
+
+</Column>
+</Row>
+
+<Caption>Dismissible tag interactive colors</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Operational tag interactive colors.](images/tag-style-interactive-color-operational.png)
+
+</Column>
+</Row>
+
+<Caption>Operational tag interactive colors</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Selectable tag interactive colors.](images/tag-style-interactive-color-selectable.png)
+
+</Column>
+</Row>
+
+<Caption>Selectable tag interactive colors</Caption>
 
 ## Typography
 
-Tag labels should be set in sentence case, and should only have one word.
-However, if more than one is necessary, then connect the words using a hyphen
-with no spaces.
+Tag titles should be concise and describe the tag in a few words or be under 20
+characters when possible. Only include long title content in tags when
+necessary, for instance, for user-defined names or system-generated strings of
+text.
 
-| Element | Font-size (px/rem) | Font-weight   | Type token  |
+| Element | Font size (px/rem) | Font weight   | Type token  |
 | ------- | ------------------ | ------------- | ----------- |
-| Label   | 12 / 0.75          | Regular / 400 | `$label-01` |
+| Title   | 12 / 0.75          | Regular / 400 | `$label-01` |
 
 ## Structure
 
-All tags have the same height. However, the width of tags varies based on the
-amount of content. All four corners of a tag are rounded with a 24px radius.
+There are three fixed heights of tags—large (32px), medium (24px), and small
+(18px). However, the width of tags can vary based on the length of the title.
 
 | Element  | Property                    | px / rem   | Spacing token |
 | -------- | --------------------------- | ---------- | ------------- |
+| Tag (lg) | height                      | 32 / 2     | –             |
+|          | radius                      | 24px       | –             |
+|          | margin                      | 8 / 0.5    | `$spacing-03` |
+|          | padding-left, padding-right | 12 / .75   | `$spacing-04` |
 | Tag (md) | height                      | 24 / 1.5   | –             |
 |          | radius                      | 12px       | –             |
 |          | margin                      | 8 / 0.5    | `$spacing-03` |
@@ -81,23 +220,58 @@ amount of content. All four corners of a tag are rounded with a 24px radius.
 
 <div className="image--fixed">
 
-![Structure and spacing measurements](images/tag-style-1.png)
+![Structure and spacing measurements of read-only tag | px / rem.](images/tag-style-structure-read-only.png)
 
 </div>
 
-<Caption>Structure and spacing measurements for a tag | px / rem</Caption>
+<Caption>
+  Structure and spacing measurements of read-only tag | px / rem.
+</Caption>
+
+<div className="image--fixed">
+
+![Structure and spacing measurements of dismissible tag | px / rem.](images/tag-style-structure-dismissible.png)
+
+</div>
+
+<Caption>
+  Structure and spacing measurements of dismissible tag | px / rem.
+</Caption>
+
+<div className="image--fixed">
+
+![Structure and spacing measurements of operational tag | px / rem.](images/tag-style-structure-operational.png)
+
+</div>
+
+<Caption>
+  Structure and spacing measurements of operational tag | px / rem.
+</Caption>
+
+<div className="image--fixed">
+
+![Structure and spacing measurements of selectable tag | px / rem.](images/tag-style-structure-selectable.png)
+
+</div>
+
+<Caption>
+  Structure and spacing measurements of selectable tag | px / rem.
+</Caption>
+
+## Size
 
-## Sizes
+There are three tag sizes — small, medium, and large.
 
-| Size   | Height px / rem |
-| ------ | --------------- |
-| Small  | 18px / 1.125    |
-| Medium | 24 / 1.5        |
+| Element   | Size        | Height (px/rem) |
+| --------- | ----------- | --------------- |
+| Container | Small (sm)  | 18 / 1.125      |
+|           | Medium (md) | 24 / 1.5        |
+|           | Large (lg)  | 32 / 2          |
 
 <div className="image--fixed">
 
 ![Sizes for tag](images/tag-style-size.png)
 
 </div>
 
-<Caption>Tag sizes | px / rem</Caption>
+<Caption>Large, medium, and small sizes of tag</Caption>