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

package/src/Atom/Heading/twig/heading-example.twig

@@ -0,0 +1,13 @@
+<div class="mx-headline">Headline: Headliner size</div>
+<h1>Heading xxl: Heading 1</h1>
+<h2>Heading xl: Heading 2</h2>
+<h3>Heading l: Heading 3</h3>
+<h4>Heading m: Heading 4</h4>
+<h5>Heading s: Heading 5</h5>
+<h6>Heading xs: Heading 6</h6>
+
+<h2 class="mx-text--eyebrow mx-text--embellished">Embellished eyebrow</h2>
+<h2 class="mx-text--eyebrow">Normal eyebrow</h2>
+
+<h2 class="mx-text--primary">Text primary: Text classes also apply to headings.</h2>
+<h2 class="mx-background--alt"><span>Background colours can be added combined with headings (and a span) to have inline <u>backgrounds</u> on text.</span></h2>

package/src/Atom/Icon/Icon.figma.ts

@@ -0,0 +1,43 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=47-17
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const size = instance.getEnum("Size", {
+  Small: "IconSizeModifier.SMALL",
+  Medium: "IconSizeModifier.MEDIUM",
+  Large: "IconSizeModifier.LARGE",
+  XLarge: "IconSizeModifier.XLARGE",
+})
+
+// Only the icons already traced as real Figma vectors are resolvable here (Chevron
+// Down, Search, Arrow Left, Arrow Right) — see the component description for why the
+// other 45 Icons enum values aren't wired up yet (real work to do incrementally, not
+// a blocker). `color`/`rotate`/`align` are real code props but aren't modelled as
+// Figma properties on this component (a full crossed variant matrix would be 168
+// combinations for what's fundamentally the same glyph with a layered treatment) —
+// omitted here rather than guessed; see the Colour/Rotate/Align example instances on
+// the Icon page for what they look like.
+const glyph = instance.getInstanceSwap("Glyph")
+let icon = "Icons.CHEVRON_DOWN"
+if (glyph && glyph.type === "INSTANCE") {
+  const id = glyph.codeConnectId()
+  if (id === "icon-chevron-down") icon = "Icons.CHEVRON_DOWN"
+  else if (id === "icon-search") icon = "Icons.SEARCH"
+  else if (id === "icon-arrow-left") icon = "Icons.ARROW_LEFT"
+  else if (id === "icon-arrow-right") icon = "Icons.ARROW_RIGHT"
+}
+
+export default {
+  example: figma.code`<Icon icon={${icon}} size={${size}} />`,
+  imports: [
+    'import { Icon, Icons } from "@pnx-mixtape/mxds/react"',
+    'import { IconSizeModifier } from "@pnx-mixtape/ids-shape"',
+  ],
+  id: "icon",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconArrowLeft.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=43-4
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping.
+export default {
+  example: figma.code`<Icon icon={Icons.ARROW_LEFT} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-arrow-left",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconArrowRight.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=43-7
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping.
+export default {
+  example: figma.code`<Icon icon={Icons.ARROW_RIGHT} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-arrow-right",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconChevronDown.figma.ts

@@ -0,0 +1,18 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=5-4
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// This Figma component is one fixed configuration of the generic Icon component
+// (icon={Icons.CHEVRON_DOWN}), not a standalone code component — Figma models each
+// glyph as a separate swappable component (for INSTANCE_SWAP slots like Button's Icon
+// Start/End), where code has one Icon component parameterised by an enum. Exists mainly
+// so parent templates (Button) can identify which icon is swapped in via codeConnectId().
+export default {
+  example: figma.code`<Icon icon={Icons.CHEVRON_DOWN} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-chevron-down",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconChevronLeft.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=86-7
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping.
+export default {
+  example: figma.code`<Icon icon={Icons.CHEVRON_LEFT} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-chevron-left",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconChevronRight.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=86-4
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping.
+export default {
+  example: figma.code`<Icon icon={Icons.CHEVRON_RIGHT} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-chevron-right",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconError.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=73-11
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping.
+export default {
+  example: figma.code`<Icon icon={Icons.ERROR} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-error",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconExternalLink.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=86-11
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping.
+export default {
+  example: figma.code`<Icon icon={Icons.EXTERNAL} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-external-link",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconInfo.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=73-8
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping.
+export default {
+  example: figma.code`<Icon icon={Icons.INFO} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-info",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconSearch.figma.ts

@@ -0,0 +1,16 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=39-78
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping — one
+// fixed configuration of the generic Icon component, mainly so parent templates
+// (Button) can identify which icon is swapped in via codeConnectId().
+export default {
+  example: figma.code`<Icon icon={Icons.SEARCH} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-search",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconSuccess.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=73-17
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping.
+export default {
+  example: figma.code`<Icon icon={Icons.SUCCESS} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-success",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/IconWarning.figma.ts

@@ -0,0 +1,14 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=73-14
+// source=src/Atom/Icon/Icon.tsx
+// component=Icon
+import figma from "figma"
+
+// See IconChevronDown.figma.ts for why this exists as its own small mapping.
+export default {
+  example: figma.code`<Icon icon={Icons.WARNING} />`,
+  imports: ['import { Icon, Icons } from "@pnx-mixtape/mxds/react"'],
+  id: "icon-warning",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Atom/Icon/README.md

@@ -1,7 +1,124 @@
 # Icon
 
-### How to use
+SVG icons rendered via CSS `mask-image`. Icons are inline with text and inherit `currentcolor` by default. Size, colour, alignment, and rotation are all controlled with modifier classes.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Atom/icon/icon.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Atom/Icon/icon.css";
+```
+
+## Twig
+
+```twig
+{# Icon only #}
+{% include '@mixtape/Atom/Icon/icon.twig' with {
+  icon: 'arrow-right',
+} %}
+
+{# Icon with adjacent text — text is rendered inside the same span #}
+{% include '@mixtape/Atom/Icon/icon.twig' with {
+  icon: 'search',
+  text: 'Search',
+  size: 'lg',
+  color: 'brand',
+} %}
+
+{# Trailing icon (after text) #}
+{% include '@mixtape/Atom/Icon/icon.twig' with {
+  icon: 'chevron-down',
+  align: 'end',
+} %}
+```
+
+**icon.twig props** (`Icon` type from `ids-shape`):
+
+| Prop         | Type                 | Required | Description                                                                  |
+| ------------ | -------------------- | -------- | ---------------------------------------------------------------------------- |
+| `icon`       | `string`             | Yes      | Icon name from the `Icons` enum — added as `mx-icon--{icon}`                 |
+| `text`       | `string`             | No       | Optional text rendered inside the `<span>` alongside the icon                |
+| `align`      | `AlignmentTypes`     | No       | Adds `mx-icon--{align}` (e.g. `end` to place the icon after the text)        |
+| `color`      | `IconColourModifier` | No       | Adds `mx-icon--color-{color}` (e.g. `info`, `brand`, `accent`)               |
+| `rotate`     | `IconRotateModifier` | No       | Adds `mx-icon--{rotate}` (e.g. `rotate-90`, `rotate-180`, `rotate-270`)      |
+| `size`       | `IconSizeModifier`   | No       | Adds `mx-icon--size-{size}` (e.g. `sm`, `md`, `lg`, `xl`)                    |
+| `attributes` | `Attribute`          | No       | Optional Drupal-style attributes object — modifier classes are merged on top |
+
+## HTML
+
+```html
+<span class="mx-icon mx-icon--arrow-right"></span>
+<span class="mx-icon mx-icon--search mx-icon--size-lg mx-icon--color-brand">Search</span>
+```
+
+## React
+
+```tsx
+import { Icon } from "@pnx-mixtape/mxds/react"
+import { Icons } from "../../enums"
+import { IconColourModifier, IconSizeModifier, IconRotateModifier } from "@pnx-mixtape/ids-shape"
+
+<Icon icon={Icons.ARROW_RIGHT} />
+<Icon icon={Icons.SUCCESS} color={IconColourModifier.SUCCESS} size={IconSizeModifier.LARGE} />
+<Icon icon={Icons.CHEVRON_DOWN} text="Expand" />
+```
+
+**Props:** `icon: Icons`, `text?: string`, `color?: IconColourModifier`, `align?: AlignmentTypes`, `rotate?: IconRotateModifier`, `size?: IconSizeModifier`
+
+## Available icons (`Icons` enum)
+
+`arrow-down`, `arrow-left`, `arrow-up`, `arrow-right`, `chevron-down`, `chevron-left`, `chevron-right`, `chevron-up`, `close`, `collapse`, `download`, `drupal`, `error`, `expand`, `external-link`, `facebook`, `google`, `info`, `instagram`, `linkedin`, `mastodon`, `bluesky`, `menu`, `search`, `success`, `twitter`, `warning`, `youtube`, `email`, `file`, `heart-selected`, `heart-unselected`, `link`, `lock`, `login`, `more`, `pencil`, `phone`, `pin`, `print`, `question`, `restart`, `share`, `star-selected`, `star-unselected`, `tick`, `trash`, `user`
+
+## Colour modifiers
+
+| Class                    | `IconColourModifier` enum    | Colour             |
+| ------------------------ | ---------------------------- | ------------------ |
+| `mx-icon--color-info`    | `IconColourModifier.INFO`    | `--colour-info`    |
+| `mx-icon--color-error`   | `IconColourModifier.ERROR`   | `--colour-error`   |
+| `mx-icon--color-warning` | `IconColourModifier.WARNING` | `--colour-warning` |
+| `mx-icon--color-success` | `IconColourModifier.SUCCESS` | `--colour-success` |
+| `mx-icon--color-brand`   | `IconColourModifier.BRAND`   | `--colour-primary` |
+| `mx-icon--color-accent`  | `IconColourModifier.ACCENT`  | `--colour-accent`  |
+
+Without a colour modifier the icon inherits `currentcolor` from its parent.
+
+## Size modifiers
+
+| Class              | `IconSizeModifier` enum   | Size                   |
+| ------------------ | ------------------------- | ---------------------- |
+| `mx-icon--size-sm` | `IconSizeModifier.SMALL`  | `--spacing-s` (1em)    |
+| `mx-icon--size-md` | `IconSizeModifier.MEDIUM` | `--spacing-m` (1.5em)  |
+| `mx-icon--size-lg` | `IconSizeModifier.LARGE`  | `--spacing-l` (2em)    |
+| `mx-icon--size-xl` | `IconSizeModifier.XLARGE` | `--spacing-xl` (2.5em) |
+
+## Rotation modifiers
+
+| Class                 | `IconRotateModifier` enum       | Rotation |
+| --------------------- | ------------------------------- | -------- |
+| `mx-icon--rotate-90`  | `IconRotateModifier.NINETY`     | 90°      |
+| `mx-icon--rotate-180` | `IconRotateModifier.ONEEIGHTY`  | 180°     |
+| `mx-icon--rotate-270` | `IconRotateModifier.TWOSEVENTY` | 270°     |
+
+## Alignment
+
+- `mx-icon--end` — places the icon after the text (default is before)
+
+## Icon-only (no text)
+
+Use `mx-icon--only` for standalone icons with no visible text. Always include an accessible label (e.g. `aria-label` on the parent or a visually-hidden `<span>`).
+
+```html
+<span class="mx-icon mx-icon--close mx-icon--only" aria-label="Close"></span>
+```
+
+## Customisation via CSS custom properties
+
+```css
+.my-component .mx-icon {
+  --icon-size: 3rem;
+  --icon-colour: var(--colour-accent);
+}
+```
+
+---
+
+→ Used in context: `mockups/ArticleListingPage.stories.ts:43`

package/src/Atom/Icon/_icon.css

@@ -27,6 +27,7 @@
   .mx-icon--only {
     inline-size: var(--icon-size, var(--spacing-s));
     block-size: var(--icon-size, var(--spacing-s));
+    align-content: start;
     overflow: hidden;
     flex-wrap: wrap;
 
@@ -75,7 +76,7 @@
   @mixin icon share;
 
   .mx-icon--status::before {
-    mask-image: svg-load("./images/info.svg");
+    mask-image: url("./images/info.svg");
   }
 }
 
@@ -142,19 +143,19 @@
  */
 
 @layer design-system.atoms {
-  .mx-icon--size-sm::before {
+  .mx-icon--size-sm {
     --icon-size: var(--spacing-s);
   }
 
-  .mx-icon--size-md::before {
+  .mx-icon--size-md {
     --icon-size: var(--spacing-m);
   }
 
-  .mx-icon--size-lg::before {
+  .mx-icon--size-lg {
     --icon-size: var(--spacing-l);
   }
 
-  .mx-icon--size-xl::before {
+  .mx-icon--size-xl {
     --icon-size: var(--spacing-xl);
   }
 }

package/src/Atom/Icon/_mixin-icon.css

@@ -1,5 +1,5 @@
 @define-mixin icon $name {
   .mx-icon--$(name)::before {
-    mask-image: svg-load("./images/$(name).svg");
+    mask-image: url("./images/$(name).svg");
   }
 }

package/src/Atom/Image/README.md

@@ -0,0 +1,86 @@
+# Image
+
+Base styles for `<img>`, `<figure>`, and `<figcaption>`. Applied globally — no class required for basic usage. Images are responsive by default (`max-inline-size: 100%`).
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Atom/Image/_image.css";
+```
+
+## Twig
+
+```twig
+{# Plain responsive image #}
+{% include '@mixtape/Atom/Image/image.twig' with {
+  src: '/photo.jpg',
+  alt: 'Description',
+  width: '800',
+  height: '600',
+} %}
+
+{# With responsive <source> alternates #}
+{% include '@mixtape/Atom/Image/image.twig' with {
+  src: '/photo.jpg',
+  alt: 'Description',
+  loading: 'lazy',
+  sources: [
+    { srcset: '/photo.avif', type: 'image/avif', media: '(min-width: 720px)' },
+    { srcset: '/photo.webp', type: 'image/webp' },
+  ],
+} %}
+```
+
+**image.twig props** (`Image` type from `ids-shape`):
+
+| Prop         | Type            | Required | Description                                                                |
+| ------------ | --------------- | -------- | -------------------------------------------------------------------------- |
+| `src`        | `string`        | Yes      | URL for the fallback `<img>`                                               |
+| `alt`        | `string`        | Yes      | Alt text — pass an empty string for decorative images                      |
+| `sources`    | `ImageSource[]` | No       | Each renders a `<source>` element inside the `<picture>` (see below)       |
+| `loading`    | `LoadingTypes`  | No       | `loading` attribute — typically `lazy` or `eager`                          |
+| `width`      | `string`        | No       | `<img>` `width` attribute                                                  |
+| `height`     | `string`        | No       | `<img>` `height` attribute                                                 |
+| `attributes` | `Attribute`     | No       | Optional Drupal-style attributes object applied to the `<picture>` wrapper |
+
+**ImageSource props** (each entry of `sources`):
+
+| Prop     | Type     | Required | Description                                  |
+| -------- | -------- | -------- | -------------------------------------------- |
+| `srcset` | `string` | Yes      | `srcset` attribute on the `<source>` element |
+| `type`   | `string` | Yes      | MIME type, e.g. `image/avif`, `image/webp`   |
+| `media`  | `string` | No       | Media query — only applied when set          |
+
+The template always wraps the image in a `<picture>` element so multiple `sources` can be picked up by the browser before falling back to `src`.
+
+## HTML
+
+```html
+<!-- Responsive image -->
+<img src="photo.jpg" alt="Description" width="800" height="600" />
+
+<!-- With caption -->
+<figure>
+  <img src="photo.jpg" alt="Description" />
+  <figcaption>Caption text appears below the image.</figcaption>
+</figure>
+```
+
+## Notes
+
+- `<figure>` is `display: table` so it shrinks to fit its content width
+- `<figcaption>` uses `caption-side: bottom` and `font-size-xs`
+- `<svg>` without a `fill` attribute inherits `currentcolor`
+
+## Customisation via CSS custom properties
+
+```css
+figcaption {
+  --caption-font-size: var(--font-size-s);
+  --caption-line-height: var(--line-height);
+}
+```
+
+---
+
+→ Used in context: `mockups/ArticleListingPage.stories.ts:14`

package/src/Atom/InlineSvg/README.md

@@ -0,0 +1,65 @@
+# InlineSvg
+
+A Twig template for rendering inline SVG elements, useful for logos and icons that need direct DOM access (e.g. for animation or colour manipulation via CSS).
+
+## Twig
+
+```twig
+{# Meaningful SVG — accessible name comes from `label` or `title` #}
+{% include '@mixtape/Atom/InlineSvg/inline-svg.twig' with {
+  content: svg_string,
+  title: 'Logo',
+  width: '120',
+  height: '40',
+  className: 'my-logo'
+} %}
+
+{# Decorative SVG — omit both `title` and `label` #}
+{% include '@mixtape/Atom/InlineSvg/inline-svg.twig' with {
+  content: divider_svg_string,
+  className: 'my-divider'
+} %}
+```
+
+**Props:**
+
+| Prop                         | Type     | Description                                                                                                          |
+| ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
+| `content`                    | `string` | Raw SVG markup (paths, groups, etc.) — required                                                                      |
+| `title`                      | `string` | Tooltip text rendered as a `<title>` child of the SVG. Also used as the accessible name if `label` is not set        |
+| `label`                      | `string` | Explicit `aria-label`. Use when you want the visible tooltip and the accessible name to differ — `label` wins for AT |
+| `width`, `height`, `viewBox` | `string` | Sizing attributes                                                                                                    |
+| `className`                  | `string` | Extra class on the `<svg>`                                                                                           |
+
+## HTML
+
+```html
+<!-- With title or label -->
+<svg
+  class="my-logo"
+  width="120"
+  height="40"
+  role="img"
+  aria-label="Logo"
+  xmlns="http://www.w3.org/2000/svg"
+>
+  <!-- SVG content -->
+  <title>Logo</title>
+</svg>
+
+<!-- Decorative (no title, no label) -->
+<svg class="my-divider" aria-hidden="true" xmlns="http://www.w3.org/2000/svg">
+  <!-- SVG content -->
+</svg>
+```
+
+## Accessibility
+
+- When `label` or `title` is provided, the template sets `role="img"` plus `aria-label="{label or title}"` on the `<svg>` so the SVG is announced by AT as a single labelled image.
+- When neither is provided, the template sets `aria-hidden="true"` — treat the SVG as decorative.
+- The inline `<title>` element remains as a hover tooltip / fallback for environments without strong SVG ARIA support; `aria-label` takes precedence as the accessible name.
+
+## Notes
+
+- Use `InlineSvg` over `<img>` when the SVG needs to respond to `currentcolor` (e.g. logo that changes with colour scheme)
+- In React, use `<img>` or a raw `<svg>` import — there is no React component for InlineSvg

package/src/Atom/InlineSvg/inline-svg.twig

@@ -16,6 +16,14 @@
   {% set attributes = attributes.setAttribute('viewBox', viewBox) %}
 {% endif %}
 
+{% if label is not empty or title is not empty %}
+  {% set attributes = attributes
+    .setAttribute('role', 'img')
+    .setAttribute('aria-label', label ?: title) %}
+{% else %}
+  {% set attributes = attributes.setAttribute('aria-hidden', 'true') %}
+{% endif %}
+
 <svg {{ attributes }} xmlns="http://www.w3.org/2000/svg">
   {{ content }}
   {% if title %}

package/src/Atom/Link/Link.figma.ts

@@ -0,0 +1,59 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=87-26
+// source=src/Atom/Link/Link.tsx
+// component=Link
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const more = instance.getEnum("More", { Off: false, On: true })
+const content = instance.getSlot("Content")
+
+// `Icon Start`/`Icon End` are Button-style INSTANCE_SWAP properties added for
+// designers — Link has NO iconStart/iconEnd prop in code at all. Icon End
+// resolving to Icon/External Link maps to the one real, exact correspondence
+// (`external`, via .mx-link--external::after). Any other icon choice (Icon Start
+// always, or a different Icon End) has no dedicated prop — real usage achieves it
+// via a plain className (see InPageNavigation.tsx: className="mx-icon mx-icon--
+// chevron-right"), so it's emitted as a className, not invented as a prop.
+function resolveIcon(propName) {
+  const swapped = instance.getInstanceSwap(propName)
+  if (!swapped || swapped.type !== "INSTANCE") return null
+  const id = swapped.codeConnectId()
+  const map = {
+    "icon-chevron-down": "chevron-down",
+    "icon-chevron-right": "chevron-right",
+    "icon-chevron-left": "chevron-left",
+    "icon-search": "search",
+    "icon-arrow-left": "arrow-left",
+    "icon-arrow-right": "arrow-right",
+    "icon-external-link": "external-link",
+    "icon-info": "info",
+    "icon-error": "error",
+    "icon-warning": "warning",
+    "icon-success": "success",
+  }
+  return map[id] ?? null
+}
+
+const showIconStart = instance.getBoolean("Show Icon Start")
+const showIconEnd = instance.getBoolean("Show Icon End")
+const iconStartSlug = showIconStart ? resolveIcon("Icon Start") : null
+const iconEndSlug = showIconEnd ? resolveIcon("Icon End") : null
+
+const isExternal = iconEndSlug === "external-link"
+
+const classNameSlugs = [iconStartSlug, isExternal ? null : iconEndSlug].filter(Boolean)
+const classNameProp = classNameSlugs.length
+  ? ` className="mx-icon ${classNameSlugs.map(s => `mx-icon--${s}`).join(" ")}"`
+  : ""
+const moreProp = more ? " more" : ""
+const externalProp = isExternal ? " external" : ""
+
+export default {
+  example: figma.code`<Link to="#"${moreProp}${externalProp}${classNameProp}>${content}</Link>`,
+  imports: ['import { Link } from "@pnx-mixtape/mxds/react"'],
+  id: "link",
+  metadata: {
+    nestable: true,
+  },
+}