@colixsystems/widget-sdk 0.164.0 → 0.166.0

package/README.md

@@ -73,7 +73,24 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.164.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.165.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.166.0 (contract 1.128.0)
+
+**A bound colour can be translucent (sc-8893).** Binding and transparency were mutually exclusive: the Studio hid the opacity control the moment a colour field bound to a brand token, so an author who wanted "our brand colour at 20%" had to abandon the binding and freeze today's hex — which then stopped following a rebrand, the very thing binding exists to prevent.
+
+A binding may now carry an opacity: `"theme:colors.primary/20"` is the primary brand colour at 20%.
+
+- **`parseThemeColorTokenRef(value)` / `formatThemeColorTokenRef(path, percent)`** publish the grammar beside the existing `isThemeColorTokenRef` predicate. The BARE form inherits whatever opacity the token itself carries — a workspace may author a translucent brand colour — so `/100` is a real value, not a redundant spelling: it is how "opaque, whatever the brand does" is said. One opacity has one spelling otherwise (no leading zeros, nothing above 100).
+- **`withHexAlpha(hex, percent)` / `hexAlphaPercent(hex)`** are the percent ↔ alpha-byte conversion the Studio's opacity control and both hosts' resolver share, so the 20% a panel reads back is the 20% a render paints.
+- **An authored opacity replaces the token's.** With none authored the token is handed back verbatim, including a token that is itself translucent — reading the bare form as 100 would quietly paint a see-through brand colour solid.
+- **A token resolving to a non-hex colour stays opaque** — alpha cannot be applied without rewriting the author's notation — and the Studio disables the opacity control for that case rather than lying about it.
+- **Nothing changes for a widget author.** The host still hands your code an ordinary colour string; it is simply `#RRGGBBAA` when an opacity was authored.
+- **Fully additive.** Every stored binding is unsuffixed, parses as before, and renders byte-identically.
+
+### What's new in 0.165.0 (contract 1.127.0 — unchanged)
+
+**`no-hardcoded-design` flags a literal corner radius.** A radius is the app's shape: `theme.radii`, Theme Settings and the SDK's `Card` / `Button` / `ListRow` / `Tabs` all carry it, so a `borderRadius: 12` pinned in a widget is exactly where two widgets in one app stop matching. The rule now warns on a literal non-zero radius on any corner spelling; read it from `theme.radii.*` or a style field, or draw the surface with the SDK component. A computed radius (`size / 2` for a circle) and `0` are not flagged, and `// appstudio-design-ok: <reason>` licenses a genuine exception. Still a warning for a human author; like every linter finding it blocks the AI widget agent's publish, which is how generated widgets are held to it.
 
 ### What's new in 0.164.0 (contract 1.127.0)
 
@@ -827,7 +844,7 @@ Additive — one new hook, one new optional context-slice member; no existing ex
 
 **Two linter rules make the styling contract checkable, and `lintStyleWiring` joins the linter export (sc-6455).** Every visual value a widget writes reaches the app's owner through one of exactly two channels — a **theme token** (`useTheme()`), which is the app-wide default and follows a look change, or a **`styleSchema` field** read off `props.style`, which the Studio offers per instance in the widget editor *and* app-wide under **Design → Widget appearance**. A literal reaches neither: it outranks the theme permanently and no control on either surface can move it, so the owner finds a corner of their app they cannot restyle. Until now that rule was documentation only.
 
-- **`no-hardcoded-design`** flags a colour literal (`#rgb` / `#rrggbb` / `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`, `hsla()`), a `fontFamily` string literal, or a numeric `fontSize`. A `fontSize` resolved off a theme token or a style field (`style.valueSize ?? 18`) is *not* flagged — a literal `default` beside a declared field is the contract working. Raw `padding` / `margin` / `borderRadius` numbers are deliberately out of scope: measured layout legitimately carries them, so a spacing rule would be noise.
+- **`no-hardcoded-design`** flags a colour literal (`#rgb` / `#rrggbb` / `#rrggbbaa`, `rgb()`, `rgba()`, `hsl()`, `hsla()`), a `fontFamily` string literal, a numeric `fontSize`, or (since 0.165.0) a literal non-zero corner radius (`borderRadius: 12`, any per-corner spelling). A `fontSize` resolved off a theme token or a style field (`style.valueSize ?? 18`) is *not* flagged — a literal `default` beside a declared field is the contract working — and neither is a computed radius (`size / 2`) or `0`. Raw `padding` / `margin` numbers are deliberately out of scope: measured layout legitimately carries them, so a spacing rule would be noise.
 - **`style-field-unread`** flags a `styleSchema` field whose name appears nowhere in the widget's source — a dead control the author moves to no effect. It runs over the WHOLE bundle, not per file, so a split-impl widget that reads a field in `widget.web.jsx` and not in `widget.native.jsx` is correctly counted as wired.
 
 A value that genuinely cannot be a token — a categorical series palette, a video letterbox, a scannable QR plate — is licensed with a preceding comment. **The reason is mandatory**; a bare marker licenses nothing. A marker on its own line covers the whole statement below it (bracket-balanced, so one marker covers a multi-line palette); a trailing marker covers only its own line.

package/dist/contract.cjs

@@ -192,20 +192,64 @@ const THEME_COLOR_TOKENS = Object.freeze([
   Object.freeze({ path: "colors.secondary", label: "Secondary" }),
 ]);
 
-// sc-8326 — the `theme:<path>` value grammar, as a PREDICATE over a STORED
-// value and declared beside the allowlist it reads. Three readers have to agree
-// on what a binding IS: the Studio's colour picker writes one, both hosts
-// resolve one, and Mason's plan validator must accept one as a gradient stop.
+// sc-8326 — the `theme:<path>` value grammar, as a PARSE over a STORED value
+// and declared beside the allowlist it reads. Three readers have to agree on
+// what a binding IS: the Studio's colour picker writes one, both hosts resolve
+// one, and Mason's plan validator must accept one as a gradient stop.
 // One definition, so they cannot drift (CLAUDE.md §3).
 const THEME_TOKEN_REF_PREFIX = "theme:";
 
+// sc-8893 — a binding may carry an OPACITY, `theme:<path>/<percent>`. Without
+// it an author had to choose between a colour that follows the workspace brand
+// and one they could make translucent; "our brand colour at 20%" was only
+// expressible by freezing today's hex, which then stopped following a rebrand.
+// `/` cannot occur in a token path, so an unsuffixed binding parses exactly as
+// it always did and no stored value changes meaning.
+const THEME_TOKEN_ALPHA_SEPARATOR = "/";
+const ALPHA_OPAQUE = 100;
+
+/**
+ * Parse a stored binding into `{ path, alpha }`, or `null` when the value is
+ * not one.
+ *
+ * `alpha` is `null` for an UNSUFFIXED binding, which inherits whatever opacity
+ * the token itself carries — a brand colour may be authored translucent, and
+ * reading the bare form as 100 would silently paint it solid. A suffix is the
+ * author's own opacity and REPLACES the token's, so `/100` is a real value: it
+ * is how "opaque, whatever the brand does" is expressed.
+ */
+function parseThemeColorTokenRef(value) {
+  if (typeof value !== "string") return null;
+  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return null;
+  const body = value.slice(THEME_TOKEN_REF_PREFIX.length);
+  const cut = body.indexOf(THEME_TOKEN_ALPHA_SEPARATOR);
+  const path = cut === -1 ? body : body.slice(0, cut);
+  if (!THEME_COLOR_TOKENS.some((token) => token.path === path)) return null;
+  if (cut === -1) return { path, alpha: null };
+  const percent = body.slice(cut + 1);
+  // One spelling per opacity: no leading zeros, nothing above 100. A malformed
+  // suffix reads as "not a binding", so the field falls back to its default
+  // rather than painting a half-parsed colour.
+  if (!/^(?:0|[1-9]\d{0,2})$/.test(percent)) return null;
+  const alpha = Number(percent);
+  return alpha > ALPHA_OPAQUE ? null : { path, alpha };
+}
+
 function isThemeColorTokenRef(value) {
-  if (typeof value !== "string") return false;
-  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return false;
-  const path = value.slice(THEME_TOKEN_REF_PREFIX.length);
-  return THEME_COLOR_TOKENS.some((token) => token.path === path);
+  return parseThemeColorTokenRef(value) !== null;
 }
 
+/**
+ * Spell one binding. `percent` of `null`/`undefined` writes the bare form — the
+ * binding that defers to the token's own opacity. The path is the caller's to
+ * take from `CONTRACT.themeColorTokens`; an unlisted one spells a string this
+ * module's own parse rejects.
+ */
+function formatThemeColorTokenRef(path, percent) {
+  const ref = `${THEME_TOKEN_REF_PREFIX}${path}`;
+  if (percent === null || percent === undefined) return ref;
+  return `${ref}${THEME_TOKEN_ALPHA_SEPARATOR}${clampAlphaPercent(percent)}`;
+}
 
 // REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
 // single lever: remapping `primaryColor` to recolour "the buttons" recolours
@@ -4483,7 +4527,21 @@ const CONTRACT = deepFreeze({
   //    and form field so every widget draws them from one implementation, plus
   //    a `height` token on the `muted` scope. Additive: the built-ins render
   //    exactly as before.
-  version: "1.127.0",
+  // 1.128.0: additive (sc-8893) — a `theme:` colour binding may carry an
+  //    OPACITY, `theme:<path>/<percent>`. Binding and transparency used to be
+  //    mutually exclusive: the Studio hid the opacity control the moment a
+  //    field bound, so "our brand colour at 20%" forced the author back to a
+  //    frozen hex, which then stopped following a rebrand — the exact thing
+  //    binding exists to prevent. `parseThemeColorTokenRef` /
+  //    `formatThemeColorTokenRef` publish the grammar and
+  //    `withHexAlpha` / `hexAlphaPercent` the percent-to-byte conversion the
+  //    Studio's control and both hosts' resolver share, so 20% authored is 20%
+  //    painted. The BARE form inherits the token's own opacity (a brand colour
+  //    may be authored translucent), which makes `/100` a real value rather
+  //    than a redundant spelling: it is how "opaque, whatever the brand does"
+  //    is said. Additive: an unsuffixed binding parses and resolves exactly as
+  //    before, so every stored value is untouched.
+  version: "1.128.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4560,6 +4618,59 @@ function isHexColor(value) {
   return typeof value === "string" && HEX_RE.test(value);
 }
 
+// sc-8893 — opacity as an authored PERCENTAGE, converted here and nowhere else.
+// The Studio's opacity control and the host's binding resolver both spell a
+// colour's alpha through these, so the 20% a panel reads back is the 20% a
+// render paints. 255/100 > 1, so percent → byte is injective and the inverse
+// below is exact.
+function clampAlphaPercent(value) {
+  const n = Math.round(Number(value));
+  // Unparseable reads as fully opaque: "cannot tell" must never turn a surface
+  // see-through on its own.
+  if (!Number.isFinite(n)) return ALPHA_OPAQUE;
+  return Math.min(ALPHA_OPAQUE, Math.max(0, n));
+}
+
+function expandShortHex(hex) {
+  const body = hex.slice(1);
+  if (body.length > 4) return hex;
+  return `#${[...body].map((c) => c + c).join("")}`;
+}
+
+/**
+ * Apply `percent` opacity to a hex colour, returning `#RRGGBBAA` — or a plain
+ * `#RRGGBB` at full opacity, so an opaque colour is never rewritten with a
+ * redundant `ff`. A non-hex colour cannot carry alpha without being rewritten
+ * into another notation, so it is returned untouched rather than invented.
+ *
+ * "Hex" is `isHexColor`'s grammar — 3, 6 or 8 digits. The 4-digit `#RGBA` form
+ * is deliberately outside it (a gradient stop may not smuggle one past the
+ * injection guard), so it is returned untouched here too.
+ */
+function withHexAlpha(hex, percent) {
+  if (!isHexColor(hex)) return hex;
+  const base = expandShortHex(hex).slice(0, 7);
+  const alpha = clampAlphaPercent(percent);
+  if (alpha === ALPHA_OPAQUE) return base;
+  return `${base}${Math.round((alpha * 255) / 100)
+    .toString(16)
+    .padStart(2, "0")}`;
+}
+
+/**
+ * Read a hex colour's opacity back as a percentage. No alpha pair is 100.
+ *
+ * The percentage is lossy in this direction — 255 alpha values map onto 101
+ * percentages — so a near-opaque `fe` reads back as 100. Only a value this
+ * function produced round-trips exactly.
+ */
+function hexAlphaPercent(hex) {
+  if (!isHexColor(hex)) return ALPHA_OPAQUE;
+  const full = expandShortHex(hex);
+  if (full.length !== 9) return ALPHA_OPAQUE;
+  return Math.round((parseInt(full.slice(7), 16) * 100) / 255);
+}
+
 /**
  * The R/G/B bytes, with any alpha pair IGNORED.
  *
@@ -4788,7 +4899,11 @@ module.exports = {
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,
+  parseThemeColorTokenRef,
+  formatThemeColorTokenRef,
   THEME_TOKEN_REF_PREFIX,
+  withHexAlpha,
+  hexAlphaPercent,
   formatMoneyIn,
   normaliseCurrencyCode,
   sameWidgetRouteValue,

package/dist/contract.js

@@ -192,20 +192,64 @@ const THEME_COLOR_TOKENS = Object.freeze([
   Object.freeze({ path: "colors.secondary", label: "Secondary" }),
 ]);
 
-// sc-8326 — the `theme:<path>` value grammar, as a PREDICATE over a STORED
-// value and declared beside the allowlist it reads. Three readers have to agree
-// on what a binding IS: the Studio's colour picker writes one, both hosts
-// resolve one, and Mason's plan validator must accept one as a gradient stop.
+// sc-8326 — the `theme:<path>` value grammar, as a PARSE over a STORED value
+// and declared beside the allowlist it reads. Three readers have to agree on
+// what a binding IS: the Studio's colour picker writes one, both hosts resolve
+// one, and Mason's plan validator must accept one as a gradient stop.
 // One definition, so they cannot drift (CLAUDE.md §3).
 const THEME_TOKEN_REF_PREFIX = "theme:";
 
+// sc-8893 — a binding may carry an OPACITY, `theme:<path>/<percent>`. Without
+// it an author had to choose between a colour that follows the workspace brand
+// and one they could make translucent; "our brand colour at 20%" was only
+// expressible by freezing today's hex, which then stopped following a rebrand.
+// `/` cannot occur in a token path, so an unsuffixed binding parses exactly as
+// it always did and no stored value changes meaning.
+const THEME_TOKEN_ALPHA_SEPARATOR = "/";
+const ALPHA_OPAQUE = 100;
+
+/**
+ * Parse a stored binding into `{ path, alpha }`, or `null` when the value is
+ * not one.
+ *
+ * `alpha` is `null` for an UNSUFFIXED binding, which inherits whatever opacity
+ * the token itself carries — a brand colour may be authored translucent, and
+ * reading the bare form as 100 would silently paint it solid. A suffix is the
+ * author's own opacity and REPLACES the token's, so `/100` is a real value: it
+ * is how "opaque, whatever the brand does" is expressed.
+ */
+function parseThemeColorTokenRef(value) {
+  if (typeof value !== "string") return null;
+  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return null;
+  const body = value.slice(THEME_TOKEN_REF_PREFIX.length);
+  const cut = body.indexOf(THEME_TOKEN_ALPHA_SEPARATOR);
+  const path = cut === -1 ? body : body.slice(0, cut);
+  if (!THEME_COLOR_TOKENS.some((token) => token.path === path)) return null;
+  if (cut === -1) return { path, alpha: null };
+  const percent = body.slice(cut + 1);
+  // One spelling per opacity: no leading zeros, nothing above 100. A malformed
+  // suffix reads as "not a binding", so the field falls back to its default
+  // rather than painting a half-parsed colour.
+  if (!/^(?:0|[1-9]\d{0,2})$/.test(percent)) return null;
+  const alpha = Number(percent);
+  return alpha > ALPHA_OPAQUE ? null : { path, alpha };
+}
+
 function isThemeColorTokenRef(value) {
-  if (typeof value !== "string") return false;
-  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return false;
-  const path = value.slice(THEME_TOKEN_REF_PREFIX.length);
-  return THEME_COLOR_TOKENS.some((token) => token.path === path);
+  return parseThemeColorTokenRef(value) !== null;
 }
 
+/**
+ * Spell one binding. `percent` of `null`/`undefined` writes the bare form — the
+ * binding that defers to the token's own opacity. The path is the caller's to
+ * take from `CONTRACT.themeColorTokens`; an unlisted one spells a string this
+ * module's own parse rejects.
+ */
+function formatThemeColorTokenRef(path, percent) {
+  const ref = `${THEME_TOKEN_REF_PREFIX}${path}`;
+  if (percent === null || percent === undefined) return ref;
+  return `${ref}${THEME_TOKEN_ALPHA_SEPARATOR}${clampAlphaPercent(percent)}`;
+}
 
 // REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
 // single lever: remapping `primaryColor` to recolour "the buttons" recolours
@@ -4479,7 +4523,21 @@ const CONTRACT = deepFreeze({
   //    and form field so every widget draws them from one implementation, plus
   //    a `height` token on the `muted` scope. Additive: the built-ins render
   //    exactly as before.
-  version: "1.127.0",
+  // 1.128.0: additive (sc-8893) — a `theme:` colour binding may carry an
+  //    OPACITY, `theme:<path>/<percent>`. Binding and transparency used to be
+  //    mutually exclusive: the Studio hid the opacity control the moment a
+  //    field bound, so "our brand colour at 20%" forced the author back to a
+  //    frozen hex, which then stopped following a rebrand — the exact thing
+  //    binding exists to prevent. `parseThemeColorTokenRef` /
+  //    `formatThemeColorTokenRef` publish the grammar and
+  //    `withHexAlpha` / `hexAlphaPercent` the percent-to-byte conversion the
+  //    Studio's control and both hosts' resolver share, so 20% authored is 20%
+  //    painted. The BARE form inherits the token's own opacity (a brand colour
+  //    may be authored translucent), which makes `/100` a real value rather
+  //    than a redundant spelling: it is how "opaque, whatever the brand does"
+  //    is said. Additive: an unsuffixed binding parses and resolves exactly as
+  //    before, so every stored value is untouched.
+  version: "1.128.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -4556,6 +4614,59 @@ function isHexColor(value) {
   return typeof value === "string" && HEX_RE.test(value);
 }
 
+// sc-8893 — opacity as an authored PERCENTAGE, converted here and nowhere else.
+// The Studio's opacity control and the host's binding resolver both spell a
+// colour's alpha through these, so the 20% a panel reads back is the 20% a
+// render paints. 255/100 > 1, so percent → byte is injective and the inverse
+// below is exact.
+function clampAlphaPercent(value) {
+  const n = Math.round(Number(value));
+  // Unparseable reads as fully opaque: "cannot tell" must never turn a surface
+  // see-through on its own.
+  if (!Number.isFinite(n)) return ALPHA_OPAQUE;
+  return Math.min(ALPHA_OPAQUE, Math.max(0, n));
+}
+
+function expandShortHex(hex) {
+  const body = hex.slice(1);
+  if (body.length > 4) return hex;
+  return `#${[...body].map((c) => c + c).join("")}`;
+}
+
+/**
+ * Apply `percent` opacity to a hex colour, returning `#RRGGBBAA` — or a plain
+ * `#RRGGBB` at full opacity, so an opaque colour is never rewritten with a
+ * redundant `ff`. A non-hex colour cannot carry alpha without being rewritten
+ * into another notation, so it is returned untouched rather than invented.
+ *
+ * "Hex" is `isHexColor`'s grammar — 3, 6 or 8 digits. The 4-digit `#RGBA` form
+ * is deliberately outside it (a gradient stop may not smuggle one past the
+ * injection guard), so it is returned untouched here too.
+ */
+function withHexAlpha(hex, percent) {
+  if (!isHexColor(hex)) return hex;
+  const base = expandShortHex(hex).slice(0, 7);
+  const alpha = clampAlphaPercent(percent);
+  if (alpha === ALPHA_OPAQUE) return base;
+  return `${base}${Math.round((alpha * 255) / 100)
+    .toString(16)
+    .padStart(2, "0")}`;
+}
+
+/**
+ * Read a hex colour's opacity back as a percentage. No alpha pair is 100.
+ *
+ * The percentage is lossy in this direction — 255 alpha values map onto 101
+ * percentages — so a near-opaque `fe` reads back as 100. Only a value this
+ * function produced round-trips exactly.
+ */
+function hexAlphaPercent(hex) {
+  if (!isHexColor(hex)) return ALPHA_OPAQUE;
+  const full = expandShortHex(hex);
+  if (full.length !== 9) return ALPHA_OPAQUE;
+  return Math.round((parseInt(full.slice(7), 16) * 100) / 255);
+}
+
 /**
  * The R/G/B bytes, with any alpha pair IGNORED.
  *
@@ -4784,7 +4895,11 @@ export {
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,
+  parseThemeColorTokenRef,
+  formatThemeColorTokenRef,
   THEME_TOKEN_REF_PREFIX,
+  withHexAlpha,
+  hexAlphaPercent,
   formatMoneyIn,
   normaliseCurrencyCode,
   sameWidgetRouteValue,

package/dist/host.d.ts

@@ -434,7 +434,8 @@ export function isThemeTokenRef(value: unknown): boolean;
 /**
  * Resolve one `theme:<path>` binding against a resolved widget theme. Returns
  * `undefined` for a non-binding, a token outside `CONTRACT.themeColorTokens`,
- * or a path that does not resolve to a colour.
+ * or a path that does not resolve to a colour. A binding carrying an opacity
+ * (`theme:<path>/<percent>`, sc-8893) resolves to `#RRGGBBAA`.
  */
 export function resolveThemeTokenRef(
   value: unknown,

package/dist/index.d.ts

@@ -2942,6 +2942,40 @@ export const THEME_TOKEN_REF_PREFIX: string;
  */
 export function isThemeColorTokenRef(value: unknown): boolean;
 
+export interface ThemeColorTokenRef {
+  path: string;
+  /** null for a bare binding, which inherits the token's own opacity. */
+  alpha: number | null;
+}
+
+/**
+ * sc-8893 — parse a binding into its token path and opacity percentage, or null
+ * when the value is not a binding. `theme:<path>` inherits whatever opacity the
+ * token carries; `theme:<path>/<percent>` replaces it with the author's.
+ */
+export function parseThemeColorTokenRef(
+  value: unknown,
+): ThemeColorTokenRef | null;
+
+/**
+ * sc-8893 — spell one binding. A `percent` of null/undefined writes the bare
+ * form, which defers to the token's own opacity.
+ */
+export function formatThemeColorTokenRef(
+  path: string,
+  percent?: unknown,
+): string;
+
+/**
+ * sc-8893 — apply an opacity percentage to a hex colour, returning `#RRGGBBAA`
+ * (or plain `#RRGGBB` at 100). A non-hex colour is returned untouched. Shared
+ * so the Studio's opacity control and the hosts' resolver convert identically.
+ */
+export function withHexAlpha(hex: string, percent: unknown): string;
+
+/** sc-8893 — read a hex colour's opacity back as a percentage (no alpha = 100). */
+export function hexAlphaPercent(hex: string): number;
+
 // Linter
 export interface LintFinding {
   rule: string;

package/dist/index.js

@@ -164,7 +164,11 @@ export {
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,
+  parseThemeColorTokenRef,
+  formatThemeColorTokenRef,
   THEME_TOKEN_REF_PREFIX,
+  withHexAlpha,
+  hexAlphaPercent,
   clampSpacingScale,
   scaleSpacing,
 } from "./contract.js";

package/dist/index.native.js

@@ -157,7 +157,11 @@ export {
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,
+  parseThemeColorTokenRef,
+  formatThemeColorTokenRef,
   THEME_TOKEN_REF_PREFIX,
+  withHexAlpha,
+  hexAlphaPercent,
   clampSpacingScale,
   scaleSpacing,
 } from "./contract.js";

package/dist/linter.cjs

@@ -1337,16 +1337,20 @@ function narrowManifestForFile(manifest, filename) {
 // colour or font pinned in the source outranks BOTH permanently, so neither
 // the workspace theme nor Design -> Widget appearance can ever reach it.
 //
-// Deliberately narrow: colour literals, a `fontFamily` string, and a bare
-// numeric `fontSize`. Raw padding/margin/borderRadius numbers are NOT flagged
-// — measured layout legitimately carries them (a `flexBasis` cell width the
-// designer skill itself teaches), so a spacing rule would be noise that
-// devalues the three unambiguous ones.
+// Deliberately narrow: colour literals, a `fontFamily` string, a bare numeric
+// `fontSize`, and a literal non-zero corner radius. A radius is the app's
+// shape — `theme.radii`, Theme Settings, the SDK components all carry it — so
+// a pinned one is the mismatch between two widgets. Raw padding/margin numbers
+// are NOT flagged: measured layout legitimately carries them (a `flexBasis`
+// cell width the designer skill itself teaches), and a computed radius
+// (`size / 2`, a circle) is geometry, not a look.
 const _DESIGN_HEX_RE =
   /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![0-9a-fA-F])/;
 const _DESIGN_FUNC_COLOR_RE = /\b(?:rgba?|hsla?)\s*\(/;
 const _DESIGN_FONT_FAMILY_RE = /\bfontFamily\s*:\s*["'`]\s*\S/;
 const _DESIGN_FONT_SIZE_RE = /\bfontSize\s*:\s*-?\d/;
+const _DESIGN_RADIUS_RE =
+  /\bborder(?:Top|Bottom|Start|End)?(?:Left|Right|Start|End)?Radius\s*:\s*(?:0*[1-9]\d*(?:\.\d+)?|0\.\d*[1-9]\d*)\s*(?=[,}]|$)/;
 // A line that already reads the theme or the author's style object is
 // resolving a DECLARED fallback, not pinning a look — `style.valueSize ?? 18`
 // is exactly what a styleSchema `default` is for. Colour literals are held to
@@ -1411,6 +1415,8 @@ function _hardcodedDesignRules(source) {
       !_DESIGN_TOKEN_REF_RE.test(line)
     ) {
       what = "a pixel font size";
+    } else if (_DESIGN_RADIUS_RE.test(line)) {
+      what = "a pixel corner radius";
     }
     if (!what) continue;
     findings.push({
@@ -1419,7 +1425,8 @@ function _hardcodedDesignRules(source) {
       label:
         `${what} pinned in the source is beyond the reach of BOTH the ` +
         `workspace theme and the author's Style controls. Read it from ` +
-        `useTheme() (theme.colors.* / theme.typography.*), or declare a ` +
+        `useTheme() (theme.colors.* / theme.typography.* / theme.radii.*), ` +
+        `use the SDK's <Card> / <Button> / <ListRow>, or declare a ` +
         `styleSchema field and apply props.style.<field>. License a value ` +
         `that truly cannot be a token — a series palette, a video ` +
         `letterbox, a QR plate — with a preceding ` +

package/dist/linter.js

@@ -1408,16 +1408,20 @@ export function narrowManifestForFile(manifest, filename) {
 // colour or font pinned in the source outranks BOTH permanently, so neither
 // the workspace theme nor Design -> Widget appearance can ever reach it.
 //
-// Deliberately narrow: colour literals, a `fontFamily` string, and a bare
-// numeric `fontSize`. Raw padding/margin/borderRadius numbers are NOT flagged
-// — measured layout legitimately carries them (a `flexBasis` cell width the
-// designer skill itself teaches), so a spacing rule would be noise that
-// devalues the three unambiguous ones.
+// Deliberately narrow: colour literals, a `fontFamily` string, a bare numeric
+// `fontSize`, and a literal non-zero corner radius. A radius is the app's
+// shape — `theme.radii`, Theme Settings, the SDK components all carry it — so
+// a pinned one is the mismatch between two widgets. Raw padding/margin numbers
+// are NOT flagged: measured layout legitimately carries them (a `flexBasis`
+// cell width the designer skill itself teaches), and a computed radius
+// (`size / 2`, a circle) is geometry, not a look.
 const _DESIGN_HEX_RE =
   /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})(?![0-9a-fA-F])/;
 const _DESIGN_FUNC_COLOR_RE = /\b(?:rgba?|hsla?)\s*\(/;
 const _DESIGN_FONT_FAMILY_RE = /\bfontFamily\s*:\s*["'`]\s*\S/;
 const _DESIGN_FONT_SIZE_RE = /\bfontSize\s*:\s*-?\d/;
+const _DESIGN_RADIUS_RE =
+  /\bborder(?:Top|Bottom|Start|End)?(?:Left|Right|Start|End)?Radius\s*:\s*(?:0*[1-9]\d*(?:\.\d+)?|0\.\d*[1-9]\d*)\s*(?=[,}]|$)/;
 // A line that already reads the theme or the author's style object is
 // resolving a DECLARED fallback, not pinning a look — `style.valueSize ?? 18`
 // is exactly what a styleSchema `default` is for. Colour literals are held to
@@ -1482,6 +1486,8 @@ function _hardcodedDesignRules(source) {
       !_DESIGN_TOKEN_REF_RE.test(line)
     ) {
       what = "a pixel font size";
+    } else if (_DESIGN_RADIUS_RE.test(line)) {
+      what = "a pixel corner radius";
     }
     if (!what) continue;
     findings.push({
@@ -1490,7 +1496,8 @@ function _hardcodedDesignRules(source) {
       label:
         `${what} pinned in the source is beyond the reach of BOTH the ` +
         `workspace theme and the author's Style controls. Read it from ` +
-        `useTheme() (theme.colors.* / theme.typography.*), or declare a ` +
+        `useTheme() (theme.colors.* / theme.typography.* / theme.radii.*), ` +
+        `use the SDK's <Card> / <Button> / <ListRow>, or declare a ` +
         `styleSchema field and apply props.style.<field>. License a value ` +
         `that truly cannot be a token — a series palette, a video ` +
         `letterbox, a QR plate — with a preceding ` +

package/dist/theme-token-refs.js

@@ -18,7 +18,11 @@
 // type today's hex, which went stale silently. A bound field stores the TOKEN,
 // so the intent survives the rebrand.
 
-import { isThemeColorTokenRef, THEME_TOKEN_REF_PREFIX } from "./contract.js";
+import {
+  parseThemeColorTokenRef,
+  withHexAlpha,
+  THEME_TOKEN_REF_PREFIX,
+} from "./contract.js";
 
 // A value is a binding, not a colour, when it carries this prefix. No CSS
 // colour can begin with it, so a stored literal can never be misread as one.
@@ -26,7 +30,15 @@ import { isThemeColorTokenRef, THEME_TOKEN_REF_PREFIX } from "./contract.js";
 // grammar from there, and two spellings of it would drift.
 const PREFIX = THEME_TOKEN_REF_PREFIX;
 
-/** True when `value` is a theme-token binding rather than a literal colour. */
+/**
+ * True when `value` is a theme-token binding rather than a literal colour.
+ *
+ * Deliberately the PREFIX alone, not the contract's full parse: the callers
+ * below use it to decide what to DROP, and a binding naming a withdrawn token
+ * or carrying a malformed opacity must go back to unset — where its
+ * `themeDefault` paints — rather than reach a renderer as the literal string
+ * `theme:...`.
+ */
 export function isThemeTokenRef(value) {
   return typeof value === "string" && value.startsWith(PREFIX);
 }
@@ -43,14 +55,16 @@ export function resolveThemeTokenRef(value, theme) {
   // The allowlist is the contract's, so what the Studio may WRITE and what a
   // host will RESOLVE cannot drift apart. sc-8326 moved the test itself there
   // too, since Mason's plan validator has to ask the same question.
-  if (!isThemeColorTokenRef(value)) return undefined;
-  const path = value.slice(PREFIX.length);
-  const resolved = path
+  const ref = parseThemeColorTokenRef(value);
+  if (!ref) return undefined;
+  const resolved = ref.path
     .split(".")
     .reduce((o, k) => (o == null ? undefined : o[k]), theme);
-  return typeof resolved === "string" && resolved.trim() !== ""
-    ? resolved
-    : undefined;
+  if (typeof resolved !== "string" || resolved.trim() === "") return undefined;
+  // sc-8893: an authored opacity REPLACES the token's. With none authored the
+  // token is handed back verbatim — including a token that is itself
+  // translucent, which reading the bare form as 100 would quietly make solid.
+  return ref.alpha === null ? resolved : withHexAlpha(resolved, ref.alpha);
 }
 
 function isPlainObject(value) {

package/package.json

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