@codecademy/styleguide 78.5.5-alpha.7e2d80.0 → 78.5.5-alpha.86d3e6.0

package/.storybook/components/index.tsx

@@ -2,7 +2,6 @@ export * from './ImageWrapper';
 export * from './TokenTable';
 export * from './Headers';
 export * from './Elements/Callout';
-export * from './Elements/KeyboardKey';
 export * from './Elements/Markdown';
 export * from './Elements/ImageGallery';
 export * from './Scales/ColorScale';

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-### [78.5.5-alpha.7e2d80.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@78.5.4...@codecademy/styleguide@78.5.5-alpha.7e2d80.0) (2026-01-06)
+### [78.5.5-alpha.86d3e6.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@78.5.4...@codecademy/styleguide@78.5.5-alpha.86d3e6.0) (2026-01-06)
 
 **Note:** Version bump only for package @codecademy/styleguide
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@codecademy/styleguide",
   "description": "Styleguide & Component library for codecademy.com",
-  "version": "78.5.5-alpha.7e2d80.0",
+  "version": "78.5.5-alpha.86d3e6.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "32955354e4424e7ed406926d63c1e4dbe253318f"
+  "gitHead": "2988ef3b1571897c2359c9031389d08356b819be"
 }

package/src/lib/Atoms/SkipToContent/SkipToContent.mdx

@@ -1,6 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 
-import { ComponentHeader, KeyboardKey } from '~styleguide/blocks';
+import { ComponentHeader } from '~styleguide/blocks';
 
 import * as SkipToContentStories from './SkipToContent.stories';
 
@@ -21,10 +21,11 @@ export const parameters = {
 
 ## Usage
 
-Use `<SkipToContent />` to add a hidden-by-default link that becomes visible when the user <KeyboardKey>Tab</KeyboardKey>s over it (gives it focus).
+Use `<SkipToContent />` to add a hidden-by-default link that becomes visible when the user <kbd>Tab</kbd>s over it (gives it focus).
 It takes in the ID of the element it will scroll to and focus ([dev.to article explaining why](https://dev.to/robdodson/managing-focus-64l)) on click (via mouse or keyboard).
 
-This type of control is necessary for pages that have a bunch of stuff keyboard users would have to <KeyboardKey>Tab</KeyboardKey> through to get to the page's main content (like navigations).
+This type of control is necessary for pages that have a bunch of stuff keyboard users would have to Tab through to get
+to the page's main content (like navigations).
 
 For this element to work properly, there must be a `<SkipToContentTarget />` component with the id passed into this component for the `contentId` prop. The `<SkipToContentTarget />` component by default has a `tabIndex` of -1.
 Example:
@@ -42,7 +43,7 @@ Example:
 </div>
 ```
 
-To see it, keep pressing <KeyboardKey>Tab</KeyboardKey> around on this page or visit [the catalog](https://www.codecademy.com/catalog/language/javascript) and navigate via <KeyboardKey>Tab</KeyboardKey> to see it in action.
+To see it, keep tabbing around on this page or visit [the catalog](https://www.codecademy.com/catalog/language/javascript) and navigate via tab to see it in action.
 
 ## Playground
 

package/src/lib/Molecules/Coachmark/Coachmark.mdx

@@ -94,6 +94,12 @@ Using `popoverProps`, you can customize the look of the rendered popover. For ex
 
 <Canvas of={CoachmarkStories.Customized} />
 
+### Z-Index
+
+You can customize the `zIndex` of the Coachmark's popover by passing `zIndex` through `popoverProps`. This is useful when the popover needs to appear above other positioned elements.
+
+<Canvas of={CoachmarkStories.ZIndex} />
+
 ## Playground
 
 <Canvas sourceState="shown" of={CoachmarkStories.Default} />

package/src/lib/Molecules/Coachmark/Coachmark.stories.tsx

@@ -1,4 +1,4 @@
-import { Coachmark, FillButton, FlexBox, Text } from '@codecademy/gamut';
+import { Box, Coachmark, FillButton, FlexBox, Text } from '@codecademy/gamut';
 import * as patterns from '@codecademy/gamut-patterns';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ComponentProps, useEffect, useState } from 'react';
@@ -197,3 +197,39 @@ export const Customized: Story = {
     );
   },
 };
+
+export const ZIndex: Story = {
+  args: {
+    popoverProps: {
+      position: 'below',
+      zIndex: 5,
+    },
+  },
+  render: function ZIndexExample(args) {
+    const [shouldShow, setShouldShow] = useState(true);
+
+    return (
+      <FlexBox flexDirection="column" gap={16}>
+        <Box bg="paleBlue" p={16} zIndex={3} position="relative">
+          Element with z-index: 3
+        </Box>
+        <Coachmark
+          {...args}
+          renderPopover={() => (
+            <FlexBox alignItems="flex-start" flexDirection="column" p={16}>
+              <Text mb={8}>This coachmark has z-index: 5 via popoverProps</Text>
+              <FillButton size="small" onClick={() => setShouldShow(false)}>
+                Got it
+              </FillButton>
+            </FlexBox>
+          )}
+          shouldShow={shouldShow}
+        >
+          <FillButton onClick={() => setShouldShow(true)}>
+            Show Coachmark
+          </FillButton>
+        </Coachmark>
+      </FlexBox>
+    );
+  },
+};

package/src/lib/Molecules/Flyout/Flyout.mdx

@@ -1,6 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 
-import { ComponentHeader, KeyboardKey, LinkTo } from '~styleguide/blocks';
+import { ComponentHeader, LinkTo } from '~styleguide/blocks';
 
 import * as FlyoutStories from './Flyout.stories';
 
@@ -25,7 +25,7 @@ export const parameters = {
 
 ## Usage
 
-On button click, a container animates in from the left or right side of the window. Flyout can be configured to close by pressing the "X" close icon, pressing the <KeyboardKey>Esc</KeyboardKey> key, and/or clicking outside of the container.
+On button click, a container animates in from the left or right side of the window. Flyout can be configured to close by pressing the “X” close icon, pressing they “esc” key, and/or clicking outside of the container.
 
 Internally, Flyout is a combination of <LinkTo id="Molecules/Modals/Overlay">Overlay</LinkTo> and <LinkTo id="Atoms/Drawer">Drawer</LinkTo>.
 

package/src/lib/Molecules/Modals/Modal/Modal.mdx

@@ -1,6 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 
-import { ComponentHeader, KeyboardKey } from '~styleguide/blocks';
+import { ComponentHeader } from '~styleguide/blocks';
 
 import * as ModalStories from './Modal.stories';
 
@@ -77,7 +77,7 @@ If the close button is hidden, you will need to create a custom way to close the
 Other than creating buttons that can close the Modal, there are other ways a Modal can be closed by the user.
 
 1. Clicking the content outside of the Modal
-2. Pressing the <KeyboardKey>Esc</KeyboardKey> key on their keyboard
+2. Clicking the escape key on their keyboard
 
 All of these methods default to `true` for accessibility reasons, and rely on setting the required `onRequestClose` prop and making sure it toggles the `isOpen` prop on the Modal.
 
@@ -89,6 +89,16 @@ A Modal can be made scrollable by including large content inside.
 
 <Canvas of={ModalStories.Scrollable} />
 
+## Z-Index
+
+Modal accepts a `zIndex` prop (defaults to `3`) that controls the stacking order of its underlying Overlay. Use this when the modal needs to appear above other positioned elements like sticky headers or custom floating UI.
+
+```tsx
+<Modal zIndex={10} isOpen={isOpen} onRequestClose={handleClose}>
+  Content that needs to appear above other positioned elements
+</Modal>
+```
+
 ## Focus management
 
 The `containerFocusRef` prop allows you to programmatically control focus on the Modal container. This is useful for advanced focus management scenarios where you need to override the default focus behavior (the Modal has `data-autofocus` by default).

package/src/lib/Molecules/Modals/Overlay/Overlay.mdx

@@ -32,6 +32,12 @@ Unlike the legacy `Modal` implementations in the monolith, this:
 
 - If you need styles such as a background behind content, see `Modal` for general modals and `Dialog` for confirmation flows.
 
+## Z-Index
+
+The `zIndex` prop controls the stacking order of the overlay. It defaults to `3`, which places it above most common UI elements. Increase this value when the overlay needs to appear above other positioned elements like sticky headers or floating UI.
+
+<Canvas of={OverlayStories.ZIndex} />
+
 ## Playground
 
 <Canvas sourceState="shown" of={OverlayStories.Default} />

package/src/lib/Molecules/Modals/Overlay/Overlay.stories.tsx

@@ -1,5 +1,5 @@
-import { FillButton, FlexBox, Overlay, Text } from '@codecademy/gamut';
-import type { Meta } from '@storybook/react';
+import { Box, FillButton, FlexBox, Overlay, Text } from '@codecademy/gamut';
+import type { Meta, StoryObj } from '@storybook/react';
 import { useEffect, useState } from 'react';
 
 const meta: Meta<typeof Overlay> = {
@@ -8,6 +8,7 @@ const meta: Meta<typeof Overlay> = {
 };
 
 export default meta;
+type Story = StoryObj<typeof Overlay>;
 
 export const Default: React.FC<React.ComponentProps<typeof Overlay>> = (
   args
@@ -34,3 +35,67 @@ export const Default: React.FC<React.ComponentProps<typeof Overlay>> = (
     </>
   );
 };
+
+export const ZIndex: Story = {
+  render: function ZIndexExample() {
+    const [defaultOpen, setDefaultOpen] = useState(false);
+    const [customOpen, setCustomOpen] = useState(false);
+
+    return (
+      <FlexBox flexDirection="column" gap={16}>
+        <FlexBox gap={16}>
+          <FillButton onClick={() => setDefaultOpen(true)}>
+            Open Overlay (default z-index: 3)
+          </FillButton>
+          <FillButton onClick={() => setCustomOpen(true)}>
+            Open Overlay (z-index: 10)
+          </FillButton>
+        </FlexBox>
+
+        <Box position="relative" height="100px">
+          <Box
+            position="absolute"
+            top={0}
+            left={0}
+            bg="paleYellow"
+            p={16}
+            zIndex={5}
+          >
+            <Text>Element with z-index: 5</Text>
+          </Box>
+        </Box>
+
+        <Overlay
+          isOpen={defaultOpen}
+          onRequestClose={() => setDefaultOpen(false)}
+          shroud
+        >
+          <FlexBox bg="white" p={24} borderRadius="md" flexDirection="column" gap={16}>
+            <Text>
+              This overlay uses the default z-index of 3.
+              <br />
+              It may appear behind elements with higher z-index values.
+            </Text>
+            <FillButton onClick={() => setDefaultOpen(false)}>Close</FillButton>
+          </FlexBox>
+        </Overlay>
+
+        <Overlay
+          isOpen={customOpen}
+          onRequestClose={() => setCustomOpen(false)}
+          shroud
+          zIndex={10}
+        >
+          <FlexBox bg="white" p={24} borderRadius="md" flexDirection="column" gap={16}>
+            <Text>
+              This overlay uses z-index: 10.
+              <br />
+              It will appear above the yellow element with z-index: 5.
+            </Text>
+            <FillButton onClick={() => setCustomOpen(false)}>Close</FillButton>
+          </FlexBox>
+        </Overlay>
+      </FlexBox>
+    );
+  },
+};

package/src/lib/Molecules/Tabs/Tabs.mdx

@@ -1,6 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 
-import { ComponentHeader, KeyboardKey, LinkTo } from '~styleguide/blocks';
+import { ComponentHeader, LinkTo } from '~styleguide/blocks';
 
 import * as TabStories from './Tabs.stories';
 
@@ -67,7 +67,7 @@ It is recommended to add a unique `aria-label` to the `TabNav` component, to dif
 
 ### Tabs with interactive content
 
-Normally, when you navigate to the contents of a `TabPanel` using the <KeyboardKey>Tab</KeyboardKey> key or arrow keys, the entire section of the `TabPanel` will be in focus.
+Normally, when you navigate to the contents of a `TabPanel` using the <kbd>tab</kbd> key or arrow keys, the entire section of the `TabPanel` will be in focus.
 
 However, if you have tabs with interactive content within them (such as a button or link), and tab into the `TabPanel`, the focus will be on the interactive content and not the entirety of the `TabPanel`.
 

package/src/lib/Molecules/Tips/InfoTip/InfoTip.mdx

@@ -1,6 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 
-import { ComponentHeader, KeyboardKey } from '~styleguide/blocks';
+import { ComponentHeader } from '~styleguide/blocks';
 
 import * as InfoTipStories from './InfoTip.stories';
 
@@ -25,7 +25,7 @@ export const parameters = {
 
 ## Usage
 
-A tip is triggered by clicking on an information icon button and can be closed by clicking outside, pressing <KeyboardKey>Esc</KeyboardKey>, or clicking the info button again.
+A tip is triggered by clicking on an information icon button and can be closed by clicking outside, pressing <kbd>Esc</kbd>, or clicking the info button again.
 
 Use an infotip to provide additional info about a nearby element or content.
 
@@ -65,9 +65,9 @@ Links or buttons within InfoTips should be used sparingly and only when the info
 
 When using `placement="floating"`, InfoTips implements focus management for easier navigation:
 
-- **<KeyboardKey>Tab</KeyboardKey>**: Navigate forward through focusable elements (links, buttons) inside the tip. When reaching the last element, wraps back to the InfoTip button for convenience
-- **<KeyboardKey>Shift</KeyboardKey>+<KeyboardKey>Tab</KeyboardKey>**: Navigate backward naturally through the page
-- **<KeyboardKey>Esc</KeyboardKey>**: Closes the tip and returns focus to the InfoTip button
+- **Tab**: Navigate forward through focusable elements (links, buttons) inside the tip. When reaching the last element, wraps back to the InfoTip button for convenience
+- **Shift+Tab**: Navigate backward naturally through the page
+- **Escape**: Closes the tip and returns focus to the InfoTip button
 
 <Canvas of={InfoTipStories.KeyboardNavigation} />
 
@@ -75,16 +75,31 @@ When using `placement="floating"`, InfoTips implements focus management for easi
 
 InfoTips have intelligent Escape key handling that works correctly both inside and outside Modals:
 
-- **InfoTips close on <KeyboardKey>Esc</KeyboardKey>** regardless of where keyboard focus is, and focus returns to the InfoTip button
-- **InfoTips inside Modals close first** - When an InfoTip is placed inside a Modal, pressing <KeyboardKey>Esc</KeyboardKey> closes the InfoTip while keeping the Modal open
-- **Layered navigation** - After closing an InfoTip inside a Modal, pressing <KeyboardKey>Esc</KeyboardKey> again closes the Modal
-- **Modals take priority over external InfoTips** - InfoTips detect when `dialog[open]`, `role="dialog"`, or `role="alertdialog"` elements are present and defer <KeyboardKey>Esc</KeyboardKey> handling to them when the InfoTip is outside the Modal
+- **InfoTips close on Escape** regardless of where keyboard focus is, and focus returns to the InfoTip button
+- **InfoTips inside Modals close first** - When an InfoTip is placed inside a Modal, pressing Escape closes the InfoTip while keeping the Modal open
+- **Layered navigation** - After closing an InfoTip inside a Modal, pressing Escape again closes the Modal
+- **Modals take priority over external InfoTips** - InfoTips detect when `dialog[open]`, `role="dialog"`, or `role="alertdialog"` elements are present and defer Escape handling to them when the InfoTip is outside the Modal
 
 <Canvas of={InfoTipStories.InfoTipInsideModal} />
 
-## InfoTips and zIndex
+## Custom Accessible Labeling
 
-You can change the zIndex of your `InfoTip` with the zIndex property.
+Provide either `ariaLabel` or `ariaLabelledby` to ensure screen reader users understand the purpose of the InfoTip button.
+
+The InfoTip button's accessible label can be customized using either prop:
+
+- **`ariaLabel`**: Directly sets the accessible label text. Useful when you want to provide a custom label without referencing another element.
+- **`ariaLabelledby`**: References the ID of another element to use as the label. Useful when you want the InfoTip button to be labeled by visible text elsewhere on the page. This is useful for when the `InfoTip` is beside text that contextualizes it.
+
+### Custom Role Description
+
+The `InfoTipButton` uses [`aria-roledescription="More information button"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-roledescription) to provide additional context to screen reader users about the button's specific purpose.
+
+<Canvas of={InfoTipStories.AriaLabel} />
+
+## Z-Index
+
+You can customize the `zIndex` of the InfoTip's portal with the `zIndex` prop. This works for both `inline` and `floating` placements, and is useful when the tip needs to appear above other positioned elements.
 
 <Canvas of={InfoTipStories.ZIndex} />
 

package/src/lib/Molecules/Tips/InfoTip/InfoTip.stories.tsx

@@ -1,6 +1,7 @@
 import {
   Anchor,
   Box,
+  Coachmark,
   FillButton,
   FlexBox,
   GridBox,
@@ -195,6 +196,7 @@ export const InfoTipInsideModal: Story = {
   },
   render: function InfoTipInsideModal(args) {
     const [isModalOpen, setIsModalOpen] = useState(false);
+    const [showCoachmark, setShowCoachmark] = useState(false);
 
     return (
       <FlexBox center flexDirection="column" gap={16} py={64}>
@@ -233,6 +235,37 @@ export const InfoTipInsideModal: Story = {
               closing the modal itself. Inline placement works correctly.
             </Text>
 
+            <FlexBox alignItems="center" borderTop={1} gap={8} mt={8} pt={16}>
+              <Text id="modal-coachmark-text">
+                This modal also contains a Coachmark
+              </Text>
+              <Coachmark
+                popoverProps={{ zIndex: 3 }}
+                renderPopover={() => (
+                  <FlexBox
+                    alignItems="flex-start"
+                    flexDirection="column"
+                    p={16}
+                  >
+                    <Text mb={8}>
+                      This Coachmark is inside a Modal. Try pressing Escape!
+                    </Text>
+                    <FillButton
+                      size="small"
+                      onClick={() => setShowCoachmark(false)}
+                    >
+                      Got it
+                    </FillButton>
+                  </FlexBox>
+                )}
+                shouldShow={showCoachmark}
+              >
+                <FillButton size="small" onClick={() => setShowCoachmark(true)}>
+                  Show Coachmark
+                </FillButton>
+              </Coachmark>
+            </FlexBox>
+
             <FillButton onClick={() => setIsModalOpen(false)}>
               Close Modal
             </FillButton>
@@ -245,19 +278,49 @@ export const InfoTipInsideModal: Story = {
 
 export const ZIndex: Story = {
   args: {
-    info: 'I am inline, cool',
+    info: 'I have a custom z-index',
     zIndex: 5,
   },
   render: (args) => (
-    <FlexBox center flexDirection="column" m={24} py={64}>
-      <Box bg="paleBlue" zIndex={3}>
-        I will not be behind the infotip, sad + unreadable
-      </Box>
-      <InfoTip info="I am inline, cool" />
-      <Box bg="paleBlue" zIndex={3}>
-        I will be behind the infotip, nice + great
-      </Box>
-      <InfoTip {...args} />
+    <FlexBox center flexDirection="column" gap={16} m={24} py={64}>
+      <Text variant="p-small">Inline placement:</Text>
+      <FlexBox alignItems="center" gap={8}>
+        <Box bg="paleBlue" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <InfoTip ariaLabel="inline default" info="Default z-index (inline)" />
+        <Box bg="paleBlue" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <InfoTip
+          {...args}
+          ariaLabel="inline custom"
+          info="z-index: 5 (inline)"
+        />
+      </FlexBox>
+
+      <Text variant="p-small" mt={24}>
+        Floating placement:
+      </Text>
+      <FlexBox alignItems="center" gap={8}>
+        <Box bg="paleGreen" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <InfoTip
+          ariaLabel="floating default"
+          info="Default z-index (floating)"
+          placement="floating"
+        />
+        <Box bg="paleGreen" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <InfoTip
+          {...args}
+          ariaLabel="floating custom"
+          info="z-index: 5 (floating)"
+          placement="floating"
+        />
+      </FlexBox>
     </FlexBox>
   ),
 };

package/src/lib/Molecules/Tips/PreviewTip/PreviewTip.mdx

@@ -55,6 +55,12 @@ The `truncateLines` prop allows you to set the maximum number of lines that the
 
 <Canvas of={PreviewTipStories.Truncation} />
 
+## Z-Index
+
+You can customize the `zIndex` of the PreviewTip's portal with the `zIndex` prop. This works for both `inline` and `floating` placements, and is useful when the tip needs to appear above other positioned elements.
+
+<Canvas of={PreviewTipStories.ZIndex} />
+
 ## Playground
 
 <Canvas sourceState="shown" of={PreviewTipStories.Default} />

package/src/lib/Molecules/Tips/PreviewTip/PreviewTip.stories.tsx

@@ -1,4 +1,4 @@
-import { Box, FlexBox, PreviewTip } from '@codecademy/gamut';
+import { Box, FlexBox, PreviewTip, Text } from '@codecademy/gamut';
 import { SmileyIndifferentIcon } from '@codecademy/gamut-icons';
 import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
@@ -110,3 +110,70 @@ const TruncationExample = (args: React.ComponentProps<typeof PreviewTip>) => {
 export const Truncation: Story = {
   render: (args) => <TruncationExample {...args} />,
 };
+
+export const ZIndex: Story = {
+  args: {
+    zIndex: 5,
+  },
+  render: (args) => (
+    <FlexBox center flexDirection="column" gap={16} py={64}>
+      <Text variant="p-small">Inline placement:</Text>
+      <FlexBox alignItems="center" gap={16}>
+        <Box bg="paleBlue" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <PreviewTip
+          {...args}
+          alignment="bottom-right"
+          href="#"
+          linkDescription="Default z-index (inline)"
+        >
+          Default z-index
+        </PreviewTip>
+        <Box bg="paleBlue" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <PreviewTip
+          {...args}
+          alignment="top-right"
+          href="#"
+          linkDescription="z-index: 5 (inline)"
+          zIndex={5}
+        >
+          z-index: 5
+        </PreviewTip>
+      </FlexBox>
+
+      <Text variant="p-small" mt={24}>
+        Floating placement:
+      </Text>
+      <FlexBox alignItems="center" gap={16}>
+        <Box bg="paleGreen" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <PreviewTip
+          {...args}
+          alignment="bottom-right"
+          href="#"
+          linkDescription="Default z-index (floating)"
+          placement="floating"
+        >
+          Default z-index
+        </PreviewTip>
+        <Box bg="paleGreen" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <PreviewTip
+          {...args}
+          alignment="top-right"
+          href="#"
+          linkDescription="z-index: 5 (floating)"
+          placement="floating"
+          zIndex={5}
+        >
+          z-index: 5
+        </PreviewTip>
+      </FlexBox>
+    </FlexBox>
+  ),
+};

package/src/lib/Molecules/Tips/ToolTip/ToolTip.mdx

@@ -63,6 +63,12 @@ When a Button is disabled with a tooltip, you must use the `aria-disabled` prop
 
 <Canvas of={ToolTipStories.Disabled} />
 
+## Z-Index
+
+You can customize the `zIndex` of the ToolTip's portal with the `zIndex` prop. This works for both `inline` and `floating` placements, and is useful when the tip needs to appear above other positioned elements.
+
+<Canvas of={ToolTipStories.ZIndex} />
+
 ## Playground
 
 <Canvas sourceState="shown" of={ToolTipStories.Default} />

package/src/lib/Molecules/Tips/ToolTip/ToolTip.stories.tsx

@@ -1,8 +1,10 @@
 import {
+  Box,
   FillButton,
   FlexBox,
   IconButton,
   StrokeButton,
+  Text,
   ToolTip,
 } from '@codecademy/gamut';
 import {
@@ -133,3 +135,60 @@ export const Disabled: Story = {
     </FlexBox>
   ),
 };
+
+export const ZIndex: Story = {
+  render: () => (
+    <FlexBox center flexDirection="column" gap={16} m={24} py={64}>
+      <Text variant="p-small">Inline placement:</Text>
+      <FlexBox alignItems="center" gap={16}>
+        <Box bg="paleBlue" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <ToolTip id="zindex-inline-default" info="Default z-index (inline)">
+          <FillButton aria-describedby="zindex-inline-default">
+            Default
+          </FillButton>
+        </ToolTip>
+        <Box bg="paleBlue" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <ToolTip id="zindex-inline-custom" info="z-index: 5 (inline)" zIndex={5}>
+          <FillButton aria-describedby="zindex-inline-custom">
+            z-index: 5
+          </FillButton>
+        </ToolTip>
+      </FlexBox>
+
+      <Text variant="p-small" mt={24}>
+        Floating placement:
+      </Text>
+      <FlexBox alignItems="center" gap={16}>
+        <Box bg="paleGreen" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <ToolTip
+          id="zindex-floating-default"
+          info="Default z-index (floating)"
+          placement="floating"
+        >
+          <FillButton aria-describedby="zindex-floating-default">
+            Default
+          </FillButton>
+        </ToolTip>
+        <Box bg="paleGreen" p={8} zIndex={3} position="relative">
+          z-index: 3
+        </Box>
+        <ToolTip
+          id="zindex-floating-custom"
+          info="z-index: 5 (floating)"
+          placement="floating"
+          zIndex={5}
+        >
+          <FillButton aria-describedby="zindex-floating-custom">
+            z-index: 5
+          </FillButton>
+        </ToolTip>
+      </FlexBox>
+    </FlexBox>
+  ),
+};

package/.storybook/components/Elements/KeyboardKey.tsx

@@ -1,17 +0,0 @@
-import styled from '@emotion/styled';
-import { css } from '@codecademy/gamut-styles';
-
-export const KeyboardKey = styled.kbd(
-  css({
-    mx: 2 as any,
-    fontFamily: 'monospace',
-    fontSize: '0.75rem' as any,
-    bg: 'background-selected',
-    border: 1,
-    borderColor: 'border-tertiary',
-    borderRadius: 'sm',
-    px: 4,
-    py: 2 as any,
-    boxShadow: 'inset 0 -1px 0 rgba(0, 0, 0, 0.2)',
-  })
-);