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

package/agent-tools/guidelines/overview.md

@@ -1,35 +1,84 @@
 # Gamut Design System
 
+## For agents
+
+Do not load all guideline files. Read this overview’s Step 2 table, then open only the `guidelines/components/*.md` (or foundation) guides you need for the current task. For Menu, DataTable, Card, and other components without a dedicated skill, use `gamut-components`.
+
 Gamut is the Codecademy / Skillsoft design system — React component library (`@codecademy/gamut`), design tokens (`@codecademy/gamut-styles`), and Figma components with live code previews via Figma Code Connect.
 
-**Design voice**: "Ruled by logic, but creative and a bit unexpected." Structured and trustworthy for a learning platform, with engaging personality. Medium density — information-rich layouts with strong typographic hierarchy. Never cramped or overly airy.
+Core principle: Always use Gamut components, tokens, and patterns. Every element must trace back to an existing token, component, or documented pattern — never introduce ad-hoc values when a system equivalent exists.
+
+Design voice: "Ruled by logic, but creative and a bit unexpected." Structured and trustworthy for a learning platform, with engaging personality. Medium density — information-rich layouts with strong typographic hierarchy.
 
-**Core principles**:
-- Components are color mode–aware by default — never hardcode hex values for adaptive UI
+Core principles:
+
+- Components are color mode–aware by default — never hardcode hex values for adaptive, accessible UI
 - All components work across all themes without modification
-- Mobile-first, 12-column grid
-- Semantic color tokens guarantee WCAG AA contrast automatically
+- 12-column grid
+- Use semantic theme tokens from `@codecademy/gamut-styles` for color roles, typography, spacing, border radii, and layout — not raw palette hex or magic numbers. Validate non-standard combinations against WCAG.
+- Product theme: infer semantic tokens, fonts, and palette from root `DESIGN.md` (installed via `gamut plugin install --theme <name>`) and `<GamutProvider>`. See [`skills/gamut-theming/SKILL.md`](../skills/gamut-theming/SKILL.md).
+
+Agent skills: `gamut-components`, `gamut-style-utilities`, `gamut-theming`, `gamut-system-props`, `gamut-color-mode`, `gamut-forms`, `gamut-accessibility`, `gamut-typography`, `gamut-testing`.
 
 ## Themes
 
-| Theme | Product | Base font | Dark mode |
-|---|---|---|---|
-| **Core** | Codecademy (default) | Apercu | ✓ |
-| **Admin** | Codecademy admin tools | Apercu | ✓ |
-| **Platform** | Codecademy learning environment | Apercu | ✓ |
-| **LX Studio** | LX Studio application | Hanken Grotesk | — |
-| **Percipio** | Skillsoft Percipio | Roboto | — |
+| Theme     | Product                         | Primary UI fonts (shipped theme)                       | Dark mode |
+| --------- | ------------------------------- | ------------------------------------------------------ | --------- |
+| Core      | Codecademy (default)            | Apercu + Suisse (`accent`)                             | ✓         |
+| Admin     | Codecademy admin tools          | Same as Core                                           | ✓         |
+| Platform  | Codecademy learning environment | Same as Core                                           | ✓         |
+| LX Studio | LX Studio application           | Skillsoft Text / Sans (`base` / `accent`)              | ✓         |
+| Percipio  | Skillsoft Percipio              | Skillsoft Text / Sans; Roboto Mono / Roboto (`system`) | ✓         |
+
+Set the theme at the app root via `<GamutProvider theme={...}>`. Match `DESIGN.md` in the app repo to the active product.
 
-Set the theme at the app root via `<GamutProvider theme={...}>`.
+Plugin install: Storybook [Meta → AI Tooling → Gamut plugin → Install](https://gamut.codecademy.com/?path=/docs-meta-ai-tooling-gamut-plugin-install--page). `gamut plugin install cursor --theme core` (or `percipio`, `lxstudio`, …) copies `DESIGN.*.md` to `./DESIGN.md`.
 
 ## Reading order
 
-| File | What it covers |
-|---|---|
-| [setup.md](setup.md) | Packages, GamutProvider, theme selection |
-| [foundations/color.md](foundations/color.md) | Semantic aliases, raw palette, decision guide |
-| [foundations/modes.md](foundations/modes.md) | Light/dark ColorMode, Background component |
-| [foundations/typography.md](foundations/typography.md) | Typefaces, font scale, rules |
-| [foundations/spacing.md](foundations/spacing.md) | Spacing, border radius, responsive grid |
-| [components/overview.md](components/overview.md) | Full component catalog |
-| [components/buttons.md](components/buttons.md) | Button variants, props, decision tree |
+### Step 1: Overview (required)
+
+| File                                                                                                                             | What it covers                                 |
+| -------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| [setup.md](setup.md)                                                                                                             | Packages, `GamutProvider`, theme selection     |
+| [foundations/spacing.md](foundations/spacing.md) + [color.md](foundations/color.md) + [typography.md](foundations/typography.md) | Tokens — spacing, color, typography            |
+| [foundations/modes.md](foundations/modes.md)                                                                                     | `ColorMode`, `Background`                      |
+| [components/overview.md](components/overview.md)                                                                                 | Component catalog, discovery, forms breadcrumb |
+| [overview-icons.md](overview-icons.md)                                                                                           | Icon selection from `@codecademy/gamut-icons`  |
+| [overview-illustrations.md](overview-illustrations.md)                                                                           | `@codecademy/gamut-illustrations`              |
+| [overview-patterns.md](overview-patterns.md)                                                                                     | `@codecademy/gamut-patterns`                   |
+| [validation-checklist.md](validation-checklist.md)                                                                               | Pre-ship checklist                             |
+
+### Step 2: Component guides (read before using that component)
+
+| Using…                                                                    | Read first                                                                                                               |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `FillButton` / `StrokeButton` / `TextButton` / `IconButton` / `CTAButton` | [components/buttons.md](components/buttons.md)                                                                           |
+| `GridForm` / `ConnectedForm`                                              | [components/forms.md](components/forms.md) · [`skills/gamut-forms/SKILL.md`](../skills/gamut-forms/SKILL.md)             |
+| `DataTable` / `DataList`                                                  | [components/data-table.md](components/data-table.md)                                                                     |
+| `Menu` / `MenuItem` / `MenuSeparator`                                     | [components/menu.md](components/menu.md)                                                                                 |
+| `Card`                                                                    | [components/card.md](components/card.md)                                                                                 |
+| `Select` / `SelectDropdown`                                               | [components/select.md](components/select.md)                                                                             |
+| `RadialProgress`                                                          | [components/radial-progress.md](components/radial-progress.md)                                                           |
+| `Shimmer` / `Spinner` / `FeatureShimmer`                                  | [components/loading-states.md](components/loading-states.md)                                                             |
+| `Coachmark`                                                               | [components/coachmark.md](components/coachmark.md)                                                                       |
+| `ToolTip` / `InfoTip`                                                     | [components/tooltips.md](components/tooltips.md)                                                                         |
+| `Video`                                                                   | [components/video.md](components/video.md)                                                                               |
+| `Rotation` / `ExpandInCollapseOut` / `FadeInSlideOut`                     | [components/animations.md](components/animations.md)                                                                     |
+| `ColorMode` / `Background`                                                | [foundations/modes.md](foundations/modes.md) · [`skills/gamut-color-mode/SKILL.md`](../skills/gamut-color-mode/SKILL.md) |
+
+### Step 3: Skills (on demand)
+
+| Skill                                                               | When                                                                                                  |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| [`gamut-components`](../skills/gamut-components/SKILL.md)           | Menu, DataTable, Card, Select, Video, Coachmark, loading, animations (read matching component guides) |
+| [`gamut-style-utilities`](../skills/gamut-style-utilities/SKILL.md) | `css` / `variant` / `states`, `StyleProps`                                                            |
+| [`gamut-system-props`](../skills/gamut-system-props/SKILL.md)       | `system.*`, responsive props, `Box`                                                                   |
+| [`gamut-theming`](../skills/gamut-theming/SKILL.md)                 | Theme matrix, `GamutProvider`, new themes                                                             |
+| [`gamut-color-mode`](../skills/gamut-color-mode/SKILL.md)           | ColorMode, semantic color, `<Background>`                                                             |
+| [`gamut-forms`](../skills/gamut-forms/SKILL.md)                     | Form accessibility wiring                                                                             |
+| [`gamut-accessibility`](../skills/gamut-accessibility/SKILL.md)     | Component a11y matrix, overlays                                                                       |
+| [`gamut-typography`](../skills/gamut-typography/SKILL.md)           | Type stacks and voice                                                                                 |
+| [`gamut-testing`](../skills/gamut-testing/SKILL.md)                 | `setupRtl`, test harnesses                                                                            |
+
+Pre-ship audit: [`commands/gamut-review.md`](../commands/gamut-review.md) (`/gamut-review`).

package/agent-tools/guidelines/setup.md

@@ -3,40 +3,81 @@
 ## Install
 
 ```sh
-npm install @codecademy/gamut-kit
+yarn add @codecademy/gamut-kit @emotion/react @emotion/styled
 ```
 
 `gamut-kit` bundles `gamut`, `gamut-icons`, `gamut-illustrations`, `gamut-patterns`, `gamut-styles`, `variance`, and `gamut-tests`.
 
+Full guide: [Meta / Installation](https://gamut.codecademy.com/?path=/docs-meta-installation--page) in Storybook (CSP `nonce` on `GamutProvider`, Jest, Next/Gatsby entry points). For Emotion + TypeScript, add `theme.d.ts` as in [TypeScript (`theme.d.ts`)](#typescript-themedts) below.
+
+Product design intent: After install, use root `DESIGN.md` (from `gamut plugin install --theme <name>`) with [`skills/gamut-theming/SKILL.md`](../skills/gamut-theming/SKILL.md) for semantic tokens, fonts, and component patterns for that product. Do not modify or alias `@codecademy/*` packages away from published APIs.
+
+Optionally add a `peerDependencies` block in `package.json` listing `@codecademy/gamut`, `@codecademy/gamut-icons`, `@codecademy/gamut-illustrations`, `@codecademy/gamut-patterns`, `@codecademy/gamut-styles`, `@codecademy/gamut-tests`, and `@codecademy/variance` (e.g. `"*"`) so editors surface those packages — see Meta / Installation for the JSON snippet.
+
 ## Required wrapper
 
-Wrap the app root in `<GamutProvider>`. This wires up the theme, color mode, and logical properties for all child components.
+Wrap the app root in `<GamutProvider>` from `@codecademy/gamut-styles`. This wires up the theme, color mode, and logical properties for all child components.
+
+At runtime, `GamutProvider` defaults to Core when `theme` is omitted (`theme = coreTheme` in the implementation). For non-Core products and for TypeScript (`theme` is required on `GamutProviderProps`), pass `theme` explicitly using the table below.
 
 ```tsx
-import { GamutProvider } from '@codecademy/gamut';
-import { theme } from '@codecademy/gamut-styles';
+import { GamutProvider, theme } from '@codecademy/gamut-styles';
 
 const App = () => (
-  <GamutProvider theme={theme}>
-    {/* app content */}
-  </GamutProvider>
+  <GamutProvider theme={theme}>{/* app content */}</GamutProvider>
 );
 ```
 
 ## Theme selection
 
-| Product | Theme to import |
-|---|---|
-| Codecademy public | `coreTheme` (default `theme`) |
-| Codecademy admin | `adminTheme` |
-| Codecademy platform | `platformTheme` |
-| LX Studio | `lxStudioTheme` |
-| Percipio | `percipioTheme` |
+| Product             | Theme to import               |
+| ------------------- | ----------------------------- |
+| Codecademy public   | `coreTheme` (default `theme`) |
+| Codecademy admin    | `adminTheme`                  |
+| Codecademy platform | `platformTheme`               |
+| LX Studio           | `lxStudioTheme`               |
+| Percipio            | `percipioTheme`               |
 
 All themes are exported from `@codecademy/gamut-styles`.
 
-## Font licensing
+## TypeScript (`theme.d.ts`)
+
+Augment `@emotion/react` so `props.theme` in `styled` / `css` matches the same theme object you pass to `<GamutProvider theme={...}>`. If the types disagree, system props and token autocomplete will not line up with runtime.
+
+Add a root `theme.d.ts` (or merge into your existing global types):
+
+```tsx
+// theme.d.ts
+import '@emotion/react';
+
+import type { CoreTheme } from '@codecademy/gamut-styles';
+
+declare module '@emotion/react' {
+  export interface Theme extends CoreTheme {}
+}
+```
+
+Use the theme interface that matches your provider — same row as the [theme selection](#theme-selection) table:
+
+| `GamutProvider` `theme` prop | Import for `Theme extends …` |
+| ---------------------------- | ---------------------------- |
+| `theme` or `coreTheme`       | `CoreTheme`                  |
+| `adminTheme`                 | `AdminTheme`                 |
+| `platformTheme`              | `PlatformTheme`              |
+| `lxStudioTheme`              | `LxStudioTheme`              |
+| `percipioTheme`              | `PercipioTheme`              |
+
+Example when the app uses Percipio:
+
+```tsx
+// theme.d.ts
+import '@emotion/react';
+
+import type { PercipioTheme } from '@codecademy/gamut-styles';
+
+declare module '@emotion/react' {
+  export interface Theme extends PercipioTheme {}
+}
+```
 
-**Apercu Pro** is licensed for codecademy.com only. Non-Codecademy products must use their theme's approved typeface:
-- LX Studio → Hanken Grotesk
-- Percipio → Roboto
+See Emotion’s [TypeScript / define a theme](https://emotion.sh/docs/typescript#define-a-theme) for details.

package/agent-tools/rules/accessibility.mdc

@@ -1,7 +1,7 @@
 ---
-description: Apply these guardrails when editing Gamut UI in TS/JS/TSX/JSX. Mirrors the General rules in the `gamut-accessibility` skill; see `skills/gamut-accessibility/SKILL.md` in this plugin for full component patterns and checklists. Loaded automatically for matched files.
+description: Apply these guardrails when editing Gamut UI in TS/JS/TSX/JSX. Universal rules (always loaded). Form wiring depth: `gamut-forms` skill; other component matrix and audit detail: `gamut-accessibility` — those skills do not repeat this rule set.
 alwaysApply: true
-globs: ["*.tsx", "*.ts", "*.jsx", "*.js"]
+globs: ['*.tsx', '*.ts', '*.jsx', '*.js']
 ---
 
 # Gamut Accessibility Rules
@@ -18,7 +18,6 @@ ARIA roles modify the accessibility tree and _imply_ behavior. Always ensure tha
 
 ARIA can augment native semantics (`aria-pressed` on a `<button>`) or override them entirely (`role="menuitem"` on an `<a>`). Both capabilities are powerful and dangerous. Override only when native HTML genuinely doesn't fit the pattern; when augmenting, don't contradict the native semantics.
 
-
 ## Align accessible names with visible copy
 
 Prefer wiring names through visible text and native `<label>` / control text / `alt` over using `aria-label`. Point `aria-labelledby` at the visible heading or label that should define the name if it's not possible to name elements from their content. Use bare `aria-label` when there is no suitable visible label.
@@ -40,21 +39,20 @@ When there is no visible text for a nameable element, consider this a sign that
 </ul>
 ```
 
-## Use Gamut components — don't reimplement what they already solve
+## Use Gamut primitives — do not fake buttons or dialogs
 
-- `<Button>` not `<div onClick>` or `<span role="button">`
-- `<Tabs>` / `<Tab>` / `<TabList>` / `<TabPanel>` — arrow key, Home, End navigation is automatic
-- `<Dialog>` / `<Modal>` — always provide an accessible name; **prefer `aria-labelledby`** to a visible title when one exists, otherwise `aria-label`. Focus lock and Escape are handled by the components.
+- Actions: use Gamut button atoms (`FillButton`, `TextButton`, `StrokeButton`, `CTAButton`, `IconButton`) — not `<div onClick>`, not `<span role="button">`, not `<a>` without `href` for actions. Variant and `tip` guidance: [`guidelines/components/buttons.md`](../guidelines/components/buttons.md).
+- Tabs / overlays: `Tabs`, `Dialog`, `Modal`, and related primitives implement keyboard and focus patterns in code — still supply labels, titles, and trigger semantics as documented in the skill.
 
 ## Every interactive control needs an accessible name
 
-- **`<IconButton>`** — provide `tip` (becomes the accessible name for icon-only)
-- **`<InfoTip>`** — provide `ariaLabel` or `ariaLabelledby`; there is no automatic fallback
-- Icon SVGs next to visible text — add `aria-hidden="true"` to decorative icons
+- `IconButton` — provide `tip` (accessible name for icon-only).
+- `InfoTip` — provide `ariaLabel` or `ariaLabelledby`; there is no automatic fallback.
+- Decorative icon SVGs next to visible text — `aria-hidden="true"` on the icon.
 
 ## Form label association
 
-Match `htmlFor` on `<FormGroupLabel>` with the `id` on the input. `<FormGroup>` auto-wires `aria-live` for `error` and `description` — do not add redundant live regions manually.
+Match `htmlFor` on `<FormGroupLabel>` with the `id` on the control. Base `<FormGroup>` renders live regions for `error` and `description`; `GridForm` and `ConnectedForm` add field wiring (`aria-describedby`, `aria-invalid`, first-error `aria-live` behavior) — do not add redundant duplicate regions. Depth: [`skills/gamut-forms/SKILL.md`](../skills/gamut-forms/SKILL.md).
 
 ## Screen-reader-only text
 
@@ -62,8 +60,19 @@ Use `<Text screenreader>` for visually hidden but announced content. `<HiddenTex
 
 ## Color and contrast
 
-Do not hardcode hex values for adaptive UI. Gamut semantic color tokens through `ColorMode` are built for WCAG AA; see the `gamut-color-mode` skill for token usage. For non-text contrast, focus order, and ARIA beyond color, see `gamut-accessibility`.
+Do not hardcode hex for adaptive UI. Prefer semantic tokens and `ColorMode` / `<Background>` so surfaces track theme and mode — see the `gamut-color-mode` skill and [`foundations/modes.md`](../guidelines/foundations/modes.md). Default pairings support accessible UI, but tokens do not guarantee WCAG compliance for every layout; validate non-standard combinations.
 
 ## Focus visibility
 
-Never suppress focus indicators with `outline: none` or `outline: 0` without a visible replacement. Gamut's focus styles are intentional and meet WCAG 2.4.7.
+Never suppress focus indicators with `outline: none` or `outline: 0` without a visible replacement. Gamut’s focus styles are intentional (WCAG 2.4.7).
+
+## Where to read more (minimal index)
+
+| Topic | Primary doc |
+| --- | --- |
+| Forms (`GridForm`, `ConnectedForm`, `FormGroup`, validation, live regions) | [`skills/gamut-forms/SKILL.md`](../skills/gamut-forms/SKILL.md) |
+| Component matrix (tips, overlays, composites, checklists; not form wiring) | [`skills/gamut-accessibility/SKILL.md`](../skills/gamut-accessibility/SKILL.md) |
+| Button variants, `IconButton` `tip`, `disabled` vs `aria-disabled` | [`guidelines/components/buttons.md`](../guidelines/components/buttons.md) |
+| ColorMode, `Background`, semantic color roles | `gamut-color-mode` skill · [`foundations/modes.md`](../guidelines/foundations/modes.md) · [`foundations/color.md`](../guidelines/foundations/color.md) |
+| Tokens, `css` / `variant` / `states` | Storybook [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) |
+| Install, `GamutProvider`, CSP | Storybook [Meta / Installation](https://gamut.codecademy.com/?path=/docs-meta-installation--page) |