@primer/primitives 11.4.0 → 11.4.1-rc.24c79953

package/dist/build/schemas/stringToken.d.ts

@@ -3,7 +3,7 @@ export declare const stringToken: z.ZodObject<{
     $description: z.ZodOptional<z.ZodString>;
     $deprecated: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
     $value: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
-    $type: z.ZodLiteral<"string" | "number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange">;
+    $type: z.ZodLiteral<"number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange" | "custom-string">;
     $extensions: z.ZodOptional<z.ZodObject<{
         'org.primer.llm': z.ZodOptional<z.ZodObject<{
             usage: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/build/schemas/stringToken.js

@@ -6,7 +6,7 @@ import { llmExtension } from './llmExtension.js';
 export const stringToken = baseToken
     .extend({
     $value: z.union([z.string(), referenceValue]),
-    $type: tokenType('string'),
+    $type: tokenType('custom-string'),
     $extensions: z
         .object({
         'org.primer.llm': llmExtension,

package/dist/build/schemas/tokenType.d.ts

@@ -1,3 +1,3 @@
 import { z } from 'zod';
 import type { TokenType } from './validTokenType.js';
-export declare const tokenType: ($type: TokenType) => z.ZodLiteral<"string" | "number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange">;
+export declare const tokenType: ($type: TokenType) => z.ZodLiteral<"number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange" | "custom-string">;

package/dist/build/schemas/transitionToken.d.ts

@@ -3,11 +3,23 @@ export declare const transitionToken: z.ZodObject<{
     $description: z.ZodOptional<z.ZodString>;
     $deprecated: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
     $value: z.ZodUnion<readonly [z.ZodObject<{
-        duration: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodString]>, z.ZodString]>;
+        duration: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+            value: z.ZodNumber;
+            unit: z.ZodEnum<{
+                s: "s";
+                ms: "ms";
+            }>;
+        }, z.core.$strict>, z.ZodString]>, z.ZodString]>;
         timingFunction: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodArray<z.ZodNumber>, z.ZodString]>, z.ZodString]>;
-        delay: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodString]>, z.ZodString]>>;
+        delay: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+            value: z.ZodNumber;
+            unit: z.ZodEnum<{
+                s: "s";
+                ms: "ms";
+            }>;
+        }, z.core.$strict>, z.ZodString]>, z.ZodString]>>;
     }, z.core.$strip>, z.ZodString]>;
-    $type: z.ZodLiteral<"string" | "number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange">;
+    $type: z.ZodLiteral<"number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange" | "custom-string">;
     $extensions: z.ZodOptional<z.ZodObject<{
         'org.primer.llm': z.ZodOptional<z.ZodObject<{
             usage: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/build/schemas/typographyToken.d.ts

@@ -1,7 +1,14 @@
 import { z } from 'zod';
 export declare const typographyValue: z.ZodObject<{
-    fontSize: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0">, z.ZodLiteral<0>]>, z.ZodString]>;
-    lineHeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0">, z.ZodLiteral<0>]>, z.ZodString]>>;
+    fontSize: z.ZodUnion<readonly [z.ZodObject<{
+        value: z.ZodNumber;
+        unit: z.ZodEnum<{
+            em: "em";
+            px: "px";
+            rem: "rem";
+        }>;
+    }, z.core.$strict>, z.ZodString]>;
+    lineHeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
     fontWeight: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
     fontFamily: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
 }, z.core.$strip>;
@@ -9,12 +16,19 @@ export declare const typographyToken: z.ZodObject<{
     $description: z.ZodOptional<z.ZodString>;
     $deprecated: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
     $value: z.ZodUnion<readonly [z.ZodObject<{
-        fontSize: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0">, z.ZodLiteral<0>]>, z.ZodString]>;
-        lineHeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0">, z.ZodLiteral<0>]>, z.ZodString]>>;
+        fontSize: z.ZodUnion<readonly [z.ZodObject<{
+            value: z.ZodNumber;
+            unit: z.ZodEnum<{
+                em: "em";
+                px: "px";
+                rem: "rem";
+            }>;
+        }, z.core.$strict>, z.ZodString]>;
+        lineHeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
         fontWeight: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
         fontFamily: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
     }, z.core.$strip>, z.ZodString]>;
-    $type: z.ZodLiteral<"string" | "number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange">;
+    $type: z.ZodLiteral<"number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange" | "custom-string">;
     $extensions: z.ZodOptional<z.ZodObject<{
         'org.primer.llm': z.ZodOptional<z.ZodObject<{
             usage: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/build/schemas/typographyToken.js

@@ -7,7 +7,7 @@ import { tokenType } from './tokenType.js';
 import { llmExtension } from './llmExtension.js';
 export const typographyValue = z.object({
     fontSize: z.union([dimensionValue, referenceValue]),
-    lineHeight: z.union([dimensionValue, referenceValue]).optional(),
+    lineHeight: z.union([z.number(), referenceValue]).optional(),
     fontWeight: z.union([fontWeightValue, referenceValue]),
     fontFamily: z.union([z.string().min(1), referenceValue]),
 });

package/dist/build/schemas/validTokenType.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-declare const validTypes: readonly ["color", "cubicBezier", "typography", "dimension", "duration", "border", "shadow", "fontFamily", "fontWeight", "gradient", "number", "string", "transition", "custom-viewportRange"];
+declare const validTypes: readonly ["color", "cubicBezier", "typography", "dimension", "duration", "border", "shadow", "fontFamily", "fontWeight", "gradient", "number", "custom-string", "transition", "custom-viewportRange"];
 export type TokenType = (typeof validTypes)[number];
 /**
  * Recursively validates $type properties in token structure

package/dist/build/schemas/validTokenType.js

@@ -12,7 +12,7 @@ const validTypes = [
     'fontWeight',
     'gradient',
     'number',
-    'string',
+    'custom-string',
     'transition',
     'custom-viewportRange',
 ];

package/dist/build/schemas/viewportRangeToken.d.ts

@@ -3,7 +3,7 @@ export declare const viewportRangeToken: z.ZodObject<{
     $description: z.ZodOptional<z.ZodString>;
     $deprecated: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>>;
     $value: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
-    $type: z.ZodLiteral<"string" | "number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange">;
+    $type: z.ZodLiteral<"number" | "border" | "color" | "fontFamily" | "fontWeight" | "transition" | "dimension" | "duration" | "gradient" | "shadow" | "typography" | "cubicBezier" | "custom-viewportRange" | "custom-string">;
     $extensions: z.ZodOptional<z.ZodObject<{
         'org.primer.llm': z.ZodOptional<z.ZodObject<{
             usage: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/build/transformers/borderToCss.js

@@ -1,4 +1,20 @@
 import { isBorder } from '../filters/isBorder.js';
+import { parseDimension } from './utilities/parseDimension.js';
+/**
+ * @description Converts a W3C dimension object to CSS string, preserving the original unit
+ * @param dim - The dimension value in W3C object format or a string
+ * @returns CSS dimension string (e.g., "2px", "0.125rem", "1em", "0")
+ */
+const dimensionToCss = (dim) => {
+    if (typeof dim === 'string') {
+        return dim;
+    }
+    const { value, unit } = parseDimension(dim);
+    if (value === 0) {
+        return '0';
+    }
+    return `${value}${unit}`;
+};
 /**
  * checks if all required properties exist on shadow token
  * @param object - BorderTokenValue
@@ -33,6 +49,6 @@ export const borderToCss = {
             throw new Error(`Invalid border token property ${JSON.stringify(value)}. Must be an object with color, width and style properties.`);
         }
         /* width | style | color */
-        return `${value.width} ${value.style} ${value.color}`;
+        return `${dimensionToCss(value.width)} ${value.style} ${value.color}`;
     },
 };

package/dist/build/transformers/dimensionToPixelUnitless.d.ts

@@ -1,8 +1,9 @@
 import type { Transform } from 'style-dictionary/types';
 /**
- * @description converts dimension tokens value to pixel value without unit, ignores `em` as they are relative to the font size of the parent element
+ * @description converts dimension tokens value to pixel value without unit
  * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
  * @matcher matches all tokens of $type `dimension`
- * @transformer returns a float number
+ * @transformer returns a number for px/rem values, or a string with unit for em values (cannot convert to unitless)
+ * @note Expects W3C DTCG format { value: number, unit: "px" | "rem" | "em" }
  */
 export declare const dimensionToPixelUnitless: Transform;

package/dist/build/transformers/dimensionToPixelUnitless.js

@@ -1,4 +1,5 @@
 import { isDimension } from '../filters/index.js';
+import { parseDimension } from './utilities/parseDimension.js';
 /**
  * @description base font size from options or 16
  * @param options
@@ -6,22 +7,11 @@ import { isDimension } from '../filters/index.js';
  */
 const getBasePxFontSize = (options) => (options && options.basePxFontSize) || 16;
 /**
- * @description checks if token value has a specific unit
- * @param value token value
- * @param unit unit string like px or value
- * @returns boolean
- */
-const hasUnit = (value, unit) => {
-    if (typeof value === 'number') {
-        return false;
-    }
-    return value.indexOf(unit) > -1;
-};
-/**
- * @description converts dimension tokens value to pixel value without unit, ignores `em` as they are relative to the font size of the parent element
+ * @description converts dimension tokens value to pixel value without unit
  * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
  * @matcher matches all tokens of $type `dimension`
- * @transformer returns a float number
+ * @transformer returns a number for px/rem values, or a string with unit for em values (cannot convert to unitless)
+ * @note Expects W3C DTCG format { value: number, unit: "px" | "rem" | "em" }
  */
 export const dimensionToPixelUnitless = {
     name: 'dimension/pixelUnitless',
@@ -31,19 +21,25 @@ export const dimensionToPixelUnitless = {
     transform: (token, config, options) => {
         const valueProp = options.usesDtcg ? '$value' : 'value';
         const baseFont = getBasePxFontSize(config);
-        const floatVal = parseFloat(token[valueProp]);
-        if (isNaN(floatVal)) {
-            throw new Error(`Invalid dimension token: '${token.path.join('.')}: ${token[valueProp]}' is not valid and cannot be transform to 'float' \n`);
-        }
-        if (floatVal === 0) {
-            return 0;
-        }
-        if (hasUnit(token[valueProp], 'rem')) {
-            return floatVal * baseFont;
+        try {
+            const { value, unit } = parseDimension(token[valueProp]);
+            if (value === 0) {
+                return 0;
+            }
+            // rem values convert to px
+            if (unit === 'rem') {
+                return value * baseFont;
+            }
+            // em values pass through as string (relative to parent, cannot convert to unitless px)
+            if (unit === 'em') {
+                return `${value}em`;
+            }
+            // px values return the number directly
+            return value;
         }
-        if (hasUnit(token[valueProp], 'px')) {
-            return floatVal;
+        catch (error) {
+            const originalMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid dimension token: '${token.path.join('.')}: ${JSON.stringify(token[valueProp])}' - ${originalMessage}\n`);
         }
-        return token[valueProp];
     },
 };

package/dist/build/transformers/dimensionToRem.d.ts

@@ -1,8 +1,9 @@
 import type { Transform } from 'style-dictionary/types';
 /**
- * @description converts dimension tokens value to `rem`, ignores `em` as they are relative to the font size of the parent element
+ * @description converts dimension tokens value to `rem`
  * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
  * @matcher matches all tokens of $type `dimension`
  * @transformer returns a `rem` string
+ * @note Expects W3C DTCG format { value: number, unit: "px" | "rem" | "em" }
  */
 export declare const dimensionToRem: Transform;

package/dist/build/transformers/dimensionToRem.js

@@ -1,4 +1,5 @@
 import { isDimension } from '../filters/index.js';
+import { parseDimension } from './utilities/parseDimension.js';
 /**
  * @description base font size from options or 16
  * @param options
@@ -6,22 +7,11 @@ import { isDimension } from '../filters/index.js';
  */
 const getBasePxFontSize = (options) => (options && options.basePxFontSize) || 16;
 /**
- * @description checks if token value has a specific unit
- * @param value token value
- * @param unit unit string like px or value
- * @returns boolean
- */
-const hasUnit = (value, unit) => {
-    if (typeof value === 'number') {
-        return false;
-    }
-    return value.indexOf(unit) > -1;
-};
-/**
- * @description converts dimension tokens value to `rem`, ignores `em` as they are relative to the font size of the parent element
+ * @description converts dimension tokens value to `rem`
  * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
  * @matcher matches all tokens of $type `dimension`
  * @transformer returns a `rem` string
+ * @note Expects W3C DTCG format { value: number, unit: "px" | "rem" | "em" }
  */
 export const dimensionToRem = {
     name: 'dimension/rem',
@@ -31,16 +21,25 @@ export const dimensionToRem = {
     transform: (token, config, options) => {
         const valueProp = options.usesDtcg ? '$value' : 'value';
         const baseFont = getBasePxFontSize(config);
-        const floatVal = parseFloat(token[valueProp]);
-        if (isNaN(floatVal)) {
-            throw new Error(`Invalid dimension token: '${token.name}: ${token[valueProp]}' is not valid and cannot be transform to 'rem' \n`);
-        }
-        if (floatVal === 0) {
-            return '0';
+        try {
+            const { value, unit } = parseDimension(token[valueProp]);
+            if (value === 0) {
+                return '0';
+            }
+            // rem values pass through unchanged
+            if (unit === 'rem') {
+                return `${value}rem`;
+            }
+            // em values pass through unchanged (relative to parent, cannot convert)
+            if (unit === 'em') {
+                return `${value}em`;
+            }
+            // px values convert to rem
+            return `${value / baseFont}rem`;
         }
-        if (hasUnit(token[valueProp], 'rem') || hasUnit(token[valueProp], 'em')) {
-            return token[valueProp];
+        catch (error) {
+            const details = error instanceof Error && error.message ? ` - ${error.message}` : error ? ` - ${String(error)}` : '';
+            throw new Error(`Invalid dimension token: '${token.name}: ${JSON.stringify(token[valueProp])}' is not valid and cannot be transformed to 'rem'${details}\n`);
         }
-        return `${floatVal / baseFont}rem`;
     },
 };

package/dist/build/transformers/dimensionToRemPxArray.d.ts

@@ -1,8 +1,9 @@
 import type { Transform } from 'style-dictionary/types';
 /**
- * @description converts dimension tokens value to `rem`, ignores `em` as they are relative to the font size of the parent element
+ * @description converts dimension tokens value to an array with both `rem` and `px` values
  * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
  * @matcher matches all tokens of $type `dimension`
  * @transformer returns an array with the `rem` and `pixel` string
+ * @note Expects W3C DTCG format { value: number, unit: "px" | "rem" | "em" }
  */
 export declare const dimensionToRemPxArray: Transform;

package/dist/build/transformers/dimensionToRemPxArray.js

@@ -1,4 +1,5 @@
 import { isDimension } from '../filters/index.js';
+import { parseDimension } from './utilities/parseDimension.js';
 /**
  * @description base font size from options or 16
  * @param options
@@ -6,22 +7,11 @@ import { isDimension } from '../filters/index.js';
  */
 const getBasePxFontSize = (options) => (options && options.basePxFontSize) || 16;
 /**
- * @description checks if token value has a specific unit
- * @param value token value
- * @param unit unit string like px or value
- * @returns boolean
- */
-const hasUnit = (value, unit) => {
-    if (typeof value === 'number') {
-        return false;
-    }
-    return value.indexOf(unit) > -1;
-};
-/**
- * @description converts dimension tokens value to `rem`, ignores `em` as they are relative to the font size of the parent element
+ * @description converts dimension tokens value to an array with both `rem` and `px` values
  * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
  * @matcher matches all tokens of $type `dimension`
  * @transformer returns an array with the `rem` and `pixel` string
+ * @note Expects W3C DTCG format { value: number, unit: "px" | "rem" | "em" }
  */
 export const dimensionToRemPxArray = {
     name: 'dimension/remPxArray',
@@ -31,16 +21,25 @@ export const dimensionToRemPxArray = {
     transform: (token, config, options) => {
         const valueProp = options.usesDtcg ? '$value' : 'value';
         const baseFont = getBasePxFontSize(config);
-        const floatVal = parseFloat(token[valueProp]);
-        if (isNaN(floatVal)) {
-            throw new Error(`Invalid dimension token: '${token.name}: ${token[valueProp]}' is not valid and cannot be transform to 'rem' \n`);
-        }
-        if (floatVal === 0) {
-            return ['0', '0'];
+        try {
+            const { value, unit } = parseDimension(token[valueProp]);
+            if (value === 0) {
+                return ['0', '0'];
+            }
+            // em values pass through unchanged (relative to parent, cannot convert)
+            if (unit === 'em') {
+                return [`${value}em`, `${value}em`];
+            }
+            // rem values pass through, convert to px for second value
+            if (unit === 'rem') {
+                return [`${value}rem`, `${value * baseFont}px`];
+            }
+            // px values convert to rem for first value
+            return [`${value / baseFont}rem`, `${value}px`];
         }
-        if (hasUnit(token[valueProp], 'rem') || hasUnit(token[valueProp], 'em')) {
-            return [token.value, `${floatVal * baseFont}px`];
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Invalid dimension token: '${token.name}: ${JSON.stringify(token[valueProp])}' is not valid and cannot be transformed to 'rem' - ${errorMessage}\n`);
         }
-        return [`${floatVal / baseFont}rem`, `${floatVal}px`];
     },
 };

package/dist/build/transformers/durationToCss.d.ts

@@ -1,8 +1,9 @@
 import type { Transform } from 'style-dictionary/types';
 /**
- * @description converts duration tokens string value to number with `ms` unit
+ * @description converts duration tokens to css duration string
  * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
  * @matcher matches all tokens of $type `duration`
  * @transformer returns a css duration
+ * @note W3C DTCG format: { value: number, unit: "ms" | "s" }
  */
 export declare const durationToCss: Transform;

package/dist/build/transformers/durationToCss.js

@@ -1,9 +1,10 @@
 import { isDuration } from '../filters/index.js';
 /**
- * @description converts duration tokens string value to number with `ms` unit
+ * @description converts duration tokens to css duration string
  * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
  * @matcher matches all tokens of $type `duration`
  * @transformer returns a css duration
+ * @note W3C DTCG format: { value: number, unit: "ms" | "s" }
  */
 export const durationToCss = {
     name: 'duration/css',
@@ -12,18 +13,24 @@ export const durationToCss = {
     filter: isDuration,
     transform: (token, _config, options) => {
         const valueProp = options.usesDtcg ? '$value' : 'value';
-        // throw an error if token value is not a string or does not end with `ms`
-        if (typeof token[valueProp] !== `string` || !(token[valueProp].endsWith(`ms`) || token[valueProp].endsWith(`s`))) {
-            throw new Error(`duration token value must be a string with an "ms" || "s" unit, invalid token: ${token.name} with value: ${token[valueProp]}`);
+        const tokenValue = token[valueProp];
+        // Validate W3C DTCG object format: { value: number, unit: "ms" | "s" }
+        if (typeof tokenValue !== 'object' || tokenValue === null || !('value' in tokenValue) || !('unit' in tokenValue)) {
+            throw new Error(`duration token value must be an object with "value" and "unit" properties (W3C DTCG format). Invalid token: ${token.name} with value: ${JSON.stringify(tokenValue)}`);
         }
-        // get value
-        let value = parseInt(token[valueProp].replace('ms', ''));
-        let unit = `ms`;
-        if (value >= 1000) {
-            value = value / 1000;
-            unit = `s`;
+        const { value, unit } = tokenValue;
+        // Validate unit
+        if (unit !== 'ms' && unit !== 's') {
+            throw new Error(`duration token unit must be "ms" or "s", invalid token: ${token.name} with unit: ${unit}`);
+        }
+        // Validate value is a finite, non-negative number
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+            throw new Error(`duration token value must be a finite, non-negative number, invalid token: ${token.name} with value: ${value}`);
+        }
+        // Convert ms >= 1000 to seconds for cleaner output
+        if (unit === 'ms' && value >= 1000) {
+            return `${value / 1000}s`;
         }
-        // return value
         return `${value}${unit}`;
     },
 };

package/dist/build/transformers/shadowToCss.js

@@ -3,6 +3,17 @@ import { isShadow } from '../filters/index.js';
 import { alpha } from './utilities/alpha.js';
 import { checkRequiredTokenProperties } from './utilities/checkRequiredTokenProperties.js';
 import { getTokenValue } from './utilities/getTokenValue.js';
+/**
+ * @description Converts a W3C dimension object to CSS string
+ * @param dim - The dimension value in W3C object format
+ * @returns CSS dimension string (e.g., "16px", "1rem", "0")
+ */
+const dimensionToCss = (dim) => {
+    if (dim.value === 0) {
+        return '0';
+    }
+    return `${dim.value}${dim.unit}`;
+};
 /**
  * @description converts w3c shadow tokens in css shadow string
  * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
@@ -27,7 +38,7 @@ export const shadowToCss = {
                 return shadow;
             checkRequiredTokenProperties(shadow, ['color', 'offsetX', 'offsetY', 'blur', 'spread']);
             /*css box shadow:  inset? | offset-x | offset-y | blur-radius | spread-radius | color */
-            return `${shadow.inset === true ? 'inset ' : ''}${shadow.offsetX} ${shadow.offsetY} ${shadow.blur} ${shadow.spread} ${toHex(alpha(getTokenValue(Object.assign(Object.assign({}, token), { [valueProp]: shadow }), 'color'), shadow.alpha || 1, token, config))}`;
+            return `${shadow.inset === true ? 'inset ' : ''}${dimensionToCss(shadow.offsetX)} ${dimensionToCss(shadow.offsetY)} ${dimensionToCss(shadow.blur)} ${dimensionToCss(shadow.spread)} ${toHex(alpha(getTokenValue(Object.assign(Object.assign({}, token), { [valueProp]: shadow }), 'color'), shadow.alpha || 1, token, config))}`;
         })
             .join(', ');
     },

package/dist/build/transformers/utilities/parseDimension.d.ts

@@ -0,0 +1,12 @@
+import type { DimensionTokenValue } from '../../types/dimensionTokenValue.js';
+/**
+ * @description Parses and validates a dimension value in W3C DTCG object format
+ * @param input - The dimension value in W3C object format { value: number, unit: "px" | "rem" | "em" }
+ * @returns Validated DimensionTokenValue
+ * @throws Error if the input is not a valid W3C dimension object
+ *
+ * W3C DTCG format: { value: 16, unit: "px" }
+ * @note `em` is not in the W3C spec but is supported for practical use
+ * @link https://www.designtokens.org/tr/drafts/format/#dimension
+ */
+export declare const parseDimension: (input: DimensionTokenValue) => DimensionTokenValue;

package/dist/build/transformers/utilities/parseDimension.js

@@ -0,0 +1,31 @@
+/**
+ * @description Parses and validates a dimension value in W3C DTCG object format
+ * @param input - The dimension value in W3C object format { value: number, unit: "px" | "rem" | "em" }
+ * @returns Validated DimensionTokenValue
+ * @throws Error if the input is not a valid W3C dimension object
+ *
+ * W3C DTCG format: { value: 16, unit: "px" }
+ * @note `em` is not in the W3C spec but is supported for practical use
+ * @link https://www.designtokens.org/tr/drafts/format/#dimension
+ */
+export const parseDimension = (input) => {
+    // Runtime validation for W3C DTCG object format
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (typeof input !== 'object' || input === null) {
+        throw new Error(`Invalid dimension value: ${JSON.stringify(input)} - must be a W3C DTCG dimension object with "value" and "unit" properties`);
+    }
+    const inputObj = input;
+    if (!('value' in inputObj) || !('unit' in inputObj)) {
+        throw new Error(`Invalid dimension value: ${JSON.stringify(input)} - must be a W3C DTCG dimension object with "value" and "unit" properties`);
+    }
+    const { value, unit } = input;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Invalid dimension value: ${JSON.stringify(input)} - value must be a finite number`);
+    }
+    // Runtime check - unit could be invalid at runtime even if types say otherwise
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (unit !== 'px' && unit !== 'rem' && unit !== 'em') {
+        throw new Error(`Invalid dimension unit: ${String(unit)} - must be "px", "rem", or "em"`);
+    }
+    return { value, unit };
+};

package/dist/build/types/borderTokenValue.d.ts

@@ -1,3 +1,5 @@
+import type {DimensionTokenValue} from './dimensionTokenValue.js'
+
 /**
  * Type definition for w3c border composite token value
  * @link https://design-tokens.github.io/community-group/format/#border
@@ -5,6 +7,6 @@
 export type StrokeStyleString = 'solid' | 'dashed' | 'dotted' | 'double' | 'groove' | 'ridge' | 'outset' | 'inset'
 export type BorderTokenValue = {
   color: string
-  width: string
+  width: string | DimensionTokenValue
   style: StrokeStyleString
 }

package/dist/build/types/dimensionTokenValue.d.ts

@@ -0,0 +1,9 @@
+/**
+ * W3C DTCG dimension token value format
+ * @link https://www.designtokens.org/tr/drafts/format/#dimension
+ * @note `em` is not in the W3C spec but is supported for practical use
+ */
+export type DimensionTokenValue = {
+  value: number
+  unit: 'px' | 'rem' | 'em'
+}

package/dist/build/types/shadowTokenValue.d.ts

@@ -1,13 +1,15 @@
+import type {DimensionTokenValue} from './dimensionTokenValue.js'
+
 /**
  * Type definition for w3c shadow composite token value
  * @link https://design-tokens.github.io/community-group/format/#shadow
  */
 export type ShadowTokenValue = {
   color: string
-  offsetX: string
-  offsetY: string
-  blur: string
-  spread: string
+  offsetX: DimensionTokenValue
+  offsetY: DimensionTokenValue
+  blur: DimensionTokenValue
+  spread: DimensionTokenValue
   // custom non w3c values
   inset?: boolean
   alpha?: number