@codecademy/styleguide 79.0.1-alpha.4fa3a1.0 → 79.0.1-alpha.5950e5.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.
 
-### [79.0.1-alpha.4fa3a1.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.0.0...@codecademy/styleguide@79.0.1-alpha.4fa3a1.0) (2026-02-02)
+### [79.0.1-alpha.5950e5.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.0.0...@codecademy/styleguide@79.0.1-alpha.5950e5.0) (2026-02-03)
 
 **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": "79.0.1-alpha.4fa3a1.0",
+  "version": "79.0.1-alpha.5950e5.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "bcc5f0d8a1a6bb0fa31053767e304e387b8c1683"
+  "gitHead": "296228a5f09e2d520a512458cf7d001d45d549eb"
 }

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

@@ -11,7 +11,7 @@ export const parameters = {
     type: 'figma',
     url: 'https://www.figma.com/file/ReGfRNillGABAj5SlITalN/branch/ayKNSg6QvZUjsgw0FFysW4/%F0%9F%93%90-Gamut?type=design&node-id=41538-55277&mode=design&t=fGkWf5GSl5cj5fQo-0',
   },
-  status: 'updating',
+  status: 'current',
   source: {
     repo: 'gamut',
     githubLink:

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

@@ -16,7 +16,7 @@ export const parameters = {
     type: 'figma',
     url: 'https://www.figma.com/design/ReGfRNillGABAj5SlITalN/%F0%9F%93%90-Gamut?node-id=55123-4176',
   },
-  status: 'updating',
+  status: 'current',
   source: {
     repo: 'gamut',
     githubLink:
@@ -119,7 +119,41 @@ Rows can be made interactive with `onClick` handlers or `href` links.
 
 <Canvas of={BarChartStories.Interactive} />
 
-### Sorting
+### With Links
+
+When a bar has an `href` link, an `aria-label` is automatically generated from the bar's data and applied to the anchor. 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), so screen reader users get a clear, data-driven description without manual `aria-label` props.
+
+<Canvas of={BarChartStories.WithLinks} />
+
+## 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 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
+
+## 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.
 
@@ -193,32 +227,6 @@ Custom sort functions can access additional properties on `BarProps` for domain-
 
 <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.
@@ -228,8 +236,8 @@ BarChart supports custom color styling through the `styleConfig` prop, allowing
 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 `'primary'`
-- **`backgroundBarColor`**: Color for the background/total bar (used for `seriesTwoValue` in stacked charts, or `seriesOneValue` in simple charts). Defaults to `'background-primary'`
+- **`seriesOneBarColor`**: Color for the series one bar (seriesOneValue: overlay in stacked charts, only bar in simple charts). Defaults to `'text'`
+- **`seriesTwoBarColor`**: Color for the series two bar (seriesTwoValue: full bar in stacked charts; unused in simple charts). Defaults to `'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'`
 
@@ -242,8 +250,8 @@ If `styleConfig` is not provided, BarChart uses these default colors:
 ```typescript
 {
   textColor: 'text',
-  foregroundBarColor: 'primary',
-  backgroundBarColor: 'background-primary',
+  seriesOneBarColor: 'text',
+  seriesTwoBarColor: 'primary',
   seriesOneLabel: 'text-secondary',
   seriesTwoLabel: 'primary',
 }
@@ -281,6 +289,10 @@ The number of tick marks is automatically calculated as: `Math.ceil((maxRange -
 
 <Canvas of={BarChartStories.CustomScale} />
 
+## 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.
+
 ## Accessibility considerations
 
 ### Chart and row labeling
@@ -302,154 +314,101 @@ The number of tick marks is automatically calculated as: `Math.ceil((maxRange -
 - 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} />
+## Interactive states
 
-- **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.
+BarChart supports both interactive and static bar rows, each with distinct visual states.
 
-<Canvas of={BarChartStories.WithExternalTitle} />
+### Static bars
 
-**Best practices:**
+When bars have neither `onClick` handlers nor `href` links, they are rendered as static, non-interactive elements.
 
-- 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
+<Canvas of={BarChartStories.Default} />
 
-## Playground
+### Interactive bars
 
-<Canvas sourceState="shown" of={BarChartStories.Default} />
+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.
 
-<Controls />
+<Canvas of={BarChartStories.Interactive} />
 
 ## 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.
+BarChart supports internationalization through the `translations` prop. You can customize user-facing strings (including sort dropdown and accessibility summaries) and configure locale-aware number formatting. The prop accepts `PartialBarChartTranslations`: override only the keys you need; nested `accessibility` and `sortOptions` are merged with defaults at runtime.
 
-**Translation Structure:**
+### 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'
-};
-```
+- **sortLabel**, **sortOptions**, and **locale** — Always strings. Control the sort dropdown label, option labels, and number-formatting locale.
+- **Accessibility keys** (`gainedNowAt`, `inLabel`, `inOnly`) — Used in auto-generated `aria-label` and screen reader text for bars. Each key can be:
+  - **String** — A fragment interpolated into the built-in template (e.g. `"in"`, `"gained - now at"`). Use when the default word order works for your language.
+  - **Function** — Receives scoped context (values, label, unit, locale) and returns the **entire** summary string. Use for pluralization, different word order, or locale-specific phrasing.
 
-**Basic Usage:**
+### 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.
+Provide only the translations you want to override; the rest fall back to default English.
 
 ```tsx
 <BarChart
-  title="Habilidades"
   barValues={barData}
   description="Progreso de habilidades"
-  minRange={0}
   maxRange={200}
+  minRange={0}
   sortFns={['alphabetically', 'none']}
+  title="Habilidades"
   translations={{
+    accessibility: {
+      gainedNowAt: 'ganado - ahora en',
+      inLabel: 'en',
+      inOnly: 'en ',
+    },
+    locale: 'es',
     sortLabel: 'Ordenar por:',
     sortOptions: {
-      none: 'Ninguno',
       labelAsc: 'Etiqueta (A-Z)',
       labelDesc: 'Etiqueta (Z-A)',
+      none: 'Ninguno',
       valueAsc: 'Valor (Bajo-Alto)',
       valueDesc: 'Valor (Alto-Bajo)',
     },
-    locale: 'es',
   }}
 />
 ```
 
-**Partial Translations:**
+<Canvas of={BarChartStories.WithStringTranslations} />
 
-You can provide only the translations you need to customize. All other strings will use the default English values:
+### Partial translations and locale
+
+You can override a single key; the rest keep their defaults. The **locale** property controls number formatting (scale labels, value labels) via `Intl.NumberFormat`:
 
 ```tsx
-<BarChart
-  // ... other props
-  translations={{
-    sortLabel: 'Sort by:',
-    // sortOptions will use default English values
-    locale: 'en-GB', // Use British English number formatting
-  }}
-/>
+// Only change locale; sort and accessibility use defaults
+translations={{ locale: 'de-DE' }}
+
+// Override just sort label and locale
+translations={{
+  locale: 'en-GB',
+  sortLabel: 'Sort by:',
+}}
 ```
 
-**Locale-Aware Number Formatting:**
-
-The `locale` property controls how numbers are formatted throughout the chart using `Intl.NumberFormat`. This affects:
+### Accessibility: strings vs functions
 
-- Scale labels on the x-axis
-- Value labels on bars
-- All numeric displays
+**Strings** — Use when the built-in template order fits your language. Fragments are plugged into the default pattern (e.g. `"{value} {unit} {inLabel} {yLabel}"`).
 
-```tsx
-// German locale (1.000 instead of 1,000)
-<BarChart
-  // ... other props
-  translations={{
-    locale: 'de-DE',
-  }}
-/>
+**Functions** — Use when you need full control. Each function receives context (`yLabel`, values, `unit`, `locale`) and returns the complete summary string.
 
-// French locale
-<BarChart
-  // ... other props
-  translations={{
-    locale: 'fr-FR',
-  }}
-/>
-```
+<Canvas of={BarChartStories.WithFunctionTranslations} />
 
-**Accessibility Translations:**
+**Best practices:**
 
-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:
+- Provide complete translations for the language your app uses; use partial overrides for one-off changes.
+- Prefer string accessibility keys when the default order works; use functions for pluralization, word order, or locale-specific phrasing.
+- Use appropriate locale codes (e.g. `'en-US'`, `'es-ES'`, `'fr-FR'`) for number formatting.
+- Test accessibility summaries with screen readers in the target language.
+- Reuse translation objects across BarChart instances where possible.
 
-```tsx
-<BarChart
-  // ... other props
-  translations={{
-    accessibility: {
-      gainedNowAt: 'ganado - ahora en', // Spanish: "gained - now at"
-      inLabel: 'en', // Spanish: "in"
-      inOnly: 'en ', // Spanish: "in "
-    },
-  }}
-/>
-```
+## Playground
 
-**Best Practices:**
+<Canvas sourceState="shown" of={BarChartStories.Default} />
 
-- 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
+<Controls />

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

@@ -1,4 +1,9 @@
-import { BarChart, BarProps, Box } from '@codecademy/gamut';
+import {
+  BarChart,
+  BarProps,
+  Box,
+  PartialBarChartTranslations,
+} from '@codecademy/gamut';
 import {
   BookFlipPageIcon,
   DataScienceIcon,
@@ -16,6 +21,14 @@ const meta: Meta<typeof BarChart> = {
     maxRange: 2000,
     unit: 'XP',
   },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'BarChart supports i18n via the `translations` prop. Accessibility keys (`gainedNowAt`, `inLabel`, `inOnly`) may be strings (fragments in the built-in template) or functions that receive scoped context (values, label, unit, locale) and return the full accessibility summary—useful for pluralization, word order, or locale-specific phrasing.',
+      },
+    },
+  },
 };
 
 export default meta;
@@ -42,6 +55,30 @@ const stackedBarData: BarProps[] = [
   { yLabel: 'React', seriesOneValue: 300, seriesTwoValue: 450 },
 ];
 
+const accessibilityBarData: BarProps[] = [
+  { yLabel: 'Python', seriesOneValue: 200, seriesTwoValue: 1500 },
+  {
+    yLabel: 'JavaScript',
+    seriesOneValue: 1800,
+    seriesTwoValue: 2000,
+    href: '/javascript',
+  },
+  { yLabel: 'HTML/CSS', seriesOneValue: 600, seriesTwoValue: 800 },
+  { yLabel: 'SQL', seriesOneValue: 550, href: '/sql' },
+  { yLabel: 'Rust', seriesOneValue: 400 },
+  { yLabel: 'React', seriesOneValue: 300, seriesTwoValue: 450 },
+];
+
+const accessibilityTranslations: PartialBarChartTranslations = {
+  accessibility: {
+    gainedNowAt: (ctx) =>
+      `${ctx.seriesOneValue} ${ctx.unit} gained — now at ${ctx.seriesTwoValue} ${ctx.unit} in ${ctx.yLabel}`,
+    inLabel: (ctx) => `${ctx.value} ${ctx.unit} in ${ctx.yLabel}`,
+    inOnly: (ctx) => `${ctx.value} ${ctx.unit}`.trim(),
+  },
+  locale: 'en',
+};
+
 const barDataWithIcons: BarProps[] = [
   {
     yLabel: 'Python',
@@ -271,8 +308,8 @@ export const CustomStyles: Story = {
   args: {
     barValues: stackedBarData,
     styleConfig: {
-      backgroundBarColor: 'text',
-      foregroundBarColor: 'primary',
+      seriesTwoBarColor: 'text',
+      seriesOneBarColor: 'primary',
       textColor: 'primary',
       seriesOneLabel: 'feedback-error',
       seriesTwoLabel: 'feedback-success',
@@ -294,3 +331,48 @@ export const CustomScale: Story = {
     description: 'Custom scale intervals for more granular value display',
   },
 };
+
+/**
+ * Bar chart with string-based translations (e.g. Spanish).
+ * Partial translations are merged with defaults.
+ */
+export const WithStringTranslations: Story = {
+  args: {
+    barValues: stackedBarData,
+    sortFns: ['alphabetically', 'numerically', 'none'],
+    title: 'Gráfico de habilidades',
+    description: 'Progreso hacia los objetivos totales por lenguaje',
+    unit: 'XP',
+    translations: {
+      locale: 'es',
+      sortLabel: 'Ordenar por:',
+      sortOptions: {
+        none: 'Ninguno',
+        labelAsc: 'Etiqueta (A-Z)',
+        labelDesc: 'Etiqueta (Z-A)',
+        valueAsc: 'Valor (Bajo-Alto)',
+        valueDesc: 'Valor (Alto-Bajo)',
+      },
+      accessibility: {
+        gainedNowAt: 'ganado - ahora en',
+        inLabel: 'en',
+        inOnly: 'en ',
+      },
+    },
+  },
+};
+
+/**
+ * Bar chart with function-based accessibility translations.
+ * Exercises gainedNowAt (stacked), inLabel (link/button single bar), and inOnly (non-interactive single bar).
+ */
+export const WithFunctionTranslations: Story = {
+  args: {
+    barValues: accessibilityBarData,
+    description:
+      'Custom aria-label summaries via translation functions (stacked, link, and non-interactive bars)',
+    title: 'Skills experience (accessibility functions)',
+    translations: accessibilityTranslations,
+    unit: 'XP',
+  },
+};