@use Modules vs. @extend: Managing Placeholder Inheritance Across Boundaries

Decision Criteria: Refactor vs. Defer

The decision to refactor @extend chains during a migration to @use depends on the scale of your design system and your tolerance for technical debt. Because @extend resolution is confined to the module scope, cross-module placeholders silently fail to produce CSS output.

Refactor Immediately If:

• You are building a shared library: If your Sass is distributed as a package, @import dependencies create unpredictable global collisions for consumers.
• CSS Bundle Size is Critical: @use improves compilation performance and source map accuracy, which outweighs the manual effort of refactoring placeholders.
• You have a strict CI/CD pipeline: If your build process treats deprecation warnings as errors, deferring is not an option.

Defer Migration If:

• The codebase is "Legacy-Stable": If the styles are rarely touched and the @import chain is stable, the risk of introducing regression during a massive @extend refactor may exceed the benefit of removing warnings.
• Placeholder Density is Extreme: If hundreds of selectors rely on a few central placeholders, a manual migration to mixins may introduce significant duplication in the final CSS.

Patterns to Minimize Duplication

To maintain the benefits of @use without duplicating placeholder definitions, transition from inheritance (@extend) to composition (@mixin).

The Mixin Pattern

Replace %placeholder with a @mixin. While @extend groups selectors in the CSS, a mixin copies the properties. This is the standard approach for module-based Sass.

// _shared.scss
@mixin base-button {
  padding: 10px;
  border-radius: 4px;
}

// _component.scss
@use 'shared';

.btn-primary {
  @include shared.base-button;
  background: blue;
}

The CSS Custom Property Pattern

For values that change frequently but the structure remains the same, move the shared logic to CSS variables defined at the :root. This removes the need for Sass-level inheritance entirely for those specific properties.

Validating Silent Failures

Since Dart Sass does not always throw a hard error for unresolvable @extend directives across modules, you must verify the output manually or via tooling:

1. CSS Diffing: Compare the compiled CSS output of the @import version against the @use version. Any missing selectors in the new version indicate a failed @extend.
2. Verbose Compilation: Run the compiler with --verbose to check for warnings regarding unresolvable placeholders.
3. Visual Regression Testing: Use tools like BackstopJS or Playwright to ensure components still inherit the expected styles.

Diagnostic Requirement: Are you using @use '...' as * as a temporary shim? This allows @extend to work by flattening the namespace, but it defeats the primary purpose of module encapsulation.