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 below 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

Themes

Preset Themes

Preset themes will automatically update with all changes. No action is required on your part.

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 any new or updated settings, while fine tuning the overall design.

TIP: custom fonts will not be imported. 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. We’ll now cover all notable changes below.

Renamed

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

Base Typography

Heading Typography

Anchor Typography

Anchor Decoration

Root Background

Added

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

Typography

Anchor Decorations

Edges

Corner Shapes

Colors

Removed

Utility Classes

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

Migrate Field Groups

Input Groups have now been replaced with the intuitive Field Groups feature.

<!-- 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 default accent color for a number of 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 sets a different brand color between light and dark mode.

This can be customized for any preset Skeleton theme (eg: Cerberus) 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. Note that icons used within Tailwind Components such as buttons, badges, chips, and field groups are sized automatically. Adding an explicit sizing utility is redundant.

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 features are new additions. These are not breaking changes and are included for completeness.

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: remember 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!