# How semantic colors work in shadcn/ui

> Learn how semantic colors work in shadcn/ui — why naming colors by role instead of hue keeps your UI consistent, accessible, and easy to theme across light and dark mode.

Published: 2026-03-05 · Author: Matt Wierzbicki · Canonical: https://www.shadcndesign.com/blog/how-semantic-colors-work-in-shadcn-ui

Semantic colors sound fancy, but the idea is simple: **give colors a job**, not a vibe.

Instead of "blue," "blue-ish," "kind of gray," you name colors based on what they do in the UI.

- `background` is the background
- `foreground` is the text on top of it
- `primary` is your main action / brand color
- `primary-foreground` is the text on top of that action color

shadcn/ui docs explain this convention clearly, even down to how suffixes work and examples like `--primary` and `--primary-foreground`.

That's the whole point. You stop decorating. You start assigning.

## The core semantic set (in human terms)

You'll see these show up across components:

- `background` / `foreground`: the base canvas and the text on it
- `border`: outlines, dividers, rules
- `input`: form surfaces (inputs, textareas)
- `primary`: the "do the thing" color (buttons, links, big actions)
- `primary-foreground`: text on top of your primary color

There are usually other pairs too (accent, muted, destructive), but the pattern repeats: **pair the surface with the text on top**.

Once you name roles, your UI gets calmer. You can change a theme without chasing colors through 200 files.

## Why brand-led palettes fail without semantic mapping

This happens all the time:

1. Someone says "our brand color is orange, let's use orange everywhere."
2. Buttons look fine at first.
3. Cards look loud.
4. Toasts look loud.
5. Charts look weird.
6. Text starts failing contrast.
7. Someone adds a new color "just for this one thing."
8. Repeat forever.

The problem isn't orange. The problem is **no mapping**.

A brand palette is not a UI. A UI needs:

- different levels of emphasis
- clear hierarchy
- readable text
- calm backgrounds
- safe borders
- accessible states

If you skip the semantic layer, your brand will leak into places it shouldn't — like borders, inputs, even backgrounds. Then your UI looks like a marketing banner, not a product.

## How "one color → full palette" works in practice

This is where the "one color can power a whole theme" claim is true — but only when you do it with roles.

If you pick **one primary** and build the rest of the theme using rules, not mood, you can generate a whole system:

- Keep `background` and `foreground` mostly neutral (safe, readable)
- Let `primary` carry brand energy
- Keep input surfaces low-contrast so forms don't feel like posters
- Keep borders subtle so layout stays clean
- Derive states from the primary in a controlled way (hover, focus, disabled)

This is exactly where you should use a tool. With a generator, you can start from one color and get a full set of variables that follow a sane convention.

If you want a fast way to do that, use the <Link href="/theme-generator">shadcn Theme Generator</Link> and generate a consistent palette from one color. That's the practical path: one decision, many results.

## Accessibility checklist (short and real)

A theme that looks "nice" might still be unusable. Here's a checklist that catches most issues fast:

### Check text contrast

Look at your main text on `background` and your `primary-foreground` text on `primary`. If people squint, it's broken.

### Check dark mode parity

Dark mode isn't just "invert." Surfaces, borders, and muted text need a different balance. When you flip your theme, ask:

- Does the UI keep the same structure?
- Do surfaces still look like surfaces?
- Do borders still separate groups clearly?

### Check error states

Destructive colors need extra care. A red button with low-contrast text is one of the easiest ways to fail accessibility. Make sure the "foreground on destructive" color is readable.

### Check focus outlines

Don't make focus disappear. Don't make it a soft shadow you can't see. If a keyboard user can't tell where focus is, the UI is failing.

## When to adjust and when to keep defaults

This is the part nobody wants to hear, but it saves hours:

### Keep defaults when:

- You want reliability fast
- You don't have time to dial in contrast manually
- The product values speed and clarity over "branding everywhere"
- You're doing your first theme or a quick MVP

### Adjust when:

- Your product has a strong visual brand and you need it in UI
- You know your contrast ratios
- You're willing to maintain it long-term
- You're doing a UI refresh, not a quick experiment

A good rule: change as little as you can to make it feel like "you." The more you change, the more maintenance debt you add.

## Replace variables the right way

If you're working with a theme collection, don't swap random colors in random places. Replace variables at the source.

Use the <Link href="/docs/themes">shadcn theming docs</Link> approach and apply your choices through the semantic variables, not custom class overrides scattered everywhere. That keeps the system consistent and debuggable.

## Learn the full workflow

The fastest way to get good at semantic theming is repetition: build, review, adjust, ship.

If you want the full, end-to-end flow with training, use the <Link href="/academy">shadcndesign Academy</Link>. It matches the learning intent: understanding why themes work, not just copy/pasting blocks.

## Looking for starting points?

If you want to see what a "finished" theme feels like before you generate your own, check our <Link href="/themes">shadcn/ui themes</Link> to browse presets. Then tweak the neutral bits and keep the primary under control.

And when you need to apply themes in code or Figma correctly, follow the guidance in our <Link href="/docs/themes">themes docs</Link>. That way, you're changing themes the right way — not hacking them in as quick one-off fixes.