Improve upgrade guide (#2096)

Closes #2015

- Mention that `corePlugins`, `safelist`, and `seperator` no longer
exist in v4
- Mention `@layer components` in the `@layer utilities` section

Author: philipp-spiess

src/docs/functions-and-directives.mdx

@@ -252,7 +252,7 @@ Use the `@config` directive to load a legacy JavaScript-based configuration file
 @config "../../tailwind.config.js";
 ```
 
-The `corePlugins`, `safelist` and `separator` options from the JavaScript-based config are not supported in v4.0.
+The `corePlugins`, `safelist`, and `separator` options from the JavaScript-based config are not supported in v4.0.
 
 <h3 id="plugin-directive">@plugin</h3>
 

src/docs/upgrade-guide.mdx

@@ -595,7 +595,7 @@ The generated CSS variables _will_ include a prefix to avoid conflicts with any
 
 ### Adding custom utilities
 
-In v3, any custom classes you defined within `@layer utilities` would get picked up by Tailwind as a true utility class and would automatically work with variants like `hover`, `focus`, or `lg`.
+In v3, any custom classes you defined within `@layer utilities` or `@layer components` would get picked up by Tailwind as a true utility class and would automatically work with variants like `hover`, `focus`, or `lg` with the difference being that `@layer components` would always come first in the generated stylesheet.
 
 In v4 we are using native cascade layers and no longer hijacking the `@layer` at-rule, so we've introduced the `@utility` API as a replacement:
 
@@ -613,6 +613,26 @@ In v4 we are using native cascade layers and no longer hijacking the `@layer` at
 }
 ```
 
+Custom utilities are now also sorted based on the amount of properties they define. This means that component utilities like this `.btn` can be overwritten by other Tailwind utilities without additional configuration:
+
+```css
+/* [!code filename:CSS] */
+/* [!code --:8] */
+@layer components {
+  .btn {
+    border-radius: 0.5rem;
+    padding: 0.5rem 1rem;
+    background-color: ButtonFace;
+  }
+}
+/* [!code ++:6] */
+@utility btn {
+  border-radius: 0.5rem;
+  padding: 0.5rem 1rem;
+  background-color: ButtonFace;
+}
+```
+
 Learn more about registering custom utilities in the [adding custom utilities documentation](/docs/adding-custom-styles#adding-custom-utilities).
 
 ### Variant stacking order
@@ -725,6 +745,8 @@ If you still need to use a JavaScript config file, you can load it explicitly us
 @config "../../tailwind.config.js";
 ```
 
+The `corePlugins`, `safelist`, and `separator` options from the JavaScript-based config are not supported in v4.0.
+
 ### Theme values in JavaScript
 
 In v3 we exported a `resolveConfig` function that you could use to turn your JavaScript-based config into a flat object that you could use in your other JavaScript.