color-value-tools 1.1.12 → 1.2.1

package/dist/cjs/index.js

@@ -130,15 +130,24 @@ const NAMED_COLORS = {
     springgreen: '#00ff7f', steelblue: '#4682b4', tan: '#d2b48c', teal: '#008080', thistle: '#d8bfd8',
     tomato: '#ff6347', turquoise: '#40e0d0', violet: '#ee82ee', wheat: '#f5deb3', white: '#ffffff',
     whitesmoke: '#f5f5f5', yellow: '#ffff00', yellowgreen: '#9acd32',
-    // Special CSS keywords
-    transparent: 'transparent', currentcolor: 'currentcolor', inherit: 'inherit', initial: 'initial', unset: 'unset',
+    // 'transparent' is the only CSS-wide keyword with an actual fixed color (fully
+    // transparent black) — normalizeColor() special-cases it before ever reaching
+    // this table (see the `str === 'transparent'` check), so this entry only
+    // matters for getColorType()/toNearestNamedColor(), which read the table
+    // directly. 'currentcolor'/'inherit'/'initial'/'unset' are deliberately NOT
+    // listed here: none of them has a color value of their own (they only resolve
+    // to one given surrounding DOM/CSSOM context this library never has access
+    // to), so treating them as resolvable named colors would mean fabricating an
+    // arbitrary RGB value with no way for a caller to tell it apart from a real
+    // one — see normalizeColor()'s `type: 'unknown'` fallback for these instead.
+    transparent: 'transparent',
 };
 function isCssVariable(value) {
     return value.trim().startsWith('var(--');
 }
 function isHexColor(value) {
     const trimmed = value.trim();
-    return /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6})$/.test(trimmed);
+    return /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/.test(trimmed);
 }
 function isOklchColor(value) {
     return /^\s*oklcha?\s*\(/i.test(value.trim());
@@ -479,11 +488,18 @@ function rgbaStringToRgba(str) {
     const parts = m[1].split(/,\s*/).map(p => p.trim());
     if (parts.length < 3)
         return null;
-    const parseChannel = (v) => v.endsWith('%') ? Math.round(parseFloat(v) * 2.55) : Math.round(parseFloat(v));
+    // Clamp channels to a valid byte and alpha to [0,1] — an out-of-range input
+    // like "rgb(300, -20, 0)" or "rgba(0,0,0,2)" is invalid CSS, but previously
+    // passed straight through unclamped, which could even corrupt downstream hex
+    // output (a negative channel stringifies with a leading "-" via toString(16)).
+    const parseChannel = (v) => {
+        const n = v.endsWith('%') ? parseFloat(v) * 2.55 : parseFloat(v);
+        return Math.round(Math.max(0, Math.min(255, n)));
+    };
     const r = parseChannel(parts[0]);
     const g = parseChannel(parts[1]);
     const b = parseChannel(parts[2]);
-    const a = parts[3] !== undefined ? parseFloat(parts[3]) : 1;
+    const a = parts[3] !== undefined ? Math.max(0, Math.min(1, parseFloat(parts[3]))) : 1;
     return { r, g, b, a };
 }
 function rgbToHsl({ r, g, b }) {
@@ -740,6 +756,16 @@ function normalizeColor(input) {
                 g = srgb.g;
                 b = srgb.b;
             }
+            else if (parsed.space === 'srgb-linear') {
+                // srgb-linear components are linear-light, not gamma-encoded — unlike
+                // plain srgb below, they need the linear-to-sRGB transfer function
+                // applied before scaling to a 0-255 byte. Without this, only the 0/1
+                // extremes happened to come out correct; any mid-range value (e.g. 0.5)
+                // converted as if it were already gamma-encoded, which is wrong.
+                r = Math.round(linearChanToSrgb(p3r) * 255);
+                g = Math.round(linearChanToSrgb(p3g) * 255);
+                b = Math.round(linearChanToSrgb(p3b) * 255);
+            }
             else {
                 r = Math.round(Math.max(0, Math.min(255, p3r * 255)));
                 g = Math.round(Math.max(0, Math.min(255, p3g * 255)));
@@ -778,10 +804,16 @@ function tetradic(color) {
     return [hex, rotateHue(hex, 90), rotateHue(hex, 180), rotateHue(hex, 270)];
 }
 function colorShades(color, steps = 9) {
-    var _a, _b;
+    var _a, _b, _c;
     const n = normalizeColor(color);
     const h = (_a = n.h) !== null && _a !== void 0 ? _a : 0;
     const s = (_b = n.s) !== null && _b !== void 0 ? _b : 0;
+    // steps - 1 === 0 below would otherwise divide by zero (NaN lightness, then
+    // a literal "#NaNNaNNaN" hex string) — a single shade is just the color's
+    // own lightness, same idea as interpolateColors() returning the midpoint
+    // for a 2-color, 1-step request.
+    if (steps <= 1)
+        return steps === 1 ? [hslToHex(h, s, (_c = n.l) !== null && _c !== void 0 ? _c : 50)] : [];
     const result = [];
     for (let i = 0; i < steps; i++) {
         const l = Math.round(100 - (i / (steps - 1)) * 100);
@@ -790,10 +822,13 @@ function colorShades(color, steps = 9) {
     return result;
 }
 function monochromatic(color, steps = 5) {
-    var _a, _b;
+    var _a, _b, _c;
     const n = normalizeColor(color);
     const h = (_a = n.h) !== null && _a !== void 0 ? _a : 0;
     const l = (_b = n.l) !== null && _b !== void 0 ? _b : 50;
+    // Same steps === 1 divide-by-zero guard as colorShades() above.
+    if (steps <= 1)
+        return steps === 1 ? [hslToHex(h, (_c = n.s) !== null && _c !== void 0 ? _c : 0, l)] : [];
     const result = [];
     for (let i = 0; i < steps; i++) {
         const s = Math.round((i / (steps - 1)) * 100);
@@ -1215,6 +1250,12 @@ function toNearestNamedColor(color) {
     let bestName = 'black';
     let bestDist = Infinity;
     for (const [name, hex] of Object.entries(NAMED_COLORS)) {
+        // Skip any non-hex entry (currently just a defensive guard — 'transparent'
+        // is the only such value left in the table, and it has no real RGB to
+        // compare against; hexToRgb() would otherwise silently fall back to
+        // normalizeHex()'s placeholder color for it).
+        if (hex[0] !== '#')
+            continue;
         const [nr, ng, nb] = hexToRgb(hex);
         const dist = Math.sqrt(Math.pow(r - nr, 2) + Math.pow(g - ng, 2) + Math.pow(b - nb, 2));
         if (dist < bestDist) {
@@ -1324,8 +1365,13 @@ function isReadableOnBackground(textColor, background, options) {
     const level = (_a = options === null || options === void 0 ? void 0 : options.level) !== null && _a !== void 0 ? _a : 'AA';
     const large = (_b = options === null || options === void 0 ? void 0 : options.largeText) !== null && _b !== void 0 ? _b : false;
     const minRequired = level === 'AAA' ? (large ? 4.5 : 7) : (large ? 3 : 4.5);
+    // The specific effective background color that minRatio was actually
+    // computed against — wcagLevel below is derived from this same color
+    // (never a hardcoded '#ffffff') so it can't disagree with minRatio/readable.
     let minRatio;
+    let effectiveBackground;
     if (typeof background === 'string') {
+        effectiveBackground = background;
         minRatio = contrastRatio(textColor, background);
     }
     else if (background.type === 'semi-transparent') {
@@ -1336,13 +1382,24 @@ function isReadableOnBackground(textColor, background, options) {
         const cr = Math.round(((_e = fg.r) !== null && _e !== void 0 ? _e : 0) * alpha + ((_f = bg.r) !== null && _f !== void 0 ? _f : 255) * (1 - alpha));
         const cg = Math.round(((_g = fg.g) !== null && _g !== void 0 ? _g : 0) * alpha + ((_h = bg.g) !== null && _h !== void 0 ? _h : 255) * (1 - alpha));
         const cb = Math.round(((_j = fg.b) !== null && _j !== void 0 ? _j : 0) * alpha + ((_k = bg.b) !== null && _k !== void 0 ? _k : 255) * (1 - alpha));
-        minRatio = contrastRatio(textColor, rgbToHex({ r: cr, g: cg, b: cb }));
+        effectiveBackground = rgbToHex({ r: cr, g: cg, b: cb });
+        minRatio = contrastRatio(textColor, effectiveBackground);
     }
     else {
-        const ratios = background.stops.map(stop => contrastRatio(textColor, stop));
-        minRatio = Math.min(...ratios);
+        // The worst-case stop (lowest ratio) drives both minRatio and wcagLevel.
+        let worstStop = background.stops[0];
+        let worstRatio = Infinity;
+        for (const stop of background.stops) {
+            const ratio = contrastRatio(textColor, stop);
+            if (ratio < worstRatio) {
+                worstRatio = ratio;
+                worstStop = stop;
+            }
+        }
+        effectiveBackground = worstStop;
+        minRatio = worstRatio;
     }
-    const wLevel = wcagLevel(textColor, typeof background === 'string' ? background : '#ffffff');
+    const wLevel = wcagLevel(textColor, effectiveBackground);
     return { readable: minRatio >= minRequired, minContrastRatio: +minRatio.toFixed(2), wcagLevel: wLevel };
 }
 function bestContrastPalette(background, palettes, options) {

package/dist/cli/src/index.js

@@ -130,15 +130,24 @@ const NAMED_COLORS = {
     springgreen: '#00ff7f', steelblue: '#4682b4', tan: '#d2b48c', teal: '#008080', thistle: '#d8bfd8',
     tomato: '#ff6347', turquoise: '#40e0d0', violet: '#ee82ee', wheat: '#f5deb3', white: '#ffffff',
     whitesmoke: '#f5f5f5', yellow: '#ffff00', yellowgreen: '#9acd32',
-    // Special CSS keywords
-    transparent: 'transparent', currentcolor: 'currentcolor', inherit: 'inherit', initial: 'initial', unset: 'unset',
+    // 'transparent' is the only CSS-wide keyword with an actual fixed color (fully
+    // transparent black) — normalizeColor() special-cases it before ever reaching
+    // this table (see the `str === 'transparent'` check), so this entry only
+    // matters for getColorType()/toNearestNamedColor(), which read the table
+    // directly. 'currentcolor'/'inherit'/'initial'/'unset' are deliberately NOT
+    // listed here: none of them has a color value of their own (they only resolve
+    // to one given surrounding DOM/CSSOM context this library never has access
+    // to), so treating them as resolvable named colors would mean fabricating an
+    // arbitrary RGB value with no way for a caller to tell it apart from a real
+    // one — see normalizeColor()'s `type: 'unknown'` fallback for these instead.
+    transparent: 'transparent',
 };
 function isCssVariable(value) {
     return value.trim().startsWith('var(--');
 }
 function isHexColor(value) {
     const trimmed = value.trim();
-    return /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6})$/.test(trimmed);
+    return /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/.test(trimmed);
 }
 function isOklchColor(value) {
     return /^\s*oklcha?\s*\(/i.test(value.trim());
@@ -479,11 +488,18 @@ function rgbaStringToRgba(str) {
     const parts = m[1].split(/,\s*/).map(p => p.trim());
     if (parts.length < 3)
         return null;
-    const parseChannel = (v) => v.endsWith('%') ? Math.round(parseFloat(v) * 2.55) : Math.round(parseFloat(v));
+    // Clamp channels to a valid byte and alpha to [0,1] — an out-of-range input
+    // like "rgb(300, -20, 0)" or "rgba(0,0,0,2)" is invalid CSS, but previously
+    // passed straight through unclamped, which could even corrupt downstream hex
+    // output (a negative channel stringifies with a leading "-" via toString(16)).
+    const parseChannel = (v) => {
+        const n = v.endsWith('%') ? parseFloat(v) * 2.55 : parseFloat(v);
+        return Math.round(Math.max(0, Math.min(255, n)));
+    };
     const r = parseChannel(parts[0]);
     const g = parseChannel(parts[1]);
     const b = parseChannel(parts[2]);
-    const a = parts[3] !== undefined ? parseFloat(parts[3]) : 1;
+    const a = parts[3] !== undefined ? Math.max(0, Math.min(1, parseFloat(parts[3]))) : 1;
     return { r, g, b, a };
 }
 function rgbToHsl({ r, g, b }) {
@@ -740,6 +756,16 @@ function normalizeColor(input) {
                 g = srgb.g;
                 b = srgb.b;
             }
+            else if (parsed.space === 'srgb-linear') {
+                // srgb-linear components are linear-light, not gamma-encoded — unlike
+                // plain srgb below, they need the linear-to-sRGB transfer function
+                // applied before scaling to a 0-255 byte. Without this, only the 0/1
+                // extremes happened to come out correct; any mid-range value (e.g. 0.5)
+                // converted as if it were already gamma-encoded, which is wrong.
+                r = Math.round(linearChanToSrgb(p3r) * 255);
+                g = Math.round(linearChanToSrgb(p3g) * 255);
+                b = Math.round(linearChanToSrgb(p3b) * 255);
+            }
             else {
                 r = Math.round(Math.max(0, Math.min(255, p3r * 255)));
                 g = Math.round(Math.max(0, Math.min(255, p3g * 255)));
@@ -778,10 +804,16 @@ function tetradic(color) {
     return [hex, rotateHue(hex, 90), rotateHue(hex, 180), rotateHue(hex, 270)];
 }
 function colorShades(color, steps = 9) {
-    var _a, _b;
+    var _a, _b, _c;
     const n = normalizeColor(color);
     const h = (_a = n.h) !== null && _a !== void 0 ? _a : 0;
     const s = (_b = n.s) !== null && _b !== void 0 ? _b : 0;
+    // steps - 1 === 0 below would otherwise divide by zero (NaN lightness, then
+    // a literal "#NaNNaNNaN" hex string) — a single shade is just the color's
+    // own lightness, same idea as interpolateColors() returning the midpoint
+    // for a 2-color, 1-step request.
+    if (steps <= 1)
+        return steps === 1 ? [hslToHex(h, s, (_c = n.l) !== null && _c !== void 0 ? _c : 50)] : [];
     const result = [];
     for (let i = 0; i < steps; i++) {
         const l = Math.round(100 - (i / (steps - 1)) * 100);
@@ -790,10 +822,13 @@ function colorShades(color, steps = 9) {
     return result;
 }
 function monochromatic(color, steps = 5) {
-    var _a, _b;
+    var _a, _b, _c;
     const n = normalizeColor(color);
     const h = (_a = n.h) !== null && _a !== void 0 ? _a : 0;
     const l = (_b = n.l) !== null && _b !== void 0 ? _b : 50;
+    // Same steps === 1 divide-by-zero guard as colorShades() above.
+    if (steps <= 1)
+        return steps === 1 ? [hslToHex(h, (_c = n.s) !== null && _c !== void 0 ? _c : 0, l)] : [];
     const result = [];
     for (let i = 0; i < steps; i++) {
         const s = Math.round((i / (steps - 1)) * 100);
@@ -1215,6 +1250,12 @@ function toNearestNamedColor(color) {
     let bestName = 'black';
     let bestDist = Infinity;
     for (const [name, hex] of Object.entries(NAMED_COLORS)) {
+        // Skip any non-hex entry (currently just a defensive guard — 'transparent'
+        // is the only such value left in the table, and it has no real RGB to
+        // compare against; hexToRgb() would otherwise silently fall back to
+        // normalizeHex()'s placeholder color for it).
+        if (hex[0] !== '#')
+            continue;
         const [nr, ng, nb] = hexToRgb(hex);
         const dist = Math.sqrt(Math.pow(r - nr, 2) + Math.pow(g - ng, 2) + Math.pow(b - nb, 2));
         if (dist < bestDist) {
@@ -1324,8 +1365,13 @@ function isReadableOnBackground(textColor, background, options) {
     const level = (_a = options === null || options === void 0 ? void 0 : options.level) !== null && _a !== void 0 ? _a : 'AA';
     const large = (_b = options === null || options === void 0 ? void 0 : options.largeText) !== null && _b !== void 0 ? _b : false;
     const minRequired = level === 'AAA' ? (large ? 4.5 : 7) : (large ? 3 : 4.5);
+    // The specific effective background color that minRatio was actually
+    // computed against — wcagLevel below is derived from this same color
+    // (never a hardcoded '#ffffff') so it can't disagree with minRatio/readable.
     let minRatio;
+    let effectiveBackground;
     if (typeof background === 'string') {
+        effectiveBackground = background;
         minRatio = contrastRatio(textColor, background);
     }
     else if (background.type === 'semi-transparent') {
@@ -1336,13 +1382,24 @@ function isReadableOnBackground(textColor, background, options) {
         const cr = Math.round(((_e = fg.r) !== null && _e !== void 0 ? _e : 0) * alpha + ((_f = bg.r) !== null && _f !== void 0 ? _f : 255) * (1 - alpha));
         const cg = Math.round(((_g = fg.g) !== null && _g !== void 0 ? _g : 0) * alpha + ((_h = bg.g) !== null && _h !== void 0 ? _h : 255) * (1 - alpha));
         const cb = Math.round(((_j = fg.b) !== null && _j !== void 0 ? _j : 0) * alpha + ((_k = bg.b) !== null && _k !== void 0 ? _k : 255) * (1 - alpha));
-        minRatio = contrastRatio(textColor, rgbToHex({ r: cr, g: cg, b: cb }));
+        effectiveBackground = rgbToHex({ r: cr, g: cg, b: cb });
+        minRatio = contrastRatio(textColor, effectiveBackground);
     }
     else {
-        const ratios = background.stops.map(stop => contrastRatio(textColor, stop));
-        minRatio = Math.min(...ratios);
+        // The worst-case stop (lowest ratio) drives both minRatio and wcagLevel.
+        let worstStop = background.stops[0];
+        let worstRatio = Infinity;
+        for (const stop of background.stops) {
+            const ratio = contrastRatio(textColor, stop);
+            if (ratio < worstRatio) {
+                worstRatio = ratio;
+                worstStop = stop;
+            }
+        }
+        effectiveBackground = worstStop;
+        minRatio = worstRatio;
     }
-    const wLevel = wcagLevel(textColor, typeof background === 'string' ? background : '#ffffff');
+    const wLevel = wcagLevel(textColor, effectiveBackground);
     return { readable: minRatio >= minRequired, minContrastRatio: +minRatio.toFixed(2), wcagLevel: wLevel };
 }
 function bestContrastPalette(background, palettes, options) {

package/dist/esm/index.js

@@ -30,15 +30,24 @@ const NAMED_COLORS = {
     springgreen: '#00ff7f', steelblue: '#4682b4', tan: '#d2b48c', teal: '#008080', thistle: '#d8bfd8',
     tomato: '#ff6347', turquoise: '#40e0d0', violet: '#ee82ee', wheat: '#f5deb3', white: '#ffffff',
     whitesmoke: '#f5f5f5', yellow: '#ffff00', yellowgreen: '#9acd32',
-    // Special CSS keywords
-    transparent: 'transparent', currentcolor: 'currentcolor', inherit: 'inherit', initial: 'initial', unset: 'unset',
+    // 'transparent' is the only CSS-wide keyword with an actual fixed color (fully
+    // transparent black) — normalizeColor() special-cases it before ever reaching
+    // this table (see the `str === 'transparent'` check), so this entry only
+    // matters for getColorType()/toNearestNamedColor(), which read the table
+    // directly. 'currentcolor'/'inherit'/'initial'/'unset' are deliberately NOT
+    // listed here: none of them has a color value of their own (they only resolve
+    // to one given surrounding DOM/CSSOM context this library never has access
+    // to), so treating them as resolvable named colors would mean fabricating an
+    // arbitrary RGB value with no way for a caller to tell it apart from a real
+    // one — see normalizeColor()'s `type: 'unknown'` fallback for these instead.
+    transparent: 'transparent',
 };
 export function isCssVariable(value) {
     return value.trim().startsWith('var(--');
 }
 export function isHexColor(value) {
     const trimmed = value.trim();
-    return /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6})$/.test(trimmed);
+    return /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{4}|[0-9A-Fa-f]{6}|[0-9A-Fa-f]{8})$/.test(trimmed);
 }
 export function isOklchColor(value) {
     return /^\s*oklcha?\s*\(/i.test(value.trim());
@@ -379,11 +388,18 @@ export function rgbaStringToRgba(str) {
     const parts = m[1].split(/,\s*/).map(p => p.trim());
     if (parts.length < 3)
         return null;
-    const parseChannel = (v) => v.endsWith('%') ? Math.round(parseFloat(v) * 2.55) : Math.round(parseFloat(v));
+    // Clamp channels to a valid byte and alpha to [0,1] — an out-of-range input
+    // like "rgb(300, -20, 0)" or "rgba(0,0,0,2)" is invalid CSS, but previously
+    // passed straight through unclamped, which could even corrupt downstream hex
+    // output (a negative channel stringifies with a leading "-" via toString(16)).
+    const parseChannel = (v) => {
+        const n = v.endsWith('%') ? parseFloat(v) * 2.55 : parseFloat(v);
+        return Math.round(Math.max(0, Math.min(255, n)));
+    };
     const r = parseChannel(parts[0]);
     const g = parseChannel(parts[1]);
     const b = parseChannel(parts[2]);
-    const a = parts[3] !== undefined ? parseFloat(parts[3]) : 1;
+    const a = parts[3] !== undefined ? Math.max(0, Math.min(1, parseFloat(parts[3]))) : 1;
     return { r, g, b, a };
 }
 export function rgbToHsl({ r, g, b }) {
@@ -640,6 +656,16 @@ export function normalizeColor(input) {
                 g = srgb.g;
                 b = srgb.b;
             }
+            else if (parsed.space === 'srgb-linear') {
+                // srgb-linear components are linear-light, not gamma-encoded — unlike
+                // plain srgb below, they need the linear-to-sRGB transfer function
+                // applied before scaling to a 0-255 byte. Without this, only the 0/1
+                // extremes happened to come out correct; any mid-range value (e.g. 0.5)
+                // converted as if it were already gamma-encoded, which is wrong.
+                r = Math.round(linearChanToSrgb(p3r) * 255);
+                g = Math.round(linearChanToSrgb(p3g) * 255);
+                b = Math.round(linearChanToSrgb(p3b) * 255);
+            }
             else {
                 r = Math.round(Math.max(0, Math.min(255, p3r * 255)));
                 g = Math.round(Math.max(0, Math.min(255, p3g * 255)));
@@ -678,10 +704,16 @@ export function tetradic(color) {
     return [hex, rotateHue(hex, 90), rotateHue(hex, 180), rotateHue(hex, 270)];
 }
 export function colorShades(color, steps = 9) {
-    var _a, _b;
+    var _a, _b, _c;
     const n = normalizeColor(color);
     const h = (_a = n.h) !== null && _a !== void 0 ? _a : 0;
     const s = (_b = n.s) !== null && _b !== void 0 ? _b : 0;
+    // steps - 1 === 0 below would otherwise divide by zero (NaN lightness, then
+    // a literal "#NaNNaNNaN" hex string) — a single shade is just the color's
+    // own lightness, same idea as interpolateColors() returning the midpoint
+    // for a 2-color, 1-step request.
+    if (steps <= 1)
+        return steps === 1 ? [hslToHex(h, s, (_c = n.l) !== null && _c !== void 0 ? _c : 50)] : [];
     const result = [];
     for (let i = 0; i < steps; i++) {
         const l = Math.round(100 - (i / (steps - 1)) * 100);
@@ -690,10 +722,13 @@ export function colorShades(color, steps = 9) {
     return result;
 }
 export function monochromatic(color, steps = 5) {
-    var _a, _b;
+    var _a, _b, _c;
     const n = normalizeColor(color);
     const h = (_a = n.h) !== null && _a !== void 0 ? _a : 0;
     const l = (_b = n.l) !== null && _b !== void 0 ? _b : 50;
+    // Same steps === 1 divide-by-zero guard as colorShades() above.
+    if (steps <= 1)
+        return steps === 1 ? [hslToHex(h, (_c = n.s) !== null && _c !== void 0 ? _c : 0, l)] : [];
     const result = [];
     for (let i = 0; i < steps; i++) {
         const s = Math.round((i / (steps - 1)) * 100);
@@ -1115,6 +1150,12 @@ export function toNearestNamedColor(color) {
     let bestName = 'black';
     let bestDist = Infinity;
     for (const [name, hex] of Object.entries(NAMED_COLORS)) {
+        // Skip any non-hex entry (currently just a defensive guard — 'transparent'
+        // is the only such value left in the table, and it has no real RGB to
+        // compare against; hexToRgb() would otherwise silently fall back to
+        // normalizeHex()'s placeholder color for it).
+        if (hex[0] !== '#')
+            continue;
         const [nr, ng, nb] = hexToRgb(hex);
         const dist = Math.sqrt(Math.pow(r - nr, 2) + Math.pow(g - ng, 2) + Math.pow(b - nb, 2));
         if (dist < bestDist) {
@@ -1224,8 +1265,13 @@ export function isReadableOnBackground(textColor, background, options) {
     const level = (_a = options === null || options === void 0 ? void 0 : options.level) !== null && _a !== void 0 ? _a : 'AA';
     const large = (_b = options === null || options === void 0 ? void 0 : options.largeText) !== null && _b !== void 0 ? _b : false;
     const minRequired = level === 'AAA' ? (large ? 4.5 : 7) : (large ? 3 : 4.5);
+    // The specific effective background color that minRatio was actually
+    // computed against — wcagLevel below is derived from this same color
+    // (never a hardcoded '#ffffff') so it can't disagree with minRatio/readable.
     let minRatio;
+    let effectiveBackground;
     if (typeof background === 'string') {
+        effectiveBackground = background;
         minRatio = contrastRatio(textColor, background);
     }
     else if (background.type === 'semi-transparent') {
@@ -1236,13 +1282,24 @@ export function isReadableOnBackground(textColor, background, options) {
         const cr = Math.round(((_e = fg.r) !== null && _e !== void 0 ? _e : 0) * alpha + ((_f = bg.r) !== null && _f !== void 0 ? _f : 255) * (1 - alpha));
         const cg = Math.round(((_g = fg.g) !== null && _g !== void 0 ? _g : 0) * alpha + ((_h = bg.g) !== null && _h !== void 0 ? _h : 255) * (1 - alpha));
         const cb = Math.round(((_j = fg.b) !== null && _j !== void 0 ? _j : 0) * alpha + ((_k = bg.b) !== null && _k !== void 0 ? _k : 255) * (1 - alpha));
-        minRatio = contrastRatio(textColor, rgbToHex({ r: cr, g: cg, b: cb }));
+        effectiveBackground = rgbToHex({ r: cr, g: cg, b: cb });
+        minRatio = contrastRatio(textColor, effectiveBackground);
     }
     else {
-        const ratios = background.stops.map(stop => contrastRatio(textColor, stop));
-        minRatio = Math.min(...ratios);
+        // The worst-case stop (lowest ratio) drives both minRatio and wcagLevel.
+        let worstStop = background.stops[0];
+        let worstRatio = Infinity;
+        for (const stop of background.stops) {
+            const ratio = contrastRatio(textColor, stop);
+            if (ratio < worstRatio) {
+                worstRatio = ratio;
+                worstStop = stop;
+            }
+        }
+        effectiveBackground = worstStop;
+        minRatio = worstRatio;
     }
-    const wLevel = wcagLevel(textColor, typeof background === 'string' ? background : '#ffffff');
+    const wLevel = wcagLevel(textColor, effectiveBackground);
     return { readable: minRatio >= minRequired, minContrastRatio: +minRatio.toFixed(2), wcagLevel: wLevel };
 }
 export function bestContrastPalette(background, palettes, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "color-value-tools",
-  "version": "1.1.12",
+  "version": "1.2.1",
   "description": "Parse, convert and manipulate colors across hex, RGB, HSL, Lab, LCH, OKLCH and CMYK, with WCAG contrast checks and CSS variables. Zero dependencies.",
   "author": "macrulez <macrulezru@gmail.com> (https://macrulez.ru/en)",
   "license": "MIT",