@colixsystems/widget-sdk 0.67.1 → 0.69.0

package/README.md

@@ -17,7 +17,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 
 | Group | Hook (signature) | Returns | Reads / scope |
 | ----- | ---------------- | ------- | ------------- |
-| **CORE** | `useTheme()` | `{ colors, spacing, radii, typography, components }` | `ctx.workspace.theme` — no scope. `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
+| **CORE** | `useTheme()` | `{ colors, elevation, spacing, radii, typography, components }` | `ctx.workspace.theme` — no scope. `elevation` is the shared depth scale (`none / sm / md / lg / xl`) you spread into a style; `colors` includes the accent's quiet tiers (`primarySoft` / `onPrimarySoft` / `primaryStrong`). `components` is HOST-OWNED (the theme's per-component style tokens); the host has already folded it into your `props.style`, so read `useWidgetStyle()` and ignore this slice. |
 | **CORE** | `useWidgetStyle()` | `{ [styleField]: value }` | `ctx.props.style` — no scope. The author-set per-widget style values declared in `manifest.styleSchema`; apply each onto whatever element you choose. |
 | **CORE** | `useUser()` | `{ id, email, displayName, roles, groupIds }` | `ctx.user` (host-built context, **camelCase** — not a wire payload; `id` null when anonymous) — no scope |
 | **CORE** | `useNavigation()` | `{ goTo, goBack, push, replace, back, currentRoute }` | `ctx.navigation` — no scope (external URLs use the `Linking` primitive) |
@@ -61,9 +61,10 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 - **`useTheme()` gains a `components` slice.** It is HOST-OWNED plumbing, not an author API: by the time your component renders, the host has already folded the matching tokens into `props.style`. Do not read `theme.components` and do not re-apply it — you would double-apply the theme and defeat the author's own styling.
 - **New host-only exports on `@colixsystems/widget-sdk/host`:** `normaliseThemeComponents(raw)` and `applyThemeComponentStyle(manifestId, theme, props)`. These are the platform-host surface (the web Player / Studio canvas and the exported Expo app), never the author API — one implementation, so the two hosts cannot diverge.
-- **`CONTRACT.themeComponents` / `CONTRACT.themeComponentShadows`** publish the vocabulary: each scope's tokens, their value types and ranges, and the widget → style-field bindings. `themeTokens.components` defaults to `{}`.
+- **`CONTRACT.themeComponents` / `CONTRACT.themeComponentShadows` / `CONTRACT.themeComponentGradient`** publish the vocabulary: each scope's tokens, their value types and ranges, and the widget → style-field bindings. `themeTokens.components` defaults to `{}`.
+- **The `button` and `card` scopes carry a `gradient` token (sc-3727)** — `{ from: "#hex", to: "#hex", angle: 0-359 }`, painted through the `<Gradient>` primitive. It reaches a widget as an ordinary style field (`gradient`, `cardGradient`, `submitGradient`), so the author rule is unchanged: read `props.style`, and treat an explicit `null` as "this instance opted out of the app-wide gradient" rather than as unset.
 
-`CONTRACT.version` → `1.45.0`. Additive; no existing export changed signature, and an unthemed app renders identically.
+`CONTRACT.version` → `1.46.0`. Additive; no existing export changed signature, and an unthemed app renders identically.
 
 ### What's new in 0.66.0
 
@@ -514,17 +515,19 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 
 **Decide before you build:** the widget's shape (card, list, form, control), its hierarchy (the one thing the eye lands on first), its single accent moment, and its empty/loading/error look — then compose. Specific decisions make a distinctive widget; leaving them to default makes a generic one.
 
-- **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners. Don't hardcode raw pixel values.
-- **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
+- **Pull spacing and corners from tokens.** Use `theme.spacing` (`xs / sm / md / lg / xl`) for a consistent padding and gap rhythm, and `theme.radii` (`sm / md / lg / pill`) for corners — `radii.lg` for cards and hero surfaces, `radii.md` for controls nested inside one. Don't hardcode raw pixel values.
+- **Build a hierarchy.** A clear title (large, bold, `colors.onSurface`), body text, and muted captions in `colors.onSurfaceMuted` — three weights, not one flat size. Reserve full-strength `colors.primary` (with `colors.onPrimary` for text on it) for the single most important action or metric.
 - **Set the theme font on every `Text`.** React Native `Text` does not inherit `fontFamily` from a parent, so a text element that omits it falls back to the system font and ignores the workspace's configured font. Put `theme.typography.fontFamily` on every text style (a shared `StyleSheet` built from `theme` keeps it in one place) and size text with `theme.typography.sizes`.
-- **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.md` + a `colors.border` hairline or a subtle shadow. Use the status roles (`danger / success / warning / info`) for state.
+- **Contain and elevate.** Wrap a logical unit in a surface: `colors.surface` + padding + `radii.lg` + `...theme.elevation.sm`. Give it the elevation **or** a `colors.border` hairline, not both — and prefer the elevation, because a hairline-only card reads as a wireframe. `theme.elevation` is a token table you spread into a style (`...theme.elevation.md`), covering `none / sm / md / lg / xl`; never hand-write `shadowOpacity` / `shadowRadius` / `boxShadow`. Use the status roles (`danger / success / warning / info`) for state.
+- **Tint the supporting cast.** `colors.primarySoft` is a tint of the workspace accent over the surface and `colors.onPrimarySoft` is guaranteed readable on it (WCAG AA, on light and dark themes alike). Use the pair for chips, secondary buttons, progress tracks, icon badges and selected rows. One saturated accent moment surrounded by several pale echoes of the same hue is what reads as designed — a row of grey-outlined buttons reads as a form. Never hand-mix a tint with `rgba(...)` or a translucent overlay.
+- **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Compose forms — pair fields into rows, don't stack one per row.** Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the native-safe way to go multi-column (widgets have no breakpoint hook, so never hard-code fixed columns). Keep wide fields (email, address, notes) full-width, cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only).
 - **Respond to touch.** Give every `Pressable` a pressed state via the function-style `style={({ pressed }) => [base, pressed && { opacity: 0.7 }]}`.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).
 - **Use imagery deliberately.** Render pictures with the `Image` primitive (`source` takes a URL or `{ uri }`); resolve workspace assets via `useAsset()`. Give every image a sized, `radii`-clipped container so it never renders as a raw rectangle, and never hardcode a credentialed image URL — expose an `image`-type property instead.
 - **Design the empty, loading, and error states.** A blank box on a fresh install reads as broken — show a short helper line when a list is empty, a calm loading line, and a single human sentence in `colors.danger` on error.
 
-**Honest ceilings:** the styling surface is React Native style objects, not full CSS. There are no per-widget gradients, no custom CSS keyframe animations or `transition` strings, and shadows are limited to the five elevation presets (`none / sm / md / lg / xl`). Aim for clean, confident, professional polish within those bounds.
+**Honest ceilings:** the styling surface is React Native style objects, not full CSS. Gradients come from the `<Gradient>` primitive (not a CSS `linear-gradient` string), depth comes from `theme.elevation` (not arbitrary `box-shadow` stacks), and there are no custom CSS keyframe animations or `transition` strings, no `filter` / `backdrop-filter` / `clip-path` / `mask` / blend modes, and no opacity-faked tints (that's what `primarySoft` is for). Aim for clean, confident, professional polish within those bounds — lifted surfaces, generous corners, one accent moment.
 
 ## Managing app users from a widget
 

package/dist/contract.cjs

@@ -8,10 +8,56 @@
 // Keep edits in lockstep between `contract.cjs` and `contract.js`. The
 // SDK build script copies both into `dist/`.
 
+// REQ-AI-AGENT-DESIGN (sc-3696): the ONE cross-platform elevation vocabulary.
+// `shadow*` applies on iOS + react-native-web, `elevation` drives Android.
+// Consumed by `_shared/cardStyle.js` SHADOW_PRESETS (web + baked built-ins),
+// the compiler's generated layout `elevationStyles`, and widgets reading
+// `useTheme().elevation` — so a widget shadow and a container shadow match.
+const ELEVATION = Object.freeze({
+  none: Object.freeze({}),
+  sm: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 1 }),
+    shadowOpacity: 0.08,
+    shadowRadius: 2,
+    elevation: 2,
+  }),
+  md: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 2 }),
+    shadowOpacity: 0.12,
+    shadowRadius: 4,
+    elevation: 4,
+  }),
+  lg: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 4 }),
+    shadowOpacity: 0.16,
+    shadowRadius: 8,
+    elevation: 8,
+  }),
+  xl: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 8 }),
+    shadowOpacity: 0.2,
+    shadowRadius: 12,
+    elevation: 12,
+  }),
+});
+
 const DEFAULT_THEME_TOKENS = Object.freeze({
   colors: Object.freeze({
     primary: "#3b82f6",
     onPrimary: "#ffffff",
+    // REQ-AI-AGENT-DESIGN (sc-3696): the accent's quiet tiers. `primarySoft` is
+    // a tint of the accent over the surface (chips, secondary buttons, progress
+    // tracks); `onPrimarySoft` is contrast-guaranteed against it;
+    // `primaryStrong` is the accent's deeper end for a gradient's far stop.
+    // All three are re-derived per tenant by `deriveAccentTints` — these
+    // literals are the derivation applied to the default palette.
+    primarySoft: "#ebf3fe",
+    onPrimarySoft: "#3168c2",
+    primaryStrong: "#326bc8",
     secondary: "#10b981",
     onSecondary: "#ffffff",
     surface: "#ffffff",
@@ -24,6 +70,7 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     warning: "#d97706",
     info: "#0284c7",
   }),
+  elevation: ELEVATION,
   spacing: Object.freeze({ xs: 4, sm: 8, md: 16, lg: 24, xl: 32 }),
   radii: Object.freeze({ sm: 4, md: 8, lg: 16, pill: 9999 }),
   typography: Object.freeze({
@@ -60,6 +107,17 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
 // cannot drift between what Mason may emit and what a host actually applies.
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
+// sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
+// angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
+// variant (a component fill projects through `<Gradient>`, which is linear-only
+// on both hosts). Declared once so the coercion, the Studio control and the
+// planner prompt agree on the bounds.
+const THEME_COMPONENT_GRADIENT = Object.freeze({
+  angleMin: 0,
+  angleMax: 359,
+  defaultAngle: 180,
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -68,6 +126,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
   radius: "cardRadius",
   padding: "cardPadding",
   shadow: "shadow",
+  gradient: "cardGradient",
 });
 
 // A form widget's submit button — the `button` scope reaches it through the
@@ -75,6 +134,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
 const FORM_SUBMIT_FIELDS = Object.freeze({
   background: "submitBackground",
   textColor: "submitTextColor",
+  gradient: "submitGradient",
 });
 
 const THEME_COMPONENTS = Object.freeze({
@@ -87,6 +147,7 @@ const THEME_COMPONENTS = Object.freeze({
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
       fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.sm" }),
       shadow: Object.freeze({ type: "shadow" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.button": Object.freeze({
@@ -96,6 +157,7 @@ const THEME_COMPONENTS = Object.freeze({
         radius: "radius",
         fontSize: "fontSize",
         shadow: "shadow",
+        gradient: "gradient",
       }),
       "appstudio.form-input": FORM_SUBMIT_FIELDS,
       "appstudio.form-builder": FORM_SUBMIT_FIELDS,
@@ -109,6 +171,7 @@ const THEME_COMPONENTS = Object.freeze({
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.md" }),
       padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.md" }),
       shadow: Object.freeze({ type: "shadow" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.user": CARD_SURFACE_FIELDS,
@@ -119,6 +182,7 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.notifications": CARD_SURFACE_FIELDS,
       "appstudio.form-input": CARD_SURFACE_FIELDS,
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
+      "appstudio.user-management": CARD_SURFACE_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -376,7 +440,13 @@ const HOOKS = [
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
       "ctx.filestore.files.upload. `upload(file, { folderId? })` resolves " +
       "to the created file row or throws the wire error; a 404 means the " +
-      "destination folder denied a write (REQ-FSH canWrite gate).",
+      "destination folder denied a write (REQ-FSH canWrite gate). " +
+      "ALWAYS pass spaceType explicitly — omitting it falls back to " +
+      "'project', which is unreadable by a logged-out visitor. Choose it by " +
+      "who must SEE the file: 'public' for content the app displays to " +
+      "anyone browsing (product, catalogue, gallery, cover images), " +
+      "'project' for content restricted to signed-in workspace users, " +
+      "'personal' for a file private to the uploading app user.",
     returnShape: {
       upload: "(file, { folderId? }) => Promise<FilestoreFile>",
       uploading: "boolean",
@@ -958,6 +1028,16 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // REQ-AI-AGENT-DESIGN (sc-3696) — the gradient surface. Widgets previously had
+  // no gradient at all, which is why generated widgets read flatter than the
+  // competition; this is the ONE cross-platform way to paint one.
+  {
+    name: "Gradient",
+    description:
+      "Linear-gradient surface. `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={{ borderRadius: theme.radii.lg, padding: theme.spacing.md }}>…</Gradient>`. A View that paints a gradient behind its children — accepts every View style prop, so it replaces the `View` you would otherwise give a flat `backgroundColor`. `colors` takes two or more theme colour roles (never raw hex); `angle` is CSS degrees (0 = to top, 90 = to right, default 180 = to bottom). Web paints a CSS `linear-gradient`; native delegates to expo-linear-gradient with the same angle projection, so the two hosts match. Use it for at most ONE element per widget (the hero action or a stat header) — text on it uses `colors.onPrimary`.",
+    rnComponent: "expo-linear-gradient",
+    docsUrl: "https://docs.expo.dev/versions/latest/sdk/linear-gradient/",
+  },
 ];
 
 const CATEGORIES = [
@@ -1573,7 +1653,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "drawing",
     description:
-      "Linear-gradient fill (<LinearGradient colors={[...]} />). The cross-platform gradient — works on both platforms (react-native-linear-gradient is native-only; prefer this).",
+      "Linear-gradient fill (<LinearGradient colors={[...]} />). Prefer the SDK's <Gradient> primitive: it wraps this on native and CSS on web, so it resolves in an AI-agent widget (which is transpiled, not bundled) where a bare import of this package does not. Reach for the package directly only from a BUNDLED widget needing a gradient shape this primitive can't express.",
   },
   {
     specifier: "lottie-react-native",
@@ -2087,7 +2167,21 @@ const CONTRACT = deepFreeze({
   //    (`@colixsystems/widget-sdk/host`), never the author surface. Additive: no
   //    export changed signature and a theme with no `components` key resolves to
   //    an empty override, rendering identically to before.
-  version: "1.45.0",
+  // 1.46.0: additive (sc-3727) — a `gradient` token type on the per-component
+  //    vocabulary. The `button` and `card` scopes each gain a `gradient` token
+  //    whose value is `{ from: "#hex", to: "#hex", angle: 0-359 }` — the
+  //    `backgroundGradient` grammar minus the radial variant, because a component
+  //    fill paints through the `<Gradient>` primitive, which is linear on both
+  //    hosts. `themeComponentGradient` publishes the angle bounds + default so the
+  //    coercion, the Studio control and the planner prompt cannot disagree. The
+  //    token binds to per-instance style fields the target widgets read
+  //    (`gradient` on Button, `cardGradient` on every card surface,
+  //    `submitGradient` on a form's submit button), so the theme value is a
+  //    DEFAULT an author overrides per instance — or suppresses with an explicit
+  //    null, which is how one button stays flat while the rest are gradiented.
+  //    Additive: no export changed signature and a theme with no gradient token
+  //    renders exactly as before.
+  version: "1.46.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2100,6 +2194,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
+  themeComponentGradient: THEME_COMPONENT_GRADIENT,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
@@ -2122,10 +2217,164 @@ function requiredContextKeys() {
   return [...keys];
 }
 
+// ---------------------------------------------------------------------------
+// Theme derivation (REQ-THEME-DARK + REQ-AI-AGENT-DESIGN)
+//
+// The colour maths every host applies on top of a tenant's picked palette.
+// It lives HERE, in the dual-format contract, because BOTH hosts need it and
+// both can reach it: the web Player through `frontend/src/services/widgetTheme.js`
+// and the exported Expo app through the compiler's generated widget-theme
+// module (which already imports `CONTRACT` from this package). Previously each
+// host carried its own hand-mirrored copy of `mixHex` / `readableTextColor` —
+// one source removes that drift (CLAUDE.md §3).
+// ---------------------------------------------------------------------------
+
+const HEX_RE = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+
+function isHexColor(value) {
+  return typeof value === "string" && HEX_RE.test(value);
+}
+
+function hexChannels(hex) {
+  let h = hex.slice(1);
+  if (h.length === 3) {
+    h = h
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  }
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+
+/** Relative luminance (WCAG 2.1) of a hex colour. */
+function relativeLuminance(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const lin = (c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** WCAG contrast ratio between two hex colours. Always >= 1. */
+function contrastRatio(a, b) {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/** Linear sRGB mix of two hex colours (`t` 0 = a, 1 = b). Bad input → `a`. */
+function mixHex(a, b, t) {
+  if (!isHexColor(a) || !isHexColor(b)) return a;
+  const pa = hexChannels(a);
+  const pb = hexChannels(b);
+  const channel = (i) => Math.round(pa[i] + (pb[i] - pa[i]) * t);
+  const hex = (n) =>
+    Math.max(0, Math.min(255, n)).toString(16).padStart(2, "0");
+  return `#${hex(channel(0))}${hex(channel(1))}${hex(channel(2))}`;
+}
+
+/**
+ * Pick a readable text colour (`dark` or `light`) for a solid background.
+ * A light background gets the dark option and vice versa, so `onPrimary` /
+ * `onSecondary` follow whatever accent the tenant picked.
+ */
+function readableTextColor(hex, dark, light) {
+  if (!isHexColor(hex)) return light;
+  return relativeLuminance(hex) > 0.55 ? dark : light;
+}
+
+// A tint at 10% accent reads as "quietly accented" on both a white and a dark
+// surface without competing with the full-strength accent moment.
+const ACCENT_TINT_WEIGHT = 0.9;
+// How far `primaryStrong` travels toward the text colour. Deepens the accent on
+// a light theme and lightens it on a dark one, which is the right direction for
+// a gradient's far stop in both.
+const ACCENT_STRONG_WEIGHT = 0.22;
+const ACCENT_TEXT_MIN_CONTRAST = 4.5;
+
+/**
+ * REQ-AI-AGENT-DESIGN (sc-3696): derive the accent's quiet tiers from the
+ * resolved palette. Returns `{ primarySoft, onPrimarySoft, primaryStrong }`.
+ *
+ * `onPrimarySoft` is not a fixed mix: the accent is stepped toward the surface's
+ * text colour until it clears WCAG AA (4.5:1) against the tint, so a chip label
+ * is legible for EVERY tenant accent rather than only for accents that happen
+ * to be dark enough. Returns `null` when the inputs aren't usable hex, letting
+ * the caller keep the default tokens.
+ */
+function deriveAccentTints(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const primarySoft = mixHex(primary, surface, ACCENT_TINT_WEIGHT);
+  let onPrimarySoft = primary;
+  for (let t = 0; t <= 0.9; t += 0.05) {
+    onPrimarySoft = mixHex(primary, onSurface, t);
+    if (contrastRatio(onPrimarySoft, primarySoft) >= ACCENT_TEXT_MIN_CONTRAST) {
+      break;
+    }
+  }
+  return {
+    primarySoft,
+    onPrimarySoft,
+    primaryStrong: mixHex(primary, onSurface, ACCENT_STRONG_WEIGHT),
+  };
+}
+
+/**
+ * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
+ * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
+ * top-left, y down). Single source for the SDK's `<Gradient>` primitive and
+ * the compiler's app-background backdrop, so a widget gradient and the app
+ * gradient read the same angle identically (CLAUDE.md §3).
+ */
+function gradientAngleToVector(angle) {
+  const deg = Number.isFinite(angle) ? angle : 180;
+  const rad = ((deg - 90) * Math.PI) / 180;
+  const dx = Math.cos(rad);
+  const dy = Math.sin(rad);
+  return {
+    start: { x: 0.5 - dx / 2, y: 0.5 - dy / 2 },
+    end: { x: 0.5 + dx / 2, y: 0.5 + dy / 2 },
+  };
+}
+
+// Alpha is allowed here (unlike HEX_RE) because the Mason build runner already
+// persists 8-digit component colours; the host must not drop what it accepted.
+const GRADIENT_HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+/**
+ * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ *
+ * ONE validator for a value arriving by two routes — the theme token and the
+ * author's never-coerced per-instance `props.style` — so `set_theme` and the
+ * renderer cannot disagree about the same value (CLAUDE.md §3). Both stops are
+ * required: a one-stop gradient would paint a fill the author never chose. The
+ * hex grammar is also the injection guard — these stops are interpolated into
+ * CSS and into generated export source.
+ */
+function normaliseComponentGradient(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const from = typeof raw.from === "string" ? raw.from.trim() : "";
+  const to = typeof raw.to === "string" ? raw.to.trim() : "";
+  if (!GRADIENT_HEX_RE.test(from) || !GRADIENT_HEX_RE.test(to)) return null;
+  const { defaultAngle } = THEME_COMPONENT_GRADIENT;
+  // Read once — a second read of an accessor could return a different value and
+  // land NaN in a style.
+  const angle = raw.angle;
+  const deg = Number.isFinite(angle) ? Math.round(angle) : defaultAngle;
+  return { from, to, angle: ((deg % 360) + 360) % 360 };
+}
+
 module.exports = {
   CONTRACT,
   isHookAllowed,
   requiredContextKeys,
+  isHexColor,
+  mixHex,
+  contrastRatio,
+  readableTextColor,
+  deriveAccentTints,
+  gradientAngleToVector,
+  normaliseComponentGradient,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/contract.js

@@ -8,10 +8,56 @@
 // Keep edits in lockstep between `contract.cjs` and `contract.js`. The
 // SDK build script copies both into `dist/`.
 
+// REQ-AI-AGENT-DESIGN (sc-3696): the ONE cross-platform elevation vocabulary.
+// `shadow*` applies on iOS + react-native-web, `elevation` drives Android.
+// Consumed by `_shared/cardStyle.js` SHADOW_PRESETS (web + baked built-ins),
+// the compiler's generated layout `elevationStyles`, and widgets reading
+// `useTheme().elevation` — so a widget shadow and a container shadow match.
+const ELEVATION = Object.freeze({
+  none: Object.freeze({}),
+  sm: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 1 }),
+    shadowOpacity: 0.08,
+    shadowRadius: 2,
+    elevation: 2,
+  }),
+  md: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 2 }),
+    shadowOpacity: 0.12,
+    shadowRadius: 4,
+    elevation: 4,
+  }),
+  lg: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 4 }),
+    shadowOpacity: 0.16,
+    shadowRadius: 8,
+    elevation: 8,
+  }),
+  xl: Object.freeze({
+    shadowColor: "#000",
+    shadowOffset: Object.freeze({ width: 0, height: 8 }),
+    shadowOpacity: 0.2,
+    shadowRadius: 12,
+    elevation: 12,
+  }),
+});
+
 const DEFAULT_THEME_TOKENS = Object.freeze({
   colors: Object.freeze({
     primary: "#3b82f6",
     onPrimary: "#ffffff",
+    // REQ-AI-AGENT-DESIGN (sc-3696): the accent's quiet tiers. `primarySoft` is
+    // a tint of the accent over the surface (chips, secondary buttons, progress
+    // tracks); `onPrimarySoft` is contrast-guaranteed against it;
+    // `primaryStrong` is the accent's deeper end for a gradient's far stop.
+    // All three are re-derived per tenant by `deriveAccentTints` — these
+    // literals are the derivation applied to the default palette.
+    primarySoft: "#ebf3fe",
+    onPrimarySoft: "#3168c2",
+    primaryStrong: "#326bc8",
     secondary: "#10b981",
     onSecondary: "#ffffff",
     surface: "#ffffff",
@@ -24,6 +70,7 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
     warning: "#d97706",
     info: "#0284c7",
   }),
+  elevation: ELEVATION,
   spacing: Object.freeze({ xs: 4, sm: 8, md: 16, lg: 24, xl: 32 }),
   radii: Object.freeze({ sm: 4, md: 8, lg: 16, pill: 9999 }),
   typography: Object.freeze({
@@ -60,6 +107,17 @@ const DEFAULT_THEME_TOKENS = Object.freeze({
 // cannot drift between what Mason may emit and what a host actually applies.
 const THEME_COMPONENT_SHADOWS = Object.freeze(["none", "sm", "md", "lg"]);
 
+// sc-3727 — the `gradient` token's value shape: two hex stops plus a CSS-degree
+// angle, the same grammar as `themeConfig.backgroundGradient` minus the radial
+// variant (a component fill projects through `<Gradient>`, which is linear-only
+// on both hosts). Declared once so the coercion, the Studio control and the
+// planner prompt agree on the bounds.
+const THEME_COMPONENT_GRADIENT = Object.freeze({
+  angleMin: 0,
+  angleMax: 359,
+  defaultAngle: 180,
+});
+
 // The card-surface field names shared by every widget that paints its own card
 // (frontend/src/components/widgets/_shared/cardStyle.js CARD_STYLE_SCHEMA).
 const CARD_SURFACE_FIELDS = Object.freeze({
@@ -68,6 +126,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
   radius: "cardRadius",
   padding: "cardPadding",
   shadow: "shadow",
+  gradient: "cardGradient",
 });
 
 // A form widget's submit button — the `button` scope reaches it through the
@@ -75,6 +134,7 @@ const CARD_SURFACE_FIELDS = Object.freeze({
 const FORM_SUBMIT_FIELDS = Object.freeze({
   background: "submitBackground",
   textColor: "submitTextColor",
+  gradient: "submitGradient",
 });
 
 const THEME_COMPONENTS = Object.freeze({
@@ -87,6 +147,7 @@ const THEME_COMPONENTS = Object.freeze({
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.sm" }),
       fontSize: Object.freeze({ type: "size", min: 8, max: 96, uiDefault: "typography.sizes.sm" }),
       shadow: Object.freeze({ type: "shadow" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.button": Object.freeze({
@@ -96,6 +157,7 @@ const THEME_COMPONENTS = Object.freeze({
         radius: "radius",
         fontSize: "fontSize",
         shadow: "shadow",
+        gradient: "gradient",
       }),
       "appstudio.form-input": FORM_SUBMIT_FIELDS,
       "appstudio.form-builder": FORM_SUBMIT_FIELDS,
@@ -109,6 +171,7 @@ const THEME_COMPONENTS = Object.freeze({
       radius: Object.freeze({ type: "size", min: 0, max: 48, uiDefault: "radii.md" }),
       padding: Object.freeze({ type: "size", min: 0, max: 64, uiDefault: "spacing.md" }),
       shadow: Object.freeze({ type: "shadow" }),
+      gradient: Object.freeze({ type: "gradient" }),
     }),
     targets: Object.freeze({
       "appstudio.user": CARD_SURFACE_FIELDS,
@@ -119,6 +182,7 @@ const THEME_COMPONENTS = Object.freeze({
       "appstudio.notifications": CARD_SURFACE_FIELDS,
       "appstudio.form-input": CARD_SURFACE_FIELDS,
       "appstudio.form-builder": CARD_SURFACE_FIELDS,
+      "appstudio.user-management": CARD_SURFACE_FIELDS,
     }),
   }),
   text: Object.freeze({
@@ -376,7 +440,13 @@ const HOOKS = [
       "`owner_id`, `folder_id`, plus the binary `file`), and POSTs through " +
       "ctx.filestore.files.upload. `upload(file, { folderId? })` resolves " +
       "to the created file row or throws the wire error; a 404 means the " +
-      "destination folder denied a write (REQ-FSH canWrite gate).",
+      "destination folder denied a write (REQ-FSH canWrite gate). " +
+      "ALWAYS pass spaceType explicitly — omitting it falls back to " +
+      "'project', which is unreadable by a logged-out visitor. Choose it by " +
+      "who must SEE the file: 'public' for content the app displays to " +
+      "anyone browsing (product, catalogue, gallery, cover images), " +
+      "'project' for content restricted to signed-in workspace users, " +
+      "'personal' for a file private to the uploading app user.",
     returnShape: {
       upload: "(file, { folderId? }) => Promise<FilestoreFile>",
       uploading: "boolean",
@@ -958,6 +1028,16 @@ const PRIMITIVES = [
     rnComponent: null,
     docsUrl: null,
   },
+  // REQ-AI-AGENT-DESIGN (sc-3696) — the gradient surface. Widgets previously had
+  // no gradient at all, which is why generated widgets read flatter than the
+  // competition; this is the ONE cross-platform way to paint one.
+  {
+    name: "Gradient",
+    description:
+      "Linear-gradient surface. `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={{ borderRadius: theme.radii.lg, padding: theme.spacing.md }}>…</Gradient>`. A View that paints a gradient behind its children — accepts every View style prop, so it replaces the `View` you would otherwise give a flat `backgroundColor`. `colors` takes two or more theme colour roles (never raw hex); `angle` is CSS degrees (0 = to top, 90 = to right, default 180 = to bottom). Web paints a CSS `linear-gradient`; native delegates to expo-linear-gradient with the same angle projection, so the two hosts match. Use it for at most ONE element per widget (the hero action or a stat header) — text on it uses `colors.onPrimary`.",
+    rnComponent: "expo-linear-gradient",
+    docsUrl: "https://docs.expo.dev/versions/latest/sdk/linear-gradient/",
+  },
 ];
 
 const CATEGORIES = [
@@ -1573,7 +1653,7 @@ const VETTED_IMPORTS = [
     platforms: ["web", "native"],
     category: "drawing",
     description:
-      "Linear-gradient fill (<LinearGradient colors={[...]} />). The cross-platform gradient — works on both platforms (react-native-linear-gradient is native-only; prefer this).",
+      "Linear-gradient fill (<LinearGradient colors={[...]} />). Prefer the SDK's <Gradient> primitive: it wraps this on native and CSS on web, so it resolves in an AI-agent widget (which is transpiled, not bundled) where a bare import of this package does not. Reach for the package directly only from a BUNDLED widget needing a gradient shape this primitive can't express.",
   },
   {
     specifier: "lottie-react-native",
@@ -2087,7 +2167,21 @@ const CONTRACT = deepFreeze({
   //    (`@colixsystems/widget-sdk/host`), never the author surface. Additive: no
   //    export changed signature and a theme with no `components` key resolves to
   //    an empty override, rendering identically to before.
-  version: "1.45.0",
+  // 1.46.0: additive (sc-3727) — a `gradient` token type on the per-component
+  //    vocabulary. The `button` and `card` scopes each gain a `gradient` token
+  //    whose value is `{ from: "#hex", to: "#hex", angle: 0-359 }` — the
+  //    `backgroundGradient` grammar minus the radial variant, because a component
+  //    fill paints through the `<Gradient>` primitive, which is linear on both
+  //    hosts. `themeComponentGradient` publishes the angle bounds + default so the
+  //    coercion, the Studio control and the planner prompt cannot disagree. The
+  //    token binds to per-instance style fields the target widgets read
+  //    (`gradient` on Button, `cardGradient` on every card surface,
+  //    `submitGradient` on a form's submit button), so the theme value is a
+  //    DEFAULT an author overrides per instance — or suppresses with an explicit
+  //    null, which is how one button stays flat while the rest are gradiented.
+  //    Additive: no export changed signature and a theme with no gradient token
+  //    renders exactly as before.
+  version: "1.46.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -2100,6 +2194,7 @@ const CONTRACT = deepFreeze({
   themeTokens: DEFAULT_THEME_TOKENS,
   themeComponents: THEME_COMPONENTS,
   themeComponentShadows: THEME_COMPONENT_SHADOWS,
+  themeComponentGradient: THEME_COMPONENT_GRADIENT,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
   bannedApis: BANNED_APIS,
@@ -2122,10 +2217,164 @@ function requiredContextKeys() {
   return [...keys];
 }
 
+// ---------------------------------------------------------------------------
+// Theme derivation (REQ-THEME-DARK + REQ-AI-AGENT-DESIGN)
+//
+// The colour maths every host applies on top of a tenant's picked palette.
+// It lives HERE, in the dual-format contract, because BOTH hosts need it and
+// both can reach it: the web Player through `frontend/src/services/widgetTheme.js`
+// and the exported Expo app through the compiler's generated widget-theme
+// module (which already imports `CONTRACT` from this package). Previously each
+// host carried its own hand-mirrored copy of `mixHex` / `readableTextColor` —
+// one source removes that drift (CLAUDE.md §3).
+// ---------------------------------------------------------------------------
+
+const HEX_RE = /^#[0-9a-f]{3}([0-9a-f]{3})?$/i;
+
+function isHexColor(value) {
+  return typeof value === "string" && HEX_RE.test(value);
+}
+
+function hexChannels(hex) {
+  let h = hex.slice(1);
+  if (h.length === 3) {
+    h = h
+      .split("")
+      .map((c) => c + c)
+      .join("");
+  }
+  return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
+}
+
+/** Relative luminance (WCAG 2.1) of a hex colour. */
+function relativeLuminance(hex) {
+  const [r, g, b] = hexChannels(hex).map((v) => v / 255);
+  const lin = (c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+/** WCAG contrast ratio between two hex colours. Always >= 1. */
+function contrastRatio(a, b) {
+  const la = relativeLuminance(a);
+  const lb = relativeLuminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/** Linear sRGB mix of two hex colours (`t` 0 = a, 1 = b). Bad input → `a`. */
+function mixHex(a, b, t) {
+  if (!isHexColor(a) || !isHexColor(b)) return a;
+  const pa = hexChannels(a);
+  const pb = hexChannels(b);
+  const channel = (i) => Math.round(pa[i] + (pb[i] - pa[i]) * t);
+  const hex = (n) =>
+    Math.max(0, Math.min(255, n)).toString(16).padStart(2, "0");
+  return `#${hex(channel(0))}${hex(channel(1))}${hex(channel(2))}`;
+}
+
+/**
+ * Pick a readable text colour (`dark` or `light`) for a solid background.
+ * A light background gets the dark option and vice versa, so `onPrimary` /
+ * `onSecondary` follow whatever accent the tenant picked.
+ */
+function readableTextColor(hex, dark, light) {
+  if (!isHexColor(hex)) return light;
+  return relativeLuminance(hex) > 0.55 ? dark : light;
+}
+
+// A tint at 10% accent reads as "quietly accented" on both a white and a dark
+// surface without competing with the full-strength accent moment.
+const ACCENT_TINT_WEIGHT = 0.9;
+// How far `primaryStrong` travels toward the text colour. Deepens the accent on
+// a light theme and lightens it on a dark one, which is the right direction for
+// a gradient's far stop in both.
+const ACCENT_STRONG_WEIGHT = 0.22;
+const ACCENT_TEXT_MIN_CONTRAST = 4.5;
+
+/**
+ * REQ-AI-AGENT-DESIGN (sc-3696): derive the accent's quiet tiers from the
+ * resolved palette. Returns `{ primarySoft, onPrimarySoft, primaryStrong }`.
+ *
+ * `onPrimarySoft` is not a fixed mix: the accent is stepped toward the surface's
+ * text colour until it clears WCAG AA (4.5:1) against the tint, so a chip label
+ * is legible for EVERY tenant accent rather than only for accents that happen
+ * to be dark enough. Returns `null` when the inputs aren't usable hex, letting
+ * the caller keep the default tokens.
+ */
+function deriveAccentTints(primary, surface, onSurface) {
+  if (!isHexColor(primary) || !isHexColor(surface) || !isHexColor(onSurface)) {
+    return null;
+  }
+  const primarySoft = mixHex(primary, surface, ACCENT_TINT_WEIGHT);
+  let onPrimarySoft = primary;
+  for (let t = 0; t <= 0.9; t += 0.05) {
+    onPrimarySoft = mixHex(primary, onSurface, t);
+    if (contrastRatio(onPrimarySoft, primarySoft) >= ACCENT_TEXT_MIN_CONTRAST) {
+      break;
+    }
+  }
+  return {
+    primarySoft,
+    onPrimarySoft,
+    primaryStrong: mixHex(primary, onSurface, ACCENT_STRONG_WEIGHT),
+  };
+}
+
+/**
+ * Map a CSS-style gradient angle (0 = to top, 90 = to right) to the
+ * `{ start, end }` unit vectors `expo-linear-gradient` expects (origin at
+ * top-left, y down). Single source for the SDK's `<Gradient>` primitive and
+ * the compiler's app-background backdrop, so a widget gradient and the app
+ * gradient read the same angle identically (CLAUDE.md §3).
+ */
+function gradientAngleToVector(angle) {
+  const deg = Number.isFinite(angle) ? angle : 180;
+  const rad = ((deg - 90) * Math.PI) / 180;
+  const dx = Math.cos(rad);
+  const dy = Math.sin(rad);
+  return {
+    start: { x: 0.5 - dx / 2, y: 0.5 - dy / 2 },
+    end: { x: 0.5 + dx / 2, y: 0.5 + dy / 2 },
+  };
+}
+
+// Alpha is allowed here (unlike HEX_RE) because the Mason build runner already
+// persists 8-digit component colours; the host must not drop what it accepted.
+const GRADIENT_HEX_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+
+/**
+ * sc-3727 — normalise a component `gradient` to `{ from, to, angle }`, or `null`.
+ *
+ * ONE validator for a value arriving by two routes — the theme token and the
+ * author's never-coerced per-instance `props.style` — so `set_theme` and the
+ * renderer cannot disagree about the same value (CLAUDE.md §3). Both stops are
+ * required: a one-stop gradient would paint a fill the author never chose. The
+ * hex grammar is also the injection guard — these stops are interpolated into
+ * CSS and into generated export source.
+ */
+function normaliseComponentGradient(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const from = typeof raw.from === "string" ? raw.from.trim() : "";
+  const to = typeof raw.to === "string" ? raw.to.trim() : "";
+  if (!GRADIENT_HEX_RE.test(from) || !GRADIENT_HEX_RE.test(to)) return null;
+  const { defaultAngle } = THEME_COMPONENT_GRADIENT;
+  // Read once — a second read of an accessor could return a different value and
+  // land NaN in a style.
+  const angle = raw.angle;
+  const deg = Number.isFinite(angle) ? Math.round(angle) : defaultAngle;
+  return { from, to, angle: ((deg % 360) + 360) % 360 };
+}
+
 export {
   CONTRACT,
   isHookAllowed,
   requiredContextKeys,
+  isHexColor,
+  mixHex,
+  contrastRatio,
+  readableTextColor,
+  deriveAccentTints,
+  gradientAngleToVector,
+  normaliseComponentGradient,
   widgetTranslationPrefix,
   widgetTranslationKey,
   sharedTranslationPrefix,

package/dist/gradient-stops.js

@@ -0,0 +1,21 @@
+// REQ-AI-AGENT-DESIGN (sc-3696) — the `<Gradient>` colour-stop normaliser,
+// shared by the web (./gradient.js) and native (./gradient.native.js) builds.
+//
+// Its own module because it must be platform-neutral: importing it from
+// ./gradient.js would drag `react-native-web` into the native bundle.
+
+/**
+ * Normalise the author's `colors` prop to at least two colour stops, or `null`
+ * when there is nothing paintable.
+ *
+ * A single stop is a legitimate authoring mistake (a "gradient" of one colour);
+ * doubling it renders a flat fill rather than throwing, which keeps a
+ * half-finished widget visible on the canvas instead of blanking it.
+ */
+export function gradientStops(colors) {
+  const list = (Array.isArray(colors) ? colors : []).filter(
+    (c) => typeof c === "string" && c.trim(),
+  );
+  if (list.length === 0) return null;
+  return list.length === 1 ? [list[0], list[0]] : list;
+}

package/dist/gradient.js

@@ -0,0 +1,35 @@
+// REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (web).
+//
+// Widgets had no gradient at all: `expo-linear-gradient` is a vetted import, but
+// an AI-agent widget is only TRANSPILED (never bundled), so a bare
+// `expo-linear-gradient` import has nothing to resolve against on the web
+// Player. Exposing the gradient as an SDK primitive fixes that for every widget
+// kind at once — the SDK is already host-shimmed, so authors import from the one
+// entry point they always import from.
+//
+// Web paints a CSS `linear-gradient`. react-native-web (0.21) passes
+// `backgroundImage` straight through to the DOM — it validates only against a
+// shortform blocklist (`background`, `font`, …), and `backgroundImage` is not on
+// it — so a plain `View` carries the gradient with no DOM escape hatch.
+//
+// The native counterpart (./gradient.native.js) delegates to
+// expo-linear-gradient, projecting the SAME CSS angle through the SAME
+// `gradientAngleToVector` from the contract. Keep the two in lockstep.
+
+import React from "react";
+import * as ReactNative from "react-native-web";
+import { gradientStops } from "./gradient-stops.js";
+
+const DEFAULT_ANGLE = 180;
+
+export function Gradient({ colors, angle = DEFAULT_ANGLE, style, ...rest }) {
+  const stops = gradientStops(colors);
+  const deg = Number.isFinite(angle) ? angle : DEFAULT_ANGLE;
+  const gradientStyle = stops
+    ? { backgroundImage: `linear-gradient(${deg}deg, ${stops.join(", ")})` }
+    : null;
+  return React.createElement(ReactNative.View, {
+    ...rest,
+    style: [style, gradientStyle],
+  });
+}

package/dist/gradient.native.js

@@ -0,0 +1,32 @@
+// REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (native).
+//
+// Delegates to expo-linear-gradient, which is pinned UNCONDITIONALLY in every
+// export (BASE_DEPENDENCIES in backend/src/core/services/export-dependencies.ts,
+// where the app-shell backdrop already uses it), so Metro always resolves it.
+//
+// The web counterpart (./gradient.js) paints a CSS `linear-gradient`. Both take
+// the SAME CSS-degree `angle` and run it through the SAME
+// `gradientAngleToVector` from the contract, so a widget authored once reads
+// identically on both hosts (widget-parity skill).
+
+import React from "react";
+import { LinearGradient } from "expo-linear-gradient";
+import { gradientAngleToVector } from "./contract.js";
+import { gradientStops } from "./gradient-stops.js";
+
+const DEFAULT_ANGLE = 180;
+
+export function Gradient({ colors, angle = DEFAULT_ANGLE, style, ...rest }) {
+  const stops = gradientStops(colors);
+  if (!stops) return React.createElement(LinearGradient, { ...rest, style });
+  const { start, end } = gradientAngleToVector(
+    Number.isFinite(angle) ? angle : DEFAULT_ANGLE,
+  );
+  return React.createElement(LinearGradient, {
+    ...rest,
+    colors: stops,
+    start,
+    end,
+    style,
+  });
+}

package/dist/host.d.ts

@@ -12,7 +12,17 @@ export function resolveProps<T = Record<string, unknown>>(
   props: unknown,
 ): T;
 
-export type ThemeComponentStyle = Record<string, string | number>;
+// sc-3727: a `gradient` token's value, the one non-scalar token type.
+export interface ThemeComponentGradient {
+  from: string;
+  to: string;
+  angle: number;
+}
+
+export type ThemeComponentStyle = Record<
+  string,
+  string | number | ThemeComponentGradient
+>;
 export type ThemeComponents = Record<string, ThemeComponentStyle>;
 
 /**

package/dist/index.d.ts

@@ -267,10 +267,26 @@ export interface WidgetManifest {
   translations?: Record<string, { en: string } & Record<string, string>>;
 }
 
+/** A React Native shadow style object — one level of `ThemeTokens.elevation`. */
+export interface ElevationLevel {
+  shadowColor?: string;
+  shadowOffset?: { width: number; height: number };
+  shadowOpacity?: number;
+  shadowRadius?: number;
+  /** Android elevation. */
+  elevation?: number;
+}
+
 export interface ThemeTokens {
   colors: {
     primary: string;
     onPrimary: string;
+    /** sc-3696: tint of the accent over the surface — chips, quiet buttons. */
+    primarySoft: string;
+    /** sc-3696: contrast-guaranteed text/icon colour on `primarySoft`. */
+    onPrimarySoft: string;
+    /** sc-3696: the accent's deeper end — a gradient's far stop. */
+    primaryStrong: string;
     secondary: string;
     onSecondary: string;
     surface: string;
@@ -278,6 +294,14 @@ export interface ThemeTokens {
     danger: string;
     [k: string]: string;
   };
+  /** sc-3696: the shared elevation vocabulary. Spread a level into a style. */
+  elevation: {
+    none: ElevationLevel;
+    sm: ElevationLevel;
+    md: ElevationLevel;
+    lg: ElevationLevel;
+    xl: ElevationLevel;
+  };
   spacing: { xs: number; sm: number; md: number; lg: number; xl: number };
   radii: { sm: number; md: number; lg: number; pill: number };
   typography: {
@@ -1339,6 +1363,91 @@ export const Icon: (props: {
   color?: string;
 }) => any;
 
+/**
+ * REQ-AI-AGENT-DESIGN (sc-3696) — linear-gradient surface. A `View` that paints
+ * a gradient behind its children, so it replaces the `View` you would otherwise
+ * give a flat `backgroundColor`. Web paints a CSS `linear-gradient`; native
+ * delegates to expo-linear-gradient through the same angle projection.
+ *
+ * @example
+ *   <Gradient
+ *     colors={[theme.colors.primary, theme.colors.primaryStrong]}
+ *     angle={160}
+ *     style={{ borderRadius: theme.radii.lg, padding: theme.spacing.md }}
+ *   >
+ *     <Text style={{ color: theme.colors.onPrimary }}>Log a glass</Text>
+ *   </Gradient>
+ */
+export const Gradient: (props: {
+  /** Two or more colour stops. Use theme colour roles, never raw hex. */
+  colors: string[];
+  /** CSS degrees: 0 = to top, 90 = to right. Defaults to 180 (to bottom). */
+  angle?: number;
+  style?: any;
+  children?: ReactNode;
+}) => any;
+
+// ------------------------------------------------------- theme derivation
+// sc-3696: the colour maths both hosts resolve `useTheme()` with. Exported so
+// the Player (frontend/src/services/widgetTheme.js) and the exported app's
+// generated theme module share ONE implementation instead of mirrored copies.
+
+/** True when `value` is a 3- or 6-digit hex colour string. */
+export function isHexColor(value: unknown): boolean;
+
+/** Linear sRGB mix of two hex colours (`t` 0 = a, 1 = b). Bad input → `a`. */
+export function mixHex(a: string, b: string, t: number): string;
+
+/** WCAG contrast ratio between two hex colours. Always >= 1. */
+export function contrastRatio(a: string, b: string): number;
+
+/** Pick `dark` or `light` — whichever is readable on the given background. */
+export function readableTextColor(
+  hex: string,
+  dark: string,
+  light: string,
+): string;
+
+/**
+ * Derive the accent's quiet tiers from a resolved palette. `onPrimarySoft` is
+ * stepped toward `onSurface` until it clears WCAG AA against the tint, so a chip
+ * label is legible for every tenant accent. `null` when the inputs aren't hex.
+ */
+export function deriveAccentTints(
+  primary: string,
+  surface: string,
+  onSurface: string,
+): {
+  primarySoft: string;
+  onPrimarySoft: string;
+  primaryStrong: string;
+} | null;
+
+/**
+ * Map a CSS gradient angle (0 = to top, 90 = to right) to the `{ start, end }`
+ * unit vectors expo-linear-gradient expects.
+ */
+export function gradientAngleToVector(angle: number): {
+  start: { x: number; y: number };
+  end: { x: number; y: number };
+};
+
+export interface ComponentGradient {
+  from: string;
+  to: string;
+  angle: number;
+}
+
+/**
+ * Normalise a component `gradient` style value to `{ from, to, angle }`, or null
+ * when it is unusable. Both stops are required; the angle wraps into 0-359.
+ * Shared by the theme-token coercion and the widget render path, so the same
+ * value cannot resolve two ways.
+ */
+export function normaliseComponentGradient(
+  raw: unknown,
+): ComponentGradient | null;
+
 // Linter
 export interface LintFinding {
   rule: string;

package/dist/index.js

@@ -70,7 +70,24 @@ export {
   Icon,
   DateTimePicker,
   FilePicker,
+  Gradient,
 } from "./primitives.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
-export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";
+// sc-3696: the trailing six are the theme-derivation helpers both hosts resolve
+// `useTheme()` with (the Player through widgetTheme.js, the export through its
+// generated theme module), plus the gradient angle projection `<Gradient>`
+// shares with the app-shell backdrop. Keep comments OUT of the export clause —
+// the contract test's orphan-export scanner parses it with a regex.
+export {
+  CONTRACT,
+  isHookAllowed,
+  requiredContextKeys,
+  isHexColor,
+  mixHex,
+  contrastRatio,
+  readableTextColor,
+  deriveAccentTints,
+  gradientAngleToVector,
+  normaliseComponentGradient,
+} from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/index.native.js

@@ -68,7 +68,24 @@ export {
   Icon,
   DateTimePicker,
   FilePicker,
+  Gradient,
 } from "./primitives.native.js";
 export { lintSource, bannedIdentifiers } from "./linter.js";
-export { CONTRACT, isHookAllowed, requiredContextKeys } from "./contract.js";
+// sc-3696: the trailing six are the theme-derivation helpers both hosts resolve
+// `useTheme()` with (the Player through widgetTheme.js, the export through its
+// generated theme module), plus the gradient angle projection `<Gradient>`
+// shares with the app-shell backdrop. Keep comments OUT of the export clause —
+// the contract test's orphan-export scanner parses it with a regex.
+export {
+  CONTRACT,
+  isHookAllowed,
+  requiredContextKeys,
+  isHexColor,
+  mixHex,
+  contrastRatio,
+  readableTextColor,
+  deriveAccentTints,
+  gradientAngleToVector,
+  normaliseComponentGradient,
+} from "./contract.js";
 export { normalizeLucideIconName } from "./lucideIconName.js";

package/dist/primitives.js

@@ -76,3 +76,7 @@ export { DateTimePicker } from "./datetimepicker.js";
 // a vetted expo-document-picker pin lands. `isSupported` is a static
 // boolean widgets branch on to hide the trigger on native.
 export { FilePicker } from "./filepicker.js";
+// REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (web). Paints a CSS
+// `linear-gradient` on a View; the native build (./gradient.native.js) delegates
+// to expo-linear-gradient through the same angle projection.
+export { Gradient } from "./gradient.js";

package/dist/primitives.native.js

@@ -36,3 +36,7 @@ export { DateTimePicker } from "./datetimepicker.native.js";
 // equivalent yet, so this build renders a disabled trigger and exposes
 // `FilePicker.isSupported = false` for widgets to branch on.
 export { FilePicker } from "./filepicker.native.js";
+// REQ-AI-AGENT-DESIGN (sc-3696) — `<Gradient>` (native). Delegates to
+// expo-linear-gradient (pinned unconditionally in every export); the web build
+// (./gradient.js) paints the equivalent CSS `linear-gradient`.
+export { Gradient } from "./gradient.native.js";

package/dist/theme-components.cjs

@@ -23,7 +23,7 @@
 // widget reads. The Mason build runner validates `set_theme` against the SAME
 // literal, so what a planner may emit and what a host applies cannot diverge.
 
-const { CONTRACT } = require("./contract.cjs");
+const { CONTRACT, normaliseComponentGradient } = require("./contract.cjs");
 
 // 3-, 6- and 8-digit hex, matching what the build runner persists — the host
 // must never drop a colour the runner already accepted.
@@ -47,6 +47,11 @@ function coerceToken(def, value) {
   if (def.type === "shadow") {
     return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
   }
+  // sc-3727: the gradient value has its own normaliser on the contract, shared
+  // with the widget render path so both routes agree (CLAUDE.md §3).
+  if (def.type === "gradient") {
+    return normaliseComponentGradient(value) || undefined;
+  }
   return undefined;
 }
 

package/dist/theme-components.js

@@ -15,7 +15,7 @@
 // widget reads. The Mason build runner validates `set_theme` against the SAME
 // literal, so what a planner may emit and what a host applies cannot diverge.
 
-import { CONTRACT } from "./contract.js";
+import { CONTRACT, normaliseComponentGradient } from "./contract.js";
 
 // 3-, 6- and 8-digit hex, matching what the build runner persists — the host
 // must never drop a colour the runner already accepted.
@@ -39,6 +39,11 @@ function coerceToken(def, value) {
   if (def.type === "shadow") {
     return CONTRACT.themeComponentShadows.includes(value) ? value : undefined;
   }
+  // sc-3727: the gradient value has its own normaliser on the contract, shared
+  // with the widget render path so both routes agree (CLAUDE.md §3).
+  if (def.type === "gradient") {
+    return normaliseComponentGradient(value) || undefined;
+  }
   return undefined;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.67.1",
+  "version": "0.69.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -48,7 +48,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.js",
-    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js"
+    "test": "node --test src/__tests__/contract.test.js src/__tests__/hooks-users.test.js src/__tests__/hooks-groups.test.js src/__tests__/hooks-schema.test.js src/__tests__/hooks-assets-by-tag.test.js src/__tests__/hooks-filestore-upload.test.js src/__tests__/hooks-filestore-file.test.js src/__tests__/hooks-mutation.test.js src/__tests__/hooks-record-permissions.test.js src/__tests__/hooks-geolocation.test.js src/__tests__/hooks-subscription.test.js src/__tests__/hooks-volatile-query-key.test.js src/__tests__/linter-users-scope.test.js src/__tests__/linter-comments.test.js src/__tests__/linter-image-height.test.js src/__tests__/linter-platform.test.js src/__tests__/linter-react-import.test.js src/__tests__/lucide-icon-names.test.js src/__tests__/lucideIconName.test.js src/__tests__/manifest-actions.test.js src/__tests__/widget-translations.test.js src/__tests__/devserver.test.js src/__tests__/host-externals.test.js src/__tests__/datetimepicker.test.js src/__tests__/property-schema-resolve.test.js src/__tests__/theme-components-parity.test.js src/__tests__/theme-depth-tokens.test.js"
   },
   "engines": {
     "node": ">=18"