tailwind-css-coding

Tailwind CSS Coding

Match the project's existing conventions. When uncertain, read 2-3 existing components to infer the local style. Check package.json for the tailwindcss version. v4 signals: @tailwindcss/postcss or @tailwindcss/vite in deps, @import "tailwindcss" in CSS, @theme {} blocks. v3 signals: tailwind.config.js with module.exports, @tailwind base; directives, autoprefixer as separate dep. These defaults apply only when the project has no established convention.

Never rules

These are unconditional. They prevent broken builds, invisible bugs, and inaccessible UI regardless of project style.

• Never construct class names dynamically -- Tailwind's compiler scans source files as plain text with regex. It never executes code. Template literals, string concatenation, and interpolation produce classes the compiler cannot find. Use lookup maps of complete static strings.

// Wrong: compiler cannot extract "bg-red-500" from this
const cls = `bg-${color}-500`;

// Correct: every class is a complete static string
const bgMap = {
  red: "bg-red-500",
  blue: "bg-blue-500",
} as const;
const cls = bgMap[color];

• Never use template literal concatenation for class composition -- CSS source order determines which class wins when two utilities target the same property, not HTML attribute order. p-4 p-6 is unpredictable. Use cn() (clsx + tailwind-merge) to merge classes safely.

// Wrong: conflicting padding, last-in-source wins (not last-in-string)
className={`p-4 ${isLarge ? "p-6" : ""}`}

// Correct: tailwind-merge resolves conflicts deterministically
import { cn } from "@/lib/utils";
className={cn("p-4", isLarge && "p-6")}

• Never use arbitrary values when a design token exists -- p-[16px] is p-4. bg-[#3b82f6] is bg-blue-500. w-[100%] is w-full. text-[14px] is text-sm. Arbitrary values bypass the design system and create inconsistency. Likewise, prefer semantic tokens over raw palette colors when the design system defines them (bg-primary, not bg-blue-500) -- see shadcn-ui-coding.