@codecademy/gamut 68.6.2-alpha.f8b396.0 → 68.6.2

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

@@ -1,84 +0,0 @@
----
-name: gamut-forms
-description: Implementing or auditing Gamut forms — FormGroup, ConnectedForm, ConnectedFormGroup, GridForm, react-hook-form wiring, labels, and accessible error/description regions. Pair with `gamut-accessibility` for non-form widgets and `accessibility.mdc` for universal HTML/ARIA rules.
----
-
-# Gamut forms
-
-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).
-
----
-
-## 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-layout/SKILL.md

@@ -1,109 +0,0 @@
----
-name: gamut-layout
-description: Use this skill when applying Gamut spacing scale, border radii, viewport or container breakpoints, or page layout grid (LayoutGrid vs GridBox) — complements gamut-system-props for system.space and responsive props.
----
-
-# Gamut Layout
-
-Token values match [`packages/gamut-styles/src/variables`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/variables) (`spacing.ts`, `borderRadii.ts`, `responsive.ts`). Breakpoints and max-content widths align with Storybook [Foundations / Layout](https://gamut.codecademy.com/?path=/docs-foundations-layout--docs).
-
-See also: [`gamut-system-props`](../gamut-system-props/SKILL.md) — `system.space`, responsive `Box` / `FlexBox` / `GridBox` props. [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page) — responsive examples.
-
-## System props for spacing
-
-Gamut layout primitives (`Box`, `FlexBox`, `GridBox`, …) expose margin, padding, and gap props backed by `system.space` from `@codecademy/gamut-styles`. Pass spacing scale numbers (`4`, `8`, `16`, …), not raw pixel strings. For custom `styled` components, compose `system.space`.
-
-Responsive behavior: All those props accept mobile-first object (`{ _: 8, md: 24 }`) or array syntax per [Responsive properties](https://gamut.codecademy.com/?path=/docs-foundations-system-responsive-properties--page). Container queries use keys `c_base`, `c_xs`, … `c_xl`; the parent must set a container (e.g. `containerType="inline-size"` on `FlexBox`). Prefer a media-query fallback when mixing `c_*` with viewport breakpoints.
-
-## Two different “grids”
-
-- **Design / page grid** (12 columns, margins/gutters) — product layout; implement with [`LayoutGrid`](https://gamut.codecademy.com/?path=/docs-layouts-layoutgrid-layoutgrid--docs) and responsive `columnGap` / `rowGap` where appropriate.
-- **CSS Grid system props** — `system.grid` on styled components or `GridBox` for local regions; not the same as full-page `LayoutGrid`. See [System props / Grid](https://gamut.codecademy.com/?path=/docs-foundations-system-props-grid--page). `LayoutGrid` is for flexible full-page sections; use `FlexBox` / `GridBox` / `Box` for smaller areas.
-
-Designer vs code names: Figma / Layout docs often label artboards XL, LG, MD, SM, XS, Base. In code, viewport breakpoints are `xl`, `lg`, `md`, `sm`, `xs` (min-widths below); `_` is the base (no min-width query).
-
-## Spacing scale
-
-All spacing is multiples of 4px on an 8px grid.
-
-| Token | Value |
-| ----- | ----- |
-| `0`   | 0     |
-| `4`   | 4px   |
-| `8`   | 8px   |
-| `12`  | 12px  |
-| `16`  | 16px  |
-| `24`  | 24px  |
-| `32`  | 32px  |
-| `40`  | 40px  |
-| `48`  | 48px  |
-| `64`  | 64px  |
-| `96`  | 96px  |
-
-Use multiples of 8px for block-element spacing. Use 4px only for inline or typographic relationships.
-
-## Border radius
-
-| Token  | Value | Use                                |
-| ------ | ----- | ---------------------------------- |
-| `none` | 0px   | Square / non-interactive elements  |
-| `sm`   | 2px   | Subtle rounding, tags              |
-| `md`   | 4px   | Buttons, inputs, interactive cards |
-| `lg`   | 8px   | Cards, panels                      |
-| `xl`   | 16px  | Large cards, modals                |
-| `full` | 999px | Pills, avatars, circular elements  |
-
-## Breakpoints
-
-Mobile-first. Styles apply from the named breakpoint and up.
-
-| Token    | Min-width | Max content width |
-| -------- | --------- | ----------------- |
-| _(base)_ | 0         | 288px             |
-| `xs`     | 480px     | 448px             |
-| `sm`     | 768px     | 704px             |
-| `md`     | 1024px    | 896px             |
-| `lg`     | 1200px    | 1072px            |
-| `xl`     | 1440px    | 1248px            |
-
-## Container query breakpoints
-
-Container keys (`c_*`) use the same min-width numbers as viewport breakpoints, but they apply to the width of a CSS containment context (usually a parent), not the browser viewport.
-
-| Key      | Min container width |
-| -------- | ------------------- |
-| `c_base` | 1px                 |
-| `c_xs`   | 480px               |
-| `c_sm`   | 768px               |
-| `c_md`   | 1024px              |
-| `c_lg`   | 1200px              |
-| `c_xl`   | 1440px              |
-
-Requirements:
-
-- A descendant of an element that establishes a container — e.g. parent `<FlexBox containerType="inline-size">`. Without that, `c_*` rules never match.
-- Prefer a viewport fallback alongside `c_*` (e.g. `display={{ _: 'block', sm: 'flex', c_md: 'grid' }}`) for browsers or trees without container support.
-
-When to use which:
-
-- Viewport keys (`_`, `xs`, … `xl`) — page-level layout, full-bleed sections, global nav.
-- Container keys (`c_base`, … `c_xl`) — reusable widgets whose width is driven by layout, not the device alone.
-
-## Page layout grid (12 columns)
-
-12-column grid at all breakpoints.
-
-| Property           | xl/lg | md   | sm/xs | base |
-| ------------------ | ----- | ---- | ----- | ---- |
-| Horizontal margins | 64px  | 48px | 32px  | 16px |
-| Column gutters     | 32px  | 24px | 16px  | 8px  |
-| Row gaps           | 32px  | 24px | 16px  | 8px  |
-
-Minimum touch target on mobile: 44×44px — see [`gamut-accessibility`](../gamut-accessibility/SKILL.md).
-
-## Responsive rules
-
-- Begin design work at 1440px (XL), then adapt down.
-- Multi-column layouts collapse to fewer columns — do not stretch or squish.
-- Catalog cards and non-lockup elements should align on one axis (usually left), not fill column widths.
-- Avoid dense or small components at the base (mobile) breakpoint.

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

@@ -1,273 +0,0 @@
----
-name: gamut-list
-description: Use this skill when building list or table layouts with List, ListRow, ListCol, and TableHeader — including variant and spacing selection, expandable row patterns, ordered/table layouts, and the rule that a list of disclosure-style items must use List's expandable row pattern (not multiple Disclosure components). See gamut-accessibility for ARIA and focus guidance.
----
-
-# Gamut List
-
-Structured, repeating layouts built from `List`, `ListRow`, `ListCol`, and `TableHeader`. Colors, borders, and spacing are wired through the `variant` and `spacing` props — consumers do not override these with raw CSS values.
-
-Source: `@codecademy/gamut` — [List.tsx](https://github.com/Codecademy/gamut/blob/main/packages/gamut/src/List/List.tsx)
-
-See also: [`gamut-accessibility`](../gamut-accessibility/SKILL.md) — ARIA, focus, and keyboard interaction rules. [`gamut-layout`](../gamut-layout/SKILL.md) — spacing tokens and system props.
-
-Storybook:
-
-- [Organisms / Lists & Tables / List](https://gamut.codecademy.com/?path=/docs-organisms-lists-tables-list-list--docs)
-- [ListRow](https://gamut.codecademy.com/?path=/docs-organisms-lists-tables-list-listrow--docs)
-- [ListCol](https://gamut.codecademy.com/?path=/docs-organisms-lists-tables-list-listcol--docs)
-
-## Components
-
-```tsx
-import { List, ListRow, ListCol, TableHeader } from '@codecademy/gamut';
-```
-
-| Component     | Role                                                                    |
-| ------------- | ----------------------------------------------------------------------- |
-| `List`        | Root wrapper; sets `variant`, `spacing`, `as`, and context for children |
-| `ListRow`     | Single row; handles expandable content and click interactions           |
-| `ListCol`     | Column cell; controls `type`, `size`, `fill`, and justification         |
-| `TableHeader` | Sticky header row; use only with `List as="table"`                      |
-
-## When to use List
-
-- Displaying repetitive content where individual rows may contain interactive elements, metrics, or controls — use List, not Card.
-- Comparing data across rows — use `variant="table"` (or `as="table"`) rather than a plain `<table>`.
-- Needing numbered rows — use `as="ol"`.
-- **Needing multiple expandable/disclosure-style items** — use List's expandable row pattern (see [Expandable rows](#expandable-rows)), not multiple standalone `Disclosure` components.
-
-## Variants
-
-```tsx
-<List variant="default" />
-```
-
-| `variant` | Use for                                                                                                 |
-| --------- | ------------------------------------------------------------------------------------------------------- |
-| `default` | Rows with abstract content (buttons, custom renders); bordered, no gutter                               |
-| `table`   | Metrics or comparable data; alternating row backgrounds                                                 |
-| `card`    | Content that doesn't need to be adjacent (e.g. curriculum progress); bordered rows with vertical gutter |
-| `block`   | Feature-forward designs or page scaffolding; always on a colored background                             |
-| `plain`   | Minimal styling — no borders or backgrounds; apply custom styles per row via Emotion `styled`           |
-
-## Spacing
-
-```tsx
-<List spacing="condensed" />
-```
-
-| `spacing`   | Use for                                      |
-| ----------- | -------------------------------------------- |
-| `normal`    | Mixed content that needs room for components |
-| `condensed` | Default choice; reduced padding between rows |
-| `compact`   | Tightest layout; data-dense views            |
-
-## `as` prop
-
-Default is `ul`. Pass `as="ol"` for numbered rows or `as="table"` for semantic table output.
-
-```tsx
-// ordered list — always include one ListCol with type="header" so numbering renders correctly
-<List as="ol">
-  <ListRow>
-    <ListCol type="header">Step one</ListCol>
-    <ListCol>Details</ListCol>
-  </ListRow>
-</List>
-
-// semantic table with sticky header
-<List as="table">
-  <TableHeader>
-    <ListCol columnHeader>Name</ListCol>
-    <ListCol columnHeader>Role</ListCol>
-  </TableHeader>
-  <ListRow>
-    <ListCol type="header">Worf</ListCol>
-    <ListCol>Lieutenant Commander</ListCol>
-  </ListRow>
-</List>
-```
-
-## Key props
-
-### List
-
-| Prop                    | Type                                                   | Default     | Effect                                                   |
-| ----------------------- | ------------------------------------------------------ | ----------- | -------------------------------------------------------- |
-| `variant`               | `'default' \| 'table' \| 'card' \| 'block' \| 'plain'` | `'default'` | Row styling                                              |
-| `spacing`               | `'normal' \| 'condensed' \| 'compact'`                 | `'normal'`  | Row padding                                              |
-| `as`                    | `'ul' \| 'ol' \| 'table'`                              | `'ul'`      | Rendered element and semantic meaning                    |
-| `header`                | `React.ReactNode`                                      | —           | Node rendered above the row list                         |
-| `emptyMessage`          | `React.ReactNode`                                      | —           | Shown when children is empty                             |
-| `loading`               | `boolean`                                              | —           | Shows placeholder while data loads                       |
-| `scrollable`            | `boolean`                                              | `false`     | Enables horizontal scroll with sticky first column       |
-| `shadow`                | `boolean`                                              | `false`     | Right-side shadow when scrollable content overflows      |
-| `disableContainerQuery` | `boolean`                                              | `false`     | Falls back to media queries instead of container queries |
-| `rowBreakpoint`         | `'xs' \| 'sm' \| 'md'`                                 | `'xs'`      | Breakpoint at which columns stack                        |
-
-### ListRow
-
-| Prop                       | Type                    | Notes                                                                   |
-| -------------------------- | ----------------------- | ----------------------------------------------------------------------- |
-| `expanded`                 | `boolean`               | Required when `renderExpanded` is set                                   |
-| `renderExpanded`           | `() => React.ReactNode` | Content revealed when `expanded` is true; animates in/out               |
-| `expandedRowAriaLabel`     | `string`                | `aria-label` for the revealed region                                    |
-| `keepSpacingWhileExpanded` | `boolean`               | Maintains row spacing while content is expanded                         |
-| `onClick`                  | mouse event handler     | Makes the full row interactive (adds `role="button"`, keyboard support) |
-
-### ListCol `type`
-
-| `type`          | Use for                                                |
-| --------------- | ------------------------------------------------------ |
-| `header`        | Primary label column; sticky when `List` is scrollable |
-| `content`       | Secondary text content                                 |
-| `control`       | Action controls (buttons, menus)                       |
-| `expand`        | Expanded content area                                  |
-| `expandControl` | The toggle button column (no right-padding)            |
-| `select`        | Checkbox / selection column                            |
-
-### ListCol `size`
-
-`'content'` (default, fits content) | `'sm'` | `'md'` | `'lg'` | `'xl'`
-
-Pass `fill` to grow a column to fill remaining space.
-
-## Expandable rows
-
-List provides two patterns for rows that reveal content. Both animate open/closed via framer-motion.
-
-### Expand on button click
-
-Use `ExpandControl` in a `type="expandControl"` column to toggle a specific row.
-
-```tsx
-const [isExpanded, setExpanded] = useState(false);
-
-<ListRow
-  expanded={isExpanded}
-  renderExpanded={() => <Text>Revealed content</Text>}
-  expandedRowAriaLabel="Row details"
->
-  <ListCol type="header">Row label</ListCol>
-  <ListCol type="content">Secondary detail</ListCol>
-  <ListCol type="expandControl">
-    <ExpandControl
-      expanded={isExpanded}
-      onExpand={() => setExpanded(!isExpanded)}
-    />
-  </ListCol>
-</ListRow>;
-```
-
-### Expand on row click
-
-Pass `onClick` to `ListRow` to make the entire row the toggle target. The row receives `role="button"` and keyboard Enter support automatically.
-
-```tsx
-const [isExpanded, setExpanded] = useState(false);
-
-<ListRow
-  expanded={isExpanded}
-  onClick={() => setExpanded(!isExpanded)}
-  renderExpanded={() => <Text>Revealed content</Text>}
->
-  <ListCol type="header">Row label</ListCol>
-  <ListCol type="content">Secondary detail</ListCol>
-  <ListCol type="control">
-    <Rotation rotated={isExpanded}>
-      <ArrowChevronDownIcon color="text-disabled" />
-    </Rotation>
-  </ListCol>
-</ListRow>;
-```
-
-## List of disclosure-style items
-
-When you need multiple expandable items (an FAQ, an accordion, a list of sections), **use List's expandable row pattern above — do not render multiple standalone `Disclosure` components**.
-
-`Disclosure` is designed for a single, isolated expandable container. For two or more expandable items, the correct pattern is `List` + `ListRow` with `expanded` / `renderExpanded`:
-
-```tsx
-// correct — list of expandable items
-<List variant="default" spacing="normal">
-  {items.map(({ id, title, body }) => {
-    const [isExpanded, setExpanded] = useState(false);
-    return (
-      <ListRow
-        key={id}
-        expanded={isExpanded}
-        renderExpanded={() => <Box p={16}>{body}</Box>}
-        expandedRowAriaLabel={`${title} details`}
-      >
-        <ListCol type="header" fill>{title}</ListCol>
-        <ListCol type="expandControl">
-          <ExpandControl
-            expanded={isExpanded}
-            onExpand={() => setExpanded(!isExpanded)}
-          />
-        </ListCol>
-      </ListRow>
-    );
-  })}
-</List>
-
-// wrong — multiple Disclosure components
-<Disclosure heading="Item 1" body="..." />
-<Disclosure heading="Item 2" body="..." />
-```
-
-## Empty state and loading
-
-```tsx
-// custom empty message
-<List emptyMessage={<Text>No results found.</Text>}>
-  {rows}
-</List>
-
-// loading placeholder
-<List loading>{rows}</List>
-```
-
-## Scrollable layout
-
-Use `scrollable` when a list has many columns and collapsing would lose information. The first (`type="header"`) column sticks to the left.
-
-```tsx
-<List scrollable shadow>
-  <TableHeader>
-    <ListCol type="header" columnHeader>
-      Name
-    </ListCol>
-    <ListCol size="md" columnHeader>
-      Score
-    </ListCol>
-    <ListCol size="md" columnHeader>
-      Progress
-    </ListCol>
-  </TableHeader>
-  {rows}
-</List>
-```
-
-## Container queries
-
-By default `List` uses CSS container queries for responsive column stacking. Disable only when:
-
-- The `List` lives in a container narrower than its breakpoint
-- You are managing your own responsive logic
-- The list has very few rows and container query overhead is unwanted
-
-```tsx
-<List disableContainerQuery spacing="condensed">
-  {rows}
-</List>
-```
-
-## Accessibility
-
-- `ListRow` sets `aria-live="polite"` automatically when `renderExpanded` is present — do not add a duplicate live region.
-- Pass `expandedRowAriaLabel` to label the revealed `role="region"`.
-- `onClick` on `ListRow` adds `role="button"` and keyboard Enter support automatically.
-- For sortable columns pass `aria-sort` on the relevant `ListCol`.
-- Ordered lists (`as="ol"`) must include at least one `ListCol type="header"` per row for numbering to render correctly.