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

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

@@ -1,14 +1,39 @@
 ---
-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.
+description: Audit Gamut usage before shipping — DESIGN.md, dependencies, GamutProvider, imports, hex colors, tests, and pre-ship design guardrails — with a consolidated report and skill pointers.
 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.
+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.
 
-Use `DESIGN.md` at the project root as the authoritative reference for the product's design intent, token names, and component patterns. This file is distributed as `DESIGN.Codecademy.md` or `DESIGN.Percipio.md` from the `@codecademy/gamut` agent-tools package and renamed to `DESIGN.md` by the consuming project. When a finding maps to a skill, note it in the report so the developer knows where to get remediation guidance.
+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 all five checks below, then print a single consolidated report using the format at the end of this file.
+Run Check 0 first, then Checks 1–6, then print a single consolidated report using the format at the end of this file.
+
+Before reporting: Read [`guidelines/validation-checklist.md`](../guidelines/validation-checklist.md) and any [`guidelines/components/`](../guidelines/components/) guides relevant to findings (e.g. `data-table.md`, `menu.md`, `forms.md`).
+
+---
+
+## How to run
+
+| Step           | Guidance                                                                                                                                                                                                                        |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Install plugin | Cursor: `gamut plugin install` (or `gamut plugin install cursor`) from `@codecademy/gamut`. Claude Code: `gamut plugin install claude`. Use `--theme core`, `percipio`, or `lxstudio` to copy `DESIGN.md` to the app repo root. |
+| When           | Before marking Gamut UI work final, before large PRs, when onboarding a codebase                                                                                                                                                |
+| Where          | App repo root (directory containing `DESIGN.md`), or pass a subpath: `/gamut-review packages/web`                                                                                                                               |
+| In editor      | Slash command `/gamut-review` (Cursor and Claude Code after plugin install; Claude may need `/reload-plugins` once)                                                                                                             |
+| Severity       | Errors (`✗`) are blocking — fix before ship. Warnings (`⚠`) are recommended follow-ups.                                                                                                                                         |
+
+---
+
+## 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–6 using this file for product/theme context. Infer product (Codecademy, Percipio, LX Studio) from `DESIGN.md` content for Check 6 theme-specific manual items.                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| 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. |
 
 ---
 
@@ -16,11 +41,11 @@ Run all five checks below, then print a single consolidated report using the for
 
 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 |
+| 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 |
 
 ---
 
@@ -28,11 +53,11 @@ Read `package.json` (and `package.json` in `$ARGUMENTS` if a path was given). In
 
 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` |
+| 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.
 
@@ -42,89 +67,147 @@ For each found symbol report the first file path where it appears.
 
 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 |
+| 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
-
-Grep source files (`.ts`, `.tsx`, `.js`, `.jsx`, `.css`, `.scss`, `.less`) for inline hex color literals (`#RGB` or `#RRGGBB`). For each match, suggest the Gamut token name using this table (case-insensitive comparison):
-
-| 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` |
+## 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` |
-
-Ignore hex values inside design token definition files themselves (e.g. `variables/colors.ts`, `_colors.scss`) — those are the source of truth, not violations.
-
-For each match outside token files report: `file:line  'HEX'  →  token` (or `→  no Gamut token` if unknown).
+| `#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`.
+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; use `setupRtl` or `MockGamutProvider` instead |
-| `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** | Tests should use `MockGamutProvider` (sets `useCache={false}`, `useGlobals={false}`), not `GamutProvider` directly |
+| 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`
-
----
+## Skill reference for remediation: `gamut-testing`
 
 ## Output format
 
@@ -132,6 +215,10 @@ Skill reference for remediation: `gamut-testing`
 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
@@ -149,17 +236,19 @@ Import patterns
        src/Other.tsx:12
 
 Hardcoded colors                                                         [→ gamut-color-mode]
-  ⚠  src/Hero.tsx:14  '#1557FF'  →  blue-500
-  ⚠  src/Nav.tsx:8   '#BADA55'  →  no Gamut token
+  ✗  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 and use setupRtl instead
+  ✗  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)
 ```

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

@@ -0,0 +1,74 @@
+# Animations
+
+`Animation` is a namespace of controlled containers from `@codecademy/gamut` — one primitive per pattern. Use these instead of raw CSS keyframes, inline `transition`, or third-party motion libraries when a Gamut primitive covers the case.
+
+Storybook: [Atoms / Animation](https://gamut.codecademy.com/?path=/docs-atoms-animation--docs)
+
+## Cross-cutting rule: animations contain content, not click targets
+
+Never put `onClick` on the animation container. The action element (`FillButton`, `StrokeButton`, etc.) wraps the animation; the primitive wraps the visual content that animates.
+
+```tsx
+// Wrong
+<Rotation onClick={handleClick}>
+  <MiniChevronDownIcon />
+</Rotation>
+
+// Right
+<StrokeButton onClick={handleClick}>
+  <Rotation>
+    <MiniChevronDownIcon />
+  </Rotation>
+</StrokeButton>
+```
+
+## Primitives
+
+### `Rotation`
+
+Rotates children — common for expand/collapse chevrons.
+
+Props: `rotated`, `degrees` (default `180`), `height`, `width`, `aria-hidden`, `children`
+
+```tsx
+<StrokeButton onClick={toggleExpanded}>
+  <Rotation rotated={isExpanded}>
+    <MiniChevronDownIcon />
+  </Rotation>
+</StrokeButton>
+```
+
+### `ExpandInCollapseOut`
+
+Expand/collapse via Framer Motion. Required: wrap in `<AnimatePresence>` and conditionally render.
+
+```tsx
+import { AnimatePresence } from 'framer-motion';
+
+<AnimatePresence>
+  {isExpanded && <ExpandInCollapseOut>{/* content */}</ExpandInCollapseOut>}
+</AnimatePresence>;
+```
+
+### `FadeInSlideOut`
+
+Fade in / slide out via Framer Motion. Required: `<AnimatePresence>` + conditional mount — toggling CSS does not trigger the animation.
+
+```tsx
+<AnimatePresence>
+  {isVisible && (
+    <FadeInSlideOut>
+      <Box border={1} p={8}>
+        {/* content */}
+      </Box>
+    </FadeInSlideOut>
+  )}
+</AnimatePresence>
+```
+
+## Rules
+
+1. Prefer Gamut animation primitives over raw keyframes or ad-hoc motion libraries.
+2. Never put click handlers on animation containers.
+3. Enter/exit: `AnimatePresence` + conditional render — not CSS show/hide.
+4. Import `AnimatePresence` from `framer-motion` (peer dependency via Gamut).

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

@@ -1,15 +1,45 @@
 # Buttons
 
-## Variants
+There is no generic `Button` export from `@codecademy/gamut`. Never import `Button` — use the specific variant that matches the design.
 
-| Component | Use for | Background | Text |
-|---|---|---|---|
-| `FillButton` | Primary CTA, high-emphasis actions | `primary` | `white` |
-| `StrokeButton` | Secondary actions, outlined style | transparent | `secondary` |
-| `CTAButton` | High-visibility marketing promotions | `primary` | `white` |
-| `CTAButton` (inverse) | CTA on a colored surface | `primary-inverse` | `secondary` |
-| `TextButton` | Low-emphasis, inline text actions | transparent | `primary` |
-| `IconButton` | Compact icon-only actions | — | — |
+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
 
@@ -17,28 +47,49 @@
 
 ## Key props
 
-| Prop | Type | Effect |
-|---|---|---|
-| `size` | `"small" \| "normal" \| "large"` | Controls padding and font size |
-| `icon` | Icon component | Leading or trailing icon |
-| `iconPosition` | `"left" \| "right"` | Defaults to left |
-| `disabled` | boolean | Disabled state styling |
-| `href` | string | Renders as `<a>` tag |
+| 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
 
-`default` → `hover` (`primary-hover` / `secondary-hover`) → `active` → `disabled` (`text-disabled` + `background-disabled`)
+Hover, active, and disabled colors are handled by the component. Do not override state colors with `color` / `bg` props.
 
-## Token cheatsheet
+## 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>
 ```
-FillButton   → bg: primary (#3A10E5 light / #FFD300 dark),  color: white,     hover: primary-hover
-StrokeButton → bg: transparent, border: secondary (#10162F / #fff), hover: secondary-hover
-TextButton   → bg: transparent, color: primary, hover: primary-hover
-```
+
+- `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.
+- Never set the `mode` prop on buttons — they inherit color context from parent `ColorMode` / `<Background>` wrappers.
+- Match variant to design intent: filled → `FillButton`, outlined → `StrokeButton`, text-only → `TextButton`, icon-only → `IconButton` (with `tip`).
+- 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/card.md

@@ -0,0 +1,19 @@
+# Card
+
+`Card` accepts specific `variant` values that map to internal color tokens via `polished`'s parser. Invalid variants (e.g. `"navy-on-white"` instead of `"white"`) cause a runtime crash in `parseToHsl()`.
+
+Storybook: [Atoms / Card](https://gamut.codecademy.com/?path=/docs-atoms-card--docs)
+
+## Valid `Card` variants
+
+`"default"`, `"white"`, `"yellow"`, `"hyper"`, `"navy"`
+
+Never guess or invent compound variant names. Inspect TypeScript definitions in `@codecademy/gamut` if unsure.
+
+## Defaults and props
+
+1. Default `shadow` to `"none"` unless the design explicitly calls for elevation.
+2. Pass `isInteractive` when the card is wrapped in `<Anchor>` or acts as a clickable surface — enables hover shadow and `borderRadius: md`.
+3. Default `borderRadius` is `none` — override with the `borderRadius` prop when the design specifies rounding.
+
+Confirm semantic surface colors against root `DESIGN.md` and the active theme Storybook page — variants are palette-backed, not arbitrary hex.

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

@@ -0,0 +1,21 @@
+# Coachmark
+
+Storybook: [Molecules / Coachmark](https://gamut.codecademy.com/?path=/docs-molecules-coachmark--docs)
+
+## Popovers: `outline` and `CheckerDense` by default
+
+Pass `outline: true` and `pattern: CheckerDense` (from `@codecademy/gamut-patterns`) via `popoverProps` unless explicitly overridden.
+
+```tsx
+import { Coachmark } from '@codecademy/gamut';
+import { CheckerDense } from '@codecademy/gamut-patterns';
+
+<Coachmark
+  popoverProps={{
+    outline: true,
+    pattern: CheckerDense,
+  }}
+>
+  {/* ... */}
+</Coachmark>;
+```