From a1e8d060f59e3cf10e718fdbdab25892415d39c3 Mon Sep 17 00:00:00 2001
From: Machado da Silva Hugo <hugomslv@users.noreply.github.com>
Date: Wed, 2 Jul 2025 10:08:33 +0200
Subject: [PATCH 1/5] chore(z-index): add Z-Index utility

---
 .changeset/slick-banks-report.md              |  6 ++
 .../utilities/z-index/z-index.docs.mdx        | 24 ++++++++
 .../z-index/z-index.snapshot.stories.ts       |  1 +
 .../utilities/z-index/z-index.stories.ts      | 61 +++++++++++++++++++
 .../utilities/z-index/z-index.styles.scss     | 36 +++++++++++
 .../src/themes/bootstrap/_utilities.scss      |  1 +
 packages/styles/src/utilities/_variables.scss | 11 ++++
 7 files changed, 140 insertions(+)
 create mode 100644 .changeset/slick-banks-report.md
 create mode 100644 packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx
 create mode 100644 packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts
 create mode 100644 packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
 create mode 100644 packages/documentation/src/stories/utilities/z-index/z-index.styles.scss

diff --git a/.changeset/slick-banks-report.md b/.changeset/slick-banks-report.md
new file mode 100644
index 0000000000..769f046e0f
--- /dev/null
+++ b/.changeset/slick-banks-report.md
@@ -0,0 +1,6 @@
+---
+'@swisspost/design-system-documentation': minor
+'@swisspost/design-system-styles': minor
+---
+
+Added Z-index utility.
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx b/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx
new file mode 100644
index 0000000000..f36e646384
--- /dev/null
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx
@@ -0,0 +1,24 @@
+import { Canvas, Controls, Meta } from '@storybook/blocks';
+import * as ZIndexStories from './z-index.stories';
+
+<Meta of={ZIndexStories} />
+
+# Z-Index
+
+<div className="lead">
+  Use our <code>{".z-{value}"}</code> utility classes to control element stacking. Each element must have a non-static position (e.g. <code>relative</code>, <code>absolute</code> or <code>fixed</code>) for the z-index to take effect.
+</div>
+
+> **Classes disponibles :**
+> - <code>.z-n1</code>
+> - <code>.z-0</code>
+> - <code>.z-1</code>
+> - <code>.z-2</code>
+> - <code>.z-3</code>
+
+## Example
+
+<Canvas sourceState="shown" of={ZIndexStories.ZIndex} />
+<div className="hide-col-default">
+  <Controls of={ZIndexStories.ZIndex} />
+</div>
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts b/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts
new file mode 100644
index 0000000000..ff8b4c5632
--- /dev/null
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts
@@ -0,0 +1 @@
+export default {};
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts b/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
new file mode 100644
index 0000000000..f71d385044
--- /dev/null
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
@@ -0,0 +1,61 @@
+import type { Args, StoryObj, StoryFn, StoryContext } from '@storybook/web-components';
+import { html } from 'lit';
+import './z-index.styles.scss';
+import { MetaExtended } from '@root/types';
+
+const meta: MetaExtended = {
+  id: 'd4b7f8a2-1c3e-4b5d-9f1a-2e6b0c7a9f3d',
+  title: 'Utilities/Z-Index',
+  args: {
+    zIndex1: '0',
+    zIndex2: '1',
+    zIndex3: '2',
+  },
+  argTypes: {
+    zIndex1: {
+      name: 'Box 1 zIndex',
+      description: 'z-index de la première boîte',
+      control: { type: 'select' },
+      options: ['n1', '0', '1', '2', '3'],
+      table: { category: 'Boxes' },
+    },
+    zIndex2: {
+      name: 'Box 2 zIndex',
+      description: 'z-index de la deuxième boîte',
+      control: { type: 'select' },
+      options: ['n1', '0', '1', '2', '3'],
+      table: { category: 'Boxes' },
+    },
+    zIndex3: {
+      name: 'Box 3 zIndex',
+      description: 'z-index de la troisième boîte',
+      control: { type: 'select' },
+      options: ['n1', '0', '1', '2', '3'],
+      table: { category: 'Boxes' },
+    },
+  },
+  render: (args: Args) => {
+    return html`
+      <div class="position-relative container-examples">
+        <div class="z-${args.zIndex1} position-absolute z-container rounded-4">
+          Box 1 (z-${args.zIndex1})
+        </div>
+        <div class="z-${args.zIndex2} position-absolute z-container rounded-4">
+          Box 2 (z-${args.zIndex2})
+        </div>
+        <div class="z-${args.zIndex3} position-absolute z-container rounded-4">
+          Box 3 (z-${args.zIndex3})
+        </div>
+      </div>
+    `;
+  },
+  decorators: [
+    (story: StoryFn, context: StoryContext) => {
+      return story(context.args, context);
+    },
+  ],
+};
+
+export default meta;
+type Story = StoryObj;
+export const ZIndex: Story = {};
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss b/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss
new file mode 100644
index 0000000000..ae867ffd34
--- /dev/null
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss
@@ -0,0 +1,36 @@
+@use '@swisspost/design-system-styles/core' as post;
+
+.container-examples {
+  position: relative;
+  width: 300px;
+  height: 200px;
+  z-index: 0;
+}
+
+.z-container {
+  width: 100px;
+  height: 100px;
+  background-color: post.$yellow;
+  color: white;
+  font-weight: bold;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid  ;
+
+}
+
+.z-container:nth-child(1) {
+  top: 0;
+  left: 0;
+}
+
+.z-container:nth-child(2) {
+  top: 35px;
+  left: 45px;
+}
+
+.z-container:nth-child(3) {
+  top: 70px;
+  left:90px;
+}
diff --git a/packages/styles/src/themes/bootstrap/_utilities.scss b/packages/styles/src/themes/bootstrap/_utilities.scss
index 5a30e00f74..b94d0ec582 100644
--- a/packages/styles/src/themes/bootstrap/_utilities.scss
+++ b/packages/styles/src/themes/bootstrap/_utilities.scss
@@ -96,5 +96,6 @@ $utilities: map.remove($utilities, 'text-decoration');
 $utilities: map.remove($utilities, 'text-transform');
 $utilities: map.remove($utilities, 'white-space');
 $utilities: map.remove($utilities, 'word-wrap');
+$utilities: map.remove($utilities, 'z-index');
 
 @import 'bootstrap/scss/utilities/api';
diff --git a/packages/styles/src/utilities/_variables.scss b/packages/styles/src/utilities/_variables.scss
index 8715969f2f..9666093509 100644
--- a/packages/styles/src/utilities/_variables.scss
+++ b/packages/styles/src/utilities/_variables.scss
@@ -567,6 +567,17 @@ $utilities: (
       reset: inherit,
     ),
   ),
+  'z-index': (
+    property: z-index,
+    class: z,
+    values: (
+      n1: -1,
+      0: 0,
+      1: 1,
+      2: 2,
+      3: 3,
+    ),
+  ),
 );
 
 /* IMPORTANT: When adding new utilities here, please ensure to remove the corresponding bootstrap utilities in `src/themes/bootstrap/_utilities.scss`. */

From 99f50cc3ef7a943914d917602f2e276dbaf6acd0 Mon Sep 17 00:00:00 2001
From: Machado da Silva Hugo <hugomslv@users.noreply.github.com>
Date: Mon, 7 Jul 2025 09:20:47 +0200
Subject: [PATCH 2/5] fix comments

Add snapshots for z-index
Add visual regression tests for z-index
Fix PR comments
---
 .../snapshots/utilities/z-index.snapshot.ts   |  7 ++++
 .../utilities/z-index/z-index.docs.mdx        | 12 +++----
 .../z-index/z-index.snapshot.stories.ts       | 32 ++++++++++++++++-
 .../utilities/z-index/z-index.stories.ts      | 31 ++++++----------
 .../utilities/z-index/z-index.styles.scss     | 35 ++++++++++++-------
 5 files changed, 76 insertions(+), 41 deletions(-)
 create mode 100644 packages/documentation/cypress/snapshots/utilities/z-index.snapshot.ts

diff --git a/packages/documentation/cypress/snapshots/utilities/z-index.snapshot.ts b/packages/documentation/cypress/snapshots/utilities/z-index.snapshot.ts
new file mode 100644
index 0000000000..ede9419b7c
--- /dev/null
+++ b/packages/documentation/cypress/snapshots/utilities/z-index.snapshot.ts
@@ -0,0 +1,7 @@
+describe('Z-Index', () => {
+  it('z-index', () => {
+    cy.visit('/iframe.html?id=snapshots--z-index');
+    cy.get('.container-examples', { timeout: 30000 }).should('be.visible');
+    cy.percySnapshot('Z-Index', { widths: [1440] });
+  });
+});
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx b/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx
index f36e646384..3ccf2ab082 100644
--- a/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx
@@ -9,12 +9,12 @@ import * as ZIndexStories from './z-index.stories';
   Use our <code>{".z-{value}"}</code> utility classes to control element stacking. Each element must have a non-static position (e.g. <code>relative</code>, <code>absolute</code> or <code>fixed</code>) for the z-index to take effect.
 </div>
 
-> **Classes disponibles :**
-> - <code>.z-n1</code>
-> - <code>.z-0</code>
-> - <code>.z-1</code>
-> - <code>.z-2</code>
-> - <code>.z-3</code>
+**Available classes:**
+- <code>.z-n1</code>
+- <code>.z-0</code>
+- <code>.z-1</code>
+- <code>.z-2</code>
+- <code>.z-3</code>
 
 ## Example
 
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts b/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts
index ff8b4c5632..38c64dc78b 100644
--- a/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts
@@ -1 +1,31 @@
-export default {};
+import type { StoryObj } from '@storybook/web-components';
+import { html } from 'lit';
+import { COLOR_SCHEMES, schemes } from '@/shared/snapshots/schemes';
+import meta from './z-index.stories';
+import './z-index.styles.scss';
+
+const { id, ...metaWithoutId } = meta;
+
+export default {
+  ...metaWithoutId,
+  title: 'Snapshots',
+};
+
+type Story = StoryObj;
+
+export const ZIndex: Story = {
+  render: () => {
+    return schemes(
+      () => html`
+        <div class="container-examples">
+          <div class="position-absolute z-n1">z-index: -1</div>
+          <div class="position-absolute z-0">z-index: 0</div>
+          <div class="position-absolute z-1">z-index: 1</div>
+          <div class="position-absolute z-2">z-index: 2</div>
+          <div class="position-absolute z-3">z-index: 3</div>
+        </div>
+      `,
+      { filter: scheme => scheme === COLOR_SCHEMES.light },
+    );
+  },
+};
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts b/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
index f71d385044..c68451fae2 100644
--- a/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
@@ -13,22 +13,22 @@ const meta: MetaExtended = {
   },
   argTypes: {
     zIndex1: {
-      name: 'Box 1 zIndex',
-      description: 'z-index de la première boîte',
+      name: 'Box 1 z-Index',
+      description: 'z-index first box',
       control: { type: 'select' },
       options: ['n1', '0', '1', '2', '3'],
       table: { category: 'Boxes' },
     },
     zIndex2: {
-      name: 'Box 2 zIndex',
-      description: 'z-index de la deuxième boîte',
+      name: 'Box 2 z-Index',
+      description: 'z-index second box',
       control: { type: 'select' },
       options: ['n1', '0', '1', '2', '3'],
       table: { category: 'Boxes' },
     },
     zIndex3: {
-      name: 'Box 3 zIndex',
-      description: 'z-index de la troisième boîte',
+      name: 'Box 3 z-Index',
+      description: 'z-index third box ',
       control: { type: 'select' },
       options: ['n1', '0', '1', '2', '3'],
       table: { category: 'Boxes' },
@@ -36,24 +36,13 @@ const meta: MetaExtended = {
   },
   render: (args: Args) => {
     return html`
-      <div class="position-relative container-examples">
-        <div class="z-${args.zIndex1} position-absolute z-container rounded-4">
-          Box 1 (z-${args.zIndex1})
-        </div>
-        <div class="z-${args.zIndex2} position-absolute z-container rounded-4">
-          Box 2 (z-${args.zIndex2})
-        </div>
-        <div class="z-${args.zIndex3} position-absolute z-container rounded-4">
-          Box 3 (z-${args.zIndex3})
-        </div>
+      <div class="container-examples">
+        <div class="z-${args.zIndex1} position-absolute">Box 1 (z-${args.zIndex1})</div>
+        <div class="z-${args.zIndex2} position-absolute">Box 2 (z-${args.zIndex2})</div>
+        <div class="z-${args.zIndex3} position-absolute">Box 3 (z-${args.zIndex3})</div>
       </div>
     `;
   },
-  decorators: [
-    (story: StoryFn, context: StoryContext) => {
-      return story(context.args, context);
-    },
-  ],
 };
 
 export default meta;
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss b/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss
index ae867ffd34..ca807aceb9 100644
--- a/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss
@@ -2,35 +2,44 @@
 
 .container-examples {
   position: relative;
-  width: 300px;
-  height: 200px;
+  height: 250px;
   z-index: 0;
 }
 
-.z-container {
+.container-examples > div{
   width: 100px;
   height: 100px;
   background-color: post.$yellow;
-  color: white;
+  color: post.$black;
   font-weight: bold;
   display: flex;
   align-items: center;
   justify-content: center;
-  border: 1px solid  ;
-
+  border: post.$white 2px solid  ;
+  border-radius: 0.5rem;
 }
 
-.z-container:nth-child(1) {
+.container-examples > div:nth-child(1) {
   top: 0;
   left: 0;
 }
 
-.z-container:nth-child(2) {
-  top: 35px;
-  left: 45px;
+.container-examples > div:nth-child(2) {
+  top: 20px;
+  left: 30px;
+}
+
+.container-examples > div:nth-child(3) {
+  top: 40px;
+  left: 60px;
+}
+
+.container-examples > div:nth-child(4) {
+  top: 60px;
+  left: 90px;
 }
 
-.z-container:nth-child(3) {
-  top: 70px;
-  left:90px;
+.container-examples > div:nth-child(5) {
+  top: 80px;
+  left: 120px;
 }

From 943d189e63dc41f73d02231c7222fe63807f2b71 Mon Sep 17 00:00:00 2001
From: Machado da Silva Hugo <hugomslv@users.noreply.github.com>
Date: Mon, 7 Jul 2025 09:29:12 +0200
Subject: [PATCH 3/5] Update slick-banks-report.md

---
 .changeset/slick-banks-report.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.changeset/slick-banks-report.md b/.changeset/slick-banks-report.md
index 769f046e0f..5c500298eb 100644
--- a/.changeset/slick-banks-report.md
+++ b/.changeset/slick-banks-report.md
@@ -3,4 +3,4 @@
 '@swisspost/design-system-styles': minor
 ---
 
-Added Z-index utility.
+Internalized bootstrap z-index utilities.

From e10d59fd99a3f430fb6230038c53ac68f4ea2ac9 Mon Sep 17 00:00:00 2001
From: Machado da Silva Hugo <hugomslv@users.noreply.github.com>
Date: Mon, 7 Jul 2025 09:34:54 +0200
Subject: [PATCH 4/5] Remove this unused import

---
 .../src/stories/utilities/z-index/z-index.stories.ts            | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts b/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
index c68451fae2..dfec0fe082 100644
--- a/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
@@ -1,4 +1,4 @@
-import type { Args, StoryObj, StoryFn, StoryContext } from '@storybook/web-components';
+import type { Args, StoryObj } from '@storybook/web-components';
 import { html } from 'lit';
 import './z-index.styles.scss';
 import { MetaExtended } from '@root/types';

From 3b834df08617732059388975aaf265b5d1fafe91 Mon Sep 17 00:00:00 2001
From: Machado da Silva Hugo <hugomslv@users.noreply.github.com>
Date: Thu, 7 Aug 2025 10:06:41 +0200
Subject: [PATCH 5/5] fix comment

---
 .../utilities/z-index/z-index.docs.mdx        |  2 +-
 .../z-index/z-index.snapshot.stories.ts       | 12 +++----
 .../utilities/z-index/z-index.stories.ts      |  8 ++---
 .../utilities/z-index/z-index.styles.scss     | 31 +++++--------------
 4 files changed, 18 insertions(+), 35 deletions(-)

diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx b/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx
index 3ccf2ab082..5ee41d23d4 100644
--- a/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.docs.mdx
@@ -1,4 +1,4 @@
-import { Canvas, Controls, Meta } from '@storybook/blocks';
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as ZIndexStories from './z-index.stories';
 
 <Meta of={ZIndexStories} />
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts b/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts
index 38c64dc78b..5444751ffd 100644
--- a/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.snapshot.stories.ts
@@ -1,4 +1,4 @@
-import type { StoryObj } from '@storybook/web-components';
+import type { StoryObj } from '@storybook/web-components-vite';
 import { html } from 'lit';
 import { COLOR_SCHEMES, schemes } from '@/shared/snapshots/schemes';
 import meta from './z-index.stories';
@@ -18,11 +18,11 @@ export const ZIndex: Story = {
     return schemes(
       () => html`
         <div class="container-examples">
-          <div class="position-absolute z-n1">z-index: -1</div>
-          <div class="position-absolute z-0">z-index: 0</div>
-          <div class="position-absolute z-1">z-index: 1</div>
-          <div class="position-absolute z-2">z-index: 2</div>
-          <div class="position-absolute z-3">z-index: 3</div>
+          <div class="position-absolute z-3">z-3</div>
+          <div class="position-absolute z-2">z-2</div>
+          <div class="position-absolute z-1">z-1</div>
+          <div class="position-absolute z-0">z-0</div>
+          <div class="position-absolute z-n1">z-n1</div>
         </div>
       `,
       { filter: scheme => scheme === COLOR_SCHEMES.light },
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts b/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
index dfec0fe082..48af040c91 100644
--- a/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.stories.ts
@@ -1,4 +1,4 @@
-import type { Args, StoryObj } from '@storybook/web-components';
+import type { Args, StoryObj } from '@storybook/web-components-vite';
 import { html } from 'lit';
 import './z-index.styles.scss';
 import { MetaExtended } from '@root/types';
@@ -37,9 +37,9 @@ const meta: MetaExtended = {
   render: (args: Args) => {
     return html`
       <div class="container-examples">
-        <div class="z-${args.zIndex1} position-absolute">Box 1 (z-${args.zIndex1})</div>
-        <div class="z-${args.zIndex2} position-absolute">Box 2 (z-${args.zIndex2})</div>
-        <div class="z-${args.zIndex3} position-absolute">Box 3 (z-${args.zIndex3})</div>
+        <div class="z-${args.zIndex1} position-absolute">z-${args.zIndex1}</div>
+        <div class="z-${args.zIndex2} position-absolute">z-${args.zIndex2}</div>
+        <div class="z-${args.zIndex3} position-absolute">z-${args.zIndex3}</div>
       </div>
     `;
   },
diff --git a/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss b/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss
index ca807aceb9..edd6a83e2c 100644
--- a/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss
+++ b/packages/documentation/src/stories/utilities/z-index/z-index.styles.scss
@@ -13,33 +13,16 @@
   color: post.$black;
   font-weight: bold;
   display: flex;
-  align-items: center;
-  justify-content: center;
+  align-items: end;
+  justify-content: start;
   border: post.$white 2px solid  ;
   border-radius: 0.5rem;
 }
 
-.container-examples > div:nth-child(1) {
-  top: 0;
-  left: 0;
+@for $i from 1 through 5 {
+  .container-examples > div:nth-child(#{$i}) {
+    top: #{($i - 1) * 30}px;
+    left: #{($i - 1) * 40}px;
+  }
 }
 
-.container-examples > div:nth-child(2) {
-  top: 20px;
-  left: 30px;
-}
-
-.container-examples > div:nth-child(3) {
-  top: 40px;
-  left: 60px;
-}
-
-.container-examples > div:nth-child(4) {
-  top: 60px;
-  left: 90px;
-}
-
-.container-examples > div:nth-child(5) {
-  top: 80px;
-  left: 120px;
-}