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

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

@@ -1,106 +0,0 @@
-# Forms
-
-Gamut provides two form organisms — `GridForm` and `ConnectedForm` — that handle layout, validation, submission state, and field registration. Always use one of these organisms for functional forms. Do not compose forms from individual form atoms when the interface needs submit, validation, reset, or dirty tracking.
-
-Related: [`skills/gamut-forms/SKILL.md`](../../skills/gamut-forms/SKILL.md) (accessibility wiring) · [`skills/gamut-accessibility/SKILL.md`](../../skills/gamut-accessibility/SKILL.md) (universal ARIA)
-
-## When to use each
-
-| Component       | Use when                                                                                                                                                                                                        |
-| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GridForm`      | Declarative, config-driven form. Pass `fields` (and optional `sections`) plus `submit` — layout, labels, validation, and submit button are automatic. Best for settings pages, profile forms, and CRUD dialogs. |
-| `ConnectedForm` | Full layout control with managed form state. Provides `react-hook-form` context; compose with `ConnectedFormGroup` and connected inputs. Best for tabs, custom columns, or content interleaved with fields.     |
-
-## Rules
-
-1. Never use bare form atoms for functional forms. `Input`, `Select`, `Checkbox`, `Radio`, `TextArea`, `FormGroup`, and `FormGroupLabel` are building blocks _inside_ organisms. Use them standalone only when there is no submit step (e.g. live search filter, immediate callback toggle).
-2. Prefer `GridForm` over `ConnectedForm` when the layout fits a grid.
-3. Always provide `defaultValues`. Omitting defaults causes uncontrolled-to-controlled warnings and broken resets.
-4. Use `validation="onChange"` when the submit button should stay disabled until required fields are valid. Default `"onSubmit"` validates only on submit.
-5. `GridForm` sections — use `GridFormSectionProps` (`title`, `as`, `fields`) to group fields under headings in one form, not multiple separate forms.
-6. Import connected inputs from `@codecademy/gamut`. `ConnectedInput`, `ConnectedSelect`, `ConnectedCheckbox`, `ConnectedRadioGroup`, `ConnectedTextArea`, `ConnectedFormGroup`, `SubmitButton`.
-7. `hideLabel: true` on checkbox/radio fields with no `label`. Without it, `FormGroupLabel` renders a stray "(optional)" or "\*" row above the control.
-8. `hideLabel: true` on toggle (`custom` type) fields. `Toggle` renders its own inline label; a `FormGroupLabel` above is redundant.
-
-## GridForm example
-
-```tsx
-import { GridForm } from '@codecademy/gamut';
-
-<GridForm
-  fields={[
-    {
-      title: 'General',
-      as: 'h2',
-      variant: 'title-sm',
-      fields: [
-        {
-          name: 'orgName',
-          label: 'Organization Name',
-          type: 'text',
-          size: 6,
-          defaultValue: 'Acme Corp',
-        },
-        {
-          name: 'emailNotifs',
-          description: 'Receive email notifications',
-          type: 'checkbox',
-          size: 12,
-          defaultValue: true,
-          hideLabel: true,
-        },
-      ],
-    },
-  ]}
-  submit={{ contents: 'Save Settings', size: 12 }}
-  onSubmit={(values) => console.log(values)}
-  validation="onChange"
-/>;
-```
-
-## ConnectedForm example (`useConnectedForm`)
-
-Prefer `useConnectedForm` for custom layouts — it types `ConnectedForm` / `ConnectedFormGroup` from `defaultValues` and spreads `connectedFormProps` (defaults + `validationRules`).
-
-```tsx
-import {
-  ConnectedForm,
-  ConnectedFormGroup,
-  ConnectedInput,
-  SubmitButton,
-  useConnectedForm,
-} from '@codecademy/gamut';
-
-export const ProfileForm = () => {
-  const { ConnectedFormGroup, ConnectedForm, connectedFormProps } =
-    useConnectedForm({
-      defaultValues: { displayName: '' },
-      validationRules: {
-        displayName: { required: 'Display name is required' },
-      },
-    });
-
-  return (
-    <ConnectedForm
-      onSubmit={(values) => console.log(values)}
-      validation="onChange"
-      {...connectedFormProps}
-    >
-      <ConnectedFormGroup
-        name="displayName"
-        label="Display Name"
-        field={{ component: ConnectedInput }}
-      />
-      <SubmitButton>Save</SubmitButton>
-    </ConnectedForm>
-  );
-};
-```
-
-## Quick reference
-
-| Layer            | Components                                                                                                                                 | When to use directly                   |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
-| Organisms        | `GridForm`, `ConnectedForm`                                                                                                                | Always for functional forms            |
-| Connected inputs | `ConnectedInput`, `ConnectedSelect`, `ConnectedCheckbox`, `ConnectedRadioGroup`, `ConnectedTextArea`, `ConnectedFormGroup`, `SubmitButton` | Only inside `ConnectedForm`            |
-| Atoms            | `Input`, `Select`, `Checkbox`, `Radio`, `TextArea`, `FormGroup`, `FormGroupLabel`, `FormError`                                             | Standalone display / live filters only |

package/agent-tools/guidelines/components/loading-states.md

@@ -1,17 +0,0 @@
-# Loading states
-
-Use `Shimmer` or `Spinner` for loading states. Do not use `FeatureShimmer` as a loading indicator.
-
-Storybook: [Atoms / Shimmer](https://gamut.codecademy.com/?path=/docs-atoms-shimmer--docs) · [Spinner](https://gamut.codecademy.com/?path=/docs-atoms-spinner--docs)
-
-## Components
-
-| Component        | Use for                                                                                                               |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `Shimmer`        | Skeleton placeholders for content being loaded                                                                        |
-| `Spinner`        | Indeterminate spinner for active loading                                                                              |
-| `FeatureShimmer` | Not a loader. Draws attention to secondary new features on a page. Do not use as a general-purpose loading indicator. |
-
-## Rule
-
-`Shimmer` and `Spinner` are the only true loading indicators. `FeatureShimmer` is for new-feature surfacing only.

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

@@ -1,58 +0,0 @@
-# Menu
-
-`Menu` and `MenuItem` from `@codecademy/gamut` are stateless — the consumer manages `active` and `disabled` state.
-
-Related: [`skills/gamut-accessibility/SKILL.md`](../../skills/gamut-accessibility/SKILL.md)
-
-Storybook: [Molecules / Menu](https://gamut.codecademy.com/?path=/docs-molecules-menu--docs)
-
-## Variants — always set explicitly
-
-Always pass the `variant` prop. Relying on the default produces the wrong variant for persistent navigation.
-
-| Variant   | Use for                                                                                                             | Rendering                                      |
-| --------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
-| `fixed`   | Persistent inline navigation — sidebars, primary nav, footer nav, any menu that does not open/close on interaction. | Must use `as="nav"` for accessible navigation. |
-| `popover` | Temporary surfaces — overflow menus, action menus, kebab menus, dismiss on outside click.                           | Default popover surface.                       |
-
-### Fixed (sidebar / persistent navigation)
-
-```tsx
-<Menu variant="fixed" as="nav">
-  <MenuItem
-    active={activeId === 'overview'}
-    onClick={() => setActive('overview')}
-  >
-    Overview
-  </MenuItem>
-  <MenuItem
-    active={activeId === 'settings'}
-    onClick={() => setActive('settings')}
-  >
-    Settings
-  </MenuItem>
-</Menu>
-```
-
-### Popover (overflow / action menu)
-
-```tsx
-<Menu variant="popover">
-  <MenuItem onClick={handleEdit}>Edit</MenuItem>
-  <MenuItem disabled label="Owner permissions required" onClick={handleDelete}>
-    Delete
-  </MenuItem>
-</Menu>
-```
-
-## `MenuItem` state
-
-- `active: boolean` — currently selected item; drive from your state.
-- `disabled: boolean` — unavailable for interaction.
-- `label: string` — when `disabled`, renders a `ToolTip` explaining why. Provide for any disabled item users might question.
-
-## Do not stretch `Menu` in flex layouts
-
-`Menu` is a flex column sized to its content. If an ancestor is a flex child that stretches (`flex={1}`, `height: 100%`, `alignSelf: stretch`), the menu expands and items spread apart.
-
-Rule: Wrap `Menu` in a block-level container with intrinsic height (`as="nav"` on a fixed menu, `Box`, or `div`). Do not use `FlexBox` as the immediate wrapper, and do not apply stretch on ancestors between `Menu` and the sidebar scroll container.

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

@@ -1,124 +0,0 @@
-# Components
-
-52 components have Figma ↔ code mappings via Figma Code Connect (`packages/code-connect/`). Live code snippets appear in Figma's inspect panel when you select a component.
-
-## Core rules
-
-- Always use existing Gamut components from `packages/gamut/src` rather than one-off equivalents. See the quick reference table below.
-- Apply exact sizing, variant, and props from the source. Never rely on defaults when the design or prompt specifies a value (e.g. `size="small"` on `Input`, `sizeVariant="small"` on `Select`).
-- When unsure, reference `Badge`, `Tag`, or button atoms in `packages/gamut/src`.
-
-## Forms vs. standalone inputs
-
-Functional forms — submit/save bundling multiple fields, validation, errors, or dirty tracking — must use `GridForm` or `ConnectedForm`. Read [forms.md](forms.md) before building any functional form.
-
-Standalone inputs — live search, real-time filters, single controls that update state immediately — use bare atoms (`Input`, `Select`, `Checkbox`, `Radio`, `TextArea`, `FormGroup`). No organism when there is no submit step.
-
-The test: submit/save bundled values → organism. Real-time state with no submit → atom.
-
-## Component discovery
-
-Before custom markup for any UI pattern:
-
-1. Enumerate exports — check `@codecademy/gamut` public API or `index.d.ts`.
-2. Prefer Gamut over raw HTML — e.g. `Menu` for nav, `DataTable` for tables, `Tabs` for tabs. Do not rebuild from `<ul>` / `<motion.div>` when a primitive exists.
-3. Read type definitions for props before custom wrappers.
-4. Never build custom media players — use `Video` ([video.md](video.md)).
-5. When no Gamut component exists, comment: `{/* No Gamut component for [pattern] — custom markup */}`
-
-### Quick reference
-
-| UI Pattern            | Gamut component(s)                                                    | Guide                                                                    |
-| --------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| Buttons               | `FillButton`, `StrokeButton`, `TextButton`, `IconButton`, `CTAButton` | [buttons.md](buttons.md)                                                 |
-| Links                 | `Anchor`                                                              | —                                                                        |
-| Typography            | `Text`                                                                | [`gamut-typography` skill](../../skills/gamut-typography/SKILL.md)       |
-| Markdown              | `Markdown`                                                            | —                                                                        |
-| Layout                | `Box`, `FlexBox`, `GridBox`, `Layout`, `LayoutGrid`                   | [spacing.md](../foundations/spacing.md)                                  |
-| Animations            | `Rotation`, `ExpandInCollapseOut`, `FadeInSlideOut`                   | [animations.md](animations.md)                                           |
-| Page containers       | `ContentContainer`, `GridContainer`                                   | —                                                                        |
-| Navigation / menus    | `Menu`, `MenuItem`, `MenuSeparator`                                   | [menu.md](menu.md)                                                       |
-| Breadcrumbs           | `Breadcrumbs`                                                         | —                                                                        |
-| Pagination            | `Pagination`                                                          | —                                                                        |
-| Tabs                  | `Tabs`                                                                | [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md) |
-| Accordions            | `Disclosure`                                                          | —                                                                        |
-| Data tables           | `DataTable`, `DataList`                                               | [data-table.md](data-table.md)                                           |
-| Lists                 | `List`                                                                | —                                                                        |
-| Cards                 | `Card`                                                                | [card.md](card.md)                                                       |
-| Charts                | `BarChart`                                                            | —                                                                        |
-| Modals                | `Dialog` (binary confirm/cancel); `Modal` (multi-view, complex)       | [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md) |
-| Drawers / flyouts     | `Drawer`, `Flyout`                                                    | [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md) |
-| Overlays / focus trap | `Overlay`, `FocusTrap`                                                | [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md) |
-| Popovers              | `Popover`, `PopoverContainer`                                         | —                                                                        |
-| Tooltips              | `ToolTip`, `InfoTip`, `PreviewTip`                                    | [tooltips.md](tooltips.md)                                               |
-| Onboarding            | `Coachmark`                                                           | [coachmark.md](coachmark.md)                                             |
-| Alerts / toasts       | `Alert`, `Toast`, `Toaster`                                           | —                                                                        |
-| Badges / tags         | `Badge`, `Tag`                                                        | —                                                                        |
-| Progress              | `ProgressBar`, `RadialProgress`                                       | [radial-progress.md](radial-progress.md)                                 |
-| Loading               | `Shimmer`, `Spinner`                                                  | [loading-states.md](loading-states.md)                                   |
-| Video                 | `Video`                                                               | [video.md](video.md)                                                     |
-| Forms                 | `GridForm`, `ConnectedForm`                                           | [forms.md](forms.md)                                                     |
-| Standalone inputs     | `Input`, `Select`, `Checkbox`, `Radio`, `TextArea`, `FormGroup`       | Forms breadcrumb above                                                   |
-| Rich select           | `SelectDropdown`                                                      | [select.md](select.md)                                                   |
-| Date                  | `DatePicker`                                                          | [`gamut-forms` skill](../../skills/gamut-forms/SKILL.md)                 |
-| Toggle (standalone)   | `Toggle`                                                              | —                                                                        |
-| Screen reader text    | `HiddenText`                                                          | —                                                                        |
-| Skip link             | `SkipToContent`                                                       | —                                                                        |
-| Dark / light regions  | `ColorMode`, `Background`                                             | [modes.md](../foundations/modes.md)                                      |
-
-## Validate variant props
-
-`Card`, `Badge`, `Tag`, and `Alert` accept specific `variant` values. Invalid strings (e.g. `"navy-on-white"`) crash `parseToHsl()` at runtime. Inspect prop types in `@codecademy/gamut` before using variant/color props. See [card.md](card.md) for `Card` variants.
-
-## Catalog by layer
-
-### Atoms
-
-Badge, FillButton, StrokeButton, CTAButton, TextButton, IconButton, Card, Checkbox, CodeBlock, Drawer, FlexBox, FormGroup, GridBox, HiddenText, Icon, Input, Label, Loader, Radio, Select, Spinner, Tag, TextArea, Toggle, Tooltip
-
-### Molecules
-
-Alert, Anchor, Breadcrumbs, Coachmark, Disclosure, GridForm, Markdown, Menu, Modal, Pagination, Popover, ProgressBar, Table, Tabs, Toast, Toaster, Video
-
-### Organisms
-
-ContentContainer, GridContainer, Layout, LayoutGrid
-
-## Key patterns
-
-### Buttons
-
-[buttons.md](buttons.md) — `FillButton` primary, `StrokeButton` secondary.
-
-### Forms and accessibility
-
-[forms.md](forms.md) · [`gamut-forms` skill](../../skills/gamut-forms/SKILL.md) · [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md)
-
-### Cards
-
-See [card.md](card.md). Variants include `default`, `white`, `yellow`, `hyper`, `navy`. Confirm against `DESIGN.md` for theme-specific surfaces.
-`FormGroup`, `GridForm`, `ConnectedForm`, tips, dialogs, composite widgets: [`skills/gamut-forms/SKILL.md`](../../skills/gamut-forms/SKILL.md) (forms) · [`skills/gamut-accessibility/SKILL.md`](../../skills/gamut-accessibility/SKILL.md) (overlays, composites, checklists) · Storybook [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page).
-
-- Background variants: `default` (ColorMode-responsive), `white`, `yellow`, `beige`, `navy`, `hyper`
-- Shadow variants: `none` (default), `outline`, `patternLeft`, `patternRight`
-- Add `isInteractive` when wrapping in `<Anchor>` — enables hover shadow + `borderRadius: md`
-- Default `borderRadius` is `none`; override with `borderRadius` prop
-
-### Color-aware regions
-
-[foundations/modes.md](../foundations/modes.md) — `<ColorMode mode="light|dark|system">`, `<Background bg="…">`.
-
-### Alerts
-
-| Variant | Tokens                                    |
-| ------- | ----------------------------------------- |
-| Error   | `feedback-error` + `background-error`     |
-| Success | `feedback-success` + `background-success` |
-| Warning | `feedback-warning` + `background-warning` |
-
-## Global tokens
-
-| Token          | Value                   | Use                |
-| -------------- | ----------------------- | ------------------ |
-| `headerHeight` | 64px (base), 80px (md+) | Global page header |
-| `headerZ`      | 15                      | Header z-index     |

package/agent-tools/guidelines/components/radial-progress.md

@@ -1,13 +0,0 @@
-# RadialProgress
-
-Storybook: [Molecules / RadialProgress](https://gamut.codecademy.com/?path=/docs-molecules-radialprogress--docs)
-
-## Labels as `children` by default
-
-`RadialProgress` renders children in a centered overlay inside the ring. Place the label (e.g. percentage text) as a child, not as a sibling below the component, unless the design explicitly places it outside the ring.
-
-```tsx
-<RadialProgress percent={75}>
-  <Text>75%</Text>
-</RadialProgress>
-```

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

@@ -1,23 +0,0 @@
-# Select vs. SelectDropdown
-
-`Select` is a native select suitable for most dropdown needs. Prefer `Select` over `SelectDropdown` for simple lists.
-
-Storybook: [Atoms / Select](https://gamut.codecademy.com/?path=/docs-atoms-select--docs) · [Organisms / SelectDropdown](https://gamut.codecademy.com/?path=/docs-organisms-selectdropdown--docs)
-
-## When to use `SelectDropdown`
-
-Only when you need:
-
-- Searchable/filterable options (`isSearchable`)
-- Multi-select (`multiple`)
-- Option subtitles, right labels, icons, abbreviations
-- Grouped options with dividers and group labels
-- Custom option styling
-
-## When to use `Select`
-
-Plain option lists with no enrichment — simpler, more performant, and more accessible.
-
-## Sizing
-
-Apply exact sizing from the design (e.g. `sizeVariant="small"` on `Select`) — do not rely on defaults when the source specifies a value.

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

@@ -1,22 +0,0 @@
-# ToolTip and InfoTip
-
-Related: [`skills/gamut-accessibility/SKILL.md`](../../skills/gamut-accessibility/SKILL.md) (`aria-describedby`, `InfoTip` labeling)
-
-Storybook: [Molecules / ToolTip](https://gamut.codecademy.com/?path=/docs-molecules-tips-tooltip--docs) · [InfoTip](https://gamut.codecademy.com/?path=/docs-molecules-tips-infotip--docs)
-
-## Use `placement: 'floating'` inside overflow containers
-
-`ToolTip` defaults to `placement: 'inline'`, which is clipped by ancestors with `overflow: hidden` (e.g. `DataTable` rows).
-
-When an `IconButton` or `ToolTip` is inside a table, card, or clipping container:
-
-- `tipProps={{ placement: 'floating' }}` on `IconButton`
-- `placement="floating"` on `ToolTip` directly
-
-This renders the tooltip in a floating layer above surrounding content.
-
-## Use `alignment="bottom-*"` near the top of the viewport
-
-Tips default to opening above the trigger. Near the page top (e.g. in a heading), the tip can clip.
-
-Pass `alignment="bottom-right"` or `"bottom-left"` so the tip opens downward.

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

@@ -1,29 +0,0 @@
-# Video
-
-Never build custom media players. Gamut exports `Video` (built on `@vidstack/react`) with controls, poster support, text tracks, and accessibility.
-
-Storybook: [Molecules / Video](https://gamut.codecademy.com/?path=/docs-molecules-video--docs)
-
-## Rule
-
-Before constructing `<video>`, image + play-button overlays, or third-party embed wrappers, use `Video`.
-
-## Common props
-
-| Prop               | Purpose             |
-| ------------------ | ------------------- |
-| `videoUrl`         | Video source        |
-| `placeholderImage` | Poster thumbnail    |
-| `videoTitle`       | Accessibility title |
-| `controls`         | Standard player UI  |
-
-```tsx
-import { Video } from '@codecademy/gamut';
-
-<Video
-  videoUrl="https://example.com/video.mp4"
-  placeholderImage="https://example.com/poster.jpg"
-  videoTitle="Course introduction"
-  controls
-/>;
-```

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

@@ -1,168 +0,0 @@
-# Color
-
-Use semantic aliases for UI that should respond to color mode (light/dark) and theme (Core, Admin, Platform, Percipio, LX Studio). The same semantic token names (`text`, `primary`, `background`, …) exist across themes; resolved palette values and hex differ by `GamutProvider` theme and active ColorMode. Never assume Codecademy Core hex when advising another product.
-
-Prefer `css` / `variant` / `states` from `@codecademy/gamut-styles` with semantic names (see Storybook [Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page)).
-
-Related: [`setup.md`](../setup.md) (which theme to import) · [`gamut-theming` skill](../../skills/gamut-theming/SKILL.md) · [`gamut-style-utilities` skill](../../skills/gamut-style-utilities/SKILL.md) · [`gamut-color-mode` skill](../../skills/gamut-color-mode/SKILL.md) · [`modes.md`](modes.md) (`<ColorMode>`, `<Background>`)
-
-Percipio, LX Studio, Admin, and Platform override subsets of semantic mappings while keeping the shared alias API — see theme sources below before hardcoding palette names or hex.
-
-## Semantic aliases (theme-stable names)
-
-These tokens describe roles. Actual colors come from the active theme + ColorMode.
-
-### Text
-
-| Token            | Use for                     | Notes                      |
-| ---------------- | --------------------------- | -------------------------- |
-| `text`           | Default body and UI text    |                            |
-| `text-accent`    | Stronger emphasis text      |                            |
-| `text-secondary` | Supporting / secondary copy | Often opacity on base text |
-| `text-disabled`  | Disabled state labels       |                            |
-
-### Background
-
-| Token                 | Use for                           | Notes                     |
-| --------------------- | --------------------------------- | ------------------------- |
-| `background`          | Default page/component background |                           |
-| `background-primary`  | Slightly elevated surfaces        |                           |
-| `background-contrast` | Maximum contrast surface          |                           |
-| `background-selected` | Selected row / item               | Often low-opacity overlay |
-| `background-hover`    | Hover state overlay               |                           |
-| `background-disabled` | Disabled surface                  |                           |
-| `background-success`  | Success state container           |                           |
-| `background-warning`  | Warning state container           |                           |
-| `background-error`    | Error state container             |                           |
-
-### Interactive
-
-| Token             | Use for                                   | Notes                        |
-| ----------------- | ----------------------------------------- | ---------------------------- |
-| `primary`         | Primary CTA, links, focus accents         | Pairs with `primary-hover`   |
-| `primary-hover`   | Hover on primary interactive              |                              |
-| `primary-inverse` | Accent on top of primary-colored surfaces |                              |
-| `secondary`       | Secondary CTA, ghost buttons              | Pairs with `secondary-hover` |
-| `secondary-hover` | Hover on secondary interactive            |                              |
-| `danger`          | Destructive actions, error emphasis       | Pairs with `danger-hover`    |
-| `danger-hover`    | Hover on danger interactive               |                              |
-
-### Border
-
-| Token              | Use for                    | Notes |
-| ------------------ | -------------------------- | ----- |
-| `border-primary`   | Strong borders, dividers   |       |
-| `border-secondary` | Medium-weight borders      |       |
-| `border-tertiary`  | Subtle borders, separators |       |
-| `border-disabled`  | Disabled input borders     |       |
-
-### Feedback
-
-| Token              | Use for                    | Notes |
-| ------------------ | -------------------------- | ----- |
-| `feedback-error`   | Error messages, validation |       |
-| `feedback-success` | Success messages           |       |
-| `feedback-warning` | Warning messages           |       |
-
-## Where resolved colors are documented
-
-Use these instead of memorizing hex:
-
-- Storybook [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page) — how aliases map per light/dark for reference layouts.
-- Storybook Foundations → Theme — per-product tables and guidance:
-  - [Core Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-core-theme--docs)
-  - [Admin Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-admin-theme--docs)
-  - [Platform Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-platform-theme--docs)
-  - [Percipio Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-percipio-theme--docs)
-  - [LX Studio Theme](https://gamut.codecademy.com/?path=/docs-foundations-theme-lx-studio-theme--docs)
-  - [Creating Themes](https://gamut.codecademy.com/?path=/docs-foundations-theme-creating-themes--docs) — authoring new themes in `gamut-styles`
-- Product design YAML (root `DESIGN.md` from agent-tools): [`DESIGN.Codecademy.md`](../../DESIGN.Codecademy.md), [`DESIGN.Percipio.md`](../../DESIGN.Percipio.md), [`DESIGN.LXStudio.md`](../../DESIGN.LXStudio.md) — semantic ↔ palette for that product.
-- Source: theme definitions in [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes), palette scales in [`packages/gamut-styles/src/variables`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/variables).
-
-## Codecademy Core — illustrative light/dark hex only
-
-The tables below are not valid for Percipio, LX Studio, or other themes. They are a quick mental model for Codecademy Core defaults only.
-
-### Text
-
-| Token            | Light        | Dark      |
-| ---------------- | ------------ | --------- |
-| `text`           | `#10162F`    | `#ffffff` |
-| `text-accent`    | `#0A0D1C`    | `#FFF0E5` |
-| `text-secondary` | navy-800 75% | white 65% |
-| `text-disabled`  | navy-800 63% | white 50% |
-
-### Background
-
-| Token                 | Light        | Dark      |
-| --------------------- | ------------ | --------- |
-| `background`          | `#ffffff`    | `#10162F` |
-| `background-primary`  | `#FFF0E5`    | `#0A0D1C` |
-| `background-contrast` | white        | black     |
-| `background-selected` | navy-800 4%  | white 4%  |
-| `background-hover`    | navy-800 12% | white 9%  |
-| `background-disabled` | navy-800 12% | white 9%  |
-| `background-success`  | `#F5FFE3`    | `#151C07` |
-| `background-warning`  | `#FFFAE5`    | `#211B00` |
-| `background-error`    | `#FBF1F0`    | `#280503` |
-
-### Interactive
-
-| Token             | Light        | Dark      |
-| ----------------- | ------------ | --------- |
-| `primary`         | `#3A10E5`    | `#FFD300` |
-| `primary-hover`   | `#5533FF`    | `#CCA900` |
-| `primary-inverse` | `#FFD300`    | `#3A10E5` |
-| `secondary`       | `#10162F`    | `#ffffff` |
-| `secondary-hover` | navy-800 86% | white 80% |
-| `danger`          | `#E91C11`    | `#E85D7F` |
-| `danger-hover`    | `#BE1809`    | `#DC5879` |
-
-### Border
-
-| Token              | Light        | Dark      |
-| ------------------ | ------------ | --------- |
-| `border-primary`   | `#10162F`    | `#ffffff` |
-| `border-secondary` | navy-800 75% | white 65% |
-| `border-tertiary`  | navy-800 28% | white 20% |
-| `border-disabled`  | navy-800 63% | white 50% |
-
-### Feedback
-
-| Token              | Light     | Dark      |
-| ------------------ | --------- | --------- |
-| `feedback-error`   | `#BE1809` | `#E85D7F` |
-| `feedback-success` | `#008A27` | `#AEE938` |
-| `feedback-warning` | `#FFD300` | `#FFFAE5` |
-
-## Raw palette (Core-centric reference)
-
-Raw tokens name fixed swatches (surfaces, illustration, `<Background bg="…">` on Codecademy). Palette keys and hex vary by theme — Percipio and others add or remap scales (`percipioPalette`, etc.). Confirm allowed keys in the active theme or `DESIGN.md` before using a raw token in a non-Core app.
-
-For Codecademy Core defaults:
-
-| Name     | Weights                    | Key values (illustrative)        |
-| -------- | -------------------------- | -------------------------------- |
-| `navy`   | 100–900                    | 800 = `#10162F`, 900 = `#0A0D1C` |
-| `hyper`  | 400, 500                   | 500 = `#3A10E5`, 400 = `#5533FF` |
-| `yellow` | 0, 400, 500, 900           | 500 = `#FFD300`                  |
-| `red`    | 0, 300, 400, 500, 600, 900 | 500 = `#E91C11`                  |
-| `green`  | 0, 100, 400, 700, 900      | 700 = `#008A27`                  |
-| `blue`   | 0, 100, 300, 400, 500, 800 | 500 = `#1557FF`                  |
-| `beige`  | —                          | `#FFF0E5`                        |
-| `pink`   | 0, 400                     | 400 = `#F966FF`                  |
-| `orange` | 100, 500                   | 500 = `#FF8C00`                  |
-
-Named shorthand aliases commonly used on Core surfaces: `beige`, `blue`, `green`, `hyper`, `navy`, `orange`, `pink`, `red`, `yellow`, `black`, `white`
-
-## Decision guide
-
-```
-Which product theme is GamutProvider using?
-  └─ Unknown → check setup.md / DESIGN.md / Storybook theme page before assuming hex or palette name
-
-Coloring UI text or backgrounds?
-  └─ Must adapt to light/dark OR theme? → semantic alias (text, background, primary, …)
-  └─ Must stay fixed regardless of mode?      → raw palette token (confirm key exists in that theme)
-  └─ Section background with content inside? → <Background bg="…"> (see modes.md)
-```

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

@@ -1,69 +0,0 @@
-# Color Modes
-
-Gamut uses semantic color aliases so components adapt to light/dark mode without configuration. See [color.md](color.md) for the full alias reference and decision guide.
-
-Product tokens: Semantic mappings vary by theme. Confirm aliases and palette keys against root `DESIGN.md` and the active theme Storybook page — do not assume Codecademy Core values in Percipio, LX Studio, or other products.
-
-Deep reference: [`skills/gamut-color-mode/SKILL.md`](../../skills/gamut-color-mode/SKILL.md) · Storybook [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page)
-
-## When to use the color mode system
-
-For any dark or light region — sidebars, footers, hero bands, callouts, panels, whole-app dark mode — use `ColorMode` or `Background` from `@codecademy/gamut-styles`. Do not handle these with custom CSS, hardcoded `rgba`, or manual color swaps.
-
-| Component    | Use when                                                                                        |
-| ------------ | ----------------------------------------------------------------------------------------------- |
-| `ColorMode`  | You know the mode (`light`, `dark`, or `system` for OS preference).                             |
-| `Background` | Background color is a palette token and Gamut should pick the best contrast mode automatically. |
-
-## Rules
-
-1. Never override Gamut colors with custom CSS when a `ColorMode` or `Background` wrapper achieves the same result via tokens.
-2. Prefer `ColorMode` over `Background` when the intended mode is known (e.g. sidebar always dark). Use `Background` when the surface color is fixed and mode should adapt.
-3. `ColorMode` has no `as` prop — nest semantic elements inside (`<nav>`, `<aside>`, `<footer>`).
-4. System props work on `ColorMode` — `p`, `m`, `width`, `position`, etc. without extra wrappers.
-5. `mode="system"` follows OS `prefers-color-scheme`. For in-app theme toggles, pass `mode="light"` or `mode="dark"` from your own state.
-
-## `<ColorMode>`
-
-```tsx
-import { ColorMode } from '@codecademy/gamut-styles';
-
-<ColorMode mode="light">{children}</ColorMode>
-<ColorMode mode="dark">{children}</ColorMode>
-<ColorMode mode="system">{children}</ColorMode>
-```
-
-Props: `mode="light" | "dark" | "system"`
-
-## `<Background>`
-
-Use `<Background>` — not a raw `bg` on layout — for colored sections with text or interactive children. Pass a palette token to `bg` (e.g. `hyper`, `navy`), not a semantic alias.
-
-```tsx
-import { Background } from '@codecademy/gamut-styles';
-
-<Background bg="hyper">{children}</Background>;
-```
-
-Nesting is supported — each `<Background>` creates its own accessible color context.
-
-## Hooks
-
-| Hook                   | Returns                               | Use                                                        |
-| ---------------------- | ------------------------------------- | ---------------------------------------------------------- |
-| `useCurrentMode()`     | `"light" \| "dark"`                   | Active mode key only                                       |
-| `useColorModes()`      | mode key, colors, all modes, resolver | Full mode data + `getColorValue`                           |
-| `usePrefersDarkMode()` | `boolean`                             | OS dark preference (prefer `mode="system"` on `ColorMode`) |
-
-Import from `@codecademy/gamut-styles`.
-
-## Example (Core theme)
-
-Core light/dark semantic mappings are documented in Storybook [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page). Other themes remap the same alias names to different palette values — verify in `DESIGN.md` and the product theme story before hardcoding palette fallbacks.
-Storybook: [Foundations / ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page) · [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page)
-
-## Common mistakes
-
-- Do not use raw palette tokens (`navy-400`, `white`) for text/backgrounds that must adapt across modes — use semantic aliases.
-- Do not use a raw `bg` prop on colored sections with content — use `<Background>`.
-- Do not wire `usePrefersDarkMode()` into `ColorMode` when `mode="system"` suffices.