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

package/src/Component/Accordion/Components/AccordionTitle.figma.ts

@@ -0,0 +1,28 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=50-102
+// source=src/Component/Accordion/Components/AccordionTitle.tsx
+// component=AccordionTitle
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const content = instance.getSlot("Content")
+
+const icon = instance.findConnectedInstances(
+  node => node.codeConnectId() === "accordion-title-icon",
+)[0]
+const iconCode = icon ? icon.executeTemplate().example : figma.code`<AccordionTitleIcon />`
+
+// `headingLevel` (optional HeadingTypes) isn't modelled — no visual effect, wraps the
+// button in a heading tag purely for document-outline purposes. Open/Closed is
+// context-derived, not a prop — both variants render the same code.
+export default {
+  example: figma.code`<AccordionTitle>
+  ${content}
+  ${iconCode}
+</AccordionTitle>`,
+  imports: ['import { AccordionTitle } from "@pnx-mixtape/mxds/react"'],
+  id: "accordion-title",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Accordion/Components/AccordionTitle.tsx

@@ -7,7 +7,7 @@ type AccordionTitleProps = PropsWithChildren & {
 }
 
 const AccordionTitle = ({ children, headingLevel = null }: AccordionTitleProps): JSX.Element => {
-  const { id, on, toggle } = useAccordion()
+  const { id, isExpanded, toggle } = useAccordion()
   const Heading = headingLevel ? headingLevel : Fragment
 
   return (
@@ -16,11 +16,8 @@ const AccordionTitle = ({ children, headingLevel = null }: AccordionTitleProps):
         type="button"
         className="mx-accordion__toggle"
         id={id}
-        aria-expanded={on}
+        aria-expanded={isExpanded}
         onClick={() => toggle()}
-        onKeyDown={({ key }) => {
-          if (key === "Enter") toggle()
-        }}
       >
         {children}
       </button>

package/src/Component/Accordion/Components/AccordionTitleIcon.figma.ts

@@ -0,0 +1,16 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=50-11
+// source=src/Component/Accordion/Components/AccordionTitleIcon.tsx
+// component=AccordionTitleIcon
+import figma from "figma"
+
+// Open/Closed isn't a prop — it's derived entirely from the parent Accordion's
+// data-open state via CSS. No props to read; the Figma variant only demonstrates the
+// two visual states, both of which render identical code.
+export default {
+  example: figma.code`<AccordionTitleIcon />`,
+  imports: ['import { AccordionTitleIcon } from "@pnx-mixtape/mxds/react"'],
+  id: "accordion-title-icon",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Accordion/README.md

@@ -1,35 +1,187 @@
 # Accordion
 
-### How to use
+Collapsible content panels built on the native `<details>`/`<summary>` HTML elements. Supports anchor-based auto-opening, print expansion, "expand/collapse all", mobile-only collapse, and a div-based fallback.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Component/Accordion/accordion.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/Accordion/accordion.css";
+```
 
-**Twig**
+---
 
-You can setup a twig namespace in your project if you wish to use the twig files directly.
+## Twig
 
-- Eg: `{% extends '@mixtape/Component/Accordion/accordion.twig' %}`
+```twig
+{% include '@mixtape/Component/Accordion/accordion.twig' with {
+  title: heading_component,
+  toggleAll: true,
+  items: [
+    include('@mixtape/Component/Accordion/accordion-item.twig', {
+      id: 'section-1',
+      title: 'Section 1',
+      content: '<p>Section 1 content.</p>',
+      open: true,
+    }),
+    include('@mixtape/Component/Accordion/accordion-item.twig', {
+      id: 'section-2',
+      title: 'Section 2',
+      content: '<p>Section 2 content.</p>',
+    }),
+  ],
+} %}
+```
 
-Alternatively copy/paste the file for more control.
+**accordion.twig props** (`Accordion` type from `ids-shape`):
 
-**JSX Components**
+| Prop        | Type                              | Required | Description                                                                         |
+| ----------- | --------------------------------- | -------- | ----------------------------------------------------------------------------------- |
+| `items`     | `AccordionItem[]` \| `Collection` | Yes      | List of rendered accordion-item strings                                             |
+| `title`     | `Heading`                         | No       | Optional heading rendered above the accordion list                                  |
+| `toggleAll` | `boolean`                         | No       | Wraps the list in `<mx-accordion-group>` and adds Expand all / Collapse all buttons |
 
-JSX components are available for use with React.
+**accordion-item.twig props** (`AccordionItem` type from `ids-shape`):
 
-- JSX import: `import { Accordion } from '@pnx-mixtape/mxds/src/react';`
+| Prop         | Type          | Required | Description                                                                                            |
+| ------------ | ------------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `title`      | `string`      | Yes      | Toggle button label rendered inside `<summary>`                                                        |
+| `content`    | `WysiwygText` | Yes      | Panel content (HTML)                                                                                   |
+| `id`         | `string`      | No       | Used by the `<mx-accordion>` web component for URL hash auto-open                                      |
+| `open`       | `boolean`     | No       | Adds the native `open` attribute to `<details>` so the panel is expanded                               |
+| `attributes` | `Attribute`   | No       | Optional Drupal-style attributes object — `mx-accordion mx-accordion--divided` is always merged on top |
 
-**JS Custom Element**
+The item template always wraps its `<details>` in `<mx-accordion>` so the URL-hash open and print-expand behaviours work out of the box. Use `toggleAll: true` on the parent when you want Expand all / Collapse all controls.
 
-Custom Elements are self defined, simply import the desired feature.
-These do not use the Shadow DOM and are not typical Web Components.
-External CSS applies.
-No Polyfills or frameworks are required.
+---
 
-- AccordionBase import: `import '@pnx-mixtape/mxds/src/Component/Accordion/Elements/Accordion';` and be sure to include `<mx-accordion>` around the `<details />` tag.
-- AccordionMobile import: `import '@pnx-mixtape/mxds/src/Component/Accordion/Elements/AccordionMobile';` and be sure to include `<mx-accordionmobile>` around the `<details />` tag.
-- AccordionDiv import: `import '@nx-mixtape/Component/Accordion/Elements/AccordionDiv';` and be sure to include `<mx-accordiondiv class="accordion">` instead of the `<details />` tag.
-- AccordionGroup import: `import '@pnx-mixtape/mxds/src/Component/Accordion/Elements/AccordionGroup';` and be sure to include `<mx-accordion-group>` around the `<details />` tags.
+## HTML + Web Component
 
-See twig files for all HTML examples.
+The `<mx-accordion>` custom element enhances a native `<details>` element with:
+
+- Auto-opening when the URL hash matches the accordion `id`
+- Opening all accordions on `window.beforeprint`
+
+```html
+<mx-accordion>
+  <details class="mx-accordion mx-accordion--divided" id="my-section">
+    <summary class="mx-accordion__toggle">
+      Section title
+      <span
+        class="mx-button mx-icon mx-button--small mx-button--icon-only mx-icon--chevron-down"
+        aria-hidden="true"
+      ></span>
+    </summary>
+    <div class="mx-accordion__content mx-rich-text mx-vertical-flow">Content goes here.</div>
+  </details>
+</mx-accordion>
+```
+
+**Import the JS:**
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Accordion/Elements/Accordion"
+```
+
+## React
+
+Uses a Context-based composition pattern. Always use `AccordionTitle`, `AccordionTitleIcon`, and `AccordionContent` as children.
+
+```tsx
+import { Accordion, AccordionTitle, AccordionContent, AccordionTitleIcon } from "@pnx-mixtape/mxds/react"
+import { HeadingTypes } from "@pnx-mixtape/ids-shape"
+
+<Accordion>
+  <AccordionTitle>
+    Section title
+    <AccordionTitleIcon />
+  </AccordionTitle>
+  <AccordionContent>
+    Content goes here.
+  </AccordionContent>
+</Accordion>
+
+// With a semantic heading level wrapping the toggle button
+<Accordion active={true}>
+  <AccordionTitle headingLevel={HeadingTypes.TWO}>
+    Open by default
+    <AccordionTitleIcon />
+  </AccordionTitle>
+  <AccordionContent>
+    Content.
+  </AccordionContent>
+</Accordion>
+```
+
+**`Accordion` props:** `active?: boolean` (default open), `id?: string`
+
+**`AccordionTitle` props:** `headingLevel?: HeadingTypes` — wraps the toggle button in a heading element for correct document outline
+
+**`AccordionTitleIcon`** — renders the chevron button. Pass a custom `className` array to override its appearance.
+
+---
+
+## Variants & Web Component extensions
+
+### Default open
+
+Set `open` on the `<details>` element (HTML/Twig) or `active={true}` prop (React).
+
+### Expand all / Collapse all
+
+Wrap multiple accordions with `<mx-accordion-group>`. Requires `<button data-expand>` and `<button data-collapse>` inside the group. The Twig template handles this automatically when `toggleAll: true`.
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Accordion/Elements/AccordionGroup"
+```
+
+### Mobile-only (`<mx-accordionmobile>`)
+
+Collapses only below a breakpoint (default: `max-width: 720px`). Passes the `mq` attribute to customise the breakpoint. Used inside the Filters component.
+
+```html
+<mx-accordionmobile mq="(max-width: 540px)">
+  <details class="mx-accordion mx-accordion--divided">...</details>
+</mx-accordionmobile>
+```
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Accordion/Elements/AccordionMobile"
+```
+
+### Div-based (`<mx-accordiondiv>`)
+
+For cases where `<details>` cannot be used. Replicates disclosure behaviour using a `<button>` + `<div>` with `inert` attribute toggling. Avoid unless necessary.
+
+```html
+<mx-accordiondiv class="mx-accordion mx-accordion--divided" id="my-div-accordion">
+  <button type="button" class="mx-accordion__toggle">Title</button>
+  <div class="mx-accordion__content mx-rich-text mx-vertical-flow">Content</div>
+</mx-accordiondiv>
+```
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Accordion/Elements/AccordionDiv"
+```
+
+---
+
+## Accessibility
+
+- Built on native `<details>`/`<summary>` — keyboard and screen reader accessible by default
+- `AccordionContent` (React) uses `role="region"` with `aria-labelledby` pointing to the toggle button id
+- `AccordionTitle` (React) sets `aria-expanded` on the button
+- The chevron icon is `aria-hidden="true"` — never use it as the only visual indicator of state
+- URL hash support: if `window.location.hash` matches the accordion `id`, it opens automatically
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-accordion--divided {
+  --line-width: 2px;
+  --line-colour: var(--colour-primary);
+  --vertical-padding: var(--spacing-s);
+  --horizontal-padding: var(--spacing-m);
+}
+```

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

@@ -7,7 +7,7 @@ exports[`Accordion 1`] = `
 <h2>Accordion group</h2>
 
               </div>
-        
+    
 <mx-accordion>
   <details class="mx-accordion mx-accordion--divided" id="music">
     <summary class="mx-accordion__toggle">
@@ -20,7 +20,6 @@ exports[`Accordion 1`] = `
   </details>
 </mx-accordion>
 
-      
 <mx-accordion>
   <details class="mx-accordion mx-accordion--divided" id="performances">
     <summary class="mx-accordion__toggle">
@@ -33,7 +32,7 @@ exports[`Accordion 1`] = `
   </details>
 </mx-accordion>
 
-    </div>
+  </div>
 "
 `;
 
@@ -44,7 +43,7 @@ exports[`Default Open 1`] = `
 <h2>Accordion group</h2>
 
               </div>
-        
+    
 <mx-accordion>
   <details class="mx-accordion mx-accordion--divided" id="music">
     <summary class="mx-accordion__toggle">
@@ -57,9 +56,8 @@ exports[`Default Open 1`] = `
   </details>
 </mx-accordion>
 
-      
 <mx-accordion>
-  <details class="mx-accordion mx-accordion--divided" open="" id="performances-default-">
+  <details class="mx-accordion mx-accordion--divided" open="" id="performances-default">
     <summary class="mx-accordion__toggle">
       Performances (default open)
       <span class="mx-button mx-icon mx-button--small mx-button--icon-only mx-icon--chevron-down" aria-hidden="true"></span>
@@ -70,7 +68,48 @@ exports[`Default Open 1`] = `
   </details>
 </mx-accordion>
 
+  </div>
+"
+`;
+
+exports[`Test 1`] = `
+"<div class="mx-accordions">
+    <mx-accordion-group>
+            <div class="mx-accordion__title">
+        
+<h2>Accordion group</h2>
+
+                  <div class="mx-accordions__toggle-all">
+            <button data-expand="" class="mx-button mx-button--light mx-button--small" type="button">Expand all</button><button data-collapse="" class="mx-button mx-button--light mx-button--small" type="button" disabled="">Collapse all</button>
+          </div>
+              </div>
+    
+<mx-accordion>
+  <details class="mx-accordion mx-accordion--divided" id="music">
+    <summary class="mx-accordion__toggle">
+      Music
+      <span class="mx-button mx-icon mx-button--small mx-button--icon-only mx-icon--chevron-down" aria-hidden="true"></span>
+    </summary>
+    <div class="mx-accordion__content mx-rich-text mx-vertical-flow">
+      I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.
     </div>
+  </details>
+</mx-accordion>
+
+<mx-accordion>
+  <details class="mx-accordion mx-accordion--divided" id="performances">
+    <summary class="mx-accordion__toggle">
+      Performances
+      <span class="mx-button mx-icon mx-button--small mx-button--icon-only mx-icon--chevron-down" aria-hidden="true"></span>
+    </summary>
+    <div class="mx-accordion__content mx-rich-text mx-vertical-flow">
+      I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.
+    </div>
+  </details>
+</mx-accordion>
+
+    </mx-accordion-group>
+  </div>
 "
 `;
 
@@ -85,7 +124,7 @@ exports[`Toggle All 1`] = `
             <button data-expand="" class="mx-button mx-button--light mx-button--small" type="button">Expand all</button><button data-collapse="" class="mx-button mx-button--light mx-button--small" type="button" disabled="">Collapse all</button>
           </div>
               </div>
-        
+    
 <mx-accordion>
   <details class="mx-accordion mx-accordion--divided" id="music">
     <summary class="mx-accordion__toggle">
@@ -98,7 +137,6 @@ exports[`Toggle All 1`] = `
   </details>
 </mx-accordion>
 
-      
 <mx-accordion>
   <details class="mx-accordion mx-accordion--divided" id="performances">
     <summary class="mx-accordion__toggle">
@@ -111,7 +149,7 @@ exports[`Toggle All 1`] = `
   </details>
 </mx-accordion>
 
-      </mx-accordion-group>
+    </mx-accordion-group>
   </div>
 "
 `;

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

@@ -1,5 +1,5 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Accordion 1`] = `"<div class="mx-accordion mx-accordion--divided" data-open="false"><button type="button" class="mx-accordion__toggle" id="_r_0_" aria-expanded="false">Open me!<span class="mx-button mx-button--small mx-icon mx-button--icon-only mx-icon--chevron-down" aria-hidden="true"></span></button><div role="region" aria-labelledby="_r_0_" class="mx-accordion__content mx-rich-text mx-vertical-flow">I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</div></div>"`;
+exports[`Accordion 1`] = `"<div class="mx-accordion mx-accordion--divided" data-open="false"><button type="button" class="mx-accordion__toggle" id="_r_0_" aria-expanded="false">Open me!<span class="mx-button mx-button--small mx-icon mx-button--icon-only mx-icon--chevron-down" aria-hidden="true"></span></button><section aria-labelledby="_r_0_" class="mx-accordion__content mx-rich-text mx-vertical-flow" inert="">I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</section></div>"`;
 
-exports[`Heading Level 1`] = `"<div class="mx-accordion mx-accordion--divided" data-open="false"><h2><button type="button" class="mx-accordion__toggle" id="_r_1_" aria-expanded="false">Open me!<span class="mx-button mx-button--small mx-icon mx-button--icon-only mx-icon--chevron-down" aria-hidden="true"></span></button></h2><div role="region" aria-labelledby="_r_1_" class="mx-accordion__content mx-rich-text mx-vertical-flow">I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</div></div>"`;
+exports[`Heading Level 1`] = `"<div class="mx-accordion mx-accordion--divided" data-open="false"><h2><button type="button" class="mx-accordion__toggle" id="_r_1_" aria-expanded="false">Open me!<span class="mx-button mx-button--small mx-icon mx-button--icon-only mx-icon--chevron-down" aria-hidden="true"></span></button></h2><section aria-labelledby="_r_1_" class="mx-accordion__content mx-rich-text mx-vertical-flow" inert="">I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.</section></div>"`;

package/src/Component/Accordion/__snapshots__/AccordionItem.stories.ts.snap

@@ -22,7 +22,7 @@ exports[`Div 1`] = `
     Music
     <span class="mx-button mx-icon mx-button--small mx-button--icon-only mx-icon--chevron-down" aria-hidden="true"></span>
   </button>
-  <div class="mx-accordion__content mx-rich-text mx-vertical-flow" inert="" role="region">
+  <div class="mx-accordion__content mx-rich-text mx-vertical-flow" role="region" inert="">
     I'm baby air plant hashtag letterpress blue bottle. Cloud bread dreamcatcher everyday carry lumbersexual, iceland cardigan swag chicharrones lo-fi fanny pack affogato freegan XOXO shaman. Shoreditch cloud bread waistcoat tbh XOXO. Chillwave pour-over umami pug glossier health goth.
   </div>
 </mx-accordiondiv>

package/src/Component/Accordion/accordion.css

@@ -51,9 +51,10 @@
     & .mx-accordion__toggle {
       cursor: pointer;
       inline-size: 100%;
+      text-align: start;
     }
 
-    &:is(> h2, > h3, > h4, > h5, > h6) {
+    & > :is(h2, h3, h4, h5, h6) {
       all: unset;
     }
 
@@ -107,15 +108,3 @@
     }
   }
 }
-
-/**
- * Print stylesheet
- */
-
-@media print {
-  .mx-accordion {
-    & .mx-accordion__content {
-      display: block !important;
-    }
-  }
-}

package/src/Component/Accordion/accordion.twig

@@ -12,9 +12,7 @@
         {% endif %}
       </div>
   {% endif %}
-  {% for item in items %}
-    {{ item }}
-  {% endfor %}
+  {{ items }}
   {% if toggleAll %}
   </mx-accordion-group>
   {% endif %}

package/src/Component/Breadcrumb/Breadcrumb.figma.ts

@@ -0,0 +1,20 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=83-258
+// source=src/Component/Breadcrumb/Breadcrumb.tsx
+// component=Breadcrumb
+import figma from "figma"
+
+// `items` (NavigationItem[]) is a data-object array — Breadcrumb renders each item's
+// `title` as a real Link internally, so it's not slot-shaped despite being composed
+// of real Link instances in Figma. Fixed representative example.
+export default {
+  example: figma.code`<Breadcrumb items={[
+  { id: "1", to: "/", title: "Home" },
+  { id: "2", to: "/section", title: "Section" },
+  { id: "3", to: "/section/page", title: "Current page" },
+]} />`,
+  imports: ['import { Breadcrumb } from "@pnx-mixtape/mxds/react"'],
+  id: "breadcrumb",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Breadcrumb/Breadcrumb.tsx

@@ -11,18 +11,27 @@ type BreadcrumbProps = ComponentPropsWithoutRef<"nav"> & {
 
 const Breadcrumb = ({ items, title, className, ...props }: BreadcrumbProps): JSX.Element => (
   <nav
-    className={classNames("mx-nav", "mx-nav--breadcrumb", "mx-nav--inline", className)}
+    className={classNames("mx-nav", "mx-nav--breadcrumbs", "mx-nav--inline", className)}
     aria-label="You are here"
     {...props}
   >
     <ul>
       {items &&
-        items.map(item => (
-          <li key={item.id}>
-            <Link to={item.to}>{item.title}</Link>
-          </li>
-        ))}
-      {title && <li>{title}</li>}
+        items.map((item, idx) => {
+          const isCurrent = !title && idx === items.length - 1
+          return (
+            <li key={item.id}>
+              <Link to={item.to} {...(isCurrent ? { "aria-current": "page" } : {})}>
+                {item.title}
+              </Link>
+            </li>
+          )
+        })}
+      {title && (
+        <li>
+          <span aria-current="page">{title}</span>
+        </li>
+      )}
     </ul>
   </nav>
 )

package/src/Component/Breadcrumb/README.md

@@ -0,0 +1,148 @@
+# Breadcrumb
+
+Horizontal navigation trail showing the user's location within the site hierarchy. Use at the top of secondary-level pages to show ancestry back to the home page.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/Breadcrumb/breadcrumb.css";
+```
+
+The CSS also depends on the Navigation component styles (for base `.mx-nav` / `.mx-nav--inline` layout):
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/Navigation/navigation.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/Breadcrumb/breadcrumb.twig' with {
+  items: [
+    link_home,
+    link_about,
+    link_current,
+  ]
+} %}
+```
+
+Each item is expected to be a pre-rendered `Link` atom. Flag the last item's link with `current: true` so it gets `aria-current="page"`:
+
+```twig
+{% include '@mixtape/Atom/Link/link.twig' with {
+  title: 'Join the team',
+  href: '/jobs/join-the-team',
+  current: true,
+} %}
+```
+
+**breadcrumb.twig props** (`Breadcrumbs` type from `ids-shape`):
+
+| Prop         | Type                   | Description                                                               |
+| ------------ | ---------------------- | ------------------------------------------------------------------------- |
+| `items`      | `Link[] \| Collection` | Pre-rendered list of Link atoms; the last one should pass `current: true` |
+| `attributes` | `Attribute`            | Optional attributes object; classes are merged onto the `<nav>`           |
+
+---
+
+## HTML
+
+Minimal working markup:
+
+```html
+<nav class="mx-nav mx-nav--inline mx-nav--breadcrumbs" aria-label="You are here">
+  <ul>
+    <li>
+      <a class="mx-link" href="/">Home</a>
+    </li>
+    <li>
+      <a class="mx-link" href="/about">About</a>
+    </li>
+    <li>
+      <a class="mx-link" href="/about/contact" aria-current="page">Contact</a>
+    </li>
+  </ul>
+</nav>
+```
+
+The chevron separators between items are rendered via CSS (`::after` on each `<li>` except the last) — do not add separator characters in markup.
+
+---
+
+## React
+
+```tsx
+import { Breadcrumb } from "@pnx-mixtape/mxds/react"
+
+<Breadcrumb
+  items={[
+    { id: "1", title: "Home", to: "/" },
+    { id: "2", title: "About", to: "/about" },
+    { id: "3", title: "Contact", to: "/about/contact" },
+  ]}
+  title="Current page title"
+/>
+
+// Without a trailing current-page label (last link is the current page)
+<Breadcrumb
+  items={[
+    { id: "1", title: "Home", to: "/" },
+    { id: "2", title: "About", to: "/about" },
+  ]}
+/>
+```
+
+**`Breadcrumb` props:**
+
+| Prop        | Type               | Default | Description                                                                                |
+| ----------- | ------------------ | ------- | ------------------------------------------------------------------------------------------ |
+| `items`     | `NavigationItem[]` | —       | Ordered ancestry links, rendered as `<a>` inside `<li>`                                    |
+| `title`     | `string`           | —       | Optional plain-text label for the current page, rendered as a trailing `<li>` with no link |
+| `className` | `string`           | —       | Extra class on the outer `<nav>`                                                           |
+
+The component also spreads any additional `<nav>` attributes onto the wrapper.
+
+**`NavigationItem` shape** (from `@pnx-mixtape/mxds/src/Component/Navigation/Navigation`):
+
+| Field   | Type     | Description                  |
+| ------- | -------- | ---------------------------- |
+| `id`    | `string` | Unique key for the list item |
+| `title` | `string` | Visible link text            |
+| `to`    | `string` | Link destination             |
+
+---
+
+## Accessibility
+
+- The wrapper is a `<nav>` landmark with `aria-label="You are here"`. This label is hard-coded in both the React and Twig templates — screen readers announce the region as a distinct landmark separate from primary site navigation.
+- The current page is marked with `aria-current="page"`:
+  - **Twig/HTML**: set `current: true` on the last `Link` atom, which outputs `aria-current="page"` on the `<a>`.
+  - **React**: the component does not currently set `aria-current` — the last segment is rendered as a plain `<li>` via the separate `title` prop. If you need `aria-current="page"` on a real anchor, render markup directly rather than via the React component.
+- CSS sets `pointer-events: none` on any element matching `[aria-current="page"]`, making the current-page link non-clickable without needing to conditionally render it.
+- Chevron separators are generated via CSS `::after` with a mask image — they are decorative, never announced, and never part of the accessibility tree.
+- The list uses native `<ul>`/`<li>`, so assistive tech reliably announces the number of trail items.
+- Keyboard behaviour: each link is a native anchor and receives focus in source order; no custom keyboard handling is required or added.
+- RTL: the chevron is rotated 180deg automatically when the ancestor has `dir="rtl"` or the `.translated-rtl` class (set by Google Translate).
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-nav--breadcrumbs {
+  --nav-font-size: var(--font-size-s); /* text size for the trail */
+  --breadcrumb-gap: var(--spacing-xxxxs); /* gap between list items */
+  --breadcrumb-foreground: var(
+    --foreground,
+    var(--colour-foreground-alt)
+  ); /* text + separator colour */
+}
+```
+
+The component also reads `--outline-size` (for focus-outline clearance padding) and the chevron uses `--spacing-m` for its icon size — both inherited from the design system tokens.
+
+---
+
+→ Used in context: `mockups/ArticleListingPage.stories.ts:5`