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

package/dist/internalCss/light-colorblind-high-contrast.css

@@ -287,13 +287,9 @@
   --base-display-color-yellow-7: #704d00;
   --base-display-color-yellow-8: #5c3d00;
   --base-display-color-yellow-9: #422b00;
-  --borderRadius-full: 624.9375rem; /** Use this border radius for pill shaped elements */
-  --borderRadius-large: 0.75rem;
-  --borderRadius-medium: 0.375rem;
-  --borderRadius-small: 0.1875rem;
-  --borderWidth-thick: 0.125rem;
-  --borderWidth-thicker: 0.25rem;
-  --borderWidth-thin: 0.0625rem;
+  --borderWidth-thick: 0.125rem; /** Thick 2px border for emphasis. Use for focus indicators, selected states, or to emphasize important boundaries */
+  --borderWidth-thicker: 0.25rem; /** Extra thick 4px border for maximum emphasis. Use sparingly for high-contrast focus indicators or critical visual separators */
+  --borderWidth-thin: 0.0625rem; /** Standard 1px border width. Use for most borders, dividers, and outlines throughout the interface */
   --button-outline-bgColor-active: #033f9d;
   --button-primary-bgColor-active: #075fc8;
   --button-primary-bgColor-disabled: #92caff;
@@ -304,63 +300,62 @@
   --control-checked-bgColor-hover: #0344a8;
   --control-checked-borderColor-active: #033f9d;
   --control-checked-borderColor-hover: #0344a8;
-  --outline-focus-offset: -0.125rem;
-  --outline-focus-width: 0.125rem;
+  --outline-focus-offset: -0.125rem; /** Focus outline offset (-2px). Negative value creates an inset outline for keyboard focus indicators, ensuring the focus ring stays within the element bounds */
+  --outline-focus-width: 0.125rem; /** Focus outline width (2px). Standard width for keyboard focus indicators to meet WCAG 2.4.7 accessibility requirements */
   --reactionButton-selected-bgColor-hover: #caecff;
   --avatarStack-fade-bgColor-default: var(--base-color-neutral-7);
   --avatarStack-fade-bgColor-muted: var(--base-color-neutral-5);
   --base-color-neutral-0: var(--base-color-white);
   --base-color-neutral-13: var(--base-color-black);
-  --bgColor-accent-emphasis: var(--base-color-blue-5);
-  --bgColor-accent-muted: var(--base-color-blue-0);
-  --bgColor-attention-emphasis: var(--base-color-yellow-5);
-  --bgColor-attention-muted: var(--base-color-yellow-0);
-  --bgColor-danger-emphasis: var(--base-color-orange-5);
-  --bgColor-danger-muted: var(--base-color-orange-0);
-  --bgColor-disabled: var(--base-color-neutral-4);
-  --bgColor-done-emphasis: var(--base-color-purple-5);
-  --bgColor-done-muted: var(--base-color-purple-0);
-  --bgColor-emphasis: var(--base-color-neutral-12);
-  --bgColor-inset: var(--base-color-neutral-2);
-  --bgColor-inverse: var(--base-color-neutral-12);
-  --bgColor-muted: var(--base-color-neutral-3);
-  --bgColor-neutral-emphasis: var(--base-color-neutral-10);
-  --bgColor-neutral-muted: var(--base-color-neutral-4);
-  --bgColor-open-emphasis: var(--base-color-orange-5);
-  --bgColor-open-muted: var(--base-color-orange-0);
-  --bgColor-severe-emphasis: var(--base-color-orange-5);
-  --bgColor-severe-muted: var(--base-color-orange-0);
-  --bgColor-sponsors-emphasis: var(--base-color-pink-5);
-  --bgColor-sponsors-muted: var(--base-color-pink-0);
-  --bgColor-success-emphasis: var(--base-color-blue-5);
-  --bgColor-success-muted: var(--base-color-blue-0);
-  --bgColor-transparent: var(--base-color-transparent);
-  --borderColor-accent-emphasis: var(--base-color-blue-5);
-  --borderColor-accent-muted: var(--base-color-blue-3);
-  --borderColor-attention-emphasis: var(--base-color-yellow-5);
-  --borderColor-attention-muted: var(--base-color-yellow-3);
-  --borderColor-danger-emphasis: var(--base-color-orange-5);
-  --borderColor-danger-muted: var(--base-color-orange-4);
-  --borderColor-default: var(--base-color-neutral-10);
-  --borderColor-disabled: #59636e1f;
-  --borderColor-done-emphasis: var(--base-color-purple-5);
-  --borderColor-done-muted: var(--base-color-purple-3);
-  --borderColor-neutral-emphasis: var(--base-color-neutral-9);
-  --borderColor-open-emphasis: var(--base-color-orange-5);
-  --borderColor-open-muted: var(--base-color-orange-3);
-  --borderColor-severe-emphasis: var(--base-color-orange-5);
-  --borderColor-severe-muted: #dc6d1a66;
-  --borderColor-sponsors-emphasis: var(--base-color-pink-5);
-  --borderColor-sponsors-muted: var(--base-color-pink-3);
-  --borderColor-success-emphasis: var(--base-color-blue-5);
-  --borderColor-success-muted: var(--base-color-blue-3);
-  --borderColor-translucent: var(--base-color-neutral-9);
-  --borderColor-transparent: var(--base-color-transparent);
-  --borderRadius-default: var(--borderRadius-medium);
-  --borderWidth-default: var(--borderWidth-thin);
-  --boxShadow-thick: inset 0 0 0 var(--borderWidth-thick);
-  --boxShadow-thicker: inset 0 0 0 var(--borderWidth-thicker);
-  --boxShadow-thin: inset 0 0 0 var(--borderWidth-thin); /** Thin shadow for borders */
+  --bgColor-accent-emphasis: var(--base-color-blue-5); /** Strong accent background for active states and focused states */
+  --bgColor-accent-muted: var(--base-color-blue-0); /** Subtle accent background for informational or selected elements */
+  --bgColor-attention-emphasis: var(--base-color-yellow-5); /** Strong attention background for prominent warnings */
+  --bgColor-attention-muted: var(--base-color-yellow-0); /** Subtle attention background for warnings and caution states */
+  --bgColor-danger-emphasis: var(--base-color-orange-5); /** Emphasized danger background for critical errors and delete confirmations */
+  --bgColor-danger-muted: var(--base-color-orange-0); /** Muted danger background for error states and destructive action contexts */
+  --bgColor-disabled: var(--base-color-neutral-4); /** Background for disabled interactive elements */
+  --bgColor-done-emphasis: var(--base-color-purple-5); /** Strong background for completed/done state badges and labels */
+  --bgColor-done-muted: var(--base-color-purple-0); /** Subtle background for completed/done state indicators */
+  --bgColor-emphasis: var(--base-color-neutral-12); /** High-emphasis dark background for strong visual contrast */
+  --bgColor-inset: var(--base-color-neutral-2); /** Inset background for recessed content areas like wells or sunken panels */
+  --bgColor-inverse: var(--base-color-neutral-12); /** Inverse background that flips between light and dark modes */
+  --bgColor-muted: var(--base-color-neutral-3); /** Muted background for secondary content areas and subtle grouping */
+  --bgColor-neutral-emphasis: var(--base-color-neutral-10); /** Strong neutral background for prominent neutral elements */
+  --bgColor-neutral-muted: var(--base-color-neutral-4); /** Subtle neutral background for tags, labels, and secondary UI elements */
+  --bgColor-open-emphasis: var(--base-color-orange-5); /** Strong background for open state badges and labels */
+  --bgColor-open-muted: var(--base-color-orange-0); /** Subtle background for open state indicators (issues, PRs) */
+  --bgColor-severe-emphasis: var(--base-color-orange-5); /** Strong severe background for prominent high-priority warnings */
+  --bgColor-severe-muted: var(--base-color-orange-0); /** Subtle severe background for high-priority warnings */
+  --bgColor-sponsors-emphasis: var(--base-color-pink-5); /** Strong background for prominent GitHub Sponsors elements */
+  --bgColor-sponsors-muted: var(--base-color-pink-0); /** Subtle background for GitHub Sponsors content */
+  --bgColor-success-emphasis: var(--base-color-blue-5); /** Strong success background for prominent positive actions */
+  --bgColor-success-muted: var(--base-color-blue-0); /** Subtle success background for positive feedback and completed states */
+  --bgColor-transparent: var(--base-color-transparent); /** Fully transparent background */
+  --borderColor-accent-emphasis: var(--base-color-blue-5); /** Strong accent border for selected or focused elements */
+  --borderColor-accent-muted: var(--base-color-blue-3); /** Subtle accent border for selected or focused elements */
+  --borderColor-attention-emphasis: var(--base-color-yellow-5); /** Strong attention border for prominent warnings */
+  --borderColor-attention-muted: var(--base-color-yellow-3); /** Subtle attention border for warnings and caution states */
+  --borderColor-danger-emphasis: var(--base-color-orange-5); /** Strong danger border for destructive actions and errors */
+  --borderColor-danger-muted: var(--base-color-orange-4); /** Subtle danger border for errors and destructive contexts */
+  --borderColor-default: var(--base-color-neutral-10); /** Default border color for most UI elements */
+  --borderColor-disabled: #59636e1f; /** Border color for disabled interactive elements */
+  --borderColor-done-emphasis: var(--base-color-purple-5); /** Strong border for completed/done state badges */
+  --borderColor-done-muted: var(--base-color-purple-3); /** Subtle border for completed/done state indicators */
+  --borderColor-neutral-emphasis: var(--base-color-neutral-9); /** Strong neutral semantic border */
+  --borderColor-open-emphasis: var(--base-color-orange-5); /** Strong border for open state badges */
+  --borderColor-open-muted: var(--base-color-orange-3); /** Subtle border for open state indicators */
+  --borderColor-severe-emphasis: var(--base-color-orange-5); /** Strong severe border for prominent high-priority warnings */
+  --borderColor-severe-muted: #dc6d1a66; /** Subtle severe border for high-priority warnings */
+  --borderColor-sponsors-emphasis: var(--base-color-pink-5); /** Strong border for prominent GitHub Sponsors elements */
+  --borderColor-sponsors-muted: var(--base-color-pink-3); /** Subtle border for GitHub Sponsors content */
+  --borderColor-success-emphasis: var(--base-color-blue-5); /** Strong success border for prominent positive elements */
+  --borderColor-success-muted: var(--base-color-blue-3); /** Subtle success border for positive feedback elements */
+  --borderColor-translucent: var(--base-color-neutral-9); /** Semi-transparent border for overlays and layered elements */
+  --borderColor-transparent: var(--base-color-transparent); /** Fully transparent border */
+  --borderWidth-default: var(--borderWidth-thin); /** Default border width for most UI elements. Alias of borderWidth.thin (1px) */
+  --boxShadow-thick: inset 0 0 0 var(--borderWidth-thick); /** Thick shadow (2px) used instead of a border for emphasis without layout shift */
+  --boxShadow-thicker: inset 0 0 0 var(--borderWidth-thicker); /** Thickest shadow (4px) used for high emphasis borders without layout shift. Use sparingly for maximum visual impact */
+  --boxShadow-thin: inset 0 0 0 var(--borderWidth-thin); /** Thin shadow used instead of a border to prevent layout shift */
   --button-danger-bgColor-active: var(--base-color-orange-6);
   --button-danger-borderColor-hover: var(--base-color-orange-7);
   --button-danger-shadow-selected: inset 0px 1px 0px 0px #43001133;
@@ -785,17 +780,17 @@
   --display-yellow-scale-7: var(--base-display-color-yellow-7);
   --display-yellow-scale-8: var(--base-display-color-yellow-8);
   --display-yellow-scale-9: var(--base-display-color-yellow-9);
-  --fgColor-accent: var(--base-color-blue-6);
-  --fgColor-attention: var(--base-color-yellow-6);
-  --fgColor-danger: var(--base-color-orange-6);
-  --fgColor-disabled: var(--base-color-neutral-9);
-  --fgColor-done: var(--base-color-purple-6);
-  --fgColor-muted: var(--base-color-neutral-11);
-  --fgColor-neutral: var(--base-color-neutral-11);
-  --fgColor-open: var(--base-color-orange-6);
-  --fgColor-severe: var(--base-color-orange-6);
-  --fgColor-sponsors: var(--base-color-pink-6);
-  --fgColor-success: var(--base-color-blue-6);
+  --fgColor-accent: var(--base-color-blue-6); /** Accent text for links and interactive elements */
+  --fgColor-attention: var(--base-color-yellow-6); /** Attention text for warnings and caution states */
+  --fgColor-danger: var(--base-color-orange-6); /** Danger text for errors and destructive actions */
+  --fgColor-disabled: var(--base-color-neutral-9); /** Text color for disabled interactive elements */
+  --fgColor-done: var(--base-color-purple-6); /** Text color for completed/done state indicators */
+  --fgColor-muted: var(--base-color-neutral-11); /** Muted text for secondary content and less important information */
+  --fgColor-neutral: var(--base-color-neutral-11); /** Neutral semantic text for icons and secondary elements */
+  --fgColor-open: var(--base-color-orange-6); /** Text color for open state indicators (issues, PRs) */
+  --fgColor-severe: var(--base-color-orange-6); /** Severe text for high-priority warnings */
+  --fgColor-sponsors: var(--base-color-pink-6); /** Text color for GitHub Sponsors content */
+  --fgColor-success: var(--base-color-blue-6); /** Success text for positive feedback and completed states */
   --header-bgColor: var(--base-color-neutral-12);
   --header-borderColor-divider: var(--base-color-neutral-7);
   --headerSearch-bgColor: var(--base-color-neutral-12);
@@ -923,23 +918,23 @@
   --reactionButton-selected-fgColor-hover: var(--base-color-blue-6);
   --selectMenu-bgColor-active: var(--base-color-blue-1);
   --selectMenu-borderColor: var(--base-color-transparent);
-  --shadow-floating-legacy: 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f;
-  --shadow-resting-medium: 0px 1px 1px 0px #25292e1a, 0px 3px 6px 0px #25292e1f;
+  --shadow-floating-legacy: 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f; /** Legacy floating shadow for backward compatibility */
+  --shadow-resting-medium: 0px 1px 1px 0px #25292e1a, 0px 3px 6px 0px #25292e1f; /** Medium resting shadow for cards and elevated surfaces */
   --skeletonLoader-bgColor: var(--base-color-neutral-5);
   --treeViewItem-leadingVisual-iconColor-rest: var(--base-color-blue-3);
   --underlineNav-borderColor-active: var(--base-color-coral-3);
   --avatar-bgColor: var(--base-color-neutral-0);
   --avatar-shadow: 0px 0px 0px 2px #ffffffcc;
   --base-color-inset: var(--base-color-neutral-0);
-  --bgColor-black: var(--base-color-neutral-13);
-  --bgColor-closed-emphasis: var(--bgColor-neutral-emphasis);
-  --bgColor-closed-muted: var(--bgColor-neutral-muted);
-  --bgColor-default: var(--base-color-neutral-0);
-  --bgColor-draft-emphasis: var(--bgColor-neutral-emphasis);
-  --bgColor-draft-muted: var(--bgColor-neutral-muted);
-  --bgColor-upsell-emphasis: var(--bgColor-done-emphasis);
-  --bgColor-upsell-muted: var(--bgColor-done-muted);
-  --bgColor-white: var(--base-color-neutral-0);
+  --bgColor-black: var(--base-color-neutral-13); /** Pure black background */
+  --bgColor-closed-emphasis: var(--bgColor-neutral-emphasis); /** Strong background for closed state badges and labels */
+  --bgColor-closed-muted: var(--bgColor-neutral-muted); /** Subtle background for closed state indicators (issues, PRs) */
+  --bgColor-default: var(--base-color-neutral-0); /** Default background color for pages and main content areas */
+  --bgColor-draft-emphasis: var(--bgColor-neutral-emphasis); /** Strong background for draft state badges and labels */
+  --bgColor-draft-muted: var(--bgColor-neutral-muted); /** Subtle background for draft state indicators */
+  --bgColor-upsell-emphasis: var(--bgColor-done-emphasis); /** Strong background for prominent upsell elements */
+  --bgColor-upsell-muted: var(--bgColor-done-muted); /** Subtle background for upsell and promotional content */
+  --bgColor-white: var(--base-color-neutral-0); /** Pure white background */
   --border-accent-emphasis: 0.0625rem solid #0349b4;
   --border-accent-muted: 0.0625rem solid #368cf9;
   --border-attention-emphasis: 0.0625rem solid #744500;
@@ -958,13 +953,13 @@
   --border-success-emphasis: 0.0625rem solid #0349b4;
   --border-success-muted: 0.0625rem solid #368cf9;
   --border-transparent: 0.0625rem solid #ffffff00;
-  --borderColor-closed-muted: var(--borderColor-default);
-  --borderColor-draft-emphasis: var(--borderColor-neutral-emphasis);
-  --borderColor-draft-muted: var(--borderColor-default);
-  --borderColor-emphasis: var(--borderColor-default);
-  --borderColor-muted: var(--borderColor-default);
-  --borderColor-upsell-emphasis: var(--borderColor-done-emphasis);
-  --borderColor-upsell-muted: var(--borderColor-done-muted);
+  --borderColor-closed-muted: var(--borderColor-default); /** Subtle border for closed state indicators */
+  --borderColor-draft-emphasis: var(--borderColor-neutral-emphasis); /** Strong border for draft state badges */
+  --borderColor-draft-muted: var(--borderColor-default); /** Subtle border for draft state indicators */
+  --borderColor-emphasis: var(--borderColor-default); /** Strong border for emphasis and visual weight */
+  --borderColor-muted: var(--borderColor-default); /** Subtle border for secondary elements and light separators */
+  --borderColor-upsell-emphasis: var(--borderColor-done-emphasis); /** Strong border for prominent upsell elements */
+  --borderColor-upsell-muted: var(--borderColor-done-muted); /** Subtle border for upsell and promotional content */
   --button-danger-bgColor-hover: var(--bgColor-danger-emphasis);
   --button-danger-bgColor-rest: var(--control-bgColor-rest);
   --button-danger-borderColor-active: var(--button-danger-borderColor-hover);
@@ -1065,16 +1060,16 @@
   --diffBlob-emptyLine-bgColor: var(--bgColor-muted);
   --diffBlob-emptyNum-bgColor: var(--bgColor-muted);
   --diffBlob-hunkLine-fgColor: var(--fgColor-muted);
-  --fgColor-black: var(--base-color-neutral-13);
-  --fgColor-closed: var(--fgColor-muted);
-  --fgColor-default: var(--base-color-neutral-13);
-  --fgColor-draft: var(--fgColor-neutral);
-  --fgColor-link: var(--fgColor-accent);
-  --fgColor-onEmphasis: var(--base-color-neutral-0);
-  --fgColor-onInverse: var(--base-color-neutral-0);
-  --fgColor-upsell: var(--fgColor-done);
-  --fgColor-white: var(--base-color-neutral-0);
-  --focus-outlineColor: var(--borderColor-accent-emphasis);
+  --fgColor-black: var(--base-color-neutral-13); /** Pure black text */
+  --fgColor-closed: var(--fgColor-muted); /** Text color for closed state indicators (issues, PRs) */
+  --fgColor-default: var(--base-color-neutral-13); /** Default text color for primary content and headings */
+  --fgColor-draft: var(--fgColor-neutral); /** Text color for draft state indicators */
+  --fgColor-link: var(--fgColor-accent); /** Text color for hyperlinks */
+  --fgColor-onEmphasis: var(--base-color-neutral-0); /** Text color for use on emphasis backgrounds */
+  --fgColor-onInverse: var(--base-color-neutral-0); /** Text color for use on inverse backgrounds */
+  --fgColor-upsell: var(--fgColor-done); /** Text color for upsell and promotional content */
+  --fgColor-white: var(--base-color-neutral-0); /** Pure white text */
+  --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
   --header-fgColor-default: #ffffffb3;
   --header-fgColor-logo: var(--base-color-neutral-0);
   --label-auburn-borderColor: var(--label-auburn-fgColor-rest);
@@ -1106,10 +1101,10 @@
   --progressBar-bgColor-severe: var(--bgColor-severe-emphasis);
   --progressBar-bgColor-sponsors: var(--bgColor-sponsors-emphasis);
   --progressBar-bgColor-success: var(--bgColor-success-emphasis);
-  --selection-bgColor: #0349b433;
-  --shadow-inset: inset 0px 1px 0px 0px #0104090a;
-  --shadow-resting-small: 0px 1px 1px 0px #0104090f, 0px 1px 3px 0px #0104090f;
-  --shadow-resting-xsmall: 0px 1px 1px 0px #0104090f;
+  --selection-bgColor: #0349b433; /** Background color for text selection highlights */
+  --shadow-inset: inset 0px 1px 0px 0px #0104090a; /** Inset shadow for recessed elements */
+  --shadow-resting-small: 0px 1px 1px 0px #0104090a, 0px 1px 2px 0px #01040908; /** Small resting shadow for buttons and interactive elements */
+  --shadow-resting-xsmall: 0px 1px 1px 0px #0104090d; /** Extra small resting shadow for minimal elevation */
   --sideNav-bgColor-selected: var(--base-color-neutral-0);
   --timelineBadge-bgColor: var(--bgColor-muted);
   --tooltip-bgColor: var(--bgColor-emphasis);
@@ -1124,8 +1119,8 @@
   --border-open-muted: var(--border-success-muted);
   --border-upsell-emphasis: 0.0625rem solid #622cbc;
   --border-upsell-muted: 0.0625rem solid #a371f7;
-  --borderColor-closed-emphasis: var(--borderColor-emphasis);
-  --borderColor-neutral-muted: var(--borderColor-muted);
+  --borderColor-closed-emphasis: var(--borderColor-emphasis); /** Strong border for closed state badges */
+  --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-rest: var(--button-danger-fgColor-rest);
@@ -1183,13 +1178,13 @@
   --diffBlob-expander-iconColor: var(--fgColor-default);
   --diffBlob-hunkNum-fgColor-hover: var(--fgColor-default);
   --diffBlob-hunkNum-fgColor-rest: var(--fgColor-default);
-  --focus-outline: 2px solid #0349b4;
+  --focus-outline: 2px solid #0349b4; /** Focus ring outline for keyboard navigation and accessibility. */
   --progressBar-track-bgColor: var(--bgColor-default);
   --reactionButton-selected-fgColor-rest: var(--fgColor-link);
-  --shadow-floating-large: 0px 0px 0px 1px #454c54, 0px 40px 80px 0px #25292e3d;
-  --shadow-floating-medium: 0px 0px 0px 1px #454c54, 0px 8px 16px -4px #25292e14, 0px 4px 32px -4px #25292e14, 0px 24px 48px -12px #25292e14, 0px 48px 96px -24px #25292e14;
-  --shadow-floating-small: 0px 0px 0px 1px #454c5480, 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f;
-  --shadow-floating-xlarge: 0px 0px 0px 1px #454c54, 0px 56px 112px 0px #25292e52;
+  --shadow-floating-large: 0px 0px 0px 1px #454c54, 0px 40px 80px 0px #25292e3d; /** Large floating shadow for modals and dialogs */
+  --shadow-floating-medium: 0px 0px 0px 1px #454c54, 0px 8px 16px -4px #25292e14, 0px 4px 32px -4px #25292e14, 0px 24px 48px -12px #25292e14, 0px 48px 96px -24px #25292e14; /** Medium floating shadow for popovers and action menus */
+  --shadow-floating-small: 0px 0px 0px 1px #454c5480, 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f; /** Small floating shadow for dropdowns, tooltips, and small overlays */
+  --shadow-floating-xlarge: 0px 0px 0px 1px #454c54, 0px 56px 112px 0px #25292e52; /** Extra large floating shadow for full-screen overlays and sheets */
   --tooltip-fgColor: var(--fgColor-onEmphasis);
   --underlineNav-borderColor-hover: var(--borderColor-muted);
   --border-neutral-muted: 0.0625rem solid #454c54;
@@ -1488,13 +1483,9 @@
     --base-display-color-yellow-7: #704d00;
     --base-display-color-yellow-8: #5c3d00;
     --base-display-color-yellow-9: #422b00;
-    --borderRadius-full: 624.9375rem; /** Use this border radius for pill shaped elements */
-    --borderRadius-large: 0.75rem;
-    --borderRadius-medium: 0.375rem;
-    --borderRadius-small: 0.1875rem;
-    --borderWidth-thick: 0.125rem;
-    --borderWidth-thicker: 0.25rem;
-    --borderWidth-thin: 0.0625rem;
+    --borderWidth-thick: 0.125rem; /** Thick 2px border for emphasis. Use for focus indicators, selected states, or to emphasize important boundaries */
+    --borderWidth-thicker: 0.25rem; /** Extra thick 4px border for maximum emphasis. Use sparingly for high-contrast focus indicators or critical visual separators */
+    --borderWidth-thin: 0.0625rem; /** Standard 1px border width. Use for most borders, dividers, and outlines throughout the interface */
     --button-outline-bgColor-active: #033f9d;
     --button-primary-bgColor-active: #075fc8;
     --button-primary-bgColor-disabled: #92caff;
@@ -1505,63 +1496,62 @@
     --control-checked-bgColor-hover: #0344a8;
     --control-checked-borderColor-active: #033f9d;
     --control-checked-borderColor-hover: #0344a8;
-    --outline-focus-offset: -0.125rem;
-    --outline-focus-width: 0.125rem;
+    --outline-focus-offset: -0.125rem; /** Focus outline offset (-2px). Negative value creates an inset outline for keyboard focus indicators, ensuring the focus ring stays within the element bounds */
+    --outline-focus-width: 0.125rem; /** Focus outline width (2px). Standard width for keyboard focus indicators to meet WCAG 2.4.7 accessibility requirements */
     --reactionButton-selected-bgColor-hover: #caecff;
     --avatarStack-fade-bgColor-default: var(--base-color-neutral-7);
     --avatarStack-fade-bgColor-muted: var(--base-color-neutral-5);
     --base-color-neutral-0: var(--base-color-white);
     --base-color-neutral-13: var(--base-color-black);
-    --bgColor-accent-emphasis: var(--base-color-blue-5);
-    --bgColor-accent-muted: var(--base-color-blue-0);
-    --bgColor-attention-emphasis: var(--base-color-yellow-5);
-    --bgColor-attention-muted: var(--base-color-yellow-0);
-    --bgColor-danger-emphasis: var(--base-color-orange-5);
-    --bgColor-danger-muted: var(--base-color-orange-0);
-    --bgColor-disabled: var(--base-color-neutral-4);
-    --bgColor-done-emphasis: var(--base-color-purple-5);
-    --bgColor-done-muted: var(--base-color-purple-0);
-    --bgColor-emphasis: var(--base-color-neutral-12);
-    --bgColor-inset: var(--base-color-neutral-2);
-    --bgColor-inverse: var(--base-color-neutral-12);
-    --bgColor-muted: var(--base-color-neutral-3);
-    --bgColor-neutral-emphasis: var(--base-color-neutral-10);
-    --bgColor-neutral-muted: var(--base-color-neutral-4);
-    --bgColor-open-emphasis: var(--base-color-orange-5);
-    --bgColor-open-muted: var(--base-color-orange-0);
-    --bgColor-severe-emphasis: var(--base-color-orange-5);
-    --bgColor-severe-muted: var(--base-color-orange-0);
-    --bgColor-sponsors-emphasis: var(--base-color-pink-5);
-    --bgColor-sponsors-muted: var(--base-color-pink-0);
-    --bgColor-success-emphasis: var(--base-color-blue-5);
-    --bgColor-success-muted: var(--base-color-blue-0);
-    --bgColor-transparent: var(--base-color-transparent);
-    --borderColor-accent-emphasis: var(--base-color-blue-5);
-    --borderColor-accent-muted: var(--base-color-blue-3);
-    --borderColor-attention-emphasis: var(--base-color-yellow-5);
-    --borderColor-attention-muted: var(--base-color-yellow-3);
-    --borderColor-danger-emphasis: var(--base-color-orange-5);
-    --borderColor-danger-muted: var(--base-color-orange-4);
-    --borderColor-default: var(--base-color-neutral-10);
-    --borderColor-disabled: #59636e1f;
-    --borderColor-done-emphasis: var(--base-color-purple-5);
-    --borderColor-done-muted: var(--base-color-purple-3);
-    --borderColor-neutral-emphasis: var(--base-color-neutral-9);
-    --borderColor-open-emphasis: var(--base-color-orange-5);
-    --borderColor-open-muted: var(--base-color-orange-3);
-    --borderColor-severe-emphasis: var(--base-color-orange-5);
-    --borderColor-severe-muted: #dc6d1a66;
-    --borderColor-sponsors-emphasis: var(--base-color-pink-5);
-    --borderColor-sponsors-muted: var(--base-color-pink-3);
-    --borderColor-success-emphasis: var(--base-color-blue-5);
-    --borderColor-success-muted: var(--base-color-blue-3);
-    --borderColor-translucent: var(--base-color-neutral-9);
-    --borderColor-transparent: var(--base-color-transparent);
-    --borderRadius-default: var(--borderRadius-medium);
-    --borderWidth-default: var(--borderWidth-thin);
-    --boxShadow-thick: inset 0 0 0 var(--borderWidth-thick);
-    --boxShadow-thicker: inset 0 0 0 var(--borderWidth-thicker);
-    --boxShadow-thin: inset 0 0 0 var(--borderWidth-thin); /** Thin shadow for borders */
+    --bgColor-accent-emphasis: var(--base-color-blue-5); /** Strong accent background for active states and focused states */
+    --bgColor-accent-muted: var(--base-color-blue-0); /** Subtle accent background for informational or selected elements */
+    --bgColor-attention-emphasis: var(--base-color-yellow-5); /** Strong attention background for prominent warnings */
+    --bgColor-attention-muted: var(--base-color-yellow-0); /** Subtle attention background for warnings and caution states */
+    --bgColor-danger-emphasis: var(--base-color-orange-5); /** Emphasized danger background for critical errors and delete confirmations */
+    --bgColor-danger-muted: var(--base-color-orange-0); /** Muted danger background for error states and destructive action contexts */
+    --bgColor-disabled: var(--base-color-neutral-4); /** Background for disabled interactive elements */
+    --bgColor-done-emphasis: var(--base-color-purple-5); /** Strong background for completed/done state badges and labels */
+    --bgColor-done-muted: var(--base-color-purple-0); /** Subtle background for completed/done state indicators */
+    --bgColor-emphasis: var(--base-color-neutral-12); /** High-emphasis dark background for strong visual contrast */
+    --bgColor-inset: var(--base-color-neutral-2); /** Inset background for recessed content areas like wells or sunken panels */
+    --bgColor-inverse: var(--base-color-neutral-12); /** Inverse background that flips between light and dark modes */
+    --bgColor-muted: var(--base-color-neutral-3); /** Muted background for secondary content areas and subtle grouping */
+    --bgColor-neutral-emphasis: var(--base-color-neutral-10); /** Strong neutral background for prominent neutral elements */
+    --bgColor-neutral-muted: var(--base-color-neutral-4); /** Subtle neutral background for tags, labels, and secondary UI elements */
+    --bgColor-open-emphasis: var(--base-color-orange-5); /** Strong background for open state badges and labels */
+    --bgColor-open-muted: var(--base-color-orange-0); /** Subtle background for open state indicators (issues, PRs) */
+    --bgColor-severe-emphasis: var(--base-color-orange-5); /** Strong severe background for prominent high-priority warnings */
+    --bgColor-severe-muted: var(--base-color-orange-0); /** Subtle severe background for high-priority warnings */
+    --bgColor-sponsors-emphasis: var(--base-color-pink-5); /** Strong background for prominent GitHub Sponsors elements */
+    --bgColor-sponsors-muted: var(--base-color-pink-0); /** Subtle background for GitHub Sponsors content */
+    --bgColor-success-emphasis: var(--base-color-blue-5); /** Strong success background for prominent positive actions */
+    --bgColor-success-muted: var(--base-color-blue-0); /** Subtle success background for positive feedback and completed states */
+    --bgColor-transparent: var(--base-color-transparent); /** Fully transparent background */
+    --borderColor-accent-emphasis: var(--base-color-blue-5); /** Strong accent border for selected or focused elements */
+    --borderColor-accent-muted: var(--base-color-blue-3); /** Subtle accent border for selected or focused elements */
+    --borderColor-attention-emphasis: var(--base-color-yellow-5); /** Strong attention border for prominent warnings */
+    --borderColor-attention-muted: var(--base-color-yellow-3); /** Subtle attention border for warnings and caution states */
+    --borderColor-danger-emphasis: var(--base-color-orange-5); /** Strong danger border for destructive actions and errors */
+    --borderColor-danger-muted: var(--base-color-orange-4); /** Subtle danger border for errors and destructive contexts */
+    --borderColor-default: var(--base-color-neutral-10); /** Default border color for most UI elements */
+    --borderColor-disabled: #59636e1f; /** Border color for disabled interactive elements */
+    --borderColor-done-emphasis: var(--base-color-purple-5); /** Strong border for completed/done state badges */
+    --borderColor-done-muted: var(--base-color-purple-3); /** Subtle border for completed/done state indicators */
+    --borderColor-neutral-emphasis: var(--base-color-neutral-9); /** Strong neutral semantic border */
+    --borderColor-open-emphasis: var(--base-color-orange-5); /** Strong border for open state badges */
+    --borderColor-open-muted: var(--base-color-orange-3); /** Subtle border for open state indicators */
+    --borderColor-severe-emphasis: var(--base-color-orange-5); /** Strong severe border for prominent high-priority warnings */
+    --borderColor-severe-muted: #dc6d1a66; /** Subtle severe border for high-priority warnings */
+    --borderColor-sponsors-emphasis: var(--base-color-pink-5); /** Strong border for prominent GitHub Sponsors elements */
+    --borderColor-sponsors-muted: var(--base-color-pink-3); /** Subtle border for GitHub Sponsors content */
+    --borderColor-success-emphasis: var(--base-color-blue-5); /** Strong success border for prominent positive elements */
+    --borderColor-success-muted: var(--base-color-blue-3); /** Subtle success border for positive feedback elements */
+    --borderColor-translucent: var(--base-color-neutral-9); /** Semi-transparent border for overlays and layered elements */
+    --borderColor-transparent: var(--base-color-transparent); /** Fully transparent border */
+    --borderWidth-default: var(--borderWidth-thin); /** Default border width for most UI elements. Alias of borderWidth.thin (1px) */
+    --boxShadow-thick: inset 0 0 0 var(--borderWidth-thick); /** Thick shadow (2px) used instead of a border for emphasis without layout shift */
+    --boxShadow-thicker: inset 0 0 0 var(--borderWidth-thicker); /** Thickest shadow (4px) used for high emphasis borders without layout shift. Use sparingly for maximum visual impact */
+    --boxShadow-thin: inset 0 0 0 var(--borderWidth-thin); /** Thin shadow used instead of a border to prevent layout shift */
     --button-danger-bgColor-active: var(--base-color-orange-6);
     --button-danger-borderColor-hover: var(--base-color-orange-7);
     --button-danger-shadow-selected: inset 0px 1px 0px 0px #43001133;
@@ -1986,17 +1976,17 @@
     --display-yellow-scale-7: var(--base-display-color-yellow-7);
     --display-yellow-scale-8: var(--base-display-color-yellow-8);
     --display-yellow-scale-9: var(--base-display-color-yellow-9);
-    --fgColor-accent: var(--base-color-blue-6);
-    --fgColor-attention: var(--base-color-yellow-6);
-    --fgColor-danger: var(--base-color-orange-6);
-    --fgColor-disabled: var(--base-color-neutral-9);
-    --fgColor-done: var(--base-color-purple-6);
-    --fgColor-muted: var(--base-color-neutral-11);
-    --fgColor-neutral: var(--base-color-neutral-11);
-    --fgColor-open: var(--base-color-orange-6);
-    --fgColor-severe: var(--base-color-orange-6);
-    --fgColor-sponsors: var(--base-color-pink-6);
-    --fgColor-success: var(--base-color-blue-6);
+    --fgColor-accent: var(--base-color-blue-6); /** Accent text for links and interactive elements */
+    --fgColor-attention: var(--base-color-yellow-6); /** Attention text for warnings and caution states */
+    --fgColor-danger: var(--base-color-orange-6); /** Danger text for errors and destructive actions */
+    --fgColor-disabled: var(--base-color-neutral-9); /** Text color for disabled interactive elements */
+    --fgColor-done: var(--base-color-purple-6); /** Text color for completed/done state indicators */
+    --fgColor-muted: var(--base-color-neutral-11); /** Muted text for secondary content and less important information */
+    --fgColor-neutral: var(--base-color-neutral-11); /** Neutral semantic text for icons and secondary elements */
+    --fgColor-open: var(--base-color-orange-6); /** Text color for open state indicators (issues, PRs) */
+    --fgColor-severe: var(--base-color-orange-6); /** Severe text for high-priority warnings */
+    --fgColor-sponsors: var(--base-color-pink-6); /** Text color for GitHub Sponsors content */
+    --fgColor-success: var(--base-color-blue-6); /** Success text for positive feedback and completed states */
     --header-bgColor: var(--base-color-neutral-12);
     --header-borderColor-divider: var(--base-color-neutral-7);
     --headerSearch-bgColor: var(--base-color-neutral-12);
@@ -2124,23 +2114,23 @@
     --reactionButton-selected-fgColor-hover: var(--base-color-blue-6);
     --selectMenu-bgColor-active: var(--base-color-blue-1);
     --selectMenu-borderColor: var(--base-color-transparent);
-    --shadow-floating-legacy: 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f;
-    --shadow-resting-medium: 0px 1px 1px 0px #25292e1a, 0px 3px 6px 0px #25292e1f;
+    --shadow-floating-legacy: 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f; /** Legacy floating shadow for backward compatibility */
+    --shadow-resting-medium: 0px 1px 1px 0px #25292e1a, 0px 3px 6px 0px #25292e1f; /** Medium resting shadow for cards and elevated surfaces */
     --skeletonLoader-bgColor: var(--base-color-neutral-5);
     --treeViewItem-leadingVisual-iconColor-rest: var(--base-color-blue-3);
     --underlineNav-borderColor-active: var(--base-color-coral-3);
     --avatar-bgColor: var(--base-color-neutral-0);
     --avatar-shadow: 0px 0px 0px 2px #ffffffcc;
     --base-color-inset: var(--base-color-neutral-0);
-    --bgColor-black: var(--base-color-neutral-13);
-    --bgColor-closed-emphasis: var(--bgColor-neutral-emphasis);
-    --bgColor-closed-muted: var(--bgColor-neutral-muted);
-    --bgColor-default: var(--base-color-neutral-0);
-    --bgColor-draft-emphasis: var(--bgColor-neutral-emphasis);
-    --bgColor-draft-muted: var(--bgColor-neutral-muted);
-    --bgColor-upsell-emphasis: var(--bgColor-done-emphasis);
-    --bgColor-upsell-muted: var(--bgColor-done-muted);
-    --bgColor-white: var(--base-color-neutral-0);
+    --bgColor-black: var(--base-color-neutral-13); /** Pure black background */
+    --bgColor-closed-emphasis: var(--bgColor-neutral-emphasis); /** Strong background for closed state badges and labels */
+    --bgColor-closed-muted: var(--bgColor-neutral-muted); /** Subtle background for closed state indicators (issues, PRs) */
+    --bgColor-default: var(--base-color-neutral-0); /** Default background color for pages and main content areas */
+    --bgColor-draft-emphasis: var(--bgColor-neutral-emphasis); /** Strong background for draft state badges and labels */
+    --bgColor-draft-muted: var(--bgColor-neutral-muted); /** Subtle background for draft state indicators */
+    --bgColor-upsell-emphasis: var(--bgColor-done-emphasis); /** Strong background for prominent upsell elements */
+    --bgColor-upsell-muted: var(--bgColor-done-muted); /** Subtle background for upsell and promotional content */
+    --bgColor-white: var(--base-color-neutral-0); /** Pure white background */
     --border-accent-emphasis: 0.0625rem solid #0349b4;
     --border-accent-muted: 0.0625rem solid #368cf9;
     --border-attention-emphasis: 0.0625rem solid #744500;
@@ -2159,13 +2149,13 @@
     --border-success-emphasis: 0.0625rem solid #0349b4;
     --border-success-muted: 0.0625rem solid #368cf9;
     --border-transparent: 0.0625rem solid #ffffff00;
-    --borderColor-closed-muted: var(--borderColor-default);
-    --borderColor-draft-emphasis: var(--borderColor-neutral-emphasis);
-    --borderColor-draft-muted: var(--borderColor-default);
-    --borderColor-emphasis: var(--borderColor-default);
-    --borderColor-muted: var(--borderColor-default);
-    --borderColor-upsell-emphasis: var(--borderColor-done-emphasis);
-    --borderColor-upsell-muted: var(--borderColor-done-muted);
+    --borderColor-closed-muted: var(--borderColor-default); /** Subtle border for closed state indicators */
+    --borderColor-draft-emphasis: var(--borderColor-neutral-emphasis); /** Strong border for draft state badges */
+    --borderColor-draft-muted: var(--borderColor-default); /** Subtle border for draft state indicators */
+    --borderColor-emphasis: var(--borderColor-default); /** Strong border for emphasis and visual weight */
+    --borderColor-muted: var(--borderColor-default); /** Subtle border for secondary elements and light separators */
+    --borderColor-upsell-emphasis: var(--borderColor-done-emphasis); /** Strong border for prominent upsell elements */
+    --borderColor-upsell-muted: var(--borderColor-done-muted); /** Subtle border for upsell and promotional content */
     --button-danger-bgColor-hover: var(--bgColor-danger-emphasis);
     --button-danger-bgColor-rest: var(--control-bgColor-rest);
     --button-danger-borderColor-active: var(--button-danger-borderColor-hover);
@@ -2266,16 +2256,16 @@
     --diffBlob-emptyLine-bgColor: var(--bgColor-muted);
     --diffBlob-emptyNum-bgColor: var(--bgColor-muted);
     --diffBlob-hunkLine-fgColor: var(--fgColor-muted);
-    --fgColor-black: var(--base-color-neutral-13);
-    --fgColor-closed: var(--fgColor-muted);
-    --fgColor-default: var(--base-color-neutral-13);
-    --fgColor-draft: var(--fgColor-neutral);
-    --fgColor-link: var(--fgColor-accent);
-    --fgColor-onEmphasis: var(--base-color-neutral-0);
-    --fgColor-onInverse: var(--base-color-neutral-0);
-    --fgColor-upsell: var(--fgColor-done);
-    --fgColor-white: var(--base-color-neutral-0);
-    --focus-outlineColor: var(--borderColor-accent-emphasis);
+    --fgColor-black: var(--base-color-neutral-13); /** Pure black text */
+    --fgColor-closed: var(--fgColor-muted); /** Text color for closed state indicators (issues, PRs) */
+    --fgColor-default: var(--base-color-neutral-13); /** Default text color for primary content and headings */
+    --fgColor-draft: var(--fgColor-neutral); /** Text color for draft state indicators */
+    --fgColor-link: var(--fgColor-accent); /** Text color for hyperlinks */
+    --fgColor-onEmphasis: var(--base-color-neutral-0); /** Text color for use on emphasis backgrounds */
+    --fgColor-onInverse: var(--base-color-neutral-0); /** Text color for use on inverse backgrounds */
+    --fgColor-upsell: var(--fgColor-done); /** Text color for upsell and promotional content */
+    --fgColor-white: var(--base-color-neutral-0); /** Pure white text */
+    --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
     --header-fgColor-default: #ffffffb3;
     --header-fgColor-logo: var(--base-color-neutral-0);
     --label-auburn-borderColor: var(--label-auburn-fgColor-rest);
@@ -2307,10 +2297,10 @@
     --progressBar-bgColor-severe: var(--bgColor-severe-emphasis);
     --progressBar-bgColor-sponsors: var(--bgColor-sponsors-emphasis);
     --progressBar-bgColor-success: var(--bgColor-success-emphasis);
-    --selection-bgColor: #0349b433;
-    --shadow-inset: inset 0px 1px 0px 0px #0104090a;
-    --shadow-resting-small: 0px 1px 1px 0px #0104090f, 0px 1px 3px 0px #0104090f;
-    --shadow-resting-xsmall: 0px 1px 1px 0px #0104090f;
+    --selection-bgColor: #0349b433; /** Background color for text selection highlights */
+    --shadow-inset: inset 0px 1px 0px 0px #0104090a; /** Inset shadow for recessed elements */
+    --shadow-resting-small: 0px 1px 1px 0px #0104090a, 0px 1px 2px 0px #01040908; /** Small resting shadow for buttons and interactive elements */
+    --shadow-resting-xsmall: 0px 1px 1px 0px #0104090d; /** Extra small resting shadow for minimal elevation */
     --sideNav-bgColor-selected: var(--base-color-neutral-0);
     --timelineBadge-bgColor: var(--bgColor-muted);
     --tooltip-bgColor: var(--bgColor-emphasis);
@@ -2325,8 +2315,8 @@
     --border-open-muted: var(--border-success-muted);
     --border-upsell-emphasis: 0.0625rem solid #622cbc;
     --border-upsell-muted: 0.0625rem solid #a371f7;
-    --borderColor-closed-emphasis: var(--borderColor-emphasis);
-    --borderColor-neutral-muted: var(--borderColor-muted);
+    --borderColor-closed-emphasis: var(--borderColor-emphasis); /** Strong border for closed state badges */
+    --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-rest: var(--button-danger-fgColor-rest);
@@ -2384,13 +2374,13 @@
     --diffBlob-expander-iconColor: var(--fgColor-default);
     --diffBlob-hunkNum-fgColor-hover: var(--fgColor-default);
     --diffBlob-hunkNum-fgColor-rest: var(--fgColor-default);
-    --focus-outline: 2px solid #0349b4;
+    --focus-outline: 2px solid #0349b4; /** Focus ring outline for keyboard navigation and accessibility. */
     --progressBar-track-bgColor: var(--bgColor-default);
     --reactionButton-selected-fgColor-rest: var(--fgColor-link);
-    --shadow-floating-large: 0px 0px 0px 1px #454c54, 0px 40px 80px 0px #25292e3d;
-    --shadow-floating-medium: 0px 0px 0px 1px #454c54, 0px 8px 16px -4px #25292e14, 0px 4px 32px -4px #25292e14, 0px 24px 48px -12px #25292e14, 0px 48px 96px -24px #25292e14;
-    --shadow-floating-small: 0px 0px 0px 1px #454c5480, 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f;
-    --shadow-floating-xlarge: 0px 0px 0px 1px #454c54, 0px 56px 112px 0px #25292e52;
+    --shadow-floating-large: 0px 0px 0px 1px #454c54, 0px 40px 80px 0px #25292e3d; /** Large floating shadow for modals and dialogs */
+    --shadow-floating-medium: 0px 0px 0px 1px #454c54, 0px 8px 16px -4px #25292e14, 0px 4px 32px -4px #25292e14, 0px 24px 48px -12px #25292e14, 0px 48px 96px -24px #25292e14; /** Medium floating shadow for popovers and action menus */
+    --shadow-floating-small: 0px 0px 0px 1px #454c5480, 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f; /** Small floating shadow for dropdowns, tooltips, and small overlays */
+    --shadow-floating-xlarge: 0px 0px 0px 1px #454c54, 0px 56px 112px 0px #25292e52; /** Extra large floating shadow for full-screen overlays and sheets */
     --tooltip-fgColor: var(--fgColor-onEmphasis);
     --underlineNav-borderColor-hover: var(--borderColor-muted);
     --border-neutral-muted: 0.0625rem solid #454c54;