Migrate from v4

Skeleton v5 represents a notable update to the core API and theme layer. This improves and expands your theme's design tokens, introduces new Tailwind Components such as Disclosures, provides size options for buttons and form fields, establishes the new brand color properties, and more.

Prerequisites

For older versions of Skeleton, please complete the following guides before you proceed.

We recommend you handle all migration changes on a dedicated feature branch, allowing you to easily revert if needed.

git checkout -b migration

Make sure you’ve accounted for the following:

• Your app is running the latest release of Skeleton v4.x (4.15.2)
• All critical dependencies have been updated (optional but recommended)
• Your app is in a fully functional state before you proceed

For svelte, the minimum peer dependency has been raised from ^5.29.0 to ^5.40.0. React remains unchanged.

npm install svelte@latest

Automated Migration

To begin, use the Skeleton CLI migration to automate many of the most tedious migration steps, such as renaming utility classes.

npx skeleton@latest migrate skeleton-5

It is highly recommended that you read through the entire migration guide to verify all changes are to your preference. And of course ensure you (or your LLM) account for the remaining items not handled by the CLI migration, noted below.

Update NPM Packages

Use your package manager of choice to update the Skeleton core and component packages.

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

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

Themes

Preset Themes

Preset themes will automatically update with all changes. No action is required on your part. You can optionally choose to use the new dracula or rosepine themes introduced as part of the v5 update.

Custom Themes

We recommend importing custom themes into the Theme Generator to automatically convert to the new format. This will also allow you to configure all new or updated settings, while fine tuning the overall design.

TIP: custom fonts are stripped during import. You can, however, implement these via the Typography controls.

Design Tokens

Please refer to the Core API documentation for a complete token reference. Refer to the Cerberus theme for a complete theme reference.

Renamed

The following token keys have changed, while the respective value remains the same.

Base Typography

Heading Typography

Anchor Typography

Anchor Decoration

Root Background

Added

The following tokens expand the capabilities of your themes. Safe default values have been provided.

Typography

Anchor Decorations

Edges

Corner Shapes

Colors

Removed

The following tokens are no longer supported and have been removed.

Utility Classes

Several utility classes have been replaced or removed. Relevant replacements are noted below.

The Input Group feature has now been replaced with Field Group. This is functionally similar, but much more intuitive to implement and use. This also encourages the use of a semantic HTML <label> element.

<!-- v4 -->
<div class="input-group grid-cols-[auto_1fr_auto]">
	<div class="ig-cell preset-tonal">https://</div>
	<input class="ig-input" type="text" />
</div>

<!-- v5 -->
<div class="field-group grid-cols-[auto_1fr_auto]">
	<label class="label label-text preset-tonal" for="url">https://</label>
	<input class="input" type="text" id="url" />
</div>

Brand Color

A new --color-brand-* token provides a dedicated accent color for your design system. It is treated as the default for several Skeleton features. Refer to the new Core API and updated Colors documentation for details.

• New presets have been added, including: preset-filled-brand, preset-tonal-brand, preset-outlined-brand.
• Brand color is now the default for: checkboxes, radios, circular progress, steps, switches, tabs, and accordions.
• Most Skeleton preset themes default to primary-500, which should result in little to no visual changes out of the box.
• The nouveau theme is the only exception; it offers a different brand color between light and dark mode.

This can be customized for any preset Skeleton theme using this pattern in your global stylesheet.

[data-theme='cerberus'] {
	--color-brand-light: var(--color-secondary-500);
	--color-brand-contrast-light: var(--color-secondary-contrast-500);
	--color-brand-dark: var(--color-secondary-500);
	--color-brand-contrast-dark: var(--color-secondary-contrast-500);
}

Element Sizing

A new universal scaling system has been introduced for keeping element sizes uniform, using the new --spacing-elem-{size} token. Use this with w-*, h-*, size-*, m-*, p-* and more, paired with xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl|7xl|8xl|9xl. Refer to Element Sizes for details.

<!-- SVG icon sized to match the "lg" element scale -->
<svg class="size-elem-lg">...</svg>

<!-- Width/height set independently -->
<div class="w-elem-base h-elem-base">...</div>

<!-- Padding/margin using the same scale -->
<div class="p-elem-sm m-elem-xl">...</div>

Icons

Refer to Icon Sizes for more explicit examples and details.

<!-- v4 -->
<ArrowUpRightIcon size="{16}" />

<!-- v5 -->
<ArrowUpRightIcon class="size-elem-lg" />

When wrapped in a button, badge, chip, or disclosure the icon size is now handled automatically. If you have manually specified a size in the past, consider removing this to allow the inherited sizing to take effect.

<!-- ❌ Not Recommended -->
<button type="button" class="btn preset-filled">
	<span>Button</span>
	<ArrowUpRightIcon class="size-elem-lg" />
</button>

<!-- ✅ Recommended -->
<button type="button" class="btn preset-filled">
	<span>Button</span>
	<ArrowUpRightIcon />
</button>

Buttons

Button sizes have been greatly expanded when using the btn-{size} utility. Refer to Button Sizes for details.

Form Fields

Form fields honor the same scale via new field-{size} utility. Refer to Field Sizes for details.

Additional Features

The following are optional and newly introduced features now available as part of the v5 update.

Design System

Tailwind Utilities

Tailwind Components

Framework Components

Migration Complete

If you’ve completed all steps above, then your app is now fully migrated. Run your local dev server to confirm.

npm run dev

TIP: don’t forget to merge all changes into your primary branch!

Support and Feedback

Need help or support? Contact the Skeleton team using either Discord or GitHub. We’re here to help!