@use module adoption boundary when replacing Sass @import in Dart Sass

The Compatibility Boundary

In Dart Sass, the compatibility boundary is file-based. While the compiler allows both rules to exist within a project, mixing @use and @import within a single stylesheet is not structurally safe. Because @import operates on a global scope and @use operates on a namespaced module system, combining them in one file leads to unpredictable execution order and potential CSS duplication.

Execution Model Risks

The primary risk of partial migration within a single file is the breakdown of the module system's core guarantee: that a module is executed only once. When you mix these rules, the following occurs:

• Global Pollution: @import continues to pull all variables, mixins, and functions into the global namespace.
• Isolation Failure: @use attempts to isolate members. If a file uses both, the compiler may struggle to determine if a variable should be resolved via the module namespace or the global scope, often resulting in duplication of the compiled CSS output.

Handling Unconverted Dependencies

When your project has adopted the module system but relies on third-party libraries that still use @import, use the following strategies:

1. Maintain Separate Entry Points: Keep legacy libraries in their own @import-based files. Do not attempt to @use a library that is authored with @import, as it will not provide the expected namespacing and may ignore module semantics.
2. Global Access: Dependencies loaded via @import remain accessible globally. You can continue to use their mixins and variables without a namespace, provided the import occurs before the styles that require them.
3. The Wrapper Pattern: If you require a library to behave like a module, you must create a migration wrapper. This involves converting the library's internal @import statements to @use or @forward.

Verification Steps

To verify your migration boundary, run these checks in your build pipeline:

• Inspect Output: Compare the generated CSS of a mixed file against a fully converted @use file. Look for duplicated rule sets which indicate the module system is being bypassed.
• Namespace Check: Ensure that variables from @use modules are prefixed (e.g., colors.$primary) and that legacy imports remain unprefixed.

Diagnostic Detail: Are you using the sass-migrator tool for this transition? The tool can automate the conversion of @import to @use, which eliminates the risk of manual mixing within files.