@codecademy/styleguide 78.5.6-alpha.a75de2.0 → 78.5.6-alpha.d3472d.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.6-alpha.a75de2.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@78.5.5...@codecademy/styleguide@78.5.6-alpha.a75de2.0) (2026-01-21)
+### [78.5.6-alpha.d3472d.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@78.5.5...@codecademy/styleguide@78.5.6-alpha.d3472d.0) (2026-01-23)
 
 **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.6-alpha.a75de2.0",
+  "version": "78.5.6-alpha.d3472d.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "b0f3823000ff2ed508f751b873066bf628086467"
+  "gitHead": "05ae7677a91ab165f0feb40a8b984397e27f26be"
 }

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

@@ -69,12 +69,6 @@ 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,14 +97,3 @@ 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/Tips/InfoTip/InfoTip.mdx

@@ -28,7 +28,8 @@ export const parameters = {
 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.
 
 Use an infotip to provide additional info about a nearby element or content.
-The info button has low and high emphasis variants and the `Tip` has 4 alignment variants.
+
+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.
 
 ## Variants
 
@@ -56,19 +57,17 @@ 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. When an InfoTip opens, focus automatically moves to the tip content, allowing keyboard users to immediately interact with any links or buttons inside.
+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.
 
 <Canvas of={InfoTipStories.WithLinksOrButtons} />
 
-### Automatic Focus Management
+### Floating placement
 
-InfoTips automatically manage focus for optimal keyboard accessibility:
+When using `placement="floating"`, InfoTips implements focus management for easier navigation:
 
-- **Opening**: Focus automatically moves to the tip content when opened
-- ** <KeyboardKey>Tab</KeyboardKey> (Floating)**: Navigate forward through focusable elements (links, buttons) inside the tip. When reaching the last element, wraps back to the InfoTip button
-- **<KeyboardKey>Shift </KeyboardKey> + <KeyboardKey>Tab</KeyboardKey> (Floating)**: Navigate backward naturally - from the button, exits to the previous page element
-- **<KeyboardKey>Tab</KeyboardKey> or <KeyboardKey>Shift</KeyboardKey> +<KeyboardKey>Tab</KeyboardKey> (Inline)**: Follows normal document flow
-- **<KeyboardKey>Escape</KeyboardKey>**: Closes the tip and returns focus to the InfoTip button
+- **<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
 
 <Canvas of={InfoTipStories.KeyboardNavigation} />
 
@@ -83,21 +82,6 @@ InfoTips have intelligent Escape key handling that works correctly both inside a
 
 <Canvas of={InfoTipStories.InfoTipInsideModal} />
 
-## Custom Accessible Labeling
-
-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`](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} />
-
 ## InfoTips and zIndex
 
 You can change the zIndex of your `InfoTip` with the zIndex property.

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

@@ -4,20 +4,17 @@ import {
   FillButton,
   FlexBox,
   GridBox,
-  IconButton,
   InfoTip,
   Modal,
   Text,
 } from '@codecademy/gamut';
-import { SparkleIcon } from '@codecademy/gamut-icons';
 import type { Meta, StoryObj } from '@storybook/react';
-import { useState } from 'react';
+import { useRef, 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.`,
   },
 };
@@ -31,10 +28,7 @@ export const Emphasis: Story = {
   },
   render: (args) => (
     <FlexBox center m={24} py={64}>
-      <Text id="emphasis-text" mr={4}>
-        Some text that needs info
-      </Text>
-      <InfoTip {...args} ariaLabelledby="emphasis-text" />
+      <Text mr={4}>Some text that needs info</Text> <InfoTip {...args} />
     </FlexBox>
   ),
 };
@@ -44,15 +38,10 @@ 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 id={labelId}>{alignment}</Text>
-              <InfoTip
-                {...args}
-                alignment={alignment}
-                ariaLabelledby={labelId}
-              />
+              <Text>{alignment}</Text>
+              <InfoTip {...args} alignment={alignment} />
             </Box>
           );
         }
@@ -67,51 +56,10 @@ export const Placement: Story = {
   },
   render: (args) => (
     <FlexBox center>
-      <Text id="placement-text" mr={4}>
+      <Text mr={4}>
         This text is in a small space and needs floating placement
       </Text>{' '}
-      <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>
+      <InfoTip {...args} />
     </FlexBox>
   ),
 };
@@ -121,16 +69,19 @@ 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 id="links-text" mr={4}>
-          This text is in a small space and needs info
-        </Text>{' '}
+        <Text mr={4}>This text is in a small space and needs info </Text>{' '}
         <InfoTip
           {...args}
-          ariaLabelledby="links-text"
           info={
-            <Text tabIndex={-1}>
+            <Text ref={ref} tabIndex={-1}>
               Hey! Here is a{' '}
               <Anchor href="https://giphy.com/search/nichijou">
                 cool link
@@ -142,6 +93,7 @@ export const WithLinksOrButtons: Story = {
               that is also super important.
             </Text>
           }
+          onClick={onClick}
         />
       </FlexBox>
     );
@@ -150,35 +102,42 @@ 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 flexDirection="column" gap={24} py={64}>
+      <FlexBox center column gap={24} py={64}>
         <GridBox gap={16} gridTemplateColumns="1fr 1fr">
-          {examples.map(({ title, placement, alignment, links }) => {
-            const labelId = `keyboard-nav-${placement}`;
+          {examples.map(({ title, placement, alignment, ref, links }) => {
+            const onClick = ({ isTipHidden }: { isTipHidden: boolean }) => {
+              if (!isTipHidden) ref.current?.focus();
+            };
+
             return (
               <FlexBox gap={8} key={placement}>
-                <Text fontSize={16} fontWeight="bold" id={labelId}>
+                <Text fontSize={16} fontWeight="bold">
                   {title}
                 </Text>
                 <InfoTip
                   alignment={alignment}
-                  ariaLabelledby={labelId}
                   info={
-                    <Text>
+                    <Text ref={ref} tabIndex={-1}>
                       {links.map((label, idx) => (
                         <>
                           {idx > 0 && ', '}
@@ -191,6 +150,7 @@ export const KeyboardNavigation: Story = {
                     </Text>
                   }
                   placement={placement}
+                  onClick={onClick}
                 />
               </FlexBox>
             );
@@ -202,10 +162,6 @@ 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)
@@ -268,10 +224,8 @@ export const InfoTipInsideModal: Story = {
             <Text>This modal contains an InfoTip below:</Text>
 
             <FlexBox alignItems="center" gap={8}>
-              <Text id="modal-infotip-text">
-                Some text that needs explanation
-              </Text>
-              <InfoTip {...args} ariaLabelledby="modal-infotip-text" />
+              <Text>Some text that needs explanation</Text>
+              <InfoTip {...args} />
             </FlexBox>
 
             <Text color="text-disabled" fontSize={14}>
@@ -299,14 +253,11 @@ export const ZIndex: Story = {
       <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"
-      />
+      <InfoTip 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" />
+      <InfoTip {...args} />
     </FlexBox>
   ),
 };
@@ -314,10 +265,7 @@ export const ZIndex: Story = {
 export const Default: Story = {
   render: (args) => (
     <FlexBox center m={24} py={64}>
-      <Text id="default-text" mr={4}>
-        Some text that needs info
-      </Text>
-      <InfoTip {...args} ariaLabelledby="default-text" />
+      <Text mr={4}>Some text that needs info</Text> <InfoTip {...args} />
     </FlexBox>
   ),
 };

package/src/lib/Organisms/BarChart/BarChart.mdx

@@ -0,0 +1,455 @@
+import { Canvas, Controls, Meta } from '@storybook/blocks';
+
+import {
+  Callout,
+  ComponentHeader,
+  ImageWrapper,
+  LinkTo,
+} from '~styleguide/blocks';
+
+import * as BarChartStories from './BarChart.stories';
+
+export const parameters = {
+  title: 'BarChart',
+  subtitle: `A horizontal bar chart for visualizing comparative data`,
+  design: {
+    type: 'figma',
+    url: 'https://www.figma.com/design/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=55123-4176',
+  },
+  status: 'updating',
+  source: {
+    repo: 'gamut',
+    githubLink:
+      'https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/BarChart',
+  },
+};
+
+<Meta of={BarChartStories} />
+
+<ComponentHeader {...parameters} />
+
+## Usage
+
+Use BarChart to display comparative data across categories, such as skills progress, XP earned, or any quantitative metrics that benefit from visual comparison.
+
+### Best practices:
+
+- Use consistent units across all bars in a chart
+- Limit the number of bars to maintain readability (5-10 is optimal)
+- Consider using the stacked variant to show progress toward a goal
+- Sort bars by value (descending) when ranking is important
+- Ensure bar colors maintain at least a 3:1 contrast ratio with the background
+
+### When NOT to use:
+
+- **Progress tracking** – for displaying the completion status of a task, use the <LinkTo id="Atoms/ProgressBar">ProgressBar</LinkTo> component.
+
+## Anatomy
+
+<ImageWrapper
+  src="./organisms/barchart.png"
+  alt="The anatomy of the BarChart component, detailed below."
+/>
+
+1. **Bar row**
+
+- Represents a single category and its values.
+
+2. **Category icon** (optional)
+
+- Use to clarify or reinforce the category name.
+
+3. **Category label**
+
+- Displays gridlines and labels to indicate the scale of the data values.
+- The number of dividers, as well as the minimum and maximum values on the value axis, are adjustable.
+- The minimum value should always be 0.
+
+4. **Series one value**
+
+- Displays the numerical value of the series one bar for clarity and precise data representation.
+
+5. **Series two value** (optional)
+
+- Displays the numerical value of the series two bar for clarity and precise data representation.
+- Include a second series value by using the stacked property. Stacked bar charts compare parts of a whole and are best suited for displaying discrete data segmented into meaningful categories.
+
+6. ** Series one bar**
+
+- A visual representation of the first value for the associated category.
+- By default, the first series bars use the text color, however, it can be overridden to any color.
+- Bars include a required border that uses white or navy, chosen automatically to ensure the highest contrast with the bar color.
+
+8. **Series two bar** _(bars with zero value)_
+
+- A visual representation of the second value for the associated category.
+- By default, the second series bars use the primary color, however, it can be overridden to any color.
+- Bars include a required border that uses white or navy, chosen automatically to ensure the highest contrast with the bar color.
+- Bars include a required border that uses white or navy, chosen automatically to ensure the highest contrast with the bar color.
+
+## Variants
+
+### Simple (Non-stacked)
+
+Use the simple variant when showing single values per category. Only `seriesOneValue` is provided.
+
+<Canvas of={BarChartStories.Default} />
+
+### Stacked
+
+Use the stacked variant when showing progress within a total. Provide both `seriesOneValue` (progress) and `seriesTwoValue` (total).
+
+<Canvas of={BarChartStories.Stacked} />
+
+### With Icons
+
+Add icons to labels for better visual identification of categories.
+
+<Canvas of={BarChartStories.WithIcons} />
+
+### Animated
+
+Enable entrance animations for a more engaging experience.
+
+<Canvas of={BarChartStories.Animated} />
+
+### Interactive
+
+Rows can be made interactive with `onClick` handlers or `href` links.
+
+<Canvas of={BarChartStories.Interactive} />
+
+### Sorting
+
+BarChart includes an optional sorting dropdown in the title area. The dropdown only renders when the `sortFns` prop is provided. You can control which sort options appear by including string literals or custom sort functions in the array.
+
+**String Literals:**
+
+- `'alphabetically'` - Adds both "Label (A-Z)" and "Label (Z-A)" options
+- `'numerically'` - Adds both "Value (Low-High)" and "Value (High-Low)" options
+- `'none'` - Adds "None" option (preserves original order)
+
+**Custom Sort Functions:**
+You can also provide custom sort functions as objects with:
+
+- `label`: The text displayed in the dropdown
+- `value`: A unique identifier for the sort option
+- `sortFn`: A function that takes an array of bars and returns a sorted array
+
+**Type Definition:**
+
+```typescript
+type CustomSortOption<TBar extends BarProps = BarProps> = {
+  label: string;
+  value: string;
+  sortFn: (bars: TBar[]) => TBar[];
+};
+
+// sortFns prop accepts:
+sortFns?: ('alphabetically' | 'numerically' | 'none' | CustomSortOption<TBar>)[]
+```
+
+**Automatic Type Inference:**
+TypeScript automatically infers the bar type from your `barValues` prop. This means custom properties (like `dateAdded`, `category`, etc.) are automatically typed in your sort functions - no type assertions needed!
+
+```typescript
+const barsWithDates = [
+  { yLabel: 'Python', seriesOneValue: 1500, dateAdded: new Date('2023-01-15') },
+  {
+    yLabel: 'JavaScript',
+    seriesOneValue: 2000,
+    dateAdded: new Date('2023-03-20'),
+  },
+  // ...
+];
+
+<BarChart
+  barValues={barsWithDates}
+  sortFns={[
+    {
+      label: 'Recently Added',
+      value: 'recent',
+      sortFn: (bars) => {
+        // TypeScript automatically knows bars have dateAdded property!
+        return [...bars].sort((a, b) => {
+          const aDate = a.dateAdded as Date | undefined;
+          const bDate = b.dateAdded as Date | undefined;
+          if (!aDate || !bDate) return 0;
+          return bDate.getTime() - aDate.getTime();
+        });
+      },
+    },
+  ]}
+/>;
+```
+
+**Note:** Since `BarProps` uses `Record<string, unknown>` for extensibility, custom properties are typed as `unknown` by default. You may need a simple type assertion (`as Date | undefined`) when accessing them, but the property names are fully type-checked.
+
+<Canvas of={BarChartStories.WithSorting} />
+
+**Example with Custom Sort Functions:**
+
+Custom sort functions can access additional properties on `BarProps` for domain-specific sorting, such as sorting by dates or categories.
+
+<Canvas of={BarChartStories.WithCustomSorting} />
+
+When a bar has an `onClick` handler or `href` link, an `aria-label` is automatically generated from the bar's data and applied to the button or link element. The label summarizes the bar's values (e.g., "100 XP in Python" for a simple bar, or "200 XP gained - now at 1500 XP in Python" for a stacked bar).
+
+This ensures that screen reader users receive a clear, data-driven description when interacting with bars, without requiring manual `aria-label` props.
+
+<Canvas of={BarChartStories.WithLinks} />
+
+## Interactive states
+
+BarChart supports both interactive and static bar rows, each with distinct visual states.
+
+### Static bars
+
+When bars have neither `onClick` handlers nor `href` links, they are rendered as static, non-interactive elements.
+
+<Canvas of={BarChartStories.Default} />
+
+### Interactive bars
+
+When bars have `onClick` handlers or `href` links, they become interactive. Interactive bars are rendered as buttons or anchor elements, providing full keyboard accessibility and proper semantic HTML.
+
+<Canvas of={BarChartStories.Interactive} />
+
+## Color modes
+
+BarChart automatically adapts to both light and dark color modes, ensuring proper contrast and readability in all themes. The component uses semantic color tokens that adjust based on the current color mode.  The `styleConfig` prop should be provided by semantic color tokens to ensure the `BarChart` is accessible in all color modes.
+
+## Custom styling
+
+BarChart supports custom color styling through the `styleConfig` prop, allowing you to customize the appearance of chart elements to match your design needs.
+
+### Style configuration options
+
+The `styleConfig` prop accepts an object with the following optional properties:
+
+- **`textColor`**: Color for text labels (y-axis labels). Defaults to `'text'`
+- **`foregroundBarColor`**: Color for the foreground/progress bar (used in stacked charts for `seriesOneValue`). Defaults to `'feedback-warning'`
+- **`backgroundBarColor`**: Color for the background/total bar (used for `seriesTwoValue` in stacked charts, or `seriesOneValue` in simple charts). Defaults to `'background-primary'`
+- **`seriesOneLabel`**: Color for the series one value label (first right label when stacked, or displayValue when not stacked). Defaults to `'text-secondary'`
+- **`seriesTwoLabel`**: Color for the series two value label (displayValue when stacked). Defaults to `'primary'`
+
+All color values should be valid color tokens from the Gamut design system. When customizing colors, ensure they maintain at least a 3:1 contrast ratio with the background for accessibility.
+
+### Default values
+
+If `styleConfig` is not provided, BarChart uses these default colors:
+
+```typescript
+{
+  textColor: 'text',
+  foregroundBarColor: 'feedback-warning',
+  backgroundBarColor: 'background-primary',
+  seriesOneLabel: 'text-secondary',
+  seriesTwoLabel: 'primary',
+}
+```
+
+### Example
+
+<Canvas of={BarChartStories.CustomStyles} />
+
+## Custom scale
+
+BarChart allows you to customize the x-axis scale interval using the `xScale` prop, which controls the spacing and granularity of scale markers along the horizontal axis.
+
+### Scale configuration
+
+The `xScale` prop determines the interval between scale markers on the x-axis. By default, BarChart automatically calculates an appropriate scale interval based on the `minRange` and `maxRange` values. However, you can override this with a custom interval to achieve more granular or specific scale markings.
+
+**When to use custom scale:**
+
+- When you need specific scale intervals (e.g., increments of 250, 500, or 1000)
+- When the automatic scale calculation doesn't provide the desired granularity
+- When you want to match scale intervals across multiple charts for consistency
+- When you need scale markers at specific values for better data interpretation
+
+**How it works:**
+
+The `xScale` value represents the interval between consecutive scale markers. For example:
+
+- `xScale: 250` creates markers at 0, 250, 500, 750, 1000, etc.
+- `xScale: 500` creates markers at 0, 500, 1000, 1500, 2000, etc.
+
+The number of tick marks is automatically calculated as: `Math.ceil((maxRange - minRange) / xScale) + 1`
+
+### Example
+
+<Canvas of={BarChartStories.CustomScale} />
+
+## Accessibility considerations
+
+### Chart and row labeling
+
+**Chart-level labeling:**
+
+- Always provide either `title` or `aria-labelledby` to describe the chart (see Title and description section below for details)
+- The chart is wrapped in a semantic `<figure>` element for proper structure
+
+**Row-level labeling:**
+
+- For non-interactive bars: A hidden text element (visible only to screen readers) is automatically added as the first child of each list item, summarizing the bar's values (e.g., "100 XP in Python")
+- For interactive bars (with `onClick` or `href`): An `aria-label` is automatically generated from the bar's data and applied to the button or link element, ensuring proper screen reader announcements
+- All accessibility labels are automatically generated from the bar's data - no manual `aria-label` props are required
+
+## UX writing
+
+- Keep y-axis labels concise (1-3 words)
+- Use consistent unit labels (e.g., "XP", "hours", "points")
+- Consider locale-aware number formatting for international audiences
+
+### Title and description
+
+The BarChart component uses semantic HTML to provide context and accessibility. The chart is wrapped in a [`<figure>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure) element, and the description is displayed in a [`<figcaption>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption) element. This semantic structure helps screen readers and other assistive technologies understand the relationship between the chart and its description. **Visual title + description is the greatly preferred pattern** for accessibility and user experience.
+
+**Preferred pattern: Visual title + description**
+
+Provide both `title` and `description` props to make the chart's purpose and key takeaways clear to all users:
+
+- `title`: A heading that identifies the chart. Can be a string or an object with `{ as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6', title: string, variant?: Text['variant'] }` to specify the heading level and optionally override the default styling with a <LinkTo id="Typography/Text">Text variant</LinkTo>.
+- `description`: A summary of the information or the overall takeaway displayed in the `<figcaption>` element.
+
+<Canvas of={BarChartStories.WithVisualTitleAndDescription} />
+
+**Alternative patterns:**
+`hideTitle` and `hideDescription` will keep the screenreader text but hide the visual descriptions.
+
+<Canvas of={BarChartStories.WithHiddenTitleAndDescription} />
+
+- **External title with visual description**: Use `aria-labelledby` for the title but show the description visually when the title exists elsewhere but you want to display the description.
+
+<Canvas of={BarChartStories.WithExternalTitle} />
+
+**Best practices:**
+
+- Always provide a `description` prop - it's required and should summarize the chart's key information
+- Use semantic heading levels for titles (h1-h6) to maintain proper document structure
+- When using `aria-labelledby`, ensure the referenced element exists and is properly labeled
+
+## Playground
+
+<Canvas sourceState="shown" of={BarChartStories.Default} />
+
+<Controls />
+
+## Internationalization
+
+<Callout text="We are currently updating global internationalization in Gamut, so the following features are subject to change." />
+
+BarChart supports internationalization through the `translations` prop, which allows you to customize all user-facing strings and configure locale-aware number formatting.
+
+**Translation Structure:**
+
+```typescript
+type BarChartTranslations = {
+  sortLabel: string;
+  sortOptions: {
+    none: string;
+    labelAsc: string;
+    labelDesc: string;
+    valueAsc: string;
+    valueDesc: string;
+  };
+  accessibility: {
+    gainedNowAt: string; // Template: "{value} {unit} gained - now at {value} {unit} in {label}"
+    inLabel: string; // Template: "{value} {unit} in {label}"
+    inOnly: string; // Template: "{value} {unit} in "
+  };
+  locale: string; // For Intl.NumberFormat, e.g., 'en', 'es', 'fr', 'de-DE'
+};
+```
+
+**Basic Usage:**
+
+The `translations` prop is optional and accepts partial translations that will be merged with the default English translations. This means you only need to provide the translations you want to override.
+
+```tsx
+<BarChart
+  title="Habilidades"
+  barValues={barData}
+  description="Progreso de habilidades"
+  minRange={0}
+  maxRange={200}
+  sortFns={['alphabetically', 'none']}
+  translations={{
+    sortLabel: 'Ordenar por:',
+    sortOptions: {
+      none: 'Ninguno',
+      labelAsc: 'Etiqueta (A-Z)',
+      labelDesc: 'Etiqueta (Z-A)',
+      valueAsc: 'Valor (Bajo-Alto)',
+      valueDesc: 'Valor (Alto-Bajo)',
+    },
+    locale: 'es',
+  }}
+/>
+```
+
+**Partial Translations:**
+
+You can provide only the translations you need to customize. All other strings will use the default English values:
+
+```tsx
+<BarChart
+  // ... other props
+  translations={{
+    sortLabel: 'Sort by:',
+    // sortOptions will use default English values
+    locale: 'en-GB', // Use British English number formatting
+  }}
+/>
+```
+
+**Locale-Aware Number Formatting:**
+
+The `locale` property controls how numbers are formatted throughout the chart using `Intl.NumberFormat`. This affects:
+
+- Scale labels on the x-axis
+- Value labels on bars
+- All numeric displays
+
+```tsx
+// German locale (1.000 instead of 1,000)
+<BarChart
+  // ... other props
+  translations={{
+    locale: 'de-DE',
+  }}
+/>
+
+// French locale
+<BarChart
+  // ... other props
+  translations={{
+    locale: 'fr-FR',
+  }}
+/>
+```
+
+**Accessibility Translations:**
+
+The accessibility strings are used in automatically generated `aria-label` attributes for interactive bars and screen reader text for non-interactive bars. These should be translated to match the language of your application:
+
+```tsx
+<BarChart
+  // ... other props
+  translations={{
+    accessibility: {
+      gainedNowAt: 'ganado - ahora en', // Spanish: "gained - now at"
+      inLabel: 'en', // Spanish: "in"
+      inOnly: 'en ', // Spanish: "in "
+    },
+  }}
+/>
+```
+
+**Best Practices:**
+
+- Always provide complete translations for the language your application uses
+- Use appropriate locale codes (e.g., `'en-US'`, `'es-ES'`, `'fr-FR'`) for number formatting
+- Test accessibility strings with screen readers in the target language
+- Consider creating translation objects that can be reused across multiple BarChart instances

package/src/lib/Organisms/BarChart/BarChart.stories.tsx

@@ -0,0 +1,296 @@
+import { BarChart, BarProps, Box } from '@codecademy/gamut';
+import {
+  BookFlipPageIcon,
+  DataScienceIcon,
+  TerminalIcon,
+} from '@codecademy/gamut-icons';
+import { action } from '@storybook/addon-actions';
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta<typeof BarChart> = {
+  component: BarChart,
+  args: {
+    title: 'Skills experience chart',
+    description: 'Chart showing programming language experience levels',
+    minRange: 0,
+    maxRange: 2000,
+    unit: 'XP',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof BarChart>;
+
+const simpleBarData: BarProps[] = [
+  { yLabel: 'Python', seriesOneValue: 1500 },
+  { yLabel: 'JavaScript', seriesOneValue: 2000 },
+  { yLabel: 'HTML/CSS', seriesOneValue: 800 },
+  { yLabel: 'SQL', seriesOneValue: 600 },
+  { yLabel: 'React', seriesOneValue: 450 },
+];
+
+const stackedBarData: BarProps[] = [
+  { yLabel: 'Python', seriesOneValue: 200, seriesTwoValue: 1500 },
+  {
+    yLabel: 'JavaScript',
+    icon: TerminalIcon,
+    seriesOneValue: 1800,
+    seriesTwoValue: 2000,
+  },
+  { yLabel: 'HTML/CSS', seriesOneValue: 600, seriesTwoValue: 800 },
+  { yLabel: 'SQL', seriesOneValue: 550, seriesTwoValue: 600 },
+  { yLabel: 'React', seriesOneValue: 300, seriesTwoValue: 450 },
+];
+
+const barDataWithIcons: BarProps[] = [
+  {
+    yLabel: 'Python',
+    seriesOneValue: 200,
+    seriesTwoValue: 1500,
+    icon: TerminalIcon,
+  },
+  {
+    yLabel: 'JavaScript',
+    seriesOneValue: 150,
+    seriesTwoValue: 2000,
+    icon: TerminalIcon,
+  },
+  {
+    yLabel: 'Data Science',
+    seriesOneValue: 100,
+    seriesTwoValue: 800,
+    icon: DataScienceIcon,
+  },
+  {
+    yLabel: 'Backend',
+    seriesOneValue: 50,
+    seriesTwoValue: 600,
+    icon: TerminalIcon,
+  },
+  {
+    yLabel: 'Reading',
+    seriesOneValue: 75,
+    seriesTwoValue: 450,
+    icon: BookFlipPageIcon,
+  },
+];
+
+export const Default: Story = {
+  args: {
+    barValues: simpleBarData,
+    title: 'Skills experience chart',
+    description: 'Chart showing programming language experience levels',
+  },
+};
+
+export const Stacked: Story = {
+  args: {
+    barValues: stackedBarData,
+    title: 'Skills progress chart',
+    description: 'Progress toward total goals for each programming language',
+  },
+};
+
+export const WithIcons: Story = {
+  args: {
+    barValues: barDataWithIcons,
+    title: 'Skills progress with icons',
+    description: 'Skills progress with visual icons for each category',
+  },
+};
+
+export const Animated: Story = {
+  args: {
+    barValues: stackedBarData,
+    animate: true,
+    title: 'Animated skills chart',
+    description: 'Animated chart showing progress with entrance animations',
+  },
+};
+
+export const Interactive: Story = {
+  args: {
+    barValues: simpleBarData.map((bar) => ({
+      ...bar,
+      onClick: action(`Clicked ${bar.yLabel}`),
+    })),
+    title: 'Interactive skills chart',
+    description: 'Click on any row to view detailed course information',
+  },
+};
+
+export const WithLinks: Story = {
+  args: {
+    barValues: simpleBarData.map((bar) => ({
+      ...bar,
+      href: `#${bar.yLabel.toLowerCase().replace(/\s+/g, '-')}`,
+    })),
+    title: 'Skills chart with links',
+    description: 'Each row links to its corresponding course page',
+  },
+};
+
+export const WithVisualTitleAndDescription: Story = {
+  args: {
+    barValues: simpleBarData,
+    title: 'Programming Skills Overview',
+    description:
+      'Experience points earned across different programming languages',
+  },
+};
+
+export const WithHiddenTitleAndDescription: Story = {
+  render: () => {
+    return (
+      <BarChart
+        barValues={simpleBarData}
+        description="Experience points earned across different programming languages"
+        hideDescription
+        hideTitle
+        maxRange={2000}
+        minRange={0}
+        title="Programming Skills Overview"
+        unit="XP"
+      />
+    );
+  },
+};
+
+export const WithExternalTitle: Story = {
+  render: () => {
+    return (
+      <>
+        <Box
+          as="h2"
+          bg="paleBlue"
+          border={1}
+          borderRadius="lg"
+          id="external-chart-title"
+          p={16}
+          textAlign="right"
+        >
+          Programming Skills Overview
+        </Box>
+        <BarChart
+          aria-labelledby="external-title"
+          barValues={simpleBarData}
+          description="Experience points earned across different programming languages"
+          hideDescription={false}
+          maxRange={2000}
+          minRange={0}
+          unit="XP"
+        />
+      </>
+    );
+  },
+};
+
+export const WithSorting: Story = {
+  args: {
+    barValues: simpleBarData,
+    sortFns: ['alphabetically', 'numerically', 'none'],
+    title: 'Skills experience chart',
+    description: 'Use the dropdown to sort bars by different criteria',
+  },
+};
+
+const customSortingBarValues = [
+  {
+    yLabel: 'Python',
+    seriesOneValue: 1500,
+    dateAdded: new Date('2023-01-15'),
+  },
+  {
+    yLabel: 'JavaScript',
+    seriesOneValue: 2000,
+    dateAdded: new Date('2023-03-20'),
+  },
+  {
+    yLabel: 'React',
+    seriesOneValue: 450,
+    dateAdded: new Date('2023-06-10'),
+  },
+  {
+    yLabel: 'TypeScript',
+    seriesOneValue: 300,
+    dateAdded: new Date('2023-08-05'),
+  },
+  {
+    yLabel: 'SQL',
+    seriesOneValue: 600,
+    dateAdded: new Date('2023-02-28'),
+  },
+];
+
+export const WithCustomSorting: Story = {
+  args: {
+    barValues: customSortingBarValues,
+    sortFns: [
+      'none',
+      {
+        label: 'Recently Added',
+        value: 'recent',
+        sortFn: (bars) => {
+          return [...bars].sort((a, b) => {
+            // TypeScript infers the type from barValues, so dateAdded is properly typed
+            const aDate = a.dateAdded as Date | undefined;
+            const bDate = b.dateAdded as Date | undefined;
+            if (!aDate && !bDate) return 0;
+            if (!aDate) return 1;
+            if (!bDate) return -1;
+            return bDate.getTime() - aDate.getTime();
+          });
+        },
+      },
+      {
+        label: 'Oldest First',
+        value: 'oldest',
+        sortFn: (bars) => {
+          return [...bars].sort((a, b) => {
+            // TypeScript infers the type from barValues, so dateAdded is properly typed
+            const aDate = a.dateAdded as Date | undefined;
+            const bDate = b.dateAdded as Date | undefined;
+            if (!aDate && !bDate) return 0;
+            if (!aDate) return 1;
+            if (!bDate) return -1;
+            return aDate.getTime() - bDate.getTime();
+          });
+        },
+      },
+    ],
+    title: 'Skills chart with date sorting',
+    description:
+      'Custom sort functions can access additional properties on BarProps, such as dates',
+  },
+};
+
+/**
+ * Bar chart with custom styling
+ */
+export const CustomStyles: Story = {
+  args: {
+    barValues: stackedBarData,
+    styleConfig: {
+      backgroundBarColor: 'text',
+      foregroundBarColor: 'primary',
+      textColor: 'primary',
+      seriesOneLabel: 'feedback-error',
+      seriesTwoLabel: 'feedback-success',
+    },
+    title: 'Custom styled skills chart',
+    description: 'Custom color scheme applied to chart elements',
+  },
+};
+
+/**
+ * Bar chart with custom xScale interval
+ */
+export const CustomScale: Story = {
+  args: {
+    barValues: simpleBarData,
+    maxRange: 2000,
+    xScale: 250,
+    title: 'Skills chart with custom scale',
+    description: 'Custom scale intervals for more granular value display',
+  },
+};

package/src/lib/Organisms/ConnectedForm/ConnectedFormGroup/ConnectedFormGroup.mdx

@@ -61,26 +61,6 @@ 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,9 +2,7 @@ import {
   ConnectedForm,
   ConnectedFormGroup,
   ConnectedFormGroupProps,
-  ConnectedInput,
   ConnectedRadioGroupInput,
-  Text,
   useConnectedForm,
 } from '@codecademy/gamut';
 import { action } from '@storybook/addon-actions';
@@ -121,85 +119,3 @@ 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: 'bottom-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,23 +95,3 @@ 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, Text } from '@codecademy/gamut';
+import { FormGroup, GridForm, Input } from '@codecademy/gamut';
 import { action } from '@storybook/addon-actions';
 import type { Meta, StoryObj } from '@storybook/react';
 
@@ -328,75 +328,3 @@ 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">Fields</LinkTo> story for specific accessibility tooling and <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">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.