Introducing a new way to review your PRs.

Read the announcement

tailwindlabs / tailwindcss

A utility-first CSS framework for rapid UI development.

View on GitHub

19 documents · Updated Nov 20, 2026

docs / css-directives-and-parsing

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.

DirectiveCompiler work
@tailwind utilitiesMarks the place where generated utility rules will be inserted. It can also set the candidate source root.
@themeAdds theme variables and keyframes to the design system.
@utilityRegisters a custom utility for later candidate compilation.
@variantRequests variant transformation for a rule.
@custom-variantRegisters a named variant for later use.
@sourceAdds candidate file patterns or inline candidates.
@applyRequests expansion of utility candidates inside a rule.
@plugin and @configLoad 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 @theme reference or prefix behavior must remain consistent for emitted variables, theme function resolution, and @apply.
  • Changes to @source must preserve the distinction between file patterns, inline candidates, and explicitly ignored candidates.
  • Changes to @utility or @custom-variant registration must preserve dependency ordering before @apply and 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 @layer ordering markers and required external imports.

Important failure modes

TriggerConsequenceGuard
Unbalanced braces or parentheses, an unterminated string, or an invalid custom propertyCSS parsing stops before directive processingThe 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 limitCompilation fails before the imported directives can affect the design systemThe integration must provide a working stylesheet loader, and import depth is limited.
A nested @source, @utility, @plugin, @config, or @custom-variant violates its placement rulesThe directive is rejected instead of producing partial compiler stateDirective scans validate nesting and required parameters.
An @theme block contains content other than custom properties or keyframesTheme registration fails and no dependent utilities are builtTheme processing validates the block contents.
@apply names an unknown utility or variant, or creates a dependency cycleCSS generation fails rather than silently omitting the requested stylesCandidate validation and dependency ordering run before expansion.
Nested selectors or @scope rules are normalized with the wrong parent contextAuthored rules or variant-generated rules apply to the wrong elementsAST normalization tracks user and variant context while resolving nesting and hoisting scope rules.

Key files

FileWhy to read it
packages/…/index.tsMain coordinator for parsing, directive recognition, design-system setup, and the build handoff.
packages/…/css-parser.tsDefines how CSS text becomes a syntax tree and how syntax errors receive source locations.
packages/…/at-import.tsShows how local imports and references become part of one compiler tree.
packages/…/ast.tsDefines the shared CSS node model, context markers, tree cleanup, and CSS nesting normalization.
packages/…/ast.test.tsShows the output guarantees for AST cleanup, nesting, scope handling, and rule ordering.
packages/…/apply.tsExplains how CSS @apply requests become utility compilation work.
packages/…/variants.tsShows how @variant requests become transformed rules after variant registration.
packages/…/apply-compat-hooks.tsDefines the boundary for legacy @plugin and @config support.