z-index-token-enforcer

A multi-tool enforcer to ensure your team uses design tokens (CSS variables) for z-index properties, using a structured layering system instead of magic numbers.

example tokens:

:root {
    /* ... global layers ... */
    --z-base: 0; /* Default stacking context */
    --z-toasts: 100; 
    --z-overlays: 200; 
    --z-popups: 300; 

    /* Internal relations */
    --z-bottom: -10;
    --z-top: 10;
}

Why?

As explained in the article "The Value of z-index", using literal numbers for z-index leads to:

1. Unpredictability: No one knows what 100 means compared to 99.
2. Maintenance Hell: Changing one value requires checking all other files.
3. Complexity: Hard to manage stacking contexts without a clear hierarchy.

By forcing the use of tokens (e.g., z-index: var(--z-overlay)), you ensure the team follows a shared design system.

How it works

The enforcer ensures that every z-index property in your codebase follows a strict token-based system, regardless of how you write your styles.

❌ Invalid Syntax (Will cause errors)

Literal numbers are strictly forbidden to prevent "magic number" battles:

In CSS / SCSS:

• z-index: 100;
• z-index: 99999;

In JavaScript / React (Inline Styles & CSS-in-JS):

• zIndex: 100
• const styles = { zIndex: '9999' }
• styled.div z-index: 50; `` (Styled Components / Emotion)

✅ Valid Syntax

Values must be CSS variables (tokens) that represent the functional layer:

In CSS / SCSS:

• z-index: var(--z-modal);
• z-index: calc(var(--z-overlay) + 1);
• z-index: auto; (and other keywords: inherit, initial, unset, revert)

In JavaScript / React:

• zIndex: "var(--z-modal)"
• zIndex: "auto"
• const Overlay = styled.div z-index: var(--z-overlay); ``

Note on prefixing: By default, the enforcer looks for the --z- prefix (e.g., --z-header). You can customize this in the options.

Installation

npm install z-index-token-enforcer --save-dev

One Tool, Three Ways to Enforce

This package provides a unified logic to check for z-index tokens across your entire stack.

1. Stylelint Plugin (Recommended for CSS/SCSS)

If you haven't set up Stylelint yet, follow the Stylelint Getting Started guide.

Config (.stylelintrc.json):

{
  "plugins": ["z-index-token-enforcer"],
  "rules": {
    "z-index-token-enforcer/only-tokens": [true, { "prefix": "--z-" }]
  }
}

2. ESLint Plugin (For CSS-in-JS / React)

If you haven't set up ESLint yet, follow the ESLint Getting Started guide.

Config (.eslintrc.json):

{
  "plugins": ["z-index-token-enforcer"],
  "rules": {
    "z-index-token-enforcer/only-tokens": ["error", { "prefix": "--z-" }]
  }
}

3. CLI Scanner (For quick checks or CI/CD)

The CLI scanner allows you to quickly scan any files or directories for invalid z-index values.

Scan all files in the project:

npx z-index-token-enforcer "**/*"

Scan only CSS files in a specific directory:

npx z-index-token-enforcer "src/**/*.css"

With custom prefix:

npx z-index-token-enforcer "**/*.css" --prefix=--custom-

Note: You use the package name (z-index-token-enforcer) to run the scanner via npx.