@deriv-com/dds-marketing 0.1.0 → 0.2.0

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

@@ -0,0 +1,87 @@
+/*
+ * Scoped to this package, like the generated sheet beside it.
+ *
+ * `:where([data-dds-context="marketing"])` confines these rules without contributing
+ * specificity, so every rule below ties or beats exactly what it would have without it.
+ * Imported after the generated sheet, which is what lets the ties fall this way.
+ */
+
+/* Implementation CSS that the contract's staticCss cannot express. */
+
+/*
+ * The picture answers a pointer that is anywhere on the card.
+ *
+ * Here because of the shape of the selector rather than the value in it. A state bound on a
+ * part emits hover on that part — `.dds-cardbody__media:hover` — so the picture would grow
+ * while the pointer was on the picture and sit still while it was on the headline of the
+ * very same card. What an editorial card wants is the root's hover reaching one of its own
+ * children, and the generator has no vocabulary for that.
+ *
+ * The body is the card's only child and takes its full height, so hovering the card is
+ * hovering the body. That is what keeps this inside one component: both halves of the
+ * selector are CardBody's own, and nothing here reaches into a part someone else owns.
+ *
+ * What stops this from growing the card is `media-frame`, not anything in this rule. A
+ * transform never reflows, so the layout was never going to move — but an <img> cannot clip
+ * itself, and before the frame existed the nearest clip was the Card's, one level up and
+ * around the copy as well. The picture grew past its own box and painted over the eyebrow
+ * and the headline, and in a body with no card around it, over whatever came next. The
+ * frame holds the box; this moves the art inside it.
+ *
+ * The step is `motion.scale.media-hover` rather than `motion.scale.hover`. The latter is held to two
+ * per cent because a control that grows past the pointer fires its own mouse-out; a picture in a frame
+ * that never moves cannot do that, so it takes twice the step.
+ *
+ * `scale` rather than `transform: scale()`, matching the `translate` CardButton binds for
+ * its lift. They are independent properties, so neither needs the other's matrix — which is
+ * what would let one card do both. None does: the lift is bound to the four variants with a
+ * fill, and this is for the one without.
+ *
+ * Two classes deep to match the generated rule it sits against, which is
+ * `.dds-cardbody .dds-cardbody__media`. A bare `.dds-cardbody__media` would lose on
+ * specificity however late it loaded, which is the quiet way an override fails.
+ */
+:where([data-dds-context="marketing"]) .dds-cardbody[data-zoom-on-hover="true"]:hover .dds-cardbody__media {
+  scale: var(--motion-scale-media-hover);
+}
+
+/*
+ * Only the property list. The duration and the curve are bound in the contract, on this
+ * same part and under this same axis, so the generated sheet already carries them — and
+ * binding them is also what tells the generator this component has motion at all, which is
+ * what makes it emit the reduced-motion block below this one.
+ *
+ * The list itself cannot be bound, because the generator computes it from the properties a
+ * contract binds on a state, and the only thing that moves here is bound in no state.
+ *
+ * Those two are `motion.duration.media-hover` and `motion.easing.media-hover`, which together
+ * with `motion.scale.media-hover` are the three roles this one effect owns. `duration.normal`
+ * is the role whose description names card hover, and 200ms is right for a card that lifts:
+ * the movement is small and over. A picture that zooms is still on screen when it stops and
+ * the eye follows it the whole way, so the same 200ms reads as a snap. 400ms is the step that
+ * follows without lagging the pointer.
+ *
+ * The curve matters more than the duration. `easing.standard` is `emphasized`, which is
+ * 87 per cent travelled by its halfway point — a one-way shape, for something arriving
+ * somewhere. A hover is the one transition that runs backwards as often as forwards, and an
+ * asymmetric curve played in reverse is a different animation: a snap going in, a drift coming
+ * out. `media-hover` is `in-out-soft`, which is the same shape both ways.
+ */
+:where([data-dds-context="marketing"]) .dds-cardbody[data-zoom-on-hover="true"] .dds-cardbody__media {
+  transition-property: scale;
+}
+
+/*
+ * The generated reduced-motion block turns the transition off and stops there, which is
+ * right for every other component in the package: with nothing to interpolate, a colour
+ * simply arrives. Here it would leave the picture jumping between two sizes on hover — more
+ * motion in less time, which is the opposite of what the reader asked for.
+ *
+ * So the scale goes too. Written here because the generated block is generated: it knows a
+ * component has transitions, not that one of them was a size.
+ */
+@media (prefers-reduced-motion: reduce) {
+  :where([data-dds-context="marketing"]) .dds-cardbody[data-zoom-on-hover="true"]:hover .dds-cardbody__media {
+    scale: none;
+  }
+}

package/dist/components/core/card-button/CardButton.css

@@ -0,0 +1,73 @@
+/* GENERATED from cardbutton.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-cardbutton {
+  transition-property: outline-color, outline-width, translate;
+  border-style: none;
+  box-sizing: border-box;
+  cursor: pointer;
+  display: flex;
+  flex-direction: column;
+  font-family: inherit;
+  outline-style: solid;
+  overflow: hidden;
+  padding: 0;
+  text-align: start;
+  text-decoration: none;
+  border-radius: var(--radius-surface);
+  min-block-size: var(--size-target-min);
+  min-inline-size: var(--size-target-min);
+  outline-width: var(--border-width-none);
+  transition-duration: var(--motion-duration-normal);
+  transition-timing-function: var(--motion-easing-standard);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton:focus-visible {
+  outline-color: var(--color-border-focus);
+  outline-width: var(--border-width-focus);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton[data-variant="accent-strong"] {
+  background-color: var(--color-bg-brand-strong);
+  color: var(--color-fg-on-brand-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton[data-variant="accent"] {
+  background-color: var(--color-bg-brand);
+  color: var(--color-fg-on-solid);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton[data-variant="plain"] {
+  border-radius: var(--radius-none);
+  color: var(--color-fg-default);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton[data-variant="surface-raised"] {
+  background-color: var(--color-bg-surface-raised);
+  color: var(--color-fg-default);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton[data-variant="surface"] {
+  background-color: var(--color-bg-surface);
+  color: var(--color-fg-default);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton[data-variant="accent-strong"]:hover:where(:not(:disabled)) {
+  translate: var(--motion-translate-hover);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton[data-variant="accent"]:hover:where(:not(:disabled)) {
+  translate: var(--motion-translate-hover);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton[data-variant="surface-raised"]:hover:where(:not(:disabled)) {
+  translate: var(--motion-translate-hover);
+}
+
+:where([data-dds-context="marketing"]) .dds-cardbutton[data-variant="surface"]:hover:where(:not(:disabled)) {
+  translate: var(--motion-translate-hover);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :where([data-dds-context="marketing"]) .dds-cardbutton { transition: none; }
+}
+

package/dist/components/core/card-button/CardButton.d.ts

@@ -0,0 +1,27 @@
+import './CardButton.css';
+import './card-button-impl.css';
+import { type CardButtonProps } from './CardButton.types.js';
+export type { CardButtonProps };
+/**
+ * A card that responds to a press.
+ *
+ * Which element it renders is decided by `href` and nothing else. A card that goes to a
+ * page and a card that opens a dialog are the same gesture with different destinations,
+ * and the element is what tells a browser which: a `<button>` answers Space and does what
+ * the page says, an `<a>` gives cmd-click, a visible destination and a copyable link. Two
+ * components for that would be two names for one gesture.
+ *
+ * Everything Card's surface does, this does — the four grounds, the corner, the clip, no
+ * inset of its own. What it adds is that the whole surface is one target, and what it gives
+ * up is holding a control: a button inside a button is unreachable, which is why
+ * `forbiddenChildren` names every one of them.
+ *
+ * `color` is bound per ground rather than inherited, which the anchor makes necessary — a
+ * `<button>` takes the text colour around it and an `<a>` does not, so without it every
+ * word in the card would come out the browser's link blue.
+ *
+ * `type="button"` on the button branch, because a card inside a form would otherwise submit
+ * it: the default for a `<button>` is `submit`, and a promotional card that reloaded the
+ * page is the kind of fault nobody looks for in a card.
+ */
+export declare function CardButton({ variant, href, children, ...rest }: CardButtonProps): import("react").JSX.Element;

package/dist/components/core/card-button/CardButton.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import './CardButton.css';
+import './card-button-impl.css';
+import { cardButtonDefaults, cardButtonParts } from './CardButton.types.js';
+/**
+ * A card that responds to a press.
+ *
+ * Which element it renders is decided by `href` and nothing else. A card that goes to a
+ * page and a card that opens a dialog are the same gesture with different destinations,
+ * and the element is what tells a browser which: a `<button>` answers Space and does what
+ * the page says, an `<a>` gives cmd-click, a visible destination and a copyable link. Two
+ * components for that would be two names for one gesture.
+ *
+ * Everything Card's surface does, this does — the four grounds, the corner, the clip, no
+ * inset of its own. What it adds is that the whole surface is one target, and what it gives
+ * up is holding a control: a button inside a button is unreachable, which is why
+ * `forbiddenChildren` names every one of them.
+ *
+ * `color` is bound per ground rather than inherited, which the anchor makes necessary — a
+ * `<button>` takes the text colour around it and an `<a>` does not, so without it every
+ * word in the card would come out the browser's link blue.
+ *
+ * `type="button"` on the button branch, because a card inside a form would otherwise submit
+ * it: the default for a `<button>` is `submit`, and a promotional card that reloaded the
+ * page is the kind of fault nobody looks for in a card.
+ */
+export function CardButton({ variant = cardButtonDefaults.variant, href, children, ...rest }) {
+    const shared = {
+        className: cardButtonParts.root,
+        // Read from `data-variant` rather than folded into the class, the same way Card reads it.
+        'data-variant': variant,
+    };
+    if (href !== undefined) {
+        return (_jsx("a", { ...rest, ...shared, href: href, children: children }));
+    }
+    return (_jsx("button", { ...rest, ...shared, type: "button", children: children }));
+}

package/dist/components/core/card-button/CardButton.types.d.ts

@@ -0,0 +1,24 @@
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+export interface CardButtonOwnProps {
+    /**
+     * `surface` — The default, and right for a pressable card on the page. The same recessed step off the white page that Card takes, so a row mixing pressable and plain cards reads as one row
+     * `surface-raised` — The card sits on a color.bg.subtle band rather than on the page, where the recessed fill all but disappears and this one lifts off the band instead
+     * `accent` — One card in a set is the promotional one and the page has already earned the colour
+     * `accent-strong` — A card carrying more weight than its neighbours. The darkest of the four, and the one that takes white at 20.55:1 — the most legible ground a marketing card has
+     * `plain` — An editorial card that goes somewhere — an article, a post, a release note. No fill, no corner and no lift: what marks it out is its picture and the gap to the next one, the way a column of articles is told apart on a page rather than the way a row of tiles is. The same ground Card's own plain variant takes, so a pressable article card and a static one sit in one column without a seam
+     */
+    variant?: 'surface' | 'surface-raised' | 'accent' | 'accent-strong' | 'plain';
+    /** The press goes somewhere with a URL of its own. It makes this an anchor rather than a button, which is what gives a reader cmd-click, a visible destination and a copyable link — none of which mean anything for a press that opens a dialog. This is the ordinary case on a marketing page, where most cards point at a page */
+    href?: string;
+    /** Allowed: any content */
+    children: ReactNode;
+}
+export type CardButtonProps = CardButtonOwnProps & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'className' | 'variant' | 'href'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const cardButtonParts: {
+    readonly root: "dds-cardbutton";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const cardButtonDefaults: {
+    readonly variant: "surface";
+};

package/dist/components/core/card-button/CardButton.types.js

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

package/dist/components/core/card-button/card-button-impl.css

@@ -0,0 +1,39 @@
+/*
+ * Scoped to this package, like the generated sheet beside it.
+ *
+ * `:where([data-dds-context="marketing"])` confines these rules without contributing
+ * specificity, so the rule below beats exactly what it needs to and nothing else.
+ */
+
+/* Implementation CSS that the contract's staticCss cannot express. */
+
+/*
+ * One motion per gesture: a card whose picture zooms does not also lift.
+ *
+ * Two motions answering one hover reads as a glitch rather than as emphasis — the frame
+ * slides up while the art inside it grows, and neither movement is legible because the
+ * other is happening. Which one to keep is decided by what the card is: an editorial card
+ * is recognised by its picture, so the picture is what should answer the pointer.
+ *
+ * This is a separate rule from `plain` having no lift, and the two are independent. That one
+ * is about the ground: with no fill, what would rise is a picture and some loose text, which
+ * reads as the words sliding. This one is about the motion already present, and it holds on
+ * every variant — an editorial card on a surface fill has a ground to lift and still should
+ * not, because its picture is already moving.
+ *
+ * Written here because the condition is a fact about this component's child. A contract binds
+ * a property under a styling axis of its own, and "the body inside me zooms" is neither — it
+ * is CardBody's prop, one level down. `:has()` is what lets this stay a rule about the
+ * CardButton: the selector is on this component's own root, and the child is only read.
+ *
+ * `>` rather than a descendant, because a CardButton holds exactly one child. A loose
+ * descendant would also match a zooming body nested somewhere deeper, which is a shape
+ * childCount already forbids and this need not restate.
+ *
+ * Specificity: the generated lift is `.dds-cardbutton[data-variant="…"]:hover:where(…)`, at
+ * three classes. This reads four — the class, the two inside `:has()`, and `:hover` — so it
+ * wins on weight rather than on load order, and would still win if the sheets were reordered.
+ */
+:where([data-dds-context="marketing"]) .dds-cardbutton:has(> .dds-cardbody[data-zoom-on-hover="true"]):hover {
+  translate: none;
+}

package/dist/components/core/checkbox/Checkbox.css

@@ -0,0 +1,149 @@
+/* GENERATED from checkbox.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-checkbox {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-gap-xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__control {
+  align-items: flex-start;
+  display: flex;
+  gap: var(--space-gap-sm);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__box {
+  align-items: center;
+  border-style: solid;
+  box-sizing: border-box;
+  display: flex;
+  flex: none;
+  justify-content: center;
+  outline-style: solid;
+  position: relative;
+  background-color: var(--color-bg-surface-raised);
+  block-size: var(--size-checkbox-box);
+  border-color: var(--color-border-default);
+  border-radius: var(--radius-control-sm);
+  border-width: var(--border-width-default);
+  inline-size: var(--size-checkbox-box);
+  outline-width: var(--border-width-none);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__field {
+  appearance: none;
+  cursor: pointer;
+  inset-block-start: 0;
+  inset-inline-start: 0;
+  margin: 0;
+  opacity: 0;
+  position: absolute;
+  block-size: var(--size-checkbox-box);
+  inline-size: var(--size-checkbox-box);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__indicator {
+  align-items: center;
+  display: flex;
+  justify-content: center;
+  pointer-events: none;
+  block-size: var(--icon-size-2xs);
+  color: var(--color-fg-on-solid);
+  inline-size: var(--icon-size-2xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__text {
+  display: flex;
+  flex-direction: column;
+  min-inline-size: 0;
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__label {
+  cursor: pointer;
+  color: var(--color-fg-default);
+  font-family: var(--font-body-md-family);
+  font-size: var(--font-body-md-size);
+  font-weight: var(--font-body-md-weight);
+  line-height: var(--font-body-md-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__message {
+  align-items: flex-start;
+  display: flex;
+  overflow-wrap: anywhere;
+  font-family: var(--font-body-sm-family);
+  font-size: var(--font-body-sm-size);
+  font-weight: var(--font-body-sm-weight);
+  gap: var(--space-gap-xs);
+  line-height: var(--font-body-sm-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__description-text {
+  color: var(--color-fg-muted);
+  font-family: var(--font-body-sm-family);
+  font-size: var(--font-body-sm-size);
+  font-weight: var(--font-body-sm-weight);
+  line-height: var(--font-body-sm-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__box:hover:where(:not(:has(.dds-checkbox__field:disabled))) {
+  box-shadow: var(--elevation-ring-hover);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox:has(.dds-checkbox__field:focus-visible) .dds-checkbox__box {
+  outline-color: var(--color-border-focus);
+  outline-width: var(--border-width-focus);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox:has(.dds-checkbox__field:disabled:not(:where(:disabled *))) {
+  opacity: var(--opacity-disabled);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-status="error"] .dds-checkbox__message {
+  color: var(--color-fg-danger);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-status="success"] .dds-checkbox__message {
+  color: var(--color-fg-success);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-status="warning"] .dds-checkbox__message {
+  color: var(--color-fg-warning);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-checked="unchecked"][data-status="error"] .dds-checkbox__box {
+  border-color: var(--color-border-danger);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-checked="unchecked"][data-status="success"] .dds-checkbox__box {
+  border-color: var(--color-border-success);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-checked="unchecked"][data-status="warning"] .dds-checkbox__box {
+  border-color: var(--color-border-warning);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-tone="accent"][data-checked="checked"] .dds-checkbox__box {
+  background-color: var(--color-bg-brand);
+  border-color: var(--color-bg-brand);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-tone="accent"][data-checked="indeterminate"] .dds-checkbox__box {
+  background-color: var(--color-bg-brand);
+  border-color: var(--color-bg-brand);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-tone="standard"][data-checked="checked"] .dds-checkbox__box {
+  background-color: var(--color-bg-strong);
+  border-color: var(--color-bg-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox[data-tone="standard"][data-checked="indeterminate"] .dds-checkbox__box {
+  background-color: var(--color-bg-strong);
+  border-color: var(--color-bg-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-checkbox .dds-checkbox__field:disabled {
+  cursor: not-allowed;
+}
+

package/dist/components/core/checkbox/Checkbox.d.ts

@@ -0,0 +1,21 @@
+import './Checkbox.css';
+import './checkbox-impl.css';
+import { type CheckboxProps } from './Checkbox.types.js';
+export type { CheckboxProps };
+/**
+ * A real `<input type="checkbox">`, invisible, with the box the user sees drawn as
+ * its sibling.
+ *
+ * The tick lives inside `box`, which is a `<span>`, and the input covers the box rather
+ * than containing anything. So every part here is a real element the generator can name,
+ * *and* the control is native: it submits with a form, it takes the keyboard for free,
+ * and it carries the mixed state properly.
+ *
+ * That is why nothing below writes `role` or `aria-checked` by hand. The element is
+ * already a checkbox and already announces its state.
+ *
+ * It carries its own status and its own description. A lone consent is the case with
+ * nothing above it to hold either, and one that cannot show its own error is a form the
+ * reader cannot be told they failed.
+ */
+export declare function Checkbox({ tone, checked, status, label, showLabel, description, statusMessage, id, onChange, ...rest }: CheckboxProps): import("react").JSX.Element;

package/dist/components/core/checkbox/Checkbox.js

@@ -0,0 +1,97 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useId } from 'react';
+import { CircleCheckSolidIcon, CircleExclamationSolidIcon, TriangleExclamationSolidIcon, } from '@deriv-com/quill-icons-web';
+import './Checkbox.css';
+import './checkbox-impl.css';
+import { given } from '../../given.js';
+import { visuallyHidden } from '../../visually-hidden.js';
+import { Icon } from '../icon/Icon.js';
+import { checkboxDefaults, checkboxParts } from './Checkbox.types.js';
+/**
+ * What each reported status looks like.
+ *
+ * Circle for error, triangle for warning: the two colours are close enough that a
+ * red-green deficiency can converge them, so the shape is what separates the pair at a
+ * glance and neither should be varied to match the other.
+ *
+ * Declared here rather than imported, which is this package's shape — marketing has no
+ * shared glyph module and TextInput states the same three the same way. A fourth copy
+ * would be the point at which one is worth making; three is not it yet.
+ */
+const statusGlyph = {
+    error: _jsx(CircleExclamationSolidIcon, {}),
+    warning: _jsx(TriangleExclamationSolidIcon, {}),
+    success: _jsx(CircleCheckSolidIcon, {}),
+};
+/**
+ * A real `<input type="checkbox">`, invisible, with the box the user sees drawn as
+ * its sibling.
+ *
+ * The tick lives inside `box`, which is a `<span>`, and the input covers the box rather
+ * than containing anything. So every part here is a real element the generator can name,
+ * *and* the control is native: it submits with a form, it takes the keyboard for free,
+ * and it carries the mixed state properly.
+ *
+ * That is why nothing below writes `role` or `aria-checked` by hand. The element is
+ * already a checkbox and already announces its state.
+ *
+ * It carries its own status and its own description. A lone consent is the case with
+ * nothing above it to hold either, and one that cannot show its own error is a form the
+ * reader cannot be told they failed.
+ */
+export function Checkbox({ tone = checkboxDefaults.tone, checked = checkboxDefaults.checked, status = checkboxDefaults.status, label, showLabel = checkboxDefaults.showLabel, description, statusMessage, id, onChange, ...rest }) {
+    const generatedId = useId();
+    // The label is a sibling rather than a wrapper, so the two need an id to be tied
+    // together. A consumer's own id wins — theirs may be what a form's error summary
+    // links to.
+    const fieldId = id ?? generatedId;
+    // Gated on the status rather than on the message having text. A box reporting an error
+    // with an empty message is a state the contract forbids, and empty is the honest
+    // rendering of a broken state.
+    const reporting = status !== 'none';
+    const showsMessage = reporting && given(statusMessage);
+    /*
+     * `given` rather than `!== undefined`, and the shared one rather than a fourth copy:
+     * absence is the switch for these props, so an empty or whitespace string has to count
+     * as absent. The preview's controls set '' when a designer clears a field rather than
+     * dropping the prop, which is how an empty line and the gap above it get left behind.
+     */
+    const describes = given(description);
+    /*
+     * Both, and in the order they are read on screen. A description says what ticking the
+     * box commits you to; a message says what is wrong with the answer — different things,
+     * so they stack rather than replace one another.
+     *
+     * A consumer's own reference is merged in rather than overwritten, so one they added
+     * cannot be dropped by this component having something to say.
+     */
+    const describedBy = [
+        describes ? `${fieldId}-description` : null,
+        showsMessage ? `${fieldId}-message` : null,
+        rest['aria-describedby'],
+    ]
+        .filter(Boolean)
+        .join(' ') || undefined;
+    /*
+     * `indeterminate` is a DOM property with no HTML attribute, so JSX cannot set it and
+     * this callback is the only way in.
+     *
+     * Deliberately not `aria-checked="mixed"` alongside it: a native checkbox already
+     * announces mixed from this property, and the explicit attribute would both repeat it
+     * and be free to contradict it — it does not clear itself when the property does.
+     */
+    const fieldRef = useCallback((node) => {
+        if (node !== null)
+            node.indeterminate = checked === 'indeterminate';
+    }, [checked]);
+    return (_jsxs("div", { className: checkboxParts.root, "data-tone": tone, "data-checked": checked, "data-status": status, children: [_jsxs("div", { className: checkboxParts.control, children: [_jsxs("span", { className: checkboxParts.box, children: [_jsx("input", { ...rest, ref: fieldRef, id: fieldId, type: "checkbox", className: checkboxParts.field, checked: checked === 'checked', onChange: onChange, 
+                                // React warns that a checked field without a handler is read-only, and it is
+                                // right: the state is the consumer's, and one that passes no handler has built
+                                // a checkbox nobody can change. Saying so is better than the warning.
+                                readOnly: onChange === undefined ? true : undefined, "aria-invalid": status === 'error' || undefined, "aria-describedby": describedBy }), _jsx("span", { className: checkboxParts.indicator, "aria-hidden": "true", children: checked === 'unchecked' ? null : (_jsx("svg", { viewBox: "0 0 24 24", width: "100%", height: "100%", fill: "none", focusable: "false", children: _jsx("path", { 
+                                        // A tick when chosen; a dash when the boxes this one summarises disagree.
+                                        // One horizontal stroke rather than a smaller square, because a filled box
+                                        // with something smaller inside it reads as a radio button gone wrong.
+                                        d: checked === 'checked' ? 'M5 12.5 10 17.5 19 7' : 'M6 12h12', stroke: "currentColor", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round" }) })) })] }), _jsxs("div", { className: checkboxParts.text, children: [_jsx("label", { className: checkboxParts.label, htmlFor: fieldId, style: showLabel ? undefined : visuallyHidden, children: label }), describes ? (_jsx("span", { id: `${fieldId}-description`, className: checkboxParts['description-text'], children: description })) : null] })] }), showsMessage ? (_jsxs("span", { id: `${fieldId}-message`, className: checkboxParts.message, children: [_jsx(Icon, { size: "xs", children: statusGlyph[status] }), statusMessage] })) : null] }));
+}

package/dist/components/core/checkbox/Checkbox.types.d.ts

@@ -0,0 +1,46 @@
+import type { InputHTMLAttributes } from 'react';
+export interface CheckboxOwnProps {
+    /**
+     * `standard` — The default, and almost always right — the ticked box fills with the neutral that outranks everything around it, so the choice is legible before any colour is read and it is the fill every other chosen control in this package takes, which is what lets a form of them read as one set of answers
+     * `accent` — The checkbox is the brand moment of the view — a single consent the design is deliberately drawing the eye to — and the surrounding design already carries brand red
+     */
+    tone?: 'standard' | 'accent';
+    /**
+     * `unchecked` — The default — the choice has not been made, or has been made against
+     * `checked` — The user has made this choice, or it arrives pre-made and they may change it
+     * `indeterminate` — A box that summarises others, where some but not all of them are ticked — a Select all above a partly selected list
+     */
+    checked?: 'unchecked' | 'checked' | 'indeterminate';
+    /** Always — it states what ticking the box agrees to, and the box shows nothing on its own. A phrase the user can read as a claim they are agreeing with: "Send me trade confirmations", not "Confirmations". Sentence case, and no full stop — a label is a phrase rather than a sentence, and a stop at the end of one reads as the start of prose. In a set, phrase every box the same way, so a reader compares the answers rather than the grammar */
+    label: string;
+    /** Drawing the words, which is nearly always. A checkbox on its own is a question, and a question with no words is not one */
+    showLabel?: boolean;
+    /** Ticking the box commits the user to something the label cannot carry without becoming a sentence — what it costs, how often it happens, what it applies to. On a box that summarises others it is where the summary belongs: "Four of six are on" says what an indeterminate tick cannot */
+    description?: string;
+}
+export type CheckboxProps = CheckboxOwnProps & Omit<InputHTMLAttributes<HTMLInputElement>, 'className' | 'tone' | 'checked' | 'status' | 'label' | 'showLabel' | 'description' | 'statusMessage'> & ({
+    status?: 'none' | 'error' | 'warning' | 'success';
+    statusMessage: string;
+} | {
+    status?: Exclude<'none' | 'error' | 'warning' | 'success', 'error' | 'warning'>;
+    statusMessage?: string;
+});
+/** The class each part carries. Apply these — do not retype them. */
+export declare const checkboxParts: {
+    readonly root: "dds-checkbox";
+    readonly control: "dds-checkbox__control";
+    readonly box: "dds-checkbox__box";
+    readonly field: "dds-checkbox__field";
+    readonly indicator: "dds-checkbox__indicator";
+    readonly text: "dds-checkbox__text";
+    readonly label: "dds-checkbox__label";
+    readonly 'description-text': "dds-checkbox__description-text";
+    readonly message: "dds-checkbox__message";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const checkboxDefaults: {
+    readonly tone: "standard";
+    readonly checked: "unchecked";
+    readonly status: "none";
+    readonly showLabel: true;
+};

package/dist/components/core/checkbox/Checkbox.types.js

@@ -0,0 +1,15 @@
+// GENERATED from checkbox.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const checkboxParts = {
+    root: 'dds-checkbox',
+    control: 'dds-checkbox__control',
+    box: 'dds-checkbox__box',
+    field: 'dds-checkbox__field',
+    indicator: 'dds-checkbox__indicator',
+    text: 'dds-checkbox__text',
+    label: 'dds-checkbox__label',
+    'description-text': 'dds-checkbox__description-text',
+    message: 'dds-checkbox__message',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const checkboxDefaults = { tone: 'standard', checked: 'unchecked', status: 'none', showLabel: true };