Glossary

These are terms that appear all over the codebase. Most map to a specific type, file, or directory.

Candidate

A string that might be a Tailwind class, e.g. bg-red-500, md:hover:flex, [--my-var:1], bg-[#fff]/50!. The scanner emits raw candidate strings; the compiler tries to parse each one with parseCandidate (packages/tailwindcss/src/candidate.ts). Successfully parsed candidates become Candidate objects (variants, root, modifier, value, important flag).

Utility

A unit of generated CSS keyed by a class name. Utilities are registered with designSystem.utilities.functional(...) or .static(...) (packages/tailwindcss/src/utilities.ts and the v3 compat layer in packages/tailwindcss/src/compat/plugin-api.ts). When a candidate's root matches a utility, the utility's compileFn returns AST nodes that become the rule body.

Variant

A class prefix that wraps the generated rule in a selector or at-rule. Examples: hover:, md:, dark:, group-hover:, peer-focus:, has-[…], not-…. Variants are registered in packages/tailwindcss/src/variants.ts and applied in applyVariant (packages/tailwindcss/src/compile.ts).

Compound variant

A variant that takes another variant as an argument and modifies it, e.g. not-hover:, group-data-[open]:, peer-supports-[backdrop-filter]:. Implemented in applyVariant by recursively resolving the inner variant, then letting the outer variant mutate the result.

Design system

The runtime context for a single compile() call. Holds the theme, registered utilities, registered variants, prefix, important flag, and ordering tables. Constructed in packages/tailwindcss/src/design-system.ts (buildDesignSystem) and threaded through every plugin/utility/variant call.

Theme

A keyed map of CSS custom properties exposed via @theme. Theme keys are namespaced (--color-red-500, --font-sans, --spacing). The Theme class lives in packages/tailwindcss/src/theme.ts. ThemeOptions flags (REFERENCE, INLINE, DEFAULT, STATIC) control how theme values surface in output CSS.

@theme

A CSS at-rule that declares theme tokens. Values become CSS custom properties on :root plus design-system entries that utilities can read. @theme reference declares tokens without emitting them — useful in component libraries.

@utility

A CSS at-rule that declares a custom utility. The compiler turns @utility tab-1 { tab-size: 1; } into a registered utility named tab-1. Functional utilities use a trailing -* (e.g. @utility tab-* { tab-size: --value(integer); }). Implemented in createCssUtility (packages/tailwindcss/src/utilities.ts).

@variant

Two related at-rules. As a directive inside CSS it conditionally wraps the body in another variant (@variant hover { ... }). As a registration it can also act like @custom-variant when given a body but no selector. See packages/tailwindcss/src/variants.ts and the @variant handling in parseCss (packages/tailwindcss/src/index.ts).

@apply

Pulls the rules generated by other utilities into the current rule. Implementation in packages/tailwindcss/src/apply.ts (substituteAtApply). Recurses through @apply chains and resolves them against the current design system.

@source

Declares an extra glob (or inline(...)/not … form) for the scanner. Recognized in parseCss and forwarded to the adapter via compiler.sources. The Rust scanner can also auto-detect sources when no @source is given.

@reference

Imports a stylesheet for theme/variant access only — no CSS is emitted from the imported file. Used by component libraries to consume design tokens without duplicating output.

Polyfills

The compiler emits fallback CSS for two browser features behind the Polyfills enum in packages/tailwindcss/src/index.ts:

• AtProperty — generates a @supports block plus --tw-… declarations to back the typed custom properties registered by utilities like transform.
• ColorMix — emits color-mix(...) fallbacks for opacity modifiers.

Features (the bit-set)

Features is an enum/bit-set returned by compile() (packages/tailwindcss/src/index.ts). Each bit is set if the input CSS used the corresponding Tailwind feature: AtApply, AtImport, JsPluginCompat, ThemeFunction, Utilities, Variants, AtTheme. Adapters use it to short-circuit rebuilds when none of the features are present.

Scanner

The Rust struct in crates/oxide/src/scanner/mod.rs. Walks file trees, tracks mtimes, runs extractors, and returns a deduped set of candidate strings. Exposed as the Scanner class via crates/node/src/lib.rs (@tailwindcss/oxide).

Extractor

The collection of state machines under crates/oxide/src/extractor/ that scan raw bytes and emit Extracted::Candidate / Extracted::CssVariable spans. Each machine handles one shape (utility, variant, modifier, arbitrary value, etc.).

Pre-processor

A per-extension transform applied before the extractors run. Lives in crates/oxide/src/extractor/pre_processors/. Examples: stripping Pug indentation, normalizing Slim attributes, decoding Razor directives.

Source detection (auto_source_detection)

The default rules for what to scan when no @source directive is given. Defined in crates/oxide/src/scanner/auto_source_detection.rs and crates/oxide/src/scanner/sources.rs. Excludes binary extensions, .gitignore-listed paths, and known build outputs.

Boundary

The character class that determines where a candidate ends. Implemented in crates/oxide/src/extractor/boundary.rs. Roughly: candidates can be terminated by whitespace, quotes, brackets, and a configurable set of punctuation depending on the surrounding context.

Canonicalize

A normalization pass that rewrites class lists into their preferred shorthand (px-4 py-4 → p-4, [&:has(…)] → has-[…], etc.). Used by both the upgrade tool and a tailwindcss canonicalize CLI subcommand. Implementation in packages/tailwindcss/src/canonicalize-candidates.ts.

Codemod

A transformation applied by the upgrade tool. Codemods come in three flavors under packages/@tailwindcss-upgrade/src/codemods/:

• css/ — rewrites *.css files (e.g. migrate-tailwind-directives, migrate-at-apply).
• template/ — rewrites class lists in templates (migrate-prefix, migrate-modernize-arbitrary-values).
• config/ — rewrites JS configs and PostCSS configs into v4 equivalents.

Instrumentation

A timing helper used everywhere. The Instrumentation class is defined in packages/@tailwindcss-node/src/instrumentation.ts and consumed in adapters and the browser build. When DEBUG is set it logs span durations to stderr. The browser variant in packages/@tailwindcss-browser/src/instrumentation.ts reports to the browser performance timeline.

Layer

A grouping at-rule (@layer base, @layer components, @layer utilities) that controls cascade ordering. Tailwind injects its own layers when processing @import "tailwindcss".

Standalone

The native, dependency-free CLI binary. Built with Bun in packages/@tailwindcss-standalone/scripts/build.ts, bundles @tailwindcss/cli, the official forms/typography/aspect-ratio plugins, and per-platform Lightning CSS / @parcel/watcher binaries.

v3 / "compat" / "legacy"

References to Tailwind CSS v3 compatibility. packages/tailwindcss/src/compat/ provides the bridge so v3 JavaScript configs (tailwind.config.js) and plugins (tailwindcss/plugin) keep working in v4. See v3 compatibility.