@primer/primitives 11.4.0 → 11.4.1-rc.14fb4bb1

package/dist/build/transformers/shadowToCss.js

@@ -3,6 +3,18 @@ import { isShadow } from '../filters/index.js';
 import { alpha } from './utilities/alpha.js';
 import { checkRequiredTokenProperties } from './utilities/checkRequiredTokenProperties.js';
 import { getTokenValue } from './utilities/getTokenValue.js';
+import { normalizeColorValue } from './utilities/normalizeColorValue.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 +39,9 @@ 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))}`;
+            const colorString = normalizeColorValue(getTokenValue(Object.assign(Object.assign({}, token), { [valueProp]: shadow }), 'color'));
+            const colorHex = shadow.alpha !== undefined ? toHex(alpha(colorString, shadow.alpha, token, config)) : toHex(colorString);
+            return `${shadow.inset === true ? 'inset ' : ''}${dimensionToCss(shadow.offsetX)} ${dimensionToCss(shadow.offsetY)} ${dimensionToCss(shadow.blur)} ${dimensionToCss(shadow.spread)} ${colorHex}`;
         })
             .join(', ');
     },

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

@@ -0,0 +1,23 @@
+import Color from 'colorjs.io';
+import type { ColorW3cValue } from '../../schemas/colorW3cValue.js';
+export type ColorValue = string | ColorW3cValue;
+/**
+ * Type guard to check if value is a valid W3C color object.
+ * Validates structure: colorSpace is a string, components is a 3-element array
+ * of numbers or 'none' keywords.
+ */
+export declare function isW3cColorValue(value: unknown): value is ColorW3cValue;
+/**
+ * Converts a W3C DTCG color object to a colorjs.io Color instance.
+ * The 'none' keyword is replaced with 0 per CSS Color 4 rules for color computation.
+ */
+export declare function w3cToColor(value: ColorW3cValue): Color;
+/**
+ * Normalizes a color value for use in transformers.
+ * String values (hex, rgb, rgba, references) are returned as-is.
+ * W3C DTCG color objects are converted to hex via colorjs.io,
+ * correctly handling all color spaces (sRGB, display-p3, lab, etc.).
+ * @param value - color string or W3C color object
+ * @returns color string usable by downstream transformers
+ */
+export declare function normalizeColorValue(value: ColorValue): string;

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

@@ -0,0 +1,74 @@
+import Color from 'colorjs.io';
+/**
+ * Type guard to check if value is a valid W3C color object.
+ * Validates structure: colorSpace is a string, components is a 3-element array
+ * of numbers or 'none' keywords.
+ */
+export function isW3cColorValue(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    if (!('colorSpace' in value) || typeof value.colorSpace !== 'string')
+        return false;
+    if (!('components' in value))
+        return false;
+    const components = value.components;
+    if (!Array.isArray(components) || components.length !== 3)
+        return false;
+    return components.every(c => typeof c === 'number' || c === 'none');
+}
+/**
+ * Maps W3C DTCG color space names to colorjs.io space identifiers
+ */
+const getColorSpace = (colorSpace) => {
+    switch (colorSpace) {
+        case 'display-p3':
+            return 'p3';
+        case 'a98-rgb':
+            return 'a98rgb';
+        case 'prophoto-rgb':
+            return 'prophoto';
+        default:
+            return colorSpace;
+    }
+};
+/**
+ * Converts a W3C DTCG color object to a colorjs.io Color instance.
+ * The 'none' keyword is replaced with 0 per CSS Color 4 rules for color computation.
+ */
+export function w3cToColor(value) {
+    var _a;
+    const coords = value.components.map(c => (c === 'none' ? 0 : c));
+    return new Color({
+        space: getColorSpace(value.colorSpace),
+        coords,
+        alpha: (_a = value.alpha) !== null && _a !== void 0 ? _a : 1,
+    });
+}
+/**
+ * Normalizes a color value for use in transformers.
+ * String values (hex, rgb, rgba, references) are returned as-is.
+ * W3C DTCG color objects are converted to hex via colorjs.io,
+ * correctly handling all color spaces (sRGB, display-p3, lab, etc.).
+ * @param value - color string or W3C color object
+ * @returns color string usable by downstream transformers
+ */
+export function normalizeColorValue(value) {
+    // String value (hex, rgb, rgba, reference, etc.) - return as-is
+    if (typeof value === 'string') {
+        return value;
+    }
+    // W3C object with hex property and sRGB color space - use hex directly
+    if (value.hex && value.colorSpace === 'srgb' && (value.alpha === undefined || value.alpha === 1)) {
+        return value.hex;
+    }
+    // Convert via colorjs.io for correct color space handling
+    const color = w3cToColor(value);
+    const rgb = color.toGamut('srgb').to('srgb');
+    const [r, g, b] = rgb.coords.map(x => Math.round(Math.max(0, Math.min(1, x !== null && x !== void 0 ? x : 0)) * 255));
+    const hex = `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
+    if (rgb.alpha < 1) {
+        const a = Math.round(rgb.alpha * 255);
+        return hex + a.toString(16).padStart(2, '0');
+    }
+    return hex;
+}

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,10 +1,13 @@
+import type {DimensionTokenValue} from './dimensionTokenValue.js'
+import type {ColorW3cValue} from '../schemas/colorW3cValue.js'
+
 /**
  * Type definition for w3c border composite token value
  * @link https://design-tokens.github.io/community-group/format/#border
  */
 export type StrokeStyleString = 'solid' | 'dashed' | 'dotted' | 'double' | 'groove' | 'ridge' | 'outset' | 'inset'
 export type BorderTokenValue = {
-  color: string
-  width: string
+  color: string | ColorW3cValue
+  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,16 @@
+import type {DimensionTokenValue} from './dimensionTokenValue.js'
+import type {ColorW3cValue} from '../schemas/colorW3cValue.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
+  color: string | ColorW3cValue
+  offsetX: DimensionTokenValue
+  offsetY: DimensionTokenValue
+  blur: DimensionTokenValue
+  spread: DimensionTokenValue
   // custom non w3c values
   inset?: boolean
   alpha?: number

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;
@@ -11,7 +15,7 @@
   --fgColor-done: #d3abff; /** Text color for completed/done state indicators */
   --fgColor-sponsors: #ff90c8; /** Text color for GitHub Sponsors content */
   --reactionButton-selected-bgColor-hover: #3a8cfd5c;
-  --avatar-shadow: 0px 0px 0px 2px #0d1117;
+  --avatar-shadow: 0 0 0 2px #0d1117;
   --avatarStack-fade-bgColor-default: #3d444d;
   --avatarStack-fade-bgColor-muted: #2a313c;
   --bgColor-accent-emphasis: #194fb1; /** Strong accent background for active states and focused states */
@@ -59,8 +63,8 @@
   --button-danger-bgColor-hover: #8f3c00;
   --button-danger-borderColor-hover: #ffb757;
   --button-danger-fgColor-rest: #ffb757;
-  --button-danger-shadow-selected: 0px 0px 0px 0px #000000;
-  --button-default-shadow-resting: 0px 0px 0px 0px #000000;
+  --button-danger-shadow-selected: 0 0 0 0 #00000000;
+  --button-default-shadow-resting: 0 0 0 0 #00000000;
   --button-inactive-bgColor: #262c36;
   --button-inactive-fgColor: #b7bdc8;
   --button-invisible-bgColor-active: #212830;
@@ -74,10 +78,10 @@
   --button-outline-fgColor-disabled: #74b9ff80;
   --button-outline-fgColor-hover: #71b7ff;
   --button-outline-fgColor-rest: #5cacff;
-  --button-outline-shadow-selected: 0px 0px 0px 0px #000000;
+  --button-outline-shadow-selected: 0 0 0 0 #00000000;
   --button-primary-bgColor-disabled: #318bf8;
   --button-primary-borderColor-rest: #91cbff;
-  --button-primary-shadow-selected: 0px 0px 0px 0px #000000;
+  --button-primary-shadow-selected: 0 0 0 0 #00000000;
   --button-star-iconColor: #f7c843;
   --buttonCounter-default-bgColor-rest: #2f3742;
   --buttonCounter-outline-bgColor-hover: #194fb133;
@@ -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: 0 6px 12px -3px #01040966, 0 6px 18px 0 #01040966; /** Legacy floating shadow for backward compatibility */
+  --shadow-inset: inset 0 1px 0 0 #0104093d; /** Inset shadow for recessed elements */
+  --shadow-resting-medium: 0 1px 1px 0 #01040966, 0 3px 6px 0 #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+  --shadow-resting-small: 0 1px 1px 0 #01040999, 0 1px 3px 0 #01040999; /** Small resting shadow for buttons and interactive elements */
+  --shadow-resting-xsmall: 0 1px 1px 0 #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);
@@ -871,10 +875,10 @@
   --focus-outline: 2px solid #409eff; /** Focus ring outline for keyboard navigation and accessibility. */
   --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-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-large: 0 0 0 1px #b7bdc8, 0 24px 48px 0 #010409; /** Large floating shadow for modals and dialogs */
+  --shadow-floating-medium: 0 0 0 1px #b7bdc8, 0 8px 16px -4px #01040966, 0 4px 32px -4px #01040966, 0 24px 48px -12px #01040966, 0 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
+  --shadow-floating-small: 0 0 0 1px #b7bdc8, 0 6px 12px -3px #01040966, 0 6px 18px 0 #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
+  --shadow-floating-xlarge: 0 0 0 1px #b7bdc8, 0 32px 64px 0 #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;
@@ -908,7 +912,7 @@
     --fgColor-done: #d3abff; /** Text color for completed/done state indicators */
     --fgColor-sponsors: #ff90c8; /** Text color for GitHub Sponsors content */
     --reactionButton-selected-bgColor-hover: #3a8cfd5c;
-    --avatar-shadow: 0px 0px 0px 2px #0d1117;
+    --avatar-shadow: 0 0 0 2px #0d1117;
     --avatarStack-fade-bgColor-default: #3d444d;
     --avatarStack-fade-bgColor-muted: #2a313c;
     --bgColor-accent-emphasis: #194fb1; /** Strong accent background for active states and focused states */
@@ -956,8 +960,8 @@
     --button-danger-bgColor-hover: #8f3c00;
     --button-danger-borderColor-hover: #ffb757;
     --button-danger-fgColor-rest: #ffb757;
-    --button-danger-shadow-selected: 0px 0px 0px 0px #000000;
-    --button-default-shadow-resting: 0px 0px 0px 0px #000000;
+    --button-danger-shadow-selected: 0 0 0 0 #00000000;
+    --button-default-shadow-resting: 0 0 0 0 #00000000;
     --button-inactive-bgColor: #262c36;
     --button-inactive-fgColor: #b7bdc8;
     --button-invisible-bgColor-active: #212830;
@@ -971,10 +975,10 @@
     --button-outline-fgColor-disabled: #74b9ff80;
     --button-outline-fgColor-hover: #71b7ff;
     --button-outline-fgColor-rest: #5cacff;
-    --button-outline-shadow-selected: 0px 0px 0px 0px #000000;
+    --button-outline-shadow-selected: 0 0 0 0 #00000000;
     --button-primary-bgColor-disabled: #318bf8;
     --button-primary-borderColor-rest: #91cbff;
-    --button-primary-shadow-selected: 0px 0px 0px 0px #000000;
+    --button-primary-shadow-selected: 0 0 0 0 #00000000;
     --button-star-iconColor: #f7c843;
     --buttonCounter-default-bgColor-rest: #2f3742;
     --buttonCounter-outline-bgColor-hover: #194fb133;
@@ -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: 0 6px 12px -3px #01040966, 0 6px 18px 0 #01040966; /** Legacy floating shadow for backward compatibility */
+    --shadow-inset: inset 0 1px 0 0 #0104093d; /** Inset shadow for recessed elements */
+    --shadow-resting-medium: 0 1px 1px 0 #01040966, 0 3px 6px 0 #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+    --shadow-resting-small: 0 1px 1px 0 #01040999, 0 1px 3px 0 #01040999; /** Small resting shadow for buttons and interactive elements */
+    --shadow-resting-xsmall: 0 1px 1px 0 #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);
@@ -1768,10 +1772,10 @@
     --focus-outline: 2px solid #409eff; /** Focus ring outline for keyboard navigation and accessibility. */
     --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-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-large: 0 0 0 1px #b7bdc8, 0 24px 48px 0 #010409; /** Large floating shadow for modals and dialogs */
+    --shadow-floating-medium: 0 0 0 1px #b7bdc8, 0 8px 16px -4px #01040966, 0 4px 32px -4px #01040966, 0 24px 48px -12px #01040966, 0 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
+    --shadow-floating-small: 0 0 0 1px #b7bdc8, 0 6px 12px -3px #01040966, 0 6px 18px 0 #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
+    --shadow-floating-xlarge: 0 0 0 1px #b7bdc8, 0 32px 64px 0 #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;
@@ -9,7 +13,7 @@
   --control-checked-bgColor-hover: #2a7aef;
   --fgColor-accent: #4493f8; /** Accent text for links and interactive elements */
   --reactionButton-selected-bgColor-hover: #3a8cfd5c;
-  --avatar-shadow: 0px 0px 0px 2px #0d1117;
+  --avatar-shadow: 0 0 0 2px #0d1117;
   --avatarStack-fade-bgColor-default: #3d444d;
   --avatarStack-fade-bgColor-muted: #2a313c;
   --bgColor-accent-emphasis: #1f6feb; /** Strong accent background for active states and focused states */
@@ -56,8 +60,8 @@
   --borderColor-success-muted: #388bfd66; /** Subtle success border for positive feedback elements */
   --borderColor-transparent: #00000000; /** Fully transparent border */
   --button-danger-bgColor-hover: #9b4215;
-  --button-danger-shadow-selected: 0px 0px 0px 0px #000000;
-  --button-default-shadow-resting: 0px 0px 0px 0px #000000;
+  --button-danger-shadow-selected: 0 0 0 0 #00000000;
+  --button-default-shadow-resting: 0 0 0 0 #00000000;
   --button-inactive-bgColor: #262c36;
   --button-inactive-fgColor: #9198a1;
   --button-invisible-bgColor-disabled: #00000000;
@@ -67,9 +71,9 @@
   --button-outline-fgColor-disabled: #4493f880;
   --button-outline-fgColor-hover: #58a6ff;
   --button-outline-fgColor-rest: #388bfd;
-  --button-outline-shadow-selected: 0px 0px 0px 0px #000000;
+  --button-outline-shadow-selected: 0 0 0 0 #00000000;
   --button-primary-bgColor-disabled: #1158c7;
-  --button-primary-shadow-selected: 0px 0px 0px 0px #000000;
+  --button-primary-shadow-selected: 0 0 0 0 #00000000;
   --button-star-iconColor: #e3b341;
   --buttonCounter-danger-bgColor-rest: #49020233;
   --buttonCounter-default-bgColor-rest: #2f3742;
@@ -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: 0 6px 12px -3px #01040966, 0 6px 18px 0 #01040966; /** Legacy floating shadow for backward compatibility */
+  --shadow-inset: inset 0 1px 0 0 #0104093d; /** Inset shadow for recessed elements */
+  --shadow-resting-medium: 0 1px 1px 0 #01040966, 0 3px 6px 0 #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+  --shadow-resting-small: 0 1px 1px 0 #01040999, 0 1px 3px 0 #01040999; /** Small resting shadow for buttons and interactive elements */
+  --shadow-resting-xsmall: 0 1px 1px 0 #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);
@@ -886,10 +890,10 @@
   --buttonKeybindingHint-danger-borderColor-disabled: var(--buttonKeybindingHint-default-borderColor-disabled);
   --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-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-large: 0 0 0 1px #3d444d, 0 24px 48px 0 #010409; /** Large floating shadow for modals and dialogs */
+  --shadow-floating-medium: 0 0 0 1px #3d444d, 0 8px 16px -4px #01040966, 0 4px 32px -4px #01040966, 0 24px 48px -12px #01040966, 0 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
+  --shadow-floating-small: 0 0 0 1px #3d444d, 0 6px 12px -3px #01040966, 0 6px 18px 0 #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
+  --shadow-floating-xlarge: 0 0 0 1px #3d444d, 0 32px 64px 0 #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);
@@ -906,7 +910,7 @@
     --control-checked-bgColor-hover: #2a7aef;
     --fgColor-accent: #4493f8; /** Accent text for links and interactive elements */
     --reactionButton-selected-bgColor-hover: #3a8cfd5c;
-    --avatar-shadow: 0px 0px 0px 2px #0d1117;
+    --avatar-shadow: 0 0 0 2px #0d1117;
     --avatarStack-fade-bgColor-default: #3d444d;
     --avatarStack-fade-bgColor-muted: #2a313c;
     --bgColor-accent-emphasis: #1f6feb; /** Strong accent background for active states and focused states */
@@ -953,8 +957,8 @@
     --borderColor-success-muted: #388bfd66; /** Subtle success border for positive feedback elements */
     --borderColor-transparent: #00000000; /** Fully transparent border */
     --button-danger-bgColor-hover: #9b4215;
-    --button-danger-shadow-selected: 0px 0px 0px 0px #000000;
-    --button-default-shadow-resting: 0px 0px 0px 0px #000000;
+    --button-danger-shadow-selected: 0 0 0 0 #00000000;
+    --button-default-shadow-resting: 0 0 0 0 #00000000;
     --button-inactive-bgColor: #262c36;
     --button-inactive-fgColor: #9198a1;
     --button-invisible-bgColor-disabled: #00000000;
@@ -964,9 +968,9 @@
     --button-outline-fgColor-disabled: #4493f880;
     --button-outline-fgColor-hover: #58a6ff;
     --button-outline-fgColor-rest: #388bfd;
-    --button-outline-shadow-selected: 0px 0px 0px 0px #000000;
+    --button-outline-shadow-selected: 0 0 0 0 #00000000;
     --button-primary-bgColor-disabled: #1158c7;
-    --button-primary-shadow-selected: 0px 0px 0px 0px #000000;
+    --button-primary-shadow-selected: 0 0 0 0 #00000000;
     --button-star-iconColor: #e3b341;
     --buttonCounter-danger-bgColor-rest: #49020233;
     --buttonCounter-default-bgColor-rest: #2f3742;
@@ -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: 0 6px 12px -3px #01040966, 0 6px 18px 0 #01040966; /** Legacy floating shadow for backward compatibility */
+    --shadow-inset: inset 0 1px 0 0 #0104093d; /** Inset shadow for recessed elements */
+    --shadow-resting-medium: 0 1px 1px 0 #01040966, 0 3px 6px 0 #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+    --shadow-resting-small: 0 1px 1px 0 #01040999, 0 1px 3px 0 #01040999; /** Small resting shadow for buttons and interactive elements */
+    --shadow-resting-xsmall: 0 1px 1px 0 #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);
@@ -1783,10 +1787,10 @@
     --buttonKeybindingHint-danger-borderColor-disabled: var(--buttonKeybindingHint-default-borderColor-disabled);
     --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-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-large: 0 0 0 1px #3d444d, 0 24px 48px 0 #010409; /** Large floating shadow for modals and dialogs */
+    --shadow-floating-medium: 0 0 0 1px #3d444d, 0 8px 16px -4px #01040966, 0 4px 32px -4px #01040966, 0 24px 48px -12px #01040966, 0 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
+    --shadow-floating-small: 0 0 0 1px #3d444d, 0 6px 12px -3px #01040966, 0 6px 18px 0 #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
+    --shadow-floating-xlarge: 0 0 0 1px #3d444d, 0 32px 64px 0 #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);