@codecademy/styleguide 78.5.5-alpha.86d3e6.0 → 78.5.5-alpha.cb4c1d.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.cb4c1d.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@78.5.4...@codecademy/styleguide@78.5.5-alpha.cb4c1d.0) (2026-01-07)
 
 **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.cb4c1d.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "2988ef3b1571897c2359c9031389d08356b819be"
+  "gitHead": "8f9681525aad2b306aff70b92f65739463850b5a"
 }

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

@@ -82,24 +82,9 @@ InfoTips have intelligent Escape key handling that works correctly both inside a
 
 <Canvas of={InfoTipStories.InfoTipInsideModal} />
 
-## Custom Accessible Labeling
+## InfoTips and zIndex
 
-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.
+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,7 +1,6 @@
 import {
   Anchor,
   Box,
-  Coachmark,
   FillButton,
   FlexBox,
   GridBox,
@@ -196,7 +195,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}>
@@ -235,37 +233,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 +245,19 @@ 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 info="I am inline, cool" />
+      <Box bg="paleBlue" zIndex={3}>
+        I will be behind the infotip, nice + great
+      </Box>
+      <InfoTip {...args} />
     </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/BarChart/BarChart.mdx

@@ -0,0 +1,92 @@
+import { Canvas, Controls, Meta } from '@storybook/blocks';
+
+import { ComponentHeader } from '~styleguide/blocks';
+
+import * as BarChartStories from './BarChart.stories';
+
+export const parameters = {
+  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: 'current',
+  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
+
+When NOT to use
+
+- For showing trends over time - use a line chart instead
+- For showing parts of a whole - use a pie or donut chart
+- For very small datasets (1-2 items) - consider using ProgressBar
+
+## 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} />
+
+## Playground
+
+<Canvas sourceState="shown" of={BarChartStories.Default} />
+
+<Controls />
+
+## Accessibility considerations
+
+- Always provide either `aria-label` or `aria-labelledby` to describe the chart
+- Each row automatically generates an accessible label summarizing its values
+- Interactive rows (with onClick/href) are properly announced as buttons/links
+- Grid lines are marked as decorative and hidden from screen readers
+- The scale header is hidden on small screens and marked as decorative
+
+## 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

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

@@ -0,0 +1,183 @@
+import { BarChart, BarProps } from '@codecademy/gamut';
+import {
+  BookFlipPageIcon,
+  CodeIcon,
+  DataScienceIcon,
+  GameControllerIcon,
+  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: {
+    'aria-label': 'Skills experience chart',
+    minRange: 0,
+    maxRange: 2000,
+    unit: 'XP',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof BarChart>;
+
+// Sample data for non-stacked (simple) bars
+const simpleBarData: BarProps[] = [
+  { yLabel: 'Python', seriesOneValue: 1500 },
+  { yLabel: 'JavaScript', seriesOneValue: 2000 },
+  { yLabel: 'HTML/CSS', seriesOneValue: 800 },
+  { yLabel: 'SQL', seriesOneValue: 600 },
+  { yLabel: 'React', seriesOneValue: 450 },
+];
+
+// Sample data for stacked bars (with seriesTwoValue)
+const stackedBarData: BarProps[] = [
+  { yLabel: 'Python', seriesOneValue: 200, seriesTwoValue: 1500 },
+  { yLabel: 'JavaScript', seriesOneValue: 1800, seriesTwoValue: 2000 },
+  { yLabel: 'HTML/CSS', seriesOneValue: 600, seriesTwoValue: 800 },
+  { yLabel: 'SQL', seriesOneValue: 550, seriesTwoValue: 600 },
+  { yLabel: 'React', seriesOneValue: 300, seriesTwoValue: 450 },
+];
+
+// Sample data with icons
+const barDataWithIcons: BarProps[] = [
+  {
+    yLabel: 'Python',
+    seriesOneValue: 200,
+    seriesTwoValue: 1500,
+    icon: CodeIcon,
+  },
+  {
+    yLabel: 'JavaScript',
+    seriesOneValue: 150,
+    seriesTwoValue: 2000,
+    icon: TerminalIcon,
+  },
+  {
+    yLabel: 'Data Science',
+    seriesOneValue: 100,
+    seriesTwoValue: 800,
+    icon: DataScienceIcon,
+  },
+  {
+    yLabel: 'Game Dev',
+    seriesOneValue: 50,
+    seriesTwoValue: 600,
+    icon: GameControllerIcon,
+  },
+  {
+    yLabel: 'Reading',
+    seriesOneValue: 75,
+    seriesTwoValue: 450,
+    icon: BookFlipPageIcon,
+  },
+];
+
+/**
+ * Default non-stacked bar chart showing single values
+ */
+export const Default: Story = {
+  args: {
+    barValues: simpleBarData,
+  },
+};
+
+/**
+ * Stacked bar chart showing progress (seriesOneValue) over total (seriesTwoValue)
+ */
+export const Stacked: Story = {
+  args: {
+    barValues: stackedBarData,
+  },
+};
+
+/**
+ * Bar chart with icons next to labels
+ */
+export const WithIcons: Story = {
+  args: {
+    barValues: barDataWithIcons,
+  },
+};
+
+/**
+ * Animated bar chart with staggered entrance
+ */
+export const Animated: Story = {
+  args: {
+    barValues: stackedBarData,
+    animate: true,
+  },
+};
+
+/**
+ * Bar chart sorted by value in descending order
+ */
+export const SortedByValue: Story = {
+  args: {
+    barValues: simpleBarData,
+    sortBy: 'value',
+    order: 'descending',
+  },
+};
+
+/**
+ * Bar chart sorted alphabetically by label
+ */
+export const SortedByLabel: Story = {
+  args: {
+    barValues: simpleBarData,
+    sortBy: 'label',
+    order: 'ascending',
+  },
+};
+
+/**
+ * Interactive bar chart with clickable rows
+ */
+export const Interactive: Story = {
+  args: {
+    barValues: simpleBarData.map((bar) => ({
+      ...bar,
+      onClick: action(`Clicked ${bar.yLabel}`),
+    })),
+  },
+};
+
+/**
+ * Interactive bar chart with linked rows
+ */
+export const WithLinks: Story = {
+  args: {
+    barValues: simpleBarData.map((bar) => ({
+      ...bar,
+      href: `#${bar.yLabel.toLowerCase().replace(/\s+/g, '-')}`,
+    })),
+  },
+};
+
+/**
+ * Bar chart with custom styling
+ */
+export const CustomStyles: Story = {
+  args: {
+    barValues: stackedBarData,
+    styleConfig: {
+      backgroundBarColor: 'paleGreen',
+      foregroundBarColor: 'feedback-success',
+      textColor: 'navy',
+    },
+  },
+};
+
+/**
+ * Bar chart with custom xScale interval
+ */
+export const CustomScale: Story = {
+  args: {
+    barValues: simpleBarData,
+    maxRange: 2000,
+    xScale: 250,
+  },
+};