@codecademy/gamut 68.6.1-alpha.c211a2.0 → 68.6.1-alpha.df4bce.0

package/agent-tools/guidelines/setup.md

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

@@ -0,0 +1,78 @@
+---
+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) |

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

@@ -0,0 +1,214 @@
+---
+name: gamut-accessibility
+description: Deep Gamut accessibility reference (component matrix, overlays, tips, live regions, checklists). Form wiring and validation UX live in **`gamut-forms`**. Universal HTML/ARIA/focus/color rules: always-loaded **`accessibility.mdc`** — read that first; this skill does not duplicate them.
+---
+
+# Gamut Accessibility
+
+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)
+
+---
+
+## 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

@@ -0,0 +1,138 @@
+---
+name: gamut-color-mode
+description: Use this skill when implementing light/dark behavior, semantic color aliases, the Background component for contrast-safe surfaces, or color-mode hooks in Gamut — including replacing hardcoded hex, fixing mode bugs, or reviewing color usage.
+---
+
+# Gamut ColorMode
+
+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.
+
+## `<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-forms/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: gamut-forms
+description: Implementing or auditing Gamut forms — FormGroup, ConnectedForm, ConnectedFormGroup, GridForm, react-hook-form wiring, labels, and accessible error/description regions. Pair with **`gamut-accessibility`** for non-form widgets and **`accessibility.mdc`** for universal HTML/ARIA rules.
+---
+
+# Gamut forms
+
+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)**.
+
+---
+
+## 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.