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

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

@@ -0,0 +1,9 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Default 1`] = `"<div class="mx-carousel" role="region" aria-roledescription="carousel" id="_r_0_"><div class="mx-carousel__buttons" role="group" aria-label="Quick page controls"><button class="mx-button mx-button--icon-only mx-carousel__prev" type="button" disabled=""><span class="sr-only">previous page</span><span class="mx-icon mx-icon--chevron-left" aria-hidden="true"></span></button><button class="mx-button mx-button--icon-only mx-carousel__next" type="button"><span class="sr-only">next page</span><span class="mx-icon mx-icon--chevron-right" aria-hidden="true"></span></button></div><ul class="mx-carousel__scrollable" aria-live="off" tabindex="0"><li data-index="0" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-1">Tile 1</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="1" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-2">Tile 2</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="2" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-3">Tile 3</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="3" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-4">Tile 4</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="4" aria-hidden="true" inert=""><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-5">Tile 5</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="5" aria-hidden="true" inert=""><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-6">Tile 6</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li></ul></div>"`;
+
+exports[`With Counter 1`] = `"<div class="mx-carousel" role="region" aria-roledescription="carousel" id="_r_2_"><div class="mx-carousel__buttons" role="group" aria-label="Quick page controls"><button class="mx-button mx-button--icon-only mx-carousel__prev" type="button" disabled=""><span class="sr-only">previous page</span><span class="mx-icon mx-icon--chevron-left" aria-hidden="true"></span></button><button class="mx-button mx-button--icon-only mx-carousel__next" type="button"><span class="sr-only">next page</span><span class="mx-icon mx-icon--chevron-right" aria-hidden="true"></span></button></div><ul class="mx-carousel__scrollable" aria-live="off" tabindex="0"><li data-index="0" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-1">Tile 1</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="1" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-2">Tile 2</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="2" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-3">Tile 3</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="3" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-4">Tile 4</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="4" aria-hidden="true" inert=""><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-5">Tile 5</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="5" aria-hidden="true" inert=""><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-6">Tile 6</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li></ul><div class="mx-carousel__pagination" data-pagination="counter" role="group" aria-label="Page controls"><button type="button" data-index="0" aria-label="Page 1" disabled="" aria-current="page">1</button><button type="button" data-index="1" aria-label="Page 2">2</button></div></div>"`;
+
+exports[`With Loop 1`] = `"<div class="mx-carousel" role="region" aria-roledescription="carousel" id="_r_3_"><div class="mx-carousel__buttons" role="group" aria-label="Quick page controls"><button class="mx-button mx-button--icon-only mx-carousel__prev" type="button" disabled=""><span class="sr-only">previous page</span><span class="mx-icon mx-icon--chevron-left" aria-hidden="true"></span></button><button class="mx-button mx-button--icon-only mx-carousel__next" type="button"><span class="sr-only">next page</span><span class="mx-icon mx-icon--chevron-right" aria-hidden="true"></span></button></div><ul class="mx-carousel__scrollable" aria-live="off" tabindex="0"><li data-index="0" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-1">Tile 1</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="1" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-2">Tile 2</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="2" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-3">Tile 3</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="3" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-4">Tile 4</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="4" aria-hidden="true" inert=""><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-5">Tile 5</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="5" aria-hidden="true" inert=""><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-6">Tile 6</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li></ul></div>"`;
+
+exports[`With Pagination 1`] = `"<div class="mx-carousel" role="region" aria-roledescription="carousel" id="_r_1_"><div class="mx-carousel__buttons" role="group" aria-label="Quick page controls"><button class="mx-button mx-button--icon-only mx-carousel__prev" type="button" disabled=""><span class="sr-only">previous page</span><span class="mx-icon mx-icon--chevron-left" aria-hidden="true"></span></button><button class="mx-button mx-button--icon-only mx-carousel__next" type="button"><span class="sr-only">next page</span><span class="mx-icon mx-icon--chevron-right" aria-hidden="true"></span></button></div><ul class="mx-carousel__scrollable" aria-live="off" tabindex="0"><li data-index="0" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-1">Tile 1</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="1" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-2">Tile 2</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="2" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-3">Tile 3</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="3" aria-hidden="false"><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-4">Tile 4</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="4" aria-hidden="true" inert=""><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-5">Tile 5</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li><li data-index="5" aria-hidden="true" inert=""><div class="mx-container"><article class="mx-card mx-card--block mx-background--box"><div class="mx-card__content mx-vertical-flow-flex"><h3 class="" id="tile-6">Tile 6</h3><p class="mx-text--lede">Tiles are just block cards without an image.</p><a href="#" class="mx-link mx-link--more">Find out more</a></div></article></div></li></ul><div class="mx-carousel__pagination" data-pagination="pagination" role="group" aria-label="Page controls"><button type="button" data-index="0" aria-label="Page 1" disabled="" aria-current="page">1</button><button type="button" data-index="1" aria-label="Page 2">2</button></div></div>"`;

package/src/Component/Carousel/carousel.css

@@ -10,8 +10,11 @@
 
   .mx-carousel__scrollable {
     list-style: none;
-    padding-inline: 0;
-    scroll-padding-inline: var(--outline-size, 2px);
+    padding-inline: calc(var(--outline-size, 2px) * 2);
+    padding-block: calc(var(--outline-size, 2px) * 2);
+    margin-inline: calc(var(--outline-size, 2px) * -2);
+    margin-block: calc(var(--outline-size, 2px) * -2);
+    scroll-padding-inline: calc(var(--outline-size, 2px) * 2);
     display: grid;
     gap: var(--horizontal-gap, var(--gap));
     grid-auto-flow: column;
@@ -23,7 +26,7 @@
     scrollbar-color: var(--scrollbar-color, var(--line-colour, var(--colour-border)) transparent);
     scrollbar-width: thin;
 
-    & > li {
+    & > [data-index] {
       display: grid;
       scroll-snap-align: start;
       scroll-snap-stop: always;
@@ -32,6 +35,7 @@
         opacity: 0.3;
       }
 
+      &.mx-container,
       & .mx-container {
         inline-size: 100%;
         display: grid;
@@ -92,6 +96,15 @@
 
         cursor: not-allowed;
       }
+
+      @media (pointer: coarse) {
+        transition: scale 0.1s linear;
+
+        &:active {
+          scale: 1.5;
+          border-color: var(--outline-color, currentcolor);
+        }
+      }
     }
   }
 }

package/src/Component/Carousel/carousel.twig

@@ -2,25 +2,24 @@
   'mx-carousel',
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
+{% set paginated = pagination or counter %}
 
-<mx-carousel{{ attributes }} role="group" {% if loop %} loop{% endif %}>
-  <div class="mx-carousel__buttons" data-buttons hidden>
+<mx-carousel{{ attributes }} role="region" aria-roledescription="carousel" {% if loop %} loop{% endif %}>
+  <div class="mx-carousel__buttons" data-buttons hidden role="group" aria-label="Quick page controls">
     <button class="mx-carousel__prev mx-button mx-button--icon-only" type="button">
-      <span class="sr-only">previous</span>
+      <span class="sr-only">previous page</span>
       <span class="mx-icon mx-icon--chevron-left"></span>
     </button>
     <button class="mx-carousel__next mx-button mx-button--icon-only" type="button">
-      <span class="sr-only">next</span>
+      <span class="sr-only">next page</span>
       <span class="mx-icon mx-icon--chevron-right"></span>
     </button>
   </div>
-  <ul class="mx-carousel__scrollable">
-    {% for item in items %}
-      <li>{{ item }}</li>
-    {% endfor %}
-  </ul>
-  {% if pagination or counter %}
+  <div class="mx-carousel__scrollable" data-track aria-live="off">
+    {{ items }}
+  </div>
+  {% if paginated %}
     {% set type = pagination ? 'pagination' : 'counter' %}
-    <ol class="mx-carousel__pagination" data-pagination="{{ type }}" hidden></ol>
+    <div class="mx-carousel__pagination" data-pagination="{{ type }}" hidden role="group" aria-label="Page controls"></div>
   {% endif %}
 </mx-carousel>

package/src/Component/ContentBlock/Components/ContentBlockContent.figma.ts

@@ -0,0 +1,28 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-184
+// source=src/Component/ContentBlock/Components/ContentBlockContent.tsx
+// component=ContentBlockContent
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const headingHandle = instance.findText("Heading")
+const heading = headingHandle.type === "TEXT" ? headingHandle.textContent : ""
+
+// "Content" replaced the old fixed "Body" text layer — a real SLOT now, same pattern
+// as CardContent/ListItemContent.
+const content = instance.getSlot("Content")
+
+export default {
+  example: figma.code`<ContentBlockContent>
+  <Heading as={HeadingTypes.THREE}>${heading}</Heading>
+  ${content}
+</ContentBlockContent>`,
+  imports: [
+    'import { ContentBlockContent, Heading } from "@pnx-mixtape/mxds/react"',
+    'import { HeadingTypes } from "@pnx-mixtape/ids-shape"',
+  ],
+  id: "content-block-content",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/ContentBlock/Components/ContentBlockMedia.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-182
+// source=src/Component/ContentBlock/Components/ContentBlockMedia.tsx
+// component=ContentBlockMedia
+import figma from "figma"
+
+// `skeleton` (boolean) not modelled — loading-state visual, not a design variant.
+export default {
+  example: figma.code`<ContentBlockMedia><Media src="..." alt="" /></ContentBlockMedia>`,
+  imports: ['import { ContentBlockMedia, Media } from "@pnx-mixtape/mxds/react"'],
+  id: "content-block-media",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/ContentBlock/ContentBlock.figma.ts

@@ -0,0 +1,18 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-187
+// source=src/Component/ContentBlock/ContentBlock.tsx
+// component=ContentBlock
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const content = instance.getSlot("Content")
+
+// `as` (wrapper tag) has no visual effect, not modelled.
+export default {
+  example: figma.code`<ContentBlock>${content}</ContentBlock>`,
+  imports: ['import { ContentBlock } from "@pnx-mixtape/mxds/react"'],
+  id: "content-block",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/ContentBlock/ContentBlock.stories.ts

@@ -11,6 +11,7 @@ import Image from "../../Atom/Image/image.twig"
 import LinkList from "../LinkList/link-list.twig"
 import Icon from "../../Atom/Icon/icon.twig"
 import "../LinkList/link-list.css"
+import { modes } from "../../../.storybook/modes"
 
 /**
  * Content Block is similar to a Card, but it is always vertical and usually includes a [LinkList](/?path=/docs/component-linklist--docs).
@@ -35,6 +36,7 @@ const meta: Meta<ContentBlockType> = {
         Link({
           title: "Music",
           href: "#",
+          listItem: true,
           iconEnd: Icon({
             icon: Icons.CHEVRON_RIGHT,
           }),
@@ -42,6 +44,7 @@ const meta: Meta<ContentBlockType> = {
         Link({
           title: "Performances",
           href: "#",
+          listItem: true,
           iconEnd: Icon({
             icon: Icons.CHEVRON_RIGHT,
           }),
@@ -49,11 +52,12 @@ const meta: Meta<ContentBlockType> = {
         Link({
           title: "Get involved",
           href: "#",
+          listItem: true,
           iconEnd: Icon({
             icon: Icons.CHEVRON_RIGHT,
           }),
         }),
-      ],
+      ].join(""),
     }),
   },
   argTypes: {
@@ -109,6 +113,14 @@ const meta: Meta<ContentBlockType> = {
       },
     },
   },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
+      },
+    },
+  },
 }
 
 export default meta

package/src/Component/ContentBlock/README.md

@@ -1,15 +1,183 @@
-# Content block
+# ContentBlock
 
-### How to use
+A vertical content block combining an optional image or icon, heading, body text, and an optional `Link` or `LinkList`. Similar to a `Card`, but always stacked vertically and typically used for wayfinding.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Component/ContentBlock/content-block.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/ContentBlock/content-block.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/ContentBlock/content-block.twig' %}`
+```twig
+{% include '@mixtape/Component/ContentBlock/content-block.twig' with {
+  title: heading_component,
+  content: '<p>Body content HTML.</p>',
+  image: image_component,
+  link: link_component,
+  linkList: link_list_component,
+} %}
+```
 
-Alternatively copy/paste the file for more control.
+**content-block.twig props** (`ContentBlock` type from `ids-shape` — extends `WayfindingBlock`):
+
+| Prop       | Type               | Required | Description                                                                            |
+| ---------- | ------------------ | -------- | -------------------------------------------------------------------------------------- |
+| `title`    | `Heading`          | yes      | Heading component rendered inside the content area                                     |
+| `content`  | `WysiwygText`      | yes      | Body content (HTML)                                                                    |
+| `image`    | `Image`            | no       | Optional `Image` component rendered above the content. Do **not** use alongside `icon` |
+| `icon`     | `Icon`             | no       | Optional `Icon` component rendered above the content. Do **not** use alongside `image` |
+| `link`     | `Link` \| `Button` | no       | Optional link rendered at the end of the content area                                  |
+| `linkList` | `LinkList`         | no       | Optional list of links rendered above `link`                                           |
+
+---
+
+## HTML
+
+```html
+<article class="mx-content-block">
+  <figure class="mx-content-block__media">
+    <img src="/photo.jpg" alt="" />
+  </figure>
+  <div class="mx-content-block__content mx-vertical-flow-flex">
+    <h3>Content block title</h3>
+    <p>
+      A short description to help explain enough about the subject matter to encourage visitors to
+      learn more.
+    </p>
+    <a class="mx-link mx-link--more" href="/read-more">Learn more</a>
+  </div>
+</article>
+```
+
+### With icon (instead of image)
+
+Icon and image are mutually exclusive — do not render both.
+
+```html
+<article class="mx-content-block">
+  <div class="mx-content-block__icon">
+    <!-- Icon atom -->
+  </div>
+  <div class="mx-content-block__content mx-vertical-flow-flex">
+    <h3>Feature block</h3>
+    <p>Description text.</p>
+  </div>
+</article>
+```
+
+### With LinkList
+
+```html
+<article class="mx-content-block">
+  <figure class="mx-content-block__media">
+    <img src="/photo.jpg" alt="" />
+  </figure>
+  <div class="mx-content-block__content mx-vertical-flow-flex">
+    <h3>Section title</h3>
+    <p>Supporting text.</p>
+    <ul class="mx-link-list">
+      <li><a class="mx-link" href="#">Music</a></li>
+      <li><a class="mx-link" href="#">Performances</a></li>
+      <li><a class="mx-link" href="#">Get involved</a></li>
+    </ul>
+  </div>
+</article>
+```
+
+---
+
+## React
+
+Uses a composition pattern — always use `ContentBlockMedia` and `ContentBlockContent` as named slots inside `ContentBlock`.
+
+```tsx
+import { ContentBlock, ContentBlockContent, ContentBlockMedia, Heading, Text, Link, Media } from "@pnx-mixtape/mxds/react"
+import { AsTypes, HeadingTypes } from "@pnx-mixtape/ids-shape"
+
+// Standard content block with image
+<ContentBlock>
+  <ContentBlockMedia>
+    <Media src="/photo.jpg" alt="" />
+  </ContentBlockMedia>
+  <ContentBlockContent>
+    <Heading as={HeadingTypes.THREE}>Content block title</Heading>
+    <Text>
+      A short description to help explain enough about the subject matter to
+      encourage visitors to learn more.
+    </Text>
+    <Link more to="/read-more">Learn more</Link>
+  </ContentBlockContent>
+</ContentBlock>
+
+// Rendered as <li> inside a grid list
+<ContentBlock as={AsTypes.LI}>
+  <ContentBlockContent>
+    <Heading as={HeadingTypes.THREE}>List item block</Heading>
+    <Text>Description text.</Text>
+  </ContentBlockContent>
+</ContentBlock>
+
+// With a media skeleton placeholder (shown behind the image while loading)
+<ContentBlock>
+  <ContentBlockMedia skeleton>
+    <Media src="/photo.jpg" alt="" />
+  </ContentBlockMedia>
+  <ContentBlockContent>
+    <Heading as={HeadingTypes.THREE}>Loading state</Heading>
+  </ContentBlockContent>
+</ContentBlock>
+```
+
+**`ContentBlock` props:**
+
+| Prop | Type      | Default | Description                                                                        |
+| ---- | --------- | ------- | ---------------------------------------------------------------------------------- |
+| `as` | `AsTypes` | `div`   | Semantic element for the outer wrapper: `div`, `li`, `article`, `aside`, `section` |
+
+**`ContentBlockMedia` props:**
+
+| Prop       | Type      | Default | Description                                           |
+| ---------- | --------- | ------- | ----------------------------------------------------- |
+| `skeleton` | `boolean` | `false` | Shows a loading skeleton placeholder behind the image |
+
+**`ContentBlockContent`** — takes children only. Renders a `<div>` with `mx-content-block__content` and `mx-vertical-flow` (vertical rhythm between child elements).
+
+---
+
+## Modifiers
+
+ContentBlock does **not** define any class modifiers or enum values. Layout is fixed (vertical stack) and colour is inherited from the surrounding section. For colour or background variants, wrap the block inside a `Section` or container with a `mx-background--*` utility.
+
+---
+
+## Accessibility
+
+- The Twig template renders the outer wrapper as `<article>`; in React the default is `<div>` — use `as={AsTypes.ARTICLE}` when the block represents standalone, self-contained content
+- Image `alt` text is required on the underlying `Media`/`Image` atom; pass `alt=""` for purely decorative imagery
+- When using an `Icon` instead of an `Image`, the icon should be decorative (`aria-hidden="true"`) — the heading is the accessible label
+- When rendering inside a list (e.g. grid of blocks), set `as={AsTypes.LI}` so the semantic list structure is preserved
+
+---
+
+## React ⇄ Twig parity
+
+| Feature         | React                                | Twig             | Notes                                                                                                                                                                   |
+| --------------- | ------------------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Icon slot       | ❌ — no `ContentBlockIcon` component | ✅ (`icon` slot) | Compose your own icon-headed block in React, or use the existing `ContentBlockMedia`/`ContentBlockHeading` pattern with an `<Icon>` placed inside `ContentBlockHeading` |
+| Default wrapper | `<div>`                              | `<article>`      | Pass `as={AsTypes.ARTICLE}` (or another semantic element) in React for parity                                                                                           |
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-content-block {
+  --content-block-gap: var(--gap); /* gap between media/icon and content */
+  --ratio: 4 / 3; /* aspect ratio applied to media images & skeleton */
+  --border-radius: 0; /* border radius applied to media images */
+}
+```

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

@@ -11,8 +11,8 @@ exports[`Content Block 1`] = `
     
 
 <ul class="mx-link-list">
-      <li>
-<a href="#">
+  
+<li><a href="#">
   
   <span>Music</span>
     
@@ -20,8 +20,7 @@ exports[`Content Block 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Performances</span>
     
@@ -29,8 +28,7 @@ exports[`Content Block 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Get involved</span>
     
@@ -38,10 +36,10 @@ exports[`Content Block 1`] = `
 
 </a>
 </li>
-  </ul>
+</ul>
 
       
-<a class="mx-link--more" href="#">
+<a href="#" class="mx-link--more">
   
   <span>Find out more</span>
     
@@ -69,8 +67,8 @@ exports[`With Icon 1`] = `
     
 
 <ul class="mx-link-list">
-      <li>
-<a href="#">
+  
+<li><a href="#">
   
   <span>Music</span>
     
@@ -78,8 +76,7 @@ exports[`With Icon 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Performances</span>
     
@@ -87,8 +84,7 @@ exports[`With Icon 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Get involved</span>
     
@@ -96,10 +92,10 @@ exports[`With Icon 1`] = `
 
 </a>
 </li>
-  </ul>
+</ul>
 
       
-<a class="mx-link--more" href="#">
+<a href="#" class="mx-link--more">
   
   <span>Find out more</span>
     
@@ -128,8 +124,8 @@ exports[`With Image 1`] = `
     
 
 <ul class="mx-link-list">
-      <li>
-<a href="#">
+  
+<li><a href="#">
   
   <span>Music</span>
     
@@ -137,8 +133,7 @@ exports[`With Image 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Performances</span>
     
@@ -146,8 +141,7 @@ exports[`With Image 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Get involved</span>
     
@@ -155,10 +149,10 @@ exports[`With Image 1`] = `
 
 </a>
 </li>
-  </ul>
+</ul>
 
       
-<a class="mx-link--more" href="#">
+<a href="#" class="mx-link--more">
   
   <span>Find out more</span>
     

package/src/Component/CookieConsent/CookieConsent.stories.ts

@@ -0,0 +1,36 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import Component from "./cookie-consent.twig"
+import "./cookie-consent.css"
+import "./Elements/CookieConsent"
+
+type CookieConsentTwigProps = {
+  id?: string
+  title?: string
+  content?: string
+  acceptLabel?: string
+  rejectLabel?: string
+  moreLabel?: string
+  moreHref?: string
+  waitRemove?: number
+}
+
+const meta: Meta<CookieConsentTwigProps> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    id: "cookie-compliance",
+    content: "<p>We use cookies to improve your experience and analyse site traffic.</p>",
+  },
+}
+
+export default meta
+type Story = StoryObj<CookieConsentTwigProps>
+
+export const CookieConsent: Story = {}
+
+export const WithPolicyLink: Story = {
+  args: {
+    moreLabel: "Learn more",
+    moreHref: "/cookie-policy",
+  },
+}

package/src/Component/CookieConsent/CookieConsent.stories.tsx

@@ -0,0 +1,24 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import Component from "./CookieConsent"
+import "./cookie-consent.css"
+import { Page } from "../../../.storybook-react/decorators"
+
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  component: Component,
+  decorators: [Page],
+  args: {
+    id: "cookie-compliance",
+    children: <p>We use cookies to improve your experience and analyse site traffic.</p>,
+  },
+}
+
+export default meta
+export const CookieConsent: StoryObj<typeof meta> = {}
+
+export const WithPolicyLink: StoryObj<typeof meta> = {
+  args: {
+    moreLabel: "Learn more",
+    moreHref: "/cookie-policy",
+  },
+}