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

package/dist/css/functional/themes/light.css

@@ -1,6 +1,10 @@
+/**
+ * @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="light"][data-light-theme="light"],
 [data-color-mode="auto"][data-light-theme="light"] {
-  --bgColor-success-emphasis: #1f883d;
+  --bgColor-success-emphasis: #1f883d; /** Strong success background for prominent positive actions */
   --button-outline-bgColor-active: #0757ba;
   --button-primary-bgColor-active: #197935;
   --button-primary-bgColor-disabled: #95d8a6;
@@ -10,50 +14,50 @@
   --color-ansi-cyan-bright: #3192aa;
   --control-checked-bgColor-active: #0757ba;
   --control-checked-bgColor-hover: #0860ca;
-  --fgColor-danger: #d1242f;
+  --fgColor-danger: #d1242f; /** Danger text for errors and destructive actions */
   --reactionButton-selected-bgColor-hover: #caecff;
   --avatarStack-fade-bgColor-default: #c8d1da;
   --avatarStack-fade-bgColor-muted: #dae0e7;
-  --bgColor-accent-emphasis: #0969da;
-  --bgColor-accent-muted: #ddf4ff;
-  --bgColor-attention-emphasis: #9a6700;
-  --bgColor-attention-muted: #fff8c5;
-  --bgColor-danger-emphasis: #cf222e;
-  --bgColor-danger-muted: #ffebe9;
-  --bgColor-disabled: #eff2f5;
-  --bgColor-done-emphasis: #8250df;
-  --bgColor-done-muted: #fbefff;
-  --bgColor-emphasis: #25292e;
-  --bgColor-inverse: #25292e;
-  --bgColor-muted: #f6f8fa;
-  --bgColor-neutral-emphasis: #59636e;
-  --bgColor-neutral-muted: #818b981f;
-  --bgColor-open-emphasis: var(--bgColor-success-emphasis);
-  --bgColor-severe-emphasis: #bc4c00;
-  --bgColor-severe-muted: #fff1e5;
-  --bgColor-sponsors-emphasis: #bf3989;
-  --bgColor-sponsors-muted: #ffeff7;
-  --bgColor-success-muted: #dafbe1;
-  --bgColor-transparent: #ffffff00;
-  --borderColor-accent-emphasis: #0969da;
-  --borderColor-accent-muted: #54aeff66;
-  --borderColor-attention-emphasis: #9a6700;
-  --borderColor-attention-muted: #d4a72c66;
-  --borderColor-danger-emphasis: #cf222e;
-  --borderColor-danger-muted: #ff818266;
-  --borderColor-default: #d1d9e0;
-  --borderColor-disabled: #818b981a;
-  --borderColor-done-emphasis: #8250df;
-  --borderColor-done-muted: #c297ff66;
-  --borderColor-emphasis: #818b98;
-  --borderColor-neutral-emphasis: #59636e;
-  --borderColor-severe-emphasis: #bc4c00;
-  --borderColor-severe-muted: #fb8f4466;
-  --borderColor-sponsors-emphasis: #bf3989;
-  --borderColor-sponsors-muted: #ff80c866;
-  --borderColor-success-emphasis: #1a7f37;
-  --borderColor-success-muted: #4ac26b66;
-  --borderColor-transparent: #ffffff00;
+  --bgColor-accent-emphasis: #0969da; /** Strong accent background for active states and focused states */
+  --bgColor-accent-muted: #ddf4ff; /** Subtle accent background for informational or selected elements */
+  --bgColor-attention-emphasis: #9a6700; /** Strong attention background for prominent warnings */
+  --bgColor-attention-muted: #fff8c5; /** Subtle attention background for warnings and caution states */
+  --bgColor-danger-emphasis: #cf222e; /** Emphasized danger background for critical errors and delete confirmations */
+  --bgColor-danger-muted: #ffebe9; /** Muted danger background for error states and destructive action contexts */
+  --bgColor-disabled: #eff2f5; /** Background for disabled interactive elements */
+  --bgColor-done-emphasis: #8250df; /** Strong background for completed/done state badges and labels */
+  --bgColor-done-muted: #fbefff; /** Subtle background for completed/done state indicators */
+  --bgColor-emphasis: #25292e; /** High-emphasis dark background for strong visual contrast */
+  --bgColor-inverse: #25292e; /** Inverse background that flips between light and dark modes */
+  --bgColor-muted: #f6f8fa; /** Muted background for secondary content areas and subtle grouping */
+  --bgColor-neutral-emphasis: #59636e; /** Strong neutral background for prominent neutral elements */
+  --bgColor-neutral-muted: #818b981f; /** Subtle neutral background for tags, labels, and secondary UI elements */
+  --bgColor-open-emphasis: var(--bgColor-success-emphasis); /** Strong background for open state badges and labels */
+  --bgColor-severe-emphasis: #bc4c00; /** Strong severe background for prominent high-priority warnings */
+  --bgColor-severe-muted: #fff1e5; /** Subtle severe background for high-priority warnings */
+  --bgColor-sponsors-emphasis: #bf3989; /** Strong background for prominent GitHub Sponsors elements */
+  --bgColor-sponsors-muted: #ffeff7; /** Subtle background for GitHub Sponsors content */
+  --bgColor-success-muted: #dafbe1; /** Subtle success background for positive feedback and completed states */
+  --bgColor-transparent: #ffffff00; /** Fully transparent background */
+  --borderColor-accent-emphasis: #0969da; /** Strong accent border for selected or focused elements */
+  --borderColor-accent-muted: #54aeff66; /** Subtle accent border for selected or focused elements */
+  --borderColor-attention-emphasis: #9a6700; /** Strong attention border for prominent warnings */
+  --borderColor-attention-muted: #d4a72c66; /** Subtle attention border for warnings and caution states */
+  --borderColor-danger-emphasis: #cf222e; /** Strong danger border for destructive actions and errors */
+  --borderColor-danger-muted: #ff818266; /** Subtle danger border for errors and destructive contexts */
+  --borderColor-default: #d1d9e0; /** Default border color for most UI elements */
+  --borderColor-disabled: #818b981a; /** Border color for disabled interactive elements */
+  --borderColor-done-emphasis: #8250df; /** Strong border for completed/done state badges */
+  --borderColor-done-muted: #c297ff66; /** Subtle border for completed/done state indicators */
+  --borderColor-emphasis: #818b98; /** Strong border for emphasis and visual weight */
+  --borderColor-neutral-emphasis: #59636e; /** Strong neutral semantic border */
+  --borderColor-severe-emphasis: #bc4c00; /** Strong severe border for prominent high-priority warnings */
+  --borderColor-severe-muted: #fb8f4466; /** Subtle severe border for high-priority warnings */
+  --borderColor-sponsors-emphasis: #bf3989; /** Strong border for prominent GitHub Sponsors elements */
+  --borderColor-sponsors-muted: #ff80c866; /** Subtle border for GitHub Sponsors content */
+  --borderColor-success-emphasis: #1a7f37; /** Strong success border for prominent positive elements */
+  --borderColor-success-muted: #4ac26b66; /** Subtle success border for positive feedback elements */
+  --borderColor-transparent: #ffffff00; /** Fully transparent border */
   --button-danger-bgColor-active: #a40e26;
   --button-danger-fgColor-disabled: #d1242f80;
   --button-danger-fgColor-rest: var(--fgColor-danger);
@@ -480,16 +484,16 @@
   --display-yellow-scale-7: #704d00;
   --display-yellow-scale-8: #5c3d00;
   --display-yellow-scale-9: #422b00;
-  --fgColor-accent: #0969da;
-  --fgColor-attention: #9a6700;
-  --fgColor-closed: var(--fgColor-danger);
-  --fgColor-disabled: #818b98;
-  --fgColor-done: #8250df;
-  --fgColor-muted: #59636e;
-  --fgColor-neutral: #59636e;
-  --fgColor-severe: #bc4c00;
-  --fgColor-sponsors: #bf3989;
-  --fgColor-success: #1a7f37;
+  --fgColor-accent: #0969da; /** Accent text for links and interactive elements */
+  --fgColor-attention: #9a6700; /** Attention text for warnings and caution states */
+  --fgColor-closed: var(--fgColor-danger); /** Text color for closed state indicators (issues, PRs) */
+  --fgColor-disabled: #818b98; /** Text color for disabled interactive elements */
+  --fgColor-done: #8250df; /** Text color for completed/done state indicators */
+  --fgColor-muted: #59636e; /** Muted text for secondary content and less important information */
+  --fgColor-neutral: #59636e; /** Neutral semantic text for icons and secondary elements */
+  --fgColor-severe: #bc4c00; /** Severe text for high-priority warnings */
+  --fgColor-sponsors: #bf3989; /** Text color for GitHub Sponsors content */
+  --fgColor-success: #1a7f37; /** Success text for positive feedback and completed states */
   --header-bgColor: #25292e;
   --header-borderColor-divider: #818b98;
   --headerSearch-bgColor: #25292e;
@@ -636,25 +640,25 @@
   --reactionButton-selected-fgColor-hover: #0550ae;
   --selectMenu-bgColor-active: #b6e3ff;
   --selectMenu-borderColor: #ffffff00;
-  --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: #818b981a;
   --topicTag-borderColor: #ffffff00;
   --treeViewItem-leadingVisual-iconColor-rest: #54aeff;
   --underlineNav-borderColor-active: #fd8c73;
   --avatar-bgColor: #ffffff;
   --avatar-shadow: 0px 0px 0px 2px #ffffffcc;
-  --bgColor-black: #1f2328;
-  --bgColor-closed-emphasis: var(--bgColor-danger-emphasis);
-  --bgColor-closed-muted: var(--bgColor-danger-muted);
-  --bgColor-default: #ffffff;
-  --bgColor-draft-emphasis: var(--bgColor-neutral-emphasis);
-  --bgColor-draft-muted: var(--bgColor-neutral-muted);
-  --bgColor-inset: var(--bgColor-muted);
-  --bgColor-open-muted: var(--bgColor-success-muted);
-  --bgColor-upsell-emphasis: var(--bgColor-done-emphasis);
-  --bgColor-upsell-muted: var(--bgColor-done-muted);
-  --bgColor-white: #ffffff;
+  --bgColor-black: #1f2328; /** Pure black background */
+  --bgColor-closed-emphasis: var(--bgColor-danger-emphasis); /** Strong background for closed state badges and labels */
+  --bgColor-closed-muted: var(--bgColor-danger-muted); /** Subtle background for closed state indicators (issues, PRs) */
+  --bgColor-default: #ffffff; /** 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-inset: var(--bgColor-muted); /** Inset background for recessed content areas like wells or sunken panels */
+  --bgColor-open-muted: var(--bgColor-success-muted); /** Subtle background for open state indicators (issues, PRs) */
+  --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: #ffffff; /** Pure white background */
   --border-accent-emphasis: 0.0625rem solid #0969da;
   --border-accent-muted: 0.0625rem solid #54aeff66;
   --border-attention-emphasis: 0.0625rem solid #9a6700;
@@ -674,15 +678,15 @@
   --border-success-emphasis: 0.0625rem solid #1a7f37;
   --border-success-muted: 0.0625rem solid #4ac26b66;
   --border-transparent: 0.0625rem solid #ffffff00;
-  --borderColor-closed-emphasis: var(--borderColor-danger-emphasis);
-  --borderColor-closed-muted: var(--borderColor-danger-muted);
-  --borderColor-draft-emphasis: var(--borderColor-neutral-emphasis);
-  --borderColor-muted: #d1d9e0b3;
-  --borderColor-open-emphasis: var(--borderColor-success-emphasis);
-  --borderColor-open-muted: var(--borderColor-success-muted);
-  --borderColor-translucent: #1f232826;
-  --borderColor-upsell-emphasis: var(--borderColor-done-emphasis);
-  --borderColor-upsell-muted: var(--borderColor-done-muted);
+  --borderColor-closed-emphasis: var(--borderColor-danger-emphasis); /** Strong border for closed state badges */
+  --borderColor-closed-muted: var(--borderColor-danger-muted); /** Subtle border for closed state indicators */
+  --borderColor-draft-emphasis: var(--borderColor-neutral-emphasis); /** Strong border for draft state badges */
+  --borderColor-muted: #d1d9e0b3; /** Subtle border for secondary elements and light separators */
+  --borderColor-open-emphasis: var(--borderColor-success-emphasis); /** Strong border for open state badges */
+  --borderColor-open-muted: var(--borderColor-success-muted); /** Subtle border for open state indicators */
+  --borderColor-translucent: #1f232826; /** Semi-transparent border for overlays and layered elements */
+  --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-fgColor-active: #ffffff;
@@ -779,16 +783,16 @@
   --diffBlob-hunkLine-bgColor: var(--bgColor-accent-muted);
   --diffBlob-hunkLine-fgColor: var(--fgColor-muted);
   --diffBlob-hunkNum-bgColor-hover: var(--bgColor-accent-emphasis);
-  --fgColor-black: #1f2328;
-  --fgColor-default: #1f2328;
-  --fgColor-draft: var(--fgColor-neutral);
-  --fgColor-link: var(--fgColor-accent);
-  --fgColor-onEmphasis: #ffffff;
-  --fgColor-onInverse: #ffffff;
-  --fgColor-open: var(--fgColor-success);
-  --fgColor-upsell: var(--fgColor-done);
-  --fgColor-white: #ffffff;
-  --focus-outlineColor: var(--borderColor-accent-emphasis);
+  --fgColor-black: #1f2328; /** Pure black text */
+  --fgColor-default: #1f2328; /** 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: #ffffff; /** Text color for use on emphasis backgrounds */
+  --fgColor-onInverse: #ffffff; /** Text color for use on inverse backgrounds */
+  --fgColor-open: var(--fgColor-success); /** Text color for open state indicators (issues, PRs) */
+  --fgColor-upsell: var(--fgColor-done); /** Text color for upsell and promotional content */
+  --fgColor-white: #ffffff; /** Pure white text */
+  --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
   --header-fgColor-default: #ffffffb3;
   --header-fgColor-logo: #ffffff;
   --overlay-bgColor: #ffffff;
@@ -801,10 +805,10 @@
   --progressBar-bgColor-severe: var(--bgColor-severe-emphasis);
   --progressBar-bgColor-sponsors: var(--bgColor-sponsors-emphasis);
   --progressBar-track-bgColor: var(--borderColor-default);
-  --selection-bgColor: #0969da33;
-  --shadow-inset: inset 0px 1px 0px 0px #1f23280a;
-  --shadow-resting-small: 0px 1px 1px 0px #1f23280f, 0px 1px 3px 0px #1f23280f;
-  --shadow-resting-xsmall: 0px 1px 1px 0px #1f23280f;
+  --selection-bgColor: #0969da33; /** Background color for text selection highlights */
+  --shadow-inset: inset 0px 1px 0px 0px #1f23280a; /** Inset shadow for recessed elements */
+  --shadow-resting-small: 0px 1px 1px 0px #1f23280a, 0px 1px 2px 0px #1f232808; /** Small resting shadow for buttons and interactive elements */
+  --shadow-resting-xsmall: 0px 1px 1px 0px #1f23280d; /** Extra small resting shadow for minimal elevation */
   --sideNav-bgColor-selected: #ffffff;
   --timelineBadge-bgColor: var(--bgColor-muted);
   --tooltip-bgColor: var(--bgColor-emphasis);
@@ -817,7 +821,7 @@
   --border-open-muted: var(--border-success-muted);
   --border-upsell-emphasis: 0.0625rem solid #8250df;
   --border-upsell-muted: 0.0625rem solid #c297ff66;
-  --borderColor-neutral-muted: var(--borderColor-muted);
+  --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-default-bgColor-disabled: var(--control-bgColor-disabled);
@@ -872,13 +876,13 @@
   --diffBlob-deletionWord-fgColor: var(--fgColor-default);
   --diffBlob-hunkNum-fgColor-hover: var(--fgColor-onEmphasis);
   --diffBlob-hunkNum-fgColor-rest: var(--fgColor-default);
-  --focus-outline: 2px solid #0969da;
+  --focus-outline: 2px solid #0969da; /** Focus ring outline for keyboard navigation and accessibility. */
   --overlay-borderColor: #d1d9e080;
   --reactionButton-selected-fgColor-rest: var(--fgColor-link);
   --tooltip-fgColor: var(--fgColor-onEmphasis);
   --underlineNav-borderColor-hover: var(--borderColor-muted);
   --border-neutral-muted: 0.0625rem solid #d1d9e0b3;
-  --borderColor-draft-muted: var(--borderColor-neutral-muted);
+  --borderColor-draft-muted: var(--borderColor-neutral-muted); /** Subtle border for draft state indicators */
   --button-danger-borderColor-hover: var(--button-primary-borderColor-rest);
   --button-default-borderColor-hover: var(--button-default-borderColor-rest);
   --button-primary-borderColor-active: var(--button-primary-borderColor-rest);
@@ -887,17 +891,17 @@
   --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 #d1d9e0, 0px 40px 80px 0px #25292e3d;
-  --shadow-floating-medium: 0px 0px 0px 1px #d1d9e0, 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 #d1d9e080, 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f;
-  --shadow-floating-xlarge: 0px 0px 0px 1px #d1d9e0, 0px 56px 112px 0px #25292e52;
+  --shadow-floating-large: 0px 0px 0px 1px #d1d9e0, 0px 40px 80px 0px #25292e3d; /** Large floating shadow for modals and dialogs */
+  --shadow-floating-medium: 0px 0px 0px 1px #d1d9e0, 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 #d1d9e080, 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 #d1d9e0, 0px 56px 112px 0px #25292e52; /** Extra large floating shadow for full-screen overlays and sheets */
   --button-danger-borderColor-active: var(--button-danger-borderColor-hover);
   --button-outline-borderColor-hover: var(--button-primary-borderColor-hover);
   --button-outline-borderColor-active: var(--button-outline-borderColor-hover);
 }
 @media (prefers-color-scheme: dark) {
   [data-color-mode][data-color-mode="auto"][data-dark-theme="light"] {
-    --bgColor-success-emphasis: #1f883d;
+    --bgColor-success-emphasis: #1f883d; /** Strong success background for prominent positive actions */
     --button-outline-bgColor-active: #0757ba;
     --button-primary-bgColor-active: #197935;
     --button-primary-bgColor-disabled: #95d8a6;
@@ -907,50 +911,50 @@
     --color-ansi-cyan-bright: #3192aa;
     --control-checked-bgColor-active: #0757ba;
     --control-checked-bgColor-hover: #0860ca;
-    --fgColor-danger: #d1242f;
+    --fgColor-danger: #d1242f; /** Danger text for errors and destructive actions */
     --reactionButton-selected-bgColor-hover: #caecff;
     --avatarStack-fade-bgColor-default: #c8d1da;
     --avatarStack-fade-bgColor-muted: #dae0e7;
-    --bgColor-accent-emphasis: #0969da;
-    --bgColor-accent-muted: #ddf4ff;
-    --bgColor-attention-emphasis: #9a6700;
-    --bgColor-attention-muted: #fff8c5;
-    --bgColor-danger-emphasis: #cf222e;
-    --bgColor-danger-muted: #ffebe9;
-    --bgColor-disabled: #eff2f5;
-    --bgColor-done-emphasis: #8250df;
-    --bgColor-done-muted: #fbefff;
-    --bgColor-emphasis: #25292e;
-    --bgColor-inverse: #25292e;
-    --bgColor-muted: #f6f8fa;
-    --bgColor-neutral-emphasis: #59636e;
-    --bgColor-neutral-muted: #818b981f;
-    --bgColor-open-emphasis: var(--bgColor-success-emphasis);
-    --bgColor-severe-emphasis: #bc4c00;
-    --bgColor-severe-muted: #fff1e5;
-    --bgColor-sponsors-emphasis: #bf3989;
-    --bgColor-sponsors-muted: #ffeff7;
-    --bgColor-success-muted: #dafbe1;
-    --bgColor-transparent: #ffffff00;
-    --borderColor-accent-emphasis: #0969da;
-    --borderColor-accent-muted: #54aeff66;
-    --borderColor-attention-emphasis: #9a6700;
-    --borderColor-attention-muted: #d4a72c66;
-    --borderColor-danger-emphasis: #cf222e;
-    --borderColor-danger-muted: #ff818266;
-    --borderColor-default: #d1d9e0;
-    --borderColor-disabled: #818b981a;
-    --borderColor-done-emphasis: #8250df;
-    --borderColor-done-muted: #c297ff66;
-    --borderColor-emphasis: #818b98;
-    --borderColor-neutral-emphasis: #59636e;
-    --borderColor-severe-emphasis: #bc4c00;
-    --borderColor-severe-muted: #fb8f4466;
-    --borderColor-sponsors-emphasis: #bf3989;
-    --borderColor-sponsors-muted: #ff80c866;
-    --borderColor-success-emphasis: #1a7f37;
-    --borderColor-success-muted: #4ac26b66;
-    --borderColor-transparent: #ffffff00;
+    --bgColor-accent-emphasis: #0969da; /** Strong accent background for active states and focused states */
+    --bgColor-accent-muted: #ddf4ff; /** Subtle accent background for informational or selected elements */
+    --bgColor-attention-emphasis: #9a6700; /** Strong attention background for prominent warnings */
+    --bgColor-attention-muted: #fff8c5; /** Subtle attention background for warnings and caution states */
+    --bgColor-danger-emphasis: #cf222e; /** Emphasized danger background for critical errors and delete confirmations */
+    --bgColor-danger-muted: #ffebe9; /** Muted danger background for error states and destructive action contexts */
+    --bgColor-disabled: #eff2f5; /** Background for disabled interactive elements */
+    --bgColor-done-emphasis: #8250df; /** Strong background for completed/done state badges and labels */
+    --bgColor-done-muted: #fbefff; /** Subtle background for completed/done state indicators */
+    --bgColor-emphasis: #25292e; /** High-emphasis dark background for strong visual contrast */
+    --bgColor-inverse: #25292e; /** Inverse background that flips between light and dark modes */
+    --bgColor-muted: #f6f8fa; /** Muted background for secondary content areas and subtle grouping */
+    --bgColor-neutral-emphasis: #59636e; /** Strong neutral background for prominent neutral elements */
+    --bgColor-neutral-muted: #818b981f; /** Subtle neutral background for tags, labels, and secondary UI elements */
+    --bgColor-open-emphasis: var(--bgColor-success-emphasis); /** Strong background for open state badges and labels */
+    --bgColor-severe-emphasis: #bc4c00; /** Strong severe background for prominent high-priority warnings */
+    --bgColor-severe-muted: #fff1e5; /** Subtle severe background for high-priority warnings */
+    --bgColor-sponsors-emphasis: #bf3989; /** Strong background for prominent GitHub Sponsors elements */
+    --bgColor-sponsors-muted: #ffeff7; /** Subtle background for GitHub Sponsors content */
+    --bgColor-success-muted: #dafbe1; /** Subtle success background for positive feedback and completed states */
+    --bgColor-transparent: #ffffff00; /** Fully transparent background */
+    --borderColor-accent-emphasis: #0969da; /** Strong accent border for selected or focused elements */
+    --borderColor-accent-muted: #54aeff66; /** Subtle accent border for selected or focused elements */
+    --borderColor-attention-emphasis: #9a6700; /** Strong attention border for prominent warnings */
+    --borderColor-attention-muted: #d4a72c66; /** Subtle attention border for warnings and caution states */
+    --borderColor-danger-emphasis: #cf222e; /** Strong danger border for destructive actions and errors */
+    --borderColor-danger-muted: #ff818266; /** Subtle danger border for errors and destructive contexts */
+    --borderColor-default: #d1d9e0; /** Default border color for most UI elements */
+    --borderColor-disabled: #818b981a; /** Border color for disabled interactive elements */
+    --borderColor-done-emphasis: #8250df; /** Strong border for completed/done state badges */
+    --borderColor-done-muted: #c297ff66; /** Subtle border for completed/done state indicators */
+    --borderColor-emphasis: #818b98; /** Strong border for emphasis and visual weight */
+    --borderColor-neutral-emphasis: #59636e; /** Strong neutral semantic border */
+    --borderColor-severe-emphasis: #bc4c00; /** Strong severe border for prominent high-priority warnings */
+    --borderColor-severe-muted: #fb8f4466; /** Subtle severe border for high-priority warnings */
+    --borderColor-sponsors-emphasis: #bf3989; /** Strong border for prominent GitHub Sponsors elements */
+    --borderColor-sponsors-muted: #ff80c866; /** Subtle border for GitHub Sponsors content */
+    --borderColor-success-emphasis: #1a7f37; /** Strong success border for prominent positive elements */
+    --borderColor-success-muted: #4ac26b66; /** Subtle success border for positive feedback elements */
+    --borderColor-transparent: #ffffff00; /** Fully transparent border */
     --button-danger-bgColor-active: #a40e26;
     --button-danger-fgColor-disabled: #d1242f80;
     --button-danger-fgColor-rest: var(--fgColor-danger);
@@ -1377,16 +1381,16 @@
     --display-yellow-scale-7: #704d00;
     --display-yellow-scale-8: #5c3d00;
     --display-yellow-scale-9: #422b00;
-    --fgColor-accent: #0969da;
-    --fgColor-attention: #9a6700;
-    --fgColor-closed: var(--fgColor-danger);
-    --fgColor-disabled: #818b98;
-    --fgColor-done: #8250df;
-    --fgColor-muted: #59636e;
-    --fgColor-neutral: #59636e;
-    --fgColor-severe: #bc4c00;
-    --fgColor-sponsors: #bf3989;
-    --fgColor-success: #1a7f37;
+    --fgColor-accent: #0969da; /** Accent text for links and interactive elements */
+    --fgColor-attention: #9a6700; /** Attention text for warnings and caution states */
+    --fgColor-closed: var(--fgColor-danger); /** Text color for closed state indicators (issues, PRs) */
+    --fgColor-disabled: #818b98; /** Text color for disabled interactive elements */
+    --fgColor-done: #8250df; /** Text color for completed/done state indicators */
+    --fgColor-muted: #59636e; /** Muted text for secondary content and less important information */
+    --fgColor-neutral: #59636e; /** Neutral semantic text for icons and secondary elements */
+    --fgColor-severe: #bc4c00; /** Severe text for high-priority warnings */
+    --fgColor-sponsors: #bf3989; /** Text color for GitHub Sponsors content */
+    --fgColor-success: #1a7f37; /** Success text for positive feedback and completed states */
     --header-bgColor: #25292e;
     --header-borderColor-divider: #818b98;
     --headerSearch-bgColor: #25292e;
@@ -1533,25 +1537,25 @@
     --reactionButton-selected-fgColor-hover: #0550ae;
     --selectMenu-bgColor-active: #b6e3ff;
     --selectMenu-borderColor: #ffffff00;
-    --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: #818b981a;
     --topicTag-borderColor: #ffffff00;
     --treeViewItem-leadingVisual-iconColor-rest: #54aeff;
     --underlineNav-borderColor-active: #fd8c73;
     --avatar-bgColor: #ffffff;
     --avatar-shadow: 0px 0px 0px 2px #ffffffcc;
-    --bgColor-black: #1f2328;
-    --bgColor-closed-emphasis: var(--bgColor-danger-emphasis);
-    --bgColor-closed-muted: var(--bgColor-danger-muted);
-    --bgColor-default: #ffffff;
-    --bgColor-draft-emphasis: var(--bgColor-neutral-emphasis);
-    --bgColor-draft-muted: var(--bgColor-neutral-muted);
-    --bgColor-inset: var(--bgColor-muted);
-    --bgColor-open-muted: var(--bgColor-success-muted);
-    --bgColor-upsell-emphasis: var(--bgColor-done-emphasis);
-    --bgColor-upsell-muted: var(--bgColor-done-muted);
-    --bgColor-white: #ffffff;
+    --bgColor-black: #1f2328; /** Pure black background */
+    --bgColor-closed-emphasis: var(--bgColor-danger-emphasis); /** Strong background for closed state badges and labels */
+    --bgColor-closed-muted: var(--bgColor-danger-muted); /** Subtle background for closed state indicators (issues, PRs) */
+    --bgColor-default: #ffffff; /** 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-inset: var(--bgColor-muted); /** Inset background for recessed content areas like wells or sunken panels */
+    --bgColor-open-muted: var(--bgColor-success-muted); /** Subtle background for open state indicators (issues, PRs) */
+    --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: #ffffff; /** Pure white background */
     --border-accent-emphasis: 0.0625rem solid #0969da;
     --border-accent-muted: 0.0625rem solid #54aeff66;
     --border-attention-emphasis: 0.0625rem solid #9a6700;
@@ -1571,15 +1575,15 @@
     --border-success-emphasis: 0.0625rem solid #1a7f37;
     --border-success-muted: 0.0625rem solid #4ac26b66;
     --border-transparent: 0.0625rem solid #ffffff00;
-    --borderColor-closed-emphasis: var(--borderColor-danger-emphasis);
-    --borderColor-closed-muted: var(--borderColor-danger-muted);
-    --borderColor-draft-emphasis: var(--borderColor-neutral-emphasis);
-    --borderColor-muted: #d1d9e0b3;
-    --borderColor-open-emphasis: var(--borderColor-success-emphasis);
-    --borderColor-open-muted: var(--borderColor-success-muted);
-    --borderColor-translucent: #1f232826;
-    --borderColor-upsell-emphasis: var(--borderColor-done-emphasis);
-    --borderColor-upsell-muted: var(--borderColor-done-muted);
+    --borderColor-closed-emphasis: var(--borderColor-danger-emphasis); /** Strong border for closed state badges */
+    --borderColor-closed-muted: var(--borderColor-danger-muted); /** Subtle border for closed state indicators */
+    --borderColor-draft-emphasis: var(--borderColor-neutral-emphasis); /** Strong border for draft state badges */
+    --borderColor-muted: #d1d9e0b3; /** Subtle border for secondary elements and light separators */
+    --borderColor-open-emphasis: var(--borderColor-success-emphasis); /** Strong border for open state badges */
+    --borderColor-open-muted: var(--borderColor-success-muted); /** Subtle border for open state indicators */
+    --borderColor-translucent: #1f232826; /** Semi-transparent border for overlays and layered elements */
+    --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-fgColor-active: #ffffff;
@@ -1676,16 +1680,16 @@
     --diffBlob-hunkLine-bgColor: var(--bgColor-accent-muted);
     --diffBlob-hunkLine-fgColor: var(--fgColor-muted);
     --diffBlob-hunkNum-bgColor-hover: var(--bgColor-accent-emphasis);
-    --fgColor-black: #1f2328;
-    --fgColor-default: #1f2328;
-    --fgColor-draft: var(--fgColor-neutral);
-    --fgColor-link: var(--fgColor-accent);
-    --fgColor-onEmphasis: #ffffff;
-    --fgColor-onInverse: #ffffff;
-    --fgColor-open: var(--fgColor-success);
-    --fgColor-upsell: var(--fgColor-done);
-    --fgColor-white: #ffffff;
-    --focus-outlineColor: var(--borderColor-accent-emphasis);
+    --fgColor-black: #1f2328; /** Pure black text */
+    --fgColor-default: #1f2328; /** 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: #ffffff; /** Text color for use on emphasis backgrounds */
+    --fgColor-onInverse: #ffffff; /** Text color for use on inverse backgrounds */
+    --fgColor-open: var(--fgColor-success); /** Text color for open state indicators (issues, PRs) */
+    --fgColor-upsell: var(--fgColor-done); /** Text color for upsell and promotional content */
+    --fgColor-white: #ffffff; /** Pure white text */
+    --focus-outlineColor: var(--borderColor-accent-emphasis); /** Outline color for focus states on interactive elements */
     --header-fgColor-default: #ffffffb3;
     --header-fgColor-logo: #ffffff;
     --overlay-bgColor: #ffffff;
@@ -1698,10 +1702,10 @@
     --progressBar-bgColor-severe: var(--bgColor-severe-emphasis);
     --progressBar-bgColor-sponsors: var(--bgColor-sponsors-emphasis);
     --progressBar-track-bgColor: var(--borderColor-default);
-    --selection-bgColor: #0969da33;
-    --shadow-inset: inset 0px 1px 0px 0px #1f23280a;
-    --shadow-resting-small: 0px 1px 1px 0px #1f23280f, 0px 1px 3px 0px #1f23280f;
-    --shadow-resting-xsmall: 0px 1px 1px 0px #1f23280f;
+    --selection-bgColor: #0969da33; /** Background color for text selection highlights */
+    --shadow-inset: inset 0px 1px 0px 0px #1f23280a; /** Inset shadow for recessed elements */
+    --shadow-resting-small: 0px 1px 1px 0px #1f23280a, 0px 1px 2px 0px #1f232808; /** Small resting shadow for buttons and interactive elements */
+    --shadow-resting-xsmall: 0px 1px 1px 0px #1f23280d; /** Extra small resting shadow for minimal elevation */
     --sideNav-bgColor-selected: #ffffff;
     --timelineBadge-bgColor: var(--bgColor-muted);
     --tooltip-bgColor: var(--bgColor-emphasis);
@@ -1714,7 +1718,7 @@
     --border-open-muted: var(--border-success-muted);
     --border-upsell-emphasis: 0.0625rem solid #8250df;
     --border-upsell-muted: 0.0625rem solid #c297ff66;
-    --borderColor-neutral-muted: var(--borderColor-muted);
+    --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-default-bgColor-disabled: var(--control-bgColor-disabled);
@@ -1769,13 +1773,13 @@
     --diffBlob-deletionWord-fgColor: var(--fgColor-default);
     --diffBlob-hunkNum-fgColor-hover: var(--fgColor-onEmphasis);
     --diffBlob-hunkNum-fgColor-rest: var(--fgColor-default);
-    --focus-outline: 2px solid #0969da;
+    --focus-outline: 2px solid #0969da; /** Focus ring outline for keyboard navigation and accessibility. */
     --overlay-borderColor: #d1d9e080;
     --reactionButton-selected-fgColor-rest: var(--fgColor-link);
     --tooltip-fgColor: var(--fgColor-onEmphasis);
     --underlineNav-borderColor-hover: var(--borderColor-muted);
     --border-neutral-muted: 0.0625rem solid #d1d9e0b3;
-    --borderColor-draft-muted: var(--borderColor-neutral-muted);
+    --borderColor-draft-muted: var(--borderColor-neutral-muted); /** Subtle border for draft state indicators */
     --button-danger-borderColor-hover: var(--button-primary-borderColor-rest);
     --button-default-borderColor-hover: var(--button-default-borderColor-rest);
     --button-primary-borderColor-active: var(--button-primary-borderColor-rest);
@@ -1784,10 +1788,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 #d1d9e0, 0px 40px 80px 0px #25292e3d;
-    --shadow-floating-medium: 0px 0px 0px 1px #d1d9e0, 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 #d1d9e080, 0px 6px 12px -3px #25292e0a, 0px 6px 18px 0px #25292e1f;
-    --shadow-floating-xlarge: 0px 0px 0px 1px #d1d9e0, 0px 56px 112px 0px #25292e52;
+    --shadow-floating-large: 0px 0px 0px 1px #d1d9e0, 0px 40px 80px 0px #25292e3d; /** Large floating shadow for modals and dialogs */
+    --shadow-floating-medium: 0px 0px 0px 1px #d1d9e0, 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 #d1d9e080, 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 #d1d9e0, 0px 56px 112px 0px #25292e52; /** Extra large floating shadow for full-screen overlays and sheets */
     --button-danger-borderColor-active: var(--button-danger-borderColor-hover);
     --button-outline-borderColor-hover: var(--button-primary-borderColor-hover);
     --button-outline-borderColor-active: var(--button-outline-borderColor-hover);

package/dist/css/functional/typography/typography.css

@@ -1,8 +1,8 @@
 :root {
-  --fontStack-monospace: ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace;
-  --fontStack-sansSerif: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
-  --fontStack-sansSerifDisplay: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
-  --fontStack-system: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
+  --fontStack-monospace: ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace; /** Monospace font stack for code, technical content, and tabular data. */
+  --fontStack-sansSerif: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; /** Sans-serif font stack for body text and general UI elements. */
+  --fontStack-sansSerifDisplay: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; /** Display font stack for headings and titles. Same as sansSerif but semantically distinct. */
+  --fontStack-system: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; /** System font stack optimized for cross-platform rendering. Primary font for all UI text. */
   --text-codeBlock-size: 0.8125rem;
   --text-codeInline-size: 0.9285em;
   --text-body-lineHeight-large: var(--base-text-lineHeight-normal);

package/dist/css/primitives.css

@@ -1,8 +1,13 @@
+/**
+ * @spec See /DESIGN_TOKENS_SPEC.md for naming logic and semantic pairings.
+ * @rule Never use raw values (hex/px). Use semantic tokens ONLY.
+ */
 @import './base/motion/motion.css';
 @import './base/size/size.css';
 @import './base/typography/typography.css';
 @import './functional/size/border.css';
 @import './functional/size/breakpoints.css';
+@import './functional/size/radius.css';
 @import './functional/size/size-coarse.css';
 @import './functional/size/size-fine.css';
 @import './functional/size/size.css';