Codecademy · dreamwasp · May 13, 2026
@@ -30,14 +30,16 @@ Nesting is supported — each `<Background>` creates its own accessible color co
 
 ## Hooks
 
-| Hook                   | Returns                           | Use                          |
-| ---------------------- | --------------------------------- | ---------------------------- |
-| `useCurrentMode()`     | `"light" \| "dark"`               | Read active mode in JS       |
-| `useColorMode()`       | `[modeKey, modeColors, allModes]` | Access all mode data         |
-| `usePrefersDarkMode()` | `boolean`                         | Read OS dark preference only |
+| Hook                   | Returns                                                 | Use                                               |
+| ---------------------- | ------------------------------------------------------- | ------------------------------------------------- |
+| `useCurrentMode()`     | `"light" \| "dark"`                                     | Active mode key only                              |
+| `useColorModes()`      | `[modeKey, currentModeColors, allModes, getColorValue]` | Full mode data + resolver for semantic color keys |
+| `usePrefersDarkMode()` | `boolean`                                               | OS `prefers-color-scheme: dark` only              |
 
 Import from `@codecademy/gamut-styles`.
 
+**Storybook:** [Foundations / ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page) · [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page)
+
 ## Common mistakes
 
 - Do not use raw color tokens (`navy-400`, `white`) for text/backgrounds that must be accessible across modes — use semantic aliases.

@@ -11,6 +11,8 @@ Gamut is the Codecademy / Skillsoft design system — React component library (`
 - Mobile-first, 12-column grid
 - Semantic color tokens guarantee WCAG AA contrast automatically
 
+**ColorMode in product UI:** Use `<ColorMode>` and `<Background>` from `@codecademy/gamut-styles` for scoped light/dark and contrast-safe surfaces — see [foundations/modes.md](foundations/modes.md) and the `gamut-color-mode` skill. Storybook: [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page), [Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) (semantic tokens + `css` / `variant` / `states`).
+
 ## Themes
 
 | Theme         | Product                         | Base font      | Dark mode |

@@ -62,7 +62,7 @@ Use `<Text screenreader>` for visually hidden but announced content. `<HiddenTex
 
 ## Color and contrast
 
-Do not hardcode hex values for adaptive UI. Gamut semantic color tokens through `ColorMode` are built for WCAG AA; see the `gamut-color-mode` skill for token usage. For non-text contrast, focus order, and ARIA beyond color, see `gamut-accessibility`.
+Do not hardcode hex values for adaptive UI. Gamut semantic color tokens through `ColorMode` are built for WCAG AA; see the `gamut-color-mode` skill for token usage. Semantic colors only guarantee contrast when the subtree is under the right **ColorMode** or **`<Background>`** context — use those primitives for section surfaces, not ad hoc `background-color`. For non-text contrast, focus order, and ARIA beyond color, see `gamut-accessibility`.
 
 ## Focus visibility
 

@@ -22,6 +22,8 @@ Gamut's color system uses **semantic aliases** instead of raw color tokens. This
 
 **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.
+
 ## `<ColorMode />`
 
 Wraps content in a color mode context. Nest these to create scoped mode regions.
@@ -64,31 +66,31 @@ When `<Background>` is rendered, it sets a `background-current` CSS variable on
 
 ```tsx
 import {
-  useColorMode,
+  useColorModes,
   useCurrentMode,
   usePrefersDarkMode,
 } from '@codecademy/gamut-styles';
 
-// Returns [currentModeKey, currentModeColors, allModes]
-const [current, currentColors, modes] = useColorMode();
+// Returns [activeModeKey, currentModeColorMap, allModesConfig, getColorValue]
+const [mode, modeColors, modes, getColorValue] = useColorModes();
 
 // Returns just the active mode key: "light" | "dark"
-const current = useCurrentMode();
+const activeMode = useCurrentMode();
 
 // Returns 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 and their color variables                    | `useColorMode()`                   |
-| Detect OS dark mode preference                                | `usePrefersDarkMode()`             |
-| Access full emotion theme                                     | `useTheme()` from `@emotion/react` |
+| Need                                                                                              | Use                                                           |
+| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Set a page or section to a specific mode                                                          | `<ColorMode mode="light">`, `mode="dark"`, or `mode="system"` |
+| Place content on a colored background with automatic contrast                                     | `<Background bg="...">`                                       |
+| Read the current mode in JavaScript                                                               | `useCurrentMode()`                                            |
+| Access active mode, resolved semantic colors for that mode, all mode configs, and `getColorValue` | `useColorModes()`                                             |
+| Detect OS dark mode preference                                                                    | `usePrefersDarkMode()`                                        |
+| Access full Emotion theme                                                                         | `useTheme()` from `@emotion/react`                            |
 
 ## Common mistakes to avoid
 

@@ -9,7 +9,7 @@ Source: `@codecademy/gamut-styles` — [`variance/config.ts`](https://github.com
 
 ## Overview
 
-System props are strongly-typed, theme-connected CSS prop groups from `@codecademy/gamut-styles`. They give styled components a consistent, responsive API. All props are built on top of `@codecademy/variance`.
+System props are strongly-typed, theme-connected CSS prop groups from `@codecademy/gamut-styles`. They give styled components a consistent, responsive API. All props are built on top of `@codecademy/variance`. Semantic color props assume the subtree is under the correct **ColorMode** / **Background** context when those surfaces need to adapt — see [`gamut-color-mode`](../gamut-color-mode/SKILL.md).
 
 Each prop group has:
 

@@ -11,6 +11,8 @@ Source: `@codecademy/gamut-styles`
 
 Gamut uses Emotion's theme system. All styled components have access to a typed theme object containing every design token. Themes are org-specific collections of tokens; components work across all themes without modification as long as they use token aliases rather than hardcoded values.
 
+**See also:** [`gamut-color-mode`](../gamut-color-mode/SKILL.md) for `<ColorMode>`, `<Background>`, `useColorModes`, and contrast-safe surfaces — read that before wiring light/dark or colored sections. Storybook: [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page), [Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page).
+
 ## Available themes
 
 | Theme     | Used for                                                   |