docs: Adding dismissible docs

src/pages/components/tabs/style.mdx

@@ -5,6 +5,22 @@ 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> <AnchorLink>Size</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
+
+</AnchorLinks>
+
 ## Color
 
 ### Line tabs
@@ -25,11 +41,13 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 </div>
 
-<Caption>Example of selected and unselected line tabs.</Caption>
+<Caption>
+Example of selected and unselected line tabs.
+</Caption>
 
 <br />
 
-#### Interactive states
+#### Interactive state color
 
 <br />
 
@@ -82,6 +100,67 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
   tabs.
 </Caption>
 
+### Dismissible line tabs
+
+| 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 />
+
+#### Interactive state color
+
+<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` |
+
+<div className="image--fixed">
+
+![Examples of unselected close hover, unselected hover, unselected focus, and disabled states for dismissible line tabs](images/tab-style-11a.png)
+
+</div>
+
+<Caption>
+  Examples of unselected close hover, unselected hover, unselected focus, and disabled states for
+  dismissible line tabs.
+</Caption>
+
+![Examples of selected close hover, selected focus, and disabled states for dismissible line tabs](images/tab-style-11b.png)
+
+</div>
+
+<Caption>
+  Examples of unselected close hover, unselected hover, unselected focus, and disabled states for
+  dismissible line tabs.
+</Caption>
+
 ### Contained tabs
 
 | Type       | Element | Property         | Color token           |
@@ -106,11 +185,13 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 
 </div>
 
-<Caption>Examples of selected and unselected contained tabs.</Caption>
+<Caption>
+Examples of selected and unselected contained tabs.
+</Caption>
 
 <br />
 
-#### Interactive states
+#### Interactive state color
 
 <br />
 
@@ -167,6 +248,83 @@ tabs.](images/tab-style-5.png)
   tabs.
 </Caption>
 
+### Dismissible contained tabs
+
+| 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 />
+
+#### 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>
+
+<div className="image--fixed">
+
+![Unselected hover, unselected close hover, unselected focus, and disabled states for dismissible contained
+tabs.](images/tab-style-12a.png)
+
+</div>
+
+<Caption>
+  Examples of unselected hover, unselected close hover, unselected focus, and disabled states for dismissible contained tabs.
+</Caption>
+
+<div className="image--fixed">
+
+![Selected close hover, selected focus, and disabled states for dismissible contained
+tabs.](images/tab-style-12b.png)
+
+</div>
+
+<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.
@@ -176,6 +334,8 @@ Tab labels should be set in sentence case, and should not exceed three words.
 | Label: unselected | 14 / 0.875         | Regular / 400  | `$body-compact-01`    |
 | Label: selected   | 14 / 0.875         | SemiBold / 600 | `$heading-compact-01` |
 
+
+
 ## Structure
 
 ### Line tabs
@@ -199,7 +359,9 @@ Tab labels should be set in sentence case, and should not exceed three words.
 
 </div>
 
-<Caption>Structure and spacing measurements for line tabs | px / rem</Caption>
+<Caption>
+Structure and spacing measurements for line tabs | px / rem
+</Caption>
 
 <br />
 
@@ -224,6 +386,36 @@ 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>
 
+### Dismissible line tabs
+
+| 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 tabs
 
 | Element           | Property                    | px / rem         | Spacing token |
@@ -270,3 +462,29 @@ 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 tabs
+
+| 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

@@ -451,6 +451,52 @@ 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 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
+
+#### Considerations
+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.
+
+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 to 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.
+
+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.
+
+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