Skip to content
Documentation

Tailwind CSS Version Policy

Current Version

Section titled “Current Version”

Tailwind CSS: ^3.4.0
Last Updated: 2026-01-28

Policy

Section titled “Policy”

The marketing site (apps/site) uses Tailwind CSS v3 and will remain on v3 until a planned migration to v4 can be executed with proper testing and code updates.

Rationale

Section titled “Rationale”

  1. Breaking Changes: Tailwind CSS v4 introduces significant breaking changes:

    • PostCSS plugin architecture changed (requires @tailwindcss/postcss)
    • Utility class syntax changes (e.g., !important is no longer valid)
    • Theme function syntax changes (e.g., theme(colors.teal.400))
    • Configuration format changes

  2. Code Compatibility: The existing site was built for Tailwind v3 and uses:

    • !important utility modifiers
    • theme() function calls in CSS
    • Tailwind v3 configuration patterns

  3. Build Stability: Tailwind v3 builds successfully with the current codebase and deployment pipeline.

  4. Migration Effort: Upgrading to v4 requires:

    • Auditing all utility classes across the codebase
    • Updating theme function calls
    • Testing all components and pages
    • Updating build configuration
    • Verifying Cloudflare Pages compatibility

Version History

Section titled “Version History”
DateVersionReason
2026-01-28v3.4.0Downgraded from v4.1.18 due to breaking changes causing build failures
2026-01-28v4.1.18Initial version (caused build failures)

Migration Plan (Future)

Section titled “Migration Plan (Future)”

When migrating to Tailwind CSS v4:

1. Preparation

Section titled “1. Preparation”
  • Create a feature branch for the migration
  • Audit all utility classes in the codebase
  • Identify all theme() function calls
  • Review Tailwind v4 migration guide

2. Code Updates

Section titled “2. Code Updates”
  • Update all !important modifiers to v4 syntax
  • Update all theme() function calls
  • Add @tailwindcss/postcss package
  • Create PostCSS configuration
  • Remove @astrojs/tailwind integration (if incompatible)

3. Testing

Section titled “3. Testing”
  • Test all pages locally
  • Verify responsive layouts
  • Check dark mode functionality
  • Test animations and transitions
  • Verify build output

4. Deployment

Section titled “4. Deployment”
  • Deploy to staging environment
  • Visual regression testing
  • Performance testing
  • Deploy to production
Section titled “Related Documentation”

Incident Report: 2026-01-28

Section titled “Incident Report: 2026-01-28”

Issue

Section titled “Issue”

Cloudflare Pages build failed after a documentation tooling update was pushed to production.

Root Cause

Section titled “Root Cause”

The site had Tailwind CSS v4.1.18 installed, which has breaking changes incompatible with the existing codebase.

Error Messages

Section titled “Error Messages”
Error: Cannot apply unknown utility class `!important`
Error: Could not resolve value for theme function: `theme(colors.teal.400)`

Resolution

Section titled “Resolution”
  1. Downgraded tailwindcss from ^4.1.18 to ^3.4.0
  2. Removed @tailwindcss/postcss package (v4-specific)
  3. Removed postcss.config.mjs (not needed for v3)
  4. Restored @astrojs/tailwind integration
  5. Verified build success locally and in CI

Prevention

Section titled “Prevention”
  • Document version policy (this page)
  • Pin Tailwind CSS to v3 in package.json
  • Add migration plan for future v4 upgrade
  • Test builds locally before pushing to production

Timeline

Section titled “Timeline”
  • 09:35 UTC: Build failure detected on Cloudflare Pages
  • 09:36 UTC: Root cause identified (Tailwind v4 breaking changes)
  • 09:38 UTC: Downgraded to Tailwind v3
  • 09:39 UTC: Build successful
  • 09:40 UTC: Changes committed and pushed

Notes

Section titled “Notes”
  • The docs site (apps/docs) does not use Tailwind CSS and is unaffected by this policy.
  • This policy applies only to the marketing site (apps/site).
  • When Tailwind v4 migration is planned, create an ADR documenting the decision and approach.