From 4f0a772a21a23b6010d6b6e0995a1c72a7c351e1 Mon Sep 17 00:00:00 2001
From: Zeno Kapitein <zeno@gitbook.io>
Date: Fri, 14 Mar 2025 18:24:25 +0100
Subject: [PATCH] Override tint lightness if supplied color is out of bounds
 (#2983)

---
 .changeset/large-toys-travel.md        |  5 +++++
 packages/colors/src/transformations.ts | 16 +++++++++++++++-
 2 files changed, 20 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/large-toys-travel.md

diff --git a/.changeset/large-toys-travel.md b/.changeset/large-toys-travel.md
new file mode 100644
index 000000000..e4c82ce53
--- /dev/null
+++ b/.changeset/large-toys-travel.md
@@ -0,0 +1,5 @@
+---
+"@gitbook/colors": minor
+---
+
+Override tint lightness if supplied color is out of bounds
diff --git a/packages/colors/src/transformations.ts b/packages/colors/src/transformations.ts
index f25ad26ca..39c290c57 100644
--- a/packages/colors/src/transformations.ts
+++ b/packages/colors/src/transformations.ts
@@ -184,6 +184,7 @@ export function colorScale(
     const mixColor = mix?.color ? rgbToOklch(hexToRgbArray(mix.color)) : null;
     const foregroundColor = rgbToOklch(hexToRgbArray(foreground));
     const backgroundColor = rgbToOklch(hexToRgbArray(background));
+    let mapping = darkMode ? colorMixMapping.dark : colorMixMapping.light;
 
     if (mixColor && mix?.ratio && mix.ratio > 0) {
         // If defined, we mix in a (tiny) bit of the mix color with the base color.
@@ -192,7 +193,20 @@ export function colorScale(
         baseColor.H = mix.color === DEFAULT_TINT_COLOR ? baseColor.H : mixColor.H;
     }
 
-    const mapping = darkMode ? colorMixMapping.dark : colorMixMapping.light;
+    if (
+        (darkMode && baseColor.L < backgroundColor.L) ||
+        (!darkMode && baseColor.L > backgroundColor.L)
+    ) {
+        // If the supplied color is outside of our lightness bounds, use the supplied color's lightness.
+        // This is mostly used to allow darker-than-dark backgrounds for brands that specifically want that look.
+        const difference = (backgroundColor.L - baseColor.L) / backgroundColor.L;
+        backgroundColor.L = baseColor.L;
+        // At the edges of the scale, the subtle lightness changes stop being perceptible. We need to amp up our mapping to still stand out.
+        const amplifier = 1;
+        mapping = mapping.map((step, index) =>
+            index < 9 ? step + step * amplifier * difference : step
+        );
+    }
 
     const result = [];