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

package/agent-tools/guidelines/components/data-table.md

@@ -0,0 +1,79 @@
+# DataTable & DataList sorting
+
+`DataTable` and `DataList` do not sort data automatically. `sortable: true` on a column only renders sort UI. You must implement sorting via `query` and `onQueryChange`, and pass pre-sorted `rows`.
+
+## How sorting works
+
+1. `sortable: true` — enables sort toggle on the column header. Without `query` / `onQueryChange`, clicks do nothing.
+2. `query` — `Query<Row>` holding current sort (and filter) state. `sort` maps column keys to `'asc' | 'desc'`.
+3. `onQueryChange` — receives `QueryChangeEvent<Row>` when the user clicks a sortable header. Update `query` in your handler.
+4. Sorted rows — sort the `rows` array yourself from `query.sort` before passing to the component.
+
+## Required pattern
+
+```tsx
+import { useMemo, useReducer } from 'react';
+import { DataTable } from '@codecademy/gamut';
+import type { Query, QueryChangeEvent } from '@codecademy/gamut';
+
+function queryReducer<Row>(
+  state: Query<Row>,
+  event: QueryChangeEvent<Row>
+): Query<Row> {
+  switch (event.type) {
+    case 'sort': {
+      const { dimension, value } = event.payload;
+      if (value === 'none') {
+        const { [dimension]: _, ...rest } = state.sort ?? {};
+        return { ...state, sort: rest };
+      }
+      return { ...state, sort: { [dimension]: value } };
+    }
+    case 'filter': {
+      const { dimension, value } = event.payload;
+      return { ...state, filter: { ...state.filter, [dimension]: value } };
+    }
+    case 'reset':
+      return {};
+    default:
+      return state;
+  }
+}
+
+const [query, onQueryChange] = useReducer(queryReducer, {});
+
+const sortedRows = useMemo(() => {
+  const sorted = [...rows];
+  const sortEntries = Object.entries(query.sort ?? {});
+  if (sortEntries.length > 0) {
+    const [key, direction] = sortEntries[0];
+    sorted.sort((a, b) => {
+      const aVal = String(a[key]).toLowerCase();
+      const bVal = String(b[key]).toLowerCase();
+      if (aVal < bVal) return direction === 'asc' ? -1 : 1;
+      if (aVal > bVal) return direction === 'asc' ? 1 : -1;
+      return 0;
+    });
+  }
+  return sorted;
+}, [query.sort, rows]);
+
+<DataTable
+  id="my-table"
+  idKey="id"
+  rows={sortedRows}
+  columns={columns}
+  query={query}
+  onQueryChange={onQueryChange}
+/>;
+```
+
+## Rules
+
+1. Never use `sortable: true` without `query` and `onQueryChange`.
+2. Always sort rows client-side (or server-side before passing) from `query.sort`.
+3. Handle `'sort'`, `'filter'`, and `'reset'` in the reducer even if you only use sorting.
+4. One active sort column in standard usage — replace the previous sort entry when the user picks a new column.
+5. Import `Query` and `QueryChangeEvent` from `@codecademy/gamut` for type safety.
+
+Storybook: [Organisms / DataTable](https://gamut.codecademy.com/?path=/docs-organisms-datatable--docs)

package/agent-tools/guidelines/components/forms.md

@@ -0,0 +1,106 @@
+# Forms
+
+Gamut provides two form organisms — `GridForm` and `ConnectedForm` — that handle layout, validation, submission state, and field registration. Always use one of these organisms for functional forms. Do not compose forms from individual form atoms when the interface needs submit, validation, reset, or dirty tracking.
+
+Related: [`skills/gamut-forms/SKILL.md`](../../skills/gamut-forms/SKILL.md) (accessibility wiring) · [`skills/gamut-accessibility/SKILL.md`](../../skills/gamut-accessibility/SKILL.md) (universal ARIA)
+
+## When to use each
+
+| Component       | Use when                                                                                                                                                                                                        |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GridForm`      | Declarative, config-driven form. Pass `fields` (and optional `sections`) plus `submit` — layout, labels, validation, and submit button are automatic. Best for settings pages, profile forms, and CRUD dialogs. |
+| `ConnectedForm` | Full layout control with managed form state. Provides `react-hook-form` context; compose with `ConnectedFormGroup` and connected inputs. Best for tabs, custom columns, or content interleaved with fields.     |
+
+## Rules
+
+1. Never use bare form atoms for functional forms. `Input`, `Select`, `Checkbox`, `Radio`, `TextArea`, `FormGroup`, and `FormGroupLabel` are building blocks _inside_ organisms. Use them standalone only when there is no submit step (e.g. live search filter, immediate callback toggle).
+2. Prefer `GridForm` over `ConnectedForm` when the layout fits a grid.
+3. Always provide `defaultValues`. Omitting defaults causes uncontrolled-to-controlled warnings and broken resets.
+4. Use `validation="onChange"` when the submit button should stay disabled until required fields are valid. Default `"onSubmit"` validates only on submit.
+5. `GridForm` sections — use `GridFormSectionProps` (`title`, `as`, `fields`) to group fields under headings in one form, not multiple separate forms.
+6. Import connected inputs from `@codecademy/gamut`. `ConnectedInput`, `ConnectedSelect`, `ConnectedCheckbox`, `ConnectedRadioGroup`, `ConnectedTextArea`, `ConnectedFormGroup`, `SubmitButton`.
+7. `hideLabel: true` on checkbox/radio fields with no `label`. Without it, `FormGroupLabel` renders a stray "(optional)" or "\*" row above the control.
+8. `hideLabel: true` on toggle (`custom` type) fields. `Toggle` renders its own inline label; a `FormGroupLabel` above is redundant.
+
+## GridForm example
+
+```tsx
+import { GridForm } from '@codecademy/gamut';
+
+<GridForm
+  fields={[
+    {
+      title: 'General',
+      as: 'h2',
+      variant: 'title-sm',
+      fields: [
+        {
+          name: 'orgName',
+          label: 'Organization Name',
+          type: 'text',
+          size: 6,
+          defaultValue: 'Acme Corp',
+        },
+        {
+          name: 'emailNotifs',
+          description: 'Receive email notifications',
+          type: 'checkbox',
+          size: 12,
+          defaultValue: true,
+          hideLabel: true,
+        },
+      ],
+    },
+  ]}
+  submit={{ contents: 'Save Settings', size: 12 }}
+  onSubmit={(values) => console.log(values)}
+  validation="onChange"
+/>;
+```
+
+## ConnectedForm example (`useConnectedForm`)
+
+Prefer `useConnectedForm` for custom layouts — it types `ConnectedForm` / `ConnectedFormGroup` from `defaultValues` and spreads `connectedFormProps` (defaults + `validationRules`).
+
+```tsx
+import {
+  ConnectedForm,
+  ConnectedFormGroup,
+  ConnectedInput,
+  SubmitButton,
+  useConnectedForm,
+} from '@codecademy/gamut';
+
+export const ProfileForm = () => {
+  const { ConnectedFormGroup, ConnectedForm, connectedFormProps } =
+    useConnectedForm({
+      defaultValues: { displayName: '' },
+      validationRules: {
+        displayName: { required: 'Display name is required' },
+      },
+    });
+
+  return (
+    <ConnectedForm
+      onSubmit={(values) => console.log(values)}
+      validation="onChange"
+      {...connectedFormProps}
+    >
+      <ConnectedFormGroup
+        name="displayName"
+        label="Display Name"
+        field={{ component: ConnectedInput }}
+      />
+      <SubmitButton>Save</SubmitButton>
+    </ConnectedForm>
+  );
+};
+```
+
+## Quick reference
+
+| Layer            | Components                                                                                                                                 | When to use directly                   |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------- |
+| Organisms        | `GridForm`, `ConnectedForm`                                                                                                                | Always for functional forms            |
+| Connected inputs | `ConnectedInput`, `ConnectedSelect`, `ConnectedCheckbox`, `ConnectedRadioGroup`, `ConnectedTextArea`, `ConnectedFormGroup`, `SubmitButton` | Only inside `ConnectedForm`            |
+| Atoms            | `Input`, `Select`, `Checkbox`, `Radio`, `TextArea`, `FormGroup`, `FormGroupLabel`, `FormError`                                             | Standalone display / live filters only |

package/agent-tools/guidelines/components/loading-states.md

@@ -0,0 +1,17 @@
+# Loading states
+
+Use `Shimmer` or `Spinner` for loading states. Do not use `FeatureShimmer` as a loading indicator.
+
+Storybook: [Atoms / Shimmer](https://gamut.codecademy.com/?path=/docs-atoms-shimmer--docs) · [Spinner](https://gamut.codecademy.com/?path=/docs-atoms-spinner--docs)
+
+## Components
+
+| Component        | Use for                                                                                                               |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `Shimmer`        | Skeleton placeholders for content being loaded                                                                        |
+| `Spinner`        | Indeterminate spinner for active loading                                                                              |
+| `FeatureShimmer` | Not a loader. Draws attention to secondary new features on a page. Do not use as a general-purpose loading indicator. |
+
+## Rule
+
+`Shimmer` and `Spinner` are the only true loading indicators. `FeatureShimmer` is for new-feature surfacing only.

package/agent-tools/guidelines/components/menu.md

@@ -0,0 +1,58 @@
+# Menu
+
+`Menu` and `MenuItem` from `@codecademy/gamut` are stateless — the consumer manages `active` and `disabled` state.
+
+Related: [`skills/gamut-accessibility/SKILL.md`](../../skills/gamut-accessibility/SKILL.md)
+
+Storybook: [Molecules / Menu](https://gamut.codecademy.com/?path=/docs-molecules-menu--docs)
+
+## Variants — always set explicitly
+
+Always pass the `variant` prop. Relying on the default produces the wrong variant for persistent navigation.
+
+| Variant   | Use for                                                                                                             | Rendering                                      |
+| --------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| `fixed`   | Persistent inline navigation — sidebars, primary nav, footer nav, any menu that does not open/close on interaction. | Must use `as="nav"` for accessible navigation. |
+| `popover` | Temporary surfaces — overflow menus, action menus, kebab menus, dismiss on outside click.                           | Default popover surface.                       |
+
+### Fixed (sidebar / persistent navigation)
+
+```tsx
+<Menu variant="fixed" as="nav">
+  <MenuItem
+    active={activeId === 'overview'}
+    onClick={() => setActive('overview')}
+  >
+    Overview
+  </MenuItem>
+  <MenuItem
+    active={activeId === 'settings'}
+    onClick={() => setActive('settings')}
+  >
+    Settings
+  </MenuItem>
+</Menu>
+```
+
+### Popover (overflow / action menu)
+
+```tsx
+<Menu variant="popover">
+  <MenuItem onClick={handleEdit}>Edit</MenuItem>
+  <MenuItem disabled label="Owner permissions required" onClick={handleDelete}>
+    Delete
+  </MenuItem>
+</Menu>
+```
+
+## `MenuItem` state
+
+- `active: boolean` — currently selected item; drive from your state.
+- `disabled: boolean` — unavailable for interaction.
+- `label: string` — when `disabled`, renders a `ToolTip` explaining why. Provide for any disabled item users might question.
+
+## Do not stretch `Menu` in flex layouts
+
+`Menu` is a flex column sized to its content. If an ancestor is a flex child that stretches (`flex={1}`, `height: 100%`, `alignSelf: stretch`), the menu expands and items spread apart.
+
+Rule: Wrap `Menu` in a block-level container with intrinsic height (`as="nav"` on a fixed menu, `Box`, or `div`). Do not use `FlexBox` as the immediate wrapper, and do not apply stretch on ancestors between `Menu` and the sidebar scroll container.

package/agent-tools/guidelines/components/overview.md

@@ -2,43 +2,123 @@
 
 52 components have Figma ↔ code mappings via Figma Code Connect (`packages/code-connect/`). Live code snippets appear in Figma's inspect panel when you select a component.
 
-## Atoms — foundational, single-purpose
+## Core rules
 
-Badge, Button (FillButton, StrokeButton, CTAButton, TextButton, IconButton), ButtonBase, Card, Checkbox, CodeBlock, ColorMode, Drawer, FlexBox, FormGroup, GridBox, HiddenText, Icon, Input, Label, Loader, Radio, Select, Spinner, Tag, TextArea, Toggle, Tooltip
+- Always use existing Gamut components from `packages/gamut/src` rather than one-off equivalents. See the quick reference table below.
+- Apply exact sizing, variant, and props from the source. Never rely on defaults when the design or prompt specifies a value (e.g. `size="small"` on `Input`, `sizeVariant="small"` on `Select`).
+- When unsure, reference `Badge`, `Tag`, or button atoms in `packages/gamut/src`.
 
-## Molecules — composed of atoms
+## Forms vs. standalone inputs
+
+Functional forms — submit/save bundling multiple fields, validation, errors, or dirty tracking — must use `GridForm` or `ConnectedForm`. Read [forms.md](forms.md) before building any functional form.
+
+Standalone inputs — live search, real-time filters, single controls that update state immediately — use bare atoms (`Input`, `Select`, `Checkbox`, `Radio`, `TextArea`, `FormGroup`). No organism when there is no submit step.
+
+The test: submit/save bundled values → organism. Real-time state with no submit → atom.
+
+## Component discovery
+
+Before custom markup for any UI pattern:
+
+1. Enumerate exports — check `@codecademy/gamut` public API or `index.d.ts`.
+2. Prefer Gamut over raw HTML — e.g. `Menu` for nav, `DataTable` for tables, `Tabs` for tabs. Do not rebuild from `<ul>` / `<motion.div>` when a primitive exists.
+3. Read type definitions for props before custom wrappers.
+4. Never build custom media players — use `Video` ([video.md](video.md)).
+5. When no Gamut component exists, comment: `{/* No Gamut component for [pattern] — custom markup */}`
+
+### Quick reference
+
+| UI Pattern            | Gamut component(s)                                                    | Guide                                                                    |
+| --------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| Buttons               | `FillButton`, `StrokeButton`, `TextButton`, `IconButton`, `CTAButton` | [buttons.md](buttons.md)                                                 |
+| Links                 | `Anchor`                                                              | —                                                                        |
+| Typography            | `Text`                                                                | [`gamut-typography` skill](../../skills/gamut-typography/SKILL.md)       |
+| Markdown              | `Markdown`                                                            | —                                                                        |
+| Layout                | `Box`, `FlexBox`, `GridBox`, `Layout`, `LayoutGrid`                   | [spacing.md](../foundations/spacing.md)                                  |
+| Animations            | `Rotation`, `ExpandInCollapseOut`, `FadeInSlideOut`                   | [animations.md](animations.md)                                           |
+| Page containers       | `ContentContainer`, `GridContainer`                                   | —                                                                        |
+| Navigation / menus    | `Menu`, `MenuItem`, `MenuSeparator`                                   | [menu.md](menu.md)                                                       |
+| Breadcrumbs           | `Breadcrumbs`                                                         | —                                                                        |
+| Pagination            | `Pagination`                                                          | —                                                                        |
+| Tabs                  | `Tabs`                                                                | [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md) |
+| Accordions            | `Disclosure`                                                          | —                                                                        |
+| Data tables           | `DataTable`, `DataList`                                               | [data-table.md](data-table.md)                                           |
+| Lists                 | `List`                                                                | —                                                                        |
+| Cards                 | `Card`                                                                | [card.md](card.md)                                                       |
+| Charts                | `BarChart`                                                            | —                                                                        |
+| Modals                | `Dialog` (binary confirm/cancel); `Modal` (multi-view, complex)       | [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md) |
+| Drawers / flyouts     | `Drawer`, `Flyout`                                                    | [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md) |
+| Overlays / focus trap | `Overlay`, `FocusTrap`                                                | [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md) |
+| Popovers              | `Popover`, `PopoverContainer`                                         | —                                                                        |
+| Tooltips              | `ToolTip`, `InfoTip`, `PreviewTip`                                    | [tooltips.md](tooltips.md)                                               |
+| Onboarding            | `Coachmark`                                                           | [coachmark.md](coachmark.md)                                             |
+| Alerts / toasts       | `Alert`, `Toast`, `Toaster`                                           | —                                                                        |
+| Badges / tags         | `Badge`, `Tag`                                                        | —                                                                        |
+| Progress              | `ProgressBar`, `RadialProgress`                                       | [radial-progress.md](radial-progress.md)                                 |
+| Loading               | `Shimmer`, `Spinner`                                                  | [loading-states.md](loading-states.md)                                   |
+| Video                 | `Video`                                                               | [video.md](video.md)                                                     |
+| Forms                 | `GridForm`, `ConnectedForm`                                           | [forms.md](forms.md)                                                     |
+| Standalone inputs     | `Input`, `Select`, `Checkbox`, `Radio`, `TextArea`, `FormGroup`       | Forms breadcrumb above                                                   |
+| Rich select           | `SelectDropdown`                                                      | [select.md](select.md)                                                   |
+| Date                  | `DatePicker`                                                          | [`gamut-forms` skill](../../skills/gamut-forms/SKILL.md)                 |
+| Toggle (standalone)   | `Toggle`                                                              | —                                                                        |
+| Screen reader text    | `HiddenText`                                                          | —                                                                        |
+| Skip link             | `SkipToContent`                                                       | —                                                                        |
+| Dark / light regions  | `ColorMode`, `Background`                                             | [modes.md](../foundations/modes.md)                                      |
+
+## Validate variant props
+
+`Card`, `Badge`, `Tag`, and `Alert` accept specific `variant` values. Invalid strings (e.g. `"navy-on-white"`) crash `parseToHsl()` at runtime. Inspect prop types in `@codecademy/gamut` before using variant/color props. See [card.md](card.md) for `Card` variants.
+
+## Catalog by layer
+
+### Atoms
+
+Badge, FillButton, StrokeButton, CTAButton, TextButton, IconButton, Card, Checkbox, CodeBlock, Drawer, FlexBox, FormGroup, GridBox, HiddenText, Icon, Input, Label, Loader, Radio, Select, Spinner, Tag, TextArea, Toggle, Tooltip
+
+### Molecules
 
 Alert, Anchor, Breadcrumbs, Coachmark, Disclosure, GridForm, Markdown, Menu, Modal, Pagination, Popover, ProgressBar, Table, Tabs, Toast, Toaster, Video
 
-## Organisms — page-level compositions
+### Organisms
 
 ContentContainer, GridContainer, Layout, LayoutGrid
 
 ## Key patterns
 
 ### Buttons
-See [buttons.md](buttons.md) for full reference. Use `FillButton` for primary actions, `StrokeButton` for secondary.
+
+[buttons.md](buttons.md) — `FillButton` primary, `StrokeButton` secondary.
+
+### Forms and accessibility
+
+[forms.md](forms.md) · [`gamut-forms` skill](../../skills/gamut-forms/SKILL.md) · [`gamut-accessibility` skill](../../skills/gamut-accessibility/SKILL.md)
 
 ### Cards
-- **Background variants**: `default` (ColorMode-responsive), `white`, `yellow`, `beige`, `navy`, `hyper`
-- **Shadow variants**: `none` (default), `outline`, `patternLeft`, `patternRight`
+
+See [card.md](card.md). Variants include `default`, `white`, `yellow`, `hyper`, `navy`. Confirm against `DESIGN.md` for theme-specific surfaces.
+`FormGroup`, `GridForm`, `ConnectedForm`, tips, dialogs, composite widgets: [`skills/gamut-forms/SKILL.md`](../../skills/gamut-forms/SKILL.md) (forms) · [`skills/gamut-accessibility/SKILL.md`](../../skills/gamut-accessibility/SKILL.md) (overlays, composites, checklists) · Storybook [Meta / Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page).
+
+- Background variants: `default` (ColorMode-responsive), `white`, `yellow`, `beige`, `navy`, `hyper`
+- Shadow variants: `none` (default), `outline`, `patternLeft`, `patternRight`
 - Add `isInteractive` when wrapping in `<Anchor>` — enables hover shadow + `borderRadius: md`
 - Default `borderRadius` is `none`; override with `borderRadius` prop
 
-### Color-aware components
-- `<ColorMode mode="light|dark|system">` — scopes a subtree to an explicit color mode
-- `<Background bg="<color>">` — applies background color + auto-switches inner color mode for contrast
+### Color-aware regions
+
+[foundations/modes.md](../foundations/modes.md) — `<ColorMode mode="light|dark|system">`, `<Background bg="…">`.
 
 ### Alerts
-| Variant | Tokens |
-|---|---|
-| Error | `feedback-error` + `background-error` |
+
+| Variant | Tokens                                    |
+| ------- | ----------------------------------------- |
+| Error   | `feedback-error` + `background-error`     |
 | Success | `feedback-success` + `background-success` |
 | Warning | `feedback-warning` + `background-warning` |
 
 ## Global tokens
 
-| Token | Value | Use |
-|---|---|---|
-| `headerHeight` | 64px (base), 80px (md+) | Global page header height |
-| `headerZ` | 15 | Z-index for global page header |
+| Token          | Value                   | Use                |
+| -------------- | ----------------------- | ------------------ |
+| `headerHeight` | 64px (base), 80px (md+) | Global page header |
+| `headerZ`      | 15                      | Header z-index     |

package/agent-tools/guidelines/components/radial-progress.md

@@ -0,0 +1,13 @@
+# RadialProgress
+
+Storybook: [Molecules / RadialProgress](https://gamut.codecademy.com/?path=/docs-molecules-radialprogress--docs)
+
+## Labels as `children` by default
+
+`RadialProgress` renders children in a centered overlay inside the ring. Place the label (e.g. percentage text) as a child, not as a sibling below the component, unless the design explicitly places it outside the ring.
+
+```tsx
+<RadialProgress percent={75}>
+  <Text>75%</Text>
+</RadialProgress>
+```

package/agent-tools/guidelines/components/select.md

@@ -0,0 +1,23 @@
+# Select vs. SelectDropdown
+
+`Select` is a native select suitable for most dropdown needs. Prefer `Select` over `SelectDropdown` for simple lists.
+
+Storybook: [Atoms / Select](https://gamut.codecademy.com/?path=/docs-atoms-select--docs) · [Organisms / SelectDropdown](https://gamut.codecademy.com/?path=/docs-organisms-selectdropdown--docs)
+
+## When to use `SelectDropdown`
+
+Only when you need:
+
+- Searchable/filterable options (`isSearchable`)
+- Multi-select (`multiple`)
+- Option subtitles, right labels, icons, abbreviations
+- Grouped options with dividers and group labels
+- Custom option styling
+
+## When to use `Select`
+
+Plain option lists with no enrichment — simpler, more performant, and more accessible.
+
+## Sizing
+
+Apply exact sizing from the design (e.g. `sizeVariant="small"` on `Select`) — do not rely on defaults when the source specifies a value.

package/agent-tools/guidelines/components/tooltips.md

@@ -0,0 +1,22 @@
+# ToolTip and InfoTip
+
+Related: [`skills/gamut-accessibility/SKILL.md`](../../skills/gamut-accessibility/SKILL.md) (`aria-describedby`, `InfoTip` labeling)
+
+Storybook: [Molecules / ToolTip](https://gamut.codecademy.com/?path=/docs-molecules-tips-tooltip--docs) · [InfoTip](https://gamut.codecademy.com/?path=/docs-molecules-tips-infotip--docs)
+
+## Use `placement: 'floating'` inside overflow containers
+
+`ToolTip` defaults to `placement: 'inline'`, which is clipped by ancestors with `overflow: hidden` (e.g. `DataTable` rows).
+
+When an `IconButton` or `ToolTip` is inside a table, card, or clipping container:
+
+- `tipProps={{ placement: 'floating' }}` on `IconButton`
+- `placement="floating"` on `ToolTip` directly
+
+This renders the tooltip in a floating layer above surrounding content.
+
+## Use `alignment="bottom-*"` near the top of the viewport
+
+Tips default to opening above the trigger. Near the page top (e.g. in a heading), the tip can clip.
+
+Pass `alignment="bottom-right"` or `"bottom-left"` so the tip opens downward.

package/agent-tools/guidelines/components/video.md

@@ -0,0 +1,29 @@
+# Video
+
+Never build custom media players. Gamut exports `Video` (built on `@vidstack/react`) with controls, poster support, text tracks, and accessibility.
+
+Storybook: [Molecules / Video](https://gamut.codecademy.com/?path=/docs-molecules-video--docs)
+
+## Rule
+
+Before constructing `<video>`, image + play-button overlays, or third-party embed wrappers, use `Video`.
+
+## Common props
+
+| Prop               | Purpose             |
+| ------------------ | ------------------- |
+| `videoUrl`         | Video source        |
+| `placeholderImage` | Poster thumbnail    |
+| `videoTitle`       | Accessibility title |
+| `controls`         | Standard player UI  |
+
+```tsx
+import { Video } from '@codecademy/gamut';
+
+<Video
+  videoUrl="https://example.com/video.mp4"
+  placeholderImage="https://example.com/poster.jpg"
+  videoTitle="Course introduction"
+  controls
+/>;
+```