diff --git a/src/data/nav-items.yaml b/src/data/nav-items.yaml index 9f12ae3250e..477a17e74b0 100644 --- a/src/data/nav-items.yaml +++ b/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 diff --git a/src/pages/components/ai-label/accessibility.mdx b/src/pages/components/ai-label/accessibility.mdx new file mode 100755 index 00000000000..346c6748267 --- /dev/null +++ b/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'] +--- + + + +No accessibility annotations are needed for AI labels, but keep these +considerations in mind if you are modifying Carbon or creating a custom +component. + + + + + +What Carbon provides +Development considerations + + + +## 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. + + + + +![Example of AI label keyboard interaction](images/ai-label-accessibility-1.png) + + + + + + The AI label icon button that triggers the popover is in the page tab order, + as are interactive elements inside an open popover. + + +#### 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. + + + + +![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) + + + The AI label button is a second tab stop after the inital tab stop for the + input. + + + + + + + + +![The revert button replaces the AI label, but otherwise the keyboard navigation and operation is similar.](images/ai-label-accessibility-4.png) + + + + + + The AI label changes to a "revert" symbol if a user modifies the input value. + Activating "revert" restores the prior AI value. + + +## 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. diff --git a/src/pages/components/ai-label/code.mdx b/src/pages/components/ai-label/code.mdx new file mode 100755 index 00000000000..04771894871 --- /dev/null +++ b/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'] +--- + + + +Preview the AI label component with the React live demo. For detailed code usage +documentation, see the Storybooks for each framework below. + + + +## Documentation + + + + + + + + + + + + + + + + + + +## Live demo + + + +The live demo for AI label will be added soon. Check back later for updates. + + diff --git a/src/pages/components/ai-label/images/ai-explainability-light.png b/src/pages/components/ai-label/images/ai-explainability-light.png new file mode 100644 index 00000000000..95f0b2424e0 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-explainability-light.png differ diff --git a/src/pages/components/ai-label/images/ai-label-01.png b/src/pages/components/ai-label/images/ai-label-01.png new file mode 100644 index 00000000000..92d27e41722 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-01.png differ diff --git a/src/pages/components/ai-label/images/ai-label-accessibility-1.png b/src/pages/components/ai-label/images/ai-label-accessibility-1.png new file mode 100644 index 00000000000..c55e2a23a02 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-accessibility-1.png differ diff --git a/src/pages/components/ai-label/images/ai-label-accessibility-3.png b/src/pages/components/ai-label/images/ai-label-accessibility-3.png new file mode 100644 index 00000000000..31fc56e4188 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-accessibility-3.png differ diff --git a/src/pages/components/ai-label/images/ai-label-accessibility-4.png b/src/pages/components/ai-label/images/ai-label-accessibility-4.png new file mode 100644 index 00000000000..7fe3a090024 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-accessibility-4.png differ diff --git a/src/pages/components/ai-label/images/ai-label-anatomy.png b/src/pages/components/ai-label/images/ai-label-anatomy.png new file mode 100644 index 00000000000..a55431898c3 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-anatomy.png differ diff --git a/src/pages/components/ai-label/images/ai-label-click-target.png b/src/pages/components/ai-label/images/ai-label-click-target.png new file mode 100644 index 00000000000..bb8d28560ab Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-click-target.png differ diff --git a/src/pages/components/ai-label/images/ai-label-explainability-01.png b/src/pages/components/ai-label/images/ai-label-explainability-01.png new file mode 100644 index 00000000000..b0357cb3485 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-explainability-01.png differ diff --git a/src/pages/components/ai-label/images/ai-label-explainability-anatomy.png b/src/pages/components/ai-label/images/ai-label-explainability-anatomy.png new file mode 100644 index 00000000000..4613e80f3cb Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-explainability-anatomy.png differ diff --git a/src/pages/components/ai-label/images/ai-label-explainability-orientation.png b/src/pages/components/ai-label/images/ai-label-explainability-orientation.png new file mode 100644 index 00000000000..1bc5e4abda4 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-explainability-orientation.png differ diff --git a/src/pages/components/ai-label/images/ai-label-levels-both.png b/src/pages/components/ai-label/images/ai-label-levels-both.png new file mode 100644 index 00000000000..0bf17f57cfb Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-levels-both.png differ diff --git a/src/pages/components/ai-label/images/ai-label-levels-broad.png b/src/pages/components/ai-label/images/ai-label-levels-broad.png new file mode 100644 index 00000000000..80fcd3d0590 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-levels-broad.png differ diff --git a/src/pages/components/ai-label/images/ai-label-levels-focused.png b/src/pages/components/ai-label/images/ai-label-levels-focused.png new file mode 100644 index 00000000000..831a215afb8 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-levels-focused.png differ diff --git a/src/pages/components/ai-label/images/ai-label-localization.png b/src/pages/components/ai-label/images/ai-label-localization.png new file mode 100644 index 00000000000..c7a0267433d Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-localization.png differ diff --git a/src/pages/components/ai-label/images/ai-label-placement-containers.png b/src/pages/components/ai-label/images/ai-label-placement-containers.png new file mode 100644 index 00000000000..af3f31ba759 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-placement-containers.png differ diff --git a/src/pages/components/ai-label/images/ai-label-placement-data-table.png b/src/pages/components/ai-label/images/ai-label-placement-data-table.png new file mode 100644 index 00000000000..2c085995f10 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-placement-data-table.png differ diff --git a/src/pages/components/ai-label/images/ai-label-placement-form.png b/src/pages/components/ai-label/images/ai-label-placement-form.png new file mode 100644 index 00000000000..d832c0a4df2 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-placement-form.png differ diff --git a/src/pages/components/ai-label/images/ai-label-placement-icons-exception.png b/src/pages/components/ai-label/images/ai-label-placement-icons-exception.png new file mode 100644 index 00000000000..c07159e2645 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-placement-icons-exception.png differ diff --git a/src/pages/components/ai-label/images/ai-label-placement-icons.png b/src/pages/components/ai-label/images/ai-label-placement-icons.png new file mode 100644 index 00000000000..701ee0940ab Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-placement-icons.png differ diff --git a/src/pages/components/ai-label/images/ai-label-placement-inputs.png b/src/pages/components/ai-label/images/ai-label-placement-inputs.png new file mode 100644 index 00000000000..271910616b6 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-placement-inputs.png differ diff --git a/src/pages/components/ai-label/images/ai-label-revert.png b/src/pages/components/ai-label/images/ai-label-revert.png new file mode 100644 index 00000000000..bfab5be7dd0 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-revert.png differ diff --git a/src/pages/components/ai-label/images/ai-label-sizes-default.png b/src/pages/components/ai-label/images/ai-label-sizes-default.png new file mode 100644 index 00000000000..32baa009d53 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-sizes-default.png differ diff --git a/src/pages/components/ai-label/images/ai-label-sizes-inline.png b/src/pages/components/ai-label/images/ai-label-sizes-inline.png new file mode 100644 index 00000000000..12a5be0d480 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-sizes-inline.png differ diff --git a/src/pages/components/ai-label/images/ai-label-states.png b/src/pages/components/ai-label/images/ai-label-states.png new file mode 100644 index 00000000000..9136d331f73 Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-states.png differ diff --git a/src/pages/components/ai-label/images/ai-label-variants.png b/src/pages/components/ai-label/images/ai-label-variants.png new file mode 100644 index 00000000000..2d28ce46cfa Binary files /dev/null and b/src/pages/components/ai-label/images/ai-label-variants.png differ diff --git a/src/pages/components/ai-label/images/style-ai-label-explainability-structure.png b/src/pages/components/ai-label/images/style-ai-label-explainability-structure.png new file mode 100644 index 00000000000..92834a7929e Binary files /dev/null and b/src/pages/components/ai-label/images/style-ai-label-explainability-structure.png differ diff --git a/src/pages/components/ai-label/images/style-ai-label-explainability.png b/src/pages/components/ai-label/images/style-ai-label-explainability.png new file mode 100644 index 00000000000..f04b945fb38 Binary files /dev/null and b/src/pages/components/ai-label/images/style-ai-label-explainability.png differ diff --git a/src/pages/components/ai-label/images/style-ai-label-states-default.png b/src/pages/components/ai-label/images/style-ai-label-states-default.png new file mode 100644 index 00000000000..a4dcbc70262 Binary files /dev/null and b/src/pages/components/ai-label/images/style-ai-label-states-default.png differ diff --git a/src/pages/components/ai-label/images/style-ai-label-states-inline.png b/src/pages/components/ai-label/images/style-ai-label-states-inline.png new file mode 100644 index 00000000000..d978f137d7b Binary files /dev/null and b/src/pages/components/ai-label/images/style-ai-label-states-inline.png differ diff --git a/src/pages/components/ai-label/images/style-ai-label-structure-default.png b/src/pages/components/ai-label/images/style-ai-label-structure-default.png new file mode 100644 index 00000000000..fab13725853 Binary files /dev/null and b/src/pages/components/ai-label/images/style-ai-label-structure-default.png differ diff --git a/src/pages/components/ai-label/images/style-ai-label-structure-inline.png b/src/pages/components/ai-label/images/style-ai-label-structure-inline.png new file mode 100644 index 00000000000..e50819d7785 Binary files /dev/null and b/src/pages/components/ai-label/images/style-ai-label-structure-inline.png differ diff --git a/src/pages/components/ai-label/style.mdx b/src/pages/components/ai-label/style.mdx new file mode 100755 index 00000000000..fd1d854f3df --- /dev/null +++ b/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'] +--- + + + +The following page documents visual specifications such as color, typography, +structure, and sizes. + + + + + +Color +Typography +Structure +Sizes + + + +## 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` | + + + + +![Examples of default AI label states](images/style-ai-label-states-default.png) + + + + +### 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` | + + + + +![Examples of inline AI label states](images/style-ai-label-states-inline.png) + + + + +### 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` | + + + + +![Examples of an explainability popover](images/style-ai-label-explainability.png) + + + + +## 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 | – | + +
+ +![Structure of default AI labels](images/style-ai-label-structure-default.png) + +
+ + + Recommended structure and spacing measurements for default AI label | px / rem + + +### 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 | – | + +
+ +![Structure of inline AI labels](images/style-ai-label-structure-inline.png) + +
+ + + Recommended structure and spacing measurements for inline AI label | px / rem + + +### Explainability popover structure + +| Element | Property | px/rem | Spacing token | +| --------- | -------- | ------ | ------------- | +| Container | padding | 24px | `$spacing-06` | +| Footer | height | 48px | – | + +
+ +![Structure of the explainability popover](images/style-ai-label-explainability-structure.png) + +
+ + + Recommended structure and spacing measurements for the explainability popover + | px / rem + + +## 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 | diff --git a/src/pages/components/ai-label/usage.mdx b/src/pages/components/ai-label/usage.mdx new file mode 100755 index 00000000000..81858d94501 --- /dev/null +++ b/src/pages/components/ai-label/usage.mdx @@ -0,0 +1,532 @@ +--- +title: AI label +description: The AI label indicates an instance of AI in the UI. +tabs: ['Usage', 'Style', 'Code', 'Accessibility'] +--- + +import A11yStatus from 'components/A11yStatus'; + + + +The AI label indicates an instance of AI in the UI. It enables AI transparency +through the visual recognition the AI icon and is the key pathway to AI +explainability by acting as the trigger for the explainability popover. + + + + + +**New!** +[AI label](https://react.carbondesignsystem.com/?path=/docs/experimental-unstable-slug--overview) +is now available as an experimental component. The AI label was previously +called "AI Slug" but has been changed to better reflect its usage. This name +change will be reflected in code and Figma once it moves to stable in the near +future. + + + + + +Live demo +Overview +Formatting +Content +Behaviors +Related +Feedback + + + +## Live demo + + + +The live demo and accessibility testing status for AI label will be added soon. +Check back later for updates. + + + +## Overview + +The AI label is more than just an indicator of AI instances in the UI. It’s also +a consistent pathway to AI explainability. Its behavior is flexible enough to +cooperate with the behaviors and interactions within existing products. + +The AI label is intended for any scenario where something is being generated by +or with AI to reinforce AI transparency, accountability, and explainability at +any interface level. This also enables more effective recognition and recall of +AI instances in a way that is identifiable across any IBM product. + + + + +![An UI example with various AI label instances](images/ai-label-01.png) + + + + +### Variants + +| Variant | Purpose | +| --------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| _Default_ | The default AI label used in most components and container type use cases. It can be used for both broad and focused AI instances. | +| _Inline_ | A specific type of AI label used only in small focused AI instances and often paired inline with text content. | + + + + +![A default and inline AI label](images/ai-label-variants.png) + + + + +Default (left), Inline (right) + +### When to use + +#### Mark AI-generated content + +AI transparency is key, and the AI label is an accessible, interactive element +that marks any AI instance presented in the interface. + +#### Provides a consistent visual reference point for AI + +For recognition and recall, users need a consistent, identifiable visual +reference to look to when they need to understand more details about how the AI +was built. + +#### A pathway to explainability + +Users must clearly understand how to access more details about how an AI was +built. By providing a bridge to explainability from the AI label, users are +given a recognizable location to learn more about the AI model. + +### When not to use + +#### Don’t use the AI label as decoration + +These are strictly intended to indicate any time a modality or component is +using AI. + +#### Don’t modify AI label behaviors + +The AI label is intended as a pathway to explainability. Any additional +behaviors can set unclear and inconsistent expectations. + +#### Don’t use the AI label as a trigger for AI actions + +The AI label is not a UI icon and should not be used with buttons or other +call-to-actions to trigger an AI action like “regenerate.” Those type of AI +actions will have their own UI icons. + +## Formatting + +### Anatomy + + + + +![Anatomy of AI label](images/ai-label-anatomy.png) + + + + +1. **AI indicator / button**: indicates AI is present and is the button trigger + for the explainability popover. It can be either the default or inline + variant. +2. **Text label**: the text abbreviation for artificial intelligence which can + be translated as needed. +3. **Explainability popover**: Area that contains AI explainability content and + interactive elements. + +### Sizing + +#### Default sizes + +The default AI label spans the range of UI icons and pictogram sizes. Which size +to use is determined by the prominence and hierarchy of the area it is in or by +its neighboring content such as other buttons. When placed next to other ghost +icon buttons we typically recommend going down one size from the button size so +they are optically weighted the same. + +| 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 | + + + + +![Default AI label sizes](images/ai-label-sizes-default.png) + + + + +#### Inline sizes + +The size of the inline AI label text should match the size of the text it is +placed inline with. For example, when inserting the inline AI label into a table +row with 14px font size, you match it with the medium-size inline AI label that +also has a 14px font. + +| Inline size | Height (px/rem) | Use case | +| ----------- | --------------- | --------------------- | +| Small (sm) | 16 / 1 | Paired with 12px type | +| Medium (md) | 18 / 1.125 | Paired with 14px type | +| Large (lg) | 22 / 1.375 | Paired with 16px type | + + + + +![Inline AI label sizes](images/ai-label-sizes-inline.png) + + + + +### Placement + +The AI label should be placed in consistent locations based on modality to help +users identify AI presence in the interface. Consistent placement reinforces +recognition and recall for users. The instructions for these placements assume a +left-to-right reading order. If right-to-left then these placements should be +mirrored. + +#### In containers + +The AI label should be placed in the upper right of the container with +appropriate margin. Never place the AI label flush to the edges of a container. + + + + +![Example of an AI label placement in a container](images/ai-label-placement-containers.png) + + + + +#### In inputs + +Place AI labels on the right side and in the middle of any form inputs +(dropdowns, text or number input, etc.). + + + + +![Example of an AI label placement in an input](images/ai-label-placement-inputs.png) + + + + +#### With other icons + +If other icons are present alongside the AI label, then the AI label should be +placed in the far left position of the icon group. + + + + +![Example of an AI label placement with other icons](images/ai-label-placement-icons.png) + + + + +The exception is when the icon has an interaction state that alters its size or +position, like an expandable search or toggle-able sort. In these instances, the +AI label is placed to the right of these exceptions but still to the left of +other icon types. + + + + +![Example of an AI label placement with search](images/ai-label-placement-icons-exception.png) + + + + +#### In data tables + +Where the AI label is positioned inside of a data table depends on which parts +of the data are AI generated. For more details, see the +[AI presence](/components/data-table/usage/#ai-presence) section on the data +table component page. + +- If the whole table has an AI presence, then place the AI label in the top + right of the table header. +- If a whole column has an AI presence, then place the AI label in the far right + of the column header. The sort icon of the table column will now appear to the + left of the AI label. +- If a whole row has an AI presence, then place the AI label to the far left of + the row and to the left of any selection or expansion controls. +- If a single cell has an AI presence, then place the AI label inline and left + to the cell text. + + + + +![Example of an AI label placement in data tables](images/ai-label-placement-data-table.png) + + + + +#### In forms + +Where the AI label is placed in a form can vary depending on if the AI presence +is across the whole form or just in certain parts of the form. For more +guidance, see the [AI presence](/components/form/usage/#ai-presence) section on +the form component page. + +- If the entire form has an AI presence, then place the AI label in top right of + the form header. +- If only some parts of the form have an AI presence then the AI label should be + embedded in the components or sections that are AI-generated. + + + + +![Example of an AI label placement in forms](images/ai-label-placement-form.png) + + + + +### Levels of visibility + +The AI label might appear at multiple levels of a page, or it might appear only +once. The content in the AI explainability popover might be focused on a single +AI instance or broadly address multiple instances. All scenarios are acceptable +and possible, but the level of visibility depends on the need for explainability +and/or the need to distinguish AI content from human content. + +| Visibility level | Usecase | +| ---------------- | ------------------------------------------------------------- | +| _Focused_ | Use for individual occurrences of AI within a section | +| _Broad_ | Use for summarization of AI usage across a section of a page. | + +#### Use a focused AI label: + +- When the user needs to have an individual AI instance explained. +- When the user needs to distinguish between AI and non-AI content. + + + + +![Example of a focused AI label instance](images/ai-label-levels-focused.png) + + + + + + An example of focused AI labeling inside single cells in a data table. + + +#### Use a broad AI label: + +- When users don’t need specific explanations of AI on a per-instance level. +- When the user doesn’t need to act on AI at an instance level. + + + + +![Example of a broad AI label instance](images/ai-label-levels-broad.png) + + + + + + An example of broad AI labeling on a whole column in a data table. + + +#### Using both focused and broad AI label + +Use both focused and broad AI labels when AI surfaces throughout the experience, +but: + +- Individual AI instances still need to be explained. +- The user needs to distinguish between AI and non-AI content. +- The user needs to act on AI at an instance level. + + + + +![Example of a broad AI label instance](images/ai-label-levels-both.png) + + + + + + An example of broad AI labeling on the whole chat converation but focused AI + labeling on a single message. + + +## Content + +### Localization + +The abbreviation `AI` in the AI label stands for the English term +`artificial intelligence`. The abbreviation can be localized for other +languages. Here are some examples of abbreviations in other languages. + +- `AI` in Chinese, Indonesia, Italian, Japanese, Korean, Spanish LA +- `IA` in European Spanish, Brazilian Portuguese, France French +- `KI` in German +- `ИИ` in Russian, Bulgarian + + + + +![Examples of the AI label in various languages](images/ai-label-localization.png) + + + + +### Explainability template + +The explainability popover is a configurable content area. Carbon for AI +provides a recommended content template for creating your explainability +content. The template is split into four main content sections: + +- Overview +- Supporting details +- Artifacts and resources +- Additional actions + +_For IBMers only:_ For more information and guidance on designing content for +your explainability popover, see the +[AI explainability popover](https://w3.ibm.com/w3publisher/design-for-ai/carbon-for-ai/ai-explainability-popover) +pattern on Design for AI. + + + + +![Examples of the AI label in various languages](images/ai-label-explainability-anatomy.png) + + + + +## Behaviors + +### States + +AI label has three interactive states: **enabled**, **hover**, and **focus**. +The AI label should never be disabled as part of a disabled or read-only state. +Learn more about states on the [style](/components/ai-label/style) tab. + + + + +![AI labels shown in their three states](images/ai-label-states.png) + + + + +Enabled (left), hover (middle), focus (right) + +### Clickable areas + +In the default AI label, the clickable area is limited to the icon without any +additional external coverage, such as in a icon-only ghost button. The inline AI +label will have a small amount of extra padding around it included in the click +target area. + + + + +![AI label click target](images/ai-label-click-target.png) + + + + +### Explainability popover + +The popover is the first layer of explainability that is accessed by clicking +the AI label. This provides a consistent up-front way to access explainability +with the ability to dig into more details on-demand. Use this popover any time +AI needs to be explained in your experience. + + + + +![An example of an AI explainability popover](images/ai-label-explainability-01.png) + + + + +#### Opening and dismissing the popover + +The AI label is the trigger that opens explainability popover. The interaction +works like a toggletip where the popover remains open until the user clicks or +tabs away from the AI label. For a details on the keyboard interactions of the +explainability popover, see the +[accessibility](/components/ai-label/accessibility#keyboard-interactions) tab. + +#### Popover orientation + +The popover should auto-position itself to the best orientation on the screen so +that it does not appear out of view for the user. It follows the same alignments +as the primitive caret-tip [popover](/components/popover/usage/#caret-tip). + + + + +![Examples of various orientations for the explainability popover](images/ai-label-explainability-orientation.png) + + + + +### Revert function + +Users can manually override AI-suggested content, but they should always be able +to programmatically switch back to the initially suggested AI content. In these +instances, when the content is overridden by the user, the AI presence styling +is removed and the AI label is replaced by a “revert” action icon-only button. +If a user activates the revert action, the AI-generated content will reappear, +along with the AI presence styling and AI label. + + + + +![An example of user edited AI component](images/ai-label-revert.png) + + + + +## Related + +#### Guidelines + +- [Carbon for AI](/guidelines/carbon-for-ai/) + +#### Components + +- [Checkbox](/components/checkbox/usage/#ai-presence) +- [Data table](/components/data-table/usage/#ai-presence) +- [Date picker](/components/date-picker/usage/#ai-presence) +- [Dropdown](/components/dropdown/usage/#ai-presence) +- [Form](/components/form/usage/#ai-presence) +- [Modal](/components/modal/usage/#ai-presence) +- [Number input](/components/number-input/usage/#ai-presence) +- [Popover](/components/popover/usage/) +- [Radio button](/components/radio-button/usage/#ai-presence) +- [Select](/components/select/usage/#ai-presence) +- [Tag](/components/tag/usage/#ai-presence) +- [Text input](/components/text-input/usage/#ai-presence) +- [Tile](/components/tile/usage/#ai-presence) + +#### Design for AI + +_For IBMers only_ + +- [AI label placement](https://w3.ibm.com/w3publisher/design-for-ai/carbon-for-ai/ai-label-placement) +- [AI explainability popover](https://w3.ibm.com/w3publisher/design-for-ai/carbon-for-ai/ai-explainability-popover) + +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on GitHub. _For IBMers only:_ Questions and feedback +can be directed to Slack in the channels +[#carbon-design-system](https://ibm-studios.slack.com/messages/C0M053VPT/) or +[#carbon-for-ai](https://ibm-studios.slack.com/messages/C0603LZUKRV). diff --git a/src/pages/guidelines/carbon-for-ai/index.mdx b/src/pages/guidelines/carbon-for-ai/index.mdx index bf5ccc38d6b..3e3820d8465 100644 --- a/src/pages/guidelines/carbon-for-ai/index.mdx +++ b/src/pages/guidelines/carbon-for-ai/index.mdx @@ -261,7 +261,8 @@ Users must clearly understand how to access more details about how an AI was built. By providing a bridge to explainability from the AI label, users are given a recognizable location to learn more about the AI model. -More information about designing with the AI label is coming soon. +For more information about using the AI label, see the +[AI label](/components/ai-label/usage/) component page.