usability.cat
Issue Wiki

Inconsistent Colors

When brand colors are used randomly across your site, it looks like each page was designed by a different person. Here's how to build a color system.

What is this?

Imagine you're painting a room and you picked "ocean blue" from the swatch. But the paint store gives you a slightly different shade of blue for each wall. One wall is teal, another is navy, the third is cerulean, and the fourth is baby blue. Individually they're all fine colors. Together? It looks like a mistake. That's what happens when your website uses #3B82F6 for one button, #2563EB for another, and #1D4ED8 for a third — all meant to be "the primary blue." Multiply that across backgrounds, text, borders, and hover states, and the cat is seeing 15 shades of "the same color."

Why it matters

  • For your visitors: Color is a wayfinding system. When your primary button is blue on the homepage but teal on the pricing page, visitors lose their learned patterns. "Blue means clickable" breaks down. They have to re-learn your interface on every page, which means they think harder and convert less.

  • For your business: Brand recognition depends on consistent color use. Think about how instantly you recognize Stripe's purple or Spotify's green. When your colors wander, your brand dissolves into generic noise. Visitors won't remember you because there was nothing consistent to remember.

  • The standard: Define a color palette with specific values for primary, secondary, neutral, and semantic colors (success, warning, error). Every color on your site should come from this palette. No hardcoded hex values scattered through your CSS.

Color tokens from a palette
:root {
  --primary: oklch(0.72 0.18 75);
  --primary-hover: oklch(0.65 0.2 75);
  --secondary: oklch(0.55 0.05 250);
  --success: oklch(0.7 0.15 142);
  --danger: oklch(0.65 0.2 25);
  --text: oklch(0.9 0.005 75);
  --text-muted: oklch(0.6 0.005 75);
}
.btn-primary { background: var(--primary); }
.btn-primary:hover { background: var(--primary-hover); }
Hardcoded colors everywhere
/* Same "blue" in 5 different shades */
.hero-btn { background: #3B82F6; }
.nav-link { color: #2563EB; }
.card-btn { background: #1E40AF; }
.footer-link { color: #60A5FA; }
.badge { background: #3B83F7; } /* off by one hex digit */

How to fix it

React / Next.js

Define your colors once in your CSS, then reference them through Tailwind utilities:

/* app/globals.css */
@theme {
  --color-primary: oklch(0.72 0.18 75);
  --color-primary-hover: oklch(0.65 0.2 75);
  --color-surface: oklch(0.15 0.005 75);
  --color-surface-raised: oklch(0.18 0.005 75);
  --color-text-primary: oklch(0.93 0.005 75);
  --color-text-secondary: oklch(0.6 0.005 75);
  --color-success: oklch(0.7 0.15 142);
  --color-warning: oklch(0.75 0.15 86);
  --color-danger: oklch(0.65 0.2 25);
}

Then in your components, always use the token names:

export function PricingCard({ featured }: { featured?: boolean }) {
  return (
    <div
      className={`p-6 ${
        featured
          ? "border-2 border-primary bg-surface-raised"
          : "border border-neutral-800 bg-surface"
      }`}
    >
      <h3 className="text-lg font-bold text-text-primary">Pro Plan</h3>
      <p className="text-text-secondary">Everything you need.</p>
      <button className="mt-4 w-full bg-primary px-4 py-2 font-semibold text-black hover:bg-primary-hover">
        Get started
      </button>
    </div>
  );
}

Plain HTML / CSS

/* Define ALL your colors in one place */
:root {
  --primary: #f59e0b;
  --primary-hover: #d97706;
  --surface: #171717;
  --surface-raised: #262626;
  --text: #fafafa;
  --text-muted: #a3a3a3;
  --border: #404040;
}

/* Never use raw hex values outside :root */
.btn {
  background: var(--primary);
  color: var(--surface);
}
.btn:hover {
  background: var(--primary-hover);
}
.card {
  background: var(--surface-raised);
  border: 1px solid var(--border);
}
p {
  color: var(--text-muted);
}
Medium impactvisualDesign~1 paw

Color inconsistency signals a lack of design system, which drags down the overall polish of your site. The cat notices every shade that doesn't match.

How the cat scores this

The scanner collects every unique color value used on your page and clusters them by similarity. If it finds multiple colors that are "almost the same" (like two blues that differ by a few shades), it flags them as likely inconsistencies. It also checks whether interactive elements (buttons, links) use a consistent primary color, and whether semantic colors (success green, error red) are applied uniformly.

Further reading

On this page