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

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

@@ -1,17 +1,20 @@
 ---
 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.
+description: Use this skill when building or refactoring styled Gamut components that need layout, spacing, color, border, background, typography, positioning, grid, flex, shadow, list styles, 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)
+Source: `@codecademy/gamut-styles` — [`variance/config.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/config.ts) (definitions) and [`variance/props.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/props.ts) (`variance.create` groups). **`Box`**, **`FlexBox`**, and **`GridBox`** compose the same groups in [`packages/gamut/src/Box/props.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Box/props.ts).
+
+**See also:** [Styleguide — Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx) (semantic colors, `variant` / `states`, `StyleProps`, responsive examples) and Storybook [Responsive properties](https://gamut.codecademy.com/storybook/?path=/docs-foundations-system-responsive-properties--page).
 
 ## 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%`)
@@ -39,7 +42,7 @@ const FlexBox = styled.div(
 
 ### `system.layout`
 
-Controls dimensions, display, overflow, and container behavior.
+Controls dimensions, display, overflow, and container behavior. This group also carries **flex/grid item** props used when laying out children: `flexGrow`, `flexShrink`, `flexBasis`, `order`, `gridColumn`, `gridRow`, `gridColumnStart`, `gridRowStart`, `gridColumnEnd`, `gridRowEnd`, `alignSelf`, `justifySelf`, `gridArea`.
 
 ```tsx
 const Box = styled.div(system.layout);
@@ -47,7 +50,7 @@ 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`
+Key props: `containerType`, `display`, `direction`, `dimensions`, `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight`, `overflow`, `overflowX`, `overflowY`, `verticalAlign`, plus the item props above (see `config.ts` for the full map).
 
 ### `system.space`
 
@@ -59,7 +62,7 @@ const Box = styled.div(system.space);
 // Single value
 <Box p={8} m={16} />;
 
-// Responsive array syntax: [mobile, tablet, desktop]
+// Responsive (array / object — see Responsive values)
 <Box my={[16, 24, 32]} px={[8, 16]} />;
 ```
 
@@ -72,10 +75,10 @@ Foreground, background, and border colors restricted to the theme's color palett
 ```tsx
 const Box = styled.div(system.color);
 
-<Box bg="navy" textColor="gray-100" borderColor="blue" />;
+<Box bg="navy" color="gray-900" textColor="gray-100" borderColor="blue" />;
 ```
 
-Key props: `bg` (background-color shorthand), `textColor`, `borderColor`
+Key props: `color`, `textColor` (both set CSS `color`), `bg`, `borderColor`, plus directional `borderColor*` variants — see `config.ts` for the full set.
 
 ### `system.typography`
 
@@ -84,16 +87,22 @@ Text styling connected to theme typography scales.
 ```tsx
 const Text = styled.p(system.typography);
 
-<Text fontSize={16} fontFamily="accent" textTransform="uppercase" lineHeight={1.5} />;
+<Text
+  fontSize={16}
+  fontFamily="accent"
+  fontStyle="italic"
+  textTransform="uppercase"
+  lineHeight="base"
+/>;
 ```
 
-Key props: `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `textAlign`, `textTransform`, `textDecoration`, `letterSpacing`, `whiteSpace`
+Key props: `fontFamily`, `fontSize`, `fontWeight`, `fontStyle`, `lineHeight`, `textAlign`, `textTransform`, `textDecoration`, `letterSpacing`, `whiteSpace` — prefer **`lineHeight`** scale keys (`base`, `title`, `spacedTitle`) from the theme over raw numbers when possible.
 
 ### `system.border`
 
-Border width, style, radius, and color.
+Border width, style, radius, and color. Many **logical shorthands** exist (`borderX`, `borderColorY`, `borderRadiusTop`, …); see `config.ts` for the full map.
 
-Key props: `border`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `borderRadius`, `borderWidth`, `borderStyle`
+Key props (non-exhaustive): `border`, `borderTop`, `borderRight`, `borderBottom`, `borderLeft`, `borderRadius`, `borderWidth`, `borderStyle`
 
 ### `system.background`
 
@@ -104,7 +113,11 @@ import myBg from './myBg.png';
 
 const Box = styled.div(system.background);
 
-<Box background={`url(${myBg})`} backgroundSize="cover" backgroundPosition="center" />;
+<Box
+  background={`url(${myBg})`}
+  backgroundSize="cover"
+  backgroundPosition="center"
+/>;
 ```
 
 Key props: `background`, `backgroundImage`, `backgroundSize`, `backgroundPosition`, `backgroundRepeat`
@@ -113,27 +126,25 @@ Key props: `background`, `backgroundImage`, `backgroundSize`, `backgroundPositio
 
 Flexbox child and container properties.
 
-Key props: `flex`, `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `flexBasis`, `alignItems`, `alignSelf`, `justifyContent`, `justifySelf`, `gap`, `rowGap`, `columnGap`
+Key props (non-exhaustive): `flex`, `flexDirection`, `flexWrap`, `flexGrow`, `flexShrink`, `flexBasis`, `alignItems`, `alignContent`, `alignSelf`, `justifyContent`, `justifyItems`, `justifySelf`, `gap`, `rowGap`, `columnGap`
 
 ### `system.grid`
 
 CSS Grid container and child properties.
 
-Key props: `gridTemplateColumns`, `gridTemplateRows`, `gridTemplateAreas`, `gridColumn`, `gridRow`, `gridArea`, `gridAutoFlow`
+Key props (non-exhaustive): `gridTemplateColumns`, `gridTemplateRows`, `gridTemplateAreas`, `gridColumn`, `gridRow`, `gridArea`, `gridAutoFlow`, `gridAutoColumns`, `gridAutoRows`, `gap`, `rowGap`, `columnGap`
 
 ### `system.positioning`
 
-Position and offset properties.
+Position and offset properties. Inset shorthands use **`transformSize`**; physical vs logical edges follow **`useLogicalProperties`**.
 
 ```tsx
-const Overlay = styled.div(
-  variance.compose(system.layout, system.positioning)
-);
+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`
+Key props: `position`, `inset`, `top`, `right`, `bottom`, `left`, `zIndex`, `opacity`
 
 ### `system.shadow`
 
@@ -141,18 +152,35 @@ Box and text shadow.
 
 Key props: `boxShadow`, `textShadow`
 
+### `system.list`
+
+List marker styling (`listStyle`, `listStyleType`, `listStylePosition`, `listStyleImage`). Included on **`Box`** alongside the other composed groups.
+
 ## Responsive values
 
-All system props accept an **array of values** for responsive breakpoints (Gamut uses a mobile-first approach):
+All system props accept responsive values **mobile-first** (min-width queries). Two shapes are supported:
+
+### Object syntax
+
+Keys are breakpoints; **`_`** is the base (no breakpoint). Includes `xs`, `sm`, `md`, `lg`, `xl`, and container keys `c_xs` … `c_xl`.
 
 ```tsx
-// [mobile, tablet, desktop]
-<Box width={['100%', '50%', '33%']} p={[8, 16, 24]} />;
+<Box width={{ _: '100%', sm: '50%', md: '33%' }} px={{ _: 8, md: 16 }} />
 ```
 
+### Array syntax
+
+Slots map in order to: base, `xs`, `sm`, `md`, `lg`, `xl`, then `c_xs` … `c_xl`. Leave a slot **empty** (or use `undefined`) to skip a breakpoint.
+
+```tsx
+<Box width={['100%', , '50%']} p={[8, 16, , 24]} />
+```
+
+Full typings and behavior: [Responsive properties (Storybook)](https://gamut.codecademy.com/storybook/?path=/docs-foundations-system-responsive-properties--page).
+
 ## Using `css()` for styled definitions
 
-For static styles in styled components, use `css()` from `@codecademy/gamut-styles`:
+For static styles in styled components, use **`css()`** from `@codecademy/gamut-styles` (same implementation as **`system.css`** on the `system` namespace).
 
 ```tsx
 import { css } from '@codecademy/gamut-styles';
@@ -168,6 +196,8 @@ 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.
+- Prefer **semantic color names** on `system.color` (e.g. `bg="background"`, `textColor="text"`) so values track **ColorMode**; use raw palette keys only when the design should stay fixed across modes.
+- Use **`bg`** with semantic tokens for most mode-aware surfaces; use **`<Background>`** from `@codecademy/gamut-styles` when you need its **contrast- and mode-aware** behavior, not for every tinted panel.
+- Use `system.space` values on the **spacing scale** rather than arbitrary pixel strings to keep rhythm consistent.
+- For background images/patterns use `system.background`; for solid fills use `system.color` / semantic **`bg`** (or **`Background`** when that component’s behavior is required).
+- For reusable **variants** or **boolean states** on styled primitives, use **`variant`** / **`states`** from `@codecademy/gamut-styles` and expose props with **`StyleProps<typeof …>`** from `@codecademy/variance` — see [Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx).

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use this skill when writing or fixing unit tests for React components that use Gamut — prefer setupRtl from @codecademy/gamut-tests, harness patterns for useLogicalProperties and ColorMode, RTL/dir testing, emotion matchers, or removing jest.mock of @codecademy/gamut / gamut-styles.
 ---
 
 # Gamut Testing
@@ -9,40 +9,34 @@ Source: `@codecademy/gamut-tests` — [`index.tsx`](https://github.com/Codecadem
 
 ---
 
-## 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
+## What `MockGamutProvider` does (under `setupRtl`)
 
-`MockGamutProvider` wraps `GamutProvider` with test-safe settings:
+`MockGamutProvider` forwards to `GamutProvider` with:
 
-- `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
+- `useCache={false}` — stable Emotion output across tests
+- `useGlobals={false}` — no global Reboot/Typography bleed between files
+- `theme={theme}` — full token theme for styled components
+- Optional **`useLogicalProperties`** — forwarded for logical vs physical CSS in variance
 
-You should never construct a `GamutProvider` manually in a test. Use `MockGamutProvider`.
+You normally **do not** import `MockGamutProvider` for plain component tests; `setupRtl` already wraps the **component under test** once. Import it **inside a harness** when the SUT needs a non-default provider flag or extra wrappers (see below).
 
 ---
 
 ## 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 |
+| Scenario                                                         | Prefer                                                                                                                                                                                                                                     |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Default unit test for a Gamut (or app) component                 | **`setupRtl(Component, defaultProps)`** once per file / describe                                                                                                                                                                           |
+| Vary **`useLogicalProperties`** across cases                     | **Harness** that accepts `useLogicalProperties` and wraps **`MockGamutProvider`**, then **`setupRtl(Harness, defaults)`**; pass overrides per `it` / `describe.each`                                                                       |
+| Need **`ColorMode`** (or other context) around the SUT           | **Harness** with `<ColorMode>` inside the tree, then **`setupRtl(Harness)`** — no need for raw `render` unless you are testing the provider itself                                                                                         |
+| **`dir` / RTL** behavior (e.g. mirrored layout, `useElementDir`) | Keep using **`setupRtl`** for the component; set **`document.documentElement.setAttribute('dir', 'rtl' \| 'ltr')`** (and scroll/viewport stubs if needed) in **`beforeEach` / `afterEach`**; reset `dir` after tests so suites do not leak |
+| Storybook-only mock, chromatic-style wrapper, or non-RTL harness | **`MockGamutProvider`** (± **`ColorMode`**) in the exported wrapper component                                                                                                                                                              |
 
 ---
 
-## `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.
+## `setupRtl` — primary pattern
 
 ```tsx
 import { setupRtl } from '@codecademy/gamut-tests';
@@ -66,13 +60,21 @@ it('accepts prop overrides', () => {
 ```
 
 `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
+
+- **`view`** — RTL `RenderResult` (`getByRole`, `getByLabelText`, `getByText`, …)
+- **`props`** — resolved props (handy for `jest.fn()` assertions)
+- **`update`** — re-render with new props without remounting
+
+### Query and interaction habits (RTL)
+
+- Prefer **`getByRole`**, **`getByLabelText`**, and accessible names over CSS selectors or snapshotting class strings unless you are explicitly testing styling.
+- Prefer **`@testing-library/user-event`** over `fireEvent` when simulating real input (import `userEvent` from **`@testing-library/user-event`** in current major versions).
 
 ### Accessing mock functions via `props`
 
 ```tsx
+import userEvent from '@testing-library/user-event';
+
 it('calls onClick when clicked', async () => {
   const { view, props } = renderView();
   await userEvent.click(view.getByRole('button'));
@@ -82,50 +84,84 @@ it('calls onClick when clicked', async () => {
 
 ---
 
-## `MockGamutProvider` directly — when you need more control
+## Harness + `setupRtl` when the wrapper is not default
 
-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`.
+`setupRtl` always wraps with **`MockGamutProvider`** with default props. To vary **`useLogicalProperties`**, add **`ColorMode`**, or compose other providers, define a **small harness** and pass **`setupRtl`** that harness — still one `renderView` factory, still `props` / `update` ergonomics.
+
+### Varying `useLogicalProperties` (logical vs physical CSS)
 
 ```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
-});
-```
+import { MockGamutProvider, setupRtl } from '@codecademy/gamut-tests';
 
-### Testing both logical and physical property modes
+import { MyComponent } from '../MyComponent';
+
+type HarnessProps = React.ComponentProps<typeof MyComponent> & {
+  useLogicalProperties?: boolean;
+};
+
+const MyHarness = ({ useLogicalProperties, ...rest }: HarnessProps) => (
+  <MockGamutProvider useLogicalProperties={useLogicalProperties}>
+    <MyComponent {...rest} />
+  </MockGamutProvider>
+);
+
+const renderView = setupRtl(MyHarness, { width: '200px' });
 
-```tsx
 describe.each([
-  { useLogicalProperties: true, widthProp: 'inlineSize' },
-  { useLogicalProperties: false, widthProp: 'width' },
+  { useLogicalProperties: true as const, widthProp: 'inlineSize' as const },
+  { useLogicalProperties: false as const, widthProp: 'width' as const },
 ])(
   'useLogicalProperties=$useLogicalProperties',
   ({ useLogicalProperties, widthProp }) => {
     it(`uses ${widthProp}`, () => {
-      const { container } = render(
-        <MockGamutProvider useLogicalProperties={useLogicalProperties}>
-          <MyComponent width="200px" />
-        </MockGamutProvider>
-      );
-      expect(container.firstChild).toHaveStyle({ [widthProp]: '200px' });
+      const { view } = renderView({ useLogicalProperties });
+      expect(view.getByTestId('my-component-root')).toHaveStyle({
+        [widthProp]: '200px',
+      });
     });
   }
 );
 ```
 
+The outer `setupRtl` wrapper adds a default **`MockGamutProvider`**; the harness’s inner **`MockGamutProvider`** sets **`useLogicalProperties`** for the subtree under test (nested `GamutProvider` / theme is the nearest one Emotion and variance see).
+
+### `ColorMode` without abandoning `setupRtl`
+
+```tsx
+import { ColorMode } from '@codecademy/gamut-styles';
+import { setupRtl } from '@codecademy/gamut-tests';
+
+const DarkHarness = (props: React.ComponentProps<typeof MyComponent>) => (
+  <ColorMode mode="dark">
+    <MyComponent {...props} />
+  </ColorMode>
+);
+
+const renderDark = setupRtl(DarkHarness, { title: 'Hi' });
+```
+
+Use **`MockGamutProvider`** only inside the harness if you also need a non-default Gamut flag **and** `ColorMode` in the same tree; otherwise **`setupRtl(DarkHarness)`** is enough.
+
+---
+
+## Raw `render` + `MockGamutProvider` — rare
+
+Reserve **`render` from `@testing-library/react`** + manual **`MockGamutProvider`** for cases where a harness would be more obscure than a single inline tree (e.g. highly dynamic one-off trees). If the same wrapper appears more than once, switch to a **harness + `setupRtl`**.
+
+---
+
+## RTL / `dir` and document-level behavior
+
+Some components (e.g. overlays that call **`useElementDir`**) resolve direction from **`document.documentElement`** when there is no real target node. For those tests:
+
+- Set **`document.documentElement.setAttribute('dir', 'rtl')`** (or `'ltr'`) around the scenario, **`unmount`** between LTR and RTL assertions when re-rendering, and restore **`dir`** in **`afterEach`** so other tests start clean.
+- Combine with the harness pattern above when **`useLogicalProperties`** affects which longhand wins (`left` vs `insetInlineStart`, etc.).
+
 ---
 
 ## Emotion style assertions
 
-Install `@emotion/jest` matchers once per test file to enable CSS-in-JS assertions:
+Install **`@emotion/jest`** matchers if you absolutely need to enable CSS-in-JS assertions:
 
 ```tsx
 import { matchers } from '@emotion/jest';
@@ -140,7 +176,7 @@ expect(element).toHaveStyle({ borderRadius: '2px' });
 expect(element).toHaveStyleRule('padding', '1rem');
 ```
 
-Use `theme` from `@codecademy/gamut-styles` to avoid hardcoding token values:
+Use **`theme`** from **`@codecademy/gamut-styles`** instead of hardcoding token strings:
 
 ```tsx
 import { theme } from '@codecademy/gamut-styles';
@@ -150,15 +186,17 @@ expect(element).toHaveStyle({ columnGap: theme.spacing[40] });
 
 ---
 
-## Visual test wrappers
+## Visual test wrappers and Storybook
 
-When creating mock components for visual tests or Storybook, wrap with `MockGamutProvider` and `ColorMode`:
+Exported mocks and stories may wrap with **`MockGamutProvider`** and **`ColorMode`** explicitly (no `setupRtl` in Storybook):
 
 ```tsx
 import { MockGamutProvider } from '@codecademy/gamut-tests';
 import { ColorMode } from '@codecademy/gamut-styles';
 
-export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (props) => (
+export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (
+  props
+) => (
   <MockGamutProvider>
     <ColorMode mode="light">
       <MyComponent {...props} />
@@ -171,11 +209,13 @@ export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (pr
 
 ## 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. |
+| Anti-pattern                                                          | Fix                                                                                                        |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `jest.mock('@codecademy/gamut', () => ({ ... }))`                     | Remove; use **`setupRtl`** (or harness + **`setupRtl`**)                                                   |
+| `jest.mock('@codecademy/gamut-styles', ...)`                          | Remove; **`MockGamutProvider`** / **`setupRtl`** supplies theme                                            |
+| **`GamutProvider`** in test files                                     | Use **`MockGamutProvider`** only when building a harness or story; default tests go through **`setupRtl`** |
+| **`import { setupRtl } from 'component-test-setup'`** in Gamut / apps | Import **`setupRtl` from `@codecademy/gamut-tests`** so **`MockGamutProvider`** is applied                 |
+| Repeated **`render(<MockGamutProvider>…`**                            | **Harness + `setupRtl`**, or a shared **`renderView`** factory                                             |
+| One **`setupRtl`** call per **`it`**                                  | Define **`renderView`** once outside **`describe`**, call it inside each **`it`**                          |
+| Asserting raw CSS strings for tokens                                  | Use **`theme`** from **`@codecademy/gamut-styles`**                                                        |
+| Leaking **`dir="rtl"`** between tests                                 | Reset **`document.documentElement`** in **`afterEach`**                                                    |

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

@@ -1,123 +1,75 @@
 ---
 name: gamut-typography
-description: Use this skill when creating or reviewing UI text in Gamut apps — headlines, body, captions, labels, code snippets, or text-heavy layouts — even if the user does not name fonts or tokens. Covers Apercu Pro, Suisse Intl Mono, scale, line heights, line length, and alignment.
+description: Use this skill when creating or reviewing UI text in Gamut apps — headlines, body, captions, labels, code snippets, or text-heavy layouts. Covers theme-specific stacks (Core Apercu/Suisse vs Percipio/LX Skillsoft), fontSize / lineHeight tokens, semantic fontWeight title (700 vs 500), line length, and alignment for Codecademy-branded surfaces.
 ---
 
 # Gamut Typography
 
-> **Scope**: This skill covers typography for **Codecademy products** using the Core, Admin, or Platform themes (Apercu + Suisse). Percipio uses Roboto for all type — see `DESIGN.md` for Percipio-specific guidance. LX Studio uses Hanken Grotesk in place of both Apercu and Suisse.
+**Implementation source of truth:** [`packages/gamut-styles/src/variables/typography.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variables/typography.ts) and themes under [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes). Agent guideline: [foundations/typography.md](../../guidelines/foundations/typography.md).
 
-## Typefaces
+## Scope by theme
 
-Codecademy products use two typefaces:
+| Themes                            | Fonts                                                                                                                                    | `fontWeight.title` |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| **Core**, **Admin**, **Platform** | `base` → Apercu stack; `accent` → Suisse + Apercu stack                                                                                  | **700**            |
+| **Percipio**, **LX Studio**       | `base` → Skillsoft Text; `accent` → Skillsoft Sans; Percipio `monospace` → Roboto Mono; LX `monospace` matches Core stack per theme file | **500**            |
 
-### Apercu Pro (`fontFamily: "base"`)
-
-The primary typeface. Geometric-ish, humanist sans-serif. Use for:
-- Headlines (Bold weight)
-- Body / paragraph text (Regular weight)
-- UI labels, menu items (Regular weight)
-- Emphasis within body copy (Italic — **not** Bold)
-
-**Rules:**
-- Do not use Bold to emphasize text within a Regular-weight paragraph. Use Italic instead.
-- Set with generous line-height for body text: **150–175%** of the type size (e.g. 16px type → 24–28px line-height).
-- Headlines should use **100–110%** line-height to appear intentional and grouped.
-- Text should be **left-aligned** by default.
-
-### Suisse Intl Mono (`fontFamily: "accent"`)
-
-Monospace accent typeface. Use sparingly for:
-- Code snippets and inline code
-- Numbers, figures, and statistics
-- Captions and labels that reference technical/engineering context
-- Enumerated lists
-- Quotations in a technical voice
-
-**Rules:**
-- Every character is the same width — avoid long paragraph-length prose in Suisse.
-- It reads large for its point size: **reduce the size by ~10–15%** relative to Apercu text at the same visual scale (e.g. 14px Suisse ≈ 16px Apercu visually).
-- Requires extra line-height to remain readable.
+Use **`fontWeight="title"`** for headlines / emphasis roles — never hardcode **`700`** on Percipio/LX unless SPECIFICALLY noted in Figma designs.
 
 ## Font size scale (`fontSize`)
 
-Sizes are accessed via the theme's `fontSize` scale. Common keys:
+Theme keys: `64`, `44`, `34`, `26`, `22`, `20`, `18`, `16`, `14`.
 
 ```tsx
 import { css } from '@codecademy/gamut-styles';
 import styled from '@emotion/styled';
-
-// Via system props
 import { system } from '@codecademy/gamut-styles';
-const Text = styled.p(system.typography);
-<Text fontSize={16} />;
 
-// Via css() utility
-const Box = styled.div(css({ fontSize: 14 }));
+const Paragraph = styled.p(system.typography);
+<Paragraph fontSize={16} lineHeight="base" />;
 
-// Via theme directly (outside styled components)
-import { theme } from '@codecademy/gamut-styles';
-const size = theme.fontSize[16];
+const Styled = styled.div(css({ fontSize: 14, fontFamily: 'base' }));
 ```
 
-## Line heights (`lineHeight`)
+## Line height (`lineHeight`)
 
-Line heights are limited to **multiples of 4px**. Type boxes are placed on an **8px placement grid**.
-
-Guidelines:
-- Body text: 150–175% of font size
-- Headlines: 100–110% of font size
+Tokens: **`base`** (1.5), **`spacedTitle`** (1.3), **`title`** (1.2). Prefer tokens over raw decimals. Only specify `lineHeight` when specified by design.
 
 ## Line length
 
-Controlling line length is essential for readability:
-
-| Context | Target |
-|---|---|
-| Single-column body text | ~66 characters (max 85) |
-| Multi-column layouts | ≤50 characters per line |
-| Minimum | 45 characters |
-
-**How to control line length**: Start with the right text style for the design, then adjust the width or column count of the text container.
-
-## Alignment
-
-- **Left-align** paragraphs by default — this is easiest to read and supports grid alignment.
-- **Center-align** only for short marketing headlines or specific interface components with brief text.
-- **Never right-align** text in normal circumstances (exceptions: numbers, equations).
-- Do not adjust letter-spacing.
+| Context            | Target                   |
+| ------------------ | ------------------------ |
+| Single-column body | ~66 characters (max ~85) |
+| Multi-column       | ≤50 characters per line  |
+| Minimum            | ~45 characters           |
 
 ## Accessing typography tokens
 
 ```tsx
-// System props (recommended for styled components)
 import { system } from '@codecademy/gamut-styles';
 import { variance } from '@codecademy/variance';
 
-const Heading = styled.h2(
-  variance.compose(system.typography, system.space)
-);
+const Heading = styled.h2(variance.compose(system.typography, system.space));
 
-<Heading fontSize={24} fontFamily="base" fontWeight="bold" lineHeight={1.1} mb={8} />;
+<Heading
+  fontSize={26}
+  fontFamily="base"
+  fontWeight="title"
+  lineHeight="title"
+  mb={8}
+/>;
 
-// css() utility (recommended for static styles)
 import { css } from '@codecademy/gamut-styles';
 
 const Caption = styled.span(
-  css({ fontFamily: 'accent', fontSize: 12, color: 'secondary' })
+  css({ fontFamily: 'accent', fontSize: 14, color: 'text-secondary' })
 );
-
-// Theme object (outside styled components)
-import { theme } from '@codecademy/gamut-styles';
-import { css as emotionCss } from '@emotion/react';
-
-const myStyles = emotionCss`
-  font-size: ${theme.fontSize[14]};
-`;
 ```
 
-## Semantic vs. visual sizing
+Prefer `<Text>` from `@codecademy/gamut` with `variant` / `as` — see Storybook [Typography / Text](https://gamut.codecademy.com/?path=/docs-typography-text--docs).
+
+## Semantic vs visual headings
 
-- The term **"Title"** distinguishes visual size from semantic HTML hierarchy (H1–H6).
-- A visually large title may use `<h2>` or `<p>` semantically — visual scale and semantic meaning are independent in Gamut.
-- Choose HTML heading levels for document structure, choose font size for visual hierarchy.
+- `<Text as="h1">` … `<Text as="h6">` gets **default heading styles**: each tag maps to the same scale as `variant="title-xxl"` … `variant="title-xs"` (`h1` largest through `h6` smallest). Plain `<Text>` defaults to `as="span"` (inherits font size).
+- Use **`variant`** plus **`fontSize` / `fontWeight` / `lineHeight`** (and other system props) to override element defaults when the outline needs one heading level but the UI needs another visual weight — e.g. `<Text as="h2" variant="title-sm">`.
+- Still pick **`h1`–`h6`** for document structure and assistive tech; overrides are for intentional divergence between semantics and appearance.

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@codecademy/gamut",
   "description": "Styleguide & Component library for Codecademy",
-  "version": "68.6.1-alpha.d52035.0",
+  "version": "68.6.1-alpha.df4bce.0",
   "author": "Codecademy Engineering <dev@codecademy.com>",
   "bin": "./bin/gamut.mjs",
   "dependencies": {
-    "@codecademy/gamut-icons": "9.57.6-alpha.d52035.0",
-    "@codecademy/gamut-illustrations": "0.58.12-alpha.d52035.0",
-    "@codecademy/gamut-patterns": "0.10.31-alpha.d52035.0",
-    "@codecademy/gamut-styles": "18.0.1-alpha.d52035.0",
-    "@codecademy/variance": "0.26.2-alpha.d52035.0",
+    "@codecademy/gamut-icons": "9.57.6-alpha.df4bce.0",
+    "@codecademy/gamut-illustrations": "0.58.12-alpha.df4bce.0",
+    "@codecademy/gamut-patterns": "0.10.31-alpha.df4bce.0",
+    "@codecademy/gamut-styles": "18.0.1-alpha.df4bce.0",
+    "@codecademy/variance": "0.26.2-alpha.df4bce.0",
     "@formatjs/intl-locale": "5.3.1",
     "@react-aria/interactions": "3.25.0",
     "@types/marked": "^4.0.8",