@colixsystems/widget-sdk 0.291.0 → 0.293.0

package/README.md

@@ -90,7 +90,15 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.291.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.293.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.293.0 (contract 1.240.0)
+
+**Status colours follow the app's look.** `theme.colors.success`, `danger`, `warning` and `info` used to be the same four colours in every app, so a warm editorial palette showed a saturated green "Completed" chip and a bright blue "Booked" one. Each tone now keeps its hue family (green, red, amber, blue) but takes the app's accent saturation and lightness, stepped until it reads as text on the surface — and a dark palette derives its own lighter set. `<Badge>`, `<Banner>`, `<Progress>`, `<Stat>` deltas and toasts pick this up with no change on your side, and a badge's soft fill and label stay WCAG AA. A colour the workspace sets in the Alerts section of Design still wins. The derivation is `deriveStatusColors(primary, surface, onSurface)`, a host-side helper like `deriveAccentTints`; the four default literals are that derivation on the default palette, so an untouched theme renders as before.
+
+### What's new in 0.292.0 (contract 1.239.0)
+
+**An Action a widget runs must be done 250 ms after the press.** The time counts from when the press reaches the server, so waiting for a free sandbox and setting the run up spend from it too. A run started by `useAction()` (or a Button's Run action) that is still going then is stopped, and `run()` rejects with `ACTION_TIMEOUT` (504). Its outcome is unknown: open requests and connector calls are cut and no new work starts, but a write that had already finished stays, and a notification already sent can't be recalled. So an Action the app waits on must do its writes as one call (a bulk write) or be safe to repeat, and never tell the user it did nothing. Move slow or multi-step work to an Action triggered by a record the widget writes. Scheduled, record-triggered and Run now runs keep their own limits.
 
 ### What's new in 0.291.0 (contract 1.238.0)
 
@@ -299,7 +307,7 @@ const { available, run, running, result, error } = useAction(props.actionId);
 
 **Bind it with an `actionRef` property.** Declare `{ type: "actionRef" }` in your `propertySchema` and the Studio renders an Action picker that warns when the chosen Action lacks the app trigger. The value is a bare Action id, so Copy Workspace remaps it like `pageRef`.
 
-When nothing is bound, or the host brokers no actions client, `available` is `false` and `run()` rejects `UNAVAILABLE`: render a visible "pick an action" state, never a blank box. A changed binding clears `result` and `error`, and a run that settles after the binding changed or the widget unmounted writes nothing. When runs overlap, `result` and `error` follow the newest one. Branch on `error.code`: `ACTION_NOT_APP_INVOKABLE` and `ACTION_NOT_FOUND` will not clear on a retry, `RATE_LIMITED` will, `INVALID_ACTION_INPUT` means the input was refused, `AUTH_REQUIRED`, `TOKEN_EXPIRED` and `TOKEN_INVALID` mean the app user must sign in, and `ACTION_FAILED` means the Action ran and failed. Never show an app user the raw message. A text answer from a bot is often markdown, so render it with `<RichText>`.
+When nothing is bound, or the host brokers no actions client, `available` is `false` and `run()` rejects `UNAVAILABLE`: render a visible "pick an action" state, never a blank box. A changed binding clears `result` and `error`, and a run that settles after the binding changed or the widget unmounted writes nothing. When runs overlap, `result` and `error` follow the newest one. Branch on `error.code`: `ACTION_NOT_APP_INVOKABLE` and `ACTION_NOT_FOUND` will not clear on a retry, `RATE_LIMITED` will, `INVALID_ACTION_INPUT` means the input was refused, `AUTH_REQUIRED`, `TOKEN_EXPIRED` and `TOKEN_INVALID` mean the app user must sign in, `ACTION_FAILED` means the Action ran and failed, and `ACTION_TIMEOUT` means it was still running 250 ms after the press and was stopped, so its outcome is unknown: some of its writes may have happened. Never show an app user the raw message. A text answer from a bot is often markdown, so render it with `<RichText>`.
 
 The linter rejects `useAction()` unless your manifest declares `actions.run:*` in `requestedScopes`.
 

package/dist/contract.cjs

@@ -87,10 +87,13 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     // background — so a dark theme gets a visible spinner with no new maths.
     loader: "#475569",
     border: "#e2e8f0",
-    danger: "#dc2626",
-    success: "#059669",
-    warning: "#d97706",
-    info: "#0284c7",
+    // The four status tones are re-derived per tenant by `deriveStatusColors`
+    // (their hue families on the accent's saturation and lightness); these
+    // literals are that derivation applied to the default palette.
+    danger: "#e90b0b",
+    success: "#067e56",
+    warning: "#9b6507",
+    info: "#0877af",
   }),
   elevation: ELEVATION,
   interaction: INTERACTION,
@@ -2285,6 +2288,12 @@ const HOOKS = [
       "INVALID_ACTION_INPUT (400) — the input was refused; " +
       "ACTION_NOT_APP_INVOKABLE (403) and ACTION_NOT_FOUND (404) will NOT " +
       "clear on a retry, so hide the affordance; RATE_LIMITED (429) will; " +
+      "ACTION_TIMEOUT (504) — the run was still going 250 ms after the press " +
+      "and was stopped, so its OUTCOME IS UNKNOWN: some of its writes may " +
+      "have happened. Never retry it blindly and never tell the user it did " +
+      "nothing; an Action a widget runs must do its writes as one call or be " +
+      "safe to repeat, and slow or multi-step work belongs in a " +
+      "record-triggered Action; " +
       "ACTION_FAILED — the Action ran and failed, or no answer arrived. NEVER " +
       "show an app user a raw error. A text answer from a bot is often " +
       "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
@@ -6802,10 +6811,17 @@ const CONTRACT = deepFreeze({
   //    PaymentError codes.
   // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
   //    (was 200).
+  // 1.239.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
   // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
   //    `connectors` host client + the `connectorRef` propertySchema type + the
   //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
-  version: "1.238.0",
+  // 1.240.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
+  // 1.239.0: additive (sc-15658) — an app-triggered run must finish within 250 ms
+  //    of the press; `useAction` errors carry the new code ACTION_TIMEOUT
+  //    (504), whose outcome is unknown.
+  version: "1.240.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -7042,6 +7058,70 @@ function deriveAccentTints(primary, surface, onSurface) {
   };
 }
 
+// The hue family each status tone keeps whatever the palette.
+const STATUS_HUES = Object.freeze({ success: 160, danger: 0, warning: 38, info: 200 });
+// Below this saturation a tone loses its hue, so a grey accent still reads as a colour.
+const STATUS_MIN_SATURATION = 0.35;
+// The lightness band a tone starts in, so a near-black or pastel accent keeps a visible hue.
+const STATUS_LIGHTNESS = Object.freeze({ min: 0.28, max: 0.62 });
+const STATUS_LIGHTNESS_STEP = 0.02;
+
+/** `[hue 0-360, saturation 0-1, lightness 0-1]` of a hex colour. */
+function hexToHsl(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+  else if (max === g) h = (b - r) / d + 2;
+  else h = (r - g) / d + 4;
+  return [h * 60, s, l];
+}
+
+function hslToHex(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1));
+  const hex = (v) => Math.round(v * 255).toString(16).padStart(2, "0");
+  return `#${hex(f(0))}${hex(f(8))}${hex(f(4))}`;
+}
+
+/**
+ * Derive the four status colours from a resolved palette. Each tone keeps its
+ * hue family (green, red, amber, blue) and takes the accent's saturation and
+ * lightness, then is stepped toward `onSurface` until it clears WCAG AA against
+ * the surface, so a status mark reads as text on every look, light or dark.
+ * Returns `{ success, danger, warning, info }`, or `null` when the inputs
+ * aren't usable hex, letting the caller keep the default tokens.
+ */
+function deriveStatusColors(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const [, accentS, accentL] = hexToHsl(primary);
+  const targetL = hexToHsl(onSurface)[2];
+  const s = Math.max(accentS, STATUS_MIN_SATURATION);
+  const out = {};
+  for (const [tone, hue] of Object.entries(STATUS_HUES)) {
+    let l = Math.min(STATUS_LIGHTNESS.max, Math.max(STATUS_LIGHTNESS.min, accentL));
+    let color = hslToHex(hue, s, l);
+    const step = targetL < l ? -STATUS_LIGHTNESS_STEP : STATUS_LIGHTNESS_STEP;
+    while (
+      contrastRatio(color, surface) < ACCENT_TEXT_MIN_CONTRAST &&
+      Math.abs(targetL - l) > STATUS_LIGHTNESS_STEP
+    ) {
+      l += step;
+      color = hslToHex(hue, s, l);
+    }
+    out[tone] = color;
+  }
+  return out;
+}
+
 // REQ-THEME-SURFACE: how far a derived surface travels toward white, and the
 // light-on-dark text pair a dark surface carries.
 const SURFACE_LIFT = Object.freeze({ surface: 0.1, surfaceMuted: 0.05, border: 0.18 });
@@ -7239,6 +7319,7 @@ module.exports = {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   deriveSurfaceTokens,
   inkForBackdrop,
   INK_CONTRAST,

package/dist/contract.js

@@ -83,10 +83,13 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     // background — so a dark theme gets a visible spinner with no new maths.
     loader: "#475569",
     border: "#e2e8f0",
-    danger: "#dc2626",
-    success: "#059669",
-    warning: "#d97706",
-    info: "#0284c7",
+    // The four status tones are re-derived per tenant by `deriveStatusColors`
+    // (their hue families on the accent's saturation and lightness); these
+    // literals are that derivation applied to the default palette.
+    danger: "#e90b0b",
+    success: "#067e56",
+    warning: "#9b6507",
+    info: "#0877af",
   }),
   elevation: ELEVATION,
   interaction: INTERACTION,
@@ -2281,6 +2284,12 @@ const HOOKS = [
       "INVALID_ACTION_INPUT (400) — the input was refused; " +
       "ACTION_NOT_APP_INVOKABLE (403) and ACTION_NOT_FOUND (404) will NOT " +
       "clear on a retry, so hide the affordance; RATE_LIMITED (429) will; " +
+      "ACTION_TIMEOUT (504) — the run was still going 250 ms after the press " +
+      "and was stopped, so its OUTCOME IS UNKNOWN: some of its writes may " +
+      "have happened. Never retry it blindly and never tell the user it did " +
+      "nothing; an Action a widget runs must do its writes as one call or be " +
+      "safe to repeat, and slow or multi-step work belongs in a " +
+      "record-triggered Action; " +
       "ACTION_FAILED — the Action ran and failed, or no answer arrived. NEVER " +
       "show an app user a raw error. A text answer from a bot is often " +
       "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
@@ -6798,10 +6807,17 @@ const CONTRACT = deepFreeze({
   //    PaymentError codes.
   // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
   //    (was 200).
+  // 1.239.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
   // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
   //    `connectors` host client + the `connectorRef` propertySchema type + the
   //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
-  version: "1.238.0",
+  // 1.240.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
+  // 1.239.0: additive (sc-15658) — an app-triggered run must finish within 250 ms
+  //    of the press; `useAction` errors carry the new code ACTION_TIMEOUT
+  //    (504), whose outcome is unknown.
+  version: "1.240.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -7038,6 +7054,70 @@ function deriveAccentTints(primary, surface, onSurface) {
   };
 }
 
+// The hue family each status tone keeps whatever the palette.
+const STATUS_HUES = Object.freeze({ success: 160, danger: 0, warning: 38, info: 200 });
+// Below this saturation a tone loses its hue, so a grey accent still reads as a colour.
+const STATUS_MIN_SATURATION = 0.35;
+// The lightness band a tone starts in, so a near-black or pastel accent keeps a visible hue.
+const STATUS_LIGHTNESS = Object.freeze({ min: 0.28, max: 0.62 });
+const STATUS_LIGHTNESS_STEP = 0.02;
+
+/** `[hue 0-360, saturation 0-1, lightness 0-1]` of a hex colour. */
+function hexToHsl(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+  else if (max === g) h = (b - r) / d + 2;
+  else h = (r - g) / d + 4;
+  return [h * 60, s, l];
+}
+
+function hslToHex(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1));
+  const hex = (v) => Math.round(v * 255).toString(16).padStart(2, "0");
+  return `#${hex(f(0))}${hex(f(8))}${hex(f(4))}`;
+}
+
+/**
+ * Derive the four status colours from a resolved palette. Each tone keeps its
+ * hue family (green, red, amber, blue) and takes the accent's saturation and
+ * lightness, then is stepped toward `onSurface` until it clears WCAG AA against
+ * the surface, so a status mark reads as text on every look, light or dark.
+ * Returns `{ success, danger, warning, info }`, or `null` when the inputs
+ * aren't usable hex, letting the caller keep the default tokens.
+ */
+function deriveStatusColors(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const [, accentS, accentL] = hexToHsl(primary);
+  const targetL = hexToHsl(onSurface)[2];
+  const s = Math.max(accentS, STATUS_MIN_SATURATION);
+  const out = {};
+  for (const [tone, hue] of Object.entries(STATUS_HUES)) {
+    let l = Math.min(STATUS_LIGHTNESS.max, Math.max(STATUS_LIGHTNESS.min, accentL));
+    let color = hslToHex(hue, s, l);
+    const step = targetL < l ? -STATUS_LIGHTNESS_STEP : STATUS_LIGHTNESS_STEP;
+    while (
+      contrastRatio(color, surface) < ACCENT_TEXT_MIN_CONTRAST &&
+      Math.abs(targetL - l) > STATUS_LIGHTNESS_STEP
+    ) {
+      l += step;
+      color = hslToHex(hue, s, l);
+    }
+    out[tone] = color;
+  }
+  return out;
+}
+
 // REQ-THEME-SURFACE: how far a derived surface travels toward white, and the
 // light-on-dark text pair a dark surface carries.
 const SURFACE_LIFT = Object.freeze({ surface: 0.1, surfaceMuted: 0.05, border: 0.18 });
@@ -7235,6 +7315,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   deriveSurfaceTokens,
   inkForBackdrop,
   INK_CONTRAST,

package/dist/index.d.ts

@@ -3513,6 +3513,7 @@ export class ActionError extends Error {
     | "AUTH_REQUIRED"
     | "TOKEN_EXPIRED"
     | "TOKEN_INVALID"
+    | "ACTION_TIMEOUT"
     | "ACTION_FAILED"
     | (string & {});
   constructor(code: string, message: string, opts?: { cause?: unknown });
@@ -6066,6 +6067,23 @@ export function deriveAccentTints(
   primaryStrong: string;
 } | null;
 
+/**
+ * Derive the four status colours from a resolved palette: each keeps its hue
+ * family and takes the accent's saturation and lightness, stepped toward
+ * `onSurface` until it clears WCAG AA against the surface. `null` when the
+ * inputs aren't hex.
+ */
+export function deriveStatusColors(
+  primary: string,
+  surface: string,
+  onSurface: string,
+): {
+  success: string;
+  danger: string;
+  warning: string;
+  info: string;
+} | null;
+
 /**
  * Map a CSS gradient angle (0 = to top, 90 = to right) to the `{ start, end }`
  * unit vectors expo-linear-gradient expects.

package/dist/index.js

@@ -215,6 +215,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   gradientAngleToVector,
   normaliseComponentGradient,
   componentGradientColors,

package/dist/index.native.js

@@ -208,6 +208,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   gradientAngleToVector,
   normaliseComponentGradient,
   componentGradientColors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.291.0",
+  "version": "0.293.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -83,10 +83,13 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     // background — so a dark theme gets a visible spinner with no new maths.
     loader: "#475569",
     border: "#e2e8f0",
-    danger: "#dc2626",
-    success: "#059669",
-    warning: "#d97706",
-    info: "#0284c7",
+    // The four status tones are re-derived per tenant by `deriveStatusColors`
+    // (their hue families on the accent's saturation and lightness); these
+    // literals are that derivation applied to the default palette.
+    danger: "#e90b0b",
+    success: "#067e56",
+    warning: "#9b6507",
+    info: "#0877af",
   }),
   elevation: ELEVATION,
   interaction: INTERACTION,
@@ -2281,6 +2284,12 @@ const HOOKS = [
       "INVALID_ACTION_INPUT (400) — the input was refused; " +
       "ACTION_NOT_APP_INVOKABLE (403) and ACTION_NOT_FOUND (404) will NOT " +
       "clear on a retry, so hide the affordance; RATE_LIMITED (429) will; " +
+      "ACTION_TIMEOUT (504) — the run was still going 250 ms after the press " +
+      "and was stopped, so its OUTCOME IS UNKNOWN: some of its writes may " +
+      "have happened. Never retry it blindly and never tell the user it did " +
+      "nothing; an Action a widget runs must do its writes as one call or be " +
+      "safe to repeat, and slow or multi-step work belongs in a " +
+      "record-triggered Action; " +
       "ACTION_FAILED — the Action ran and failed, or no answer arrived. NEVER " +
       "show an app user a raw error. A text answer from a bot is often " +
       "MARKDOWN, so render it with <RichText value={result} />, not <Text>. " +
@@ -6798,10 +6807,17 @@ const CONTRACT = deepFreeze({
   //    PaymentError codes.
   // 1.237.0: widening — `manifest.translations` may declare up to 500 keys
   //    (was 200).
+  // 1.239.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
   // 1.238.0: additive (sc-15659) — `useConnector(connectorRef)` + the
   //    `connectors` host client + the `connectorRef` propertySchema type + the
   //    `connectors.call:*` scope. A widget calls a REST connector's listed operations.
-  version: "1.238.0",
+  // 1.240.0: additive — `deriveStatusColors`; the four status tokens follow the
+  //    palette, and their default literals are that derivation on the default.
+  // 1.239.0: additive (sc-15658) — an app-triggered run must finish within 250 ms
+  //    of the press; `useAction` errors carry the new code ACTION_TIMEOUT
+  //    (504), whose outcome is unknown.
+  version: "1.240.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -7038,6 +7054,70 @@ function deriveAccentTints(primary, surface, onSurface) {
   };
 }
 
+// The hue family each status tone keeps whatever the palette.
+const STATUS_HUES = Object.freeze({ success: 160, danger: 0, warning: 38, info: 200 });
+// Below this saturation a tone loses its hue, so a grey accent still reads as a colour.
+const STATUS_MIN_SATURATION = 0.35;
+// The lightness band a tone starts in, so a near-black or pastel accent keeps a visible hue.
+const STATUS_LIGHTNESS = Object.freeze({ min: 0.28, max: 0.62 });
+const STATUS_LIGHTNESS_STEP = 0.02;
+
+/** `[hue 0-360, saturation 0-1, lightness 0-1]` of a hex colour. */
+function hexToHsl(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  if (max === r) h = (g - b) / d + (g < b ? 6 : 0);
+  else if (max === g) h = (b - r) / d + 2;
+  else h = (r - g) / d + 4;
+  return [h * 60, s, l];
+}
+
+function hslToHex(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1));
+  const hex = (v) => Math.round(v * 255).toString(16).padStart(2, "0");
+  return `#${hex(f(0))}${hex(f(8))}${hex(f(4))}`;
+}
+
+/**
+ * Derive the four status colours from a resolved palette. Each tone keeps its
+ * hue family (green, red, amber, blue) and takes the accent's saturation and
+ * lightness, then is stepped toward `onSurface` until it clears WCAG AA against
+ * the surface, so a status mark reads as text on every look, light or dark.
+ * Returns `{ success, danger, warning, info }`, or `null` when the inputs
+ * aren't usable hex, letting the caller keep the default tokens.
+ */
+function deriveStatusColors(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const [, accentS, accentL] = hexToHsl(primary);
+  const targetL = hexToHsl(onSurface)[2];
+  const s = Math.max(accentS, STATUS_MIN_SATURATION);
+  const out = {};
+  for (const [tone, hue] of Object.entries(STATUS_HUES)) {
+    let l = Math.min(STATUS_LIGHTNESS.max, Math.max(STATUS_LIGHTNESS.min, accentL));
+    let color = hslToHex(hue, s, l);
+    const step = targetL < l ? -STATUS_LIGHTNESS_STEP : STATUS_LIGHTNESS_STEP;
+    while (
+      contrastRatio(color, surface) < ACCENT_TEXT_MIN_CONTRAST &&
+      Math.abs(targetL - l) > STATUS_LIGHTNESS_STEP
+    ) {
+      l += step;
+      color = hslToHex(hue, s, l);
+    }
+    out[tone] = color;
+  }
+  return out;
+}
+
 // REQ-THEME-SURFACE: how far a derived surface travels toward white, and the
 // light-on-dark text pair a dark surface carries.
 const SURFACE_LIFT = Object.freeze({ surface: 0.1, surfaceMuted: 0.05, border: 0.18 });
@@ -7235,6 +7315,7 @@ export {
   contrastRatio,
   readableTextColor,
   deriveAccentTints,
+  deriveStatusColors,
   deriveSurfaceTokens,
   inkForBackdrop,
   INK_CONTRAST,