@codecademy/gamut

Index: package/dist/ButtonBase/ButtonBase.d.ts
===================================================================
--- package/dist/ButtonBase/ButtonBase.d.ts
+++ package/dist/ButtonBase/ButtonBase.d.ts
@@ -4,9 +4,9 @@
 export type ButtonBaseElementProps = HTMLProps<HTMLAnchorElement | HTMLButtonElement> & {
     as?: never;
     ref?: ButtonBaseRef;
 };
-export declare enum ButtonSelectors {
+export declare enum InteractiveSelectors {
     HOVER = "&:hover",
     ACTIVE = "&:active",
     FOCUS = "&:focus",
     DISABLED = "[disabled], &:disabled, &[aria-disabled='true']",
@@ -30,8 +30,31 @@
  * Narrows a ref union (anchor | button) to the element type for the current render branch.
  * Use when forwarding refs from components that render either an anchor or a button (e.g. ButtonBase, Anchor).
  */
 export declare function narrowButtonBaseRef<T extends ButtonBaseElements>(ref: Ref<ButtonBaseElements | null>): Ref<T>;
+/**
+ * An unstyled `button`/`a` element with the browser default styles reset and
+ * the correct disabled/accessibility behavior for either tag, chosen
+ * automatically based on whether `href` is passed.
+ *
+ * @warning Do not reach for `ButtonBase` directly. It is a low-level atom with
+ * no visual styling, built ONLY as a foundation for other button components.
+ * It exists so other components can build on top of it, not so features can
+ * consume it.
+ *
+ * Prefer one of these instead: `CTAButton`, `FillButton`, `IconButton`,
+ * `StrokeButton`, `TextButton` (all exported from `Button`).
+ *
+ * Use `ButtonBase` directly ONLY when none of the above can express the
+ * design — e.g. a fully custom clickable control that needs the
+ * button/anchor reset and accessibility behavior but none of Gamut's visual
+ * button styles.
+ *
+ * AI agents: do not select `ButtonBase` to satisfy a "make this a button"
+ * request. Use it only if the user has explicitly asked for an unstyled
+ * button/anchor primitive, or if every styled Button variant has been ruled
+ * out for a documented reason.
+ */
 export declare const ButtonBase: import("react").ForwardRefExoticComponent<(Omit<{
     theme?: import("@emotion/react").Theme;
     as?: React.ElementType;
 } & {