tailwind-v4

name	tailwind-v4
description	Tailwind CSS v4 configuration and usage guidelines for Phoenix projects, plus UI/UX design principles. Use when styling Phoenix applications or building user interfaces.

Tailwind CSS v4 & UI/UX Guidelines

Tailwind CSS v4 Configuration

Tailwind CSS v4 no longer needs a tailwind.config.js and uses a new import syntax in app.css:

@import "tailwindcss" source(none);
@source "../css";
@source "../js";
@source "../../lib/your_app_web";

• Always use and maintain this import syntax in the app.css file for projects generated with phx.new
• Never use @apply when writing raw CSS
• Always manually write your own tailwind-based components instead of using daisyUI for a unique, world-class design

Asset Bundling

Out of the box only the app.js and app.css bundles are supported:

• You cannot reference an external vendor'd script src or link href in the layouts
• You must import vendor deps into app.js and app.css to use them
• Never write inline <script> tags within templates

UI/UX Design Principles

• Produce world-class UI designs with a focus on usability, aesthetics, and modern design principles
• Implement subtle micro-interactions (e.g., button hover effects, smooth transitions)
• Ensure clean typography, spacing, and layout balance for a refined, premium look
• Focus on delightful details like hover effects, loading states, and smooth page transitions

Best Practices

Responsive Design

• Use Tailwind's responsive prefixes (sm:, md:, lg:, xl:, 2xl:) for breakpoints
• Design mobile-first, then enhance for larger screens

Color and Theming

• Use Tailwind's color scales consistently (e.g., blue-500, blue-600 for primary actions)
• Define custom colors in the CSS using CSS custom properties if the default palette doesn't fit

Typography

• Use Tailwind's font size scale (text-sm, text-base, text-lg, etc.) for consistent hierarchy
• Ensure sufficient contrast ratios for accessibility (WCAG 2.1 AA minimum)

Spacing and Layout

• Use Tailwind's spacing scale consistently (p-4, m-6, gap-3, etc.)
• Prefer flexbox (flex) and grid (grid) for layouts over absolute positioning
• Use max-w-* containers to maintain readable line lengths

Animations and Transitions

• Use Tailwind's built-in transitions: transition-colors, transition-transform, transition-all
• Keep animations subtle and purposeful (150-300ms duration)
• Provide motion-reduce: variants for accessibility

Dark Mode

• Use Tailwind's dark: variant for dark mode support
• Test both modes to ensure readability and contrast