@codecademy/gamut 68.6.1-alpha.c211a2.0 → 68.6.1-alpha.df4bce.0

package/agent-tools/guidelines/components/buttons.md

@@ -0,0 +1,91 @@
+# Buttons
+
+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.
+
+**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
+
+`small` | `normal` (default) | `large`
+
+## Key props
+
+| Prop           | Type                                                  | Effect                                           |
+| -------------- | ----------------------------------------------------- | ------------------------------------------------ |
+| `variant`      | `"primary" \| "secondary" \| "danger" \| "interface"` | Color emphasis (see table above)                 |
+| `size`         | `"small" \| "normal" \| "large"`                      | Padding and font size                            |
+| `icon`         | Icon component                                        | Leading or trailing icon (Fill, Stroke, Text)    |
+| `iconPosition` | `"left" \| "right"`                                   | Defaults to left                                 |
+| `disabled`     | boolean                                               | Disabled state styling                           |
+| `href`         | string                                                | Renders as `<a>` tag                             |
+| `tip`          | string                                                | Required on `IconButton` (tooltip + hover label) |
+
+## States
+
+Hover, active, and disabled colors are handled by the component. Do not override state colors with `color` / `bg` props.
+
+## Accessibility — `disabled` vs `aria-disabled`
+
+| Situation                                                           | Use                                                    | Why                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Button should not be activatable (default)                          | `disabled` prop                                        | Renders native `disabled` on `<button>`; removed from tab order; correct for most forms and actions                                                                                                                                                     |
+| Disabled button **with a tooltip** that must stay readable on focus | `aria-disabled` only — **do not** also pass `disabled` | Native `disabled` blocks keyboard focus, so the tooltip cannot be reached. Gamut disabled **styles** also match `[aria-disabled='true']`. See [ToolTip — With a disabled Button](https://gamut.codecademy.com/?path=/docs-molecules-tips-tooltip--docs) |
+
+```tsx
+// Default — not interactive
+<FillButton disabled>Submit</FillButton>
+
+// Disabled but focusable (e.g. wrapped in ToolTip explaining why)
+<ToolTip id="why-disabled" info="Complete the lesson first">
+  <FillButton aria-describedby="why-disabled" aria-disabled>
+    Submit
+  </FillButton>
+</ToolTip>
+```
+
+- **`href` + `disabled`:** `ButtonBase` (internal) drops `href` and renders a `<button disabled>` — link-style buttons cannot stay anchors while disabled.
+- **`IconButton`:** provide an accessible name via `tip` (used as `aria-label` when `aria-label` is omitted). See ToolTip / IconButton Storybook pages.
+- **`ButtonBase` is not exported** from `@codecademy/gamut` (only the `ButtonBaseElements` type is). Prefer stock atoms; custom button styling belongs in Gamut itself or via `css` / `variant` from `gamut-styles`, not by importing `ButtonBase`.
+
+## Rules
+
+- Use `FillButton` for primary actions and `StrokeButton` for secondary — do not use both at equal weight on the same screen.
+- Reserve `CTAButton` for marketing / high-visibility promotions; do not use it for standard UI actions.
+- Avoid placing buttons in the wrong color-mode context (e.g. light-mode buttons on a navy band without `<Background>`). See [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`.

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

@@ -0,0 +1,52 @@
+# Components
+
+52 components have Figma ↔ code mappings via Figma Code Connect (`packages/code-connect/`). Live code snippets appear in Figma's inspect panel when you select a component.
+
+## Atoms — foundational, single-purpose
+
+Badge, Button (FillButton, StrokeButton, CTAButton, TextButton, IconButton), ButtonBase, Card, Checkbox, CodeBlock, ColorMode, Drawer, FlexBox, FormGroup, GridBox, HiddenText, Icon, Input, Label, Loader, Radio, Select, Spinner, Tag, TextArea, Toggle, Tooltip
+
+## Molecules — composed of atoms
+
+Alert, Anchor, Breadcrumbs, Coachmark, Disclosure, GridForm, Markdown, Menu, Modal, Pagination, Popover, ProgressBar, Table, Tabs, Toast, Toaster, Video
+
+## Organisms — page-level compositions
+
+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`     |
+| 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 |

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

@@ -0,0 +1,172 @@
+# Color
+
+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.
+
+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      |
+| ---------------- | ------------ | --------- |
+| `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      |
+| --------------------- | ------------ | --------- |
+| `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      |
+| ----------------- | ------------ | --------- |
+| `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      |
+| ------------------ | ------------ | --------- |
+| `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      |
+| ------------------ | --------- | --------- |
+| `feedback-error`   | `#BE1809` | `#E85D7F` |
+| `feedback-success` | `#008A27` | `#AEE938` |
+| `feedback-warning` | `#FFD300` | `#FFFAE5` |
+
+## Raw palette (Core-centric reference)
+
+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.
+
+For Codecademy Core defaults:
+
+| 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 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?
+  └─ 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

@@ -0,0 +1,47 @@
+# 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.
+
+## `<ColorMode>`
+
+Wraps a subtree in an explicit color mode. Nest to create scoped mode regions.
+
+```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
+```
+
+**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.
+
+```tsx
+import { Background } from '@codecademy/gamut-styles';
+
+<Background bg="hyper">{children}</Background>;
+```
+
+Nesting is supported — each `<Background>` creates its own accessible color context.
+
+## Hooks
+
+| 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.
+- 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.

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

@@ -0,0 +1,107 @@
+# 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  |
+
+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  |
+
+## 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            |
+
+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**
+
+- **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.
+
+## Page layout grid (12 columns)
+
+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  |
+
+Minimum touch target on mobile: **44×44px** — see `gamut-accessibility` skill for hit-target guidance.
+
+## Responsive rules
+
+- Begin design work at 1440px (XL), then adapt down.
+- Multi-column layouts collapse to fewer columns — do not stretch or squish.
+- Catalog cards and non-lockup elements should align on one axis (usually left), not fill column widths.
+- Avoid dense or small components at the base (mobile) breakpoint.

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

@@ -0,0 +1,83 @@
+# Typography
+
+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)).
+
+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).
+
+**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
+
+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              |
+
+## 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)
+
+| Context            | Target              |
+| ------------------ | ------------------- |
+| Single-column body | ~66 chars (max ~85) |
+| Multi-column       | ≤50 chars per line  |
+| Minimum            | ~45 chars           |
+
+## 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.

package/agent-tools/guidelines/overview.md

@@ -0,0 +1,40 @@
+# Gamut Design System
+
+Gamut is the Codecademy / Skillsoft design system — React component library (`@codecademy/gamut`), design tokens (`@codecademy/gamut-styles`), and Figma components with live code previews via Figma Code Connect.
+
+**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, accessible UI
+- All components work across all themes without modification
+- 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`).
+
+## Themes
+
+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={...}>`.
+
+## 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) | 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                                          |