From a38356225cce8a80b3c8ca29035c38b6803844b7 Mon Sep 17 00:00:00 2001
From: Lisa White <lisa.white@contentful.com>
Date: Tue, 29 Oct 2024 15:53:15 -0600
Subject: [PATCH] docs(progress-stepper): add horizontal width limitation
 example

---
 .../components/progress-stepper/README.mdx    | 10 +++++
 ...ogressStepperHorizontalWidthLimitation.tsx | 39 +++++++++++++++++++
 2 files changed, 49 insertions(+)
 create mode 100644 packages/components/progress-stepper/examples/ProgressStepperHorizontalWidthLimitation.tsx

diff --git a/packages/components/progress-stepper/README.mdx b/packages/components/progress-stepper/README.mdx
index 0d1390803f..c38fa8bc2c 100644
--- a/packages/components/progress-stepper/README.mdx
+++ b/packages/components/progress-stepper/README.mdx
@@ -74,6 +74,16 @@ Example of the ProgressStepper with buttons to move between steps.
 
 ```
 
+### Horizontal Label Width Limitation
+
+When the ProgressStepper renders in the horizontal orientation with labels, the component will have extra width on the sides of the first and last steps.
+This extra width is necessary in order to accommodate the centering of the labels under each step.
+This example demonstrates this extra width so that consumers of this component can plan accordingly in designs, as the ProgressStepper component will not be the same width as the content area.
+
+```jsx file=./examples/ProgressStepperHorizontalWidthLimitation.tsx
+
+```
+
 ## Props (API reference)
 
 ### ProgressStepper
diff --git a/packages/components/progress-stepper/examples/ProgressStepperHorizontalWidthLimitation.tsx b/packages/components/progress-stepper/examples/ProgressStepperHorizontalWidthLimitation.tsx
new file mode 100644
index 0000000000..8f97704da5
--- /dev/null
+++ b/packages/components/progress-stepper/examples/ProgressStepperHorizontalWidthLimitation.tsx
@@ -0,0 +1,39 @@
+import React from 'react';
+import { ProgressStepper } from '@contentful/f36-progress-stepper';
+import { Box, Header } from '@contentful/f36-components';
+import tokens from '@contentful/f36-tokens';
+import { css } from 'emotion';
+
+export default function ProgressStepperHorizontalWidthLimitation() {
+  const styles = {
+    root: css({
+      border: `1px solid ${tokens.gray300}`,
+    }),
+    stepperContainer: css({
+      padding: `${tokens.spacingS} 0`,
+    }),
+    headerContainer: css({
+      borderTop: `1px solid ${tokens.gray300}`,
+    }),
+  };
+
+  return (
+    <Box className={styles.root}>
+      <Box className={styles.stepperContainer}>
+        <ProgressStepper
+          activeStep={2}
+          ariaLabel="Horizontal progress stepper width limitation example"
+        >
+          <ProgressStepper.Step state="complete" labelText="Label 1" />
+          <ProgressStepper.Step state="complete" labelText="Label 2" />
+          <ProgressStepper.Step state="active" labelText="Label 3" />
+          <ProgressStepper.Step labelText="Label 4" />
+          <ProgressStepper.Step labelText="Label 5" />
+        </ProgressStepper>
+      </Box>
+      <Box className={styles.headerContainer}>
+        <Header title="Header within the same parent container" />
+      </Box>
+    </Box>
+  );
+}