Tailwind CSS Utility Class Standards

Consistent utility class ordering makes your markup predictable for both developers and AI coding tools.

Why Class Order Matters

Without consistent ordering:

• Class strings become hard to scan and review
• AI tools produce inconsistent class arrangements
• Merge conflicts are more frequent
• It’s harder to spot missing or conflicting utilities

Recommended Class Order

Follow this order for all elements:

1. Layout — display, position, top/right/bottom/left, z-index
2. Flex/Grid — flex, flex-col, grid, gap, justify-*, items-*
3. Spacing — padding, margin
4. Sizing — width, height, min-*, max-*
5. Typography — text-*, font-*, leading-*, tracking-*
6. Visual — bg-*, border-*, rounded-*, shadow-*, opacity-*
7. Misc — cursor-*, transition-*, transform-*, animate-*

Correct ✅

<div class="flex items-center gap-4 px-6 py-3 w-full text-sm font-medium bg-blue-600 text-white rounded-lg shadow-sm hover:bg-blue-700 transition-colors">
  Button
</div>

Incorrect ❌

<div class="hover:bg-blue-700 text-sm py-3 flex bg-blue-600 px-6 font-medium items-center text-white transition-colors w-full rounded-lg shadow-sm gap-4">
  Button
</div>

Responsive Design

Group responsive variants at the class level, not the breakpoint level.

Correct ✅

<div class="text-sm md:text-base lg:text-lg px-4 md:px-6 lg:px-8">
  Content
</div>

Incorrect ❌

<!-- Don't reorder by breakpoint -->
<div class="text-sm px-4 md:text-base md:px-6 lg:text-lg lg:px-8">
  Content
</div>

Component Class Extraction

Use @apply in CSS for repeated patterns. Don’t repeat the same class string.

Correct ✅

/* In global.css */
@layer components {
  .card {
    @apply rounded-xl border border-slate-200 bg-white p-6 shadow-sm;
  }
}

<div class="card">Content</div>
<div class="card">More content</div>

Incorrect ❌

<div class="rounded-xl border border-slate-200 bg-white p-6 shadow-sm">Content</div>
<div class="rounded-xl border border-slate-200 bg-white p-6 shadow-sm">More</div>
<div class="rounded-xl border border-slate-200 bg-white p-6 shadow-sm">More</div>

State Variants Order

Order state variants like this: hover → focus → active → disabled.

Correct ✅

<button class="bg-blue-600 hover:bg-blue-700 focus:ring-2 focus:ring-blue-400 active:bg-blue-800 disabled:opacity-50">
  Submit
</button>

Conditional Classes

Use clsx or cn() for conditional classes. Avoid inline ternaries.

Correct ✅

import { cn } from '@/lib/utils'

export function Button({ variant, className }: ButtonProps) {
  return (
    <button
      className={cn(
        'inline-flex items-center rounded-md px-4 py-2 text-sm font-medium',
        variant === 'primary' && 'bg-blue-600 text-white hover:bg-blue-700',
        variant === 'secondary' && 'bg-slate-100 text-slate-900 hover:bg-slate-200',
        className
      )}
    />
  )
}

Incorrect ❌

<button className={`inline-flex ${variant === 'primary' ? 'bg-blue-600' : 'bg-slate-100'} px-4`}>
  Submit
</button>

Color Tokens

Use configured color tokens. Avoid arbitrary values except for one-offs.

Correct ✅

<div class="bg-blue-600 text-white border-slate-200">
  Uses design tokens
</div>

Acceptable for one-offs ✅

<div class="w-[327px]">
  <!-- Specific dimension not in config -->
</div>

Incorrect ❌

<div class="bg-[#3b82f6] text-[#ffffff]">
  <!-- Duplicates existing tokens -->
</div>

AI Coding Prompt Example

When writing Tailwind CSS classes:
- Order: Layout → Flex/Grid → Spacing → Sizing → Typography → Visual → Misc
- Group responsive variants per-property (not per-breakpoint)
- Extract repeated patterns with @apply into component classes
- Use cn() utility for conditional classes in React components
- State variants: hover → focus → active → disabled
- Use configured design tokens instead of arbitrary values
- Keep class strings under ~15 classes; extract if longer

Best Practices Summary

• Consistent class ordering: Layout → Flex → Spacing → Size → Type → Visual
• Extract repeated patterns with @apply
• Use cn() for conditional classes
• Group responsive variants by property
• Prefer tokens over arbitrary values
• Extract component classes when the same string appears 3+ times