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

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

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

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

@@ -1,3 +1,7 @@
+/**
+ * @spec See /DESIGN_TOKENS_SPEC.md for naming logic and semantic pairings.
+ * @rule Never use raw values (hex/px). Use semantic tokens ONLY.
+ */
 [data-color-mode="dark"][data-dark-theme="dark_dimmed"],
 [data-color-mode="auto"][data-light-theme="dark_dimmed"] {
   --button-danger-fgColor-active: #ffffff;
@@ -842,14 +846,14 @@
   --selectMenu-borderColor: var(--borderColor-default);
   --selection-bgColor: #316dcab3; /** Background color for text selection highlights */
   --shadow-floating-large: 0px 0px 0px 1px #3d444d, 0px 24px 48px 0px #010409; /** Large floating shadow for modals and dialogs */
-  --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
-  --shadow-floating-medium: 0px 0px 0px 1px #3d444d, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966;
+  --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Legacy floating shadow for backward compatibility */
+  --shadow-floating-medium: 0px 0px 0px 1px #3d444d, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
   --shadow-floating-small: 0px 0px 0px 1px #3d444d, 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
-  --shadow-floating-xlarge: 0px 0px 0px 1px #3d444d, 0px 32px 64px 0px #010409;
-  --shadow-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-xlarge: 0px 0px 0px 1px #3d444d, 0px 32px 64px 0px #010409; /** Extra large floating shadow for full-screen overlays and sheets */
+  --shadow-inset: inset 0px 1px 0px 0px #0104093d; /** Inset shadow for recessed elements */
+  --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+  --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999; /** Small resting shadow for buttons and interactive elements */
+  --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc; /** Extra small resting shadow for minimal elevation */
   --tooltip-bgColor: var(--bgColor-emphasis);
   --tooltip-fgColor: var(--fgColor-onEmphasis);
   --treeViewItem-leadingVisual-iconColor-rest: var(--fgColor-muted);
@@ -1739,14 +1743,14 @@
     --selectMenu-borderColor: var(--borderColor-default);
     --selection-bgColor: #316dcab3; /** Background color for text selection highlights */
     --shadow-floating-large: 0px 0px 0px 1px #3d444d, 0px 24px 48px 0px #010409; /** Large floating shadow for modals and dialogs */
-    --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966;
-    --shadow-floating-medium: 0px 0px 0px 1px #3d444d, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966;
+    --shadow-floating-legacy: 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Legacy floating shadow for backward compatibility */
+    --shadow-floating-medium: 0px 0px 0px 1px #3d444d, 0px 8px 16px -4px #01040966, 0px 4px 32px -4px #01040966, 0px 24px 48px -12px #01040966, 0px 48px 96px -24px #01040966; /** Medium floating shadow for popovers and action menus */
     --shadow-floating-small: 0px 0px 0px 1px #3d444d, 0px 6px 12px -3px #01040966, 0px 6px 18px 0px #01040966; /** Small floating shadow for dropdowns, tooltips, and small overlays */
-    --shadow-floating-xlarge: 0px 0px 0px 1px #3d444d, 0px 32px 64px 0px #010409;
-    --shadow-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-xlarge: 0px 0px 0px 1px #3d444d, 0px 32px 64px 0px #010409; /** Extra large floating shadow for full-screen overlays and sheets */
+    --shadow-inset: inset 0px 1px 0px 0px #0104093d; /** Inset shadow for recessed elements */
+    --shadow-resting-medium: 0px 1px 1px 0px #01040966, 0px 3px 6px 0px #010409cc; /** Medium resting shadow for cards and elevated surfaces */
+    --shadow-resting-small: 0px 1px 1px 0px #01040999, 0px 1px 3px 0px #01040999; /** Small resting shadow for buttons and interactive elements */
+    --shadow-resting-xsmall: 0px 1px 1px 0px #010409cc; /** Extra small resting shadow for minimal elevation */
     --tooltip-bgColor: var(--bgColor-emphasis);
     --tooltip-fgColor: var(--fgColor-onEmphasis);
     --treeViewItem-leadingVisual-iconColor-rest: var(--fgColor-muted);

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

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

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

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

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

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

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

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

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

@@ -1,3 +1,7 @@
+/**
+ * @spec See /DESIGN_TOKENS_SPEC.md for naming logic and semantic pairings.
+ * @rule Never use raw values (hex/px). Use semantic tokens ONLY.
+ */
 [data-color-mode="light"][data-light-theme="light_colorblind_high_contrast"],
 [data-color-mode="auto"][data-light-theme="light_colorblind_high_contrast"] {
   --button-outline-bgColor-active: #033f9d;
@@ -620,8 +624,8 @@
   --reactionButton-selected-fgColor-hover: #023b95;
   --selectMenu-bgColor-active: #9cd7ff;
   --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: #dae0e7;
   --treeViewItem-leadingVisual-iconColor-rest: #368cf9;
   --underlineNav-borderColor-active: #cd3425;
@@ -803,9 +807,9 @@
   --progressBar-bgColor-sponsors: var(--bgColor-sponsors-emphasis);
   --progressBar-bgColor-success: var(--bgColor-success-emphasis);
   --selection-bgColor: #0349b433; /** Background color for text selection highlights */
-  --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;
+  --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: #ffffff;
   --timelineBadge-bgColor: var(--bgColor-muted);
   --tooltip-bgColor: var(--bgColor-emphasis);
@@ -883,9 +887,9 @@
   --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; /** 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;
+  --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;
+  --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;
@@ -1517,8 +1521,8 @@
     --reactionButton-selected-fgColor-hover: #023b95;
     --selectMenu-bgColor-active: #9cd7ff;
     --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: #dae0e7;
     --treeViewItem-leadingVisual-iconColor-rest: #368cf9;
     --underlineNav-borderColor-active: #cd3425;
@@ -1700,9 +1704,9 @@
     --progressBar-bgColor-sponsors: var(--bgColor-sponsors-emphasis);
     --progressBar-bgColor-success: var(--bgColor-success-emphasis);
     --selection-bgColor: #0349b433; /** Background color for text selection highlights */
-    --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;
+    --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: #ffffff;
     --timelineBadge-bgColor: var(--bgColor-muted);
     --tooltip-bgColor: var(--bgColor-emphasis);
@@ -1780,9 +1784,9 @@
     --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; /** 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;
+    --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;
+    --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;

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

@@ -1,3 +1,7 @@
+/**
+ * @spec See /DESIGN_TOKENS_SPEC.md for naming logic and semantic pairings.
+ * @rule Never use raw values (hex/px). Use semantic tokens ONLY.
+ */
 [data-color-mode="light"][data-light-theme="light_colorblind"],
 [data-color-mode="auto"][data-light-theme="light_colorblind"] {
   --button-outline-bgColor-active: #0757ba;
@@ -633,8 +637,8 @@
   --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;
@@ -802,9 +806,9 @@
   --progressBar-bgColor-success: var(--bgColor-success-emphasis);
   --progressBar-track-bgColor: var(--borderColor-default);
   --selection-bgColor: #0969da33; /** Background color for text selection highlights */
-  --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;
+  --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);
@@ -888,9 +892,9 @@
   --buttonKeybindingHint-danger-borderColor-rest: var(--buttonKeybindingHint-default-borderColor-rest);
   --buttonKeybindingHint-danger-fgColor-disabled: var(--buttonKeybindingHint-default-fgColor-disabled);
   --shadow-floating-large: 0px 0px 0px 1px #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;
+  --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;
+  --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);
@@ -1530,8 +1534,8 @@
     --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;
@@ -1699,9 +1703,9 @@
     --progressBar-bgColor-success: var(--bgColor-success-emphasis);
     --progressBar-track-bgColor: var(--borderColor-default);
     --selection-bgColor: #0969da33; /** Background color for text selection highlights */
-    --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;
+    --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);
@@ -1785,9 +1789,9 @@
     --buttonKeybindingHint-danger-borderColor-rest: var(--buttonKeybindingHint-default-borderColor-rest);
     --buttonKeybindingHint-danger-fgColor-disabled: var(--buttonKeybindingHint-default-fgColor-disabled);
     --shadow-floating-large: 0px 0px 0px 1px #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;
+    --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;
+    --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);