Clarify some details around @reference (#2376)

Closes #2374 

I opted to also add a section on subpath imports to note that they're
usable with `@import`, `@reference`, `@plugin`, and `@config`.

---

Closes #2377

I've added a note to the upgrade guide as well about arbitrary values in
grid-cols, grid-rows, and object-position — while this behavior was
related to v2 compat it was still supported in v3 so it feels fine to
call it out as having changed.

Author: thecrypticace

src/docs/functions-and-directives.mdx

@@ -160,7 +160,7 @@ To do this without duplicating any CSS in your output, use the `@reference` dire
 </style>
 ```
 
-If you’re just using the default theme with no customizations, you can import `tailwindcss` directly:
+If you’re just using the default theme with no customizations (e.g. by using things like `@theme`, `@custom-variant`, `@plugin`, etc…), you can import `tailwindcss` directly:
 
 ```html
 <!-- [!code filename:Vue] -->
@@ -178,6 +178,37 @@ If you’re just using the default theme with no customizations, you can import
 </style>
 ```
 
+### Subpath Imports
+
+When using the CLI, Vite, or PostCSS the directives `@import`, `@reference`, `@plugin`, and `@config` all support [subpath imports](https://nodejs.org/api/packages.html#subpath-imports) which work similarly to bundler and TypeScript path aliases:
+
+```json
+// [!code filename:package.json]
+{
+  // ...
+  "imports": {
+    /* [!code highlight:2] */
+    "#app.css": "./src/css/app.css"
+  }
+}
+```
+
+```html
+<!-- [!code filename:Vue] -->
+<template>
+  <h1>Hello world!</h1>
+</template>
+
+<style>
+  /* [!code highlight:2] */
+  @reference "#app.css";
+
+  h1 {
+    @apply text-2xl font-bold text-red-500;
+  }
+</style>
+```
+
 ## Functions
 
 Tailwind provides the following build-time functions to make working with colors and the spacing scale easier.

src/docs/upgrade-guide.mdx

@@ -690,6 +690,20 @@ To update your project for this change, replace usage of the old variable shorth
 <div class="bg-(--brand-color)"></div>
 ```
 
+### Arbitrary values in grid and object-position utilities
+
+Commas were previously replaced with spaces in the `grid-cols-*`, `grid-rows-*`, and `object-*` utilities inside arbitrary values. This special behavior existed in Tailwind CSS v3 for compatibility with v2. This compatibility no longer exists in v4.0 and underscores must be used to represent spaces.
+
+To update your project for this change, replace usage of commas that were intended to be spaces with underscores:
+
+```html
+<!-- [!code filename:HTML] -->
+<!-- [!code --:2] -->
+<div class="grid-cols-[max-content,auto]"></div>
+<!-- [!code ++:2] -->
+<div class="grid-cols-[max-content_auto]"></div>
+```
+
 ### Hover styles on mobile
 
 In v4 we've updated the `hover` variant to only apply when the primary input device supports hover: