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

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

@@ -0,0 +1,101 @@
+---
+name: gamut-forms
+description: Implementing or auditing Gamut forms — GridForm, ConnectedForm, FormGroup, labels, validation. When invoked, read guidelines/components/forms.md first. Pair with gamut-accessibility for non-form widgets.
+---
+
+# Gamut forms
+
+## Read first
+
+When this skill applies, read [`guidelines/components/forms.md`](../../guidelines/components/forms.md) before writing code.
+
+Canonical wiring for `FormGroup`, `ConnectedForm`, `ConnectedFormGroup`, `GridForm`, and field renderers. Source: `packages/gamut/src/Form/`, `ConnectedForm/`, `GridForm/`.
+
+Universal label and primitive guidance: [`accessibility.mdc`](../../rules/accessibility.mdc) · overlay and composite patterns: [`gamut-accessibility`](../gamut-accessibility/SKILL.md).
+
+---
+
+## Mandatory: use organisms for functional forms
+
+Functional forms (submit/save, validation, dirty state) must use `GridForm` or `ConnectedForm`. Do not compose from bare `Input`, `Select`, `Checkbox`, etc.
+
+| Organism        | When                                                     |
+| --------------- | -------------------------------------------------------- |
+| `GridForm`      | Declarative `fields` + `submit` — settings, CRUD dialogs |
+| `ConnectedForm` | Custom layout with managed `react-hook-form` state       |
+
+Rules: Always set `defaultValues`. Use `validation="onChange"` when submit should stay disabled until valid. `hideLabel: true` on checkbox/radio fields with no `label`, and on toggle (`custom`) fields where `Toggle` renders its own label.
+
+---
+
+## Prefer connected layouts
+
+For typical product forms, prefer `GridForm` (declarative `fields`, `LayoutGrid`, submit/cancel) or `ConnectedForm` with `ConnectedFormGroup` / `useConnectedForm`. Use raw `FormGroup` + atoms only when the layout is simple and you fully own `id`, `htmlFor`, invalid state, and any `aria-describedby` (see below).
+
+---
+
+## Labels and controls
+
+`htmlFor` / `id` pairing — universal rule in [`accessibility.mdc`](../../rules/accessibility.mdc) (Form label association). Form-specific notes:
+
+- `FormGroupLabel` → control `id` (or stable `name` when that is your field’s id convention).
+- Checkbox, Radio, Select: same pairing; checkbox/radio use the visually hidden input pattern from `@codecademy/gamut-styles` where applicable.
+
+---
+
+## `FormGroup` (baseline)
+
+[`FormGroup.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/Form/elements/FormGroup.tsx)
+
+- `description` → `FormGroupDescription` with `aria-live="assertive"`.
+- `error` (string) → `FormError` with `aria-live="polite"` and `role="alert"`.
+
+Raw `FormGroup` does not set `aria-describedby` or `aria-invalid` on `children`. If you compose fields outside `ConnectedFormGroup` / `GridForm`, wire those yourself or accept that only the live regions above communicate errors/descriptions.
+
+---
+
+## `ConnectedFormGroup`
+
+[`ConnectedFormGroup.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/ConnectedForm/ConnectedFormGroup.tsx)
+
+- Passes `aria-describedby` (error region id when shown) and `aria-invalid` on the rendered field component.
+- `FormError`: `aria-live="assertive"` and `role="alert"` only when `isFirstError`; otherwise `aria-live="off"` and `role="status"` so subsequent errors do not interrupt repeatedly.
+
+---
+
+## `GridForm`
+
+[`GridFormInputGroup/index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/GridForm/GridFormInputGroup/index.tsx) · [`GridFormTextInput`](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/GridForm/GridFormInputGroup/GridFormTextInput/index.tsx)
+
+- Composes `ConnectedForm`, `LayoutGrid`, `GridFormButtons`, and field metadata. `FormError` uses the same first-error assertive pattern as `ConnectedFormGroup` (`aria-live` assertive vs off, `role` alert vs status).
+- Built-in text inputs set `aria-invalid` and register with react-hook-form via `register`. Custom / `custom` / `custom-group` renderers must still expose correct `id`, `label`, and error surfacing consistent with this pattern.
+
+---
+
+## Live regions — do not double up
+
+`FormGroup`, `ConnectedFormGroup`, and `GridForm` already render `FormError` (and base `FormGroup` renders `FormGroupDescription`) with live-region attributes. Do not add a second `aria-live` wrapper for the same message stream.
+
+---
+
+## Storybook
+
+- [Organisms / GridForm / About](https://gamut.codecademy.com/?path=/docs-organisms-gridform-about--docs) · [Usage](https://gamut.codecademy.com/?path=/docs-organisms-gridform-usage--docs) · [Validation](https://gamut.codecademy.com/?path=/docs-organisms-gridform-validation--docs) · [Fields](https://gamut.codecademy.com/?path=/docs-organisms-gridform-fields--docs)
+- [Organisms / ConnectedForm / ConnectedForm](https://gamut.codecademy.com/?path=/docs-organisms-connectedform-connectedform--docs) · [ConnectedFormGroup](https://gamut.codecademy.com/?path=/docs-organisms-connectedform-connectedformgroup--docs)
+
+---
+
+## Example — baseline `FormGroup`
+
+```tsx
+<FormGroup
+  htmlFor="email-input"
+  description="Used for login"
+  error={errors.email}
+>
+  <FormGroupLabel htmlFor="email-input">Email</FormGroupLabel>
+  <Input id="email-input" type="email" />
+</FormGroup>
+```
+
+When using `ConnectedFormGroup` or `GridForm`, prefer their docs and defaults over hand-rolling the above for every field.

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

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