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

package/src/Layout/Masthead/README.md

@@ -0,0 +1,92 @@
+# Masthead
+
+A slim bar above the primary Header. Used for skip links, utility navigation (e.g. language switcher, secondary links), and government/agency branding banners. Skip links are hidden offscreen and revealed on keyboard focus.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Layout/Masthead/masthead.css";
+```
+
+## HTML
+
+```html
+<!-- With skip links and utility nav -->
+<div class="mx-masthead mx-section mx-section--s mx-background--reverse">
+  <nav class="mx-skip-links" aria-label="Skip links">
+    <a href="#main-content">Skip to main content</a>
+    <a href="#main-nav">Skip to navigation</a>
+  </nav>
+  <nav class="mx-masthead__nav" aria-label="Utility navigation">
+    <a href="/login">Login</a>
+    <a href="/accessibility">Accessibility</a>
+  </nav>
+</div>
+```
+
+## Twig
+
+```twig
+{% include '@mixtape/Layout/Masthead/masthead.twig' with {
+  skipLinks: [
+    { title: 'Skip to main content', href: '#main-content' },
+  ],
+  links: [
+    { title: 'Login', href: '/login' },
+  ],
+  background: 'reverse',
+} %}
+```
+
+## Skip links
+
+`.mx-skip-links` is `position: fixed` at the top of the viewport. It is visually hidden (`transform: translateY(-100%)`) until a child `<a>` receives focus, at which point it slides into view. Always include at minimum a "Skip to main content" link for keyboard accessibility.
+
+## Utility nav (`.mx-masthead__nav`)
+
+Hidden on mobile, displayed as `inline-flex` at `--global-nav-up` (720px+).
+
+## Notes
+
+- Place `<Masthead>` before `<Header>` in the page structure
+- Combine with `mx-background--reverse` for a dark top bar
+- The `MastheadModifier` enum (`dark` | `light`) from `ids-shape` controls background in Twig
+
+## React
+
+```tsx
+import { Masthead } from "@pnx-mixtape/mxds/react"
+import { MastheadModifier } from "@pnx-mixtape/ids-shape"
+;<Masthead
+  background={MastheadModifier.DARK}
+  skipLinks={[<a href="#content">Skip to content</a>, <a href="#nav">Skip to navigation</a>]}
+  links={[
+    <a className="mx-link" href="/login">
+      Log in
+    </a>,
+  ]}
+>
+  A PreviousNext product
+</Masthead>
+```
+
+**Props:**
+
+| Prop         | Type               | Default                 | Description                                                                                         |
+| ------------ | ------------------ | ----------------------- | --------------------------------------------------------------------------------------------------- |
+| `background` | `MastheadModifier` | `MastheadModifier.DARK` | `DARK` → `mx-background--reverse`, `LIGHT` → `mx-background--alt`                                   |
+| `skipLinks`  | `ReactNode[]`      | —                       | Rendered inside `<nav aria-label="Skip to links">`. Only the nav is rendered when this is non-empty |
+| `links`      | `ReactNode[]`      | —                       | Rendered inside `<nav aria-label="Additional links">` (hidden on mobile)                            |
+| `children`   | `ReactNode`        | —                       | Arbitrary content (e.g. agency name, logo) rendered in the `flex` inner wrapper                     |
+| `className`  | `string`           | —                       | Extra class on the outer `<div>`                                                                    |
+
+The outer element is a `<div>`, not a `<header>` — see [Accessibility](#accessibility) below.
+
+---
+
+## Accessibility
+
+- The outer wrapper is a plain `<div>` — **not** a `<header>`. The Page's primary `<header class="mx-header">` is the banner landmark; making Masthead a second `<header>` at the same level would create ambiguity for assistive tech.
+- Skip links are wrapped in `<nav aria-label="Skip to links">` so they appear as a distinct landmark in the AT landmark list.
+- Utility links are wrapped in `<nav aria-label="Additional links">`. If you also have a primary `<nav>` inside the Header (labelled `"Primary navigation"`), screen readers can distinguish them.
+- If you customise these labels, ensure each `<nav>` on the page has a unique accessible name.

package/src/Layout/Masthead/__snapshots__/Masthead.stories.ts.snap

@@ -2,21 +2,20 @@
 
 exports[`Light 1`] = `
 "  <nav class="mx-skip-links" aria-label="Skip to links">
-          
+    
 <a href="#content">
   
   <span>Skip to content</span>
     
 </a>
 
-          
 <a href="#nav">
   
   <span>Skip to navigation</span>
     
 </a>
 
-      </nav>
+  </nav>
 <div class="mx-masthead mx-spacing--top-xxs mx-spacing--bottom-xxs mx-background--alt">
   <div class="flex">
         <div>A PreviousNext product</div>
@@ -27,21 +26,20 @@ exports[`Light 1`] = `
 
 exports[`Masthead 1`] = `
 "  <nav class="mx-skip-links" aria-label="Skip to links">
-          
+    
 <a href="#content">
   
   <span>Skip to content</span>
     
 </a>
 
-          
 <a href="#nav">
   
   <span>Skip to navigation</span>
     
 </a>
 
-      </nav>
+  </nav>
 <div class="mx-masthead mx-spacing--top-xxs mx-spacing--bottom-xxs mx-background--reverse">
   <div class="flex">
         <div>A PreviousNext product</div>
@@ -52,26 +50,25 @@ exports[`Masthead 1`] = `
 
 exports[`With Links 1`] = `
 "  <nav class="mx-skip-links" aria-label="Skip to links">
-          
+    
 <a href="#content">
   
   <span>Skip to content</span>
     
 </a>
 
-          
 <a href="#nav">
   
   <span>Skip to navigation</span>
     
 </a>
 
-      </nav>
+  </nav>
 <div class="mx-masthead mx-spacing--top-xxs mx-spacing--bottom-xxs mx-background--reverse">
   <div class="flex">
         <div>A PreviousNext product</div>
             <nav class="mx-masthead__nav" aria-label="Additional links">
-              
+      
 <a href="#">
   
 <span class="mx-icon mx-icon--user"></span>
@@ -80,7 +77,6 @@ exports[`With Links 1`] = `
     
 </a>
 
-              
 <a href="#">
   
 <span class="mx-icon mx-icon--login"></span>
@@ -89,7 +85,7 @@ exports[`With Links 1`] = `
     
 </a>
 
-          </nav>
+    </nav>
       </div>
 </div>
 "

package/src/Layout/Masthead/__snapshots__/Masthead.stories.tsx.snap

@@ -0,0 +1,7 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`Light 1`] = `"<nav class="mx-skip-links" aria-label="Skip to links"><a href="#content">Skip to content</a><a href="#nav">Skip to navigation</a></nav><div class="mx-masthead mx-spacing--top-xxs mx-spacing--bottom-xxs mx-background--alt"><div class="flex"><div>A PreviousNext product</div></div></div>"`;
+
+exports[`Masthead 1`] = `"<nav class="mx-skip-links" aria-label="Skip to links"><a href="#content">Skip to content</a><a href="#nav">Skip to navigation</a></nav><div class="mx-masthead mx-spacing--top-xxs mx-spacing--bottom-xxs mx-background--reverse"><div class="flex"><div>A PreviousNext product</div></div></div>"`;
+
+exports[`With Links 1`] = `"<nav class="mx-skip-links" aria-label="Skip to links"><a href="#content">Skip to content</a><a href="#nav">Skip to navigation</a></nav><div class="mx-masthead mx-spacing--top-xxs mx-spacing--bottom-xxs mx-background--reverse"><div class="flex"><div>A PreviousNext product</div><nav class="mx-masthead__nav" aria-label="Additional links"><a class="mx-link" href="#">Create account</a><a class="mx-link" href="#">Log in</a></nav></div></div>"`;

package/src/Layout/Masthead/masthead.css

@@ -28,11 +28,9 @@
     display: flex;
     z-index: 200;
     transform: translateY(-100%);
-    visibility: hidden;
 
-    &:has(a:focus) {
+    &:has(a:focus, a:focus-visible) {
       transform: translateY(0);
-      visibility: visible;
     }
 
     & a {
@@ -42,9 +40,3 @@
     }
   }
 }
-
-@media print {
-  .mx-masthead {
-    display: none;
-  }
-}

package/src/Layout/Masthead/masthead.twig

@@ -7,9 +7,7 @@
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
 {% if skipLinks is not empty %}
   <nav class="mx-skip-links" aria-label="Skip to links">
-    {% for link in skipLinks %}
-      {{ link }}
-    {% endfor %}
+    {{ skipLinks }}
   </nav>
 {% endif %}
 {% if content is not empty or links is not empty %}
@@ -20,9 +18,7 @@
     {% endif %}
     {% if links is not empty %}
     <nav class="mx-masthead__nav" aria-label="Additional links">
-      {% for link in links %}
-        {{ link }}
-      {% endfor %}
+      {{ links }}
     </nav>
     {% endif %}
   </div>

package/src/Layout/Page/Page.figma.ts

@@ -0,0 +1,21 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=79-294
+// source=src/Layout/Page/Page.tsx
+// component=Page
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const masthead = instance.getSlot("Masthead")
+const header = instance.getSlot("Header")
+const content = instance.getSlot("Content")
+const footer = instance.getSlot("Footer")
+
+// `mainId` (defaults to "main") not modelled — no visual effect.
+export default {
+  example: figma.code`<Page masthead={${masthead}} header={${header}} footer={${footer}}>${content}</Page>`,
+  imports: ['import { Page } from "@pnx-mixtape/mxds/react"'],
+  id: "page",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Layout/Page/Page.stories.tsx

@@ -16,7 +16,7 @@ const meta: Meta<typeof Component> = {
     footer: mixtapeFooter,
     children: (
       <HeroBanner>
-        <Heading as={HeadingTypes.ONE} modifier={HeadingStyles.HEADLINE}>
+        <Heading as={HeadingTypes.ONE} style={[HeadingStyles.HEADLINE]}>
           Always put your best foot forward.
         </Heading>
         <Text modifier={TextStyles.XL}>

package/src/Layout/Page/Page.tsx

@@ -3,12 +3,17 @@ import { JSX, PropsWithChildren, ReactNode } from "react"
 type PageProps = PropsWithChildren & {
   header?: ReactNode
   footer?: ReactNode
+  masthead?: ReactNode
+  mainId?: string
 }
 
-const Page = ({ children, header, footer }: PageProps): JSX.Element => (
+const Page = ({ children, header, footer, masthead, mainId = "main" }: PageProps): JSX.Element => (
   <div className="mx-page">
+    {masthead}
     {header}
-    <main className="mx-section">{children}</main>
+    <main id={mainId} className="mx-page">
+      {children}
+    </main>
     {footer}
   </div>
 )

package/src/Layout/Page/README.md

@@ -1,19 +1,93 @@
 # Page
 
-### How to use
+The root layout component. Creates a named CSS grid with multiple column tracks — `full`, `container`, `feature`, and `narrow` — that all child layouts and sections can snap to via `subgrid`. Handles fluid gutters automatically.
 
-**CSS**
+This is the outermost wrapper for every page.
 
-`@import '@pnx-mixtape/mxds/src/Layout/Page/page.css';`
+## CSS Import
 
-**Twig**
+```css
+@import "@pnx-mixtape/mxds/src/Layout/Page/page.css";
+```
 
-You can setup a twig namespace in your project if you wish to use the twig files directly.
+## Twig
 
-- Eg: `{% extends '@mixtape/Layout/Page/page.twig' %}`
+```twig
+{% include '@mixtape/Layout/Page/page.twig' with {
+  masthead: masthead_component,
+  header: header_component,
+  main: [
+    hero_section,
+    content_section,
+    cards_section,
+  ],
+  footer: footer_component,
+} %}
+```
 
-Alternatively copy/paste the file for more control.
+**page.twig props:**
 
-**JSX Components**
+| Prop         | Type           | Required | Description                                                                      |
+| ------------ | -------------- | -------- | -------------------------------------------------------------------------------- |
+| `masthead`   | `Collection`   | No       | Rendered Masthead markup placed before the header (e.g. global alert, brand bar) |
+| `header`     | `Header`       | No       | Rendered Header component                                                        |
+| `main`       | `Collection[]` | No       | Array of rendered child sections — each is looped into the `<main>` element      |
+| `footer`     | `Footer`       | No       | Rendered Footer component placed after `<main>`                                  |
+| `attributes` | `Attribute`    | No       | Optional Drupal-style attributes object — `mx-page` is always merged on top      |
 
-- JSX import: `import { Page, PageSidebar, HeroBanner } from '@pnx-mixtape/mxds/src/react';`
+The template applies the same `attributes` (with `mx-page`) to both the outer `<div>` and the inner `<main>` — when adding extra classes via `attributes` they will appear on both elements. The `Page` layout is not declared as a type in `ids-shape`; the variable list above reflects the template's own contract.
+
+## HTML
+
+```html
+<div class="mx-page">
+  <header>...</header>
+  <main id="main" class="mx-page">
+    <!-- page content -->
+  </main>
+  <footer>...</footer>
+</div>
+```
+
+## React
+
+```tsx
+import { Page, Header, Footer } from "@pnx-mixtape/react"
+;<Page
+  header={<Header logo={logo} navigationItems={navItems} />}
+  footer={<Footer copyright="© 2026 PreviousNext">{footerContent}</Footer>}
+>
+  {/* page sections go here */}
+</Page>
+```
+
+**Props:** `header?: ReactNode`, `footer?: ReactNode`, `masthead?: ReactNode`, `mainId?: string` (default `"main"`), `children`
+
+The `<main>` element is given `id="main"` by default so a "Skip to content" link can target it via `<a href="#main">`. Override with the `mainId` prop (React) or `mainId` Twig variable if you need a different anchor.
+
+## Column tracks
+
+The grid defines four named column tracks. All direct children default to `container` width. Use width modifier classes to break out:
+
+| Track       | Class                                       | Width                                   | Description                                      |
+| ----------- | ------------------------------------------- | --------------------------------------- | ------------------------------------------------ |
+| `narrow`    | `mx-page--narrow` or `mx-section--narrow`   | `58ch` (`--container-max-width-narrow`) | Narrowest — for long-form reading content        |
+| `container` | _(default)_                                 | `76ch` (`--container-max-width`)        | Centred content with fluid gutters — the default |
+| `feature`   | `mx-page--feature` or `mx-section--feature` | container + `8rem` each side            | Wider than container, bleeds into gutters        |
+| `full`      | `mx-page--full` or `mx-section--full`       | 100% viewport                           | Full viewport width, no gutters (full bleed)     |
+
+> Background colour sections (e.g. `mx-background--primary`) automatically span `full` and use `subgrid` so their children align to the same column tracks.
+
+## Gutters
+
+Gutters are fluid: `clamp(--gutter-min, 6vw, --gutter-max)` — clamped between `1em` and `2em`.
+
+## Customisation via CSS custom properties
+
+```css
+.mx-page {
+  --gutter-min: 1.5rem;
+  --gutter-max: 4rem;
+  --container-max-width: 80ch;
+}
+```

package/src/Layout/Page/__snapshots__/Page.stories.tsx.snap

@@ -1,3 +1,3 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Page 1`] = `"<div class="mx-page"><header class="mx-page mx-header mx-section--s"><div class="mx-header__inner"><div class="mx-header__brand"><a href="https://mxds.pnx.io/" class="mx-logo"><img alt="Mixtape" loading="eager" src="https://mxds.pnx.io/images/mixtape-logo.png"></a></div><div class="mx-header__main"><div id="_r_0_" class="mx-header__nav"><nav class="mx-nav mx-nav--dropdown" aria-label="Primary Navigation" id="_r_0_"><ul class="mx-nav__level-1"><li class="mx-nav__has-subnav"><a href="http://example.com/#1" class="">Home</a><button aria-controls="_r_1_" aria-expanded="false" class="mx-nav__toggle mx-icon mx-icon--only mx-icon--chevron-down" type="button">Sub-navigation</button></li><li class=""><a href="http://example.com/#2" class="">About</a></li><li class=""><a href="http://example.com/#3" class="">Contact</a></li></ul></nav></div></div></div></header><main class="mx-section"><div class="mx-page mx-section--xl"><div class="mx-hero-banner mx-vertical-flow"><h1 class="mx-headline" id="always-put-your-best-">Always put your best foot forward.</h1><p class="mx-text--xl">Make the most of the opportunity by encouraging an action and keeping your copy clear and concise.</p></div></div></main><footer class="mx-footer mx-section--top-l mx-section--bottom-m"><div class="mx-footer__inner"><span class="mx-footer__copyright mx-text--s">© 2022 Company Name</span></div></footer></div>"`;
+exports[`Page 1`] = `"<div class="mx-page"><header class="mx-page mx-header mx-section--s"><div class="mx-header__inner"><div class="mx-header__brand"><img alt="Mixtape" src="mixtape-logo.png"></div><div class="mx-header__main"><div id="_r_0_" class="mx-header__nav mx-header__collapse-toggle"><nav class="mx-nav mx-nav--dropdown" aria-label="Primary Navigation" id="_r_0_"><ul class="mx-nav__level-1"><li class="mx-nav__has-subnav"><a href="http://example.com/#1" class="">Home</a><button aria-controls="_r_1_" aria-expanded="false" class="mx-nav__toggle mx-icon mx-icon--only mx-icon--chevron-down" type="button">Sub-navigation</button></li><li class=""><a href="http://example.com/#2" class="">About</a></li><li class=""><a href="http://example.com/#3" class="">Contact</a></li></ul></nav></div></div></div></header><main id="main" class="mx-page"><div class="mx-page mx-hero-banner"><div class="mx-hero-banner__inner"><h1 class="mx-headline" id="always-put-your-best">Always put your best foot forward.</h1><p class="mx-text--xl">Make the most of the opportunity by encouraging an action and keeping your copy clear and concise.</p></div></div></main><footer class="mx-footer mx-section--l"><div class="mx-footer__inner"><span class="mx-footer__copyright mx-text--s">© 2022 Company Name</span></div></footer></div>"`;

package/src/Layout/Page/page.twig

@@ -1,13 +1,13 @@
-{% set classes = ['mx-page'] %}
-{% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
-{% set mainAttributes = (attributes ?? create_attribute()).addClass(classes) %}
+{% set mainId = mainId|default('main') %}
+{% set attributes = (attributes ?? create_attribute()).addClass(['mx-page']) %}
+{% set mainAttributes = create_attribute()
+  .addClass(['mx-page'])
+  .setAttribute('id', mainId) %}
 <div{{ attributes }}>
   {{ masthead }}
   {{ header }}
   <main{{ mainAttributes }}>
-    {% for child in main %}
-      {{ child }}
-    {% endfor %}
+    {{ main }}
   </main>
   {{ footer }}
 </div>

package/src/Layout/Section/Background.stories.ts

@@ -3,12 +3,9 @@ import Component from "./twig/section-background.twig"
 import "./section.css"
 import { Section as SectionType, Image as ImageType } from "@pnx-mixtape/ids-shape"
 import { BackgroundStyles } from "../../enums"
-import Section from "./Section.stories"
+import SectionStories from "./Section.stories"
 
 // Deps.
-import Heading from "../../Atom/Heading/heading.twig"
-import Link from "../../Atom/Link/link.twig"
-import Icon from "../../Atom/Icon/icon.twig"
 import Image from "../../Atom/Image/image.twig"
 
 type MxSectionType = SectionType & {
@@ -22,14 +19,14 @@ const meta: Meta<MxSectionType> = {
   tags: ["autodocs"],
   component: Component,
   args: {
-    ...Section.args,
+    ...SectionStories.args,
     image: Image({
       src: "https://picsum.photos/id/56/1642/560?grayscale",
       alt: "Blurry bubbles",
     }),
   },
   argTypes: {
-    ...Section.argTypes,
+    ...SectionStories.argTypes,
     image: {
       description: "[Image](/?path=/docs/atom-image--docs) component.",
       control: "text",

package/src/Layout/Section/README.md

@@ -0,0 +1,144 @@
+# Section
+
+A page section wrapper with vertical padding and an optional page-grid column track. The most commonly used layout primitive — every content region on a page is typically a `Section`.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Layout/Section/section.css";
+```
+
+## Twig
+
+```twig
+{# Plain section with vertical padding and a background colour #}
+{% include '@mixtape/Layout/Section/section.twig' with {
+  as: 'section',
+  modifiers: ['l'],
+  background: 'primary',
+  container: true,
+  content: section_content,
+} %}
+
+{# Section header with title + a "view all" link, then content #}
+{% include '@mixtape/Layout/Section/section.twig' with {
+  as: 'section',
+  modifiers: ['xl'],
+  container: true,
+  title: heading_component,
+  link: more_link_component,
+  content: cards_grid,
+} %}
+```
+
+**section.twig props** (`Section` type from `ids-shape`, extends `WayfindingBlock`):
+
+| Prop              | Type                 | Required | Description                                                                                           |
+| ----------------- | -------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
+| `content`         | `WysiwygText`        | No       | Main rendered content of the section — placed inside the inner container when `container: true`       |
+| `title`           | `Heading`            | No       | Optional rendered Heading placed inside `<div class="mx-section__header">`                            |
+| `link`            | `Link \| Button`     | No       | Optional rendered Link/Button placed alongside the title in the section header                        |
+| `as`              | `SectionTypes`       | No       | Semantic element. Defaults to `div` — pass `section`/`header`/`footer`/`aside` etc.                   |
+| `modifiers`       | `SectionModifiers[]` | No       | Each value is appended as `mx-section--{modifier}` (e.g. `s`, `l`, `xl`, `top-l`)                     |
+| `background`      | `string`             | No       | Adds `mx-background--{background}` to the outer element                                               |
+| `container`       | `boolean`            | No       | Wraps content in `<div class="mx-container mx-vertical-flow">` to enable container queries            |
+| `attributes`      | `Attribute`          | No       | Optional Drupal-style attributes object on the outer element — modifier classes merged on top         |
+| `innerAttributes` | `Attribute`          | No       | Optional Drupal-style attributes object on the inner container (only rendered when `container: true`) |
+
+The section header is only output when `title` or `link` is non-empty. The Twig template does not currently consume the `linkBefore` flag from the `Section` type — if you need the link to appear before the title, author the markup directly.
+
+## HTML
+
+```html
+<!-- Section with large padding, full-width background -->
+<section class="mx-section mx-section--l mx-background--primary">
+  <div>Content here</div>
+</section>
+
+<!-- Narrow reading column -->
+<div class="mx-page mx-page--narrow">
+  <section class="mx-section mx-section--xl">Long article text</section>
+</div>
+```
+
+## React
+
+```tsx
+import Section from "@pnx-mixtape/mxds/src/Layout/Section/Section"
+import SectionGrid from "@pnx-mixtape/mxds/src/Layout/Section/SectionGrid"
+import { PageWidths, SectionFlow } from "../../enums"
+import { SectionTypes, SectionModifiers, GridModifiers } from "@pnx-mixtape/ids-shape"
+
+// Basic section with vertical padding
+<Section sizes={SectionModifiers.L}>
+  Content here
+</Section>
+
+// Section that acts as its own page-grid container (containing=true)
+<Section sizes={SectionModifiers.XL} containing width={PageWidths.NARROW}>
+  Narrow reading column
+</Section>
+
+// Section with an inner CSS container query context
+<Section sizes={SectionModifiers.M} container>
+  Content responding to container size
+</Section>
+
+// Section + grid in one
+<SectionGrid sizes={SectionModifiers.L} cols={GridModifiers.MD_3}>
+  <div>Card 1</div>
+  <div>Card 2</div>
+  <div>Card 3</div>
+</SectionGrid>
+```
+
+**`Section` props:**
+
+| Prop         | Type                                     | Default | Description                                                           |
+| ------------ | ---------------------------------------- | ------- | --------------------------------------------------------------------- |
+| `as`         | `SectionTypes`                           | `div`   | Semantic element: `div`, `section`, `header`, `footer`, `aside`, `ul` |
+| `sizes`      | `SectionModifiers \| SectionModifiers[]` | —       | Vertical padding variant(s)                                           |
+| `width`      | `PageWidths`                             | —       | Column track: `narrow`, `feature`, `full`                             |
+| `flow`       | `SectionFlow`                            | —       | Flow behaviour: `flow` or `group`                                     |
+| `containing` | `boolean`                                | `false` | Makes the section behave as a `mx-page` grid root                     |
+| `container`  | `boolean`                                | `false` | Adds `mx-container` (CSS container query context) to inner wrapper    |
+
+**`SectionGrid`** accepts the same props plus `cols: GridModifiers | GridModifiers[]` — renders a `Grid` inside automatically.
+
+## Padding size modifiers (`SectionModifiers` enum)
+
+| Class            | `SectionModifiers` enum | Padding                |
+| ---------------- | ----------------------- | ---------------------- |
+| `mx-section--s`  | `SectionModifiers.S`    | `--spacing-s` (1em)    |
+| `mx-section--m`  | `SectionModifiers.M`    | `--spacing-m` (1.5em)  |
+| `mx-section--l`  | `SectionModifiers.L`    | `--spacing-xl` (2.5em) |
+| `mx-section--xl` | `SectionModifiers.XL`   | `--spacing-uul` (5em)  |
+
+One-sided variants: `mx-section--top-{s|m|l|xl}` and `mx-section--bottom-{s|m|l|xl}`
+
+## Flow & Group modes
+
+These use `container-style` spacing so adjacent sections of the same type share padding automatically — no manual margin collapsing needed.
+
+- **`mx-section--flow`** (`SectionFlow.FLOW`) — Sections flow with consistent vertical rhythm. Adjacent flow sections share padding intelligently.
+- **`mx-section--group`** (`SectionFlow.GROUP`) — Sections that share a background colour group together. Padding is applied only at the start/end of each group island.
+- **`mx-section--divider`** — Adds a top border line between sections.
+
+## CSS container query context
+
+Adding `container` (React) or `mx-container` (HTML) class to the inner wrapper enables `@container` queries in child components using `container-type: inline-size`.
+
+## Customisation via CSS custom properties
+
+```css
+/* Override section spacing scale */
+:root {
+  --section-s: var(--spacing-m);
+  --section-l: var(--spacing-xxl);
+  --section-xl: var(--spacing-xxxl);
+}
+```
+
+---
+
+→ Used in context: `mockups/ArticleListingPage.stories.ts:9`

package/src/Layout/Section/Section.figma.ts

@@ -0,0 +1,47 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=112-18
+// source=src/Layout/Section/Section.tsx
+// component=Section
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+// Only the symmetric padding-block scale is modelled — `sizes` also accepts an array
+// of independent Top-*/Bottom-* values (e.g. real usage: [TOP_M, BOTTOM_XL]), which
+// isn't representable as a single enum value. Same simplification Text made for its
+// Style axis (pure scale only, not every combinable modifier).
+const sizes = instance.getEnum("Sizes", {
+  None: null,
+  S: "SectionModifiers.S",
+  M: "SectionModifiers.M",
+  L: "SectionModifiers.L",
+  XL: "SectionModifiers.XL",
+})
+const sizesProp = sizes ? ` sizes={${sizes}}` : ""
+
+const content = instance.getSlot("Content")
+
+// Real, supported props deliberately NOT modelled as Figma variants:
+// - `background` (BackgroundStyles) — Section's own stories never exercise it either;
+//   crossing it with Sizes would mean 30 variants for a prop that isn't this
+//   component's main axis. `Card`/`GlobalAlert` already demonstrate the same enum.
+// - `flow` (SectionFlow) — the CSS spacing effect only differs based on adjacent
+//   sibling sections (`:has()`-based selectors in section.css); a single isolated
+//   instance shows identical padding for Flow vs Group vs a plain Sizes value, so
+//   there's no honest way to distinguish it visually in isolation.
+// - `width` + `containing` — the width/container concept is already fully modelled by
+//   the `Page` component (Chunk 5); duplicating that variant matrix here for a prop
+//   that just nests a `.mx-page`/`.mx-section` width class isn't worth the repeat.
+// - `as` (semantic tag only, no visual effect), `container`/`innerClassName`/
+//   `className` (cosmetic escape hatches) — same reasoning as other components'
+//   non-visual tag/className props (ContentBlock, ListItem, Card's `block`).
+export default {
+  example: figma.code`<Section${sizesProp}>${content}</Section>`,
+  imports: [
+    'import { Section } from "@pnx-mixtape/mxds/react"',
+    'import { SectionModifiers } from "@pnx-mixtape/ids-shape"',
+  ],
+  id: "section",
+  metadata: {
+    nestable: true,
+  },
+}