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

package/agent-tools/commands/gamut-review.md

@@ -0,0 +1,246 @@
+---
+description: Use this command when auditing existing code for Gamut usage — dependencies, GamutProvider, deep imports, hardcoded hex colors, and test patterns — and you need a consolidated report with pointers to the matching Gamut skills.
+argument-hint: [path]
+allowed-tools: Read Glob Grep
+---
+
+This is an audit of **existing code** at **`$ARGUMENTS`** (default: current working directory). Your job is to find violations and misuse, not to generate new code.
+
+When `DESIGN.md` is present at the audit root, use it as the authoritative reference for product design intent, token names, and component patterns. It is copied from `DESIGN.Codecademy.md`, `DESIGN.Percipio.md`, or `DESIGN.LXStudio.md` in `@codecademy/gamut` agent-tools (via `gamut plugin install --theme <name>`). When a finding maps to a skill, note it in the report so the developer knows where to get remediation guidance.
+
+Run **Check 0** first, then Checks 1–5, then print a single consolidated report using the format at the end of this file.
+
+---
+
+## Check 0 — DESIGN.md present
+
+Resolve the audit root: `$ARGUMENTS` if provided, otherwise the current working directory. Look for **`DESIGN.md`** at that root (not inside `node_modules` or package subfolders unless the audit path is explicitly that folder).
+
+| Result      | Action                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Found**   | Report `✓ DESIGN.md present (<path>)`. Proceed with Checks 1–5 using this file for product/theme context.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| **Missing** | Report `✗ DESIGN.md not found` as a **blocking** finding. Include remediation: from the repo root run `gamut plugin install cursor --theme core` (or `percipio`, `lxstudio`, `admin`, `platform`; also `claude`), or manually copy the matching `DESIGN.*.md` from `@codecademy/gamut` agent-tools and rename to `DESIGN.md`. Still run Checks 1–3 and 5. For **Check 4**, list hex violations with `palette:` / `semantic:` only where Appendix A/B apply without product YAML — prefix the Hardcoded colors section with **`⚠ low confidence — no DESIGN.md`** and **do not** assume Codecademy Core semantics; do not use Appendix B shortcuts as authoritative. |
+
+---
+
+## Check 1 — Dependencies
+
+Read `package.json` (and `package.json` in `$ARGUMENTS` if a path was given). Inspect `dependencies`, `devDependencies`, and `peerDependencies` combined.
+
+| Package                    | Expectation                                             |
+| -------------------------- | ------------------------------------------------------- |
+| `@codecademy/gamut`        | **Required** — core component library                   |
+| `@codecademy/gamut-styles` | Recommended — design tokens and theme primitives        |
+| `@codecademy/variance`     | Recommended — style-prop system used by Gamut internals |
+
+---
+
+## Check 2 — Setup
+
+Search source files (`.ts`, `.tsx`, `.js`, `.jsx`) for these symbols. Skip `node_modules`, `dist`, `.next`, `build`, `.turbo`.
+
+| Symbol          | Expectation                                                         |
+| --------------- | ------------------------------------------------------------------- |
+| `GamutProvider` | **Required** — must appear at least once (app root wrapper)         |
+| `ColorMode`     | Recommended — enables semantic light/dark theming                   |
+| `Background`    | Recommended — semantic surface color via `@codecademy/gamut-styles` |
+
+For each found symbol report the first file path where it appears.
+
+---
+
+## Check 3 — Import patterns
+
+Grep source files for any of these patterns. Each match is an error.
+
+| Pattern                         | Reason                                                                  |
+| ------------------------------- | ----------------------------------------------------------------------- |
+| `@codecademy/gamut/dist/`       | Deep dist import — bypasses public API and breaks on internal refactors |
+| `@codecademy/gamut/src/`        | Deep src import — not part of the published package                     |
+| `@codecademy/gamut-styles/src/` | Deep src import — use the package root                                  |
+| `@codecademy/variance/src/`     | Deep src import — use the package root                                  |
+
+Report each violation as `file:line`.
+
+---
+
+## Check 4 — Hardcoded colors (semantic-first)
+
+**Rule:** Inline hex literals in application UI code are violations. Remediation is **not** “replace hex with `navy-800`” — prefer **semantic ColorMode tokens** (`text`, `background`, `primary`, …) so light/dark and theme switches stay correct. Reserve **raw palette tokens** for colors that must stay fixed and for **`bg` on `<Background>`** from `@codecademy/gamut-styles` (section surfaces with content).
+
+Align findings with project docs and Storybook:
+
+- [@codecademy/gamut agent-tools `guidelines/foundations/color.md`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/agent-tools/guidelines/foundations/color.md) — decision guide and semantic tables.
+- [Foundations / ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page) — aliases per mode; `<Background>` behavior.
+- [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) — semantic colors + `css` / `variant` / `states` from `gamut-styles`.
+- Foundations / Theme stories (Core, Admin, Platform, Percipio, LX Studio) — verify hex ↔ semantic if the product is not Codecademy Core.
+
+**Theme context:** If Check 0 passed, infer product/theme from root `DESIGN.md` and `GamutProvider` / app config. If Check 0 failed, follow the low-confidence rules in Check 0 — **do not** assume Codecademy Core semantics. If `DESIGN.md` exists but theme is still unclear, add a report note to confirm against the correct theme Storybook page.
+
+**Discovery:** Grep source files (`.ts`, `.tsx`, `.js`, `.jsx`, `.css`, `.scss`, `.less`) for inline hex literals (`#RGB` or `#RRGGBB`). Comparison is case-insensitive. Skip `node_modules`, `dist`, `.next`, `build`, `.turbo` (same spirit as other checks).
+
+### Workflow (each hex match)
+
+1. **Context** — Inspect the surrounding line(s): CSS property (`color`, `background`, `border-color`, …), JSX prop (`color`, `bg`, `borderColor`, SVG fill), or asset. Note whether the subtree is a **section with content** (candidate for `<Background>` + palette `bg`) vs component chrome (prefer semantics).
+2. **Identify palette** — Normalize hex (case-insensitive); map to a Gamut palette name using **Appendix A** below. If missing from the appendix, match against `DESIGN.md` / `packages/gamut-styles` palette definitions.
+3. **Recommend semantic first** — Use **Appendix B** (Core **light** literals from `color.md`) plus role:
+   - Body / UI foreground → `text`; strong emphasis → `text-accent`.
+   - Page or card fill → `background` / `background-primary` / state surfaces (`background-success`, `background-warning`, `background-error`).
+   - CTAs, links, hyper accents → `primary` (+ `primary-hover` on hover); toggles / checkboxes → `interface`.
+   - Ghost / secondary buttons → `secondary`.
+   - Destructive → `danger` / `danger-hover`.
+   - Dividers / outlines → `border-primary` / `border-secondary` / `border-tertiary`.
+   - Inline feedback copy → `feedback-error` / `feedback-success` / `feedback-warning`.
+   - **Disambiguation:** `#FFD300` — warning copy → `feedback-warning`; yellow accent on top of primary-colored surfaces → `primary-inverse`.
+   - Same hex can map to multiple semantics (e.g. `#10162F` → `text` vs `border-primary` vs `secondary`): pick from **property + component role**.
+4. **When palette-only is OK** — **`bg` prop on `<Background>`** (`<Background bg="hyper">`, etc.) is the primary place for **fixed surface** palette colors on sections (see `color.md` decision guide + ColorMode docs). After replacing hex there, use a **named palette token**, not hex. **Exceptions** (flag with rationale): charts/data viz, third-party widgets, exported static illustrations — still prefer tokens over hex when feasible.
+
+**Severity:** Hex on adaptive UI (random wrappers, `styled-components`, inline `style`) → **error**. Hex inside documented exceptions → **warning** with note.
+
+**Reporting:** For each match outside token definition files:
+
+`file:line  'HEX'  →  semantic: <token(s)> | palette: <token> | note: <theme/disambiguation>`
+
+Use `semantic: (n/a)` only when no semantic applies (e.g. pure illustration); still give `palette: …`. If unmappable: `→  no Gamut token`.
+
+Ignore hex inside design token definition files (e.g. `variables/colors.ts`, `_colors.scss`) — source of truth, not violations.
+
+### Appendix B — Core light: hex → suggested semantic (shortcut)
+
+Use with step 3; verify for non-Core themes. Opacity variants in `color.md` are not listed here — keep using the named semantic token.
+
+| Hex (normalized) | Typical semantic direction                                                                                               |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `#10162f`        | `text`, `border-primary`, or `secondary` (by role)                                                                       |
+| `#0a0d1c`        | `text-accent`                                                                                                            |
+| `#ffffff`        | `background` (fills), `secondary` (inverse ghost on dark — rare in light-only grep context)                              |
+| `#fff0e5`        | `background-primary`                                                                                                     |
+| `#f5ffe3`        | `background-success`                                                                                                     |
+| `#fffae5`        | `background-warning`                                                                                                     |
+| `#fbf1f0`        | `background-error`                                                                                                       |
+| `#3a10e5`        | `primary`, `interface` (controls vs marketing CTA — prefer `primary` for links/buttons)                                  |
+| `#5533ff`        | `primary-hover`, `interface-hover`                                                                                       |
+| `#ffd300`        | `feedback-warning` or `primary-inverse` (see disambiguation above)                                                       |
+| `#cca900`        | Often pairs with hover in dark mode; in light UI as literal hex → check palette appendix (`yellow-400`) then assign role |
+| `#e91c11`        | `danger`                                                                                                                 |
+| `#be1809`        | `danger-hover`, `feedback-error`                                                                                         |
+| `#008a27`        | `feedback-success`                                                                                                       |
+
+Hexes with **no row above** still get **Appendix A** palette id + role-based semantic guess (e.g. blue scale → often decorative or legacy marketing; prefer design review unless mapping clearly to `primary`).
+
+### Appendix A — Hex → palette token (identification only)
+
+Case-insensitive. Use to label `palette:` in the report; **do not** stop at this step without Appendix B / role triage.
+
+| Hex       | Token                      |
+| --------- | -------------------------- |
+| `#000000` | `black`                    |
+| `#ffffff` | `white`                    |
+| `#10162f` | `navy` / `navy-800`        |
+| `#0a0d1c` | `navy-900`                 |
+| `#fff0e5` | `beige-100`                |
+| `#f5fcff` | `blue-0`                   |
+| `#d3f2ff` | `blue-100`                 |
+| `#66c4ff` | `blue-300`                 |
+| `#3388ff` | `blue-400`                 |
+| `#1557ff` | `blue-500`                 |
+| `#1d2340` | `blue-800`                 |
+| `#f5ffe3` | `green-0`                  |
+| `#eafdc6` | `green-100`                |
+| `#aee938` | `green-400` / `lightGreen` |
+| `#008a27` | `green-700`                |
+| `#151c07` | `green-900`                |
+| `#fffae5` | `yellow-0`                 |
+| `#cca900` | `yellow-400`               |
+| `#ffd300` | `yellow-500` / `yellow`    |
+| `#211b00` | `yellow-900`               |
+| `#fff5ff` | `pink-0`                   |
+| `#f966ff` | `pink-400` / `pink`        |
+| `#fbf1f0` | `red-0`                    |
+| `#e85d7f` | `red-300`                  |
+| `#dc5879` | `red-400` / `paleRed`      |
+| `#e91c11` | `red-500` / `red`          |
+| `#be1809` | `red-600`                  |
+| `#280503` | `red-900`                  |
+| `#ffe8cc` | `orange-100`               |
+| `#ff8c00` | `orange-500` / `orange`    |
+| `#5533ff` | `hyper-400`                |
+| `#3a10e5` | `hyper-500` / `hyper`      |
+| `#f5f5f5` | `gray-100`                 |
+| `#eeeeee` | `gray-200`                 |
+| `#e0e0e0` | `gray-300`                 |
+| `#9e9e9e` | `gray-600`                 |
+| `#616161` | `gray-800`                 |
+| `#424242` | `gray-900`                 |
+| `#fffbf8` | `beige-0`                  |
+| `#8a7300` | `gold-800` / `gold`        |
+| `#d14900` | `orange-800`               |
+| `#ca00d1` | `pink-800`                 |
+| `#006d82` | `teal-500` / `teal`        |
+| `#b3ccff` | `purple-300` / `purple`    |
+
+---
+
+## Check 5 — Test setup
+
+Grep test files (`**/__tests__/**/*.{ts,tsx}`, `**/*.test.{ts,tsx}`, `**/*.spec.{ts,tsx}`) for these patterns. Skip `node_modules`, `dist`.
+
+| Pattern                                               | Verdict                               | Reason                                                                                                                                                                                                                                                  |
+| ----------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `jest.mock\(.*@codecademy/gamut`                      | **Error**                             | Manual mocking bypasses theme context and produces false-positive tests; prefer **`setupRtl`** from `@codecademy/gamut-tests` (or a harness + **`setupRtl`**); use raw **`MockGamutProvider`** + **`render`** only for rare one-offs or Storybook mocks |
+| `jest.mock\(.*@codecademy/gamut-styles`               | **Error**                             | Same issue as above — mocking gamut-styles breaks token resolution                                                                                                                                                                                      |
+| `from '@codecademy/gamut-tests'`                      | Good — report count of files using it | Correct import for `setupRtl` and `MockGamutProvider`                                                                                                                                                                                                   |
+| `from 'component-test-setup'` (without gamut-tests)   | **Warning**                           | Should import `setupRtl` from `@codecademy/gamut-tests`, not directly from `component-test-setup` — the gamut-tests wrapper adds `MockGamutProvider` automatically                                                                                      |
+| `new GamutProvider` or `<GamutProvider` in test files | **Warning**                           | Prefer **`setupRtl`**; use **`MockGamutProvider`** (sets `useCache={false}`, `useGlobals={false}`) in harnesses or stories, not **`GamutProvider`** directly                                                                                            |
+
+Skill reference for remediation: `gamut-testing`
+
+---
+
+## Output format
+
+```
+Gamut Review — <absolute path>
+══════════════════════════════════════════════════
+
+DESIGN.md
+  ✓  present   <path>/DESIGN.md
+  ✗  missing   run: gamut plugin install cursor --theme <core|percipio|lxstudio|…>  [blocking for color audit]
+
+Dependencies
+  ✓  @codecademy/gamut            <version>
+  ⚠  @codecademy/gamut-styles     not found — recommended
+  ✗  @codecademy/variance         not found — recommended
+
+Setup
+  ✓  GamutProvider   found (src/App.tsx)
+  ⚠  ColorMode       not found — use ColorMode for light/dark theming  [→ gamut-color-mode]
+  ⚠  Background      not found — use <Background> for semantic surfaces  [→ gamut-color-mode]
+
+Import patterns
+  ✓  Deep dist imports         none found
+  ✗  Deep src imports          2 occurrences
+       src/Thing.tsx:7
+       src/Other.tsx:12
+
+Hardcoded colors                                                         [→ gamut-color-mode]
+  ✗  src/Card.tsx:22   '#10162F'  →  semantic: text | palette: navy-800 | note: Core light body copy
+  ⚠  src/Hero.tsx:14   '#1557FF'  →  semantic: primary (if link/CTA) | palette: blue-500 | note: no exact semantic; confirm theme
+  ⚠  src/Nav.tsx:8     '#BADA55'  →  semantic: (n/a) | palette: — | note: no Gamut token
+
+Test setup                                                               [→ gamut-testing]
+  ✓  @codecademy/gamut-tests   used in 12 test files
+  ✗  jest.mock(@codecademy/gamut)   2 occurrences — remove; prefer setupRtl (or harness + setupRtl)
+       src/components/Foo/__tests__/Foo.test.tsx:3
+       src/components/Bar/__tests__/Bar.test.tsx:5
+  ⚠  direct component-test-setup import   1 occurrence — import from @codecademy/gamut-tests
+       src/components/Baz/__tests__/Baz.test.tsx:2
+
+══════════════════════════════════════════════════
+<N> error(s), <N> warning(s) found.   (or "All checks passed." if none)
+```
+
+Icons: `✓` = pass, `⚠` = warning (recommended, not required), `✗` = error (required).
+`[→ skill-name]` annotations indicate which Gamut skill has remediation guidance for that category.
+
+After printing the report, offer one sentence of prioritized next-step advice based on what was found.

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-style-utilities` skill](../../skills/gamut-style-utilities/SKILL.md) · [`gamut-color-mode` skill](../../skills/gamut-color-mode/SKILL.md) · [`modes.md`](modes.md) (`<ColorMode>`, `<Background>`)
+
+Percipio, LX Studio, Admin, and Platform override subsets of semantic mappings while keeping the shared alias API — see theme sources below before hardcoding palette names or hex.
+
+## Semantic aliases (theme-stable names)
+
+These tokens describe **roles**. Actual colors come from the active theme + ColorMode.
+
+### Text
+
+| Token            | Use for                     | Notes                      |
+| ---------------- | --------------------------- | -------------------------- |
+| `text`           | Default body and UI text    |                            |
+| `text-accent`    | Stronger emphasis text      |                            |
+| `text-secondary` | Supporting / secondary copy | Often opacity on base text |
+| `text-disabled`  | Disabled state labels       |                            |
+
+### Background
+
+| Token                 | Use for                           | Notes                     |
+| --------------------- | --------------------------------- | ------------------------- |
+| `background`          | Default page/component background |                           |
+| `background-primary`  | Slightly elevated surfaces        |                           |
+| `background-contrast` | Maximum contrast surface          |                           |
+| `background-selected` | Selected row / item               | Often low-opacity overlay |
+| `background-hover`    | Hover state overlay               |                           |
+| `background-disabled` | Disabled surface                  |                           |
+| `background-success`  | Success state container           |                           |
+| `background-warning`  | Warning state container           |                           |
+| `background-error`    | Error state container             |                           |
+
+### Interactive
+
+| Token             | Use for                                   | Notes                        |
+| ----------------- | ----------------------------------------- | ---------------------------- |
+| `primary`         | Primary CTA, links, focus accents         | Pairs with `primary-hover`   |
+| `primary-hover`   | Hover on primary interactive              |                              |
+| `primary-inverse` | Accent on top of primary-colored surfaces |                              |
+| `secondary`       | Secondary CTA, ghost buttons              | Pairs with `secondary-hover` |
+| `secondary-hover` | Hover on secondary interactive            |                              |
+| `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.