From 43eee38ce6edabc9fb7c70c4340077361c96efe7 Mon Sep 17 00:00:00 2001
From: Bartosz-Do <xbartoszdobija@gmail.com>
Date: Tue, 7 Jul 2026 17:26:34 +0200
Subject: [PATCH] Add documentation for the Progress Step component (#2677)

---
 .changeset/progress-step-docs.md            |  6 ++
 .gitignore                                  |  1 +
 docs/content/ui/components/progress-step.md | 94 +++++++++++++++++++++
 shared/includes/ui/progress-steps.html      |  7 +-
 4 files changed, 103 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/progress-step-docs.md
 create mode 100644 docs/content/ui/components/progress-step.md

diff --git a/.changeset/progress-step-docs.md b/.changeset/progress-step-docs.md
new file mode 100644
index 000000000..5ab8b6ca6
--- /dev/null
+++ b/.changeset/progress-step-docs.md
@@ -0,0 +1,6 @@
+---
+"@tabler/docs": patch
+"@tabler/preview": patch
+---
+
+Added `Progress Step` component documentation and updated `ui/progress-steps.html` formatting for cleaner rendered output.
diff --git a/.gitignore b/.gitignore
index b05a5d31e..b224e65e1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,6 +11,7 @@ node_modules/
 /_site/
 /.cache/
 .sass-cache/
+.pnpm-store/
 
 /_gh_pages/
 /site/docs/**/dist/
diff --git a/docs/content/ui/components/progress-step.md b/docs/content/ui/components/progress-step.md
new file mode 100644
index 000000000..12b9afc17
--- /dev/null
+++ b/docs/content/ui/components/progress-step.md
@@ -0,0 +1,94 @@
+---
+title: Progress Steps
+summary: A progress step helps users track their place in a short process by breaking it into clear, simple steps. This makes flows like setup or onboarding easier to follow and finish.
+new: true
+description: Use progress steps to display compact onboarding, checkout, and setup progress.
+---
+
+## Default markup
+
+Use `.progress-steps` as the container and `.progress-steps-item` for each segment. These two classes are enough to create the base component structure.
+
+```html
+<ol class="progress-steps" aria-label="Onboarding progress">
+  <li class="progress-steps-item"></li>
+  <li class="progress-steps-item"></li>
+  <li class="progress-steps-item"></li>
+</ol>
+```
+
+The example below shows the default progress step structure.
+
+{% capture html -%}
+
+<ol class="progress-steps" aria-label="Onboarding progress">
+  <li class="progress-steps-item"></li>
+  <li class="progress-steps-item"></li>
+  <li class="progress-steps-item"></li>
+  <li class="progress-steps-item"></li>
+</ol>
+{%- endcapture %}
+
+{% include "docs/example.html" html=html %}
+
+## Variants
+
+### Current and completed step
+
+Use color classes to mark completed steps. Set `aria-current="step"` on the current item.
+
+{% capture html -%} {% include "ui/progress-steps.html" count=4 active=2 aria-label="Setup progress" %} {%- endcapture %} {% include "docs/example.html" html=html %}
+
+### Custom labels
+
+Use hidden labels so assistive technologies can announce meaningful step names.
+
+{% capture html -%} {% include "ui/progress-steps.html" labels="Account,Profile,Billing,Review" active=3 aria-label="Checkout progress" %} {%- endcapture %} {% include "docs/example.html" html=html %}
+
+### Color state
+
+Use contextual background classes on completed and current items. This helps match state color to your flow semantics.
+
+{% capture html -%}
+
+<div class="mb-2">
+  <ol class="progress-steps" aria-label="Green progress">
+    <li class="progress-steps-item bg-green" aria-current="step">
+      <span class="visually-hidden">Step 1</span>
+    </li>
+    <li class="progress-steps-item">
+      <span class="visually-hidden">Step 2</span>
+    </li>
+  </ol>
+</div>
+
+<div class="mb-2">
+  <ol class="progress-steps" aria-label="Orange progress">
+	 <li class="progress-steps-item bg-orange" aria-current="step">
+	   <span class="visually-hidden">Step 1</span>
+	 </li>
+	 <li class="progress-steps-item">
+      <span class="visually-hidden">Step 2</span>
+    </li>
+  </ol>
+</div>
+
+<div>
+  <ol class="progress-steps" aria-label="Red progress">
+    <li class="progress-steps-item bg-red" aria-current="step">
+      <span class="visually-hidden">Step 1</span>
+    </li>
+    <li class="progress-steps-item">
+      <span class="visually-hidden">Step 2</span>
+    </li>
+  </ol>
+</div>
+{%- endcapture %}
+
+{% include "docs/example.html" html=html %}
+
+### Width and layout utilities
+
+Use utility classes on `.progress-steps` to control width and placement in layouts.
+
+{% capture html -%} {% include "ui/progress-steps.html" count=5 active=1 class="w-50" id="profile-progress" aria-label="Profile completion" %} {%- endcapture %} {% include "docs/example.html" html=html %}
diff --git a/shared/includes/ui/progress-steps.html b/shared/includes/ui/progress-steps.html
index e0d686560..5eb1492af 100644
--- a/shared/includes/ui/progress-steps.html
+++ b/shared/includes/ui/progress-steps.html
@@ -8,14 +8,11 @@
 {% assign color = include.color | default: 'primary' %}
 
 <ol class="progress-steps{% if include.class %} {{ include.class }}{% endif %}" {% if include.id %}
-   id="{{ include.id }}" {% endif %}{% if include['aria-label'] %} aria-label="{{ include['aria-label'] }}" {% endif %}>
-   {% for i in (1..count) %}
-   {% assign default = 'Step ' | append: i %}
-   {% assign label = labels[forloop.index0] | default: default %}
+   id="{{ include.id }}" {% endif %}{% if include['aria-label'] %} aria-label="{{ include['aria-label'] }}" {% endif %}>{% for i in (1..count) %}{% assign default = 'Step ' | append: i %}{% assign label = labels[forloop.index0] | default: default %}
    <li class="progress-steps-item{% if i <= active %} bg-{{ color }}{% endif %}" {% if i==active %} aria-current="step"{% endif %}>
       <span class="visually-hidden">
       {{ label }}
       </span>
    </li>
-   {% endfor %}
+	{% endfor %}
 </ol>
\ No newline at end of file