From 39d83693024954be74c6e964cb7c5df1a99165c1 Mon Sep 17 00:00:00 2001
From: MohammadHossein Jahanbakhsh <mhos7ein@gmail.com>
Date: Mon, 17 Aug 2026 02:03:22 +0330
Subject: [PATCH 1/2] Document all @import options on the functions and
 directives page

Centralize the options that can be passed to @import (important, prefix, source, theme, reference, and layer) so they are discoverable from the @import directive reference instead of only scattered across other guides.
---
 src/docs/functions-and-directives.mdx | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/docs/functions-and-directives.mdx b/src/docs/functions-and-directives.mdx
index de68c6662..1479a7497 100644
--- a/src/docs/functions-and-directives.mdx
+++ b/src/docs/functions-and-directives.mdx
@@ -18,6 +18,33 @@ Use the `@import` directive to inline import CSS files, including Tailwind itsel
 @import "tailwindcss";
 ```
 
+### `@import` options
+
+When importing Tailwind (or its individual stylesheets), you can pass options after the path:
+
+```css
+/* [!code filename:CSS] */
+@import "tailwindcss" important;
+@import "tailwindcss" prefix(tw);
+@import "tailwindcss" source("../src");
+@import "tailwindcss" theme(reference);
+@import "tailwindcss" reference;
+@import "tailwindcss/utilities.css" layer(utilities);
+```
+
+- Use `important` to mark all utilities as `!important`, or `prefix(…)` to namespace generated utilities and theme CSS variables — see [styling with utility classes](/docs/styling-with-utility-classes#using-the-important-flag).
+- Use `source(…)` to set the base path for automatic source detection, or `source(none)` to disable it — see [detecting classes in source files](/docs/detecting-classes-in-source-files#setting-your-base-path).
+- Use `theme(…)` to control how theme variables are emitted, for example `theme(reference)`, `theme(static)`, or `theme(inline)`.
+- Use `reference` to import styles for reference only without emitting CSS (same idea as [`@reference`](#reference-directive)).
+- Use `layer(…)` to place the imported styles in a [cascade layer](https://developer.mozilla.org/en-US/docs/Web/CSS/@import#layer_name), which is especially useful when [importing Tailwind’s stylesheets individually](/docs/preflight#disabling-preflight).
+
+These options can also be combined on a single import when needed:
+
+```css
+/* [!code filename:CSS] */
+@import "tailwindcss" source(none) prefix(tw);
+```
+
 <h3 id="theme-directive">
   <a href="#theme-directive">@theme</a>
 </h3>

From 2a70309d9800b55b48fb48aec220972210c74cb4 Mon Sep 17 00:00:00 2001
From: MohammadHossein Jahanbakhsh <mhos7ein@gmail.com>
Date: Mon, 17 Aug 2026 12:40:31 +0330
Subject: [PATCH 2/2] docs: use theme.css entrypoint for theme(reference)
 import example

The full tailwindcss entrypoint includes Preflight and utilities, which
breaks theme(reference). Point the example at tailwindcss/theme.css instead.
---
 src/docs/functions-and-directives.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/docs/functions-and-directives.mdx b/src/docs/functions-and-directives.mdx
index 1479a7497..70b7746a8 100644
--- a/src/docs/functions-and-directives.mdx
+++ b/src/docs/functions-and-directives.mdx
@@ -27,7 +27,7 @@ When importing Tailwind (or its individual stylesheets), you can pass options af
 @import "tailwindcss" important;
 @import "tailwindcss" prefix(tw);
 @import "tailwindcss" source("../src");
-@import "tailwindcss" theme(reference);
+@import "tailwindcss/theme.css" theme(reference);
 @import "tailwindcss" reference;
 @import "tailwindcss/utilities.css" layer(utilities);
 ```