@primer/primitives 11.4.0 → 11.4.1-rc.4e2d1de5

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

@@ -3,9 +3,21 @@ 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">;
     $extensions: z.ZodOptional<z.ZodObject<{

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

@@ -1,7 +1,21 @@
 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.ZodUnion<readonly [z.ZodObject<{
+        value: z.ZodNumber;
+        unit: z.ZodEnum<{
+            em: "em";
+            px: "px";
+            rem: "rem";
+        }>;
+    }, z.core.$strict>, z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0">, z.ZodLiteral<0>]>]>, z.ZodString]>;
+    lineHeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+        value: z.ZodNumber;
+        unit: z.ZodEnum<{
+            em: "em";
+            px: "px";
+            rem: "rem";
+        }>;
+    }, z.core.$strict>, z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0">, z.ZodLiteral<0>]>]>, z.ZodString]>>;
     fontWeight: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
     fontFamily: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
 }, z.core.$strip>;
@@ -9,8 +23,22 @@ 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.ZodUnion<readonly [z.ZodObject<{
+            value: z.ZodNumber;
+            unit: z.ZodEnum<{
+                em: "em";
+                px: "px";
+                rem: "rem";
+            }>;
+        }, z.core.$strict>, z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0">, z.ZodLiteral<0>]>]>, z.ZodString]>;
+        lineHeight: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodObject<{
+            value: z.ZodNumber;
+            unit: z.ZodEnum<{
+                em: "em";
+                px: "px";
+                rem: "rem";
+            }>;
+        }, z.core.$strict>, z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<"0">, z.ZodLiteral<0>]>]>, z.ZodString]>>;
         fontWeight: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
         fontFamily: z.ZodUnion<readonly [z.ZodString, z.ZodString]>;
     }, z.core.$strip>, z.ZodString]>;

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/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/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/css/functional/themes/dark-colorblind-high-contrast.css

@@ -1,3 +1,7 @@
+/**
+ * @spec See /DESIGN_TOKENS_SPEC.md for naming logic and semantic pairings.
+ * @rule Never use raw values (hex/px). Use semantic tokens ONLY.
+ */
 [data-color-mode="dark"][data-dark-theme="dark_colorblind_high_contrast"],
 [data-color-mode="auto"][data-light-theme="dark_colorblind_high_contrast"] {
   --button-primary-bgColor-active: #3685f3;
@@ -792,11 +796,11 @@
   --reactionButton-selected-fgColor-rest: var(--fgColor-link);
   --selectMenu-borderColor: var(--borderColor-default);
   --selection-bgColor: #194fb1b3; /** Background color for text selection highlights */
-  --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
-  --shadow-inset: inset 0px 1px 0px 0px #0104093d;
-  --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;
-  --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999;
-  --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc;
+  --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Legacy floating shadow for backward compatibility */
+  --shadow-inset: inset 0px 1px 0px 0px #0104093d; /** Inset shadow for recessed elements */
+  --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+  --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999; /** Small resting shadow for buttons and interactive elements */
+  --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc; /** Extra small resting shadow for minimal elevation */
   --topicTag-borderColor: var(--borderColor-accent-emphasis);
   --treeViewItem-leadingVisual-iconColor-rest: var(--fgColor-muted);
   --underlineNav-iconColor-rest: var(--fgColor-muted);
@@ -872,9 +876,9 @@
   --page-header-bgColor: var(--bgColor-default);
   --progressBar-track-bgColor: var(--bgColor-inverse);
   --shadow-floating-large: 0px 0px 0px 1px #b7bdc8, 0px 24px 48px 0px #010409; /** Large floating shadow for modals and dialogs */
-  --shadow-floating-medium: 0px 0px 0px 1px #b7bdc8, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966;
+  --shadow-floating-medium: 0px 0px 0px 1px #b7bdc8, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
   --shadow-floating-small: 0px 0px 0px 1px #b7bdc8, 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
-  --shadow-floating-xlarge: 0px 0px 0px 1px #b7bdc8, 0px 32px 64px 0px #010409;
+  --shadow-floating-xlarge: 0px 0px 0px 1px #b7bdc8, 0px 32px 64px 0px #010409; /** Extra large floating shadow for full-screen overlays and sheets */
   --tooltip-bgColor: var(--bgColor-inverse);
   --tooltip-fgColor: var(--fgColor-onInverse);
   --border-neutral-emphasis: 0.0625rem solid #b7bdc8;
@@ -1689,11 +1693,11 @@
     --reactionButton-selected-fgColor-rest: var(--fgColor-link);
     --selectMenu-borderColor: var(--borderColor-default);
     --selection-bgColor: #194fb1b3; /** Background color for text selection highlights */
-    --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
-    --shadow-inset: inset 0px 1px 0px 0px #0104093d;
-    --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;
-    --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999;
-    --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc;
+    --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Legacy floating shadow for backward compatibility */
+    --shadow-inset: inset 0px 1px 0px 0px #0104093d; /** Inset shadow for recessed elements */
+    --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+    --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999; /** Small resting shadow for buttons and interactive elements */
+    --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc; /** Extra small resting shadow for minimal elevation */
     --topicTag-borderColor: var(--borderColor-accent-emphasis);
     --treeViewItem-leadingVisual-iconColor-rest: var(--fgColor-muted);
     --underlineNav-iconColor-rest: var(--fgColor-muted);
@@ -1769,9 +1773,9 @@
     --page-header-bgColor: var(--bgColor-default);
     --progressBar-track-bgColor: var(--bgColor-inverse);
     --shadow-floating-large: 0px 0px 0px 1px #b7bdc8, 0px 24px 48px 0px #010409; /** Large floating shadow for modals and dialogs */
-    --shadow-floating-medium: 0px 0px 0px 1px #b7bdc8, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966;
+    --shadow-floating-medium: 0px 0px 0px 1px #b7bdc8, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
     --shadow-floating-small: 0px 0px 0px 1px #b7bdc8, 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
-    --shadow-floating-xlarge: 0px 0px 0px 1px #b7bdc8, 0px 32px 64px 0px #010409;
+    --shadow-floating-xlarge: 0px 0px 0px 1px #b7bdc8, 0px 32px 64px 0px #010409; /** Extra large floating shadow for full-screen overlays and sheets */
     --tooltip-bgColor: var(--bgColor-inverse);
     --tooltip-fgColor: var(--fgColor-onInverse);
     --border-neutral-emphasis: 0.0625rem solid #b7bdc8;

package/dist/css/functional/themes/dark-colorblind.css

@@ -1,3 +1,7 @@
+/**
+ * @spec See /DESIGN_TOKENS_SPEC.md for naming logic and semantic pairings.
+ * @rule Never use raw values (hex/px). Use semantic tokens ONLY.
+ */
 [data-color-mode="dark"][data-dark-theme="dark_colorblind"],
 [data-color-mode="auto"][data-light-theme="dark_colorblind"] {
   --button-primary-bgColor-active: #3685f3;
@@ -815,11 +819,11 @@
   --reactionButton-selected-fgColor-rest: var(--fgColor-link);
   --selectMenu-borderColor: var(--borderColor-default);
   --selection-bgColor: #1f6febb3; /** Background color for text selection highlights */
-  --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
-  --shadow-inset: inset 0px 1px 0px 0px #0104093d;
-  --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;
-  --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999;
-  --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc;
+  --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Legacy floating shadow for backward compatibility */
+  --shadow-inset: inset 0px 1px 0px 0px #0104093d; /** Inset shadow for recessed elements */
+  --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+  --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999; /** Small resting shadow for buttons and interactive elements */
+  --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc; /** Extra small resting shadow for minimal elevation */
   --tooltip-bgColor: var(--bgColor-emphasis);
   --treeViewItem-leadingVisual-iconColor-rest: var(--fgColor-muted);
   --underlineNav-iconColor-rest: var(--fgColor-muted);
@@ -887,9 +891,9 @@
   --buttonKeybindingHint-danger-borderColor-rest: var(--buttonKeybindingHint-default-borderColor-rest);
   --buttonKeybindingHint-danger-fgColor-disabled: var(--buttonKeybindingHint-default-fgColor-disabled);
   --shadow-floating-large: 0px 0px 0px 1px #3d444d, 0px 24px 48px 0px #010409; /** Large floating shadow for modals and dialogs */
-  --shadow-floating-medium: 0px 0px 0px 1px #3d444d, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966;
+  --shadow-floating-medium: 0px 0px 0px 1px #3d444d, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
   --shadow-floating-small: 0px 0px 0px 1px #3d444d, 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
-  --shadow-floating-xlarge: 0px 0px 0px 1px #3d444d, 0px 32px 64px 0px #010409;
+  --shadow-floating-xlarge: 0px 0px 0px 1px #3d444d, 0px 32px 64px 0px #010409; /** Extra large floating shadow for full-screen overlays and sheets */
   --underlineNav-borderColor-hover: var(--borderColor-neutral-muted);
   --button-danger-borderColor-active: var(--button-danger-borderColor-hover);
   --button-outline-borderColor-hover: var(--button-default-borderColor-hover);
@@ -1712,11 +1716,11 @@
     --reactionButton-selected-fgColor-rest: var(--fgColor-link);
     --selectMenu-borderColor: var(--borderColor-default);
     --selection-bgColor: #1f6febb3; /** Background color for text selection highlights */
-    --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
-    --shadow-inset: inset 0px 1px 0px 0px #0104093d;
-    --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc;
-    --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999;
-    --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc;
+    --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Legacy floating shadow for backward compatibility */
+    --shadow-inset: inset 0px 1px 0px 0px #0104093d; /** Inset shadow for recessed elements */
+    --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+    --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999; /** Small resting shadow for buttons and interactive elements */
+    --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc; /** Extra small resting shadow for minimal elevation */
     --tooltip-bgColor: var(--bgColor-emphasis);
     --treeViewItem-leadingVisual-iconColor-rest: var(--fgColor-muted);
     --underlineNav-iconColor-rest: var(--fgColor-muted);
@@ -1784,9 +1788,9 @@
     --buttonKeybindingHint-danger-borderColor-rest: var(--buttonKeybindingHint-default-borderColor-rest);
     --buttonKeybindingHint-danger-fgColor-disabled: var(--buttonKeybindingHint-default-fgColor-disabled);
     --shadow-floating-large: 0px 0px 0px 1px #3d444d, 0px 24px 48px 0px #010409; /** Large floating shadow for modals and dialogs */
-    --shadow-floating-medium: 0px 0px 0px 1px #3d444d, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966;
+    --shadow-floating-medium: 0px 0px 0px 1px #3d444d, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
     --shadow-floating-small: 0px 0px 0px 1px #3d444d, 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
-    --shadow-floating-xlarge: 0px 0px 0px 1px #3d444d, 0px 32px 64px 0px #010409;
+    --shadow-floating-xlarge: 0px 0px 0px 1px #3d444d, 0px 32px 64px 0px #010409; /** Extra large floating shadow for full-screen overlays and sheets */
     --underlineNav-borderColor-hover: var(--borderColor-neutral-muted);
     --button-danger-borderColor-active: var(--button-danger-borderColor-hover);
     --button-outline-borderColor-hover: var(--button-default-borderColor-hover);