@codecademy/styleguide 79.2.3-alpha.78c04d.0 → 79.2.3-alpha.9808a5.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.2.3-alpha.78c04d.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.2.2...@codecademy/styleguide@79.2.3-alpha.78c04d.0) (2026-03-19)
+### [79.2.3-alpha.9808a5.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.2.2...@codecademy/styleguide@79.2.3-alpha.9808a5.0) (2026-03-19)
 
 **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.2.3-alpha.78c04d.0",
+  "version": "79.2.3-alpha.9808a5.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "00f84dfe2b9149d1133f8cf7d4a5701b93864f94"
+  "gitHead": "3d8b09cbaeb9e885da137c9bb125b41a3a327015"
 }

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

@@ -131,14 +131,15 @@ When a bar has an `href` link, an `aria-label` is automatically generated from t
 
 ## Title and description
 
-The `BarChart` component uses semantic HTML to provide context and accessibility. The chart is wrapped in a [`<figure>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure), and the description is displayed in a [`<figcaption>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption). 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.
+The `BarChart` component uses semantic HTML to provide context and accessibility. The chart is wrapped in a [`<figure>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure), and the description is displayed in a [`<figcaption>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption). This semantic structure helps screen readers and other assistive technologies understand the relationship between the chart and its description.
 
 **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.
+- `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>. Use semantic heading levels (h1–h6) so the surrounding document outline stays correct.
+- `description`: **Required.** A summary of the information or the overall takeaway displayed in the `<figcaption>` element.
+- When the visible title lives outside the chart, use `aria-labelledby` to point at that heading (see below). The referenced element must exist and have an accessible name.
 
 <Canvas of={BarChartStories.WithVisualTitleAndDescription} />
 
@@ -151,12 +152,6 @@ Provide both `title` and `description` props to make the chart's purpose and key
 
 <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.
@@ -237,45 +232,29 @@ Custom sort functions can access additional properties on `BarProps` for domain-
 
 ## 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.
+`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'`
-- **`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'`
+- **`textColor`**: Color for each bar row's `categoryLabel`. Defaults to `'text'`
+- **`seriesOneBarColor`**: Color for the bar that represents `seriesOneValue` (the only bar in simple charts; the overlay segment in stacked charts). Defaults to `'text'`
+- **`seriesTwoBarColor`**: Color for the bar that represents `seriesTwoValue` (the full-length bar behind the overlay in stacked charts; unused when only `seriesOneValue` is set). Defaults to `'primary'`
+- **`seriesOneLabel`**: Color for the numeric label for `seriesOneValue` (when stacked: the value before the arrow). In simple charts, color for the value label beside the bar (`seriesOneValue`). Defaults to `'text-secondary'`
+- **`seriesTwoLabel`**: Color for the numeric label for `seriesTwoValue` (stacked charts only—the total at the end of the bar). 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',
-  seriesOneBarColor: 'text',
-  seriesTwoBarColor: '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 `scaleInterval` prop, which controls the spacing and granularity of scale markers along the horizontal axis.
+`BarChart` allows you to customize the scale interval using the `scaleInterval` prop, which controls the spacing and granularity of scale markers that measure the length of the bars.
 
 ### Scale configuration
 
-The `scaleInterval` prop determines the interval between scale markers on the x-axis. By default, BarChart automatically calculates an appropriate scale interval based on the `maxScaleValue` value (the scale always starts at 0). However, you can override this with a custom interval to achieve more granular or specific scale markings.
+The `scaleInterval` prop determines the interval between scale markers that show the length of the bars. By default, `BarChart` automatically calculates an appropriate scale interval based on the `maxScaleValue` value (the scale always starts at 0). However, you can override this with a custom interval to achieve more granular or specific scale markings.
 
 **When to use custom scale:**
 
@@ -299,7 +278,7 @@ The number of tick marks is automatically calculated as: `Math.ceil(maxScaleValu
 
 ## 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.
+`BarChart` uses semantic color tokens via `styleConfig`, so colors automatically adapt to light and dark color modes to ensure proper contrast and readability in all themes.
 
 ## Accessibility considerations
 
@@ -318,13 +297,13 @@ BarChart automatically adapts to both light and dark color modes, ensuring prope
 
 ## UX writing
 
-- Keep y-axis labels concise (1-3 words)
+- Keep the category labels concise (1-3 words)
 - Use consistent unit labels (e.g., "XP", "hours", "points")
 - Consider locale-aware number formatting for international audiences
 
 ## Interactive states
 
-BarChart supports both interactive and static bar rows, each with distinct visual states.
+`BarChart` supports both interactive and static bar rows, each with distinct visual states.
 
 ### Static bars
 
@@ -342,11 +321,11 @@ When bars have `onClick` handlers or `href` links, they become interactive. Inte
 
 <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. 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.
+`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
 
-- **sortLabel**, **sortOptions**, and **locale** — Always strings. Control the sort dropdown label, option labels, and number-formatting locale.
+- `**sortLabel**`, `**sortOptions**`, and `**locale**` — Always strings. Control the sort dropdown label, option labels, and number-formatting locale.
 - **Accessibility** — Two optional summary functions; when omitted, default English summaries are used. Each function receives context and returns the full summary string.
   - `**stackedBarSummary**` — Used for stacked (two-value) rows. Context includes `seriesOneValue`, `seriesTwoValue`, **gained** (seriesTwoValue - seriesOneValue), `unit`, `locale`, `categoryLabel`.
   - `**singleValueBarSummary**` — Used for all single-value rows. Context includes `value`, `unit`, `locale`, `categoryLabel`.