# Colors That Clash

**SHOULD** · **ID:** `design-color-harmony` · **Category:** design
**Source:** Custom
**Interactive version:** https://ui-guides-agent-rules.netlify.app/principles/design-color-harmony

> SHOULD: Use harmonious color combinations from a defined palette. Clashing colors create visual discomfort. Consider color temperature and saturation balance.

Use harmonious color combinations from a defined palette

This is our own rule, not an upstream citation — the Rams review has no bullet for it, and we previously mislabelled it as one. The practical test is not "do these two hues look nice together" but "where did this hue come from": a palette generated in a perceptual space (OKLCH is the practical one) gives you hues at matched lightness and chroma, so a warning next to a success next to a primary read as members of one family instead of three separate accidents. Ad-hoc picks fail in a specific way — they collide at the same lightness, so the eye cannot tell which one is meant to be louder. Choose the relationship (analogous, complementary, triadic) once, encode it as tokens, and let components consume tokens only.

## Bad — do not do this

`design-color-harmony-bad`

```tsx
export function ColorHarmonyBad() {
  return (
    <div className="w-full max-w-sm space-y-4">
      <div className="bg-card border border-border rounded-lg p-4">
        <h4 className="font-medium mb-3">Clashing Colors</h4>
        <div className="space-y-3 p-4 bg-muted rounded-lg">
          <div className="flex gap-2">
            <button className="px-3 py-1.5 bg-[var(--ex-clash-orange)] text-white rounded-md text-sm">
              Action
            </button>
            <button className="px-3 py-1.5 bg-[var(--ex-clash-purple)] text-white rounded-md text-sm">
              Another
            </button>
          </div>
          <div className="space-y-2 text-sm">
            <div className="text-[var(--ex-clash-green)]">Success: But wrong green</div>
            <div className="text-[var(--ex-clash-pink)]">Error: Hot pink instead of red</div>
            <div className="text-[var(--ex-clash-cyan)]">Warning: Cyan warning?</div>
          </div>
        </div>
        <div className="mt-3 bg-muted rounded p-2 font-mono text-xs">
          <code className="text-error">Random hex values that clash</code>
        </div>
      </div>
      <p className="text-xs text-error">
        Colors from different palettes - visual chaos
      </p>
    </div>
  );
}
```

## Good — do this

`design-color-harmony-good`

```tsx
export function ColorHarmonyGood() {
  return (
    <div className="w-full max-w-sm space-y-4">
      <div className="bg-card border border-border rounded-lg p-4">
        <h4 className="font-medium mb-3">Harmonious Colors</h4>
        <div className="space-y-3 p-4 bg-muted rounded-lg">
          <div className="flex gap-2">
            <button className="px-3 py-1.5 bg-primary text-primary-foreground rounded-md text-sm">
              Primary
            </button>
            <button className="px-3 py-1.5 bg-secondary text-secondary-foreground rounded-md text-sm">
              Secondary
            </button>
          </div>
          <div className="space-y-2 text-sm">
            <div className="text-success">Success: Operation completed</div>
            <div className="text-destructive">Error: Something went wrong</div>
            <div className="text-warning">Warning: Please review</div>
          </div>
        </div>
        <div className="mt-3 bg-muted rounded p-2 font-mono text-xs">
          <code>Design tokens: primary, success, destructive</code>
        </div>
      </div>
      <p className="text-xs text-success">
        Cohesive palette from design system tokens
      </p>
    </div>
  );
}
```

## References

- [Color Mechanics in UI](https://www.smashingmagazine.com/2023/04/color-mechanics-ui-kits/)