From 42d102f143a264a5014edbeb0a78760a717463bb Mon Sep 17 00:00:00 2001
From: Baptiste Parmantier <baptiste.parmantier.pro@gmail.com>
Date: Sat, 13 Dec 2025 00:32:07 +0100
Subject: [PATCH 1/2] wip

---
 .../foundamentals/components/_default.mdx     |  1 +
 .../foundamentals/components/step.mdx         | 17 ++++
 explainer.config.ts                           |  4 +
 .../content/step-group/step-group.astro       | 81 +++++++++++++++++++
 .../components/content/step-group/step.astro  |  7 ++
 5 files changed, 110 insertions(+)
 create mode 100644 content/docs/documentation/foundamentals/components/step.mdx
 create mode 100644 src/lib/components/content/step-group/step-group.astro
 create mode 100644 src/lib/components/content/step-group/step.astro

diff --git a/content/docs/documentation/foundamentals/components/_default.mdx b/content/docs/documentation/foundamentals/components/_default.mdx
index cdbe2ca..c7ff02f 100644
--- a/content/docs/documentation/foundamentals/components/_default.mdx
+++ b/content/docs/documentation/foundamentals/components/_default.mdx
@@ -11,4 +11,5 @@ collection:
   - text
   - card
   - callout
+  - step
 ---
diff --git a/content/docs/documentation/foundamentals/components/step.mdx b/content/docs/documentation/foundamentals/components/step.mdx
new file mode 100644
index 0000000..2688475
--- /dev/null
+++ b/content/docs/documentation/foundamentals/components/step.mdx
@@ -0,0 +1,17 @@
+---
+title: Step
+description: Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+permalink: step
+icon: lucide:grid-2x2
+---
+
+# Steps
+
+::::step-group
+:::step
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+:::
+:::step
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+:::
+::::
diff --git a/explainer.config.ts b/explainer.config.ts
index e1da083..acb34a3 100644
--- a/explainer.config.ts
+++ b/explainer.config.ts
@@ -3,6 +3,8 @@ import CardGroup from "@/components/content/card-group/card-group.astro";
 import Card from "@/components/content/card-group/card.astro";
 import CodeGroup from "@/components/content/code-group/code-group.astro";
 import CodeBlock from "@/components/content/codeblock.astro";
+import StepGroup from "@/components/content/step-group/step-group.astro";
+import Step from "@/components/content/step-group/step.astro";
 import { defineExplainerConfig } from "@/utils";
 
 export default defineExplainerConfig({
@@ -51,6 +53,8 @@ export default defineExplainerConfig({
       "code-group": CodeGroup,
       pre: CodeBlock,
       callout: Callout,
+      "step-group": StepGroup,
+      step: Step,
     },
     icons: {
       markdown: "devicon:markdown",
diff --git a/src/lib/components/content/step-group/step-group.astro b/src/lib/components/content/step-group/step-group.astro
new file mode 100644
index 0000000..c7837b8
--- /dev/null
+++ b/src/lib/components/content/step-group/step-group.astro
@@ -0,0 +1,81 @@
+---
+
+---
+
+<div class="step-group my-8">
+  <slot />
+</div>
+
+<style is:global>
+  .step-group {
+    counter-reset: step-counter;
+  }
+
+  .step-group .step-content {
+    display: flex;
+    position: relative;
+    padding-left: 2.5rem; /* Space for the number and line */
+    margin-bottom: 2rem; /* Space between steps */
+  }
+
+  /* Vertical line */
+  .step-group .step-content::before {
+    content: "";
+    position: absolute;
+    left: 11px; /* Align with center of the circle */
+    top: 0;
+    bottom: -1rem; /* Extend line below the current step */
+    width: 2px;
+    background-color: var(
+      --astro-code-color-text
+    ); /* Use a Shiki variable for consistency */
+    opacity: 0.15;
+  }
+
+  /* Number circle */
+  .step-group .step-content::after {
+    counter-increment: step-counter;
+    content: counter(step-counter);
+    position: absolute;
+    left: 0;
+    top: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 24px;
+    width: 24px;
+    border-radius: 9999px; /* Full circle */
+    border: 1px solid var(--astro-code-color-text); /* Border color */
+    background-color: var(--astro-code-color-background); /* Background color */
+    color: var(--astro-code-color-text); /* Text color */
+    font-size: 0.875rem; /* text-sm */
+    font-weight: 600; /* font-semibold */
+    z-index: 10;
+  }
+
+  /* Hide line for the last step */
+  .step-group .step-content:last-of-type::before {
+    display: none;
+  }
+
+  /* Ensure text and headings within the step start correctly */
+  .step-group .step-content > * {
+    flex-grow: 1;
+  }
+
+  /* Reset top margin for the first heading inside a step to align with the number */
+  .step-group .step-content :where(h1, h2, h3, h4, h5, h6):first-child {
+    margin-top: 0;
+  }
+
+  /* Adjust margins for content within a step */
+  .step-group .step-content :where(p, ul, ol, .code-block, .callout) {
+    margin-top: 0.5rem;
+    margin-bottom: 0.5rem;
+  }
+
+  /* Remove bottom margin for the last element within a step-content to avoid extra space */
+  .step-group .step-content > *:last-child {
+    margin-bottom: 0;
+  }
+</style>
diff --git a/src/lib/components/content/step-group/step.astro b/src/lib/components/content/step-group/step.astro
new file mode 100644
index 0000000..58a5a0b
--- /dev/null
+++ b/src/lib/components/content/step-group/step.astro
@@ -0,0 +1,7 @@
+---
+
+---
+
+<div class="step-content">
+  <slot />
+</div>

From 37cbe2c7eb0679b839b39663eea927820807d30e Mon Sep 17 00:00:00 2001
From: Baptiste Parmantier <baptiste.parmantier.pro@gmail.com>
Date: Sat, 13 Dec 2025 01:55:06 +0100
Subject: [PATCH 2/2] feat: implement step component

---
 .../foundamentals/components/step.mdx         | 39 +++++++++-
 .../content/step-group/step-group.astro       | 76 +------------------
 .../components/content/step-group/step.astro  | 46 ++++++++++-
 3 files changed, 82 insertions(+), 79 deletions(-)

diff --git a/content/docs/documentation/foundamentals/components/step.mdx b/content/docs/documentation/foundamentals/components/step.mdx
index 2688475..2e52286 100644
--- a/content/docs/documentation/foundamentals/components/step.mdx
+++ b/content/docs/documentation/foundamentals/components/step.mdx
@@ -7,11 +7,46 @@ icon: lucide:grid-2x2
 
 # Steps
 
+This section details various processes or features, broken down into a series of manageable steps.
+
+Each `step-group` provides a structured guide, with individual steps offering explanations, instructions, and often code examples to help you achieve a specific goal or understand a particular concept.
+
+Follow the sequence of steps to successfully complete the task.
+
+## Usage
+
 ::::step-group
-:::step
+:::step{title="Lorem ipsum dolor sit amet"}
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+```rs [main.rs]
+fn main() {
+    println!("Hello, world!");
+}
+```
+
 :::
-:::step
+:::step{title="Lorem ipsum dolor sit amet"}
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
 :::
 ::::
+
+````plain [Simple steps]
+::::step-group
+  :::step{title="Lorem ipsum dolor sit amet"}
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+
+    ```rs [main.rs]
+    fn main() {
+        println!("Hello, world!");
+    }
+    ```
+  :::
+
+  :::step{title="Lorem ipsum dolor sit amet"}
+    Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+    sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+  :::
+::::
+````
diff --git a/src/lib/components/content/step-group/step-group.astro b/src/lib/components/content/step-group/step-group.astro
index c7837b8..be8e2d7 100644
--- a/src/lib/components/content/step-group/step-group.astro
+++ b/src/lib/components/content/step-group/step-group.astro
@@ -2,80 +2,6 @@
 
 ---
 
-<div class="step-group my-8">
+<div class="step-group relative my-8 py-5">
   <slot />
 </div>
-
-<style is:global>
-  .step-group {
-    counter-reset: step-counter;
-  }
-
-  .step-group .step-content {
-    display: flex;
-    position: relative;
-    padding-left: 2.5rem; /* Space for the number and line */
-    margin-bottom: 2rem; /* Space between steps */
-  }
-
-  /* Vertical line */
-  .step-group .step-content::before {
-    content: "";
-    position: absolute;
-    left: 11px; /* Align with center of the circle */
-    top: 0;
-    bottom: -1rem; /* Extend line below the current step */
-    width: 2px;
-    background-color: var(
-      --astro-code-color-text
-    ); /* Use a Shiki variable for consistency */
-    opacity: 0.15;
-  }
-
-  /* Number circle */
-  .step-group .step-content::after {
-    counter-increment: step-counter;
-    content: counter(step-counter);
-    position: absolute;
-    left: 0;
-    top: 0;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    height: 24px;
-    width: 24px;
-    border-radius: 9999px; /* Full circle */
-    border: 1px solid var(--astro-code-color-text); /* Border color */
-    background-color: var(--astro-code-color-background); /* Background color */
-    color: var(--astro-code-color-text); /* Text color */
-    font-size: 0.875rem; /* text-sm */
-    font-weight: 600; /* font-semibold */
-    z-index: 10;
-  }
-
-  /* Hide line for the last step */
-  .step-group .step-content:last-of-type::before {
-    display: none;
-  }
-
-  /* Ensure text and headings within the step start correctly */
-  .step-group .step-content > * {
-    flex-grow: 1;
-  }
-
-  /* Reset top margin for the first heading inside a step to align with the number */
-  .step-group .step-content :where(h1, h2, h3, h4, h5, h6):first-child {
-    margin-top: 0;
-  }
-
-  /* Adjust margins for content within a step */
-  .step-group .step-content :where(p, ul, ol, .code-block, .callout) {
-    margin-top: 0.5rem;
-    margin-bottom: 0.5rem;
-  }
-
-  /* Remove bottom margin for the last element within a step-content to avoid extra space */
-  .step-group .step-content > *:last-child {
-    margin-bottom: 0;
-  }
-</style>
diff --git a/src/lib/components/content/step-group/step.astro b/src/lib/components/content/step-group/step.astro
index 58a5a0b..28e1f63 100644
--- a/src/lib/components/content/step-group/step.astro
+++ b/src/lib/components/content/step-group/step.astro
@@ -1,7 +1,49 @@
 ---
+import { cn } from "@/utils";
 
+type Props = {
+  title?: string;
+  class?: string;
+};
+const { title, class: className } = Astro.props;
 ---
 
-<div class="step-content">
-  <slot />
+<div class={cn("step relative flex gap-6 pb-8 last:pb-0", className)}>
+  <div
+    class="step-line absolute left-4 top-0 h-full w-px bg-border -translate-x-1/2"
+    aria-hidden="true"
+  >
+  </div>
+  <div
+    class="step-number relative z-10 flex items-center justify-center size-8 bg-secondary rounded-full border border-border text-sm font-semibold text-foreground shrink-0"
+  >
+  </div>
+  <div class="flex-1 min-w-0">
+    {
+      title && (
+        <h3 class="text-lg font-semibold !mt-0 pt-0 mb-3 leading-none text-foreground">
+          {title}
+        </h3>
+      )
+    }
+    <div class="step-content text-muted-foreground [&>p:first-child]:!pt-0">
+      <slot />
+    </div>
+  </div>
 </div>
+
+<style is:global>
+  .step-group {
+    counter-reset: step;
+  }
+</style>
+
+<style>
+  .step {
+    counter-increment: step;
+  }
+
+  .step-number::after {
+    content: counter(step);
+  }
+</style>