Improve Migration steps for TW apply (#3589)

endigo9740 · web-flow · commit 98432911fadf · 2025-07-04T10:00:37.000-05:00
diff --git a/sites/skeleton.dev/src/content/docs/get-started/migrate-from-v2.mdx b/sites/skeleton.dev/src/content/docs/get-started/migrate-from-v2.mdx
@@ -61,14 +61,16 @@ Migrate to the latest release of SvelteKit v2.
 
 ### Tailwind v4
 
-Before migration to tailwind V4 using their upgrade guide some manual steps are required:
+Before migration to tailwind v4 using their upgrade guide some manual steps are 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).
 
 Migrate to the latest release of Tailwind v4.
 
+> TIP: Having trouble running Tailwind's automated migration script due to `@apply`? Remove the classes temporarily, then follow [these steps](/docs/get-started/migrate-from-v2#replacing-apply) to adapt to native CSS custom properties and Tailwind's new utilities.
+
 <figure class="linker bg-noise">
 	<a class="btn preset-filled" href="https://tailwindcss.com/docs/upgrade-guide" target="_blank">
 		Tailwind v4 Migration &rarr;
@@ -214,6 +216,35 @@ Taliwind v4 represents a major update for Tailwind. We've detailed the most nota
 - The Skeleton `data-theme` attribute has moved from `<body>` to `<html>`
 - Themes colors are now stored in the [oklch format](https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl), but optionally support any format.
 
+### Replacing @apply
+
+We strongly encourage you take this opportunity to move away from any usage of `@apply`. Tailwind has long since advocated against heavy use of this, and Tailwind v4 introduces new directives and functions that make this much easier to avoid. Here's a trivial example:
+
+```css
+/* Before */
+
+.foo {
+	@apply bg-surface-50-950 text-surface-950 dark:text-surface-50 p-4;
+}
+```
+
+```css
+/* After */
+
+.foo {
+	background-color: var(--color-surface-50-950);
+	color: var(--color-surface-950);
+	padding: --spacing(4);
+	@variant dark {
+		color: var(--color-surface-50);
+	}
+}
+```
+
+- Usage of `@apply` may be found in your global stylesheet or component `<style>` blocks.
+- Refer to the Skeleton [Core API](/docs/get-started/core-api) documentation for a full list of Skeleton's CSS custom properties.
+- Refer to the Tailwind's [functions and directives](https://tailwindcss.com/docs/functions-and-directives) for information on how to utilize these new features.
+
 ### Replace Unsupported Features
 
 Skeleton v3 represents a point of reflection on what features should remain as part of the core experience. As such, we've identified a number of features that fall outside of this scope. Don't fret though, we've gone out of our way to detail each feature and provide the best alternative available.
