@codecademy/gamut 68.6.1-alpha.f6b2ce.0 → 68.6.2-alpha.1fc7ca.0

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

@@ -1,259 +0,0 @@
----
-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.
-
-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–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. |
-
----
-
-## 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/animations.md

@@ -1,74 +0,0 @@
-# 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,95 +0,0 @@
-# Buttons
-
-There is no generic `Button` export from `@codecademy/gamut`. Never import `Button` — use the specific variant that matches the design.
-
-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
-
-- 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

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

@@ -1,21 +0,0 @@
-# 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>;
-```

package/agent-tools/guidelines/components/data-table.md

@@ -1,79 +0,0 @@
-# DataTable & DataList sorting
-
-`DataTable` and `DataList` do not sort data automatically. `sortable: true` on a column only renders sort UI. You must implement sorting via `query` and `onQueryChange`, and pass pre-sorted `rows`.
-
-## How sorting works
-
-1. `sortable: true` — enables sort toggle on the column header. Without `query` / `onQueryChange`, clicks do nothing.
-2. `query` — `Query<Row>` holding current sort (and filter) state. `sort` maps column keys to `'asc' | 'desc'`.
-3. `onQueryChange` — receives `QueryChangeEvent<Row>` when the user clicks a sortable header. Update `query` in your handler.
-4. Sorted rows — sort the `rows` array yourself from `query.sort` before passing to the component.
-
-## Required pattern
-
-```tsx
-import { useMemo, useReducer } from 'react';
-import { DataTable } from '@codecademy/gamut';
-import type { Query, QueryChangeEvent } from '@codecademy/gamut';
-
-function queryReducer<Row>(
-  state: Query<Row>,
-  event: QueryChangeEvent<Row>
-): Query<Row> {
-  switch (event.type) {
-    case 'sort': {
-      const { dimension, value } = event.payload;
-      if (value === 'none') {
-        const { [dimension]: _, ...rest } = state.sort ?? {};
-        return { ...state, sort: rest };
-      }
-      return { ...state, sort: { [dimension]: value } };
-    }
-    case 'filter': {
-      const { dimension, value } = event.payload;
-      return { ...state, filter: { ...state.filter, [dimension]: value } };
-    }
-    case 'reset':
-      return {};
-    default:
-      return state;
-  }
-}
-
-const [query, onQueryChange] = useReducer(queryReducer, {});
-
-const sortedRows = useMemo(() => {
-  const sorted = [...rows];
-  const sortEntries = Object.entries(query.sort ?? {});
-  if (sortEntries.length > 0) {
-    const [key, direction] = sortEntries[0];
-    sorted.sort((a, b) => {
-      const aVal = String(a[key]).toLowerCase();
-      const bVal = String(b[key]).toLowerCase();
-      if (aVal < bVal) return direction === 'asc' ? -1 : 1;
-      if (aVal > bVal) return direction === 'asc' ? 1 : -1;
-      return 0;
-    });
-  }
-  return sorted;
-}, [query.sort, rows]);
-
-<DataTable
-  id="my-table"
-  idKey="id"
-  rows={sortedRows}
-  columns={columns}
-  query={query}
-  onQueryChange={onQueryChange}
-/>;
-```
-
-## Rules
-
-1. Never use `sortable: true` without `query` and `onQueryChange`.
-2. Always sort rows client-side (or server-side before passing) from `query.sort`.
-3. Handle `'sort'`, `'filter'`, and `'reset'` in the reducer even if you only use sorting.
-4. One active sort column in standard usage — replace the previous sort entry when the user picks a new column.
-5. Import `Query` and `QueryChangeEvent` from `@codecademy/gamut` for type safety.
-
-Storybook: [Organisms / DataTable](https://gamut.codecademy.com/?path=/docs-organisms-datatable--docs)