shadcn-errors-styling-conflicts

name	shadcn-errors-styling-conflicts
description	Use when a className override on a shadcn component does not visually take effect, when two Tailwind utility classes appear in the rendered DOM but only one applies, when a cva variant looks correct in code but the consumer className does not win, when porting code from Tailwind v3 to v4 and class semantics shift, when adding arbitrary values (bg-[#fff], size-[28px]) next to preset utilities, when the important modifier (! prefix in v3, suffix in v4) behaves unexpectedly, when a component built with cva looks unstyled or doubled-up, or when reviewing PRs that build className strings with template literals or string concatenation. Prevents the canonical class-merging bugs: skipping cn() so duplicates leak through the DOM, calling cn() inside cva (no-op since cva already runs clsx), assuming the important modifier always overrides plain utilities, mixing arbitrary properties with their preset equivalents, and applying v3-only class names in a v4 project. Covers the cn() helper rule (clsx + tailwind-merge wrapper), tailwind-merge semantics (last-wins, arbitrary-value handling, important-tracking, dedup), the exact cva merge order (base then variants then compoundVariants then defaultVariants then consumer className), the Tailwind v3 to v4 class-semantics shifts that surface as merge failures, the !important precedence trap, and the six most common class-merging anti-patterns observed in shadcn projects. Keywords: tailwind-merge, twMerge, className not applied, className ignored, cn helper, cva variant override, duplicate tailwind classes, why is my className ignored, class conflict, tailwind class conflict, tailwind-merge surprise, arbitrary classes not merging, bg-[#fff] vs bg-white, important class merge, !important class merge, p-4 p-2 merge, last wins tailwind, my override does not work, my styles do not apply, cva default variant override, compoundVariants ignored, shadcn className not working, template string className, raw className concat, missing twMerge, clsx alone, ring-2 vs ring, size-4 vs w-4 h-4.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui Errors: Styling and Class-Merging Conflicts

When a className override on a shadcn component appears in the rendered DOM but does not affect the visible style, the cause is almost always one of three things: (1) the cn() helper was skipped and duplicate Tailwind utilities leaked through, (2) the cva merge order was misunderstood and the consumer className landed before the variant class instead of after it, or (3) Tailwind v3 and v4 class semantics were mixed in the same file. This skill enumerates the deterministic rules and the verified merge order so the diagnosis takes seconds.

Quick Reference

The cn() rule (memorize this)

// lib/utils.ts : every shadcn project ships this file
import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"
export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)) }

• ALWAYS use cn(...) when composing className from more than one source.
• NEVER concatenate className with + or template literals. Raw strings bypass conflict resolution and let duplicates leak through.
• NEVER use clsx alone for className that may collide. clsx joins conditionals but does NOT resolve Tailwind conflicts.
• NEVER use twMerge alone when you need conditionals. twMerge does not understand object syntax or falsy values; that is clsx's job.
• The order inside cn(...) is significant : LAST WINS for conflicting Tailwind utilities.

tailwind-merge semantics (verified at github.com/dcastil/tailwind-merge)

Input	Output	Reason
twMerge('p-4 p-2')	p-2	Same utility family : last wins