feat: add ai docs to form and data table (#4124)

* ai_fdt * Update src/pages/components/data-table/usage.mdx Co-authored-by: Anna Gonzales <[email protected]> * Update src/pages/components/form/usage.mdx Co-authored-by: Anna Gonzales <[email protected]> * Update src/pages/components/form/usage.mdx Co-authored-by: Anna Gonzales <[email protected]> * ai_fdt * ai-fdt * Update src/pages/components/data-table/usage.mdx Co-authored-by: Anna Gonzales <[email protected]> * Update src/pages/components/data-table/usage.mdx Co-authored-by: Anna Gonzales <[email protected]> * Update src/pages/components/data-table/style.mdx Co-authored-by: Anna Gonzales <[email protected]> * ai_fdt * ai_fdt * ai_fdt * Update src/pages/components/data-table/style.mdx Co-authored-by: Alison Joseph <[email protected]> * Update src/pages/components/data-table/style.mdx Co-authored-by: Alison Joseph <[email protected]> * Update src/pages/components/data-table/style.mdx Co-authored-by: Alison Joseph <[email protected]> * chore: yarn format --------- Co-authored-by: Alina Jacob <[email protected]> Co-authored-by: Anna Gonzales <[email protected]> Co-authored-by: Alison Joseph <[email protected]> Co-authored-by: Alison Joseph <[email protected]>
carbon-design-system · Jun 21, 2024 · a187086 · a187086
1 parent 52482b4
commit a187086
Show file tree

Hide file tree

Showing 23 changed files with 302 additions and 17 deletions.
diff --git a/src/pages/components/data-table/images/style-ai-presence-datatable-row-hover.png b/src/pages/components/data-table/images/style-ai-presence-datatable-row-hover.png
diff --git a/src/pages/components/data-table/images/style-ai-presence-datatable.png b/src/pages/components/data-table/images/style-ai-presence-datatable.png
diff --git a/src/pages/components/data-table/images/style-ai-presence-entire-datatable.png b/src/pages/components/data-table/images/style-ai-presence-entire-datatable.png
diff --git a/src/pages/components/data-table/images/style-ai-presence-individual-cells.png b/src/pages/components/data-table/images/style-ai-presence-individual-cells.png
diff --git a/src/pages/components/data-table/images/style-ai-presence-row-columns.png b/src/pages/components/data-table/images/style-ai-presence-row-columns.png
diff --git a/src/pages/components/data-table/images/usage-ai-presence-datatable-column-ai.png b/src/pages/components/data-table/images/usage-ai-presence-datatable-column-ai.png
diff --git a/src/pages/components/data-table/images/usage-ai-presence-datatable-row-ai-d.png b/src/pages/components/data-table/images/usage-ai-presence-datatable-row-ai-d.png
diff --git a/src/pages/components/data-table/images/usage-ai-presence-datatable-row-ai-l.png b/src/pages/components/data-table/images/usage-ai-presence-datatable-row-ai-l.png
diff --git a/src/pages/components/data-table/images/usage-ai-presence-datatable.png b/src/pages/components/data-table/images/usage-ai-presence-datatable.png
diff --git a/src/pages/components/data-table/images/usage-ai-presence-inline-datatable.png b/src/pages/components/data-table/images/usage-ai-presence-inline-datatable.png
diff --git a/src/pages/components/data-table/style.mdx b/src/pages/components/data-table/style.mdx
@@ -6,6 +6,22 @@ description:
 tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 ---
 
+<PageDescription>
+
+The following page documents visual specifications such as color, typography,
+structure, and AI presence.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Color</AnchorLink>
+<AnchorLink>Typography</AnchorLink>
+<AnchorLink>Structure</AnchorLink>
+<AnchorLink>AI presence</AnchorLink>
+
+</AnchorLinks>
+
 ## Color
 
 ### Table header
@@ -290,3 +306,87 @@ sizes.
 <Caption>
   Structure and spacing measurements for batch action bar | px/rem
 </Caption>
+
+## AI presence
+
+The following are the unique styles applied to the component when the AI slug is
+present. Unless specified, all other tokens in the component remain the same as
+the non-AI variant.
+
+More information about AI style elements is coming soon.
+
+<Title>Entire table</Title>
+
+| Element                    | Property         | Token / Size        |
+| -------------------------- | ---------------- | ------------------- |
+| Data table:background      | background-color | `$layer` \*         |
+|                            | box-shadow       | `$ai-drop-shadow`   |
+|                            | inner-shadow     | `$ai-inner-shadow`  |
+| Linear gradient:background | start            | `$ai-aura-start-sm` |
+|                            | stop             | `$ai-aura-stop`     |
+| Linear gradient:border     | top              | `$ai-border-start`  |
+|                            | bottom           | `$ai-border-end`    |
+| AI Slug                    | size             | large               |
+
+<Row>
+<Column colLg={12}>
+
+![AI Data table](images/style-ai-presence-entire-datatable.png)
+
+<Caption>
+  Structure and spacing measurements for entire data table generated by AI.
+</Caption>
+
+</Column>
+</Row>
+
+<Title>Individual cells</Title>
+
+| Element     | Property | Token / Size |
+| ----------- | -------- | ------------ |
+| Inline Slug | size     | medium       |
+
+<Row>
+<Column colLg={12}>
+
+![Data table with AI generated cells](images/style-ai-presence-individual-cells.png)
+
+<Caption>
+  Structure and spacing measurements for individual cells of a data table
+  generated by AI.
+</Caption>
+
+</Column>
+</Row>
+
+<Title>Rows and columns</Title>
+
+| Element                    | Property  | Token / Size        |
+| -------------------------- | --------- | ------------------- |
+| Linear gradient:background | start     | `$ai-aura-start-sm` |
+|                            | stop      | `$ai-aura-stop`     |
+| Linear gradient:border     | left, top | `$ai-border-strong` |
+| AI Slug                    | size      | mini                |
+
+<Row>
+<Column colLg={12}>
+
+![Data table with AI generated rows and columns](images/style-ai-presence-row-columns.png)
+
+<Caption>
+  Structure and spacing measurements for rows and columns of a data table
+  generated by AI.
+</Caption>
+
+</Column>
+</Row>
+
+<Row>
+<Column colLg={12}>
+
+![AI Data table hover interaction](images/style-ai-presence-datatable-row-hover.png)
+
+<Caption>Hover interaction for an AI generated row.</Caption>
+
+</Column>
+</Row>
diff --git a/src/pages/components/data-table/usage.mdx b/src/pages/components/data-table/usage.mdx
@@ -16,6 +16,15 @@ your product's users.
 
 </PageDescription>
 
+<InlineNotification>
+
+Experimental slug is now available for
+[data table](https://react.carbondesignsystem.com/?path=/docs/experimental-unstable-slug-datatable--overview).
+This addition changes the visual appearance of the component and introduces an
+AI explainability feature when AI is present in the component.
+
+</InlineNotification>
+
 <AnchorLinks>
 
 <AnchorLink>Live demo</AnchorLink>
@@ -25,6 +34,7 @@ your product's users.
 <AnchorLink>Variants</AnchorLink>
 <AnchorLink>Universal behaviors</AnchorLink>
 <AnchorLink>Modifiers</AnchorLink>
+<AnchorLink>AI presence</AnchorLink>
 <AnchorLink>Related</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
@@ -217,8 +227,8 @@ row heights.
 ### Placement
 
 Data tables should be placed in a page's main content area and given plenty of
-space to display data without truncation. Avoid placing data tables inside
-modals or smaller containers where the information can feel cramped or needs
+space to display data without truncation. Avoid placing data tables inside data
+tables or smaller containers where the information can feel cramped or needs
 truncation.
 
 The data table can be placed on the grid following the three different
@@ -317,8 +327,8 @@ For further content guidance, see Carbon's
 The expandable data table helps present large amounts of data in a small space.
 Use the expanded section for supplementary information or data that needs
 additional query time. When the content in the expanded area feels cramped,
-consider taking the user to a dedicated page, side panel, or modal to view the
-information and complete tasks.
+consider taking the user to a dedicated page, side panel, or data table to view
+the information and complete tasks.
 
 <Row>
 <Column colLg={12}>
@@ -616,6 +626,87 @@ alternating colors to make scanning horizontal information easier for the user.
 </Column>
 </Row>
 
+## AI presence
+
+Data table has a modification that takes on the AI visual styling when AI is
+present in the table. The AI variants of a data table function the same as the
+normal variants except for the addition of the AI slug, which is both a visual
+indicator and the trigger for the explainability popover. Where the AI label
+goes inside of a data table depends on which parts of the data are AI generated.
+
+More information about designing for AI guidelines is coming soon.
+
+#### Entire table
+
+When the entire data table is styled for AI, it indicates to the user that AI is
+present in all aspects of the data table.
+
+<Row>
+<Column colLg={12}>
+
+![Example of a data table generated by AI](images/usage-ai-presence-datatable.png)
+
+<Caption>Example of a data table generated by AI.</Caption>
+
+</Column>
+</Row>
+
+#### Individual cells
+
+If only some data table cells have content generated by AI, then those cells
+have an in-line AI slug next to them. These cells do not get any AI layering.
+
+<Row>
+<Column colLg={12}>
+
+![Example of a data table cell generated by AI represneted by the in-line AI slug](images/usage-ai-presence-inline-datatable.png)
+
+<Caption>
+  Example of a data table cell generated by AI represneted by the in-line AI
+  slug.
+</Caption>
+
+</Column>
+</Row>
+
+#### Rows and columns
+
+If content belonging to only a row or column of the data table is generated by
+AI, then only those respective row/s and column/s should receive the AI presence
+styling along with the AI slug, not the entire data table.
+
+<Row>
+<Column colLg={12}>
+
+![Example of a data table column generated by AI](images/usage-ai-presence-datatable-column-ai.png)
+
+<Caption>Example of a data table column generated by AI.</Caption>
+
+</Column>
+</Row>
+
+<Row>
+<Column colLg={12}>
+
+<Tabs>
+
+<Tab label="Light mode">
+
+![Light mode example of data table rows generated by AI](images/usage-ai-presence-datatable-row-ai-l.png)
+
+</Tab>
+
+<Tab label="Dark mode">
+
+![Dark mode example of data table rows generated by AI](images/usage-ai-presence-datatable-row-ai-d.png)
+
+</Tab>
+
+</Tabs>
+
+</Column>
+</Row>
+
 ## Related
 
 ### Community extensions

diff --git a/src/pages/components/form/images/form-style-presence.png b/src/pages/components/form/images/form-style-presence.png
diff --git a/src/pages/components/form/images/form-usage-states-ai.png b/src/pages/components/form/images/form-usage-states-ai.png
diff --git a/src/pages/components/form/images/usage-ai-presence-form.png b/src/pages/components/form/images/usage-ai-presence-form.png
diff --git a/src/pages/components/form/style.mdx b/src/pages/components/form/style.mdx
@@ -6,6 +6,22 @@ description:
 tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 ---
 
+<PageDescription>
+
+The following page documents visual specifications such as color, typography,
+structure, and AI presence.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Color</AnchorLink>
+<AnchorLink>Typography</AnchorLink>
+<AnchorLink>Structure</AnchorLink>
+<AnchorLink>AI presence</AnchorLink>
+
+</AnchorLinks>
+
 ## Color
 
 Refer to the [text input](/components/text-input/usage),
@@ -83,3 +99,33 @@ content and layout of the design. On mobile, forms can only have one column.
 </div>
 
 <Caption>Structure and spacing measurements</Caption>
+
+## AI presence
+
+The following are the unique styles applied to the component when the AI slug is
+present. Unless specified, all other tokens in the component remain the same as
+the non-AI variant. The AI styling spec of individual components inside of the
+form can be found on their respective style tabs.
+
+More information about AI style elements is coming soon.
+
+| Element                    | Property         | Token / Size        |
+| -------------------------- | ---------------- | ------------------- |
+| Form:background            | background-color | `$layer` \*         |
+|                            | box-shadow       | `$ai-drop-shadow`   |
+|                            | inner-shadow     | `$ai-inner-shadow`  |
+| Linear gradient:background | start            | `$ai-aura-start-sm` |
+|                            | stop             | `$ai-aura-stop`     |
+| Linear gradient:border     | top              | `$ai-border-start`  |
+|                            | bottom           | `$ai-border-end`    |
+| AI Slug                    | size             | large               |
+
+<Row>
+<Column colLg={8}>
+
+![Form AI presence](images/form-style-presence.png)
+
+<Caption>Structure and spacing measurements for an AI form.</Caption>
+
+</Column>
+</Row>
diff --git a/src/pages/components/form/usage.mdx b/src/pages/components/form/usage.mdx
@@ -15,6 +15,15 @@ configure options.
 
 </PageDescription>
 
+<InlineNotification>
+
+Experimental slug is now available for
+[form](https://react.carbondesignsystem.com/?path=/story/experimental-unstable-slug-form--form-example).
+This addition changes the visual appearance of the component and introduces an
+AI explainability feature when AI is present in the component.
+
+</InlineNotification>
+
 <AnchorLinks>
 
 <AnchorLink>Live demo</AnchorLink>
@@ -23,6 +32,7 @@ configure options.
 <AnchorLink>Content</AnchorLink>
 <AnchorLink>Behaviors</AnchorLink>
 <AnchorLink>Additional guidance</AnchorLink>
+<AnchorLink>AI presence</AnchorLink>
 <AnchorLink>Related</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
@@ -388,6 +398,12 @@ form.
 
 </Tab>
 
+<Tab label="AI">
+
+![Examples fluid input states](images/form-usage-states-ai.png)
+
+</Tab>
+
 </Tabs>
 
 </Column>
@@ -407,6 +423,34 @@ pattern.
 | [Designing for longer forms](/patterns/forms-pattern/#designing-for-longer-forms) | Techniques to help make longer forms less overwhelming, including guidance for accordion and multistep forms.   |
 | [Form variants](/patterns/forms-pattern/#variants)                                | Forms may be presented as dedicated pages, side panels, or dialogs depending on the use case and the situation. |
 
+## AI presence
+
+Form has a modification that takes on the AI visual styling when AI is present
+in the form. The AI variants of a form function the same as the normal variants
+except for the addition of the AI slug, which is both a visual indicator and the
+trigger for the explainability popover.
+
+The AI presence in form can appear in two ways: broadly, over the whole form, or
+focused, just in certain parts of the form. When the entire form is styled for
+AI, it indicates to the user that AI is present in all aspects of the form. If
+only a limited amount of the form content is generated by AI, then only those
+components should receive the AI presence styling, not the entire form.
+
+More information about designing for AI guidelines is coming soon.
+
+<Row>
+<Column colLg={12}>
+
+![Example of form with full and compoment based AI presence](images/usage-ai-presence-form.png)
+
+<Caption>
+  Example of form with full AI presence on the left and compoment based AI
+  presence on the right.
+</Caption>
+
+</Column>
+</Row>
+
 ## Related
 
 <Row>

diff --git a/src/pages/components/modal/images/modal-style-presence.png b/src/pages/components/modal/images/modal-style-presence.png
diff --git a/src/pages/components/modal/images/modal-usage-style-presence.png b/src/pages/components/modal/images/modal-usage-style-presence.png