@primer/primitives/dist/docs/functional/size/z-index.json

Typography, spacing, and color primitives for Primer design system

{
  "zIndex-behind": {
    "key": "{zIndex.behind}",
    "$extensions": {
      "org.primer.llm": {
        "usage": ["decorative-background", "canvas-element", "background-pattern"],
        "rules": "Use to push an element behind its siblings. WARNING: Negative z-index can behave unpredictably if any ancestor creates a new stacking context (via transform, opacity < 1, filter, will-change, etc.). Only use when you control the full stacking context chain. Do NOT use as a general \"hide\" mechanism."
      }
    },
    "filePath": "src/tokens/functional/size/z-index.json5",
    "isSource": true,
    "original": {
      "$value": -1,
      "$type": "number",
      "$description": "Place element behind base content. Use for decorative backgrounds or canvas elements.",
      "$extensions": {
        "org.primer.llm": {
          "usage": ["decorative-background", "canvas-element", "background-pattern"],
          "rules": "Use to push an element behind its siblings. WARNING: Negative z-index can behave unpredictably if any ancestor creates a new stacking context (via transform, opacity < 1, filter, will-change, etc.). Only use when you control the full stacking context chain. Do NOT use as a general \"hide\" mechanism."
        }
      },
      "key": "{zIndex.behind}"
    },
    "name": "zIndex-behind",
    "attributes": {},
    "path": ["zIndex", "behind"],
    "value": -1,
    "type": "number",
    "description": "Place element behind base content. Use for decorative backgrounds or canvas elements."
  },
  "zIndex-default": {
    "key": "{zIndex.default}",
    "$extensions": {
      "org.primer.llm": {
        "usage": ["default-content", "in-flow-element", "reset"],
        "rules": "Use to explicitly reset z-index to the default layer. Suitable for elements that should participate in normal document flow stacking. Do NOT use for any element that needs to appear above other content."
      }
    },
    "filePath": "src/tokens/functional/size/z-index.json5",
    "isSource": true,
    "original": {
      "$value": "{base.zIndex.0}",
      "$type": "number",
      "$description": "Default stacking order. No elevation above surrounding content.",
      "$extensions": {
        "org.primer.llm": {
          "usage": ["default-content", "in-flow-element", "reset"],
          "rules": "Use to explicitly reset z-index to the default layer. Suitable for elements that should participate in normal document flow stacking. Do NOT use for any element that needs to appear above other content."
        }
      },
      "key": "{zIndex.default}"
    },
    "name": "zIndex-default",
    "attributes": {},
    "path": ["zIndex", "default"],
    "value": 0,
    "type": "number",
    "description": "Default stacking order. No elevation above surrounding content."
  },
  "zIndex-dropdown": {
    "key": "{zIndex.dropdown}",
    "$extensions": {
      "org.primer.llm": {
        "usage": ["dropdown-menu", "select-panel", "autocomplete-list", "action-menu", "context-menu"],
        "rules": "Use for menus, select panels, and autocomplete lists that overlay page content. These should appear above sticky elements but below overlays and modals. Pair with `shadow.floating.small` or `shadow.floating.medium` for visual elevation."
      }
    },
    "filePath": "src/tokens/functional/size/z-index.json5",
    "isSource": true,
    "original": {
      "$value": "{base.zIndex.200}",
      "$type": "number",
      "$description": "Dropdown menus and select panels that appear above page content.",
      "$extensions": {
        "org.primer.llm": {
          "usage": ["dropdown-menu", "select-panel", "autocomplete-list", "action-menu", "context-menu"],
          "rules": "Use for menus, select panels, and autocomplete lists that overlay page content. These should appear above sticky elements but below overlays and modals. Pair with `shadow.floating.small` or `shadow.floating.medium` for visual elevation."
        }
      },
      "key": "{zIndex.dropdown}"
    },
    "name": "zIndex-dropdown",
    "attributes": {},
    "path": ["zIndex", "dropdown"],
    "value": 200,
    "type": "number",
    "description": "Dropdown menus and select panels that appear above page content."
  },
  "zIndex-modal": {
    "key": "{zIndex.modal}",
    "$extensions": {
      "org.primer.llm": {
        "usage": ["modal-dialog", "dialog", "full-screen-overlay", "lightbox", "confirm-dialog"],
        "rules": "Use for modal dialogs that require user interaction before returning to the page. MUST trap focus within the modal. MUST appear above all other page content except popovers and skip links. Pair with `shadow.floating.large` or `shadow.floating.xlarge` for visual elevation."
      }
    },
    "filePath": "src/tokens/functional/size/z-index.json5",
    "isSource": true,
    "original": {
      "$value": "{base.zIndex.400}",
      "$type": "number",
      "$description": "Modal dialogs and full-screen overlays.",
      "$extensions": {
        "org.primer.llm": {
          "usage": ["modal-dialog", "dialog", "full-screen-overlay", "lightbox", "confirm-dialog"],
          "rules": "Use for modal dialogs that require user interaction before returning to the page. MUST trap focus within the modal. MUST appear above all other page content except popovers and skip links. Pair with `shadow.floating.large` or `shadow.floating.xlarge` for visual elevation."
        }
      },
      "key": "{zIndex.modal}"
    },
    "name": "zIndex-modal",
    "attributes": {},
    "path": ["zIndex", "modal"],
    "value": 400,
    "type": "number",
    "description": "Modal dialogs and full-screen overlays."
  },
  "zIndex-overlay": {
    "key": "{zIndex.overlay}",
    "$extensions": {
      "org.primer.llm": {
        "usage": ["overlay-backdrop", "side-panel", "drawer", "slide-over", "bottom-sheet"],
        "rules": "Use for overlay surfaces that partially cover the page — drawers, side panels, and backdrop layers. These appear above dropdowns but below modal dialogs. SHOULD be paired with a backdrop/scrim element to indicate the overlay is blocking interaction with content beneath."
      }
    },
    "filePath": "src/tokens/functional/size/z-index.json5",
    "isSource": true,
    "original": {
      "$value": "{base.zIndex.300}",
      "$type": "number",
      "$description": "Overlay backdrops, side panels, and drawers.",
      "$extensions": {
        "org.primer.llm": {
          "usage": ["overlay-backdrop", "side-panel", "drawer", "slide-over", "bottom-sheet"],
          "rules": "Use for overlay surfaces that partially cover the page — drawers, side panels, and backdrop layers. These appear above dropdowns but below modal dialogs. SHOULD be paired with a backdrop/scrim element to indicate the overlay is blocking interaction with content beneath."
        }
      },
      "key": "{zIndex.overlay}"
    },
    "name": "zIndex-overlay",
    "attributes": {},
    "path": ["zIndex", "overlay"],
    "value": 300,
    "type": "number",
    "description": "Overlay backdrops, side panels, and drawers."
  },
  "zIndex-popover": {
    "key": "{zIndex.popover}",
    "$extensions": {
      "org.primer.llm": {
        "usage": ["tooltip", "popover", "hover-card", "floating-label"],
        "rules": "Use for tooltips, popovers, and hover cards that must appear above all other UI elements including modals. These are the highest layer in normal UI. Do NOT use for persistent navigation — use `sticky` instead."
      }
    },
    "filePath": "src/tokens/functional/size/z-index.json5",
    "isSource": true,
    "original": {
      "$value": "{base.zIndex.500}",
      "$type": "number",
      "$description": "Tooltips and popovers that appear above all normal UI.",
      "$extensions": {
        "org.primer.llm": {
          "usage": ["tooltip", "popover", "hover-card", "floating-label"],
          "rules": "Use for tooltips, popovers, and hover cards that must appear above all other UI elements including modals. These are the highest layer in normal UI. Do NOT use for persistent navigation — use `sticky` instead."
        }
      },
      "key": "{zIndex.popover}"
    },
    "name": "zIndex-popover",
    "attributes": {},
    "path": ["zIndex", "popover"],
    "value": 500,
    "type": "number",
    "description": "Tooltips and popovers that appear above all normal UI."
  },
  "zIndex-skipLink": {
    "key": "{zIndex.skipLink}",
    "$extensions": {
      "org.primer.llm": {
        "usage": ["skip-link", "skip-navigation", "skip-to-content"],
        "rules": "MUST use for accessibility skip links that allow keyboard users to bypass navigation. This is the highest z-index level and MUST always appear above everything else including modals and tooltips. NEVER use for non-accessibility purposes."
      }
    },
    "filePath": "src/tokens/functional/size/z-index.json5",
    "isSource": true,
    "original": {
      "$value": "{base.zIndex.600}",
      "$type": "number",
      "$description": "Accessibility skip links. Must always be the topmost layer.",
      "$extensions": {
        "org.primer.llm": {
          "usage": ["skip-link", "skip-navigation", "skip-to-content"],
          "rules": "MUST use for accessibility skip links that allow keyboard users to bypass navigation. This is the highest z-index level and MUST always appear above everything else including modals and tooltips. NEVER use for non-accessibility purposes."
        }
      },
      "key": "{zIndex.skipLink}"
    },
    "name": "zIndex-skipLink",
    "attributes": {},
    "path": ["zIndex", "skipLink"],
    "value": 600,
    "type": "number",
    "description": "Accessibility skip links. Must always be the topmost layer."
  },
  "zIndex-sticky": {
    "key": "{zIndex.sticky}",
    "$extensions": {
      "org.primer.llm": {
        "usage": ["sticky-header", "sticky-sidebar", "sticky-table-header", "sticky-footer", "sticky-nav"],
        "rules": "MUST use with `position: sticky` or `position: fixed` for headers, sidebars, and navigation bars that persist during scroll. Do NOT use for floating overlays or dropdowns — use higher z-index levels instead."
      }
    },
    "filePath": "src/tokens/functional/size/z-index.json5",
    "isSource": true,
    "original": {
      "$value": "{base.zIndex.100}",
      "$type": "number",
      "$description": "Sticky elements that remain visible while scrolling.",
      "$extensions": {
        "org.primer.llm": {
          "usage": ["sticky-header", "sticky-sidebar", "sticky-table-header", "sticky-footer", "sticky-nav"],
          "rules": "MUST use with `position: sticky` or `position: fixed` for headers, sidebars, and navigation bars that persist during scroll. Do NOT use for floating overlays or dropdowns — use higher z-index levels instead."
        }
      },
      "key": "{zIndex.sticky}"
    },
    "name": "zIndex-sticky",
    "attributes": {},
    "path": ["zIndex", "sticky"],
    "value": 100,
    "type": "number",
    "description": "Sticky elements that remain visible while scrolling."
  }
}