Skip to content

Documentation improvement: clarify migration expectations before Tailwind v4 installation steps #19717

@dm-uvarov

Description

@dm-uvarov

Problem

While following the installation documentation, it may not be obvious to users coming from Tailwind v3 that the configuration and setup workflow has significantly changed in v4.

Migration information already exists in the upgrade guide, but users who start from the installation page may not realize they should review migration guidance first.

Expected behavior

The installation documentation should clearly indicate that Tailwind v4 introduces breaking workflow differences compared to v3 and guide migrating users to the upgrade guide before beginning setup.

Actual behavior

Users may attempt to apply v3 configuration patterns during installation, which can lead to confusion or failed setup before discovering migration differences.

Suggested improvement

Consider adding a short visible note near installation/setup sections indicating that:

  • Tailwind v4 setup differs from v3
  • migrating users should review the upgrade guide before installation.

Additional context

I searched existing open and closed issues related to Tailwind v4 migration and found they mainly address runtime or upgrade bugs, but not documentation expectations prior to installation.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions