@khanacademy/wonder-blocks-tokens 16.2.0 → 16.4.0

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

@@ -1,5 +1,5 @@
 
-> @khanacademy/wonder-blocks-tokens@16.2.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,24 @@
 # @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
+
+- 40f217b: Add Noto as fallback font for Thunderblocks in tokens.fontFamily
+
 ## 16.2.0
 
 ### Minor Changes

package/dist/build/generate-token-docs.d.ts

@@ -0,0 +1,41 @@
+#!/usr/bin/env -S node -r @swc-node/register
+import themeDefault from "../theme/default";
+type ThemeObject = typeof themeDefault;
+export declare function flattenToMap(obj: unknown, prefix?: string, map?: Map<string, string | number>): Map<string, string | number>;
+export declare function toCssVar(tokenGroup: string, dotPath: string): string;
+type Group = {
+    /** Slug used for the output filename. */
+    id: string;
+    /** Storybook title path. */
+    title: string;
+    /** H1 rendered in the MDX page. */
+    heading: string;
+    /** Variable name used in code examples (e.g. `sizing`). */
+    tokenPrefix: string;
+    /** Short blurb shown above the table, rendered as markdown. */
+    description: string;
+    /** Whether to emit a CSS Variable column. */
+    includeCssVar: boolean;
+} & ({
+    /**
+     * Returns the token subtree for a given theme. One value column is
+     * emitted per theme.
+     */
+    getTokens: (theme: ThemeObject) => unknown;
+} | {
+    /**
+     * For tokens that aren't themed (e.g. media query breakpoints). A
+     * single Value column is emitted.
+     */
+    tokens: unknown;
+});
+export declare const groups: ReadonlyArray<Group>;
+export declare function renderThemedTable(group: Group & {
+    getTokens: (theme: ThemeObject) => unknown;
+}): string;
+export declare function renderSimpleTable(group: Group & {
+    tokens: unknown;
+}): string;
+export declare function renderMdx(group: Group): string;
+export declare function generateTokenDocs(outputDir: string): void;
+export {};

package/dist/css/index.css

@@ -856,7 +856,7 @@
 --wb-boxShadow-low: 0 2px 2px 0 color-mix(in srgb, #252368 20%, transparent);
 --wb-boxShadow-mid: 0 4px 8px 0 color-mix(in srgb, #252368 20%, transparent);
 --wb-boxShadow-high: 0 8px 16px 0 color-mix(in srgb, #252368 20%, transparent);
---wb-font-family-sans: Plus Jakarta Sans, serif;
+--wb-font-family-sans: Plus Jakarta Sans, "Noto Sans", sans-serif;
 --wb-font-family-serif: "Noto Serif", serif;
 --wb-font-family-mono: Inconsolata, monospace;
 --wb-font-size-xxxLarge: 3.6rem;

package/dist/css/vars.css

@@ -490,7 +490,7 @@
 --wb-boxShadow-low: 0 2px 2px 0 color-mix(in srgb, #252368 20%, transparent);
 --wb-boxShadow-mid: 0 4px 8px 0 color-mix(in srgb, #252368 20%, transparent);
 --wb-boxShadow-high: 0 8px 16px 0 color-mix(in srgb, #252368 20%, transparent);
---wb-font-family-sans: Plus Jakarta Sans, serif;
+--wb-font-family-sans: Plus Jakarta Sans, "Noto Sans", sans-serif;
 --wb-font-family-serif: "Noto Serif", serif;
 --wb-font-family-mono: Inconsolata, monospace;
 --wb-font-size-xxxLarge: 3.6rem;

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.2.0",
+  "version": "16.4.0",
   "publishConfig": {
     "access": "public"
   },
@@ -35,6 +35,7 @@
   "bin": "./bin/cli.js",
   "scripts": {
     "build:css": "node -r @swc-node/register ./src/build/generate-css-variables.ts",
+    "build:token-docs": "node -r @swc-node/register ./src/build/generate-token-docs.ts",
     "test": "echo \"Error: no test specified\" && exit 1"
   }
 }