Adds Z-Index Layering System

Author: latin-panda

packages/web-forms/README.md

@@ -49,6 +49,23 @@ It uses the [PrimeVue component library](https://primevue.org/).
 
 We are using a customized version of the Material Light Indigo theme provided by PrimeVue.
 
+#### Z-Index Layering System
+
+This package uses a centralized `z-index` layering system to manage UI stacking order, defined in `src/assets/css/z-index.css`. Custom properties (e.g., `--z-index-error-banner`) ensure elements like floating error messages, form controls, and overlays stack correctly without overlap.
+
+- **Key Layers**:
+
+  - `--z-index-base: 0` (background)
+  - `--z-index-form-content: 10` (inputs, buttons)
+  - `--z-index-form-floating: 20` (highlights, tooltips)
+  - `--z-index-error-banner: 30` (floating errors)
+  - `--z-index-overlay: 100` (modals)
+  - `--z-index-topmost: 1000` (loaders, notifications)
+
+- **Usage**: Apply with `z-index: var(--z-index-error-banner);` on positioned elements (e.g., `position: absolute`).
+
+See [src/assets/css/z-index.css](src/assets/css/z-index.css) for full details.
+
 ### Icons
 
 We use **Material Icons** using IcoMoon to select a subset of icons in order to minimize the size. The font files are located in [`./src/assets/fonts/`](./src/assets/fonts/), and the CSS is [`./src/assets/css/icomoon.css`](/src/assets/css/icomoon.css). Our IcoMoon definition is in the root directory of this package at [`./icomoon.json`](./icomoon.json).

packages/web-forms/src/assets/css/z-index.css

@@ -0,0 +1,39 @@
+/**
+ * Z-Index Layering System
+ *
+ * This project uses a centralized z-index layering system to manage the stacking order of UI
+ * elements, preventing overlap issues and ensuring maintainability. CSS custom properties are
+ * defined with meaningful names and a logical sequence, making it easy to understand and adjust
+ * the stacking order.
+ *
+ * Purpose:
+ * - Avoid z-index conflicts by assigning predefined layers to UI components.
+ * - Provide clarity on stacking priorities for developers and maintainers.
+ * - Allow flexibility for future additions without restructuring existing values.
+ *
+ * Example:
+ * .error-banner-placeholder {
+ *   z-index: var(--z-index-error-banner);
+ *   position: absolute;
+ * }
+ */
+
+:root {
+	/* Base layer for static content (e.g., page content, form background) */
+	--z-index-base: 0;
+
+	/* Standard form controls (e.g., inputs, labels, buttons) */
+	--z-index-form-content: 10;
+
+	/* Floating form elements (e.g., validation highlights, tooltips) */
+	--z-index-form-floating: 20;
+
+	/* Floating error messages or banners above the form */
+	--z-index-error-banner: 30;
+
+	/* Overlays like modals, popups, or dialogs above form content */
+	--z-index-overlay: 100;
+
+	/* Critical UI elements (e.g., loading spinners, toast notifications) */
+	--z-index-topmost: 1000;
+}

packages/web-forms/src/components/OdkWebForm.vue

@@ -269,7 +269,7 @@ watchEffect(() => {
 
 		.form-error-message.p-message.p-message-error {
 			position: fixed;
-			z-index: 100;
+			z-index: var(--z-index-error-banner);
 			border-radius: 10px;
 			background-color: var(--error-bg-color);
 			border: 1px solid var(--error-text-color);

packages/web-forms/src/components/controls/Range/RangeControl.vue

@@ -192,7 +192,7 @@ const orientation = props.node.appearances.vertical ? 'vertical' : 'horizontal';
 		// No clue why PrimeVue has a default `transform` style to shrink this!
 		transform: none;
 
-		z-index: 1;
+		z-index: var(--z-index-form-content);
 
 		&:focus-visible {
 			box-shadow:

packages/web-forms/src/components/widgets/LikertWidget.vue

@@ -69,7 +69,7 @@ defineEmits(['change']);
 
 		.p-radiobutton {
 			position: relative;
-			z-index: 10;
+			z-index: var(--z-index-form-content);
 		}
 
 		.label-text {

packages/web-forms/src/demo/FeedbackButton.vue

@@ -38,7 +38,7 @@ const surveyLink = computed(() => {
 	right: 0;
 	bottom: 150px;
 	height: 4rem;
-	z-index: 99999;
+	z-index: var(--z-index-topmost);
 	border-top-left-radius: 5px;
 	border-top-right-radius: 5px;
 	text-align: center;

packages/web-forms/src/index.ts

@@ -3,6 +3,7 @@ import OdkWebForm from './components/OdkWebForm.vue';
 
 import '@fontsource/roboto/300.css';
 import './assets/css/icomoon.css';
+import './assets/css/z-index.css';
 import './themes/2024-light/theme.scss';
 
 // TODO/sk: Purge it - using postcss-purgecss