@domandigital/craft 0.18.0 → 0.18.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @domandigital/craft
 
+## 0.18.2
+
+### Patch Changes
+
+- 61387cf: CHARACTER.md: a dated calibration entry, "Direction boards, 2026-10-09: fit before distance", with the rules a direction board follows after the DD boards optimised for distance from the null set instead of fit. Docs only.
+
+## 0.18.1
+
+### Patch Changes
+
+- 72c3463: `gradientContrast` no longer blends across a hard stop. A gradient such as `linear-gradient(90deg, #000 50%, #fff 50%)` is painted as a jump from black to white, but 0.18.0 sampled the greys between them and could fail text that clears every colour the browser actually paints. Stop positions are now read, and a stop placed at or before an earlier position starts a hard edge that is not sampled, as in CSS. A painted blend is still sampled between its stops. Found by Codex review on Doman-Digital/dd-drift-guards#8, where the same fix landed.
+
 ## 0.18.0
 
 ### Minor Changes

package/CHARACTER.md

@@ -912,6 +912,22 @@ What moved: the estate is still atypical of what the model builds for its own br
 
 `craft tells harvest` on the v2 models gives the same three candidates as before (red accent #e77a63, 66 of 140; square shape, 47 of 140; the opening `hero > hero > cards`, 54 of 140) and 40 recurring phrases (the same count as before; the list was not diffed line by line). The only difference is in the already-caught list, which now includes `no-real-imagery` (117 of 140), `hero-eyebrow-chip` (53), `stats-row` (42) and `unproven-claim` (35): tells that came in with snapshot v2 and later phases, which the v1 harvest could not see. Nothing was added to the catalogue, and no tell or threshold changed.
 
+### Direction boards, 2026-10-09: fit before distance
+
+The first visual-direction boards for Doman Digital's own site were built in the hour after `craft null build` finished, with the harvest in front of the session. Every one of the seven choices on all three boards was argued from what the null set did (17 of 20 Fraunces, 20 of 20 cream, 20 of 20 terracotta) and what the estate already had. The reasons were real and each cited a source, and the boards were still wrong in the way that matters: placeholder boxes where the client's interface should have been, a ledger explained in a block beside the proof instead of on it, a legend whose line types only read after their labels, and three headlines where one constant line was needed. A reviewer reading this document caught it in one pass: craft asks for fit with a reason and says never to reward strangeness, and the boards had optimised for distance.
+
+What the tool did and did not do. `null build`, `tells harvest` and the estate register gave the session a precise picture of the default and nothing that said "show the work". `direction validate` would have passed a file whose seven choices cite only `reference`, `estate` and the null, and whose sources hold no `product` or `photo` at all. Those are the two gaps, tracked as a warning pair in Linear (DOM, 9 October).
+
+Rules for a direction board, recorded so the next one starts here:
+
+- **The null is a floor, never the argument.** A choice clears the null set and the estate; its reason comes from the client's world. A reason of the form "the null never picks this" is not a reason.
+- **One line of copy, one image, every board.** The headline, subline, routes and the work shown are identical across directions, so the look is the only variable. The headline is checked against every null page before it goes on a board.
+- **The work is on the board, large, and real.** A placeholder where the interface should be is a board about a site that does not exist. Use the client's own published interface with its period, and put the responsibility labels on the work: this is run, this is built and connected, this is yours. The ledger explained beside the proof is the weaker form of the ledger shown on it.
+- **A legend is learned where it points.** Line types, colours and marks carry meaning only at the moment they point at something; a key read first is a key forgotten.
+- **A generated concept image is a composition study.** It can show a layout worth adopting. It is never evidence, never ships, and its headline is checked like any other: the one produced in this review had the null set's own shape.
+
+The board in question is the DD redesign's Stage 05 artefact (DOM-397, CRO-21); v1.1 applied all five.
+
 ## The catalogue
 
 Generated from the package. Run `pnpm --filter @domandigital/craft run docs`

package/README.md

@@ -213,7 +213,8 @@ restraint rule) and art direction (`craft direction`, `craft estate`).
   against the worst point. The worst point is sampled along every segment, not
   only at the stops: mid-grey text on a black-to-white gradient clears 4.5:1
   against both ends and is about 1:1 in the middle, which the drift-guards
-  version passed. WCAG defines no method for gradients, so this is craft's
+  version passed. A hard stop (`#000 50%, #fff 50%`) is a jump the browser
+  paints without a blend, so it is not sampled across. WCAG defines no method for gradients, so this is craft's
   rule, not a conformance claim.
 - **`checkPhotoReview(text, { minScore, required })`**: gates a build on the
   report `halide review --json` wrote. It takes the report's text (null when

package/dist/index.cjs

@@ -726,6 +726,9 @@ function composite(top, under) {
   };
 }
 function gradientStops(gradient) {
+  return parseStops(gradient).map((s) => s.colour);
+}
+function parseStops(gradient) {
   const inner = /gradient\(([\s\S]*)\)\s*$/.exec(gradient.trim());
   if (!inner) throw new Error(`not a CSS gradient: ${gradient}`);
   const parts2 = [];
@@ -744,27 +747,57 @@ function gradientStops(gradient) {
   if (current.trim()) parts2.push(current.trim());
   const stops = [];
   for (const part of parts2) {
-    const colour = part.replace(/(\s+-?[\d.]+(%|px|r?em|deg|turn|vw|vh))+\s*$/i, "").trim();
-    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(colour)) continue;
+    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(part)) continue;
+    const positions = [];
+    let colour = part;
+    for (let i = 0; i < 2; i++) {
+      const m = /\s+(-?[\d.]+)(%|px|r?em|vw|vh|deg|turn|rad|grad)\s*$/i.exec(colour);
+      if (!m) break;
+      positions.unshift({ value: parseFloat(m[1]), unit: m[2].toLowerCase() });
+      colour = colour.slice(0, m.index);
+    }
+    colour = colour.trim();
     if (!toRgba(colour)) throw new Error(`unreadable gradient stop "${colour}" in ${gradient}`);
-    stops.push(colour);
+    stops.push({ colour, positions });
   }
   if (stops.length === 0) throw new Error(`no colour stops in ${gradient}`);
   return stops;
 }
+function blendedSegments(stops) {
+  const entries = [];
+  for (const s of stops) {
+    const rgba = toRgba(s.colour);
+    if (s.positions.length === 0) entries.push({ rgba, pos: null });
+    for (const pos of s.positions) entries.push({ rgba, pos });
+  }
+  const furthest = {};
+  const pairs = [];
+  for (let i = 0; i + 1 < entries.length; i++) {
+    const pos = entries[i].pos;
+    if (pos) furthest[pos.unit] = Math.max(furthest[pos.unit] ?? -Infinity, pos.value);
+    const next = entries[i + 1].pos;
+    const hard = next !== null && furthest[next.unit] !== void 0 && next.value <= furthest[next.unit];
+    if (!hard) pairs.push([entries[i].rgba, entries[i + 1].rgba]);
+  }
+  return pairs;
+}
 function gradientContrast(text, gradient, beneath = "#ffffff") {
   const under = toRgba(beneath);
   if (!under || under.a < 1) throw new Error(`beneath must be an opaque colour, got ${beneath}`);
   const fg = toRgba(text);
   if (!fg || fg.a < 1) throw new Error(`text must be an opaque colour, got ${text}`);
   const textHex = formatHex(fg);
-  const raw = gradientStops(gradient).map((s) => toRgba(s));
-  const stops = raw.map((s) => formatHex(composite(s, under)));
+  const parsed = parseStops(gradient);
+  const stops = parsed.map((s) => formatHex(composite(toRgba(s.colour), under)));
   let worst = stops[0];
   let worstRatio = wcagContrast(textHex, worst);
-  for (let i = 0; i + 1 < raw.length; i++) {
-    for (let k = 1; k <= SAMPLES_PER_SEGMENT; k++) {
-      const point = formatHex(composite(mix(raw[i], raw[i + 1], k / SAMPLES_PER_SEGMENT), under));
+  for (const s of stops) {
+    const ratio = wcagContrast(textHex, s);
+    if (ratio < worstRatio) [worst, worstRatio] = [s, ratio];
+  }
+  for (const [a, b] of blendedSegments(parsed)) {
+    for (let k = 1; k < SAMPLES_PER_SEGMENT; k++) {
+      const point = formatHex(composite(mix(a, b, k / SAMPLES_PER_SEGMENT), under));
       const ratio = wcagContrast(textHex, point);
       if (ratio < worstRatio) [worst, worstRatio] = [point, ratio];
     }

package/dist/index.d.cts

@@ -178,7 +178,8 @@ declare function checkPair(text: string, background: string): ContrastCheck;
  * the backdrop's luminance comes closest to the text's: mid-grey text on a
  * black-to-white gradient clears 4.5:1 against both ends and about 1:1 in the
  * middle. So each segment is sampled, interpolated as browsers paint legacy
- * colours (sRGB, premultiplied alpha). Pure.
+ * colours (sRGB, premultiplied alpha), except across a hard stop
+ * (`#000 50%, #fff 50%`), where the browser paints a jump and no blend. Pure.
  */
 /** Samples per segment between two stops: under 1/255 of a channel apart for any pair. */
 declare const SAMPLES_PER_SEGMENT = 256;

package/dist/index.d.ts

@@ -178,7 +178,8 @@ declare function checkPair(text: string, background: string): ContrastCheck;
  * the backdrop's luminance comes closest to the text's: mid-grey text on a
  * black-to-white gradient clears 4.5:1 against both ends and about 1:1 in the
  * middle. So each segment is sampled, interpolated as browsers paint legacy
- * colours (sRGB, premultiplied alpha). Pure.
+ * colours (sRGB, premultiplied alpha), except across a hard stop
+ * (`#000 50%, #fff 50%`), where the browser paints a jump and no blend. Pure.
  */
 /** Samples per segment between two stops: under 1/255 of a channel apart for any pair. */
 declare const SAMPLES_PER_SEGMENT = 256;

package/dist/index.js

@@ -436,6 +436,9 @@ function composite(top, under) {
   };
 }
 function gradientStops(gradient) {
+  return parseStops(gradient).map((s) => s.colour);
+}
+function parseStops(gradient) {
   const inner = /gradient\(([\s\S]*)\)\s*$/.exec(gradient.trim());
   if (!inner) throw new Error(`not a CSS gradient: ${gradient}`);
   const parts2 = [];
@@ -454,27 +457,57 @@ function gradientStops(gradient) {
   if (current.trim()) parts2.push(current.trim());
   const stops = [];
   for (const part of parts2) {
-    const colour = part.replace(/(\s+-?[\d.]+(%|px|r?em|deg|turn|vw|vh))+\s*$/i, "").trim();
-    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(colour)) continue;
+    if (/^(to\s|circle|ellipse|closest|farthest|at\s|from\s|in\s|-?[\d.]+(deg|turn|rad|grad)$)/i.test(part)) continue;
+    const positions = [];
+    let colour = part;
+    for (let i = 0; i < 2; i++) {
+      const m = /\s+(-?[\d.]+)(%|px|r?em|vw|vh|deg|turn|rad|grad)\s*$/i.exec(colour);
+      if (!m) break;
+      positions.unshift({ value: parseFloat(m[1]), unit: m[2].toLowerCase() });
+      colour = colour.slice(0, m.index);
+    }
+    colour = colour.trim();
     if (!toRgba(colour)) throw new Error(`unreadable gradient stop "${colour}" in ${gradient}`);
-    stops.push(colour);
+    stops.push({ colour, positions });
   }
   if (stops.length === 0) throw new Error(`no colour stops in ${gradient}`);
   return stops;
 }
+function blendedSegments(stops) {
+  const entries = [];
+  for (const s of stops) {
+    const rgba = toRgba(s.colour);
+    if (s.positions.length === 0) entries.push({ rgba, pos: null });
+    for (const pos of s.positions) entries.push({ rgba, pos });
+  }
+  const furthest = {};
+  const pairs = [];
+  for (let i = 0; i + 1 < entries.length; i++) {
+    const pos = entries[i].pos;
+    if (pos) furthest[pos.unit] = Math.max(furthest[pos.unit] ?? -Infinity, pos.value);
+    const next = entries[i + 1].pos;
+    const hard = next !== null && furthest[next.unit] !== void 0 && next.value <= furthest[next.unit];
+    if (!hard) pairs.push([entries[i].rgba, entries[i + 1].rgba]);
+  }
+  return pairs;
+}
 function gradientContrast(text, gradient, beneath = "#ffffff") {
   const under = toRgba(beneath);
   if (!under || under.a < 1) throw new Error(`beneath must be an opaque colour, got ${beneath}`);
   const fg = toRgba(text);
   if (!fg || fg.a < 1) throw new Error(`text must be an opaque colour, got ${text}`);
   const textHex = formatHex(fg);
-  const raw = gradientStops(gradient).map((s) => toRgba(s));
-  const stops = raw.map((s) => formatHex(composite(s, under)));
+  const parsed = parseStops(gradient);
+  const stops = parsed.map((s) => formatHex(composite(toRgba(s.colour), under)));
   let worst = stops[0];
   let worstRatio = wcagContrast(textHex, worst);
-  for (let i = 0; i + 1 < raw.length; i++) {
-    for (let k = 1; k <= SAMPLES_PER_SEGMENT; k++) {
-      const point = formatHex(composite(mix(raw[i], raw[i + 1], k / SAMPLES_PER_SEGMENT), under));
+  for (const s of stops) {
+    const ratio = wcagContrast(textHex, s);
+    if (ratio < worstRatio) [worst, worstRatio] = [s, ratio];
+  }
+  for (const [a, b] of blendedSegments(parsed)) {
+    for (let k = 1; k < SAMPLES_PER_SEGMENT; k++) {
+      const point = formatHex(composite(mix(a, b, k / SAMPLES_PER_SEGMENT), under));
       const ratio = wcagContrast(textHex, point);
       if (ratio < worstRatio) [worst, worstRatio] = [point, ratio];
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/craft",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "private": false,
   "description": "The Doman Digital house craft standard as numbers: OKLCh colour ramps that snap to existing anchors, derived semantic tokens with measured WCAG and APCA contrast, one shared motion vocabulary for CSS and JS, and a base stylesheet. Zero dependencies.",
   "license": "Apache-2.0",
@@ -56,9 +56,10 @@
     "dist"
   ],
   "devDependencies": {
+    "@types/node": "^20.19.43",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.9"
+    "vitest": "^4.0.0"
   },
   "engines": {
     "node": ">=22.12"