Tailwind UI Skill

Tailwind CSS v4.1 development with accessibility and theming baked in.

Quick Reference

v4.1 Critical Changes

Never use deprecated utilities — always use replacements:

Deprecated	Replacement
bg-opacity-*	bg-black/50 (opacity modifier)
bg-gradient-*	bg-linear-*
shadow-sm	shadow-xs
shadow	shadow-sm
rounded-sm	rounded-xs
rounded	rounded-sm
ring	ring-3
outline-none	outline-hidden
leading-*	Use text-base/7 line-height modifiers
flex-shrink-* / flex-grow-*	shrink-* / grow-*
space-x-* in flex/grid	Use gap-* instead

Essential Patterns

<!-- Gap over space utilities -->
<div class="flex gap-4">...</div>

<!-- Opacity modifiers -->
<div class="bg-primary-500/60">...</div>

<!-- Line height modifiers -->
<p class="text-base/7">...</p>

<!-- Dynamic viewport height (mobile-safe) -->
<div class="min-h-dvh">...</div>

<!-- Size utility for equal dimensions -->
<div class="size-12">...</div>

Reference Files

Load these based on the task:

• references/v4-migration.md — Full v4.1 breaking changes, upgrade process, new features
• references/accessibility.md — WCAG 2.1 AA patterns: contrast, focus, screen readers
• references/theming.md — @theme setup, CSS variables, light/dark mode
• references/components.md — Accessible component patterns (buttons, forms, cards, nav)
• references/app-conventions.md — Project-specific list & form page design tokens (border radius, list style, form sections). Load this for any list or form page in frontend/ai.client.

Theme Asset

• assets/theme-starter.css — Starter @theme with primary/secondary/tertiary color scales

Core Principles

1. Use Tailwind's scale — Avoid arbitrary values like ml-[16px]; use ml-4
2. Never use @apply — Use CSS variables or framework components
3. Gap over margins — Use gap-* in flex/grid, not space-* or child margins
4. Test both modes — Always verify light AND dark mode appearance
5. Accessibility first — Every interactive element needs visible focus states and proper contrast