@pnx-mixtape/mxds 0.0.29 → 0.1.0-rc.0

package/src/Component/SocialShare/README.md

@@ -0,0 +1,171 @@
+# SocialShare
+
+A row of "share this page" buttons that open the current URL in a social network's share intent (Facebook, LinkedIn, X/Twitter, Bluesky, email). Use this on articles, news items, or any page you want readers to distribute. For outbound links to your own profiles, use [SocialLinks](../SocialLinks/README.md) instead.
+
+## CSS Import
+
+`SocialShare` ships a small stylesheet for standalone layout (flex row + gap). Import it alongside the core CSS (icons, links, buttons):
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/SocialShare/social-share.css";
+```
+
+When nested inside `UtilityList`, additional layout comes from `utility-list.css`.
+
+---
+
+## Twig
+
+The Twig implementation wraps a configurable set of share links in a single `<nav>`. Pass each platform's fully-formed share URL as a prop — empty/omitted props render no link for that platform.
+
+```twig
+{% include '@mixtape/Component/SocialShare/social-share.twig' with {
+  twitter: 'https://twitter.com/intent/tweet?url=' ~ page_url,
+  facebook: 'https://www.facebook.com/sharer.php?u=' ~ page_url,
+  linkedin: 'https://www.linkedin.com/shareArticle?url=' ~ page_url,
+  bluesky: 'https://bsky.app/intent/compose?text=' ~ page_text,
+  email: 'mailto:?subject=' ~ page_title ~ '&body=' ~ page_url,
+} %}
+```
+
+**social-share.twig props** (`SocialShare` type from `ids-shape`):
+
+| Prop       | Type     | Required | Description                                |
+| ---------- | -------- | -------- | ------------------------------------------ |
+| `twitter`  | `string` | No       | Full X/Twitter share-intent URL            |
+| `bluesky`  | `string` | No       | Full Bluesky compose-intent URL            |
+| `facebook` | `string` | No       | Full Facebook sharer URL                   |
+| `linkedin` | `string` | No       | Full LinkedIn share URL                    |
+| `email`    | `string` | No       | A `mailto:` URL with optional subject/body |
+
+Render order in the output is: **bluesky, twitter, linkedin, facebook, email**.
+
+> **Parity note:** the Twig template supports `bluesky` and `email` in addition to the three platforms supported by React. If you need Bluesky or email share in a React app, compose a plain anchor using the same `mx-link mx-icon mx-icon--only mx-icon--<platform>` classes.
+
+---
+
+## HTML
+
+A single share button is a `mx-link` with icon-only styling pointing at the share-intent URL. Open in a new tab.
+
+```html
+<nav class="mx-social-share flex gap--s" aria-label="Social share buttons">
+  <a
+    class="mx-link mx-icon mx-icon--only mx-icon--twitter"
+    href="https://twitter.com/intent/tweet?url=https%3A%2F%2Fexample.com"
+    target="_blank"
+    rel="noopener noreferrer"
+  >
+    Share to X (Twitter)
+  </a>
+  <a
+    class="mx-link mx-icon mx-icon--only mx-icon--facebook"
+    href="https://www.facebook.com/sharer.php?u=https%3A%2F%2Fexample.com"
+    target="_blank"
+    rel="noopener noreferrer"
+  >
+    Share to Facebook
+  </a>
+</nav>
+```
+
+The visible link text ("Share to Facebook") is the accessible label — visually hidden by the `mx-icon--only` modifier but read by screen readers.
+
+---
+
+## React
+
+The React implementation renders a single share button — compose multiple `<SocialShare />` calls to produce a row.
+
+```tsx
+import { SocialShare } from "@pnx-mixtape/mxds/react"
+import { SocialShareTypes } from "@pnx-mixtape/mxds/src/enums"
+
+// Share the current page
+<SocialShare type={SocialShareTypes.FACEBOOK} />
+
+// Share a specific URL with custom text (used for Twitter/X tweet body)
+<SocialShare
+  type={SocialShareTypes.TWITTER}
+  shareUrl="https://previousnext.com.au/article"
+  text="Check out this article"
+/>
+
+// A row of share buttons
+<nav aria-label="Share this page" className="flex gap--s">
+  <SocialShare type={SocialShareTypes.FACEBOOK} />
+  <SocialShare type={SocialShareTypes.TWITTER} text="Hello World!!" />
+  <SocialShare type={SocialShareTypes.LINKEDIN} />
+</nav>
+```
+
+Clicking a button opens a popup window (600×480) at the network's share intent URL.
+
+**`SocialShare` props:**
+
+| Prop       | Type               | Default                | Description                                                  |
+| ---------- | ------------------ | ---------------------- | ------------------------------------------------------------ |
+| `type`     | `SocialShareTypes` | —                      | Required. One of `TWITTER`, `FACEBOOK`, `LINKEDIN`           |
+| `shareUrl` | `string`           | `window.location.href` | URL to share. Invalid URLs fall back to the current page URL |
+| `text`     | `string`           | `""`                   | Pre-filled text — only used for Twitter/X                    |
+
+The React `SocialShareTypes` enum currently supports three values:
+
+| Enum value                  | String       |
+| --------------------------- | ------------ |
+| `SocialShareTypes.TWITTER`  | `"twitter"`  |
+| `SocialShareTypes.FACEBOOK` | `"facebook"` |
+| `SocialShareTypes.LINKEDIN` | `"linkedin"` |
+
+---
+
+### React ⇄ Twig parity
+
+| Feature                       | React                                     | Twig                   |
+| ----------------------------- | ----------------------------------------- | ---------------------- |
+| Twitter / Facebook / LinkedIn | ✅                                        | ✅                     |
+| Bluesky                       | ❌ — not in `SocialShareTypes` enum       | ✅ (`bluesky: string`) |
+| Email                         | ❌ — not in `SocialShareTypes` enum       | ✅ (`email: string`)   |
+| Button style override         | ❌ — `ButtonModifiers.DARK` is hard-coded | ❌ — no styling prop   |
+
+If you need Bluesky or email share from React, compose a plain anchor with `mx-link mx-icon mx-icon--only mx-icon--<platform>` classes until the enum and switch are extended.
+
+## Modifiers
+
+Neither the React nor the Twig component exposes a modifier API. Visual modifiers come from the atoms used underneath:
+
+| Class                          | Source                                  | Visual intent                                                                   |
+| ------------------------------ | --------------------------------------- | ------------------------------------------------------------------------------- |
+| `mx-icon--only` (Twig)         | `Link`/`Icon` atom                      | Hides the visible label, renders icon only                                      |
+| `mx-button--icon-only` (React) | `Button` atom                           | Same effect for the React `ButtonLink`                                          |
+| `mx-button--dark` (React)      | `ButtonModifiers.DARK` from `ids-shape` | Dark fill — hard-coded in the React `SocialShare` component                     |
+| `mx-icon--<platform>`          | `Icons` enum                            | Platform-specific glyph (`facebook`, `twitter`, `linkedin`, `bluesky`, `email`) |
+| `flex` + `gap--s`              | Layout utilities                        | Horizontal row with small gap — applied by the Twig wrapper                     |
+
+The React component hard-codes `ButtonModifiers.DARK` — there is no prop to change it. The Twig component has no styling modifier prop.
+
+---
+
+## Accessibility
+
+- Wrap a row of share buttons in a `<nav aria-label="Share this page">` (or similar) — the Twig template does this automatically with `aria-label="Social share buttons"`.
+- Each button is icon-only. The accessible name must come from either visible text (Twig: "Share to Facebook" hidden via `mx-icon--only`) or an `aria-label` / `sr-only` span. Never render a bare icon with no label.
+- Use `target="_blank" rel="noopener noreferrer"` (Twig template already does) — share-intent URLs should open in a new tab so the user doesn't lose their place on the article.
+- The React component opens a 600×480 popup via `window.open` on click — the `href` is still present, so middle-click and keyboard activation still work.
+
+---
+
+## Customisation via CSS custom properties
+
+`SocialShare` does not define its own custom properties. Styling is inherited from:
+
+- `.mx-link` / `.mx-icon` / `.mx-button` atoms — override their custom properties (e.g. `--link-colour`, `--button-background`) on an ancestor.
+- The `gap--s` utility — controlled by `--spacing-s`.
+
+Example, scoped to a dark surface:
+
+```css
+.mx-background--reverse .mx-social-share {
+  --link-colour: var(--colour-on-reverse);
+}
+```

package/src/Component/SocialShare/SocialShare.figma.ts

@@ -0,0 +1,21 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=66-380
+// source=src/Component/SocialShare/SocialShare.tsx
+// component=SocialShare
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const type = instance.getEnum("Type", {
+  Twitter: "SocialShareTypes.TWITTER",
+  Facebook: "SocialShareTypes.FACEBOOK",
+  LinkedIn: "SocialShareTypes.LINKEDIN",
+})
+
+export default {
+  example: figma.code`<SocialShare type={${type}} />`,
+  imports: ['import { SocialShare, SocialShareTypes } from "@pnx-mixtape/mxds/react"'],
+  id: "social-share",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/SocialShare/SocialShare.stories.ts

@@ -1,5 +1,6 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./social-share.twig"
+import "./social-share.css"
 import { SocialShare as SocialShareType } from "@pnx-mixtape/ids-shape"
 
 const meta: Meta<SocialShareType> = {

package/src/Component/SocialShare/SocialShare.stories.tsx

@@ -1,4 +1,5 @@
 import SocialShare from "./SocialShare"
+import "./social-share.css"
 import { Page } from "../../../.storybook-react/decorators"
 
 export default {

package/src/Component/SocialShare/SocialShare.tsx

@@ -2,6 +2,7 @@ import { JSX, useMemo } from "react"
 import { ButtonLink } from "../../Atom/Button/Button"
 import { Icons, SocialShareTypes } from "../../enums"
 import { ButtonModifiers } from "@pnx-mixtape/ids-shape"
+import { validators } from "../../Utility/utilities"
 
 type SocialShareProps = {
   type: SocialShareTypes
@@ -13,18 +14,43 @@ const twitterUrl: string = "https://twitter.com/intent/tweet/"
 const facebookUrl: string = "https://www.facebook.com/sharer/sharer.php"
 const linkedInUrl: string = "https://www.linkedin.com/sharing/share-offsite/"
 
+const BUTTON_MODIFIERS = [ButtonModifiers.DARK]
+
 const SocialShare = ({
   type,
   shareUrl = window.location.href,
   text = "",
 }: SocialShareProps): JSX.Element => {
+  // Validate shareUrl using validators.url
+  if (!validators.url(shareUrl)) {
+    if (process.env.NODE_ENV !== "production") console.error("Invalid share URL provided") // eslint-disable-line no-console
+    shareUrl = window.location.href
+  }
   const socialShareUrl: string = useMemo(() => {
-    if (type === SocialShareTypes.TWITTER)
-      return encodeURI(`${twitterUrl}?url=${shareUrl}&text=${text}`)
-    if (type === SocialShareTypes.FACEBOOK) return encodeURI(`${facebookUrl}?url=${shareUrl}`)
-    if (type === SocialShareTypes.LINKEDIN) return encodeURI(`${linkedInUrl}/?url=${shareUrl}`)
+    if (type === SocialShareTypes.TWITTER) {
+      const url = new URL(twitterUrl)
+      url.search = new URLSearchParams({
+        url: shareUrl,
+        text: text,
+      }).toString()
+      return url.toString()
+    }
+    if (type === SocialShareTypes.FACEBOOK) {
+      const url = new URL(facebookUrl)
+      url.search = new URLSearchParams({
+        u: shareUrl,
+      }).toString()
+      return url.toString()
+    }
+    if (type === SocialShareTypes.LINKEDIN) {
+      const url = new URL(linkedInUrl)
+      url.search = new URLSearchParams({
+        url: shareUrl,
+      }).toString()
+      return url.toString()
+    }
     return ""
-  }, [type])
+  }, [type, text, shareUrl])
 
   const socialIcon: Icons = useMemo(() => {
     if (type === SocialShareTypes.TWITTER) return Icons.TWITTER
@@ -36,8 +62,8 @@ const SocialShare = ({
   return (
     <ButtonLink
       iconOnly
-      icon={socialIcon}
-      modifiers={[ButtonModifiers.DARK]}
+      iconStart={socialIcon}
+      modifiers={BUTTON_MODIFIERS}
       to={socialShareUrl}
       onClick={() => {
         window.open(socialShareUrl, "popup", "width=600,height=480")

package/src/Component/SocialShare/__snapshots__/SocialShare.stories.ts.snap

@@ -4,19 +4,19 @@ exports[`Social Share 1`] = `
 "
 <nav class="mx-social-share flex gap--s" aria-label="Social share buttons">
   
-      <a class="mx-link mx-icon mx-icon--only mx-icon--bluesky" href="https://bsky.app/intent/compose" target="_blank">
+      <a class="mx-link mx-icon mx-icon--only mx-icon--bluesky" href="https://bsky.app/intent/compose" target="_blank" rel="noopener noreferrer">
       Share to Bluesky
     </a>
-        <a class="mx-link mx-icon mx-icon--only mx-icon--twitter" href="https://twitter.com/intent/tweet" target="_blank">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--twitter" href="https://twitter.com/intent/tweet" target="_blank" rel="noopener noreferrer">
       Share to X (Twitter)
     </a>
-        <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="https://www.linkedin.com/shareArticle" target="_blank">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="https://www.linkedin.com/shareArticle" target="_blank" rel="noopener noreferrer">
       Share to LinkedIn
     </a>
-        <a class="mx-link mx-icon mx-icon--only mx-icon--facebook" href="https://www.facebook.com/sharer.php" target="_blank">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--facebook" href="https://www.facebook.com/sharer.php" target="_blank" rel="noopener noreferrer">
       Share to Facebook
     </a>
-        <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="mailto:" target="_blank">
+        <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="mailto:" target="_blank" rel="noopener noreferrer">
       Share via email
     </a>
   </nav>

package/src/Component/SocialShare/__snapshots__/SocialShare.stories.tsx.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Facebook 1`] = `"<a href="https://www.facebook.com/sharer/sharer.php?url=https://previousnext.com.au" class="mx-button mx-button--dark mx-button--icon-only mx-icon mx-icon--facebook">Share on facebook</a>"`;
+exports[`Facebook 1`] = `"<a href="https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fpreviousnext.com.au" class="mx-button mx-button--dark mx-button--icon-only"><span class="mx-icon mx-icon--facebook"></span>Share on facebook</a>"`;
 
-exports[`Linked In 1`] = `"<a href="https://www.linkedin.com/sharing/share-offsite//?url=https://previousnext.com.au" class="mx-button mx-button--dark mx-button--icon-only mx-icon mx-icon--linkedin">Share on linkedin</a>"`;
+exports[`Linked In 1`] = `"<a href="https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fpreviousnext.com.au" class="mx-button mx-button--dark mx-button--icon-only"><span class="mx-icon mx-icon--linkedin"></span>Share on linkedin</a>"`;
 
-exports[`Twitter 1`] = `"<a href="https://twitter.com/intent/tweet/?url=https://previousnext.com.au&amp;text=Hello%20World!!" class="mx-button mx-button--dark mx-button--icon-only mx-icon mx-icon--twitter">Share on twitter</a>"`;
+exports[`Twitter 1`] = `"<a href="https://twitter.com/intent/tweet/?url=https%3A%2F%2Fpreviousnext.com.au&amp;text=Hello+World%21%21" class="mx-button mx-button--dark mx-button--icon-only"><span class="mx-icon mx-icon--twitter"></span>Share on twitter</a>"`;

package/src/Component/SocialShare/social-share.css

@@ -0,0 +1,19 @@
+/**
+ * Social Share
+ *
+ * Base styling so `.mx-social-share` renders correctly when used standalone,
+ * not only when nested inside `.mx-utility-list__share`.
+ */
+
+@layer design-system.components {
+  .mx-social-share {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--social-share-gap, var(--spacing-s));
+
+    & a[href] {
+      --link-colour: var(--social-share-link-colour, var(--colour-link));
+    }
+  }
+}

package/src/Component/SocialShare/social-share.twig

@@ -8,27 +8,27 @@
 <nav{{ attributes }} aria-label="Social share buttons">
   {{ title }}
   {% if bluesky is not empty %}
-    <a class="mx-link mx-icon mx-icon--only mx-icon--bluesky" href="{{ bluesky }}" target="_blank">
+    <a class="mx-link mx-icon mx-icon--only mx-icon--bluesky" href="{{ bluesky }}" target="_blank" rel="noopener noreferrer">
       Share to Bluesky
     </a>
   {% endif %}
   {% if twitter is not empty %}
-    <a class="mx-link mx-icon mx-icon--only mx-icon--twitter" href="{{ twitter }}" target="_blank">
+    <a class="mx-link mx-icon mx-icon--only mx-icon--twitter" href="{{ twitter }}" target="_blank" rel="noopener noreferrer">
       Share to X (Twitter)
     </a>
   {% endif %}
   {% if linkedin is not empty %}
-    <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="{{ linkedin }}" target="_blank">
+    <a class="mx-link mx-icon mx-icon--only mx-icon--linkedin" href="{{ linkedin }}" target="_blank" rel="noopener noreferrer">
       Share to LinkedIn
     </a>
   {% endif %}
   {% if facebook is not empty %}
-    <a class="mx-link mx-icon mx-icon--only mx-icon--facebook" href="{{ facebook }}" target="_blank">
+    <a class="mx-link mx-icon mx-icon--only mx-icon--facebook" href="{{ facebook }}" target="_blank" rel="noopener noreferrer">
       Share to Facebook
     </a>
   {% endif %}
   {% if email is not empty %}
-    <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="{{ email }}" target="_blank">
+    <a class="mx-link mx-icon mx-icon--only mx-icon--email" href="{{ email }}" target="_blank" rel="noopener noreferrer">
       Share via email
     </a>
   {% endif %}

package/src/Component/Steps/README.md

@@ -0,0 +1,179 @@
+# Steps
+
+A stepped-progress indicator — a vertically connected series of panels with numbered markers and a line joining them. Use for multi-step forms, tutorials, timelines, onboarding flows, and "how it works" explainers.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/Steps/steps.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/Steps/steps.twig' with {
+  modifiers: ['light'],
+  counters: true,
+  fill: false,
+  items: [
+    step_item_1,
+    step_item_2,
+    step_item_3,
+  ]
+} %}
+```
+
+**steps.twig props** (`Steps` type from `ids-shape`):
+
+| Prop        | Type              | Description                                          |
+| ----------- | ----------------- | ---------------------------------------------------- |
+| `items`     | `StepItem[]`      | List of rendered step item strings                   |
+| `modifiers` | `StepsModifier[]` | Colour variants — see table below                    |
+| `fill`      | `boolean`         | Fills every marker with a solid colour               |
+| `counters`  | `boolean`         | Makes the numeric counter inside each marker visible |
+
+**step-item.twig props** (`StepItem` type from `ids-shape`):
+
+| Prop      | Type          | Description                                                                                                                                                                           |
+| --------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `content` | `WysiwygText` | Step content (HTML) — first heading should be an `<h2>`, `<h3>`, or `<h4>` (marker offset auto-adjusts)                                                                               |
+| `status`  | `boolean`     | Fills this individual marker — combine with `counters` to indicate current / completed steps                                                                                          |
+| `current` | `boolean`     | Adds `aria-current="step"` to the `<li>`. Use on the active step in a multi-step flow. Not yet on the `StepItem` shape type — see [ComponentIssues](../../../docs/ComponentIssues.md) |
+
+---
+
+## HTML
+
+Minimal working markup — the wrapper is an `<ol>` and each step is an `<li class="mx-steps__panel">` holding a `<div class="mx-steps__panel-content">`. Numbering is generated automatically via CSS counters.
+
+```html
+<ol class="mx-steps mx-steps--light">
+  <li class="mx-steps__panel">
+    <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
+      <h2>Step one</h2>
+      <p>Describe the first step.</p>
+    </div>
+  </li>
+  <li class="mx-steps__panel">
+    <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
+      <h2>Step two</h2>
+      <p>Describe the second step.</p>
+    </div>
+  </li>
+  <li class="mx-steps__panel">
+    <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
+      <h2>Step three</h2>
+      <p>Describe the third step.</p>
+    </div>
+  </li>
+</ol>
+```
+
+### With visible counters
+
+Add `mx-steps--counters` to the wrapper to reveal the numbered badge inside each marker.
+
+```html
+<ol class="mx-steps mx-steps--light mx-steps--counters">
+  <li class="mx-steps__panel">...</li>
+  <li class="mx-steps__panel">...</li>
+  <li class="mx-steps__panel">...</li>
+</ol>
+```
+
+### Highlighting progress (current, completed, upcoming)
+
+Add `mx-steps--fill` to an individual `mx-steps__panel` to fill its marker — combine with counters to show progress. Completed and current steps are filled; upcoming steps remain unfilled. Add `aria-current="step"` to the active step so assistive tech announces it.
+
+```html
+<ol class="mx-steps mx-steps--dark mx-steps--counters">
+  <!-- Completed -->
+  <li class="mx-steps__panel mx-steps--fill">
+    <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
+      <h2>Account details</h2>
+      <p>Saved.</p>
+    </div>
+  </li>
+  <!-- Current -->
+  <li class="mx-steps__panel mx-steps--fill" aria-current="step">
+    <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
+      <h2>Payment</h2>
+      <p>Enter your card details.</p>
+    </div>
+  </li>
+  <!-- Upcoming -->
+  <li class="mx-steps__panel">
+    <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
+      <h2>Confirmation</h2>
+      <p>Review and submit.</p>
+    </div>
+  </li>
+</ol>
+```
+
+### Fill all markers
+
+Apply `mx-steps--fill` to the wrapper to fill every marker at once.
+
+```html
+<ol class="mx-steps mx-steps--light mx-steps--fill">
+  <li class="mx-steps__panel">...</li>
+  <li class="mx-steps__panel">...</li>
+</ol>
+```
+
+---
+
+## React
+
+This component does not ship a React implementation. Use the Twig template, or author the HTML directly and apply the class names listed below.
+
+---
+
+## Modifiers (`StepsModifier` enum from `ids-shape`)
+
+The `modifiers` array on the Twig component maps to these classes on `.mx-steps`. The enum has three values:
+
+| Class                     | `StepsModifier` value | Visual intent                                                                                                                               |
+| ------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mx-steps--light`         | `light`               | Neutral border colour — default, low-emphasis. No dedicated CSS: this is the base appearance (the class is a no-op marker for the default). |
+| `mx-steps--dark`          | `dark`                | Brand primary line & counter scheme                                                                                                         |
+| `mx-steps--supplementary` | `supplementary`       | Brand accent line & counter scheme                                                                                                          |
+
+Additional (non-enum) state classes applied at the wrapper or panel level:
+
+| Class                | Applied via                | Effect                                                                                |
+| -------------------- | -------------------------- | ------------------------------------------------------------------------------------- |
+| `mx-steps--counters` | `counters: true` on Steps  | Reveals the number inside every marker                                                |
+| `mx-steps--fill`     | `fill: true` on Steps      | Fills every marker with the line colour                                               |
+| `mx-steps--fill`     | `status: true` on StepItem | Fills only that panel's marker — the composable way to show current / completed steps |
+
+---
+
+## Accessibility
+
+- The wrapper renders as `<ol>` and each step as `<li>`, so the order is exposed to assistive tech as a numbered list.
+- Mark the active step with `aria-current="step"` (Twig: `current: true`) on the panel so screen readers announce which step the user is on.
+- The numeric marker is produced by a CSS counter on the `::after` pseudo-element — it is decorative and not exposed to assistive tech. Always include the step title and content as real text so screen readers can announce each step; never rely on the visual number alone.
+- The connecting line is drawn with `::before` on `mx-steps__panel-content` and is purely decorative.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-steps {
+  --line-width: 2px; /* thickness of the connecting line and marker border */
+  --line-colour: var(--colour-border); /* colour of the line and marker outline */
+  --background: var(--colour-background); /* marker fill when unfilled */
+  --foreground: inherit; /* counter text colour when filled */
+  --counter-size: 2rem; /* diameter of each marker */
+  --counter-top: 0; /* vertical offset of marker (auto-adjusts for h3/h4) */
+  --counter-scheme: var(--colour-scheme); /* colour-scheme for the counter digit */
+  --counter-visibility: hidden; /* toggled to visible by .mx-steps--counters */
+  --indent: var(--spacing-xxl); /* left padding of content from the marker/line */
+  --spacing: var(--spacing-l); /* vertical gap below each panel */
+}
+```

package/src/Component/Steps/StepItem.stories.ts

@@ -7,7 +7,7 @@ import { StepItem as StepsItemType } from "@pnx-mixtape/ids-shape"
  * An individual Steps item, design to be used in its parent context.
  */
 const meta: Meta<StepsItemType> = {
-  tags: ["autodocs", "ids-mvp"],
+  tags: ["autodocs", "ids-mvp", "no-snapshot"],
   component: Component,
   args: {
     content:
@@ -34,6 +34,9 @@ const meta: Meta<StepsItemType> = {
       },
     },
   },
+  render: args => {
+    return `<ol class="mx-steps">${Component({ ...args })}</ol>`
+  },
 }
 
 export default meta

package/src/Component/Steps/Steps.stories.ts

@@ -27,7 +27,7 @@ const meta: Meta<StepsType> = {
         content:
           "<h4>Motown</h4><p>Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>",
       }),
-    ],
+    ].join(""),
   },
   argTypes: {
     modifiers: {
@@ -55,14 +55,14 @@ const meta: Meta<StepsType> = {
     },
     items: {
       description:
-        "A list of [StepItem](/?path=/docs/component-steps-stepitem--docs) objects, where `status` fills in it's individual marker only.",
+        "A concatenated string of [StepItem](/?path=/docs/component-steps-stepitem--docs) markup, where `status` fills in it's individual marker only.",
       type: {
         name: "other",
         required: true,
-        value: "array",
+        value: "string",
       },
       table: {
-        type: { summary: "StepItem[]" },
+        type: { summary: "string" },
       },
     },
   },
@@ -110,7 +110,7 @@ export const Highlighted: Story = {
         content:
           "Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.",
       }),
-    ],
+    ].join(""),
   },
 }
 
@@ -135,7 +135,7 @@ export const Progress: Story = {
         content:
           "Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.",
       }),
-    ],
+    ].join(""),
   },
 }
 

package/src/Component/Steps/__snapshots__/StepItem.stories.ts.snap

@@ -1,19 +1,19 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`Filled 1`] = `
-"<div class="mx-steps__panel mx-steps--fill">
+"<li class="mx-steps__panel mx-steps--fill">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h2>Funk</h2><p>Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>
   </div>
-</div>
+</li>
 "
 `;
 
 exports[`Step Item 1`] = `
-"<div class="mx-steps__panel">
+"<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h2>Funk</h2><p>Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>
   </div>
-</div>
+</li>
 "
 `;