@codecademy/gamut 68.6.1-alpha.c211a2.0 → 68.6.1-alpha.d52035.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,44 @@
+# 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.
+
+### 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,66 @@
+# Spacing, Border Radius & Layout
+
+## 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 |
+
+Container query variants (`c_xs`–`c_xl`) mirror these values but trigger on component width.
+
+## Grid
+
+12-column grid at all breakpoints.
+
+| 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**.
+
+## 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,50 @@
+# Typography
+
+## Typefaces
+
+| 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 |
+
+Percipio overrides all families to Roboto. Apercu is licensed for codecademy.com only.
+
+## 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 |
+
+## Line height
+
+| Token | Value | Use |
+|---|---|---|
+| `base` | 1.5 | Body text |
+| `spacedTitle` | 1.3 | Sub-headlines, medium titles |
+| `title` | 1.2 | Large headlines |
+
+Target 45–85 characters per line (66 ideal for web body text).
+
+## Rules
+
+- 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.

package/agent-tools/guidelines/overview.md

@@ -0,0 +1,38 @@
+# 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 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         | —         |
+
+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                                   |

package/agent-tools/guidelines/setup.md

@@ -0,0 +1,42 @@
+# Setup
+
+## Install
+
+```sh
+npm install @codecademy/gamut-kit
+```
+
+`gamut-kit` bundles `gamut`, `gamut-icons`, `gamut-illustrations`, `gamut-patterns`, `gamut-styles`, `variance`, and `gamut-tests`.
+
+## Required wrapper
+
+Wrap the app root in `<GamutProvider>`. This wires up the theme, color mode, and logical properties for all child components.
+
+```tsx
+import { GamutProvider } from '@codecademy/gamut';
+import { theme } from '@codecademy/gamut-styles';
+
+const App = () => (
+  <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` |
+
+All themes are exported from `@codecademy/gamut-styles`.
+
+## 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

package/agent-tools/rules/accessibility.mdc

@@ -0,0 +1,68 @@
+---
+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']
+---
+
+# Gamut Accessibility Rules
+
+## 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
+
+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>
+
+<!-- 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>
+```
+
+## Use Gamut components — don't reimplement what they already solve
+
+- `<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.
+
+## 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
+
+## 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.
+
+## Screen-reader-only text
+
+Use `<Text screenreader>` for visually hidden but announced content. `<HiddenText>` is deprecated.
+
+## 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`.
+
+## 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.