From f104e917a930c09d81806b3cb01de205c91836d4 Mon Sep 17 00:00:00 2001 From: dreamwasp Date: Wed, 13 May 2026 10:09:29 -0400 Subject: [PATCH] add color mode mentions --- .../guidelines/foundations/modes.md | 12 +++++---- .../gamut-agent-tools/guidelines/overview.md | 2 ++ .../gamut-agent-tools/rules/accessibility.mdc | 2 +- .../skills/gamut-color-mode/SKILL.md | 26 ++++++++++--------- .../skills/gamut-system-props/SKILL.md | 2 +- .../skills/gamut-theming/SKILL.md | 2 ++ 6 files changed, 27 insertions(+), 19 deletions(-) diff --git a/packages/gamut-agent-tools/guidelines/foundations/modes.md b/packages/gamut-agent-tools/guidelines/foundations/modes.md index 99861b4acf..abf3793481 100644 --- a/packages/gamut-agent-tools/guidelines/foundations/modes.md +++ b/packages/gamut-agent-tools/guidelines/foundations/modes.md @@ -30,14 +30,16 @@ Nesting is supported — each `` 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. diff --git a/packages/gamut-agent-tools/guidelines/overview.md b/packages/gamut-agent-tools/guidelines/overview.md index 3077c0033f..87f32cc1b6 100644 --- a/packages/gamut-agent-tools/guidelines/overview.md +++ b/packages/gamut-agent-tools/guidelines/overview.md @@ -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 `` and `` 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 | diff --git a/packages/gamut-agent-tools/rules/accessibility.mdc b/packages/gamut-agent-tools/rules/accessibility.mdc index 22fd3a871e..bb1678509a 100644 --- a/packages/gamut-agent-tools/rules/accessibility.mdc +++ b/packages/gamut-agent-tools/rules/accessibility.mdc @@ -62,7 +62,7 @@ Use `` for visually hidden but announced content. ``** 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 diff --git a/packages/gamut-agent-tools/skills/gamut-color-mode/SKILL.md b/packages/gamut-agent-tools/skills/gamut-color-mode/SKILL.md index 062d0a5b04..b8b8463353 100644 --- a/packages/gamut-agent-tools/skills/gamut-color-mode/SKILL.md +++ b/packages/gamut-agent-tools/skills/gamut-color-mode/SKILL.md @@ -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. + ## `` Wraps content in a color mode context. Nest these to create scoped mode regions. @@ -64,16 +66,16 @@ When `` 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(); @@ -81,14 +83,14 @@ const prefersDark = usePrefersDarkMode(); ## Decision guide -| Need | Use | -| ------------------------------------------------------------- | ---------------------------------- | ---- | --------- | -| Set a page or section to a specific mode | `` | -| Place content on a colored background with automatic contrast | `` | -| 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 | ``, `mode="dark"`, or `mode="system"` | +| Place content on a colored background with automatic contrast | `` | +| 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 diff --git a/packages/gamut-agent-tools/skills/gamut-system-props/SKILL.md b/packages/gamut-agent-tools/skills/gamut-system-props/SKILL.md index a1eb06e6f6..6b9b3c80ef 100644 --- a/packages/gamut-agent-tools/skills/gamut-system-props/SKILL.md +++ b/packages/gamut-agent-tools/skills/gamut-system-props/SKILL.md @@ -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: diff --git a/packages/gamut-agent-tools/skills/gamut-theming/SKILL.md b/packages/gamut-agent-tools/skills/gamut-theming/SKILL.md index b1e17b7c97..583ab57e9f 100644 --- a/packages/gamut-agent-tools/skills/gamut-theming/SKILL.md +++ b/packages/gamut-agent-tools/skills/gamut-theming/SKILL.md @@ -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 ``, ``, `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 |