@workday/canvas-kit-docs 15.0.0-alpha.1303-next.0 → 15.0.0

package/dist/mdx/react/icon/Assets.mdx

@@ -1,35 +1,192 @@
-import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
-import SystemIconList from './examples/IconList';
-import AppletIconList from './examples/AppletIconList';
-import AccentIconList from './examples/AccentIconList';
-import Overview from './examples/Overview';
+import {ExampleCodeBlock, StorybookStatusIndicator} from '@workday/canvas-kit-docs';
+import {InformationHighlight} from '@workday/canvas-kit-react/information-highlight';
+import ExpressiveBasic from './examples/ExpressiveBasic';
+import ExpressiveCustomStyles from './examples/ExpressiveCustomStyles';
+import SVGBasic from './examples/SVGBasic';
+import SystemBasic from './examples/SystemBasic';
+import SystemCircleBasic from './examples/SystemCircleBasic';
+import SystemCustomStyles from './examples/SystemCustomStyles';
 
 
 # Assets
 
-Assets are graphics which help communicate meaning or highlight areas of interaction to our users.
-These may be presented individually or as part of a group with related information in components and
-patterns.
+Assets are graphics used to communicate meaning or highlight areas of interaction within user
+interfaces. They enhance usability, reinforce metaphors, and bring clarity to components and
+patterns. Assets may be presented individually or grouped with related information in components.
 
-<ExampleCodeBlock code={Overview} />
+## Types of Assets
 
-## Accent Icon List
+Assets in the Canvas design system are organized into two primary types:
+
+- **System Icons:** Utility icons intended for use in UI actions and functional controls.
+- **Expressive Icons:** Decorative icons used to add additional context.
+
+⚠️ Deprecated:
+
+> **Note:** These asset types are now replaced by [Expressive Icon components](#expressive-icons)
+> for enhanced flexibility and consistency.
+
+- **Accent Icons:** larger secondary icons used to add visual interest and delight to by
+  communicating the overall tone and meaning of a page.
+- **Applet Icons:** convey entry points, categories of actions, or information sources on the
+  Workday homepage.
+
+## System Icons
+
+System Icons are small symbols used to convey simple actions and functions. They are the most common
+icons encountered in products and help communicate metaphors at a glance.
+
+For detailed documentation, refer to the
+[System Icon Docs](https://canvas.workdaydesign.com/styles/assets/system-icons).
+
+### Install
+
+To use System Icons, install the following packages:
+
+```sh
+npm install @workday/canvas-kit-react @workday/canvas-system-icons-web
+```
+
+### System Icon Component
+
+<ExampleCodeBlock code={SystemBasic} />
+
+<br />
+
+**Props**
+
+| Prop                  | Type                                            | Description                                                                                                                                                                                                                                 |
+| --------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`icon` (required)** | `CanvasSystemIcon`                              | The icon asset from `@workday/canvas-system-icons-web`.                                                                                                                                                                                     |
+| `color`               | string                                          | Sets the main icon’s (fill and accent layers) color.                                                                                                                                                                                        |
+| `accent`              | string                                          | Accent layer color for the system icon.                                                                                                                                                                                                     |
+| `inverse`             | boolean                                         | If set to `true`, the icon will be displayed in the inverse variant.                                                                                                                                                                        |
+| `size`                | `'xxs'`, `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'` | The size of the icon. Must match one of the allowed token sizes. For custom sizes, use stencil variable `systemIconStencil.vars.size` with the `cs` prop (see Custom Styles example).                                                       |
+| `shouldMirror`        | boolean                                         | If set to `true`, transforms the SVG's x-axis to mirror the graphic. Use if you want to always mirror the icon regardless of content direction. If the SVG should mirror only in a right-to-left language, use `shouldMirrorInRTL` instead. |
+| `shouldMirrorInRTL`   | boolean                                         | If set to `true`, transforms the SVG's x-axis to mirror the graphic when the content direction is `rtl`. This indicates the icon should be mirrored in right-to-left languages.                                                             |
+
+#### Custom Styles
+
+<ExampleCodeBlock code={SystemCustomStyles} />
+
+<br />
+
+### System Icon Circle Component
+
+Provides a circular background for icons with configurable color and contrast.
+
+> **Note:** If you need to define custom colors, set both `background` and `color` props to ensure
+> proper contrast.
+
+| Prop                  | Type               | Description                                                                                                                                                                                                                               |
+| --------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`icon` (required)** | `CanvasSystemIcon` | The icon asset from `@workday/canvas-system-icons-web`.                                                                                                                                                                                   |
+| `color`               | string             | Sets the icon color.                                                                                                                                                                                                                      |
+| `background`          | string             | Sets the background color of the icon circle wrapper.                                                                                                                                                                                     |
+| `inverse`             | boolean            | If set to `true`, the icon will be displayed in the inverse variant.                                                                                                                                                                      |
+| `size`                | string, number     | The size of the icon circle wrapper. Can use any valid value (token or px/rem) as a string or number.                                                                                                                                     |
+| `shouldMirror`        | boolean            | If set to `true`, transforms the SVG's x-axis to mirror the graphic. Use if you want to always mirror the icon regardless of content direction. If the SVG should mirror only in right-to-left language, use `shouldMirrorInRTL` instead. |
+| `shouldMirrorInRTL`   | boolean            | If set to `true`, transforms the SVG's x-axis to mirror the graphic when the content direction is `rtl`.                                                                                                                                  |
+
+<ExampleCodeBlock code={SystemCircleBasic} />
+
+<br />
+
+## Expressive Icons
+
+Expressive Icons are designed for decorative or illustrative purposes, bringing extra visual
+interest and meaning to the UI beyond functional system icons.
+
+### Install
+
+To use Expressive Icons, install the following packages:
+
+```sh
+npm install @workday/canvas-kit-react @workday/canvas-expressive-icons-web
+```
+
+### Expressive Icon Component
+
+<ExampleCodeBlock code={ExpressiveBasic} />
+
+<br />
+
+| Prop                  | Type                                   | Description                                                               |
+| --------------------- | -------------------------------------- | ------------------------------------------------------------------------- |
+| **`icon` (required)** | `CanvasExpressiveIcon`                 | The icon asset from `@workday/canvas-expressive-icons-web`.               |
+| `color`               | string                                 | Sets the icon outline main color.                                         |
+| `accent`              | string                                 | Sets the icon accent color for the accent layer (`wd-icon-accent`).       |
+| `size`                | `'xs'`, `'sm'`, `'md'`, `'lg'`, `'xl'` | The size of the icon. You can use any of the available token size values. |
+
+#### Custom Styles
+
+<ExampleCodeBlock code={ExpressiveCustomStyles} />
+
+<br />
+
+## Accent Icon <StorybookStatusIndicator type="deprecated" />
+
+<InformationHighlight className="sb-unstyled" variant="caution" cs={{p: {marginBlock: 0}}}>
+  <InformationHighlight.Icon />
+  <InformationHighlight.Body>
+    `AccentIcon` in main has been deprecated and will be removed in a future major version. Please
+    use [ExpressiveIcon](https://canvas.workdaydesign.com/styles/assets/expressive-icons) instead.
+  </InformationHighlight.Body>
+</InformationHighlight>
 
 Accent Icons add clarity, and visual interest, they bring delight to the experience by communicating
 the overall tone and meaning of a page.
 
-<ExampleCodeBlock code={AccentIconList} />
+### Install
+
+To use Accent Icons, install the following packages:
+
+```sh
+npm install @workday/canvas-kit-react @workday/canvas-accent-icons-web
+```
+
+### Usage
+
+```jsx
+import {apiIcon} from '@workday/canvas-accent-icons-web';
+
+<AccentIcon icon={apiIcon} />;
+```
 
-## Applet Icon List
+## Applet Icon <StorybookStatusIndicator type="deprecated" />
+
+<InformationHighlight className="sb-unstyled" variant="caution" cs={{p: {marginBlock: 0}}}>
+  <InformationHighlight.Icon />
+  <InformationHighlight.Body>
+    `AppletIcon` in main has been deprecated and will be removed in a future major version. Please
+    use [ExpressiveIcon](https://canvas.workdaydesign.com/styles/assets/expressive-icons) instead.
+  </InformationHighlight.Body>
+</InformationHighlight>
 
 Applet Icons convey entry points, categories of actions, or information sources on the Workday
 homepage.
 
-<ExampleCodeBlock code={AppletIconList} />
+### Install
+
+To use Applet Icons, install the following packages:
+
+```sh
+npm install @workday/canvas-kit-react @workday/canvas-applet-icons-web
+```
+
+### Usage
+
+```jsx
+import {gigsIcon} from '@workday/canvas-applet-icons-web';
+
+<AppletIcon icon={gigsIcon} />;
+```
 
-## System Icon List
+## Svg Component
 
-System Icons are symbols used to convey simple actions and functions, they are the most common icons
-encountered in products and help communicate metaphors at a glance.
+The `Svg` component enables you to render SVG-based icons from Canvas assets with complete control
+over their appearance and behavior. Use this component for advanced customization such as applying
+unique styles, implementing animations, or composing icons in complex ways not supported by
+higher-level icon components.
 
-<ExampleCodeBlock code={SystemIconList} />
+<ExampleCodeBlock code={SVGBasic} />

package/dist/mdx/react/icon/examples/AccentIconList.tsx

@@ -1,7 +1,8 @@
 import React from 'react';
+
 import * as CanvasAccenttIcons from '@workday/canvas-accent-icons-web';
-import {Box, Flex} from '@workday/canvas-kit-react/layout';
 import {AccentIcon} from '@workday/canvas-kit-react/icon';
+import {Box, Flex} from '@workday/canvas-kit-react/layout';
 import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {createStyles, px2rem} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
@@ -14,7 +15,7 @@ const styleOverrides = {
   parentContainer: createStyles({
     flexDirection: 'column',
     alignItems: 'center',
-    gap: system.space.x6,
+    gap: system.gap.lg,
   }),
   iconGroupContainer: createStyles({
     flexWrap: 'wrap',
@@ -23,8 +24,8 @@ const styleOverrides = {
     alignItems: 'center',
     width: `max(${px2rem(320)},20%)`,
     flexDirection: 'row',
-    gap: system.space.x3,
-    padding: system.space.x3,
+    gap: px2rem(12),
+    padding: system.padding.sm,
   }),
 };
 

package/dist/mdx/react/icon/examples/AppletIconList.tsx

@@ -1,7 +1,8 @@
 import React from 'react';
+
 import * as CanvasAppletIcons from '@workday/canvas-applet-icons-web';
-import {Box, Flex} from '@workday/canvas-kit-react/layout';
 import {AppletIcon} from '@workday/canvas-kit-react/icon';
+import {Box, Flex} from '@workday/canvas-kit-react/layout';
 import {TextInput} from '@workday/canvas-kit-react/text-input';
 import {createStyles, px2rem} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
@@ -14,7 +15,7 @@ const styleOverrides = {
   parentContainer: createStyles({
     flexDirection: 'column',
     alignItems: 'center',
-    gap: system.space.x6,
+    gap: system.gap.lg,
   }),
   iconGroupContainer: createStyles({
     flexWrap: 'wrap',
@@ -23,8 +24,8 @@ const styleOverrides = {
     alignItems: 'center',
     width: `max(${px2rem(320)},20%)`,
     flexDirection: 'row',
-    gap: system.space.x3,
-    padding: system.space.x3,
+    gap: px2rem(12),
+    padding: system.padding.sm,
   }),
 };
 

package/dist/mdx/react/icon/examples/ExpressiveBasic.tsx

@@ -0,0 +1,41 @@
+import {searchIcon} from '@workday/canvas-expressive-icons-web';
+import {ExpressiveIcon} from '@workday/canvas-kit-react/icon';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {base, system} from '@workday/canvas-tokens-web';
+
+const styles = createStyles({
+  display: 'flex',
+  gap: system.gap.md,
+  margin: system.gap.md,
+  alignItems: 'center',
+  '&>span': {
+    height: 'fit-content',
+  },
+});
+
+export default () => {
+  return (
+    <>
+      <div className={styles}>
+        <ExpressiveIcon icon={searchIcon} size="xl" />
+        <ExpressiveIcon icon={searchIcon} size="lg" />
+        <ExpressiveIcon icon={searchIcon} size="md" />
+        <ExpressiveIcon icon={searchIcon} size="sm" />
+        <ExpressiveIcon icon={searchIcon} size="xs" />
+      </div>
+      <div className={styles}>
+        <ExpressiveIcon icon={searchIcon} />
+        <ExpressiveIcon
+          icon={searchIcon}
+          color={system.color.fg.success.default}
+          accent={base.greenA200}
+        />
+        <ExpressiveIcon
+          icon={searchIcon}
+          color={system.color.fg.warning.default}
+          accent={base.amberA200}
+        />
+      </div>
+    </>
+  );
+};

package/dist/mdx/react/icon/examples/ExpressiveCustomStyles.tsx

@@ -0,0 +1,54 @@
+import {searchIcon} from '@workday/canvas-expressive-icons-web';
+import {ExpressiveIcon, expressiveIconStencil} from '@workday/canvas-kit-react/icon';
+import {Text} from '@workday/canvas-kit-react/text';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = createStyles({
+  display: 'flex',
+  gap: system.gap.md,
+  margin: system.gap.md,
+  alignItems: 'center',
+  '&>span': {
+    height: 'fit-content',
+  },
+});
+
+export default () => {
+  return (
+    <>
+      <div className={styles}>
+        <Text>Icon with custom hover styles</Text>
+        <ExpressiveIcon
+          icon={searchIcon}
+          cs={{
+            '&:hover .wd-icon-fill': {
+              fill: system.color.fg.success.default,
+            },
+            '&:hover .wd-icon-accent': {
+              fill: system.color.surface.success.strong,
+            },
+          }}
+        />
+      </div>
+      <div className={styles}>
+        <Text>Using stencil variables</Text>
+        <ExpressiveIcon
+          icon={searchIcon}
+          cs={{
+            [expressiveIconStencil.vars.color]: system.color.fg.success.default,
+            [expressiveIconStencil.vars.accentColor]: system.color.surface.success.strong,
+            [expressiveIconStencil.vars.size]: system.size.lg,
+
+            '&:hover .wd-icon-fill': {
+              [expressiveIconStencil.vars.color]: system.color.fg.warning.strong,
+            },
+            '&:hover .wd-icon-accent': {
+              [expressiveIconStencil.vars.accentColor]: system.color.surface.warning.strong,
+            },
+          }}
+        />
+      </div>
+    </>
+  );
+};

package/dist/mdx/react/icon/examples/{IconList.tsx → ExpressiveIconList.tsx}

@@ -1,20 +1,21 @@
 import React from 'react';
-import * as CanvasIcons from '@workday/canvas-system-icons-web';
-import {Box, Flex} from '@workday/canvas-kit-react/layout';
-import {SystemIcon} from '@workday/canvas-kit-react/icon';
+
+import * as CanvasIcons from '@workday/canvas-expressive-icons-web';
+import {ExpressiveIcon} from '@workday/canvas-kit-react/icon';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {Subtext} from '@workday/canvas-kit-react/text';
 import {TextInput} from '@workday/canvas-kit-react/text-input';
-import {createStyles} from '@workday/canvas-kit-styling';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
 import {system} from '@workday/canvas-tokens-web';
 
 const ImportedIcons = Object.keys(CanvasIcons);
-
-const allIcons = ImportedIcons.filter(icon => icon !== 'CanvasSystemIcons');
+const allIcons = ImportedIcons.filter(icon => !icon.startsWith('Canvas') && icon.endsWith('Icon'));
 
 const styleOverrides = {
   parentContainer: createStyles({
     flexDirection: 'column',
     alignItems: 'center',
-    gap: system.space.x6,
+    gap: system.gap.lg,
   }),
   firstChildContainer: createStyles({
     flexWrap: 'wrap',
@@ -23,8 +24,14 @@ const styleOverrides = {
     alignItems: 'center',
     width: `max(320px,20%)`,
     flexDirection: 'row',
-    gap: system.space.x3,
-    padding: system.space.x3,
+    gap: px2rem(12),
+    padding: system.padding.sm,
+  }),
+  text: createStyles({
+    fontFamily: system.fontFamily.mono,
+    padding: system.padding.xxs,
+    backgroundColor: system.color.surface.alt.default,
+    borderRadius: system.shape.sm,
   }),
 };
 
@@ -50,10 +57,10 @@ export default () => {
           .map((singleIcon, index) => {
             return (
               <Flex cs={styleOverrides.secondChildContainer} key={index}>
-                <Box>
-                  <SystemIcon icon={CanvasIcons[singleIcon]} />
-                </Box>
-                <Box>{singleIcon}</Box>
+                <ExpressiveIcon icon={CanvasIcons[singleIcon]} />
+                <Subtext as="code" size="large" cs={styleOverrides.text}>
+                  {singleIcon}
+                </Subtext>
               </Flex>
             );
           })}

package/dist/mdx/react/icon/examples/SVGBasic.tsx

@@ -0,0 +1,31 @@
+import {Svg} from '@workday/canvas-kit-react/icon';
+import {createStencil} from '@workday/canvas-kit-styling';
+import {CanvasIconTypes, imageIcon} from '@workday/canvas-system-icons-web';
+import {system} from '@workday/canvas-tokens-web';
+
+const svgStencil = createStencil({
+  vars: {
+    size: '',
+  },
+  base: ({size}) => ({
+    svg: {
+      width: size,
+      height: size,
+    },
+    '.wd-icon-fill': {
+      fill: system.color.fg.success.default,
+    },
+    '.wd-icon-accent': {
+      fill: system.color.fg.success.strong,
+    },
+    '.wd-icon-background': {
+      fill: system.color.surface.success.default,
+    },
+  }),
+});
+
+export default () => {
+  return (
+    <Svg src={imageIcon} type={CanvasIconTypes.System} cs={svgStencil({size: system.size.xs})} />
+  );
+};

package/dist/mdx/react/icon/examples/SystemBasic.tsx

@@ -0,0 +1,44 @@
+import {SystemIcon} from '@workday/canvas-kit-react/icon';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {imageIcon} from '@workday/canvas-system-icons-web';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = createStyles({
+  display: 'flex',
+  gap: system.gap.md,
+  margin: system.gap.md,
+  alignItems: 'center',
+  '&>span': {
+    height: 'fit-content',
+  },
+});
+
+export default () => {
+  return (
+    <>
+      <div className={styles}>
+        <SystemIcon icon={imageIcon} size="xl" />
+        <SystemIcon icon={imageIcon} size="lg" />
+        <SystemIcon icon={imageIcon} size="md" />
+        <SystemIcon icon={imageIcon} size="sm" />
+        <SystemIcon icon={imageIcon} size="xs" />
+        <SystemIcon icon={imageIcon} size="xxs" />
+      </div>
+      <div className={styles}>
+        <SystemIcon icon={imageIcon} />
+        <SystemIcon icon={imageIcon} color={system.color.fg.success.default} />
+        <SystemIcon
+          icon={imageIcon}
+          color={system.color.fg.success.default}
+          accent={system.color.fg.success.strong}
+        />
+        <SystemIcon
+          icon={imageIcon}
+          color={system.color.fg.warning.default}
+          accent={system.color.fg.warning.strong}
+          background={system.color.surface.warning.default}
+        />
+      </div>
+    </>
+  );
+};

package/dist/mdx/react/icon/examples/SystemCircleBasic.tsx

@@ -0,0 +1,34 @@
+import {SystemIconCircle, systemIconCircleStencil} from '@workday/canvas-kit-react/icon';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {imageIcon} from '@workday/canvas-system-icons-web';
+import {base, system} from '@workday/canvas-tokens-web';
+
+const styles = createStyles({
+  display: 'flex',
+  gap: system.gap.md,
+  margin: system.gap.md,
+  alignItems: 'center',
+  '&>span': {
+    height: 'fit-content',
+  },
+});
+
+export default () => {
+  return (
+    <div className={styles}>
+      <SystemIconCircle icon={imageIcon} />
+      <SystemIconCircle icon={imageIcon} inverse={true} />
+      <SystemIconCircle
+        icon={imageIcon}
+        background={system.color.fg.success.default}
+        color={system.color.fg.inverse}
+      />
+      <SystemIconCircle icon={imageIcon} size={base.size1200} />
+      <SystemIconCircle
+        icon={imageIcon}
+        size={base.size1200}
+        cs={{[systemIconCircleStencil.vars.size]: base.size1000}}
+      />
+    </div>
+  );
+};

package/dist/mdx/react/icon/examples/SystemCustomStyles.tsx

@@ -0,0 +1,62 @@
+import {SystemIcon, systemIconStencil} from '@workday/canvas-kit-react/icon';
+import {Text} from '@workday/canvas-kit-react/text';
+import {createStyles} from '@workday/canvas-kit-styling';
+import {imageIcon} from '@workday/canvas-system-icons-web';
+import {system} from '@workday/canvas-tokens-web';
+
+const styles = createStyles({
+  display: 'flex',
+  gap: system.gap.md,
+  margin: system.gap.md,
+  alignItems: 'center',
+  '&>span': {
+    height: 'fit-content',
+  },
+});
+
+export default () => {
+  return (
+    <>
+      <div className={styles}>
+        <Text>Icon with custom hover styles</Text>
+        <SystemIcon
+          icon={imageIcon}
+          cs={{
+            '&:hover .wd-icon-fill': {
+              fill: system.color.fg.success.default,
+            },
+            '&:hover .wd-icon-accent': {
+              fill: system.color.fg.success.strong,
+            },
+            '&:hover .wd-icon-background': {
+              fill: system.color.surface.success.default,
+            },
+          }}
+        />
+      </div>
+      <div className={styles}>
+        <Text>Using stencil variables</Text>
+        <SystemIcon
+          icon={imageIcon}
+          cs={{
+            [systemIconStencil.vars.color]: system.color.fg.success.default,
+            [systemIconStencil.vars.accentColor]: system.color.fg.success.strong,
+            [systemIconStencil.vars.backgroundColor]: system.color.surface.success.default,
+            // No `component.systemIcon.size.*` token for `40px`. Keeping `size` here for now.
+            [systemIconStencil.vars.size]: system.size.lg,
+
+            '&:hover .wd-icon-fill': {
+              [systemIconStencil.vars.color]: system.color.fg.warning.strong,
+            },
+            '&:hover .wd-icon-accent': {
+              [systemIconStencil.vars.accentColor]: system.color.fg.warning.default,
+            },
+            '&:hover .wd-icon-background': {
+              [systemIconStencil.vars.backgroundColor]: system.color.surface.warning.default,
+            },
+          }}
+        />
+      </div>
+    </>
+  );
+};