From 9a69f169ee6d6a40b08f0e9e6eb1d2abd9821845 Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Wed, 10 Dec 2025 12:31:32 -0500
Subject: [PATCH] docs: add zIndex documentation to floating components

- Overlay: add zIndex story and docs section
- Modal: add zIndex note with code example
- InfoTip: update story to show inline and floating placements
- PreviewTip: add zIndex story showing both placements
- ToolTip: add zIndex story showing both placements
- Coachmark: add zIndex story using popoverProps passthrough
---
 packages/gamut/src/Popover/Popover.tsx        |  8 +-
 packages/gamut/src/Popover/elements.tsx       |  8 +-
 packages/gamut/src/Popover/types.tsx          |  5 ++
 packages/gamut/src/Tip/shared/FloatingTip.tsx |  2 +
 packages/gamut/src/Tip/shared/types.tsx       |  7 +-
 .../src/lib/Molecules/Coachmark/Coachmark.mdx |  6 ++
 .../Molecules/Coachmark/Coachmark.stories.tsx | 38 ++++++++-
 .../src/lib/Molecules/Modals/Modal/Modal.mdx  | 10 +++
 .../lib/Molecules/Modals/Overlay/Overlay.mdx  |  6 ++
 .../Modals/Overlay/Overlay.stories.tsx        | 69 ++++++++++++++-
 .../lib/Molecules/Tips/InfoTip/InfoTip.mdx    | 19 ++++-
 .../Tips/InfoTip/InfoTip.stories.tsx          | 83 ++++++++++++++++---
 .../Molecules/Tips/PreviewTip/PreviewTip.mdx  |  6 ++
 .../Tips/PreviewTip/PreviewTip.stories.tsx    | 69 ++++++++++++++-
 .../lib/Molecules/Tips/ToolTip/ToolTip.mdx    |  6 ++
 .../Tips/ToolTip/ToolTip.stories.tsx          | 59 +++++++++++++
 16 files changed, 376 insertions(+), 25 deletions(-)

diff --git a/packages/gamut/src/Popover/Popover.tsx b/packages/gamut/src/Popover/Popover.tsx
index 86bbb05d9ee..601c2f5b065 100755
--- a/packages/gamut/src/Popover/Popover.tsx
+++ b/packages/gamut/src/Popover/Popover.tsx
@@ -40,8 +40,8 @@ export const Popover: React.FC<PopoverProps> = ({
     variant,
   }),
   verticalOffset = getDefaultOffset({ axis: 'vertical', position, variant }),
-
   widthRestricted,
+  zIndex,
 }) => {
   const [popoverHeight, setPopoverHeight] = useState<number>(0);
   const [popoverWidth, setPopoverWidth] = useState<number>(0);
@@ -233,7 +233,11 @@ export const Popover: React.FC<PopoverProps> = ({
   );
 
   return (
-    <PopoverPortal animation={animation} isOpen={Boolean(isOpen && targetRef)}>
+    <PopoverPortal
+      animation={animation}
+      isOpen={Boolean(isOpen && targetRef)}
+      zIndex={zIndex}
+    >
       {skipFocusTrap ? (
         <>{contents}</>
       ) : (
diff --git a/packages/gamut/src/Popover/elements.tsx b/packages/gamut/src/Popover/elements.tsx
index 04908315050..74b251d02b5 100644
--- a/packages/gamut/src/Popover/elements.tsx
+++ b/packages/gamut/src/Popover/elements.tsx
@@ -61,12 +61,12 @@ export const PatternContainer = styled.div(
 );
 
 export const PopoverPortal: React.FC<
-  Pick<PopoverProps, 'animation' | 'isOpen'> & WithChildrenProp
-> = ({ animation, isOpen, ...rest }) =>
+  Pick<PopoverProps, 'animation' | 'isOpen' | 'zIndex'> & WithChildrenProp
+> = ({ animation, isOpen, zIndex, ...rest }) =>
   animation ? (
     <AnimatePresence>
       {isOpen && (
-        <BodyPortal>
+        <BodyPortal zIndex={zIndex}>
           <motion.div
             animate={{ opacity: 1 }}
             exit={{ opacity: 0 }}
@@ -81,7 +81,7 @@ export const PopoverPortal: React.FC<
       )}
     </AnimatePresence>
   ) : (
-    <BodyPortal {...rest} />
+    <BodyPortal zIndex={zIndex} {...rest} />
   );
 
 export type PopoverContainerProps = Pick<PopoverProps, 'position' | 'align'>;
diff --git a/packages/gamut/src/Popover/types.tsx b/packages/gamut/src/Popover/types.tsx
index b85d4d4595c..40807e752ff 100755
--- a/packages/gamut/src/Popover/types.tsx
+++ b/packages/gamut/src/Popover/types.tsx
@@ -113,4 +113,9 @@ export type PopoverProps = PopoverBaseProps &
      * Whether to add width restrictions to Popover.
      */
     widthRestricted?: boolean;
+
+    /**
+     * z-index for the Popover's portal. Defaults to 1.
+     */
+    zIndex?: number;
   };
diff --git a/packages/gamut/src/Tip/shared/FloatingTip.tsx b/packages/gamut/src/Tip/shared/FloatingTip.tsx
index c251d1570cf..41a1a33000d 100644
--- a/packages/gamut/src/Tip/shared/FloatingTip.tsx
+++ b/packages/gamut/src/Tip/shared/FloatingTip.tsx
@@ -36,6 +36,7 @@ export const FloatingTip: React.FC<TipWrapperProps> = ({
   type,
   username,
   wrapperRef,
+  zIndex,
 }) => {
   const ref = useRef<HTMLDivElement>(null);
 
@@ -172,6 +173,7 @@ export const FloatingTip: React.FC<TipWrapperProps> = ({
         targetRef={ref}
         variant="secondary"
         widthRestricted={false}
+        zIndex={zIndex}
       >
         <FloatingTipTextWrapper
           horizNarrow={narrow && isHorizontalCenter}
diff --git a/packages/gamut/src/Tip/shared/types.tsx b/packages/gamut/src/Tip/shared/types.tsx
index a91c5e6a6f7..887a064a721 100644
--- a/packages/gamut/src/Tip/shared/types.tsx
+++ b/packages/gamut/src/Tip/shared/types.tsx
@@ -51,14 +51,16 @@ export interface TipNewBaseProps {
    * If ToolTipWrapper should inherit the dimensions of the parent element. Can only be used for inline tips.
    */
   inheritDims?: boolean;
+  /**
+   * z-index for the tip's portal. Defaults to 1.
+   */
+  zIndex?: number;
 }
 export interface TipInlineProps extends TipNewBaseProps {
   placement?: 'inline';
-  zIndex?: number;
 }
 export interface TipFloatingProps extends TipNewBaseProps {
   placement: 'floating';
-  zIndex?: never;
   inheritDims?: never;
 }
 
@@ -83,5 +85,4 @@ export type TipPlacementComponentProps = Omit<
     | ((node: HTMLDivElement | null) => void);
   type: 'info' | 'tool' | 'preview';
   wrapperRef?: React.RefObject<HTMLDivElement>;
-  zIndex?: number;
 } & React.PropsWithChildren;
diff --git a/packages/styleguide/src/lib/Molecules/Coachmark/Coachmark.mdx b/packages/styleguide/src/lib/Molecules/Coachmark/Coachmark.mdx
index 381e882de7e..c4962dfd8bf 100644
--- a/packages/styleguide/src/lib/Molecules/Coachmark/Coachmark.mdx
+++ b/packages/styleguide/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} />
diff --git a/packages/styleguide/src/lib/Molecules/Coachmark/Coachmark.stories.tsx b/packages/styleguide/src/lib/Molecules/Coachmark/Coachmark.stories.tsx
index 126306353ec..3c14c2a86ed 100644
--- a/packages/styleguide/src/lib/Molecules/Coachmark/Coachmark.stories.tsx
+++ b/packages/styleguide/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>
+    );
+  },
+};
diff --git a/packages/styleguide/src/lib/Molecules/Modals/Modal/Modal.mdx b/packages/styleguide/src/lib/Molecules/Modals/Modal/Modal.mdx
index ad0ff55a868..7a6b2eabfe5 100644
--- a/packages/styleguide/src/lib/Molecules/Modals/Modal/Modal.mdx
+++ b/packages/styleguide/src/lib/Molecules/Modals/Modal/Modal.mdx
@@ -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).
diff --git a/packages/styleguide/src/lib/Molecules/Modals/Overlay/Overlay.mdx b/packages/styleguide/src/lib/Molecules/Modals/Overlay/Overlay.mdx
index 58af32ec62d..fc8a6327120 100644
--- a/packages/styleguide/src/lib/Molecules/Modals/Overlay/Overlay.mdx
+++ b/packages/styleguide/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} />
diff --git a/packages/styleguide/src/lib/Molecules/Modals/Overlay/Overlay.stories.tsx b/packages/styleguide/src/lib/Molecules/Modals/Overlay/Overlay.stories.tsx
index cc24ef064c6..a6c9e9aedce 100644
--- a/packages/styleguide/src/lib/Molecules/Modals/Overlay/Overlay.stories.tsx
+++ b/packages/styleguide/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>
+    );
+  },
+};
diff --git a/packages/styleguide/src/lib/Molecules/Tips/InfoTip/InfoTip.mdx b/packages/styleguide/src/lib/Molecules/Tips/InfoTip/InfoTip.mdx
index 15b440bf553..903042c971f 100644
--- a/packages/styleguide/src/lib/Molecules/Tips/InfoTip/InfoTip.mdx
+++ b/packages/styleguide/src/lib/Molecules/Tips/InfoTip/InfoTip.mdx
@@ -82,9 +82,24 @@ InfoTips have intelligent Escape key handling that works correctly both inside a
 
 <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} />
 
diff --git a/packages/styleguide/src/lib/Molecules/Tips/InfoTip/InfoTip.stories.tsx b/packages/styleguide/src/lib/Molecules/Tips/InfoTip/InfoTip.stories.tsx
index 66807b72d2b..4f806892d19 100644
--- a/packages/styleguide/src/lib/Molecules/Tips/InfoTip/InfoTip.stories.tsx
+++ b/packages/styleguide/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>
   ),
 };
diff --git a/packages/styleguide/src/lib/Molecules/Tips/PreviewTip/PreviewTip.mdx b/packages/styleguide/src/lib/Molecules/Tips/PreviewTip/PreviewTip.mdx
index 6889298460f..df0b228b230 100644
--- a/packages/styleguide/src/lib/Molecules/Tips/PreviewTip/PreviewTip.mdx
+++ b/packages/styleguide/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} />
diff --git a/packages/styleguide/src/lib/Molecules/Tips/PreviewTip/PreviewTip.stories.tsx b/packages/styleguide/src/lib/Molecules/Tips/PreviewTip/PreviewTip.stories.tsx
index 5095548c279..011aa49406c 100644
--- a/packages/styleguide/src/lib/Molecules/Tips/PreviewTip/PreviewTip.stories.tsx
+++ b/packages/styleguide/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>
+  ),
+};
diff --git a/packages/styleguide/src/lib/Molecules/Tips/ToolTip/ToolTip.mdx b/packages/styleguide/src/lib/Molecules/Tips/ToolTip/ToolTip.mdx
index b6b991b5cd7..eb601570601 100644
--- a/packages/styleguide/src/lib/Molecules/Tips/ToolTip/ToolTip.mdx
+++ b/packages/styleguide/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} />
diff --git a/packages/styleguide/src/lib/Molecules/Tips/ToolTip/ToolTip.stories.tsx b/packages/styleguide/src/lib/Molecules/Tips/ToolTip/ToolTip.stories.tsx
index d4fa6f4133e..b43691ec466 100644
--- a/packages/styleguide/src/lib/Molecules/Tips/ToolTip/ToolTip.stories.tsx
+++ b/packages/styleguide/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>
+  ),
+};