frontend-tailwind-best-practices

SKILL.md

Tailwind CSS Best Practices

Styling patterns and conventions for frontend applications. Contains 10 rules covering layout utilities, affordances, color schemes, responsive design, and className handling.

When to Apply

Reference these guidelines when:

Writing component styles with Tailwind

Creating layouts (stacks, grids, centering)

Handling responsive design

Working with color schemes

Merging className props

Rules Summary

Layout Utilities (CRITICAL)

layout-stack-utilities - @rules/layout-stack-utilities.md
Use custom stack utilities instead of flex classes.

// Bad
<div className="flex flex-col gap-4">
<div className="flex flex-row gap-4">

// Good
<div className="v-stack gap-4">
<div className="h-stack gap-4">

Available utilities:

v-stack - Vertical stack (flex column)

h-stack - Horizontal stack (flex row)

v-stack-reverse - Reversed vertical stack

h-stack-reverse - Reversed horizontal stack

z-stack - Overlapping stack (grid-based, centers children on top of each other)

center - Center content both horizontally and vertically

spacer - Flexible spacer that fills available space

circle - Perfect circle with aspect-ratio 1/1

layout-prefer-gaps - @rules/layout-prefer-gaps.md

Use gap-* on parents instead of child margins.

// Bad
<div>
  <Item className="mb-4" />
  <Item className="mb-4" />
</div>

// Good
<div className="flex flex-col gap-4">
  <Item />
  <Item />
</div>

layout-responsive-stacks - @rules/layout-responsive-stacks.md

Switch layout direction at breakpoints.

// Mobile: vertical, Desktop: horizontal
<div className="v-stack lg:h-stack gap-4">
  <main className="grow">...</main>
  <aside className="shrink-0 lg:w-80">...</aside>
</div>

// Mobile: horizontal, Desktop: vertical
<div className="h-stack md:v-stack">

Color Schemes (CRITICAL)

color-schemes - @rules/color-schemes.md

Use class-based color schemes with a custom dark variant.

<button className="rounded-full bg-gray-900 px-4 py-2 text-white dark:bg-gray-100 dark:text-gray-900">
  Toggle
</button>

className Handling (CRITICAL)

classname-cn-utility - @rules/classname-cn-utility.md

Always use cn() to merge classNames in components.

import { cn } from "~/lib/cn";

function Button({ className, variant }: Props) {
  return (
    <button
      className={cn(
        "base-classes",
        {
          "variant-primary": variant === "primary",
          "variant-secondary": variant === "secondary",
        },
        className, // external className always last
      )}
    />
  );
}

classname-prop-types - @rules/classname-prop-types.md

Use proper types for className props.

import type { ClassName, ClassNameRecord } from "~/lib/cn";

// Single element
type Props = {
  className?: ClassName;
};

// Multiple elements
type Props = {
  className?: ClassNameRecord<"root" | "label" | "input">;
};

// Usage
<Input className={{ root: "w-full", label: "font-bold" }} />;

Affordances (HIGH)

affordance-classes - @rules/affordance-classes.md

Define element-agnostic visual patterns that compose with utilities.

<label className="ui-button" htmlFor="document-upload">
  Choose file
</label>

Responsive Design (MEDIUM)

responsive-breakpoints - @rules/responsive-breakpoints.md

Use responsive prefixes with Tailwind defaults.

// Standard breakpoints (min-width)
<div className="px-4 md:px-8 lg:px-12">

// Show/hide with standard breakpoints
<div className="hidden md:block">Desktop only</div>
<div className="md:hidden">Mobile only</div>

responsive-text - @rules/responsive-text.md

Scale text responsively.

// Responsive font size
<h1 className="text-2xl md:text-3xl lg:text-4xl">

// Responsive line height with text
<p className="text-sm leading-5 md:text-base md:leading-6">

responsive-capabilities - @rules/responsive-capabilities.md

Design for input capabilities (pointer/hover) instead of device labels.

<button className="h-10 w-10 pointer-coarse:h-12 pointer-coarse:w-12">
  <Icon />
</button>

Anti-Patterns

Don't
Do

flex flex-col
v-stack

flex flex-row
h-stack

flex items-center justify-center
center

bg-gray-100
bg-neutral-100

bg-[#hex]
Use design tokens

className="..." without cn()
cn("...", className)

Inline style for responsive
Tailwind prefixes

Key Files

File
Purpose

tailwind.config.js
Config, custom utilities, colors

app/styles/global.css
Color scheme CSS variables

app/styles/tailwind.css
Additional utilities

app/utils/cn.ts
className merge utility