@codecademy/gamut-styles 21.2.1-alpha.d682ce.0 → 21.2.1-alpha.e40070.0

package/dist/ColorMode.d.ts

@@ -350,6 +350,11 @@ export declare const providerProps: import("@codecademy/variance/dist/types/conf
     };
     readonly zIndex: {
         readonly property: "zIndex";
+        readonly scale: "zIndexes";
+        readonly allowRawValue: true;
+    };
+    readonly isolation: {
+        readonly property: "isolation";
     };
     readonly opacity: {
         readonly property: "opacity";
@@ -823,6 +828,9 @@ export declare const VariableProvider: import("@emotion/styled").StyledComponent
         readonly resolveProperty: (useLogicalProperties: boolean) => import("@codecademy/variance/dist/types/properties").PropertyMode;
         readonly transform: (value: string | number) => string | 0;
     }>;
+    isolation?: import("@codecademy/variance/dist/types/config").Scale<{
+        readonly property: "isolation";
+    }>;
     justifyContent?: import("@codecademy/variance/dist/types/config").Scale<{
         readonly property: "justifyContent";
     }>;
@@ -928,6 +936,8 @@ export declare const VariableProvider: import("@emotion/styled").StyledComponent
     }>;
     zIndex?: import("@codecademy/variance/dist/types/config").Scale<{
         readonly property: "zIndex";
+        readonly scale: "zIndexes";
+        readonly allowRawValue: true;
     }>;
     backgroundPosition?: import("@codecademy/variance/dist/types/config").Scale<{
         readonly property: "backgroundPosition";
@@ -1456,6 +1466,9 @@ export declare const ColorMode: import("react").ForwardRefExoticComponent<Omit<O
         readonly resolveProperty: (useLogicalProperties: boolean) => import("@codecademy/variance/dist/types/properties").PropertyMode;
         readonly transform: (value: string | number) => string | 0;
     }>;
+    isolation?: import("@codecademy/variance/dist/types/config").Scale<{
+        readonly property: "isolation";
+    }>;
     justifyContent?: import("@codecademy/variance/dist/types/config").Scale<{
         readonly property: "justifyContent";
     }>;
@@ -1561,6 +1574,8 @@ export declare const ColorMode: import("react").ForwardRefExoticComponent<Omit<O
     }>;
     zIndex?: import("@codecademy/variance/dist/types/config").Scale<{
         readonly property: "zIndex";
+        readonly scale: "zIndexes";
+        readonly allowRawValue: true;
     }>;
     backgroundPosition?: import("@codecademy/variance/dist/types/config").Scale<{
         readonly property: "backgroundPosition";

package/dist/themes/admin.d.ts

@@ -34,13 +34,17 @@ export declare const adminTheme: Record<"breakpoints", {
     md: string;
     lg: string;
     xl: string;
-}> & import("@codecademy/variance/dist/createTheme/types").Merge<Record<"elements", Record<"elements", import("@codecademy/variance").KeyAsVariable<{
-    readonly headerHeight: {
-        readonly base: "4rem";
-        readonly md: "5rem";
-    };
-    readonly headerZ: 15;
-}, "elements">>> & import("@codecademy/variance/dist/createTheme/types").Merge<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<Record<"breakpoints", {
+}> & import("@codecademy/variance/dist/createTheme/types").Merge<Record<"zIndexes", Record<"zIndexes", import("@codecademy/variance").KeyAsVariable<{
+    readonly underlay: -100;
+    readonly base: 0;
+    readonly foreground: 100;
+    readonly floating: 200;
+    readonly appBar: 300;
+    readonly flyout: 400;
+    readonly modal: 500;
+    readonly popover: 600;
+    readonly topmost: 700;
+}, "zIndexes">>> & import("@codecademy/variance/dist/createTheme/types").Merge<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<Record<"breakpoints", {
     c_base: string;
     c_xs: string;
     c_sm: string;
@@ -120,7 +124,18 @@ export declare const adminTheme: Record<"breakpoints", {
             readonly base: "4rem";
             readonly md: "5rem";
         };
-        readonly headerZ: 15;
+        readonly headerZ: 300;
+    };
+    zIndexes: {
+        readonly underlay: -100;
+        readonly base: 0;
+        readonly foreground: 100;
+        readonly floating: 200;
+        readonly appBar: 300;
+        readonly flyout: 400;
+        readonly modal: 500;
+        readonly popover: 600;
+        readonly topmost: 700;
     };
 } & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"colors", import("@codecademy/variance").KeyAsVariable<import("@codecademy/variance").LiteralPaths<{
     readonly beige: "#FFF0E5";
@@ -544,7 +559,13 @@ export declare const adminTheme: Record<"breakpoints", {
 }>, Record<"borders", import("@codecademy/variance").LiteralPaths<{
     1: string;
     2: string;
-}, "-">>>, Record<"elevation", import("@codecademy/variance").LiteralPaths<import("..").ElevationScale, "-">>>, import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"name", string>> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, {
+}, "-">>>, Record<"elevation", import("@codecademy/variance").LiteralPaths<import("..").ElevationScale, "-">>>, import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"elements", Record<"elements", import("@codecademy/variance").KeyAsVariable<{
+    readonly headerHeight: {
+        readonly base: "4rem";
+        readonly md: "5rem";
+    };
+    readonly headerZ: 300;
+}, "elements">>>>, import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"name", string>> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, {
     colors: import("@codecademy/variance").KeyAsVariable<import("@codecademy/variance").LiteralPaths<{
         primary: {
             _: "blue-500";

package/dist/themes/core.d.ts

@@ -15,13 +15,17 @@ export declare const coreTheme: Record<"breakpoints", {
     md: string;
     lg: string;
     xl: string;
-}> & import("@codecademy/variance/dist/createTheme/types").Merge<Record<"elements", Record<"elements", import("@codecademy/variance").KeyAsVariable<{
-    readonly headerHeight: {
-        readonly base: "4rem";
-        readonly md: "5rem";
-    };
-    readonly headerZ: 15;
-}, "elements">>> & import("@codecademy/variance/dist/createTheme/types").Merge<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<Record<"breakpoints", {
+}> & import("@codecademy/variance/dist/createTheme/types").Merge<Record<"zIndexes", Record<"zIndexes", import("@codecademy/variance").KeyAsVariable<{
+    readonly underlay: -100;
+    readonly base: 0;
+    readonly foreground: 100;
+    readonly floating: 200;
+    readonly appBar: 300;
+    readonly flyout: 400;
+    readonly modal: 500;
+    readonly popover: 600;
+    readonly topmost: 700;
+}, "zIndexes">>> & import("@codecademy/variance/dist/createTheme/types").Merge<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<Record<"breakpoints", {
     c_base: string;
     c_xs: string;
     c_sm: string;
@@ -101,7 +105,18 @@ export declare const coreTheme: Record<"breakpoints", {
             readonly base: "4rem";
             readonly md: "5rem";
         };
-        readonly headerZ: 15;
+        readonly headerZ: 300;
+    };
+    zIndexes: {
+        readonly underlay: -100;
+        readonly base: 0;
+        readonly foreground: 100;
+        readonly floating: 200;
+        readonly appBar: 300;
+        readonly flyout: 400;
+        readonly modal: 500;
+        readonly popover: 600;
+        readonly topmost: 700;
     };
 } & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"colors", import("@codecademy/variance").KeyAsVariable<import("@codecademy/variance").LiteralPaths<{
     readonly beige: "#FFF0E5";
@@ -525,7 +540,13 @@ export declare const coreTheme: Record<"breakpoints", {
 }>, Record<"borders", import("@codecademy/variance").LiteralPaths<{
     1: string;
     2: string;
-}, "-">>>, Record<"elevation", import("@codecademy/variance").LiteralPaths<import("../variables").ElevationScale, "-">>>, import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"name", string>> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys;
+}, "-">>>, Record<"elevation", import("@codecademy/variance").LiteralPaths<import("../variables").ElevationScale, "-">>>, import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"elements", Record<"elements", import("@codecademy/variance").KeyAsVariable<{
+    readonly headerHeight: {
+        readonly base: "4rem";
+        readonly md: "5rem";
+    };
+    readonly headerZ: 300;
+}, "elements">>>>, import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"name", string>> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys;
 export type CoreThemeShape = typeof coreTheme;
 export interface CoreTheme extends CoreThemeShape {
 }

package/dist/themes/core.js

@@ -1,5 +1,5 @@
 import { createTheme } from '@codecademy/variance';
-import { borderRadii, containerQueries, coreElevation, corePalette, elements, fontFamily, fontSize, fontWeight, lineHeight, mediaQueries, spacing } from '../variables';
+import { borderRadii, containerQueries, coreElevation, corePalette, elements, fontFamily, fontSize, fontWeight, lineHeight, mediaQueries, spacing, zIndexes } from '../variables';
 
 /**
  *  @description  This is the core theme that all other Codecademy themes are extended from
@@ -18,7 +18,8 @@ export const coreTheme = createTheme({
   lineHeight,
   fontWeight,
   spacing,
-  elements
+  elements,
+  zIndexes
 }).addColors(corePalette).addColorModes('light', {
   light: {
     text: {
@@ -129,4 +130,4 @@ export const coreTheme = createTheme({
 }) => ({
   1: `1px solid ${colors['border-primary']}`,
   2: `2px solid ${colors['border-primary']}`
-})).addScale('elevation', coreElevation).createScaleVariables('elements').addName('core').build();
+})).addScale('elevation', coreElevation).createScaleVariables('elements').createScaleVariables('zIndexes').addName('core').build();

package/dist/themes/lxStudio.d.ts

@@ -78,18 +78,39 @@ export declare const lxStudioTheme: Record<"breakpoints", {
         lg: string;
         xl: string;
     };
+    zIndexes: Record<"zIndexes", import("@codecademy/variance").KeyAsVariable<{
+        readonly underlay: -100;
+        readonly base: 0;
+        readonly foreground: 100;
+        readonly floating: 200;
+        readonly appBar: 300;
+        readonly flyout: 400;
+        readonly modal: 500;
+        readonly popover: 600;
+        readonly topmost: 700;
+    }, "zIndexes">> & {
+        readonly underlay: -100;
+        readonly base: 0;
+        readonly foreground: 100;
+        readonly floating: 200;
+        readonly appBar: 300;
+        readonly flyout: 400;
+        readonly modal: 500;
+        readonly popover: 600;
+        readonly topmost: 700;
+    };
     elements: Record<"elements", import("@codecademy/variance").KeyAsVariable<{
         readonly headerHeight: {
             readonly base: "4rem";
             readonly md: "5rem";
         };
-        readonly headerZ: 15;
+        readonly headerZ: 300;
     }, "elements">> & {
         readonly headerHeight: {
             readonly base: "4rem";
             readonly md: "5rem";
         };
-        readonly headerZ: 15;
+        readonly headerZ: 300;
     };
     fontSize: {
         readonly 64: string;
@@ -120,8 +141,8 @@ export declare const lxStudioTheme: Record<"breakpoints", {
         readonly 64: string;
         readonly 96: string;
     };
-    _variables: import("@codecademy/variance/dist/createTheme/types").Assign<Record<string, import("@codecademy/variance").CSSObject>, Record<string, import("@codecademy/variance").CSSObject>> & Record<string, import("@codecademy/variance").CSSObject>;
-    _tokens: import("@codecademy/variance/dist/createTheme/types").Assign<Record<string | number, any>, Record<string | number, any>> & Record<string | number, any>;
+    _variables: import("@codecademy/variance/dist/createTheme/types").Assign<import("@codecademy/variance/dist/createTheme/types").Assign<Record<string, import("@codecademy/variance").CSSObject>, Record<string, import("@codecademy/variance").CSSObject>>, Record<string, import("@codecademy/variance").CSSObject>> & Record<string, import("@codecademy/variance").CSSObject>;
+    _tokens: import("@codecademy/variance/dist/createTheme/types").Assign<import("@codecademy/variance/dist/createTheme/types").Assign<Record<string | number, any>, Record<string | number, any>>, Record<string | number, any>> & Record<string | number, any>;
     colors: import("@codecademy/variance/dist/createTheme/types").Assign<import("@codecademy/variance").KeyAsVariable<import("@codecademy/variance").LiteralPaths<{
         readonly beige: "#FFF0E5";
         readonly blue: "#1557FF";

package/dist/themes/percipio.d.ts

@@ -62,18 +62,39 @@ export declare const percipioTheme: Record<"breakpoints", {
         lg: string;
         xl: string;
     };
+    zIndexes: Record<"zIndexes", import("@codecademy/variance").KeyAsVariable<{
+        readonly underlay: -100;
+        readonly base: 0;
+        readonly foreground: 100;
+        readonly floating: 200;
+        readonly appBar: 300;
+        readonly flyout: 400;
+        readonly modal: 500;
+        readonly popover: 600;
+        readonly topmost: 700;
+    }, "zIndexes">> & {
+        readonly underlay: -100;
+        readonly base: 0;
+        readonly foreground: 100;
+        readonly floating: 200;
+        readonly appBar: 300;
+        readonly flyout: 400;
+        readonly modal: 500;
+        readonly popover: 600;
+        readonly topmost: 700;
+    };
     elements: Record<"elements", import("@codecademy/variance").KeyAsVariable<{
         readonly headerHeight: {
             readonly base: "4rem";
             readonly md: "5rem";
         };
-        readonly headerZ: 15;
+        readonly headerZ: 300;
     }, "elements">> & {
         readonly headerHeight: {
             readonly base: "4rem";
             readonly md: "5rem";
         };
-        readonly headerZ: 15;
+        readonly headerZ: 300;
     };
     borderRadii: {
         none: string;
@@ -112,8 +133,8 @@ export declare const percipioTheme: Record<"breakpoints", {
         readonly 64: string;
         readonly 96: string;
     };
-    _variables: import("@codecademy/variance/dist/createTheme/types").Assign<Record<string, import("@codecademy/variance").CSSObject>, Record<string, import("@codecademy/variance").CSSObject>> & Record<string, import("@codecademy/variance").CSSObject>;
-    _tokens: import("@codecademy/variance/dist/createTheme/types").Assign<Record<string | number, any>, Record<string | number, any>> & Record<string | number, any>;
+    _variables: import("@codecademy/variance/dist/createTheme/types").Assign<import("@codecademy/variance/dist/createTheme/types").Assign<Record<string, import("@codecademy/variance").CSSObject>, Record<string, import("@codecademy/variance").CSSObject>>, Record<string, import("@codecademy/variance").CSSObject>> & Record<string, import("@codecademy/variance").CSSObject>;
+    _tokens: import("@codecademy/variance/dist/createTheme/types").Assign<import("@codecademy/variance/dist/createTheme/types").Assign<Record<string | number, any>, Record<string | number, any>>, Record<string | number, any>> & Record<string | number, any>;
     colors: import("@codecademy/variance/dist/createTheme/types").Assign<import("@codecademy/variance").KeyAsVariable<import("@codecademy/variance").LiteralPaths<{
         readonly beige: "#FFF0E5";
         readonly blue: "#1557FF";

package/dist/themes/platform.d.ts

@@ -50,13 +50,17 @@ export declare const platformTheme: Record<"breakpoints", {
     md: string;
     lg: string;
     xl: string;
-}> & import("@codecademy/variance/dist/createTheme/types").Merge<Record<"elements", Record<"elements", import("@codecademy/variance").KeyAsVariable<{
-    readonly headerHeight: {
-        readonly base: "4rem";
-        readonly md: "5rem";
-    };
-    readonly headerZ: 15;
-}, "elements">>> & import("@codecademy/variance/dist/createTheme/types").Merge<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<Record<"breakpoints", {
+}> & import("@codecademy/variance/dist/createTheme/types").Merge<Record<"zIndexes", Record<"zIndexes", import("@codecademy/variance").KeyAsVariable<{
+    readonly underlay: -100;
+    readonly base: 0;
+    readonly foreground: 100;
+    readonly floating: 200;
+    readonly appBar: 300;
+    readonly flyout: 400;
+    readonly modal: 500;
+    readonly popover: 600;
+    readonly topmost: 700;
+}, "zIndexes">>> & import("@codecademy/variance/dist/createTheme/types").Merge<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<import("@codecademy/variance/dist/createTheme/types").MergeTheme<Record<"breakpoints", {
     c_base: string;
     c_xs: string;
     c_sm: string;
@@ -136,7 +140,18 @@ export declare const platformTheme: Record<"breakpoints", {
             readonly base: "4rem";
             readonly md: "5rem";
         };
-        readonly headerZ: 15;
+        readonly headerZ: 300;
+    };
+    zIndexes: {
+        readonly underlay: -100;
+        readonly base: 0;
+        readonly foreground: 100;
+        readonly floating: 200;
+        readonly appBar: 300;
+        readonly flyout: 400;
+        readonly modal: 500;
+        readonly popover: 600;
+        readonly topmost: 700;
     };
 } & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"colors", import("@codecademy/variance").KeyAsVariable<import("@codecademy/variance").LiteralPaths<{
     readonly beige: "#FFF0E5";
@@ -560,7 +575,13 @@ export declare const platformTheme: Record<"breakpoints", {
 }>, Record<"borders", import("@codecademy/variance").LiteralPaths<{
     1: string;
     2: string;
-}, "-">>>, Record<"elevation", import("@codecademy/variance").LiteralPaths<import("../variables").ElevationScale, "-">>>, import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"name", string>> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"colors", import("@codecademy/variance").KeyAsVariable<import("@codecademy/variance").LiteralPaths<{
+}, "-">>>, Record<"elevation", import("@codecademy/variance").LiteralPaths<import("../variables").ElevationScale, "-">>>, import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"elements", Record<"elements", import("@codecademy/variance").KeyAsVariable<{
+    readonly headerHeight: {
+        readonly base: "4rem";
+        readonly md: "5rem";
+    };
+    readonly headerZ: 300;
+}, "elements">>>>, import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"name", string>> & import("@codecademy/variance/dist/createTheme/types").PrivateThemeKeys, Record<"colors", import("@codecademy/variance").KeyAsVariable<import("@codecademy/variance").LiteralPaths<{
     readonly lightBeige: "#FFFBF8";
     readonly gold: "#8A7300";
     readonly teal: "#006D82";

package/dist/variables/elements.d.ts

@@ -4,8 +4,9 @@ export declare const elements: {
         readonly md: "5rem";
     };
     /**
-     * Semi-arbitrary z-index for global page headers.
-     * @remarks PLEASE talk to web platform before adding new z-index constants!
+     * z-index for global page headers. Aliases the `appBar` token from the `zIndexes`
+     * scale so consumers still reading `elements.headerZ` stay in sync with the scale.
+     * Prefer `zIndex="appBar"` in new code.
      */
-    readonly headerZ: 15;
+    readonly headerZ: 300;
 };

package/dist/variables/elements.js

@@ -1,11 +1,13 @@
+import { zIndexes } from './zIndexes';
 export const elements = {
   headerHeight: {
     base: '4rem',
     md: '5rem'
   },
   /**
-   * Semi-arbitrary z-index for global page headers.
-   * @remarks PLEASE talk to web platform before adding new z-index constants!
+   * z-index for global page headers. Aliases the `appBar` token from the `zIndexes`
+   * scale so consumers still reading `elements.headerZ` stay in sync with the scale.
+   * Prefer `zIndex="appBar"` in new code.
    */
-  headerZ: 15
+  headerZ: zIndexes.appBar
 };

package/dist/variables/index.d.ts

@@ -6,3 +6,4 @@ export * from './responsive';
 export * from './spacing';
 export * from './timing';
 export * from './typography';
+export * from './zIndexes';

package/dist/variables/index.js

@@ -5,4 +5,5 @@ export * from './elevation';
 export * from './responsive';
 export * from './spacing';
 export * from './timing';
-export * from './typography';
+export * from './typography';
+export * from './zIndexes';

package/dist/variables/zIndexes.d.ts

@@ -0,0 +1,53 @@
+import { Globals } from 'csstype';
+/**
+ * Semantic z-index scale. Every z-index in Gamut should reference a token here rather than a
+ * magic number.
+ *
+ * The `zIndex` system prop accepts a token name directly (e.g. `zIndex="modal"`), this object's
+ * numeric values (e.g. `zIndex={zIndexes.modal}`), a raw in-between number as an escape hatch
+ * (e.g. `zIndex={550}`), or arithmetic on a token (e.g. `zIndexes.foreground - 2`).
+ *
+ * Values are spaced by 100 so in-between escape-hatch numbers are available. `floating` (200) is
+ * the floor of the portal band and the default for `BodyPortal`.
+ *
+ * @remarks PLEASE talk to web platform before adding new z-index tokens.
+ */
+export declare const zIndexes: {
+    /** Decorative layer behind content (underlines, backdrops, shadows). */
+    readonly underlay: -100;
+    /** Ground layer — establishes a local stacking context without lifting above siblings. */
+    readonly base: 0;
+    /**
+     * The raised in-flow layer: an element in front of what sits/scrolls behind it, but below
+     * all portal overlays. Covers content lifted above an `underlay` (e.g. text over its
+     * underline) and sticky content headers (e.g. a sticky table `thead`).
+     */
+    readonly foreground: 100;
+    /**
+     * Portal floor: the default for `BodyPortal`, and the layer for persistent floating page
+     * furniture at rest (e.g. an AI chat launcher, help bubble). Above page content, below the
+     * app nav and all overlays.
+     */
+    readonly floating: 200;
+    /** Global app header / nav bar. Aliased by the legacy `elements.headerZ` constant. */
+    readonly appBar: 300;
+    /** Portaled side panel (the `Flyout` component = `Drawer` inside `Overlay`). */
+    readonly flyout: 400;
+    /** `Overlay`, `Modal`, and `Dialog` (they share one portal primitive). */
+    readonly modal: 500;
+    /** Portal-mode `Popover` and the portaled `SelectDropdown` menu — above modal. */
+    readonly popover: 600;
+    /**
+     * Top-most transient overlays that must never be clipped: floating tooltips (`FloatingTip`)
+     * and toasts / notifications (`Toaster`). Highest layer — nothing in Gamut sits above it.
+     */
+    readonly topmost: 700;
+};
+/**
+ * A `zIndexes` token name (e.g. `'foreground'`), a raw number as an escape hatch
+ * (e.g. `550`, or `zIndexes.foreground + 1`), or a CSS global (`'initial'`, `'inherit'`, …).
+ * Use this for component `zIndex` props that forward to a `Box`-like `zIndex` system prop or
+ * `BodyPortal`. The scale still resolves token names to `var(--zIndexes-*)` at runtime; this
+ * type just also permits the numeric/global escape hatches the scale type alone would reject.
+ */
+export type ZIndexType = keyof typeof zIndexes | number | Globals;

package/dist/variables/zIndexes.js

@@ -0,0 +1,52 @@
+/**
+ * Semantic z-index scale. Every z-index in Gamut should reference a token here rather than a
+ * magic number.
+ *
+ * The `zIndex` system prop accepts a token name directly (e.g. `zIndex="modal"`), this object's
+ * numeric values (e.g. `zIndex={zIndexes.modal}`), a raw in-between number as an escape hatch
+ * (e.g. `zIndex={550}`), or arithmetic on a token (e.g. `zIndexes.foreground - 2`).
+ *
+ * Values are spaced by 100 so in-between escape-hatch numbers are available. `floating` (200) is
+ * the floor of the portal band and the default for `BodyPortal`.
+ *
+ * @remarks PLEASE talk to web platform before adding new z-index tokens.
+ */
+export const zIndexes = {
+  /** Decorative layer behind content (underlines, backdrops, shadows). */
+  underlay: -100,
+  /** Ground layer — establishes a local stacking context without lifting above siblings. */
+  base: 0,
+  /**
+   * The raised in-flow layer: an element in front of what sits/scrolls behind it, but below
+   * all portal overlays. Covers content lifted above an `underlay` (e.g. text over its
+   * underline) and sticky content headers (e.g. a sticky table `thead`).
+   */
+  foreground: 100,
+  /**
+   * Portal floor: the default for `BodyPortal`, and the layer for persistent floating page
+   * furniture at rest (e.g. an AI chat launcher, help bubble). Above page content, below the
+   * app nav and all overlays.
+   */
+  floating: 200,
+  /** Global app header / nav bar. Aliased by the legacy `elements.headerZ` constant. */
+  appBar: 300,
+  /** Portaled side panel (the `Flyout` component = `Drawer` inside `Overlay`). */
+  flyout: 400,
+  /** `Overlay`, `Modal`, and `Dialog` (they share one portal primitive). */
+  modal: 500,
+  /** Portal-mode `Popover` and the portaled `SelectDropdown` menu — above modal. */
+  popover: 600,
+  /**
+   * Top-most transient overlays that must never be clipped: floating tooltips (`FloatingTip`)
+   * and toasts / notifications (`Toaster`). Highest layer — nothing in Gamut sits above it.
+   */
+  topmost: 700
+};
+
+/**
+ * A `zIndexes` token name (e.g. `'foreground'`), a raw number as an escape hatch
+ * (e.g. `550`, or `zIndexes.foreground + 1`), or a CSS global (`'initial'`, `'inherit'`, …).
+ * Use this for component `zIndex` props that forward to a `Box`-like `zIndex` system prop or
+ * `BodyPortal`. The scale still resolves token names to `var(--zIndexes-*)` at runtime; this
+ * type just also permits the numeric/global escape hatches the scale type alone would reject.
+ */

package/dist/variance/config.d.ts

@@ -455,6 +455,11 @@ export declare const positioning: {
     };
     readonly zIndex: {
         readonly property: "zIndex";
+        readonly scale: "zIndexes";
+        readonly allowRawValue: true;
+    };
+    readonly isolation: {
+        readonly property: "isolation";
     };
     readonly opacity: {
         readonly property: "opacity";
@@ -1215,6 +1220,11 @@ export declare const all: {
     };
     zIndex: {
         readonly property: "zIndex";
+        readonly scale: "zIndexes";
+        readonly allowRawValue: true;
+    };
+    isolation: {
+        readonly property: "isolation";
     };
     opacity: {
         readonly property: "opacity";

package/dist/variance/config.js

@@ -450,8 +450,19 @@ export const positioning = {
     resolveProperty: getPropertyMode,
     transform: transformSize
   },
+  // `scale: 'zIndexes'` resolves token names (e.g. `zIndex="modal"`) to `var(--zIndexes-*)`.
+  // `allowRawValue` keeps the numeric/global escape hatch (e.g. `zIndex={550}`,
+  // `zIndex={zIndexes.foreground + 1}`) that scaled props otherwise reject.
   zIndex: {
-    property: 'zIndex'
+    property: 'zIndex',
+    scale: 'zIndexes',
+    allowRawValue: true
+  },
+  // Companion to `zIndex`, deliberately unscaled: `isolation: 'isolate'` establishes a local
+  // stacking context so descendant `zIndex` values are scoped to this element, without the
+  // `position` change or z-index lift that `position: relative` + a `zIndexes` token would add.
+  isolation: {
+    property: 'isolation'
   },
   opacity: {
     property: 'opacity'

package/dist/variance/props.d.ts

@@ -324,6 +324,11 @@ export declare const positioning: import("@codecademy/variance/dist/types/config
     };
     readonly zIndex: {
         readonly property: "zIndex";
+        readonly scale: "zIndexes";
+        readonly allowRawValue: true;
+    };
+    readonly isolation: {
+        readonly property: "isolation";
     };
     readonly opacity: {
         readonly property: "opacity";
@@ -1218,6 +1223,11 @@ export declare const css: import("@codecademy/variance/dist/types/config").CSS<i
     };
     zIndex: {
         readonly property: "zIndex";
+        readonly scale: "zIndexes";
+        readonly allowRawValue: true;
+    };
+    isolation: {
+        readonly property: "isolation";
     };
     opacity: {
         readonly property: "opacity";
@@ -1895,6 +1905,11 @@ export declare const variant: import("@codecademy/variance/dist/types/config").V
     };
     zIndex: {
         readonly property: "zIndex";
+        readonly scale: "zIndexes";
+        readonly allowRawValue: true;
+    };
+    isolation: {
+        readonly property: "isolation";
     };
     opacity: {
         readonly property: "opacity";
@@ -2572,6 +2587,11 @@ export declare const states: import("@codecademy/variance/dist/types/config").St
     };
     zIndex: {
         readonly property: "zIndex";
+        readonly scale: "zIndexes";
+        readonly allowRawValue: true;
+    };
+    isolation: {
+        readonly property: "isolation";
     };
     opacity: {
         readonly property: "opacity";

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@codecademy/gamut-styles",
   "description": "Styleguide & Component library for codecademy.com",
-  "version": "21.2.1-alpha.d682ce.0",
+  "version": "21.2.1-alpha.e40070.0",
   "author": "Jake Hiller <jake@codecademy.com>",
   "dependencies": {
-    "@codecademy/variance": "1.1.1-alpha.d682ce.0",
+    "@codecademy/variance": "1.1.1-alpha.e40070.0",
     "@emotion/is-prop-valid": "^1.1.0",
     "framer-motion": "^12.0.0",
     "get-nonce": "^1.0.0",