@deriv-com/dds-marketing 1.0.0 → 1.0.2

package/dist/components/core/background/background-impl.css

@@ -0,0 +1,427 @@
+/*
+ * Scoped to this package, like the generated sheet beside it.
+ *
+ * `:where([data-dds-context="marketing"])` confines these rules without contributing
+ * specificity, so every override below still ties or beats exactly what it did before.
+ */
+
+/*
+ * The canvas fills the band and sits under what the band holds.
+ *
+ * Absolutely placed at all four edges rather than sized by width and height, so it follows the
+ * band through every resize without the script having to set its CSS size — the script sets only
+ * the bitmap, from the box this gives it. No pointer events: the pattern is paint, and every press
+ * on the band belongs to the content.
+ *
+ * These are positions and a pointer rule, not design decisions, and a contract has no way to state
+ * an inset of zero on a part — which is why they are here rather than bound.
+ */
+:where([data-dds-context="marketing"]) .dds-background .dds-background__canvas {
+  position: absolute;
+  inset: 0;
+  display: block;
+  inline-size: 100%;
+  block-size: 100%;
+  pointer-events: none;
+}
+
+/*
+ * The content stacks above the canvas by being positioned after it. The root isolates, so this
+ * order is settled inside the band and nothing outside it has to know a canvas is there.
+ */
+:where([data-dds-context="marketing"]) .dds-background .dds-background__content {
+  position: relative;
+}
+
+/*
+ * A Background with nothing to hold is a layer: it fills the band it is placed in, behind that
+ * band's own content, which is how a block draws the pattern under itself without its layout
+ * changing. The band has to be positioned, and every block that offers the pattern is. It takes no
+ * pointer events — the content is on top and gets every press — and the pointer is listened for on
+ * the band instead, in `useHalftone`.
+ */
+:where([data-dds-context="marketing"]) .dds-background[data-layer='true'] {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+}
+
+/*
+ * The two hairline patterns: the rule grid, for `pattern="grid"` — the grid PageHeader paints, for
+ * any band — and the rings, for `pattern="rings"`.
+ *
+ * Both are repeating gradients of hairlines painted onto the root under everything it holds, with
+ * the band's own ground laid over them as a fade: opaque at the top, clear at the foot, so the
+ * lines rise from the bottom of the band the way the halftone does. A background-image rather than
+ * an element, because it is a texture on the ground and not content, and rather than a canvas
+ * because the only thing about it that moves is where the lines start — see *The idle motion*.
+ *
+ * The line takes the pattern role for the ground it is on: the inverse on the dark ground, a
+ * brighter white on the coral, and the brand's coral on the light — each a step above the subtle
+ * border, which a hairline drawn across a whole band thinned out to almost nothing. The fade is each tone's own ground, so
+ * the lines disappear into the band rather than into a colour the band is not.
+ */
+:where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings']) {
+  --dds-background-rule: var(--color-border-pattern-inverse);
+  --dds-background-fade: var(--color-bg-brand-strong);
+  /*
+   * How thick a rule is: border.width.hairline, which is half a CSS pixel — one device pixel on a
+   * screen of twice the density, and the line this grid was drawn with. A standard-density screen
+   * has no half pixel to draw it on, and there the rules came out faint or not at all depending on
+   * where each one fell: on a tall band every horizontal rule vanished. So below twice the density
+   * the rule is border.width.default, one pixel — the thinnest line that screen can draw.
+   */
+  --dds-background-hairline: var(--border-width-hairline);
+}
+
+@media (max-resolution: 1.99dppx) {
+  :where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings']) {
+    --dds-background-hairline: var(--border-width-default);
+  }
+}
+
+/*
+ * On the light ground the lines are the brand's coral rather than a grey, as the halftone's dots
+ * and the aurora's pools are there: a third of color.bg.brand, about as strong as the grey it
+ * replaces, so the grid stays quiet but reads as the brand's. It lights up to the full coral.
+ */
+:where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings'])[data-tone='light'] {
+  --dds-background-rule: color-mix(in srgb, var(--color-bg-brand) 35%, transparent);
+  --dds-background-fade: var(--color-bg-page);
+}
+
+/*
+ * On the coral ground the inverse pattern line, white at a quarter, all but vanished into the
+ * coral, so the lines rest at the muted inverse there and light up to full white.
+ */
+:where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings'])[data-tone='brand'] {
+  --dds-background-rule: var(--color-fg-muted-inverse);
+  --dds-background-fade: var(--color-bg-brand);
+}
+
+/*
+ * The grid: two sets of rules at size.rule-grid.pitch, one across and one down.
+ *
+ * `to right` is physical: a CSS gradient has no logical direction. A grid is symmetric, so it reads
+ * the same in either direction, and it is centred across the band — see the positions below.
+ */
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='grid'] {
+  --dds-background-pitch: var(--size-rule-grid-pitch);
+  background-image:
+    linear-gradient(to bottom, var(--dds-background-fade), transparent),
+    linear-gradient(to right, var(--dds-background-rule) 0 var(--dds-background-hairline), transparent 0),
+    linear-gradient(to bottom, var(--dds-background-rule) 0 var(--dds-background-hairline), transparent 0);
+  /*
+   * Each set of rules is one rule on a tile one pitch long, repeated: a tile the size of the band
+   * left a seam wherever the band was not a whole number of pitches, and a rising grid carried
+   * that seam up through it. Across, a rule falls on the band's middle — the tile is placed half a
+   * pitch right of centre, and its rule is its left edge — so the grid is symmetric about the
+   * middle, where the rings are centred and the words sit, and never ends on a sliver at one side
+   * only. Down, it counts from the top less the idle shift, so the rules rise a pitch a cycle.
+   */
+  background-size:
+    100% 100%,
+    var(--dds-background-pitch) 100%,
+    100% var(--dds-background-pitch);
+  background-repeat: no-repeat, repeat-x, repeat-y;
+  background-position:
+    left top,
+    calc(50% + var(--dds-background-pitch) / 2) top,
+    left calc(var(--dds-background-shift, 0%) * -1);
+}
+
+/*
+ * The rings: circles at size.rings.pitch, centred on the middle of the band's foot, so they spread
+ * up and out from where the halftone's glow would rest.
+ *
+ * Each ring is a hairline at full ink — as much line as a grid rule, so the two read at the same
+ * strength — with half a hairline of fade either side. A curve drawn with hard stops steps along
+ * every pixel it crosses; the fade anti-aliases it. A ridge that only touched the ink at its peak
+ * came out a good deal fainter than the grid in the same colour.
+ */
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='rings'] {
+  --dds-background-pitch: var(--size-rings-pitch);
+  background-image:
+    linear-gradient(to bottom, var(--dds-background-fade), transparent),
+    var(--dds-background-rings);
+}
+
+/*
+ * The rings themselves, declared on the root and on its lit copy alike, so each resolves them in
+ * its own ink. They start at the idle shift rather than at the centre, which spreads every ring a
+ * pitch outward each cycle: a repeating gradient repeats over its first stop to its last, and both
+ * move together, so the spacing never changes.
+ */
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='rings'],
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='rings']::before {
+  --dds-background-rings: repeating-radial-gradient(
+    circle at 50% 100%,
+    transparent var(--dds-background-shift, 0%)
+      calc(var(--dds-background-shift, 0%) + var(--dds-background-pitch) - var(--dds-background-hairline) * 2),
+    var(--dds-background-rule)
+      calc(var(--dds-background-shift, 0%) + var(--dds-background-pitch) - var(--dds-background-hairline) * 1.5)
+      calc(var(--dds-background-shift, 0%) + var(--dds-background-pitch) - var(--dds-background-hairline) * 0.5),
+    transparent calc(var(--dds-background-shift, 0%) + var(--dds-background-pitch))
+  );
+}
+
+/*
+ * The pointer's light on the grid and the rings, on an interactive band.
+ *
+ * A second, brighter copy of the lines, drawn in a pseudo-element behind the band's content and
+ * shown only inside a soft circle around the pointer — size.rule-grid.spotlight on the grid,
+ * size.rings.spotlight on the rings — so the lines under the pointer brighten and fade back into
+ * the resting ones, and nothing else changes. The pointer's position arrives as two custom
+ * properties written once a frame by `useSpotlight`, and `data-spotlit` while it is over the band;
+ * the circle fades in and out on the element's opacity, which the compositor runs.
+ *
+ * `::before`, so it comes before the content in the band's painting order and the content stays on
+ * top of it. The lit line is a step up from the resting one on each ground: muted-inverse on the
+ * dark ground, full white on the coral, the full brand coral on the light one. Same hairline, same pitch, same
+ * position, so a lit line is the resting line brighter rather than a line beside it.
+ */
+:where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings'])::before {
+  --dds-background-lit: var(--color-fg-muted-inverse);
+  /* The shift is registered as not inherited — see *The idle motion* — so the lit copy asks for it. */
+  --dds-background-shift: inherit;
+  content: '';
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  mask-image: radial-gradient(
+    circle var(--dds-background-reach) at var(--dds-background-spot-x, 50%) var(--dds-background-spot-y, 50%),
+    #000,
+    transparent
+  );
+  opacity: 0;
+  transition-property: opacity;
+  transition-duration: var(--motion-duration-normal);
+  transition-timing-function: var(--motion-easing-enter);
+}
+
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='grid']::before {
+  --dds-background-reach: var(--size-rule-grid-spotlight);
+  background-image:
+    linear-gradient(to right, var(--dds-background-lit) 0 var(--dds-background-hairline), transparent 0),
+    linear-gradient(to bottom, var(--dds-background-lit) 0 var(--dds-background-hairline), transparent 0);
+  background-size:
+    var(--dds-background-pitch) 100%,
+    100% var(--dds-background-pitch);
+  background-repeat: repeat-x, repeat-y;
+  background-position:
+    calc(50% + var(--dds-background-pitch) / 2) top,
+    left calc(var(--dds-background-shift, 0%) * -1);
+}
+
+/* The rings' lit copy: the same rings, with the rule redeclared as the lit ink. */
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='rings']::before {
+  --dds-background-reach: var(--size-rings-spotlight);
+  --dds-background-rule: var(--dds-background-lit);
+  background-image: var(--dds-background-rings);
+}
+
+:where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings'])[data-tone='light']::before {
+  --dds-background-lit: var(--color-bg-brand);
+}
+
+:where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings'])[data-tone='brand']::before {
+  --dds-background-lit: var(--color-fg-on-brand);
+}
+
+:where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings'])[data-spotlit='true']::before {
+  opacity: 1;
+}
+
+/*
+ * The aurora, for `pattern="aurora"`: broad soft pools of the brand's colour rising from the
+ * band's foot and drifting into one another — the band lit by colour rather than by points.
+ *
+ * Three ellipses fading to nothing, in two inks, painted on a pseudo-element behind the content
+ * and larger than the band, so it can sway either way without its edge showing. The sway is a
+ * transform about the middle of the foot, there and back over motion.duration.drift: a small
+ * slide, a small turn and a slight swell, and because the turn lifts one side as it lowers the
+ * other, the pools pass across each other rather than moving as one. A transform, so the
+ * compositor runs it and the gradients are painted once rather than every frame.
+ *
+ * The inks are the tone's: coral deepening to the brand's darkest on the dark ground; coral and
+ * its hover step, washed thin, on the light ground; and on the coral ground white and the brand's
+ * darkest, as the halftone's dots turn white there — darker inks alone were lost on the coral, and
+ * near-black came out as a muddy stain rather than light. The white stays at the foot, under the
+ * words rather than behind them, and the words are checked against the coral alone. How strongly
+ * it is painted is a share of the pool's own opacity, as the halftone's is — under half on the
+ * dark ground, where coral at seven tenths burned rather than glowed, and faintest on the light,
+ * where coral at strength would be a coral band.
+ *
+ * The band's top stays plain: the pools fade out under a mask before they reach the upper third.
+ */
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora'] {
+  --dds-background-pool: var(--color-bg-brand);
+  --dds-background-pool-deep: var(--color-bg-brand-active);
+  --dds-background-strength: 0.4;
+  /*
+   * How strongly the pool under the pointer is painted, per ground. Its own number rather than a
+   * share of the pools': half of the light ground's faint wash was invisible, and half of the
+   * coral ground's white washed out the white words the pointer was over.
+   */
+  --dds-background-hover: 0.25;
+}
+
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora'][data-tone='light'] {
+  --dds-background-pool-deep: var(--color-bg-brand-hover);
+  --dds-background-strength: 0.22;
+  --dds-background-hover: 0.3;
+}
+
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora'][data-tone='brand'] {
+  --dds-background-pool: var(--color-fg-on-brand);
+  --dds-background-pool-deep: var(--color-bg-brand-active);
+  --dds-background-strength: 0.6;
+  --dds-background-hover: 0.2;
+}
+
+/*
+ * Behind the content without being before it: the root isolates, so a negative stacking order
+ * puts both pseudo-elements over the band's ground and under everything it holds.
+ */
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora']::before,
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora']::after {
+  content: '';
+  position: absolute;
+  z-index: -1;
+  pointer-events: none;
+}
+
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora']::before {
+  /*
+   * Half a band deeper than the band, as well as wider: the turn lowers one end of the layer, and
+   * a layer that stopped at the foot showed its own edge there as a hard diagonal. So the foot is
+   * two thirds of the way down the layer, and every position and reach below is measured to it.
+   */
+  inset-block: 0 -50%;
+  inset-inline: -25%;
+  background-image:
+    radial-gradient(ellipse 30% 53% at 32% calc(100% / 1.5), var(--dds-background-pool), transparent),
+    radial-gradient(ellipse 26% 43% at 66% calc(100% / 1.5), var(--dds-background-pool-deep), transparent),
+    radial-gradient(ellipse 18% 31% at 50% calc(100% / 1.5), var(--dds-background-pool), transparent);
+  mask-image: linear-gradient(to bottom, transparent 20%, #000 calc(100% / 1.5));
+  opacity: var(--dds-background-strength);
+  transform-origin: 50% calc(100% / 1.5);
+  animation: dds-background-aurora var(--motion-duration-drift) var(--motion-easing-shift) infinite alternate;
+}
+
+@keyframes dds-background-aurora {
+  from {
+    transform: translateX(-6%) rotate(-3deg);
+  }
+  to {
+    transform: translateX(6%) rotate(3deg) scale(1.08, 1.14);
+  }
+}
+
+/*
+ * The pool that trails the pointer: a disc of the pool's ink, size.aurora.spotlight in radius,
+ * moved under the pointer by a transform that eases after it over motion.duration.trail — the
+ * halftone's glow and this one keep the same distance behind the hand. Placed from the band's
+ * physical top left because the pointer's position is measured from there. It fades in while the
+ * pointer is over the band and out when it leaves, at the ground's own hover strength: at the
+ * pools' full strength, and twice the size, it washed over a narrow band and drowned its words.
+ *
+ * It trails the pointer only while lit. Unlit it moves at once, so the pointer arriving puts the
+ * pool where the pointer is before it fades in — `useSpotlight` writes the position first —
+ * rather than the pool sliding in from wherever it last was, or from the band's corner.
+ */
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora']::after {
+  left: 0;
+  top: 0;
+  inline-size: calc(var(--size-aurora-spotlight) * 2);
+  block-size: calc(var(--size-aurora-spotlight) * 2);
+  /*
+   * Eased to nothing rather than straight to it: a straight fade stops abruptly at its rim, and the
+   * eye read the stop as the edge of a disc. The steps follow a smooth curve down from the centre.
+   */
+  background-image: radial-gradient(
+    circle closest-side,
+    var(--dds-background-pool),
+    color-mix(in srgb, var(--dds-background-pool) 62%, transparent) 30%,
+    color-mix(in srgb, var(--dds-background-pool) 26%, transparent) 58%,
+    color-mix(in srgb, var(--dds-background-pool) 7%, transparent) 82%,
+    transparent
+  );
+  transform: translate(
+    calc(var(--dds-background-spot-x, 50%) - var(--size-aurora-spotlight)),
+    calc(var(--dds-background-spot-y, 50%) - var(--size-aurora-spotlight))
+  );
+  opacity: 0;
+  transition-property: opacity, transform;
+  transition-duration: var(--motion-duration-normal), var(--motion-duration-instant);
+  transition-timing-function: var(--motion-easing-enter);
+}
+
+:where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora'][data-spotlit='true']::after {
+  opacity: var(--dds-background-hover);
+  transition-duration: var(--motion-duration-normal), var(--motion-duration-trail);
+}
+
+/*
+ * The idle motion of the grid and the rings: the grid's rules rise a pitch and the rings spread a
+ * pitch outward, over motion.duration.drift at an even pace, and again — a pitch on, the pattern
+ * is where it began, so the loop has no seam. The halftone's glow and the
+ * aurora's pools drift in the same time, so every pattern is moving at a band's pace at rest.
+ *
+ * The shift is registered so it can be animated: an unregistered custom property only flips from
+ * one value to the next. It is not inherited, so the frames reach the root and the lit copy that
+ * asks for it, and never restyle the band's content. What moves is a background's start, which
+ * repaints the band whenever it changes — so it changes in two hundred even steps a cycle, about
+ * twenty a second, rather than at the display's rate: well under a pixel a step at this pace,
+ * so it still reads as smooth, and as cheap as the halftone's drift, which draws at thirty. It
+ * stops while the band is off screen (`data-offscreen`, written by Background), and when the band
+ * is asked to hold still.
+ */
+@property --dds-background-shift {
+  syntax: '<length>';
+  inherits: false;
+  initial-value: 0;
+}
+/*
+ * Every use names a fallback of nothing, for an engine without `@property`: there the shift is an
+ * unregistered property nobody sets while the band is still, and a bare reference to it would make
+ * the whole background invalid — the grid and the rings would vanish exactly when motion is off.
+ */
+
+:where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings']) {
+  animation: dds-background-shift var(--motion-duration-drift) steps(200) infinite;
+}
+
+@keyframes dds-background-shift {
+  to {
+    --dds-background-shift: var(--dds-background-pitch);
+  }
+}
+
+/* Off screen, nobody sees it move: every pattern's idle motion waits where it is. */
+:where([data-dds-context="marketing"]) .dds-background[data-offscreen='true'],
+:where([data-dds-context="marketing"]) .dds-background[data-offscreen='true']::before {
+  animation-play-state: paused;
+}
+
+/* `animated={false}`: every pattern holds still at rest. What it does under the pointer is `interactive`. */
+:where([data-dds-context="marketing"]) .dds-background[data-animated='false'],
+:where([data-dds-context="marketing"]) .dds-background[data-animated='false'][data-pattern='aurora']::before {
+  animation: none;
+}
+
+/*
+ * For a reader who asked for less motion, nothing moves at rest, and the pointer's light on every
+ * pattern comes and goes at once rather than fading or trailing.
+ */
+@media (prefers-reduced-motion: reduce) {
+  :where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings']),
+  :where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora']::before {
+    animation: none;
+  }
+
+  :where([data-dds-context="marketing"]) .dds-background:is([data-pattern='grid'], [data-pattern='rings'], [data-pattern='aurora'])::before,
+  :where([data-dds-context="marketing"]) .dds-background[data-pattern='aurora']::after {
+    transition: none;
+  }
+}

package/dist/components/core/background/halftone.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The halftone, drawn on a canvas and only when it has to be.
+ *
+ * A grid of dots, each as large and as bright as the glow is where it sits: full at the glow's
+ * centre, falling away along a soft ellipse, and gone at the edges. The glow rests at the middle of
+ * the band's bottom edge and — where the band allows it — follows the pointer. The dots themselves
+ * answer the pointer too: a moving pointer shoves the ones near it aside and a click sends a ripple
+ * out from where it landed, and each dot springs back to its place in the grid.
+ *
+ * What it costs is the reason it is written this way rather than as CSS or as an animation loop:
+ *
+ * - It draws on change and nowhere else. A resize draws one frame; a pointer draws frames only
+ *   while the glow is catching up or a dot is still moving. The resting drift is the one thing that
+ *   keeps it drawing, at half the display's rate, and only while the band is on screen and motion
+ *   is allowed — with the drift set to nothing, a band nobody is touching runs no code at all.
+ * - A band out of view draws nothing, and catches up with one frame when it returns.
+ * - The bitmap is held to twice the CSS pixel density, which is all a dot this small can use.
+ * - The dots are batched by brightness into a few dozen paths, so a frame is a few dozen fills
+ *   rather than one per dot. Drawing visits only the rows below the pattern's edge, rejects a dot
+ *   too small to be seen before working out its light — every dot, while the size floor keeps the
+ *   screen across the whole band — and draws a dot under a pixel and a half as a square, which
+ *   nobody can tell from a circle at that size.
+ * - Pointer events only record where the pointer is. The frame reads the band's position once and
+ *   acts on it, so a fast mouse costs one layout read a frame rather than one per event; a shove or
+ *   a ripple visits the grid cells it can reach, and the spring visits only the dots still moving.
+ *
+ * Every default comes from a token: the inks are the canvas's computed `color` (the glow's edge) and
+ * `outline-color` (its centre), the grid is
+ * size.halftone.pitch and size.halftone.dot, and the glow's movement is the canvas's transition
+ * duration and timing function. The rest are settings this file names, and `retune` overrides any
+ * of them while a pattern is being decided — the preview's Tune panel, and nothing a page uses.
+ */
+export interface HalftoneOptions {
+    /** Whether the pattern answers the pointer. Ignored for reduced motion. */
+    interactive: boolean;
+    /** Whether the resting glow drifts on its own. Ignored for reduced motion. */
+    animated: boolean;
+    /**
+     * Where the pointer is listened for, when that is not the band itself — a Background used as a
+     * layer behind a block's content, where the content covers the layer and the pointer never
+     * reaches it. Positions are still measured against the band.
+     */
+    host?: HTMLElement;
+}
+export interface Halftone {
+    /** Stop listening, stop drawing, and let go of every observer. */
+    destroy: () => void;
+}
+/** Every setting the pattern is drawn with. Colours are any CSS colour; lengths are CSS pixels. */
+export interface HalftoneTuning {
+    /** The dots' colour at the edge of the glow. Defaults to the canvas's `color`. */
+    base: string;
+    /** The dots' colour at the glow's centre. Defaults to the canvas's outline colour. */
+    active: string;
+    /** How opaque the faintest dots are, from 0 to 1 — what makes the edge a fade, not a line. */
+    floor: number;
+    /**
+     * How strong the whole pattern is, from 0 to 1: every dot's opacity, scaled. The pattern's shape
+     * is untouched — the glow, the fade, the floor — only how loudly it is drawn.
+     */
+    opacity: number;
+    /** The widest a dot grows, at the glow's centre. size.halftone.dot. */
+    dot: number;
+    /** Centre to centre, between neighbouring dots. size.halftone.pitch. */
+    pitch: number;
+    /** How wide the glow reaches, as a share of the band's width. */
+    reachX: number;
+    /** How tall the glow reaches, as a share of the band's height. */
+    reachY: number;
+    /**
+     * How large the glow is while a pointer is over the band, as a share of its resting size. Below 1
+     * the light gathers under the pointer instead of washing across the band it rested across.
+     */
+    hoverScale: number;
+    /**
+     * Where the pattern begins, as a share of the band's height from the top. Above it no dot is
+     * drawn, whatever the glow is doing — 0.3 would keep the pattern to the band's lower seven tenths.
+     */
+    top: number;
+    /** How soft the pattern's upper edge is, as a share of the band's height. */
+    topFade: number;
+    /**
+     * The smallest a dot gets, however far it is from the glow, as a share of its widest — what
+     * keeps the screen of dots across the whole band rather than only around the glow. 0 lets the
+     * dots far from the glow shrink to nothing.
+     */
+    sizeFloor: number;
+    /** The highest the glow may rise towards the pointer, as a share of the band's height from the top. */
+    ceiling: number;
+    /** How sharply the glow falls off — higher is a tighter, harder-edged glow. */
+    falloff: number;
+    /** Where the glow rests, as a share of the band's width. */
+    restX: number;
+    /** Where the glow rests, as a share of the band's height. */
+    restY: number;
+    /** How long the glow takes to catch up with the pointer and to glide back to rest, in ms. */
+    follow: number;
+    /** How far the resting glow drifts either side of its rest, as a share of the band's width. 0 holds it still. */
+    drift: number;
+    /** How far it rises and falls as it drifts, as a share of the band's height. */
+    driftRise: number;
+    /** How long one sweep of the drift takes, in seconds — longer is slower. */
+    driftPeriod: number;
+    /** How far from a moving pointer the dots are shoved aside, in px. 0 turns the shove off. */
+    proximity: number;
+    /** How hard the dots resist being shoved — higher moves them less. */
+    resistance: number;
+    /** How long a shoved dot takes to settle back into the grid, in seconds. */
+    returnDuration: number;
+    /** How far a click's ripple reaches, in px. 0 turns the ripple off. */
+    shockRadius: number;
+    /** How hard a click's ripple pushes the dots it reaches. */
+    shockStrength: number;
+}
+/**
+ * Override settings on every halftone on the page, live. For deciding a pattern — the preview's
+ * Tune panel calls it — and never for a page: what a page draws is what the tokens and the
+ * settings above say.
+ */
+export declare function retune(next: Partial<HalftoneTuning>): void;
+/** The settings the last halftone drew with, overrides included — for a panel to show. */
+export declare function currentTuning(): HalftoneTuning | null;
+export declare function halftone(root: HTMLElement, canvas: HTMLCanvasElement, options: HalftoneOptions): Halftone;