CSS directives and parsing
The core CSS pipeline reads a CSS entry file, turns it into a tree of CSS nodes, and uses Tailwind directives as work orders for the compiler. It resolves local stylesheet imports, gathers theme and source information, registers custom behavior, and prepares the tree for utility and variant generation.
Input model
CSS syntax tree
The parser in packages/…/css-parser.ts turns CSS text into a nested syntax tree of style rules, at-rules, declarations, and comments. This gives later passes one shared view of normal CSS and Tailwind directives, so both can remain in the same source file and preserve their place in the output.
The parser understands escaped characters, quoted strings, comments, nested brackets, custom properties, and declarations without a final semicolon. It also accepts HTML comment markers between top-level nodes and distinguishes a final !important flag from text inside a value. It removes ordinary comments and moves license comments to the start of the tree. When the caller provides a source path, nodes carry source ranges for diagnostics and source maps.
Invalid CSS stops the pipeline with a CssSyntaxError. The error includes the source file and line position when source information is available.
References: packages/…/css-parser.ts• L38-72 packages/…/css-parser.ts• L101-178 packages/…/css-parser.ts• L205-239 packages/…/css-parser.ts• L615-677
Tree traversal
The compiler walks the syntax tree in source order. The walk can keep a node, skip its children, replace it with other nodes, or remove it. This lets a directive either configure later work or become ordinary CSS before the final output is printed.
Context nodes carry facts such as the base path of an imported sheet, reference mode, or theme mode. These facts follow the relevant subtree without changing the CSS that the user wrote. The AST also keeps source context for variant-generated and user-authored content, so later nesting work can apply the correct selector rules.
References: packages/…/walk.ts• L1-20 packages/…/walk.ts• L44-55 packages/…/ast.ts• L53-71 packages/…/ast.ts• L191-220 packages/…/ast.ts• L411-435
CSS tree normalization
The AST normalizer prepares the shared tree for safe CSS output after directive work is complete. It removes compiler-only context, drops empty or impossible rules, keeps required ordering markers, and preserves source links while it resolves CSS nesting and hoists environment rules such as @media and @scope.
This step keeps authored CSS and generated utility rules compatible in one output tree. User-authored @scope keeps CSS nesting semantics, while scope rules produced by variants use the variant's parent selector so the final rule applies to the intended utility. The normalizer also removes theme values and keyframes that no output rule uses, while retaining values marked as static or required by another theme value.
References: packages/…/ast.ts• L223-248 packages/…/ast.ts• L368-435 packages/…/ast.ts• L454-519 packages/…/ast.ts• L707-725 packages/…/ast.ts• L740-805 packages/…/ast.ts• L953-1213 packages/…/ast.ts• L1278-1450
Directive processing
Directive scan
packages/…/index.ts is the main coordinator for directive processing. After it parses the entry CSS and places it in a root context, it scans at-rules and records the work that each directive requests.
The scan does not treat every at-rule as a Tailwind directive. Unknown CSS at-rules remain in the tree for normal CSS processing. Tailwind directives either register information in the design system, mark an insertion point, collect source or module paths, or are replaced with nodes that later compiler stages can use.
| Directive | Compiler work |
|---|---|
@tailwind utilities | Marks the place where generated utility rules will be inserted. It can also set the candidate source root. |
@theme | Adds theme variables and keyframes to the design system. |
@utility | Registers a custom utility for later candidate compilation. |
@variant | Requests variant transformation for a rule. |
@custom-variant | Registers a named variant for later use. |
@source | Adds candidate file patterns or inline candidates. |
@apply | Requests expansion of utility candidates inside a rule. |
@plugin and @config | Load legacy JavaScript extensions through the compatibility layer. |
References: packages/…/index.ts• L143-170 packages/…/index.ts• L175-308 packages/…/index.ts• L311-455 packages/…/apply-compat-hooks.ts• L54-145
Utility insertion point
@tailwind utilities is the handoff from CSS input to candidate-driven generation. The compiler keeps the first such directive as the insertion point, removes later copies, and later replaces the first node with the rules built from valid candidates.
The directive can include source(none) to disable automatic source discovery or source("...") to set an explicit source pattern. If the input has no utility directive, the compiler can still process other CSS and directive work, but it has no location for generated utility rules.
References: packages/…/index.ts• L175-222 packages/…/index.ts• L682-688 packages/…/index.ts• L754-855
Theme registration
@theme defines the design values that utility and variant compilation can resolve. Its custom properties become theme entries, while its keyframes are retained for later placement in the output. The first theme position becomes the output position for the emitted theme variables.
Theme options control whether values are emitted, used as references, treated as defaults, or expanded inline. A theme prefix changes the names used by both theme variables and the utilities that refer to them. A theme block accepts only custom properties and keyframes, so invalid contents fail early.
References: packages/…/index.ts• L87-106 packages/…/index.ts• L547-601 packages/…/index.ts• L655-676 packages/…/theme.ts• L4-12 packages/…/theme.ts• L41-85
Utility and variant registration
@utility and @custom-variant extend the design system before candidates are compiled. A custom utility supplies CSS for a named utility family. A custom variant supplies selector or at-rule behavior that can wrap utility rules.
The compiler registers custom variants in dependency order. This allows one custom variant to use another and lets the compiler report circular definitions before it generates CSS. The registration directives themselves are removed from the final CSS.
@variant has a different role: it applies an already known variant to the rules in its body. The compiler replaces it with the transformed rules after all variants are available.
References: packages/…/index.ts• L224-255 packages/…/index.ts• L311-455 packages/…/index.ts• L628-653 packages/…/variants.ts• L1290-1340
Candidate source control
@source tells the compiler where candidate names may come from or which names to add directly. A normal source becomes a file pattern associated with a base path. An inline(...) source expands candidate patterns immediately. A negated source marks matching candidates as invalid instead of adding them.
The resulting source records are returned to the caller that scans project files. Inline candidates are already available when the compiler builds its first result. This separates source discovery from CSS generation while keeping both decisions in the CSS entry file.
References: packages/…/index.ts• L258-309 packages/…/index.ts• L744-749
Rule expansion
@apply turns utility names written in a CSS rule into the declarations and nested rules for those utilities. The compiler first gathers all definitions and dependencies, then expands them in dependency order. This supports custom utilities that apply other custom utilities.
The same candidate rules used for generated utilities provide the source of the expansion. Variant names are checked as part of that work, and circular utility dependencies are rejected. @apply is therefore a compile-time request rather than a CSS at-rule that remains in the output.
References: packages/…/apply.ts• L10-79 packages/…/apply.ts• L81-150 packages/…/apply.ts• L156-218 packages/…/index.ts• L678-680
Import resolution
Stylesheet imports
The import pass resolves local @import and @reference rules before the main directive scan. The caller supplies a stylesheet loader. Each loaded sheet is parsed with its own base path, and its own imports are resolved before its nodes are placed into the parent tree.
The pass keeps remote and data imports in the CSS because the core compiler does not fetch them. It inlines local imports and wraps their nodes with the requested layer, media condition, or supports condition. This preserves the meaning of the import while making the imported directives visible to the same compiler run.
References: packages/…/at-import.ts• L7-24 packages/…/at-import.ts• L26-80 packages/…/at-import.ts• L150-177
Reference mode
@reference loads a stylesheet for its theme and utility knowledge without treating that stylesheet as ordinary output CSS. The compiler marks the imported subtree as reference content, so theme values remain available for operations such as @apply while reference-only theme variables are not emitted as normal declarations.
An import can also request reference, theme, or prefix behavior through its conditions. The compiler carries these requests into the imported tree and uses them when it processes theme blocks and utility generation.
References: packages/…/at-import.ts• L26-36 packages/…/index.ts• L457-545 packages/…/index.ts• L547-566 packages/…/theme.ts• L193-207
Import boundaries
Each imported stylesheet receives the directory or base path returned by the loader. That path controls the next level of relative imports and the source location attached to imported nodes. The import pass uses a recursion limit because core does not have enough path information to prove that every import cycle is circular.
The loader is part of the integration boundary. The core package asks for content and resolved base data, while the surrounding tool decides how package names and file paths are found.
References: packages/…/index.ts• L56-77 packages/…/at-import.ts• L44-72
Compiler handoff
The input flow moves from authored CSS to a shared tree, then to directive state and generated rules, before the tree is normalized for serialization.
flowchart LR
A[CSS input] --> B[CSS syntax tree]
B --> C[Directive and import scan]
C --> D[Design system and compiler work]
D --> E[Generated utility rules]
E --> F[Normalized CSS tree]
F --> G[CSS output]
Design system setup
After the directive scan, the compiler builds a design system from the collected theme and utility information. It then applies compatibility hooks, registers custom variants and utilities, expands variants and functions, and resolves @apply before candidate-driven output is built.
The compiler also records feature flags for the work requested by the input. These flags let callers identify whether imports, utilities, variants, theme data, functions, @apply, or compatibility support affected the result.
References: packages/…/index.ts• L604-653 packages/…/index.ts• L655-712 packages/…/index.ts• L118-141
Candidate compilation
The build API accepts candidate names from source scanning and combines them with candidates from @source inline(...). It rejects known invalid candidates, parses valid candidates, and asks the design system to produce sorted AST nodes for the utility and its variants.
The generated nodes replace the saved @tailwind utilities position. If no new candidate changes the result, the compiler can reuse the prior AST. This supports repeated builds as source files change without reparsing the CSS entry work for every candidate update.
References: packages/…/index.ts• L715-857 packages/…/compile.ts• L11-121
Output preparation
The final AST contains both user CSS and generated rules. The optimizer removes compiler-only context and directive nodes, normalizes nesting, removes unused theme material, and keeps relevant source information for CSS serialization. The public compile API then returns CSS text and can build a source map from the current AST.
This page focuses on the input and directive stages. The broader ordering of generated utilities and the final CSS output belongs to compiler and CSS generation. Theme values are described in theme and design tokens, while candidate utility and variant rules are described in utility and variant compilation.
References: packages/…/index.ts• L715-729 packages/…/index.ts• L778-855 packages/…/index.ts• L861-907 packages/…/ast.ts• L223-248 packages/…/ast.ts• L454-519 packages/…/ast.ts• L1748-1968
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to directive names or parameters must stay aligned with the feature flags and the build handoff that decides whether work is needed.
- Changes to local import resolution must preserve the base path passed to nested stylesheet loads and to source records.
- Changes to
@themereference or prefix behavior must remain consistent for emitted variables, theme function resolution, and@apply. - Changes to
@sourcemust preserve the distinction between file patterns, inline candidates, and explicitly ignored candidates. - Changes to
@utilityor@custom-variantregistration must preserve dependency ordering before@applyand candidate compilation run. - Changes to parser source ranges must preserve both diagnostics and generated source maps.
- Changes to parser end-of-input handling must preserve valid declarations, custom properties, and at-rules that omit a final terminator.
- Changes to AST context or nesting rules must preserve the different selector behavior of authored CSS and variant-generated CSS.
- Changes to AST cleanup must preserve empty
@layerordering markers and required external imports.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Unbalanced braces or parentheses, an unterminated string, or an invalid custom property | CSS parsing stops before directive processing | The parser checks delimiters and required values, then reports CssSyntaxError with a source position when available. |
| A local import cannot be loaded or exceeds the recursion limit | Compilation fails before the imported directives can affect the design system | The integration must provide a working stylesheet loader, and import depth is limited. |
A nested @source, @utility, @plugin, @config, or @custom-variant violates its placement rules | The directive is rejected instead of producing partial compiler state | Directive scans validate nesting and required parameters. |
An @theme block contains content other than custom properties or keyframes | Theme registration fails and no dependent utilities are built | Theme processing validates the block contents. |
@apply names an unknown utility or variant, or creates a dependency cycle | CSS generation fails rather than silently omitting the requested styles | Candidate validation and dependency ordering run before expansion. |
Nested selectors or @scope rules are normalized with the wrong parent context | Authored rules or variant-generated rules apply to the wrong elements | AST normalization tracks user and variant context while resolving nesting and hoisting scope rules. |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.ts | Main coordinator for parsing, directive recognition, design-system setup, and the build handoff. |
| packages/…/css-parser.ts | Defines how CSS text becomes a syntax tree and how syntax errors receive source locations. |
| packages/…/at-import.ts | Shows how local imports and references become part of one compiler tree. |
| packages/…/ast.ts | Defines the shared CSS node model, context markers, tree cleanup, and CSS nesting normalization. |
| packages/…/ast.test.ts | Shows the output guarantees for AST cleanup, nesting, scope handling, and rule ordering. |
| packages/…/apply.ts | Explains how CSS @apply requests become utility compilation work. |
| packages/…/variants.ts | Shows how @variant requests become transformed rules after variant registration. |
| packages/…/apply-compat-hooks.ts | Defines the boundary for legacy @plugin and @config support. |