@pithyjs/ui-kit 0.1.0-beta.0

package/dist/organisms/content/Card.js

@@ -0,0 +1,353 @@
+/** @codex
+{
+  "id": "pithy.ui-kit.card",
+  "title": "<Card> Organism",
+  "category": "feature",
+  "risk": "medium"
+}
+*/
+import { captureChildren } from '@pithyjs/core';
+import { effect } from '@pithyjs/signals';
+import { isSafeHref, sanitizeHref } from '@pithyjs/shared';
+import { cleanupRouterDirectives } from '@pithyjs/router';
+import { captureSlot, extractSlot } from '../../shared/slots';
+import { generateSectionHeadingId, validateEnum } from '../../shared/section';
+import { ORIENTATIONS } from '../../shared/types';
+import { CARD_VARIANTS, CARD_PADDINGS, CARD_RADII, CARD_MEDIA_ASPECTS, } from '../../shared/card';
+// -- Helpers ------------------------------------------------------------------
+function firstHeadingIn(root) {
+    if (!root)
+        return null;
+    return root.querySelector('h1, h2, h3, h4, h5, h6');
+}
+function wrapSlot(name, className, tag, fragment) {
+    if (!fragment)
+        return null;
+    // If the user projected a single element whose tag already matches our
+    // target (e.g. `<footer data-slot="footer">`), reuse it instead of
+    // wrapping — otherwise the flex container would wrap a block child and
+    // lose all layout. `<template data-slot="...">` always falls through to
+    // the wrapper since extractSlot unpacks its content, and a mismatched
+    // tag (e.g. `<div data-slot="footer">`) is wrapped so the semantic tag
+    // we advertise is preserved.
+    const only = fragment.children.length === 1 && fragment.childNodes.length === 1
+        ? fragment.firstElementChild
+        : null;
+    if (only && only.tagName.toLowerCase() === tag) {
+        only.classList.add(className);
+        captureSlot(only, name);
+        return only;
+    }
+    const wrapper = document.createElement(tag);
+    wrapper.classList.add(className);
+    captureSlot(wrapper, name);
+    wrapper.appendChild(fragment);
+    return wrapper;
+}
+// -- Component ----------------------------------------------------------------
+/**
+ * Content container with named slots (`media`, `header`, default = body,
+ * `footer`), five variants, orientation, and a pseudo-link pattern that
+ * lets the whole card act as a navigation target without sacrificing
+ * interactive children.
+ *
+ * @example
+ * ```html
+ * <Card variant="'elevated'" clickable="true" href="'/post/hello'">
+ *   <img data-slot="media" src="/hero.jpg" alt="">
+ *   <header data-slot="header">
+ *     <Heading level="3">Hello world</Heading>
+ *   </header>
+ *   <Text>A short excerpt…</Text>
+ *   <footer data-slot="footer">
+ *     <Text color="'text-muted'" size="'sm'">3 min read</Text>
+ *   </footer>
+ * </Card>
+ * ```
+ */
+/** @codexApi {"parent":"pithy.ui-kit.card","name":"Card","stability":"stable","signature":"(props?: CardProps) => { el: HTMLElement; destroy: () => void }"} */
+export function Card(props = {}) {
+    const { variant: rawVariant = 'default', padding: rawPadding = 'md', radius: rawRadius = 'md', orientation: rawOrientation = 'vertical', mediaOverlay = false, clickable = false, href, linkLabel: rawLinkLabel, disabled = false, selected = false, eyebrow, ariaLabel: rawAriaLabel, ariaLabelledBy: rawAriaLabelledBy, id, } = props;
+    // Whitespace-only labels would set an effectively empty accessible name
+    // and silently bypass the heading fallback. Trim once and treat empty
+    // strings as absent — same pattern as <Button>.
+    const ariaLabel = rawAriaLabel?.trim() || undefined;
+    const linkLabel = rawLinkLabel?.trim() || undefined;
+    const ariaLabelledBy = rawAriaLabelledBy?.trim() || undefined;
+    if (import.meta.env?.DEV) {
+        if (rawAriaLabel != null && !ariaLabel) {
+            console.warn('[<Card>] `ariaLabel` was empty or whitespace-only; falling back to heading / ariaLabelledBy / linkLabel.');
+        }
+        if (rawLinkLabel != null && !linkLabel) {
+            console.warn('[<Card>] `linkLabel` was empty or whitespace-only; falling back to heading / ariaLabelledBy / ariaLabel.');
+        }
+        if (rawAriaLabelledBy != null && !ariaLabelledBy) {
+            console.warn('[<Card>] `ariaLabelledBy` was whitespace-only; falling back to heading / ariaLabel / linkLabel.');
+        }
+    }
+    // Destructure defaults first so undefined props skip validateEnum's warning path.
+    const variant = validateEnum('Card', 'variant', rawVariant, CARD_VARIANTS, 'default');
+    const padding = validateEnum('Card', 'padding', rawPadding, CARD_PADDINGS, 'md');
+    const radius = validateEnum('Card', 'radius', rawRadius, CARD_RADII, 'md');
+    const orientation = validateEnum('Card', 'orientation', rawOrientation, ORIENTATIONS, 'vertical');
+    // Horizontal thumbnails need a predictable aspect ratio or lists get janky.
+    const resolvedMediaAspect = props.mediaAspect &&
+        CARD_MEDIA_ASPECTS.includes(props.mediaAspect)
+        ? props.mediaAspect
+        : orientation === 'horizontal'
+            ? '16/9'
+            : undefined;
+    if (import.meta.env?.DEV) {
+        if (clickable && !href) {
+            console.warn('[<Card>] `clickable` requires `href`. The card will render without the stretched link overlay.');
+        }
+        if (!clickable && href) {
+            console.warn("[<Card>] `href` is ignored when `clickable` is false. Set `clickable='true'` to activate the link overlay.");
+        }
+        if (props.mediaAspect &&
+            !CARD_MEDIA_ASPECTS.includes(props.mediaAspect)) {
+            console.warn(`[<Card>] Invalid mediaAspect: "${props.mediaAspect}". Expected one of: ${CARD_MEDIA_ASPECTS.join(', ')}.`);
+        }
+        // Runtime guard for the site builder's untyped prop bag — TS consumers
+        // can't reach this, but JSON-driven rendering can.
+        if (typeof props.onClick === 'function') {
+            console.warn("[<Card>] `onClick` is not supported in V0.1. Use `clickable='true'` + `href` for navigation, or nest a <Button onClick=...> inside the footer slot. A first-class onClick card lands in V0.2.");
+        }
+    }
+    // Sanitize before both validating and assigning so the rendered URL is
+    // exactly what isSafeHref() checked — control-char / whitespace bypass
+    // surfaces disappear.
+    const normalizedHref = typeof href === 'string' ? sanitizeHref(href) : '';
+    const safeHref = clickable && normalizedHref && isSafeHref(normalizedHref)
+        ? normalizedHref
+        : null;
+    if (import.meta.env?.DEV && clickable && href && !safeHref) {
+        if (!normalizedHref) {
+            console.warn(`[<Card>] \`href\` was empty or whitespace-only after sanitization; the card will not be clickable.`);
+        }
+        else {
+            console.warn(`[<Card>] Unsafe href rejected: "${normalizedHref}". Only http(s), mailto, tel, fragment-only (#...), query-only (?...), and relative URLs (/..., ./..., ../...) are allowed.`);
+        }
+    }
+    const disposers = [];
+    // Capture projected children before any inner components render — mirrors
+    // the Navbar/section-template pattern. Named nodes are re-homed into slot
+    // wrappers below; anything left in the fragment becomes the default body.
+    const { el: childFragment, destroy: destroyChildren } = captureChildren();
+    disposers.push(destroyChildren);
+    const article = document.createElement('article');
+    article.classList.add('ui-card');
+    article.dataset.variant = variant;
+    article.dataset.padding = padding;
+    article.dataset.radius = radius;
+    article.dataset.orientation = orientation;
+    if (clickable && safeHref)
+        article.dataset.clickable = 'true';
+    if (mediaOverlay)
+        article.dataset.mediaOverlay = 'true';
+    if (id)
+        article.id = id;
+    // Reactive `selected` + `disabled`: follow Button's pattern — accept a
+    // boolean or a `() => boolean` getter. A function triggers an effect;
+    // a literal bakes in once.
+    const readDisabled = () => typeof disabled === 'function' ? disabled() : disabled;
+    const readSelected = () => typeof selected === 'function' ? selected() : selected;
+    const isReactive = typeof disabled === 'function' || typeof selected === 'function';
+    const applyState = () => {
+        const isDisabled = readDisabled();
+        const isSelected = readSelected();
+        if (isDisabled) {
+            article.dataset.disabled = 'true';
+            article.setAttribute('aria-disabled', 'true');
+            // `inert` blocks focus, clicks, and AT on every descendant.
+            article.setAttribute('inert', '');
+        }
+        else {
+            delete article.dataset.disabled;
+            article.removeAttribute('aria-disabled');
+            article.removeAttribute('inert');
+        }
+        if (isSelected) {
+            article.dataset.selected = 'true';
+        }
+        else {
+            delete article.dataset.selected;
+        }
+        // aria-current only has meaning in a navigation context, which disabled
+        // removes — keep the existing (non-reactive) gate on clickable && safeHref.
+        if (isSelected && clickable && safeHref && !isDisabled) {
+            article.setAttribute('aria-current', 'true');
+        }
+        else {
+            article.removeAttribute('aria-current');
+        }
+    };
+    if (isReactive) {
+        disposers.push(effect(applyState));
+    }
+    else {
+        applyState();
+    }
+    // An element can't @container-query itself, so layout lives on a child.
+    // See card.scss for the chrome/query-container split.
+    const layout = document.createElement('div');
+    layout.classList.add('ui-card-layout');
+    captureSlot(layout, 'default');
+    article.appendChild(layout);
+    // Slots — order is significant: media comes first so it can bleed when
+    // padding=none, then header/body/footer.
+    const mediaFragment = extractSlot(childFragment, 'media');
+    const mediaWrapper = wrapSlot('media', 'ui-card-media', 'div', mediaFragment);
+    if (mediaWrapper && resolvedMediaAspect) {
+        mediaWrapper.dataset.aspect = resolvedMediaAspect;
+    }
+    if (mediaWrapper)
+        layout.appendChild(mediaWrapper);
+    const headerFragment = extractSlot(childFragment, 'header');
+    let headerWrapper = wrapSlot('header', 'ui-card-header', 'header', headerFragment);
+    // If no header slot was projected, create one so the eyebrow has a home.
+    // Mirrors the Hero / CTA section eyebrow pattern.
+    if (typeof eyebrow === 'string' && eyebrow.trim().length > 0) {
+        const eyebrowEl = document.createElement('span');
+        eyebrowEl.classList.add('ui-card-eyebrow');
+        eyebrowEl.textContent = eyebrow.trim();
+        if (!headerWrapper) {
+            headerWrapper = document.createElement('header');
+            headerWrapper.classList.add('ui-card-header');
+            captureSlot(headerWrapper, 'header');
+        }
+        headerWrapper.prepend(eyebrowEl);
+    }
+    if (headerWrapper)
+        layout.appendChild(headerWrapper);
+    // Extract footer BEFORE the body collapse — otherwise the body scoop below
+    // would swallow footer nodes along with the default content.
+    const footerFragment = extractSlot(childFragment, 'footer');
+    const footerWrapper = wrapSlot('footer', 'ui-card-footer', 'footer', footerFragment);
+    // Skip the wrapper when empty so media+footer-only cards don't carry a
+    // vestigial element.
+    const remainingHasContent = childFragment.childNodes.length > 0 &&
+        Array.from(childFragment.childNodes).some(n => n.nodeType !== Node.TEXT_NODE || (n.textContent ?? '').trim().length > 0);
+    if (remainingHasContent) {
+        const body = document.createElement('div');
+        body.classList.add('ui-card-body');
+        body.appendChild(childFragment);
+        layout.appendChild(body);
+    }
+    if (footerWrapper)
+        layout.appendChild(footerWrapper);
+    // Overlay mode collapses header/body/footer into one caption group so
+    // the scrim, inverse text, and block-end anchoring share a positioning
+    // context. Media stays at z-index 0.
+    if (mediaOverlay) {
+        const caption = document.createElement('div');
+        caption.classList.add('ui-card-caption');
+        const nodesToMove = Array.from(layout.children).filter(c => c.classList.contains('ui-card-header') ||
+            c.classList.contains('ui-card-body') ||
+            c.classList.contains('ui-card-footer'));
+        for (const node of nodesToMove)
+            caption.appendChild(node);
+        // Only add the caption if it actually has content — an image-only card
+        // with `mediaOverlay` is still a valid configuration.
+        if (caption.children.length > 0)
+            layout.appendChild(caption);
+    }
+    // Accessible name fallback chain:
+    //   ariaLabelledBy > clickable heading (auto-id) > heading (auto-id)
+    //   > ariaLabel > linkLabel > DEV warning
+    // Non-clickable cards with headings also get aria-labelledby so screen
+    // readers announce "article, <heading text>" instead of bare "article".
+    const heading = firstHeadingIn(headerWrapper);
+    if (ariaLabelledBy) {
+        article.setAttribute('aria-labelledby', ariaLabelledBy);
+    }
+    else if (clickable && safeHref) {
+        if (heading) {
+            if (!heading.id)
+                heading.id = generateSectionHeadingId('card', id);
+            article.setAttribute('aria-labelledby', heading.id);
+        }
+        else if (ariaLabel) {
+            article.setAttribute('aria-label', ariaLabel);
+        }
+        else if (linkLabel) {
+            article.setAttribute('aria-label', linkLabel);
+        }
+        else if (import.meta.env?.DEV) {
+            console.warn('[<Card>] Clickable card has no accessible name. Add a heading in the header slot, or pass `ariaLabel` / `ariaLabelledBy`.');
+        }
+    }
+    else if (heading) {
+        if (!heading.id)
+            heading.id = generateSectionHeadingId('card', id);
+        article.setAttribute('aria-labelledby', heading.id);
+    }
+    else if (ariaLabel) {
+        article.setAttribute('aria-label', ariaLabel);
+    }
+    // Pseudo-link overlay — absolute anchor at z-index 1 covers the card for
+    // hit-testing. Interactive descendants (buttons/inner links) are raised
+    // above it via a :is() rule in card.scss so they stay clickable.
+    if (clickable && safeHref) {
+        const overlay = document.createElement('a');
+        overlay.classList.add('ui-card-link');
+        overlay.href = safeHref;
+        overlay.setAttribute('data-router-link', '');
+        overlay.setAttribute('data-prefetch', 'none');
+        disposers.push(() => cleanupRouterDirectives(overlay));
+        if (linkLabel) {
+            overlay.setAttribute('aria-label', linkLabel);
+        }
+        else if (ariaLabelledBy) {
+            // Honour the explicit override — keeps article + overlay names in sync.
+            overlay.setAttribute('aria-labelledby', ariaLabelledBy);
+        }
+        else if (heading) {
+            // Reference the heading id so the link name stays in sync with reactive
+            // heading text — snapshotting textContent would freeze a stale name.
+            if (!heading.id)
+                heading.id = generateSectionHeadingId('card', id);
+            overlay.setAttribute('aria-labelledby', heading.id);
+        }
+        else if (ariaLabel) {
+            overlay.setAttribute('aria-label', ariaLabel);
+        }
+        else {
+            // Last-resort visually-hidden label so the link always has an
+            // accessible name even when heading and labels are absent.
+            const sr = document.createElement('span');
+            sr.classList.add('ui-card-link-label');
+            sr.textContent = 'Open';
+            overlay.appendChild(sr);
+        }
+        article.appendChild(overlay);
+    }
+    // Interactive-by-content: a non-clickable card that contains a focusable
+    // descendant (button, inner link, form control) still participates in the
+    // hover/focus-within lift. Tagged at mount so the SCSS can rely on a plain
+    // attribute selector rather than `:has()` inside `:where()` (which has
+    // uneven browser behaviour today).
+    if (!article.dataset.clickable) {
+        const focusable = article.querySelector('a, button, input, select, textarea, [role="button"], [tabindex]:not([tabindex="-1"])');
+        if (focusable)
+            article.dataset.interactive = 'true';
+    }
+    return {
+        el: article,
+        destroy: () => {
+            for (const dispose of disposers) {
+                try {
+                    dispose();
+                }
+                catch (err) {
+                    if (import.meta.env?.DEV) {
+                        console.error('[<Card>] disposer threw:', err);
+                    }
+                }
+            }
+            disposers.length = 0;
+            article.replaceChildren();
+        },
+    };
+}
+//# sourceMappingURL=Card.js.map

package/dist/organisms/content/Card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Card.js","sourceRoot":"","sources":["../../../src/organisms/content/Card.ts"],"names":[],"mappings":"AAAA;;;;;;;EAOE;AAEF,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,YAAY,EAAoB,MAAM,oBAAoB,CAAC;AACpE,OAAO,EACL,aAAa,EACb,aAAa,EACb,UAAU,EACV,kBAAkB,GAKnB,MAAM,mBAAmB,CAAC;AA8D3B,gFAAgF;AAEhF,SAAS,cAAc,CACrB,IAA2C;IAE3C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,OAAO,IAAI,CAAC,aAAa,CAAC,wBAAwB,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,QAAQ,CACf,IAAY,EACZ,SAAiB,EACjB,GAAgC,EAChC,QAAiC;IAEjC,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,uEAAuE;IACvE,mEAAmE;IACnE,uEAAuE;IACvE,wEAAwE;IACxE,sEAAsE;IACtE,uEAAuE;IACvE,6BAA6B;IAC7B,MAAM,IAAI,GACR,QAAQ,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC;QAChE,CAAC,CAAC,QAAQ,CAAC,iBAAiB;QAC5B,CAAC,CAAC,IAAI,CAAC;IACX,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,KAAK,GAAG,EAAE,CAAC;QAC/C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC9B,WAAW,CAAC,IAAmB,EAAE,IAAI,CAAC,CAAC;QACvC,OAAO,IAAmB,CAAC;IAC7B,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;IAC5C,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACjC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC3B,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC9B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,gFAAgF;AAEhF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,gKAAgK;AAChK,MAAM,UAAU,IAAI,CAAC,QAAmB,EAAE;IAIxC,MAAM,EACJ,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,OAAO,EAAE,UAAU,GAAG,IAAI,EAC1B,MAAM,EAAE,SAAS,GAAG,IAAI,EACxB,WAAW,EAAE,cAAc,GAAG,UAAU,EACxC,YAAY,GAAG,KAAK,EACpB,SAAS,GAAG,KAAK,EACjB,IAAI,EACJ,SAAS,EAAE,YAAY,EACvB,QAAQ,GAAG,KAAK,EAChB,QAAQ,GAAG,KAAK,EAChB,OAAO,EACP,SAAS,EAAE,YAAY,EACvB,cAAc,EAAE,iBAAiB,EACjC,EAAE,GACH,GAAG,KAAK,CAAC;IAEV,wEAAwE;IACxE,sEAAsE;IACtE,gDAAgD;IAChD,MAAM,SAAS,GAAG,YAAY,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACpD,MAAM,SAAS,GAAG,YAAY,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IACpD,MAAM,cAAc,GAAG,iBAAiB,EAAE,IAAI,EAAE,IAAI,SAAS,CAAC;IAC9D,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;QACzB,IAAI,YAAY,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACvC,OAAO,CAAC,IAAI,CACV,0GAA0G,CAC3G,CAAC;QACJ,CAAC;QACD,IAAI,YAAY,IAAI,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACvC,OAAO,CAAC,IAAI,CACV,0GAA0G,CAC3G,CAAC;QACJ,CAAC;QACD,IAAI,iBAAiB,IAAI,IAAI,IAAI,CAAC,cAAc,EAAE,CAAC;YACjD,OAAO,CAAC,IAAI,CACV,iGAAiG,CAClG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,kFAAkF;IAClF,MAAM,OAAO,GAAG,YAAY,CAC1B,MAAM,EACN,SAAS,EACT,UAAU,EACV,aAAa,EACb,SAAS,CACV,CAAC;IACF,MAAM,OAAO,GAAG,YAAY,CAC1B,MAAM,EACN,SAAS,EACT,UAAU,EACV,aAAa,EACb,IAAI,CACL,CAAC;IACF,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;IAC3E,MAAM,WAAW,GAAG,YAAY,CAC9B,MAAM,EACN,aAAa,EACb,cAAc,EACd,YAAY,EACZ,UAAU,CACX,CAAC;IAEF,4EAA4E;IAC5E,MAAM,mBAAmB,GACvB,KAAK,CAAC,WAAW;QAChB,kBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC;QACnE,CAAC,CAAC,KAAK,CAAC,WAAW;QACnB,CAAC,CAAC,WAAW,KAAK,YAAY;YAC5B,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,SAAS,CAAC;IAElB,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;QACzB,IAAI,SAAS,IAAI,CAAC,IAAI,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CACV,gGAAgG,CACjG,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;YACvB,OAAO,CAAC,IAAI,CACV,4GAA4G,CAC7G,CAAC;QACJ,CAAC;QACD,IACE,KAAK,CAAC,WAAW;YACjB,CAAE,kBAAwC,CAAC,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,EACtE,CAAC;YACD,OAAO,CAAC,IAAI,CACV,kCAAkC,KAAK,CAAC,WAAW,uBAAuB,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAC3G,CAAC;QACJ,CAAC;QACD,uEAAuE;QACvE,mDAAmD;QACnD,IAAI,OAAQ,KAA+B,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;YACnE,OAAO,CAAC,IAAI,CACV,+LAA+L,CAChM,CAAC;QACJ,CAAC;IACH,CAAC;IAED,uEAAuE;IACvE,uEAAuE;IACvE,sBAAsB;IACtB,MAAM,cAAc,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1E,MAAM,QAAQ,GACZ,SAAS,IAAI,cAAc,IAAI,UAAU,CAAC,cAAc,CAAC;QACvD,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,IAAI,CAAC;IAEX,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,SAAS,IAAI,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAC3D,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,OAAO,CAAC,IAAI,CACV,oGAAoG,CACrG,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CACV,mCAAmC,cAAc,6HAA6H,CAC/K,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAsB,EAAE,CAAC;IAExC,0EAA0E;IAC1E,0EAA0E;IAC1E,0EAA0E;IAC1E,MAAM,EAAE,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,eAAe,EAAE,CAAC;IAC1E,SAAS,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAEhC,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;IAClD,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACjC,OAAO,CAAC,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC;IAClC,OAAO,CAAC,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC;IAClC,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC;IAChC,OAAO,CAAC,OAAO,CAAC,WAAW,GAAG,WAAW,CAAC;IAC1C,IAAI,SAAS,IAAI,QAAQ;QAAE,OAAO,CAAC,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC;IAC9D,IAAI,YAAY;QAAE,OAAO,CAAC,OAAO,CAAC,YAAY,GAAG,MAAM,CAAC;IACxD,IAAI,EAAE;QAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAExB,uEAAuE;IACvE,sEAAsE;IACtE,2BAA2B;IAC3B,MAAM,YAAY,GAAG,GAAG,EAAE,CACxB,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IACzD,MAAM,YAAY,GAAG,GAAG,EAAE,CACxB,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IACzD,MAAM,UAAU,GACd,OAAO,QAAQ,KAAK,UAAU,IAAI,OAAO,QAAQ,KAAK,UAAU,CAAC;IAEnE,MAAM,UAAU,GAAG,GAAG,EAAE;QACtB,MAAM,UAAU,GAAG,YAAY,EAAE,CAAC;QAClC,MAAM,UAAU,GAAG,YAAY,EAAE,CAAC;QAElC,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,CAAC,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC;YAClC,OAAO,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;YAC9C,4DAA4D;YAC5D,OAAO,CAAC,YAAY,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACpC,CAAC;aAAM,CAAC;YACN,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;YAChC,OAAO,CAAC,eAAe,CAAC,eAAe,CAAC,CAAC;YACzC,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QACnC,CAAC;QAED,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,CAAC,OAAO,CAAC,QAAQ,GAAG,MAAM,CAAC;QACpC,CAAC;aAAM,CAAC;YACN,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC;QAClC,CAAC;QAED,wEAAwE;QACxE,4EAA4E;QAC5E,IAAI,UAAU,IAAI,SAAS,IAAI,QAAQ,IAAI,CAAC,UAAU,EAAE,CAAC;YACvD,OAAO,CAAC,YAAY,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QAC/C,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC;QAC1C,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,UAAU,EAAE,CAAC;QACf,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;IACrC,CAAC;SAAM,CAAC;QACN,UAAU,EAAE,CAAC;IACf,CAAC;IAED,wEAAwE;IACxE,sDAAsD;IACtD,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IAC7C,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACvC,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC/B,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAE5B,uEAAuE;IACvE,yCAAyC;IACzC,MAAM,aAAa,GAAG,WAAW,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;IAC1D,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC;IAC9E,IAAI,YAAY,IAAI,mBAAmB,EAAE,CAAC;QACxC,YAAY,CAAC,OAAO,CAAC,MAAM,GAAG,mBAAmB,CAAC;IACpD,CAAC;IACD,IAAI,YAAY;QAAE,MAAM,CAAC,WAAW,CAAC,YAAY,CAAC,CAAC;IAEnD,MAAM,cAAc,GAAG,WAAW,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IAC5D,IAAI,aAAa,GAAG,QAAQ,CAC1B,QAAQ,EACR,gBAAgB,EAChB,QAAQ,EACR,cAAc,CACf,CAAC;IAEF,yEAAyE;IACzE,kDAAkD;IAClD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7D,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;QACjD,SAAS,CAAC,SAAS,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;QAC3C,SAAS,CAAC,WAAW,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;QACvC,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,aAAa,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;YACjD,aAAa,CAAC,SAAS,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;YAC9C,WAAW,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;QACvC,CAAC;QACD,aAAa,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,aAAa;QAAE,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;IAErD,2EAA2E;IAC3E,6DAA6D;IAC7D,MAAM,cAAc,GAAG,WAAW,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;IAC5D,MAAM,aAAa,GAAG,QAAQ,CAC5B,QAAQ,EACR,gBAAgB,EAChB,QAAQ,EACR,cAAc,CACf,CAAC;IAEF,uEAAuE;IACvE,qBAAqB;IACrB,MAAM,mBAAmB,GACvB,aAAa,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC,IAAI,CACvC,CAAC,CAAC,EAAE,CACF,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAC3E,CAAC;IACJ,IAAI,mBAAmB,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACnC,IAAI,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;QAChC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,aAAa;QAAE,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC;IAErD,sEAAsE;IACtE,uEAAuE;IACvE,qCAAqC;IACrC,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAC9C,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;QACzC,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CACpD,CAAC,CAAC,EAAE,CACF,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC;YACtC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC;YACpC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CACzC,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,WAAW;YAAE,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC1D,uEAAuE;QACvE,sDAAsD;QACtD,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC/D,CAAC;IAED,kCAAkC;IAClC,qEAAqE;IACrE,0CAA0C;IAC1C,uEAAuE;IACvE,wEAAwE;IACxE,MAAM,OAAO,GAAG,cAAc,CAAC,aAAa,CAAC,CAAC;IAC9C,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,CAAC,YAAY,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAC;IAC1D,CAAC;SAAM,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;QACjC,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,CAAC,OAAO,CAAC,EAAE;gBAAE,OAAO,CAAC,EAAE,GAAG,wBAAwB,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACnE,OAAO,CAAC,YAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACtD,CAAC;aAAM,IAAI,SAAS,EAAE,CAAC;YACrB,OAAO,CAAC,YAAY,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAChD,CAAC;aAAM,IAAI,SAAS,EAAE,CAAC;YACrB,OAAO,CAAC,YAAY,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAChD,CAAC;aAAM,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;YAChC,OAAO,CAAC,IAAI,CACV,2HAA2H,CAC5H,CAAC;QACJ,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,EAAE,CAAC;QACnB,IAAI,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,GAAG,wBAAwB,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACnE,OAAO,CAAC,YAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;SAAM,IAAI,SAAS,EAAE,CAAC;QACrB,OAAO,CAAC,YAAY,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IAChD,CAAC;IAED,yEAAyE;IACzE,wEAAwE;IACxE,iEAAiE;IACjE,IAAI,SAAS,IAAI,QAAQ,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,QAAQ,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QAC5C,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QACtC,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC;QACxB,OAAO,CAAC,YAAY,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC;QAC7C,OAAO,CAAC,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;QAC9C,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC;QACvD,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,CAAC,YAAY,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAChD,CAAC;aAAM,IAAI,cAAc,EAAE,CAAC;YAC1B,wEAAwE;YACxE,OAAO,CAAC,YAAY,CAAC,iBAAiB,EAAE,cAAc,CAAC,CAAC;QAC1D,CAAC;aAAM,IAAI,OAAO,EAAE,CAAC;YACnB,wEAAwE;YACxE,qEAAqE;YACrE,IAAI,CAAC,OAAO,CAAC,EAAE;gBAAE,OAAO,CAAC,EAAE,GAAG,wBAAwB,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACnE,OAAO,CAAC,YAAY,CAAC,iBAAiB,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;QACtD,CAAC;aAAM,IAAI,SAAS,EAAE,CAAC;YACrB,OAAO,CAAC,YAAY,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,8DAA8D;YAC9D,2DAA2D;YAC3D,MAAM,EAAE,GAAG,QAAQ,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;YAC1C,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;YACvC,EAAE,CAAC,WAAW,GAAG,MAAM,CAAC;YACxB,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED,yEAAyE;IACzE,0EAA0E;IAC1E,2EAA2E;IAC3E,uEAAuE;IACvE,mCAAmC;IACnC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;QAC/B,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CACrC,sFAAsF,CACvF,CAAC;QACF,IAAI,SAAS;YAAE,OAAO,CAAC,OAAO,CAAC,WAAW,GAAG,MAAM,CAAC;IACtD,CAAC;IAED,OAAO;QACL,EAAE,EAAE,OAAO;QACX,OAAO,EAAE,GAAG,EAAE;YACZ,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;gBAChC,IAAI,CAAC;oBACH,OAAO,EAAE,CAAC;gBACZ,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC;wBACzB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,GAAG,CAAC,CAAC;oBACjD,CAAC;gBACH,CAAC;YACH,CAAC;YACD,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;YACrB,OAAO,CAAC,eAAe,EAAE,CAAC;QAC5B,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/organisms/content/_card-horizontal.scss

@@ -0,0 +1,88 @@
+/// Card horizontal orientation — @container upgrade
+/// @group organisms/content
+
+@use 'card-tokens' as tokens;
+
+// ============================================
+// Horizontal orientation — mobile-first @container upgrade
+// ============================================
+//
+// Below $card-horizontal-min the layout stays vertical (base rules win).
+// At or above the threshold, horizontal cards switch the layout element
+// to a 2-column grid: media spans the full block-size on the inline-start,
+// header/body/footer stack on the inline-end.
+
+@container (min-inline-size: #{tokens.$card-horizontal-min}) {
+  .ui-card[data-orientation='horizontal'] > .ui-card-layout {
+    display: grid;
+    grid-template-columns:
+      clamp(
+        #{tokens.$card-media-min},
+        #{tokens.$card-media-preferred},
+        #{tokens.$card-media-max}
+      )
+      1fr;
+    // Explicit 3-row track: header (auto) | body (1fr fills extra space) |
+    // footer (auto, pinned at the bottom by the track order alone). This
+    // produces the editorial layout: header+body hug the block-start while
+    // footer always sits flush to the card's block-end, no matter how tall
+    // the media side is.
+    grid-template-rows: auto 1fr auto;
+    column-gap: var(--space-md); // media ↔ body: Friends
+    row-gap: 0;
+    align-items: stretch;
+  }
+
+  .ui-card[data-orientation='horizontal'] > .ui-card-layout > .ui-card-media {
+    grid-column: 1;
+    grid-row: 1 / -1;
+    // Media fills the grid cell edge-to-edge. Any aspect-ratio set on the
+    // media slot loses meaning here because the cell's block-size is driven
+    // by the layout; the inner img/video relies on object-fit: cover (from
+    // base .ui-card-media rules) to crop gracefully.
+    aspect-ratio: auto;
+    inline-size: auto;
+    block-size: auto;
+  }
+
+  .ui-card[data-orientation='horizontal'] > .ui-card-layout > .ui-card-header {
+    grid-column: 2;
+    grid-row: 1;
+  }
+
+  .ui-card[data-orientation='horizontal'] > .ui-card-layout > .ui-card-body {
+    grid-column: 2;
+    grid-row: 2;
+    // Content hugs the block-start of the 1fr track instead of centre-
+    // stretching across the extra space.
+    align-self: start;
+  }
+
+  .ui-card[data-orientation='horizontal'] > .ui-card-layout > .ui-card-footer {
+    grid-column: 2;
+    grid-row: 3;
+    // Row 3 is auto-sized and placed after the 1fr row → footer naturally
+    // pins to the block-end. The base `margin-block-start: auto` rule is a
+    // no-op in grid context and doesn't interfere here.
+  }
+
+  // Padded horizontal: media kisses the leading + block edges.
+  .ui-card[data-orientation='horizontal']:not([data-padding='none'])
+    > .ui-card-layout
+    > .ui-card-media {
+    margin-block: calc(-1 * var(--_card-padding));
+    margin-inline-start: calc(-1 * var(--_card-padding));
+    border-start-start-radius: inherit;
+    border-end-start-radius: inherit;
+    border-start-end-radius: 0;
+    border-end-end-radius: 0;
+  }
+
+  // Zero-padding horizontal: only the trailing corners need squaring.
+  .ui-card[data-orientation='horizontal'][data-padding='none']
+    > .ui-card-layout
+    > .ui-card-media {
+    border-start-end-radius: 0;
+    border-end-end-radius: 0;
+  }
+}

package/dist/organisms/content/_card-link.scss

@@ -0,0 +1,49 @@
+/// Card pseudo-link overlay + focus ring
+/// @group organisms/content
+
+@use '@pithyjs/design-system/a11y/styles/mixins' as a11y;
+
+// ============================================
+// Pseudo-link overlay (clickable cards)
+// ============================================
+
+.ui-card-link {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  border-radius: inherit;
+  color: inherit;
+  text-decoration: none;
+  // The link itself carries no visible chrome — the card is the affordance.
+  -webkit-tap-highlight-color: transparent;
+}
+
+// Interactive descendants inside a clickable card rise above the overlay
+// anchor so they still receive their own clicks (buttons, tag chips,
+// inline links inside the body slot).
+.ui-card[data-clickable='true']
+  .ui-card-layout
+  :is(
+    a:not(.ui-card-link),
+    button,
+    [role='button'],
+    input,
+    select,
+    textarea,
+    [tabindex]:not([tabindex='-1'])
+  ) {
+  position: relative;
+  z-index: 2;
+}
+
+.ui-card-link-label {
+  // Visually-hidden but kept in the a11y tree.
+  @include a11y.visually-hidden;
+}
+
+// Card-wide focus ring: when the stretched link takes keyboard focus, the
+// whole article paints the focus ring — the card *is* the focus indicator.
+// Disabled cards are inert (no focus possible), but guard defensively.
+.ui-card:not([data-disabled='true']):has(.ui-card-link:focus-visible) {
+  @include a11y.focus-ring;
+}

package/dist/organisms/content/_card-overlay.scss

@@ -0,0 +1,91 @@
+/// Card full-bleed media overlay mode
+/// @group organisms/content
+
+// ============================================
+// Full-bleed media overlay mode
+// ============================================
+//
+// Flipped topology: media fills the card (ignoring `padding`) and the
+// header/body/footer collapse into a single `.ui-card-caption` group that
+// rides a gradient scrim at the block-end. Uses CSS Grid with a single
+// named area so media + caption stack in the same cell — caption pins to
+// block-end, media fills. Text color flips to `--color-text-inverse`
+// (always readable on the dark scrim regardless of theme).
+
+.ui-card[data-media-overlay='true'] > .ui-card-layout {
+  display: grid;
+  grid-template-areas: 'stack';
+  padding: 0;
+  gap: 0;
+  // Overlay cards are media-first — block-size is dictated by the media's
+  // aspect ratio. The caption lives on top.
+  min-block-size: 100%;
+}
+
+.ui-card[data-media-overlay='true'] > .ui-card-layout > .ui-card-media {
+  grid-area: stack;
+  z-index: 0;
+  inline-size: 100%;
+  block-size: 100%;
+  // Cancel the vertical-mode negative-inset margins — they're irrelevant
+  // now that media spans the whole card via grid-area.
+  margin: 0;
+  // Inherit the card's radius so corners stay rounded.
+  border-radius: inherit;
+}
+
+.ui-card[data-media-overlay='true'] > .ui-card-layout > .ui-card-caption {
+  grid-area: stack;
+  align-self: end;
+  z-index: 1;
+
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-xs);
+  padding: var(--_card-padding);
+  color: var(--color-text-inverse);
+
+  // Scrim — fades from transparent at the top to a dark `--color-overlay`
+  // tint at the block-end so the caption stays readable over any image.
+  // `--color-overlay` is a design-system token that's always dark, by design.
+  background: linear-gradient(
+    to top,
+    color-mix(in oklch, var(--color-overlay) 82%, transparent) 0%,
+    color-mix(in oklch, var(--color-overlay) 50%, transparent) 45%,
+    transparent 100%
+  );
+
+  // Inherit the card's radius on the block-end corners only.
+  border-end-start-radius: inherit;
+  border-end-end-radius: inherit;
+}
+
+// Inside a caption, the heading, body, and eyebrow all inherit the inverse
+// color. Eyebrow keeps a slight tint drop so it reads as secondary.
+.ui-card[data-media-overlay='true']
+  .ui-card-caption
+  :is(h1, h2, h3, h4, h5, h6),
+.ui-card[data-media-overlay='true'] .ui-card-caption .ui-card-body,
+.ui-card[data-media-overlay='true'] .ui-card-caption .ui-card-body .ui-text,
+.ui-card[data-media-overlay='true'] .ui-card-caption .ui-text {
+  color: var(--color-text-inverse);
+}
+
+.ui-card[data-media-overlay='true'] .ui-card-caption .ui-card-eyebrow {
+  color: var(--color-text-inverse);
+  opacity: 0.9;
+}
+
+// Muted text becomes less translucent against the scrim — fully opaque
+// inverse color reads better than a muted variant would.
+.ui-card[data-media-overlay='true'] .ui-card-caption [data-color='text-muted'] {
+  color: var(--color-text-inverse);
+  opacity: 0.8;
+}
+
+// Footer's auto margin-block-start makes sense inside a flex column card,
+// but inside the compact caption stack we want tight rhythm.
+.ui-card[data-media-overlay='true'] .ui-card-caption > .ui-card-footer {
+  margin-block-start: 0;
+  padding-block-start: 0;
+}