@codecademy/gamut 68.6.1-alpha.bc8b32.0 → 68.6.1-alpha.c8d945.0

package/agent-tools/skills/gamut-style-utilities/SKILL.md

@@ -1,107 +0,0 @@
----
-name: gamut-style-utilities
-description: Use this skill when authoring Gamut styles with @codecademy/gamut-styles — css(), variant(), states(), StyleProps from variance, or the useTheme() escape hatch; choosing between these APIs and system props; semantic tokens with ColorMode.
----
-
-# Gamut style utilities
-
-Source: `@codecademy/gamut-styles` — [`variance/props.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/props.ts) (`css`, `variant`, `states` built on `PROPERTIES.all`).
-
-**See also:** [`gamut-theming`](../gamut-theming/SKILL.md) (which theme, `GamutProvider`, new themes). [`gamut-system-props`](../gamut-system-props/SKILL.md) (`system.*`, responsive props, `Box`). [`gamut-color-mode`](../gamut-color-mode/SKILL.md) (semantic color, `<ColorMode>`, `<Background>`). [Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx) and [system compose](https://gamut.codecademy.com/?path=/docs-foundations-system-compose--page).
-
-## Overview
-
-Use **`css()`**, **`variant()`**, and **`states()`** from `@codecademy/gamut-styles` for **typed, token-scaled** style objects (same scales as composed **`system.*`** props). Prefer **semantic** color keys so styles track **ColorMode** and theme.
-
-For **layout-heavy** styled components, prefer composing **`system.*`** via `variance.compose()` (see **`gamut-system-props`**) instead of re-stating every longhand in `css()`.
-
-## `css()` — static style objects
-
-```tsx
-import { css } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-
-const Box = styled.div(css({ bg: 'navy-400', p: 4 }));
-const Text = styled.div(css({ color: 'primary', p: 4 }));
-```
-
-## `variant()` and `states()` — branching and toggles
-
-- **`variant()`** — mutually exclusive modes: `base`, `defaultVariant`, and a `variants` map (semantic colors, spacing shorthands, nested selectors such as `'&:hover'`).
-
-```tsx
-import { variant } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-
-const Anchor = styled.a(
-  variant({
-    base: { p: 4 },
-    defaultVariant: 'interface',
-    variants: {
-      interface: {
-        color: 'text',
-        '&:hover': { color: 'text-accent' },
-      },
-      inline: {
-        color: 'primary',
-        '&:hover': { color: 'secondary' },
-      },
-    },
-  })
-);
-```
-
-- **`states()`** — independent boolean-style props (`base` + named keys).
-
-```tsx
-import { states } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-
-const UtilityBox = styled.div(
-  states({
-    base: { mx: 4, my: 8, p: 16 },
-    disabled: { bg: 'background-disabled', color: 'text-disabled' },
-    center: { alignItems: 'center', justifyContent: 'center' },
-  })
-);
-```
-
-### `StyleProps` on React components
-
-```tsx
-import { states } from '@codecademy/gamut-styles';
-import { StyleProps } from '@codecademy/variance';
-import styled from '@emotion/styled';
-
-const panelShellStates = states({ base: { p: 4 }, dense: { p: 2 } });
-const PanelShell = styled.div(panelShellStates);
-
-export type PanelShellProps = StyleProps<typeof panelShellStates> & {
-  title: string;
-};
-
-export const Panel: React.FC<PanelShellProps> = ({ title, ...rest }) => (
-  <PanelShell {...rest}>{title}</PanelShell>
-);
-```
-
-Prefer **`variant` / `states`** over branching on raw `theme` fields inside styled **template literals** when the output is Emotion-managed CSS.
-
-## `useTheme()` — escape hatch
-
-Prefer **`css()`**, **`system.*`**, **`variant()`**, and **`states()`** for styling. Use **`useTheme()`** from `@emotion/react` when a token value must be read in **plain JS** (charts, canvas, third-party props), not as the default way to color DOM nodes.
-
-```tsx
-import { useTheme } from '@emotion/react';
-
-const Sparkline = () => {
-  const theme = useTheme();
-  return <path strokeWidth={theme.spacing[4]} d="M0 0 L10 10" />;
-};
-```
-
-## Key principles
-
-- Prefer **semantic** color keys in `css` / `variant` / `states` so **ColorMode** and theme switches apply; see **`gamut-color-mode`**.
-- Never hardcode hex in component styles — use tokens / semantic aliases.
-- Prefer **`variant` / `states`** for modes and toggles instead of ad-hoc `theme` interpolation in template literals.

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

@@ -1,203 +0,0 @@
----
-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, 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) (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`). [Styleguide — Best practices](../../../../styleguide/src/lib/Meta/Best%20practices.mdx) (semantic colors, 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%`)
-
-## 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,221 +0,0 @@
----
-name: gamut-testing
-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
-
-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,48 +0,0 @@
----
-name: gamut-theming
-description: Use this skill when choosing or extending Gamut themes (Core, Admin, Platform, LX Studio, Percipio), wiring GamutProvider and Emotion theme TypeScript augmentation, or following CreatingThemes — not for day-to-day css(), variant(), or states() patterns (see gamut-style-utilities).
----
-
-# Gamut Theming
-
-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).
-
-## 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 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,75 +0,0 @@
----
-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. 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
-
-**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).
-
-## 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.