diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..4867674
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,3 @@
+node_modules/
+.next/
+.source/
diff --git a/docs/content/docs/advanced/architecture.mdx b/docs/content/docs/advanced/architecture.mdx
new file mode 100644
index 0000000..65d1da8
--- /dev/null
+++ b/docs/content/docs/advanced/architecture.mdx
@@ -0,0 +1,145 @@
+---
+title: Architecture
+description: How TailwindPHP mirrors TailwindCSS file-for-file, the compilation pipeline, the lightningcss equivalent, and where the PHP port deviates.
+---
+
+# Architecture
+
+TailwindPHP is a 1:1 port. The codebase mirrors TailwindCSS's own structure — same file names, same organization — and isolates the parts that *cannot* be a direct port (PHP has no Rust, no V8) under `src/_tailwindphp/`. This page walks the compilation pipeline, the source layout, the `lightningcss` reimplementation, and the convention used to document deviations.
+
+## The pipeline
+
+Generating CSS is a sequence of stages. There is no separate build step — each call to `tw::generate()` runs the full pipeline.
+
+```
+CSS input (@import "tailwindcss"; @theme { … })
+ │
+ ▼
+┌──────────────┐
+│ Parse CSS │ css-parser.php → ast.php nodes
+└──────┬───────┘
+ ▼ design system (theme, utilities, variants)
+┌──────────────┐
+│ Scan content │ candidate.php — extract class names from HTML
+└──────┬───────┘
+ ▼ candidates
+┌──────────────┐
+│ Compile │ compile.php — candidate → AST, via design-system.php
+└──────┬───────┘
+ ▼ AST
+┌──────────────┐
+│ Optimize │ _tailwindphp/LightningCss.php — nesting, @media, calc()
+└──────┬───────┘
+ ▼ ast.php toCss()
+┌──────────────┐
+│ Minify │ _tailwindphp/CssMinifier.php (optional)
+└──────┬───────┘
+ ▼
+CSS output
+```
+
+**Parse.** `css-parser.php` reads the CSS input — `@import`, `@theme`, `@utility`, `@layer`, raw rules — into an abstract syntax tree of `ast.php` nodes (style rules, at-rules, declarations). `@import` directives for virtual modules (`tailwindcss`, `tailwindcss/preflight`, …) and file paths are resolved and substituted at this stage.
+
+**Build the design system.** `theme.php` resolves theme values (colors, spacing, breakpoints) from the parsed `@theme` blocks plus the defaults. `design-system.php` is the central registry that ties the theme to the utility and variant lookups defined in `utilities.php` and `variants.php`.
+
+**Scan content.** `candidate.php` extracts class-name candidates from the supplied content (HTML, templates) and parses each into its parts — base utility, variants, modifiers, arbitrary values, important flag.
+
+**Compile.** `compile.php` turns each candidate into AST nodes by looking it up in the design system, applying its variants and modifiers. Candidates that don't resolve to a real utility are discarded.
+
+**Serialize and optimize.** `ast.php`'s `toCss()` walks the tree (helpers in `walk.php`) and emits the CSS string. The `lightningcss`-equivalent transforms in `_tailwindphp/LightningCss.php` are applied so the output matches what TailwindCSS produces after its Rust post-processing pass.
+
+**Minify.** When `minify` is enabled, `_tailwindphp/CssMinifier.php` runs as a final pass. See [Caching & minification](/docs/advanced/caching).
+
+## Source layout
+
+`src/` mirrors TailwindCSS. The one structural change: TailwindCSS's `utilities.ts` is 6,000+ lines, so it is split into `src/utilities/` with one file per category for maintainability.
+
+```
+src/
+├── _tailwindphp/ # PHP-specific — NOT part of the TailwindCSS port
+│ ├── LightningCss.php # CSS transforms (lightningcss Rust library equivalent)
+│ ├── CssMinifier.php # CSS minification
+│ └── lib/ # Companion library ports (TailwindPHP\Lib\*)
+│ ├── clsx/ # clsx port
+│ ├── tailwind-merge/ # tailwind-merge port
+│ └── cva/ # CVA port
+│
+├── plugin/ # Plugin system
+│ └── plugins/
+│ ├── typography-plugin.php # @tailwindcss/typography port
+│ └── forms-plugin.php # @tailwindcss/forms port
+│
+├── utilities/ # Split from TailwindCSS utilities.ts (one file per category)
+│ ├── accessibility.php # sr-only, forced-colors
+│ ├── backgrounds.php # bg-*, gradient-*, from-*, via-*, to-*
+│ ├── borders.php # border-*, rounded-*, divide-*, outline-*
+│ ├── effects.php # shadow-*, opacity-*, mix-blend-*
+│ ├── filters.php # blur-*, brightness-*, contrast-*, …
+│ ├── flexbox.php # flex-*, grid-*, gap-*, justify-*, align-*
+│ ├── interactivity.php # cursor-*, scroll-*, touch-*, select-*
+│ ├── layout.php # display, position, z-*, overflow-*, …
+│ ├── masks.php # mask-linear-*, mask-radial-*, mask-conic-*
+│ ├── sizing.php # w-*, h-*, min-*, max-*, size-*
+│ ├── spacing.php # m-*, p-*, space-*
+│ ├── svg.php # fill-*, stroke-*
+│ ├── tables.php # border-collapse, table-layout
+│ ├── transforms.php # translate-*, rotate-*, scale-*, skew-*
+│ ├── transitions.php # transition-*, duration-*, ease-*, delay-*
+│ └── typography.php # font-*, text-*, leading-*, tracking-*
+│
+├── utils/ # Helper functions (ported from utils/)
+│
+├── index.php # Main entry — compile(), cn(), variants(), merge(), join()
+├── ast.php # AST nodes and toCss()
+├── candidate.php # Candidate parsing (class name → parts)
+├── compile.php # Candidate to CSS compilation
+├── css-functions.php # theme(), --theme(), --spacing(), --alpha()
+├── css-parser.php # CSS parsing
+├── design-system.php # Central registry for utilities/variants
+├── plugin.php # Plugin system (PluginInterface, PluginAPI, PluginManager)
+├── theme.php # Theme value resolution
+├── utilities.php # Utility registration and lookup
+├── value-parser.php # CSS value parsing
+├── variants.php # Variant handling (hover, focus, responsive, …)
+└── walk.php # AST traversal
+```
+
+## The lightningcss equivalent
+
+TailwindCSS delegates its CSS post-processing — nesting, media-query handling, value simplification — to [lightningcss](https://lightningcss.dev/), a parser/transformer/minifier written in Rust. PHP can't load a Rust library, so `src/_tailwindphp/LightningCss.php` reimplements the transforms TailwindPHP actually relies on, producing byte-identical output for the cases the test suite covers.
+
+Confirmed transforms include:
+
+| Transform | What it does |
+|-----------|--------------|
+| Nesting flattening | Resolves `&` selectors and flattens nested rules to top-level selectors (`transformNesting`) |
+| `@media` hoisting | Moves nested media queries up to the top level (`transformNesting`, `mergeAtRules`) |
+| `calc()` simplification | Simplifies `calc()` expressions (`simplifyCalcExpressions`) |
+| Leading-zero removal | `0.5` → `.5` (`normalizeLeadingZeros`) |
+| Transform-function spacing | Normalizes spacing inside transform functions (`normalizeTransformFunctions`) |
+| Grid value normalization | Adds spaces around `/` in span values, bare integers → px for `grid-template-*` (`normalizeGridValues`) |
+| Color normalization | Normalizes color syntax and evaluates `color-mix()` to `oklab()` (`normalizeColors`, `evaluateColorMix`) |
+| URL quoting | `url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`) |
+| Vendor prefixes | Autoprefixer-equivalent prefixing (`addVendorPrefixes`) |
+
+This file is deliberately quarantined under `_tailwindphp/` and marked `@port-deviation:replacement` — it stands in for an external dependency rather than porting TailwindCSS source.
+
+## Port deviation markers
+
+Every implementation file carries `@port-deviation:*` markers in its docblock that state where and why the PHP implementation departs from the TypeScript original. The goal is that a reader comparing PHP to TailwindCSS source never has to wonder whether a difference is intentional.
+
+| Marker | Meaning |
+|--------|---------|
+| `@port-deviation:none` | Direct 1:1 port with no significant deviations |
+| `@port-deviation:async` | PHP uses synchronous code instead of async/await |
+| `@port-deviation:storage` | Different data structures (PHP array vs JS Map/Set) |
+| `@port-deviation:types` | PHPDoc annotations instead of TypeScript types |
+| `@port-deviation:sourcemaps` | Source-map tracking omitted |
+| `@port-deviation:enum` | PHP constants instead of TypeScript enums |
+| `@port-deviation:errors` | Different error-handling approach |
+| `@port-deviation:replacement` | PHP implementation replacing an external library (e.g. lightningcss) |
+| `@port-deviation:helper` | PHP-specific helper not in the original |
+| `@port-deviation:performance` | PHP-specific optimization that preserves identical output |
+| `@port-deviation:omitted` | Entire module/feature not ported (outside scope) |
+
+For the `@port-deviation:performance` markers and how parity is enforced, see [Performance & testing](/docs/advanced/performance).
diff --git a/docs/content/docs/advanced/caching.mdx b/docs/content/docs/advanced/caching.mdx
new file mode 100644
index 0000000..5a7b95a
--- /dev/null
+++ b/docs/content/docs/advanced/caching.mdx
@@ -0,0 +1,107 @@
+---
+title: Caching & Minification
+description: The file-based cache (cache, cacheTtl, clearCache) and the CSS minifier that shrinks output for production.
+---
+
+# Caching & Minification
+
+Two production concerns sit at the edge of the pipeline: avoiding recompilation of identical input, and shrinking the generated CSS. Both are PHP-specific helpers under `src/_tailwindphp/` and the public API around them.
+
+## Caching
+
+CSS generation runs the whole pipeline on every call. For content that doesn't change between requests, the file-based cache writes the result to disk and serves it on subsequent calls.
+
+Pass `cache` to `tw::generate()` — `true` for the default directory, or a path string for a custom one:
+
+```php
+use TailwindPHP\tw;
+
+// Cache to the default directory: sys_get_temp_dir() . '/tailwindphp'
+$css = tw::generate([
+ 'content' => '
Hello
',
+ 'cache' => true,
+]);
+
+// Cache to a custom directory
+$css = tw::generate([
+ 'content' => '
Hello
',
+ 'cache' => '/path/to/cache',
+]);
+
+// With a time-to-live (seconds)
+$css = tw::generate([
+ 'content' => '
Hello
',
+ 'cache' => true,
+ 'cacheTtl' => 3600, // expire after 1 hour
+]);
+```
+
+The cache directory is created automatically if it doesn't exist.
+
+### Cache key
+
+The key is derived from the **content**, the **CSS configuration**, and the **minify** flag — hashed into the filename `tailwind_.css`. Any change to the markup, the CSS input, or whether minification is on produces a different key, and therefore a different file. There is no risk of stale output for a given input: different inputs never collide on the same cache file.
+
+### Time-to-live
+
+`cacheTtl` is a lifetime in seconds. On a cache hit, the file's modification time is compared against the current time; if the file is older than `cacheTtl`, it is treated as a miss and recompiled. With no `cacheTtl`, entries never expire — clear them explicitly.
+
+### Clearing the cache
+
+`tw::clearCache()` (or the `clearCache()` function) removes the `tailwind_*.css` files from a cache directory and returns the number of files deleted.
+
+```php
+use TailwindPHP\tw;
+use function TailwindPHP\clearCache;
+
+$deleted = tw::clearCache(); // default directory
+$deleted = tw::clearCache('/path/to/cache'); // custom directory
+clearCache('/path/to/cache'); // function form
+```
+
+## Minification
+
+The minifier (`src/_tailwindphp/CssMinifier.php`) shrinks the output for production. Enable it inline with `minify`, or run it as a separate pass with `tw::minify()`:
+
+```php
+use TailwindPHP\tw;
+
+// Minify during generation
+$css = tw::generate([
+ 'content' => '
Hello
',
+ 'minify' => true,
+]);
+
+// Or minify an existing string
+$css = tw::generate('
Hello
');
+$minified = tw::minify($css);
+```
+
+### What it does
+
+The minifier applies a fixed set of size reductions:
+
+| Step | Effect |
+|------|--------|
+| Remove comments | Strips `/* … */` blocks |
+| Collapse whitespace | Collapses runs of whitespace and removes it around `{ } ; : ,` and selector combinators |
+| Shorten hex colors | `#ffffff` → `#fff`, `#aabbcc` → `#abc` |
+| Remove zero units | `0px` → `0` (preserves `0s`/`0ms` time values) |
+| Shorten font-weight | `font-weight:normal` → `400`, `font-weight:bold` → `700` |
+| Remove empty rules | Drops selectors with empty declaration blocks |
+
+By design it does **not** merge duplicate selectors or combine shorthand properties — both make debugging harder and can affect the cascade.
+
+### CLI: `--minify` vs `--optimize`
+
+The [CLI](/docs/cli) exposes the same minifier through two flags:
+
+```bash
+# Optimize and minify (smallest output)
+tailwindphp -i ./src/app.css -o ./dist/styles.css --minify # or -m
+
+# Optimize only — apply transforms without minifying
+tailwindphp -i ./src/app.css -o ./dist/styles.css --optimize
+```
+
+For the rest of the public API — `tw::generate()`, `tw::compile()`, inspection methods, and input formats — see the [API reference](/docs/api).
diff --git a/docs/content/docs/advanced/index.mdx b/docs/content/docs/advanced/index.mdx
new file mode 100644
index 0000000..72f2a3b
--- /dev/null
+++ b/docs/content/docs/advanced/index.mdx
@@ -0,0 +1,18 @@
+---
+title: Advanced
+description: The internals of TailwindPHP — how the port mirrors TailwindCSS file-for-file, the compilation pipeline, caching, minification, and performance.
+---
+
+# Advanced
+
+TailwindPHP is a 1:1 port of TailwindCSS 4.x to pure PHP. The guiding principle is fidelity: the codebase mirrors the original TypeScript project file-for-file — same file names, same organization — so that any behavior in TailwindCSS has an obvious home in PHP, and so that upstream changes can be tracked without guesswork.
+
+Anything that is *not* part of the TailwindCSS port lives in one clearly marked place: `src/_tailwindphp/`. That directory holds the PHP-specific helpers — a reimplementation of the Rust `lightningcss` transforms (`LightningCss.php`), the CSS minifier (`CssMinifier.php`), and the companion library ports (`lib/`: clsx, tailwind-merge, CVA) under the `TailwindPHP\Lib\*` namespace. Everything else under `src/` corresponds to a file in TailwindCSS.
+
+Correctness is verified against Tailwind's own test suite. Test cases are extracted directly from TailwindCSS's `.test.ts` files and run against PHP output, so any drift from the original behavior fails immediately. The result is 4,074 passing tests covering utilities, variants, directives, plugins, and the companion libraries.
+
+## Pages
+
+- **[Architecture](/docs/advanced/architecture)** — the compilation pipeline (parse → scan → compile → optimize → minify), the source layout, the `lightningcss` equivalent, and the `@port-deviation` marker convention.
+- **[Caching & minification](/docs/advanced/caching)** — the file-based cache (`cache`, `cacheTtl`, `clearCache()`) and what the CSS minifier does.
+- **[Performance & testing](/docs/advanced/performance)** — PHP-specific optimizations, how parity with TailwindCSS is verified, and the code-quality gate.
diff --git a/docs/content/docs/advanced/meta.json b/docs/content/docs/advanced/meta.json
new file mode 100644
index 0000000..bc30c7a
--- /dev/null
+++ b/docs/content/docs/advanced/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Advanced",
+ "pages": ["index", "architecture", "caching", "performance"]
+}
diff --git a/docs/content/docs/advanced/performance.mdx b/docs/content/docs/advanced/performance.mdx
new file mode 100644
index 0000000..ddf0f7e
--- /dev/null
+++ b/docs/content/docs/advanced/performance.mdx
@@ -0,0 +1,77 @@
+---
+title: Performance & Testing
+description: PHP-specific optimizations that preserve identical output, and the extraction-based test loop that keeps the port in lockstep with TailwindCSS.
+---
+
+# Performance & Testing
+
+TailwindPHP optimizes for correctness first. Where a PHP-specific change speeds things up without altering output, it is applied and marked `@port-deviation:performance`. Parity with TailwindCSS is not assumed — it is continuously verified against Tailwind's own test suite.
+
+## Performance
+
+This is build-time CSS generation. The PHP port prioritizes matching TailwindCSS byte-for-byte over raw throughput, and the TypeScript original stays faster regardless — V8's JIT compiles the hot paths to native code in a way PHP cannot match. That is expected and fine for the intended use case.
+
+A few hot paths carry hand-tuned optimizations that **preserve identical output**:
+
+- **`ast.php` `toCss()`** — accumulates fragments in an array and `implode`s once instead of repeated string concatenation, and uses pre-computed indent strings.
+- **`css-parser.php`** — compares characters directly instead of going through `ord()`, and tracks buffer lengths instead of recomputing `strlen()`.
+
+Both are documented with `@port-deviation:performance` and gated on the test suite — they cannot change the generated CSS.
+
+### Benchmarks
+
+The `benchmarks/` directory contains a comparison harness. Run it with:
+
+```bash
+composer bench # PHP vs TypeScript
+composer bench:save # write benchmarks/results.json
+```
+
+Sample results on PHP 8.4.5 / Node.js v22.17.0 (Apple M1):
+
+| Benchmark | PHP | TypeScript |
+|-----------|-----|------------|
+| `css-parser` on preflight.css | ~816 ops/s | ~15.45K ops/s (≈20× faster) |
+| `toCss` | ~65.85K ops/s | ~2.59M ops/s (≈39× faster) |
+
+TypeScript is faster for these low-level operations, as expected. For full-page CSS generation — the actual use case — PHP performance is adequate (roughly 14 ms per page in the sample run). For repeated identical input, the [file cache](/docs/advanced/caching) removes the cost entirely.
+
+## Testing & parity
+
+Tests exist to guarantee the PHP port produces the same output as TailwindCSS. Two approaches work together.
+
+**1. Extraction-based tests.** Scripts in `test-coverage/` parse TailwindCSS's own `.test.ts` files and extract the test cases to JSON. PHPUnit then feeds those cases through TailwindPHP and compares the output against the expected CSS. Because the expectations come straight from upstream, any divergence in PHP behavior surfaces as a failure. These cover the complex surfaces: utilities, variants, integration, CSS functions, and the browser-level `ui.spec` tests.
+
+**2. Hand-ported unit tests.** Simpler TypeScript test files (AST, CSS parsing, escaping, candidate parsing, value parsing, …) are ported directly to PHP and live beside their source as `*.test.php`, mirroring the structure and assertions of the originals.
+
+The loop is **extract → run → verify**: re-extract from the current TailwindCSS reference, run the suite, and any drift fails. This keeps the port in lockstep with upstream and means a TailwindCSS update can be validated mechanically rather than by inspection. Drift fails CI.
+
+```bash
+composer extract # re-extract test cases from the TailwindCSS reference
+composer test # run the full suite
+```
+
+There are **4,074 passing tests**. The largest suites:
+
+| Suite | Tests | Source |
+|-------|-------|--------|
+| Core (utilities, variants, integration) | 1,322 | extracted from `.test.ts` |
+| API coverage (utilities, modifiers, variants, directives, plugins) | 1,774 | exhaustive API tests |
+| PHP-specific unit tests (theme, design-system, utils) | 300 | various `.test.ts` ports |
+| Public API (`tw::generate`, `tw::compile`, inspection) | 140 | API tests |
+| Companion libraries (clsx, tailwind-merge, CVA) | 129 | reference suites |
+
+## Code quality
+
+Formatting and static analysis run through Composer scripts:
+
+```bash
+composer lint # Pint --test (check formatting)
+composer format # Pint (fix formatting)
+composer analyse # PHPStan (static analysis, level 3)
+composer quality # lint + analyse
+```
+
+PHPStan runs at level 3 — higher levels conflict with the function-based architecture the port uses. All source files are analyzed; test files are excluded.
+
+For the structure these tests verify and where deviations are recorded, see [Architecture](/docs/advanced/architecture).
diff --git a/docs/content/docs/api.mdx b/docs/content/docs/api.mdx
new file mode 100644
index 0000000..4362ba4
--- /dev/null
+++ b/docs/content/docs/api.mdx
@@ -0,0 +1,355 @@
+---
+title: API
+description: The full TailwindPHP\tw static API — generate, compile, properties, computed values, theme inspectors, caching — plus the reusable TailwindCompiler instance.
+---
+
+# API
+
+The entire static surface lives on one class: `TailwindPHP\tw` (an alias of the internal `Tailwind` class). Every method is callable statically, and the inspection methods (`properties`, `computedProperties`, `value`, `computedValue`) all accept the [input formats](#input-formats) described at the bottom of this page.
+
+For repeated work against the same CSS configuration, call [`tw::compile()`](#twcompile) once and reuse the returned [`TailwindCompiler`](#tailwindcompiler-instance-methods).
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate('
');
+```
+
+## tw::generate()
+
+```php
+public static function generate(string|array $input, string $css = '@import "tailwindcss";'): string
+```
+
+Parses content, extracts class candidates, and returns the generated CSS. The default `$css` is `@import "tailwindcss";`, which pulls in theme, preflight, and utilities. **Returns** `string`.
+
+```php
+use TailwindPHP\tw;
+
+// String input
+$css = tw::generate('
');
+
+// String with custom CSS
+$css = tw::generate('
',
+ 'cache' => '/path/to/cache',
+ 'cacheTtl' => 3600, // expire after 1 hour
+]);
+```
+
+The cache key is derived from the **content**, the **CSS configuration**, and the **minify** option, so different inputs produce different cache files. Clear entries with [`tw::clearCache()`](#twclearcache) or the standalone `TailwindPHP\clearCache()` function.
+
+For the deeper guide, see [Caching & minification](/docs/advanced/caching).
diff --git a/docs/content/docs/class-utilities/index.mdx b/docs/content/docs/class-utilities/index.mdx
new file mode 100644
index 0000000..f441c00
--- /dev/null
+++ b/docs/content/docs/class-utilities/index.mdx
@@ -0,0 +1,110 @@
+---
+title: Class Utilities
+description: cn(), merge(), and join() for building and de-conflicting Tailwind class strings in PHP — PHP ports of clsx and tailwind-merge, no JS toolchain required.
+---
+
+# Class Utilities
+
+Building `class` attributes in templates means joining strings, toggling classes on conditions, and stopping later utilities from clashing with earlier ones (`p-2` and `p-4` should not both survive). In JavaScript that work is split across [clsx](https://github.com/lukeed/clsx) and [tailwind-merge](https://github.com/dcastil/tailwind-merge). TailwindPHP ships PHP ports of both, so you get the same behavior with no Node.js toolchain and no extra Composer packages.
+
+Three functions cover the spectrum: `cn()` constructs and de-conflicts, `merge()` only de-conflicts, and `join()` only concatenates.
+
+## cn()
+
+The recommended utility. It runs clsx-style conditional construction first, then resolves Tailwind conflicts with tailwind-merge — so the last conflicting utility wins.
+
+```php
+use function TailwindPHP\cn;
+
+// Conflicts are resolved — px-4 overrides px-2
+cn('px-2 py-1', 'px-4');
+// => 'py-1 px-4'
+
+// Conditional classes via a key => bool array
+cn('btn', ['btn-primary' => true, 'btn-disabled' => false]);
+// => 'btn btn-primary'
+```
+
+### Accepted arguments
+
+`cn()` accepts any number of arguments. Each is flattened and filtered with clsx semantics:
+
+| Argument | Behavior |
+|----------|----------|
+| `string` | Added as-is. |
+| `int` / `float` | Cast to string and added. |
+| Sequential array | Each element is processed recursively. |
+| `key => bool` array | Each key is added when its value is truthy. |
+| `null`, `false`, `0`, `''` | Ignored. |
+
+```php
+cn('flex', ['items-center' => true], ['p-4', ['gap-2']], null);
+// => 'flex items-center p-4 gap-2'
+```
+
+### Component pattern
+
+`cn()` is what makes a component overridable: merge the component's own classes with whatever the caller passes, and conflicts resolve in the caller's favor.
+
+```php
+use function TailwindPHP\cn;
+
+function Card(array $props = []): string {
+ $class = cn(
+ 'rounded-lg border bg-card text-card-foreground shadow-sm',
+ $props['class'] ?? null
+ );
+ return "
+```
+
+For declarative, multi-axis component styles, pair `cn()` with [variants()](/docs/class-utilities/variants).
+
+## merge()
+
+Conflict resolution only — no conditional construction. Pass class strings; later classes override earlier ones when they target the same property. Use it when your input is already plain strings.
+
+```php
+use function TailwindPHP\merge;
+
+merge('px-2 py-1 bg-red-500', 'px-4 bg-blue-500');
+// => 'py-1 px-4 bg-blue-500'
+
+// Conflict resolution is variant-aware
+merge('hover:bg-red-500', 'hover:bg-blue-500');
+// => 'hover:bg-blue-500'
+```
+
+`cn()` is `merge()` composed on top of clsx, so reach for `merge()` directly only when you do not need the conditional array syntax.
+
+## join()
+
+Simple concatenation with no conflict resolution. Falsy values are dropped, but conflicting utilities are all kept. Use it when you know there are no conflicts and want the cheapest option.
+
+```php
+use function TailwindPHP\join;
+
+join('foo', 'bar', null, 'baz');
+// => 'foo bar baz'
+```
+
+## Which should I use?
+
+| Function | Constructs (conditionals, arrays) | Resolves conflicts | Use when |
+|----------|:---:|:---:|----------|
+| `cn()` | yes | yes | Default choice — building class strings that may conflict. |
+| `merge()` | no | yes | Input is plain strings; you only need de-conflicting. |
+| `join()` | yes | no | You know there are no conflicts and want minimal work. |
+
+## Imports
+
+```php
+use function TailwindPHP\cn;
+use function TailwindPHP\merge;
+use function TailwindPHP\join;
+```
+
+All three live in the main `TailwindPHP` namespace and are bundled with the package. They are PHP ports of clsx (by Luke Edwards) and tailwind-merge (by Dany Castillo).
diff --git a/docs/content/docs/class-utilities/meta.json b/docs/content/docs/class-utilities/meta.json
new file mode 100644
index 0000000..5f770e8
--- /dev/null
+++ b/docs/content/docs/class-utilities/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Class Utilities",
+ "pages": ["index", "variants"]
+}
diff --git a/docs/content/docs/class-utilities/variants.mdx b/docs/content/docs/class-utilities/variants.mdx
new file mode 100644
index 0000000..5053520
--- /dev/null
+++ b/docs/content/docs/class-utilities/variants.mdx
@@ -0,0 +1,165 @@
+---
+title: Variants
+description: variants() and compose() — a PHP port of CVA (Class Variance Authority) for declarative, multi-axis component styles built on base, variants, compoundVariants, and defaults.
+---
+
+# Variants
+
+`variants()` is a PHP port of [CVA (Class Variance Authority)](https://github.com/joe-bell/cva). It turns a declarative config — a base, named variant axes, and defaults — into a callable that maps props to a class string. Use it when a component has style dimensions like size and intent that combine.
+
+```php
+use function TailwindPHP\variants;
+
+$button = variants([
+ 'base' => 'btn font-semibold border rounded',
+ 'variants' => [
+ 'intent' => [
+ 'primary' => 'bg-blue-500 text-white',
+ 'secondary' => 'bg-gray-200 text-gray-800',
+ ],
+ 'size' => [
+ 'sm' => 'text-sm px-2 py-1',
+ 'md' => 'text-base px-4 py-2',
+ ],
+ ],
+ 'defaultVariants' => [
+ 'intent' => 'primary',
+ 'size' => 'md',
+ ],
+]);
+
+$button();
+// => 'btn font-semibold border rounded bg-blue-500 text-white text-base px-4 py-2'
+```
+
+`variants()` returns a `callable`; call it with a props array (or nothing) to get the resolved string.
+
+## Config
+
+| Key | Type | Purpose |
+|-----|------|---------|
+| `base` | `string` | Classes applied to every output. |
+| `variants` | `array` | Named axes, each mapping value names to class strings. |
+| `compoundVariants` | `array` | Class strings applied only when several variant values combine. |
+| `defaultVariants` | `array` | Value per axis used when a prop is omitted. |
+
+All keys are optional. With no `variants`, the result returns `base` plus any custom classes:
+
+```php
+$x = variants(['base' => 'box']);
+$x(); // => 'box'
+$x(['class' => 'p-4']); // => 'box p-4'
+```
+
+A variant value may map to `null` to contribute nothing — useful as an explicit "unset" option in an axis.
+
+## Calling the result
+
+Pass a single props array, CVA-style. Keys match your variant axis names; omitted axes fall back to `defaultVariants`.
+
+```php
+$button(['intent' => 'secondary']);
+// => 'btn font-semibold border rounded bg-gray-200 text-gray-800 text-base px-4 py-2'
+
+$button(['size' => 'sm', 'class' => 'mt-4']);
+// => 'btn font-semibold border rounded bg-blue-500 text-white text-sm px-2 py-1 mt-4'
+```
+
+The `class` key (and its alias `className`) is appended to the end of the output. Appending alone does not resolve conflicts — see the component pattern below for that.
+
+## compoundVariants
+
+Each entry in `compoundVariants` is an array of variant conditions plus a `class` (or `className`) of extra classes. The classes apply only when every condition matches the resolved props (defaults included). A condition value can be a single string or an array of strings to match any of several values.
+
+```php
+$button = variants([
+ 'base' => 'btn',
+ 'variants' => [
+ 'intent' => [
+ 'primary' => 'bg-blue-500',
+ 'warning' => 'bg-yellow-500',
+ 'danger' => 'bg-red-500',
+ ],
+ 'size' => ['sm' => 'text-sm', 'md' => 'text-base'],
+ ],
+ 'compoundVariants' => [
+ // Applies only when intent=primary AND size=md
+ ['intent' => 'primary', 'size' => 'md', 'class' => 'uppercase'],
+ // Applies when intent is warning OR danger
+ ['intent' => ['warning', 'danger'], 'class' => '!border-red-500'],
+ ],
+ 'defaultVariants' => ['intent' => 'primary', 'size' => 'md'],
+]);
+
+$button();
+// => 'btn bg-blue-500 text-base uppercase'
+
+$button(['intent' => 'danger']);
+// => 'btn bg-red-500 text-base !border-red-500'
+```
+
+## Component pattern
+
+`variants()` only appends `class`; to let callers truly override variant defaults, wrap the output in [cn()](/docs/class-utilities) so conflicts resolve in the caller's favor.
+
+```php
+use function TailwindPHP\variants;
+use function TailwindPHP\cn;
+
+function Button(array $props = []): string {
+ static $styles = null;
+ $styles ??= variants([
+ 'base' => 'inline-flex items-center justify-center rounded-md font-medium',
+ 'variants' => [
+ 'variant' => [
+ 'default' => 'bg-primary text-primary-foreground hover:bg-primary/90',
+ 'outline' => 'border border-input bg-background hover:bg-accent',
+ 'ghost' => 'hover:bg-accent hover:text-accent-foreground',
+ ],
+ 'size' => [
+ 'default' => 'h-10 px-4 py-2',
+ 'sm' => 'h-9 px-3',
+ 'lg' => 'h-11 px-8',
+ ],
+ ],
+ 'defaultVariants' => ['variant' => 'default', 'size' => 'default'],
+ ]);
+
+ // cn() merges variant output with custom classes, resolving conflicts
+ $class = cn($styles($props), $props['class'] ?? null);
+ $text = $props['children'] ?? 'Button';
+ return "";
+}
+
+// The custom px-8 wins over the variant's px-3 via cn()
+Button(['variant' => 'outline', 'size' => 'sm', 'class' => 'mt-4 px-8']);
+```
+
+The `static $styles` cache builds the variant config once and reuses it across calls.
+
+## compose()
+
+`compose()` merges several variant components into one. The composed callable forwards each prop to every component, collects their outputs, and appends any `class`/`className`.
+
+```php
+use function TailwindPHP\variants;
+use function TailwindPHP\compose;
+
+$box = variants(['variants' => ['shadow' => ['sm' => 'shadow-sm', 'md' => 'shadow-md']]]);
+$stack = variants(['variants' => ['gap' => ['1' => 'gap-1', '2' => 'gap-2']]]);
+$card = compose($box, $stack);
+
+$card(['shadow' => 'md', 'gap' => '2']);
+// => 'shadow-md gap-2'
+```
+
+This keeps reusable axes (spacing, elevation, layout) in separate definitions and combines them per component.
+
+## Imports
+
+```php
+use function TailwindPHP\variants;
+use function TailwindPHP\compose;
+```
+
+Both live in the main `TailwindPHP` namespace and are bundled with the package — a PHP port of CVA by Joe Bell.
diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/cli.mdx
new file mode 100644
index 0000000..753db2a
--- /dev/null
+++ b/docs/content/docs/cli.mdx
@@ -0,0 +1,92 @@
+---
+title: CLI
+description: The bin/tailwindphp command — a 1:1 port of @tailwindcss/cli that builds, watches, and minifies CSS with no Node.js.
+---
+
+# CLI
+
+`./vendor/bin/tailwindphp` is a **1:1 port of [@tailwindcss/cli](https://github.com/tailwindlabs/tailwindcss/tree/next/packages/%40tailwindcss-cli)** — same options, same behavior, no Node.js required. After `composer require tailwindphp/tailwindphp`, the binary is linked into `vendor/bin/`.
+
+If you only need CSS at runtime from PHP, use the [API](/docs/api) instead — the CLI is for build-step workflows that write a stylesheet to disk.
+
+## Quick start
+
+```bash
+# Build CSS from an input file
+./vendor/bin/tailwindphp -i ./src/app.css -o ./dist/styles.css
+
+# Watch for changes and rebuild
+./vendor/bin/tailwindphp -i ./src/app.css -o ./dist/styles.css --watch
+
+# Build minified for production
+./vendor/bin/tailwindphp -i ./src/app.css -o ./dist/styles.css --minify
+```
+
+## Options
+
+```bash
+tailwindphp [--input input.css] [--output output.css] [--watch] [options…]
+```
+
+| Option | Description | Default |
+|---|---|---|
+| `-i, --input` | Input CSS file | `@import "tailwindcss"` |
+| `-o, --output` | Output file | `-` (stdout) |
+| `-w, --watch` | Watch for changes and rebuild as needed | — |
+| `-m, --minify` | Optimize and minify the output | — |
+| `--optimize` | Optimize the output without minifying | — |
+| `--cwd` | The current working directory | `.` |
+| `-h, --help` | Display usage information | — |
+
+When `--output` is `-` (the default), the compiled CSS is written to stdout, so you can pipe it elsewhere.
+
+## Input CSS
+
+Create an `app.css` with your Tailwind import and a `@source` directive telling TailwindPHP where to scan for classes:
+
+```css
+@import "tailwindcss";
+@source "./templates"; /* Directory to scan for classes */
+```
+
+`@source` accepts directories, glob patterns, and multiple entries:
+
+```css
+@import "tailwindcss";
+@source "./templates"; /* a directory */
+@source "./src/**/*.php"; /* a glob */
+@source "./resources/views"; /* add as many as you need */
+```
+
+See [@source](/docs/usage/source) for the full directive reference, including `not` and `inline()` forms.
+
+## Examples
+
+```bash
+# Build from CSS with a @source directive
+tailwindphp -i ./src/app.css -o ./dist/styles.css
+
+# Build minified for production
+tailwindphp -i ./src/app.css -o ./dist/styles.css -m
+
+# Watch mode with minification
+tailwindphp -i ./src/app.css -o ./dist/styles.css -w -m
+
+# Run against a different working directory
+tailwindphp -i app.css -o dist/styles.css --cwd=/path/to/project
+```
+
+The CLI creates the output directory if it does not exist, and exits with an error if the input file is missing or the input and output paths are identical.
+
+## Global installation
+
+Install globally to use `tailwindphp` from anywhere:
+
+```bash
+composer global require tailwindphp/tailwindphp
+
+# Now available globally
+tailwindphp -i ./src/app.css -o ./dist/styles.css
+```
+
+See [Getting Started](/docs/getting-started) for project setup and the [API](/docs/api) for runtime CSS generation from PHP.
diff --git a/docs/content/docs/getting-started.mdx b/docs/content/docs/getting-started.mdx
new file mode 100644
index 0000000..7372e1b
--- /dev/null
+++ b/docs/content/docs/getting-started.mdx
@@ -0,0 +1,113 @@
+---
+title: Getting Started
+description: Install TailwindPHP with Composer and generate your first Tailwind CSS from PHP — no Node.js, no build step, no config file.
+---
+
+# Getting Started
+
+## Install
+
+```bash
+composer require tailwindphp/tailwindphp
+```
+
+TailwindPHP needs PHP 8.2 or later and Composer. There is no Node.js dependency, no build step, and no npm in your Docker image or CI. Just `composer require` and call the API.
+
+## Generate your first CSS
+
+```php
+Hello
');
+```
+
+`generate()` scans the markup, extracts the class names it finds, and emits only the CSS those classes need — nothing more. With no second argument it uses a default `@import "tailwindcss"`, which pulls in the theme, [Preflight](/docs/usage/imports), and the utilities layer.
+
+## Customize via a CSS string
+
+Pass an input CSS string as the second argument to add `@theme` variables, custom rules, or directives. New theme values become utilities automatically:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate(
+ '
Hello
',
+ '@import "tailwindcss"; @theme { --color-brand: #3b82f6; }'
+);
+// .bg-brand now resolves to var(--color-brand)
+```
+
+See [Theme](/docs/usage/theme) for the full set of theme namespaces.
+
+## Array input
+
+For anything beyond a one-liner, pass an array with `content` and `css` keys. This is the place to define components with `@apply`:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate([
+ 'content' => '
Hello
',
+ 'css' => '
+ @import "tailwindcss";
+
+ @theme {
+ --color-brand: #3b82f6;
+ --font-heading: "Inter", sans-serif;
+ }
+
+ .btn {
+ @apply px-4 py-2 rounded-lg bg-brand text-white;
+ }
+ ',
+]);
+```
+
+The array form also accepts `minify`, `importPaths`, `cache`, and `cacheTtl`. See [Usage](/docs/usage) for the input formats and [Directives](/docs/usage/directives) for `@apply`, `@theme`, `@utility`, and friends.
+
+## Write to a file
+
+`generate()` returns a string, so writing a stylesheet is a one-liner:
+
+```php
+use TailwindPHP\tw;
+
+file_put_contents('dist/styles.css', tw::generate([
+ 'content' => file_get_contents('templates/page.html'),
+ 'css' => '@import "tailwindcss";',
+]));
+```
+
+For file-based builds, content scanning via `@source`, and watch mode, use the [CLI](/docs/cli) instead — it is a 1:1 port of `@tailwindcss/cli`.
+
+## Minify for production
+
+Pass `minify => true` to compress the output during generation, or call `tw::minify()` on an existing string:
+
+```php
+use TailwindPHP\tw;
+
+// Minify during generation
+$css = tw::generate([
+ 'content' => '
');
+$minified = tw::minify($css);
+```
+
+The minifier removes comments, collapses whitespace, shortens hex colors (`#ffffff` to `#fff`), and strips units from zero values (`0px` to `0`). See [Caching & minification](/docs/advanced/caching) for caching options.
+
+## Next steps
+
+- [Usage](/docs/usage) — the generate workflow, content scanning, and input formats.
+- [Class utilities](/docs/class-utilities) — `cn()`, `merge()`, `join()`, and `variants()`.
+- [Plugins](/docs/plugins) — typography, forms, and custom plugins.
+- [API](/docs/api) — the full `tw` surface and reusable compiler instances.
+- [CLI](/docs/cli) — file-based and watch builds without Node.js.
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
new file mode 100644
index 0000000..2aaf72c
--- /dev/null
+++ b/docs/content/docs/index.mdx
@@ -0,0 +1,51 @@
+---
+title: TailwindPHP
+description: A 1:1 port of TailwindCSS 4.x to PHP. Generate Tailwind utility CSS with pure PHP — no Node.js, no build step — plus cn(), tailwind-merge, CVA, and the typography and forms plugins.
+---
+
+# TailwindPHP
+
+TailwindPHP is a **1:1 port of TailwindCSS 4.x to PHP**. It parses your CSS, scans your markup for class names, and generates the exact same utility CSS that TailwindCSS produces — entirely in PHP, with no Node.js, no build step, and no extensions beyond a standard PHP 8.2+ build.
+
+- **Pure PHP** — ships as a Composer package and runs anywhere PHP 8.2+ runs. No `exec`, no FFI, no native build tooling.
+- **Byte-for-byte output** — utilities, variants, directives, and CSS functions all match TailwindCSS v4.3. Output is verified against Tailwind's own test suites, extracted from the TypeScript source and re-run on every push (4,000+ tests).
+- **The whole feature set** — all 364 utilities, every variant (hover, focus, responsive, dark mode, container queries, arbitrary values), and the full directive surface: `@import`, `@theme`, `@apply`, `@utility`, `@custom-variant`, `@layer`, `@plugin`, and `@source`.
+- **Batteries included** — `cn()`, `merge()`, `join()`, and `variants()` bundle PHP ports of clsx, tailwind-merge, and CVA, so the companion libraries every Tailwind project reaches for are already there.
+- **Plugins** — `@tailwindcss/typography` and `@tailwindcss/forms` are ported in full, and a PHP plugin API lets you write your own.
+
+## Why TailwindPHP exists
+
+TailwindCSS is written in TypeScript and runs on Node.js. That's a hard requirement for any PHP project that wants Tailwind: a second runtime, an npm install, and a build step in CI and Docker. For a lot of PHP applications that's friction they'd rather not take on.
+
+TailwindPHP removes it. Your PHP code compiles Tailwind CSS directly, using only the standard library. That unlocks a few things that are awkward or impossible with the JavaScript toolchain:
+
+- **WordPress and PHP frameworks** — ship Tailwind-powered themes and plugins without asking users to install Node.js or run a build. Just `composer require` and go.
+- **Runtime CSS** — generate utility CSS on the fly from user input, database content, or template variables, instead of at build time.
+- **Simpler deployment** — no Node.js in production, no build step in CI, no npm in your Docker image.
+
+It's the same idea [scssphp](https://github.com/scssphp/scssphp) brought to SCSS — the full compiler, in PHP.
+
+## What it does
+
+- Compiles the complete TailwindCSS v4.3 utility set, variants, and arbitrary values from class names found in your content.
+- Resolves the full directive surface: `@import` (including virtual modules like `tailwindcss` and `tailwindcss/utilities`), `@theme`, `@apply`, `@utility`, `@custom-variant`, `@layer`, `@plugin`, and `@source`.
+- Implements Tailwind's CSS functions — `theme()`, `--theme()`, `--spacing()`, and `--alpha()` — plus `color-mix()` → `oklab()` conversion and the CSS transforms TailwindCSS delegates to LightningCSS.
+- Resolves `@import` from the filesystem with nested imports, deduplication, and custom resolvers, or from inline CSS strings.
+- Ships Preflight (Tailwind's base reset), prefix support, `@property` fallbacks, vendor prefixing, and keyframe hoisting.
+- Bundles `cn()`, `merge()`, `join()`, and `variants()`/`compose()` for class-name construction, conflict resolution, and component variants.
+- Includes the typography and forms plugins, plus a plugin API (`addUtilities`, `matchUtilities`, `addComponents`, `addVariant`, `theme`, …) for custom plugins.
+- Provides a CLI (`bin/tailwindphp`) that mirrors `@tailwindcss/cli`, plus file-based caching and a CSS minifier for production.
+
+## What it is not
+
+TailwindPHP is a CSS compiler, not an editor toolchain. It deliberately leaves out the IDE-facing pieces of the Tailwind ecosystem — IntelliSense, autocomplete, class sorting, and source maps — because those are editor features, not part of CSS generation. Everything that produces CSS is in scope; everything that powers your editor is not.
+
+## Where to start
+
+- [Getting Started](/docs/getting-started) — install the package and generate your first stylesheet.
+- [Usage](/docs/usage) — scan content, customize the theme, and use Tailwind's directives.
+- [Class Utilities](/docs/class-utilities) — `cn()`, `merge()`, `join()`, and `variants()`.
+- [Plugins](/docs/plugins) — typography, forms, and writing your own.
+- [API](/docs/api) — the full `tw` surface and the `TailwindCompiler` instance.
+- [CLI](/docs/cli) — `bin/tailwindphp` for file-based builds and watch mode.
+- [Advanced](/docs/advanced) — architecture, caching, and performance.
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
new file mode 100644
index 0000000..fcaa894
--- /dev/null
+++ b/docs/content/docs/meta.json
@@ -0,0 +1,13 @@
+{
+ "title": "Documentation",
+ "pages": [
+ "index",
+ "getting-started",
+ "usage",
+ "class-utilities",
+ "plugins",
+ "api",
+ "cli",
+ "advanced"
+ ]
+}
diff --git a/docs/content/docs/plugins/custom.mdx b/docs/content/docs/plugins/custom.mdx
new file mode 100644
index 0000000..e339bb0
--- /dev/null
+++ b/docs/content/docs/plugins/custom.mdx
@@ -0,0 +1,123 @@
+---
+title: Custom Plugins
+description: Write your own plugin by implementing PluginInterface and using the PluginAPI to register utilities, components, and variants, then load it with @plugin.
+---
+
+# Custom Plugins
+
+A custom plugin is a PHP class implementing `TailwindPHP\Plugin\PluginInterface`. It receives a `PluginAPI` instance and uses it to register static and functional utilities, components, and variants. Once registered with `registerPlugin()`, the plugin resolves by name in a `@plugin` directive — the same mechanism the built-in typography and forms plugins use.
+
+## `PluginInterface`
+
+Implement three methods:
+
+```php
+namespace TailwindPHP\Plugin;
+
+interface PluginInterface
+{
+ public function getName(): string;
+ public function __invoke(PluginAPI $api, array $options = []): void;
+ public function getThemeExtensions(array $options = []): array;
+}
+```
+
+- `getName()` returns the identifier used in `@plugin "..."`.
+- `__invoke()` runs the plugin, registering everything through `$api`. The `$options` array carries the values from the `@plugin` CSS block.
+- `getThemeExtensions()` returns theme namespaces to merge before utilities are generated (return `[]` if none).
+
+## Example
+
+```php
+use TailwindPHP\Plugin\PluginInterface;
+use TailwindPHP\Plugin\PluginAPI;
+
+class MyCustomPlugin implements PluginInterface
+{
+ public function getName(): string
+ {
+ return 'my-custom-plugin';
+ }
+
+ public function __invoke(PluginAPI $api, array $options = []): void
+ {
+ // Static utilities
+ $api->addUtilities([
+ '.btn' => [
+ 'padding' => '0.5rem 1rem',
+ 'border-radius' => '0.25rem',
+ 'font-weight' => '600',
+ ],
+ '.btn-primary' => [
+ 'background-color' => 'blue',
+ 'color' => 'white',
+ ],
+ ]);
+
+ // Functional utilities (generates .tab-1, .tab-2, .tab-4, .tab-8)
+ $api->matchUtilities(
+ [
+ 'tab' => fn ($value) => ['tab-size' => $value],
+ ],
+ ['values' => ['1' => '1', '2' => '2', '4' => '4', '8' => '8']]
+ );
+
+ // Component classes (sorted into the components layer)
+ $api->addComponents([
+ '.card' => [
+ 'background-color' => 'white',
+ 'border-radius' => '0.5rem',
+ 'padding' => '1rem',
+ ],
+ ]);
+
+ // Custom variant
+ $api->addVariant('hocus', '&:hover, &:focus');
+
+ // Read a theme value
+ $primary = $api->theme('colors.blue.500', '#3b82f6');
+ }
+
+ public function getThemeExtensions(array $options = []): array
+ {
+ return []; // Return theme additions if needed
+ }
+}
+```
+
+## `PluginAPI` reference
+
+The API mirrors the TailwindCSS plugin API:
+
+| Method | Signature | Purpose |
+|--------|-----------|---------|
+| `addBase` | `addBase(array $css): void` | Add base-layer styles. |
+| `addUtilities` | `addUtilities(array $utilities, array $options = []): void` | Register static utility classes keyed by selector. |
+| `matchUtilities` | `matchUtilities(array $utilities, array $options = []): void` | Register functional utilities; `$options['values']` supplies the value map, `$options['supportsNegativeValues']` enables negatives. |
+| `addComponents` | `addComponents(array $components, array $options = []): void` | Register component classes (components layer). |
+| `matchComponents` | `matchComponents(array $components, array $options = []): void` | Register functional components with a value map. |
+| `addVariant` | `addVariant(string $name, string\|array $variant): void` | Register a static variant from a selector. |
+| `matchVariant` | `matchVariant(string $name, callable $callback, array $options = []): void` | Register a functional variant; `$options['values']` supplies the value map. |
+| `theme` | `theme(string $path, mixed $defaultValue = null): mixed` | Read a theme value by dot path (e.g. `colors.blue.500`). |
+| `config` | `config(?string $path = null, mixed $defaultValue = null): mixed` | Read a config value by dot path, or the whole config when `$path` is null. |
+| `prefix` | `prefix(string $className): string` | Apply the configured prefix to a class name. |
+
+The callback passed to `matchUtilities`, `matchComponents`, and `matchVariant` receives the value and a second argument array containing a `modifier` key.
+
+## Registering and using
+
+Register the plugin instance, then reference it by the name from `getName()`:
+
+```php
+use TailwindPHP\tw;
+use function TailwindPHP\registerPlugin;
+
+registerPlugin(new MyCustomPlugin());
+
+$css = tw::generate(
+ '
…
',
+ '@plugin "my-custom-plugin"; @import "tailwindcss/utilities.css";'
+);
+```
+
+See [Plugins](/docs/plugins) for the `@plugin` directive, and [Theme](/docs/usage/theme) for the values exposed through `$api->theme()`.
diff --git a/docs/content/docs/plugins/forms.mdx b/docs/content/docs/plugins/forms.mdx
new file mode 100644
index 0000000..6534465
--- /dev/null
+++ b/docs/content/docs/plugins/forms.mdx
@@ -0,0 +1,74 @@
+---
+title: Forms Plugin
+description: The @tailwindcss/forms port resets native form controls to a consistent baseline so inputs, selects, checkboxes, and radios are easy to style with utilities.
+---
+
+# Forms Plugin
+
+`@tailwindcss/forms` is a 1:1 PHP port of the official forms plugin. It provides an opinionated reset for form controls — text inputs, textareas, selects, checkboxes, and radios — bringing them to a consistent baseline (appearance reset, border, padding, focus ring, custom select chevron and checkbox/radio icons) that you can then override with utilities.
+
+## Usage
+
+Load the plugin with `@plugin` and import the utilities layer:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate(
+ '',
+ '@plugin "@tailwindcss/forms"; @import "tailwindcss/utilities.css";'
+);
+```
+
+## Strategy
+
+The `strategy` option controls how styles are applied:
+
+| Strategy | Behavior |
+|----------|----------|
+| `base` | Styles native form elements globally via selectors like `[type='text']`, `textarea`, and `select`. |
+| `class` | Styles only the explicit `form-*` classes, leaving unclassed elements untouched. |
+
+When `strategy` is omitted, **both** strategies are applied — native elements get the baseline reset and the `form-*` classes are available too. Set a single strategy to opt out of the other:
+
+```css
+@plugin "@tailwindcss/forms" {
+ strategy: "class";
+}
+```
+
+## Class strategy
+
+With the `class` strategy (or the default), apply these classes explicitly to the elements you want to style:
+
+| Class | Element |
+|-------|---------|
+| `form-input` | Text-like inputs |
+| `form-textarea` | `
+
+
+
+
+ ',
+ '
+ @plugin "@tailwindcss/forms" {
+ strategy: "class";
+ }
+ @import "tailwindcss/utilities.css";
+ '
+);
+```
+
+Each class resets the control's appearance and sets borders, padding, and a focus ring; `form-select` adds a chevron background image, and `form-checkbox`/`form-radio` add checked-state icons. Override any of it with regular utilities (for example `class="form-input rounded-lg border-gray-300"`).
+
+See [Plugins](/docs/plugins) for the `@plugin` directive and loading details.
diff --git a/docs/content/docs/plugins/index.mdx b/docs/content/docs/plugins/index.mdx
new file mode 100644
index 0000000..fb1de2b
--- /dev/null
+++ b/docs/content/docs/plugins/index.mdx
@@ -0,0 +1,69 @@
+---
+title: Plugins
+description: Load the official typography and forms plugins with the @plugin directive, pass options via CSS blocks, and register your own PHP plugin classes.
+---
+
+# Plugins
+
+TailwindPHP ships PHP ports of the official TailwindCSS plugins and exposes a native PHP plugin API. Plugins register utilities, components, and variants; they are loaded with the `@plugin` directive in your input CSS. The built-in plugins are 1:1 ports of their JavaScript counterparts — same selectors and output — implemented in PHP rather than executed through Node.
+
+## Using `@plugin`
+
+Reference a plugin by name with `@plugin`. Built-in plugins use their npm package name. Pair the directive with `@import "tailwindcss/utilities.css";` so the plugin's classes are emitted into the utilities layer:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate([
+ 'content' => '
Hello
Content here
',
+ 'css' => '
+ @plugin "@tailwindcss/typography";
+ @import "tailwindcss/utilities.css";
+ ',
+]);
+```
+
+Multiple plugins can be loaded together, and order is independent:
+
+```css
+@plugin "@tailwindcss/typography";
+@plugin "@tailwindcss/forms";
+@import "tailwindcss/utilities.css";
+```
+
+`@plugin` cannot be nested inside another at-rule (such as `@media`), and an unregistered plugin name throws.
+
+## Plugin options
+
+Pass options to a plugin using CSS block syntax after the name. Keys map to the plugin's option array:
+
+```css
+@plugin "@tailwindcss/forms" {
+ strategy: "class";
+}
+
+@plugin "@tailwindcss/typography" {
+ className: "markdown";
+}
+```
+
+The `@tailwindcss/forms` plugin accepts `strategy` (`base` or `class`); `@tailwindcss/typography` accepts `className` to rename the generated `prose` class. See the per-plugin pages for the full option list.
+
+## Built-in plugins
+
+| Plugin | Description |
+|--------|-------------|
+| `@tailwindcss/typography` | The `prose` classes — typographic defaults for rich text. See [Typography](/docs/plugins/typography). |
+| `@tailwindcss/forms` | Resettable, stylable form controls. See [Forms](/docs/plugins/forms). |
+
+## Custom plugins
+
+Write your own plugin by implementing `PluginInterface` and using the methods on `PluginAPI` (`addUtilities`, `matchUtilities`, `addComponents`, `addVariant`, `theme`, and more). Register it with `registerPlugin(new MyPlugin())` so the name returned by `getName()` resolves in a `@plugin "my-plugin"` directive:
+
+```php
+use function TailwindPHP\registerPlugin;
+
+registerPlugin(new MyCustomPlugin());
+```
+
+See [Custom Plugins](/docs/plugins/custom) for the interface, a full example, and the complete `PluginAPI` method reference.
diff --git a/docs/content/docs/plugins/meta.json b/docs/content/docs/plugins/meta.json
new file mode 100644
index 0000000..f5fa6d8
--- /dev/null
+++ b/docs/content/docs/plugins/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Plugins",
+ "pages": ["index", "typography", "forms", "custom"]
+}
diff --git a/docs/content/docs/plugins/typography.mdx b/docs/content/docs/plugins/typography.mdx
new file mode 100644
index 0000000..092bd0a
--- /dev/null
+++ b/docs/content/docs/plugins/typography.mdx
@@ -0,0 +1,86 @@
+---
+title: Typography Plugin
+description: The @tailwindcss/typography port adds the prose classes — typographic defaults for rendered HTML — with size, color, and invert modifiers.
+---
+
+# Typography Plugin
+
+`@tailwindcss/typography` is a 1:1 PHP port of the official typography plugin. It adds the `prose` class and its modifiers, which apply readable typographic defaults to a block of rendered HTML — headings, paragraphs, lists, blockquotes, code, tables, and more — without styling each element by hand.
+
+## Usage
+
+Load the plugin with `@plugin` and import the utilities layer, then apply `prose` to the container that wraps your content:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate(
+ '
Title
Body text…
',
+ '@plugin "@tailwindcss/typography"; @import "tailwindcss/utilities.css";'
+);
+```
+
+The generated `.prose` rule defines `--tw-prose-*` custom properties (`--tw-prose-body`, `--tw-prose-headings`, `--tw-prose-links`, `--tw-prose-code`, `--tw-prose-quotes`, and others) and styles the descendant elements through them.
+
+## Classes
+
+### Sizes
+
+Size modifiers scale the entire type ramp. They are applied alongside the base `prose` class:
+
+| Class | Purpose |
+|-------|---------|
+| `prose` | Default size |
+| `prose-sm` | Small |
+| `prose-base` | Base |
+| `prose-lg` | Large |
+| `prose-xl` | Extra large |
+| `prose-2xl` | 2× extra large |
+
+```html
+…
+```
+
+### Color themes
+
+Color modifiers swap the gray scale used for body text, headings, and borders:
+
+| Class | Theme |
+|-------|-------|
+| `prose-slate` | Slate |
+| `prose-gray` | Gray |
+| `prose-zinc` | Zinc |
+| `prose-neutral` | Neutral |
+| `prose-stone` | Stone |
+
+### Invert
+
+`prose-invert` flips the color palette for use on dark backgrounds. Combine it with size and color modifiers freely:
+
+```html
+…
+```
+
+## Options
+
+### `className`
+
+By default the plugin generates the `prose` class. Set `className` to rename it — the modifiers follow the new name (`markdown`, `markdown-lg`, `markdown-invert`, …). When set, `prose` classes are not generated:
+
+```php
+$css = tw::generate(
+ '…',
+ '
+ @plugin "@tailwindcss/typography" {
+ className: "markdown";
+ }
+ @import "tailwindcss/utilities.css";
+ '
+);
+```
+
+## Notes
+
+This is a TailwindCSS v4 port. Some v3-specific behaviors from the original plugin — `.dark`-selector dark mode and certain element-variant config formats — work differently in v4 and are not supported here; use the `prose-invert` modifier and v4 variants instead.
+
+See [Plugins](/docs/plugins) for the `@plugin` directive and loading details.
diff --git a/docs/content/docs/usage/directives.mdx b/docs/content/docs/usage/directives.mdx
new file mode 100644
index 0000000..e2b0dec
--- /dev/null
+++ b/docs/content/docs/usage/directives.mdx
@@ -0,0 +1,131 @@
+---
+title: Directives
+description: Inline utilities with @apply, register custom utilities with @utility, define variants with @custom-variant, and control cascade order with @layer.
+---
+
+# Directives
+
+Directives are the `@`-prefixed at-rules you write in your input CSS to compose, extend, and order Tailwind's output. This page covers `@apply`, `@utility`, `@custom-variant`, and `@layer`. `@theme` is covered in [Theme](/docs/usage/theme); `@plugin` in [Plugins](/docs/plugins); and `@source` in [@source](/docs/usage/source).
+
+## `@apply`
+
+`@apply` inlines the declarations of existing utilities into your own selector. Use it to attach utility styles to a semantic class, including inside nested selectors and media queries.
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate('
', '
+ @import "tailwindcss";
+
+ @theme { --color-brand: #3b82f6; }
+
+ .btn {
+ @apply px-4 py-2 rounded-lg bg-brand text-white;
+ }
+');
+```
+
+Variants work in an `@apply` list — `@apply bg-blue-500 hover:bg-blue-600;` expands the `:hover` state, and responsive prefixes such as `@apply px-4 md:px-6 lg:px-8;` emit the corresponding `@media` rules. The important modifier is honored too (`@apply !flex;`). Nested selectors are supported, so a rule like `.card { h2 { @apply text-xl font-bold; } }` applies utilities to the nested `h2`.
+
+## `@utility`
+
+`@utility` registers a custom utility that participates in Tailwind's engine — it sorts into the `utilities` layer and accepts variants like any built-in. A static utility takes a fixed body:
+
+```css
+@utility content-auto {
+ content-visibility: auto;
+}
+```
+
+Because it is a real utility, variants compose automatically (`hover:content-auto`, `md:content-auto`). The body may itself use `@apply` and nested selectors:
+
+```css
+@utility btn-primary {
+ @apply px-4 py-2 bg-blue-500 text-white rounded;
+}
+
+@utility card {
+ color: red;
+ &:hover { color: blue; }
+}
+```
+
+A functional utility uses a `-*` suffix in the name and reads the matched value with `--value()`:
+
+```css
+@utility tab-* {
+ tab-size: --value(--tab-size, integer);
+}
+```
+
+`--value()` resolves the candidate's value — here either a `--tab-size-*` theme token or a bare integer — so `tab-4` produces `tab-size: 4`.
+
+## `@custom-variant`
+
+`@custom-variant` defines a new variant you can prefix onto any utility. The compact form names the variant and gives a selector or at-rule in parentheses.
+
+A selector-list variant uses `&` for the element:
+
+```css
+@custom-variant hocus (&:hover, &:focus);
+```
+
+`hocus:bg-blue-500` then emits both the `:hover` and `:focus` rules. An attribute form works the same way:
+
+```css
+@custom-variant loading (&[data-loading="true"]);
+```
+
+An at-rule variant wraps matched utilities in that at-rule:
+
+```css
+@custom-variant tablet (@media (min-width: 600px));
+```
+
+Custom variants stack with built-ins — `sm:hocus:bg-blue-500` nests the `hocus` selector inside the `sm` media query. For more involved cases, use the block form with `@slot` marking where the utility's declarations are injected:
+
+```css
+@custom-variant child {
+ & > * {
+ @slot;
+ }
+}
+
+@custom-variant sidebar-open {
+ .sidebar-open & {
+ @slot;
+ }
+}
+```
+
+## `@layer`
+
+`@layer` controls cascade order using native CSS cascade layers. A bare `@layer` statement declares the order of layers; later layers win regardless of selector specificity. Tailwind's canonical order is:
+
+```css
+@layer theme, base, components, utilities;
+```
+
+This is exactly what `@import "tailwindcss"` sets up internally. You can declare your own order, or split it across multiple statements (`@layer reset, base;` then `@layer components, utilities;`), and assign rules to a named layer with a block:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate('
Title
', '
+ @import "tailwindcss";
+
+ @layer base {
+ h1 { font-size: var(--text-2xl); }
+ a { color: var(--color-blue-600); text-decoration-line: underline; }
+ }
+');
+```
+
+Adding base styles via `@layer base` keeps them below `components` and `utilities`, so a utility class always overrides your element defaults. The same applies to `@layer components { … }` for component classes that should sit beneath utilities. Anonymous layers and `layer()` modifiers on `@import` are covered in [Imports](/docs/usage/imports).
+
+## Next steps
+
+- [Theme](/docs/usage/theme) — `@theme` tokens and the theme functions.
+- [Imports](/docs/usage/imports) — `@import`, virtual modules, and `layer()` modifiers.
+- [Plugins](/docs/plugins) — the `@plugin` directive and the plugin API.
+- [@source](/docs/usage/source) — control which files and classes are scanned.
diff --git a/docs/content/docs/usage/imports.mdx b/docs/content/docs/usage/imports.mdx
new file mode 100644
index 0000000..d5d1bf2
--- /dev/null
+++ b/docs/content/docs/usage/imports.mdx
@@ -0,0 +1,183 @@
+---
+title: Imports & Virtual Modules
+description: Resolve @import in your CSS — virtual modules, file imports via importPaths, custom resolvers, Preflight, and per-import modifiers.
+---
+
+# Imports & Virtual Modules
+
+TailwindPHP resolves `@import` rules before compilation. Imports can point at built-in virtual modules (`tailwindcss` and friends), at files on disk via the `importPaths` option, or at anything you return from a custom resolver.
+
+## Virtual modules
+
+`@import "tailwindcss"` is the entry point most projects use. It expands to the four lines below — the layer order declaration plus the three sub-imports, each assigned to its cascade layer:
+
+```css
+@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@import "tailwindcss/preflight.css" layer(base);
+@import "tailwindcss/utilities.css" layer(utilities);
+```
+
+Each sub-import is itself a virtual module you can import on its own. The available virtual modules are:
+
+| Module | Contents |
+|--------|----------|
+| `tailwindcss` | The full bundle: theme + Preflight + utilities. |
+| `tailwindcss/theme.css` | Theme variables only (colors, spacing base, breakpoints, etc.). |
+| `tailwindcss/preflight.css` | The Preflight base reset. |
+| `tailwindcss/utilities.css` | The utilities layer. |
+| `tw-animate-css` | The `tw-animate-css` animation utilities. |
+
+Importing the parts individually lets you skip Preflight or reorder layers (see below).
+
+## The `importPaths` option
+
+To resolve `@import` against the filesystem, pass `importPaths` in the array form of `generate()`. It accepts a single path, a directory, or an array of either.
+
+```php
+use TailwindPHP\tw;
+
+// Single file
+$css = tw::generate([
+ 'content' => '
',
+ 'css' => '.custom { color: red; }',
+ 'importPaths' => '/path/to/styles.css',
+]);
+```
+
+### Nested imports
+
+Imports inside a loaded file are resolved relative to that file. If `/path/to/styles.css` contains `@import "./components/buttons.css"`, the path is resolved against `/path/to/`:
+
+```css
+/* /path/to/styles.css */
+@import "tailwindcss";
+@import "./components/buttons.css";
+@import "./components/cards.css";
+
+@theme {
+ --color-brand: #3b82f6;
+}
+```
+
+### Deduplication
+
+Importing the same file or virtual module more than once is a no-op after the first — repeated `@import "tailwindcss"` lines, or two files that both import the same partial, are deduplicated automatically. This also protects against circular imports.
+
+## Custom resolver
+
+For virtual file systems, databases, or any non-filesystem source, pass a callable as `importPaths`. It receives the import URI and the file doing the importing, and returns CSS or `null`:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate([
+ 'content' => '
Hello
',
+ 'importPaths' => function (?string $uri, ?string $fromFile): ?string {
+ if ($uri === null) {
+ // Entry CSS — returned when no file is supplied
+ return '@import "tailwindcss"; @import "custom.css";';
+ }
+ if ($uri === 'custom.css') {
+ return '.virtual-class { color: purple; }';
+ }
+ return null; // Unknown imports are silently skipped
+ },
+]);
+```
+
+When `$uri` is `null`, return the entry CSS. For any other URI, return its CSS contents, or `null` to skip it.
+
+## Preflight
+
+Preflight is Tailwind's opinionated base reset, built on top of [modern-normalize](https://github.com/sindresorhus/modern-normalize). It smooths over cross-browser inconsistencies so utilities behave predictably. Among other things it removes default margins, unstyles headings and lists, makes images block-level, resets border styles so `border-width` alone draws a border, and lets buttons inherit fonts.
+
+Preflight ships inside `@import "tailwindcss"` — if you import the full bundle, you already have it:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate([
+ 'content' => '
Hello
',
+ 'css' => '@import "tailwindcss";',
+]);
+```
+
+### Extending Preflight
+
+Add your own base styles on top of Preflight with `@layer base`:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate([
+ 'content' => '
Title
Content
',
+ 'css' => '
+ @import "tailwindcss";
+ @layer base {
+ h1 { font-size: var(--text-2xl); }
+ h2 { font-size: var(--text-xl); }
+ a { color: var(--color-blue-600); text-decoration-line: underline; }
+ }
+ ',
+]);
+```
+
+### Disabling Preflight
+
+When integrating into an existing project, import only the parts you need and omit the Preflight line:
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate([
+ 'content' => '
Hello
',
+ 'css' => '
+ @layer theme, base, components, utilities;
+ @import "tailwindcss/theme.css" layer(theme);
+ @import "tailwindcss/utilities.css" layer(utilities);
+ ',
+]);
+```
+
+## Import modifiers
+
+When importing Tailwind's files individually, modifiers go on the imports they affect:
+
+```css
+/* Assign the import to a cascade layer */
+@import "tailwindcss/utilities.css" layer(utilities);
+
+/* prefix affects both theme variables and utilities */
+@import "tailwindcss/theme.css" layer(theme) prefix(tw);
+@import "tailwindcss/utilities.css" layer(utilities) prefix(tw);
+
+/* important affects utilities */
+@import "tailwindcss/utilities.css" layer(utilities) important;
+
+/* theme(static) or theme(inline) affects theme variables */
+@import "tailwindcss/theme.css" layer(theme) theme(static);
+```
+
+Continue with [Theme](/docs/usage/theme) for theme variables, or [@source](/docs/usage/source) to control which files are scanned for class names.
diff --git a/docs/content/docs/usage/index.mdx b/docs/content/docs/usage/index.mdx
new file mode 100644
index 0000000..4381a24
--- /dev/null
+++ b/docs/content/docs/usage/index.mdx
@@ -0,0 +1,83 @@
+---
+title: Usage
+description: Generate Tailwind CSS from your content — scan markup for class names, pass optional CSS configuration, and get back only the CSS you use.
+---
+
+# Usage
+
+The core workflow is a single call: give TailwindPHP your content plus optional CSS configuration, and it returns the CSS for the classes it finds. Class names are extracted from the markup, compiled against the resolved theme, and the result contains only the utilities you actually use.
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate('
Hello
');
+```
+
+With no second argument, `generate()` uses a default `@import "tailwindcss"` (theme + [Preflight](/docs/usage/imports) + utilities). Pass a CSS string or an array to customize.
+
+## Content scanning
+
+TailwindPHP finds class names by reading the `class` and `className` attributes in your content. To inspect what gets pulled out, use `tw::extractCandidates()`:
+
+```php
+use TailwindPHP\tw;
+
+tw::extractCandidates('
');
+// ['flex', 'p-4', 'bg-blue-500']
+```
+
+Both `class` and `className` attributes are scanned, and the returned list is deduplicated. Arbitrary candidates (such as `[mask-type:luminance]` or `bg-[#1da1f2]`) are extracted the same way and compiled if they are valid. Whatever appears here is exactly what `generate()` will compile.
+
+## Input formats
+
+Every static method accepts the same three input shapes:
+
+| Format | Signature | Use when |
+|--------|-----------|----------|
+| String only | `tw::generate($content)` | Default theme, no customization. |
+| String + CSS string | `tw::generate($content, $css)` | Quick theme tweaks or directives inline. |
+| Array | `tw::generate(['content' => ..., 'css' => ...])` | You need `minify`, `importPaths`, or `cache`. |
+
+```php
+use TailwindPHP\tw;
+
+// Format 1: String only
+tw::generate('
');
+
+// Format 2: String + CSS string
+tw::generate('
', '@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');
+
+// Format 3: Array with content, css, and options
+tw::generate([
+ 'content' => '
',
+ 'css' => '@import "tailwindcss";',
+ 'minify' => true,
+]);
+```
+
+The array form is the only one that takes options. Beyond `css` and `minify` it accepts `importPaths` (see [Imports](/docs/usage/imports)), `cache`, and `cacheTtl` (see [Caching](/docs/advanced/caching)).
+
+## Reusable compiler
+
+Compiling many fragments against the same configuration — a request loop, a batch of templates, a component library — is cheaper with a single compiler instance. `tw::compile()` resolves the theme and design system once, then reuses them:
+
+```php
+use TailwindPHP\tw;
+
+$compiler = tw::compile('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');
+
+$css = $compiler->generate('
');
+$candidates = $compiler->extractCandidates('
');
+$minified = $compiler->minify($css);
+```
+
+The compiler also exposes property inspection (`properties()`, `computedProperties()`, `value()`, `computedValue()`) and theme accessors (`colors()`, `breakpoints()`, `spacing()`). See the full [API](/docs/api) for every method.
+
+## Configuring the input CSS
+
+Most of TailwindPHP's power lives in the CSS string you pass as configuration. Continue with:
+
+- [Theme](/docs/usage/theme) — `@theme` variables and namespaces.
+- [Directives](/docs/usage/directives) — `@apply`, `@utility`, `@layer`, `@custom-variant`.
+- [Imports](/docs/usage/imports) — `@import`, virtual modules, `importPaths`, and Preflight.
+- [@source](/docs/usage/source) — control which files and classes are scanned.
diff --git a/docs/content/docs/usage/meta.json b/docs/content/docs/usage/meta.json
new file mode 100644
index 0000000..a837b9b
--- /dev/null
+++ b/docs/content/docs/usage/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Usage",
+ "pages": ["index", "theme", "directives", "imports", "source"]
+}
diff --git a/docs/content/docs/usage/source.mdx b/docs/content/docs/usage/source.mdx
new file mode 100644
index 0000000..3b3762c
--- /dev/null
+++ b/docs/content/docs/usage/source.mdx
@@ -0,0 +1,104 @@
+---
+title: The @source Directive
+description: Use @source in your input CSS to control which template files are scanned for class names and which candidates are forced in or excluded.
+---
+
+# The @source Directive
+
+`@source` lives in your input CSS and tells TailwindPHP where to find the template files it should scan for class names. It is primarily used with the [CLI](/docs/cli), where a single input CSS file drives a build over a content directory.
+
+```css
+@import "tailwindcss";
+@source "./templates";
+```
+
+`@source` directives are read during compilation and removed from the output — they never appear in the generated CSS. Paths must be quoted, and both single and double quotes are accepted.
+
+## Directories
+
+Point `@source` at a directory to scan every supported file inside it:
+
+```css
+@source "./templates";
+```
+
+## Glob patterns
+
+Narrow the scan with a glob:
+
+```css
+@source "./src/**/*.php";
+```
+
+## Multiple sources
+
+Add as many `@source` directives as you need; they accumulate:
+
+```css
+@source "./templates";
+@source "./components/**/*.php";
+```
+
+## Negated patterns
+
+Prefix a path with `not` to exclude it from scanning:
+
+```css
+@source "./src";
+@source not "./src/legacy";
+```
+
+## Inline candidates
+
+`@source inline(...)` forces classes into the output even when they never appear in scanned files — useful for class names assembled dynamically at runtime:
+
+```css
+@source inline("flex p-4 m-2");
+```
+
+Inline candidates support variants too:
+
+```css
+@source inline("hover:bg-blue-500 focus:ring-2");
+```
+
+### Brace expansion
+
+Inline patterns expand brace groups, so you can enumerate many candidates compactly:
+
+```css
+@source inline("p-{1,2,4}");
+/* Generates p-1, p-2, and p-4 */
+
+@source inline("text-{red,blue}-500");
+/* Generates text-red-500 and text-blue-500 */
+```
+
+## Ignored inline candidates
+
+`@source not inline(...)` does the opposite of `inline()` — it strips matching candidates from the output even if they were found in your content. Brace expansion works here as well:
+
+```css
+@source not inline("legacy");
+@source not inline("p-{1,2}");
+```
+
+## Validation rules
+
+`@source` is a statement, not a block. The compiler rejects:
+
+- A directive with a body — `@source cannot have a body.`
+- A nested directive (inside `@media`, for example) — `@source cannot be nested.`
+- An unquoted path — `@source paths must be quoted.`
+
+```css
+/* Invalid — throws "`@source` cannot have a body." */
+@source "./src" {
+ .some-style { color: red; }
+}
+
+/* Invalid — throws "`@source` paths must be quoted." */
+@source ./src;
+```
+
+See the [CLI](/docs/cli) for running source-driven builds, and [Imports](/docs/usage/imports) for resolving `@import` and virtual modules.
diff --git a/docs/content/docs/usage/theme.mdx b/docs/content/docs/usage/theme.mdx
new file mode 100644
index 0000000..754a34e
--- /dev/null
+++ b/docs/content/docs/usage/theme.mdx
@@ -0,0 +1,167 @@
+---
+title: Theme & Customization
+description: Define design tokens with @theme, read them in CSS with theme() and the --theme/--spacing/--alpha functions, and inspect resolved values from PHP.
+---
+
+# Theme & Customization
+
+Tailwind's theme is a flat set of CSS variables. You extend or replace it with a `@theme { … }` block in your input CSS, reference those values from inside CSS via the theme functions, and read the resolved values back from PHP. There is no JavaScript config file — the theme lives entirely in CSS.
+
+## The `@theme` block
+
+A `@theme` block declares design tokens as CSS custom properties. The namespace prefix on each variable (`--color-*`, `--font-*`, `--breakpoint-*`, `--spacing-*`, …) tells Tailwind which utilities and variants the token feeds.
+
+```php
+use TailwindPHP\tw;
+
+$css = tw::generate('
', '
+ @import "tailwindcss";
+
+ @theme {
+ --color-brand: #3b82f6;
+ --font-heading: "Inter", sans-serif;
+ --breakpoint-xs: 20rem;
+ --spacing-huge: 10rem;
+ }
+');
+```
+
+Each token registers utilities under its namespace. The example above makes `bg-brand`, `text-brand`, `border-brand`, the `font-heading` family, an `xs:` responsive variant, and `p-huge`/`m-huge` spacing available — generated only when the class appears in your content.
+
+```css
+/* bg-brand resolves to the theme variable */
+:root {
+ --color-brand: #3b82f6;
+}
+.bg-brand {
+ background-color: var(--color-brand);
+}
+```
+
+The `--breakpoint-xs` token registers the `xs:` variant directly:
+
+```css
+@media (min-width: 20rem) {
+ .xs\:flex {
+ display: flex;
+ }
+}
+```
+
+### Common namespaces
+
+| Namespace | Feeds |
+|-----------|-------|
+| `--color-*` | `bg-*`, `text-*`, `border-*`, `fill-*`, `stroke-*`, … |
+| `--font-*` | `font-*` family utilities |
+| `--text-*` | `text-*` font-size utilities |
+| `--breakpoint-*` | responsive variants (`sm:`, `md:`, custom `xs:`) |
+| `--spacing-*` | named spacing values (`p-huge`, `m-huge`) |
+| `--radius-*` | `rounded-*` utilities |
+| `--shadow-*` | `shadow-*` utilities |
+
+### Clearing a namespace
+
+Setting a namespace wildcard to `initial` removes Tailwind's defaults for that namespace before your own tokens are added. This lets you start from a clean palette:
+
+```css
+@theme {
+ /* Drop every default color, then define only what you need */
+ --color-*: initial;
+ --color-brand: #3b82f6;
+ --color-ink: #111827;
+}
+```
+
+`--*: initial;` clears the entire theme. A single value of `initial` on a non-wildcard key (`--color-red-500: initial;`) removes just that one token. Only `initial` is accepted as the value for a `-*` wildcard — any other value is an error.
+
+## Reading theme values in CSS
+
+### `theme()`
+
+The legacy `theme()` function reads a value using dot notation against the v3-style namespaces. It resolves to the token's value at compile time, so it can be used anywhere a value is expected — including custom rules and other declarations.
+
+```php
+$css = tw::generate('
+ A 1:1 port of TailwindCSS 4.x to PHP. Compile the full utility set —
+ every variant, directive, and arbitrary value — in pure PHP, with no
+ Node.js and no build step. cn(), tailwind-merge, CVA, and the typography
+ and forms plugins are bundled in.
+