feat(tokens): add z-index tokens with fallback values (#32356)

change/@fluentui-tokens-6453c666-41f3-4fb9-bba7-ca79fa23508d.json

@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat: add z-index tokens",
+  "packageName": "@fluentui/tokens",
+  "email": "marcosvmmoura@gmail.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-theme/stories/src/Theme/colors/ThemeColors.stories.tsx

@@ -52,15 +52,18 @@ export const Colors = () => {
   // It returns tokens matching the input value.
   const searchToken = React.useCallback(
     newSearchValue => {
-      const tokensFoundBySearch = tokens.filter(
-        token =>
+      const tokensFoundBySearch = tokens.filter(token => {
+        const tokensMatchSearchValue = (tokenItem?: string | number) => tokenItem?.toString().includes(newSearchValue);
+
+        return (
           token.toLowerCase().includes(newSearchValue) ||
-          theme.webLight[token].toString().includes(newSearchValue) ||
-          theme.webDark[token].toString().includes(newSearchValue) ||
-          theme.teamsLight[token].toString().includes(newSearchValue) ||
-          theme.teamsDark[token].toString().includes(newSearchValue) ||
-          theme.teamsHighContrast[token].toString().includes(newSearchValue),
-      );
+          tokensMatchSearchValue(theme.webLight[token]) ||
+          tokensMatchSearchValue(theme.webDark[token]) ||
+          tokensMatchSearchValue(theme.teamsLight[token]) ||
+          tokensMatchSearchValue(theme.teamsDark[token]) ||
+          tokensMatchSearchValue(theme.teamsHighContrast[token])
+        );
+      });
       setTokensSearchResult(tokensFoundBySearch);
     },
     [setTokensSearchResult],

packages/tokens/etc/tokens.api.md

@@ -449,7 +449,7 @@ export const teamsHighContrastTheme: Theme;
 export const teamsLightTheme: Theme;
 
 // @public (undocumented)
-export type Theme = FontSizeTokens & LineHeightTokens & BorderRadiusTokens & StrokeWidthTokens & HorizontalSpacingTokens & VerticalSpacingTokens & DurationTokens & CurveTokens & ShadowTokens & ShadowBrandTokens & FontFamilyTokens & FontWeightTokens & ColorPaletteTokens & ColorStatusTokens & ColorTokens;
+export type Theme = FontSizeTokens & LineHeightTokens & BorderRadiusTokens & StrokeWidthTokens & HorizontalSpacingTokens & VerticalSpacingTokens & DurationTokens & CurveTokens & ShadowTokens & ShadowBrandTokens & FontFamilyTokens & FontWeightTokens & ColorPaletteTokens & ColorStatusTokens & ColorTokens & ZIndexTokens;
 
 // @public
 export function themeToTokensObject<TTheme extends Theme>(theme: TTheme): Record<keyof TTheme, string>;
@@ -510,6 +510,18 @@ export const webDarkTheme: Theme;
 // @public (undocumented)
 export const webLightTheme: Theme;
 
+// @public
+export type ZIndexTokens = {
+    zIndexBackground?: string;
+    zIndexContent?: string;
+    zIndexOverlay?: string;
+    zIndexPopup?: string;
+    zIndexMessages?: string;
+    zIndexFloating?: string;
+    zIndexPriority?: string;
+    zIndexDebug?: string;
+};
+
 // (No @packageDocumentation comment for this package)
 
 ```

packages/tokens/src/index.ts

@@ -62,4 +62,5 @@ export type {
   Theme,
   TypographyStyle,
   TypographyStyles,
+  ZIndexTokens,
 } from './types';

packages/tokens/src/themeToTokensObject.test.ts

@@ -1,11 +1,22 @@
 import { webLightTheme } from './themes/web/lightTheme';
 import { themeToTokensObject } from './themeToTokensObject';
 import { tokens } from './tokens';
+import { Theme } from './types';
+
+function assertKeys(generatedTokens: Record<keyof Theme, string>, expectedTokens = tokens) {
+  Object.keys(generatedTokens).forEach(token => {
+    expect(expectedTokens).toHaveProperty(token);
+    expect.objectContaining({
+      [token]: expect.stringMatching(`var\\(--${token}(, .+)?\\)`),
+    });
+  });
+}
 
 describe('themeToTokensObject', () => {
   it('passing any of our default themes to the function generates the default tokens object', () => {
     const generatedTokens = themeToTokensObject(webLightTheme);
-    expect(generatedTokens).toEqual(tokens);
+
+    assertKeys(generatedTokens);
   });
 
   it('passing a custom theme with custom tokens on top of a default theme generates the correct tokens object', () => {
@@ -17,6 +28,7 @@ describe('themeToTokensObject', () => {
       customColor3: 'var(--customColor3)',
     };
     const generatedTokens = themeToTokensObject(customTheme);
-    expect(generatedTokens).toEqual(expectedTokens);
+
+    assertKeys(generatedTokens, expectedTokens);
   });
 });

packages/tokens/src/tokens.test.ts

@@ -4,7 +4,10 @@ import { tokens } from './tokens';
 describe('tokens', () => {
   it('CSS variables match expected format', () => {
     (Object.keys(tokens) as (keyof Theme)[]).forEach(token => {
-      expect(tokens[token]).toBe(`var(--${token})`);
+      const tokenValue = tokens[token];
+      const tokenRegex = new RegExp(`var\\(--${token}(, .+)?\\)`);
+
+      expect(tokenValue).toMatch(tokenRegex);
     });
   });
 });

packages/tokens/src/tokens.ts

@@ -539,4 +539,58 @@ export const tokens: Record<keyof Theme, string> = {
   curveEasyEaseMax: 'var(--curveEasyEaseMax)',
   curveEasyEase: 'var(--curveEasyEase)',
   curveLinear: 'var(--curveLinear)',
+
+  /**
+   * ZIndexes
+   * Special case where the tokens contain default values
+   * ZIndexes are not mandatory, so they are not included in the theme, but can be used as tokens with default values
+   */
+
+  /**
+   * Elevation 0
+   * Can be used for background elements, like surfaces
+   */
+  zIndexBackground: 'var(--zIndexBackground, 0)',
+
+  /**
+   * Elevation 2
+   * Can be used content that is on top of the background, like cards
+   */
+  zIndexContent: 'var(--zIndexContent, 1)',
+
+  /**
+   * Elevation 4
+   * Can be used for overlays, like the backdrop of a modal
+   */
+  zIndexOverlay: 'var(--zIndexOverlay, 1000)',
+
+  /**
+   * Elevation 8
+   * Can be used for popups, like modals and drawers
+   */
+  zIndexPopup: 'var(--zIndexPopup, 2000)',
+
+  /**
+   * Elevation 16
+   * Can be used for messages, like snackbars and toasts
+   */
+  zIndexMessages: 'var(--zIndexMessages, 3000)',
+
+  /**
+   * Elevation 28
+   * Can be used for floating elements, like dropdowns
+   */
+  zIndexFloating: 'var(--zIndexFloating, 4000)',
+
+  /**
+   * Elevation 64
+   * Can be used for high priority floating elements, like tooltips
+   */
+  zIndexPriority: 'var(--zIndexPriority, 5000)',
+
+  /**
+   * Special elevation
+   * Can be used for elements that need to be above everything else, like debug overlays
+   */
+  zIndexDebug: 'var(--zIndexDebug, 6000)',
 };

packages/tokens/src/types.ts

@@ -683,6 +683,20 @@ export type CurveTokens = {
   curveLinear: string;
 };
 
+/**
+ * Design tokens for z-index groups and levels
+ */
+export type ZIndexTokens = {
+  zIndexBackground?: string;
+  zIndexContent?: string;
+  zIndexOverlay?: string;
+  zIndexPopup?: string;
+  zIndexMessages?: string;
+  zIndexFloating?: string;
+  zIndexPriority?: string;
+  zIndexDebug?: string;
+};
+
 /**
  * Design tokens for shadow levels
  */
@@ -773,6 +787,7 @@ export type Theme = FontSizeTokens &
   FontWeightTokens &
   ColorPaletteTokens &
   ColorStatusTokens &
-  ColorTokens;
+  ColorTokens &
+  ZIndexTokens;
 
 export type PartialTheme = Partial<Theme>;