@workday/canvas-kit-docs 12.3.1 → 12.3.3

package/dist/mdx/preview-react/side-panel/SidePanel.mdx

@@ -41,9 +41,12 @@ logic or styling for bidirecitonal support.
 
 ### Hidden Name
 
-`SidePanel` should always have an accessible label. Often this is the heading element with an `id`
-attribute. However, as seen in the example below, you can apply a `hidden` attribute to your label
-if you do not want it to be visible.
+`SidePanel` must always have an accessible label for both the HTML `<section>` container and the
+`ToggleButton`. The `labelProps` component must always be present in the DOM in order for the
+`panelProps` and `controlProps` component labels to be assigned properly. A `hidden` attribute can
+be applied to the `labelProps` component. In the example below, we are demonstrating the
+`AccessibleHide` component that relies on CSS properties to visually hide text for screen readers
+only.
 
 <ExampleCodeBlock code={HiddenName} />
 
@@ -60,6 +63,28 @@ used (this case is covered in the Examples section).
 Sometimes you'll want to control `SidePanel`'s' expand / collapse behavior from outside the
 component. In that case, you can use the `controlProps` supplied by the `useSidePanel` hook.
 
+#### Notes about accessibility
+
+The `controlProps` object delivers ARIA attributes to a component under the following assumptions:
+
+1. The control is an icon button that does not already have an accessible name
+2. The control appears at (or near) the top of the expandable content in the `SidePanel`
+
+Spreading the `controlProps` onto an external control can introduce serious accessibility issues:
+
+- `aria-labelledby` HTML `id` reference may become invalid when the SidePanel is collapsed, or when
+  the `labelProps` component isn't present in the DOM.
+- `aria-labelledby` will change the name of `controlProps` component to the title of the
+  `SidePanel`. (This may be undesirable. For example, the "Show Side Panel" button will be
+  overwritten with the "Tasks Panel" heading.)
+- `aria-expanded` won't make sense to screen reader users when the expanded `SidePanel` content
+  isn't logically following the control.
+- `aria-controls` is unsupported by screen readers and will not allow users to navigate to the
+  controlled content.
+
+In the following example, the `controlProps` click handler function is passed down to the
+`SecondaryButton` and a toggle state was added to the button using the `aria-pressed` property.
+
 <ExampleCodeBlock code={ExternalControl} />
 
 ### Right Origin

package/dist/mdx/preview-react/side-panel/examples/AlwaysOpen.tsx

@@ -1,35 +1,54 @@
 import * as React from 'react';
-import {styled} from '@workday/canvas-kit-react/common';
-import {space} from '@workday/canvas-kit-react/tokens';
 import {AccentIcon} from '@workday/canvas-kit-react/icon';
 import {rocketIcon} from '@workday/canvas-accent-icons-web';
 import {SidePanel, useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {Text} from '@workday/canvas-kit-react/text';
+import {Heading, Text} from '@workday/canvas-kit-react/text';
+import {base, system} from '@workday/canvas-tokens-web';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
 
-const StyledAccentIcon = styled(AccentIcon)({
-  marginRight: space.s,
-});
+const stylesOverride = {
+  accentIcon: createStyles({
+    marginRight: system.space.x4,
+  }),
+  pageContainer: createStyles({
+    gap: system.space.x4,
+    height: px2rem(320),
+  }),
+  panelContainer: createStyles({
+    alignItems: 'center',
+    paddingY: system.space.x4,
+    paddingX: system.space.x4,
+  }),
+  panelHeading: createStyles({
+    color: base.licorice500,
+  }),
+  mainContent: createStyles({
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexBasis: 'auto',
+    flex: 1,
+  }),
+};
 
 export default () => {
   const {panelProps, labelProps} = useSidePanel();
 
   return (
-    <Flex gap="s" height={320}>
+    <Flex cs={stylesOverride.pageContainer}>
       <SidePanel {...panelProps}>
-        <Flex alignItems="center" paddingY="s" paddingX="s">
-          <StyledAccentIcon icon={rocketIcon} />
-          <Text
-            as="h3"
-            typeLevel="body.large"
-            color="licorice500"
-            fontWeight="bold"
-            {...labelProps}
-          >
+        <Flex cs={stylesOverride.panelContainer}>
+          <AccentIcon icon={rocketIcon} cs={stylesOverride.accentIcon} />
+          <Heading size="small" cs={stylesOverride.panelHeading} {...labelProps}>
             Tasks Panel
-          </Text>
+          </Heading>
         </Flex>
       </SidePanel>
+      <Flex as="main" cs={stylesOverride.mainContent}>
+        <Text as="p" typeLevel="body.large">
+          This is the main content section.
+        </Text>
+      </Flex>
     </Flex>
   );
 };

package/dist/mdx/preview-react/side-panel/examples/Basic.tsx

@@ -6,54 +6,60 @@ import {
   SidePanelTransitionStates,
 } from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {Text} from '@workday/canvas-kit-react/text';
+import {Heading, Text} from '@workday/canvas-kit-react/text';
 import {CanvasProvider} from '@workday/canvas-kit-react/common';
 import {AccentIcon} from '@workday/canvas-kit-react/icon';
 import {rocketIcon} from '@workday/canvas-accent-icons-web';
-// local helper hook for setting content direction;
 import {useDirection} from './useDirection';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+import {system, base} from '@workday/canvas-tokens-web';
+
+const stylesOverride = {
+  viewPortContainer: createStyles({
+    height: px2rem(320),
+  }),
+  panel: createStyles({
+    alignItems: 'center',
+    paddingY: system.space.x4,
+    paddingX: system.space.x4,
+  }),
+  accentIcon: createStyles({
+    marginInlineEnd: system.space.x4,
+  }),
+  mainContent: createStyles({
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexDirection: 'column',
+    flex: 1,
+    flexBasis: 'auto',
+  }),
+};
 
 export default () => {
   const {direction, toggleDirection} = useDirection();
   const {expanded, panelProps, labelProps, controlProps} = useSidePanel();
-  const [panelState, setPanelState] = React.useState<SidePanelTransitionStates>(
-    expanded ? 'expanded' : 'collapsed'
-  );
-
-  const expandedContent = (
-    <Flex alignItems="center" paddingY="s" paddingX="s">
-      <Flex marginInlineEnd="s">
-        <AccentIcon icon={rocketIcon} />
-      </Flex>
-      <Text as="h3" typeLevel="body.large" color="licorice500" fontWeight="bold" {...labelProps}>
-        Tasks Panel
-      </Text>
-    </Flex>
-  );
 
   return (
     <CanvasProvider theme={{canvas: {direction}}}>
-      <Flex height={320}>
-        <SidePanel {...panelProps} onStateTransition={setPanelState}>
+      <Flex cs={stylesOverride.viewPortContainer}>
+        <SidePanel {...panelProps}>
           <SidePanel.ToggleButton {...controlProps} />
-          {panelState === 'expanded' ? (
-            expandedContent
-          ) : (
-            <Text hidden {...labelProps}>
+          <Flex cs={stylesOverride.panel}>
+            {expanded && (
+              <Flex cs={stylesOverride.accentIcon}>
+                <AccentIcon icon={rocketIcon} />
+              </Flex>
+            )}
+            <Heading size="small" {...labelProps} hidden={!expanded ? true : undefined}>
               Tasks Panel
-            </Text>
-          )}
+            </Heading>
+          </Flex>
         </SidePanel>
-        <Flex
-          as="main"
-          alignItems="center"
-          justifyContent="center"
-          flexDirection="column"
-          flex={1}
-          flexBasis="auto"
-        >
-          <p>Toggle the content direction</p>
-          <SecondaryButton onClick={toggleDirection} role="button">
+        <Flex as="main" cs={stylesOverride.mainContent}>
+          <Text as="p" typeLevel="body.large">
+            Toggle the content direction
+          </Text>
+          <SecondaryButton onClick={toggleDirection}>
             Set to {direction === 'ltr' ? 'Right-to-Left' : 'Left-to-Right'}
           </SecondaryButton>
         </Flex>

package/dist/mdx/preview-react/side-panel/examples/ExternalControl.tsx

@@ -5,9 +5,45 @@ import {
   SidePanelTransitionStates,
 } from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {Text} from '@workday/canvas-kit-react/text';
+import {Heading, Text} from '@workday/canvas-kit-react/text';
 import {SecondaryButton} from '@workday/canvas-kit-react/button';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+import {base, system} from '@workday/canvas-tokens-web';
 
+const stylesOverride = {
+  viewport: createStyles({
+    height: px2rem(320),
+  }),
+  panel: createStyles({
+    alignItems: 'center',
+    paddingY: system.space.x4,
+    paddingX: system.space.x4,
+  }),
+  panelHeading: createStyles({
+    color: base.licorice500,
+  }),
+  main: createStyles({
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexDirection: 'column',
+    flex: 1,
+    flexBasis: 'auto',
+  }),
+};
+
+/*
+ * NOTE TO DEV:
+ * Spreading the `controlProps` onto an external control creates serious accessibility issues.
+ * - `aria-labelledby` id reference is invalid when the SidePanel is collapsed
+ * - `aria-labelledby` will change the name of "Toggle Side Panel" button to "Tasks Panel"
+ * - `aria-expanded` won't make sense to screen reader users when the expanded SidePanel content isn't following the control
+ * - `aria-controls` is unsupported by screen readers and will not allow users to navigate to the controlled content
+ *
+ * SOLUTION:
+ * - Pass the `controlProps` click handler function down to the external control component.
+ * - Add a toggle state to Button components with `aria-pressed` for screen readers,
+ * - OR use a similar toggle input like Checkbox or Switch.
+ */
 export default () => {
   const {expanded, panelProps, labelProps, controlProps} = useSidePanel({initialExpanded: false});
   const [panelState, setPanelState] = React.useState<SidePanelTransitionStates>(
@@ -15,9 +51,8 @@ export default () => {
   );
 
   return (
-    <Flex height={320}>
+    <Flex cs={stylesOverride.viewport}>
       <SidePanel
-        as="aside"
         {...panelProps}
         onExpandedChange={expanded => {
           console.log(`expanded prop is: ${expanded ? 'true' : 'false'}`);
@@ -25,30 +60,19 @@ export default () => {
         onStateTransition={setPanelState}
       >
         {panelState === 'expanded' && (
-          <Flex alignItems="center" paddingY="s" paddingX="s">
-            <Text
-              as="h3"
-              typeLevel="body.large"
-              color="licorice500"
-              fontWeight="bold"
-              {...labelProps}
-            >
+          <Flex cs={stylesOverride.panel}>
+            <Heading size="small" cs={stylesOverride.panelHeading} {...labelProps}>
               Tasks Panel
-            </Text>
+            </Heading>
           </Flex>
         )}
       </SidePanel>
-      <Flex
-        as="main"
-        alignItems="center"
-        justifyContent="center"
-        flexDirection="column"
-        flex={1}
-        flexBasis="auto"
-      >
-        <p>Control the panel externally</p>
-        <SecondaryButton {...controlProps} role="button">
-          Toggle Side Panel
+      <Flex as="main" cs={stylesOverride.main}>
+        <Text as="p" typeLevel="body.large">
+          Control the panel externally
+        </Text>
+        <SecondaryButton onClick={controlProps.onClick} aria-pressed={expanded}>
+          Show Side Panel
         </SecondaryButton>
       </Flex>
     </Flex>

package/dist/mdx/preview-react/side-panel/examples/HiddenName.tsx

@@ -1,13 +1,29 @@
 import * as React from 'react';
 import {SidePanel, useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
+import {AccessibleHide} from '@workday/canvas-kit-react/common';
+import {Text} from '@workday/canvas-kit-react/text';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+
+const stylesOverride = {
+  viewport: createStyles({
+    height: px2rem(320),
+  }),
+  main: createStyles({
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexDirection: 'column',
+    flex: 1,
+    flexBasis: 'auto',
+  }),
+};
 
 export default () => {
   const {panelProps, labelProps, controlProps} = useSidePanel();
+
   return (
-    <Flex height={320}>
+    <Flex cs={stylesOverride.viewport}>
       <SidePanel
-        as="aside"
         {...panelProps}
         onExpandedChange={expanded => {
           console.log(`expanded prop is: ${expanded ? 'true' : 'false'}`);
@@ -17,10 +33,13 @@ export default () => {
         }}
       >
         <SidePanel.ToggleButton {...controlProps} />
-        <span hidden {...labelProps}>
-          Side Panel with a hidden label
-        </span>
+        <AccessibleHide {...labelProps}>Hidden Title</AccessibleHide>
       </SidePanel>
+      <Flex as="main" cs={stylesOverride.main}>
+        <Text as="p" typeLevel="body.large">
+          Side Panel with a hidden title text.
+        </Text>
+      </Flex>
     </Flex>
   );
 };

package/dist/mdx/preview-react/side-panel/examples/OnExpandedChange.tsx

@@ -1,6 +1,22 @@
 import * as React from 'react';
 import {Flex} from '@workday/canvas-kit-react/layout';
 import {SidePanel, useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
+import {Text} from '@workday/canvas-kit-react/text';
+import {AccessibleHide} from '@workday/canvas-kit-react/common';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+
+const stylesOverride = {
+  viewport: createStyles({
+    height: px2rem(320),
+  }),
+  main: createStyles({
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexDirection: 'column',
+    flex: 1,
+    flexBasis: 'auto',
+  }),
+};
 
 export default () => {
   const {expanded, panelProps, labelProps, controlProps} = useSidePanel();
@@ -10,15 +26,15 @@ export default () => {
   };
 
   return (
-    <Flex height={320}>
+    <Flex cs={stylesOverride.viewport}>
       <SidePanel {...panelProps} onExpandedChange={handleExpandedChange}>
         <SidePanel.ToggleButton {...controlProps} />
-        <span hidden {...labelProps}>
-          custom side panel
-        </span>
+        <AccessibleHide {...labelProps}>Hidden Title</AccessibleHide>
       </SidePanel>
-      <Flex as="main" alignItems="center" justifyContent="center" flex={1} flexBasis="auto">
-        <p>Side panel is {expanded ? 'expanded' : 'collapsed'}.</p>
+      <Flex as="main" cs={stylesOverride.main}>
+        <Text as="p" typeLevel="body.large">
+          Side panel is {expanded ? 'expanded' : 'collapsed'}.
+        </Text>
       </Flex>
     </Flex>
   );

package/dist/mdx/preview-react/side-panel/examples/OnStateTransition.tsx

@@ -5,27 +5,42 @@ import {
   useSidePanel,
   SidePanelTransitionStates,
 } from '@workday/canvas-kit-preview-react/side-panel';
+import {AccessibleHide} from '@workday/canvas-kit-react/common';
+import {Text} from '@workday/canvas-kit-react/text';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+
+const stylesOverride = {
+  viewport: createStyles({
+    height: px2rem(320),
+  }),
+  main: createStyles({
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexDirection: 'column',
+    flex: 1,
+    flexBasis: 'auto',
+  }),
+};
 
 export default () => {
   const {panelProps, labelProps, controlProps} = useSidePanel();
-  const [transitionState, setTransitionState] = React.useState<SidePanelTransitionStates>(
-    'expanded'
-  );
+  const [transitionState, setTransitionState] =
+    React.useState<SidePanelTransitionStates>('expanded');
 
   const handleStateTransition = (transition: SidePanelTransitionStates) => {
     setTransitionState(transition);
   };
 
   return (
-    <Flex height={320}>
+    <Flex cs={stylesOverride.viewport}>
       <SidePanel {...panelProps} onStateTransition={handleStateTransition}>
         <SidePanel.ToggleButton {...controlProps} />
-        <span hidden {...labelProps}>
-          custom side panel
-        </span>
+        <AccessibleHide {...labelProps}>Hidden Title</AccessibleHide>
       </SidePanel>
-      <Flex as="main" alignItems="center" justifyContent="center" flex={1} flexBasis="auto">
-        <p>Side panel is {transitionState}.</p>
+      <Flex as="main" cs={stylesOverride.main}>
+        <Text as="p" typeLevel="body.large">
+          Side panel is {transitionState}.
+        </Text>
       </Flex>
     </Flex>
   );

package/dist/mdx/preview-react/side-panel/examples/RightOrigin.tsx

@@ -1,45 +1,49 @@
 import * as React from 'react';
 import {SecondaryButton} from '@workday/canvas-kit-react/button';
-import {
-  SidePanel,
-  useSidePanel,
-  SidePanelTransitionStates,
-} from '@workday/canvas-kit-preview-react/side-panel';
+import {SidePanel, useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {Text} from '@workday/canvas-kit-react/text';
-import {CanvasProvider, styled} from '@workday/canvas-kit-react/common';
+import {Heading, Text} from '@workday/canvas-kit-react/text';
+import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+import {system} from '@workday/canvas-tokens-web';
+
 // local helper hook for setting content direction;
 import {useDirection} from './useDirection';
 
-const StyledSidePanel = styled(SidePanel)({
-  marginLeft: 'auto',
-});
+const stylesOverride = {
+  viewport: createStyles({
+    height: px2rem(320),
+  }),
+  panelContainer: createStyles({
+    marginLeft: 'auto',
+  }),
+  panel: createStyles({
+    alignItems: 'center',
+    justifyContent: 'flex-end',
+    paddingY: system.space.x4,
+    paddingX: system.space.x4,
+  }),
+  main: createStyles({
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexDirection: 'column',
+    flex: 1,
+    flexBasis: 'auto',
+  }),
+};
 
 const RightPanel = () => {
   const {expanded, panelProps, labelProps, controlProps} = useSidePanel();
-  const [panelState, setPanelState] = React.useState<SidePanelTransitionStates>(
-    expanded ? 'expanded' : 'collapsed'
-  );
-
-  const expandedContent = (
-    <Flex alignItems="center" justifyContent="flex-end" paddingY="s" paddingX="s">
-      <Text as="h3" typeLevel="body.large" color="licorice500" fontWeight="bold" {...labelProps}>
-        Tasks Panel
-      </Text>
-    </Flex>
-  );
 
   return (
-    <StyledSidePanel {...panelProps} onStateTransition={setPanelState} origin="right">
+    <SidePanel {...panelProps} origin="right" className={stylesOverride.panelContainer}>
       <SidePanel.ToggleButton {...controlProps} />
-      {panelState === 'expanded' ? (
-        expandedContent
-      ) : (
-        <Text hidden {...labelProps}>
+      <Flex cs={stylesOverride.panel}>
+        <Heading size="small" hidden={!expanded ? true : undefined} {...labelProps}>
           Tasks Panel
-        </Text>
-      )}
-    </StyledSidePanel>
+        </Heading>
+      </Flex>
+    </SidePanel>
   );
 };
 
@@ -48,17 +52,12 @@ export default () => {
 
   return (
     <CanvasProvider theme={{canvas: {direction}}}>
-      <Flex height={320}>
-        <Flex
-          as="main"
-          alignItems="center"
-          justifyContent="center"
-          flexDirection="column"
-          flex={1}
-          flexBasis="auto"
-        >
-          <p>Toggle the content direction</p>
-          <SecondaryButton onClick={toggleDirection} role="button">
+      <Flex cs={stylesOverride.viewport}>
+        <Flex as="main" cs={stylesOverride.main}>
+          <Text as="p" typeLevel="body.large">
+            Toggle the content direction
+          </Text>
+          <SecondaryButton onClick={toggleDirection}>
             Set to {direction === 'ltr' ? 'Right-to-Left' : 'Left-to-Right'}
           </SecondaryButton>
         </Flex>

package/dist/mdx/preview-react/side-panel/examples/Variant.tsx

@@ -1,54 +1,54 @@
 import * as React from 'react';
 import {SecondaryButton} from '@workday/canvas-kit-react/button';
-import {
-  SidePanel,
-  useSidePanel,
-  SidePanelTransitionStates,
-} from '@workday/canvas-kit-preview-react/side-panel';
+import {SidePanel, useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex} from '@workday/canvas-kit-react/layout';
-import {Text} from '@workday/canvas-kit-react/text';
+import {Heading, Text} from '@workday/canvas-kit-react/text';
 import {CanvasProvider} from '@workday/canvas-kit-react/common';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+import {base, system} from '@workday/canvas-tokens-web';
+
 // local helper hook for setting content direction;
 import {useDirection} from './useDirection';
 
+const stylesOverride = {
+  viewport: createStyles({
+    height: px2rem(320),
+    backgroundColor: base.soap100,
+  }),
+  panel: createStyles({
+    alignItems: 'center',
+    paddingY: system.space.x4,
+    paddingX: system.space.x4,
+  }),
+  main: createStyles({
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexDirection: 'column',
+    flex: 1,
+    flexBasis: 'auto',
+  }),
+};
+
 export default () => {
   const {direction, toggleDirection} = useDirection();
   const {expanded, panelProps, labelProps, controlProps} = useSidePanel();
-  const [panelState, setPanelState] = React.useState<SidePanelTransitionStates>(
-    expanded ? 'expanded' : 'collapsed'
-  );
-
-  const expandedContent = (
-    <Flex alignItems="center" paddingY="s" paddingX="s">
-      <Text as="h3" typeLevel="body.large" color="licorice500" fontWeight="bold" {...labelProps}>
-        Alternate Panel
-      </Text>
-    </Flex>
-  );
 
   return (
     <CanvasProvider theme={{canvas: {direction}}}>
-      <Flex height={320} backgroundColor="soap100">
-        <SidePanel {...panelProps} onStateTransition={setPanelState} variant="alternate">
+      <Flex cs={stylesOverride.viewport}>
+        <SidePanel {...panelProps} variant="alternate">
           <SidePanel.ToggleButton {...controlProps} />
-          {panelState === 'expanded' ? (
-            expandedContent
-          ) : (
-            <Text hidden {...labelProps}>
-              Tasks Panel
-            </Text>
-          )}
+          <Flex cs={stylesOverride.panel}>
+            <Heading size="small" hidden={!expanded ? true : undefined} {...labelProps}>
+              Alternate Panel
+            </Heading>
+          </Flex>
         </SidePanel>
-        <Flex
-          as="main"
-          alignItems="center"
-          justifyContent="center"
-          flexDirection="column"
-          flex={1}
-          flexBasis="auto"
-        >
-          <p>Toggle the content direction</p>
-          <SecondaryButton onClick={toggleDirection} role="button">
+        <Flex as="main" cs={stylesOverride.main}>
+          <Text as="p" typeLevel="body.large">
+            Toggle the content direction
+          </Text>
+          <SecondaryButton onClick={toggleDirection}>
             Set to {direction === 'ltr' ? 'Right-to-Left' : 'Left-to-Right'}
           </SecondaryButton>
         </Flex>

package/dist/mdx/react/_examples/mdx/SidePanel.mdx

@@ -5,7 +5,24 @@ import WithOverlay from './examples/SidePanelWithOverlay';
 
 # Canvas Kit Examples
 
-## Side Panel With Navigation
+## Side Panel As Navigation
+
+This example demonstrates SidePanel as a navigation system that can be reduced into a "compact view"
+to save horizontal space on screen. It combines semantic HTML nested list markup with Canvas Kit's
+`<Expandable>` component to create an accordion. When in compact view, the Canvas Kit `<Menu>`
+component is used to create the fly-out menus. Both of these components are implemented according to
+the [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) to provide a
+wide range of support for accessibility.
+
+- The `<SidePanel>` uses the `as` prop to render with a semantic HTML `<nav>` element
+- The SidePanel's heading element with the `labelProps` must remain in the DOM even while the
+  component is in compact view, else the `aria-labelledby` reference for the toggle button will
+  become invalid. The `hidden` attribute is conditionally set on the heading based on the `expanded`
+  state of the SidePanel provided by the `useSidePanel` hook.
+- The semantic HTML nested list markup helps support non-visual screen reader users understand the
+  nested hierarchy of the elements inside the expandable containers
+- In the compact view, the `<Tooltip>` component is used to provide an accessible name to the icon
+  button menu targets
 
 <ExampleCodeBlock code={WithNavigation} />
 

package/dist/mdx/react/_examples/mdx/examples/SidePanelWithNavigation.tsx

@@ -1,130 +1,168 @@
 import * as React from 'react';
-import {styled, StyledType} from '@workday/canvas-kit-react/common';
-import {colors, space, gradients, type} from '@workday/canvas-kit-react/tokens';
-import {SidePanel} from '@workday/canvas-kit-preview-react/side-panel';
-import {Flex, Box} from '@workday/canvas-kit-react/layout';
-import {BodyText, Subtext} from '@workday/canvas-kit-react/text';
+import {base, system} from '@workday/canvas-tokens-web';
+import {SidePanel, useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
+import {Flex} from '@workday/canvas-kit-react/layout';
+import {Heading, Subtext, Text} from '@workday/canvas-kit-react/text';
 import {Expandable} from '@workday/canvas-kit-labs-react/expandable';
 import {SystemIcon} from '@workday/canvas-kit-react/icon';
-import {birthdayIcon, ribbonIcon} from '@workday/canvas-system-icons-web';
+import {Hyperlink, TertiaryButton} from '@workday/canvas-kit-react/button';
+import {Menu} from '@workday/canvas-kit-react/menu';
+import {birthdayIcon, checkIcon, ribbonIcon} from '@workday/canvas-system-icons-web';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+import {Tooltip} from '../../../../tooltip';
 
-const StyledPanel = styled(SidePanel.as('nav'))({
-  backgroundColor: colors.soap200,
-  zIndex: 1,
-});
-
-const StyledExpandable = styled(Expandable.Target)({
-  borderRadius: 0,
-  ':hover': {
-    backgroundColor: colors.soap500,
+const data = {
+  bestsellers: {
+    icon: ribbonIcon,
+    title: 'Best Sellers',
+    subtitle: 'Award winning sweet treats',
+    items: ['Mango Coco Sago', 'Matcha Creme Pie', 'Key Lime Cheesecake', 'Tiramisu'],
   },
-});
-
-const StyledLink = styled(Subtext.as('a'))<StyledType>({
-  color: colors.blackPepper300,
-  ':hover': {
-    backgroundColor: colors.soap500,
+  cakes: {
+    icon: birthdayIcon,
+    title: 'Custom Cakes',
+    subtitle: 'To celebrate your life milestones',
+    items: ['Anniversary', 'Birthday', 'Graduation', 'Wedding'],
   },
-});
+};
+
+const stylesOverride = {
+  navContainer: createStyles({
+    height: px2rem(800),
+    positio: 'relative',
+    backgroundColor: base.frenchVanilla100,
+  }),
+  accordionContainer: createStyles({
+    flexDirection: 'column',
+    rowGap: system.space.zero,
+    paddingInlineStart: system.space.zero,
+  }),
+  accordionIcon: createStyles({
+    verticalAlign: 'middle',
+    padding: system.space.x1,
+  }),
+  accordionSubText: createStyles({
+    margin: system.space.zero,
+  }),
+  listContainer: createStyles({
+    listStyle: 'none',
+    padding: system.space.x4,
+    paddingTop: system.space.x16,
+    flexDirection: 'column',
+  }),
+  links: createStyles({
+    textDecoration: 'none',
+    padding: system.space.x4,
+  }),
+  linkCheck: createStyles({
+    marginLeft: 'auto',
+  }),
+  flyOut: createStyles({
+    marginTop: '8rem',
+  }),
+};
+
+const Accordion = ({config}) => {
+  const [currentPage, setCurrentPage] = React.useState('');
 
-const cakes = [
-  {value: 'Anniversary', linkValue: '#AnniversaryCakes'},
-  {value: 'Birthday', linkValue: '#BirthdayCakes'},
-  {value: 'Graduation', linkValue: '#GraduationCakes'},
-  {value: 'Wedding', linkValue: 'WeddingCakes'},
-];
+  const handleClick = e => {
+    e.preventDefault();
+    setCurrentPage(e.target.textContent);
+  };
 
-const bestsellers = [
-  {value: 'Mango Coco Sago', linkValue: '#LemonRhubarbBars'},
-  {value: 'Matcha Creme Pie', linkValue: '#MatchaCremePie'},
-  {value: 'Key Lime Cheesecake', linkValue: '#KeyLimeCheesecake'},
-  {value: 'Tiramisu', linkValue: '#Tiramisu'},
-];
+  return (
+    <Expandable>
+      <Expandable.Target>
+        <SystemIcon cs={stylesOverride.accordionIcon} icon={config.icon} />
+        <Expandable.Title>
+          {config.title}
+          <Subtext size="medium" cs={stylesOverride.accordionSubText}>
+            {config.subtitle}
+          </Subtext>
+        </Expandable.Title>
+        <Expandable.Icon iconPosition="end" />
+      </Expandable.Target>
+      <Expandable.Content as="ul" cs={stylesOverride.listContainer}>
+        {config.items.map(i => {
+          return (
+            <li key={i}>
+              <Flex
+                as="a"
+                href="#"
+                aria-current={i === currentPage ? 'true' : undefined}
+                className={stylesOverride.links}
+                onClick={handleClick}
+              >
+                {i}
+                {i === currentPage && <SystemIcon icon={checkIcon} cs={stylesOverride.linkCheck} />}
+              </Flex>
+            </li>
+          );
+        })}
+      </Expandable.Content>
+    </Expandable>
+  );
+};
 
-const gettingStarted = [
-  'Extended Systems',
-  'Canvas Glossary',
-  'Frequently Asked Questions',
-  'Canvas Support',
-];
+const IconButtonMenu = ({config}) => {
+  return (
+    <Menu>
+      <Tooltip title={config.title} placement="right">
+        <Menu.Target as={TertiaryButton}>
+          <SystemIcon icon={config.icon} />
+        </Menu.Target>
+      </Tooltip>
+      <Menu.Popper placement="right">
+        <Menu.Card cs={stylesOverride.flyOut}>
+          <Menu.List>
+            {config.items.map(i => (
+              <Menu.Item>{i}</Menu.Item>
+            ))}
+          </Menu.List>
+        </Menu.Card>
+      </Menu.Popper>
+    </Menu>
+  );
+};
+
+const CompactView = () => {
+  return (
+    <Flex as="ul" cs={stylesOverride.listContainer}>
+      <Flex.Item as="li">
+        <IconButtonMenu config={data.bestsellers} />
+      </Flex.Item>
+      <Flex.Item as="li">
+        <IconButtonMenu config={data.cakes} />
+      </Flex.Item>
+    </Flex>
+  );
+};
+
+const ExpandedView = () => {
+  return (
+    <Flex as="ul" cs={stylesOverride.accordionContainer}>
+      <Flex.Item as="li">
+        <Accordion config={data.bestsellers} />
+      </Flex.Item>
+      <Flex.Item as="li">
+        <Accordion config={data.cakes} />
+      </Flex.Item>
+    </Flex>
+  );
+};
 
 export default () => {
+  const {expanded, panelProps, labelProps, controlProps} = useSidePanel();
+
   return (
-    <Flex height={800} position="relative" backgroundColor="frenchVanilla100">
-      <StyledPanel touched={true} variant="alternate">
-        <Flex as="ul" flexDirection="column" rowGap="zero" paddingInlineStart="zero">
-          <Flex.Item as="li" listStyle="none">
-            <Expandable padding="zero">
-              <StyledExpandable paddingTop="m" paddingBottom="xxs" paddingX="m" textAlign="center">
-                <SystemIcon icon={ribbonIcon} paddingRight="s" />
-                <Expandable.Title padding="zero">
-                  <BodyText size="small" fontWeight="bold" color="blackpepper300" marginY="zero">
-                    Bestsellers
-                  </BodyText>
-                  <Subtext size="medium" color="blackpepper300" marginY="zero">
-                    Award winning sweet treats
-                  </Subtext>
-                </Expandable.Title>
-                <Expandable.Icon iconPosition="end" />
-              </StyledExpandable>
-              <Expandable.Content paddingY="zero" paddingX="zero" as="ul">
-                {bestsellers.map(item => {
-                  return (
-                    <li>
-                      <StyledLink
-                        size="large"
-                        display="flex"
-                        textDecoration="none"
-                        paddingLeft="xxl"
-                        paddingTop="xxs"
-                        paddingBottom="zero"
-                        href={item.linkValue}
-                      >
-                        {item.value}
-                      </StyledLink>
-                    </li>
-                  );
-                })}
-              </Expandable.Content>
-            </Expandable>
-          </Flex.Item>
-          <Flex.Item as="li" listStyle="none">
-            <Expandable padding="zero">
-              <StyledExpandable paddingTop="m" paddingBottom="xxs" paddingX="m" textAlign="center">
-                <SystemIcon icon={birthdayIcon} paddingRight="s" />
-                <Expandable.Title padding="zero">
-                  <BodyText size="small" fontWeight="bold" color="blackpepper300" marginY="zero">
-                    Custom Cakes
-                  </BodyText>
-                  <Subtext size="medium" color="blackpepper300" marginY="zero">
-                    To celebrate your life milestones
-                  </Subtext>
-                </Expandable.Title>
-                <Expandable.Icon iconPosition="end" />
-              </StyledExpandable>
-              <Expandable.Content paddingY="zero" paddingX="zero" as="ul">
-                {cakes.map(item => {
-                  return (
-                    <li>
-                      <StyledLink
-                        size="large"
-                        display="flex"
-                        textDecoration="none"
-                        paddingLeft="xxl"
-                        paddingTop="xxs"
-                        paddingBottom="zero"
-                        href={item.linkValue}
-                      >
-                        {item.value}
-                      </StyledLink>
-                    </li>
-                  );
-                })}
-              </Expandable.Content>
-            </Expandable>
-          </Flex.Item>
-        </Flex>
-      </StyledPanel>
+    <Flex cs={stylesOverride.navContainer}>
+      <SidePanel as="nav" {...panelProps}>
+        <Heading size="small" {...labelProps} hidden={!expanded ? true : undefined}>
+          Cake or Death Bakery
+        </Heading>
+        <SidePanel.ToggleButton {...controlProps} />
+        {expanded ? <ExpandedView /> : <CompactView />}
+      </SidePanel>
     </Flex>
   );
 };

package/dist/mdx/react/_examples/mdx/examples/SidePanelWithOverlay.tsx

@@ -1,28 +1,46 @@
 import * as React from 'react';
-import {styled} from '@workday/canvas-kit-react/common';
-import {depth} from '@workday/canvas-kit-react/tokens';
 import {SidePanel, useSidePanel} from '@workday/canvas-kit-preview-react/side-panel';
 import {Flex, Box} from '@workday/canvas-kit-react/layout';
-import {Text} from '@workday/canvas-kit-react/text';
+import {Heading} from '@workday/canvas-kit-react/text';
+import {createStyles, px2rem} from '@workday/canvas-kit-styling';
+import {system, base} from '@workday/canvas-tokens-web';
 
-const StyledPanel = styled(SidePanel)({
-  ...depth[6],
-  zIndex: 1,
-});
+const stylesOverride = {
+  panelContainer: createStyles({
+    height: px2rem(320),
+    backgroundColor: base.soap100,
+    position: 'relative',
+  }),
+  panelContent: createStyles({
+    alignItems: 'center',
+    paddingY: system.space.x4,
+    paddingX: system.space.x4,
+  }),
+  panel: createStyles({
+    zIndex: 1,
+  }),
+  overlay: createStyles({
+    position: 'absolute',
+    background: system.color.bg.overlay,
+    height: '100%',
+    width: '100%',
+  }),
+};
 
 export default () => {
-  const {labelProps} = useSidePanel();
+  const {expanded, panelProps, labelProps, controlProps} = useSidePanel();
 
   return (
-    <Flex height={320} backgroundColor="soap100" position="relative">
-      <StyledPanel touched={true} variant="alternate">
-        <Flex alignItems="center" paddingY="s" paddingX="s">
-          <Text as="h3" typeLevel="body.large" fontWeight="bold" color="licorice500">
+    <Flex cs={stylesOverride.panelContainer}>
+      <SidePanel className={stylesOverride.panel} {...panelProps} variant="alternate">
+        <Flex cs={stylesOverride.panelContainer}>
+          <Heading size="small" {...labelProps} hidden={!expanded ? true : undefined}>
             Alternate Panel
-          </Text>
+          </Heading>
+          <SidePanel.ToggleButton {...controlProps} />
         </Flex>
-      </StyledPanel>
-      <Box position="absolute" background="rgba(0,0,0,0.65)" height="100%" width="100%" />
+      </SidePanel>
+      {expanded && <Box cs={stylesOverride.overlay} />}
     </Flex>
   );
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workday/canvas-kit-docs",
-  "version": "12.3.1",
+  "version": "12.3.3",
   "description": "Documentation components of Canvas Kit components",
   "author": "Workday, Inc. (https://www.workday.com)",
   "license": "Apache-2.0",
@@ -44,10 +44,10 @@
   "dependencies": {
     "@emotion/styled": "^11.6.0",
     "@storybook/csf": "0.0.1",
-    "@workday/canvas-kit-labs-react": "^12.3.1",
-    "@workday/canvas-kit-preview-react": "^12.3.1",
-    "@workday/canvas-kit-react": "^12.3.1",
-    "@workday/canvas-kit-styling": "^12.3.1",
+    "@workday/canvas-kit-labs-react": "^12.3.3",
+    "@workday/canvas-kit-preview-react": "^12.3.3",
+    "@workday/canvas-kit-react": "^12.3.3",
+    "@workday/canvas-kit-styling": "^12.3.3",
     "@workday/canvas-system-icons-web": "^3.0.0",
     "@workday/canvas-tokens-web": "^2.1.0",
     "markdown-to-jsx": "^7.2.0",
@@ -60,5 +60,5 @@
     "mkdirp": "^1.0.3",
     "typescript": "5.0"
   },
-  "gitHead": "8f197dfdb262f224d73c602d6811d24302e6154c"
+  "gitHead": "813b84599c30a0c575cbdd5f958fbf5321412c90"
 }