docs: Adding dismissible docs (#3581)

* docs: Adding dismissible docs

* docs: add dismissible images

* docs: update image names

* docs: dismissible color and structure sections

* docs: updated style images

* docs: updated caption formatting

* docs: removed a br

* chore(mdx): fix formatting

* Update src/pages/components/tabs/style.mdx

Co-authored-by: Aubrey O'Neal <47198241+aubrey-oneal@users.noreply.github.com>

* Update src/pages/components/tabs/usage.mdx

Co-authored-by: Aubrey O'Neal <47198241+aubrey-oneal@users.noreply.github.com>

* Update src/pages/components/tabs/usage.mdx

Co-authored-by: Anna Gonzales <agonz@us.ibm.com>

* Update src/pages/components/tabs/usage.mdx

Co-authored-by: Anna Gonzales <agonz@us.ibm.com>

* docs: update titles and images

* docs: removed a few anchor links

* docs: updated image caption

* updated dismissible image

* fix: format

---------

Co-authored-by: Alison Joseph <alison.joseph@us.ibm.com>
Co-authored-by: TJ Egan <tw15egan@gmail.com>
Co-authored-by: Aubrey O'Neal <47198241+aubrey-oneal@users.noreply.github.com>
Co-authored-by: Anna Gonzales <agonz@us.ibm.com>
Co-authored-by: Francine Lucca <francinelucca@hotmail.com>

src/pages/components/tabs/style.mdx

@@ -5,9 +5,23 @@ description:
 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>
+
+</AnchorLinks>
+
 ## Color
 
-### Line tabs
+### Line tab color
 
 | Type       | Element | Property         | Color token           |
 | ---------- | ------- | ---------------- | --------------------- |
@@ -29,7 +43,7 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 <br />
 
-#### Interactive states
+#### Line tab interactive state color
 
 <br />
 
@@ -58,7 +72,7 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 <br />
 
-#### Scrollable states
+#### Line tab scrollable states
 
 <br />
 
@@ -82,7 +96,72 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
   tabs.
 </Caption>
 
-### Contained tabs
+### Dismissible line tab color
+
+| Type       | Element | Property         | Color token           |
+| ---------- | ------- | ---------------- | --------------------- |
+| Unselected | Tab     | background-color | transparent           |
+|            |         | border-bottom    | `$border-subtle` \*   |
+|            | Label   | text-color       | `$text-secondary`     |
+|            | Icon    | svg              | `$icon-secondary`     |
+| Selected   | Label   | text-color       | `$text-primary`       |
+|            | Icon    | svg              | `$icon-primary`       |
+|            | Tab     | border-bottom    | `$border-interactive` |
+
+<div className="image--fixed">
+
+![Example of selected and unselected dismissible line tabs](images/tab-style-9.png)
+
+</div>
+
+<Caption>Example of selected and unselected dismissible line tabs.</Caption>
+
+<br />
+
+#### Dismissible line tab interactive state
+
+<br />
+
+| State    | Element         | Property         | Color token         |
+| -------- | --------------- | ---------------- | ------------------- |
+| Hover    | Label           | text-color       | `$text-primary`     |
+|          | Icon            | svg              | `$icon-primary`     |
+|          |                 | background-color | `$background-hover` |
+|          | Tab             | border-bottom    | `$border-strong`    |
+| Focus    | Tab: unselected | border           | `$focus`            |
+|          | Tab: selected   | border           | `$focus`            |
+| Disabled | Label           | text-color       | `$text-disabled`    |
+|          | Icon            | svg              | `$icon-disabled`    |
+|          | Tab             | background-color | transparent         |
+|          |                 | border-bottom    | `$border-disabled`  |
+
+<Row>
+<Column colLg={8}>
+
+![Examples of unselected close hover, unselected hover, unselected focus, and disabled states for dismissible line tabs](images/tab-style-11a.png)
+
+</Column>
+</Row>
+
+<Caption>
+  Examples of unselected close hover, unselected hover, unselected focus, and
+  disabled states for dismissible line tabs.
+</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Examples of selected close hover, selected focus, and disabled states for dismissible line tabs](images/tab-style-11b.png)
+
+</Column>
+</Row>
+
+<Caption>
+  Examples of selected close hover, selected focus, and disabled states for
+  dismissible line tabs.
+</Caption>
+
+### Contained tab color
 
 | Type       | Element | Property         | Color token           |
 | ---------- | ------- | ---------------- | --------------------- |
@@ -110,7 +189,7 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 <br />
 
-#### Interactive states
+#### Contained tab interactive state color
 
 <br />
 
@@ -143,7 +222,7 @@ tabs.](images/tab-style-5.png)
 
 <br />
 
-#### Scrollable states
+#### Dismissible contained tab scrollable states
 
 <br />
 
@@ -167,6 +246,89 @@ tabs.](images/tab-style-5.png)
   tabs.
 </Caption>
 
+### Dismissible contained tab color
+
+| Type       | Element          | Property         | Color token           |
+| ---------- | ---------------- | ---------------- | --------------------- |
+| Unselected | Tab              | background-color | `$layer-accent` \*    |
+|            |                  | border-right     | `$border-strong` \*   |
+|            | Label            | text-color       | `$text-secondary`     |
+|            | Icon             | svg              | `$icon-secondary`     |
+|            | Dismissible icon | svg              | `$icon-secondary`     |
+| Selected   | Tab              | background-color | `$layer` \*           |
+|            |                  | border-top       | `$border-interactive` |
+|            | Label            | text-color       | `$text-primary`       |
+|            | Icon             | svg              | `$icon-primary`       |
+|            | Dismissible icon | svg              | `$icon-primary`       |
+
+<Caption>
+  * Denotes a contextual color token that will change values based on the layer
+  it is placed on.
+</Caption>
+
+<div className="image--fixed">
+
+![Examples of selected and unselected dismissible contained tabs](images/tab-style-10.png)
+
+</div>
+
+<Caption>
+  Examples of selected and unselected dismissible contained tabs.
+</Caption>
+
+<br />
+
+#### Dismissible tab interactive state color
+
+<br />
+
+| State    | Element                      | Property         | Color token              |
+| -------- | ---------------------------- | ---------------- | ------------------------ |
+| Hover    | Tab                          | background-color | `$layer-accent-hover` \* |
+|          | Label                        | text-color       | `$text-primary`          |
+|          | Icon                         | svg              | `$icon-primary`          |
+|          | Dismissible icon             | svg              | `$icon-primary`          |
+|          | Selected: dismissible icon   | background-color | `$layer-hover` \*        |
+|          | Unselected: dismissible icon | background-color | `$layer-accent-hover` \* |
+| Focus    | Tab                          | border           | `$focus`                 |
+| Disabled | Label                        | text-color       | `$text-disabled`         |
+|          | Icon                         | svg              | `$icon-disabled`         |
+|          | Tab                          | background-color | `$button-disabled`       |
+|          |                              | border-right     | `$border-disabled`       |
+
+<Caption>
+  * Denotes a contextual color token that will change values based on the layer
+  it is placed on.
+</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Unselected hover, unselected close hover, unselected focus, and disabled states for dismissible contained
+tabs.](images/tab-style-12a.png)
+
+</Column>
+</Row>
+
+<Caption>
+  Examples of unselected hover, unselected close hover, unselected focus, and
+  disabled states for dismissible contained tabs.
+</Caption>
+
+<Row>
+<Column colLg={8}>
+
+![Selected close hover, selected focus, and disabled states for dismissible contained
+tabs.](images/tab-style-12b.png)
+
+</Column>
+</Row>
+
+<Caption>
+  Examples of selected close hover, selected focus, and disabled states for
+  dismissible contained tabs.
+</Caption>
+
 ## Typography
 
 Tab labels should be set in sentence case, and should not exceed three words.
@@ -178,7 +340,7 @@ Tab labels should be set in sentence case, and should not exceed three words.
 
 ## Structure
 
-### Line tabs
+### Line tab structure
 
 | Element         | Property                    | px / rem   | Spacing token |
 | --------------- | --------------------------- | ---------- | ------------- |
@@ -203,7 +365,7 @@ Tab labels should be set in sentence case, and should not exceed three words.
 
 <br />
 
-#### Icon-only modifier
+#### Line tab icon-only modifier
 
 <br />
 
@@ -224,7 +386,37 @@ Tab labels should be set in sentence case, and should not exceed three words.
   Structure and spacing measurements for icon-only line tabs | px / rem
 </Caption>
 
-### Contained tabs
+### Dismissible line tab structure
+
+| Element          | Property                    | px / rem   | Spacing token |
+| ---------------- | --------------------------- | ---------- | ------------- |
+| Tab              | height                      | 40 / 2.5   | –             |
+|                  | border-bottom               | 2px        | –             |
+|                  | width                       | auto-width | –             |
+|                  | margin-left                 | 1px        | –             |
+| Label            | padding-left, padding-right | 16 / 1     | `$spacing-05` |
+|                  | padding-top, padding-bottom | 8 / 0.5    | `$spacing-03` |
+| Dismissible icon | padding-right               | 16 / 1     | `$spacing-05` |
+|                  | padding-left                | 8 / 0.5    | `$spacing-03` |
+|                  | svg                         | 16 x 16    | –             |
+| Icon             | padding-right               | 8 / 0.5    | `$spacing-03` |
+|                  | padding-left                | 16 / 1     | `$spacing-05` |
+|                  | svg                         | 16 x 16    | –             |
+
+<div className="image--fixed">
+
+![Structure and spacing measurements for dismissible line tabs without icons (top) and with icons (bottom).](images/tab-style-13.png)
+
+</div>
+
+<Caption>
+  Structure and spacing measurements for line tabs without icons (top) and with
+  icons (bottom) | px / rem
+</Caption>
+
+<br />
+
+### Contained tab structure
 
 | Element           | Property                    | px / rem         | Spacing token |
 | ----------------- | --------------------------- | ---------------- | ------------- |
@@ -251,7 +443,7 @@ Tab labels should be set in sentence case, and should not exceed three words.
 
 <br />
 
-#### Icon-only modifier
+#### Contained tab icon-only modifier
 
 <br />
 
@@ -270,3 +462,30 @@ Tab labels should be set in sentence case, and should not exceed three words.
 <Caption>
   Structure and spacing measurements for icon-only contained tabs | px / rem
 </Caption>
+
+### Dismissible contained tab structure
+
+| Element          | Property                    | px / rem         | Spacing token |
+| ---------------- | --------------------------- | ---------------- | ------------- |
+| Tab              | height                      | 40 / 2.5         | –             |
+|                  | border-top                  | 2px              | –             |
+|                  | width                       | auto-width, grid | –             |
+| Label            | padding-left, padding-right | 16 / 1           | `$spacing-05` |
+| Dismissible icon | padding-right               | 16 / 1           | `$spacing-05` |
+|                  | padding-left                | 8 / .5           | `$spacing-03` |
+|                  | svg                         | 16 x 16          | –             |
+| Icon             | padding-right               | 8 / .5           | `$spacing-03` |
+|                  | padding-left                | 16 / 1           | `$spacing-05` |
+|                  | svg                         | 16 x 16          | –             |
+| Tab              | border-right                | 1px              | –             |
+
+<div className="image--fixed">
+
+![Structure and spacing measurements for dismissible contained tabs in px and rem](images/tab-style-14.png)
+
+</div>
+
+<Caption>
+  Structure and spacing measurements for dismissible contained tabs without
+  icons (top) and with icons (bottom)| px / rem
+</Caption>

src/pages/components/tabs/usage.mdx

@@ -562,6 +562,75 @@ secondary labels with line tabs or auto-width contained tabs.
 </Column>
 </Row>
 
+### Dismissible tabs
+
+Dismissible tabs allow users to close tabs providing a focused and relevant
+experience. Users can add or remove tabs as needed, accommodating future content
+additions or modifications without drastically changing the overall layout or
+structure.
+
+<Row>
+<Column colLg={8}>
+
+![Dismissible tabs](images/tabs-usage-15.png)
+
+</Column>
+</Row>
+
+<Caption>
+  Example of dismissible line tabs (top) and dismissible contained tabs (bottom)
+</Caption>
+
+#### When to use
+
+- Use dismissible tabs to offer flexibility and scalability in complex
+  interfaces that require users to create multiple sections or modules.
+- Use dismissible tabs for content created or curated by the user.
+- Use to focus a specific data set or search results.
+
+#### When not to use
+
+- Do not use when tabs contain frequently used or critical information.
+- Do not use as navigation.
+
+#### Dismissible tabs with icons
+
+Carbon provides an option to include icons within the dismissible tabs. Only use
+icons within dismissible tabs if all tabs will include icons. Do not mix
+dismisible tabs without icons with dismissible tabs with icons.
+
+#### Dismissing a tab
+
+When dismissing a tab, an inline warning or modal may be used when information
+contained in a tab will no longer be accessible or difficult to retrieve. Since
+warnings, especially modals, are highly disruptive, only use when the dismissal
+causes errors, unintentional deletions, or unsaved changes.
+
+#### Triggering a new tab
+
+There are various ways to trigger a new tab. The trigger button can visually
+change its shape and size depending on the use case. Keep the trigger close
+enough to the new tab to associate the add action with the new tab item. The
+order of tabs can be ascending or descending depending on use case but do keep
+them in a sequential, logical order.
+
+If all tabs are dismissible, make sure a user understands how to trigger new
+tabs once the tabs are gone. Provide visual cues, such as a container or
+placeholder tab, so the user clearly understands that the trigger button is
+creating a new tab in a place they expect.
+
+<Row>
+<Column colLg={8}>
+
+![Dismissible tabs](images/tabs-usage-16.png)
+
+</Column>
+</Row>
+
+<Caption>
+  Example of dismissible tabs within a UI utilizing a button to add a tab
+</Caption>
+
 ## Related
 
 #### Content switcher versus tabs