Tailwind v4 Support - RFC and Status Update

[endigo9740]

Hey everyone, Chris here from the Skeleton team. Today I wanted to share a status update regarding our recent delay to Skeleton v3, as we update to support Tailwind v4. As well as talk about our initial findings for updating an improving existing features. This also comes with two new RFCs shared near the bottom of this post.

NOTE: RFC stands for "Request for Comment". It means we're proposing significant changes to the library and wish to gather feedback and questions from the community as quickly as possible. Look for the sections tagged "RFC" below and please share yourt thoughts in the comment section below or on Discord.

Status update on Tailwind v4 Support

Onboarding Improvements

First up, we wanted to let everyone know that we've completed the initial phase on our Tailwind v4 roadmap. This included updating the Skeleton v2 and v3 onboarding, pinning CLI tooling to set versions, which will in return limit installation to Tailwind v3 for now. Generally speaking you should also find the Skeleton v2 onboarding to be much more streamlined.

• v2 Onboarding: https://www.skeleton.dev/docs/get-started
• v3 Onboarding: https://next.skeleton.dev/docs/get-started/installation

Tailwind v4 Audit

Additionally, we've completed our initial audit of Tailwind v4. You can find a full run down of our findings in the written post or video below. Note the written post is slightly more up to date though!

• Written Notes: Tailwind v4 Audit
• Video Walkthrough: Watch on YouTube

Generally speaking we have moved from a theoretical understanding of the changes, to working knowledge after going hands on with our own prototypes. As such we've discovered a number of ways Tailwind v4 can improve Skeleton, which we'll cover below.

Using Sass to Generate Dynamic CSS

Once of the biggest challenges of the new rewrite is moving from the Javascript-based plugin in Tailwind v3 to the CSS-only configuration in Tailwind v4. In previous versions we relied heavily on Javascript to abstract, loop, and generate repetitive properties and classes. This includes a few of the following features:

• Color Properties: (ex: --color-primary-500) - combines 7 color names and 11 shades
• Contrast Color Properties (ex: --color-primary-contrast-500) - same as the base color properties
• Color Pairings - (we'll cover this in more detail below)
• Presets - (we'll cover this in more detail below)

In the previous JS-based plugin, everything was defined using a CSS-in-JS format, which enabled access to JS constants and iterative loops to generate CSS properties and classes. Here's a quick example of that in practice:

export const extendColors = () => {
	// Loop Color Names
	settings.colorNames.forEach((colorName) => {
		// Generate Base Colors
		colorPalette[colorName] = generatePaletteRamp(colorName, '');
		// Generate Contrast Colors
		colorPalette[`${colorName}-contrast`] = generatePaletteRamp(colorName, '-contrast');
	});
	return { colors: colorPalette };
};

While we've truncated for space, generally speaking we loop through each available color name (ex: primary, secondary, ..., surface), generate a color ramp per each shade (ex: 50-950), then feed those values into our plugin, which allows Tailwind to make use of them.

For Tailwind v4, all configuration is now CSS-based, which means we need a replacement for these JS features. We spent the last week testing everything from CSS-in-JS tools (Vanilla Extract, Panda CSS, etc), to generic templating tools (EJS), to contemplating rolling our own home-grown tooling. However, we've settle on a extremely novel solution - we're now building select portions of Skeleton using Sass (aka Syntactically Awesome Style Sheets).

NOTE: for clarity, Sass is used ONLY by maintainers of Skeleton. It will not be a dependency for end users.

If you've been in the web world for the last ten or so years, you may already be aware of Sass. In many ways it's the predecessor to Tailwind. Before utility class systems were popular, folks leaned on Sass to provide many features not originally provided by native CSS - such as Variables and Nesting. However, we can now lean on this to solve a number of hard problems for authoring our styles in Skeleton:

• Shared import variables - which can be looped!
• Iterative loops - for creating properties/classes/etc
• Syntax highlighting is fully supported in code editors
• And high quality documentation for contributors to reference

The result is we can dynamically generate repetitive CSS quickly very quickly and easily - we simply import our source values and iterate with a loop like so:

@use '../internal/constants.scss';

@theme {
	@each $color in constants.$colors {
		@each $shade in constants.$shades {
			$contrasting-shade: 1000 - $shade;
			--color-#{$color}-#{$shade}-#{$contrasting-shade}: light-dark(
				var(--color-#{$color}-#{$shade}),
				var(--color-#{$color}-#{$contrasting-shade})
			);
			--color-#{$color}-#{$contrasting-shade}-#{$shade}: light-dark(
				var(--color-#{$color}-#{$contrasting-shade}),
				var(--color-#{$color}-#{$shade})
			);
		}
	}
}

If you would like to learn more, I'd recommend checking out this post by long time Skeleton contributor @Hugos68. He goes in a bit further into the technical side for why and how this works:

• https://hugokorte.vercel.app/blog/authoring-a-tailwind-library-with-sass

Deprecating Redundant Features

Additionally, we've come to realize that Skeleton currently provides two features that have now been absorbed into the Tailwind core. These include the following:

• Radial/Conic Gradients - Tailwind v4 | Skeleton v3
• Dynamic Spacing - Tailwind v4 | Skeleton v3

We never set out to predict the future, but just try to add features that we think can benefit users. That said, our goal is not to replace Tailwind, but augment and extend it. As such, we will be removing the redundant Skeleton features. Moving to adopt Tailwind's --spacing property in favor of Skeleton's --space-scale-factor in our theme settings.

Color Scheme for Color Pairings

Speaking of overlapping features, Tailwind v4 now supports new CSS features such as light-dark() and color-scheme. Together these enable a new way to selectively toggle between two specific color values - typically for light/dark interfaces.

If that sounds familiar, it's because it's analogous to Skeleton's own Color Pairing system! However, given this feature is fully native, this comes with a number of benefits. For example, we can now just lean into Skeleton's @theme properties and implement pairings as Tailwind colors, like so:

@theme {
    --color-surface-50: white;
    --color-surface-950: black;
    --color-surface-50-950: light-dark(var(--color-primary-50), var(--color-primary-950));
}

We no longer have to emulate these using custom rolled utility classes. It also means this fully supports all Tailwind color properties (ex: bg-*, text-*, fill-*, etc) out of the box! If Tailwind adds a new color property in the future, it just works, no change required on our end.

Additionally, by pairing this with color-scheme you will now be able to selectively toggle the light/dark "scheme" at any scope on the page - be that the entire page, a particular section, or even a particular component. See Tailwind's doc for a quick example. Note this is completely isolated and independent of Dark Mode. Though you can certainly pair these together.

Furthermore, color pairings are now just treated as if they are first-class Tailwind colors. This means they can take full advanrage of Tailwind's new color transparency mechanics, which use Color Mix. The result is all Skeleton color pairing classes finally support transparency!

<!-- This will have 75% opacity! -->
<div class="bg-primary-50-950/75">...</div>

RFC: Proposed Preset Changes

Building on the changes to Color Pairing, the team and I have began to rethink Skeleton's Presets system (aka "Variants" in Skeleton v2). These are a group of canned classes that can be used to style common UI elements such as buttons, cards, etc.

While Presets are a hugely popular feature in Skeleton (even among our team), today I want to bring forth a proposal to remove this as a feature provided and maintained by Skeleton. To help explain this, let's look at the source of a few Presets to understand what they represent:

/* Filled */
.preset-filled-primary-50-950 { @apply bg-primary-50 dark:bg-primary-950 text-primary-contrast-50 dark:text-primary-contrast-950 }

/* Tonal */
.preset-tonal-primary { @apply bg-primary-950 dark:bg-primary-50 text-primary-50 dark:text-primary-950 }

/* Outlined */
.preset-outlined-primary-50-950 { @apply border border-primary-50 dark:border-primary-950 text-primary-50 dark:text-primary-950 }

• Filled: this sets the light and dark mode background and text color (affects text and SVG fill color)
• Tonal: this is a canned and inverted pairing that provides a "faded" style
• Outlined: similar to filled, but affecting border instead of background

Per the new Color Pairing changes describe above, we can now simplify these down to the following:

/* Filled */
.preset-filled-primary-50-950 { @apply bg-primary-50-950 text-primary-contrast-50-950 }

/* Tonal */
.preset-tonal-primary { @apply bg-primary-950-50 text-primary-50-950 }

/* Outlined */
.preset-outlined-primary-50-950 { @apply border border-primary-50-950 text-primary-50-950 }

This begs the question - if Presets only represent a couple primitive utility classes, then why do they exist at all? Why break away from Tailwind's Utility-First approach to styling? In fact, there's a few caveats that exist because of these abstractions:

• You cannot easily modify or mix and match background vs text/fill colors
• You cannot mix and match colors and styles between modes or schemes
• You cannot easily modify the border size for the Outlined presets (overwriting is bad practice in Tailwind)
• You cannot utilize the new opacity settings provided by the new color pairing system

We're already encouraging folks generate their own Presets for things like input validation and gradients. So why not make this the default stance for the library? Shorter/reusable/representative classes obviously have a benefit in practice. But maybe those are better maintained in user-land rather than by Skeleton?

The Proposal

Presets become a technique rather than a Skeleton-provided feature. This would include the following changes.

1. We drop all pre-generated Presets from the core library (filled, tonal, outline)
2. We provide even more documentation and examples for generating your own Presets
3. The Presets section moves from the "Design" -> "Guide" top-level category section
4. Custom presets become custom classes in your global stylesheet built using our primitives

NOTE: If desired, Skeleton can provide an optional and opinionated set of Presets pre-generated for users. This would come in the form of an extra CSS stylesheet you would import into your project. This would exist in Skeleton v3, but likely be permanently removed starting in Skeleton v4+

As this is an RFC, please know what you think in the comments below!

RFC: Proposed Typography Improvements

Finally, we have one more change for your consideration - replacing Skeleton's type-scale system for Typographic Scale, with a more direct implementation for Tailwind's built-in text classes. Currently this operates by setting the following scale factor - which is then used to calculate the text sizes for type-scale-[1-13]

--type-scale-factor: 1.125

For a quick comparison, here's what Skeleton's dynamic type-scale classes look like compared to the semantic (but fixed size) classes provided by Tailwind:

Our original intention was to keep dynamic scaling typography system separate from Tailwind's built-in text classes. However, after viewing what Tailwind is doing with Spacing (updating the existing mechanic in place) - we think we've taken the wrong approach for Typography. Instead of updating in place, we've duplicated all type sizes, which is very confusing in practice.

Proposal

The proposal here is simple - Skeleton simply removes the type-scale utilities and applies the scaling factor to all existing Tailwind utility classes, such as text-base, text-xl, etc. And if you prefer not to use this feature, we'll default to Tailwind's existing scale out of the box. No modification required.

The benefits here are numerous:

1. A single system instead of two
2. Semantic names to quickly differentiate each text size (sm, mg, lg) instead of numbers (1-13)
3. You get all the benefits of the scaling from your theme settings
4. You can now apply scaling more broadly on demand (base text size, etc)

NOTE: theme properties for headings/base/anchors are unaffected, and classes like .h1 and .anchor continue to operate exact as they do now. Again this ONLY removes type-scale-* classes.

The downside is there may be a small migration for any existing Skeleton v3 user that's already using the type-scale primitives. However, we may be able to automate correcting these using Skeleton's new CLI migration tool.

Once again, this is an RFC, so we welcome your feedback in the comments below!

[MrVauxs]

I am down to removing vestigial code as the RFCs suggest. The type scale I didn't even notice at first, while the presets I'd accept removing, though it would be nice if example code would be more prevalent in the tutorials, like as an optional step to the Installation page.

[endigo9740]

Yeah I think a lot of folks missed the type-scale system outright, an those that did notice it were confused with where and how to use it versus built-in text sizes. I also forgot to mention Tailwind's solution covers line-height which our's always lacked! So I'm extremely keen to make this change.

Per Presets - we would likely completely overhaul the documentation for this and move the section from "Design System" over to "Guides". Much like the Layouts section, this would teach you how to fish rather than giving you a fish by default. However we would still give you the fish as well through the optional stylesheet that would contain likely all current Preset classes pre-generated for you. At least until our next major version where we can make the call if it feels safe to remove for good.

[cassepipe]

All proposed changes seem very sound in my modest opinion. I'd ust like to say that as a beginner that was very happy to discover Skeleton, it was great to use/play with the default variants/presets so hooray to keep them in a extra scss sheet

[endigo9740]

Glad to hear Cassepipe - just FYI .scss is ONLY for authoring the styles, like when we're maintaining the source. Anything you import and use in Tailwind will just be plain old .css following Tailwind v4's new conventions. We definitely don't want to give the impression Sass is needed for the end users!

NOTE: I've appended a small note the the article above to clarify this point!

[TAS-ApeNomad]

I've hit a few instances where I felt constrained by the presets and agree that moving this to user-land makes the most sense. Anything which can be made less redundant and fixed in place seems to offer more flexibility in the end. I do agree that examples of add-ons for basic presets for those that don't want or need to roll their own bridges any gap there.

[Cikmo]

There's definitely something to be said about having presets that allow you to quickly throw something together without too much manual boilerplate. It's pretty much the whole point of a UI library, in the end.

Personally I build a lot of smaller projects using Skeleton, and having to create the presets each time would add a little more "boring" stuff to do before I could actually start creating. Even if it's just copy-pasting it from previous projects.

But in the end, it probably doesn't matter too much, I just wanted to mention something that could be an argument against removing them.

[endigo9740]

Make sense @Cikmo, we definitely understand that folks like turnkey nature of Presets in their current form. That's part of why we raise this as part of an RFC. I was curious to hear how folks use Presets and how open they are to the concept of rolling their own.

I think this is kind of a double edge sword. Sometimes it's nice to just be able to use the stock options, especially if you're in a hurry. But there's something I call the "Bootstrap effect", where back in the day you could always identify an app built using Bootstrap because they were so homogenous. In most cases only swapping out the colors and small implementation details. This was not inherently a good or bad thing, just an observation.

With Skeleton I've always wanted it to be more of a chameleon, in that it should adhere to the aesthetic you're building for your brand and your project. Not the other way around. Which is why I'm so glad that in v3 we're finally making the distinction that the core is a design system and components are an optional aside to this.

I'm curious to see the reception to this as I'm not aware of other projects that take this strategy. Typically you're scaffolding your own design system from the ground up, or you're using rudimentary theme systems provided by a component library. This idea of a library that provides guidance and assets for both is super cool IMO. Though I'm a bit partial :)

[jhechtf]

I would agree with what Cikmo says - a lot of the reason i chose Skeleton over [insert other ui setup] was because the presets all looked pretty good with some exception (looking at you, default theme success color) and there were just enough components in it to save me some time. Without them, or with me having to generate them myself, I don't know that I'd have a very strong reason to use Skeleton beyond the one project that has it.

I was also the "big dissenter" in the v2 way the modals and drawers were setup to use stores, which has meant that i've had to roll my own versions and mimic the styling. Full disclosure I've not been able to upgrade to V3 (too much other work to do) but in reading the docs I can't say I like the new direction any more even after giving it some time to settle.

This is obviously just me, but this move feels like I'm just that much closer to "just use Tailwind".

[ddxv]

As a light but enthusiastic user I fully support these changes.

In my opinion after reading the above I would like to remove the --presets from my existing v3 projects and use the built-in tailwind.

So perhaps in the migration guide that could be covered clearly?

[endigo9740]

So perhaps in the migration guide that could be covered clearly?

We're very diligent about posting migration steps when there's a notable change. Expect the same when this occurs! Note these changes are merely proposed at the moment, and we're only starting to rewrite the "plugin" this week.

[jibbewillem]

I love using class="badge variant-soft-primary" for quick styling. But I did run into customization issues a few time where I needed to remove the variant style and added my own background/text color. So I won't grieve the removal of variants. The only thing I would ask for is a page in the docs that shows off some possible variants, so I can steal them without draining all my creative energy on coming up with them myself.

I also like your comment about the Bootstrap-effect. You need to draw a line somewhere between supplying all components and making users come up with their own. I agree drawing the line a bit closer to the user-side, like how Skeleton has been doing.

On all the other changes: using Tailwind for all the thing we can is the best approach in my opinion. So, migrating to native solutions is something I won't complain about.

[endigo9740]

Just FYI for anyone that is curious, what we called Variants in prior versions of Skeleton are now referred to as Presets. Same concept, but they received their original name in the early days of Skeleton before we realized this conflicted with a concept built-into Tailwind already:

https://tailwindcss.com/docs/functions-and-directives#variant-directive

And just a quick update - I implemented Presets nearly 1:1 in the new Tailwind v4 version of Skeleton yesterday! Right now they are still built into the core and available by default. But I may still look to abstract them away to an optional stylesheet before the next public release.

Just wanted to reassure everyone that Presets are not going away, they're already implemented, it's just a matter of whether they are enabled by default or not.

[Cikmo]

I think I agree with @jibbewillem that it would be helpful to include some example presets (the ones currently built-in) in the docs. That way, users who don’t want to create their own can simply yoink them, rather than relying on a separate stylesheet. It feels like the best of both worlds in that you're moving it to user land while still having them premade for those that want it.

[endigo9740]

Agreed. If possible I'd actually like to provide the source for the entire set of presets in a non-minified form so it can be linked and reference directly. This will make the stylesheet a bit larger in the NPM package, but your app's version of Tailwind will minify any styles consumed still. The trade off in readability may be worthwhile here. Otherwise we will rework the Presets page to focus on examples of building your own, referencing these just as you stated.

[officialankan]

I really like the variants/presets feature of skeleton and I think it is one of the main reasons for being quick to use and adopt as a non-UI-developer. But hey, I understand if you want to take a step back - just keep a guide for the CSS n00bs like me :)