@workday/canvas-kit-docs 14.0.0-alpha.1149-next.0 → 14.0.0-alpha.1153-next.0

package/dist/es6/lib/docs.js

@@ -395717,7 +395717,9 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use brand or system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)."
+          }
         },
         {
           "kind": "property",
@@ -395802,7 +395804,9 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)."
+          }
         },
         {
           "kind": "property",
@@ -397281,7 +397285,9 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)."
+          }
         },
         {
           "kind": "property",
@@ -400052,7 +400058,9 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)."
+          }
         },
         {
           "kind": "property",
@@ -400171,7 +400179,10 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).",
+            "see": "| Old Token      | New Token      |\n|----------------|---------------------|\n| `commonColors.background`      | `system.color.bg.default`               |\n| `commonColors.backgroundAlt`   | `system.color.bg.alt.default`           |\n| `commonColors.focusOutline`    | `system.color.border.primary.default`   |\n| `commonColors.focusBackground` | `system.color.bg.primary.default`       |\n| `commonColors.hoverBackground` | `system.color.bg.alt.strong`            |\n| `commonColors.divider`         | `system.color.border.divider`           |"
+          }
         },
         {
           "kind": "property",
@@ -400188,7 +400199,10 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system depth tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).",
+            "see": "| Old Token      | New Token      |\n|----------------|---------------------|\n| `depth[0]`     | `{boxShadow: 'none'}`   |\n| `depth[1]`     | `{boxShadow: system.depth[1]}`   |\n| `depth[2]`     | `{boxShadow: system.depth[2]}`   |\n| `depth[3]`     | `{boxShadow: system.depth[3]}`   |\n| `depth[4]`     | `{boxShadow: system.depth[4]}`   |\n| `depth[5]`     | `{boxShadow: system.depth[5]}`   |\n| `depth[6]`     | `{boxShadow: system.depth[6]}`   |"
+          }
         },
         {
           "kind": "property",
@@ -400204,7 +400218,9 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)."
+          }
         },
         {
           "kind": "property",
@@ -400629,7 +400645,9 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)."
+          }
         },
         {
           "kind": "property",
@@ -400731,7 +400749,10 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).",
+            "see": "| Old Token      | New Token      |\n|----------------|---------------------|\n| `iconColors.active`   | `system.color.fg.primary.default`   |\n| `iconColors.disabled` | `system.color.fg.disabled.default`   |\n| `iconColors.hover`    | `system.color.fg.muted.stronger`   |\n| `iconColors.inverse`  | `system.color.fg.inverse`   |\n| `iconColors.standard` | `system.color.fg.muted.soft`   |"
+          }
         },
         {
           "kind": "property",
@@ -401125,7 +401146,10 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).",
+            "see": "| Old Token      | New Token      |\n|----------------|---------------------|\n| `inputColors.background` | `system.color.bg.default` |\n| `inputColors.border` | `system.color.border.input.default` |\n| `inputColors.placeholder` | `system.color.fg.muted.default` |\n| `inputColors.text` | `system.color.fg.default` |\n| `inputColors.icon` | `system.color.fg.muted.soft` |\n| `inputColors.iconHover` | `system.color.fg.muted.stronger` |\n| `inputColors.selectionControlFill` | `system.color.bg.primary.default` |\n| `inputColors.hoverBorder` | `system.color.border.input.strong` |\n| `inputColors.focusBorder` | `system.color.border.primary.default` |\n| `inputColors.disabled.background` | `system.color.bg.alt.softer` |\n| `inputColors.disabled.border` | `system.color.border.input.disabled` |\n| `inputColors.disabled.text` | `system.color.fg.disabled` |\n| `inputColors.disabled.icon` | `system.color.fg.disabled` |\n| `inputColors.error.border` | `system.color.border.critical.default` |\n| `inputColors.error.message` | `base.blackPepper100` |\n| `inputColors.error.icon` | `system.color.fg.critical.default` |\n| `inputColors.alert.border` | `system.color.border.caution.default` |\n| `inputColors.alert.message` | `base.blackPepper100` |\n| `inputColors.alert.icon` | `base.cantaloupe500` |"
+          }
         },
         {
           "kind": "property",
@@ -401141,7 +401165,9 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs)."
+          }
         },
         {
           "kind": "property",
@@ -401158,7 +401184,10 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system space tokens from `@workday/canvas-tokens-web` instead. Check new values column for the new tokens. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).",
+            "example": "```ts\n// before\nimport { space } from '@workday/canvas-kit-react/tokens';\nconst space = space.zero;\n\n// now\nimport { system } from '@workday/canvas-tokens-web';\nimport { cssVar } from '@workday/canvas-kit-styling';\nconst space = cssVar(system.space.zero);\n```"
+          }
         },
         {
           "kind": "property",
@@ -401243,7 +401272,10 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).",
+            "see": "| Old Property            | Tokens for foreground (text and icons)     | Tokens for border                          |\n|-------------------------|-------------------------------------|---------------------------------------|\n| `statusColors.active`   | `system.color.fg.primary.default`   | `system.color.border.primary.default` |\n| `statusColors.success`  | `system.color.fg.success.default`   | none                                  |\n| `statusColors.warning`  | `system.color.fg.caution.default`   | `system.color.border.caution.default` |\n| `statusColors.error`    | `system.color.fg.critical.default`  | `system.color.border.critical.default`|"
+          }
         },
         {
           "kind": "property",
@@ -401260,7 +401292,11 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system type tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).",
+            "see": "{@link \n}\n for values mapping table",
+            "example": "```ts\n// before\nimport { type } from '@workday/canvas-kit-react/tokens';\nconst styles = css({\n  ...type.levels.body.large,\n  fontWeight: type.properties.fontWeights.bold,\n  color: type.variants.error,\n})\n\n// now\nimport { system } from '@workday/canvas-tokens-web';\nimport { createStyles } from '@workday/canvas-kit-styling';\nconst styles = createStyles({\n  ...system.type.body.large,\n  fontWeight: system.fontWeight.bold,\n  color: system.color.fg.critical.default,\n})\n```"
+          }
         },
         {
           "kind": "property",
@@ -401413,7 +401449,10 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
               "filePath": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/index.ts"
             }
           ],
-          "tags": {}
+          "tags": {
+            "deprecated": "Use system color tokens from `@workday/canvas-tokens-web` instead. View Docs [here](https://workday.github.io/canvas-tokens/?path=/docs/docs-getting-started--docs).",
+            "see": "| Old Property                        | Tokens for text                   |\n|-------------------------------------|-----------------------------------|\n| `typeColors.body`                   | `system.color.fg.default`         |\n| `typeColors.heading`                | `system.color.fg.strong`          |\n| `typeColors.hint`                   | `system.color.fg.muted.default`   |\n| `typeColors.inverse`                | `system.color.fg.inverse`         |\n| `typeColors.label`                  | `system.color.fg.default`         |\n| `typeColors.link`                   | `system.color.fg.primary.default` |\n| `typeColors.selectHighlight`        | `system.color.fg.primary.default` |\n| `typeColors.selectHighlightInverse` | `system.color.fg.inverse`         |"
+          }
         }
       ]
     }
@@ -403229,7 +403268,7 @@ export const docs = (typeof window !== 'undefined' && window.__docs) ||
   {
     "name": "space",
     "fileName": "/home/runner/work/canvas-kit/canvas-kit/modules/react/tokens/lib/space.ts",
-    "description": "An object of space keys and rem values (strings)\n\nBelow is a table to show the equivalent values from `px` to `rem`.\nThis is based on the default browser font size which is `16px`.\n\n| px Value  | rem Value | space token |\n| --------- | --------- | ----------- |\n| 0         | 0         | zero        |\n| 4px       | 0.25rem   | xxxs        |\n| 8px       | 0.5rem    | xxs         |\n| 12px      | 0.75rem   | xs          |\n| 16px      | 1rem      | s           |\n| 24px      | 1.5rem    | m           |\n| 32px      | 2rem      | l           |\n| 40px      | 2.5rem    | xl          |\n| 64px      | 4rem      | xxl         |\n| 80px      | 5rem      | xxxl        |",
+    "description": "An object of space keys and rem values (strings)\n\nBelow is a table to show the equivalent values from `px` to `rem`.\nThis is based on the default browser font size which is `16px`.\n\n| px Value  | rem Value | space token | new token |\n| --------- | --------- | ----------- | --------- |\n| 0         | 0         | zero        | `system.space.zero` |\n| 4px       | 0.25rem   | xxxs        | `system.space.x1` |\n| 8px       | 0.5rem    | xxs         | `system.space.x2` |\n| 12px      | 0.75rem   | xs          | `system.space.x3` |\n| 16px      | 1rem      | s           | `system.space.x4` |\n| 24px      | 1.5rem    | m           | `system.space.x6` |\n| 32px      | 2rem      | l           | `system.space.x8` |\n| 40px      | 2.5rem    | xl          | `system.space.x10` |\n| 64px      | 4rem      | xxl         | `system.space.x16` |\n| 80px      | 5rem      | xxxl        | `system.space.x20` |",
     "declarations": [
       {
         "name": "space",

package/dist/es6/lib/stackblitzFiles/packageJSONFile.js

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "13.1.4",
-    "@workday/canvas-kit-preview-react": "13.1.4",
-    "@workday/canvas-kit-react": "13.1.4",
-    "@workday/canvas-kit-react-fonts": "^13.1.4",
-    "@workday/canvas-kit-styling": "13.1.4",
+    "@workday/canvas-kit-labs-react": "13.1.5",
+    "@workday/canvas-kit-preview-react": "13.1.5",
+    "@workday/canvas-kit-react": "13.1.5",
+    "@workday/canvas-kit-react-fonts": "^13.1.5",
+    "@workday/canvas-kit-styling": "13.1.5",
     "@workday/canvas-system-icons-web": "3.0.22",
     "@workday/canvas-tokens-web": "2.0.0"
   },

package/dist/es6/lib/stackblitzFiles/packageJSONFile.ts

@@ -18,11 +18,11 @@ export const packageJSONFile = `{
     "@emotion/react": "11.11.4",
     "@types/react": "18.2.60",
     "@types/react-dom": "18.2.19",
-    "@workday/canvas-kit-labs-react": "13.1.4",
-    "@workday/canvas-kit-preview-react": "13.1.4",
-    "@workday/canvas-kit-react": "13.1.4",
-    "@workday/canvas-kit-react-fonts": "^13.1.4",
-    "@workday/canvas-kit-styling": "13.1.4",
+    "@workday/canvas-kit-labs-react": "13.1.5",
+    "@workday/canvas-kit-preview-react": "13.1.5",
+    "@workday/canvas-kit-react": "13.1.5",
+    "@workday/canvas-kit-react-fonts": "^13.1.5",
+    "@workday/canvas-kit-styling": "13.1.5",
     "@workday/canvas-system-icons-web": "3.0.22",
     "@workday/canvas-tokens-web": "2.0.0"
   },

package/dist/mdx/styling/mdx/CreateStyles.mdx

@@ -0,0 +1,111 @@
+import {ExampleCodeBlock} from '@workday/canvas-kit-docs';
+import {InformationHighlight} from '@workday/canvas-kit-preview-react/information-highlight';
+import {system} from '@workday/canvas-tokens-web'
+
+import CreateStyles from './examples/CreateStyles';
+
+
+# Create Styles
+
+The primary utility function is the `createStyles` function. It makes a call to the `css` function
+from `@emotion/css`. Emotion still does most of the heavy lifting by handling the serialization,
+hashing, caching, and style injection.
+
+## Basic Example
+
+In this example, the HTML will look like:
+
+```html
+<div class="css-m39zwu"></div>
+```
+
+The CSS will look like this:
+
+```css
+.css-m39zwu {
+  background: var(--cnvs-sys-color-bg-primary-default);
+  color: var(--cnvs-sys-color-text-inverse);
+}
+```
+<InformationHighlight className="sb-unstyled" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading> Note</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		The `createStyles` function handles wrapping our Tokens in `var(--${token})`.
+	</InformationHighlight.Body>
+</InformationHighlight>
+
+We're using `className` for simplicity here.
+
+<ExampleCodeBlock code={CreateStyles} />
+
+<InformationHighlight className="sb-unstyled" variant="caution" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading> Caution: Performance Hit</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		Do not inline the call to `createStyles` in the render function of a component. This will cause performance issues as a new style is inserted into the browser on every render.
+	</InformationHighlight.Body>
+</InformationHighlight>
+
+```tsx
+// Bad example (inside render function)
+import {system} from '@workday/canvas-tokens-webs';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+function MyComponent() {
+  const styles = createStyles({color: system.color.static.red.default}); // Don't do this
+  return <PrimaryButton className={createStyles({color: system.color.static.red.default})}>Text</PrimaryButton>;
+}
+```
+
+## When to Use `createStyles`
+
+`createStyles` is a great way to generate static styles when styling our components that don't rely
+on dynamic styles. Use `createStyles` if you want to create re useable styles or need to apply
+simple style overrides to our components.
+
+## When to Use Something Else
+
+You should use [stencils](/docs/styling-getting-started-stencils--docs) when styling our components
+that have complex styles and dynamic properties.
+
+## Proper Usage
+
+```tsx
+// Bad example (inside render function)
+import {system} from '@workday/canvas-tokens-webs';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+function MyComponent() {
+  const styles = createStyles({color: system.color.static.red.default}); // Don't do this
+  return <PrimaryButton cs={styles}>Text</PrimaryButton>;
+}
+
+// Good example (outside render function)
+import {system} from '@workday/canvas-tokens-webs';
+import {PrimaryButton} from '@workday/canvas-kit-react/button';
+
+const styles = createStyles({color: system.color.static.red.default});
+
+function MyComponent() {
+  return <PrimaryButton cs={styles}>Text</PrimaryButton>;
+}
+```
+
+<InformationHighlight className="sb-unstyled" cs={{marginBlock: system.space.x4,}}>
+	<InformationHighlight.Icon />
+	<InformationHighlight.Heading>Note</InformationHighlight.Heading>
+	<InformationHighlight.Body>
+		Most of our components support using the `cs` prop to apply the static styles. It merges everything together and applies `className` and `style` attributes to a React element
+	</InformationHighlight.Body>
+</InformationHighlight>
+
+
+
+## Performance Benefits
+
+`createStyles` is performant because:
+
+- Styles are statically evaluated when styles are defined outside the render function
+- No new StyleSheets are injected during render
+- It works well with the browser's selector cache

package/dist/mdx/styling/mdx/CustomizingStyles.mdx

@@ -0,0 +1,179 @@
+# How To Customize Styles
+
+There are multiple ways to customize styles for components within Canvas Kit. The approach you
+choose will depend on your use case. Ranging from some simple overrides to fully custom solutions,
+here are the following options:
+
+- [Create Styles](#createstyles)
+- [Stencils](#stencils)
+
+## Create Styles
+
+### Using `createStyles` with `cs` prop
+
+Use `createStyles` in tandem with `cs` prop when you're overriding static styles and making small modifications to an
+existing Canvas Kit component like padding, color and flex properties. Take our `Text` component as
+an example.
+
+```tsx
+import {createStyles} from '@Workday/canvas-kit-styling';
+import {system} from '@Workday/canvas-tokens-web';
+import {Text} from '@Workday/canvas-kit-react/text';
+
+const uppercaseTextStyles = createStyles({
+  textTransform: 'uppercase',
+  margin: system.space.x4
+})
+//...
+<Text cs={uppercaseTextStyles}>My uppercased text</Text>;
+```
+
+> **Note:** `createStyles` handles wrapping our token variables in `var(--${token})`
+
+You can also apply styles created via `createStyles` via `className`.
+
+```tsx
+import {createStyles} from '@Workday/canvas-kit-styling';
+import {system} from '@Workday/canvas-tokens-web';
+import {Text} from '@Workday/canvas-kit-react/text';
+
+const uppercaseTextStyles = createStyles({
+  textTransform: 'uppercase',
+  margin: system.space.x4
+})
+//...
+<Text className={uppercaseTextStyles}>My uppercased text</Text>;
+```
+
+If you need to dynamically apply styles based on some state or prop, use [Stencils](#stencils) instead.
+
+
+## Stencils
+
+Stencils can be useful when applying dynamic styles or building your own reusable component.
+
+### Extending Stencils
+
+[Stencils](https://workday.github.io/canvas-kit/?path=/docs/styling-basics--create-stencil) help you
+organize the styling of reusable components into base styles, modifiers, and variables. The
+organization makes it more natural to produce static and clean CSS with optional extraction into CSS
+files.
+
+Stencils that define variables, modifiers and base styles can be extended to create your own
+reusable component using Canvas Kit styles.
+
+If we take `SystemIcon` component as an example, it defines `systemIconStencil` which defines styles
+for an icon. This stencil can be extended to build a custom icon component for your use case.
+
+**Before v11** you'd have to use `systemIconStyles` function to overwrite styles for an icon:
+
+```tsx
+// Before v11
+import {systemIconStyles} from '@workday/canvas-kit-react';
+import {space} from '@workday/canvas-kit-react/tokens'; // old tokens
+
+// old way of styling with Emotion styled
+const StyledNavIcon = styled('span')(({size, iconStyles}){
+  display: 'inline-flex',
+  pointerEvents: 'unset',
+  margin: `${space.xxxs} ${space.xxxs} 0 0`,
+  padding: '0',
+  'svg': {
+    ...iconStyles,
+    width: size,
+    height: size,
+  }
+});
+
+const NavIcon = ({iconColor, iconHover, iconBackground, iconBackgroundHover, icon, size}) => {
+  // old way of styling with systemIconStyles function
+  // systemIconStyles is deprecated in v11
+  const iconStyles = systemIconStyles({
+    fill: iconColor,
+    fillHover: iconHover,
+    background: iconBackground,
+    backgroundHover: iconBackgroundHover,
+  });
+
+  // insert icon function used by platform or any other functionality here
+
+  return (
+    <StyledNavIcon
+      icon={icon}
+      size={size}
+      iconStyles={iconStyles}
+    />
+  );
+};
+```
+
+**In v11** you'd extend `systemIconStencil` to reuse its styles:
+
+```tsx
+// v11
+import {createStencil} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+import {systemIconStencil} from '@workday/canvas-kit-react/icon';
+
+const navIconStencil = createStencil({
+  // We extend `systemIconStencil` to inherit it's base styles, modifiers and variables so that we can customize it
+  extends: systemIconStencil,
+  vars: {
+    // These variables support our styling iconHover and iconBackgroundHover
+    // they can be removed later and overwritten by `cs`.
+    // Also note the variables have no value. This allows for cascading styles.
+    fillHover: '',
+    backgroundHover: '',
+  },
+  base: ({fillHover, backgroundHover}) => ({
+    display: 'inline-flex',
+    pointerEvents: 'unset',
+    // instead of using our old tokens it's better to use our new system tokens
+    margin: `${system.space.x1} ${system.space.x1} 0 0`,
+    padding: '0',
+    '&:hover, &.hover': {
+      // systemIconStencil doesn't have hover specific variables
+      // so we reassigned color and backgroundColor variables using pseudo-selector
+      [systemIconStencil.vars.color]: fillHover,
+      [systemIconStencil.vars.backgroundColor]: backgroundHover,
+    },
+  }),
+});
+
+// Your reusable NavIcon component using Stencils
+const NavIcon = ({
+  iconColor,
+  iconHover,
+  iconBackground,
+  iconBackgroundHover,
+  icon,
+  size,
+  ...elemProps
+}) => {
+  // insert icon function used by platform or any other functionality here
+
+  return (
+    <span
+      icon={icon}
+      {...handleCsProp(
+        elemProps,
+        navIconStencil({
+          // Because we're extending systemIconStencil, it already has a size prop and applies size to the svg's width and height
+          // so we don't need to set these variables in our navIconStencil
+          size,
+          // systemIconStencil already has color (for icon fill) and backgroundColor variables
+          // so we assigned them to our prop values
+          color: iconColor,
+          backgroundColor: iconBackground,
+          fillHover: iconHover,
+          backgroundHover: iconBackgroundHover,
+        })
+      )}
+    />
+  );
+};
+```
+
+Another example of Stencil extension and customization is our
+[CustomButton](https://workday.github.io/canvas-kit/?path=/story/components-buttons--custom-styles)
+example. This example highlights the power of inheritance that you get from extending stencils.