chore!: change z-indexes on theme from array to dictionary

Author: joshuaellis

.changeset/seven-cats-roll.md

@@ -0,0 +1,7 @@
+---
+'@strapi/design-system': major
+---
+
+chore!: change z-indexes on theme from array to dictionary
+
+`z-indices` on the theme object were an array of length 4. We've since changed this to a dictionary to help engineers understand how to correctly apply these values. See the `Elevation` documentation for more information.

docs/.storybook/preview.tsx

@@ -135,7 +135,7 @@ const preview: Preview = {
           'Getting Started',
           ['Welcome', 'Contributing', 'Changelog', 'Migration Guides', ['V1 to V2']],
           'Foundations',
-          ['Accessibility', 'Color', 'Grid', 'Icons', ['Overview', '*'], 'Typography'],
+          ['Accessibility', 'Color', 'Elevation', 'Grid', 'Icons', ['Overview', '*'], 'Typography'],
           'Primitives',
           ['Overview', '*'],
           'Inputs',

docs/stories/01-foundations/elevation.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Foundations/Elevation" />
+
+# Layers
+
+Modern UI is composed of different layers, be that modals, popovers or tooltips.
+
+## Shadows
+
+Shadows are used to create a sense of depth and separation between elements. They might be used to indicate evelation of
+an element e.g. a Popover, or alternatively, they can indicate that UI can scroll below another element e.g. Tables.
+
+## Z-Index
+
+The z-index determines the stacking order of elements. Elements with a higher z-index always sit in front of elements
+with a lower z-index. Our current collection of z-index values are lised below with their alias, they're currently
+non-linear to support growing other common use-cases we may not have encountered yet. All are accessible via the theme
+object – `theme.zIndices.<alias>`.
+
+- `navigation` – `100`
+- `overlay` – `300`
+- `modal` – `310`
+- `dialog` – `320`
+- `popover` – `500`
+- `notification` – `700`
+- `tooltip` – `1000`

packages/design-system/src/components/Box/Box.tsx

@@ -23,7 +23,6 @@ interface TransientBoxProps
     | 'pointerEvents'
     | 'display'
     | 'position'
-    | 'zIndex'
     | 'overflow'
     | 'cursor'
     | 'transition'
@@ -120,6 +119,7 @@ interface TransientBoxProps
   borderRadius?: CSSProperties['borderRadius'];
   borderStyle?: CSSProperties['borderStyle'];
   borderWidth?: CSSProperties['borderWidth'];
+  zIndex?: DefaultThemeOrCSSProp<'zIndicies', 'zIndex'>;
 }
 
 interface BoxPropsImpl extends TransientBoxProps {
@@ -294,7 +294,7 @@ const StyledBox = styled.div<PropsToTransientProps<TransientBoxProps>>`
   right: ${({ $right, theme }) => extractStyleFromTheme(theme.spaces, $right, $right)};
   top: ${({ $top, theme }) => extractStyleFromTheme(theme.spaces, $top, $top)};
   bottom: ${({ $bottom, theme }) => extractStyleFromTheme(theme.spaces, $bottom, $bottom)};
-  z-index: ${({ $zIndex }) => $zIndex};
+  z-index: ${({ $zIndex, theme }) => extractStyleFromTheme(theme.zIndices, $zIndex, $zIndex)};
   overflow: ${({ $overflow }) => $overflow};
 
   // Size

packages/design-system/src/components/Combobox/Combobox.tsx

@@ -366,7 +366,7 @@ const Content = styled(ComboboxPrimitive.Content)`
   width: var(--radix-combobox-trigger-width);
   /* This is from the design-system figma file. */
   max-height: 15rem;
-  z-index: ${({ theme }) => theme.zIndices[1]};
+  z-index: ${({ theme }) => theme.zIndices.popover};
 `;
 
 const Viewport = styled(ComboboxPrimitive.Viewport)`

packages/design-system/src/components/DatePicker/DatePicker.tsx

@@ -875,7 +875,7 @@ const DatePickerContentImpl = React.forwardRef<DatePickerContentImplElement, Con
 
 const ContentElement = styled<BoxComponent>(Box)`
   box-shadow: ${({ theme }) => theme.shadows.filterShadow};
-  z-index: ${({ theme }) => theme.zIndices[0]};
+  z-index: ${({ theme }) => theme.zIndices.popover};
   border: 1px solid ${({ theme }) => theme.colors.neutral150};
 `;
 

packages/design-system/src/components/Dialog/Dialog.tsx

@@ -35,7 +35,7 @@ export interface DialogProps extends BoxProps {
   as?: TypographyProps<any>['tag'];
 }
 
-export const Dialog = ({ onClose, title, as = 'h2', isOpen, id, zIndex = 4, ...props }: DialogProps) => {
+export const Dialog = ({ onClose, title, as = 'h2', isOpen, id, zIndex = 'dialog', ...props }: DialogProps) => {
   const generatedId = useId(id);
 
   useLockScroll(isOpen);

packages/design-system/src/components/ModalLayout/ModalLayout.tsx

@@ -25,7 +25,7 @@ export const ModalLayout = ({ onClose, labelledBy, ...props }: ModalLayoutProps)
   return (
     <Portal>
       <ModalContext.Provider value={onClose}>
-        <ModalWrapper justifyContent="center" paddingLeft={8} paddingRight={8} position="fixed" zIndex={4}>
+        <ModalWrapper justifyContent="center" paddingLeft={8} paddingRight={8} position="fixed" zIndex="modal">
           <FocusTrap>
             <DismissibleLayer onEscapeKeyDown={onClose} onPointerDownOutside={onClose}>
               <Box

packages/design-system/src/components/Popover/Popover.tsx

@@ -32,7 +32,7 @@ export const POPOVER_PLACEMENTS = [
 
 const PopoverWrapper = styled<BoxComponent>(Box)`
   box-shadow: ${({ theme }) => theme.shadows.filterShadow};
-  z-index: ${({ theme }) => theme.zIndices[0]};
+  z-index: ${({ theme }) => theme.zIndices.popover};
   border: 1px solid ${({ theme }) => theme.colors.neutral150};
 `;
 export interface ContentProps

packages/design-system/src/components/Select/SelectParts.tsx

@@ -174,7 +174,7 @@ const SelectContent = styled(Select.Content)`
   min-width: var(--radix-select-trigger-width);
   /* This is from the design-system figma file. */
   max-height: 15rem;
-  z-index: ${({ theme }) => theme.zIndices[1]};
+  z-index: ${({ theme }) => theme.zIndices.popover};
 `;
 
 /* -------------------------------------------------------------------------------------------------

packages/design-system/src/components/Tooltip/Tooltip.tsx

@@ -81,6 +81,7 @@ const TooltipContent = styled(Tooltip.Content)`
   padding-inline: ${(props) => props.theme.spaces[2]};
   padding-block: ${(props) => props.theme.spaces[2]};
   border-radius: ${(props) => props.theme.borderRadius};
+  z-index: ${(props) => props.theme.zIndices.tooltip};
   will-change: opacity;
   transform-origin: var(--radix-tooltip-content-transform-origin);
 

packages/design-system/src/themes/common-theme.ts

@@ -4,7 +4,15 @@ import { Sizes, sizes } from './sizes';
 
 export interface CommonTheme {
   sizes: Sizes;
-  zIndices: [5, 10, 15, 20];
+  zIndices: {
+    navigation: 100;
+    overlay: 300;
+    modal: 310;
+    dialog: 320;
+    popover: 500;
+    notification: 700;
+    tooltip: 1000;
+  };
   spaces: ['0px', '4px', '8px', '12px', '16px', '20px', '24px', '32px', '40px', '48px', '56px', '64px'];
   borderRadius: '4px';
   mediaQueries: {
@@ -23,7 +31,15 @@ export interface CommonTheme {
 
 export const commonTheme: CommonTheme = {
   sizes,
-  zIndices: [5, 10, 15, 20], // TBD
+  zIndices: {
+    navigation: 100,
+    overlay: 300,
+    modal: 310,
+    dialog: 320,
+    popover: 500,
+    notification: 700,
+    tooltip: 1000,
+  },
   spaces: ['0px', '4px', '8px', '12px', '16px', '20px', '24px', '32px', '40px', '48px', '56px', '64px'],
   borderRadius: '4px',
   mediaQueries: {