docs: Al label component (#4133)

* docs: Al label component

* Content and image updates

* updated-images

* Added-style-tab

* added-style-images

* Added-accessibility-content

* Add-link-to-ai-overview

* Updates from review

* Update style.mdx

* Updates from Gower's review

* additonal-a11y-content

* final-a11y-edits

---------

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

src/data/nav-items.yaml

@@ -88,6 +88,8 @@
       path: /components/overview/components
     - title: Accordion
       path: /components/accordion/usage/
+    - title: AI label
+      path: /components/ai-label/usage/
     - title: Breadcrumb
       path: /components/breadcrumb/usage/
     - title: Button

src/pages/components/ai-label/accessibility.mdx

@@ -0,0 +1,91 @@
+---
+title: AI label
+description: The AI label indicates an instance of AI in the UI.
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+<PageDescription>
+
+No accessibility annotations are needed for AI labels, but keep these
+considerations in mind if you are modifying Carbon or creating a custom
+component.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>What Carbon provides</AnchorLink>
+<AnchorLink>Development considerations</AnchorLink>
+
+</AnchorLinks>
+
+## What Carbon provides
+
+### Keyboard interactions
+
+The AI labels is the trigger button. The AI label is in the tab order and is
+activated by pressing `Enter` or `Space`. The activation toggles the
+explainability popover open and closed, and focus remains on the trigger.
+
+When the popover contains interactive elements, pressing `Tab` will move focus
+to the first component in the popover. When the popover only has non-interactive
+text, or when the focus is on the last component in the popover, pressing `Tab`
+will close the popover and move focus to the next tab stop on the page. Pressing
+`Esc` in an open popover closes it and returns focus to the trigger.
+
+<Row>
+<Column colLg={12}>
+
+![Example of AI label keyboard interaction](images/ai-label-accessibility-1.png)
+
+</Column>
+</Row>
+
+<Caption>
+  The AI label icon button that triggers the popover is in the page tab order,
+  as are interactive elements inside an open popover.
+</Caption>
+
+#### Input interactions
+
+The AI label can appear inside user inputs, where it adds an additional tab
+stop. For example, a text input will take focus as normal (the existing value
+will be selected), and then the AI label will take a second tab stop. If the
+user clears the existing AI-supplied value, (with the `Delete` key), then the AI
+label becomes a `revert` icon, which on activation will restore the AI-supplied
+value in the input.
+
+<Row>
+<Column colLg={8}>
+
+![The AI label inside the input takes its own tab stop, and still toggles the explainability popover on and off.](images/ai-label-accessibility-3.png)
+
+<Caption>
+  The AI label button is a second tab stop after the inital tab stop for the
+  input.
+</Caption>
+
+</Column>
+</Row>
+
+<Row>
+<Column colLg={8}>
+
+![The revert button replaces the AI label, but otherwise the keyboard navigation and operation is similar.](images/ai-label-accessibility-4.png)
+
+</Column>
+</Row>
+
+<Caption>
+  The AI label changes to a "revert" symbol if a user modifies the input value.
+  Activating "revert" restores the prior AI value.
+</Caption>
+
+## Development considerations
+
+Keep these considerations in mind if you are modifying Carbon or creating a
+custom component.
+
+- The icon button has `aria-label="AI - Show information"`.
+- The button uses `aria-expanded` to set toggletip visibility and
+  `aria-controls` to handle navigation to the content.

src/pages/components/ai-label/code.mdx

@@ -0,0 +1,45 @@
+---
+title: AI label
+description: The AI label indicates an instance of AI in the UI.
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+<PageDescription>
+
+Preview the AI label component with the React live demo. For detailed code usage
+documentation, see the Storybooks for each framework below.
+
+</PageDescription>
+
+## Documentation
+
+<Row className="resource-card-group">
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+    subTitle="React"
+    href="https://react.carbondesignsystem.com/?path=/docs/experimental-unstable-slug--overview"
+    >
+
+<MdxIcon name="react" />
+
+  </ResourceCard>
+</Column>
+<Column colLg={4} colMd={4} noGutterSm>
+  <ResourceCard
+      subTitle="Web Components"
+      href="https://web-components.carbondesignsystem.com/?path=/story/experimental-slug--default"
+      >
+
+<MdxIcon name="webcomponents" />
+
+  </ResourceCard>
+</Column>
+</Row>
+
+## Live demo
+
+<InlineNotification>
+
+The live demo for AI label will be added soon. Check back later for updates.
+
+</InlineNotification>

src/pages/components/ai-label/style.mdx

@@ -0,0 +1,189 @@
+---
+title: AI label
+description: The AI label indicates an instance of AI in the UI.
+tabs: ['Usage', 'Style', 'Code', 'Accessibility']
+---
+
+<PageDescription>
+
+The following page documents visual specifications such as color, typography,
+structure, and sizes.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Color</AnchorLink>
+<AnchorLink>Typography</AnchorLink>
+<AnchorLink>Structure</AnchorLink>
+<AnchorLink>Sizes</AnchorLink>
+
+</AnchorLinks>
+
+## Color
+
+### Default color
+
+| State   | Element | Property   | Color token           |
+| ------- | ------- | ---------- | --------------------- |
+| Enabled | Text    | text color | `$text-primary`       |
+|         | Button  | border     | `$border-inverse`     |
+|         |         | background | `transparent`         |
+| Hover   | Text    | text color | `$text-inverse`       |
+|         | Button  | border     | `$border-inverse`     |
+|         |         | background | `$background-inverse` |
+| Focus   | Button  | border     | `$focus`              |
+
+<Row>
+<Column colLg={8}>
+
+![Examples of default AI label states](images/style-ai-label-states-default.png)
+
+</Column>
+</Row>
+
+### Inline color
+
+| State   | Element | Property   | Color token       |
+| ------- | ------- | ---------- | ----------------- |
+| Enabled | Text    | text color | `$text-primary`   |
+|         | Dot     | fill       | `$icon-primary`   |
+|         | Button  | background | `transparent`     |
+| Hover   | Text    | text color | `$text-secondary` |
+|         | Button  | border     | `$border-inverse` |
+|         |         | background | `transparent`     |
+| Focus   | Button  | border     | `$focus`          |
+
+<Row>
+<Column colLg={8}>
+
+![Examples of inline AI label states](images/style-ai-label-states-inline.png)
+
+</Column>
+</Row>
+
+### Explainability popover color
+
+| Element            | Property               | Color token              |
+| ------------------ | ---------------------- | ------------------------ |
+| Popover background | background             | `$ai-popover-background` |
+|                    | linear-gradient: start | `$ai-aura-start`         |
+|                    | linear-gradient: end   | `$ai-aura-end`           |
+| Popover border     | linear-gradient: start | `$ai-border-start`       |
+|                    | linear-gradient: end   | `$ai-border-end`         |
+
+<Row>
+<Column colLg={8}>
+
+![Examples of an explainability popover](images/style-ai-label-explainability.png)
+
+</Column>
+</Row>
+
+## Typography
+
+### Default type
+
+| Element       | Font-size (px/rem) | Font-weight    | Type token    |
+| ------------- | ------------------ | -------------- | ------------- |
+| Text (xl)     | 20 / 1.25          | SemiBold / 600 | `$heading-03` |
+| Text (sm–lg)  | 16 / 1             | SemiBold / 600 | `$heading-02` |
+| Text (2xs–xs) | 12 / 0.75          | SemiBold / 600 | –             |
+| Text (mini)   | 9 / 0.5625         | SemiBold / 600 | –             |
+
+### Inline type
+
+| Element   | Font-size (px/rem) | Font-weight    | Type token    |
+| --------- | ------------------ | -------------- | ------------- |
+| Text (lg) | 16 / 1             | SemiBold / 600 | `$heading-02` |
+| Text (md) | 14 / 0.875         | SemiBold / 600 | `$heading-01` |
+| Text (sm) | 12 / 0.75          | SemiBold / 600 | –             |
+
+### Explainability popover type
+
+| Element | Font-size (px/rem) | Font-weight   | Type token    |
+| ------- | ------------------ | ------------- | ------------- |
+| Text    | 14 / 0.875         | Regular / 400 | `$label-02`   |
+| Title   | 28 / 1.75          | Regular / 400 | `$heading-04` |
+| Body    | 14 / 0.875         | Regular / 400 | `$body-01`    |
+
+## Structure
+
+### Default structure
+
+| Element | Property | Value                                                 | Spacing token |
+| ------- | -------- | ----------------------------------------------------- | ------------- |
+| Button  | border   | 1px                                                   | –             |
+|         | height   | See [sizes](/components/ai-label/style#default-sizes) | –             |
+| Text    | padding  | centered                                              | –             |
+
+<div className="image--fixed">
+
+![Structure of default AI labels](images/style-ai-label-structure-default.png)
+
+</div>
+
+<Caption>
+  Recommended structure and spacing measurements for default AI label | px / rem
+</Caption>
+
+### Inline structure
+
+| Element        | Property                    | px/rem                                               | Spacing token |
+| -------------- | --------------------------- | ---------------------------------------------------- | ------------- |
+| Text           | padding-left                | 4px                                                  | `$spacing-02` |
+| Button         | border                      | 1px                                                  | –             |
+|                | padding-left, padding-right | 4px                                                  | `$spacing-02` |
+|                | height                      | See [sizes](/components/ai-label/style#inline-sizes) | –             |
+| Bullet (sm-md) | height, width               | 4px                                                  | –             |
+| Bullet (lg)    | height, width               | 8px                                                  | –             |
+
+<div className="image--fixed">
+
+![Structure of inline AI labels](images/style-ai-label-structure-inline.png)
+
+</div>
+
+<Caption>
+  Recommended structure and spacing measurements for inline AI label | px / rem
+</Caption>
+
+### Explainability popover structure
+
+| Element   | Property | px/rem | Spacing token |
+| --------- | -------- | ------ | ------------- |
+| Container | padding  | 24px   | `$spacing-06` |
+| Footer    | height   | 48px   | –             |
+
+<div className="image--fixed">
+
+![Structure of the explainability popover](images/style-ai-label-explainability-structure.png)
+
+</div>
+
+<Caption>
+  Recommended structure and spacing measurements for the explainability popover
+  | px / rem
+</Caption>
+
+## Sizes
+
+### Default sizes
+
+| Default size     | Height (px/rem) |
+| ---------------- | --------------- |
+| Mini             | 16 / 1          |
+| 2x small (2xs)   | 20 / 1.25       |
+| Extra small (xs) | 24 / 1.5        |
+| Small (sm)       | 32 / 2          |
+| Medium (md)      | 40 / 2.5        |
+| Large (lg)       | 48 / 3          |
+| Extra large (xl) | 64 / 4          |
+
+### Inline sizes
+
+| Inline size | Height (px/rem) |
+| ----------- | --------------- |
+| Small (sm)  | 16 / 1          |
+| Medium (md) | 18 / 1.125      |
+| Large (lg)  | 22 / 1.375      |