From b0c870ae727cd816ee69ad727ef6b3b92a89ca1c Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 10:04:01 -0400
Subject: [PATCH 01/11] chore(ai-tools): skill audit

---
 .../guidelines/foundations/modes.md           |  14 ++-
 .../gamut/agent-tools/guidelines/overview.md  |  35 +++---
 .../gamut/agent-tools/rules/accessibility.mdc |   5 +-
 .../skills/gamut-color-mode/SKILL.md          | 113 ++++++++++++------
 .../lib/Foundations/ColorMode/ColorMode.mdx   |  12 +-
 5 files changed, 111 insertions(+), 68 deletions(-)

diff --git a/packages/gamut/agent-tools/guidelines/foundations/modes.md b/packages/gamut/agent-tools/guidelines/foundations/modes.md
index c39db9880e2..00802c917c9 100644
--- a/packages/gamut/agent-tools/guidelines/foundations/modes.md
+++ b/packages/gamut/agent-tools/guidelines/foundations/modes.md
@@ -23,21 +23,23 @@ Use `<Background>` — not a raw `bg` prop — whenever setting a colored backgr
 ```tsx
 import { Background } from '@codecademy/gamut-styles';
 
-<Background bg="hyper">{children}</Background>
+<Background bg="hyper">{children}</Background>;
 ```
 
 Nesting is supported — each `<Background>` creates its own accessible color context.
 
 ## 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                              |
+| `useColorMode()`       | `[modeKey, modeColors, allModes]` | Full mode data + resolver for semantic color keys |
+| `usePrefersDarkMode()` | `boolean`                         | Read OS dark preference 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 7a411433d14..301f8307100 100644
--- a/packages/gamut/agent-tools/guidelines/overview.md
+++ b/packages/gamut/agent-tools/guidelines/overview.md
@@ -5,31 +5,34 @@ Gamut is the Codecademy / Skillsoft design system — React component library (`
 **Design voice**: "Ruled by logic, but creative and a bit unexpected." Structured and trustworthy for a learning platform, with engaging personality. Medium density — information-rich layouts with strong typographic hierarchy. Never cramped or overly airy.
 
 **Core principles**:
+
 - Components are color mode–aware by default — never hardcode hex values for adaptive UI
 - All components work across all themes without modification
 - 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 |
-|---|---|---|---|
-| **Core** | Codecademy (default) | Apercu | ✓ |
-| **Admin** | Codecademy admin tools | Apercu | ✓ |
-| **Platform** | Codecademy learning environment | Apercu | ✓ |
-| **LX Studio** | LX Studio application | Hanken Grotesk | — |
-| **Percipio** | Skillsoft Percipio | Roboto | — |
+| Theme         | Product                         | Base font      | Dark mode |
+| ------------- | ------------------------------- | -------------- | --------- |
+| **Core**      | Codecademy (default)            | Apercu         | ✓         |
+| **Admin**     | Codecademy admin tools          | Apercu         | ✓         |
+| **Platform**  | Codecademy learning environment | Apercu         | ✓         |
+| **LX Studio** | LX Studio application           | Hanken Grotesk | —         |
+| **Percipio**  | Skillsoft Percipio              | Roboto         | —         |
 
 Set the theme at the app root via `<GamutProvider theme={...}>`.
 
 ## Reading order
 
-| File | What it covers |
-|---|---|
-| [setup.md](setup.md) | Packages, GamutProvider, theme selection |
-| [foundations/color.md](foundations/color.md) | Semantic aliases, raw palette, decision guide |
-| [foundations/modes.md](foundations/modes.md) | Light/dark ColorMode, Background component |
-| [foundations/typography.md](foundations/typography.md) | Typefaces, font scale, rules |
-| [foundations/spacing.md](foundations/spacing.md) | Spacing, border radius, responsive grid |
-| [components/overview.md](components/overview.md) | Full component catalog |
-| [components/buttons.md](components/buttons.md) | Button variants, props, decision tree |
+| File                                                   | What it covers                                |
+| ------------------------------------------------------ | --------------------------------------------- |
+| [setup.md](setup.md)                                   | Packages, GamutProvider, theme selection      |
+| [foundations/color.md](foundations/color.md)           | Semantic aliases, raw palette, decision guide |
+| [foundations/modes.md](foundations/modes.md)           | Light/dark ColorMode, Background component    |
+| [foundations/typography.md](foundations/typography.md) | Typefaces, font scale, rules                  |
+| [foundations/spacing.md](foundations/spacing.md)       | Spacing, border radius, responsive grid       |
+| [components/overview.md](components/overview.md)       | Full component catalog                        |
+| [components/buttons.md](components/buttons.md)         | Button variants, props, decision tree         |
diff --git a/packages/gamut/agent-tools/rules/accessibility.mdc b/packages/gamut/agent-tools/rules/accessibility.mdc
index 22fd3a871e7..b3f2fb9afa7 100644
--- a/packages/gamut/agent-tools/rules/accessibility.mdc
+++ b/packages/gamut/agent-tools/rules/accessibility.mdc
@@ -1,7 +1,7 @@
 ---
 description: Apply these guardrails when editing Gamut UI in TS/JS/TSX/JSX. Mirrors the General rules in the `gamut-accessibility` skill; see `skills/gamut-accessibility/SKILL.md` in this plugin for full component patterns and checklists. Loaded automatically for matched files.
 alwaysApply: true
-globs: ["*.tsx", "*.ts", "*.jsx", "*.js"]
+globs: ['*.tsx', '*.ts', '*.jsx', '*.js']
 ---
 
 # Gamut Accessibility Rules
@@ -18,7 +18,6 @@ ARIA roles modify the accessibility tree and _imply_ behavior. Always ensure tha
 
 ARIA can augment native semantics (`aria-pressed` on a `<button>`) or override them entirely (`role="menuitem"` on an `<a>`). Both capabilities are powerful and dangerous. Override only when native HTML genuinely doesn't fit the pattern; when augmenting, don't contradict the native semantics.
 
-
 ## Align accessible names with visible copy
 
 Prefer wiring names through visible text and native `<label>` / control text / `alt` over using `aria-label`. Point `aria-labelledby` at the visible heading or label that should define the name if it's not possible to name elements from their content. Use bare `aria-label` when there is no suitable visible label.
@@ -62,7 +61,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
 
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 b610fe0c7aa..61dd55dad15 100644
--- a/packages/gamut/agent-tools/skills/gamut-color-mode/SKILL.md
+++ b/packages/gamut/agent-tools/skills/gamut-color-mode/SKILL.md
@@ -13,51 +13,85 @@ Gamut's color system uses **semantic aliases** instead of raw color tokens. This
 
 ### 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 |
+| 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.
+
 ## `<ColorMode />`
 
-Wraps content in a color mode context. Nest these to create scoped mode regions.
+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 mode
-const Page = ({ children }) => (
-  <ColorMode mode="light">{children}</ColorMode>
-);
+// Explicit light or dark
+<ColorMode mode="light">{children}</ColorMode>
 
-// Follows the user's OS preference (prefers-color-scheme)
-const Page = ({ children }) => (
-  <ColorMode mode="system">{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>` — not raw `bg` prop — whenever you need a specific background color for a section (card, landing page, hero, etc.). It **automatically switches the color mode** to ensure the content inside meets contrast requirements.
+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>
-);
+const Card = ({ children }) => <Background bg="hyper">{children}</Background>;
 
-// Nested backgrounds — each creates its own accessible color context
+// Nested backgrounds — each creates its own color context
 const Page = () => (
-  <Background bg="black">
-    <Background bg="paleGreen" />
+  <Background bg="black" p={24}>
+    <Background bg="paleGreen" p={24}>
+      {/* content inside inner Background uses its own mode */}
+    </Background>
   </Background>
 );
 ```
@@ -69,31 +103,36 @@ When `<Background>` is rendered, it sets a `background-current` CSS variable on
 ## Color mode hooks
 
 ```tsx
-import { useColorMode, useCurrentMode, usePrefersDarkMode } from '@codecademy/gamut-styles';
+import {
+  useColorModes,
+  useCurrentMode,
+  usePrefersDarkMode,
+} from '@codecademy/gamut-styles';
 
-// Returns [currentModeKey, currentModeColors, allModes]
-const [current, currentColors, modes] = useColorMode();
+// [activeModeKey, activeModeColors, allModes, getColorValue]
+const [current, currentColors, modes, getColorValue] = useColorModes();
 
-// Returns just the active mode key: "light" | "dark"
+// Active mode key: "light" | "dark" (optional override argument)
 const current = useCurrentMode();
+const forced = useCurrentMode('light');
 
-// Returns boolean from window.matchMedia('(prefers-color-scheme: dark)')
+// 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            | 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 raw `bg` prop for colored section backgrounds that contain text or interactive elements — use `<Background>` so contrast is guaranteed.
-- Do not manually toggle modes based on `usePrefersDarkMode()` — use `<ColorMode mode="system">` 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).
diff --git a/packages/styleguide/src/lib/Foundations/ColorMode/ColorMode.mdx b/packages/styleguide/src/lib/Foundations/ColorMode/ColorMode.mdx
index 9e5964a3256..c7383fc9d36 100644
--- a/packages/styleguide/src/lib/Foundations/ColorMode/ColorMode.mdx
+++ b/packages/styleguide/src/lib/Foundations/ColorMode/ColorMode.mdx
@@ -101,17 +101,17 @@ const Page = ({ children }) => (
 );
 ```
 
-## `useCurrentMode` | `useColorMode`
+## `useCurrentMode` | `useColorModes`
 
-For situations where you need to access the current mode in JS, the value of always present on the emotion theme context. If you need the full theme you may use the built in `useTheme` hook from `@emotion/react`. However for cases that are specific to modes only we expose 2 hooks to help.
+For situations where you need to access the current mode in JS, the value is always present on the emotion theme context. If you need the full theme you may use the built in `useTheme` hook from `@emotion/react`. However for cases that are specific to modes only we expose 2 hooks to help.
 
-- `useColorMode()`: If you need access to all modes and their variables this hook will return a tuple of `[mode, modeColors, modes]`.
-- `useCurrentMode()`: For simpler usages where you want to get the default mode, this hook returns the key of the active mode.
+- `useColorModes()`: If you need access to all modes and their variables this hook returns a tuple of `[mode, modeColors, modes, getColorValue]`.
+- `useCurrentMode(mode?)`: For simpler usages where you want the active mode key, or to override with a specific mode.
 
 ```tsx
-import { useColorMode, useCurrentMode } from '@codecademy/gamut-styles';
+import { useColorModes, useCurrentMode } from '@codecademy/gamut-styles';
 
-const [current, currentColors, modes] = useColorMode();
+const [current, currentColors, modes, getColorValue] = useColorModes();
 
 const current = useCurrentMode();
 ```

From c9d9c71dd82fddda86efb994b08850b13ad5a671 Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 10:33:24 -0400
Subject: [PATCH 02/11] gamut-review

---
 .../agent-tools/commands/gamut-review.md      | 217 +++++++++++-------
 1 file changed, 139 insertions(+), 78 deletions(-)

diff --git a/packages/gamut/agent-tools/commands/gamut-review.md b/packages/gamut/agent-tools/commands/gamut-review.md
index 0545be9a65c..b26b67b9c80 100644
--- a/packages/gamut/agent-tools/commands/gamut-review.md
+++ b/packages/gamut/agent-tools/commands/gamut-review.md
@@ -16,11 +16,11 @@ Run all five checks below, then print a single consolidated report using the for
 
 Read `package.json` (and `package.json` in `$ARGUMENTS` if a path was given). Inspect `dependencies`, `devDependencies`, and `peerDependencies` combined.
 
-| Package | Expectation |
-|---|---|
-| `@codecademy/gamut` | **Required** — core component library |
-| `@codecademy/gamut-styles` | Recommended — design tokens and theme primitives |
-| `@codecademy/variance` | Recommended — style-prop system used by Gamut internals |
+| Package                    | Expectation                                             |
+| -------------------------- | ------------------------------------------------------- |
+| `@codecademy/gamut`        | **Required** — core component library                   |
+| `@codecademy/gamut-styles` | Recommended — design tokens and theme primitives        |
+| `@codecademy/variance`     | Recommended — style-prop system used by Gamut internals |
 
 ---
 
@@ -28,11 +28,11 @@ Read `package.json` (and `package.json` in `$ARGUMENTS` if a path was given). In
 
 Search source files (`.ts`, `.tsx`, `.js`, `.jsx`) for these symbols. Skip `node_modules`, `dist`, `.next`, `build`, `.turbo`.
 
-| Symbol | Expectation |
-|---|---|
-| `GamutProvider` | **Required** — must appear at least once (app root wrapper) |
-| `ColorMode` | Recommended — enables semantic light/dark theming |
-| `Background` | Recommended — semantic surface color via `@codecademy/gamut-styles` |
+| Symbol          | Expectation                                                         |
+| --------------- | ------------------------------------------------------------------- |
+| `GamutProvider` | **Required** — must appear at least once (app root wrapper)         |
+| `ColorMode`     | Recommended — enables semantic light/dark theming                   |
+| `Background`    | Recommended — semantic surface color via `@codecademy/gamut-styles` |
 
 For each found symbol report the first file path where it appears.
 
@@ -42,71 +42,131 @@ For each found symbol report the first file path where it appears.
 
 Grep source files for any of these patterns. Each match is an error.
 
-| Pattern | Reason |
-|---|---|
-| `@codecademy/gamut/dist/` | Deep dist import — bypasses public API and breaks on internal refactors |
-| `@codecademy/gamut/src/` | Deep src import — not part of the published package |
-| `@codecademy/gamut-styles/src/` | Deep src import — use the package root |
-| `@codecademy/variance/src/` | Deep src import — use the package root |
+| Pattern                         | Reason                                                                  |
+| ------------------------------- | ----------------------------------------------------------------------- |
+| `@codecademy/gamut/dist/`       | Deep dist import — bypasses public API and breaks on internal refactors |
+| `@codecademy/gamut/src/`        | Deep src import — not part of the published package                     |
+| `@codecademy/gamut-styles/src/` | Deep src import — use the package root                                  |
+| `@codecademy/variance/src/`     | Deep src import — use the package root                                  |
 
 Report each violation as `file:line`.
 
 ---
 
-## Check 4 — Hardcoded colors
-
-Grep source files (`.ts`, `.tsx`, `.js`, `.jsx`, `.css`, `.scss`, `.less`) for inline hex color literals (`#RGB` or `#RRGGBB`). For each match, suggest the Gamut token name using this table (case-insensitive comparison):
-
-| Hex | Token |
-|---|---|
-| `#000000` | `black` |
-| `#ffffff` | `white` |
-| `#10162f` | `navy` / `navy-800` |
-| `#0a0d1c` | `navy-900` |
-| `#fff0e5` | `beige-100` |
-| `#f5fcff` | `blue-0` |
-| `#d3f2ff` | `blue-100` |
-| `#66c4ff` | `blue-300` |
-| `#3388ff` | `blue-400` |
-| `#1557ff` | `blue-500` |
-| `#1d2340` | `blue-800` |
-| `#f5ffe3` | `green-0` |
-| `#eafdc6` | `green-100` |
+## Check 4 — Hardcoded colors (semantic-first)
+
+**Rule:** Inline hex literals in application UI code are violations. Remediation is **not** “replace hex with `navy-800`” — prefer **semantic ColorMode tokens** (`text`, `background`, `primary`, …) so light/dark and theme switches stay correct. Reserve **raw palette tokens** for colors that must stay fixed and for **`bg` on `<Background>`** from `@codecademy/gamut-styles` (section surfaces with content).
+
+Align findings with project docs and Storybook:
+
+- [@codecademy/gamut agent-tools `guidelines/foundations/color.md`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/agent-tools/guidelines/foundations/color.md) — decision guide and semantic tables.
+- [Foundations / ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page) — aliases per mode; `<Background>` behavior.
+- [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) — semantic colors + `css` / `variant` / `states` from `gamut-styles`.
+- Foundations / Theme stories (Core, Admin, Platform, Percipio, LX Studio) — verify hex ↔ semantic if the product is not Codecademy Core.
+
+**Theme context:** Infer from `GamutProvider` / app config / root `DESIGN.md` (from `DESIGN.Codecademy.md`, `DESIGN.Percipio.md`, or `DESIGN.LXStudio.md`). If unknown, **assume Codecademy Core** semantics below and add a report note to confirm against the correct theme Storybook page.
+
+**Discovery:** Grep source files (`.ts`, `.tsx`, `.js`, `.jsx`, `.css`, `.scss`, `.less`) for inline hex literals (`#RGB` or `#RRGGBB`). Comparison is case-insensitive. Skip `node_modules`, `dist`, `.next`, `build`, `.turbo` (same spirit as other checks).
+
+### Workflow (each hex match)
+
+1. **Context** — Inspect the surrounding line(s): CSS property (`color`, `background`, `border-color`, …), JSX prop (`color`, `bg`, `borderColor`, SVG fill), or asset. Note whether the subtree is a **section with content** (candidate for `<Background>` + palette `bg`) vs component chrome (prefer semantics).
+2. **Identify palette** — Normalize hex (case-insensitive); map to a Gamut palette name using **Appendix A** below. If missing from the appendix, match against `DESIGN.md` / `packages/gamut-styles` palette definitions.
+3. **Recommend semantic first** — Use **Appendix B** (Core **light** literals from `color.md`) plus role:
+   - Body / UI foreground → `text`; strong emphasis → `text-accent`.
+   - Page or card fill → `background` / `background-primary` / state surfaces (`background-success`, `background-warning`, `background-error`).
+   - CTAs, links, hyper accents → `primary` (+ `primary-hover` on hover); toggles / checkboxes → `interface`.
+   - Ghost / secondary buttons → `secondary`.
+   - Destructive → `danger` / `danger-hover`.
+   - Dividers / outlines → `border-primary` / `border-secondary` / `border-tertiary`.
+   - Inline feedback copy → `feedback-error` / `feedback-success` / `feedback-warning`.
+   - **Disambiguation:** `#FFD300` — warning copy → `feedback-warning`; yellow accent on top of primary-colored surfaces → `primary-inverse`.
+   - Same hex can map to multiple semantics (e.g. `#10162F` → `text` vs `border-primary` vs `secondary`): pick from **property + component role**.
+4. **When palette-only is OK** — **`bg` prop on `<Background>`** (`<Background bg="hyper">`, etc.) is the primary place for **fixed surface** palette colors on sections (see `color.md` decision guide + ColorMode docs). After replacing hex there, use a **named palette token**, not hex. **Exceptions** (flag with rationale): charts/data viz, third-party widgets, exported static illustrations — still prefer tokens over hex when feasible.
+
+**Severity:** Hex on adaptive UI (random wrappers, `styled-components`, inline `style`) → **error**. Hex inside documented exceptions → **warning** with note.
+
+**Reporting:** For each match outside token definition files:
+
+`file:line  'HEX'  →  semantic: <token(s)> | palette: <token> | note: <theme/disambiguation>`
+
+Use `semantic: (n/a)` only when no semantic applies (e.g. pure illustration); still give `palette: …`. If unmappable: `→  no Gamut token`.
+
+Ignore hex inside design token definition files (e.g. `variables/colors.ts`, `_colors.scss`) — source of truth, not violations.
+
+### Appendix B — Core light: hex → suggested semantic (shortcut)
+
+Use with step 3; verify for non-Core themes. Opacity variants in `color.md` are not listed here — keep using the named semantic token.
+
+| Hex (normalized) | Typical semantic direction                                                                                               |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `#10162f`        | `text`, `border-primary`, or `secondary` (by role)                                                                       |
+| `#0a0d1c`        | `text-accent`                                                                                                            |
+| `#ffffff`        | `background` (fills), `secondary` (inverse ghost on dark — rare in light-only grep context)                              |
+| `#fff0e5`        | `background-primary`                                                                                                     |
+| `#f5ffe3`        | `background-success`                                                                                                     |
+| `#fffae5`        | `background-warning`                                                                                                     |
+| `#fbf1f0`        | `background-error`                                                                                                       |
+| `#3a10e5`        | `primary`, `interface` (controls vs marketing CTA — prefer `primary` for links/buttons)                                  |
+| `#5533ff`        | `primary-hover`, `interface-hover`                                                                                       |
+| `#ffd300`        | `feedback-warning` or `primary-inverse` (see disambiguation above)                                                       |
+| `#cca900`        | Often pairs with hover in dark mode; in light UI as literal hex → check palette appendix (`yellow-400`) then assign role |
+| `#e91c11`        | `danger`                                                                                                                 |
+| `#be1809`        | `danger-hover`, `feedback-error`                                                                                         |
+| `#008a27`        | `feedback-success`                                                                                                       |
+
+Hexes with **no row above** still get **Appendix A** palette id + role-based semantic guess (e.g. blue scale → often decorative or legacy marketing; prefer design review unless mapping clearly to `primary`).
+
+### Appendix A — Hex → palette token (identification only)
+
+Case-insensitive. Use to label `palette:` in the report; **do not** stop at this step without Appendix B / role triage.
+
+| Hex       | Token                      |
+| --------- | -------------------------- |
+| `#000000` | `black`                    |
+| `#ffffff` | `white`                    |
+| `#10162f` | `navy` / `navy-800`        |
+| `#0a0d1c` | `navy-900`                 |
+| `#fff0e5` | `beige-100`                |
+| `#f5fcff` | `blue-0`                   |
+| `#d3f2ff` | `blue-100`                 |
+| `#66c4ff` | `blue-300`                 |
+| `#3388ff` | `blue-400`                 |
+| `#1557ff` | `blue-500`                 |
+| `#1d2340` | `blue-800`                 |
+| `#f5ffe3` | `green-0`                  |
+| `#eafdc6` | `green-100`                |
 | `#aee938` | `green-400` / `lightGreen` |
-| `#008a27` | `green-700` |
-| `#151c07` | `green-900` |
-| `#fffae5` | `yellow-0` |
-| `#cca900` | `yellow-400` |
-| `#ffd300` | `yellow-500` / `yellow` |
-| `#211b00` | `yellow-900` |
-| `#fff5ff` | `pink-0` |
-| `#f966ff` | `pink-400` / `pink` |
-| `#fbf1f0` | `red-0` |
-| `#e85d7f` | `red-300` |
-| `#dc5879` | `red-400` / `paleRed` |
-| `#e91c11` | `red-500` / `red` |
-| `#be1809` | `red-600` |
-| `#280503` | `red-900` |
-| `#ffe8cc` | `orange-100` |
-| `#ff8c00` | `orange-500` / `orange` |
-| `#5533ff` | `hyper-400` |
-| `#3a10e5` | `hyper-500` / `hyper` |
-| `#f5f5f5` | `gray-100` |
-| `#eeeeee` | `gray-200` |
-| `#e0e0e0` | `gray-300` |
-| `#9e9e9e` | `gray-600` |
-| `#616161` | `gray-800` |
-| `#424242` | `gray-900` |
-| `#fffbf8` | `beige-0` |
-| `#8a7300` | `gold-800` / `gold` |
-| `#d14900` | `orange-800` |
-| `#ca00d1` | `pink-800` |
-| `#006d82` | `teal-500` / `teal` |
-| `#b3ccff` | `purple-300` / `purple` |
-
-Ignore hex values inside design token definition files themselves (e.g. `variables/colors.ts`, `_colors.scss`) — those are the source of truth, not violations.
-
-For each match outside token files report: `file:line  'HEX'  →  token` (or `→  no Gamut token` if unknown).
+| `#008a27` | `green-700`                |
+| `#151c07` | `green-900`                |
+| `#fffae5` | `yellow-0`                 |
+| `#cca900` | `yellow-400`               |
+| `#ffd300` | `yellow-500` / `yellow`    |
+| `#211b00` | `yellow-900`               |
+| `#fff5ff` | `pink-0`                   |
+| `#f966ff` | `pink-400` / `pink`        |
+| `#fbf1f0` | `red-0`                    |
+| `#e85d7f` | `red-300`                  |
+| `#dc5879` | `red-400` / `paleRed`      |
+| `#e91c11` | `red-500` / `red`          |
+| `#be1809` | `red-600`                  |
+| `#280503` | `red-900`                  |
+| `#ffe8cc` | `orange-100`               |
+| `#ff8c00` | `orange-500` / `orange`    |
+| `#5533ff` | `hyper-400`                |
+| `#3a10e5` | `hyper-500` / `hyper`      |
+| `#f5f5f5` | `gray-100`                 |
+| `#eeeeee` | `gray-200`                 |
+| `#e0e0e0` | `gray-300`                 |
+| `#9e9e9e` | `gray-600`                 |
+| `#616161` | `gray-800`                 |
+| `#424242` | `gray-900`                 |
+| `#fffbf8` | `beige-0`                  |
+| `#8a7300` | `gold-800` / `gold`        |
+| `#d14900` | `orange-800`               |
+| `#ca00d1` | `pink-800`                 |
+| `#006d82` | `teal-500` / `teal`        |
+| `#b3ccff` | `purple-300` / `purple`    |
 
 ---
 
@@ -114,13 +174,13 @@ For each match outside token files report: `file:line  'HEX'  →  token` (or `
 
 Grep test files (`**/__tests__/**/*.{ts,tsx}`, `**/*.test.{ts,tsx}`, `**/*.spec.{ts,tsx}`) for these patterns. Skip `node_modules`, `dist`.
 
-| Pattern | Verdict | Reason |
-|---|---|---|
-| `jest.mock\(.*@codecademy/gamut` | **Error** | Manual mocking bypasses theme context and produces false-positive tests; use `setupRtl` or `MockGamutProvider` instead |
-| `jest.mock\(.*@codecademy/gamut-styles` | **Error** | Same issue as above — mocking gamut-styles breaks token resolution |
-| `from '@codecademy/gamut-tests'` | Good — report count of files using it | Correct import for `setupRtl` and `MockGamutProvider` |
-| `from 'component-test-setup'` (without gamut-tests) | **Warning** | Should import `setupRtl` from `@codecademy/gamut-tests`, not directly from `component-test-setup` — the gamut-tests wrapper adds `MockGamutProvider` automatically |
-| `new GamutProvider` or `<GamutProvider` in test files | **Warning** | Tests should use `MockGamutProvider` (sets `useCache={false}`, `useGlobals={false}`), not `GamutProvider` directly |
+| Pattern                                               | Verdict                               | Reason                                                                                                                                                             |
+| ----------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `jest.mock\(.*@codecademy/gamut`                      | **Error**                             | Manual mocking bypasses theme context and produces false-positive tests; use `setupRtl` or `MockGamutProvider` instead                                             |
+| `jest.mock\(.*@codecademy/gamut-styles`               | **Error**                             | Same issue as above — mocking gamut-styles breaks token resolution                                                                                                 |
+| `from '@codecademy/gamut-tests'`                      | Good — report count of files using it | Correct import for `setupRtl` and `MockGamutProvider`                                                                                                              |
+| `from 'component-test-setup'` (without gamut-tests)   | **Warning**                           | Should import `setupRtl` from `@codecademy/gamut-tests`, not directly from `component-test-setup` — the gamut-tests wrapper adds `MockGamutProvider` automatically |
+| `new GamutProvider` or `<GamutProvider` in test files | **Warning**                           | Tests should use `MockGamutProvider` (sets `useCache={false}`, `useGlobals={false}`), not `GamutProvider` directly                                                 |
 
 Skill reference for remediation: `gamut-testing`
 
@@ -149,8 +209,9 @@ Import patterns
        src/Other.tsx:12
 
 Hardcoded colors                                                         [→ gamut-color-mode]
-  ⚠  src/Hero.tsx:14  '#1557FF'  →  blue-500
-  ⚠  src/Nav.tsx:8   '#BADA55'  →  no Gamut token
+  ✗  src/Card.tsx:22   '#10162F'  →  semantic: text | palette: navy-800 | note: Core light body copy
+  ⚠  src/Hero.tsx:14   '#1557FF'  →  semantic: primary (if link/CTA) | palette: blue-500 | note: no exact semantic; confirm theme
+  ⚠  src/Nav.tsx:8     '#BADA55'  →  semantic: (n/a) | palette: — | note: no Gamut token
 
 Test setup                                                               [→ gamut-testing]
   ✓  @codecademy/gamut-tests   used in 12 test files

From d3499c54f5e156309d3a4fd175740c5340e56a06 Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 11:00:55 -0400
Subject: [PATCH 03/11] button.md

---
 .../guidelines/components/buttons.md          | 93 ++++++++++++++-----
 1 file changed, 70 insertions(+), 23 deletions(-)

diff --git a/packages/gamut/agent-tools/guidelines/components/buttons.md b/packages/gamut/agent-tools/guidelines/components/buttons.md
index c7a487adbbb..3c41cccf59c 100644
--- a/packages/gamut/agent-tools/guidelines/components/buttons.md
+++ b/packages/gamut/agent-tools/guidelines/components/buttons.md
@@ -1,15 +1,43 @@
 # Buttons
 
-## Variants
+Agent reference: 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.
 
-| Component | Use for | Background | Text |
-|---|---|---|---|
-| `FillButton` | Primary CTA, high-emphasis actions | `primary` | `white` |
-| `StrokeButton` | Secondary actions, outlined style | transparent | `secondary` |
-| `CTAButton` | High-visibility marketing promotions | `primary` | `white` |
-| `CTAButton` (inverse) | CTA on a colored surface | `primary-inverse` | `secondary` |
-| `TextButton` | Low-emphasis, inline text actions | transparent | `primary` |
-| `IconButton` | Compact icon-only actions | — | — |
+**Related docs:** [overview.md](../overview.md) (reading order) · [foundations/color.md](../foundations/color.md) and `gamut-color-mode` skill — semantic tokens for **custom** styled controls only, not stock button atoms · [foundations/modes.md](../foundations/modes.md) — ColorMode / `<Background>` when placing buttons on colored surfaces
+
+**Storybook (UX source of truth):**
+
+- [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
 
@@ -17,28 +45,47 @@
 
 ## Key props
 
-| Prop | Type | Effect |
-|---|---|---|
-| `size` | `"small" \| "normal" \| "large"` | Controls padding and font size |
-| `icon` | Icon component | Leading or trailing icon |
-| `iconPosition` | `"left" \| "right"` | Defaults to left |
-| `disabled` | boolean | Disabled state styling |
-| `href` | string | Renders as `<a>` tag |
+| 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
 
-`default` → `hover` (`primary-hover` / `secondary-hover`) → `active` → `disabled` (`text-disabled` + `background-disabled`)
+Hover, active, and disabled colors are handled by the component. Do not override state colors with `color` / `bg` props.
 
-## Token cheatsheet
+## 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>
 ```
-FillButton   → bg: primary (#3A10E5 light / #FFD300 dark),  color: white,     hover: primary-hover
-StrokeButton → bg: transparent, border: secondary (#10162F / #fff), hover: secondary-hover
-TextButton   → bg: transparent, color: primary, hover: primary-hover
-```
+
+- **`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.
+- 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 [modes.md](../foundations/modes.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 [color.md](../foundations/color.md) and `gamut-styles` utilities — do not import internal `ButtonBase`.

From bd6f3c0498e84444b7e688e9fa7850fe6e2e175b Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 11:16:43 -0400
Subject: [PATCH 04/11] color.md;

---
 .../guidelines/foundations/color.md           | 202 +++++++++++++-----
 .../gamut/agent-tools/guidelines/overview.md  |  20 +-
 2 files changed, 154 insertions(+), 68 deletions(-)

diff --git a/packages/gamut/agent-tools/guidelines/foundations/color.md b/packages/gamut/agent-tools/guidelines/foundations/color.md
index 4f0084d3e1a..2e28af241dc 100644
--- a/packages/gamut/agent-tools/guidelines/foundations/color.md
+++ b/packages/gamut/agent-tools/guidelines/foundations/color.md
@@ -1,86 +1,172 @@
 # Color
 
-Use **semantic aliases** for all UI that adapts to color mode or theme. Use raw palette tokens only when a color must stay fixed regardless of mode.
+Use **semantic aliases** for UI that should respond to **color mode** (light/dark) and **theme** (Core, Admin, Platform, Percipio, LX Studio). The **same semantic token names** (`text`, `primary`, `background`, …) exist across themes; **resolved palette values and hex differ** by `GamutProvider` theme and active ColorMode. Never assume Codecademy Core hex when advising another product.
 
-## Semantic aliases
+Prefer **`css` / `variant` / `states`** from `@codecademy/gamut-styles` with semantic names (see Storybook [Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page)).
+
+**Related:** [`setup.md`](../setup.md) (which theme to import) · [`gamut-theming` skill](../../skills/gamut-theming/SKILL.md) · [`gamut-color-mode` skill](../../skills/gamut-color-mode/SKILL.md) · [`modes.md`](modes.md) (`<ColorMode>`, `<Background>`)
+
+Percipio, LX Studio, Admin, and Platform override subsets of semantic mappings while keeping the shared alias API — see theme sources below before hardcoding palette names or hex.
+
+## Semantic aliases (theme-stable names)
+
+These tokens describe **roles**. Actual colors come from the active theme + ColorMode.
+
+### Text
+
+| Token            | Use for                     | Notes                      |
+| ---------------- | --------------------------- | -------------------------- |
+| `text`           | Default body and UI text    |                            |
+| `text-accent`    | Stronger emphasis text      |                            |
+| `text-secondary` | Supporting / secondary copy | Often opacity on base text |
+| `text-disabled`  | Disabled state labels       |                            |
+
+### Background
+
+| Token                 | Use for                           | Notes                     |
+| --------------------- | --------------------------------- | ------------------------- |
+| `background`          | Default page/component background |                           |
+| `background-primary`  | Slightly elevated surfaces        |                           |
+| `background-contrast` | Maximum contrast surface          |                           |
+| `background-selected` | Selected row / item               | Often low-opacity overlay |
+| `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                                   | Notes                        |
+| ----------------- | ----------------------------------------- | ---------------------------- |
+| `primary`         | Primary CTA, links, focus accents         | Pairs with `primary-hover`   |
+| `primary-hover`   | Hover on primary interactive              |                              |
+| `primary-inverse` | Accent on top of primary-colored surfaces |                              |
+| `secondary`       | Secondary CTA, ghost buttons              | Pairs with `secondary-hover` |
+| `secondary-hover` | Hover on secondary interactive            |                              |
+| `interface`       | Checkboxes, toggles, sliders              | Pairs with `interface-hover` |
+| `interface-hover` | Hover on interface elements               |                              |
+| `danger`          | Destructive actions, error emphasis       | Pairs with `danger-hover`    |
+| `danger-hover`    | Hover on danger interactive               |                              |
+
+### Border
+
+| Token              | Use for                    | Notes |
+| ------------------ | -------------------------- | ----- |
+| `border-primary`   | Strong borders, dividers   |       |
+| `border-secondary` | Medium-weight borders      |       |
+| `border-tertiary`  | Subtle borders, separators |       |
+| `border-disabled`  | Disabled input borders     |       |
+
+### Feedback
+
+| Token              | Use for                    | Notes |
+| ------------------ | -------------------------- | ----- |
+| `feedback-error`   | Error messages, validation |       |
+| `feedback-success` | Success messages           |       |
+| `feedback-warning` | Warning messages           |       |
+
+## Where resolved colors are documented
+
+Use these instead of memorizing hex:
+
+- **Storybook [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page)** — how aliases map per light/dark for reference layouts.
+- **Storybook Foundations → Theme** — per-product tables and guidance:
+  - [Core Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-core-theme--docs)
+  - [Admin Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-admin-theme--docs)
+  - [Platform Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-platform-theme--docs)
+  - [Percipio Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-percipio-theme--docs)
+  - [LX Studio Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-lx-studio-theme--docs)
+  - [Creating Themes](https://gamut.codecademy.com/?path=/docs-foundations-theme-creating-themes--docs) — authoring new themes in `gamut-styles`
+- **Product design YAML** (root `DESIGN.md` from agent-tools): [`DESIGN.Codecademy.md`](../../DESIGN.Codecademy.md), [`DESIGN.Percipio.md`](../../DESIGN.Percipio.md), [`DESIGN.LXStudio.md`](../../DESIGN.LXStudio.md) — semantic ↔ palette for that product.
+- **Source:** theme definitions in [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes), palette scales in [`packages/gamut-styles/src/variables`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/variables).
+
+## Codecademy Core — illustrative light/dark hex only
+
+The tables below are **not** valid for Percipio, LX Studio, or other themes. They are a quick mental model for Codecademy **Core** defaults only.
 
 ### Text
 
-| Token | Light | Dark | Use for |
-|---|---|---|---|
-| `text` | `#10162F` | `#ffffff` | Default body and UI text |
-| `text-accent` | `#0A0D1C` | `#FFF0E5` | Stronger emphasis text |
-| `text-secondary` | navy-800 75% | white 65% | Supporting / secondary copy |
-| `text-disabled` | navy-800 63% | white 50% | Disabled state labels |
+| Token            | Light        | Dark      |
+| ---------------- | ------------ | --------- |
+| `text`           | `#10162F`    | `#ffffff` |
+| `text-accent`    | `#0A0D1C`    | `#FFF0E5` |
+| `text-secondary` | navy-800 75% | white 65% |
+| `text-disabled`  | navy-800 63% | white 50% |
 
 ### Background
 
-| Token | Light | Dark | Use for |
-|---|---|---|---|
-| `background` | `#ffffff` | `#10162F` | Default page/component background |
-| `background-primary` | `#FFF0E5` | `#0A0D1C` | Slightly elevated surfaces |
-| `background-contrast` | white | black | Maximum contrast surface |
-| `background-selected` | navy-800 4% | white 4% | Selected row / item |
-| `background-hover` | navy-800 12% | white 9% | Hover state overlay |
-| `background-disabled` | navy-800 12% | white 9% | Disabled surface |
-| `background-success` | `#F5FFE3` | `#151C07` | Success state container |
-| `background-warning` | `#FFFAE5` | `#211B00` | Warning state container |
-| `background-error` | `#FBF1F0` | `#280503` | Error state container |
+| Token                 | Light        | Dark      |
+| --------------------- | ------------ | --------- |
+| `background`          | `#ffffff`    | `#10162F` |
+| `background-primary`  | `#FFF0E5`    | `#0A0D1C` |
+| `background-contrast` | white        | black     |
+| `background-selected` | navy-800 4%  | white 4%  |
+| `background-hover`    | navy-800 12% | white 9%  |
+| `background-disabled` | navy-800 12% | white 9%  |
+| `background-success`  | `#F5FFE3`    | `#151C07` |
+| `background-warning`  | `#FFFAE5`    | `#211B00` |
+| `background-error`    | `#FBF1F0`    | `#280503` |
 
 ### Interactive
 
-| Token | Light | Dark | Use for |
-|---|---|---|---|
-| `primary` | `#3A10E5` | `#FFD300` | Primary CTA, links, focus rings |
-| `primary-hover` | `#5533FF` | `#CCA900` | Hover on primary interactive |
-| `primary-inverse` | `#FFD300` | `#3A10E5` | Primary on a colored background |
-| `secondary` | `#10162F` | `#ffffff` | Secondary CTA, ghost buttons |
-| `secondary-hover` | navy-800 86% | white 80% | Hover on secondary interactive |
-| `interface` | `#3A10E5` | `#FFD300` | Checkboxes, toggles, sliders |
-| `interface-hover` | `#5533FF` | `#CCA900` | Hover on interface elements |
-| `danger` | `#E91C11` | `#E85D7F` | Destructive actions, error states |
-| `danger-hover` | `#BE1809` | `#DC5879` | Hover on danger interactive |
+| Token             | Light        | Dark      |
+| ----------------- | ------------ | --------- |
+| `primary`         | `#3A10E5`    | `#FFD300` |
+| `primary-hover`   | `#5533FF`    | `#CCA900` |
+| `primary-inverse` | `#FFD300`    | `#3A10E5` |
+| `secondary`       | `#10162F`    | `#ffffff` |
+| `secondary-hover` | navy-800 86% | white 80% |
+| `interface`       | `#3A10E5`    | `#FFD300` |
+| `interface-hover` | `#5533FF`    | `#CCA900` |
+| `danger`          | `#E91C11`    | `#E85D7F` |
+| `danger-hover`    | `#BE1809`    | `#DC5879` |
 
 ### Border
 
-| Token | Light | Dark | Use for |
-|---|---|---|---|
-| `border-primary` | `#10162F` | `#ffffff` | Strong borders, dividers |
-| `border-secondary` | navy-800 75% | white 65% | Medium-weight borders |
-| `border-tertiary` | navy-800 28% | white 20% | Subtle borders, separators |
-| `border-disabled` | navy-800 63% | white 50% | Disabled input borders |
+| Token              | Light        | Dark      |
+| ------------------ | ------------ | --------- |
+| `border-primary`   | `#10162F`    | `#ffffff` |
+| `border-secondary` | navy-800 75% | white 65% |
+| `border-tertiary`  | navy-800 28% | white 20% |
+| `border-disabled`  | navy-800 63% | white 50% |
 
 ### Feedback
 
-| Token | Light | Dark | Use for |
-|---|---|---|---|
-| `feedback-error` | `#BE1809` | `#E85D7F` | Error messages, validation |
-| `feedback-success` | `#008A27` | `#AEE938` | Success messages |
-| `feedback-warning` | `#FFD300` | `#FFFAE5` | Warning messages |
+| Token              | Light     | Dark      |
+| ------------------ | --------- | --------- |
+| `feedback-error`   | `#BE1809` | `#E85D7F` |
+| `feedback-success` | `#008A27` | `#AEE938` |
+| `feedback-warning` | `#FFD300` | `#FFFAE5` |
+
+## Raw palette (Core-centric reference)
 
-## Raw palette
+Raw tokens name **fixed** swatches (surfaces, illustration, `<Background bg="…">` on Codecademy). **Palette keys and hex vary by theme** — Percipio and others add or remap scales (`percipioPalette`, etc.). Confirm allowed keys in the active theme or `DESIGN.md` before using a raw token in a non-Core app.
 
-Use raw tokens only when color must be **fixed** (not adaptive).
+For Codecademy Core defaults:
 
-| Name | Weights | Key values |
-|---|---|---|
-| `navy` | 100–900 | 800 = `#10162F`, 900 = `#0A0D1C` |
-| `hyper` | 400, 500 | 500 = `#3A10E5`, 400 = `#5533FF` |
-| `yellow` | 0, 400, 500, 900 | 500 = `#FFD300` |
-| `red` | 0, 300, 400, 500, 600, 900 | 500 = `#E91C11` |
-| `green` | 0, 100, 400, 700, 900 | 700 = `#008A27` |
-| `blue` | 0, 100, 300, 400, 500, 800 | 500 = `#1557FF` |
-| `beige` | — | `#FFF0E5` |
-| `pink` | 0, 400 | 400 = `#F966FF` |
-| `orange` | 100, 500 | 500 = `#FF8C00` |
+| Name     | Weights                    | Key values (illustrative)        |
+| -------- | -------------------------- | -------------------------------- |
+| `navy`   | 100–900                    | 800 = `#10162F`, 900 = `#0A0D1C` |
+| `hyper`  | 400, 500                   | 500 = `#3A10E5`, 400 = `#5533FF` |
+| `yellow` | 0, 400, 500, 900           | 500 = `#FFD300`                  |
+| `red`    | 0, 300, 400, 500, 600, 900 | 500 = `#E91C11`                  |
+| `green`  | 0, 100, 400, 700, 900      | 700 = `#008A27`                  |
+| `blue`   | 0, 100, 300, 400, 500, 800 | 500 = `#1557FF`                  |
+| `beige`  | —                          | `#FFF0E5`                        |
+| `pink`   | 0, 400                     | 400 = `#F966FF`                  |
+| `orange` | 100, 500                   | 500 = `#FF8C00`                  |
 
-Named shorthand aliases: `beige`, `blue`, `green`, `hyper`, `navy`, `orange`, `pink`, `red`, `yellow`, `black`, `white`
+Named shorthand aliases commonly used on Core surfaces: `beige`, `blue`, `green`, `hyper`, `navy`, `orange`, `pink`, `red`, `yellow`, `black`, `white`
 
 ## Decision guide
 
 ```
+Which product theme is GamutProvider using?
+  └─ Unknown → check setup.md / DESIGN.md / Storybook theme page before assuming hex or palette name
+
 Coloring UI text or backgrounds?
-  └─ Needs to adapt to light/dark or theme? → use semantic alias (text, background, primary, …)
-  └─ Must be fixed regardless of mode?      → use raw token (navy-800, yellow-500, …)
-  └─ Setting a section background with content inside? → use <Background bg="…"> (see modes.md)
+  └─ Must adapt to light/dark OR theme? → semantic alias (text, background, primary, …)
+  └─ Must stay fixed regardless of mode?      → raw palette token (confirm key exists in that theme)
+  └─ Section background with content inside? → <Background bg="…"> (see modes.md)
 ```
diff --git a/packages/gamut/agent-tools/guidelines/overview.md b/packages/gamut/agent-tools/guidelines/overview.md
index 301f8307100..b40c519c614 100644
--- a/packages/gamut/agent-tools/guidelines/overview.md
+++ b/packages/gamut/agent-tools/guidelines/overview.md
@@ -11,7 +11,7 @@ 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`).
+**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
 
@@ -27,12 +27,12 @@ Set the theme at the app root via `<GamutProvider theme={...}>`.
 
 ## Reading order
 
-| File                                                   | What it covers                                |
-| ------------------------------------------------------ | --------------------------------------------- |
-| [setup.md](setup.md)                                   | Packages, GamutProvider, theme selection      |
-| [foundations/color.md](foundations/color.md)           | Semantic aliases, raw palette, decision guide |
-| [foundations/modes.md](foundations/modes.md)           | Light/dark ColorMode, Background component    |
-| [foundations/typography.md](foundations/typography.md) | Typefaces, font scale, rules                  |
-| [foundations/spacing.md](foundations/spacing.md)       | Spacing, border radius, responsive grid       |
-| [components/overview.md](components/overview.md)       | Full component catalog                        |
-| [components/buttons.md](components/buttons.md)         | Button variants, props, decision tree         |
+| File                                                   | What it covers                                                          |
+| ------------------------------------------------------ | ----------------------------------------------------------------------- |
+| [setup.md](setup.md)                                   | Packages, GamutProvider, theme selection                                |
+| [foundations/color.md](foundations/color.md)           | Semantic roles (all themes), where to verify hex, Core-only cheatsheets |
+| [foundations/modes.md](foundations/modes.md)           | Light/dark ColorMode, Background component                              |
+| [foundations/typography.md](foundations/typography.md) | Typefaces, font scale, rules                                            |
+| [foundations/spacing.md](foundations/spacing.md)       | Spacing, border radius, responsive grid                                 |
+| [components/overview.md](components/overview.md)       | Full component catalog                                                  |
+| [components/buttons.md](components/buttons.md)         | Button variants, props, decision tree                                   |

From 64fed33331dd97ef84576f3b3bcabd902bee7acb Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 11:47:22 -0400
Subject: [PATCH 05/11] spacing.md

---
 .../guidelines/foundations/spacing.md         | 115 ++++++++++++------
 .../gamut/agent-tools/guidelines/overview.md  |  18 +--
 2 files changed, 87 insertions(+), 46 deletions(-)

diff --git a/packages/gamut/agent-tools/guidelines/foundations/spacing.md b/packages/gamut/agent-tools/guidelines/foundations/spacing.md
index 27f8b0edacc..0c3eb342d20 100644
--- a/packages/gamut/agent-tools/guidelines/foundations/spacing.md
+++ b/packages/gamut/agent-tools/guidelines/foundations/spacing.md
@@ -1,62 +1,103 @@
 # Spacing, Border Radius & Layout
 
+Token values match [`packages/gamut-styles/src/variables`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/variables) (`spacing.ts`, `borderRadii.ts`, `responsive.ts`). Breakpoints and max-content widths align with Storybook [Foundations / Layout](https://gamut.codecademy.com/?path=/docs-foundations-layout--docs).
+
+**In code — use system props for spacing:** Gamut layout primitives (`Box`, `FlexBox`, `GridBox`, …) expose margin, padding, and gap props backed by **`system.space`** from `@codecademy/gamut-styles`. Pass **spacing scale numbers** (`4`, `8`, `16`, …), not raw pixel strings. For custom `styled` components, compose `system.space` (see [`gamut-system-props` skill](../../skills/gamut-system-props/SKILL.md)). [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) shows responsive `Box` examples.
+
+**Responsive behavior:** All those props accept mobile-first **object** (`{ _: 8, md: 24 }`) or **array** syntax per [Responsive properties](https://gamut.codecademy.com/?path=/docs-foundations-system-responsive-properties--page). **Container queries** use keys `c_base`, `c_xs`, … `c_xl`; the parent must set a container (e.g. `containerType="inline-size"` on `FlexBox`). Prefer a media-query fallback when mixing `c_*` with viewport breakpoints.
+
+**Two different “grids”:**
+
+- **Design / page grid** (this doc’s “Grid” section, 12 columns, margins/gutters) — product layout guidelines; implement with [`LayoutGrid`](https://gamut.codecademy.com/?path=/docs-layouts-layoutgrid-layoutgrid--docs) and responsive `columnGap` / `rowGap` where appropriate.
+- **CSS Grid system props** — `system.grid` on styled components or `GridBox` for **local** regions; not the same as full-page `LayoutGrid`. See [System props / Grid](https://gamut.codecademy.com/?path=/docs-foundations-system-props-grid--page). `LayoutGrid` is for flexible full-page sections; use `FlexBox` / `GridBox` / `Box` for smaller areas ([LayoutGrid usage](https://gamut.codecademy.com/?path=/docs-layouts-layoutgrid-layoutgrid--docs)).
+
+**Designer vs code names:** Figma / Layout docs often label artboards **XL, LG, MD, SM, XS, Base**. In code, viewport breakpoints are **`xl`, `lg`, `md`, `sm`, `xs`** (min-widths below); **`_`** is the base (no min-width query). The “Max content width” column maps to those design sizes, not the `xs` token name alone.
+
 ## Spacing scale
 
 All spacing is multiples of 4px on an 8px grid.
 
 | Token | Value |
-|---|---|
-| `0` | 0 |
-| `4` | 4px |
-| `8` | 8px |
-| `12` | 12px |
-| `16` | 16px |
-| `24` | 24px |
-| `32` | 32px |
-| `40` | 40px |
-| `48` | 48px |
-| `64` | 64px |
-| `96` | 96px |
+| ----- | ----- |
+| `0`   | 0     |
+| `4`   | 4px   |
+| `8`   | 8px   |
+| `12`  | 12px  |
+| `16`  | 16px  |
+| `24`  | 24px  |
+| `32`  | 32px  |
+| `40`  | 40px  |
+| `48`  | 48px  |
+| `64`  | 64px  |
+| `96`  | 96px  |
 
 Use multiples of 8px for block-element spacing. Use 4px only for inline or typographic relationships.
 
 ## Border radius
 
-| Token | Value | Use |
-|---|---|---|
-| `none` | 0px | Square / non-interactive elements |
-| `sm` | 2px | Subtle rounding, tags |
-| `md` | 4px | Buttons, inputs, interactive cards |
-| `lg` | 8px | Cards, panels |
-| `xl` | 16px | Large cards, modals |
-| `full` | 999px | Pills, avatars, circular elements |
+| Token  | Value | Use                                |
+| ------ | ----- | ---------------------------------- |
+| `none` | 0px   | Square / non-interactive elements  |
+| `sm`   | 2px   | Subtle rounding, tags              |
+| `md`   | 4px   | Buttons, inputs, interactive cards |
+| `lg`   | 8px   | Cards, panels                      |
+| `xl`   | 16px  | Large cards, modals                |
+| `full` | 999px | Pills, avatars, circular elements  |
 
 ## Breakpoints
 
 Mobile-first. Styles apply from the named breakpoint and up.
 
-| Token | Min-width | Max content width |
-|---|---|---|
-| _(base)_ | 0 | 288px |
-| `xs` | 480px | 448px |
-| `sm` | 768px | 704px |
-| `md` | 1024px | 896px |
-| `lg` | 1200px | 1072px |
-| `xl` | 1440px | 1248px |
+| Token    | Min-width | Max content width |
+| -------- | --------- | ----------------- |
+| _(base)_ | 0         | 288px             |
+| `xs`     | 480px     | 448px             |
+| `sm`     | 768px     | 704px             |
+| `md`     | 1024px    | 896px             |
+| `lg`     | 1200px    | 1072px            |
+| `xl`     | 1440px    | 1248px            |
+
+The grid table below collapses **xl+lg**, **md**, **sm+xs**, and **base** to four implementation tiers; max-content widths still follow the six design sizes in Layout.
+
+## Container query breakpoints
+
+Container keys (`c_*`) use the **same min-width numbers** as viewport breakpoints, but they apply to the **width of a CSS containment context** (usually a parent), not the browser viewport. Use them when a component must adapt inside sidebars, split layouts, or embeds. Full detail: [Responsive properties — Container Queries](https://gamut.codecademy.com/?path=/docs-foundations-system-responsive-properties--page).
+
+| Key      | Min container width | Typical use                                                             |
+| -------- | ------------------- | ----------------------------------------------------------------------- |
+| `c_base` | 1px                 | Always matches once a container exists; base style inside the container |
+| `c_xs`   | 480px               | Matches viewport `xs` threshold, but on **container** width             |
+| `c_sm`   | 768px               |                                                                         |
+| `c_md`   | 1024px              |                                                                         |
+| `c_lg`   | 1200px              |                                                                         |
+| `c_xl`   | 1440px              |                                                                         |
+
+**Requirements**
+
+- A **descendant** of an element that establishes a container — e.g. parent `<FlexBox containerType="inline-size">` (or other `container-type`). Without that, `c_*` rules never match.
+- Prefer a **viewport fallback** alongside `c_*` (e.g. `display={{ _: 'block', sm: 'flex', c_md: 'grid' }}`) for browsers or trees without container support.
+
+**Object vs array**
+
+- **Object:** `p={{ _: 8, c_md: 24 }}` — readable for a few container-only overrides.
+- **Array:** after the six viewport slots (`_` through `xl`), indices **6–11** are `c_base`, `c_xs`, `c_sm`, `c_md`, `c_lg`, `c_xl` respectively. Use when you need the full ordered chain.
+
+**When to use which**
 
-Container query variants (`c_xs`–`c_xl`) mirror these values but trigger on component width.
+- **Viewport keys** (`_`, `xs`, … `xl`) — page-level layout, full-bleed sections, global nav.
+- **Container keys** (`c_base`, … `c_xl`) — reusable widgets whose width is driven by layout, not the device alone.
 
-## Grid
+## Page layout grid (12 columns)
 
-12-column grid at all breakpoints.
+12-column grid at all breakpoints. Tier columns group breakpoints with identical margin/gutter/row-gap numbers from [Layout](https://gamut.codecademy.com/?path=/docs-foundations-layout--docs).
 
-| Property | xl/lg | md | sm/xs | base |
-|---|---|---|---|---|
-| Horizontal margins | 64px | 48px | 32px | 16px |
-| Column gutters | 32px | 24px | 16px | 8px |
-| Row gaps | 32px | 24px | 16px | 8px |
+| Property           | xl/lg | md   | sm/xs | base |
+| ------------------ | ----- | ---- | ----- | ---- |
+| Horizontal margins | 64px  | 48px | 32px  | 16px |
+| Column gutters     | 32px  | 24px | 16px  | 8px  |
+| Row gaps           | 32px  | 24px | 16px  | 8px  |
 
-Minimum touch target on mobile: **44×44px**.
+Minimum touch target on mobile: **44×44px** — see `gamut-accessibility` skill for hit-target guidance.
 
 ## Responsive rules
 
diff --git a/packages/gamut/agent-tools/guidelines/overview.md b/packages/gamut/agent-tools/guidelines/overview.md
index b40c519c614..308ee0f5c69 100644
--- a/packages/gamut/agent-tools/guidelines/overview.md
+++ b/packages/gamut/agent-tools/guidelines/overview.md
@@ -27,12 +27,12 @@ Set the theme at the app root via `<GamutProvider theme={...}>`.
 
 ## Reading order
 
-| File                                                   | What it covers                                                          |
-| ------------------------------------------------------ | ----------------------------------------------------------------------- |
-| [setup.md](setup.md)                                   | Packages, GamutProvider, theme selection                                |
-| [foundations/color.md](foundations/color.md)           | Semantic roles (all themes), where to verify hex, Core-only cheatsheets |
-| [foundations/modes.md](foundations/modes.md)           | Light/dark ColorMode, Background component                              |
-| [foundations/typography.md](foundations/typography.md) | Typefaces, font scale, rules                                            |
-| [foundations/spacing.md](foundations/spacing.md)       | Spacing, border radius, responsive grid                                 |
-| [components/overview.md](components/overview.md)       | Full component catalog                                                  |
-| [components/buttons.md](components/buttons.md)         | Button variants, props, decision tree                                   |
+| File                                                   | What it covers                                                                 |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| [setup.md](setup.md)                                   | Packages, GamutProvider, theme selection                                       |
+| [foundations/color.md](foundations/color.md)           | Semantic roles (all themes), where to verify hex, Core-only cheatsheets        |
+| [foundations/modes.md](foundations/modes.md)           | Light/dark ColorMode, Background component                                     |
+| [foundations/typography.md](foundations/typography.md) | Typefaces, font scale, rules                                                   |
+| [foundations/spacing.md](foundations/spacing.md)       | Spacing scale, radii, Layout grid; system props + responsive/container queries |
+| [components/overview.md](components/overview.md)       | Full component catalog                                                         |
+| [components/buttons.md](components/buttons.md)         | Button variants, props, decision tree                                          |

From 93663fcbf1fda7254dd66b11b885dfb4637eb2ad Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 12:05:59 -0400
Subject: [PATCH 06/11] typography

---
 .../guidelines/foundations/typography.md      | 107 ++++++++++------
 .../gamut/agent-tools/guidelines/overview.md  |  18 +--
 .../skills/gamut-typography/SKILL.md          | 116 +++++-------------
 3 files changed, 114 insertions(+), 127 deletions(-)

diff --git a/packages/gamut/agent-tools/guidelines/foundations/typography.md b/packages/gamut/agent-tools/guidelines/foundations/typography.md
index a09d91ab761..31e5fe487bc 100644
--- a/packages/gamut/agent-tools/guidelines/foundations/typography.md
+++ b/packages/gamut/agent-tools/guidelines/foundations/typography.md
@@ -1,50 +1,83 @@
 # Typography
 
-## Typefaces
+Use **theme typography tokens** (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`) — never hardcoded font-family strings or magic px for product UI. Prefer `<Text>` from `@codecademy/gamut`, or `system.typography` / `css()` from `@codecademy/gamut-styles` ([`gamut-system-props` skill](../../skills/gamut-system-props/SKILL.md)).
 
-| Token | Codecademy font | Non-Codecademy | Use for |
-|---|---|---|---|
-| `base` | Apercu Pro | Hanken Grotesk | All UI text, headlines, body copy |
-| `accent` | Suisse Intl Mono | Hanken Grotesk | Code, captions, labels, technical context |
-| `monospace` | Monaco / Menlo / Consolas | Monaco / Menlo / Consolas | Code editor contexts |
+Source of truth for scales and stacks: [`packages/gamut-styles/src/variables/typography.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variables/typography.ts) and theme builders under [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes).
 
-Percipio overrides all families to Roboto. Apercu is licensed for codecademy.com only.
+**Storybook:** [Typography / Text](https://gamut.codecademy.com/?path=/docs-typography-text--docs) · [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) (system props) · Foundations / Theme: [Core](https://gamut.codecademy.com/?path=/docs-foundations-theme-core-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)
+
+**DESIGN.md drift:** [`DESIGN.Percipio.md`](../../DESIGN.Percipio.md) and [`DESIGN.LXStudio.md`](../../DESIGN.LXStudio.md) sometimes describe **Roboto** or **Hanken Grotesk** for those products. **Shipped `gamut-styles` themes** currently use the stacks below (Skillsoft Text / Sans). Treat DESIGN YAML as product narrative until it matches code — confirm with the design platform when they disagree.
+
+## Themes × font families
+
+Semantic keys (`base`, `accent`, `monospace`, `system`) are stable; resolved stacks depend on `GamutProvider` theme ([`setup.md`](../setup.md)).
+
+| Theme                             | `fontFamily.base`                    | `fontFamily.accent`                   | `fontFamily.monospace`                 | `fontFamily.system`            |
+| --------------------------------- | ------------------------------------ | ------------------------------------- | -------------------------------------- | ------------------------------ |
+| **Core**, **Admin**, **Platform** | Apercu stack (`fontBase`)            | Suisse + Apercu stack (`fontAccent`)  | Monaco / Menlo stack (`fontMonospace`) | System UI stack (`fontSystem`) |
+| **Percipio**                      | Skillsoft Text (`fontPercipioBase`)  | Skillsoft Sans (`fontPercipioAccent`) | Roboto Mono                            | Roboto (`system`)              |
+| **LX Studio**                     | Same as Percipio (`base` / `accent`) | Same                                  | Same stack as Core (`fontMonospace`)   | Same as Core (`fontSystem`)    |
+
+Admin and Platform extend Core for colors / modes only — typography matches Core.
+
+**Licensing:** Apercu is licensed for Codecademy surfaces only; Skillsoft products use Percipio/LX stacks above.
 
 ## Font size scale
 
-| Token | Size | Common use |
-|---|---|---|
-| `64` | 64px | Hero / display |
-| `44` | 44px | Page titles |
-| `34` | 34px | Section titles |
-| `26` | 26px | Sub-section titles |
-| `22` | 22px | Card titles, large UI labels |
-| `20` | 20px | Secondary titles |
-| `18` | 18px | Large body, intro text |
-| `16` | 16px | Default body text |
-| `14` | 14px | Small body, captions, labels |
-
-## Font weight
-
-| Token | Value | Use |
-|---|---|---|
-| `base` | 400 | Body text, UI labels |
-| `title` | 700 | Headlines, CTAs, buttons |
+Values are `rem`-backed keys on `theme.fontSize` (aliases shown as px for readability).
+
+| Token | Size | Common use                   |
+| ----- | ---- | ---------------------------- |
+| `64`  | 64px | Hero / display               |
+| `44`  | 44px | Page titles                  |
+| `34`  | 34px | Section titles               |
+| `26`  | 26px | Sub-section titles           |
+| `22`  | 22px | Card titles, large UI labels |
+| `20`  | 20px | Secondary titles             |
+| `18`  | 18px | Large body, intro text       |
+| `16`  | 16px | Default body text            |
+| `14`  | 14px | Small body, captions, labels |
 
 ## Line height
 
-| Token | Value | Use |
-|---|---|---|
-| `base` | 1.5 | Body text |
-| `spacedTitle` | 1.3 | Sub-headlines, medium titles |
-| `title` | 1.2 | Large headlines |
+| Token         | Value | Use                          |
+| ------------- | ----- | ---------------------------- |
+| `base`        | 1.5   | Body text                    |
+| `spacedTitle` | 1.3   | Sub-headlines, medium titles |
+| `title`       | 1.2   | Large headlines              |
+
+## Font weight (semantic)
+
+Use **semantic keys** on components — do not assume a numeric bold everywhere.
+
+| Token   | Core / Admin / Platform | Percipio / LX Studio              |
+| ------- | ----------------------- | --------------------------------- |
+| `base`  | 400                     | 400                               |
+| `title` | **700**                 | **500** (`fontWeightMediumTitle`) |
+
+Headlines, CTAs, and buttons should use **`fontWeight="title"`** so Percipio/LX get **500**, Core gets **700**. Literal `700` breaks Skillsoft branding on those themes.
+
+Numeric **`400`** and **`700`** keys also exist on the theme for rare explicit needs.
+
+## Codecademy (Core / Admin / Platform) — voice & layout
+
+These UX rules target **Apercu + Suisse** products; do not blindly apply to Percipio/LX without brand guidance.
+
+- **`fontFamily="base"` (Apercu):** default UI and marketing type. Emphasis inside body copy: **Italic**, not Bold for intra-paragraph stress.
+- **`fontFamily="accent"` (Suisse stack):** technical accent — code snippets, captions, labels with engineering flavor, figures. Use sparingly; glyph box reads larger — step **down ~10–15%** vs equivalent `base` size; give comfortable line-height.
+- **Alignment:** left-align by default; center only short marketing headlines; avoid right-align except tabs / numerics.
+- **Letter-spacing:** do not tweak tracking unless design specifies.
+- **Line length:** ~45–85 characters per line (~66 ideal for single-column body); constrain container width, not arbitrary CSS letter-spacing.
+
+## Line length (all products)
 
-Target 45–85 characters per line (66 ideal for web body text).
+| Context            | Target              |
+| ------------------ | ------------------- |
+| Single-column body | ~66 chars (max ~85) |
+| Multi-column       | ≤50 chars per line  |
+| Minimum            | ~45 chars           |
 
-## Rules
+## Related skills
 
-- Use `title` weight (700) for headlines, CTAs, and buttons.
-- Use Apercu Italic to emphasize within a Regular paragraph — not Bold.
-- Use `accent` (Suisse) sparingly: code snippets, captions, enumerated items. Suisse reads ~10–15% large — size it down relative to Apercu equivalents.
-- Left-align text by default. Center-align only for short marketing headlines. Never right-align.
-- Do not adjust letter-spacing.
+- [`gamut-typography`](../../skills/gamut-typography/SKILL.md) — deeper editorial patterns for agents.
+- [`gamut-theming`](../../skills/gamut-theming/SKILL.md) — accessing `theme.font*` in styled components.
diff --git a/packages/gamut/agent-tools/guidelines/overview.md b/packages/gamut/agent-tools/guidelines/overview.md
index 308ee0f5c69..07650d86832 100644
--- a/packages/gamut/agent-tools/guidelines/overview.md
+++ b/packages/gamut/agent-tools/guidelines/overview.md
@@ -15,13 +15,15 @@ Gamut is the Codecademy / Skillsoft design system — React component library (`
 
 ## Themes
 
-| Theme         | Product                         | Base font      | Dark mode |
-| ------------- | ------------------------------- | -------------- | --------- |
-| **Core**      | Codecademy (default)            | Apercu         | ✓         |
-| **Admin**     | Codecademy admin tools          | Apercu         | ✓         |
-| **Platform**  | Codecademy learning environment | Apercu         | ✓         |
-| **LX Studio** | LX Studio application           | Hanken Grotesk | —         |
-| **Percipio**  | Skillsoft Percipio              | Roboto         | —         |
+Runtime stacks come from `@codecademy/gamut-styles` (see [foundations/typography.md](foundations/typography.md)). Product `DESIGN.*.md` may differ until reconciled.
+
+| Theme         | Product                         | Primary UI fonts (shipped theme)                                               | Dark mode |
+| ------------- | ------------------------------- | ------------------------------------------------------------------------------ | --------- |
+| **Core**      | Codecademy (default)            | Apercu + Suisse (`accent`)                                                     | ✓         |
+| **Admin**     | Codecademy admin tools          | Same as Core                                                                   | ✓         |
+| **Platform**  | Codecademy learning environment | Same as Core                                                                   | ✓         |
+| **LX Studio** | LX Studio application           | Skillsoft Text / Sans (`base` / `accent`); DESIGN docs may list Hanken Grotesk | —         |
+| **Percipio**  | Skillsoft Percipio              | Skillsoft Text / Sans; DESIGN docs may list Roboto                             | —         |
 
 Set the theme at the app root via `<GamutProvider theme={...}>`.
 
@@ -32,7 +34,7 @@ Set the theme at the app root via `<GamutProvider theme={...}>`.
 | [setup.md](setup.md)                                   | Packages, GamutProvider, theme selection                                       |
 | [foundations/color.md](foundations/color.md)           | Semantic roles (all themes), where to verify hex, Core-only cheatsheets        |
 | [foundations/modes.md](foundations/modes.md)           | Light/dark ColorMode, Background component                                     |
-| [foundations/typography.md](foundations/typography.md) | Typefaces, font scale, rules                                                   |
+| [foundations/typography.md](foundations/typography.md) | Theme fonts, scales, semantic `title` weight (700 vs 500), Core voice rules    |
 | [foundations/spacing.md](foundations/spacing.md)       | Spacing scale, radii, Layout grid; system props + responsive/container queries |
 | [components/overview.md](components/overview.md)       | Full component catalog                                                         |
 | [components/buttons.md](components/buttons.md)         | Button variants, props, decision tree                                          |
diff --git a/packages/gamut/agent-tools/skills/gamut-typography/SKILL.md b/packages/gamut/agent-tools/skills/gamut-typography/SKILL.md
index 8cfd69954c4..5508d229902 100644
--- a/packages/gamut/agent-tools/skills/gamut-typography/SKILL.md
+++ b/packages/gamut/agent-tools/skills/gamut-typography/SKILL.md
@@ -1,123 +1,75 @@
 ---
 name: gamut-typography
-description: Use this skill when creating or reviewing UI text in Gamut apps — headlines, body, captions, labels, code snippets, or text-heavy layouts — even if the user does not name fonts or tokens. Covers Apercu Pro, Suisse Intl Mono, scale, line heights, line length, and alignment.
+description: Use this skill when creating or reviewing UI text in Gamut apps — headlines, body, captions, labels, code snippets, or text-heavy layouts. Covers theme-specific stacks (Core Apercu/Suisse vs Percipio/LX Skillsoft), fontSize / lineHeight tokens, semantic fontWeight title (700 vs 500), line length, and alignment for Codecademy-branded surfaces.
 ---
 
 # Gamut Typography
 
-> **Scope**: This skill covers typography for **Codecademy products** using the Core, Admin, or Platform themes (Apercu + Suisse). Percipio uses Roboto for all type — see `DESIGN.md` for Percipio-specific guidance. LX Studio uses Hanken Grotesk in place of both Apercu and Suisse.
+**Implementation source of truth:** [`packages/gamut-styles/src/variables/typography.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variables/typography.ts) and themes under [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes). Agent guideline: [foundations/typography.md](../../guidelines/foundations/typography.md).
 
-## Typefaces
+## Scope by theme
 
-Codecademy products use two typefaces:
+| Themes                            | Fonts                                                                                                                                    | `fontWeight.title` |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| **Core**, **Admin**, **Platform** | `base` → Apercu stack; `accent` → Suisse + Apercu stack                                                                                  | **700**            |
+| **Percipio**, **LX Studio**       | `base` → Skillsoft Text; `accent` → Skillsoft Sans; Percipio `monospace` → Roboto Mono; LX `monospace` matches Core stack per theme file | **500**            |
 
-### Apercu Pro (`fontFamily: "base"`)
-
-The primary typeface. Geometric-ish, humanist sans-serif. Use for:
-- Headlines (Bold weight)
-- Body / paragraph text (Regular weight)
-- UI labels, menu items (Regular weight)
-- Emphasis within body copy (Italic — **not** Bold)
-
-**Rules:**
-- Do not use Bold to emphasize text within a Regular-weight paragraph. Use Italic instead.
-- Set with generous line-height for body text: **150–175%** of the type size (e.g. 16px type → 24–28px line-height).
-- Headlines should use **100–110%** line-height to appear intentional and grouped.
-- Text should be **left-aligned** by default.
-
-### Suisse Intl Mono (`fontFamily: "accent"`)
-
-Monospace accent typeface. Use sparingly for:
-- Code snippets and inline code
-- Numbers, figures, and statistics
-- Captions and labels that reference technical/engineering context
-- Enumerated lists
-- Quotations in a technical voice
-
-**Rules:**
-- Every character is the same width — avoid long paragraph-length prose in Suisse.
-- It reads large for its point size: **reduce the size by ~10–15%** relative to Apercu text at the same visual scale (e.g. 14px Suisse ≈ 16px Apercu visually).
-- Requires extra line-height to remain readable.
+Use **`fontWeight="title"`** for headlines / emphasis roles — never hardcode **`700`** on Percipio/LX unless SPECIFICALLY noted in Figma designs.
 
 ## Font size scale (`fontSize`)
 
-Sizes are accessed via the theme's `fontSize` scale. Common keys:
+Theme keys: `64`, `44`, `34`, `26`, `22`, `20`, `18`, `16`, `14`.
 
 ```tsx
 import { css } from '@codecademy/gamut-styles';
 import styled from '@emotion/styled';
-
-// Via system props
 import { system } from '@codecademy/gamut-styles';
-const Text = styled.p(system.typography);
-<Text fontSize={16} />;
 
-// Via css() utility
-const Box = styled.div(css({ fontSize: 14 }));
+const Paragraph = styled.p(system.typography);
+<Paragraph fontSize={16} lineHeight="base" />;
 
-// Via theme directly (outside styled components)
-import { theme } from '@codecademy/gamut-styles';
-const size = theme.fontSize[16];
+const Styled = styled.div(css({ fontSize: 14, fontFamily: 'base' }));
 ```
 
-## Line heights (`lineHeight`)
+## Line height (`lineHeight`)
 
-Line heights are limited to **multiples of 4px**. Type boxes are placed on an **8px placement grid**.
-
-Guidelines:
-- Body text: 150–175% of font size
-- Headlines: 100–110% of font size
+Tokens: **`base`** (1.5), **`spacedTitle`** (1.3), **`title`** (1.2). Prefer tokens over raw decimals. Only specify `lineHeight` when specified by design.
 
 ## Line length
 
-Controlling line length is essential for readability:
-
-| Context | Target |
-|---|---|
-| Single-column body text | ~66 characters (max 85) |
-| Multi-column layouts | ≤50 characters per line |
-| Minimum | 45 characters |
-
-**How to control line length**: Start with the right text style for the design, then adjust the width or column count of the text container.
-
-## Alignment
-
-- **Left-align** paragraphs by default — this is easiest to read and supports grid alignment.
-- **Center-align** only for short marketing headlines or specific interface components with brief text.
-- **Never right-align** text in normal circumstances (exceptions: numbers, equations).
-- Do not adjust letter-spacing.
+| Context            | Target                   |
+| ------------------ | ------------------------ |
+| Single-column body | ~66 characters (max ~85) |
+| Multi-column       | ≤50 characters per line  |
+| Minimum            | ~45 characters           |
 
 ## Accessing typography tokens
 
 ```tsx
-// System props (recommended for styled components)
 import { system } from '@codecademy/gamut-styles';
 import { variance } from '@codecademy/variance';
 
-const Heading = styled.h2(
-  variance.compose(system.typography, system.space)
-);
+const Heading = styled.h2(variance.compose(system.typography, system.space));
 
-<Heading fontSize={24} fontFamily="base" fontWeight="bold" lineHeight={1.1} mb={8} />;
+<Heading
+  fontSize={26}
+  fontFamily="base"
+  fontWeight="title"
+  lineHeight="title"
+  mb={8}
+/>;
 
-// css() utility (recommended for static styles)
 import { css } from '@codecademy/gamut-styles';
 
 const Caption = styled.span(
-  css({ fontFamily: 'accent', fontSize: 12, color: 'secondary' })
+  css({ fontFamily: 'accent', fontSize: 14, color: 'text-secondary' })
 );
-
-// Theme object (outside styled components)
-import { theme } from '@codecademy/gamut-styles';
-import { css as emotionCss } from '@emotion/react';
-
-const myStyles = emotionCss`
-  font-size: ${theme.fontSize[14]};
-`;
 ```
 
-## Semantic vs. visual sizing
+Prefer `<Text>` from `@codecademy/gamut` with `variant` / `as` — see Storybook [Typography / Text](https://gamut.codecademy.com/?path=/docs-typography-text--docs).
+
+## Semantic vs visual headings
 
-- The term **"Title"** distinguishes visual size from semantic HTML hierarchy (H1–H6).
-- A visually large title may use `<h2>` or `<p>` semantically — visual scale and semantic meaning are independent in Gamut.
-- Choose HTML heading levels for document structure, choose font size for visual hierarchy.
+- `<Text as="h1">` … `<Text as="h6">` gets **default heading styles**: each tag maps to the same scale as `variant="title-xxl"` … `variant="title-xs"` (`h1` largest through `h6` smallest). Plain `<Text>` defaults to `as="span"` (inherits font size).
+- Use **`variant`** plus **`fontSize` / `fontWeight` / `lineHeight`** (and other system props) to override element defaults when the outline needs one heading level but the UI needs another visual weight — e.g. `<Text as="h2" variant="title-sm">`.
+- Still pick **`h1`–`h6`** for document structure and assistive tech; overrides are for intentional divergence between semantics and appearance.

From 5d41e5244564d65ee113abffa74689bcdeebe2a9 Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 13:51:17 -0400
Subject: [PATCH 07/11] refactor setup

---
 .../gamut/agent-tools/guidelines/overview.md  |  6 +-
 .../gamut/agent-tools/guidelines/setup.md     | 74 +++++++++++++++----
 2 files changed, 63 insertions(+), 17 deletions(-)

diff --git a/packages/gamut/agent-tools/guidelines/overview.md b/packages/gamut/agent-tools/guidelines/overview.md
index 07650d86832..21d74d04551 100644
--- a/packages/gamut/agent-tools/guidelines/overview.md
+++ b/packages/gamut/agent-tools/guidelines/overview.md
@@ -6,10 +6,10 @@ Gamut is the Codecademy / Skillsoft design system — React component library (`
 
 **Core principles**:
 
-- Components are color mode–aware by default — never hardcode hex values for adaptive UI
+- Components are color mode–aware by default — never hardcode hex values for adaptive, accessible UI
 - All components work across all themes without modification
-- Mobile-first, 12-column grid
-- Semantic color tokens guarantee WCAG AA contrast automatically
+- 12-column grid
+- Use **semantic theme tokens** from `@codecademy/gamut-styles` for **color roles** (ColorMode-aware), **typography**, **spacing**, **border radii**, and shared **layout** values (`elements`, …) — not raw palette hex or magic numbers. Defaults support accessible pairings, but **no token set guarantees WCAG AA** for every composition; validate non-standard combinations.
 
 **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`).
 
diff --git a/packages/gamut/agent-tools/guidelines/setup.md b/packages/gamut/agent-tools/guidelines/setup.md
index 645631ebd4f..04ee0fe6e44 100644
--- a/packages/gamut/agent-tools/guidelines/setup.md
+++ b/packages/gamut/agent-tools/guidelines/setup.md
@@ -3,40 +3,86 @@
 ## Install
 
 ```sh
-npm install @codecademy/gamut-kit
+yarn add @codecademy/gamut-kit @emotion/react @emotion/styled
 ```
 
 `gamut-kit` bundles `gamut`, `gamut-icons`, `gamut-illustrations`, `gamut-patterns`, `gamut-styles`, `variance`, and `gamut-tests`.
 
+**Full guide:** [Meta / Installation](https://gamut.codecademy.com/?path=/docs-meta-installation--page) in Storybook (CSP `nonce` on `GamutProvider`, Jest, Next/Gatsby entry points). For Emotion + TypeScript, add `theme.d.ts` as in [TypeScript (`theme.d.ts`)](#typescript-themedts) below.
+
+Optionally add a `peerDependencies` block in `package.json` listing `@codecademy/gamut`, `@codecademy/gamut-icons`, `@codecademy/gamut-illustrations`, `@codecademy/gamut-patterns`, `@codecademy/gamut-styles`, `@codecademy/gamut-tests`, and `@codecademy/variance` (e.g. `"*"`) so editors surface those packages — see Meta / Installation for the JSON snippet.
+
 ## Required wrapper
 
-Wrap the app root in `<GamutProvider>`. This wires up the theme, color mode, and logical properties for all child components.
+Wrap the app root in `<GamutProvider>` from `@codecademy/gamut-styles`. This wires up the theme, color mode, and logical properties for all child components.
+
+At runtime, `GamutProvider` defaults to Core when `theme` is omitted (`theme = coreTheme` in the implementation). For non-Core products and for TypeScript (`theme` is required on `GamutProviderProps`), pass `theme` explicitly using the table below.
 
 ```tsx
-import { GamutProvider } from '@codecademy/gamut';
-import { theme } from '@codecademy/gamut-styles';
+import { GamutProvider, theme } from '@codecademy/gamut-styles';
 
 const App = () => (
-  <GamutProvider theme={theme}>
-    {/* app content */}
-  </GamutProvider>
+  <GamutProvider theme={theme}>{/* app content */}</GamutProvider>
 );
 ```
 
 ## Theme selection
 
-| Product | Theme to import |
-|---|---|
-| Codecademy public | `coreTheme` (default `theme`) |
-| Codecademy admin | `adminTheme` |
-| Codecademy platform | `platformTheme` |
-| LX Studio | `lxStudioTheme` |
-| Percipio | `percipioTheme` |
+| Product             | Theme to import               |
+| ------------------- | ----------------------------- |
+| Codecademy public   | `coreTheme` (default `theme`) |
+| Codecademy admin    | `adminTheme`                  |
+| Codecademy platform | `platformTheme`               |
+| LX Studio           | `lxStudioTheme`               |
+| Percipio            | `percipioTheme`               |
 
 All themes are exported from `@codecademy/gamut-styles`.
 
+## TypeScript (`theme.d.ts`)
+
+Augment `@emotion/react` so `props.theme` in `styled` / `css` matches the **same theme object** you pass to `<GamutProvider theme={...}>`. If the types disagree, system props and token autocomplete will not line up with runtime.
+
+Add a root `theme.d.ts` (or merge into your existing global types):
+
+```tsx
+// theme.d.ts
+import '@emotion/react';
+
+import type { CoreTheme } from '@codecademy/gamut-styles';
+
+declare module '@emotion/react' {
+  export interface Theme extends CoreTheme {}
+}
+```
+
+Use the **theme interface that matches your provider** — same row as the [theme selection](#theme-selection) table:
+
+| `GamutProvider` `theme` prop | Import for `Theme extends …` |
+| ---------------------------- | ---------------------------- |
+| `theme` or `coreTheme`       | `CoreTheme`                  |
+| `adminTheme`                 | `AdminTheme`                 |
+| `platformTheme`              | `PlatformTheme`              |
+| `lxStudioTheme`              | `LxStudioTheme`              |
+| `percipioTheme`              | `PercipioTheme`              |
+
+Example when the app uses Percipio:
+
+```tsx
+// theme.d.ts
+import '@emotion/react';
+
+import type { PercipioTheme } from '@codecademy/gamut-styles';
+
+declare module '@emotion/react' {
+  export interface Theme extends PercipioTheme {}
+}
+```
+
+See Emotion’s [TypeScript / define a theme](https://emotion.sh/docs/typescript#define-a-theme) for details.
+
 ## Font licensing
 
 **Apercu Pro** is licensed for codecademy.com only. Non-Codecademy products must use their theme's approved typeface:
+
 - LX Studio → Hanken Grotesk
 - Percipio → Roboto

From df431fb351c3a754ad99026d1119a63264136d76 Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 15:29:10 -0400
Subject: [PATCH 08/11] refactor form accessibility docs

---
 .../guidelines/components/overview.md         |  22 +-
 .../gamut/agent-tools/guidelines/setup.md     |   7 -
 .../gamut/agent-tools/rules/accessibility.mdc |  32 ++-
 .../skills/gamut-accessibility/SKILL.md       | 223 ++++++++----------
 .../agent-tools/skills/gamut-forms/SKILL.md   |  84 +++++++
 5 files changed, 219 insertions(+), 149 deletions(-)
 create mode 100644 packages/gamut/agent-tools/skills/gamut-forms/SKILL.md

diff --git a/packages/gamut/agent-tools/guidelines/components/overview.md b/packages/gamut/agent-tools/guidelines/components/overview.md
index be2230563c2..1e1916f327f 100644
--- a/packages/gamut/agent-tools/guidelines/components/overview.md
+++ b/packages/gamut/agent-tools/guidelines/components/overview.md
@@ -17,28 +17,36 @@ ContentContainer, GridContainer, Layout, LayoutGrid
 ## Key patterns
 
 ### Buttons
+
 See [buttons.md](buttons.md) for full reference. Use `FillButton` for primary actions, `StrokeButton` for secondary.
 
+### Forms and accessibility
+
+**`FormGroup`**, **`GridForm`**, **`ConnectedForm`**, tips, dialogs, composite widgets: **[`skills/gamut-forms/SKILL.md`](../../skills/gamut-forms/SKILL.md)** (forms) · **[`skills/gamut-accessibility/SKILL.md`](../../skills/gamut-accessibility/SKILL.md)** (overlays, composites, checklists) · Storybook [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page).
+
 ### 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
 
 ### Color-aware components
+
 - `<ColorMode mode="light|dark|system">` — scopes a subtree to an explicit color mode
 - `<Background bg="<color>">` — applies background color + auto-switches inner color mode for contrast
 
 ### Alerts
-| Variant | Tokens |
-|---|---|
-| Error | `feedback-error` + `background-error` |
+
+| Variant | Tokens                                    |
+| ------- | ----------------------------------------- |
+| Error   | `feedback-error` + `background-error`     |
 | Success | `feedback-success` + `background-success` |
 | Warning | `feedback-warning` + `background-warning` |
 
 ## Global tokens
 
-| Token | Value | Use |
-|---|---|---|
-| `headerHeight` | 64px (base), 80px (md+) | Global page header height |
-| `headerZ` | 15 | Z-index for global page header |
+| Token          | Value                   | Use                            |
+| -------------- | ----------------------- | ------------------------------ |
+| `headerHeight` | 64px (base), 80px (md+) | Global page header height      |
+| `headerZ`      | 15                      | Z-index for global page header |
diff --git a/packages/gamut/agent-tools/guidelines/setup.md b/packages/gamut/agent-tools/guidelines/setup.md
index 04ee0fe6e44..096b2e4d5fe 100644
--- a/packages/gamut/agent-tools/guidelines/setup.md
+++ b/packages/gamut/agent-tools/guidelines/setup.md
@@ -79,10 +79,3 @@ declare module '@emotion/react' {
 ```
 
 See Emotion’s [TypeScript / define a theme](https://emotion.sh/docs/typescript#define-a-theme) for details.
-
-## Font licensing
-
-**Apercu Pro** is licensed for codecademy.com only. Non-Codecademy products must use their theme's approved typeface:
-
-- LX Studio → Hanken Grotesk
-- Percipio → Roboto
diff --git a/packages/gamut/agent-tools/rules/accessibility.mdc b/packages/gamut/agent-tools/rules/accessibility.mdc
index b3f2fb9afa7..1d4077623e5 100644
--- a/packages/gamut/agent-tools/rules/accessibility.mdc
+++ b/packages/gamut/agent-tools/rules/accessibility.mdc
@@ -1,5 +1,5 @@
 ---
-description: Apply these guardrails when editing Gamut UI in TS/JS/TSX/JSX. Mirrors the General rules in the `gamut-accessibility` skill; see `skills/gamut-accessibility/SKILL.md` in this plugin for full component patterns and checklists. Loaded automatically for matched files.
+description: Apply these guardrails when editing Gamut UI in TS/JS/TSX/JSX. Universal rules (always loaded). Form wiring depth: **`gamut-forms`** skill; other component matrix and audit detail: **`gamut-accessibility`** — those skills do not repeat this rule set.
 alwaysApply: true
 globs: ['*.tsx', '*.ts', '*.jsx', '*.js']
 ---
@@ -39,21 +39,20 @@ When there is no visible text for a nameable element, consider this a sign that
 </ul>
 ```
 
-## Use Gamut components — don't reimplement what they already solve
+## Use Gamut primitives — do not fake buttons or dialogs
 
-- `<Button>` not `<div onClick>` or `<span role="button">`
-- `<Tabs>` / `<Tab>` / `<TabList>` / `<TabPanel>` — arrow key, Home, End navigation is automatic
-- `<Dialog>` / `<Modal>` — always provide an accessible name; **prefer `aria-labelledby`** to a visible title when one exists, otherwise `aria-label`. Focus lock and Escape are handled by the components.
+- **Actions:** use Gamut button atoms (`FillButton`, `TextButton`, `StrokeButton`, `CTAButton`, `IconButton`) — not `<div onClick>`, not `<span role="button">`, not `<a>` without `href` for actions. Variant and `tip` guidance: [`guidelines/components/buttons.md`](../guidelines/components/buttons.md).
+- **Tabs / overlays:** `Tabs`, `Dialog`, `Modal`, and related primitives implement keyboard and focus patterns in code — still supply labels, titles, and trigger semantics as documented in the skill.
 
 ## Every interactive control needs an accessible name
 
-- **`<IconButton>`** — provide `tip` (becomes the accessible name for icon-only)
-- **`<InfoTip>`** — provide `ariaLabel` or `ariaLabelledby`; there is no automatic fallback
-- Icon SVGs next to visible text — add `aria-hidden="true"` to decorative icons
+- **`IconButton`** — provide `tip` (accessible name for icon-only).
+- **`InfoTip`** — provide `ariaLabel` or `ariaLabelledby`; there is no automatic fallback.
+- Decorative icon SVGs next to visible text — `aria-hidden="true"` on the icon.
 
 ## Form label association
 
-Match `htmlFor` on `<FormGroupLabel>` with the `id` on the input. `<FormGroup>` auto-wires `aria-live` for `error` and `description` — do not add redundant live regions manually.
+Match **`htmlFor`** on **`<FormGroupLabel>`** with the **`id`** on the control. Base **`<FormGroup>`** renders live regions for **`error`** and **`description`**; **`GridForm`** and **`ConnectedForm`** add field wiring (**`aria-describedby`**, **`aria-invalid`**, first-error **`aria-live`** behavior) — do not add redundant duplicate regions. Depth: **[`skills/gamut-forms/SKILL.md`](../skills/gamut-forms/SKILL.md)**.
 
 ## Screen-reader-only text
 
@@ -61,8 +60,19 @@ 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. 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`.
+Do not hardcode hex for adaptive UI. Prefer semantic tokens and **`ColorMode` / `<Background>`** so surfaces track theme and mode — see the **`gamut-color-mode`** skill and [`foundations/modes.md`](../guidelines/foundations/modes.md). Default pairings support accessible UI, but **tokens do not guarantee WCAG compliance** for every layout; validate non-standard combinations.
 
 ## Focus visibility
 
-Never suppress focus indicators with `outline: none` or `outline: 0` without a visible replacement. Gamut's focus styles are intentional and meet WCAG 2.4.7.
+Never suppress focus indicators with `outline: none` or `outline: 0` without a visible replacement. Gamut’s focus styles are intentional (WCAG 2.4.7).
+
+## Where to read more (minimal index)
+
+| Topic | Primary doc |
+| --- | --- |
+| Forms (`GridForm`, `ConnectedForm`, `FormGroup`, validation, live regions) | [`skills/gamut-forms/SKILL.md`](../skills/gamut-forms/SKILL.md) |
+| Component matrix (tips, overlays, composites, checklists; not form wiring) | [`skills/gamut-accessibility/SKILL.md`](../skills/gamut-accessibility/SKILL.md) |
+| Button variants, `IconButton` `tip`, `disabled` vs `aria-disabled` | [`guidelines/components/buttons.md`](../guidelines/components/buttons.md) |
+| ColorMode, `Background`, semantic color roles | **`gamut-color-mode`** skill · [`foundations/modes.md`](../guidelines/foundations/modes.md) · [`foundations/color.md`](../guidelines/foundations/color.md) |
+| Tokens, `css` / `variant` / `states` | Storybook [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) |
+| Install, `GamutProvider`, CSP | Storybook [Meta / Installation](https://gamut.codecademy.com/?path=/docs-meta-installation--page) |
diff --git a/packages/gamut/agent-tools/skills/gamut-accessibility/SKILL.md b/packages/gamut/agent-tools/skills/gamut-accessibility/SKILL.md
index 068fb91d9a3..ceefe737221 100644
--- a/packages/gamut/agent-tools/skills/gamut-accessibility/SKILL.md
+++ b/packages/gamut/agent-tools/skills/gamut-accessibility/SKILL.md
@@ -1,65 +1,57 @@
 ---
 name: gamut-accessibility
-description: Use this skill when implementing or auditing accessibility in Gamut UIs — interactive widgets, forms, focus and keyboard flows, live regions, ARIA, or contrast — including fixes for screen readers, WCAG issues, or Gamut + React Aria patterns.
+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` — interactive components wrap `react-aria-components`, `@react-aria/interactions`, and `react-focus-on`.
+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 — verify behavior in Storybook and source, do not assume React Aria.
 
----
-
-## General rules
-
-Use ARIA sparingly and only when it's the best option available.
-
-### Prefer HTML over ARIA
-
-Unnecessary ARIA can cause harm. If a native HTML element or attribute with the semantics and behavior you need already exists, use it. Reach for ARIA only when native HTML is genuinely insufficient for the pattern.
-
-### A Role is a Promise
-
-ARIA roles modify the accessibility tree and _imply_ behavior. Always ensure that the implied keyboard behavior, focusability, and interactivity exists when a role is used.
-
-### ARIA can both cloak and enhance
+**Product-oriented button variants and props:** [`guidelines/components/buttons.md`](../../guidelines/components/buttons.md)
 
-ARIA can augment native semantics (`aria-pressed` on a `<button>`) or override them entirely (`role="menuitem"` on an `<a>`). Both capabilities are powerful and dangerous. Override only when native HTML genuinely doesn't fit the pattern; when augmenting, don't contradict the native semantics.
-
-
-### Align accessible names with visible copy
-
-Prefer wiring names through visible text and native `<label>` / control text / `alt` over using `aria-label`. Point `aria-labelledby` at the visible heading or label that should define the name if it's not possible to name elements from their content. Use bare `aria-label` when there is no suitable visible label.
-
-### Treat missing visible labels as a design smell
-
-When there is no visible text for a nameable element, consider this a sign that the content design could be improved, but not a requirement that it is changed. This is not an accessibility violation.
+---
 
-```html
-<!-- smell: this list has no conceptual name, so we have to create one using ARIA -->
-<ul aria-label="List heading">
-  <li>...</li>
-</ul>
+## Universal rules
 
-<!-- better: the list's name is visible and can be used for its accessible name -->
-<h2 id="list-name">List heading</h2>
-<ul aria-labelledby="list-name">
-  <li>...</li>
-</ul>
-```
+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
 
-Gamut wraps React Aria for most interactive widget primitives. Roving tabindex, keyboard event handling, and ARIA attribute management are implemented for you in `<Tabs>`, `<Dialog>`, `<Modal>`, and form components. The developer's responsibilities are: supply accessible names, wire labels to inputs, and avoid overriding what the library already provides.
+**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
-
-### Button / IconButton
-
-`<Button>` renders a semantic `<button>` — no `role` needed. For icon-only buttons use `<IconButton>` with a `tip` prop; `tip` becomes the button's `aria-label`. Do not use `<div onClick>` or `<a>` without `href` for actions.
+## 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 [`buttons.md`](../../guidelines/components/buttons.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
@@ -69,77 +61,59 @@ Gamut wraps React Aria for most interactive widget primitives. Roving tabindex,
 <div onClick={handleDelete}><DeleteIcon /></div>
 ```
 
-### Dialog / Modal
+### Dialog / Modal (detail)
 
-Both use `<FocusTrap>` (`react-focus-on`) internally. Focus locks to the dialog on open and returns to the trigger on close. Escape closes the dialog automatically.
+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.
 
-Always provide an accessible name. **Prefer `aria-labelledby`** when a visible heading or title defines the dialog name; use **`aria-label`** only when there is no suitable visible title string.
+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 aria-labelledby="confirm-title">
-  <h2 id="confirm-title">Confirm deletion</h2>
-</Dialog>
+<Dialog
+  title="Confirm deletion"
+  confirmCta={{ children: 'Delete', onClick: handleDelete }}
+  onRequestClose={handleClose}
+  isOpen={open}
+/>
 ```
 
-### Alert
-
-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
-
-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.
+### Alert (detail)
 
-### Forms
-
-`<FormGroup>` + `<FormGroupLabel>` + input element is the complete accessible pattern:
-
-```tsx
-<FormGroup htmlFor="email-input" description="Used for login" error={errors.email}>
-  <FormGroupLabel htmlFor="email-input">Email</FormGroupLabel>
-  <Input id="email-input" type="email" />
-</FormGroup>
-```
+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.
 
-- `htmlFor` on `<FormGroupLabel>` and `id` on the input must match
-- `error` prop on `<FormGroup>` renders into an `aria-live="assertive"` region automatically
-- `description` prop renders into an `aria-live="polite"` region automatically
-- Do not add `aria-describedby` or `aria-errormessage` manually — `<FormGroup>` manages these
+### Tabs (detail)
 
-**Checkbox / Radio**: `htmlFor` is required; the input is visually hidden via `screenReaderOnly` from `@codecademy/gamut-styles` but remains in the accessibility tree.
+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
+### InfoTip (example)
 
-Unlike `<IconButton>`, `<InfoTip>` has no automatic label fallback. Always provide `ariaLabel` or `ariaLabelledby` (camelCase props).
+**`<InfoTip>`** needs **`ariaLabel`** or **`ariaLabelledby`** — see also the always-loaded rules.
 
 ```tsx
 <InfoTip ariaLabel="More information about billing" />
 ```
 
-### SkipToContent
+### ToolTip (detail)
 
-Include `<SkipToContent>` as the first focusable element in the page shell. The main content region must have a matching `id` for the skip link to target.
+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).
 
-### Text (screen-reader-only)
+### SkipToContent (detail)
 
-`<Text screenreader>` is the supported pattern for visually hidden but announced content. `<HiddenText>` is deprecated.
-
-```tsx
-<Text screenreader>Loading results…</Text>
-```
+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 available for custom overlay patterns not covered by `<Dialog>` or `<Modal>`.
+**`<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 Aria components do this automatically; custom implementations must store a ref to the trigger and call `.focus()` on unmount.
+- **`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.
 
 ---
 
@@ -148,19 +122,20 @@ Always return focus to the trigger on close. React Aria components do this autom
 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
 
-Gamut's `<Tabs>` implements this via React Aria. If you build a custom composite widget, you must implement roving tabindex manually. A flat `tabIndex={0}` on every item is wrong — it puts every item in the sequential tab order, which is not the composite pattern.
+- 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` fires for both pointer and keyboard (Space/Enter on native buttons and links). `mousedown` is pointer-only and silently breaks keyboard access.
+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"`, `click` alone is not sufficient — it only fires on keyboard when the element is a native `<button>` or `<a href>`. You must also handle `keydown` for Space and Enter explicitly:
+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) => {
@@ -171,40 +146,40 @@ const handleKeyDown = (e: React.KeyboardEvent) => {
 };
 ```
 
-This is another reason to use `<Button>` — it handles this correctly and you don't.
+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"` |
-| Form validation errors on submit | `aria-live="assertive"` |
-| Frequently updating counts or progress | `aria-live="polite"` + `aria-atomic="true"` |
+| 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.
 
-`<FormGroup>` already uses `aria-live="assertive"` for the `error` prop. Don't elevate unrelated inline errors to assertive — reserve it for interruptions the user didn't directly trigger.
+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
+- **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
-
-Gamut's `ColorMode` and semantic color tokens are designed to meet WCAG AA (4.5:1 for normal text, 3:1 for large text and non-text UI components). Hardcoding hex values bypasses this guarantee and breaks in dark mode. See the `gamut-color-mode` skill for semantic token usage.
+## Color and contrast (non-text)
 
-Non-text contrast (focus indicators, input borders, icon-only controls) requires a minimum 3:1 ratio against adjacent colors per WCAG 1.4.11.
+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.
 
 ---
 
@@ -215,7 +190,7 @@ Non-text contrast (focus indicators, input borders, icon-only controls) requires
 - [ ] 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 are announced via live region
+- [ ] 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)
@@ -225,15 +200,15 @@ Non-text contrast (focus indicators, input borders, icon-only controls) requires
 
 ## Common anti-patterns
 
-| Anti-pattern | Fix |
-|---|---|
-| `<div onClick={…}>` for actions | `<Button>` |
-| `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 `<Button>`, or add `keydown` handler |
-| `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` directly 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 |
+| 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                                                        |
diff --git a/packages/gamut/agent-tools/skills/gamut-forms/SKILL.md b/packages/gamut/agent-tools/skills/gamut-forms/SKILL.md
new file mode 100644
index 00000000000..dda98544d5c
--- /dev/null
+++ b/packages/gamut/agent-tools/skills/gamut-forms/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: gamut-forms
+description: Implementing or auditing Gamut forms — FormGroup, ConnectedForm, ConnectedFormGroup, GridForm, react-hook-form wiring, labels, and accessible error/description regions. Pair with **`gamut-accessibility`** for non-form widgets and **`accessibility.mdc`** for universal HTML/ARIA rules.
+---
+
+# Gamut forms
+
+Canonical wiring for **`FormGroup`**, **`ConnectedForm`**, **`ConnectedFormGroup`**, **`GridForm`**, and field renderers. Source: **`packages/gamut/src/Form/`**, **`ConnectedForm/`**, **`GridForm/`**.
+
+Universal label and primitive guidance: **[`accessibility.mdc`](../../rules/accessibility.mdc)** · overlay and composite patterns: **[`gamut-accessibility`](../gamut-accessibility/SKILL.md)**.
+
+---
+
+## Prefer connected layouts
+
+For typical product forms, prefer **`GridForm`** (declarative **`fields`**, **`LayoutGrid`**, submit/cancel) or **`ConnectedForm`** with **`ConnectedFormGroup`** / **`useConnectedForm`**. Use raw **`FormGroup`** + atoms only when the layout is simple and you fully own **`id`**, **`htmlFor`**, invalid state, and any **`aria-describedby`** (see below).
+
+---
+
+## Labels and controls
+
+**`htmlFor`** / **`id`** pairing — universal rule in **[`accessibility.mdc`](../../rules/accessibility.mdc)** (Form label association). Form-specific notes:
+
+- **`FormGroupLabel`** → control **`id`** (or stable **`name`** when that is your field’s id convention).
+- **Checkbox**, **Radio**, **Select**: same pairing; checkbox/radio use the visually hidden input pattern from **`@codecademy/gamut-styles`** where applicable.
+
+---
+
+## `FormGroup` (baseline)
+
+[`FormGroup.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Form/elements/FormGroup.tsx)
+
+- **`description`** → **`FormGroupDescription`** with **`aria-live="assertive"`**.
+- **`error`** (string) → **`FormError`** with **`aria-live="polite"`** and **`role="alert"`**.
+
+Raw **`FormGroup`** does **not** set **`aria-describedby`** or **`aria-invalid`** on **`children`**. If you compose fields outside **`ConnectedFormGroup`** / **`GridForm`**, wire those yourself or accept that only the live regions above communicate errors/descriptions.
+
+---
+
+## `ConnectedFormGroup`
+
+[`ConnectedFormGroup.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/ConnectedForm/ConnectedFormGroup.tsx)
+
+- Passes **`aria-describedby`** (error region id when shown) and **`aria-invalid`** on the rendered field component.
+- **`FormError`**: **`aria-live="assertive"`** and **`role="alert"`** only when **`isFirstError`**; otherwise **`aria-live="off"`** and **`role="status"`** so subsequent errors do not interrupt repeatedly.
+
+---
+
+## `GridForm`
+
+[`GridFormInputGroup/index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/GridForm/GridFormInputGroup/index.tsx) · [`GridFormTextInput`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/GridForm/GridFormInputGroup/GridFormTextInput/index.tsx)
+
+- Composes **`ConnectedForm`**, **`LayoutGrid`**, **`GridFormButtons`**, and field metadata. **`FormError`** uses the same **first-error assertive** pattern as **`ConnectedFormGroup`** (**`aria-live`** assertive vs off, **`role`** alert vs status).
+- Built-in text inputs set **`aria-invalid`** and register with **react-hook-form** via **`register`**. Custom / **`custom`** / **`custom-group`** renderers must still expose correct **`id`**, **`label`**, and error surfacing consistent with this pattern.
+
+---
+
+## Live regions — do not double up
+
+**`FormGroup`**, **`ConnectedFormGroup`**, and **`GridForm`** already render **`FormError`** (and base **`FormGroup`** renders **`FormGroupDescription`**) with live-region attributes. Do not add a second **`aria-live`** wrapper for the same message stream.
+
+---
+
+## Storybook
+
+- [Organisms / GridForm / About](https://gamut.codecademy.com/?path=/docs-organisms-gridform-about--docs) · [Usage](https://gamut.codecademy.com/?path=/docs-organisms-gridform-usage--docs) · [Validation](https://gamut.codecademy.com/?path=/docs-organisms-gridform-validation--docs) · [Fields](https://gamut.codecademy.com/?path=/docs-organisms-gridform-fields--docs)
+- [Organisms / ConnectedForm / ConnectedForm](https://gamut.codecademy.com/?path=/docs-organisms-connectedform-connectedform--docs) · [ConnectedFormGroup](https://gamut.codecademy.com/?path=/docs-organisms-connectedform-connectedformgroup--docs)
+
+---
+
+## Example — baseline `FormGroup`
+
+```tsx
+<FormGroup
+  htmlFor="email-input"
+  description="Used for login"
+  error={errors.email}
+>
+  <FormGroupLabel htmlFor="email-input">Email</FormGroupLabel>
+  <Input id="email-input" type="email" />
+</FormGroup>
+```
+
+When using **`ConnectedFormGroup`** or **`GridForm`**, prefer their docs and defaults over hand-rolling the above for every field.

From d556822b10d23f5f8ee52cb68cabe6a4b061e896 Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 15:53:14 -0400
Subject: [PATCH 09/11] refactor system props

---
 .../skills/gamut-system-props/SKILL.md        | 82 +++++++++++++------
 .../src/lib/Meta/Best practices.mdx           | 11 +--
 2 files changed, 62 insertions(+), 31 deletions(-)

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 c9baa26f601..b61e5cc567a 100644
--- a/packages/gamut/agent-tools/skills/gamut-system-props/SKILL.md
+++ b/packages/gamut/agent-tools/skills/gamut-system-props/SKILL.md
@@ -1,17 +1,20 @@
 ---
 name: gamut-system-props
-description: Use this skill when building or refactoring styled Gamut components that need layout, spacing, color, border, background, typography, positioning, grid, flex, shadow, or responsive values from @codecademy/gamut-styles — including composing system prop groups with variance.
+description: Use this skill when building or refactoring styled Gamut components that need layout, spacing, color, border, background, typography, positioning, grid, flex, shadow, list styles, or responsive values from @codecademy/gamut-styles — including composing system prop groups with variance.
 ---
 
 # Gamut System Props
 
-Source: `@codecademy/gamut-styles` — [`variance/config.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/config.ts)
+Source: `@codecademy/gamut-styles` — [`variance/config.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/config.ts) (definitions) and [`variance/props.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/props.ts) (`variance.create` groups). **`Box`**, **`FlexBox`**, and **`GridBox`** compose the same groups in [`packages/gamut/src/Box/props.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Box/props.ts).
+
+**See also:** [Styleguide — Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx) (semantic colors, `variant` / `states`, `StyleProps`, responsive examples) and Storybook [Responsive properties](https://gamut.codecademy.com/storybook/?path=/docs-foundations-system-responsive-properties--page).
 
 ## 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`.
 
 Each prop group has:
+
 - **`properties`**: The CSS properties it controls
 - **`scale`**: Token scale it's restricted to (theme colors, spacing values, etc.)
 - **`transform`**: Optional transform applied before output (e.g. `width={0.5}` → `width: 50%`)
@@ -39,7 +42,7 @@ const FlexBox = styled.div(
 
 ### `system.layout`
 
-Controls dimensions, display, overflow, and container behavior.
+Controls dimensions, display, overflow, and container behavior. This group also carries **flex/grid item** props used when laying out children: `flexGrow`, `flexShrink`, `flexBasis`, `order`, `gridColumn`, `gridRow`, `gridColumnStart`, `gridRowStart`, `gridColumnEnd`, `gridRowEnd`, `alignSelf`, `justifySelf`, `gridArea`.
 
 ```tsx
 const Box = styled.div(system.layout);
@@ -47,7 +50,7 @@ const Box = styled.div(system.layout);
 <Box display="flex" width="50%" height="300px" verticalAlign="middle" />;
 ```
 
-Key props: `display`, `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `overflow`, `overflowX`, `overflowY`, `verticalAlign`
+Key props: `containerType`, `display`, `direction`, `dimensions`, `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `overflow`, `overflowX`, `overflowY`, `verticalAlign`, plus the item props above (see `config.ts` for the full map).
 
 ### `system.space`
 
@@ -59,7 +62,7 @@ const Box = styled.div(system.space);
 // Single value
 <Box p={8} m={16} />;
 
-// Responsive array syntax: [mobile, tablet, desktop]
+// Responsive (array / object — see Responsive values)
 <Box my={[16, 24, 32]} px={[8, 16]} />;
 ```
 
@@ -72,10 +75,10 @@ Foreground, background, and border colors restricted to the theme's color palett
 ```tsx
 const Box = styled.div(system.color);
 
-<Box bg="navy" textColor="gray-100" borderColor="blue" />;
+<Box bg="navy" color="gray-900" textColor="gray-100" borderColor="blue" />;
 ```
 
-Key props: `bg` (background-color shorthand), `textColor`, `borderColor`
+Key props: `color`, `textColor` (both set CSS `color`), `bg`, `borderColor`, plus directional `borderColor*` variants — see `config.ts` for the full set.
 
 ### `system.typography`
 
@@ -84,16 +87,22 @@ Text styling connected to theme typography scales.
 ```tsx
 const Text = styled.p(system.typography);
 
-<Text fontSize={16} fontFamily="accent" textTransform="uppercase" lineHeight={1.5} />;
+<Text
+  fontSize={16}
+  fontFamily="accent"
+  fontStyle="italic"
+  textTransform="uppercase"
+  lineHeight="base"
+/>;
 ```
 
-Key props: `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `textAlign`, `textTransform`, `textDecoration`, `letterSpacing`, `whiteSpace`
+Key props: `fontFamily`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `textAlign`, `textTransform`, `textDecoration`, `letterSpacing`, `whiteSpace` — prefer **`lineHeight`** scale keys (`base`, `title`, `spacedTitle`) from the theme over raw numbers when possible.
 
 ### `system.border`
 
-Border width, style, radius, and color.
+Border width, style, radius, and color. Many **logical shorthands** exist (`borderX`, `borderColorY`, `borderRadiusTop`, …); see `config.ts` for the full map.
 
-Key props: `border`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `borderRadius`, `borderWidth`, `borderStyle`
+Key props (non-exhaustive): `border`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `borderRadius`, `borderWidth`, `borderStyle`
 
 ### `system.background`
 
@@ -104,7 +113,11 @@ import myBg from './myBg.png';
 
 const Box = styled.div(system.background);
 
-<Box background={`url(${myBg})`} backgroundSize="cover" backgroundPosition="center" />;
+<Box
+  background={`url(${myBg})`}
+  backgroundSize="cover"
+  backgroundPosition="center"
+/>;
 ```
 
 Key props: `background`, `backgroundImage`, `backgroundSize`, `backgroundPosition`, `backgroundRepeat`
@@ -113,27 +126,25 @@ Key props: `background`, `backgroundImage`, `backgroundSize`, `backgroundPositio
 
 Flexbox child and container properties.
 
-Key props: `flex`, `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `flexBasis`, `alignItems`, `alignSelf`, `justifyContent`, `justifySelf`, `gap`, `rowGap`, `columnGap`
+Key props (non-exhaustive): `flex`, `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `flexBasis`, `alignItems`, `alignContent`, `alignSelf`, `justifyContent`, `justifyItems`, `justifySelf`, `gap`, `rowGap`, `columnGap`
 
 ### `system.grid`
 
 CSS Grid container and child properties.
 
-Key props: `gridTemplateColumns`, `gridTemplateRows`, `gridTemplateAreas`, `gridColumn`, `gridRow`, `gridArea`, `gridAutoFlow`
+Key props (non-exhaustive): `gridTemplateColumns`, `gridTemplateRows`, `gridTemplateAreas`, `gridColumn`, `gridRow`, `gridArea`, `gridAutoFlow`, `gridAutoColumns`, `gridAutoRows`, `gap`, `rowGap`, `columnGap`
 
 ### `system.positioning`
 
-Position and offset properties.
+Position and offset properties. Inset shorthands use **`transformSize`**; physical vs logical edges follow **`useLogicalProperties`**.
 
 ```tsx
-const Overlay = styled.div(
-  variance.compose(system.layout, system.positioning)
-);
+const Overlay = styled.div(variance.compose(system.layout, system.positioning));
 
 <Overlay position="absolute" top={0} left={0} width="100%" height="100%" />;
 ```
 
-Key props: `position`, `top`, `right`, `bottom`, `left`, `zIndex`
+Key props: `position`, `inset`, `top`, `right`, `bottom`, `left`, `zIndex`, `opacity`
 
 ### `system.shadow`
 
@@ -141,18 +152,35 @@ Box and text shadow.
 
 Key props: `boxShadow`, `textShadow`
 
+### `system.list`
+
+List marker styling (`listStyle`, `listStyleType`, `listStylePosition`, `listStyleImage`). Included on **`Box`** alongside the other composed groups.
+
 ## Responsive values
 
-All system props accept an **array of values** for responsive breakpoints (Gamut uses a mobile-first approach):
+All system props accept responsive values **mobile-first** (min-width queries). Two shapes are supported:
+
+### Object syntax
+
+Keys are breakpoints; **`_`** is the base (no breakpoint). Includes `xs`, `sm`, `md`, `lg`, `xl`, and container keys `c_xs` … `c_xl`.
 
 ```tsx
-// [mobile, tablet, desktop]
-<Box width={['100%', '50%', '33%']} p={[8, 16, 24]} />;
+<Box width={{ _: '100%', sm: '50%', md: '33%' }} px={{ _: 8, md: 16 }} />
 ```
 
+### Array syntax
+
+Slots map in order to: base, `xs`, `sm`, `md`, `lg`, `xl`, then `c_xs` … `c_xl`. Leave a slot **empty** (or use `undefined`) to skip a breakpoint.
+
+```tsx
+<Box width={['100%', , '50%']} p={[8, 16, , 24]} />
+```
+
+Full typings and behavior: [Responsive properties (Storybook)](https://gamut.codecademy.com/storybook/?path=/docs-foundations-system-responsive-properties--page).
+
 ## Using `css()` for styled definitions
 
-For static styles in styled components, use `css()` from `@codecademy/gamut-styles`:
+For static styles in styled components, use **`css()`** from `@codecademy/gamut-styles` (same implementation as **`system.css`** on the `system` namespace).
 
 ```tsx
 import { css } from '@codecademy/gamut-styles';
@@ -168,6 +196,8 @@ const Text = styled.div(css({ color: 'primary', p: 4 }));
 ## Key principles
 
 - Compose `system.*` groups via `variance.compose()` — don't apply multiple groups by chaining `styled.div(system.a)(system.b)`.
-- Use `system.color` (semantic aliases) for colors that need to adapt to dark/light mode; use raw tokens only for colors that should stay fixed regardless of mode.
-- Use `system.space` values that reference the spacing scale rather than arbitrary pixel values to maintain visual rhythm.
-- For background images/patterns use `system.background`; for solid background colors that may switch mode use `<Background>` from ColorMode.
+- Prefer **semantic color names** on `system.color` (e.g. `bg="background"`, `textColor="text"`) so values track **ColorMode**; use raw palette keys only when the design should stay fixed across modes.
+- Use **`bg`** with semantic tokens for most mode-aware surfaces; use **`<Background>`** from `@codecademy/gamut-styles` when you need its **contrast- and mode-aware** behavior, not for every tinted panel.
+- Use `system.space` values on the **spacing scale** rather than arbitrary pixel strings to keep rhythm consistent.
+- For background images/patterns use `system.background`; for solid fills use `system.color` / semantic **`bg`** (or **`Background`** when that component’s behavior is required).
+- For reusable **variants** or **boolean states** on styled primitives, use **`variant`** / **`states`** from `@codecademy/gamut-styles` and expose props with **`StyleProps<typeof …>`** from `@codecademy/variance` — see [Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx).
diff --git a/packages/styleguide/src/lib/Meta/Best practices.mdx b/packages/styleguide/src/lib/Meta/Best practices.mdx
index 7944e30406b..9902b2358bc 100644
--- a/packages/styleguide/src/lib/Meta/Best practices.mdx	
+++ b/packages/styleguide/src/lib/Meta/Best practices.mdx	
@@ -109,9 +109,10 @@ System props are a core part of our new approach to dynamic and customized styli
 
 ```tsx
 import { Box } from '@codecademy/gamut';
+import { pxRem } from '@codecademy/gamut-styles';
 
 const MyContainer = ({ children }) => (
-  <Box paddingX={[16, 32, 64, , 96]}>{children}</Box>
+  <Box px={[16, 32, 64, , 96]}>{children}</Box>
 );
 
 const MyOtherContainer = ({ children }) => (
@@ -212,18 +213,18 @@ const SomeCoolLayout = ({ children }) => (
 **Design Token Access** - Responsively accessing tokens by key.
 
 ```tsx
+import { Box } from '@codecademy/gamut';
+
 const CardLikeThing = ({ children }) => (
   <Box
-    backgroundColor={{ _: 'background', md: 'text' }}
+    bg={{ _: 'background', md: 'text' }}
     textColor={{ _: 'text', md: 'background' }}
   >
     {children}
   </Box>
 );
 
-const Content = ({ children }) => (
-  <Box padding={{ _: 16, md: 32 }}>{children}</Box>
-);
+const Content = ({ children }) => <Box p={{ _: 16, md: 32 }}>{children}</Box>;
 ```
 
 # ❌ Nested selectors

From b468a830549c9f249098f95536aa2517587ab628 Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 16:23:56 -0400
Subject: [PATCH 10/11] tests audit

---
 .../agent-tools/commands/gamut-review.md      |  16 +-
 .../agent-tools/skills/gamut-testing/SKILL.md | 164 +++++++++++-------
 2 files changed, 110 insertions(+), 70 deletions(-)

diff --git a/packages/gamut/agent-tools/commands/gamut-review.md b/packages/gamut/agent-tools/commands/gamut-review.md
index b26b67b9c80..02e512ab278 100644
--- a/packages/gamut/agent-tools/commands/gamut-review.md
+++ b/packages/gamut/agent-tools/commands/gamut-review.md
@@ -174,13 +174,13 @@ Case-insensitive. Use to label `palette:` in the report; **do not** stop at this
 
 Grep test files (`**/__tests__/**/*.{ts,tsx}`, `**/*.test.{ts,tsx}`, `**/*.spec.{ts,tsx}`) for these patterns. Skip `node_modules`, `dist`.
 
-| Pattern                                               | Verdict                               | Reason                                                                                                                                                             |
-| ----------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `jest.mock\(.*@codecademy/gamut`                      | **Error**                             | Manual mocking bypasses theme context and produces false-positive tests; use `setupRtl` or `MockGamutProvider` instead                                             |
-| `jest.mock\(.*@codecademy/gamut-styles`               | **Error**                             | Same issue as above — mocking gamut-styles breaks token resolution                                                                                                 |
-| `from '@codecademy/gamut-tests'`                      | Good — report count of files using it | Correct import for `setupRtl` and `MockGamutProvider`                                                                                                              |
-| `from 'component-test-setup'` (without gamut-tests)   | **Warning**                           | Should import `setupRtl` from `@codecademy/gamut-tests`, not directly from `component-test-setup` — the gamut-tests wrapper adds `MockGamutProvider` automatically |
-| `new GamutProvider` or `<GamutProvider` in test files | **Warning**                           | Tests should use `MockGamutProvider` (sets `useCache={false}`, `useGlobals={false}`), not `GamutProvider` directly                                                 |
+| Pattern                                               | Verdict                               | Reason                                                                                                                                                                                                                                                  |
+| ----------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jest.mock\(.*@codecademy/gamut`                      | **Error**                             | Manual mocking bypasses theme context and produces false-positive tests; prefer **`setupRtl`** from `@codecademy/gamut-tests` (or a harness + **`setupRtl`**); use raw **`MockGamutProvider`** + **`render`** only for rare one-offs or Storybook mocks |
+| `jest.mock\(.*@codecademy/gamut-styles`               | **Error**                             | Same issue as above — mocking gamut-styles breaks token resolution                                                                                                                                                                                      |
+| `from '@codecademy/gamut-tests'`                      | Good — report count of files using it | Correct import for `setupRtl` and `MockGamutProvider`                                                                                                                                                                                                   |
+| `from 'component-test-setup'` (without gamut-tests)   | **Warning**                           | Should import `setupRtl` from `@codecademy/gamut-tests`, not directly from `component-test-setup` — the gamut-tests wrapper adds `MockGamutProvider` automatically                                                                                      |
+| `new GamutProvider` or `<GamutProvider` in test files | **Warning**                           | Prefer **`setupRtl`**; use **`MockGamutProvider`** (sets `useCache={false}`, `useGlobals={false}`) in harnesses or stories, not **`GamutProvider`** directly                                                                                            |
 
 Skill reference for remediation: `gamut-testing`
 
@@ -215,7 +215,7 @@ Hardcoded colors                                                         [→ ga
 
 Test setup                                                               [→ gamut-testing]
   ✓  @codecademy/gamut-tests   used in 12 test files
-  ✗  jest.mock(@codecademy/gamut)   2 occurrences — remove and use setupRtl instead
+  ✗  jest.mock(@codecademy/gamut)   2 occurrences — remove; prefer setupRtl (or harness + setupRtl)
        src/components/Foo/__tests__/Foo.test.tsx:3
        src/components/Bar/__tests__/Bar.test.tsx:5
   ⚠  direct component-test-setup import   1 occurrence — import from @codecademy/gamut-tests
diff --git a/packages/gamut/agent-tools/skills/gamut-testing/SKILL.md b/packages/gamut/agent-tools/skills/gamut-testing/SKILL.md
index e1d9ed3e980..9dbc0f04e2b 100644
--- a/packages/gamut/agent-tools/skills/gamut-testing/SKILL.md
+++ b/packages/gamut/agent-tools/skills/gamut-testing/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gamut-testing
-description: Use this skill when writing or fixing unit tests for React components that use Gamut — setupRtl, MockGamutProvider, ColorMode in tests, emotion matchers, or removing jest.mock of @codecademy/gamut / gamut-styles.
+description: Use this skill when writing or fixing unit tests for React components that use Gamut — prefer setupRtl from @codecademy/gamut-tests, harness patterns for useLogicalProperties and ColorMode, RTL/dir testing, emotion matchers, or removing jest.mock of @codecademy/gamut / gamut-styles.
 ---
 
 # Gamut Testing
@@ -9,40 +9,34 @@ Source: `@codecademy/gamut-tests` — [`index.tsx`](https://github.com/Codecadem
 
 ---
 
-## Core rule: never mock Gamut components
-
-Do not use `jest.mock('@codecademy/gamut')` or manually mock individual Gamut components in test files. This silently bypasses emotion's theme context, produces tests that can't catch real rendering failures, and requires every test file to maintain its own fragile mock list.
-
-Use `MockGamutProvider` or `setupRtl` — both are designed for exactly this purpose.
-
 ---
 
-## What `MockGamutProvider` does
+## What `MockGamutProvider` does (under `setupRtl`)
 
-`MockGamutProvider` wraps `GamutProvider` with test-safe settings:
+`MockGamutProvider` forwards to `GamutProvider` with:
 
-- `useCache={false}` — disables emotion's style injection cache so styles are predictable across tests
-- `useGlobals={false}` — disables global CSS (Reboot, Typography, CSS Variables) to avoid side effects between test files
-- `theme={coreTheme}` — provides the full Gamut token set so styled components resolve correctly
+- `useCache={false}` — stable Emotion output across tests
+- `useGlobals={false}` — no global Reboot/Typography bleed between files
+- `theme={theme}` — full token theme for styled components
+- Optional **`useLogicalProperties`** — forwarded for logical vs physical CSS in variance
 
-You should never construct a `GamutProvider` manually in a test. Use `MockGamutProvider`.
+You normally **do not** import `MockGamutProvider` for plain component tests; `setupRtl` already wraps the **component under test** once. Import it **inside a harness** when the SUT needs a non-default provider flag or extra wrappers (see below).
 
 ---
 
 ## Decision guide
 
-| Scenario | Use |
-|---|---|
-| Standard component unit test | `setupRtl` from `@codecademy/gamut-tests` |
-| Test that needs to vary `useLogicalProperties` | `render` + `MockGamutProvider` directly |
-| Test that needs `ColorMode` context | `render` + `MockGamutProvider` + `<ColorMode>` |
-| Visual test mock / Storybook wrapper | `MockGamutProvider` directly |
+| Scenario                                                         | Prefer                                                                                                                                                                                                                                     |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Default unit test for a Gamut (or app) component                 | **`setupRtl(Component, defaultProps)`** once per file / describe                                                                                                                                                                           |
+| Vary **`useLogicalProperties`** across cases                     | **Harness** that accepts `useLogicalProperties` and wraps **`MockGamutProvider`**, then **`setupRtl(Harness, defaults)`**; pass overrides per `it` / `describe.each`                                                                       |
+| Need **`ColorMode`** (or other context) around the SUT           | **Harness** with `<ColorMode>` inside the tree, then **`setupRtl(Harness)`** — no need for raw `render` unless you are testing the provider itself                                                                                         |
+| **`dir` / RTL** behavior (e.g. mirrored layout, `useElementDir`) | Keep using **`setupRtl`** for the component; set **`document.documentElement.setAttribute('dir', 'rtl' \| 'ltr')`** (and scroll/viewport stubs if needed) in **`beforeEach` / `afterEach`**; reset `dir` after tests so suites do not leak |
+| Storybook-only mock, chromatic-style wrapper, or non-RTL harness | **`MockGamutProvider`** (± **`ColorMode`**) in the exported wrapper component                                                                                                                                                              |
 
 ---
 
-## `setupRtl` — preferred pattern
-
-`setupRtl` from `@codecademy/gamut-tests` wraps `setupRtl` from `component-test-setup` with `MockGamutProvider` automatically. You do not need to add `MockGamutProvider` yourself.
+## `setupRtl` — primary pattern
 
 ```tsx
 import { setupRtl } from '@codecademy/gamut-tests';
@@ -66,13 +60,21 @@ it('accepts prop overrides', () => {
 ```
 
 `renderView` returns `{ view, props, update }`:
-- `view` — RTL `RenderResult` (getByRole, getByText, etc.)
-- `props` — the resolved props passed to the component (useful for asserting on jest.fn() mocks)
-- `update` — re-render with updated props without remounting
+
+- **`view`** — RTL `RenderResult` (`getByRole`, `getByLabelText`, `getByText`, …)
+- **`props`** — resolved props (handy for `jest.fn()` assertions)
+- **`update`** — re-render with new props without remounting
+
+### Query and interaction habits (RTL)
+
+- Prefer **`getByRole`**, **`getByLabelText`**, and accessible names over CSS selectors or snapshotting class strings unless you are explicitly testing styling.
+- Prefer **`@testing-library/user-event`** over `fireEvent` when simulating real input (import `userEvent` from **`@testing-library/user-event`** in current major versions).
 
 ### Accessing mock functions via `props`
 
 ```tsx
+import userEvent from '@testing-library/user-event';
+
 it('calls onClick when clicked', async () => {
   const { view, props } = renderView();
   await userEvent.click(view.getByRole('button'));
@@ -82,50 +84,84 @@ it('calls onClick when clicked', async () => {
 
 ---
 
-## `MockGamutProvider` directly — when you need more control
+## Harness + `setupRtl` when the wrapper is not default
 
-Use `render` + `MockGamutProvider` when `setupRtl` doesn't give enough control over the wrapper — for example, when testing both logical and physical CSS property modes, or when adding `ColorMode`.
+`setupRtl` always wraps with **`MockGamutProvider`** with default props. To vary **`useLogicalProperties`**, add **`ColorMode`**, or compose other providers, define a **small harness** and pass **`setupRtl`** that harness — still one `renderView` factory, still `props` / `update` ergonomics.
+
+### Varying `useLogicalProperties` (logical vs physical CSS)
 
 ```tsx
-import { MockGamutProvider } from '@codecademy/gamut-tests';
-import { render } from '@testing-library/react';
-
-it('uses logical properties when enabled', () => {
-  const { container } = render(
-    <MockGamutProvider useLogicalProperties>
-      <MyComponent width="200px" />
-    </MockGamutProvider>
-  );
-  // assert on inlineSize rather than width
-});
-```
+import { MockGamutProvider, setupRtl } from '@codecademy/gamut-tests';
 
-### Testing both logical and physical property modes
+import { MyComponent } from '../MyComponent';
+
+type HarnessProps = React.ComponentProps<typeof MyComponent> & {
+  useLogicalProperties?: boolean;
+};
+
+const MyHarness = ({ useLogicalProperties, ...rest }: HarnessProps) => (
+  <MockGamutProvider useLogicalProperties={useLogicalProperties}>
+    <MyComponent {...rest} />
+  </MockGamutProvider>
+);
+
+const renderView = setupRtl(MyHarness, { width: '200px' });
 
-```tsx
 describe.each([
-  { useLogicalProperties: true, widthProp: 'inlineSize' },
-  { useLogicalProperties: false, widthProp: 'width' },
+  { useLogicalProperties: true as const, widthProp: 'inlineSize' as const },
+  { useLogicalProperties: false as const, widthProp: 'width' as const },
 ])(
   'useLogicalProperties=$useLogicalProperties',
   ({ useLogicalProperties, widthProp }) => {
     it(`uses ${widthProp}`, () => {
-      const { container } = render(
-        <MockGamutProvider useLogicalProperties={useLogicalProperties}>
-          <MyComponent width="200px" />
-        </MockGamutProvider>
-      );
-      expect(container.firstChild).toHaveStyle({ [widthProp]: '200px' });
+      const { view } = renderView({ useLogicalProperties });
+      expect(view.getByTestId('my-component-root')).toHaveStyle({
+        [widthProp]: '200px',
+      });
     });
   }
 );
 ```
 
+The outer `setupRtl` wrapper adds a default **`MockGamutProvider`**; the harness’s inner **`MockGamutProvider`** sets **`useLogicalProperties`** for the subtree under test (nested `GamutProvider` / theme is the nearest one Emotion and variance see).
+
+### `ColorMode` without abandoning `setupRtl`
+
+```tsx
+import { ColorMode } from '@codecademy/gamut-styles';
+import { setupRtl } from '@codecademy/gamut-tests';
+
+const DarkHarness = (props: React.ComponentProps<typeof MyComponent>) => (
+  <ColorMode mode="dark">
+    <MyComponent {...props} />
+  </ColorMode>
+);
+
+const renderDark = setupRtl(DarkHarness, { title: 'Hi' });
+```
+
+Use **`MockGamutProvider`** only inside the harness if you also need a non-default Gamut flag **and** `ColorMode` in the same tree; otherwise **`setupRtl(DarkHarness)`** is enough.
+
+---
+
+## Raw `render` + `MockGamutProvider` — rare
+
+Reserve **`render` from `@testing-library/react`** + manual **`MockGamutProvider`** for cases where a harness would be more obscure than a single inline tree (e.g. highly dynamic one-off trees). If the same wrapper appears more than once, switch to a **harness + `setupRtl`**.
+
+---
+
+## RTL / `dir` and document-level behavior
+
+Some components (e.g. overlays that call **`useElementDir`**) resolve direction from **`document.documentElement`** when there is no real target node. For those tests:
+
+- Set **`document.documentElement.setAttribute('dir', 'rtl')`** (or `'ltr'`) around the scenario, **`unmount`** between LTR and RTL assertions when re-rendering, and restore **`dir`** in **`afterEach`** so other tests start clean.
+- Combine with the harness pattern above when **`useLogicalProperties`** affects which longhand wins (`left` vs `insetInlineStart`, etc.).
+
 ---
 
 ## Emotion style assertions
 
-Install `@emotion/jest` matchers once per test file to enable CSS-in-JS assertions:
+Install **`@emotion/jest`** matchers if you absolutely need to enable CSS-in-JS assertions:
 
 ```tsx
 import { matchers } from '@emotion/jest';
@@ -140,7 +176,7 @@ expect(element).toHaveStyle({ borderRadius: '2px' });
 expect(element).toHaveStyleRule('padding', '1rem');
 ```
 
-Use `theme` from `@codecademy/gamut-styles` to avoid hardcoding token values:
+Use **`theme`** from **`@codecademy/gamut-styles`** instead of hardcoding token strings:
 
 ```tsx
 import { theme } from '@codecademy/gamut-styles';
@@ -150,15 +186,17 @@ expect(element).toHaveStyle({ columnGap: theme.spacing[40] });
 
 ---
 
-## Visual test wrappers
+## Visual test wrappers and Storybook
 
-When creating mock components for visual tests or Storybook, wrap with `MockGamutProvider` and `ColorMode`:
+Exported mocks and stories may wrap with **`MockGamutProvider`** and **`ColorMode`** explicitly (no `setupRtl` in Storybook):
 
 ```tsx
 import { MockGamutProvider } from '@codecademy/gamut-tests';
 import { ColorMode } from '@codecademy/gamut-styles';
 
-export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (props) => (
+export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (
+  props
+) => (
   <MockGamutProvider>
     <ColorMode mode="light">
       <MyComponent {...props} />
@@ -171,11 +209,13 @@ export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (pr
 
 ## Common anti-patterns
 
-| Anti-pattern | Fix |
-|---|---|
-| `jest.mock('@codecademy/gamut', () => ({ ... }))` | Remove mock; use `setupRtl` or `MockGamutProvider` |
-| `jest.mock('@codecademy/gamut-styles', ...)` | Remove mock; `MockGamutProvider` handles theme context |
-| Wrapping with `GamutProvider` directly in tests | Use `MockGamutProvider` — it sets `useCache={false}` and `useGlobals={false}` |
-| Repeating `render(<MockGamutProvider>...</MockGamutProvider>)` in every test | Extract with `setupRtl`; define `renderView` once above the `describe` block |
-| One `setupRtl` call per `it` block | Define `renderView` once outside `describe`, call it inside each `it` |
-| Asserting on raw CSS token strings | Import `theme` from `@codecademy/gamut-styles` and use `theme.spacing[n]`, `theme.fontSize`, etc. |
+| Anti-pattern                                                          | Fix                                                                                                        |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `jest.mock('@codecademy/gamut', () => ({ ... }))`                     | Remove; use **`setupRtl`** (or harness + **`setupRtl`**)                                                   |
+| `jest.mock('@codecademy/gamut-styles', ...)`                          | Remove; **`MockGamutProvider`** / **`setupRtl`** supplies theme                                            |
+| **`GamutProvider`** in test files                                     | Use **`MockGamutProvider`** only when building a harness or story; default tests go through **`setupRtl`** |
+| **`import { setupRtl } from 'component-test-setup'`** in Gamut / apps | Import **`setupRtl` from `@codecademy/gamut-tests`** so **`MockGamutProvider`** is applied                 |
+| Repeated **`render(<MockGamutProvider>…`**                            | **Harness + `setupRtl`**, or a shared **`renderView`** factory                                             |
+| One **`setupRtl`** call per **`it`**                                  | Define **`renderView`** once outside **`describe`**, call it inside each **`it`**                          |
+| Asserting raw CSS strings for tokens                                  | Use **`theme`** from **`@codecademy/gamut-styles`**                                                        |
+| Leaking **`dir="rtl"`** between tests                                 | Reset **`document.documentElement`** in **`afterEach`**                                                    |

From 3728995e842d7e92e01009b04e5d08ad3a941182 Mon Sep 17 00:00:00 2001
From: dreamwasp <cass.spain@skillsoft.com>
Date: Fri, 15 May 2026 16:53:24 -0400
Subject: [PATCH 11/11] break out theme docs

---
 .../guidelines/foundations/color.md           |   2 +-
 .../guidelines/foundations/typography.md      |   3 +-
 .../gamut/agent-tools/guidelines/overview.md  |   4 +
 .../skills/gamut-color-mode/SKILL.md          |   2 +
 .../skills/gamut-style-utilities/SKILL.md     | 107 ++++++++++++++++
 .../skills/gamut-system-props/SKILL.md        |   2 +-
 .../agent-tools/skills/gamut-theming/SKILL.md | 117 ++++--------------
 7 files changed, 143 insertions(+), 94 deletions(-)
 create mode 100644 packages/gamut/agent-tools/skills/gamut-style-utilities/SKILL.md

diff --git a/packages/gamut/agent-tools/guidelines/foundations/color.md b/packages/gamut/agent-tools/guidelines/foundations/color.md
index 2e28af241dc..e6ebb20e288 100644
--- a/packages/gamut/agent-tools/guidelines/foundations/color.md
+++ b/packages/gamut/agent-tools/guidelines/foundations/color.md
@@ -4,7 +4,7 @@ Use **semantic aliases** for UI that should respond to **color mode** (light/dar
 
 Prefer **`css` / `variant` / `states`** from `@codecademy/gamut-styles` with semantic names (see Storybook [Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page)).
 
-**Related:** [`setup.md`](../setup.md) (which theme to import) · [`gamut-theming` skill](../../skills/gamut-theming/SKILL.md) · [`gamut-color-mode` skill](../../skills/gamut-color-mode/SKILL.md) · [`modes.md`](modes.md) (`<ColorMode>`, `<Background>`)
+**Related:** [`setup.md`](../setup.md) (which theme to import) · [`gamut-theming` skill](../../skills/gamut-theming/SKILL.md) · [`gamut-style-utilities` skill](../../skills/gamut-style-utilities/SKILL.md) · [`gamut-color-mode` skill](../../skills/gamut-color-mode/SKILL.md) · [`modes.md`](modes.md) (`<ColorMode>`, `<Background>`)
 
 Percipio, LX Studio, Admin, and Platform override subsets of semantic mappings while keeping the shared alias API — see theme sources below before hardcoding palette names or hex.
 
diff --git a/packages/gamut/agent-tools/guidelines/foundations/typography.md b/packages/gamut/agent-tools/guidelines/foundations/typography.md
index 31e5fe487bc..bacae3d9d27 100644
--- a/packages/gamut/agent-tools/guidelines/foundations/typography.md
+++ b/packages/gamut/agent-tools/guidelines/foundations/typography.md
@@ -80,4 +80,5 @@ These UX rules target **Apercu + Suisse** products; do not blindly apply to Perc
 ## Related skills
 
 - [`gamut-typography`](../../skills/gamut-typography/SKILL.md) — deeper editorial patterns for agents.
-- [`gamut-theming`](../../skills/gamut-theming/SKILL.md) — accessing `theme.font*` in styled components.
+- [`gamut-style-utilities`](../../skills/gamut-style-utilities/SKILL.md) — `css()` / `variant` / `states` and tokenized typography in styled components.
+- [`gamut-theming`](../../skills/gamut-theming/SKILL.md) — which theme / `GamutProvider` / `theme.d.ts`.
diff --git a/packages/gamut/agent-tools/guidelines/overview.md b/packages/gamut/agent-tools/guidelines/overview.md
index 21d74d04551..2ded51f5d00 100644
--- a/packages/gamut/agent-tools/guidelines/overview.md
+++ b/packages/gamut/agent-tools/guidelines/overview.md
@@ -13,6 +13,8 @@ Gamut is the Codecademy / Skillsoft design system — React component library (`
 
 **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`).
 
+**Agent skills (styling / themes):** `gamut-style-utilities` (`css`, `variant`, `states`, `StyleProps`), `gamut-theming` (which theme, `GamutProvider`, new themes), `gamut-system-props` (`system.*` / `Box`), `gamut-color-mode` (ColorMode / semantic color).
+
 ## Themes
 
 Runtime stacks come from `@codecademy/gamut-styles` (see [foundations/typography.md](foundations/typography.md)). Product `DESIGN.*.md` may differ until reconciled.
@@ -38,3 +40,5 @@ Set the theme at the app root via `<GamutProvider theme={...}>`.
 | [foundations/spacing.md](foundations/spacing.md)       | Spacing scale, radii, Layout grid; system props + responsive/container queries |
 | [components/overview.md](components/overview.md)       | Full component catalog                                                         |
 | [components/buttons.md](components/buttons.md)         | Button variants, props, decision tree                                          |
+| `agent-tools/skills/gamut-style-utilities/SKILL.md`    | `css` / `variant` / `states`, `StyleProps`, `useTheme` escape hatch            |
+| `agent-tools/skills/gamut-theming/SKILL.md`            | Theme matrix, `GamutProvider`, CreatingThemes                                  |
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 61dd55dad15..72754d14ace 100644
--- a/packages/gamut/agent-tools/skills/gamut-color-mode/SKILL.md
+++ b/packages/gamut/agent-tools/skills/gamut-color-mode/SKILL.md
@@ -26,6 +26,8 @@ This set is not exhaustive (e.g. `text-accent`, `background-disabled`, `danger`
 
 **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.
diff --git a/packages/gamut/agent-tools/skills/gamut-style-utilities/SKILL.md b/packages/gamut/agent-tools/skills/gamut-style-utilities/SKILL.md
new file mode 100644
index 00000000000..36eba4d4975
--- /dev/null
+++ b/packages/gamut/agent-tools/skills/gamut-style-utilities/SKILL.md
@@ -0,0 +1,107 @@
+---
+name: gamut-style-utilities
+description: Use this skill when authoring Gamut styles with @codecademy/gamut-styles — css(), variant(), states(), StyleProps from variance, or the useTheme() escape hatch; choosing between these APIs and system props; semantic tokens with ColorMode.
+---
+
+# Gamut style utilities
+
+Source: `@codecademy/gamut-styles` — [`variance/props.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/props.ts) (`css`, `variant`, `states` built on `PROPERTIES.all`).
+
+**See also:** [`gamut-theming`](../gamut-theming/SKILL.md) (which theme, `GamutProvider`, new themes). [`gamut-system-props`](../gamut-system-props/SKILL.md) (`system.*`, responsive props, `Box`). [`gamut-color-mode`](../gamut-color-mode/SKILL.md) (semantic color, `<ColorMode>`, `<Background>`). [Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx) and [system compose](https://gamut.codecademy.com/?path=/docs-foundations-system-compose--page).
+
+## Overview
+
+Use **`css()`**, **`variant()`**, and **`states()`** from `@codecademy/gamut-styles` for **typed, token-scaled** style objects (same scales as composed **`system.*`** props). Prefer **semantic** color keys so styles track **ColorMode** and theme.
+
+For **layout-heavy** styled components, prefer composing **`system.*`** via `variance.compose()` (see **`gamut-system-props`**) instead of re-stating every longhand in `css()`.
+
+## `css()` — static style objects
+
+```tsx
+import { css } from '@codecademy/gamut-styles';
+import styled from '@emotion/styled';
+
+const Box = styled.div(css({ bg: 'navy-400', p: 4 }));
+const Text = styled.div(css({ color: 'primary', p: 4 }));
+```
+
+## `variant()` and `states()` — branching and toggles
+
+- **`variant()`** — mutually exclusive modes: `base`, `defaultVariant`, and a `variants` map (semantic colors, spacing shorthands, nested selectors such as `'&:hover'`).
+
+```tsx
+import { variant } from '@codecademy/gamut-styles';
+import styled from '@emotion/styled';
+
+const Anchor = styled.a(
+  variant({
+    base: { p: 4 },
+    defaultVariant: 'interface',
+    variants: {
+      interface: {
+        color: 'text',
+        '&:hover': { color: 'text-accent' },
+      },
+      inline: {
+        color: 'primary',
+        '&:hover': { color: 'secondary' },
+      },
+    },
+  })
+);
+```
+
+- **`states()`** — independent boolean-style props (`base` + named keys).
+
+```tsx
+import { states } from '@codecademy/gamut-styles';
+import styled from '@emotion/styled';
+
+const UtilityBox = styled.div(
+  states({
+    base: { mx: 4, my: 8, p: 16 },
+    disabled: { bg: 'background-disabled', color: 'text-disabled' },
+    center: { alignItems: 'center', justifyContent: 'center' },
+  })
+);
+```
+
+### `StyleProps` on React components
+
+```tsx
+import { states } from '@codecademy/gamut-styles';
+import { StyleProps } from '@codecademy/variance';
+import styled from '@emotion/styled';
+
+const panelShellStates = states({ base: { p: 4 }, dense: { p: 2 } });
+const PanelShell = styled.div(panelShellStates);
+
+export type PanelShellProps = StyleProps<typeof panelShellStates> & {
+  title: string;
+};
+
+export const Panel: React.FC<PanelShellProps> = ({ title, ...rest }) => (
+  <PanelShell {...rest}>{title}</PanelShell>
+);
+```
+
+Prefer **`variant` / `states`** over branching on raw `theme` fields inside styled **template literals** when the output is Emotion-managed CSS.
+
+## `useTheme()` — escape hatch
+
+Prefer **`css()`**, **`system.*`**, **`variant()`**, and **`states()`** for styling. Use **`useTheme()`** from `@emotion/react` when a token value must be read in **plain JS** (charts, canvas, third-party props), not as the default way to color DOM nodes.
+
+```tsx
+import { useTheme } from '@emotion/react';
+
+const Sparkline = () => {
+  const theme = useTheme();
+  return <path strokeWidth={theme.spacing[4]} d="M0 0 L10 10" />;
+};
+```
+
+## Key principles
+
+- Prefer **semantic** color keys in `css` / `variant` / `states` so **ColorMode** and theme switches apply; see **`gamut-color-mode`**.
+- Never hardcode hex in component styles — use tokens / semantic aliases.
+- Prefer **`variant` / `states`** for modes and toggles instead of ad-hoc `theme` interpolation in template literals.
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 b61e5cc567a..cb717366c8c 100644
--- a/packages/gamut/agent-tools/skills/gamut-system-props/SKILL.md
+++ b/packages/gamut/agent-tools/skills/gamut-system-props/SKILL.md
@@ -7,7 +7,7 @@ description: Use this skill when building or refactoring styled Gamut components
 
 Source: `@codecademy/gamut-styles` — [`variance/config.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/config.ts) (definitions) and [`variance/props.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/props.ts) (`variance.create` groups). **`Box`**, **`FlexBox`**, and **`GridBox`** compose the same groups in [`packages/gamut/src/Box/props.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Box/props.ts).
 
-**See also:** [Styleguide — Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx) (semantic colors, `variant` / `states`, `StyleProps`, responsive examples) and Storybook [Responsive properties](https://gamut.codecademy.com/storybook/?path=/docs-foundations-system-responsive-properties--page).
+**See also:** [`gamut-style-utilities`](../gamut-style-utilities/SKILL.md) (`css`, `variant`, `states`, `StyleProps`). [Styleguide — Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx) (semantic colors, responsive examples) and Storybook [Responsive properties](https://gamut.codecademy.com/storybook/?path=/docs-foundations-system-responsive-properties--page).
 
 ## Overview
 
diff --git a/packages/gamut/agent-tools/skills/gamut-theming/SKILL.md b/packages/gamut/agent-tools/skills/gamut-theming/SKILL.md
index cd228bcd8b5..a94f14c241e 100644
--- a/packages/gamut/agent-tools/skills/gamut-theming/SKILL.md
+++ b/packages/gamut/agent-tools/skills/gamut-theming/SKILL.md
@@ -1,113 +1,48 @@
 ---
 name: gamut-theming
-description: Use this skill when working with GamutProvider themes, Emotion theme tokens, or behavior that differs across Core, Admin, Platform, LX Studio, and Percipio — including new themes, token access in styled components, or debugging theme-specific styles.
+description: Use this skill when choosing or extending Gamut themes (Core, Admin, Platform, LX Studio, Percipio), wiring GamutProvider and Emotion theme TypeScript augmentation, or following CreatingThemes — not for day-to-day css(), variant(), or states() patterns (see gamut-style-utilities).
 ---
 
 # Gamut Theming
 
 Source: `@codecademy/gamut-styles`
 
-## Overview
-
-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.
-
-## Available themes
-
-| Theme | Used for |
-|---|---|
-| Core | Codecademy default (public-facing products) |
-| Admin | Codecademy admin tools |
-| Platform | Codecademy learning environment / shared platform surfaces |
-| LX Studio | Learning Experience Studio |
-| Percipio | Skillsoft Percipio platform |
-
-The active theme is set at the app level via `<GamutProvider>`. Components inside receive the current theme via Emotion's context.
-
-## Accessing tokens in styled components
-
-### Via `css()` utility (recommended for static styles)
-
-```tsx
-import { css } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-
-// Static color token
-const Box = styled.div(css({ bg: 'navy-400', p: 4 }));
-
-// Semantic color alias (adapts to color mode and theme)
-const Text = styled.div(css({ color: 'primary', p: 4 }));
-```
-
-### Via `theme` prop (for dynamic styles)
+**See also:** [`gamut-style-utilities`](../gamut-style-utilities/SKILL.md) (`css`, `variant`, `states`, `StyleProps`, `useTheme` escape hatch). [`gamut-color-mode`](../gamut-color-mode/SKILL.md) (semantic color, `<ColorMode>`, `<Background>`). [`gamut-system-props`](../gamut-system-props/SKILL.md) (`system.*`, responsive `Box` props).
 
-Every Emotion styled component receives `theme` as a prop:
-
-```tsx
-import styled from '@emotion/styled';
-
-const DynamicBox = styled.div`
-  color: ${({ theme }) => theme.colors.blue};
-  font-size: ${({ theme }) => theme.fontSize[16]};
-`;
-```
-
-### Via imported `theme` object (outside styled components)
-
-```tsx
-import { css as emotionCss } from '@emotion/react';
-import { theme } from '@codecademy/gamut-styles';
-
-// For use in plain CSS-in-JS outside of styled components
-const myStyles = emotionCss`
-  font-size: ${theme.fontSize[14]};
-  color: ${theme.colors['navy-400']};
-`;
-```
-
-### Via `useTheme()` hook
-
-```tsx
-import { useTheme } from '@emotion/react';
-
-const MyComponent = () => {
-  const theme = useTheme();
-  return <div style={{ color: theme.colors.primary }} />;
-};
-```
-
-## System props as the primary token API
+## Overview
 
-For most styling needs, use **system props** (see the `gamut-system-props` skill) rather than accessing the theme directly. System props are the idiomatic way to use design tokens in Gamut components:
+Gamut uses Emotion's theme system. **Themes** are org-specific token bundles (colors, typography, spacing, etc.). The active theme is set at the app root with **`<GamutProvider theme={...}>`**; child styled components read tokens through Emotion context.
 
-```tsx
-import { variance } from '@codecademy/variance';
-import { system } from '@codecademy/gamut-styles';
+For **authoring component styles** (`css`, `variant`, `states`, system props, ColorMode), use the skills linked above and the styleguide [Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx).
 
-const Card = styled.div(
-  variance.compose(system.layout, system.space, system.color)
-);
+## Available themes
 
-// token scale values are validated at the type level
-<Card bg="navy-400" p={16} width="100%" />;
-```
+| Theme     | Used for                                                   |
+| --------- | ---------------------------------------------------------- |
+| Core      | Codecademy default                                         |
+| Admin     | Codecademy admin tools                                     |
+| Platform  | Codecademy learning environment / shared platform surfaces |
+| LX Studio | Learning Experience Studio                                 |
+| Percipio  | Skillsoft Percipio platform                                |
 
-## Theme-aware vs. color-mode-aware
+Product-level import names and `theme.d.ts` patterns live in [setup.md](../../guidelines/setup.md).
 
-| Concern | Tool |
-|---|---|
-| Tokens change per theme (colors, sizes, fonts) | Access via `theme.*` or system props |
-| Colors change per light/dark mode | Use semantic color aliases + `<ColorMode>` |
-| Background contrast | Use `<Background>` from ColorMode |
+## Theme vs color mode vs style API
 
-Semantic aliases like `primary`, `secondary`, `text`, `background` serve double duty: they resolve to theme-specific values **and** switch between light/dark variants automatically.
+| Concern                                                 | Where to read                                      |
+| ------------------------------------------------------- | -------------------------------------------------- |
+| Which `theme` object to pass to `GamutProvider`         | This skill + [setup.md](../../guidelines/setup.md) |
+| Light / dark semantic colors, `ColorMode`, `Background` | **`gamut-color-mode`**                             |
+| `css` / `variant` / `states`, `useTheme` for non-CSS JS | **`gamut-style-utilities`**                        |
+| Composed `system.*` props on styled primitives / `Box`  | **`gamut-system-props`**                           |
 
 ## Creating a new theme
 
-See `CreatingThemes.mdx` in the styleguide (`packages/styleguide/src/lib/Foundations/Theme/CreatingThemes.mdx`) for the full guide. Themes are defined in `@codecademy/gamut-styles` and must extend the base theme shape with all required token keys.
+See `CreatingThemes.mdx` in the styleguide (`packages/styleguide/src/lib/Foundations/Theme/CreatingThemes.mdx`). Themes are defined in `@codecademy/gamut-styles` and must extend the base theme shape with all required token keys.
 
 ## Key principles
 
-- Prefer semantic token aliases over raw token values when the style needs to respond to color mode changes.
-- Use raw tokens (e.g. `navy-400`) only for styles that should be fixed regardless of mode.
-- Never hardcode hex values in styled components — always go through the theme/system props.
-- The `GamutProvider` at the app root wires up the theme, color mode, and logical properties settings; components should not need to know which theme is active.
+- Pick the **correct theme export** for the product (`coreTheme`, `adminTheme`, `platformTheme`, `lxStudioTheme`, `percipioTheme`, etc.) so tokens and fonts match design intent.
+- Align **`theme.d.ts`** / `Theme extends …` with the same theme interface you pass to `GamutProvider` (see [setup.md](../../guidelines/setup.md)).
+- Components stay portable across themes when they use **token and semantic aliases** rather than one-off hex; authoring rules live in **`gamut-style-utilities`** and **`gamut-color-mode`**.
+- **`GamutProvider`** wires theme, color mode, and logical-properties settings at the root; individual components should not hard-code which org theme is active.