@codecademy/gamut 68.5.2-alpha.f0a056.0 → 68.6.1-alpha.edab62.0

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,86 @@
+# 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.
+
+## Semantic aliases
+
+### 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 |
+
+### 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 |
+
+### 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 |
+
+### 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 |
+
+### 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 |
+
+## Raw palette
+
+Use raw tokens only when color must be **fixed** (not adaptive).
+
+| 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` |
+
+Named shorthand aliases: `beige`, `blue`, `green`, `hyper`, `navy`, `orange`, `pink`, `red`, `yellow`, `black`, `white`
+
+## Decision guide
+
+```
+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)
+```

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

@@ -0,0 +1,45 @@
+# 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"` | Read active mode in JS |
+| `useColorMode()` | `[modeKey, modeColors, allModes]` | Access all mode data |
+| `usePrefersDarkMode()` | `boolean` | Read OS dark preference only |
+
+Import from `@codecademy/gamut-styles`.
+
+## 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,35 @@
+# 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
+
+## 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 aliases, raw palette, decision guide |
+| [foundations/modes.md](foundations/modes.md) | Light/dark ColorMode, Background component |
+| [foundations/typography.md](foundations/typography.md) | Typefaces, font scale, rules |
+| [foundations/spacing.md](foundations/spacing.md) | Spacing, border radius, responsive grid |
+| [components/overview.md](components/overview.md) | Full component catalog |
+| [components/buttons.md](components/buttons.md) | Button variants, props, decision tree |

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,69 @@
+---
+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. 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.