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

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

@@ -1,107 +0,0 @@
-# Spacing, Border Radius & Layout
-
-Token values match [`packages/gamut-styles/src/variables`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/variables) (`spacing.ts`, `borderRadii.ts`, `responsive.ts`). Breakpoints and max-content widths align with Storybook [Foundations / Layout](https://gamut.codecademy.com/?path=/docs-foundations-layout--docs).
-
-In code — use system props for spacing: Gamut layout primitives (`Box`, `FlexBox`, `GridBox`, …) expose margin, padding, and gap props backed by `system.space` from `@codecademy/gamut-styles`. Pass spacing scale numbers (`4`, `8`, `16`, …), not raw pixel strings. For custom `styled` components, compose `system.space` (see [`gamut-system-props` skill](../../skills/gamut-system-props/SKILL.md)). [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) shows responsive `Box` examples.
-
-Responsive behavior: All those props accept mobile-first object (`{ _: 8, md: 24 }`) or array syntax per [Responsive properties](https://gamut.codecademy.com/?path=/docs-foundations-system-responsive-properties--page). Container queries use keys `c_base`, `c_xs`, … `c_xl`; the parent must set a container (e.g. `containerType="inline-size"` on `FlexBox`). Prefer a media-query fallback when mixing `c_*` with viewport breakpoints.
-
-Two different “grids”:
-
-- Design / page grid (this doc’s “Grid” section, 12 columns, margins/gutters) — product layout guidelines; implement with [`LayoutGrid`](https://gamut.codecademy.com/?path=/docs-layouts-layoutgrid-layoutgrid--docs) and responsive `columnGap` / `rowGap` where appropriate.
-- CSS Grid system props — `system.grid` on styled components or `GridBox` for local regions; not the same as full-page `LayoutGrid`. See [System props / Grid](https://gamut.codecademy.com/?path=/docs-foundations-system-props-grid--page). `LayoutGrid` is for flexible full-page sections; use `FlexBox` / `GridBox` / `Box` for smaller areas ([LayoutGrid usage](https://gamut.codecademy.com/?path=/docs-layouts-layoutgrid-layoutgrid--docs)).
-
-Designer vs code names: Figma / Layout docs often label artboards XL, LG, MD, SM, XS, Base. In code, viewport breakpoints are `xl`, `lg`, `md`, `sm`, `xs` (min-widths below); `_` is the base (no min-width query). The “Max content width” column maps to those design sizes, not the `xs` token name alone.
-
-## Spacing scale
-
-All spacing is multiples of 4px on an 8px grid.
-
-| Token | Value |
-| ----- | ----- |
-| `0`   | 0     |
-| `4`   | 4px   |
-| `8`   | 8px   |
-| `12`  | 12px  |
-| `16`  | 16px  |
-| `24`  | 24px  |
-| `32`  | 32px  |
-| `40`  | 40px  |
-| `48`  | 48px  |
-| `64`  | 64px  |
-| `96`  | 96px  |
-
-Use multiples of 8px for block-element spacing. Use 4px only for inline or typographic relationships.
-
-## Border radius
-
-| Token  | Value | Use                                |
-| ------ | ----- | ---------------------------------- |
-| `none` | 0px   | Square / non-interactive elements  |
-| `sm`   | 2px   | Subtle rounding, tags              |
-| `md`   | 4px   | Buttons, inputs, interactive cards |
-| `lg`   | 8px   | Cards, panels                      |
-| `xl`   | 16px  | Large cards, modals                |
-| `full` | 999px | Pills, avatars, circular elements  |
-
-## Breakpoints
-
-Mobile-first. Styles apply from the named breakpoint and up.
-
-| Token    | Min-width | Max content width |
-| -------- | --------- | ----------------- |
-| _(base)_ | 0         | 288px             |
-| `xs`     | 480px     | 448px             |
-| `sm`     | 768px     | 704px             |
-| `md`     | 1024px    | 896px             |
-| `lg`     | 1200px    | 1072px            |
-| `xl`     | 1440px    | 1248px            |
-
-The grid table below collapses xl+lg, md, sm+xs, and base to four implementation tiers; max-content widths still follow the six design sizes in Layout.
-
-## Container query breakpoints
-
-Container keys (`c_*`) use the same min-width numbers as viewport breakpoints, but they apply to the width of a CSS containment context (usually a parent), not the browser viewport. Use them when a component must adapt inside sidebars, split layouts, or embeds. Full detail: [Responsive properties — Container Queries](https://gamut.codecademy.com/?path=/docs-foundations-system-responsive-properties--page).
-
-| Key      | Min container width | Typical use                                                             |
-| -------- | ------------------- | ----------------------------------------------------------------------- |
-| `c_base` | 1px                 | Always matches once a container exists; base style inside the container |
-| `c_xs`   | 480px               | Matches viewport `xs` threshold, but on container width                 |
-| `c_sm`   | 768px               |                                                                         |
-| `c_md`   | 1024px              |                                                                         |
-| `c_lg`   | 1200px              |                                                                         |
-| `c_xl`   | 1440px              |                                                                         |
-
-Requirements
-
-- A descendant of an element that establishes a container — e.g. parent `<FlexBox containerType="inline-size">` (or other `container-type`). Without that, `c_*` rules never match.
-- Prefer a viewport fallback alongside `c_*` (e.g. `display={{ _: 'block', sm: 'flex', c_md: 'grid' }}`) for browsers or trees without container support.
-
-Object vs array
-
-- Object: `p={{ _: 8, c_md: 24 }}` — readable for a few container-only overrides.
-- Array: after the six viewport slots (`_` through `xl`), indices 6–11 are `c_base`, `c_xs`, `c_sm`, `c_md`, `c_lg`, `c_xl` respectively. Use when you need the full ordered chain.
-
-When to use which
-
-- Viewport keys (`_`, `xs`, … `xl`) — page-level layout, full-bleed sections, global nav.
-- Container keys (`c_base`, … `c_xl`) — reusable widgets whose width is driven by layout, not the device alone.
-
-## Page layout grid (12 columns)
-
-12-column grid at all breakpoints. Tier columns group breakpoints with identical margin/gutter/row-gap numbers from [Layout](https://gamut.codecademy.com/?path=/docs-foundations-layout--docs).
-
-| Property           | xl/lg | md   | sm/xs | base |
-| ------------------ | ----- | ---- | ----- | ---- |
-| Horizontal margins | 64px  | 48px | 32px  | 16px |
-| Column gutters     | 32px  | 24px | 16px  | 8px  |
-| Row gaps           | 32px  | 24px | 16px  | 8px  |
-
-Minimum touch target on mobile: 44×44px — see `gamut-accessibility` skill for hit-target guidance.
-
-## Responsive rules
-
-- Begin design work at 1440px (XL), then adapt down.
-- Multi-column layouts collapse to fewer columns — do not stretch or squish.
-- Catalog cards and non-lockup elements should align on one axis (usually left), not fill column widths.
-- Avoid dense or small components at the base (mobile) breakpoint.

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

@@ -1,82 +0,0 @@
-# Typography
-
-Use theme typography tokens (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`) — never hardcoded font-family strings or magic px for product UI. Prefer `<Text>` from `@codecademy/gamut`, or `system.typography` / `css()` from `@codecademy/gamut-styles` ([`gamut-system-props` skill](../../skills/gamut-system-props/SKILL.md)).
-
-Source of truth for scales and stacks: [`packages/gamut-styles/src/variables/typography.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variables/typography.ts) and theme builders under [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes).
-
-Storybook: [Typography / Text](https://gamut.codecademy.com/?path=/docs-typography-text--docs) · [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) (system props) · Foundations / Theme: [Core](https://gamut.codecademy.com/?path=/docs-foundations-theme-core-theme--docs), [Percipio](https://gamut.codecademy.com/?path=/docs-foundations-theme-percipio-theme--docs), [LX Studio](https://gamut.codecademy.com/?path=/docs-foundations-theme-lx-studio-theme--docs)
-
-## Themes × font families
-
-Semantic keys (`base`, `accent`, `monospace`, `system`) are stable; resolved stacks depend on `GamutProvider` theme ([`setup.md`](../setup.md)).
-
-| Theme                 | `fontFamily.base`                    | `fontFamily.accent`                   | `fontFamily.monospace`                 | `fontFamily.system`            |
-| --------------------- | ------------------------------------ | ------------------------------------- | -------------------------------------- | ------------------------------ |
-| Core, Admin, Platform | Apercu stack (`fontBase`)            | Suisse + Apercu stack (`fontAccent`)  | Monaco / Menlo stack (`fontMonospace`) | System UI stack (`fontSystem`) |
-| Percipio              | Skillsoft Text (`fontPercipioBase`)  | Skillsoft Sans (`fontPercipioAccent`) | Roboto Mono                            | Roboto (`system`)              |
-| LX Studio             | Same as Percipio (`base` / `accent`) | Same                                  | Same stack as Core (`fontMonospace`)   | Same as Core (`fontSystem`)    |
-
-Admin and Platform extend Core for colors / modes only — typography matches Core.
-
-Licensing: Apercu is licensed for Codecademy surfaces only; Skillsoft products use Percipio/LX stacks above.
-
-## Font size scale
-
-Values are `rem`-backed keys on `theme.fontSize` (aliases shown as px for readability).
-
-| Token | Size | Common use                   |
-| ----- | ---- | ---------------------------- |
-| `64`  | 64px | Hero / display               |
-| `44`  | 44px | Page titles                  |
-| `34`  | 34px | Section titles               |
-| `26`  | 26px | Sub-section titles           |
-| `22`  | 22px | Card titles, large UI labels |
-| `20`  | 20px | Secondary titles             |
-| `18`  | 18px | Large body, intro text       |
-| `16`  | 16px | Default body text            |
-| `14`  | 14px | Small body, captions, labels |
-
-## Line height
-
-| Token         | Value | Use                          |
-| ------------- | ----- | ---------------------------- |
-| `base`        | 1.5   | Body text                    |
-| `spacedTitle` | 1.3   | Sub-headlines, medium titles |
-| `title`       | 1.2   | Large headlines              |
-
-## Font weight (semantic)
-
-Use semantic keys on components — do not assume a numeric bold everywhere.
-
-| Token   | Core / Admin / Platform | Percipio / LX Studio          |
-| ------- | ----------------------- | ----------------------------- |
-| `base`  | 400                     | 400                           |
-| `title` | 700                     | 500 (`fontWeightMediumTitle`) |
-
-Headlines, CTAs, and buttons should use `fontWeight="title"` so Percipio/LX get 500, Core gets 700. Literal `700` breaks Skillsoft branding on those themes.
-
-Numeric `400` and `700` keys also exist on the theme for rare explicit needs.
-
-## Codecademy (Core / Admin / Platform) — voice & layout
-
-These UX rules target Apercu + Suisse products; do not blindly apply to Percipio/LX without brand guidance.
-
-- `fontFamily="base"` (Apercu): default UI and marketing type. Emphasis inside body copy: Italic, not Bold for intra-paragraph stress.
-- `fontFamily="accent"` (Suisse stack): technical accent — code snippets, captions, labels with engineering flavor, figures. Use sparingly; glyph box reads larger — step down ~10–15% vs equivalent `base` size; give comfortable line-height.
-- Alignment: left-align by default; center only short marketing headlines; avoid right-align except tabs / numerics.
-- Letter-spacing: do not tweak tracking unless design specifies.
-- Line length: ~45–85 characters per line (~66 ideal for single-column body); constrain container width, not arbitrary CSS letter-spacing.
-
-## Line length (all products)
-
-| Context            | Target              |
-| ------------------ | ------------------- |
-| Single-column body | ~66 chars (max ~85) |
-| Multi-column       | ≤50 chars per line  |
-| Minimum            | ~45 chars           |
-
-## Related skills
-
-- [`gamut-typography`](../../skills/gamut-typography/SKILL.md) — deeper editorial patterns for agents.
-- [`gamut-style-utilities`](../../skills/gamut-style-utilities/SKILL.md) — `css()` / `variant` / `states` and tokenized typography in styled components.
-- [`gamut-theming`](../../skills/gamut-theming/SKILL.md) — which theme / `GamutProvider` / `theme.d.ts`.

package/agent-tools/guidelines/overview-icons.md

@@ -1,19 +0,0 @@
-# Icons
-
-Icons must come from `@codecademy/gamut-icons`. Do not import or generate icons from other sources. If a needed icon is unavailable, pick a verified alternative from the library or flag for confirmation — do not substitute non-system assets.
-
-## Identifying the correct icon
-
-Do not rely on Figma layer names (`data-name`). Layer names are often stale after icon swaps.
-
-Determine the correct icon by:
-
-1. Reading the design image — visually identify the shape (three vertical dots → kebab menu, 3×3 grid → app switcher, etc.).
-2. Using contextual clues — tooltip text, element purpose, surrounding UI patterns.
-3. Cross-referencing exports — search `@codecademy/gamut-icons` for icons matching visual and semantic intent.
-4. Treating layer names as hints only — if a layer name conflicts with visual/contextual evidence, trust the evidence.
-5. When uncertain, flag for confirmation rather than guessing.
-
-Before using any icon, confirm it exists in `@codecademy/gamut-icons` (`packages/gamut-icons/src` or package exports).
-
-Storybook: [Foundations / Icons](https://gamut.codecademy.com/?path=/docs-foundations-icons--page)

package/agent-tools/guidelines/overview-illustrations.md

@@ -1,7 +0,0 @@
-# Illustrations
-
-Illustrations must come from `@codecademy/gamut-illustrations`. Do not generate or import illustrations from other sources.
-
-If the correct illustration is unavailable, flag for confirmation rather than substituting a non-system asset.
-
-Storybook: [Illustrations](https://gamut.codecademy.com/?path=/docs-illustrations--page) · `packages/gamut-illustrations/src` exports.

package/agent-tools/guidelines/overview-patterns.md

@@ -1,7 +0,0 @@
-# Patterns
-
-Patterns must come from `@codecademy/gamut-patterns`. Match Figma component names to pattern exports when possible.
-
-If the correct pattern is unavailable, flag for confirmation rather than substituting a non-system asset.
-
-Storybook: browse pattern stories under the Gamut styleguide, or inspect `packages/gamut-patterns/src` exports.

package/agent-tools/guidelines/overview.md

@@ -1,84 +0,0 @@
-# Gamut Design System
-
-## For agents
-
-Do not load all guideline files. Read this overview’s Step 2 table, then open only the `guidelines/components/*.md` (or foundation) guides you need for the current task. For Menu, DataTable, Card, and other components without a dedicated skill, use `gamut-components`.
-
-Gamut is the Codecademy / Skillsoft design system — React component library (`@codecademy/gamut`), design tokens (`@codecademy/gamut-styles`), and Figma components with live code previews via Figma Code Connect.
-
-Core principle: Always use Gamut components, tokens, and patterns. Every element must trace back to an existing token, component, or documented pattern — never introduce ad-hoc values when a system equivalent exists.
-
-Design voice: "Ruled by logic, but creative and a bit unexpected." Structured and trustworthy for a learning platform, with engaging personality. Medium density — information-rich layouts with strong typographic hierarchy.
-
-Core principles:
-
-- Components are color mode–aware by default — never hardcode hex values for adaptive, accessible UI
-- All components work across all themes without modification
-- 12-column grid
-- Use semantic theme tokens from `@codecademy/gamut-styles` for color roles, typography, spacing, border radii, and layout — not raw palette hex or magic numbers. Validate non-standard combinations against WCAG.
-- Product theme: infer semantic tokens, fonts, and palette from root `DESIGN.md` (installed via `gamut plugin install --theme <name>`) and `<GamutProvider>`. See [`skills/gamut-theming/SKILL.md`](../skills/gamut-theming/SKILL.md).
-
-Agent skills: `gamut-components`, `gamut-style-utilities`, `gamut-theming`, `gamut-system-props`, `gamut-color-mode`, `gamut-forms`, `gamut-accessibility`, `gamut-typography`, `gamut-testing`.
-
-## Themes
-
-| Theme     | Product                         | Primary UI fonts (shipped theme)                       | Dark mode |
-| --------- | ------------------------------- | ------------------------------------------------------ | --------- |
-| Core      | Codecademy (default)            | Apercu + Suisse (`accent`)                             | ✓         |
-| Admin     | Codecademy admin tools          | Same as Core                                           | ✓         |
-| Platform  | Codecademy learning environment | Same as Core                                           | ✓         |
-| LX Studio | LX Studio application           | Skillsoft Text / Sans (`base` / `accent`)              | ✓         |
-| Percipio  | Skillsoft Percipio              | Skillsoft Text / Sans; Roboto Mono / Roboto (`system`) | ✓         |
-
-Set the theme at the app root via `<GamutProvider theme={...}>`. Match `DESIGN.md` in the app repo to the active product.
-
-Plugin install: Storybook [Meta → AI Tooling → Gamut plugin → Install](https://gamut.codecademy.com/?path=/docs-meta-ai-tooling-gamut-plugin-install--page). `gamut plugin install cursor --theme core` (or `percipio`, `lxstudio`, …) copies `DESIGN.*.md` to `./DESIGN.md`.
-
-## Reading order
-
-### Step 1: Overview (required)
-
-| File                                                                                                                             | What it covers                                 |
-| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| [setup.md](setup.md)                                                                                                             | Packages, `GamutProvider`, theme selection     |
-| [foundations/spacing.md](foundations/spacing.md) + [color.md](foundations/color.md) + [typography.md](foundations/typography.md) | Tokens — spacing, color, typography            |
-| [foundations/modes.md](foundations/modes.md)                                                                                     | `ColorMode`, `Background`                      |
-| [components/overview.md](components/overview.md)                                                                                 | Component catalog, discovery, forms breadcrumb |
-| [overview-icons.md](overview-icons.md)                                                                                           | Icon selection from `@codecademy/gamut-icons`  |
-| [overview-illustrations.md](overview-illustrations.md)                                                                           | `@codecademy/gamut-illustrations`              |
-| [overview-patterns.md](overview-patterns.md)                                                                                     | `@codecademy/gamut-patterns`                   |
-| [validation-checklist.md](validation-checklist.md)                                                                               | Pre-ship checklist                             |
-
-### Step 2: Component guides (read before using that component)
-
-| Using…                                                                    | Read first                                                                                                               |
-| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `FillButton` / `StrokeButton` / `TextButton` / `IconButton` / `CTAButton` | [components/buttons.md](components/buttons.md)                                                                           |
-| `GridForm` / `ConnectedForm`                                              | [components/forms.md](components/forms.md) · [`skills/gamut-forms/SKILL.md`](../skills/gamut-forms/SKILL.md)             |
-| `DataTable` / `DataList`                                                  | [components/data-table.md](components/data-table.md)                                                                     |
-| `Menu` / `MenuItem` / `MenuSeparator`                                     | [components/menu.md](components/menu.md)                                                                                 |
-| `Card`                                                                    | [components/card.md](components/card.md)                                                                                 |
-| `Select` / `SelectDropdown`                                               | [components/select.md](components/select.md)                                                                             |
-| `RadialProgress`                                                          | [components/radial-progress.md](components/radial-progress.md)                                                           |
-| `Shimmer` / `Spinner` / `FeatureShimmer`                                  | [components/loading-states.md](components/loading-states.md)                                                             |
-| `Coachmark`                                                               | [components/coachmark.md](components/coachmark.md)                                                                       |
-| `ToolTip` / `InfoTip`                                                     | [components/tooltips.md](components/tooltips.md)                                                                         |
-| `Video`                                                                   | [components/video.md](components/video.md)                                                                               |
-| `Rotation` / `ExpandInCollapseOut` / `FadeInSlideOut`                     | [components/animations.md](components/animations.md)                                                                     |
-| `ColorMode` / `Background`                                                | [foundations/modes.md](foundations/modes.md) · [`skills/gamut-color-mode/SKILL.md`](../skills/gamut-color-mode/SKILL.md) |
-
-### Step 3: Skills (on demand)
-
-| Skill                                                               | When                                                                                                  |
-| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| [`gamut-components`](../skills/gamut-components/SKILL.md)           | Menu, DataTable, Card, Select, Video, Coachmark, loading, animations (read matching component guides) |
-| [`gamut-style-utilities`](../skills/gamut-style-utilities/SKILL.md) | `css` / `variant` / `states`, `StyleProps`                                                            |
-| [`gamut-system-props`](../skills/gamut-system-props/SKILL.md)       | `system.*`, responsive props, `Box`                                                                   |
-| [`gamut-theming`](../skills/gamut-theming/SKILL.md)                 | Theme matrix, `GamutProvider`, new themes                                                             |
-| [`gamut-color-mode`](../skills/gamut-color-mode/SKILL.md)           | ColorMode, semantic color, `<Background>`                                                             |
-| [`gamut-forms`](../skills/gamut-forms/SKILL.md)                     | Form accessibility wiring                                                                             |
-| [`gamut-accessibility`](../skills/gamut-accessibility/SKILL.md)     | Component a11y matrix, overlays                                                                       |
-| [`gamut-typography`](../skills/gamut-typography/SKILL.md)           | Type stacks and voice                                                                                 |
-| [`gamut-testing`](../skills/gamut-testing/SKILL.md)                 | `setupRtl`, test harnesses                                                                            |
-
-Pre-ship audit: [`commands/gamut-review.md`](../commands/gamut-review.md) (`/gamut-review`).

package/agent-tools/guidelines/setup.md

@@ -1,83 +0,0 @@
-# Setup
-
-## Install
-
-```sh
-yarn add @codecademy/gamut-kit @emotion/react @emotion/styled
-```
-
-`gamut-kit` bundles `gamut`, `gamut-icons`, `gamut-illustrations`, `gamut-patterns`, `gamut-styles`, `variance`, and `gamut-tests`.
-
-Full guide: [Meta / Installation](https://gamut.codecademy.com/?path=/docs-meta-installation--page) in Storybook (CSP `nonce` on `GamutProvider`, Jest, Next/Gatsby entry points). For Emotion + TypeScript, add `theme.d.ts` as in [TypeScript (`theme.d.ts`)](#typescript-themedts) below.
-
-Product design intent: After install, use root `DESIGN.md` (from `gamut plugin install --theme <name>`) with [`skills/gamut-theming/SKILL.md`](../skills/gamut-theming/SKILL.md) for semantic tokens, fonts, and component patterns for that product. Do not modify or alias `@codecademy/*` packages away from published APIs.
-
-Optionally add a `peerDependencies` block in `package.json` listing `@codecademy/gamut`, `@codecademy/gamut-icons`, `@codecademy/gamut-illustrations`, `@codecademy/gamut-patterns`, `@codecademy/gamut-styles`, `@codecademy/gamut-tests`, and `@codecademy/variance` (e.g. `"*"`) so editors surface those packages — see Meta / Installation for the JSON snippet.
-
-## Required wrapper
-
-Wrap the app root in `<GamutProvider>` from `@codecademy/gamut-styles`. This wires up the theme, color mode, and logical properties for all child components.
-
-At runtime, `GamutProvider` defaults to Core when `theme` is omitted (`theme = coreTheme` in the implementation). For non-Core products and for TypeScript (`theme` is required on `GamutProviderProps`), pass `theme` explicitly using the table below.
-
-```tsx
-import { GamutProvider, theme } from '@codecademy/gamut-styles';
-
-const App = () => (
-  <GamutProvider theme={theme}>{/* app content */}</GamutProvider>
-);
-```
-
-## Theme selection
-
-| Product             | Theme to import               |
-| ------------------- | ----------------------------- |
-| Codecademy public   | `coreTheme` (default `theme`) |
-| Codecademy admin    | `adminTheme`                  |
-| Codecademy platform | `platformTheme`               |
-| LX Studio           | `lxStudioTheme`               |
-| Percipio            | `percipioTheme`               |
-
-All themes are exported from `@codecademy/gamut-styles`.
-
-## TypeScript (`theme.d.ts`)
-
-Augment `@emotion/react` so `props.theme` in `styled` / `css` matches the same theme object you pass to `<GamutProvider theme={...}>`. If the types disagree, system props and token autocomplete will not line up with runtime.
-
-Add a root `theme.d.ts` (or merge into your existing global types):
-
-```tsx
-// theme.d.ts
-import '@emotion/react';
-
-import type { CoreTheme } from '@codecademy/gamut-styles';
-
-declare module '@emotion/react' {
-  export interface Theme extends CoreTheme {}
-}
-```
-
-Use the theme interface that matches your provider — same row as the [theme selection](#theme-selection) table:
-
-| `GamutProvider` `theme` prop | Import for `Theme extends …` |
-| ---------------------------- | ---------------------------- |
-| `theme` or `coreTheme`       | `CoreTheme`                  |
-| `adminTheme`                 | `AdminTheme`                 |
-| `platformTheme`              | `PlatformTheme`              |
-| `lxStudioTheme`              | `LxStudioTheme`              |
-| `percipioTheme`              | `PercipioTheme`              |
-
-Example when the app uses Percipio:
-
-```tsx
-// theme.d.ts
-import '@emotion/react';
-
-import type { PercipioTheme } from '@codecademy/gamut-styles';
-
-declare module '@emotion/react' {
-  export interface Theme extends PercipioTheme {}
-}
-```
-
-See Emotion’s [TypeScript / define a theme](https://emotion.sh/docs/typescript#define-a-theme) for details.

package/agent-tools/rules/accessibility.mdc

@@ -1,78 +0,0 @@
----
-description: Apply these guardrails when editing Gamut UI in TS/JS/TSX/JSX. Universal rules (always loaded). Form wiring depth: `gamut-forms` skill; other component matrix and audit detail: `gamut-accessibility` — those skills do not repeat this rule set.
-alwaysApply: true
-globs: ['*.tsx', '*.ts', '*.jsx', '*.js']
----
-
-# Gamut Accessibility Rules
-
-## Prefer HTML over ARIA
-
-Unnecessary ARIA can cause harm. If a native HTML element or attribute with the semantics and behavior you need already exists, use it. Reach for ARIA only when native HTML is genuinely insufficient for the pattern.
-
-## A Role is a Promise
-
-ARIA roles modify the accessibility tree and _imply_ behavior. Always ensure that the implied keyboard behavior, focusability, and interactivity exists when a role is used.
-
-## ARIA can both cloak and enhance
-
-ARIA can augment native semantics (`aria-pressed` on a `<button>`) or override them entirely (`role="menuitem"` on an `<a>`). Both capabilities are powerful and dangerous. Override only when native HTML genuinely doesn't fit the pattern; when augmenting, don't contradict the native semantics.
-
-## Align accessible names with visible copy
-
-Prefer wiring names through visible text and native `<label>` / control text / `alt` over using `aria-label`. Point `aria-labelledby` at the visible heading or label that should define the name if it's not possible to name elements from their content. Use bare `aria-label` when there is no suitable visible label.
-
-## Treat missing visible labels as a design smell
-
-When there is no visible text for a nameable element, consider this a sign that the content design could be improved, but not a requirement that it is changed. This is not an accessibility violation.
-
-```html
-<!-- smell: this list has no conceptual name, so we have to create one using ARIA -->
-<ul aria-label="List heading">
-  <li>...</li>
-</ul>
-
-<!-- better: the list's name is visible and can be used for its accessible name -->
-<h2 id="list-name">List heading</h2>
-<ul aria-labelledby="list-name">
-  <li>...</li>
-</ul>
-```
-
-## Use Gamut primitives — do not fake buttons or dialogs
-
-- Actions: use Gamut button atoms (`FillButton`, `TextButton`, `StrokeButton`, `CTAButton`, `IconButton`) — not `<div onClick>`, not `<span role="button">`, not `<a>` without `href` for actions. Variant and `tip` guidance: [`guidelines/components/buttons.md`](../guidelines/components/buttons.md).
-- Tabs / overlays: `Tabs`, `Dialog`, `Modal`, and related primitives implement keyboard and focus patterns in code — still supply labels, titles, and trigger semantics as documented in the skill.
-
-## Every interactive control needs an accessible name
-
-- `IconButton` — provide `tip` (accessible name for icon-only).
-- `InfoTip` — provide `ariaLabel` or `ariaLabelledby`; there is no automatic fallback.
-- Decorative icon SVGs next to visible text — `aria-hidden="true"` on the icon.
-
-## Form label association
-
-Match `htmlFor` on `<FormGroupLabel>` with the `id` on the control. Base `<FormGroup>` renders live regions for `error` and `description`; `GridForm` and `ConnectedForm` add field wiring (`aria-describedby`, `aria-invalid`, first-error `aria-live` behavior) — do not add redundant duplicate regions. Depth: [`skills/gamut-forms/SKILL.md`](../skills/gamut-forms/SKILL.md).
-
-## Screen-reader-only text
-
-Use `<Text screenreader>` for visually hidden but announced content. `<HiddenText>` is deprecated.
-
-## Color and contrast
-
-Do not hardcode hex for adaptive UI. Prefer semantic tokens and `ColorMode` / `<Background>` so surfaces track theme and mode — see the `gamut-color-mode` skill and [`foundations/modes.md`](../guidelines/foundations/modes.md). Default pairings support accessible UI, but tokens do not guarantee WCAG compliance for every layout; validate non-standard combinations.
-
-## Focus visibility
-
-Never suppress focus indicators with `outline: none` or `outline: 0` without a visible replacement. Gamut’s focus styles are intentional (WCAG 2.4.7).
-
-## Where to read more (minimal index)
-
-| Topic | Primary doc |
-| --- | --- |
-| Forms (`GridForm`, `ConnectedForm`, `FormGroup`, validation, live regions) | [`skills/gamut-forms/SKILL.md`](../skills/gamut-forms/SKILL.md) |
-| Component matrix (tips, overlays, composites, checklists; not form wiring) | [`skills/gamut-accessibility/SKILL.md`](../skills/gamut-accessibility/SKILL.md) |
-| Button variants, `IconButton` `tip`, `disabled` vs `aria-disabled` | [`guidelines/components/buttons.md`](../guidelines/components/buttons.md) |
-| ColorMode, `Background`, semantic color roles | `gamut-color-mode` skill · [`foundations/modes.md`](../guidelines/foundations/modes.md) · [`foundations/color.md`](../guidelines/foundations/color.md) |
-| Tokens, `css` / `variant` / `states` | Storybook [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) |
-| Install, `GamutProvider`, CSP | Storybook [Meta / Installation](https://gamut.codecademy.com/?path=/docs-meta-installation--page) |