Home › Tailwind CSS › Tailwind CSS v4 rules

Tailwind CSS v4 rules

Windsurf rules for clean, consistent, accessible Tailwind CSS v4 styling.

WindsurfTailwind CSS

How to use

Save this as .windsurf/rules/tailwind.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# Windsurf rules — Tailwind CSS v4

- Tailwind v4: configure design tokens in CSS with `@theme` in the main stylesheet; there is no `tailwind.config.js` unless the project already has one.
- Use theme tokens (`bg-primary`, `text-muted-foreground`, spacing scale) instead of arbitrary values like `w-[437px]` or hex colors.
- Mobile-first: base classes for small screens, then `sm:`/`md:`/`lg:` overrides.
- Merge conditional classes with `cn()` (clsx + tailwind-merge); never build class names by string concatenation (the compiler can't see them).
- Repeated class lists → extract a component, not `@apply`. Use `@apply` only for third-party markup you can't control.
- Dark mode with `dark:` variants on every color utility you add.
- Accessibility: visible `focus-visible:` styles, sufficient contrast, `sr-only` labels for icon buttons.
- Keep class order consistent (use prettier-plugin-tailwindcss).