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

package/agent-tools/skills/gamut-accessibility/SKILL.md

@@ -1,224 +0,0 @@
----
-name: gamut-accessibility
-description: Gamut a11y matrix, overlays, FocusTrap, tips, live regions. When invoked, read guidelines/components/buttons.md, menu.md, tooltips.md as needed. Forms: gamut-forms. Cursor: accessibility.mdc.
----
-
-# Gamut Accessibility
-
-## Read first
-
-When this skill applies, read the linked component guides for widgets you are auditing (not all at once):
-
-- [`guidelines/components/buttons.md`](../../guidelines/components/buttons.md)
-- [`guidelines/components/menu.md`](../../guidelines/components/menu.md)
-- [`guidelines/components/tooltips.md`](../../guidelines/components/tooltips.md)
-
-Universal rules: [`accessibility.mdc`](../../rules/accessibility.mdc) (Cursor, always-on). Form wiring: `gamut-forms`.
-
-Source: `@codecademy/gamut` — `react-aria-components` is used only in [`packages/gamut/src/Tabs/`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Tabs/) (`Tabs.tsx`, `TabList.tsx`, `Tab.tsx`, `TabPanel.tsx`). `react-focus-on` powers `FocusTrap` ([`packages/gamut/src/FocusTrap/index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/FocusTrap/index.tsx)), used by overlays such as `Overlay` ([`packages/gamut/src/Overlay/index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Overlay/index.tsx)) and `Popover`. Other widgets (e.g. `Menu`, `DatePicker`) implement keyboard and ARIA in Gamut code — verify behavior in Storybook and source, do not assume React Aria.
-
-Product-oriented button variants and props: [`guidelines/components/buttons.md`](../../guidelines/components/buttons.md) · Menus: [`guidelines/components/menu.md`](../../guidelines/components/menu.md) · Tooltips: [`guidelines/components/tooltips.md`](../../guidelines/components/tooltips.md)
-
----
-
-## Universal rules
-
-Prefer native HTML, minimal ARIA, correct roles, visible names, focus visibility, semantic color / `ColorMode`, and Gamut primitives — see the always-loaded Gamut Accessibility Rules: [`accessibility.mdc`](../../rules/accessibility.mdc). This skill adds Gamut component behavior and audit detail below.
-
----
-
-## How Gamut handles accessibility
-
-Tabs use `react-aria-components` (see `packages/gamut/src/Tabs/*.tsx`) for roving tabindex and keyboard navigation. Overlays (e.g. `Overlay`, `Popover`) use `FocusTrap` → `react-focus-on` for focus containment and Escape/outside close. Other interactive components (`Menu`, `DatePicker`, `Modal`, `Dialog`, etc.) rely on in-repo implementations — supply accessible names, wire labels to controls, and avoid duplicating what a component already sets (`aria-live`, `aria-describedby`, tabindex, etc.); confirm in source when auditing.
-
----
-
-## Component reference (index)
-
-There is no exported `<Button>` — use `FillButton`, `TextButton`, `StrokeButton`, `CTAButton`, and `IconButton` (shared `ButtonProps` type). Prefer these over `<div onClick>` or `<span role="button">`.
-
-Forms — `FormGroup`, `ConnectedForm` / `ConnectedFormGroup`, `GridForm`, field atoms (`Select`, `Checkbox`, `Radio`), validation, `aria-live` / `aria-describedby`: canonical reference is [`gamut-forms`](../gamut-forms/SKILL.md).
-
-| Component(s)                                            | Handled in library                                                                                                       | App / author responsibilities                                                                                                                                                                                                                                                              |
-| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `FillButton`, `TextButton`, `StrokeButton`, `CTAButton` | Render `<button>` (or `<a>` when `href` is set); native click + keyboard activation                                      | Visible text or `href` purpose; follow [`buttons.md`](../../guidelines/components/buttons.md) for variants and `disabled` vs `aria-disabled`.                                                                                                                                              |
-| `IconButton`                                            | `tip` feeds the accessible name for icon-only controls                                                                   | Always pass `tip` when the button has no visible text.                                                                                                                                                                                                                                     |
-| `Dialog`                                                | `Overlay` (shroud, Escape, focus), `role="dialog"`, `aria-modal`, close control with configurable `closeButtonProps.tip` | Provide a clear `title` (and meaningful body copy). Confirm naming with [Molecules / Modals / Dialog](https://gamut.codecademy.com/?path=/docs-molecules-modals-dialog--docs).                                                                                                             |
-| `Modal`                                                 | Same overlay/focus stack; optional `aria-label`; multi-`views` support                                                   | `title` / view titles; pass `aria-label` when there is no visible title string. [Molecules / Modals / Modal](https://gamut.codecademy.com/?path=/docs-molecules-modals-modal--docs).                                                                                                       |
-| `Alert`                                                 | Default `aria-live="polite"`, `role="status"`                                                                            | Use `aria-live="assertive"` only for urgent interruptions; do not nest inside another live region.                                                                                                                                                                                         |
-| `Tabs`, `Tab`, `TabList`, `TabPanel`                    | `react-aria-components` in `packages/gamut/src/Tabs/` — roving tabindex, arrows, Home/End                                | Name each tab; Tab moves into the active panel per APG.                                                                                                                                                                                                                                    |
-| Forms                                                   | See Forms above                                                                                                          | [`gamut-forms`](../gamut-forms/SKILL.md)                                                                                                                                                                                                                                                   |
-| `DatePicker` + `DatePickerInput`                        | Segmented input + calendar behavior inside `FormGroup`                                                                   | Provide `label` / `name` / `form` as for any input; keep `DatePickerInput` inside `DatePicker`. When embedded in `FormGroup` / `GridForm`, follow [`gamut-forms`](../gamut-forms/SKILL.md). [Organisms / DatePicker](https://gamut.codecademy.com/?path=/docs-organisms-datepicker--docs). |
-| `Menu`, `MenuItem`, `MenuSeparator`                     | List + `MenuProvider` (keyboard / roles depend on variant)                                                               | Label `Menu` / menubar per pattern; follow Storybook [Molecules / Menu](https://gamut.codecademy.com/?path=/docs-molecules-menu--docs).                                                                                                                                                    |
-| `Popover`                                               | `FocusTrap` when open (unless `skipFocusTrap`), positioning                                                              | `onRequestClose`, meaningful `role` when needed; do not trap focus unnecessarily when `skipFocusTrap`.                                                                                                                                                                                     |
-| `Flyout`                                                | `Overlay`, `Drawer`, visible `title`, close `IconButton` with `tip={closeLabel}`                                         | Pass `title` and `closeLabel`; name panel content.                                                                                                                                                                                                                                         |
-| `Drawer`                                                | Focuses container when `expanded`, `tabIndex={-1}` on shell                                                              | Drawer is a surface, not a full dialog — supply headings/labels inside for screen readers.                                                                                                                                                                                                 |
-| `Disclosure`                                            | `DisclosureButton` drives expand/collapse                                                                                | Provide `heading` / structure so the control’s purpose is clear.                                                                                                                                                                                                                           |
-| `Toggle`                                                | `ToggleLabel` + `htmlFor` wired to control `id`                                                                          | With no visible `label`, pass `ariaLabel` (or use `as="button"` pattern per props).                                                                                                                                                                                                        |
-| `ToolTip`                                               | Floating mode renders a screen-reader `role="tooltip"` branch with `id`                                                  | Pass the same `id` to the trigger’s `aria-describedby` when you rely on the tooltip as supplementary description (see component `id` JSDoc).                                                                                                                                               |
-| `InfoTip`                                               | —                                                                                                                        | `ariaLabel` or `ariaLabelledby` (camelCase) — no automatic fallback.                                                                                                                                                                                                                       |
-| `PreviewTip`                                            | `Anchor`-based preview, focus-driven content                                                                             | `linkDescription` and visible anchor text; do not use the preview as the sole name for an unrelated control.                                                                                                                                                                               |
-| `SkipToContent`                                         | Skip link behavior                                                                                                       | Place early in the tab order; `href` target `id` must exist on main content.                                                                                                                                                                                                               |
-| `Toast` + `Toaster`                                     | `Toaster` wraps the stack in `aria-live="polite"`                                                                        | Keep messages concise; avoid stacking many simultaneous assertive announcements.                                                                                                                                                                                                           |
-| `Pagination`                                            | Page / control buttons                                                                                                   | Ensure current page and actions are perceivable (labels / `aria-current` patterns per Storybook). [Molecules / Pagination](https://gamut.codecademy.com/?path=/docs-molecules-pagination--docs).                                                                                           |
-| `FocusTrap`                                             | Escape, outside click, `allowPageInteraction`                                                                            | Return focus to trigger on close for custom overlays.                                                                                                                                                                                                                                      |
-
-```tsx
-// correct
-<IconButton icon={DeleteIcon} tip="Delete item" onClick={handleDelete} />
-
-// wrong — no accessible name, no keyboard semantics
-<div onClick={handleDelete}><DeleteIcon /></div>
-```
-
-### Dialog / Modal (detail)
-
-Both use `Overlay` and `FocusTrap` (`react-focus-on`) patterns: focus moves into the surface, Escape closes (when enabled), focus should return to the trigger on close.
-
-Prefer a visible title so the dialog has a clear name; on `Modal`, pass `aria-label` when there is no suitable visible title string. Close control: `IconButton` with `closeButtonProps.tip` (defaults documented in source).
-
-```tsx
-<Dialog
-  title="Confirm deletion"
-  confirmCta={{ children: 'Delete', onClick: handleDelete }}
-  onRequestClose={handleClose}
-  isOpen={open}
-/>
-```
-
-### Alert (detail)
-
-Renders with `aria-live="polite"` and `role="status"` by default. Override with `aria-live="assertive"` only for time-sensitive errors requiring immediate interruption. Do not nest `<Alert>` inside another live region.
-
-### Tabs (detail)
-
-Built on `react-aria-components`. Follows the [ARIA Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/): arrow keys navigate tabs, Tab moves focus into the active panel, Home/End jump to first/last tab. The tablist is a composite — only the active tab is in the tab sequence (roving tabindex). No manual `aria-selected` or keyboard handling needed.
-
-### InfoTip (example)
-
-`<InfoTip>` needs `ariaLabel` or `ariaLabelledby` — see also the always-loaded rules.
-
-```tsx
-<InfoTip ariaLabel="More information about billing" />
-```
-
-### ToolTip (detail)
-
-When `placement="floating"`, the component renders a screen-reader-only branch with `role="tooltip"` and an optional `id`. Pass the same `id` to the described element’s `aria-describedby` so assistive tech associates the tooltip copy with the trigger. Inline placement uses the wrapper differently — see [Molecules / Tips / ToolTip](https://gamut.codecademy.com/?path=/docs-molecules-tips-tooltip--docs).
-
-### SkipToContent (detail)
-
-Include `<SkipToContent>` as the first focusable element in the page shell. The main content region must expose a matching `id` for the skip target.
-
----
-
-## Focus management
-
-`<FocusTrap>` is for custom overlay patterns not covered by `Dialog` / `Modal`.
-
-Key props:
-
-- `active` — enable/disable the trap dynamically
-- `onEscapeKey` — close handler
-- `onClickOutside` — dismiss on outside click
-- `allowPageInteraction` — permit scrolling outside the trap without closing
-
-Always return focus to the trigger on close. `react-focus-on` (via `FocusTrap`) and overlay flows handle much of this for dialogs/popovers; `Tabs` inherit focus behavior from `react-aria-components`. Custom surfaces must store a ref to the trigger and call `.focus()` on close when the library does not.
-
----
-
-## Composite widgets and managed focus
-
-ARIA composite roles (`listbox`, `menu`, `tree`, `grid`, `tablist`) use managed focus: only one element in the composite is in the tab sequence at a time. Tab moves focus to the next element outside the composite; arrow keys move focus within it.
-
-Implementation pattern — roving tabindex:
-
-- Set `tabIndex={0}` on the currently active item
-- Set `tabIndex={-1}` on all other items
-- On arrow key, update which item holds `tabIndex={0}` and call `.focus()` on it
-
-`Tabs` (`react-aria-components`) implement roving tabindex for the tablist pattern. `Menu` and other composites implement focus in Gamut — if you build a custom composite, implement roving tabindex yourself. A flat `tabIndex={0}` on every item is wrong — it puts every item in the sequential tab order.
-
----
-
-## Device-independent events
-
-Use `click` for activation, not `mousedown`. `click` follows pointer activation; native `<button>` (and similar controls) also fire `click` from keyboard (Space and Enter). A focused `<a href>` is usually activated with Enter, which fires `click` — Space often scrolls the page instead of activating the link. `mousedown` does not represent keyboard activation, so relying on it alone breaks keyboard-only use.
-
-For custom elements with `role="button"`, do not assume the browser will synthesize `click` from the keyboard the way it does for native interactive elements (`<button>`, `<a href>`, and other built-ins). Handle `keydown` for Space and Enter explicitly:
-
-```tsx
-const handleKeyDown = (e: React.KeyboardEvent) => {
-  if (e.key === ' ' || e.key === 'Enter') {
-    e.preventDefault();
-    handleActivation();
-  }
-};
-```
-
-Prefer Gamut `*Button` components (or `Anchor` with a real `href`) so you do not reimplement this.
-
----
-
-## Live regions
-
-| Scenario                                   | Pattern                                     |
-| ------------------------------------------ | ------------------------------------------- |
-| Status updates, non-critical notifications | `aria-live="polite"`                        |
-| Urgent global interruptions                | `aria-live="assertive"` (use sparingly)     |
-| Frequently updating counts or progress     | `aria-live="polite"` + `aria-atomic="true"` |
-
-Form-bound `aria-live` and `FormError` patterns: see Forms above (do not assume assertive on every field error).
-
-Inject live regions into the DOM before they need to announce. A region added simultaneously with its first announcement may be ignored by some assistive technologies.
-
-Do not elevate unrelated inline errors to `assertive` — reserve assertive for urgent interruptions the user did not directly trigger.
-
----
-
-## ARIA authoring rules
-
-- No redundant roles: don't set `role="button"` on `<button>` or `role="heading"` on `<h2>`
-- `aria-hidden` cascades: placing `aria-hidden="true"` on a parent removes the entire subtree from the accessibility tree, including focusable descendants — never put it on an ancestor of a focusable element
-- `role="presentation"` and `aria-hidden` on focusable elements: both are prohibited on elements that can receive focus — they remove semantics while leaving the element keyboard-reachable, producing an operable but unnamed control
-- Labelling vs describing: `aria-label` / `aria-labelledby` name the control. `aria-describedby` provides supplementary context. Both can coexist on the same element
-- Required fields: use `aria-required="true"` or the HTML `required` attribute. Visual asterisks must have an explanatory text string visible on the page; the asterisk glyph itself should carry `aria-hidden="true"` — `<FormGroupLabel>` already handles this
-- `display:none` vs `aria-hidden`: elements with `display:none` are already removed from the accessibility tree; adding `aria-hidden` is redundant. Use `aria-hidden="true"` only when an element is visually present but should be hidden from assistive technology
-
----
-
-## Color and contrast (non-text)
-
-Semantic tokens, `ColorMode`, and `<Background>` are covered in the always-loaded `accessibility.mdc` rule and the `gamut-color-mode` skill. Here: non-text contrast (focus rings, input borders, icon affordances) should meet ~3:1 vs adjacent colors where WCAG 1.4.11 applies — validate in your layout.
-
----
-
-## Testing checklist
-
-- [ ] Full keyboard navigation: every interactive element reachable and operable without a mouse
-- [ ] Focus is always visible and never lost or unexpectedly trapped
-- [ ] Dialogs trap focus correctly; Escape closes; focus returns to the trigger
-- [ ] Composite widgets (tabs, menus, listboxes) use arrow keys internally, not Tab
-- [ ] All form inputs have programmatically associated labels (not placeholder-only)
-- [ ] Form errors surface through the library’s `FormError` / live-region patterns (Forms above)
-- [ ] Icon-only controls have accessible names
-- [ ] No content relies solely on color to convey meaning
-- [ ] Screen reader matrix: VoiceOver + Safari (iOS), VoiceOver + Chrome (macOS), NVDA + Chrome (Windows)
-- [ ] 200% zoom: layout intact, no content overflow or disappearance
-
----
-
-## Common anti-patterns
-
-| Anti-pattern                                             | Fix                                                                                   |
-| -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `<div onClick={…}>` for actions                          | `FillButton`, `TextButton`, `StrokeButton`, `CTAButton`, or `IconButton` (with `tip`) |
-| `placeholder` as the only label                          | `FormGroupLabel` with matching `htmlFor` / `id`                                       |
-| `aria-label` on a `<div>` with no role                   | Add a meaningful `role` or use a semantic element                                     |
-| `role="button"` without Space/Enter handlers             | Use a Gamut `*Button`, `Anchor` with `href`, or add `keydown`                         |
-| `tabIndex={0}` on every item in a composite              | Roving tabindex: `0` on active item, `-1` on rest                                     |
-| Tooltip as the only accessible name for a control        | Set `aria-label` (or visible text) on the control as well                             |
-| `aria-hidden="true"` on a focusable element              | Also remove from tab order (`tabIndex={-1}`) or restructure                           |
-| `mousedown` for activation                               | Use `click`                                                                           |
-| `outline: none` without a replacement                    | Use Gamut’s built-in focus styles                                                     |
-| Multiple `aria-live` regions for the same content stream | One region per logical stream; reuse it across updates                                |

package/agent-tools/skills/gamut-color-mode/SKILL.md

@@ -1,149 +0,0 @@
----
-name: gamut-color-mode
-description: Light/dark behavior, semantic color aliases, Background, color-mode hooks, hardcoded hex fixes. When invoked, read guidelines/foundations/modes.md and color.md first.
----
-
-# Gamut ColorMode
-
-## Read first
-
-When this skill applies, read before writing code:
-
-- [`guidelines/foundations/modes.md`](../../guidelines/foundations/modes.md)
-- [`guidelines/foundations/color.md`](../../guidelines/foundations/color.md)
-
-Confirm token mappings against root `DESIGN.md` and the active theme — do not assume Codecademy Core values.
-
-Source: `@codecademy/gamut-styles` — [`ColorMode.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/ColorMode.tsx)
-
-## Overview
-
-Gamut's color system uses semantic aliases instead of raw color tokens. This means components automatically adapt across light and dark modes without configuration.
-
-### Semantic color aliases
-
-| Alias        | Purpose                                    |
-| ------------ | ------------------------------------------ |
-| `text`       | Standard text color for all type           |
-| `background` | Base background color                      |
-| `primary`    | Interactive elements with primary action   |
-| `secondary`  | Interactive elements with secondary action |
-
-This set is not exhaustive (e.g. `text-accent`, `background-disabled`, `danger` — see the light/dark tables in Storybook).
-
-Key principle: Always use these aliases in component styles — never hardcode specific color tokens like `navy-400` for anything that needs to change per mode.
-
-Storybook: [Foundations / ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page) — interactive reference. [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) — semantic tokens, `css` / `variant` / `states`, and system props with ColorMode.
-
-Agent skill: [`gamut-style-utilities`](../gamut-style-utilities/SKILL.md) — `css` / `variant` / `states` with semantic colors alongside ColorMode.
-
-## `<ColorMode />`
-
-Wraps content in a color mode context. Place `<ColorMode />` as high in the app tree as practical. For a nested or static themed area on a page, use `<Background />` instead.
-
-```tsx
-import { ColorMode } from '@codecademy/gamut-styles';
-
-// Explicit light or dark
-<ColorMode mode="light">{children}</ColorMode>
-
-// Follow OS light/dark preference (see mode="system" below)
-<ColorMode mode="system">{children}</ColorMode>
-```
-
-Props: `mode="light" | "dark" | "system"`
-
-### `mode="system"` (OS preference)
-
-`system` is not a third color theme. It always resolves to `"light"` or `"dark"` based on the user's OS setting.
-
-How it works
-
-1. `ColorMode` calls `usePrefersDarkMode()`, which reads `window.matchMedia('(prefers-color-scheme: dark)')`.
-2. If the query matches → active mode is `"dark"`; otherwise `"light"`.
-3. Descendants receive that mode's semantic color variables (`text`, `background`, `primary`, etc.) — same as passing `mode="light"` or `mode="dark"` directly.
-
-When the OS changes (e.g. user toggles system appearance), the media query fires a `change` event, `ColorMode` re-renders, and semantic colors update for everything inside the wrapper.
-
-What it does not do
-
-- Read in-app preferences (account settings, a theme toggle in localStorage). For those, pass `mode="light"` or `mode="dark"` yourself from your own state.
-- Replace `<Background>`. A colored band still needs `<Background bg="hyper">` if you want contrast-based mode selection for that surface.
-
-Prefer `mode="system"` over wiring the hook yourself
-
-```tsx
-// Prefer — ColorMode owns light/dark resolution
-<ColorMode mode="system">{children}</ColorMode>;
-
-// Avoid — duplicates what mode="system" already does
-const prefersDark = usePrefersDarkMode();
-<ColorMode mode={prefersDark ? 'dark' : 'light'}>{children}</ColorMode>;
-```
-
-Use `usePrefersDarkMode()` only when you need the OS preference for something other than setting `ColorMode`'s mode (e.g. picking a decorative palette `bg` in a demo).
-
-Place `<ColorMode mode="system">` high in the tree (often inside `GamutProvider`) so the whole app follows system appearance unless a subtree overrides with `mode="light"`, `mode="dark"`, or `<Background>`.
-
-## `<Background />`
-
-Use `<Background>` instead of putting `bg` on a layout component when a section needs a fixed palette color (card, hero, landing band, etc.) — independent of the parent color mode. Pass a palette token to `bg` (e.g. `hyper`, `navy`, `paleGreen`), not a semantic alias (`text`, `background`, `primary`).
-
-`<Background>` switches light/dark to whichever mode gives the highest contrast between that surface and body `text`. Nested Gamut components inherit readable colors without extra setup.
-
-```tsx
-import { Background } from '@codecademy/gamut-styles';
-
-// Single background — mode switches automatically if needed
-const Card = ({ children }) => <Background bg="hyper">{children}</Background>;
-
-// Nested backgrounds — each creates its own color context
-const Page = () => (
-  <Background bg="black" p={24}>
-    <Background bg="paleGreen" p={24}>
-      {/* content inside inner Background uses its own mode */}
-    </Background>
-  </Background>
-);
-```
-
-### `background-current` CSS variable
-
-When `<Background>` is rendered, it sets a `background-current` CSS variable on the theme. Use this to reference an ancestor's background color (e.g. for simulating transparency or masking content).
-
-## Color mode hooks
-
-```tsx
-import {
-  useColorModes,
-  useCurrentMode,
-  usePrefersDarkMode,
-} from '@codecademy/gamut-styles';
-
-// [activeModeKey, activeModeColors, allModes, getColorValue]
-const [current, currentColors, modes, getColorValue] = useColorModes();
-
-// Active mode key: "light" | "dark" (optional override argument)
-const current = useCurrentMode();
-const forced = useCurrentMode('light');
-
-// Boolean from window.matchMedia('(prefers-color-scheme: dark)')
-const prefersDark = usePrefersDarkMode();
-```
-
-## Decision guide
-
-| Need                                                          | Use                                |
-| ------------------------------------------------------------- | ---------------------------------- | ---- | --------- |
-| Set a page or section to a specific mode                      | `<ColorMode mode="light            | dark | system">` |
-| Place content on a colored background with automatic contrast | `<Background bg="...">`            |
-| Read the current mode in JavaScript                           | `useCurrentMode()`                 |
-| Access all modes, variables, and resolve raw colors           | `useColorModes()`                  |
-| Detect OS dark mode preference                                | `usePrefersDarkMode()`             |
-| Access full emotion theme                                     | `useTheme()` from `@emotion/react` |
-
-## Common mistakes to avoid
-
-- Do not use raw color tokens (e.g. `color: 'navy-400'`) for text, backgrounds, or borders that need to be accessible across modes — use semantic aliases instead.
-- Do not use a raw `bg` prop for colored section backgrounds that need static, ColorMode-agnostic, background colors — use `<Background>` so mode selection is handled for you.
-- Do not manually set `ColorMode`'s `mode` from `usePrefersDarkMode()` when `mode="system"` is enough. The hook is still useful for non-mode concerns (e.g. choosing a decorative `bg` in Storybook demos).

package/agent-tools/skills/gamut-components/SKILL.md

@@ -1,46 +0,0 @@
----
-name: gamut-components
-description: Implements or reviews Gamut UI components in TSX — Menu, DataTable, DataList, Card, Select, Video, Coachmark, Shimmer, animations, tooltips. Use when no narrower gamut-* skill applies. When invoked, read only the relevant guidelines/components/*.md files.
-paths: '**/*.tsx'
----
-
-# Gamut components (guideline router)
-
-Use when building or changing Gamut components in `.tsx` files and a narrower skill does not already cover the task (`gamut-forms`, `gamut-color-mode`, etc.).
-
-## Read first
-
-1. Read [`guidelines/overview.md`](../../guidelines/overview.md) Step 2 table only (component → guide mapping).
-2. Read only the `guidelines/components/*.md` files for components you will touch in this task — not all guides.
-
-Do not load every guideline file. Skip guides for components you are not using.
-
-## Component → guideline
-
-| Component(s)                                                          | Guideline                                                                             |
-| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
-| `FillButton`, `StrokeButton`, `TextButton`, `IconButton`, `CTAButton` | [`buttons.md`](../../guidelines/components/buttons.md)                                |
-| `GridForm`, `ConnectedForm`                                           | [`forms.md`](../../guidelines/components/forms.md) — prefer `gamut-forms` skill       |
-| `DataTable`, `DataList`                                               | [`data-table.md`](../../guidelines/components/data-table.md)                          |
-| `Menu`, `MenuItem`, `MenuSeparator`                                   | [`menu.md`](../../guidelines/components/menu.md)                                      |
-| `Card`                                                                | [`card.md`](../../guidelines/components/card.md)                                      |
-| `Select`, `SelectDropdown`                                            | [`select.md`](../../guidelines/components/select.md)                                  |
-| `RadialProgress`                                                      | [`radial-progress.md`](../../guidelines/components/radial-progress.md)                |
-| `Shimmer`, `Spinner`, `FeatureShimmer`                                | [`loading-states.md`](../../guidelines/components/loading-states.md)                  |
-| `Coachmark`                                                           | [`coachmark.md`](../../guidelines/components/coachmark.md)                            |
-| `ToolTip`, `InfoTip`, `PreviewTip`                                    | [`tooltips.md`](../../guidelines/components/tooltips.md)                              |
-| `Video`                                                               | [`video.md`](../../guidelines/components/video.md)                                    |
-| `Rotation`, `ExpandInCollapseOut`, `FadeInSlideOut`                   | [`animations.md`](../../guidelines/components/animations.md)                          |
-| `ColorMode`, `Background`                                             | [`modes.md`](../../guidelines/foundations/modes.md) — prefer `gamut-color-mode` skill |
-
-Discovery and forms vs. atoms: [`components/overview.md`](../../guidelines/components/overview.md).
-
-## Related skills
-
-| Topic                  | Skill                              |
-| ---------------------- | ---------------------------------- |
-| Forms                  | `gamut-forms`                      |
-| Color / modes          | `gamut-color-mode`                 |
-| Layout / spacing props | `gamut-system-props`               |
-| Accessibility          | `gamut-accessibility`              |
-| Product theme          | `gamut-theming` + root `DESIGN.md` |

package/agent-tools/skills/gamut-forms/SKILL.md

@@ -1,101 +0,0 @@
----
-name: gamut-forms
-description: Implementing or auditing Gamut forms — GridForm, ConnectedForm, FormGroup, labels, validation. When invoked, read guidelines/components/forms.md first. Pair with gamut-accessibility for non-form widgets.
----
-
-# Gamut forms
-
-## Read first
-
-When this skill applies, read [`guidelines/components/forms.md`](../../guidelines/components/forms.md) before writing code.
-
-Canonical wiring for `FormGroup`, `ConnectedForm`, `ConnectedFormGroup`, `GridForm`, and field renderers. Source: `packages/gamut/src/Form/`, `ConnectedForm/`, `GridForm/`.
-
-Universal label and primitive guidance: [`accessibility.mdc`](../../rules/accessibility.mdc) · overlay and composite patterns: [`gamut-accessibility`](../gamut-accessibility/SKILL.md).
-
----
-
-## Mandatory: use organisms for functional forms
-
-Functional forms (submit/save, validation, dirty state) must use `GridForm` or `ConnectedForm`. Do not compose from bare `Input`, `Select`, `Checkbox`, etc.
-
-| Organism        | When                                                     |
-| --------------- | -------------------------------------------------------- |
-| `GridForm`      | Declarative `fields` + `submit` — settings, CRUD dialogs |
-| `ConnectedForm` | Custom layout with managed `react-hook-form` state       |
-
-Rules: Always set `defaultValues`. Use `validation="onChange"` when submit should stay disabled until valid. `hideLabel: true` on checkbox/radio fields with no `label`, and on toggle (`custom`) fields where `Toggle` renders its own label.
-
----
-
-## Prefer connected layouts
-
-For typical product forms, prefer `GridForm` (declarative `fields`, `LayoutGrid`, submit/cancel) or `ConnectedForm` with `ConnectedFormGroup` / `useConnectedForm`. Use raw `FormGroup` + atoms only when the layout is simple and you fully own `id`, `htmlFor`, invalid state, and any `aria-describedby` (see below).
-
----
-
-## Labels and controls
-
-`htmlFor` / `id` pairing — universal rule in [`accessibility.mdc`](../../rules/accessibility.mdc) (Form label association). Form-specific notes:
-
-- `FormGroupLabel` → control `id` (or stable `name` when that is your field’s id convention).
-- Checkbox, Radio, Select: same pairing; checkbox/radio use the visually hidden input pattern from `@codecademy/gamut-styles` where applicable.
-
----
-
-## `FormGroup` (baseline)
-
-[`FormGroup.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Form/elements/FormGroup.tsx)
-
-- `description` → `FormGroupDescription` with `aria-live="assertive"`.
-- `error` (string) → `FormError` with `aria-live="polite"` and `role="alert"`.
-
-Raw `FormGroup` does not set `aria-describedby` or `aria-invalid` on `children`. If you compose fields outside `ConnectedFormGroup` / `GridForm`, wire those yourself or accept that only the live regions above communicate errors/descriptions.
-
----
-
-## `ConnectedFormGroup`
-
-[`ConnectedFormGroup.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/ConnectedForm/ConnectedFormGroup.tsx)
-
-- Passes `aria-describedby` (error region id when shown) and `aria-invalid` on the rendered field component.
-- `FormError`: `aria-live="assertive"` and `role="alert"` only when `isFirstError`; otherwise `aria-live="off"` and `role="status"` so subsequent errors do not interrupt repeatedly.
-
----
-
-## `GridForm`
-
-[`GridFormInputGroup/index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/GridForm/GridFormInputGroup/index.tsx) · [`GridFormTextInput`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/GridForm/GridFormInputGroup/GridFormTextInput/index.tsx)
-
-- Composes `ConnectedForm`, `LayoutGrid`, `GridFormButtons`, and field metadata. `FormError` uses the same first-error assertive pattern as `ConnectedFormGroup` (`aria-live` assertive vs off, `role` alert vs status).
-- Built-in text inputs set `aria-invalid` and register with react-hook-form via `register`. Custom / `custom` / `custom-group` renderers must still expose correct `id`, `label`, and error surfacing consistent with this pattern.
-
----
-
-## Live regions — do not double up
-
-`FormGroup`, `ConnectedFormGroup`, and `GridForm` already render `FormError` (and base `FormGroup` renders `FormGroupDescription`) with live-region attributes. Do not add a second `aria-live` wrapper for the same message stream.
-
----
-
-## Storybook
-
-- [Organisms / GridForm / About](https://gamut.codecademy.com/?path=/docs-organisms-gridform-about--docs) · [Usage](https://gamut.codecademy.com/?path=/docs-organisms-gridform-usage--docs) · [Validation](https://gamut.codecademy.com/?path=/docs-organisms-gridform-validation--docs) · [Fields](https://gamut.codecademy.com/?path=/docs-organisms-gridform-fields--docs)
-- [Organisms / ConnectedForm / ConnectedForm](https://gamut.codecademy.com/?path=/docs-organisms-connectedform-connectedform--docs) · [ConnectedFormGroup](https://gamut.codecademy.com/?path=/docs-organisms-connectedform-connectedformgroup--docs)
-
----
-
-## Example — baseline `FormGroup`
-
-```tsx
-<FormGroup
-  htmlFor="email-input"
-  description="Used for login"
-  error={errors.email}
->
-  <FormGroupLabel htmlFor="email-input">Email</FormGroupLabel>
-  <Input id="email-input" type="email" />
-</FormGroup>
-```
-
-When using `ConnectedFormGroup` or `GridForm`, prefer their docs and defaults over hand-rolling the above for every field.

package/agent-tools/skills/gamut-style-utilities/SKILL.md

@@ -1,111 +0,0 @@
----
-name: gamut-style-utilities
-description: css(), variant(), states(), StyleProps, useTheme from @codecademy/gamut-styles. When invoked, read guidelines/foundations/color.md for semantic tokens.
----
-
-# Gamut style utilities
-
-## Read first
-
-When this skill applies, read [`guidelines/foundations/color.md`](../../guidelines/foundations/color.md) before choosing color tokens in `css` / `variant` / `states`.
-
-Source: `@codecademy/gamut-styles` — [`variance/props.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/props.ts) (`css`, `variant`, `states` built on `PROPERTIES.all`).
-
-See also: [`gamut-theming`](../gamut-theming/SKILL.md) (which theme, `GamutProvider`, new themes). [`gamut-system-props`](../gamut-system-props/SKILL.md) (`system.*`, responsive props, `Box`). [`gamut-color-mode`](../gamut-color-mode/SKILL.md) (semantic color, `<ColorMode>`, `<Background>`). [Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx) and [system compose](https://gamut.codecademy.com/?path=/docs-foundations-system-compose--page).
-
-## Overview
-
-Use `css()`, `variant()`, and `states()` from `@codecademy/gamut-styles` for typed, token-scaled style objects (same scales as composed `system.*` props). Prefer semantic color keys so styles track ColorMode and theme.
-
-For layout-heavy styled components, prefer composing `system.*` via `variance.compose()` (see `gamut-system-props`) instead of re-stating every longhand in `css()`.
-
-## `css()` — static style objects
-
-```tsx
-import { css } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-
-const Box = styled.div(css({ bg: 'navy-400', p: 4 }));
-const Text = styled.div(css({ color: 'primary', p: 4 }));
-```
-
-## `variant()` and `states()` — branching and toggles
-
-- `variant()` — mutually exclusive modes: `base`, `defaultVariant`, and a `variants` map (semantic colors, spacing shorthands, nested selectors such as `'&:hover'`).
-
-```tsx
-import { variant } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-
-const Anchor = styled.a(
-  variant({
-    base: { p: 4 },
-    defaultVariant: 'interface',
-    variants: {
-      interface: {
-        color: 'text',
-        '&:hover': { color: 'text-accent' },
-      },
-      inline: {
-        color: 'primary',
-        '&:hover': { color: 'secondary' },
-      },
-    },
-  })
-);
-```
-
-- `states()` — independent boolean-style props (`base` + named keys).
-
-```tsx
-import { states } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-
-const UtilityBox = styled.div(
-  states({
-    base: { mx: 4, my: 8, p: 16 },
-    disabled: { bg: 'background-disabled', color: 'text-disabled' },
-    center: { alignItems: 'center', justifyContent: 'center' },
-  })
-);
-```
-
-### `StyleProps` on React components
-
-```tsx
-import { states } from '@codecademy/gamut-styles';
-import { StyleProps } from '@codecademy/variance';
-import styled from '@emotion/styled';
-
-const panelShellStates = states({ base: { p: 4 }, dense: { p: 2 } });
-const PanelShell = styled.div(panelShellStates);
-
-export type PanelShellProps = StyleProps<typeof panelShellStates> & {
-  title: string;
-};
-
-export const Panel: React.FC<PanelShellProps> = ({ title, ...rest }) => (
-  <PanelShell {...rest}>{title}</PanelShell>
-);
-```
-
-Prefer `variant` / `states` over branching on raw `theme` fields inside styled template literals when the output is Emotion-managed CSS.
-
-## `useTheme()` — escape hatch
-
-Prefer `css()`, `system.*`, `variant()`, and `states()` for styling. Use `useTheme()` from `@emotion/react` when a token value must be read in plain JS (charts, canvas, third-party props), not as the default way to color DOM nodes.
-
-```tsx
-import { useTheme } from '@emotion/react';
-
-const Sparkline = () => {
-  const theme = useTheme();
-  return <path strokeWidth={theme.spacing[4]} d="M0 0 L10 10" />;
-};
-```
-
-## Key principles
-
-- Prefer semantic color keys in `css` / `variant` / `states` so ColorMode and theme switches apply; see `gamut-color-mode`.
-- Never hardcode hex in component styles — use tokens / semantic aliases.
-- Prefer `variant` / `states` for modes and toggles instead of ad-hoc `theme` interpolation in template literals.