@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/dist/components/core/button-icon/ButtonIcon.types.d.ts

@@ -0,0 +1,41 @@
+import type { AnchorHTMLAttributes, ReactNode } from 'react';
+export interface ButtonIconOwnProps {
+    /**
+     * `primary` — The one glyph-alone press a section is built around — a play control over a hero, the single action a band exists for. Carries the brand fill, which is what makes it findable at a glance and what makes it meaningless once there are two.
+     * `secondary` — The ordinary case for these, because they usually arrive several at a time — a footer's social row, a carousel's two directions, a bar's dismiss. An outline rather than a quiet fill, for Button's reason: this package has color.bg.hover for the wash but no hover partner for color.bg.subtle, so a filled secondary would get lighter on hover instead of darker. It keeps the circle, the mark and the target and gives up only the fill.
+     * `inverse` — A section that paints its own ground — a brand-coloured band, a photo, a dark takeover. There the brand fill is invisible against the fill behind it and a neutral edge is the wrong ink over a photograph, so the only thing that reads is a solid at the far end of the neutral ramp: pure black in light, pure white in dark. It outranks everything near it, which is what makes it right there and wrong anywhere else.
+     * `plain` — The control sits on a surface that has already said what it is — the exit on a sheet, a step in a set of marks — and a ring around it would be the loudest thing there. It keeps the target and the states and gives up only the edge, so what a reader presses is unchanged and what they see is the glyph.
+     */
+    variant?: 'primary' | 'secondary' | 'inverse' | 'plain';
+    /**
+     * `sm` — A dense row of controls — a filter bar, a utility strip, a compact carousel. A square of size.control.sm holding a mark at icon.control.sm. Desktop only: at thirty-two it is below what a finger reliably hits.
+     * `md` — The default, and nearly everywhere — footers, navigation bars, promotional bars, carousels. A square of size.control.md holding a mark at icon.control.md, which is the measure Button's label-side glyph takes at the same step.
+     * `lg` — One prominent press, usually the only control in view — a play control over a hero, a single action in a conversion band. A square of size.control.lg holding a mark at icon.control.lg. One per page, in the same spirit as Button's own lg.
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * `default` — The control is on a light ground, which is every surface this package paints by default
+     * `inverse` — The control is on a ground that runs against the mode — a mark in a navigation bar standing on a dark hero. The ink and the tints move together; nothing else does
+     */
+    tone?: 'default' | 'inverse';
+    /** Always — the glyph is the whole control, so it is required rather than a slot that may be empty. Pass the glyph itself, from the icon package, rather than one already sized: the size a mark takes in this circle is this component's decision, at icon.control.md on md and icon.control.lg on lg, and the width and height the glyph shipped with are overridden by the class this component clones onto it. */
+    icon: ReactNode;
+    /** Always. It is the entire accessible name, because nothing on screen carries one — the words that would have been the label if there had been room for one. Required rather than optional: an optional name on a control that draws none is a control that ships unnamed. On the anchor branch it names the destination; on the button branch it names what happens. */
+    label: string;
+    /** The press goes somewhere with a URL of its own — a social account, an app store, another page. It makes this an anchor rather than a button, which is what gives a visitor cmd-click, a visible destination and a copyable link, none of which mean anything for a press the page handles itself. This is the ordinary case on a marketing page.
+  
+  `target` and `rel` are not props of this component and do not need to be: it is typed against AnchorHTMLAttributes, so `target="_blank"` and `rel="noopener noreferrer"` are already in reach and land on the anchor. A destination leaving the site is common enough here that the pairing is the page's decision rather than an axis of this component, which is the ruling Button recorded first. */
+    href?: string;
+}
+export type ButtonIconProps = ButtonIconOwnProps & Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'className' | 'variant' | 'size' | 'tone' | 'icon' | 'label' | 'href'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const buttonIconParts: {
+    readonly root: "dds-buttonicon";
+    readonly icon: "dds-buttonicon__icon";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const buttonIconDefaults: {
+    readonly variant: "primary";
+    readonly size: "md";
+    readonly tone: "default";
+};

package/dist/components/core/button-icon/ButtonIcon.types.js

@@ -0,0 +1,8 @@
+// GENERATED from button-icon.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const buttonIconParts = {
+    root: 'dds-buttonicon',
+    icon: 'dds-buttonicon__icon',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const buttonIconDefaults = { variant: 'primary', size: 'md', tone: 'default' };

package/dist/components/core/card/Card.css

@@ -0,0 +1,65 @@
+/* GENERATED from card.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-card {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border-radius: var(--radius-surface);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="accent-strong"] {
+  background-color: var(--color-bg-brand-strong);
+  color: var(--color-fg-on-brand-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="accent"] {
+  background-color: var(--color-bg-brand);
+  color: var(--color-fg-on-solid);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="plain"] {
+  border-radius: var(--radius-none);
+  color: var(--color-fg-default);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="surface-raised"] {
+  background-color: var(--color-bg-surface-raised);
+  color: var(--color-fg-default);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="surface"] {
+  background-color: var(--color-bg-surface);
+  color: var(--color-fg-default);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="accent-strong"][data-compact="true"] {
+  border-radius: var(--radius-surface-compact);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="accent"][data-compact="true"] {
+  border-radius: var(--radius-surface-compact);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="plain"][data-tone="inverse"] {
+  color: var(--color-fg-on-brand-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="surface-raised"][data-compact="true"] {
+  border-radius: var(--radius-surface-compact);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="surface-raised"][data-tone="inverse"] {
+  background-color: var(--color-bg-surface-raised-inverse);
+  color: var(--color-fg-on-brand-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="surface"][data-compact="true"] {
+  border-radius: var(--radius-surface-compact);
+}
+
+:where([data-dds-context="marketing"]) .dds-card[data-variant="surface"][data-tone="inverse"] {
+  background-color: var(--color-bg-surface-inverse);
+  color: var(--color-fg-on-brand-strong);
+}
+

package/dist/components/core/card/Card.d.ts

@@ -0,0 +1,24 @@
+import './Card.css';
+import { type CardProps } from './Card.types.js';
+export type { CardProps };
+/**
+ * A `<div>` with a fill, a corner, and nothing else.
+ *
+ * There is no padding here on purpose: the shape a marketing card most often
+ * takes is a picture reaching the edges with copy inset beneath it, and one
+ * measure cannot serve both. `CardBody` holds the inset, one level in, so a
+ * card can hold either or both without either fighting the other.
+ *
+ * The variant is a ground, not an emphasis. Which one is right follows from
+ * what the card is sitting on rather than from how important it is — `surface`
+ * is recessed against the white page, `surface-raised` lifts off a subtle band,
+ * and the two brand fills are the page having earned a colour. The stylesheet
+ * reads it from `data-variant`, so it is set here rather than folded into the
+ * class.
+ *
+ * `tone` says which way round the ground is rather than how dark it is. A card on a band that
+ * paints its own dark ground takes `inverse`, and its neutral fill becomes a veil of white over
+ * that band instead of a sheet of paper on top of it — an opaque white rectangle on a dark footer
+ * reads as a hole punched in it. The brand fills ignore it: they carry their own ground either way.
+ */
+export declare function Card({ variant, tone, compact, children, ...rest }: CardProps): import("react").JSX.Element;

package/dist/components/core/card/Card.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import './Card.css';
+import { cardDefaults, cardParts } from './Card.types.js';
+/**
+ * A `<div>` with a fill, a corner, and nothing else.
+ *
+ * There is no padding here on purpose: the shape a marketing card most often
+ * takes is a picture reaching the edges with copy inset beneath it, and one
+ * measure cannot serve both. `CardBody` holds the inset, one level in, so a
+ * card can hold either or both without either fighting the other.
+ *
+ * The variant is a ground, not an emphasis. Which one is right follows from
+ * what the card is sitting on rather than from how important it is — `surface`
+ * is recessed against the white page, `surface-raised` lifts off a subtle band,
+ * and the two brand fills are the page having earned a colour. The stylesheet
+ * reads it from `data-variant`, so it is set here rather than folded into the
+ * class.
+ *
+ * `tone` says which way round the ground is rather than how dark it is. A card on a band that
+ * paints its own dark ground takes `inverse`, and its neutral fill becomes a veil of white over
+ * that band instead of a sheet of paper on top of it — an opaque white rectangle on a dark footer
+ * reads as a hole punched in it. The brand fills ignore it: they carry their own ground either way.
+ */
+export function Card({ variant = cardDefaults.variant, tone = cardDefaults.tone, compact = cardDefaults.compact, children, ...rest }) {
+    return (_jsx("div", { className: cardParts.root, "data-variant": variant, "data-tone": tone, "data-compact": compact ? 'true' : 'false', ...rest, children: children }));
+}

package/dist/components/core/card/Card.types.d.ts

@@ -0,0 +1,33 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface CardOwnProps {
+    /**
+     * `surface` — The default, and right for a card on the page. The marketing page is white and this is a step off it, so the card is told apart by being recessed — no shadow and no border, because the fill is already the edge
+     * `surface-raised` — The card sits on a color.bg.subtle band rather than on the page. There the recessed fill is only 1.09:1 against its ground and all but disappears; this one is 1.23:1 the other way, lifting off the band instead of sinking into it
+     * `plain` — An editorial card — an article, a post, a story — where the picture and the headline are what separate one card from the next. It paints no background, so it shows whatever is under it: the page, a subtle band, or a section that has taken a colour. The corner and the clip are still the card's, so a picture at the top of it meets a rounded edge rather than squaring one off It takes no corner either: radius.surface is the shape of a fill, and with no fill there is nothing to round — a rounded picture sitting on the page reads as a floating tile rather than as the art leading an article.
+     * `accent` — One card in a set is the promotional one and the page has already earned the colour. The coral is the loudest ground here, so a row of them is a row of nothing louder than the rest
+     * `accent-strong` — A card carrying more weight than its neighbours, where the coral would be too loud and the page ground too quiet. The darkest of the four, and the one that takes white at 20.55:1 — the most legible ground a marketing card has
+     */
+    variant?: 'surface' | 'surface-raised' | 'plain' | 'accent' | 'accent-strong';
+    /**
+     * `default` — The page is light, which is nearly every page. The fills are opaque and the ink is dark
+     * `inverse` — The card sits on a band that paints its own dark ground. The neutral fills become a veil of white over that ground rather than a sheet of paper on top of it, which is what keeps a card on a dark band from reading as a hole cut in it. The two neutral variants stay two steps apart: `surface` is the quiet one a panel wants, `surface-raised` the stronger lift that suits something the size of a control.
+     */
+    tone?: 'default' | 'inverse';
+    /** The card is small enough that a generous corner is a fifth of its width. `radius.surface` is twenty-four, which is the corner of a feature card in a grid; on a rail beside a footer's columns it reads as bulbous. This takes it to `radius.surface-compact`.
+  
+  It pairs with CardBody's prop of the same name, and the two are separate because the box and its contents are separate components: this one owns the ground and the corner, that one owns the inset and the type. A small card wants both. */
+    compact?: boolean;
+    /** Allowed: any content */
+    children: ReactNode;
+}
+export type CardProps = CardOwnProps & Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'variant' | 'tone' | 'compact'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const cardParts: {
+    readonly root: "dds-card";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const cardDefaults: {
+    readonly variant: "surface";
+    readonly tone: "default";
+    readonly compact: false;
+};

package/dist/components/core/card/Card.types.js

@@ -0,0 +1,7 @@
+// GENERATED from card.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const cardParts = {
+    root: 'dds-card',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const cardDefaults = { variant: 'surface', tone: 'default', compact: false };

package/dist/components/core/card-body/CardBody.css

@@ -0,0 +1,139 @@
+/* GENERATED from cardbody.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-cardbody {
+  transition-property: background-color, color;
+  box-sizing: border-box;
+  display: flex;
+  flex: auto;
+  flex-direction: column;
+  min-block-size: 0;
+  position: relative;
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody .dds-cardbody__scrim {
+  display: block;
+  inset: 0;
+  position: absolute;
+  background-color: var(--color-bg-overlay);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody .dds-cardbody__content {
+  transition-property: padding-block, padding-inline;
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  gap: var(--space-heading-title-description-compact);
+  padding-block: var(--space-inset-card);
+  padding-inline: var(--space-inset-card);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody .dds-cardbody__mark {
+  align-self: flex-start;
+  display: flex;
+  margin-block-end: var(--space-gap-lg);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody .dds-cardbody__eyebrow {
+  transition-property: color;
+  margin: 0;
+  text-transform: uppercase;
+  font-family: var(--font-eyebrow-family);
+  font-size: var(--font-eyebrow-size);
+  font-weight: var(--font-eyebrow-weight);
+  letter-spacing: var(--font-eyebrow-letter-spacing);
+  line-height: var(--font-eyebrow-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody .dds-cardbody__title {
+  transition-property: font-family, font-size, font-weight, letter-spacing, line-height;
+  margin: 0;
+  font-family: var(--font-h5-family);
+  font-size: var(--font-h5-size);
+  font-weight: var(--font-h5-weight);
+  letter-spacing: var(--font-h5-letter-spacing);
+  line-height: var(--font-h5-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody .dds-cardbody__description {
+  transition-property: font-family, font-size, font-weight, letter-spacing, line-height;
+  margin: 0;
+  font-family: var(--font-body-md-family);
+  font-size: var(--font-body-md-size);
+  font-weight: var(--font-body-md-weight);
+  letter-spacing: var(--font-body-md-letter-spacing);
+  line-height: var(--font-body-md-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody .dds-cardbody__media-frame {
+  display: block;
+  flex: auto;
+  min-block-size: 0;
+  overflow: hidden;
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody .dds-cardbody__media {
+  block-size: 100%;
+  display: block;
+  inline-size: 100%;
+  object-fit: cover;
+  border-radius: var(--radius-none);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-over-media="true"] {
+  display: grid;
+  background-color: var(--color-bg-brand-strong);
+  color: var(--color-fg-on-brand-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-flush="true"] .dds-cardbody__content {
+  padding-inline: 0;
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-over-media="true"] .dds-cardbody__media-frame {
+  block-size: 100%;
+  inset: 0;
+  position: absolute;
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-compact="true"] .dds-cardbody__content {
+  padding-block: var(--space-inset-md);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-compact="true"] .dds-cardbody__description {
+  font-family: var(--font-body-sm-family);
+  font-size: var(--font-body-sm-size);
+  font-weight: var(--font-body-sm-weight);
+  letter-spacing: var(--font-body-sm-letter-spacing);
+  line-height: var(--font-body-sm-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-compact="true"] .dds-cardbody__title {
+  font-family: var(--font-label-md-family);
+  font-size: var(--font-label-md-size);
+  font-weight: var(--font-label-md-weight);
+  letter-spacing: var(--font-label-md-letter-spacing);
+  line-height: var(--font-label-md-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-over-media="false"] .dds-cardbody__eyebrow {
+  color: var(--color-fg-muted);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-zoom-on-hover="true"] .dds-cardbody__media {
+  transition-duration: var(--motion-duration-media-hover);
+  transition-timing-function: var(--motion-easing-media-hover);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-flush="false"][data-compact="true"] .dds-cardbody__content {
+  padding-inline: var(--space-inset-md);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbody[data-over-media="false"][data-tone="inverse"] .dds-cardbody__eyebrow {
+  color: var(--color-fg-muted-inverse);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :where([data-dds-context="marketing"]) .dds-cardbody,
+  :where([data-dds-context="marketing"]) .dds-cardbody * { transition: none; }
+}
+

package/dist/components/core/card-body/CardBody.d.ts

@@ -0,0 +1,62 @@
+import './CardBody.css';
+import './card-body-impl.css';
+import { type CardBodyProps } from './CardBody.types.js';
+export type { CardBodyProps };
+/**
+ * Everything a `Card` holds: the words inset from its edges, and the picture
+ * that reaches them.
+ *
+ * The inset lives on `content` rather than on this component's own box. That is
+ * the whole reason both fit in one region — a body that padded itself and then
+ * pulled the picture back out with a negative margin would be two decisions
+ * undoing each other, and the system has no way to write the second one anyway:
+ * `staticCss` takes keywords, `100%` and `0`, so there is no negative value to
+ * reach for.
+ *
+ * `mediaPosition` reorders the elements rather than painting them somewhere
+ * else. A CSS `order` would move the picture visually and leave a screen reader
+ * hearing the old sequence, which is the one way a caption can end up read as an
+ * introduction. So it is not a styling axis and emits no rule — it decides which
+ * of two nodes is written first.
+ *
+ * `overMedia` is the axis, and it is a different question: not where the picture
+ * sits in the column but whether it is in the column at all. Under it the root
+ * becomes a grid, the picture and the wash are pinned to all four edges and out
+ * of the flow, and the content is the only child left to occupy the cell. The
+ * two props do not compose — a picture that is the ground has no position in a
+ * column it left — so `mediaPosition` is not read at all in that branch, which
+ * is why the markup below chooses between two whole shapes rather than
+ * threading one through the other.
+ *
+ * `flush` is the other axis, and it is the one prop here that answers to a
+ * decision made on a different component. Card's `plain` variant paints no
+ * ground, so there is no fill for the copy to be held off and the picture
+ * becomes the card's edge instead — at which point the inline inset indents the
+ * words from their own picture. It drops that half and keeps the block padding,
+ * which was never about the fill. Nothing can check the pair: the ground is
+ * Card's prop and the inset is this one's, and neither component can see the
+ * other.
+ *
+ * `zoomOnHover` is the third axis and the only one whose rule is not in the
+ * generated sheet. A state bound on a part emits hover on that part, which would
+ * zoom the picture only while the pointer was on the picture and leave it still
+ * over the headline of the same card. The root's hover reaching its own child has
+ * no vocabulary here, so it is in the impl sheet beside this file.
+ *
+ * `given` on the four strings that gate a region: absence is the switch, so an
+ * empty string and a string of spaces both count as absent. A title bound to a
+ * value that has not loaded would otherwise render an empty heading, which a
+ * screen reader announces as a heading with no name — and `src=""` is worse than
+ * nothing, since a browser resolves it against the page URL and re-requests the
+ * document as an image.
+ *
+ * `alt` is not read through `given`, and `mark` is not either. An `alt` of `""` is
+ * a real answer meaning "skip this, the copy already said it", and collapsing it
+ * into absence would put a filename back into a screen reader. A node is not
+ * blank-able the way a string is, so `mark` is tested against `undefined`.
+ *
+ * No region sets a colour. Card sets one per variant on its root and colour
+ * inherits, so the same title is `fg.on-solid` on the brand fill and
+ * `fg.default` on the page without this component knowing which card it is in.
+ */
+export declare function CardBody({ eyebrow, title, description, mark, src, alt, aspect, mediaPosition, overMedia, flush, compact, tone, zoomOnHover, children: _children, ...rest }: CardBodyProps): import("react").JSX.Element;

package/dist/components/core/card-body/CardBody.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { given } from '../../given.js';
+import { Icon } from '../icon/Icon.js';
+import './CardBody.css';
+import './card-body-impl.css';
+import { cardBodyDefaults, cardBodyParts } from './CardBody.types.js';
+/**
+ * Everything a `Card` holds: the words inset from its edges, and the picture
+ * that reaches them.
+ *
+ * The inset lives on `content` rather than on this component's own box. That is
+ * the whole reason both fit in one region — a body that padded itself and then
+ * pulled the picture back out with a negative margin would be two decisions
+ * undoing each other, and the system has no way to write the second one anyway:
+ * `staticCss` takes keywords, `100%` and `0`, so there is no negative value to
+ * reach for.
+ *
+ * `mediaPosition` reorders the elements rather than painting them somewhere
+ * else. A CSS `order` would move the picture visually and leave a screen reader
+ * hearing the old sequence, which is the one way a caption can end up read as an
+ * introduction. So it is not a styling axis and emits no rule — it decides which
+ * of two nodes is written first.
+ *
+ * `overMedia` is the axis, and it is a different question: not where the picture
+ * sits in the column but whether it is in the column at all. Under it the root
+ * becomes a grid, the picture and the wash are pinned to all four edges and out
+ * of the flow, and the content is the only child left to occupy the cell. The
+ * two props do not compose — a picture that is the ground has no position in a
+ * column it left — so `mediaPosition` is not read at all in that branch, which
+ * is why the markup below chooses between two whole shapes rather than
+ * threading one through the other.
+ *
+ * `flush` is the other axis, and it is the one prop here that answers to a
+ * decision made on a different component. Card's `plain` variant paints no
+ * ground, so there is no fill for the copy to be held off and the picture
+ * becomes the card's edge instead — at which point the inline inset indents the
+ * words from their own picture. It drops that half and keeps the block padding,
+ * which was never about the fill. Nothing can check the pair: the ground is
+ * Card's prop and the inset is this one's, and neither component can see the
+ * other.
+ *
+ * `zoomOnHover` is the third axis and the only one whose rule is not in the
+ * generated sheet. A state bound on a part emits hover on that part, which would
+ * zoom the picture only while the pointer was on the picture and leave it still
+ * over the headline of the same card. The root's hover reaching its own child has
+ * no vocabulary here, so it is in the impl sheet beside this file.
+ *
+ * `given` on the four strings that gate a region: absence is the switch, so an
+ * empty string and a string of spaces both count as absent. A title bound to a
+ * value that has not loaded would otherwise render an empty heading, which a
+ * screen reader announces as a heading with no name — and `src=""` is worse than
+ * nothing, since a browser resolves it against the page URL and re-requests the
+ * document as an image.
+ *
+ * `alt` is not read through `given`, and `mark` is not either. An `alt` of `""` is
+ * a real answer meaning "skip this, the copy already said it", and collapsing it
+ * into absence would put a filename back into a screen reader. A node is not
+ * blank-able the way a string is, so `mark` is tested against `undefined`.
+ *
+ * No region sets a colour. Card sets one per variant on its root and colour
+ * inherits, so the same title is `fg.on-solid` on the brand fill and
+ * `fg.default` on the page without this component knowing which card it is in.
+ */
+export function CardBody({ eyebrow, title, description, mark, src, alt, aspect, mediaPosition = cardBodyDefaults.mediaPosition, overMedia = cardBodyDefaults.overMedia, flush = cardBodyDefaults.flush, compact = cardBodyDefaults.compact, tone = cardBodyDefaults.tone, zoomOnHover = cardBodyDefaults.zoomOnHover, children: _children, ...rest }) {
+    // Pulled out of `rest` and deliberately unused. `HTMLAttributes` carries a
+    // `children` the contract does not declare, and the generator only omits props
+    // it knows about — so the type accepts children this component has no slot for,
+    // with no complaint from TypeScript. Left in `rest` it would spread onto the div
+    // and be silently overridden by the regions below: the same nothing, harder to
+    // explain.
+    void _children;
+    const media = given(src) ? (
+    // The frame, not the picture, is what sits in the column: it takes the height the
+    // copy leaves and clips whatever grows past it. An <img> cannot clip itself, so a
+    // picture that scales on hover has to scale inside something.
+    _jsx("div", { className: cardBodyParts['media-frame'], 
+        // Applied here rather than bound, because the contract cannot hold it: a
+        // token binding needs a token and the system has no aspect-ratio one, and a
+        // structural rule needs a styling axis, which a number cannot be. Setting it
+        // also has to undo the `flex: auto` the stylesheet sets unconditionally —
+        // left alone, flex-grow wins over `aspect-ratio` in this column and the ratio
+        // asked for is silently not the ratio drawn.
+        //
+        // On the frame rather than on the picture, which is where it moved when the
+        // frame arrived: the ratio is a fact about the box, and the picture inside it
+        // fills that box at 100% and covers.
+        style: aspect === undefined ? undefined : { flex: 'none', aspectRatio: aspect }, children: _jsx("img", { className: cardBodyParts.media, src: src, alt: alt }) })) : null;
+    const content = (_jsxs("div", { className: cardBodyParts.content, children: [mark !== undefined ? (_jsx("div", { className: cardBodyParts.mark, children: _jsx(Icon, { size: "lg", children: mark }) })) : null, given(eyebrow) ? _jsx("p", { className: cardBodyParts.eyebrow, children: eyebrow }) : null, given(title) ? _jsx("h3", { className: cardBodyParts.title, children: title }) : null, given(description) ? (_jsx("p", { className: cardBodyParts.description, children: description })) : null] }));
+    if (overMedia) {
+        return (
+        // Both values, never just the set one. The stylesheet selects on
+        // `[data-over-media="true"]`, and an attribute that is simply absent when false
+        // would leave the two branches distinguished by nothing a selector can name.
+        _jsxs("div", { className: cardBodyParts.root, "data-over-media": "true", "data-flush": flush ? 'true' : 'false', "data-zoom-on-hover": zoomOnHover ? 'true' : 'false', "data-compact": compact ? 'true' : 'false', "data-tone": tone, ...rest, children: [media, _jsx("span", { className: cardBodyParts.scrim }), content] }));
+    }
+    return (_jsxs("div", { className: cardBodyParts.root, "data-over-media": "false", "data-flush": flush ? 'true' : 'false', "data-zoom-on-hover": zoomOnHover ? 'true' : 'false', "data-compact": compact ? 'true' : 'false', "data-tone": tone, ...rest, children: [mediaPosition === 'above' ? media : null, content, mediaPosition === 'above' ? null : media] }));
+}

package/dist/components/core/card-body/CardBody.types.d.ts

@@ -0,0 +1,61 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface CardBodyOwnProps {
+    /** The picture is the card's ground and the copy is read on top of it. Set explicitly rather than inferred from src, which BannerBody can afford to do and this cannot: there, art is always behind the words, so having art and being over it are the same fact. Here a picture is a region in the column by default, and the same src means two different cards */
+    overMedia?: boolean;
+    /** The card has no fill for the copy to be held off — Card's `plain` variant, where the picture is the card's edge rather than the ground being it. The inline inset goes and the copy lines up with the picture above it; the block padding stays, because the space between a picture and the line under it is still doing its job */
+    flush?: boolean;
+    /** The card is pressable and its picture is what answers the pointer — an editorial card inside a CardButton, on any ground. The picture grows by motion.scale.media-hover and media-frame clips it, so what the reader sees is the frame holding still while the art moves inside it. Setting this is also what stops the card lifting: CardButton suppresses its own lift when the body it holds zooms, so the two motions never compete */
+    zoomOnHover?: boolean;
+    /** The card is small enough that the standard inset and the standard type are most of it. `space.inset.card` is thirty-two, which is a fifth of the width of a rail beside a footer's columns; `font.h5` is twenty-four, which is a heading over a group of cards rather than the name of one two hundred pixels wide.
+  
+  This takes the inset to `space.inset.md`, the title to `font.label.md` and the description to `font.body.sm` — sixteen and fourteen, where the standard card runs twenty-four and sixteen. The pair moves together: dropping the title alone would put a heading two pixels above its own body copy.
+  
+  It is about the card's size rather than its importance. A compact card is not a lesser one. */
+    compact?: boolean;
+    /**
+     * `default` — The card is on the page, which is nearly every card
+     * `inverse` — The card sits on a band that paints its own dark ground, and carries `tone="inverse"` itself. The eyebrow takes the inverse muted ink so it stays quieter than the copy without falling below what a reader can make out
+     */
+    tone?: 'default' | 'inverse';
+    /** The card is filed under something a reader scans before the headline — the date an article ran, how long it takes to read, the category it sits in. Write it in the case it should be read in: the part draws the capitals itself, so 'August' is what belongs here and AUGUST is what appears */
+    eyebrow?: string;
+    /** The card names what it is about. A noun phrase rather than a sentence — 'Balance protection', not 'We protect your balance' — because it is read as a label on the block beneath it. A string rather than a node: a node could carry a mark or a link, and would cost the component its examples — the checker requires a named element there, so no row could ever show a card with real copy in it. */
+    title?: string;
+    /** What the title means, usually a sentence or two. It takes the default body step, because a card's copy is copy rather than a caption. A string rather than a node, for the reason the title is one — a node prop cannot be given text in an examples row, and a card nobody can show is worse than a sentence that cannot hold a link. */
+    description?: string;
+    /** The card leads with a glyph — a badge, a shield, a small piece of art that makes the feature recognisable before the title is read. Set it on every card in a set or on none of them: one card in a row carrying a mark reads as the important one, which is a claim the mark was not meant to make. Pass the glyph; the body draws it at its own step, and an Icon passed already sized is unwrapped rather than obeyed */
+    mark?: ReactNode;
+    /** The card shows a picture — a photograph, a product render, a screenshot of the thing being described. Absent is the ordinary case: most cards are words */
+    src?: string;
+    /** Whenever src is, and empty when the picture says nothing the copy has not already said. A decorative render beside a title naming it — a shield next to 'Integrity' — takes alt="", which tells a screen reader to skip it rather than read a filename aloud. A photograph carrying meaning of its own takes a sentence describing what it shows */
+    alt?: string;
+    /** The picture must hold a known shape rather than absorb the card's spare height — a logo that distorts the moment it is cropped, or a chart whose proportions are the point. Written as the division rather than the result, so the shape is legible: aspect={16 / 9}, not aspect={1.7778} */
+    aspect?: number;
+    /**
+     * `below` — The copy introduces the picture — a feature named and explained, then shown. The ordinary case, and what a reader scanning a column of cards is reading for
+     * `above` — The picture is what the reader recognises the card by and the words caption it — a photograph leading an article, a screenshot the copy then describes. Changes the order of the elements themselves rather than only their appearance, so what a screen reader hears follows what the page shows
+     */
+    mediaPosition?: 'below' | 'above';
+}
+export type CardBodyProps = CardBodyOwnProps & Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'overMedia' | 'flush' | 'zoomOnHover' | 'compact' | 'tone' | 'eyebrow' | 'title' | 'description' | 'mark' | 'src' | 'alt' | 'aspect' | 'mediaPosition'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const cardBodyParts: {
+    readonly root: "dds-cardbody";
+    readonly scrim: "dds-cardbody__scrim";
+    readonly content: "dds-cardbody__content";
+    readonly mark: "dds-cardbody__mark";
+    readonly eyebrow: "dds-cardbody__eyebrow";
+    readonly title: "dds-cardbody__title";
+    readonly description: "dds-cardbody__description";
+    readonly 'media-frame': "dds-cardbody__media-frame";
+    readonly media: "dds-cardbody__media";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const cardBodyDefaults: {
+    readonly overMedia: false;
+    readonly flush: false;
+    readonly zoomOnHover: false;
+    readonly compact: false;
+    readonly tone: "default";
+    readonly mediaPosition: "below";
+};

package/dist/components/core/card-body/CardBody.types.js

@@ -0,0 +1,15 @@
+// GENERATED from card-body.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const cardBodyParts = {
+    root: 'dds-cardbody',
+    scrim: 'dds-cardbody__scrim',
+    content: 'dds-cardbody__content',
+    mark: 'dds-cardbody__mark',
+    eyebrow: 'dds-cardbody__eyebrow',
+    title: 'dds-cardbody__title',
+    description: 'dds-cardbody__description',
+    'media-frame': 'dds-cardbody__media-frame',
+    media: 'dds-cardbody__media',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const cardBodyDefaults = { overMedia: false, flush: false, zoomOnHover: false, compact: false, tone: 'default', mediaPosition: 'below' };