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

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

@@ -1,48 +1,46 @@
 ---
 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: 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
 
-Source: `@codecademy/gamut-tests` — [`index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-tests/src/index.tsx)
-
----
+## Read first
 
-## Core rule: never mock Gamut components
+When this skill applies, skim [`commands/gamut-review.md`](../../commands/gamut-review.md) Check 5 (test setup) for blocking patterns before changing tests.
 
-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.
+Source: `@codecademy/gamut-tests` — [`index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-tests/src/index.tsx)
 
-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 +64,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 +88,84 @@ it('calls onClick when clicked', async () => {
 
 ---
 
-## `MockGamutProvider` directly — when you need more control
+## 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.
 
-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`.
+### 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 +180,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 +190,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 +213,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-theming/SKILL.md

@@ -1,115 +1,63 @@
 ---
 name: gamut-theming
-description: Use this skill when working with GamutProvider themes, Emotion theme tokens, or behavior that differs across Core, Admin, Platform, LX Studio, and Percipio — including new themes, token access in styled components, or debugging theme-specific styles.
+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. All styled components have access to a typed theme object containing every design token. Themes are org-specific collections of tokens; components work across all themes without modification as long as they use token aliases rather than hardcoded values.
+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:
 
-**See also:** [`gamut-color-mode`](../gamut-color-mode/SKILL.md) for `<ColorMode>`, `<Background>`, `useColorModes`, and contrast-safe surfaces — read that before wiring light/dark or colored sections. Storybook: [ColorMode](https://gamut.codecademy.com/?path=/docs-foundations-colormode--page), [Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page).
+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 (public-facing products)                |
+| Core      | Codecademy default                                         |
 | Admin     | Codecademy admin tools                                     |
 | Platform  | Codecademy learning environment / shared platform surfaces |
 | LX Studio | Learning Experience Studio                                 |
 | Percipio  | Skillsoft Percipio platform                                |
 
-The active theme is set at the app level via `<GamutProvider>`. Components inside receive the current theme via Emotion's context.
-
-## Accessing tokens in styled components
-
-### Via `css()` utility (recommended for static styles)
-
-```tsx
-import { css } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-
-// Static color token
-const Box = styled.div(css({ bg: 'navy-400', p: 4 }));
-
-// Semantic color alias (adapts to color mode and theme)
-const Text = styled.div(css({ color: 'primary', p: 4 }));
-```
-
-### Via `theme` prop (for dynamic styles)
-
-Every Emotion styled component receives `theme` as a prop:
-
-```tsx
-import styled from '@emotion/styled';
-
-const DynamicBox = styled.div`
-  color: ${({ theme }) => theme.colors.blue};
-  font-size: ${({ theme }) => theme.fontSize[16]};
-`;
-```
-
-### Via imported `theme` object (outside styled components)
-
-```tsx
-import { css as emotionCss } from '@emotion/react';
-import { theme } from '@codecademy/gamut-styles';
-
-// For use in plain CSS-in-JS outside of styled components
-const myStyles = emotionCss`
-  font-size: ${theme.fontSize[14]};
-  color: ${theme.colors['navy-400']};
-`;
-```
-
-### Via `useTheme()` hook
-
-```tsx
-import { useTheme } from '@emotion/react';
-
-const MyComponent = () => {
-  const theme = useTheme();
-  return <div style={{ color: theme.colors.primary }} />;
-};
-```
-
-## System props as the primary token API
-
-For most styling needs, use **system props** (see the `gamut-system-props` skill) rather than accessing the theme directly. System props are the idiomatic way to use design tokens in Gamut components:
-
-```tsx
-import { variance } from '@codecademy/variance';
-import { system } from '@codecademy/gamut-styles';
-
-const Card = styled.div(
-  variance.compose(system.layout, system.space, system.color)
-);
-
-// token scale values are validated at the type level
-<Card bg="navy-400" p={16} width="100%" />;
-```
-
-## Theme-aware vs. color-mode-aware
+Product-level import names and `theme.d.ts` patterns live in [setup.md](../../guidelines/setup.md).
 
-| Concern                                        | Tool                                       |
-| ---------------------------------------------- | ------------------------------------------ |
-| Tokens change per theme (colors, sizes, fonts) | Access via `theme.*` or system props       |
-| Colors change per light/dark mode              | Use semantic color aliases + `<ColorMode>` |
-| Background contrast                            | Use `<Background>` from ColorMode          |
+## Theme vs color mode vs style API
 
-Semantic aliases like `primary`, `secondary`, `text`, `background` serve double duty: they resolve to theme-specific values **and** switch between light/dark variants automatically.
+| 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`) for the full guide. Themes are defined in `@codecademy/gamut-styles` and must extend the base theme shape with all required token keys.
+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
 
-- Prefer semantic token aliases over raw token values when the style needs to respond to color mode changes.
-- Use raw tokens (e.g. `navy-400`) only for styles that should be fixed regardless of mode.
-- Never hardcode hex values in styled components — always go through the theme/system props.
-- The `GamutProvider` at the app root wires up the theme, color mode, and logical properties settings; components should not need to know which theme is active.
+- 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,123 +1,79 @@
 ---
 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: 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
 
-> **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.
+## Read first
 
-## Typefaces
+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`.
 
-Codecademy products use two typefaces:
+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).
 
-### Apercu Pro (`fontFamily: "base"`)
+## Scope by theme
 
-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)
+| 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                |
 
-**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.