@colixsystems/widget-sdk 0.179.0 → 0.180.0

package/README.md

@@ -57,7 +57,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **FILES** (`ctx.assets`) | `useAsset(id)` | `{ url, file, loading, error, refetch }` | `ctx.assets.get` — no scope |
 | **FILES** | `useAssetsByTag(tag, { type })` (optional: the whole argument, and `type` within it) | `{ assets, loading, error, refetch }` | `ctx.assets.list` (unwraps `{ data, meta }` to `assets`) — no scope. `type` defaults to `"image"`; pass `"all"` / `"audio"` / `"video"` / `"document"` to widen. Falsy `tag` collapses to `assets: []` without a round-trip. |
 | **DIRECTORY** (`ctx.directory`) | `useDirectory(query)` (optional: query) | `{ users, loading, error, refetch }` | `directory.users.list` — `directory.read:users` |
-| **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
+| **DIRECTORY** | `useUsers(query)` (optional: query) | `{ users, loading, error, refetch, invite, deactivate, reactivate, remove, sendPasswordReset }` | `directory.users.*` — `users.read:*` plus the `users.read` (or `users.write`) capability, else `FORBIDDEN` (edits, incl. `sendPasswordReset()`, also `users.write:*`; `remove()` also `users.delete:*`) |
 | **DIRECTORY** | `useGroups(query)` (optional: query) | `{ groups, loading, error, refetch, create, remove, addMember, removeMember }` | `directory.groups.*` — `groups.read:*` (mutations also `groups.write:*`) |
 | **DIRECTORY** | `useInvites(query)` (optional: query) | `{ invites, loading, error, refetch, resend, revoke }` | `directory.invites.*` — `users.write:*` + the SystemAcl `users.write` capability (the whole invite surface, list included). `query` is `{ status?, limit?, offset? }` with `status` ∈ `pending \| accepted \| revoked \| expired \| all` (endpoint default `all`). |
 | **DIRECTORY** | `useBankIdLink()` | `{ linked, available, status, qr, message, startLink, refresh, cancel, unlink, refetchStatus, … }` | `directory.bankid.*` — no scope (JWT-gated self-service) |
@@ -74,7 +74,17 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.179.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.180.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.180.0 (contract 1.141.0)
+
+**`<Button>` stays readable on a coloured section.** A section that paints its own fill (a card or band on the theme's colours, or a gradient wash) already gave its text a colour that reads there. Its buttons kept the page's paint, so an `outlined` button drew its label and border in the primary colour on a band washed in that same colour, and a `secondary` fill disappeared into it. A button there is now measured against the section by the same rule as its text: a colour that already reads is kept, and one the section makes unreadable takes the section's text colour, but only when that reads better. "The section makes it unreadable" is measured against the surface the look was designed for: a colour moves only when the section costs it at least a third of the contrast it had there, so a white or lightly tinted panel changes nothing.
+
+- `outlined`: a label under 4.5:1 and a border under 3:1 against the section are re-inked.
+- `secondary`: a fill under 3:1 against the section becomes the section's outlined button.
+- `primary` and `danger`: a fill under 3:1 turns inverse, with the section's text colour as its fill and its own colour as its label, so it still leads the quieter buttons. Where that label would not reach 4.5:1, or you set the label colour, the fill is kept and gains an edge in the section's text colour instead.
+
+A colour you pass in `fields`, `style` (`backgroundColor`, `borderColor`) or `labelStyle` (`color`), or that the app's button look sets, is never changed. A `<Card>` inside such a section becomes the surface its content reads: it re-derives `surface`, `onSurface`, `border` and the rest from its own fill, as a layout container does, and its buttons are measured against it. Inside a section `useTheme().colors.backdrop` is the fill your widget sits on and `colors.backdropBase` the surface the look was designed for; on the page itself both are absent.
 
 ### What's new in 0.179.0 (contract 1.140.0)
 

package/dist/button-style.js

@@ -2,6 +2,8 @@
 // the built-in widgets (frontend `_shared/buttonStyle.js` re-exports these).
 // Platform-free, so both hosts resolve a button identically.
 
+import { INK_CONTRAST, contrastRatio, inkForBackdrop, isHexColor } from "./contract.js";
+
 export const BUTTON_PADDING_MAX = 64;
 export const BUTTON_BORDER_WIDTH_MAX = 8;
 
@@ -58,3 +60,95 @@ export function selfAlignStyle(style) {
   const alignSelf = SELF_ALIGNMENTS[style && style.align];
   return alignSelf ? { alignSelf } : null;
 }
+
+// How much of its page contrast a section must cost a colour before it moves:
+// a tint or neutral panel never does, a coloured band always does.
+const SECTION_LOSS = 1.5;
+
+/**
+ * A variant's own paint, measured against the painted section it sits on
+ * (`colors.backdrop`) by the rule that section's text follows. A colour moves
+ * only where it is unreadable there AND the section is what broke it, measured
+ * against the surface the look was designed for (`colors.backdropBase`). Only
+ * what the look painted moves; `owned` names what the maker set.
+ *
+ * A transparent button re-inks its label and border separately. A fill the
+ * section swallows is replaced: a quiet `secondary` becomes the section's
+ * outlined button, and an emphatic fill turns inverse (the section's ink as
+ * fill, its own colour as label), so it still outranks the quiet ones. Where
+ * that label would not read, or the maker chose it, the fill gains an edge.
+ *
+ * @param {string} variant
+ * @param {{container: object, ink: string}} paint
+ * @param {object} colors - the surface-aware theme colours.
+ * @param {{fill?: boolean, label?: boolean, border?: boolean}} [owned]
+ * @returns {{container: object, ink: string}} `paint` itself when nothing moves.
+ */
+export function paintOnBackdrop(variant, paint, colors, owned = {}) {
+  const { backdrop, backdropBase, onSurface: ink } = colors || {};
+  if (owned.fill || ![backdrop, backdropBase, ink].every(isHexColor)) return paint;
+  const reink = (colour, minimum) =>
+    isHexColor(colour) && brokenBySection(colour, backdrop, backdropBase, minimum)
+      ? inkForBackdrop(colour, ink, backdrop, minimum)
+      : colour;
+  const { container } = paint;
+  const fill = container.backgroundColor;
+  if (fill === "transparent") return reinkOutline(paint, reink, owned);
+  if (reink(fill, INK_CONTRAST.boundary) === fill) return paint;
+  if (!owned.label && variant === "secondary") {
+    return {
+      container: { backgroundColor: "transparent", borderWidth: 1, borderColor: ink },
+      ink,
+    };
+  }
+  if (!owned.label && contrastRatio(fill, ink) >= INK_CONTRAST.text) {
+    const edge = container.borderColor ? { borderColor: ink } : null;
+    return { container: { ...container, backgroundColor: ink, ...edge }, ink: fill };
+  }
+  if (owned.border) return paint;
+  return { container: { ...container, borderWidth: 1, borderColor: ink }, ink: paint.ink };
+}
+
+function brokenBySection(colour, backdrop, base, minimum) {
+  const here = contrastRatio(colour, backdrop);
+  return here < minimum && here * SECTION_LOSS <= contrastRatio(colour, base);
+}
+
+function reinkOutline(paint, reink, owned) {
+  const { borderColor } = paint.container;
+  const label = owned.label ? paint.ink : reink(paint.ink, INK_CONTRAST.text);
+  const border = owned.border ? borderColor : reink(borderColor, INK_CONTRAST.boundary);
+  if (label === paint.ink && border === borderColor) return paint;
+  return { container: { ...paint.container, borderColor: border }, ink: label };
+}
+
+const SIDE_BORDER_COLORS = [
+  "borderColor",
+  "borderTopColor",
+  "borderRightColor",
+  "borderBottomColor",
+  "borderLeftColor",
+];
+
+/**
+ * Which of a button's fill, label and border its caller set, so
+ * `paintOnBackdrop` never replaces them: the surface `fields`, and colours in
+ * the flattened container `style` and `labelStyle`.
+ */
+export function ownedButtonPaint(variant, fields, style, labelStyle) {
+  const f = fields || {};
+  const s = style || {};
+  const danger = variant === "danger";
+  return {
+    fill: Boolean(
+      f.background || f.gradient || s.backgroundColor || (danger && f.dangerBackground),
+    ),
+    label: Boolean(f.textColor || (labelStyle && labelStyle.color) || (danger && f.dangerTextColor)),
+    border: Boolean(
+      f.borderColor ||
+        f.ringColor ||
+        SIDE_BORDER_COLORS.some((key) => s[key]) ||
+        (danger && f.dangerBorderColor),
+    ),
+  };
+}

package/dist/button-view.js

@@ -8,7 +8,12 @@ import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { lucideGlyph } from "./icon.js";
 import { applyThemeComponentStyle } from "./theme-components.js";
 import { cornerRadiusOverlay, shadowStyle, gradientProps } from "./card-style.js";
-import { buttonSurfaceOverlay, buttonSurfaceTextOverlay } from "./button-style.js";
+import {
+  buttonSurfaceOverlay,
+  buttonSurfaceTextOverlay,
+  ownedButtonPaint,
+  paintOnBackdrop,
+} from "./button-style.js";
 
 export const BUTTON_VARIANTS = Object.freeze(["primary", "secondary", "outlined", "danger"]);
 
@@ -39,8 +44,8 @@ function variantPaint(variant, colors) {
 }
 
 // Precedence, weakest first: variant, danger scope, ring, then the fields.
-function containerLayers(variant, f, colors) {
-  const paint = variantPaint(variant, colors);
+function containerLayers(variant, f, colors, owned) {
+  const paint = paintOnBackdrop(variant, variantPaint(variant, colors), colors, owned);
   let ink = paint.ink;
   const layers = [paint.container];
   if (variant === "danger") {
@@ -115,7 +120,13 @@ export function makeButton(rn) {
       ? fields || {}
       : applyThemeComponentStyle(THEMED_AS, theme, { style: fields }).style || {};
     const resolvedVariant = BUTTON_VARIANTS.includes(variant) ? variant : "primary";
-    const { layers, ink } = containerLayers(resolvedVariant, f, colors);
+    const owned = ownedButtonPaint(
+      resolvedVariant,
+      f,
+      StyleSheet.flatten(style),
+      StyleSheet.flatten(labelStyle),
+    );
+    const { layers, ink } = containerLayers(resolvedVariant, f, colors, owned);
 
     const fontSize =
       typeof f.fontSize === "number" && Number.isFinite(f.fontSize)

package/dist/card-style.js

@@ -5,7 +5,7 @@
 // Every resolver emits ONLY the fields that are set, so a widget's own base
 // style keeps whatever the author left alone.
 
-import { CONTRACT, normaliseComponentGradient } from "./contract.js";
+import { CONTRACT, isHexColor, mixHex, normaliseComponentGradient } from "./contract.js";
 import { normaliseCornerRadius, cornerRadiusStyle } from "./corner-radius.js";
 import { normaliseSpacing, spacingStyle, isZeroSpacing } from "./spacing.js";
 
@@ -118,6 +118,35 @@ export function gradientProps(value) {
     : null;
 }
 
+/**
+ * The colour a card's buttons are measured against: its opaque flat fill, or
+ * a gradient's midpoint, as a layout container's ink basis is read. `null`
+ * (a translucent or unknown fill) keeps the backdrop the card inherited.
+ *
+ * @param {object|Array} styles - the card's container style, as composed.
+ * @param {{colors: string[]}|null} gradient - its `gradientProps`.
+ */
+export function cardBackdrop(styles, gradient) {
+  if (gradient) {
+    const [from, to] = gradient.colors;
+    return isOpaqueHex(from) && isOpaqueHex(to) ? mixHex(from, to, 0.5) : null;
+  }
+  let fill = null;
+  for (const style of [styles].flat(Infinity)) {
+    if (style && typeof style === "object" && style.backgroundColor !== undefined) {
+      fill = style.backgroundColor;
+    }
+  }
+  return isOpaqueHex(fill) ? fill : null;
+}
+
+// The colour maths ignores alpha, so a see-through fill cannot be judged.
+function isOpaqueHex(value) {
+  if (!isHexColor(value)) return false;
+  const hex = value.slice(1);
+  return hex.length !== 8 || hex.slice(6).toLowerCase() === "ff";
+}
+
 /** The card-surface gradient (`cardGradient`). */
 export function cardGradientProps(style) {
   return gradientProps(style && style.cardGradient);

package/dist/card-view.js

@@ -6,7 +6,7 @@
 // swap lives here once rather than in each widget.
 
 import React from "react";
-import { useHostTheme } from "./hooks.js";
+import { useHostTheme, BackdropScope } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 import { CONTRACT } from "./contract.js";
 import {
@@ -14,6 +14,7 @@ import {
   cardSurfaceStyle,
   cardGradientProps,
   cardLayoutStyle,
+  cardBackdrop,
 } from "./card-style.js";
 import { normaliseThemeComponents } from "./theme-components.js";
 
@@ -134,12 +135,17 @@ export function makeCard(rn) {
 
     const overlay = withoutMargin ? cardSurfaceStyle(fields) : cardOverlay(fields);
     const gradient = cardGradientProps(fields);
+    const basis = cardBackdrop(
+      [base, overlay, typeof containerStyle === "function" ? null : containerStyle],
+      gradient,
+    );
+    const scoped = React.createElement(BackdropScope, { basis }, children);
 
     if (!gradient) {
       return React.createElement(
         Container,
         { style: composeStyle([base, overlay, layout], containerStyle), ...rest },
-        children,
+        scoped,
       );
     }
 
@@ -156,7 +162,7 @@ export function makeCard(rn) {
           style: composeStyle([base, paint, layout], containerStyle),
           ...rest,
         },
-        children,
+        scoped,
       );
     }
 
@@ -179,7 +185,7 @@ export function makeCard(rn) {
           ),
           ...rest,
         },
-        children,
+        scoped,
       ),
     );
   }

package/dist/contract.cjs

@@ -2480,7 +2480,7 @@ const PRIMITIVES = [
   {
     name: "Button",
     description:
-      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. Never hand-roll a button from `Pressable` + background + radius.',
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -4764,7 +4764,10 @@ const CONTRACT = deepFreeze({
   //    (boolean, default false): the widget draws live figures about its
   //    records, so the app-builder counts it as the page's figures when it
   //    reuses it. Existing manifests omit it and read false.
-  version: "1.140.0",
+  // 1.141.0: additive (sc-9346) — inside a section that paints its own fill,
+  //    `theme.colors.backdrop` is that fill, and `<Button>` re-inks a variant
+  //    colour that cannot be read against it by the rule its text follows.
+  version: "1.141.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5037,6 +5040,25 @@ function deriveSurfaceTokens(backgroundColor) {
   };
 }
 
+// sc-8370: WCAG 1.4.3 for text, 1.4.11 for a control's boundary.
+const INK_CONTRAST = Object.freeze({ text: 4.5, boundary: 3 });
+
+/**
+ * The measured re-ink rule every painted section applies — to its text tiers
+ * and to its buttons alike. `current` is kept while it reaches `minimum`
+ * against `backdrop`; below that, `candidate` replaces it only when it is
+ * genuinely more readable there. A backdrop with no good answer keeps what it
+ * had rather than committing to a colour that is wrong for half of it.
+ */
+function inkForBackdrop(current, candidate, backdrop, minimum) {
+  if (!isHexColor(current) || !isHexColor(candidate) || !isHexColor(backdrop)) {
+    return current;
+  }
+  const held = contrastRatio(current, backdrop);
+  if (held >= minimum) return current;
+  return contrastRatio(candidate, backdrop) > held ? candidate : current;
+}
+
 /**
  * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
  * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
@@ -5119,6 +5141,8 @@ module.exports = {
   readableTextColor,
   deriveAccentTints,
   deriveSurfaceTokens,
+  inkForBackdrop,
+  INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,

package/dist/contract.js

@@ -2480,7 +2480,7 @@ const PRIMITIVES = [
   {
     name: "Button",
     description:
-      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. Never hand-roll a button from `Pressable` + background + radius.',
+      'Themed button. `<Button title="Save" onPress={save} />` — THE way to draw a button: its fill, label colour, border, corner radius, padding, weight, shadow and gradient come from the app\'s button look (Theme Settings > Buttons, and Destructive / Focus ring for the danger variant and emphasis border), so it matches the built-in Button widget. Props: `title`, `onPress` (omit it for a purely visual button inside something else that is pressable), `variant` ("primary" default | "secondary" | "outlined" | "danger"), `icon` (a lucide name) with `iconPosition` ("leading" | "trailing"), `disabled`, `accessibilityLabel`, `testID`, `style` (extra container style, e.g. `alignSelf`) and `labelStyle`. Pass `fields` — `{ background, textColor, borderColor, borderWidth, paddingX, paddingY, radius, fontWeight, fontSize, shadow, gradient }` — to override one button, e.g. from style fields your widget declares. On a section that paints its own fill (`theme.colors.backdrop` there), a variant colour that the section makes unreadable takes that section\'s text colour, as its text does: an outlined label and border, a secondary whose fill disappears becomes outlined, and a primary or danger fill turns inverse (that text colour as its fill, its own colour as its label). A white or lightly tinted panel changes nothing, and a button inside a `<Card>` is measured against that card. A colour you pass in `fields`, `style` or `labelStyle`, or that the app\'s button look sets, is never changed. Never hand-roll a button from `Pressable` + background + radius.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -4760,7 +4760,10 @@ const CONTRACT = deepFreeze({
   //    (boolean, default false): the widget draws live figures about its
   //    records, so the app-builder counts it as the page's figures when it
   //    reuses it. Existing manifests omit it and read false.
-  version: "1.140.0",
+  // 1.141.0: additive (sc-9346) — inside a section that paints its own fill,
+  //    `theme.colors.backdrop` is that fill, and `<Button>` re-inks a variant
+  //    colour that cannot be read against it by the rule its text follows.
+  version: "1.141.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5033,6 +5036,25 @@ function deriveSurfaceTokens(backgroundColor) {
   };
 }
 
+// sc-8370: WCAG 1.4.3 for text, 1.4.11 for a control's boundary.
+const INK_CONTRAST = Object.freeze({ text: 4.5, boundary: 3 });
+
+/**
+ * The measured re-ink rule every painted section applies — to its text tiers
+ * and to its buttons alike. `current` is kept while it reaches `minimum`
+ * against `backdrop`; below that, `candidate` replaces it only when it is
+ * genuinely more readable there. A backdrop with no good answer keeps what it
+ * had rather than committing to a colour that is wrong for half of it.
+ */
+function inkForBackdrop(current, candidate, backdrop, minimum) {
+  if (!isHexColor(current) || !isHexColor(candidate) || !isHexColor(backdrop)) {
+    return current;
+  }
+  const held = contrastRatio(current, backdrop);
+  if (held >= minimum) return current;
+  return contrastRatio(candidate, backdrop) > held ? candidate : current;
+}
+
 /**
  * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
  * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
@@ -5115,6 +5137,8 @@ export {
   readableTextColor,
   deriveAccentTints,
   deriveSurfaceTokens,
+  inkForBackdrop,
+  INK_CONTRAST,
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,

package/dist/hooks.js

@@ -46,6 +46,7 @@ import {
   // sc-5717 — "is this key still at its declared default", shared with the
   // host codec so the hook and the encoder can never disagree about it.
   sameWidgetRouteValue,
+  deriveSurfaceTokens,
 } from "./contract.js";
 
 /** @internal — host-injected context value of shape WidgetContext (see index.d.ts). */
@@ -67,6 +68,27 @@ export function WidgetContextProvider({ value, children }) {
   return React.createElement(HostWidgetContext.Provider, { value }, children);
 }
 
+/**
+ * @internal — a surface painting its own fill inside a coloured section
+ * becomes the surface its content reads and its buttons are measured against
+ * (`<Card>` uses it), by the derivation a layout container applies.
+ * Outside such a section there is no backdrop and nothing changes.
+ */
+export function BackdropScope({ basis, children }) {
+  const ctx = useContext(HostWidgetContext);
+  const theme = ctx && ctx.workspace ? ctx.workspace.theme : null;
+  const colors = theme && theme.colors;
+  const scoped = Boolean(basis && colors && colors.backdrop && colors.backdrop !== basis);
+  const value = useMemo(
+    () =>
+      scoped
+        ? { ...ctx, workspace: { ...ctx.workspace, theme: { ...theme, colors: { ...colors, ...deriveSurfaceTokens(basis), backdrop: basis } } } }
+        : ctx,
+    [scoped, ctx, theme, colors, basis],
+  );
+  return React.createElement(HostWidgetContext.Provider, { value }, children);
+}
+
 // Exported for ./toast.js + future hook modules outside hooks.js. Internal
 // utility — widget code should not import this directly.
 export function useWidgetContextOrThrow(hookName) {

package/dist/host.d.ts

@@ -39,6 +39,21 @@ export type ThemeWidgetStyles = Record<string, ThemeComponentStyle>;
  */
 export function normaliseThemeComponents(raw: unknown): ThemeComponents;
 
+/** Minimum contrast: `text` for labels (WCAG 1.4.3), `boundary` for edges (1.4.11). */
+export const INK_CONTRAST: Readonly<{ text: number; boundary: number }>;
+
+/**
+ * The measured re-ink rule a painted section applies to its text and buttons:
+ * `current` while it reaches `minimum` against `backdrop`, else `candidate`
+ * when that reads better there, else `current`.
+ */
+export function inkForBackdrop(
+  current: string,
+  candidate: string,
+  backdrop: string,
+  minimum: number,
+): string;
+
 /**
  * REQ-THEME-ELEMENT host helper: validates a raw `themeConfig.widgetStyles` blob.
  * Structural only — the key space is the workspace's widget catalog, not the

package/dist/host.js

@@ -41,7 +41,7 @@ export {
 // surface — the page background and every container that carries its own fill.
 // Host plumbing, deliberately off the author entry point: a widget reads the
 // already-correct `useTheme().colors`, it never derives them itself.
-export { deriveSurfaceTokens } from "./contract.js";
+export { deriveSurfaceTokens, inkForBackdrop, INK_CONTRAST } from "./contract.js";
 
 // REQ-WSDK-PLATFORM §6: the host half of `useToast()` — the queue, the
 // auto-dismiss timing, and the themed values a toast is painted with. The

package/dist/index.d.ts

@@ -393,6 +393,11 @@ export interface ThemeTokens {
     onSurface: string;
     danger: string;
     [k: string]: string;
+  } & {
+    /** Inside a section painting its own fill: that fill. Absent on the page. */
+    backdrop?: string;
+    /** The surface the look was designed for, which `backdrop` is judged against. */
+    backdropBase?: string;
   };
   /** sc-3696: the shared elevation vocabulary. Spread a level into a style. */
   elevation: {

package/package.json

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