[Feature] Upgrade to Tailwind v4 🎉

[antoine4livre]

Issue #122

Sub issues

• Upgrade to Tailwind CSS v4 #121
• Migrate to an ESM only package #123
• Replace VuePress documentation #124
• Remove unused/obsolete plugins #127
• Upgrade GitHub Action #125
• Upgrade default Node version #126

---

Here is a list of solutions to keep features of the @studiometa/tailwind-config v2 after the migration.

Before upgrading check the compatibility of Tailwind v4 with your project. For all changes between Tailwind v3 and Tailwind v4, refer to the official upgrade guide.

Important

Tailwind CSS v4.0 is a full-featured CSS build tool designed for a specific workflow, and is not designed to be used with CSS preprocessors like Sass, Less, or Stylus.

Theme

Screens

Breakpoints now matches with the default configuration with custom names and additional values:

- xxs: 0px
- xs: 480px
+ xs: 30rem (480px)
- s: 768px
+ s: 40rem (640px)
- m: 1024px
+ m: 48rem (768px)
- l: 1280px
+ l: 64rem (1024px)
- xl: 1440px
+ xl: 80rem (1280px)
- xxl: 1920px
+ 2xl: 96rem (1536px)
- xxxl: 2560px
+ 3xl: 120rem (1920px)

Layers

Custom layers (z-indexes) declaration has been removed because Tailwind v4 handle them natively.

Transition timing function

In addition to the default values, our custom timing functions are unchanged, check the declaration.

Top / Right / Bottom / Left

Custom inset values declaration has been removed because Tailwind v4 handle them natively.

Plugins

All plugins have been removed, check the reasons and alternative solutions below.

Breakpoint

The breakpoint plugin was used for the breakpoint recognition in the @studiometa/js-toolkit but is no longer used since the usage of a config object.

Font-Face

Manual @font-face declaration takes the same amount of time and many projects use remote font CDN.

Float Grid

Our legacy (float) grid plugin has been removed because modern projects use grid or flex layouts.

Custom container

The core container plugin has been removed in Tailwind v4 and our custom container plugin too.
Use a custom utility instead:

@utility container {
  max-width: 90rem;
  margin-inline: auto;
  padding-inline: 2rem;
  @screen m {
    padding-inline: 4rem;
  }
}

Variant factory

Use the simple custom variant native declaration instead. Note that the direct children selector variant is native in Tailwind for a while.

Example with a "hocus" variant:

@custom-variant hocus {
  &:hover, &:focus {
    @slot;
  }
}

Typography

This third party plugin can be replaced with a custom utility:

@utility type-h1 {
  font-size: 4rem;
  font-weight: 700;
  line-height: 1.2;
  letter-spacing: -0.02em;
}
/* or */
@utility type-h2 {
  @apply text-lg font-bold tracking-wide;
}

[titouanmathis]

Nice upgrade!

Some adjustments to the docs, we are nearly there.

[titouanmathis]

👍

Before merging, can you add a CHANGELOG.md file based on our other packages?

[titouanmathis]

Minor changes for the actions