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

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

@@ -1,225 +0,0 @@
----
-name: gamut-system-props
-description: Layout, spacing, color, flex, grid system props from @codecademy/gamut-styles. When invoked, read guidelines/foundations/spacing.md first.
----
-
-# Gamut System Props
-
-## Read first
-
-When this skill applies, read [`guidelines/foundations/spacing.md`](../../guidelines/foundations/spacing.md) before writing code.
-
-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: [`gamut-style-utilities`](../gamut-style-utilities/SKILL.md) (`css`, `variant`, `states`, `StyleProps`). [foundations/spacing.md](../../guidelines/foundations/spacing.md) (token scale). [Styleguide — Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx) and Storybook [Responsive properties](https://gamut.codecademy.com/storybook/?path=/docs-foundations-system-responsive-properties--page).
-
-## Styling rules
-
-- Never use inline `style` attributes. Use system props on `Box` / `FlexBox` / `Text`, or `css` / `variant` / `states` on styled components.
-- Use shorthand — `mb={16}`, not `marginBottom={16}`.
-
-| Long form      | Shorthand |
-| -------------- | --------- |
-| `margin`       | `m`       |
-| `marginTop`    | `mt`      |
-| `marginBottom` | `mb`      |
-| `marginX`      | `mx`      |
-| `marginY`      | `my`      |
-| `padding`      | `p`       |
-| `paddingX`     | `px`      |
-| `paddingY`     | `py`      |
-
-Colors and borders: `bg`, `color` / `textColor`, `borderColor`, `borderRadius` — values must be Gamut tokens, never raw hex.
-
-## 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. 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);
-
-<Box display="flex" width="50%" height="300px" verticalAlign="middle" />;
-```
-
-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`
-
-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 / object — see Responsive values)
-<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" color="gray-900" textColor="gray-100" borderColor="blue" />;
-```
-
-Key props: `color`, `textColor` (both set CSS `color`), `bg`, `borderColor`, plus directional `borderColor*` variants — see `config.ts` for the full set.
-
-### `system.typography`
-
-Text styling connected to theme typography scales.
-
-```tsx
-const Text = styled.p(system.typography);
-
-<Text
-  fontSize={16}
-  fontFamily="accent"
-  fontStyle="italic"
-  textTransform="uppercase"
-  lineHeight="base"
-/>;
-```
-
-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. Many logical shorthands exist (`borderX`, `borderColorY`, `borderRadiusTop`, …); see `config.ts` for the full map.
-
-Key props (non-exhaustive): `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 (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 (non-exhaustive): `gridTemplateColumns`, `gridTemplateRows`, `gridTemplateAreas`, `gridColumn`, `gridRow`, `gridArea`, `gridAutoFlow`, `gridAutoColumns`, `gridAutoRows`, `gap`, `rowGap`, `columnGap`
-
-### `system.positioning`
-
-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));
-
-<Overlay position="absolute" top={0} left={0} width="100%" height="100%" />;
-```
-
-Key props: `position`, `inset`, `top`, `right`, `bottom`, `left`, `zIndex`, `opacity`
-
-### `system.shadow`
-
-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 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
-<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` (same implementation as `system.css` on the `system` namespace).
-
-```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)`.
-- 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,225 +0,0 @@
----
-name: gamut-testing
-description: Unit tests for Gamut UI — setupRtl, MockGamutProvider, no jest.mock of @codecademy/gamut. When invoked, see commands/gamut-review.md Check 5 for test guardrails.
----
-
-# Gamut Testing
-
-## Read first
-
-When this skill applies, skim [`commands/gamut-review.md`](../../commands/gamut-review.md) Check 5 (test setup) for blocking patterns before changing tests.
-
-Source: `@codecademy/gamut-tests` — [`index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-tests/src/index.tsx)
-
----
-
----
-
-## What `MockGamutProvider` does (under `setupRtl`)
-
-`MockGamutProvider` forwards to `GamutProvider` with:
-
-- `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 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                                                         | 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` — primary pattern
-
-```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`, `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'));
-  expect(props.onClick).toHaveBeenCalled();
-});
-```
-
----
-
-## Harness + `setupRtl` when the wrapper is not default
-
-`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, setupRtl } from '@codecademy/gamut-tests';
-
-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' });
-
-describe.each([
-  { useLogicalProperties: true as const, widthProp: 'inlineSize' as const },
-  { useLogicalProperties: false as const, widthProp: 'width' as const },
-])(
-  'useLogicalProperties=$useLogicalProperties',
-  ({ useLogicalProperties, widthProp }) => {
-    it(`uses ${widthProp}`, () => {
-      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 if you absolutely need 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` instead of hardcoding token strings:
-
-```tsx
-import { theme } from '@codecademy/gamut-styles';
-
-expect(element).toHaveStyle({ columnGap: theme.spacing[40] });
-```
-
----
-
-## Visual test wrappers and Storybook
-
-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
-) => (
-  <MockGamutProvider>
-    <ColorMode mode="light">
-      <MyComponent {...props} />
-    </ColorMode>
-  </MockGamutProvider>
-);
-```
-
----
-
-## Common anti-patterns
-
-| 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-theming/SKILL.md

@@ -1,63 +0,0 @@
----
-name: gamut-theming
-description: Gamut themes, GamutProvider, theme.d.ts, CreatingThemes. When invoked, read guidelines/setup.md and repo DESIGN.md first. Not for css/variant/states (see gamut-style-utilities).
----
-
-# Gamut Theming
-
-## Read first
-
-When this skill applies, read before writing code:
-
-- [`guidelines/setup.md`](../../guidelines/setup.md)
-- Root `DESIGN.md` in the app repo (product tokens and patterns)
-
-Source: `@codecademy/gamut-styles`
-
-See also: [`gamut-style-utilities`](../gamut-style-utilities/SKILL.md) (`css`, `variant`, `states`, `StyleProps`, `useTheme` escape hatch). [`gamut-color-mode`](../gamut-color-mode/SKILL.md) (semantic color, `<ColorMode>`, `<Background>`). [`gamut-system-props`](../gamut-system-props/SKILL.md) (`system.*`, responsive `Box` props).
-
-## Overview
-
-Gamut uses Emotion's theme system. Themes are org-specific token bundles (colors, typography, spacing, etc.). The active theme is set at the app root with `<GamutProvider theme={...}>`; child styled components read tokens through Emotion context.
-
-For authoring component styles (`css`, `variant`, `states`, system props, ColorMode), use the skills linked above and the styleguide [Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx).
-
-## Infer theme from the repo
-
-Do not hardcode a product theme in generic guidance. In an app repo:
-
-1. Read root `DESIGN.md` (installed via `gamut plugin install --theme <name>`) for semantic tokens, fonts, and product patterns.
-2. Confirm `<GamutProvider theme={...}>` matches that product (`coreTheme`, `percipioTheme`, `lxStudioTheme`, etc.).
-3. Use Storybook Foundations / Theme stories for the active product when verifying hex ↔ semantic mappings.
-
-## Available themes
-
-| Theme     | Used for                                                   |
-| --------- | ---------------------------------------------------------- |
-| Core      | Codecademy default                                         |
-| Admin     | Codecademy admin tools                                     |
-| Platform  | Codecademy learning environment / shared platform surfaces |
-| LX Studio | Learning Experience Studio                                 |
-| Percipio  | Skillsoft Percipio platform                                |
-
-Product-level import names and `theme.d.ts` patterns live in [setup.md](../../guidelines/setup.md).
-
-## Theme vs color mode vs style API
-
-| Concern                                                 | Where to read                                      |
-| ------------------------------------------------------- | -------------------------------------------------- |
-| Which `theme` object to pass to `GamutProvider`         | This skill + [setup.md](../../guidelines/setup.md) |
-| Light / dark semantic colors, `ColorMode`, `Background` | `gamut-color-mode`                                 |
-| `css` / `variant` / `states`, `useTheme` for non-CSS JS | `gamut-style-utilities`                            |
-| Composed `system.*` props on styled primitives / `Box`  | `gamut-system-props`                               |
-
-## Creating a new theme
-
-See `CreatingThemes.mdx` in the styleguide (`packages/styleguide/src/lib/Foundations/Theme/CreatingThemes.mdx`). Themes are defined in `@codecademy/gamut-styles` and must extend the base theme shape with all required token keys.
-
-## Key principles
-
-- Pick the correct theme export for the product (`coreTheme`, `adminTheme`, `platformTheme`, `lxStudioTheme`, `percipioTheme`, etc.) so tokens and fonts match `DESIGN.md` and design intent.
-- Align `theme.d.ts` / `Theme extends …` with the same theme interface you pass to `GamutProvider` (see [setup.md](../../guidelines/setup.md)).
-- Components stay portable across themes when they use token and semantic aliases rather than one-off hex; authoring rules live in `gamut-style-utilities` and `gamut-color-mode`.
-- `GamutProvider` wires theme, color mode, and logical-properties settings at the root; individual components should not hard-code which org theme is active.

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

@@ -1,79 +0,0 @@
----
-name: gamut-typography
-description: Gamut UI text — headlines, body, fontSize, lineHeight, fontWeight title. When invoked, read guidelines/foundations/typography.md and DESIGN.md for the active theme.
----
-
-# Gamut Typography
-
-## Read first
-
-When this skill applies, read [`guidelines/foundations/typography.md`](../../guidelines/foundations/typography.md) before writing code. Confirm stacks and `fontWeight.title` against root `DESIGN.md`.
-
-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).
-
-## Scope by theme
-
-| 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                |
-
-Use `fontWeight="title"` for headlines / emphasis roles — never hardcode `700` on Percipio/LX unless SPECIFICALLY noted in Figma designs.
-
-## Font size scale (`fontSize`)
-
-Theme keys: `64`, `44`, `34`, `26`, `22`, `20`, `18`, `16`, `14`.
-
-```tsx
-import { css } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Paragraph = styled.p(system.typography);
-<Paragraph fontSize={16} lineHeight="base" />;
-
-const Styled = styled.div(css({ fontSize: 14, fontFamily: 'base' }));
-```
-
-## Line height (`lineHeight`)
-
-Tokens: `base` (1.5), `spacedTitle` (1.3), `title` (1.2). Prefer tokens over raw decimals. Only specify `lineHeight` when specified by design.
-
-## Line length
-
-| Context            | Target                   |
-| ------------------ | ------------------------ |
-| Single-column body | ~66 characters (max ~85) |
-| Multi-column       | ≤50 characters per line  |
-| Minimum            | ~45 characters           |
-
-## Accessing typography tokens
-
-```tsx
-import { system } from '@codecademy/gamut-styles';
-import { variance } from '@codecademy/variance';
-
-const Heading = styled.h2(variance.compose(system.typography, system.space));
-
-<Heading
-  fontSize={26}
-  fontFamily="base"
-  fontWeight="title"
-  lineHeight="title"
-  mb={8}
-/>;
-
-import { css } from '@codecademy/gamut-styles';
-
-const Caption = styled.span(
-  css({ fontFamily: 'accent', fontSize: 14, color: 'text-secondary' })
-);
-```
-
-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
-
-- `<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.