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

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.86d3e6.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@78.5.4...@codecademy/styleguide@78.5.5-alpha.86d3e6.0) (2026-01-06)
+### [78.5.5-alpha.ebe1b3.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@78.5.4...@codecademy/styleguide@78.5.5-alpha.ebe1b3.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.86d3e6.0",
+  "version": "78.5.5-alpha.ebe1b3.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "2988ef3b1571897c2359c9031389d08356b819be"
+  "gitHead": "873587dd5513aace45c681f478a5ceb4de320604"
 }

package/src/lib/Atoms/FormElements/FormGroup/FormGroup.mdx

@@ -69,6 +69,12 @@ A field can include <LinkTo id="Molecules/Tips/InfoTip"> our existing `InfoTip`<
 
 <Canvas of={FormGroupStories.HighEmphasisInfoTip} />
 
+#### Accessibility
+
+InfoTip buttons are automatically labelled by string field labels for accessibility.
+
+<Canvas of={FormGroupStories.InfoTipAutoLabelling} />
+
 ## Playground
 
 <Canvas sourceState="shown" of={FormGroupStories.Default} />

package/src/lib/Atoms/FormElements/FormGroup/FormGroup.stories.tsx

@@ -97,3 +97,14 @@ export const HighEmphasisInfoTip: Story = {
     children: <Input />,
   },
 };
+
+export const InfoTipAutoLabelling: Story = {
+  args: {
+    label: 'Email address',
+    htmlFor: 'auto-label-input',
+    infotip: {
+      info: 'We will never share your email with third parties.',
+    },
+    children: <Input htmlFor="auto-label-input" type="email" />,
+  },
+};

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

@@ -94,12 +94,6 @@ 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 { Box, Coachmark, FillButton, FlexBox, Text } from '@codecademy/gamut';
+import { 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,39 +197,3 @@ 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/Modals/Modal/Modal.mdx

@@ -89,16 +89,6 @@ 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,12 +32,6 @@ 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 { Box, FillButton, FlexBox, Overlay, Text } from '@codecademy/gamut';
-import type { Meta, StoryObj } from '@storybook/react';
+import { FillButton, FlexBox, Overlay, Text } from '@codecademy/gamut';
+import type { Meta } from '@storybook/react';
 import { useEffect, useState } from 'react';
 
 const meta: Meta<typeof Overlay> = {
@@ -8,7 +8,6 @@ const meta: Meta<typeof Overlay> = {
 };
 
 export default meta;
-type Story = StoryObj<typeof Overlay>;
 
 export const Default: React.FC<React.ComponentProps<typeof Overlay>> = (
   args
@@ -35,67 +34,3 @@ 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/Tips/InfoTip/InfoTip.mdx

@@ -28,8 +28,7 @@ export const parameters = {
 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.
-
-Infotip consists of an icon button and the .tip-bg subcomponent. The info button has low and high emphasis variants and the `.tip` has 4 alignment variants.
+The info button has low and high emphasis variants and the `Tip` has 4 alignment variants.
 
 ## Variants
 
@@ -57,16 +56,18 @@ This `floating` variant should only be used as needed.
 
 ### InfoTips with links or buttons
 
-Links or buttons within InfoTips should be used sparingly and only when the information is critical to the user's understanding of the content. If an infotip _absolutely requires_ a link or button, it needs to provide a programmatic focus by way of the `onClick` prop. The `onClick` prop accepts a function that can accept an `{isTipHidden}` argument and using that you can set programmatic focus as needed.
+Links or buttons within InfoTips should be used sparingly and only when the information is critical to the user's understanding of the content. When an InfoTip opens, focus automatically moves to the tip content, allowing keyboard users to immediately interact with any links or buttons inside.
 
 <Canvas of={InfoTipStories.WithLinksOrButtons} />
 
-### Floating placement
+### Automatic Focus Management
 
-When using `placement="floating"`, InfoTips implements focus management for easier navigation:
+InfoTips automatically manage focus for optimal keyboard accessibility:
 
-- **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
+- **Opening**: Focus automatically moves to the tip content when opened
+- **Tab (Floating)**: Navigate forward through focusable elements (links, buttons) inside the tip. When reaching the last element, wraps back to the InfoTip button
+- **Shift+Tab (Floating)**: Navigate backward naturally - from the button, exits to the previous page element
+- **Tab/Shift+Tab (Inline)**: Follows normal document flow
 - **Escape**: Closes the tip and returns focus to the InfoTip button
 
 <Canvas of={InfoTipStories.KeyboardNavigation} />
@@ -93,13 +94,13 @@ The InfoTip button's accessible label can be customized using either prop:
 
 ### 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.
+The `InfoTipButton` uses [`aria-roledescription`](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. This defaults to `"More information button"` but can be customized via the `ariaRoleDescription` prop for translation or other accessibility needs.
 
 <Canvas of={InfoTipStories.AriaLabel} />
 
-## Z-Index
+## InfoTips and zIndex
 
-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.
+You can change the zIndex of your `InfoTip` with the zIndex property.
 
 <Canvas of={InfoTipStories.ZIndex} />
 

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

@@ -1,21 +1,23 @@
 import {
   Anchor,
   Box,
-  Coachmark,
   FillButton,
   FlexBox,
   GridBox,
+  IconButton,
   InfoTip,
   Modal,
   Text,
 } from '@codecademy/gamut';
+import { SparkleIcon } from '@codecademy/gamut-icons';
 import type { Meta, StoryObj } from '@storybook/react';
-import { useRef, useState } from 'react';
+import { useState } from 'react';
 
 const meta: Meta<typeof InfoTip> = {
   component: InfoTip,
   args: {
     alignment: 'top-left',
+    ariaLabel: 'More information',
     info: `I am additional information about a nearby element or content.`,
   },
 };
@@ -29,7 +31,10 @@ export const Emphasis: Story = {
   },
   render: (args) => (
     <FlexBox center m={24} py={64}>
-      <Text mr={4}>Some text that needs info</Text> <InfoTip {...args} />
+      <Text id="emphasis-text" mr={4}>
+        Some text that needs info
+      </Text>
+      <InfoTip {...args} ariaLabelledby="emphasis-text" />
     </FlexBox>
   ),
 };
@@ -39,10 +44,15 @@ export const Alignments: Story = {
     <GridBox gap={24} gridTemplateColumns="1fr 1fr" ml={8} py={64}>
       {(['top-right', 'top-left', 'bottom-right', 'bottom-left'] as const).map(
         (alignment) => {
+          const labelId = `alignment-${alignment}`;
           return (
             <Box key={alignment}>
-              <Text>{alignment}</Text>
-              <InfoTip {...args} alignment={alignment} />
+              <Text id={labelId}>{alignment}</Text>
+              <InfoTip
+                {...args}
+                alignment={alignment}
+                ariaLabelledby={labelId}
+              />
             </Box>
           );
         }
@@ -57,10 +67,51 @@ export const Placement: Story = {
   },
   render: (args) => (
     <FlexBox center>
-      <Text mr={4}>
+      <Text id="placement-text" mr={4}>
         This text is in a small space and needs floating placement
       </Text>{' '}
-      <InfoTip {...args} />
+      <InfoTip {...args} ariaLabelledby="placement-text" />
+    </FlexBox>
+  ),
+};
+
+export const AriaLabel: Story = {
+  render: (args) => (
+    <FlexBox center column gap={24} my={48} width={1}>
+      <FlexBox alignItems="center" gap={8}>
+        <Text fontSize={16} fontWeight="bold">
+          Using ariaLabel (no visible label text):
+        </Text>
+      </FlexBox>
+      <FlexBox alignItems="center" gap={8}>
+        <IconButton
+          icon={SparkleIcon}
+          tip="This tool needs to be explained in the InfoTip"
+          tipProps={{ placement: 'floating' }}
+          onClick={() => null}
+        />
+        <InfoTip
+          {...args}
+          ariaLabel="Learn more about this tool"
+          info="This is some helpful info about the tool represented by the IconButton"
+        />
+      </FlexBox>
+
+      <FlexBox alignItems="center" gap={8}>
+        <Text fontSize={16} fontWeight="bold">
+          Using ariaLabelledby (references visible text):
+        </Text>
+      </FlexBox>
+      <FlexBox alignItems="center" gap={8}>
+        <Text id="custom-info-id">
+          I am some helpful yet concise text that needs more explanation
+        </Text>
+        <InfoTip
+          alignment="bottom-left"
+          ariaLabelledby="custom-info-id"
+          info="I am clarifying information related to the concise text."
+        />
+      </FlexBox>
     </FlexBox>
   ),
 };
@@ -70,19 +121,16 @@ export const WithLinksOrButtons: Story = {
     placement: 'floating',
   },
   render: function WithLinksOrButtons(args) {
-    const ref = useRef<HTMLDivElement>(null);
-
-    const onClick = ({ isTipHidden }: { isTipHidden: boolean }) => {
-      if (!isTipHidden) ref.current?.focus();
-    };
-
     return (
       <FlexBox center py={64}>
-        <Text mr={4}>This text is in a small space and needs info </Text>{' '}
+        <Text id="links-text" mr={4}>
+          This text is in a small space and needs info
+        </Text>{' '}
         <InfoTip
           {...args}
+          ariaLabelledby="links-text"
           info={
-            <Text ref={ref} tabIndex={-1}>
+            <Text tabIndex={-1}>
               Hey! Here is a{' '}
               <Anchor href="https://giphy.com/search/nichijou">
                 cool link
@@ -94,7 +142,6 @@ export const WithLinksOrButtons: Story = {
               that is also super important.
             </Text>
           }
-          onClick={onClick}
         />
       </FlexBox>
     );
@@ -103,42 +150,35 @@ export const WithLinksOrButtons: Story = {
 
 export const KeyboardNavigation: Story = {
   render: function KeyboardNavigation() {
-    const floatingRef = useRef<HTMLDivElement>(null);
-    const inlineRef = useRef<HTMLDivElement>(null);
-
     const examples = [
       {
         title: 'Floating Placement',
         placement: 'floating' as const,
-        ref: floatingRef,
         links: ['Link 1', 'Link 2', 'Link 3'],
       },
       {
         title: 'Inline Placement',
         placement: 'inline' as const,
         alignment: 'bottom-right' as const,
-        ref: inlineRef,
         links: ['Link A', 'Link B'],
       },
     ];
 
     return (
-      <FlexBox center column gap={24} py={64}>
+      <FlexBox center flexDirection="column" gap={24} py={64}>
         <GridBox gap={16} gridTemplateColumns="1fr 1fr">
-          {examples.map(({ title, placement, alignment, ref, links }) => {
-            const onClick = ({ isTipHidden }: { isTipHidden: boolean }) => {
-              if (!isTipHidden) ref.current?.focus();
-            };
-
+          {examples.map(({ title, placement, alignment, links }) => {
+            const labelId = `keyboard-nav-${placement}`;
             return (
               <FlexBox gap={8} key={placement}>
-                <Text fontSize={16} fontWeight="bold">
+                <Text fontSize={16} fontWeight="bold" id={labelId}>
                   {title}
                 </Text>
                 <InfoTip
                   alignment={alignment}
+                  ariaLabelledby={labelId}
                   info={
-                    <Text ref={ref} tabIndex={-1}>
+                    <Text>
                       {links.map((label, idx) => (
                         <>
                           {idx > 0 && ', '}
@@ -151,7 +191,6 @@ export const KeyboardNavigation: Story = {
                     </Text>
                   }
                   placement={placement}
-                  onClick={onClick}
                 />
               </FlexBox>
             );
@@ -163,6 +202,10 @@ export const KeyboardNavigation: Story = {
             Keyboard Navigation:
           </Text>
           <Box as="ul" fontSize={14} pl={16}>
+            <li>
+              <strong>Opening:</strong> Focus automatically moves to the tip
+              content when opened
+            </li>
             <li>
               <strong>Floating - Tab:</strong> Navigates forward through links,
               then wraps to button (contained)
@@ -196,7 +239,6 @@ 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}>
@@ -226,8 +268,10 @@ export const InfoTipInsideModal: Story = {
             <Text>This modal contains an InfoTip below:</Text>
 
             <FlexBox alignItems="center" gap={8}>
-              <Text>Some text that needs explanation</Text>
-              <InfoTip {...args} />
+              <Text id="modal-infotip-text">
+                Some text that needs explanation
+              </Text>
+              <InfoTip {...args} ariaLabelledby="modal-infotip-text" />
             </FlexBox>
 
             <Text color="text-disabled" fontSize={14}>
@@ -235,37 +279,6 @@ 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>
@@ -278,49 +291,22 @@ export const InfoTipInsideModal: Story = {
 
 export const ZIndex: Story = {
   args: {
-    info: 'I have a custom z-index',
+    info: 'I am inline, cool',
     zIndex: 5,
   },
   render: (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 center flexDirection="column" m={24} py={64}>
+      <Box bg="paleBlue" zIndex={3}>
+        I will not be behind the infotip, sad + unreadable
+      </Box>
+      <InfoTip
+        ariaLabel="z-index example without override"
+        info="I am inline, cool"
+      />
+      <Box bg="paleBlue" zIndex={3}>
+        I will be behind the infotip, nice + great
+      </Box>
+      <InfoTip {...args} ariaLabel="z-index example with override" />
     </FlexBox>
   ),
 };
@@ -328,7 +314,10 @@ export const ZIndex: Story = {
 export const Default: Story = {
   render: (args) => (
     <FlexBox center m={24} py={64}>
-      <Text mr={4}>Some text that needs info</Text> <InfoTip {...args} />
+      <Text id="default-text" mr={4}>
+        Some text that needs info
+      </Text>
+      <InfoTip {...args} ariaLabelledby="default-text" />
     </FlexBox>
   ),
 };

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

@@ -55,12 +55,6 @@ 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, Text } from '@codecademy/gamut';
+import { Box, FlexBox, PreviewTip } from '@codecademy/gamut';
 import { SmileyIndifferentIcon } from '@codecademy/gamut-icons';
 import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
@@ -110,70 +110,3 @@ 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,12 +63,6 @@ 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,10 +1,8 @@
 import {
-  Box,
   FillButton,
   FlexBox,
   IconButton,
   StrokeButton,
-  Text,
   ToolTip,
 } from '@codecademy/gamut';
 import {
@@ -135,60 +133,3 @@ 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/src/lib/Organisms/ConnectedForm/ConnectedFormGroup/ConnectedFormGroup.mdx

@@ -61,6 +61,26 @@ A `ConnectedFormGroup` can be in one of three states: `default`, `error`, or `di
 
 <Canvas of={ConnectedFormGroupStories.States} />
 
+## InfoTip
+
+A `ConnectedFormGroup` can include an `infotip` prop to provide additional context.
+
+### Automatic labelling
+
+InfoTip buttons are automatically labelled by string field labels for accessibility.
+
+<Canvas of={ConnectedFormGroupStories.InfoTipAutoLabelling} />
+
+### ReactNode labels
+
+For ReactNode labels (e.g., styled text or icons), you have three options:
+
+- `labelledByFieldLabel: true` - opt into automatic labelling by the field label
+- `ariaLabel` - provide a custom accessible name
+- `ariaLabelledby` - reference another element on the page, such as a section heading
+
+<Canvas of={ConnectedFormGroupStories.InfoTipWithReactNodeLabel} />
+
 ## Playground
 
 To see how a `ConnectedFormGroup` can be used in a `ConnectedForm`, check out the <LinkTo id="Organisms/ConnectedForm/ConnectedForm">ConnectedForm</LinkTo> page.

package/src/lib/Organisms/ConnectedForm/ConnectedFormGroup/ConnectedFormGroup.stories.tsx

@@ -2,7 +2,9 @@ import {
   ConnectedForm,
   ConnectedFormGroup,
   ConnectedFormGroupProps,
+  ConnectedInput,
   ConnectedRadioGroupInput,
+  Text,
   useConnectedForm,
 } from '@codecademy/gamut';
 import { action } from '@storybook/addon-actions';
@@ -119,3 +121,85 @@ export const States = () => {
     </ConnectedForm>
   );
 };
+
+/**
+ * InfoTip buttons are automatically labelled by string field labels for accessibility.
+ * Screen readers will announce "Field Label, button" when focusing the InfoTip.
+ */
+export const InfoTipAutoLabelling: Story = {
+  render: () => (
+    <ConnectedForm
+      defaultValues={{ email: '' }}
+      onSubmit={(values) => action('Form Submitted')(values)}
+    >
+      <ConnectedFormGroup
+        field={{ component: ConnectedInput, type: 'email' }}
+        infotip={{
+          info: 'We will never share your email with third parties.',
+          placement: 'floating',
+        }}
+        label="Email address"
+        name="email"
+      />
+    </ConnectedForm>
+  ),
+};
+
+/**
+ * For ReactNode labels, you have three options for accessible InfoTip labelling:
+ * - `labelledByFieldLabel: true` - uses the field label
+ * - `ariaLabel` - provides a custom accessible name
+ * - `ariaLabelledby` - references another element on the page
+ */
+export const InfoTipWithReactNodeLabel: Story = {
+  render: () => (
+    <ConnectedForm
+      defaultValues={{ username: '', password: '', apiKey: '' }}
+      onSubmit={(values) => action('Form Submitted')(values)}
+    >
+      <Text as="h3" id="api-section-heading" mb={8}>
+        API Configuration
+      </Text>
+      <ConnectedFormGroup
+        field={{ component: ConnectedInput }}
+        infotip={{
+          alignment: 'top-left',
+          info: 'Choose a unique username between 3-20 characters.',
+          labelledByFieldLabel: true,
+        }}
+        label={
+          <Text as="span" fontWeight="bold">
+            Username (labelledByFieldLabel)
+          </Text>
+        }
+        name="username"
+      />
+      <ConnectedFormGroup
+        field={{ component: ConnectedInput, type: 'password' }}
+        infotip={{
+          info: 'Password must be at least 8 characters with one uppercase letter and one number.',
+          ariaLabel: 'Password requirements',
+        }}
+        label={
+          <Text as="span" fontWeight="bold">
+            Password (ariaLabel)
+          </Text>
+        }
+        name="password"
+      />
+      <ConnectedFormGroup
+        field={{ component: ConnectedInput }}
+        infotip={{
+          info: 'You can find your API key in the developer settings dashboard.',
+          ariaLabelledby: 'api-section-heading',
+        }}
+        label={
+          <Text as="span" fontWeight="bold">
+            API Key (ariaLabelledby)
+          </Text>
+        }
+        name="apiKey"
+      />
+    </ConnectedForm>
+  ),
+};

package/src/lib/Organisms/GridForm/Fields.mdx

@@ -95,3 +95,23 @@ Hidden inputs can be used to include data that users can't see or modify with th
 We call it a "sweet container" so that bots do not immediately detect it as a honeypot input.
 
 <Canvas of={FieldsStories.SweetContainer} />
+
+## InfoTip
+
+Any field can include an `infotip` prop to provide additional context to users.
+
+### Automatic labelling
+
+InfoTip buttons are automatically labelled by string field labels for accessibility.
+
+<Canvas of={FieldsStories.InfoTipAutoLabelling} />
+
+### ReactNode labels
+
+For ReactNode labels, you have three options:
+
+- `labelledByFieldLabel: true` - opt into automatic labelling by the field label
+- `ariaLabel` - provide a custom accessible name
+- `ariaLabelledby` - reference another element on the page, such as a section heading
+
+<Canvas of={FieldsStories.InfoTipWithReactNodeLabel} />

package/src/lib/Organisms/GridForm/Fields.stories.tsx

@@ -1,4 +1,4 @@
-import { FormGroup, GridForm, Input } from '@codecademy/gamut';
+import { FormGroup, GridForm, Input, Text } from '@codecademy/gamut';
 import { action } from '@storybook/addon-actions';
 import type { Meta, StoryObj } from '@storybook/react';
 
@@ -328,3 +328,75 @@ export const SweetContainer: Story = {
     ],
   },
 };
+
+/**
+ * InfoTip buttons are automatically labelled by string field labels for accessibility.
+ * Screen readers will announce "Field Label, button" when focusing the InfoTip.
+ */
+export const InfoTipAutoLabelling: Story = {
+  args: {
+    fields: [
+      {
+        label: 'Email address',
+        name: 'email',
+        size: 9,
+        type: 'email',
+        infotip: {
+          info: 'We will never share your email with third parties.',
+          placement: 'floating',
+        },
+      },
+    ],
+  },
+};
+
+/**
+ * For ReactNode labels, you have three options for accessible InfoTip labelling:
+ * - `labelledByFieldLabel: true` - uses the field label
+ * - `ariaLabel` - provides a custom accessible name
+ * - `ariaLabelledby` - references another element on the page
+ */
+export const InfoTipWithReactNodeLabel: Story = {
+  render: (args) => (
+    <>
+      <Text as="h3" id="api-section-heading" mb={8}>
+        API Configuration
+      </Text>
+      <GridForm {...args} />
+    </>
+  ),
+  args: {
+    fields: [
+      {
+        label: <strong>Username (labelledByFieldLabel)</strong>,
+        name: 'username',
+        size: 9,
+        type: 'text',
+        infotip: {
+          info: 'Choose a unique username between 3-20 characters.',
+          labelledByFieldLabel: true,
+        },
+      },
+      {
+        label: <strong>Password (ariaLabel)</strong>,
+        name: 'password',
+        size: 9,
+        type: 'password',
+        infotip: {
+          info: 'Password must be at least 8 characters with one uppercase letter and one number.',
+          ariaLabel: 'Password requirements',
+        },
+      },
+      {
+        label: <strong>API Key (ariaLabelledby)</strong>,
+        name: 'apiKey',
+        size: 9,
+        type: 'text',
+        infotip: {
+          info: 'You can find your API key in the developer settings dashboard.',
+          ariaLabelledby: 'api-section-heading',
+        },
+      },
+    ],
+  },
+};

package/src/lib/Organisms/GridForm/Layout.mdx

@@ -34,7 +34,7 @@ Solo field form should always have their solo input be required. They should aut
 
 ## InfoTips
 
-A field can include our existing `InfoTip`. See the <LinkTo id="Molecules/Tips/InfoTip">InfoTip</LinkTo> story for more information on what props are available.
+A field can include our existing `InfoTip`. See the <LinkTo id="Molecules/Tips/InfoTip">Fields</LinkTo> story for specific accessibility tooling and <LinkTo id="Molecules/Tips/InfoTip">InfoTip</LinkTo> story for more information on what props are available.
 
 See the <LinkTo id="Atoms/FormInputs/Radio">Radio</LinkTo> story for an example of how to add a infotip to a radio option.