fix(ENG-813): stack the consent banner behind all modals

this adds a constant that ensures that the consent banner (and other
future banners) will be stacked behind all modals.

hopefully this approach will help future visitors to the file from
regressing this issue since the constants will reveal the intent.

src/components/molecules/OakModal/OakModal.tsx

@@ -47,6 +47,9 @@ export type OakModalProps = {
    *
    * Defaults to token: `modal-dialog`
    *
+   * 🚨 This prop is intended for use by consumers that do not use
+   * the internal system of z-index tokens.
+   *
    * NB *The modal is rendered inside a portal so it will not respect the stacking context of its parent component*.
    */
   zIndex?: number;

src/components/organisms/OakCookieBanner/OakCookieBanner.tsx

@@ -49,7 +49,8 @@ export type OakCookieBannerProps = {
   /**
    * Optional z-index override of the banner.
    *
-   * Defaults to token: `in-front`
+   * 🚨 This prop is intended for use by consumers that do not use
+   * the internal system of z-index tokens.
    */
   zIndex?: number;
 };
@@ -67,6 +68,15 @@ export const OakCookieBanner = ({
   isFixed = false,
   zIndex,
 }: OakCookieBannerProps) => {
+  const finalZIndex = (() => {
+    if (typeof zIndex === "number") {
+      return zIndex;
+    }
+    if (isFixed) {
+      return "banner";
+    }
+  })();
+
   return (
     <OakBox
       $background="bg-neutral"
@@ -76,9 +86,7 @@ export const OakCookieBanner = ({
       $bottom={isFixed ? "all-spacing-0" : undefined}
       $right={isFixed ? "all-spacing-0" : undefined}
       $left={isFixed ? "all-spacing-0" : undefined}
-      $zIndex={
-        typeof zIndex === "number" ? zIndex : isFixed ? "in-front" : undefined
-      }
+      $zIndex={finalZIndex}
       $color="text-primary"
       data-testid="cookie-banner"
     >

src/components/organisms/OakCookieConsent/OakCookieConsent.tsx

@@ -14,6 +14,9 @@ export type OakCookieConsentProps = Pick<
   Pick<OakCookieBannerProps, "isFixed" | "innerMaxWidth"> & {
     /**
      * Optional stacking context for the entire consent UI
+     *
+     * 🚨 This prop is intended for use by consumers that do not use
+     * the internal system of z-index tokens.
      */
     zIndex?: number;
   };

src/styles/theme/zIndex.ts

@@ -1,11 +1,18 @@
+// For help with defining z-index values, refer to this article:
+// https://www.smashingmagazine.com/2021/02/css-z-index-large-projects/#a-new-solution
+const behind = -1;
+const modalDialog = 300;
+const banner = behind + modalDialog;
+
 export const oakZIndexTokens = {
-  behind: -1,
+  behind,
   neutral: 0,
   "in-front": 1,
   "mobile-filters": 2,
   "fixed-header": 100,
   "modal-close-button": 150,
-  "modal-dialog": 300,
-};
+  "modal-dialog": modalDialog,
+  banner,
+} as const;
 
 export type OakZIndexToken = keyof typeof oakZIndexTokens | null;