@jtakeit/astro 0.1.0

package/template/src/components/motion/fields.ts

@@ -0,0 +1,430 @@
+/**
+ * The hero fields, as GLSL.
+ *
+ * Data only — no DOM, no WebGL calls. `HeroField.astro` owns the canvas, the
+ * palette, the sizing budget and every path back to the still CSS ground; this
+ * file is what each field actually looks like, which is the part worth reading
+ * on its own.
+ *
+ * Adding one is a fragment source plus a row in FRAGMENT. What it has to earn
+ * is a *different job* — another variation on soft coloured blobs is the same
+ * field with different constants.
+ *
+ * Every fragment shader is handed the same uniforms:
+ *
+ *   u_resolution  canvas pixels
+ *   u_time        seconds, already multiplied by the component's `speed`
+ *   u_grain       0–1
+ *   u_colors[4]   the variant's tokens, in the order they were passed
+ *   u_bg          the ground colour
+ */
+
+export type Field =
+  | 'drift'
+  | 'aurora'
+  | 'plasma'
+  | 'glow'
+  | 'flow'
+  | 'silk'
+  | 'smoke'
+  | 'riso'
+  | 'veil'
+  | 'ribbons';
+
+/** The fields drawn by a fragment shader. `ribbons` is Canvas 2D and is not one. */
+export type ShaderField = Exclude<Field, 'ribbons'>;
+
+export const VERTEX = `attribute vec2 a_position;
+void main() { gl_Position = vec4(a_position, 0.0, 1.0); }`;
+
+/*
+ * highp where it exists, mediump where it does not. A phone GPU without highp
+ * in the fragment stage renders the noise as banding rather than failing, so
+ * the guard is worth the four lines.
+ */
+const HEAD = `#ifdef GL_FRAGMENT_PRECISION_HIGH
+precision highp float;
+#else
+precision mediump float;
+#endif
+
+uniform vec2 u_resolution;
+uniform float u_time;
+uniform float u_grain;
+uniform vec3 u_colors[4];
+uniform vec3 u_bg;
+
+// Even, unstructured noise for the grain. A multiply hash shows a faint
+// axis-aligned mesh at integer fragment coordinates, which reads as a net.
+float grainHash(vec2 p) {
+  vec3 p3 = fract(vec3(p.xyx) * 0.1031);
+  p3 += dot(p3, p3.yzx + 33.33);
+  return fract((p3.x + p3.y) * p3.z);
+}
+`;
+
+/** Value noise: cheap, slightly blocky, right for large soft shapes. */
+const VALUE_NOISE = `
+float hash21(vec2 p) {
+  p = fract(p * vec2(234.34, 435.345));
+  p += dot(p, p + 34.23);
+  return fract(p.x * p.y);
+}
+
+float noise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  return mix(
+    mix(hash21(i), hash21(i + vec2(1.0, 0.0)), u.x),
+    mix(hash21(i + vec2(0.0, 1.0)), hash21(i + vec2(1.0, 1.0)), u.x),
+    u.y);
+}
+
+float fbm(vec2 p) {
+  float v = 0.0;
+  float a = 0.5;
+  for (int i = 0; i < 4; i++) {
+    v += a * noise(p);
+    p = p * 2.03 + vec2(17.0, 9.2);
+    a *= 0.5;
+  }
+  return v;
+}
+`;
+
+/** Simplex noise: smoother and directionless, right for anything flowing. */
+const SIMPLEX = `
+vec3 permute(vec3 x) { return mod(((x * 34.0) + 1.0) * x, 289.0); }
+
+float snoise(vec2 v) {
+  const vec4 C = vec4(0.211324865405187, 0.366025403784439,
+                     -0.577350269189626, 0.024390243902439);
+  vec2 i = floor(v + dot(v, C.yy));
+  vec2 x0 = v - i + dot(i, C.xx);
+  vec2 i1 = (x0.x > x0.y) ? vec2(1.0, 0.0) : vec2(0.0, 1.0);
+  vec4 x12 = x0.xyxy + C.xxzz;
+  x12.xy -= i1;
+  i = mod(i, 289.0);
+  vec3 p = permute(permute(i.y + vec3(0.0, i1.y, 1.0)) + i.x + vec3(0.0, i1.x, 1.0));
+  vec3 m = max(0.5 - vec3(dot(x0, x0), dot(x12.xy, x12.xy), dot(x12.zw, x12.zw)), 0.0);
+  m = m * m;
+  m = m * m;
+  vec3 x = 2.0 * fract(p * C.www) - 1.0;
+  vec3 h = abs(x) - 0.5;
+  vec3 ox = floor(x + 0.5);
+  vec3 a0 = x - ox;
+  m *= 1.79284291400159 - 0.85373472095314 * (a0 * a0 + h * h);
+  vec3 g;
+  g.x = a0.x * x0.x + h.x * x0.y;
+  g.yz = a0.yz * x12.xz + h.yz * x12.yw;
+  return 130.0 * dot(m, g);
+}
+`;
+
+/**
+ * A ramp through the four colours. WebGL1 forbids indexing a uniform array by
+ * a computed value in the fragment stage, so the steps are written out.
+ */
+const PALETTE = `
+vec3 palette(float x) {
+  float f = clamp(x, 0.0, 1.0) * 3.0;
+  vec3 col = u_colors[0];
+  col = mix(col, u_colors[1], smoothstep(0.0, 1.0, clamp(f, 0.0, 1.0)));
+  col = mix(col, u_colors[2], smoothstep(0.0, 1.0, clamp(f - 1.0, 0.0, 1.0)));
+  col = mix(col, u_colors[3], smoothstep(0.0, 1.0, clamp(f - 2.0, 0.0, 1.0)));
+  return col;
+}
+`;
+
+/** Four lamps of colour on slow orbits through a warped field. */
+const DRIFT = `
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_resolution.xy;
+  float m = min(u_resolution.x, u_resolution.y);
+  // Aspect-corrected, so the field does not stretch with the window.
+  vec2 p = (gl_FragCoord.xy - 0.5 * u_resolution.xy) / m * 1.3;
+  float t = u_time;
+
+  p += 0.15 * vec2(sin(t * 0.31), cos(t * 0.23));
+  p += 0.19 * (vec2(fbm(p * 2.0), fbm(p * 2.0 + vec2(5.2, 1.3))) - 0.5);
+
+  vec3 acc = u_bg * 0.25;
+  float total = 0.25;
+  for (int i = 0; i < 4; i++) {
+    float fi = float(i);
+    vec2 c = vec2(
+      sin(t * (0.21 + fi * 0.071) + fi * 2.4),
+      cos(t * (0.17 + fi * 0.093) + fi * 1.7)) * 0.75;
+    float w = exp(-dot(p - c, p - c) * 3.4);
+    acc += u_colors[i] * w;
+    total += w;
+  }
+  vec3 col = acc / total;
+
+  float vd = length(uv - 0.5) * 1.41421356;
+  col *= 1.0 - 0.15 * smoothstep(0.35, 1.0, vd);
+  col += (grainHash(gl_FragCoord.xy + vec2(t * 17.0)) - 0.5) * u_grain * 0.09;
+  gl_FragColor = vec4(clamp(col, 0.0, 1.0), 1.0);
+}
+`;
+
+/** Three layers of simplex noise riding each other. Weather. */
+const AURORA = `
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_resolution.xy;
+  vec2 p = uv - 0.5;
+  p.x *= u_resolution.x / u_resolution.y;
+  float t = u_time * 0.1;
+
+  // The second and third layers take the one above as an offset, which is what
+  // turns noise into weather.
+  float n1 = snoise(p * 0.4 + vec2(t * 0.2, -t * 0.3));
+  float n2 = snoise(p * 0.55 + vec2(-t * 0.15, t * 0.25) + n1 * 0.25);
+  float n3 = snoise(p * 0.75 + vec2(t * 0.1, -t * 0.2) + n2 * 0.2);
+
+  float dist = length(p) * 1.5;
+  float vignette = 1.0 - smoothstep(0.3, 1.2, dist);
+
+  vec3 col = u_bg;
+  col = mix(col, u_colors[0], smoothstep(-0.2, 0.5, n1) * 0.85);
+  col = mix(col, u_colors[1], smoothstep(-0.1, 0.6, n2) * 0.70);
+  col = mix(col, u_colors[2], smoothstep(-0.3, 0.4, n3) * 0.60);
+  col = mix(col, u_colors[3], smoothstep(0.0, 0.7, n1 * n2) * 0.50);
+  col += u_colors[1] * smoothstep(0.8, 0.0, dist) * 0.3;
+  col = mix(u_bg, col, 0.2 + 0.8 * vignette);
+
+  col += (grainHash(gl_FragCoord.xy + vec2(u_time * 17.0)) - 0.5) * u_grain * 0.1;
+  gl_FragColor = vec4(clamp(col, 0.0, 1.0), 1.0);
+}
+`;
+
+/**
+ * Interference. Four sine fields summed and read through the palette, which
+ * produces bands and rings rather than blobs — the one field in the set with
+ * visible structure to it.
+ */
+const PLASMA = `
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_resolution.xy;
+  float m = min(u_resolution.x, u_resolution.y);
+  vec2 p = (gl_FragCoord.xy - 0.5 * u_resolution.xy) / m * 1.5;
+  float t = u_time;
+
+  p += 0.32 * vec2(sin(t * 0.31), cos(t * 0.23));
+
+  // Higher k is more rings in the same frame. Past ~9 a phone shows moiré.
+  float k = 7.0;
+  float v = sin(p.x * k + t)
+    + sin(p.y * k * 0.8 - t * 0.7)
+    + sin((p.x + p.y) * k * 0.6 + t * 0.5)
+    + sin(length(p) * k * 1.2 - t);
+  vec3 col = palette(0.5 + 0.5 * sin(v));
+
+  float vd = length(uv - 0.5) * 1.41421356;
+  col = mix(col, u_bg, 0.61 * smoothstep(0.35, 1.0, vd));
+  col += (grainHash(gl_FragCoord.xy + vec2(t * 17.0)) - 0.5) * u_grain * 0.12;
+  gl_FragColor = vec4(clamp(col, 0.0, 1.0), 1.0);
+}
+`;
+
+/**
+ * One bright filament of light in a dark room. Almost all of the frame stays
+ * near the ground colour, which is what makes the lit part read as light rather
+ * than as paint — and what makes this the only field in the set that needs a
+ * dark ground to work at all.
+ */
+const GLOW = `
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_resolution.xy;
+  vec2 p = uv * vec2(u_resolution.x / u_resolution.y, 1.0);
+  float t = u_time * 0.2;
+
+  float n1 = snoise(p * 0.5 + t);
+  float n2 = snoise(p * 0.9 - t * 0.5 + n1);
+  float n3 = snoise(p * 1.6 + t * 0.35 + n2 * 0.5);
+  // The power is what thins the lit band into a filament: everything but the
+  // ridge of the noise falls away to nothing.
+  float light = pow(abs(n2), 2.5) * 0.5;
+
+  vec3 col = u_bg;
+  col += u_colors[0] * smoothstep(0.1, 1.0, n1) * 0.5;
+  col += u_colors[1] * light;
+  col += u_colors[2] * pow(abs(n3), 4.0) * 0.35;
+
+  col += (grainHash(gl_FragCoord.xy + vec2(u_time * 17.0)) - 0.5) * u_grain * 0.16;
+  // Toward the ground rather than toward black, so a light palette is possible
+  // even though this field does not really want one.
+  col = mix(u_bg, col, smoothstep(1.2, 0.2, length(uv - 0.5)));
+  gl_FragColor = vec4(clamp(col, 0.0, 1.0), 1.0);
+}
+`;
+
+/**
+ * A flow field. An fbm sample decides a direction at every point, and a second
+ * one is read along it — which is what turns noise into something that appears
+ * to be *moving somewhere*, like ink pulled through water or marbled paper.
+ */
+const FLOW = `
+void main() {
+  float m = min(u_resolution.x, u_resolution.y);
+  vec2 p = (gl_FragCoord.xy - 0.5 * u_resolution.xy) / m * 1.5;
+  float t = u_time;
+
+  float angle = fbm(p * 2.0 + 1.7) * 6.2831;
+  vec2 dir = vec2(cos(angle), sin(angle));
+  vec3 col = palette(fbm(p * 3.0 + dir * 1.1 + t * 0.10));
+
+  col += (grainHash(gl_FragCoord.xy + vec2(t * 17.0)) - 0.5) * u_grain * 0.06;
+  gl_FragColor = vec4(clamp(col, 0.0, 1.0), 1.0);
+}
+`;
+
+/**
+ * Silk. Four rounds of feeding the coordinate back through a cosine of itself
+ * fold the plane into smooth creases — the softest field in the set, and the
+ * one that survives being put behind a lot of text.
+ */
+const SILK = `
+void main() {
+  float m = min(u_resolution.x, u_resolution.y);
+  vec2 q = (gl_FragCoord.xy - 0.5 * u_resolution.xy) / m * 1.5 * 1.6;
+  float t = u_time * 0.35;
+
+  float amp = 0.72;
+  for (float i = 1.0; i < 5.0; i += 1.0) {
+    q.x += amp / i * cos(i * 2.4 * q.y + t * 0.8 + 1.0);
+    q.y += amp / i * cos(i * 1.7 * q.x + t * 0.6);
+  }
+  vec3 col = palette(0.5 + 0.5 * sin(q.x + q.y));
+
+  col += (grainHash(gl_FragCoord.xy + vec2(u_time * 17.0)) - 0.5) * u_grain * 0.06;
+  gl_FragColor = vec4(clamp(col, 0.0, 1.0), 1.0);
+}
+`;
+
+
+/**
+ * Smoke. Two rounds of domain warping — an fbm pair displaces the plane, and a
+ * second pair displaces it again — which is what produces volume: plumes that
+ * fold over each other and read as depth rather than as a pattern on a wall.
+ *
+ * The behaviour is the classic Iñigo Quilez warp, by way of the 21st.dev shader
+ * builder's "Smoke". What arrived with it was a fixed blue palette, and that is
+ * the half that had to go: the ramp is `u_colors` here, so it is their smoke.
+ *
+ * It is not `flow`. That one is a single flow field — one direction per point,
+ * one sample read along it — and it reads as marbling, flat and streaked. This
+ * has an inside.
+ */
+const SMOKE = `
+void main() {
+  float m = min(u_resolution.x, u_resolution.y);
+  // Deliberately wider than the flow field. At the same scale the two are the
+  // same picture: what separates them is that this has a handful of large
+  // plumes crossing the frame, where flow is even everywhere.
+  vec2 p = (gl_FragCoord.xy - 0.5 * u_resolution.xy) / m * 1.1;
+  float t = u_time;
+
+  // How far the second warp pushes. Past ~6 the plumes stop reading as one
+  // volume and start reading as noise.
+  const float warp = 5.0;
+  vec2 q = vec2(fbm(p + t * 0.08), fbm(p + vec2(5.2, 1.3) - t * 0.06));
+  vec2 r = vec2(fbm(p + warp * q + vec2(1.7, 9.2)),
+                fbm(p + warp * q + vec2(8.3, 2.8)));
+  // The contrast goes on the ramp coordinate, not on the finished colour.
+  // Two rounds of warping pull fbm hard toward its average, so the field needs
+  // spreading — but spreading the *colour* blows the light end of the palette
+  // to white, and the centre below 0.5 is what keeps the dark end in the frame.
+  vec3 col = palette(clamp((fbm(p + 3.0 * r) - 0.5) * 1.4 + 0.4, 0.0, 1.0));
+
+  col += (grainHash(gl_FragCoord.xy + vec2(t * 17.0)) - 0.5) * u_grain * 0.07;
+  gl_FragColor = vec4(clamp(col, 0.0, 1.0), 1.0);
+}
+`;
+
+/**
+ * Riso. A slow wave through the palette, read through a coarse *quantised*
+ * noise — the ramp is dithered into cells of flat colour before it is looked
+ * up, which is the risograph and newsprint fault, not a texture laid on top.
+ *
+ * That distinction is the whole field. `u_grain` adds noise to the finished
+ * pixel and every field here has it; this adds noise to the *position in the
+ * ramp*, so the speckle lands as neighbouring bands of solid colour with a
+ * ragged border between them. It is the one field in the set that does not
+ * produce a smooth gradient, and the one that survives being printed.
+ *
+ * The cell is in device pixels and does not move. A dither that drifts shimmers,
+ * which is a screen effect; a dither that sits still is ink.
+ */
+const RISO = `
+void main() {
+  float m = min(u_resolution.x, u_resolution.y);
+  // Two or three bands across the frame, not six. Wide bands leave flat areas
+  // for the dither to *not* be in, and a speckle that is everywhere is a
+  // texture rather than a print.
+  vec2 p = (gl_FragCoord.xy - 0.5 * u_resolution.xy) / m * 1.4;
+  float t = u_time;
+
+  vec2 q = p;
+  q.x += sin(q.y * 2.1 + t * 0.2) * 0.33;
+  q.y += cos(q.x * 2.7 - t * 0.17) * 0.26;
+  float wave = 0.5 + 0.5 * sin(q.x * 2.4 + q.y * 1.6 + fbm(q * 2.0) * 3.0);
+
+  // Three device pixels: coarse enough to see as ink, fine enough that it is
+  // not a mosaic. The amplitude decides how far into the neighbouring band a
+  // speckle can reach — past ~0.3 the ramp stops being a gradient at all.
+  float cell = hash21(floor(gl_FragCoord.xy / 3.0));
+  vec3 col = palette(clamp(wave + (cell - 0.5) * 0.22, 0.0, 1.0));
+
+  gl_FragColor = vec4(clamp(col, 0.0, 1.0), 1.0);
+}
+`;
+
+/**
+ * Veil. A curtain: one fbm decides where the drapery hangs, a second is read
+ * *along* it, and the whole thing fades out toward the top and bottom edges of
+ * the frame.
+ *
+ * It is the field anchored to an edge. `aurora` is centred — a glow in the
+ * middle with a vignette around it — and everything in it points inward; this
+ * hangs from the horizontal and thins as it rises, so the hero's copy sits in
+ * the quiet part rather than on top of the bright part. Two fields of weather
+ * with two different compositions.
+ *
+ * Where the curtain is absent the ground shows through, which is why it wants a
+ * ground worth showing.
+ */
+const VEIL = `
+void main() {
+  float m = min(u_resolution.x, u_resolution.y);
+  vec2 p = (gl_FragCoord.xy - 0.5 * u_resolution.xy) / m * 1.88;
+  float t = u_time;
+
+  float curtain = fbm(vec2(p.x * 2.0 + t * 0.15, p.y * 0.6 - t * 0.05));
+  // The second sample is indexed by the first rather than offset by it, which
+  // is what makes the bands hang vertically instead of drifting sideways.
+  float band = fbm(vec2(p.x * 2.2 - t * 0.1, curtain * 2.4));
+  // The upper bound sits past 1: the curtain never quite reaches the brightest
+  // colour, which is the difference between a veil and a floodlight.
+  float glow = smoothstep(0.18, 1.05, band) * (1.0 - abs(p.y) * 0.55);
+
+  vec3 col = mix(u_bg, palette(clamp(glow, 0.0, 1.0)),
+    0.12 + 0.88 * smoothstep(0.0, 0.35, glow));
+
+  col += (grainHash(gl_FragCoord.xy + vec2(t * 17.0)) - 0.5) * u_grain * 0.08;
+  gl_FragColor = vec4(clamp(col, 0.0, 1.0), 1.0);
+}
+`;
+
+export const FRAGMENT: Record<ShaderField, string> = {
+  drift: HEAD + VALUE_NOISE + DRIFT,
+  aurora: HEAD + SIMPLEX + AURORA,
+  plasma: HEAD + PALETTE + PLASMA,
+  glow: HEAD + SIMPLEX + GLOW,
+  flow: HEAD + VALUE_NOISE + PALETTE + FLOW,
+  silk: HEAD + PALETTE + SILK,
+  smoke: HEAD + VALUE_NOISE + PALETTE + SMOKE,
+  riso: HEAD + VALUE_NOISE + PALETTE + RISO,
+  veil: HEAD + VALUE_NOISE + PALETTE + VEIL,
+};

package/template/src/components/surface/Pattern.astro

@@ -0,0 +1,278 @@
+---
+/**
+ * The page's ground.
+ *
+ * One decorative layer behind the content, printed in the variant's own tokens.
+ * It is the opposite trade from `HeroField`: no canvas, no JavaScript, nothing
+ * that can lose a context, and it is meant to be *quiet*. The hero is where a
+ * page spends its one loud moment; this is the paper the rest of it is printed
+ * on, and a ground somebody notices is a ground turned up too far.
+ *
+ *   <Pattern pattern="rules" scope="page" />
+ *   <Pattern pattern="construction" opacity={0.05} draw />
+ *   <Pattern pattern="motif"><path d="…" /></Pattern>
+ *
+ * Six grounds ship and they are not six skins of one look — pick from the
+ * design, not by taste. What each one is for is in the table in
+ * `docs/surface.md` of @jtakeit/astro; the figures themselves are in
+ * ./patterns.ts. The seventh choice is **none**, and it is a real one: on a
+ * page carrying strong photographs it is usually the right answer. It is made
+ * by not rendering this component — `jtk/design.json` leaves
+ * `surface.pattern` empty and nothing appears.
+ *
+ * ── it fails to nothing ─────────────────────────────────────────────────────
+ *
+ * No JavaScript, no mask support, a printer, reduced motion: every one of them
+ * ends at the plain token ground, which is a design somebody chose rather than
+ * a hole in the page. Nothing readable is ever inside this layer, nothing is
+ * ever positioned against it, and it is never the LCP element.
+ */
+import { STENCILS, DRAWINGS, DEFAULTS, isStencil, nextMotifId, type Pattern } from './patterns';
+
+interface Props {
+  /**
+   * grain · rules · hatch · contour · construction · motif.
+   * Required: there is no sensible default ground, and a default is exactly how
+   * fifty sites end up sharing one. Choosing *none* means not rendering this.
+   */
+  pattern: Pattern;
+  /**
+   * `page` pins one layer behind the whole document; `block` fills the section
+   * it sits in — that section needs `class="has-pattern"`, which is the two
+   * properties the layer has to sit under content rather than over it.
+   *
+   * A page-scope ground is only visible through sections that let it through.
+   * On a stack of full-bleed bands with their own backgrounds, half of them
+   * cover it — use `block` there, on the sections that should carry it.
+   */
+  scope?: 'page' | 'block';
+  /** The figure's pitch: line spacing, hatch gap, motif tile. Any CSS length. */
+  size?: string;
+  /** Stroke weight. Any CSS length. */
+  weight?: string;
+  /**
+   * The volume knob, and the property most likely to be set too high. A ground
+   * that competes with body text makes the page harder to read for everyone who
+   * did not choose it, so `fl-check` measures this one rather than leaving it
+   * to taste.
+   */
+  opacity?: number;
+  /** What the ground is printed in. A token, not a colour. */
+  ink?: string;
+  /**
+   * Let a drawn ground set itself out once, in order, and then stop. Ignored by
+   * the stencils — a texture has no beginning. Reduced motion gets the finished
+   * drawing, never a missing one.
+   */
+  draw?: boolean;
+  class?: string;
+}
+
+const {
+  pattern,
+  scope = 'block',
+  size,
+  weight,
+  opacity,
+  ink,
+  draw = false,
+  class: className,
+} = Astro.props;
+
+/*
+ * `motif` is the ground that carries the client's own mark — their tile, their
+ * fabric, their stamp, the shape off their sign — and it is the one entry in
+ * the catalogue that cannot be filled in from a catalogue. Empty, it would
+ * render an invisible layer that looks like it works, so it fails the build
+ * instead, the way `HeroField` fails without a palette.
+ */
+if (pattern === 'motif' && !Astro.slots.has('default')) {
+  throw new Error(
+    '<Pattern pattern="motif"> needs the mark itself as its content — one SVG figure ' +
+      "taken from this business's own material. See references/surface.md; the other " +
+      'five grounds are chosen from the catalogue, this one is not.',
+  );
+}
+
+const base = DEFAULTS[pattern];
+const stencil = isStencil(pattern) ? STENCILS[pattern] : null;
+const drawing = pattern === 'motif' ? null : DRAWINGS[pattern as keyof typeof DRAWINGS];
+
+/*
+ * The geometry lives on the layer rather than on :root, because the same token
+ * name means a 180px noise tile to one ground and a 14px hatch gap to another —
+ * one shared value would put at least one of them in the wrong place. A variant
+ * retunes a ground per breakpoint by targeting `.pattern`, which is also where
+ * it can drop the pitch on a phone.
+ */
+const vars = [
+  `--pattern-size:${size ?? base.size}`,
+  `--pattern-weight:${weight ?? base.weight}`,
+  `--pattern-opacity:${opacity ?? base.opacity}`,
+  ink ? `--pattern-ink:${ink}` : '',
+  stencil ? `--pattern-stencil:${stencil}` : '',
+]
+  .filter(Boolean)
+  .join(';');
+
+/* Its own tile, in user units: an SVG <pattern> takes a number, not a token. */
+const tile = pattern === 'motif' ? Math.max(1, parseFloat(size ?? base.size) || 96) : 0;
+const motifId = pattern === 'motif' ? nextMotifId() : '';
+---
+
+<div
+  class:list={['pattern', `pattern--${scope}`, className]}
+  data-pattern={pattern}
+  data-draw={draw && !stencil ? '' : undefined}
+  style={vars}
+  aria-hidden="true"
+>
+  {
+    stencil ? (
+      <div class="pattern__stencil" />
+    ) : pattern === 'motif' ? (
+      <svg class="pattern__drawing" aria-hidden="true" focusable="false">
+        <defs>
+          <pattern id={motifId} width={tile} height={tile} patternUnits="userSpaceOnUse">
+            <slot />
+          </pattern>
+        </defs>
+        <rect width="100%" height="100%" fill={`url(#${motifId})`} />
+      </svg>
+    ) : (
+      <svg
+        class="pattern__drawing"
+        viewBox={drawing?.viewBox}
+        preserveAspectRatio="xMidYMid slice"
+        fill="none"
+        stroke="currentColor"
+        aria-hidden="true"
+        focusable="false"
+        set:html={drawing?.markup}
+      />
+    )
+  }
+</div>
+
+<style>
+  .pattern {
+    pointer-events: none;
+    color: var(--pattern-ink, var(--ink, #000));
+  }
+
+  /*
+   * Behind the document. A fixed layer costs one composited surface and does
+   * not repaint on scroll, which is why the page ground is fixed rather than a
+   * tall repeating image: the same picture for a tenth of the work.
+   */
+  .pattern--page {
+    position: fixed;
+    inset: 0;
+    z-index: -1;
+  }
+
+  /*
+   * Inside its section. `z-index: -1` puts it above that section's background
+   * and below its content — but only where the section is a stacking context,
+   * which is what `.has-pattern` is for. Without it the layer disappears behind
+   * the band's own colour.
+   */
+  .pattern--block {
+    position: absolute;
+    inset: 0;
+    z-index: -1;
+    overflow: hidden;
+  }
+
+  .pattern__stencil,
+  .pattern__drawing {
+    position: absolute;
+    inset: 0;
+    inline-size: 100%;
+    block-size: 100%;
+    opacity: var(--pattern-opacity, 0.06);
+  }
+
+  /*
+   * The ink, stencilled. Painting a token through a mask rather than shipping a
+   * coloured image is what keeps the ground in the variant's palette — and it
+   * follows the studio bar's live accent for the same reason `HeroField` does.
+   *
+   * Where masks are unsupported the layer would be a solid block of ink over
+   * the page, so it is not drawn at all: no ground is a design, a rectangle of
+   * ink is a bug.
+   */
+  .pattern__stencil {
+    display: none;
+  }
+
+  @supports (mask-image: linear-gradient(#000, #000)) or
+    (-webkit-mask-image: linear-gradient(#000, #000)) {
+    .pattern__stencil {
+      display: block;
+      background-color: currentColor;
+      -webkit-mask-image: var(--pattern-stencil);
+      mask-image: var(--pattern-stencil);
+      -webkit-mask-repeat: repeat;
+      mask-repeat: repeat;
+    }
+  }
+
+  /*
+   * Only a tile has a size. The ruled and hatched grounds are gradients, which
+   * measure their pitch themselves out of --pattern-size and repeat inside one
+   * mask box; sizing that box would squash the figure instead of tiling it.
+   */
+  .pattern[data-pattern='grain'] .pattern__stencil {
+    -webkit-mask-size: var(--pattern-size) var(--pattern-size);
+    mask-size: var(--pattern-size) var(--pattern-size);
+  }
+
+  .pattern__drawing {
+    stroke-width: var(--pattern-weight, 1px);
+  }
+
+  /* The figures arrive as markup from patterns.ts, so the scoped selector does
+     not reach them. */
+  .pattern__drawing :global(*) {
+    vector-effect: non-scaling-stroke;
+  }
+
+  /*
+   * Setting out, once. The still state is the default, so a visitor with no
+   * JavaScript sees the finished drawing — `html.js` is set before first paint
+   * in the layout, and only then is anything hidden.
+   *
+   * `pathLength="1"` on every figure is what makes this one rule work for a
+   * circle, a line and a 56-point contour alike: the browser measures the path,
+   * nobody types a length into the markup, and a figure edited later still
+   * draws correctly.
+   */
+  html.js .pattern[data-draw] .pattern__drawing :global(*) {
+    stroke-dasharray: 1;
+    stroke-dashoffset: 1;
+    animation: pattern-draw 1.4s var(--ease, ease) forwards;
+    animation-delay: calc(var(--i, 0) * 180ms);
+  }
+
+  @keyframes pattern-draw {
+    to {
+      stroke-dashoffset: 0;
+    }
+  }
+
+  /* Reduced motion means the finished picture, not a missing one. */
+  @media (prefers-reduced-motion: reduce) {
+    html.js .pattern[data-draw] .pattern__drawing :global(*) {
+      stroke-dashoffset: 0;
+      animation: none;
+    }
+  }
+
+  /* Ink is expensive and a texture is not the content. */
+  @media print {
+    .pattern {
+      display: none;
+    }
+  }
+</style>