Smart Replace

Find the best matching style for orphaned colors using perceptual color science

Smart Replace is available in both Free and Pro tiers. Free users can apply up to 5 fixes per session.

The problem with hex matching

When you have an orphaned color like #1487FC and need to reconnect it to a style, a naive tool would compare hex values to find the nearest match. But hex distance does not correspond to how humans see color. Two colors with similar hex codes can look obviously different, and two colors with very different hex codes can appear nearly identical.

For example, #808080 and #808880 differ by only 8 in the green channel, but the shift is barely visible. Meanwhile, #FF0000 and #00FF00 are both “bright” but look completely different.

How Smart Replace works

Smart Replace converts colors from RGB to the Lab color space and measures distance using the Delta E 2000 (DE2000) metric. DE2000 is the industry standard for measuring how different two colors look to the human eye. It accounts for the non-linear way humans perceive hue, saturation, and lightness.

When LintKit detects an orphaned fill or stroke, Smart Replace calculates the DE2000 distance between that color and every style in your library, then suggests the closest matches.

The three-gate algorithm

Smart Replace does not blindly suggest the lowest Delta E match. It uses a three-gate system to prevent inappropriate substitutions. A candidate style must pass all three gates to appear as a suggestion.

1. Gate 1: Perceptual distance

   Reject any match where the Delta E exceeds the threshold (default: 6). If the colors are too far apart perceptually, they are not a valid match regardless of other factors.

2. Gate 2: Neutral color guard

   Prevent matching neutral colors (grays, blacks, whites with chroma below 8) to saturated colors. A medium gray should never be suggested as a replacement for a vibrant blue, even if the Delta E happens to be low. When one color is neutral and the other is saturated, the match is only accepted if Delta E is below 2.5.

3. Gate 3: Hue guard

   For saturated colors, reject any match where the hue rotates more than 35 degrees. This prevents suggesting a red style as a replacement for an orange, or a blue for a green, even when they share similar lightness and saturation.

Confidence tiers

The style picker shows a confidence label next to each suggested match:

Delta E	Label	What it means
Less than 1	Exact match	The colors are effectively identical. Safe to apply without checking.
1 to 3	Very close	Difference is imperceptible in most contexts. Safe for most use cases.
3 to 10	Similar	Visible difference when compared side by side. Review before applying.
10 or above	Possible match	Clearly different colors. Only shown when no better match exists.

Perceptual difference reference

Use this table to understand what Delta E numbers actually look like:

DE2000 range	Human perception
0 to 1	Imperceptible. No one can tell these apart.
1 to 3	Noticeable to a trained eye. Most people would not notice.
3 to 6	Obvious when the two colors are placed side by side.
6 to 10	Clearly different colors. No one would confuse them.
10+	Totally different colors.

Adjusting the tolerance

The colorTolerance config key controls the Delta E threshold for Gate 1. The default is 5.

• Lower the value (for example, 3) to get fewer but more accurate suggestions. Use this when your design system has many similar colors and you need precise matching.
• Raise the value (for example, 8) to get more suggestions, including looser matches. Use this during exploratory cleanup when you want to see all potential matches.

You can change this value in your configuration.

When Smart Replace helps

Design system migrations

You renamed or reorganized styles and need to reconnect orphaned layers to their closest match. Smart Replace finds the right style even when the name changed, because it matches on visual similarity rather than naming conventions.

Cross-file cleanup

A file accumulated colors from multiple contributors. One person used #1488FD and another used #1487FC. Smart Replace identifies these as effectively the same color and suggests the canonical style for both.

Brand updates

Your primary blue shifted from #1288FD to #1289FF. Smart Replace finds all near-matches across the file so you can reconnect them to the updated style.

When to match manually

Smart Replace is not the right tool for every situation:

• Intentionally similar colors: If your system has both gray-100 (#F5F5F5) and gray-200 (#EEEEEE), Smart Replace might suggest either. You will need to pick the correct one based on semantic intent.
• Colors that serve different purposes: A text/secondary and border/default might be the same hex value but should not be consolidated. Review the style names, not just the color swatches.
• Opacity-dependent colors: Colors with different opacity values may look similar on a white background but different on other backgrounds. Smart Replace compares the raw color values, not the composited result.