refactor: simplify color block generation in SCSS and enhance contrast logic

Author: pixelflips

docs/lib/sage-frontend/stylesheets/docs/_colors.scss

@@ -43,78 +43,55 @@
 }
 
 // build individual color blocks
+/* stylelint-disable max-nesting-depth */
 @each $name, $color in $sage-colors {
-  // Skip if $color is not a map (handles aliases like primary, sage, orange, charcoal)
-  @if type-of($color) == map {
-    @each $value, $map in $color {
-      // Skip if $map is null or not a map (safety check)
-      @if $map != null and type-of($map) == map {
-        // Use sage-color-hex() for SCSS operations (lightness() requires actual color values)
-        $hex: sage-color-hex($name, $value);
-
-        // Determine class name for $value == 50
-        $classname: ".color-#{"" + $name}-#{$value}";
-
-        /* stylelint-disable max-nesting-depth, block-closing-brace-newline-after */
-        // This should be numeric, not string
-        @if ($value == 50) {
-          $classname: ".color-#{"" + $name}-0#{$value}";
-        }
-
-        #{$classname} {
-          padding: sage-spacing(sm) sage-spacing();
-          font-size: sage-font-size(body);
-          background: $hex;
-
-          // Use lightness-based logic for dynamic contrast (prioritized for better readability)
-          // If background is dark (lightness < 65%), use light text; otherwise use dark text
-          @if (lightness($hex) < 65) {
-            // Dark background → use light text color
-            @if ($name == white) {
-              color: sage-color(black);
-            } @else if ($name == grey or $name == black or $name == charcoal) {
-              color: sage-color(white);
-            } @else {
-              // For colored backgrounds, use the lightest shade (100) or white
-              color: sage-color($name, 100);
-            }
-          } @else {
-            // Light background → use dark text color
-            @if ($name == white) {
-              color: sage-color(grey, 950);
-            } @else if ($name == black or $name == charcoal) {
-              color: sage-color(white);
-            } @else if ($name == grey) {
-              color: sage-color(grey, 950);
-            } @else {
-              // For colored backgrounds, use a darker shade (400+) for contrast
-              color: sage-color($name, 400);
-            }
-          }
-
-          &::after {
-            content: "#{$hex}";
-            padding-inline-start: sage-spacing(xs);
-            font-weight: sage-font-weight(semibold);
-            text-transform: uppercase;
-          }
-        }
-        /* stylelint-enable max-nesting-depth, block-closing-brace-newline-after */
+  @each $value, $map in $color {
+    // Use sage-color-hex() for actual hex values (needed for color documentation display)
+    // This ensures colors are displayed correctly regardless of dark/light mode
+    $hex: sage-color-hex($name, $value);
+
+    // Determine class name for $value == 50
+    $classname: ".color-#{"" + $name}-#{$value}";
+
+    // This should be numeric, not string
+    @if ($value == 50) {
+      $classname: ".color-#{"" + $name}-0#{$value}";
+    }
+
+    #{$classname} {
+      padding: sage-spacing(sm) sage-spacing();
+      font-size: sage-font-size(body);
+      background: $hex;
+
+      // Simple lightness-based contrast: white text on dark, black text on light
+      @if (lightness($hex) < 55%) {
+        color: sage-color-hex(white);
+      }
+      @else {
+        color: sage-color-hex(grey, 950);
+      }
+
+      &::after {
+        content: "#{$hex}";
+        padding-inline-start: sage-spacing(xs);
+        font-weight: sage-font-weight(semibold);
+        text-transform: uppercase;
       }
     }
   }
 }
+/* stylelint-enable max-nesting-depth */
 
 [class*="color-"]:only-child {
   border-radius: sage-border(radius);
 }
 
 .color-white-100 {
   border-radius: sage-border(radius);
-  border: 1px solid sage-color(grey, 800);
-  box-shadow: inset 0 0 0.0625rem sage-color(grey, 800);
+  border: 1px solid sage-color-hex(grey, 300);
+  box-shadow: inset 0 0 0.0625rem sage-color-hex(grey, 300);
 }
 
 .color-black-100 {
-  color: sage-color(white);
+  color: sage-color-hex(white);
 }