/**
 * Rajgir Parent Theme
 *
 * Design System — Z-Index Tokens
 *
 * Canonical path:
 * assets/css/tokens/z-index.css
 *
 * Responsibility:
 * - Centralized stacking-layer tokens.
 * - Meaningful semantic layer names.
 * - Prevent arbitrary z-index values.
 *
 * Canonical layering model:
 *
 * Base
 *   ↓
 * Dropdown
 *   ↓
 * Sticky
 *   ↓
 * Modal
 *   ↓
 * Toast
 *
 * IMPORTANT:
 * Exact numeric values are not locked by the currently approved
 * source material. Therefore this file exposes semantic tokens
 * without inventing unauthorized numeric values.
 *
 * @package Rajgir
 */


/* ==========================================================================
   RAJGIR Z-INDEX TOKEN SYSTEM
   ========================================================================== */

:root {

	/*
	 * ----------------------------------------------------------------------
	 * BASE
	 * ----------------------------------------------------------------------
	 *
	 * Normal document/content layer.
	 *
	 * No explicit z-index is required for ordinary document flow.
	 */

	--rajgir-z-base:
		var(--wp--preset--z-index--base);


	/*
	 * ----------------------------------------------------------------------
	 * DROPDOWN
	 * ----------------------------------------------------------------------
	 */

	--rajgir-z-dropdown:
		var(--wp--preset--z-index--dropdown);


	/*
	 * ----------------------------------------------------------------------
	 * STICKY
	 * ----------------------------------------------------------------------
	 */

	--rajgir-z-sticky:
		var(--wp--preset--z-index--sticky);


	/*
	 * ----------------------------------------------------------------------
	 * MODAL
	 * ----------------------------------------------------------------------
	 */

	--rajgir-z-modal:
		var(--wp--preset--z-index--modal);


	/*
	 * ----------------------------------------------------------------------
	 * TOAST
	 * ----------------------------------------------------------------------
	 */

	--rajgir-z-toast:
		var(--wp--preset--z-index--toast);

}


/* ==========================================================================
   SEMANTIC LAYER ALIASES
   ========================================================================== */

:root {

	/*
	 * Semantic aliases allow components to consume the centralized
	 * layering vocabulary without inventing their own z-index scale.
	 */

	--rajgir-layer-base:
		var(--rajgir-z-base);

	--rajgir-layer-dropdown:
		var(--rajgir-z-dropdown);

	--rajgir-layer-sticky:
		var(--rajgir-z-sticky);

	--rajgir-layer-modal:
		var(--rajgir-z-modal);

	--rajgir-layer-toast:
		var(--rajgir-z-toast);

}


/* ==========================================================================
   Z-INDEX USAGE CONTRACT
   ========================================================================== */

/*
 * Components must consume semantic tokens:
 *
 *     z-index: var(--rajgir-layer-dropdown);
 *
 *     z-index: var(--rajgir-layer-sticky);
 *
 *     z-index: var(--rajgir-layer-modal);
 *
 *     z-index: var(--rajgir-layer-toast);
 *
 *
 * Components must NOT create arbitrary values such as:
 *
 *     z-index: 999;
 *     z-index: 9999;
 *     z-index: 99999;
 *     z-index: 999999;
 *
 * The approved source explicitly prohibits random z-index values.
 */


/* ==========================================================================
   STACKING ORDER
   ========================================================================== */

/*
 * Canonical conceptual order:
 *
 * BASE
 *   ↓
 * DROPDOWN
 *   ↓
 * STICKY
 *   ↓
 * MODAL
 *   ↓
 * TOAST
 *
 * This hierarchy provides the shared Rajgir stacking vocabulary.
 *
 * Exact numeric implementation remains controlled by the approved
 * Design System token authority.
 */


/* ==========================================================================
   COMPONENT DEPENDENCY
   ========================================================================== */

/*
 * Expected consumers:
 *
 * Header / Sticky UI
 *     → --rajgir-layer-sticky
 *
 * Dropdown / Menu
 *     → --rajgir-layer-dropdown
 *
 * Modal / Drawer / Bottom Sheet
 *     → --rajgir-layer-modal
 *
 * Toast / Notification
 *     → --rajgir-layer-toast
 *
 * Ordinary content
 *     → base document flow
 */


/* ==========================================================================
   MODAL / NAVIGATION RELATIONSHIP
   ========================================================================== */

/*
 * When multiple overlay surfaces coexist, their layering must follow
 * the centralized stacking strategy.
 *
 * Example:
 *
 * Modal
 *     ↓
 * Bottom Navigation
 *
 * The modal must not be blocked by lower-priority navigation UI.
 *
 * Actual numeric values must come from the centralized token system.
 */


/* ==========================================================================
   FIXED / STICKY UI RULE
   ========================================================================== */

/*
 * Sticky and fixed UI must also preserve:
 *
 * - content visibility;
 * - accessibility;
 * - mobile viewport usability;
 * - performance.
 *
 * Z-index alone must never be used to hide a layout problem.
 */


/* ==========================================================================
   STACKING CONTEXT RULE
   ========================================================================== */

/*
 * A z-index value is meaningful only within its stacking context.
 *
 * Therefore:
 *
 * z-index
 *     +
 * positioning
 *     +
 * stacking context
 *
 * must be considered together.
 *
 * Do not solve unrelated layout problems by increasing z-index.
 */


/* ==========================================================================
   OVERFLOW RULE
   ========================================================================== */

/*
 * Do not combine arbitrary z-index escalation with:
 *
 *     overflow: hidden;
 *
 * merely to hide layout problems.
 *
 * Root cause must be corrected in the appropriate layout layer.
 */


/* ==========================================================================
   Z-INDEX BOUNDARY
   ========================================================================== */

/*
 * This file owns:
 *
 *     Z-index vocabulary
 *
 * It does NOT own:
 *
 *     positioning;
 *     modal behavior;
 *     dropdown behavior;
 *     sticky behavior;
 *     navigation behavior;
 *     toast behavior;
 *     JavaScript interaction;
 *     business logic.
 *
 * Those responsibilities belong to their respective component/layout
 * layers.
 */


/* ==========================================================================
   GOVERNANCE
   ========================================================================== */

/*
 * New stacking layers must not be invented casually.
 *
 * If a new layer is required:
 *
 * Requirement
 *     ↓
 * Layering Review
 *     ↓
 * Design System Decision
 *     ↓
 * Token Update
 *     ↓
 * Component Consumption
 *
 * Exact numeric values require approved authority.
 */