@codecademy/gamut 68.6.0 → 68.6.1-alpha.edab62.0

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

@@ -0,0 +1,239 @@
+---
+name: gamut-accessibility
+description: Use this skill when implementing or auditing accessibility in Gamut UIs — interactive widgets, forms, focus and keyboard flows, live regions, ARIA, or contrast — including fixes for screen readers, WCAG issues, or Gamut + React Aria patterns.
+---
+
+# Gamut Accessibility
+
+Source: `@codecademy/gamut` — interactive components wrap `react-aria-components`, `@react-aria/interactions`, and `react-focus-on`.
+
+---
+
+## General rules
+
+Use ARIA sparingly and only when it's the best option available.
+
+### 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>
+```
+
+---
+
+## How Gamut handles accessibility
+
+Gamut wraps React Aria for most interactive widget primitives. Roving tabindex, keyboard event handling, and ARIA attribute management are implemented for you in `<Tabs>`, `<Dialog>`, `<Modal>`, and form components. The developer's responsibilities are: supply accessible names, wire labels to inputs, and avoid overriding what the library already provides.
+
+---
+
+## Component reference
+
+### Button / IconButton
+
+`<Button>` renders a semantic `<button>` — no `role` needed. For icon-only buttons use `<IconButton>` with a `tip` prop; `tip` becomes the button's `aria-label`. Do not use `<div onClick>` or `<a>` without `href` for actions.
+
+```tsx
+// correct
+<IconButton icon={DeleteIcon} tip="Delete item" onClick={handleDelete} />
+
+// wrong — no accessible name, no keyboard semantics
+<div onClick={handleDelete}><DeleteIcon /></div>
+```
+
+### Dialog / Modal
+
+Both use `<FocusTrap>` (`react-focus-on`) internally. Focus locks to the dialog on open and returns to the trigger on close. Escape closes the dialog automatically.
+
+Always provide an accessible name. **Prefer `aria-labelledby`** when a visible heading or title defines the dialog name; use **`aria-label`** only when there is no suitable visible title string.
+
+```tsx
+<Dialog aria-labelledby="confirm-title">
+  <h2 id="confirm-title">Confirm deletion</h2>
+</Dialog>
+```
+
+### Alert
+
+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
+
+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.
+
+### Forms
+
+`<FormGroup>` + `<FormGroupLabel>` + input element is the complete accessible pattern:
+
+```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>
+```
+
+- `htmlFor` on `<FormGroupLabel>` and `id` on the input must match
+- `error` prop on `<FormGroup>` renders into an `aria-live="assertive"` region automatically
+- `description` prop renders into an `aria-live="polite"` region automatically
+- Do not add `aria-describedby` or `aria-errormessage` manually — `<FormGroup>` manages these
+
+**Checkbox / Radio**: `htmlFor` is required; the input is visually hidden via `screenReaderOnly` from `@codecademy/gamut-styles` but remains in the accessibility tree.
+
+### InfoTip
+
+Unlike `<IconButton>`, `<InfoTip>` has no automatic label fallback. Always provide `ariaLabel` or `ariaLabelledby` (camelCase props).
+
+```tsx
+<InfoTip ariaLabel="More information about billing" />
+```
+
+### SkipToContent
+
+Include `<SkipToContent>` as the first focusable element in the page shell. The main content region must have a matching `id` for the skip link to target.
+
+### Text (screen-reader-only)
+
+`<Text screenreader>` is the supported pattern for visually hidden but announced content. `<HiddenText>` is deprecated.
+
+```tsx
+<Text screenreader>Loading results…</Text>
+```
+
+---
+
+## Focus management
+
+`<FocusTrap>` is available for custom overlay patterns not covered by `<Dialog>` or `<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 Aria components do this automatically; custom implementations must store a ref to the trigger and call `.focus()` on unmount.
+
+---
+
+## 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
+
+Gamut's `<Tabs>` implements this via React Aria. If you build a custom composite widget, you must implement roving tabindex manually. A flat `tabIndex={0}` on every item is wrong — it puts every item in the sequential tab order, which is not the composite pattern.
+
+---
+
+## Device-independent events
+
+Use `click` for activation, not `mousedown`. `click` fires for both pointer and keyboard (Space/Enter on native buttons and links). `mousedown` is pointer-only and silently breaks keyboard access.
+
+For custom elements with `role="button"`, `click` alone is not sufficient — it only fires on keyboard when the element is a native `<button>` or `<a href>`. You must also handle `keydown` for Space and Enter explicitly:
+
+```tsx
+const handleKeyDown = (e: React.KeyboardEvent) => {
+  if (e.key === ' ' || e.key === 'Enter') {
+    e.preventDefault();
+    handleActivation();
+  }
+};
+```
+
+This is another reason to use `<Button>` — it handles this correctly and you don't.
+
+---
+
+## Live regions
+
+| Scenario | Pattern |
+|---|---|
+| Status updates, non-critical notifications | `aria-live="polite"` |
+| Form validation errors on submit | `aria-live="assertive"` |
+| Frequently updating counts or progress | `aria-live="polite"` + `aria-atomic="true"` |
+
+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.
+
+`<FormGroup>` already uses `aria-live="assertive"` for the `error` prop. Don't elevate unrelated inline errors to assertive — reserve it for interruptions the user didn't 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
+
+Gamut's `ColorMode` and semantic color tokens are designed to meet WCAG AA (4.5:1 for normal text, 3:1 for large text and non-text UI components). Hardcoding hex values bypasses this guarantee and breaks in dark mode. See the `gamut-color-mode` skill for semantic token usage.
+
+Non-text contrast (focus indicators, input borders, icon-only controls) requires a minimum 3:1 ratio against adjacent colors per WCAG 1.4.11.
+
+---
+
+## 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 are announced via live region
+- [ ] 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 | `<Button>` |
+| `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 `<Button>`, or add `keydown` handler |
+| `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` directly 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,99 @@
+---
+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 |
+
+**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.
+
+## `<ColorMode />`
+
+Wraps content in a color mode context. Nest these to create scoped mode regions.
+
+```tsx
+import { ColorMode } from '@codecademy/gamut-styles';
+
+// Explicit light or dark mode
+const Page = ({ children }) => (
+  <ColorMode mode="light">{children}</ColorMode>
+);
+
+// Follows the user's OS preference (prefers-color-scheme)
+const Page = ({ children }) => (
+  <ColorMode mode="system">{children}</ColorMode>
+);
+```
+
+**Props**: `mode="light" | "dark" | "system"`
+
+## `<Background />`
+
+Use `<Background>` — not raw `bg` prop — whenever you need a specific background color for a section (card, landing page, hero, etc.). It **automatically switches the color mode** to ensure the content inside meets contrast requirements.
+
+```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 accessible color context
+const Page = () => (
+  <Background bg="black">
+    <Background bg="paleGreen" />
+  </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 { useColorMode, useCurrentMode, usePrefersDarkMode } from '@codecademy/gamut-styles';
+
+// Returns [currentModeKey, currentModeColors, allModes]
+const [current, currentColors, modes] = useColorMode();
+
+// Returns just the active mode key: "light" | "dark"
+const current = useCurrentMode();
+
+// Returns 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 and their color variables | `useColorMode()` |
+| 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 raw `bg` prop for colored section backgrounds that contain text or interactive elements — use `<Background>` so contrast is guaranteed.
+- Do not manually toggle modes based on `usePrefersDarkMode()` — use `<ColorMode mode="system">` instead.

package/agent-tools/skills/gamut-system-props/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: gamut-system-props
+description: Use this skill when building or refactoring styled Gamut components that need layout, spacing, color, border, background, typography, positioning, grid, flex, shadow, or responsive values from @codecademy/gamut-styles — including composing system prop groups with variance.
+---
+
+# Gamut System Props
+
+Source: `@codecademy/gamut-styles` — [`variance/config.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/config.ts)
+
+## Overview
+
+System props are strongly-typed, theme-connected CSS prop groups from `@codecademy/gamut-styles`. They give styled components a consistent, responsive API. All props are built on top of `@codecademy/variance`.
+
+Each prop group has:
+- **`properties`**: The CSS properties it controls
+- **`scale`**: Token scale it's restricted to (theme colors, spacing values, etc.)
+- **`transform`**: Optional transform applied before output (e.g. `width={0.5}` → `width: 50%`)
+
+## Basic usage
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+// Apply a single group
+const Box = styled.div(system.layout);
+
+// Compose multiple groups
+import { variance } from '@codecademy/variance';
+
+const FlexBox = styled.div(
+  variance.compose(system.layout, system.flex, system.space)
+);
+
+<FlexBox display="flex" p={16} gap={8} width="100%" />;
+```
+
+## Prop groups
+
+### `system.layout`
+
+Controls dimensions, display, overflow, and container behavior.
+
+```tsx
+const Box = styled.div(system.layout);
+
+<Box display="flex" width="50%" height="300px" verticalAlign="middle" />;
+```
+
+Key props: `display`, `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `overflow`, `overflowX`, `overflowY`, `verticalAlign`
+
+### `system.space`
+
+Margin and padding using the theme's spacing scale. Supports logical properties (switches based on `useLogicalProperties` in `<GamutProvider>`).
+
+```tsx
+const Box = styled.div(system.space);
+
+// Single value
+<Box p={8} m={16} />;
+
+// Responsive array syntax: [mobile, tablet, desktop]
+<Box my={[16, 24, 32]} px={[8, 16]} />;
+```
+
+Key props: `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`, `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`
+
+### `system.color`
+
+Foreground, background, and border colors restricted to the theme's color palette.
+
+```tsx
+const Box = styled.div(system.color);
+
+<Box bg="navy" textColor="gray-100" borderColor="blue" />;
+```
+
+Key props: `bg` (background-color shorthand), `textColor`, `borderColor`
+
+### `system.typography`
+
+Text styling connected to theme typography scales.
+
+```tsx
+const Text = styled.p(system.typography);
+
+<Text fontSize={16} fontFamily="accent" textTransform="uppercase" lineHeight={1.5} />;
+```
+
+Key props: `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `textAlign`, `textTransform`, `textDecoration`, `letterSpacing`, `whiteSpace`
+
+### `system.border`
+
+Border width, style, radius, and color.
+
+Key props: `border`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `borderRadius`, `borderWidth`, `borderStyle`
+
+### `system.background`
+
+Background image, size, position, and repeat (for images/patterns — use `system.color` for solid background colors).
+
+```tsx
+import myBg from './myBg.png';
+
+const Box = styled.div(system.background);
+
+<Box background={`url(${myBg})`} backgroundSize="cover" backgroundPosition="center" />;
+```
+
+Key props: `background`, `backgroundImage`, `backgroundSize`, `backgroundPosition`, `backgroundRepeat`
+
+### `system.flex`
+
+Flexbox child and container properties.
+
+Key props: `flex`, `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `flexBasis`, `alignItems`, `alignSelf`, `justifyContent`, `justifySelf`, `gap`, `rowGap`, `columnGap`
+
+### `system.grid`
+
+CSS Grid container and child properties.
+
+Key props: `gridTemplateColumns`, `gridTemplateRows`, `gridTemplateAreas`, `gridColumn`, `gridRow`, `gridArea`, `gridAutoFlow`
+
+### `system.positioning`
+
+Position and offset properties.
+
+```tsx
+const Overlay = styled.div(
+  variance.compose(system.layout, system.positioning)
+);
+
+<Overlay position="absolute" top={0} left={0} width="100%" height="100%" />;
+```
+
+Key props: `position`, `top`, `right`, `bottom`, `left`, `zIndex`
+
+### `system.shadow`
+
+Box and text shadow.
+
+Key props: `boxShadow`, `textShadow`
+
+## Responsive values
+
+All system props accept an **array of values** for responsive breakpoints (Gamut uses a mobile-first approach):
+
+```tsx
+// [mobile, tablet, desktop]
+<Box width={['100%', '50%', '33%']} p={[8, 16, 24]} />;
+```
+
+## Using `css()` for styled definitions
+
+For static styles in styled components, use `css()` from `@codecademy/gamut-styles`:
+
+```tsx
+import { css } from '@codecademy/gamut-styles';
+import styled from '@emotion/styled';
+
+// Static color using raw token
+const Box = styled.div(css({ bg: 'navy-400', p: 4 }));
+
+// Semantic color (adapts to color mode)
+const Text = styled.div(css({ color: 'primary', p: 4 }));
+```
+
+## Key principles
+
+- Compose `system.*` groups via `variance.compose()` — don't apply multiple groups by chaining `styled.div(system.a)(system.b)`.
+- Use `system.color` (semantic aliases) for colors that need to adapt to dark/light mode; use raw tokens only for colors that should stay fixed regardless of mode.
+- Use `system.space` values that reference the spacing scale rather than arbitrary pixel values to maintain visual rhythm.
+- For background images/patterns use `system.background`; for solid background colors that may switch mode use `<Background>` from ColorMode.

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

@@ -0,0 +1,181 @@
+---
+name: gamut-testing
+description: Use this skill when writing or fixing unit tests for React components that use Gamut — setupRtl, MockGamutProvider, ColorMode in tests, emotion matchers, or removing jest.mock of @codecademy/gamut / gamut-styles.
+---
+
+# Gamut Testing
+
+Source: `@codecademy/gamut-tests` — [`index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-tests/src/index.tsx)
+
+---
+
+## Core rule: never mock Gamut components
+
+Do not use `jest.mock('@codecademy/gamut')` or manually mock individual Gamut components in test files. This silently bypasses emotion's theme context, produces tests that can't catch real rendering failures, and requires every test file to maintain its own fragile mock list.
+
+Use `MockGamutProvider` or `setupRtl` — both are designed for exactly this purpose.
+
+---
+
+## What `MockGamutProvider` does
+
+`MockGamutProvider` wraps `GamutProvider` with test-safe settings:
+
+- `useCache={false}` — disables emotion's style injection cache so styles are predictable across tests
+- `useGlobals={false}` — disables global CSS (Reboot, Typography, CSS Variables) to avoid side effects between test files
+- `theme={coreTheme}` — provides the full Gamut token set so styled components resolve correctly
+
+You should never construct a `GamutProvider` manually in a test. Use `MockGamutProvider`.
+
+---
+
+## Decision guide
+
+| Scenario | Use |
+|---|---|
+| Standard component unit test | `setupRtl` from `@codecademy/gamut-tests` |
+| Test that needs to vary `useLogicalProperties` | `render` + `MockGamutProvider` directly |
+| Test that needs `ColorMode` context | `render` + `MockGamutProvider` + `<ColorMode>` |
+| Visual test mock / Storybook wrapper | `MockGamutProvider` directly |
+
+---
+
+## `setupRtl` — preferred pattern
+
+`setupRtl` from `@codecademy/gamut-tests` wraps `setupRtl` from `component-test-setup` with `MockGamutProvider` automatically. You do not need to add `MockGamutProvider` yourself.
+
+```tsx
+import { setupRtl } from '@codecademy/gamut-tests';
+
+import { MyComponent } from '../MyComponent';
+
+const renderView = setupRtl(MyComponent, {
+  label: 'Default label',
+  onClick: jest.fn(),
+});
+
+it('renders the label', () => {
+  const { view } = renderView();
+  expect(view.getByText('Default label')).toBeInTheDocument();
+});
+
+it('accepts prop overrides', () => {
+  const { view } = renderView({ label: 'Override' });
+  expect(view.getByText('Override')).toBeInTheDocument();
+});
+```
+
+`renderView` returns `{ view, props, update }`:
+- `view` — RTL `RenderResult` (getByRole, getByText, etc.)
+- `props` — the resolved props passed to the component (useful for asserting on jest.fn() mocks)
+- `update` — re-render with updated props without remounting
+
+### Accessing mock functions via `props`
+
+```tsx
+it('calls onClick when clicked', async () => {
+  const { view, props } = renderView();
+  await userEvent.click(view.getByRole('button'));
+  expect(props.onClick).toHaveBeenCalled();
+});
+```
+
+---
+
+## `MockGamutProvider` directly — when you need more control
+
+Use `render` + `MockGamutProvider` when `setupRtl` doesn't give enough control over the wrapper — for example, when testing both logical and physical CSS property modes, or when adding `ColorMode`.
+
+```tsx
+import { MockGamutProvider } from '@codecademy/gamut-tests';
+import { render } from '@testing-library/react';
+
+it('uses logical properties when enabled', () => {
+  const { container } = render(
+    <MockGamutProvider useLogicalProperties>
+      <MyComponent width="200px" />
+    </MockGamutProvider>
+  );
+  // assert on inlineSize rather than width
+});
+```
+
+### Testing both logical and physical property modes
+
+```tsx
+describe.each([
+  { useLogicalProperties: true, widthProp: 'inlineSize' },
+  { useLogicalProperties: false, widthProp: 'width' },
+])(
+  'useLogicalProperties=$useLogicalProperties',
+  ({ useLogicalProperties, widthProp }) => {
+    it(`uses ${widthProp}`, () => {
+      const { container } = render(
+        <MockGamutProvider useLogicalProperties={useLogicalProperties}>
+          <MyComponent width="200px" />
+        </MockGamutProvider>
+      );
+      expect(container.firstChild).toHaveStyle({ [widthProp]: '200px' });
+    });
+  }
+);
+```
+
+---
+
+## Emotion style assertions
+
+Install `@emotion/jest` matchers once per test file to enable CSS-in-JS assertions:
+
+```tsx
+import { matchers } from '@emotion/jest';
+
+expect.extend(matchers);
+```
+
+Then assert on styles:
+
+```tsx
+expect(element).toHaveStyle({ borderRadius: '2px' });
+expect(element).toHaveStyleRule('padding', '1rem');
+```
+
+Use `theme` from `@codecademy/gamut-styles` to avoid hardcoding token values:
+
+```tsx
+import { theme } from '@codecademy/gamut-styles';
+
+expect(element).toHaveStyle({ columnGap: theme.spacing[40] });
+```
+
+---
+
+## Visual test wrappers
+
+When creating mock components for visual tests or Storybook, wrap with `MockGamutProvider` and `ColorMode`:
+
+```tsx
+import { MockGamutProvider } from '@codecademy/gamut-tests';
+import { ColorMode } from '@codecademy/gamut-styles';
+
+export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (props) => (
+  <MockGamutProvider>
+    <ColorMode mode="light">
+      <MyComponent {...props} />
+    </ColorMode>
+  </MockGamutProvider>
+);
+```
+
+---
+
+## Common anti-patterns
+
+| Anti-pattern | Fix |
+|---|---|
+| `jest.mock('@codecademy/gamut', () => ({ ... }))` | Remove mock; use `setupRtl` or `MockGamutProvider` |
+| `jest.mock('@codecademy/gamut-styles', ...)` | Remove mock; `MockGamutProvider` handles theme context |
+| Wrapping with `GamutProvider` directly in tests | Use `MockGamutProvider` — it sets `useCache={false}` and `useGlobals={false}` |
+| Repeating `render(<MockGamutProvider>...</MockGamutProvider>)` in every test | Extract with `setupRtl`; define `renderView` once above the `describe` block |
+| One `setupRtl` call per `it` block | Define `renderView` once outside `describe`, call it inside each `it` |
+| Asserting on raw CSS token strings | Import `theme` from `@codecademy/gamut-styles` and use `theme.spacing[n]`, `theme.fontSize`, etc. |