Imports

Use @import to deliver a stylesheet and make its definitions available. Use @reference when local compilation needs those definitions but another output owns the native stylesheet. For application setup, follow Installation; for route-specific ownership, see Route-level styles.

Both local outputs use bg-brand. An import delivers the native .card rule; a reference only makes definitions available. A locally used token can still emit with either output.

Text description

1. tokens.css declares --color-brand in @theme and a native .card rule that reads it. The two local compilations differ only in @import versus @reference.
2. Both local outputs generate bg-brand and retain its --color-brand dependency.
3. Only the import output contains .card. The reference does not make that rule a local usage root or publish the referenced stylesheet.
4. The branches compare compiled outputs, not runtime loading steps. Native overrides also need actual stylesheet delivery.

@import "@master/css"

The package import is the only project entry marker. It loads the preset's native CSS, including its stable layer order and base styles, and identifies the stylesheet that receives generated utility CSS.

@import "@master/css";

Explicit standalone compiler and manifest APIs remain available. A manifest alone does not load native CSS; applications using runtime or server rendering must also deliver the relevant native stylesheet.

Local file URLs

Node file compilation reads CSS import names using CSS escaping and case rules. Relative @import and @reference URLs resolve their pathname against the source file: percent escapes identify filename characters, while query strings and fragments are excluded from the filesystem path. For example, "./tokens%20%23.css?v=1#theme" reads a sibling file named tokens #.css. Existing bare relative CSS paths such as "tokens.css" are also expanded. Bare package imports without a matching local file remain available to the host resolver. Reference files remain compile-time context and do not emit their native CSS. For a prepared virtual stylesheet, the host's explicit filesystem source owner also supplies the base for relative CSS references. Resources in a referenced theme token remain relative to the reference file when used elsewhere.

Stylesheet boundaries and resource URLs

Import media, supports and layer qualifiers apply to the imported stylesheet. Keep those boundaries when publishing CSS, and resolve image and font URLs from their original source file. A token used through @reference also retains its defining file as the resource owner.

Global Master definitions belong in unqualified imports or references. A qualified import can contain native CSS, including native rules that apply a previously available mixin; it cannot register @theme, @utility, @mixin, @custom-media or @custom-container definitions.

@import "./tokens.css";@import "./print.css" print;@import "./components.css" layer(components);

Each @import inlines its stylesheet again, so a file imported from several places is repeated. One import graph inlines at most 10,000 stylesheets and 64 MiB of CSS; import shared files once instead of from every file that uses them.

Loading definitions and scanning metadata does not publish files. CLI file export and Vite production builds publish the required stylesheet and resource assets. Custom compiler hosts must publish every asset returned by their delivery APIs; a manifest alone does not deliver native rules. See rendering and stylesheet delivery and compiler entrypoints.

Publish the complete asset set

A compiled CSS entry can still import other CSS files or refer to images and fonts. Publishing only the entry text leaves those dependencies unavailable. Preserve each returned URL and import qualifier; flattening a child with an external import can change its loading order or conditional scope.

Follow the references from the entry to the child stylesheet and then its image. These are separate delivered files; the print qualifier stays on the import. Names are illustrative, not generated filename conventions.

Text description

1. The delivered app.css imports print.css with a print qualifier. The child remains a separate stylesheet, and that qualifier stays on its import.
2. A declaration in print.css refers to mark.svg relative to the child stylesheet’s delivered URL.
3. Publish the entry, child stylesheet and image at the URLs their references resolve to. Copying only app.css leaves two dependencies unavailable.
4. The drawing is a dependency graph, not a request waterfall. Actual generated names and whether an asset remains separate depend on the compilation and host.

Production flattening keeps the cascade: layer statements stay in place, layer(), supports() and media qualifiers become the equivalent @layer, @supports and @media blocks, and empty stylesheets disappear. External imports at the top of a stylesheet move up with it when only other external imports precede it. A stylesheet that keeps a namespace or an import under a qualifier, or whose external imports would follow inlined rules, remains a separate file, as do the imports before it in the same file, because an @import cannot follow rules.

Images and fonts retain the defining stylesheet as their source owner, including resources used through @reference. Publication rewrites their URLs while retaining query strings and fragments. Reference-only stylesheets are not published merely because their definitions were read.

The CLI's --no-export path prints CSS without copying assets. Its file-export watch path keeps the last successful output when an imported stylesheet or resource is missing, reports the error, and rebuilds after recovery. Do not treat stale output as a successful latest build.

For a custom host, use the compiler delivery contract. For Vite's processed-text, raw-source and URL imports, use Stylesheet loading. Route-level styles explains which page owns a local stylesheet.

@reference

Use a reference when compilation needs definitions from another stylesheet without importing its native rules. This example loads a spacing token and a selector mixin from the app entry:

@import "@master/css";@mixin --manual-dark {  &:where([data-theme="dark"], [data-theme="dark"] *) {    @contents;  }}

@reference "../app.css";.button {  padding: var(--spacing-md);  @apply --manual-dark {    color: white;  }}

A reference supplies tokens, utilities, mixins, custom media, custom containers and native keyframe definitions for resolution. It does not deliver the referenced file's native CSS, generate its classes, or add its scanning sources. Used managed tokens and keyframes can still cause local output to include their dependencies. Referenced native rules are never usage roots. Native overrides need an actual @import or another delivered stylesheet. Referenced keyframes are emitted only when locally used.

Both cases reference the same file. Only local usage changes. The output excerpt omits the surrounding theme layer.

Text description

1. The referenced file defines --color-accent and .remote { color: var(--color-accent); }. Its undelivered native rule is not a usage root.
2. A reference alone makes the token available without delivering that native rule or retaining the token solely for it.
3. Adding .local { color: var(--color-accent); } retains the token through the local consumer. The output still does not copy .remote.

References must be top-level statements containing one quoted resource. Relative paths use the declaring stylesheet's directory. Package references resolve exported CSS entries. References are not entry markers.

Vite, Next.js, and Webpack supply project definition context to local stylesheets, CSS Modules, and SFC styles. An explicit reference is useful for dependencies outside that context or standalone compilation. Local stylesheets do not become scanning or pruning roots. CSS Modules and scoped hosts must deliver generated theme selectors globally.

Definition context loads before local definitions, so local definitions can replace imported or referenced ones. Compiler hosts that split CSS output must also track which output delivers shared variables and keyframes; see compiler resource ownership.