Tailwind CSS Guidelines

Overview

Foundational Tailwind CSS guidelines for utility-first styling. Covers class composition, responsive design, dark mode, color systems, typography, spacing, state variants, and Tailwind v4 changes. Prioritize utility classes over custom CSS, compose with clsx/tw-merge, and follow mobile-first responsive patterns.

Utility-First Methodology

Class Composition

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

function cn(...inputs: ClassValue[]): string {
  return twMerge(clsx(inputs));
}

// Usage: last class wins for conflicts
cn("px-4 py-2 bg-blue-500", isActive && "bg-blue-700", className)

Responsive Design

Mobile-first: base styles apply to all screens, breakpoint prefixes apply at that width and above.

Common Responsive Patterns

Container Queries

<div class="@container">
  <div class="flex flex-col @md:flex-row">...</div>
</div>

Dark Mode

Color Pairing Strategy

Opacity-Based Dark Mode Colors

Accessibility

Color System

Color Hierarchy

Opacity Modifiers

CSS Variable Theming

<!-- Inline theme overrides -->
<button class="bg-[var(--btn-bg)] text-[var(--btn-text)]"
        style="--btn-bg: var(--color-indigo-600); --btn-text: white;">
  Submit
</button>

<!-- Tailwind v4: @theme for custom tokens -->

Typography

Text Size Scale

Line Height Slash Syntax (v4)

Font Weight Pairing

Text Wrapping

Responsive Text

<h1 class="text-2xl font-bold tracking-tight sm:text-3xl lg:text-4xl">
  Page Title
</h1>
<p class="text-sm/6 text-gray-600 md:text-base/7">
  Description text that scales with viewport.
</p>

Spacing and Sizing

Spacing Scale Consistency

Gap vs Space

Prefer gap over space-* in flex/grid contexts. space-* uses margins and breaks with flex-wrap.

Common Padding Pairs

Negative Margins

Borders, Rings, and Outlines

When to Use Each

Focus Patterns

Subtle Borders with Opacity

Inset Rings

State Variants

Standard States

Disabled Pattern

<button class="bg-indigo-600 hover:bg-indigo-500 disabled:opacity-50
               disabled:cursor-not-allowed disabled:hover:bg-indigo-600">
  Submit
</button>

Group and Peer States

Data Attribute Styling

Tailwind v4 Changes

@theme Directive

@import "tailwindcss";

@theme {
  --color-brand: #4f46e5;
  --color-brand-light: #818cf8;
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

@utility Directive

@utility scrollbar-hidden {
  scrollbar-width: none;
  &::-webkit-scrollbar {
    display: none;
  }
}

/* Usage: class="scrollbar-hidden" */

@custom-variant Directive

/* Class-based dark mode toggle */
@custom-variant dark (&:where(.dark, .dark *));

/* Custom theme variants */
@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

@variant Directive (Apply Variants in Custom CSS)

.my-element {
  background: white;
  @variant dark {
    background: black;
  }
}

@source Directive (Content Detection)

@import "tailwindcss";
/* Include external library templates */
@source "../node_modules/@my-company/ui-lib";
/* Exclude legacy code */
@source not "./src/legacy";
/* Safelist specific utilities */
@source inline("underline");
@source inline("{hover:,}bg-red-{50,{100..900..100},950}");

Built-in Container Queries (No Plugin)

<div class="@container">
  <div class="grid grid-cols-1 @sm:grid-cols-3 @lg:grid-cols-4">...</div>
</div>
<!-- Named containers, max-width, ranges -->
<div class="@container/main">
  <div class="@sm:@max-md:grid-cols-2">...</div>
</div>

v4 New Features

v4.1 Features

v4 Migration Checklist

Common Anti-Patterns

MCP Component Library

The frontend-components MCP server provides browsable component libraries for reference and reuse:

Key tools: list_frameworks, list_components(framework), get_component(framework, ...), search_components(query), get_component_by_path(path)

Use search_components(query: "keyword") to find components across all libraries, or filter by framework.