@primer/primitives 11.4.1-rc.eb8ee149 → 11.5.0-rc.14eaeb12

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/base/motion/motion.css

@@ -1,7 +1,7 @@
 :root {
   --base-duration-0: 0ms;
   --base-duration-100: 100ms;
-  --base-duration-1000: 1s;
+  --base-duration-1000: 1000ms;
   --base-duration-200: 200ms;
   --base-duration-300: 300ms;
   --base-duration-400: 400ms;

package/dist/css/functional/size/radius.css

@@ -1,6 +1,6 @@
 :root {
   --borderRadius-full: 624.9375rem; /** Use this border radius for pill shaped elements */
-  --borderRadius-large: 0.75rem; /** Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired. Always use this for buttons. */
+  --borderRadius-large: 0.75rem; /** Large border radius (12px). Use for larger containers, dialogs, or when more visual softness is desired. */
   --borderRadius-medium: 0.375rem; /** Medium border radius (6px). The default choice for most buttons, cards, and containers */
   --borderRadius-small: 0.1875rem; /** Small border radius (3px). Use for small variants of components or small UI elements like badges, tags, or anything below 16px in height */
   --borderRadius-default: var(--borderRadius-medium); /** Default border radius for most UI elements. Alias of borderRadius.medium (6px). Use when in doubt */

package/dist/css/functional/size/size-coarse.css

@@ -1,6 +1,7 @@
 @media (pointer: coarse) {
   :root {
     --control-minTarget-auto: 2.75rem; /** Minimum touch target size for coarse pointer devices (touch screens) */
+    --controlStack-large-gap-auto: 0.75rem; /** Gap between stacked controls in large density layouts for touch devices */
     --controlStack-medium-gap-auto: 0.75rem; /** Gap between stacked controls in medium density layouts for touch devices */
     --controlStack-small-gap-auto: 1rem; /** Gap between stacked controls in small density layouts for touch devices */
   }

package/dist/css/functional/size/size-fine.css

@@ -1,6 +1,7 @@
 @media (pointer: fine) {
   :root {
     --control-minTarget-auto: 1rem; /** Minimum target size for fine pointer devices (mouse) */
+    --controlStack-large-gap-auto: 0.5rem; /** Gap between stacked controls in large density layouts for mouse interfaces */
     --controlStack-medium-gap-auto: 0.5rem; /** Gap between stacked controls in medium density layouts for mouse interfaces */
     --controlStack-small-gap-auto: 0.5rem; /** Gap between stacked controls in small density layouts for mouse interfaces */
   }

package/dist/css/functional/size/size.css

@@ -16,6 +16,7 @@
   --spinner-strokeWidth-default: 0.125rem;
   --control-large-gap: 0.5rem;
   --control-large-lineBoxHeight: 1.25rem;
+  --control-large-paddingInline-condensed: 0.5rem;
   --control-large-paddingInline-normal: 0.75rem;
   --control-large-paddingInline-spacious: 1rem;
   --control-large-size: 2.5rem;
@@ -32,9 +33,11 @@
   --control-small-paddingBlock: 0.25rem;
   --control-small-paddingInline-condensed: 0.5rem;
   --control-small-paddingInline-normal: 0.75rem;
+  --control-small-paddingInline-spacious: 1rem;
   --control-small-size: 1.75rem;
   --control-xlarge-gap: 0.5rem;
   --control-xlarge-lineBoxHeight: 1.25rem;
+  --control-xlarge-paddingInline-condensed: 0.5rem;
   --control-xlarge-paddingInline-normal: 0.75rem;
   --control-xlarge-paddingInline-spacious: 1rem;
   --control-xlarge-size: 3rem;
@@ -47,8 +50,10 @@
   --controlStack-large-gap-auto: 0.5rem;
   --controlStack-large-gap-condensed: 0.5rem;
   --controlStack-large-gap-spacious: 0.75rem;
+  --controlStack-medium-gap-auto: 0.5rem;
   --controlStack-medium-gap-condensed: 0.5rem;
   --controlStack-medium-gap-spacious: 0.75rem;
+  --controlStack-small-gap-auto: 0.5rem;
   --controlStack-small-gap-condensed: 0.5rem;
   --controlStack-small-gap-spacious: 1rem;
   --overlay-borderRadius: 0.375rem;

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

@@ -15,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 */
@@ -58,13 +58,13 @@
   --borderColor-sponsors-muted: #f87cbd; /** Subtle border for GitHub Sponsors content */
   --borderColor-success-emphasis: #409eff; /** Strong success border for prominent positive elements */
   --borderColor-success-muted: #5cacff; /** Subtle success border for positive feedback elements */
-  --borderColor-translucent: #9198a1; /** Semi-transparent border for overlays and layered elements */
+  --borderColor-translucent: #9198a1; /** Semi-transparent border for overlays and layered elements. Border-specific token — no bgColor-translucent counterpart exists by design. */
   --borderColor-transparent: #00000000; /** Fully transparent border */
   --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;
@@ -78,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;
@@ -668,6 +668,7 @@
   --border-sponsors-muted: 0.0625rem solid #f87cbd;
   --border-success-emphasis: 0.0625rem solid #409eff;
   --border-success-muted: 0.0625rem solid #5cacff;
+  --border-translucent: 0.0625rem solid #9198a1; /** Semi-transparent border shorthand for overlays and layered elements. Border-specific token — no bgColor-translucent counterpart exists by design. */
   --border-transparent: 0.0625rem solid #00000000;
   --borderColor-closed-muted: var(--borderColor-default); /** Subtle border for closed state indicators */
   --borderColor-draft-muted: var(--borderColor-default); /** Subtle border for draft state indicators */
@@ -796,17 +797,18 @@
   --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);
   --avatar-borderColor: var(--borderColor-emphasis);
   --border-closed-emphasis: var(--border-danger-emphasis);
   --border-closed-muted: var(--border-danger-muted);
+  --border-draft-muted: 0.0625rem solid #b7bdc8;
   --border-emphasis: 0.0625rem solid #b7bdc8;
   --border-muted: 0.0625rem solid #b7bdc8;
   --border-open-emphasis: var(--border-success-emphasis);
@@ -818,14 +820,17 @@
   --borderColor-neutral-muted: var(--borderColor-muted); /** Subtle neutral semantic border */
   --button-danger-bgColor-disabled: var(--control-bgColor-disabled);
   --button-danger-borderColor-rest: var(--control-borderColor-rest);
+  --button-danger-iconColor-disabled: var(--button-danger-fgColor-disabled);
   --button-default-bgColor-disabled: var(--control-bgColor-disabled);
   --button-default-borderColor-disabled: var(--control-borderColor-disabled);
   --button-default-borderColor-rest: var(--control-borderColor-rest);
+  --button-default-fgColor-disabled: var(--control-fgColor-disabled);
   --button-invisible-borderColor-hover: var(--control-transparent-borderColor-hover);
   --button-invisible-fgColor-disabled: var(--control-fgColor-disabled);
   --button-invisible-iconColor-disabled: var(--control-fgColor-disabled);
   --button-outline-bgColor-disabled: var(--control-bgColor-disabled);
   --button-primary-fgColor-rest: var(--fgColor-white);
+  --button-primary-iconColor-disabled: var(--button-primary-fgColor-disabled);
   --button-primary-iconColor-rest: var(--fgColor-white);
   --buttonKeybindingHint-danger-bgColor-disabled: var(--buttonKeybindingHint-default-bgColor-disabled);
   --buttonKeybindingHint-danger-fgColor-active: var(--fgColor-onEmphasis);
@@ -875,10 +880,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;
@@ -896,6 +901,7 @@
   --controlKnob-borderColor-rest: var(--control-borderColor-emphasis);
   --progressBar-track-borderColor: var(--progressBar-track-bgColor);
   --underlineNav-borderColor-hover: var(--borderColor-neutral-muted);
+  --border-draft-emphasis: 0.0625rem solid #b7bdc8;
   --button-outline-borderColor-hover: var(--button-default-borderColor-hover);
   --button-outline-borderColor-active: var(--button-outline-borderColor-hover);
 }
@@ -912,7 +918,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 */
@@ -955,13 +961,13 @@
     --borderColor-sponsors-muted: #f87cbd; /** Subtle border for GitHub Sponsors content */
     --borderColor-success-emphasis: #409eff; /** Strong success border for prominent positive elements */
     --borderColor-success-muted: #5cacff; /** Subtle success border for positive feedback elements */
-    --borderColor-translucent: #9198a1; /** Semi-transparent border for overlays and layered elements */
+    --borderColor-translucent: #9198a1; /** Semi-transparent border for overlays and layered elements. Border-specific token — no bgColor-translucent counterpart exists by design. */
     --borderColor-transparent: #00000000; /** Fully transparent border */
     --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;
@@ -975,10 +981,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;
@@ -1565,6 +1571,7 @@
     --border-sponsors-muted: 0.0625rem solid #f87cbd;
     --border-success-emphasis: 0.0625rem solid #409eff;
     --border-success-muted: 0.0625rem solid #5cacff;
+    --border-translucent: 0.0625rem solid #9198a1; /** Semi-transparent border shorthand for overlays and layered elements. Border-specific token — no bgColor-translucent counterpart exists by design. */
     --border-transparent: 0.0625rem solid #00000000;
     --borderColor-closed-muted: var(--borderColor-default); /** Subtle border for closed state indicators */
     --borderColor-draft-muted: var(--borderColor-default); /** Subtle border for draft state indicators */
@@ -1693,17 +1700,18 @@
     --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);
     --avatar-borderColor: var(--borderColor-emphasis);
     --border-closed-emphasis: var(--border-danger-emphasis);
     --border-closed-muted: var(--border-danger-muted);
+    --border-draft-muted: 0.0625rem solid #b7bdc8;
     --border-emphasis: 0.0625rem solid #b7bdc8;
     --border-muted: 0.0625rem solid #b7bdc8;
     --border-open-emphasis: var(--border-success-emphasis);
@@ -1715,14 +1723,17 @@
     --borderColor-neutral-muted: var(--borderColor-muted); /** Subtle neutral semantic border */
     --button-danger-bgColor-disabled: var(--control-bgColor-disabled);
     --button-danger-borderColor-rest: var(--control-borderColor-rest);
+    --button-danger-iconColor-disabled: var(--button-danger-fgColor-disabled);
     --button-default-bgColor-disabled: var(--control-bgColor-disabled);
     --button-default-borderColor-disabled: var(--control-borderColor-disabled);
     --button-default-borderColor-rest: var(--control-borderColor-rest);
+    --button-default-fgColor-disabled: var(--control-fgColor-disabled);
     --button-invisible-borderColor-hover: var(--control-transparent-borderColor-hover);
     --button-invisible-fgColor-disabled: var(--control-fgColor-disabled);
     --button-invisible-iconColor-disabled: var(--control-fgColor-disabled);
     --button-outline-bgColor-disabled: var(--control-bgColor-disabled);
     --button-primary-fgColor-rest: var(--fgColor-white);
+    --button-primary-iconColor-disabled: var(--button-primary-fgColor-disabled);
     --button-primary-iconColor-rest: var(--fgColor-white);
     --buttonKeybindingHint-danger-bgColor-disabled: var(--buttonKeybindingHint-default-bgColor-disabled);
     --buttonKeybindingHint-danger-fgColor-active: var(--fgColor-onEmphasis);
@@ -1772,10 +1783,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;
@@ -1793,6 +1804,7 @@
     --controlKnob-borderColor-rest: var(--control-borderColor-emphasis);
     --progressBar-track-borderColor: var(--progressBar-track-bgColor);
     --underlineNav-borderColor-hover: var(--borderColor-neutral-muted);
+    --border-draft-emphasis: 0.0625rem solid #b7bdc8;
     --button-outline-borderColor-hover: var(--button-default-borderColor-hover);
     --button-outline-borderColor-active: var(--button-outline-borderColor-hover);
   }