@codecademy/gamut 68.6.1-alpha.e6c390.0 → 68.6.1-alpha.f6b2ce.0

package/agent-tools/guidelines/foundations/color.md

@@ -1,86 +1,168 @@
 # 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-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.
+
+## 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            |                              |
+| `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% |
+| `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)
 ```

package/agent-tools/guidelines/foundations/modes.md

@@ -1,24 +1,43 @@
 # Color Modes
 
-Gamut uses **semantic color aliases** so components adapt to light/dark mode without configuration. See [color.md](color.md) for the full alias reference.
+Gamut uses semantic color aliases so components adapt to light/dark mode without configuration. See [color.md](color.md) for the full alias reference and decision guide.
 
-## `<ColorMode>`
+Product tokens: Semantic mappings vary by theme. Confirm aliases and palette keys against root `DESIGN.md` and the active theme Storybook page — do not assume Codecademy Core values in Percipio, LX Studio, or other products.
+
+Deep reference: [`skills/gamut-color-mode/SKILL.md`](../../skills/gamut-color-mode/SKILL.md) · Storybook [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page)
+
+## When to use the color mode system
+
+For any dark or light region — sidebars, footers, hero bands, callouts, panels, whole-app dark mode — use `ColorMode` or `Background` from `@codecademy/gamut-styles`. Do not handle these with custom CSS, hardcoded `rgba`, or manual color swaps.
+
+| Component    | Use when                                                                                        |
+| ------------ | ----------------------------------------------------------------------------------------------- |
+| `ColorMode`  | You know the mode (`light`, `dark`, or `system` for OS preference).                             |
+| `Background` | Background color is a palette token and Gamut should pick the best contrast mode automatically. |
 
-Wraps a subtree in an explicit color mode. Nest to create scoped mode regions.
+## Rules
+
+1. Never override Gamut colors with custom CSS when a `ColorMode` or `Background` wrapper achieves the same result via tokens.
+2. Prefer `ColorMode` over `Background` when the intended mode is known (e.g. sidebar always dark). Use `Background` when the surface color is fixed and mode should adapt.
+3. `ColorMode` has no `as` prop — nest semantic elements inside (`<nav>`, `<aside>`, `<footer>`).
+4. System props work on `ColorMode` — `p`, `m`, `width`, `position`, etc. without extra wrappers.
+5. `mode="system"` follows OS `prefers-color-scheme`. For in-app theme toggles, pass `mode="light"` or `mode="dark"` from your own state.
+
+## `<ColorMode>`
 
 ```tsx
 import { ColorMode } from '@codecademy/gamut-styles';
 
-<ColorMode mode="light">{children}</ColorMode>   // force light
-<ColorMode mode="dark">{children}</ColorMode>    // force dark
-<ColorMode mode="system">{children}</ColorMode>  // follows OS preference
+<ColorMode mode="light">{children}</ColorMode>
+<ColorMode mode="dark">{children}</ColorMode>
+<ColorMode mode="system">{children}</ColorMode>
 ```
 
-**Props**: `mode="light" | "dark" | "system"`
+Props: `mode="light" | "dark" | "system"`
 
 ## `<Background>`
 
-Use `<Background>` — not a raw `bg` prop — whenever setting a colored background on a section that contains text or interactive elements. It automatically switches the color mode inside to maintain accessible contrast.
+Use `<Background>` — not a raw `bg` on layout — for colored sections with text or interactive children. Pass a palette token to `bg` (e.g. `hyper`, `navy`), not a semantic alias.
 
 ```tsx
 import { Background } from '@codecademy/gamut-styles';
@@ -30,18 +49,21 @@ Nesting is supported — each `<Background>` creates its own accessible color co
 
 ## Hooks
 
-| Hook                   | Returns                                                 | Use                                               |
-| ---------------------- | ------------------------------------------------------- | ------------------------------------------------- |
-| `useCurrentMode()`     | `"light" \| "dark"`                                     | Active mode key only                              |
-| `useColorModes()`      | `[modeKey, currentModeColors, allModes, getColorValue]` | Full mode data + resolver for semantic color keys |
-| `usePrefersDarkMode()` | `boolean`                                               | OS `prefers-color-scheme: dark` only              |
+| Hook                   | Returns                               | Use                                                        |
+| ---------------------- | ------------------------------------- | ---------------------------------------------------------- |
+| `useCurrentMode()`     | `"light" \| "dark"`                   | Active mode key only                                       |
+| `useColorModes()`      | mode key, colors, all modes, resolver | Full mode data + `getColorValue`                           |
+| `usePrefersDarkMode()` | `boolean`                             | OS dark preference (prefer `mode="system"` on `ColorMode`) |
 
 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)
+## Example (Core theme)
+
+Core light/dark semantic mappings are documented in Storybook [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page). Other themes remap the same alias names to different palette values — verify in `DESIGN.md` and the product theme story before hardcoding palette fallbacks.
+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.
-- Do not use a raw `bg` prop on colored sections containing content — use `<Background>` so contrast is guaranteed.
-- Do not manually toggle modes from `usePrefersDarkMode()` — use `<ColorMode mode="system">` instead.
+- Do not use raw palette tokens (`navy-400`, `white`) for text/backgrounds that must adapt across modes — use semantic aliases.
+- Do not use a raw `bg` prop on colored sections with content — use `<Background>`.
+- Do not wire `usePrefersDarkMode()` into `ColorMode` when `mode="system"` suffices.

package/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
 

package/agent-tools/guidelines/foundations/typography.md

@@ -1,50 +1,82 @@
 # 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)
+
+## 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-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`.

package/agent-tools/guidelines/overview-icons.md

@@ -0,0 +1,19 @@
+# Icons
+
+Icons must come from `@codecademy/gamut-icons`. Do not import or generate icons from other sources. If a needed icon is unavailable, pick a verified alternative from the library or flag for confirmation — do not substitute non-system assets.
+
+## Identifying the correct icon
+
+Do not rely on Figma layer names (`data-name`). Layer names are often stale after icon swaps.
+
+Determine the correct icon by:
+
+1. Reading the design image — visually identify the shape (three vertical dots → kebab menu, 3×3 grid → app switcher, etc.).
+2. Using contextual clues — tooltip text, element purpose, surrounding UI patterns.
+3. Cross-referencing exports — search `@codecademy/gamut-icons` for icons matching visual and semantic intent.
+4. Treating layer names as hints only — if a layer name conflicts with visual/contextual evidence, trust the evidence.
+5. When uncertain, flag for confirmation rather than guessing.
+
+Before using any icon, confirm it exists in `@codecademy/gamut-icons` (`packages/gamut-icons/src` or package exports).
+
+Storybook: [Foundations / Icons](https://gamut.codecademy.com/?path=/docs-foundations-icons--page)

package/agent-tools/guidelines/overview-illustrations.md

@@ -0,0 +1,7 @@
+# Illustrations
+
+Illustrations must come from `@codecademy/gamut-illustrations`. Do not generate or import illustrations from other sources.
+
+If the correct illustration is unavailable, flag for confirmation rather than substituting a non-system asset.
+
+Storybook: [Illustrations](https://gamut.codecademy.com/?path=/docs-illustrations--page) · `packages/gamut-illustrations/src` exports.

package/agent-tools/guidelines/overview-patterns.md

@@ -0,0 +1,7 @@
+# Patterns
+
+Patterns must come from `@codecademy/gamut-patterns`. Match Figma component names to pattern exports when possible.
+
+If the correct pattern is unavailable, flag for confirmation rather than substituting a non-system asset.
+
+Storybook: browse pattern stories under the Gamut styleguide, or inspect `packages/gamut-patterns/src` exports.