@khanacademy/wonder-blocks-tokens 16.3.0 → 16.4.0

package/.turbo/turbo-build$colon$css.log

@@ -1,5 +1,5 @@
 
-> @khanacademy/wonder-blocks-tokens@16.3.0 build:css /home/runner/work/wonder-blocks/wonder-blocks/packages/wonder-blocks-tokens
+> @khanacademy/wonder-blocks-tokens@16.4.0 build:css /home/runner/work/wonder-blocks/wonder-blocks/packages/wonder-blocks-tokens
 > node -r @swc-node/register ./src/build/generate-css-variables.ts
 
 CSS variables generated successfully in: /home/runner/work/wonder-blocks/wonder-blocks/packages/wonder-blocks-tokens/dist/css

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @khanacademy/wonder-blocks-tokens
 
+## 16.4.0
+
+### Minor Changes
+
+- c1c74df: Soft-deprecate the `spacing` primitive token in favor of `sizing`. Editors
+  will now show deprecation warnings on `spacing`, `VALID_PRIMARY_SPACING`,
+  `VALID_SECONDARY_SPACING`, and `VALID_SPACING`. No runtime or visual changes
+  — each `spacing.<name>` value still maps 1:1 to a `sizing.size_<n>` token. A
+  codemod is available at `wb-codemod/transforms/migrate-spacing-to-sizing.ts`
+  to help migrate consumers; run it with
+  `npx @khanacademy/wb-codemod -t migrate-spacing-to-sizing <paths>`.
+- 72c5272: Add `tokenValue()` helper to resolve the raw value of a semantic token at runtime. Useful for interoperating with third-party libraries that expect raw color values instead of CSS `var(...)` references.
+
 ## 16.3.0
 
 ### Minor Changes

package/dist/es/index.js

@@ -8,6 +8,8 @@ const width={xsMax:567,smMin:568,smMax:681,mdMin:682,mdMax:1023,lgMin:1024};cons
 
 const BASELINE_VALUE=10;function remToPx(value,baseline=BASELINE_VALUE){const num=parseFloat(value);const result=Math.round(num*baseline);return `${result}px`}function pxToRem(value,baseline=BASELINE_VALUE){return `${value/baseline}rem`}
 
+const cssVarRegex=/^\s*var\(\s*(--[^,)\s]+)/;function tokenValue(token,element){const rootElement=element||document.querySelector("[data-wb-theme]")||document.documentElement;const match=token.match(cssVarRegex);if(!match){return token}return getComputedStyle(rootElement).getPropertyValue(match[1]).trim()}
+
 function mapValuesToCssVars(obj,prefix="--wb-"){const cssVars={};for(const key in obj){if(typeof obj[key]==="object"){cssVars[key]=mapValuesToCssVars(obj[key],`${prefix}${key}-`);}else {cssVars[key]=`var(${prefix}${key})`;}}return cssVars}
 
 const CSS_VAR_PREFIX="--wb-";
@@ -30,4 +32,4 @@ var theme = mapValuesToCssVars(themeDefault,CSS_VAR_PREFIX);
 
 const {border,boxShadow,semanticColor,sizing,font}=theme;
 
-export { border, boxShadow, breakpoint, color$1 as color, fade, font, mapValuesToCssVars, mix, pxToRem, remToPx, semanticColor, sizing, spacing };
+export { border, boxShadow, breakpoint, color$1 as color, fade, font, mapValuesToCssVars, mix, pxToRem, remToPx, semanticColor, sizing, spacing, tokenValue };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { color } from "./tokens/color";
 import { spacing } from "./tokens/spacing";
 import { breakpoint } from "./tokens/media-queries";
-import { mix, fade, pxToRem, remToPx } from "./util";
+import { mix, fade, pxToRem, remToPx, tokenValue } from "./util";
 import { mapValuesToCssVars } from "./internal/map-values-to-css-vars";
 declare const border: {
     radius: {
@@ -882,4 +882,9 @@ mix, fade,
 /**
  * Allows converting regular JS tokens to CSS variables.
  */
-mapValuesToCssVars, };
+mapValuesToCssVars, 
+/**
+ * Resolves the raw value of a Wonder Blocks token at runtime by reading
+ * the computed value of its underlying CSS custom property.
+ */
+tokenValue, };

package/dist/index.js

@@ -12,6 +12,8 @@ const width={xsMax:567,smMin:568,smMax:681,mdMin:682,mdMax:1023,lgMin:1024};cons
 
 const BASELINE_VALUE=10;function remToPx(value,baseline=BASELINE_VALUE){const num=parseFloat(value);const result=Math.round(num*baseline);return `${result}px`}function pxToRem(value,baseline=BASELINE_VALUE){return `${value/baseline}rem`}
 
+const cssVarRegex=/^\s*var\(\s*(--[^,)\s]+)/;function tokenValue(token,element){const rootElement=element||document.querySelector("[data-wb-theme]")||document.documentElement;const match=token.match(cssVarRegex);if(!match){return token}return getComputedStyle(rootElement).getPropertyValue(match[1]).trim()}
+
 function mapValuesToCssVars(obj,prefix="--wb-"){const cssVars={};for(const key in obj){if(typeof obj[key]==="object"){cssVars[key]=mapValuesToCssVars(obj[key],`${prefix}${key}-`);}else {cssVars[key]=`var(${prefix}${key})`;}}return cssVars}
 
 const CSS_VAR_PREFIX="--wb-";
@@ -47,3 +49,4 @@ exports.remToPx = remToPx;
 exports.semanticColor = semanticColor;
 exports.sizing = sizing;
 exports.spacing = spacing;
+exports.tokenValue = tokenValue;

package/dist/tokens/spacing.d.ts

@@ -1,6 +1,11 @@
 /**
- * NOTE: These tokens are going to be deprecated in favor of the new `sizing`
- * tokens.
+ * Primitive tokens for dimensional values (margin, padding, gaps, sizes).
+ *
+ * @deprecated Use `sizing` from `@khanacademy/wonder-blocks-tokens` instead.
+ * Each `spacing.<name>` value has an equivalent `sizing.size_<n>` token (e.g.
+ * `spacing.medium_16` → `sizing.size_160`). A codemod is available at
+ * `wb-codemod/transforms/migrate-spacing-to-sizing.ts` to help migrate
+ * consumers.
  */
 export declare const spacing: {
     readonly xxxxSmall_2: 2;
@@ -14,6 +19,24 @@ export declare const spacing: {
     readonly xxLarge_48: 48;
     readonly xxxLarge_64: 64;
 };
+/**
+ * @deprecated The `spacing` token is deprecated; use `sizing` from
+ * `@khanacademy/wonder-blocks-tokens` instead. For APIs that need to constrain
+ * to a numeric set, prefer `number` (or `number | string` to also accept rem
+ * strings from `sizing`).
+ */
 export type VALID_PRIMARY_SPACING = 4 | 8 | 16 | 32 | 64;
+/**
+ * @deprecated The `spacing` token is deprecated; use `sizing` from
+ * `@khanacademy/wonder-blocks-tokens` instead. For APIs that need to constrain
+ * to a numeric set, prefer `number` (or `number | string` to also accept rem
+ * strings from `sizing`).
+ */
 export type VALID_SECONDARY_SPACING = 6 | 12 | 24 | 48;
+/**
+ * @deprecated The `spacing` token is deprecated; use `sizing` from
+ * `@khanacademy/wonder-blocks-tokens` instead. For APIs that need to constrain
+ * to a numeric set, prefer `number` (or `number | string` to also accept rem
+ * strings from `sizing`).
+ */
 export type VALID_SPACING = VALID_PRIMARY_SPACING | VALID_SECONDARY_SPACING;

package/dist/util/index.d.ts

@@ -1,3 +1,4 @@
 import { mix, fade } from "./color-utils";
 import { pxToRem, remToPx } from "./sizing-utils";
-export { mix, fade, pxToRem, remToPx };
+import { tokenValue } from "./token-value";
+export { mix, fade, pxToRem, remToPx, tokenValue };

package/dist/util/token-value.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Resolves the raw value of a Wonder Blocks token at runtime.
+ *
+ * Semantic tokens are exported as `var(--...)` strings so that theming works
+ * through the CSS cascade. This helper reads the computed value of that custom
+ * property, returning the concrete string (e.g. a hex or `rgba()` value) that
+ * third-party libraries expecting raw color values can consume.
+ *
+ * If `token` is not a `var(...)` expression, it is returned unchanged.
+ *
+ * @param token A token string — typically a `var(--...)` reference exported
+ * from this package, but a raw value is accepted and returned as-is.
+ * @param element The element whose computed style should be read. Defaults to
+ * the first `[data-wb-theme]` element in the current document, falling back to
+ * `document.documentElement`. Pass a descendant of a `[data-wb-theme]` element
+ * to resolve the value for that theme scope.
+ * @returns The resolved raw value, trimmed. Returns an empty string when the
+ * custom property is not defined on the given element.
+ *
+ * @example
+ * ```ts
+ * import {semanticColor, tokenValue} from "@khanacademy/wonder-blocks-tokens";
+ *
+ * tokenValue(semanticColor.core.foreground.instructive.default);
+ * // => "#1865f2"
+ * ```
+ */
+export declare function tokenValue(token: string, element?: Element): string;

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core primitive design tokens for Web Wonder Blocks",
   "author": "Khan Academy",
   "license": "MIT",
-  "version": "16.3.0",
+  "version": "16.4.0",
   "publishConfig": {
     "access": "public"
   },