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

package/src/Atom/Background/backgrounds.twig

@@ -1,12 +1,72 @@
 <div class="mx-spacing--m mx-rich-text mx-vertical-flow {{ modifier_class }}{% if modifier %} mx-background--{{ modifier }}{% endif %}">
-  <div class="mx-background--box mx-section--m  mx-vertical-flow ">
-    <p>But I must explain to you how all this mistaken idea of denouncing of a <a href="#">pleasure and praising pain</a> was born and I will give you a complete account of the system, and expound the actual teachings of the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes, or avoids pleasure itself, because it is pleasure, but because those who do not know how to pursue pleasure rationally encounter consequences that are extremely painful. Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences.</p>
-    <a href="#" class="mx-button mx-button--dark">Contact us</a> or
-    <a href="#" class="mx-link--external">Contact the Lorem Ipsum Squad</a>
-  </div>
-  <div class="mx-background--reset mx-background--box mx-section--m  mx-vertical-flow ">
-    <p>But I must explain to you how all this mistaken idea of denouncing of a <a href="#">pleasure and praising pain</a> was born and I will give you a complete account of the system, and expound the actual teachings of the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes, or avoids pleasure itself, because it is pleasure, but because those who do not know how to pursue pleasure rationally encounter consequences that are extremely painful. Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences.</p>
-    <a href="#" class="mx-button mx-button--dark">Contact us</a> or
-    <a href="#" class="mx-link--external">Contact the Lorem Ipsum Squad</a>
+  <div class="mx-vertical-flow">
+    <p class="mx-text--alt"><strong>General check</strong></p>
+    <p class="mx-text--eyebrow mx-text--embellished">Colour contrast works</p>
+    <p>But I must explain to you how all this mistaken idea of denouncing of a <a href="#">pleasure and praising pain</a> was born and I will give you a complete account of the system, and expound the actual teachings of the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes, or avoids pleasure itself, because it is pleasure, but because those who do not know how to pursue pleasure rationally encounter consequences that are extremely painful. Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences. To find out more <a href="#" class="mx-link--external">Contact the Lorem Ipsum Squad</a>.</p>
+    <p class="mx-text--primary"><strong>Primary text</strong></p>
+    <div class="mx-form-actions">
+      <a href="#" class="mx-button mx-button--dark">Contact us</a>
+      <a href="#" class="mx-button mx-button--dark mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--light">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--white">Contact us</a>
+    </div>
+  </div>
+  <div class="mx-background--box mx-background--reverse mx-section--m mx-vertical-flow">
+    <p class="mx-text--alt"><strong>Reverse check</strong></p>
+    <p class="mx-text--eyebrow mx-text--embellished">Reverse background with auto contrast</p>
+    <p>But I must explain to you how all this mistaken idea of denouncing of a <a href="#">pleasure and praising pain</a> was born and I will give you a complete account of the system, and expound the actual teachings of the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes, or avoids pleasure itself, because it is pleasure, but because those who do not know how to pursue pleasure rationally encounter consequences that are extremely painful. Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences. To find out more <a href="#" class="mx-link--external">Contact the Lorem Ipsum Squad</a>.</p>
+    <p class="mx-text--primary"><strong>Primary text</strong></p>
+    <div class="mx-form-actions">
+      <a href="#" class="mx-button mx-button--dark">Contact us</a>
+      <a href="#" class="mx-button mx-button--dark mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--light">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--white">Contact us</a>
+    </div>
+  </div>
+  <div class="mx-background--box mx-background--primary mx-section--m mx-vertical-flow">
+    <p class="mx-text--alt"><strong>Primary check</strong></p>
+    <p class="mx-text--eyebrow mx-text--embellished">Primary background with auto contrast</p>
+    <p>But I must explain to you how all this mistaken idea of denouncing of a <a href="#">pleasure and praising pain</a> was born and I will give you a complete account of the system, and expound the actual teachings of the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes, or avoids pleasure itself, because it is pleasure, but because those who do not know how to pursue pleasure rationally encounter consequences that are extremely painful. Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences. To find out more <a href="#" class="mx-link--external">Contact the Lorem Ipsum Squad</a>.</p>
+    <p class="mx-text--primary"><strong>Primary text</strong></p>
+    <div class="mx-form-actions">
+      <a href="#" class="mx-button mx-button--dark">Contact us</a>
+      <a href="#" class="mx-button mx-button--dark mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--light">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--white">Contact us</a>
+    </div>
+  </div>
+  <div class="mx-background--box mx-background--accent mx-section--m mx-vertical-flow">
+    <p class="mx-text--alt"><strong>Accent check</strong></p>
+    <p class="mx-text--eyebrow mx-text--embellished">Accent background with auto contrast</p>
+    <p>But I must explain to you how all this mistaken idea of denouncing of a <a href="#">pleasure and praising pain</a> was born and I will give you a complete account of the system, and expound the actual teachings of the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes, or avoids pleasure itself, because it is pleasure, but because those who do not know how to pursue pleasure rationally encounter consequences that are extremely painful. Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences. To find out more <a href="#" class="mx-link--external">Contact the Lorem Ipsum Squad</a>.</p>
+    <p class="mx-text--primary"><strong>Primary text</strong></p>
+    <div class="mx-form-actions">
+      <a href="#" class="mx-button mx-button--dark">Contact us</a>
+      <a href="#" class="mx-button mx-button--dark mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--light">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--white">Contact us</a>
+    </div>
+  </div>
+  <div class="mx-background--box mx-section--m mx-vertical-flow">
+    <p class="mx-text--alt"><strong>Reset check</strong></p>
+    <p class="mx-text--eyebrow mx-text--embellished">Resets background when no colour is used</p>
+    <p>But I must explain to you how all this mistaken idea of denouncing of a <a href="#">pleasure and praising pain</a> was born and I will give you a complete account of the system, and expound the actual teachings of the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes, or avoids pleasure itself, because it is pleasure, but because those who do not know how to pursue pleasure rationally encounter consequences that are extremely painful. Nor again is there anyone who loves or pursues or desires to obtain pain of itself, because it is pain, but occasionally circumstances occur in which toil and pain can procure him some great pleasure. To take a trivial example, which of us ever undertakes laborious physical exercise, except to obtain some advantage from it? But who has any right to find fault with a man who chooses to enjoy a pleasure that has no annoying consequences. To find out more <a href="#" class="mx-link--external">Contact the Lorem Ipsum Squad</a>.</p>
+    <p class="mx-text--primary"><strong>Primary text</strong></p>
+    <div class="mx-form-actions">
+      <a href="#" class="mx-button mx-button--dark">Contact us</a>
+      <a href="#" class="mx-button mx-button--dark mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--light">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent">Contact us</a>
+      <a href="#" class="mx-button mx-button--accent mx-button--outline">Contact us</a>
+      <a href="#" class="mx-button mx-button--white">Contact us</a>
+    </div>
   </div>
 </div>

package/src/Atom/Blockquote/README.md

@@ -0,0 +1,27 @@
+# Blockquote
+
+Styles the native `<blockquote>` element with a left border and inline padding. No class required — applied globally via `@layer design-system.defaults`.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Atom/Blockquote/_blockquote.css";
+```
+
+## HTML
+
+```html
+<blockquote>
+  <p>Design is not just what it looks like. Design is how it works.</p>
+</blockquote>
+```
+
+## Customisation via CSS custom properties
+
+```css
+blockquote {
+  --line-width: 4px; /* border thickness (default: 6px) */
+  --line-colour: var(--colour-primary); /* border colour (default: --colour-border) */
+  --line-gap: var(--spacing-l); /* inline padding (default: --gap) */
+}
+```

package/src/Atom/Blockquote/_blockquote.css

@@ -1,6 +1,11 @@
 @layer design-system.defaults {
   blockquote {
     padding-inline-start: var(--line-gap, var(--gap));
-    border-inline-start: var(--line-width, 6px) solid var(--line-colour, var(--colour-border));
+    border-inline-start: var(--line-width, 1ch) solid
+      var(--line-colour, var(--blockquote-line-colour, var(--colour-accent)));
+
+    & cite {
+      display: inline-block;
+    }
   }
 }

package/src/Atom/Button/Button.figma.ts

@@ -0,0 +1,70 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=5-67
+// source=src/Atom/Button/Button.tsx
+// component=Button
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const label = instance.getString("Label")
+const disabled = instance.getBoolean("Disabled")
+
+// ButtonModifiers enum values are DARK/LIGHT/WHITE/DESTRUCTIVE/OUTLINE. "Accent" has
+// no enum value in code — it's CSS-only (mx-button--accent) — so it falls back to a
+// className rather than the modifiers prop. See ButtonModifiers README for details.
+const colour = instance.getEnum("Colour", {
+  Dark: "ButtonModifiers.DARK",
+  Light: "ButtonModifiers.LIGHT",
+  White: "ButtonModifiers.WHITE",
+  Destructive: "ButtonModifiers.DESTRUCTIVE",
+  Accent: null,
+})
+const outline = instance.getEnum("Outline", { Off: false, On: true })
+
+// `mx-button--icon-only` (fixed 40x40 round shape, no label) is now a real `iconOnly`
+// boolean prop in code (added after the original pilot, which deliberately dropped
+// size modifiers from scope — this one earned its way back in once FormSearch, Chunk
+// 1, needed a real icon-only submit button).
+const iconOnly = instance.getEnum("Icon Only", { Off: false, On: true })
+
+// Icon Start/Icon End are real INSTANCE_SWAP properties. Button's code prop takes the
+// Icons enum value directly (not a rendered <Icon/> element), so rather than
+// executeTemplate() (which would render a full nested <Icon icon={...} /> snippet) we
+// read codeConnectId() from the swapped instance and map it back to the enum value —
+// each swappable Icon/X component in this file has its own tiny Code Connect mapping
+// (IconChevronDown.figma.ts / IconSearch.figma.ts) purely so this lookup works.
+function iconEnumFor(showPropName, swapPropName) {
+  const shown = instance.getBoolean(showPropName)
+  if (!shown) return null
+  const swapped = instance.getInstanceSwap(swapPropName)
+  if (!swapped || swapped.type !== "INSTANCE") return null
+  const id = swapped.codeConnectId()
+  if (id === "icon-chevron-down") return "Icons.CHEVRON_DOWN"
+  if (id === "icon-search") return "Icons.SEARCH"
+  if (id === "icon-arrow-left") return "Icons.ARROW_LEFT"
+  if (id === "icon-arrow-right") return "Icons.ARROW_RIGHT"
+  return null
+}
+
+const iconStart = iconEnumFor("Show Icon Start", "Icon Start")
+const iconEnd = iconEnumFor("Show Icon End", "Icon End")
+
+const modifiers = [colour, outline ? "ButtonModifiers.OUTLINE" : null].filter(Boolean)
+const modifiersProp = modifiers.length ? ` modifiers={[${modifiers.join(", ")}]}` : ""
+const classNameProp = colour === null ? ` className="mx-button--accent"` : ""
+const iconStartProp = iconStart ? ` iconStart={${iconStart}}` : ""
+const iconEndProp = iconEnd ? ` iconEnd={${iconEnd}}` : ""
+const iconOnlyProp = iconOnly ? " iconOnly" : ""
+const disabledProp = disabled ? " disabled" : ""
+const children = iconOnly ? "" : label
+
+export default {
+  example: figma.code`<Button${modifiersProp}${classNameProp}${iconStartProp}${iconEndProp}${iconOnlyProp}${disabledProp}>${children}</Button>`,
+  imports: [
+    'import { Button, Icons } from "@pnx-mixtape/mxds/react"',
+    'import { ButtonModifiers } from "@pnx-mixtape/ids-shape"',
+  ],
+  id: "button",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Button/Button.stories.ts

@@ -5,6 +5,10 @@ import "./button.css"
 import { Button as ButtonType, ButtonModifiers, ButtonTypes } from "@pnx-mixtape/ids-shape"
 import { Icons } from "../../enums"
 
+enum MxButtonModifiers {
+  ACCENT = "accent",
+}
+
 /**
  * A button atom with optional icon.
  */
@@ -40,7 +44,7 @@ const meta: Meta<ButtonType> = {
     modifiers: {
       description:
         "Define the style of the button. **outline** and **full-width** can be used with the other colour options.",
-      options: Object.values(ButtonModifiers),
+      options: Object.values({ ...ButtonModifiers, ...MxButtonModifiers }),
       control: "multi-select",
       table: {
         type: { summary: "enum" },

package/src/Atom/Button/Button.stories.tsx

@@ -17,7 +17,8 @@ const meta: Meta<typeof Component> = {
       options: Object.values(ButtonModifiers),
       control: "multi-select",
     },
-    icon: { options: Object.values(Icons), control: "select" },
+    iconStart: { options: Object.values(Icons), control: "select" },
+    iconEnd: { options: Object.values(Icons), control: "select" },
   },
 }
 

package/src/Atom/Button/Button.tsx

@@ -1,12 +1,14 @@
 import { JSX, PropsWithChildren, ComponentPropsWithoutRef } from "react"
 import classNames from "classnames"
 import Link from "../Link/Link"
+import Icon from "../Icon/Icon"
 import { ButtonModifiers } from "@pnx-mixtape/ids-shape"
-import { Icons } from "../../enums"
+import { EMPTY_ARRAY, Icons } from "../../enums"
 
 export type ButtonProps = PropsWithChildren & {
   modifiers?: ButtonModifiers[]
-  icon?: Icons
+  iconStart?: Icons
+  iconEnd?: Icons
   iconOnly?: boolean
   className?: string
 }
@@ -19,25 +21,27 @@ export type ButtonLinkType = ComponentPropsWithoutRef<"a"> &
 
 const Button = ({
   children,
-  modifiers,
-  icon,
+  modifiers = EMPTY_ARRAY,
+  iconStart,
+  iconEnd,
   iconOnly,
   className,
   type = "button",
   ...props
 }: ButtonType): JSX.Element => {
   const classes = ["mx-button", className]
-  const buttonMods = [...modifiers].map(modifier => `mx-button--${modifier}`)
+  const buttonMods = modifiers.map(modifier => `mx-button--${modifier}`)
   return (
     <button
       className={classNames([...classes, ...buttonMods], {
         ["mx-button--icon-only"]: iconOnly,
-        [`mx-icon mx-icon--${icon}`]: icon,
       })}
       type={type}
       {...props}
     >
+      {iconStart && <Icon icon={iconStart} />}
       {children}
+      {iconEnd && <Icon icon={iconEnd} />}
     </button>
   )
 }
@@ -45,24 +49,26 @@ const Button = ({
 export const ButtonLink = ({
   to,
   children,
-  modifiers,
-  icon,
+  modifiers = EMPTY_ARRAY,
+  iconStart,
+  iconEnd,
   iconOnly,
   className,
   ...props
 }: ButtonLinkType): JSX.Element => {
   const classes = ["mx-button", className]
-  const buttonMods = [...modifiers].map(modifier => `mx-button--${modifier}`)
+  const buttonMods = modifiers.map(modifier => `mx-button--${modifier}`)
   return (
     <Link
       className={classNames([...classes, ...buttonMods], {
         ["mx-button--icon-only"]: iconOnly,
-        [`mx-icon mx-icon--${icon}`]: icon,
       })}
       to={to}
       {...props}
     >
+      {iconStart && <Icon icon={iconStart} />}
       {children}
+      {iconEnd && <Icon icon={iconEnd} />}
     </Link>
   )
 }

package/src/Atom/Button/README.md

@@ -1,30 +1,132 @@
-# Buttons
+# Button
 
-### How to use
+A flexible button component supporting multiple visual styles, sizes, and icon configurations.
 
-**CSS**
-
-For everything;
-
-`@import '@pnx-mixtape/mxds/src/Atom/Button/button.css';`
-
-For specifics;
+## CSS Import
 
 ```css
+/* Full component (recommended) */
+@import "@pnx-mixtape/mxds/src/Atom/Button/button.css";
+
+/* Partial imports for customisation */
 @import "@pnx-mixtape/mxds/src/Atom/Button/_buttons.css";
 @import "@pnx-mixtape/mxds/src/Atom/Button/_buttons-styles.css";
+```
 
-.button--primary {
-  --border-radius: 0;
+## Twig
 
-  @media (--medium-up) {
-    border-width: 6px;
-  }
-}
+```twig
+{# Standard <button> #}
+{% include '@mixtape/Atom/Button/button.twig' with {
+  as: 'button',
+  title: 'Save',
+  modifiers: ['dark'],
+} %}
+
+{# Anchor styled as a button — pass as: 'link' to render an <a> #}
+{% include '@mixtape/Atom/Button/button.twig' with {
+  as: 'link',
+  title: 'Learn more',
+  href: '/about',
+  modifiers: ['outline', 'dark'],
+} %}
+
+{# Icon-only button — title becomes sr-only text #}
+{% include '@mixtape/Atom/Button/button.twig' with {
+  as: 'button',
+  title: 'Close',
+  iconOnly: true,
+  iconStart: include('@mixtape/Atom/Icon/icon.twig', { icon: 'close' }),
+} %}
+
+{# Submit / reset / input variants #}
+{% include '@mixtape/Atom/Button/button.twig' with {
+  as: 'submit',
+  title: 'Submit',
+  modifiers: ['dark'],
+} %}
+```
+
+**button.twig props** (`Button` type from `ids-shape`):
+
+| Prop         | Type                | Required | Description                                                                                                                                                                           |
+| ------------ | ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `as`         | `ButtonTypes`       | Yes      | Determines the rendered element. `link` renders `<a href>`, `input` renders `<input type="button">`, anything else renders a `<button type="{as}">` (defaulting to `button` if empty) |
+| `title`      | `string`            | Yes      | Visible label, or `sr-only` label when `iconOnly` is set                                                                                                                              |
+| `href`       | `string`            | No       | Destination URL — only used when `as: 'link'`                                                                                                                                         |
+| `modifiers`  | `ButtonModifiers[]` | No       | Each value is appended as `mx-button--{modifier}` (e.g. `dark`, `outline`, `destructive`)                                                                                             |
+| `disabled`   | `boolean`           | No       | Adds the `disabled` attribute to `<button>` and `<input>` variants                                                                                                                    |
+| `iconStart`  | `Icon`              | No       | Optional rendered Icon atom shown before the label                                                                                                                                    |
+| `iconEnd`    | `Icon`              | No       | Optional rendered Icon atom shown after the label                                                                                                                                     |
+| `iconOnly`   | `boolean`           | No       | Adds `mx-button--icon-only` and wraps the title in `class="sr-only"` — pair with `iconStart`/`iconEnd`                                                                                |
+| `attributes` | `Attribute`         | No       | Optional Drupal-style attributes object — modifier classes are merged on top                                                                                                          |
+
+The `as` prop maps directly to the rendered element. `link` and `input` are special-cased; any other value (`button`, `submit`, `reset`) is used verbatim as the `<button type="...">` value.
+
+## HTML
+
+```html
+<a class="mx-button mx-button--dark" href="#">Primary button</a>
+<button class="mx-button mx-button--destructive" type="button">Delete</button>
+```
+
+## React
+
+```tsx
+import { Button, ButtonLink } from "@pnx-mixtape/mxds/react"
+import { ButtonModifiers } from "@pnx-mixtape/ids-shape"
+
+<Button modifiers={[ButtonModifiers.DARK]}>Save</Button>
+<ButtonLink to="/path" modifiers={[ButtonModifiers.OUTLINE, ButtonModifiers.DARK]}>Learn more</ButtonLink>
 ```
 
-**HTML**
+**Props:** `modifiers: ButtonModifiers[]`, `iconStart?: Icons`, `iconEnd?: Icons`, `iconOnly?: boolean`
+
+If you have content from a CMS that arrives as Twig-style `Icon` objects (`{ name, attributes }`), unwrap them at the integration layer before passing to React Button — there's no shape adapter today.
+
+## Colour Modifiers
+
+Defined in `_buttons-styles.css`. Enum values from [`@pnx-mixtape/ids-shape`](https://unpkg.com/@pnx-mixtape/ids-shape/docs/index.html).
+
+| Class                    | Enum value                    | Intent                                                 |
+| ------------------------ | ----------------------------- | ------------------------------------------------------ |
+| `mx-button--dark`        | `ButtonModifiers.DARK`        | High-emphasis — primary colour fill, light text        |
+| `mx-button--light`       | `ButtonModifiers.LIGHT`       | Low-emphasis — transparent background, underlined text |
+| `mx-button--white`       | `ButtonModifiers.WHITE`       | White fill — for use on dark/coloured backgrounds      |
+| `mx-button--destructive` | `ButtonModifiers.DESTRUCTIVE` | Danger/delete — error colour fill                      |
+| `mx-button--accent`      | _(CSS-only, no enum value)_   | Accent colour fill                                     |
+
+### Outline combination
+
+Any colour modifier can be combined with `mx-button--outline` (`ButtonModifiers.OUTLINE`) to produce a ghost/outlined variant with no background fill:
 
 ```html
-<a class="button button--dark" href="#">Primary button</a>
+<button class="mx-button mx-button--dark mx-button--outline">Outlined dark</button>
+```
+
+## Layout Modifiers
+
+Defined in `_buttons.css`. These are CSS-only — not in the `ButtonModifiers` enum.
+
+| Class                   | Intent                                                                      |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `mx-button--large`      | Increased padding — use for primary CTAs                                    |
+| `mx-button--small`      | Reduced size and font — use in dense UI                                     |
+| `mx-button--full-width` | Stretches to container width, content centred                               |
+| `mx-button--icon-only`  | Circular button — hides label visually, requires accessible label in markup |
+
+## Customisation via CSS custom properties
+
+```css
+.my-context .mx-button {
+  --button-dark-bg: var(--colour-accent); /* override dark variant background */
+  --button-dark-fg: var(--colour-foreground);
+  --radius: 0; /* square corners */
+  --vertical-padding: 1rem;
+  --horizontal-padding: 2rem;
+}
 ```
+
+---
+
+→ Used in context: `mockups/ContactPage.stories.ts:16`

package/src/Atom/Button/_buttons-styles.css

@@ -3,21 +3,22 @@
  */
 
 @layer design-system.atoms {
+  /* @public --button-dark-bg --button-dark-fg --button-dark-line --button-accent-bg --button-accent-fg --button-accent-line --button-accent-scheme --button-light-bg --button-light-fg --button-light-line */
   .mx-button--dark {
-    --line-colour: var(--button-dark-bg, var(--colour-link));
-    --background: var(--button-dark-bg, var(--colour-link));
-    --foreground: var(--button-dark-fg, var(--colour-foreground-reverse));
+    --line-colour: var(--button-dark-line, var(--colour-link));
+    --button-bg: var(--button-dark-bg, var(--colour-link));
+    --button-fg: var(--button-dark-fg, var(--colour-foreground-reverse));
 
     &.mx-button--outline {
-      --background: transparent;
-      --foreground: var(--button-dark-bg, var(--colour-link));
+      --button-bg: transparent;
+      --button-fg: var(--button-dark-bg, var(--colour-link));
     }
   }
 
   .mx-button--light {
-    --line-colour: var(--button-light-bg, transparent);
-    --background: var(--button-light-bg, transparent);
-    --foreground: var(--button-light-fg, var(--link-colour, var(--colour-link)));
+    --line-colour: var(--button-light-line, transparent);
+    --button-bg: var(--button-light-bg, transparent);
+    --button-fg: var(--button-light-fg, var(--colour-link));
 
     text-decoration-line: underline;
 
@@ -27,34 +28,51 @@
   }
 
   .mx-button--accent {
-    --line-colour: var(--button-light-bg, var(--colour-accent));
-    --background: var(--button-light-bg, var(--colour-accent));
+    --line-colour: var(
+      --button-accent-line,
+      light-dark(var(--colour-accent), var(--colour-accent-darkest))
+    );
+    --button-bg: var(
+      --button-accent-bg,
+      light-dark(var(--colour-accent), var(--colour-accent-darkest))
+    );
+    --button-fg: var(--button-accent-bg, var(--colour-foreground));
+
+    color-scheme: var(--button-accent-scheme, light);
 
     &.mx-button--outline {
-      --background: transparent;
-      --foreground: var(--button-light-bg, var(--colour-accent));
+      --button-bg: transparent;
+      --button-fg: var(
+        --button-accent-bg,
+        light-dark(var(--colour-accent), var(--colour-accent-darkest))
+      );
+      --line-colour: var(--button-fg);
+
+      color-scheme: var(--button-accent-scheme-rev, var(--button-accent-scheme, dark));
     }
   }
 
   .mx-button--destructive {
     --line-colour: var(--colour-error);
-    --background: var(--colour-error);
-    --foreground: var(--colour-foreground-reverse);
+    --button-bg: var(--colour-error);
+    --button-fg: var(--colour-foreground-reverse);
 
     &.mx-button--outline {
-      --background: transparent;
-      --foreground: var(--colour-error);
+      --button-bg: transparent;
+      --button-fg: var(--colour-error);
     }
   }
 
   .mx-button--white {
-    --line-colour: var(--colour-foreground-reverse);
-    --background: var(--colour-foreground-reverse);
-    --foreground: var(--colour-foreground);
+    --button-bg: var(--colour-background);
+    --button-fg: var(--colour-foreground);
+    --line-colour: var(--colour-background);
+
+    color-scheme: light;
 
     &.mx-button--outline {
-      --background: transparent;
-      --foreground: var(--colour-foreground-reverse);
+      --button-bg: transparent;
+      --button-fg: var(--colour-foreground-reverse);
     }
   }
 }

package/src/Atom/Button/_buttons.css

@@ -3,6 +3,7 @@
  */
 
 @layer design-system.atoms {
+  /* @public --button-gap --button-font-size */
   .mx-button {
     --outline-offset: 1px;
 
@@ -11,14 +12,14 @@
     gap: var(--button-gap, var(--spacing-s));
     font-size: var(--button-font-size, var(--font-size));
     font-weight: var(--font-weight-bold);
-    font-family: var(--font-family);
+    font-family: var(--font-family), sans-serif;
     line-height: var(--line-height-ui);
     border: var(--line-width, 2px) solid var(--line-colour, currentcolor);
     border-radius: var(--radius, var(--border-radius-l));
     padding-block: var(--vertical-padding, var(--spacing-xxs));
     padding-inline: var(--horizontal-padding, var(--spacing-m));
-    background-color: var(--background, var(--colour-background));
-    color: var(--foreground, var(--colour-foreground));
+    background-color: var(--button-bg, var(--background, var(--colour-background)));
+    color: var(--button-fg, var(--foreground, var(--colour-foreground)));
     text-decoration-line: none;
 
     &:hover {
@@ -53,6 +54,7 @@
     block-size: var(--spacing-xl);
     padding: 0;
     border-radius: var(--border-radius-round);
+    align-content: start;
     overflow: hidden;
     flex-wrap: wrap;
 

package/src/Atom/DefinitionList/DefinitionList.figma.ts

@@ -0,0 +1,26 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=46-13
+// source=src/Atom/DefinitionList/DefinitionList.tsx
+// component=DefinitionList
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+// Resolved dynamically rather than hardcoded — works for however many real
+// DefinitionListItem children this instance actually has.
+const items = instance.findConnectedInstances(
+  node => node.codeConnectId() === "definition-list-item",
+)
+const item1 = items[0]?.executeTemplate().example
+const item2 = items[1]?.executeTemplate().example
+
+export default {
+  example: figma.code`<DefinitionList>
+  ${item1}
+  ${item2}
+</DefinitionList>`,
+  imports: ['import { DefinitionList } from "@pnx-mixtape/mxds/react"'],
+  id: "definition-list",
+  metadata: {
+    nestable: true,
+  },
+}