@codecademy/gamut 68.6.1 → 68.6.2-alpha.f8b396.0

package/agent-tools/skills/gamut-accessibility/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: gamut-accessibility
+description: Deep Gamut accessibility reference (component matrix, overlays, tips, live regions, checklists). Form wiring and validation UX live in `gamut-forms`. Universal HTML/ARIA/focus/color rules: always-loaded `accessibility.mdc` — read that first; this skill does not duplicate them.
+---
+
+# Gamut Accessibility
+
+Source: `@codecademy/gamut` — `react-aria-components` is used only in [`packages/gamut/src/Tabs/`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Tabs/) (`Tabs.tsx`, `TabList.tsx`, `Tab.tsx`, `TabPanel.tsx`). `react-focus-on` powers `FocusTrap` ([`packages/gamut/src/FocusTrap/index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/FocusTrap/index.tsx)), used by overlays such as `Overlay` ([`packages/gamut/src/Overlay/index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Overlay/index.tsx)) and `Popover`. Other widgets (e.g. `Menu`, `DatePicker`) implement keyboard and ARIA in Gamut code.
+
+Product-oriented button variants and props: [`gamut-buttons`](../gamut-buttons/SKILL.md)
+
+---
+
+## Universal rules
+
+Prefer native HTML, minimal ARIA, correct roles, visible names, focus visibility, semantic color / `ColorMode`, and Gamut primitives — see the always-loaded Gamut Accessibility Rules: [`accessibility.mdc`](../../rules/accessibility.mdc). This skill adds Gamut component behavior and audit detail below.
+
+---
+
+## How Gamut handles accessibility
+
+Tabs use `react-aria-components` (see `packages/gamut/src/Tabs/*.tsx`) for roving tabindex and keyboard navigation. Overlays (e.g. `Overlay`, `Popover`) use `FocusTrap` → `react-focus-on` for focus containment and Escape/outside close. Other interactive components (`Menu`, `DatePicker`, `Modal`, `Dialog`, etc.) rely on in-repo implementations — supply accessible names, wire labels to controls, and avoid duplicating what a component already sets (`aria-live`, `aria-describedby`, tabindex, etc.); confirm in source when auditing.
+
+---
+
+## Component reference (index)
+
+There is no exported `<Button>` — use `FillButton`, `TextButton`, `StrokeButton`, `CTAButton`, and `IconButton` (shared `ButtonProps` type). Prefer these over `<div onClick>` or `<span role="button">`.
+
+Forms — `FormGroup`, `ConnectedForm` / `ConnectedFormGroup`, `GridForm`, field atoms (`Select`, `Checkbox`, `Radio`), validation, `aria-live` / `aria-describedby`: canonical reference is [`gamut-forms`](../gamut-forms/SKILL.md).
+
+| Component(s)                                            | Handled in library                                                                                                       | App / author responsibilities                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `FillButton`, `TextButton`, `StrokeButton`, `CTAButton` | Render `<button>` (or `<a>` when `href` is set); native click + keyboard activation                                      | Visible text or `href` purpose; follow [`gamut-buttons`](../gamut-buttons/SKILL.md) for variants and `disabled` vs `aria-disabled`.                                                                                                                                                        |
+| `IconButton`                                            | `tip` feeds the accessible name for icon-only controls                                                                   | Always pass `tip` when the button has no visible text.                                                                                                                                                                                                                                     |
+| `Dialog`                                                | `Overlay` (shroud, Escape, focus), `role="dialog"`, `aria-modal`, close control with configurable `closeButtonProps.tip` | Provide a clear `title` (and meaningful body copy). Confirm naming with [Molecules / Modals / Dialog](https://gamut.codecademy.com/?path=/docs-molecules-modals-dialog--docs).                                                                                                             |
+| `Modal`                                                 | Same overlay/focus stack; optional `aria-label`; multi-`views` support                                                   | `title` / view titles; pass `aria-label` when there is no visible title string. [Molecules / Modals / Modal](https://gamut.codecademy.com/?path=/docs-molecules-modals-modal--docs).                                                                                                       |
+| `Alert`                                                 | Default `aria-live="polite"`, `role="status"`                                                                            | Use `aria-live="assertive"` only for urgent interruptions; do not nest inside another live region.                                                                                                                                                                                         |
+| `Tabs`, `Tab`, `TabList`, `TabPanel`                    | `react-aria-components` in `packages/gamut/src/Tabs/` — roving tabindex, arrows, Home/End                                | Name each tab; Tab moves into the active panel per APG.                                                                                                                                                                                                                                    |
+| Forms                                                   | See Forms above                                                                                                          | [`gamut-forms`](../gamut-forms/SKILL.md)                                                                                                                                                                                                                                                   |
+| `DatePicker` + `DatePickerInput`                        | Segmented input + calendar behavior inside `FormGroup`                                                                   | Provide `label` / `name` / `form` as for any input; keep `DatePickerInput` inside `DatePicker`. When embedded in `FormGroup` / `GridForm`, follow [`gamut-forms`](../gamut-forms/SKILL.md). [Organisms / DatePicker](https://gamut.codecademy.com/?path=/docs-organisms-datepicker--docs). |
+| `Menu`, `MenuItem`, `MenuSeparator`                     | List + `MenuProvider` (keyboard / roles depend on variant)                                                               | Label `Menu` / menubar per pattern; follow Storybook [Molecules / Menu](https://gamut.codecademy.com/?path=/docs-molecules-menu--docs).                                                                                                                                                    |
+| `Popover`                                               | `FocusTrap` when open (unless `skipFocusTrap`), positioning                                                              | `onRequestClose`, meaningful `role` when needed; do not trap focus unnecessarily when `skipFocusTrap`.                                                                                                                                                                                     |
+| `Flyout`                                                | `Overlay`, `Drawer`, visible `title`, close `IconButton` with `tip={closeLabel}`                                         | Pass `title` and `closeLabel`; name panel content.                                                                                                                                                                                                                                         |
+| `Drawer`                                                | Focuses container when `expanded`, `tabIndex={-1}` on shell                                                              | Drawer is a surface, not a full dialog — supply headings/labels inside for screen readers.                                                                                                                                                                                                 |
+| `Disclosure`                                            | `DisclosureButton` drives expand/collapse                                                                                | Provide `heading` / structure so the control’s purpose is clear.                                                                                                                                                                                                                           |
+| `Toggle`                                                | `ToggleLabel` + `htmlFor` wired to control `id`                                                                          | With no visible `label`, pass `ariaLabel` (or use `as="button"` pattern per props).                                                                                                                                                                                                        |
+| `ToolTip`                                               | Floating mode renders a screen-reader `role="tooltip"` branch with `id`                                                  | Pass the same `id` to the trigger’s `aria-describedby` when you rely on the tooltip as supplementary description (see component `id` JSDoc).                                                                                                                                               |
+| `InfoTip`                                               | —                                                                                                                        | `ariaLabel` or `ariaLabelledby` (camelCase) — no automatic fallback.                                                                                                                                                                                                                       |
+| `PreviewTip`                                            | `Anchor`-based preview, focus-driven content                                                                             | `linkDescription` and visible anchor text; do not use the preview as the sole name for an unrelated control.                                                                                                                                                                               |
+| `SkipToContent`                                         | Skip link behavior                                                                                                       | Place early in the tab order; `href` target `id` must exist on main content.                                                                                                                                                                                                               |
+| `Toast` + `Toaster`                                     | `Toaster` wraps the stack in `aria-live="polite"`                                                                        | Keep messages concise; avoid stacking many simultaneous assertive announcements.                                                                                                                                                                                                           |
+| `Pagination`                                            | Page / control buttons                                                                                                   | Ensure current page and actions are perceivable (labels / `aria-current` patterns per Storybook). [Molecules / Pagination](https://gamut.codecademy.com/?path=/docs-molecules-pagination--docs).                                                                                           |
+| `FocusTrap`                                             | Escape, outside click, `allowPageInteraction`                                                                            | Return focus to trigger on close for custom overlays.                                                                                                                                                                                                                                      |
+
+```tsx
+// correct
+<IconButton icon={DeleteIcon} tip="Delete item" onClick={handleDelete} />
+
+// wrong — no accessible name, no keyboard semantics
+<div onClick={handleDelete}><DeleteIcon /></div>
+```
+
+### Dialog / Modal (detail)
+
+Both use `Overlay` and `FocusTrap` (`react-focus-on`) patterns: focus moves into the surface, Escape closes (when enabled), focus should return to the trigger on close.
+
+Prefer a visible title so the dialog has a clear name; on `Modal`, pass `aria-label` when there is no suitable visible title string. Close control: `IconButton` with `closeButtonProps.tip` (defaults documented in source).
+
+```tsx
+<Dialog
+  title="Confirm deletion"
+  confirmCta={{ children: 'Delete', onClick: handleDelete }}
+  onRequestClose={handleClose}
+  isOpen={open}
+/>
+```
+
+### Alert (detail)
+
+Renders with `aria-live="polite"` and `role="status"` by default. Override with `aria-live="assertive"` only for time-sensitive errors requiring immediate interruption. Do not nest `<Alert>` inside another live region.
+
+### Tabs (detail)
+
+Built on `react-aria-components`. Follows the [ARIA Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/): arrow keys navigate tabs, Tab moves focus into the active panel, Home/End jump to first/last tab. The tablist is a composite — only the active tab is in the tab sequence (roving tabindex). No manual `aria-selected` or keyboard handling needed.
+
+### InfoTip (example)
+
+`<InfoTip>` needs `ariaLabel` or `ariaLabelledby` — see also the always-loaded rules.
+
+```tsx
+<InfoTip ariaLabel="More information about billing" />
+```
+
+### ToolTip (detail)
+
+When `placement="floating"`, the component renders a screen-reader-only branch with `role="tooltip"` and an optional `id`. Pass the same `id` to the described element’s `aria-describedby` so assistive tech associates the tooltip copy with the trigger. Inline placement uses the wrapper differently — see [Molecules / Tips / ToolTip](https://gamut.codecademy.com/?path=/docs-molecules-tips-tooltip--docs).
+
+### SkipToContent (detail)
+
+Include `<SkipToContent>` as the first focusable element in the page shell. The main content region must expose a matching `id` for the skip target.
+
+---
+
+## Focus management
+
+`<FocusTrap>` is for custom overlay patterns not covered by `Dialog` / `Modal`.
+
+Key props:
+
+- `active` — enable/disable the trap dynamically
+- `onEscapeKey` — close handler
+- `onClickOutside` — dismiss on outside click
+- `allowPageInteraction` — permit scrolling outside the trap without closing
+
+Always return focus to the trigger on close. `react-focus-on` (via `FocusTrap`) and overlay flows handle much of this for dialogs/popovers; `Tabs` inherit focus behavior from `react-aria-components`. Custom surfaces must store a ref to the trigger and call `.focus()` on close when the library does not.
+
+---
+
+## Composite widgets and managed focus
+
+ARIA composite roles (`listbox`, `menu`, `tree`, `grid`, `tablist`) use managed focus: only one element in the composite is in the tab sequence at a time. Tab moves focus to the next element outside the composite; arrow keys move focus within it.
+
+Implementation pattern — roving tabindex:
+
+- Set `tabIndex={0}` on the currently active item
+- Set `tabIndex={-1}` on all other items
+- On arrow key, update which item holds `tabIndex={0}` and call `.focus()` on it
+
+`Tabs` (`react-aria-components`) implement roving tabindex for the tablist pattern. `Menu` and other composites implement focus in Gamut — if you build a custom composite, implement roving tabindex yourself. A flat `tabIndex={0}` on every item is wrong — it puts every item in the sequential tab order.
+
+---
+
+## Device-independent events
+
+Use `click` for activation, not `mousedown`. `click` follows pointer activation; native `<button>` (and similar controls) also fire `click` from keyboard (Space and Enter). A focused `<a href>` is usually activated with Enter, which fires `click` — Space often scrolls the page instead of activating the link. `mousedown` does not represent keyboard activation, so relying on it alone breaks keyboard-only use.
+
+For custom elements with `role="button"`, do not assume the browser will synthesize `click` from the keyboard the way it does for native interactive elements (`<button>`, `<a href>`, and other built-ins). Handle `keydown` for Space and Enter explicitly:
+
+```tsx
+const handleKeyDown = (e: React.KeyboardEvent) => {
+  if (e.key === ' ' || e.key === 'Enter') {
+    e.preventDefault();
+    handleActivation();
+  }
+};
+```
+
+Prefer Gamut `*Button` components (or `Anchor` with a real `href`) so you do not reimplement this.
+
+---
+
+## Live regions
+
+| Scenario                                   | Pattern                                     |
+| ------------------------------------------ | ------------------------------------------- |
+| Status updates, non-critical notifications | `aria-live="polite"`                        |
+| Urgent global interruptions                | `aria-live="assertive"` (use sparingly)     |
+| Frequently updating counts or progress     | `aria-live="polite"` + `aria-atomic="true"` |
+
+Form-bound `aria-live` and `FormError` patterns: see Forms above (do not assume assertive on every field error).
+
+Inject live regions into the DOM before they need to announce. A region added simultaneously with its first announcement may be ignored by some assistive technologies.
+
+Do not elevate unrelated inline errors to `assertive` — reserve assertive for urgent interruptions the user did not directly trigger.
+
+---
+
+## ARIA authoring rules
+
+- No redundant roles: don't set `role="button"` on `<button>` or `role="heading"` on `<h2>`
+- `aria-hidden` cascades: placing `aria-hidden="true"` on a parent removes the entire subtree from the accessibility tree, including focusable descendants — never put it on an ancestor of a focusable element
+- `role="presentation"` and `aria-hidden` on focusable elements: both are prohibited on elements that can receive focus — they remove semantics while leaving the element keyboard-reachable, producing an operable but unnamed control
+- Labelling vs describing: `aria-label` / `aria-labelledby` name the control. `aria-describedby` provides supplementary context. Both can coexist on the same element
+- Required fields: use `aria-required="true"` or the HTML `required` attribute. Visual asterisks must have an explanatory text string visible on the page; the asterisk glyph itself should carry `aria-hidden="true"` — `<FormGroupLabel>` already handles this
+- `display:none` vs `aria-hidden`: elements with `display:none` are already removed from the accessibility tree; adding `aria-hidden` is redundant. Use `aria-hidden="true"` only when an element is visually present but should be hidden from assistive technology
+
+---
+
+## Color and contrast (non-text)
+
+Semantic tokens, `ColorMode`, and `<Background>` are covered in the always-loaded `accessibility.mdc` rule and the `gamut-color-mode` skill. Here: non-text contrast (focus rings, input borders, icon affordances) should meet ~3:1 vs adjacent colors where WCAG 1.4.11 applies — validate in your layout.
+
+---
+
+## Testing checklist
+
+- [ ] Full keyboard navigation: every interactive element reachable and operable without a mouse
+- [ ] Focus is always visible and never lost or unexpectedly trapped
+- [ ] Dialogs trap focus correctly; Escape closes; focus returns to the trigger
+- [ ] Composite widgets (tabs, menus, listboxes) use arrow keys internally, not Tab
+- [ ] All form inputs have programmatically associated labels (not placeholder-only)
+- [ ] Form errors surface through the library’s `FormError` / live-region patterns (Forms above)
+- [ ] Icon-only controls have accessible names
+- [ ] No content relies solely on color to convey meaning
+- [ ] Screen reader matrix: VoiceOver + Safari (iOS), VoiceOver + Chrome (macOS), NVDA + Chrome (Windows)
+- [ ] 200% zoom: layout intact, no content overflow or disappearance
+
+---
+
+## Common anti-patterns
+
+| Anti-pattern                                             | Fix                                                                                   |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| `<div onClick={…}>` for actions                          | `FillButton`, `TextButton`, `StrokeButton`, `CTAButton`, or `IconButton` (with `tip`) |
+| `placeholder` as the only label                          | `FormGroupLabel` with matching `htmlFor` / `id`                                       |
+| `aria-label` on a `<div>` with no role                   | Add a meaningful `role` or use a semantic element                                     |
+| `role="button"` without Space/Enter handlers             | Use a Gamut `*Button`, `Anchor` with `href`, or add `keydown`                         |
+| `tabIndex={0}` on every item in a composite              | Roving tabindex: `0` on active item, `-1` on rest                                     |
+| Tooltip as the only accessible name for a control        | Set `aria-label` (or visible text) on the control as well                             |
+| `aria-hidden="true"` on a focusable element              | Also remove from tab order (`tabIndex={-1}`) or restructure                           |
+| `mousedown` for activation                               | Use `click`                                                                           |
+| `outline: none` without a replacement                    | Use Gamut’s built-in focus styles                                                     |
+| Multiple `aria-live` regions for the same content stream | One region per logical stream; reuse it across updates                                |

package/agent-tools/skills/gamut-buttons/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: gamut-buttons
+description: Use this skill when choosing Gamut button atoms (FillButton, StrokeButton, TextButton, IconButton, CTAButton), variant and size props, or disabled vs aria-disabled patterns — not for custom styled controls (see gamut-color-mode and gamut-style-utilities).
+---
+
+# Gamut Buttons
+
+Which button component and which `variant` to use. Colors are wired inside each atom — consumers do not pass `color`, `bg`, hex, or semantic token names on stock buttons.
+
+See also: [`gamut-color-mode`](../gamut-color-mode/SKILL.md) — semantic tokens for custom styled controls only, not stock button atoms; ColorMode / `<Background>` when placing buttons on colored surfaces. [`gamut-accessibility`](../gamut-accessibility/SKILL.md) — universal action and naming rules.
+
+Storybook:
+
+- [Atoms / Buttons / Button](https://gamut.codecademy.com/?path=/docs-atoms-buttons-button--docs) — variants, light/dark examples
+- [FillButton](https://gamut.codecademy.com/?path=/docs-atoms-buttons-fillbutton--docs) · [StrokeButton](https://gamut.codecademy.com/?path=/docs-atoms-buttons-strokebutton--docs) · [TextButton](https://gamut.codecademy.com/?path=/docs-atoms-buttons-textbutton--docs) · [IconButton](https://gamut.codecademy.com/?path=/docs-atoms-buttons-iconbutton--docs) · [CTAButton](https://gamut.codecademy.com/?path=/docs-atoms-buttons-ctabutton--docs)
+- [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) — semantic tokens for custom `css` / `variant` / `states`, not prebuilt atoms
+- [UX Writing / Component guidelines / Buttons](https://gamut.codecademy.com/?path=/docs-ux-writing-component-guidelines-buttons--docs) — label copy
+
+## Component selection
+
+| Component      | Use for                                       | Default `variant`                                |
+| -------------- | --------------------------------------------- | ------------------------------------------------ |
+| `FillButton`   | Primary / high-emphasis actions               | `primary`                                        |
+| `StrokeButton` | Secondary / outlined actions                  | `primary` (often pass `secondary` per Storybook) |
+| `TextButton`   | Low-emphasis, inline actions                  | `primary`                                        |
+| `IconButton`   | Icon-only; requires `tip` and accessible name | `secondary`                                      |
+| `CTAButton`    | Marketing / high-visibility CTA only          | `primary` (only option)                          |
+
+## `variant` prop
+
+Shared by `FillButton`, `StrokeButton`, `TextButton`, and `IconButton`. `CTAButton` only supports `primary`.
+
+| `variant`   | Typical use                    |
+| ----------- | ------------------------------ |
+| `primary`   | Submit, main CTA               |
+| `secondary` | Close, cancel, low priority    |
+| `danger`    | Destructive actions            |
+| `interface` | Controls styled like UI chrome |
+
+```tsx
+<FillButton variant="primary">Submit</FillButton>
+<StrokeButton variant="secondary">Cancel</StrokeButton>
+<IconButton icon={SearchIcon} tip="Search" variant="secondary" />
+<CTAButton>Try Pro for free</CTAButton>
+```
+
+## Sizes
+
+`small` | `normal` (default) | `large`
+
+## Key props
+
+| Prop           | Type                                                  | Effect                                           |
+| -------------- | ----------------------------------------------------- | ------------------------------------------------ |
+| `variant`      | `"primary" \| "secondary" \| "danger" \| "interface"` | Color emphasis (see table above)                 |
+| `size`         | `"small" \| "normal" \| "large"`                      | Padding and font size                            |
+| `icon`         | Icon component                                        | Leading or trailing icon (Fill, Stroke, Text)    |
+| `iconPosition` | `"left" \| "right"`                                   | Defaults to left                                 |
+| `disabled`     | boolean                                               | Disabled state styling                           |
+| `href`         | string                                                | Renders as `<a>` tag                             |
+| `tip`          | string                                                | Required on `IconButton` (tooltip + hover label) |
+
+## States
+
+Hover, active, and disabled colors are handled by the component. Do not override state colors with `color` / `bg` props.
+
+## Accessibility — `disabled` vs `aria-disabled`
+
+| Situation                                                       | Use                                                | Why                                                                                                                                                                                                                                                 |
+| --------------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Button should not be activatable (default)                      | `disabled` prop                                    | Renders native `disabled` on `<button>`; removed from tab order; correct for most forms and actions                                                                                                                                                 |
+| Disabled button with a tooltip that must stay readable on focus | `aria-disabled` only — do not also pass `disabled` | Native `disabled` blocks keyboard focus, so the tooltip cannot be reached. Gamut disabled styles also match `[aria-disabled='true']`. See [ToolTip — With a disabled Button](https://gamut.codecademy.com/?path=/docs-molecules-tips-tooltip--docs) |
+
+```tsx
+// Default — not interactive
+<FillButton disabled>Submit</FillButton>
+
+// Disabled but focusable (e.g. wrapped in ToolTip explaining why)
+<ToolTip id="why-disabled" info="Complete the lesson first">
+  <FillButton aria-describedby="why-disabled" aria-disabled>
+    Submit
+  </FillButton>
+</ToolTip>
+```
+
+- `href` + `disabled`: `ButtonBase` (internal) drops `href` and renders a `<button disabled>` — link-style buttons cannot stay anchors while disabled.
+- `IconButton`: provide an accessible name via `tip` (used as `aria-label` when `aria-label` is omitted). See ToolTip / IconButton Storybook pages.
+- `ButtonBase` is not exported from `@codecademy/gamut` (only the `ButtonBaseElements` type is). Prefer stock atoms; custom button styling belongs in Gamut itself or via `css` / `variant` from `gamut-styles`, not by importing `ButtonBase`.
+
+## Rules
+
+- Use `FillButton` for primary actions and `StrokeButton` for secondary — do not use both at equal weight on the same screen.
+- Reserve `CTAButton` for marketing / high-visibility promotions; do not use it for standard UI actions.
+- Avoid placing buttons in the wrong color-mode context (e.g. light-mode buttons on a navy band without `<Background>`). See [`gamut-color-mode`](../gamut-color-mode/SKILL.md).
+- Every interactive `Card` wrapped in `<Anchor>` should have `isInteractive` — not a button inside.
+- Do not set `color`, `bg`, or hex on stock button components. For custom styled controls, follow [`gamut-color-mode`](../gamut-color-mode/SKILL.md) and `gamut-styles` utilities — do not import internal `ButtonBase`.

package/agent-tools/skills/gamut-color-mode/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: gamut-color-mode
+description: Use this skill when implementing light/dark behavior, semantic color aliases, the Background component for contrast-safe surfaces, or color-mode hooks in Gamut — including replacing hardcoded hex, fixing mode bugs, or reviewing color usage.
+---
+
+# Gamut ColorMode
+
+Source: `@codecademy/gamut-styles` — [`ColorMode.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/ColorMode.tsx)
+
+## Overview
+
+Gamut's color system uses semantic aliases instead of raw color tokens. This means components automatically adapt across light and dark modes without configuration.
+
+### Semantic color aliases
+
+| Alias        | Purpose                                    |
+| ------------ | ------------------------------------------ |
+| `text`       | Standard text color for all type           |
+| `background` | Base background color                      |
+| `primary`    | Interactive elements with primary action   |
+| `secondary`  | Interactive elements with secondary action |
+
+This set is not exhaustive (e.g. `text-accent`, `background-disabled`, `danger` — see the light/dark tables in Storybook).
+
+Key principle: Always use these aliases in component styles — never hardcode specific color tokens like `navy-400` for anything that needs to change per mode.
+
+Storybook: [Foundations / ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page) — interactive reference. [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) — semantic tokens, `css` / `variant` / `states`, and system props with ColorMode.
+
+Agent skill: [`gamut-style-utilities`](../gamut-style-utilities/SKILL.md) — `css` / `variant` / `states` with semantic colors alongside ColorMode.
+
+## `<ColorMode />`
+
+Wraps content in a color mode context. Place `<ColorMode />` as high in the app tree as practical. For a nested or static themed area on a page, use `<Background />` instead.
+
+```tsx
+import { ColorMode } from '@codecademy/gamut-styles';
+
+// Explicit light or dark
+<ColorMode mode="light">{children}</ColorMode>
+
+// Follow OS light/dark preference (see mode="system" below)
+<ColorMode mode="system">{children}</ColorMode>
+```
+
+Props: `mode="light" | "dark" | "system"`
+
+### `mode="system"` (OS preference)
+
+`system` is not a third color theme. It always resolves to `"light"` or `"dark"` based on the user's OS setting.
+
+How it works
+
+1. `ColorMode` calls `usePrefersDarkMode()`, which reads `window.matchMedia('(prefers-color-scheme: dark)')`.
+2. If the query matches → active mode is `"dark"`; otherwise `"light"`.
+3. Descendants receive that mode's semantic color variables (`text`, `background`, `primary`, etc.) — same as passing `mode="light"` or `mode="dark"` directly.
+
+When the OS changes (e.g. user toggles system appearance), the media query fires a `change` event, `ColorMode` re-renders, and semantic colors update for everything inside the wrapper.
+
+What it does not do
+
+- Read in-app preferences (account settings, a theme toggle in localStorage). For those, pass `mode="light"` or `mode="dark"` yourself from your own state.
+- Replace `<Background>`. A colored band still needs `<Background bg="hyper">` if you want contrast-based mode selection for that surface.
+
+Prefer `mode="system"` over wiring the hook yourself
+
+```tsx
+// Prefer — ColorMode owns light/dark resolution
+<ColorMode mode="system">{children}</ColorMode>;
+
+// Avoid — duplicates what mode="system" already does
+const prefersDark = usePrefersDarkMode();
+<ColorMode mode={prefersDark ? 'dark' : 'light'}>{children}</ColorMode>;
+```
+
+Use `usePrefersDarkMode()` only when you need the OS preference for something other than setting `ColorMode`'s mode (e.g. picking a decorative palette `bg` in a demo).
+
+Place `<ColorMode mode="system">` high in the tree (often inside `GamutProvider`) so the whole app follows system appearance unless a subtree overrides with `mode="light"`, `mode="dark"`, or `<Background>`.
+
+## `<Background />`
+
+Use `<Background>` instead of putting `bg` on a layout component when a section needs a fixed palette color (card, hero, landing band, etc.) — independent of the parent color mode. Pass a palette token to `bg` (e.g. `hyper`, `navy`, `paleGreen`), not a semantic alias (`text`, `background`, `primary`).
+
+`<Background>` switches light/dark to whichever mode gives the highest contrast between that surface and body `text`. Nested Gamut components inherit readable colors without extra setup.
+
+```tsx
+import { Background } from '@codecademy/gamut-styles';
+
+// Single background — mode switches automatically if needed
+const Card = ({ children }) => <Background bg="hyper">{children}</Background>;
+
+// Nested backgrounds — each creates its own color context
+const Page = () => (
+  <Background bg="black" p={24}>
+    <Background bg="paleGreen" p={24}>
+      {/* content inside inner Background uses its own mode */}
+    </Background>
+  </Background>
+);
+```
+
+### `background-current` CSS variable
+
+When `<Background>` is rendered, it sets a `background-current` CSS variable on the theme. Use this to reference an ancestor's background color (e.g. for simulating transparency or masking content).
+
+## Color mode hooks
+
+```tsx
+import {
+  useColorModes,
+  useCurrentMode,
+  usePrefersDarkMode,
+} from '@codecademy/gamut-styles';
+
+// [activeModeKey, activeModeColors, allModes, getColorValue]
+const [current, currentColors, modes, getColorValue] = useColorModes();
+
+// Active mode key: "light" | "dark" (optional override argument)
+const current = useCurrentMode();
+const forced = useCurrentMode('light');
+
+// Boolean from window.matchMedia('(prefers-color-scheme: dark)')
+const prefersDark = usePrefersDarkMode();
+```
+
+## Decision guide
+
+| Need                                                          | Use                                |
+| ------------------------------------------------------------- | ---------------------------------- | ---- | --------- |
+| Set a page or section to a specific mode                      | `<ColorMode mode="light            | dark | system">` |
+| Place content on a colored background with automatic contrast | `<Background bg="...">`            |
+| Read the current mode in JavaScript                           | `useCurrentMode()`                 |
+| Access all modes, variables, and resolve raw colors           | `useColorModes()`                  |
+| Detect OS dark mode preference                                | `usePrefersDarkMode()`             |
+| Access full emotion theme                                     | `useTheme()` from `@emotion/react` |
+
+## Common mistakes to avoid
+
+- Do not use raw color tokens (e.g. `color: 'navy-400'`) for text, backgrounds, or borders that need to be accessible across modes — use semantic aliases instead.
+- Do not use a raw `bg` prop for colored section backgrounds that need static, ColorMode-agnostic, background colors — use `<Background>` so mode selection is handled for you.
+- Do not manually set `ColorMode`'s `mode` from `usePrefersDarkMode()` when `mode="system"` is enough. The hook is still useful for non-mode concerns (e.g. choosing a decorative `bg` in Storybook demos).
+
+## Semantic aliases (theme-stable names)
+
+These tokens describe roles. Actual colors come from the active theme + ColorMode. Never assume Codecademy Core hex when advising another product.
+
+### Text
+
+| Token            | Use for                     |
+| ---------------- | --------------------------- |
+| `text`           | Default body and UI text    |
+| `text-accent`    | Stronger emphasis text      |
+| `text-secondary` | Supporting / secondary copy |
+| `text-disabled`  | Disabled state labels       |
+
+### Background
+
+| Token                 | Use for                           |
+| --------------------- | --------------------------------- |
+| `background`          | Default page/component background |
+| `background-primary`  | Slightly elevated surfaces        |
+| `background-contrast` | Maximum contrast surface          |
+| `background-selected` | Selected row / item               |
+| `background-hover`    | Hover state overlay               |
+| `background-disabled` | Disabled surface                  |
+| `background-success`  | Success state container           |
+| `background-warning`  | Warning state container           |
+| `background-error`    | Error state container             |
+
+### Interactive
+
+| Token             | Use for                                   |
+| ----------------- | ----------------------------------------- |
+| `primary`         | Primary CTA, links, focus accents         |
+| `primary-hover`   | Hover on primary interactive              |
+| `primary-inverse` | Accent on top of primary-colored surfaces |
+| `secondary`       | Secondary CTA, ghost buttons              |
+| `secondary-hover` | Hover on secondary interactive            |
+| `danger`          | Destructive actions, error emphasis       |
+| `danger-hover`    | Hover on danger interactive               |
+
+### Border
+
+| Token              | Use for                    |
+| ------------------ | -------------------------- |
+| `border-primary`   | Strong borders, dividers   |
+| `border-secondary` | Medium-weight borders      |
+| `border-tertiary`  | Subtle borders, separators |
+| `border-disabled`  | Disabled input borders     |
+
+### Feedback
+
+| Token              | Use for                    |
+| ------------------ | -------------------------- |
+| `feedback-error`   | Error messages, validation |
+| `feedback-success` | Success messages           |
+| `feedback-warning` | Warning messages           |
+
+## Where resolved colors are documented
+
+- Storybook [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page)
+- [Core](https://gamut.codecademy.com/?path=/docs-foundations-theme-core-theme--docs) · [Admin](https://gamut.codecademy.com/?path=/docs-foundations-theme-admin-theme--docs) · [Platform](https://gamut.codecademy.com/?path=/docs-foundations-theme-platform-theme--docs) · [Percipio](https://gamut.codecademy.com/?path=/docs-foundations-theme-percipio-theme--docs) · [LX Studio](https://gamut.codecademy.com/?path=/docs-foundations-theme-lx-studio-theme--docs) theme pages
+- Root `DESIGN.md` from agent-tools (`DESIGN.Codecademy.md`, `DESIGN.Percipio.md`, `DESIGN.LXStudio.md`)
+- Source: [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes)
+
+## Codecademy Core — illustrative light/dark hex only
+
+Not valid for Percipio, LX Studio, or other themes. Quick mental model for Core defaults only.
+
+| Token            | Light     | Dark      |
+| ---------------- | --------- | --------- |
+| `text`           | `#10162F` | `#ffffff` |
+| `text-accent`    | `#0A0D1C` | `#FFF0E5` |
+| `background`     | `#ffffff` | `#10162F` |
+| `primary`        | `#3A10E5` | `#FFD300` |
+| `primary-hover`  | `#5533FF` | `#CCA900` |
+| `secondary`      | `#10162F` | `#ffffff` |
+| `danger`         | `#E91C11` | `#E85D7F` |
+| `feedback-error` | `#BE1809` | `#E85D7F` |
+
+Full tables: Storybook theme pages or audit with [`gamut-review`](../gamut-review/SKILL.md) Appendix A/B for hex triage.
+
+## Raw palette (Core-centric reference)
+
+Raw tokens name fixed swatches for `<Background bg="…">`, illustration, and surfaces. Confirm allowed keys in the active theme or `DESIGN.md` before using in non-Core apps.
+
+Named shorthand aliases on Core: `beige`, `blue`, `green`, `hyper`, `navy`, `orange`, `pink`, `red`, `yellow`, `black`, `white`
+
+## Color decision guide
+
+```
+Which product theme is GamutProvider using?
+  └─ Unknown → check DESIGN.md / gamut-theming / Storybook theme page
+
+Coloring UI text or backgrounds?
+  └─ Must adapt to light/dark OR theme? → semantic alias (text, background, primary, …)
+  └─ Must stay fixed regardless of mode?  → raw palette token (confirm key in that theme)
+  └─ Section background with content?     → <Background bg="…">
+```
+
+## Card and alert patterns
+
+### Cards
+
+- Background variants: `default` (ColorMode-responsive), `white`, `yellow`, `beige`, `navy`, `hyper`
+- Shadow variants: `none` (default), `outline`, `patternLeft`, `patternRight`
+- Add `isInteractive` when wrapping in `<Anchor>` — enables hover shadow + `borderRadius: md`
+- Default `borderRadius` is `none`; override with `borderRadius` prop
+
+### Alerts
+
+| Variant | Tokens                                    |
+| ------- | ----------------------------------------- |
+| Error   | `feedback-error` + `background-error`     |
+| Success | `feedback-success` + `background-success` |
+| Warning | `feedback-warning` + `background-warning` |
+
+52 components have Figma ↔ code mappings via Code Connect (`packages/code-connect/`).