feat!: support Tailwind v4

[unseen-ninja]

This PR aims to provide a semi-automatic SASS-based build system to generate viable configs for Tailwind v4. (#19)

The current setup generates two distinct files.

1. shades.css is home to all of Catppuccin's colours and the different tints and shades tailwind expects. Tints and shades are only generated for each of the 14 accent colours.
2. tailwind.config.css then is the actual config tailwind uses. This builds on top of shades.css therefore it needs to be imported in your CSS structure!

The Tailwind config provides default colours for light and dark mode (set to be latte and mocha respectively) as well as flavour classes and custom variants for each of the four flavours.

In short a demo config file would look like this:

@import "tailwindcss";


/* from shades.css */
:root {
  --catppuccin-latte-mauve: #8839ef;
  --catppuccin-latte-base: #eff1f5;
  --catppuccin-frappe-mauve: #ca9ee6;
  --catppuccin-frappe-base: #303446;
  --catppuccin-macchiato-mauve: #c6a0f6;
  --catppuccin-macchiato-base: #24273a;
  --catppuccin-mocha-mauve: #cba6f7;
  --catppuccin-mocha-base: #1e1e2e;
}



/* from tailwind.config.css */
@theme inline {
  --color-ctp-mauve: var(--catppuccin-mauve);
  --color-ctp-base: var(--catppuccin-base);
}


@layer base {
  :root {
    --catppuccin-mauve: var(--catppuccin-latte-mauve);
    --catppuccin-base: var(--catppuccin-latte-base);
    @variant dark {
      --catppuccin-mauve: var(--catppuccin-mocha-mauve);
      --catppuccin-base: var(--catppuccin-mocha-base);
    }
  }
  .latte {
    --catppuccin-mauve: var(--catppuccin-latte-mauve);
    --catppuccin-base: var(--catppuccin-latte-base);
  }
  .frappe {
    --catppuccin-mauve: var(--catppuccin-frappe-mauve);
    --catppuccin-base: var(--catppuccin-frappe-base);
  }
  .macchiato {
    --catppuccin-mauve: var(--catppuccin-macchiato-mauve);
    --catppuccin-base: var(--catppuccin-macchiato-base);
  }
  .mocha {
    --catppuccin-mauve: var(--catppuccin-mocha-mauve);
    --catppuccin-base: var(--catppuccin-mocha-base);
  }
}

[unseen-ninja]

This is how it could look in the end: https://play.tailwindcss.com/eYXckDj09D

[ghost]

What do we need to ship this?

[unseen-ninja]

What do we need to ship this?

We're currently in the progress of implementing tints and shades into ctp/palette. To implement it fully and officially for TW (v4) we want to rely on the official NPM package in order to future proof the TW port. Once everything is published on NPM we'll quickly get this into TW and all other applicable places as well.

[twhite96]

We're currently in the progress of implementing tints and shades into ctp/palette. To implement it fully and officially for TW (v4) we want to rely on the official NPM package in order to future proof the TW port. Once everything is published on NPM we'll quickly get this into TW and all other applicable places as well.

Is this still usable? I want to use it in an Astro project theme picker but am not sure of the compatibility with TW4 and the tailwind typescript config. If not I'll revert to the default tailwind theme as I am not shipping just yet.

[42willow]

We're currently in the progress of implementing tints and shades into ctp/palette. To implement it fully and officially for TW (v4) we want to rely on the official NPM package in order to future proof the TW port. Once everything is published on NPM we'll quickly get this into TW and all other applicable places as well.

Is this still usable? I want to use it in an Astro project theme picker but am not sure of the compatibility with TW4 and the tailwind typescript config. If not I'll revert to the default tailwind theme as I am not shipping just yet. @twhite96

I'm doing exactly the same thing as you at the moment. It's usable, but will definitely change in the future (at the very least how it's imported). At the moment I'm installing and importing it in an incredibly scuffed way like this:

$ bun install github:catppuccin/tailwindcss#feat\!/tailwindcss-v4

@import "@catppuccin/tailwindcss/docs/src/styles/palette.css";
@import "@catppuccin/tailwindcss/docs/src/styles/tailwind.config.css";

Here's the message from @unseen-ninja on discord:

treat that more like … a not-even alpha iteration. which means.. right now there is no cleaner way of importing everything. i was a bit all over the place over the past couple weeks hence there wasn't any real progress on that front. i do have that on my todo list for this week tho – hopefully i'll actually get around to it!

[unseen-ninja]

Following up on this; Both the import method – the two file right now are quite messy to import – is 100% going to get changed to something more reasonable. With the update of ctp/palette there will also be changes to the colours due to the fact that we a) generate them in another colour space compared to this draft and b) revamped blending intensities – these will mostly impact the shades, which are going to be a tad lighter. I would advise against using the stuff in this draft for anything in production.

[sgoudham]

I should have some time this upcoming weekend to get back to this PR.

The plan will be to publish a beta v2 of catppuccin/palette and ingest that into this PR, and then a beta v1 of catppuccin/tailwind for people to try out in their applications.

[unseen-ninja]

On build this now generates ./dist/tailwind.config.css which can be imported into whatever tailwind project. In the long run the plan is to serve that through node modules for easier handling. ✨

[sgoudham]

Happy to report that @catppuccin/[email protected] is now available, supporting TailwindCSS 4.

After installing the beta version, please follow the instructions from step 2. on the README to learn how to import and use the theme.

The package will stay in beta until v2.0.0 of @catppuccin/palette has officially released, but I personally don't see anything changing colour wise ( :crossed_fingers: ) - Of course, huge thanks to @unseen-ninja for doing 99% of the work on this :heart:

Pinging people that have reacted as they are most likely interested: @42willow @lundjrl @stephansama @twhite96

[stephansama]

This is amazing thank you for pinging Mr. Goudham

[lundjrl]

Yes yes this was the first thing I woke up to this morning. Thank you sir! @sgoudham

[darallium]

Thanks for handling v4!

I'm worrying about the static configuration files the sass seems dynamical but not for the users. users have might be able to switch the prefixes or something else

[sgoudham]

I've published @catppuccin/[email protected] which supports using frappe and macchiato for the dark variant, see step 2. from the README for the updated instructions.

This is a breaking change from 1.0.0-beta.1 , you can easily migrate by replacing config.css with mocha.css if you were using it:

@import "tailwindcss";
- @import "@catppuccin/tailwindcss/config.css";
+ @import "@catppuccin/tailwindcss/mocha.css";

[sgoudham]

I'm worrying about the static configuration files the sass seems dynamical but not for the users. users have might be able to switch the prefixes or something else - @darallium

Yeah, one approach that I was thinking about is providing some sort of CLI generator if users want to change the prefix. However, I'm not sure if I want to allow people to customise it easily here.

-ctp is the default prefix which is short, concise and used in other places across the organisation. If a user were to make it an empty prefix, they will unfortunately run into #16 as an issue. This might be a naive opinion from me, but I don't really think people would want to change the prefix to something other than -ctp if it being empty introduced problems?

(Fwiw, @unseen-ninja and I tried to think of other solutions to avoid the conflicting class problem entirely but we weren't happy with any of the other alternate solutions that we thought of (e.g. renaming base to something else, etc)

Happy to discuss further on that topic though.

[darallium]

-ctp is the default prefix which is short, concise and used in other places across the organisation. If a user were to make it an empty prefix, they will unfortunately run into #16 as an issue. This might be a naive opinion from me, but I don't really think people would want to change the prefix to something other than -ctp if it being empty introduced problems?

(Fwiw, @unseen-ninja and I tried to think of other solutions to avoid the conflicting class problem entirely but we weren't happy with any of the other alternate solutions that we thought of (e.g. renaming base to something else, etc)

Happy to discuss further on that topic though.

yeah ofcourse ctp prefix is better than most personally, i prefer to use -cp prefix because -ctp conflicts with my personal themesets. and the problems is not only for the prefix. e.g, my website collapsed because older version can set the default theme color but cannot in this version. fortunately i could understand how this and olds work but worrying about someone report as issue however, the implementations is not very needed because beta i think

[JasonLovesDoggo]

default prefix which is short, concise and used in other places across the organisation. If a user were to make it an empty prefix, they will unfortunately run into #16 as an issue. This might be a naive opinion from me, but I don't really think people would want to change the prefix to something other than -ctp if it being empty introduced prob

Personally i've been using my own variant of https://play.tailwindcss.com/eYXckDj09D for the past 4ish weeks on my WIP portfolio. I reset all other tailwind colors

@theme {
	--color-*: initial;
}

before importing my catppuccin theme to not accidentally use any other colors. I really enjoy just using no prefix. A simple workaround that I have for text-base is just define a utility named text-normal which just does the same thing. Just giving my 2c on why no prefix should be supported IMO.

[sgoudham]

Just giving my 2c on why no prefix should be supported IMO.

Sure. It's worth mentioning that because Tailwind v4 simplifies the process so much into static files. We can't support any sort of dynamic configuration.

One way or another, users will have search and replace the "ctp" prefix in the files that we provide or clone this repository, change the prefix, generate the CSS and then import as a separate file in their project.

[JasonLovesDoggo]

Just giving my 2c on why no prefix should be supported IMO.

Sure. It's worth mentioning that because Tailwind v4 simplifies the process so much into static files. We can't support any sort of dynamic configuration.

One way or another, users will have search and replace the "ctp" prefix in the files that we provide or clone this repository, change the prefix, generate the CSS and then import as a separate file in their project.

Yep, that's all fine. Perhaps the generation script (the scss) could support a custom prefix. All good if not, ctrl+r never fails me!

[unseen-ninja]

Yep, that's all fine. Perhaps the generation script (the scss) could support a custom prefix.

It's a quick change on line 9 – you can either specify another prefix, or just have it empty for no prefix.

Imho it's better to have the prefix for the main release in order to avoid the mentioned issue with text-base as otherwise it might confuse users who don't realise what is going on. We've thought about that a lot already, tried different ideas of working around it, and just came back to the prefix idea again and again.

[JasonLovesDoggo]

Yep, that's all fine. Perhaps the generation script (the scss) could support a custom prefix.

It's a quick change on line 9 – you can either specify another prefix, or just have it empty for no prefix.

Imho it's better to have the prefix for the main release in order to avoid the mentioned issue with text-base as otherwise it might confuse users who don't realise what is going on. We've thought about that a lot already, tried different ideas of working around it, and just came back to the prefix idea again and again.

Ah perfect. I saw -ctp- hard coded in the script somewhere so I assumed it would affect the output. Thanks!

[lundjrl]

I'm not trying to pollute the PR. Just wanted to express my thanks for all of you working on this ❤️ 🚀

[Cyberistic]

Could we get some sort of migration guide? We use the older version with no prefix so would need to go through hundreds of files.. is the current solution to compile the scss ourself?