diff --git a/src/pages/components/tag/images/tag-style-color-dismissible.png b/src/pages/components/tag/images/tag-style-color-dismissible.png new file mode 100644 index 00000000000..882d0649e82 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-color-dismissible.png differ diff --git a/src/pages/components/tag/images/tag-style-color-operational.png b/src/pages/components/tag/images/tag-style-color-operational.png new file mode 100644 index 00000000000..c24b86d8cf0 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-color-operational.png differ diff --git a/src/pages/components/tag/images/tag-style-color-read-only.png b/src/pages/components/tag/images/tag-style-color-read-only.png new file mode 100644 index 00000000000..08242cad009 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-color-read-only.png differ diff --git a/src/pages/components/tag/images/tag-style-color-selectable.png b/src/pages/components/tag/images/tag-style-color-selectable.png new file mode 100644 index 00000000000..405c91fcdc4 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-color-selectable.png differ diff --git a/src/pages/components/tag/images/tag-style-interactive-color-dismissible.png b/src/pages/components/tag/images/tag-style-interactive-color-dismissible.png new file mode 100644 index 00000000000..c940d801d82 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-interactive-color-dismissible.png differ diff --git a/src/pages/components/tag/images/tag-style-interactive-color-operational.png b/src/pages/components/tag/images/tag-style-interactive-color-operational.png new file mode 100644 index 00000000000..86b3bfdf53d Binary files /dev/null and b/src/pages/components/tag/images/tag-style-interactive-color-operational.png differ diff --git a/src/pages/components/tag/images/tag-style-interactive-color-selectable.png b/src/pages/components/tag/images/tag-style-interactive-color-selectable.png new file mode 100644 index 00000000000..e33f02630d3 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-interactive-color-selectable.png differ diff --git a/src/pages/components/tag/images/tag-style-size.png b/src/pages/components/tag/images/tag-style-size.png index e9137612f81..9645727264a 100644 Binary files a/src/pages/components/tag/images/tag-style-size.png and b/src/pages/components/tag/images/tag-style-size.png differ diff --git a/src/pages/components/tag/images/tag-style-structure-dismissible.png b/src/pages/components/tag/images/tag-style-structure-dismissible.png new file mode 100644 index 00000000000..bf066260be9 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-structure-dismissible.png differ diff --git a/src/pages/components/tag/images/tag-style-structure-operational-examples.png b/src/pages/components/tag/images/tag-style-structure-operational-examples.png new file mode 100644 index 00000000000..a5859ee7074 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-structure-operational-examples.png differ diff --git a/src/pages/components/tag/images/tag-style-structure-operational-popover.png b/src/pages/components/tag/images/tag-style-structure-operational-popover.png new file mode 100644 index 00000000000..788374005d3 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-structure-operational-popover.png differ diff --git a/src/pages/components/tag/images/tag-style-structure-operational-tooltip-toggletip.png b/src/pages/components/tag/images/tag-style-structure-operational-tooltip-toggletip.png new file mode 100644 index 00000000000..dfe4cffa24c Binary files /dev/null and b/src/pages/components/tag/images/tag-style-structure-operational-tooltip-toggletip.png differ diff --git a/src/pages/components/tag/images/tag-style-structure-operational.png b/src/pages/components/tag/images/tag-style-structure-operational.png new file mode 100644 index 00000000000..addab72bf9a Binary files /dev/null and b/src/pages/components/tag/images/tag-style-structure-operational.png differ diff --git a/src/pages/components/tag/images/tag-style-structure-read-only.png b/src/pages/components/tag/images/tag-style-structure-read-only.png new file mode 100644 index 00000000000..7196c4e90f0 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-structure-read-only.png differ diff --git a/src/pages/components/tag/images/tag-style-structure-selectable.png b/src/pages/components/tag/images/tag-style-structure-selectable.png new file mode 100644 index 00000000000..44a5384dec3 Binary files /dev/null and b/src/pages/components/tag/images/tag-style-structure-selectable.png differ diff --git a/src/pages/components/tag/images/tag-usage-anatomy.png b/src/pages/components/tag/images/tag-usage-anatomy.png new file mode 100644 index 00000000000..e7ff31663ad Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-anatomy.png differ diff --git a/src/pages/components/tag/images/tag-usage-clickable-areas.png b/src/pages/components/tag/images/tag-usage-clickable-areas.png new file mode 100644 index 00000000000..6afd0e4b421 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-clickable-areas.png differ diff --git a/src/pages/components/tag/images/tag-usage-colors.png b/src/pages/components/tag/images/tag-usage-colors.png new file mode 100644 index 00000000000..92f9639b1c8 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-colors.png differ diff --git a/src/pages/components/tag/images/tag-usage-decorative-icons.png b/src/pages/components/tag/images/tag-usage-decorative-icons.png new file mode 100644 index 00000000000..5dc7d7646da Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-decorative-icons.png differ diff --git a/src/pages/components/tag/images/tag-usage-dismissable.png b/src/pages/components/tag/images/tag-usage-dismissable.png new file mode 100644 index 00000000000..936720380dd Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-dismissable.png differ diff --git a/src/pages/components/tag/images/tag-usage-operational.png b/src/pages/components/tag/images/tag-usage-operational.png new file mode 100644 index 00000000000..80c2252fbca Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-operational.png differ diff --git a/src/pages/components/tag/images/tag-usage-overflow-do.png b/src/pages/components/tag/images/tag-usage-overflow-do.png new file mode 100644 index 00000000000..32f4149b620 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-overflow-do.png differ diff --git a/src/pages/components/tag/images/tag-usage-overflow-dont.png b/src/pages/components/tag/images/tag-usage-overflow-dont.png new file mode 100644 index 00000000000..22c7cb4c9e1 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-overflow-dont.png differ diff --git a/src/pages/components/tag/images/tag-usage-overflow.png b/src/pages/components/tag/images/tag-usage-overflow.png new file mode 100644 index 00000000000..668edeee438 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-overflow.png differ diff --git a/src/pages/components/tag/images/tag-usage-overview.png b/src/pages/components/tag/images/tag-usage-overview.png new file mode 100644 index 00000000000..5ad8d130cc0 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-overview.png differ diff --git a/src/pages/components/tag/images/tag-usage-placement.png b/src/pages/components/tag/images/tag-usage-placement.png new file mode 100644 index 00000000000..fee1d5393ae Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-placement.png differ diff --git a/src/pages/components/tag/images/tag-usage-read-only-colors-do.png b/src/pages/components/tag/images/tag-usage-read-only-colors-do.png new file mode 100644 index 00000000000..d092b5e7aed Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-read-only-colors-do.png differ diff --git a/src/pages/components/tag/images/tag-usage-read-only-colors-dont.png b/src/pages/components/tag/images/tag-usage-read-only-colors-dont.png new file mode 100644 index 00000000000..1263e92d027 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-read-only-colors-dont.png differ diff --git a/src/pages/components/tag/images/tag-usage-read-only.png b/src/pages/components/tag/images/tag-usage-read-only.png new file mode 100644 index 00000000000..af07a31265c Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-read-only.png differ diff --git a/src/pages/components/tag/images/tag-usage-selectable-wrap-do.png b/src/pages/components/tag/images/tag-usage-selectable-wrap-do.png new file mode 100644 index 00000000000..c956f3d3ff5 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-selectable-wrap-do.png differ diff --git a/src/pages/components/tag/images/tag-usage-selectable-wrap-dont.png b/src/pages/components/tag/images/tag-usage-selectable-wrap-dont.png new file mode 100644 index 00000000000..fc23452ce1d Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-selectable-wrap-dont.png differ diff --git a/src/pages/components/tag/images/tag-usage-selectable.png b/src/pages/components/tag/images/tag-usage-selectable.png new file mode 100644 index 00000000000..c739bd99484 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-selectable.png differ diff --git a/src/pages/components/tag/images/tag-usage-sizing.png b/src/pages/components/tag/images/tag-usage-sizing.png new file mode 100644 index 00000000000..3cb82112585 Binary files /dev/null and b/src/pages/components/tag/images/tag-usage-sizing.png differ diff --git a/src/pages/components/tag/style.mdx b/src/pages/components/tag/style.mdx index 0a87478655e..7406945fed9 100755 --- a/src/pages/components/tag/style.mdx +++ b/src/pages/components/tag/style.mdx @@ -1,103 +1,312 @@ --- 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'] --- + + +The following page documents visual specifications such as color, typography, +structure, and size. + + + + + +Color +Typography +Structure +Size +Feedback + + + ## 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 variants of tag use +[component tokens](https://carbondesignsystem.com/elements/color/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](https://carbondesignsystem.com/elements/color/tokens) | +| | | Icon | icon-color | See all component [color tokens](https://carbondesignsystem.com/elements/color/tokens) | +| | | Background | background-color | See all component [color tokens](https://carbondesignsystem.com/elements/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](https://carbondesignsystem.com/elements/color/tokens) | +| | | Icon | icon-color | See all component [color tokens](https://carbondesignsystem.com/elements/color/tokens) | +| | | Background | background-color | See all component [color tokens](https://carbondesignsystem.com/elements/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](https://carbondesignsystem.com/elements/color/tokens) | +| | | Icon | icon-color | See all component [color tokens](https://carbondesignsystem.com/elements/color/tokens) | +| | | Border | border | See all component [color tokens](https://carbondesignsystem.com/elements/color/tokens) | +| | | Background | background-color | See all component [color tokens](https://carbondesignsystem.com/elements/color/tokens) | +| Selectable tag | | Text | text-color | `$text-primary` | +| | | Icon | icon-color | `$icon-primary` | +| | | Border | border | `$border-inverse` | +| | | Background | background-color | `$layer` \* | + + + * Denotes a contextual color token that will change values based on the layer + it is placed on. + + + + + +![Read-only tag colors.](images/tag-style-color-read-only.png) + + + + +Read-only tag colors + + + + +![Dismissible tag colors.](images/tag-style-color-dismissible.png) + + + + +Dismissible tag colors + + + + +![Operational tag colors.](images/tag-style-color-operational.png) + + + + +Operational tag colors + + + + +![Selectable tag color.](images/tag-style-color-selectable.png) + + + + +Selectable tag color + +### 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](https://carbondesignsystem.com/elements/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](https://carbondesignsystem.com/elements/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` \* | + + + * Denotes a contextual color token that will change values based on the layer + it is placed on. + + + + + +![Dismissible tag interactive colors.](images/tag-style-interactive-color-dismissible.png) + + + + +Dismissible tag interactive colors + + + + +![Operational tag interactive colors.](images/tag-style-interactive-color-operational.png) + + + + +Operational tag interactive colors + + + + +![Selectable tag interactive colors.](images/tag-style-interactive-color-selectable.png) + + + + +Selectable tag interactive colors ## 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 (md) | height | 24 / 1.5 | – | -| | radius | 12px | – | -| | margin | 8 / 0.5 | `$spacing-03` | -| | padding-left, padding-right | 8 / 0.5 | `$spacing-03` | -| Tag (sm) | height | 18 / 1.125 | – | -| | radius | 9px | – | -| | margin | 8 / 0.5 | `$spacing-03` | -| | padding-left, padding-right | 8 / 0.5 | `$spacing-03` | +| Element | Property | px / rem | Spacing token | +| ------------------ | --------------------------- | ---------- | ------------- | +| Tag container (lg) | height | 32 / 2 | – | +| | radius | 16px | – | +| | margin | 8 / 0.5 | `$spacing-03` | +| | padding-left, padding-right | 12 / 0.75 | `$spacing-04` | +| Tag icon (lg) | padding-left (decorative) | 8 / 0.5 | `$spacing-03` | +| | padding-right (decorative) | 4 / 0.25 | `$spacing-02` | +| | padding-left (dismissible) | 12 / 0.75 | `$spacing-04` | +| | padding-right (dismissible) | 8 / 0.5 | `$spacing-03` | +| | icon | 16px | – | +| Tag container (md) | height | 24 / 1.5 | – | +| | radius | 16px | – | +| | margin | 8 / 0.5 | `$spacing-03` | +| | padding-left, padding-right | 8 / 0.5 | `$spacing-03` | +| Tag icon (md) | padding-left (decorative) | 4 / 0.25 | `$spacing-02` | +| | padding-right (decorative) | 4 / 0.25 | `$spacing-02` | +| | padding-left (dismissible) | 8 / 0.5 | `$spacing-03` | +| | padding-right (dismissible) | 4 / 0.25 | `$spacing-02` | +| | icon | 16px | – | +| Tag container (sm) | height | 18 / 1.125 | – | +| | radius | 16px | – | +| | margin | 8 / 0.5 | `$spacing-03` | +| | padding-left, padding-right | 8 / 0.5 | `$spacing-03` | +| Tag icon (sm) | padding-left (dismissible) | 8 / 0.5 | `$spacing-03` | +| | padding-right (dismissible) | 1 / 0.0625 | – | +| | icon | 16px | – |
-![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)
-Structure and spacing measurements for a tag | px / rem + + Structure and spacing measurements of read-only tag | px / rem. + + +
+ +![Structure and spacing measurements of dismissible tag | px / rem.](images/tag-style-structure-dismissible.png) + +
+ + + Structure and spacing measurements of dismissible tag | px / rem. + + +
+ +![Structure and spacing measurements of operational tag | px / rem.](images/tag-style-structure-operational.png) + +
+ + + Structure and spacing measurements of operational tag | px / rem. + + +
+ +![Structure and spacing measurements of selectable tag | px / rem.](images/tag-style-structure-selectable.png) + +
+ + + Structure and spacing measurements of selectable tag | px / rem. + + +
+ +![Structure and spacing measurements of operational tag tooltip and toggletip | px / rem.](images/tag-style-structure-operational-tooltip-toggletip.png) + +
+ + + Structure and spacing measurements of operational tag tooltip and toggletip | + px / rem. + + +
+ +![Structure and spacing measurements of operational tag popover | px / rem.](images/tag-style-structure-operational-popover.png) + +
+ + + Structure and spacing measurements of operational tag popover | px / rem. + + +## 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 |
-![Sizes for tag](images/tag-style-size.png) +![Small, medium, and large sizes of tag](images/tag-style-size.png)
-Tag sizes | px / rem +Small, medium, and large sizes of tag diff --git a/src/pages/components/tag/usage.mdx b/src/pages/components/tag/usage.mdx index 54af3cd71a9..2a42d79b6a9 100755 --- a/src/pages/components/tag/usage.mdx +++ b/src/pages/components/tag/usage.mdx @@ -1,8 +1,8 @@ --- title: Tag description: - Use tags to label, categorize, or organize items using keywords that describe - them. + Tags are used to label, categorize, filter, select, or disclose additional + tags to the user. tabs: ['Usage', 'Style', 'Code', 'Accessibility'] --- @@ -15,10 +15,28 @@ them. + + +Experimental interactive tags, selectable, operational, and dismissible, are now +available. Dismissible tags are now their own variant and separate from +read-only tags. Though we are not deprecating the current tags, we encourage all +design teams to use the new experimental tags for dismissible, selectable, and +operational use cases in their products moving forward. + + + Live demo Overview +Formatting +Content +Read-only tag +Dismissible tag +Selectable tag +Operational tag +Modifiers +References Feedback @@ -40,35 +58,395 @@ them. ## Overview -Multiple or single tags can be used to categorize items. +Tags are components that are often used to label different items, create +categorization, filter data, select or deselect options, and include +functionality to disclose several related tags in another view. To support these +different use cases, tags come in four variants—read-only, dismissible, +selectable, and operational. + + + + +![Tags being used in context of a product UI.](images/tag-usage-overview.png) -Use short labels for easy scanning. Use two words only if necessary to describe -the status and differentiate it from other tags. + + + +Tags being used in context of a product UI. ### When to use Use tags when content is mapped to multiple categories, and the user needs a way to differentiate between them. +### When to use + +- Use for categorizing, labeling, or read-only situations +- Use as a method of filtering data on a page, within a component, or in + conjunction with search capabilities +- Use in a chat flow to make decisions and advance the chat +- Use for creating user-generated custom labeling and use when needing to remove + created labels +- Use to view an overflow of multiple tags, like in a toggletip, popover, modal, + or detail view + +### When not to use + +- Do not use tags as links that direct you to an entirely different page or + launch you from a current experience to a separate tab +- Avoid using tags with multiple functions to prevent confusion and reduce + accidental clicks + +### Variants + +| Variant | Purpose | +| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Read-only tag](#read-only-tag) | Tags that have no interactive functionality and are commonly used for categorizing and labeling. | +| [Dismissible tag](#dismissible-tag) | Tags that can be dismissed, closed, or removed. These tags are typically used for filtering and creating user-generated content. | +| [Selectable tag](#selectable-tag) | Tags that can be selected or deselected and are frequently used as selections that filter data in the context of a page. They also can be used in chat flows to make decisions to advance the chat. | +| [Operational tag](#operational-tag) | When interacted with, these tags can disclose additional or overflow tags, like in a toggletip, popover, modal, or breadcrumb detail view. | + +## Formatting + +### Anatomy + +Read-only, dismissible, selectable, and operational tags are all comprised of a +container, a text title, and the option to add a decorative icon. Dismissible +tags include an additional close icon to filter or dismiss a tag. Selectable and +Operational tags include a container border to indicate at a glance that these +variants have increased interactivity and function differently. + + + + +![Anatomy of read-only, dismissible, selectable, and operational tags.](images/tag-usage-anatomy.png) + + + + + + Anatomy of read-only, dismissible, selectable, and operational tags. + + + + + +#### 1. Read-only tag + +A. Decorative icon (optional)
B. Title
C. Container
+ +#### 3. Selectable tag + +A. Decorative icon (optional)
B. Title
C. Container
E. +Border
+ + + + +#### 2. Dismissible tag + +A. Decorative icon (optional)
B. Title
C. Container
D. +Close icon
+ +#### 4. Operational tag + +A. Decorative icon (optional)
B. Title
C. Container
E. +Border
+ + + + +### Sizing + +There are three different tag sizes — small, medium, and large. Use small tags +in condensed or inline spaces. The medium tag size is the default size and is +most commonly used. Use large tags when they are used as a primary task of the +page or focal point, when you have more screen real estate at your disposal, or +if the tag lives near other components that are also 32px in height. + + + + +![Tags shown in small, medium, and large sizes.](images/tag-usage-sizing.png) + + + + +Tags shown in small, medium, and large sizes. + +### Placement + +Vertically align the tag’s container to the other components or text near it. Do +not hang tag containers into grid gutters to vertically align the tag’s titles +with other text on the page. When tags are placed in groups, it is recommended +to have 8px of space between them on the top, bottom, left, and right. + + + + +![Vertical alignment of a group of tags with other components and text.](images/tag-usage-placement.png) + + + + + + Vertical alignment of a group of tags with other components and text. + + +## Content + +### Main elements + +#### Title + +- Tag titles should be concise and informative. +- Tag titles should 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, when + there are user-defined names of categories, system-generated strings of text, + etc. + +### Further guidance + +For further content guidance, see Carbon’s +[content guidelines](https://carbondesignsystem.com/guidelines/content/overview/). + +### States + +The four tag variants have different states: + +- **Read-only tags:** enabled, disabled, and skeleton +- **Dismissible tags** and **operational tags:** enabled, hover, focus, on + click, disabled, and skeleton +- **Selectable tags:** enabled, hover, focus, selected, disabled, and skeleton + +For more information on tag states, see the +[style tab](https://carbondesignsystem.com/components/tag/style). + +| State | When to use | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _Enabled_ | When a tag is live but a user is not directly interacting with it. This is commonly referred to as the default or normal state of the component. | +| _Hover_ | When a user is hovering over the tag with the mouse cursor to interact with it (except read-only tags). | +| _Focus_ | When a user presses tab or clicks on the tag, it becomes focused, indicating the user has successfully navigated to the component (except read-only tags). | +| _On click_ | When a user presses enters, space, or clicks on the tag to either dismiss it or disclose a list of additional tags. | +| _Selected_ | When a user presses enter, space, or clicks on the tag to select it or deselect it. | +| _Disabled_ | When a user is not allowed to interact with the tag due to either permissions, dependencies, or pre-requisites. The disabled state completely removes the interactive function from a component. The styling is not subject to WCAG contrast compliance. | + +### Interactions + +#### Mouse + +Read-only tags: Do not get mouse functionality besides a mouse cursor on hover +and do not have interactive functionality. + +Dismissible tags: Receive a mouse cursor when hovering over the title area of +the tag. When hovering over the close icon, the icon gets a background color +change and a mouse pointer. Once the close icon area is clicked, the tag will be +dismissed, closed, or removed. + +Selectable tags: Receive a full background color change and mouse pointer on +hover. Clicking anywhere on the tag will put it in a selected state. Once in the +selected state, clicking anywhere on the tag again will deselect it. + +Operational tags: Receive a background color change and mouse pointer on hover. +Clicking anywhere on the tag will disclose a way of viewing more related tags in +either a toggletip, popover, modal, or breadcrumb view. + +#### Keyboard + +Read-only tags: Can not be operated by a keyboard and have no interactive +functionality. + +Dismissible tags: Receive focus on the close icon area by pressing the `Tab` +key. Pressing the `Enter` or `Space` keys will dismiss, close, or remove the +tag. + +Selectable tags: The container receives focus by pressing the `Tab` key. +Pressing the `Enter` or `Space` keys will select or deselect the tag. If +navigating in a group of tags, use the `Tab` key to move focus to different tags +in the group. + +Operational tags: The container receives focus by pressing the `Tab` key. +Pressing the `Enter` or `Space` keys will disclose additional related tags, in a +toggletip, popover, modal, or breadcrumb view. + +### Clickable areas + +Read-only tags are not clickable and can not be interacted with. Dismissible +tags have a clickable area around the close icon to dismiss or close the tag. +Selectable and operational tags containers are clickable to either select the +tag or view more tags. + -![Example of tags in a data table.](images/tag-usage-2.png) +![Read-only, dismissible, selectable, and operational tags with their clickable areas.](images/tag-usage-clickable-areas.png) + + + + + + Read-only, dismissible, selectable, and operational tags with their clickable + areas. + + +## Read-only tag + +Read-only tags are used to categorize, are used for labeling, and do not have +interactive functionality. Read-only tags come in several color choices and can +use optional decorative icons to delineate between multiple categories. + + + + +![Read-only tags in the context of a product UI.](images/tag-usage-read-only.png) -Tags can also be used as a method of filtering data, to show only items within -that particular category. +Read-only tags in the context of a product UI. + +If your design intends to use tags as labels or for categorization, use +modifiers like colors or icons to help indicate this differentiation. + + + + +![Do use colors to help distinguish between different tag labels or categories for easier scanning.](images/tag-usage-read-only-colors-do.png) + + + + +![Do not use the same color for every tag if they are supposed to be used as labels or categories.](images/tag-usage-read-only-colors-dont.png) + + + + +## Dismissible tag + +Dismissible tags allow users to dismiss, close, or remove a tag. Dismissible +tags are commonly used with the search component to search or filter keywords on +a page or within sections of a page. + +Dismissible tags can also be used as user-generated labels that are applied to +instances and can be removed later if needed. Do not use a dismissible tag if +the intention for it is to remain persistent at all times since they can be +closed or dismissed by the user. + + + + +![Dismissible tags in the context of a product UI.](images/tag-usage-dismissable.png) + + + + +Dismissible tags in the context of a product UI. + +## Selectable tag + +Selectable tags give users the ability to select or deselect them. They can be +used in a form containing only tags as the selection method, in a chat to make +decisions and forward the chat, and can be used as selections to filter content +on a page or within a component. + +In some cases, selectable tags can be used as an alternative to traditional form +components when the entire form consistently uses tags as its form selection +style. Selectable tags should always remain in high contrast to ensure a +noticeable difference between selected and unselected tags. + + + + +![Selectable tags in the context of a product UI.](images/tag-usage-selectable.png) + + + + +Selectable tags in the context of a product UI. + +When selectable tags are in groups, we recommend using horizontal alignment for +easier scanning when there are only a few tags. Keep groups of tags horizontally +on one line when there are six tags or less. Horizontal alignment is not +recommended when there are many tags to select from in a group. Tags should wrap +to form another line if there are too many to arrange horizontally on one line. +If the number of tags exceeds five lines of wrapping, consider using a different +component for your use case, like a +[multi-select dropdown](https://carbondesignsystem.com/components/dropdown/usage/#multiselect). + + + + +![Do wrap tags in a group to a few multiple lines when possible.](images/tag-usage-selectable-wrap-do.png) + + + + +![Do not wrap tags in a group of more than five lines when possible.](images/tag-usage-selectable-wrap-dont.png) + + + + +## Operational tag + +Operational tags enable the user to see a more comprehensive view of all tags +disclosed in a toggletip, popover, or breadcrumb detail view. Do not use tags as +links that direct you to an entirely different page or launch you from a current +experience to a separate tab. + + + + +![Operational tags in the context of a product UI.](images/tag-usage-operational.png) + + + + +Operational tags in the context of a product UI. + +## Modifiers + +### Decorative icons + +Decorative icons lead before the tag title. Decorative icons are optional and +are often used to support the tag title visually. We recommend not using +decorative icons in the small tag size where there is compact spacing, which +could create possible visual tension between some icon shapes and tags with +borders. + + + + +![Tags with decorative icons.](images/tag-usage-decorative-icons.png) + + + + +Tags with decorative icons. + +### Tag colors + +Read-only, dismissible, and operational tags come in a variety of different +colors, with values from the IBM Design Language +[color palette](https://www.ibm.com/design/language/color) using +[component tokens](https://carbondesignsystem.com/elements/color/tokens). It is +recommended to use multiple colors to denote different categories or labels. +Selectable tags are unavailable in these colors; instead, they use +[core tokens](https://carbondesignsystem.com/elements/color/overview#core-tokens). -![Example of tags in search.](images/tag-usage-1.png) +![Read-only using component color tokens and selectable tags using core color tokens.](images/tag-usage-colors.png) + + Read-only using component color tokens and selectable tags using core color + tokens. + + ## Feedback Help us improve this component by providing feedback, asking questions, and