Skeleton v3 + Tailwind v4 - RC2 Migration Guide

[endigo9740]

This guide covers the instruction for existing Skeleton v3 users to migrate to the latest release that supports Tailwind v4. This will require a manual migration to fully support the new configuration and feature changes.

As such, we'll utilize the following semantics to refer to the different versions of Skeleton v3:

• RC1 (Release Candidate 1) - the old version of Skeleton v3 that only supports Tailwind v3
• RC2 (Release Candidate 2) - the new version of Skeleton v3 that only supports Tailwind v4.

Prerequisites

Create a Migration Branch

We recommend using standard Git workflows to handle all migration changes on a dedicated feature branch. This ensures you can easily drop or revert changes if something goes wrong.

git checkout -b migration

Migrate to Tailwind v4

Please follow the official Tailwind documentation for migrating to Tailwind v4. This includes using their dedicated migration CLI to automate much of the process.

However, before migrating to tailwind V4 there are some manual steps required:

1. Remove the skeleton plugin from your tailwind.config file.
2. Rename your app.postcss or app.pcss to app.css.
3. Remove the purgecss (vite-plugin-tailwind-purgecss) vite plugin from your vite.config (if installed).

After doing these steps you can follow the Tailwind v4 Migration Guide

npx @tailwindcss/upgrade

NOTE: after upgrading, your app will temporarily be in a non-functional state since Skeleton is not yet updated.

The most notable change comes from moving from Tailwind configuration in tailwind.config to the new CSS-based configuration in your app's global stylesheet. We recommend backing up your tailwind.config as reference for the upcoming steps.

Migrate to the Tailwind Vite Plugin

NOTE: If you're using Next.js, skip this step. Next.js uses Turbopack in favor of Vite.

In the past, Tailwind was provided via a PostCSS plugin. In Tailwind v4, there is now a first-class Vite plugin. We recommend this for all supported projects, including: SvelteKit, Vite/Svelte, Vite/React, and Astro.

Using the following steps to migrate to from PostCSS to the Vite plugin:

1. Delete postcss.config.mjs
2. Run npm uninstall postcss @tailwindcss/postcss
3. Run npm install @tailwindcss/vite
4. Open your Vite config file in the root of your project:

• Astro: astro.config
• All other frameworks: vite.config

5. Import the following at the top of the file: import tailwindcss from '@tailwindcss/vite'
6. Finally, add the Vite plugin ABOVE your specific framework plugin:

plugins: [
    tailwindcss(),
    //  ex: svelte(), react(), sveltekit(), etc.
]

Migrate to Skeleton v3 RC2

Ensure both your core and component packages are updated for Skeleton.

For React Users:

npm i -D @skeletonlabs/skeleton@next @skeletonlabs/skeleton-react@next

For Svelte Users:

npm i -D @skeletonlabs/skeleton@next @skeletonlabs/skeleton-svelte@next

For most other frameworks:

npm i -D @skeletonlabs/skeleton@next

Run npm list (or similar for other package managers) to list the installed dependencies. Each package should meet or exceed the following versions:

@skeletonlabs/skeleton: 3.0.0-next.11
@skeletonlabs/skeleton-react: 1.0.0-next.15
@skeletonlabs/skeleton-svelte: 1.0.0-next.20

Migrate Tailwind Configuration

The most critical step is to ensure your app replaces the configuration lost when tailwind.config was removed. Open your app's global stylesheet and ensure the following is appended at the top of the file:

@import 'tailwindcss';
/* @plugin '@tailwindcss/forms'; */

@source '../node_modules/@skeletonlabs/skeleton-{react|svelte}/dist'; /* <-- set framework */

@import '@skeletonlabs/skeleton';
@import '@skeletonlabs/skeleton/optional/presets';
@import '@skeletonlabs/skeleton/themes/cerberus';

/* @custom-variant dark (&:where(.dark, .dark *)); */

You may need to adjust these settings to your preference:

• If you are using the Tailwind Forms plugin to enable form/input style normalization for Skeleton, uncomment the @plugin line above.
• Update the @source path to resolve to your node_modules and set the proper component name: react or svelte
• Skeleton's canned Presets are now optional. We recommend keeping this import, but review your options.
• If you're using a preset theme other than cerberus please change that now.
• Add additional theme imports for each theme you wish to register
• If you're using a Custom theme, we'll detail the migration process for that later in this guide.
• If you were using the Media Strategy for Dark Mode, remove the @custom-variant line.
• If you were using the Class Strategy for Dark Mode, uncomment the @custom-variant line.

If you had additional custom configuration in your tailwind.config that is not represented above, you'll need to consult the Tailwind v4 documentation and implement directly. This includes additional plugins, expanded theme or utility classes, etc. This is beyond the scope of Skeleton and this migration guide though.

CSS Class Name Changes

As part of updates to support the new and improved features in Tailwind v4, we've renamed and replaced a number of classes.

v3 RC1	v3 RC2
btn-xl	btn-lg
input-group-cell	ig-cell
(none)	ig-input
(none)	ig-select
(none)	ig-btn
type-scale-1	text-xs
type-scale-2	text-sm
type-scale-3	text-base
type-scale-4	text-lg
type-scale-5	text-xl
type-scale-6	text-2xl
type-scale-7	text-3xl
type-scale-8	text-4xl
type-scale-9	text-5xl
type-scale-10	text-6xl
type-scale-11	text-7xl
type-scale-12	text-8xl
type-scale-13	text-9xl
rounded	rounded-base

Mesh Gradients

If you're using CSS mesh gradient, you'll need to modify the syntax slightly to utilize the new color and transparency values.

/* v3 RC1 */

background-image:
  radial-gradient(at 24% 25%, rgba(var(--color-primary-500) / 0.30) 0px, transparent 30%),
  radial-gradient(at 35% 13%, rgba(var(--color-success-500) / 0.18) 0px, transparent 30%),
  radial-gradient(at 100% 64%, rgba(var(--color-error-500) / 0.03) 0px, transparent 40%);

/* v3 RC2 */

background-image:
  radial-gradient(at 24% 25%, color-mix(in oklab, var(--color-primary-500) 30%, transparent) 0px, transparent 30%),
  radial-gradient(at 35% 13%, color-mix(in oklab, var(--color-success-500) 18%, transparent) 0px, transparent 30%),
  radial-gradient(at 100% 64%, color-mix(in oklab, var(--color-error-500) 3%, transparent) 0px, transparent 40%);

Removing @apply

While this step is optional, we strongly encourage you take this opportunity to move away from any usage of @apply. Tailwind has long since advocated against this, and Tailwind v4 introduces new directives and functions that make this much easier to avoid. Here's a trivial example:

/* RC1 */

.foo {
	@apply bg-surface-50-950 text-surface-950 dark:text-surface-50 p-4;
}

/* RC2 */

.foo {
	background-color: var(--color-surface-50-950);
	color: var(--color-surface-950);
	padding: --spacing(4);
	@variant dark {
	    color: var(--color-surface-50);
	}
}

• Most usage should be in your global stylesheet or component <style> blocks.
• Refer to the Skeleton Core API documentation for a full list of Skeleton's CSS custom properties
• Refer to the Tailwind's functions and directives for information on how to utilize these new features

Move the Date Theme Attribute

The data-theme attribute which indicates your custom theme has moved from the <body> to the <html> tag. If you're using a theme other than cerberus then please change this accordingly.

<!-- RC1 -->
<body data-theme="cerberus">

<!-- RC2 -->
<html data-theme="cerberus">

Migrating Custom Themes

This step is only required if you implemented one or more custom themes in your application.

Tap here to expand and view the Custom Theme migration.

Tailwind v4 now provides first-class support for themes. In RC2, all Skeleton themes have been converted from a Javascript-based format that was previously fed into the Skeleton Tailwind plugin in tailwind.config, to a pure CSS-based file that you simply import in your global stylesheet.

You have two options for migrating your custom theme:

• Option 1: recreate your theme from scratch using the updated Theme Generator.
• Option 2: manually migrate your theme code, which we'll cover below.

NOTE: We'll use Skeleton's cerberus theme as an example, but make sure to replace all instances of the theme name.

Convert the File Format

Rename the theme file from .ts|.js to .css.

Convert to the CSS Boilerplate

Remove all Javascript boilerplate surrounding the list of theme properties.

/* Before */

import type { Theme } from './index.js';

const cerberus = {
	name: 'cerberus',
	properties: {
		/* List of Properties */
	},
	metadata: { version: '3.0.0', emoji: '🐺' }
} satisfies Theme;

export default cerberus;

/* After */

[data-theme='cerberus'] {
    /* List of Properties */
}

Update Theme Properties

Theme properties were previously stored in a Javascript object format, which included extra quotes and commas we no longer need. Edit each line to ensure they contain valid CSS custom property definitions:

TIP: Monitor your editor's syntax highlighting to ensure all properties are valid.

/* Before */

'--base-font-family': 'system-ui',
'--base-font-size': 'inherit',
/* ... */
'--base-font-family': 'system-ui',
'--base-font-size': 'inherit',
'--base-line-height': 'inherit',

/* After */

--base-font-family: system-ui;
--base-font-size: inherit;
/* ... */
--base-font-family: system-ui;
--base-font-size: inherit;
--base-line-height: inherit;

Remove These Properties

Skeleton RC2 no long requires the following properties. These should be removed from your theme:

• --type-scale-[1-13] - Type Scale feature which is now implemented into text-* classes.
• --outline-width-default - this is no longer controlled by the theme to avoid accessibility issues.

Rename These Properties

Likewise RC2 has renamed a few properties to ensure consistency with Tailwind v4's namespace conventions:

v3 RC1	v3 RC2
--space-scale-factor	--spacing
--type-scale-factor	--text-scaling
--radii-default	--radius-base
--radii-container	--radius-container
--border-width-default	--default-border-width
--divide-width-default	--default-divide-width
--ring-width-default	--default-ring-width

Change Property Value Formats

• --spacing - should now be represented in a rem format; default is 0.25rem
• --text-scaling - should be converted from a string to a float; default is 1.0
• --radius-[base|container] - should be converted from rem to px format
• --[base|heading|anchor]-font-family - make sure you're using a valid font-family list.

TIP: please refer to the Code output for the Theme Generator for specific examples.

Update Color Formats

Finally, Tailwind v4 now supports color transparency with any format due to the use of color-mix(). As such the restriction to RGB can now be lifted. You may now convert the current (invalid) color format, to any valid CSS color format. However, Skeleton is aiming to standardize on OKLCH format

Here's an example of before/after conversion. If you are using VS Code, we recommend the hex-to-rgb or oklchanger extensions to aid in this process. Otherwise, any standard converter will work, such this one for OKLCH.

/* Before */

--color-primary-500: 1 112 243; /* This is invalid CSS */

/* After */
/* NOTE: use a uniform format for all colors */

--color-primary-500: oklch(57.32% 0.2144 258.29); /* OKLCH */
--color-primary-500: rgb(1, 112, 243); /* RGB */
--color-primary-500: #0170f3; /* Hex */

Register and Activate Theme

Once all above theme migrations are complete, make sure you've registered and set and active theme per our documented instructions.

Support

Have a question or need support? Reach out in the comment section below, or within the #skeleton-next channel on our Discord.

[jdvlpr]

I migrated using this guide, thanks!

One minor typo in the CSS Class Name Changes section, I think:

ig-button should be ig-btn

Based on the docs here: https://next.skeleton.dev/docs/tailwind/forms/#groups

[endigo9740]

Fixed, thank you!