chore: upgrade Tailwind CSS v3 → v4 (breaking change)

[josecelano]

Overview

Upgrade tailwindcss from v3.4.x to v4.x along with related packages:

• tailwindcss: ^3.4.17 → ^4.x
• prettier-plugin-tailwindcss: ^0.6.x → ^0.7.x
• @tailwindcss/typography: ^0.5.x (check v4 compatibility)
• @tailwindcss/forms: ^0.5.x (check v4 compatibility)
• @tailwindcss/container-queries: ^0.1.x (check v4 compatibility)

What's New in v4

Tailwind CSS v4 is a ground-up rewrite with a new CSS-first configuration model:

• CSS-first config: Configuration moves from tailwind.config.ts to CSS using @theme directive
• New engine: Oxide engine — significantly faster builds
• No more tailwind.config.ts: Replaced by CSS variables in @layer theme
• Automatic content detection: No more content array needed
• New plugin API: Plugins updated to use new CSS-based approach
• PostCSS changes: Different PostCSS plugin setup

Breaking Changes

• tailwind.config.ts format is deprecated in favour of CSS config
• Plugin packages (@tailwindcss/typography, @tailwindcss/forms, @tailwindcss/container-queries) have new v4-compatible versions
• Class name changes for some utilities (e.g. shadow-sm renamed)
• postcss.config.js needs updating

Required Work

1. Update packages

npm install tailwindcss@^4

2. Migrate configuration

• Migrate tailwind.config.ts to CSS-first approach in src/app.css
• Update postcss.config.js

3. Update plugin imports

Verify plugin compatibility with v4.

4. Testing Checklist

• All pages render correctly
• Responsive layouts work
• Typography plugin styles apply correctly
• Form styles work
• Container queries work
• Build completes successfully
• No TypeScript errors

Resources

• Tailwind CSS v4 migration guide
• Upgrade guide

Priority

Medium — significant migration effort, should be done in isolation.

Part of

Epic: Major dependency upgrades tracking issue