adastra_app/docs/decisions/0012-scss-bootstrap-import-deprecation.md

ADR 0012: SCSS Strategy — Bootstrap Variable Overrides and Sass @import Deprecation

Date: 2026-04-26 Status: Accepted (workaround pending Bootstrap 6)

Context

Bootstrap 5 relies on Sass's @import rule and !default variable overrides: our custom _variable.scss must be loaded before Bootstrap's variables.scss so that Bootstrap picks up our values via !default.

Dart Sass 1.80+ deprecates @import in favour of the @use module system. The @use system uses isolated module scopes, which breaks the !default override mechanism: variables loaded via @use in our file do not flow into Bootstrap's module scope.

Migrating to @use for the Bootstrap import chain would require either:

• Waiting for Bootstrap 6, which is expected to adopt @use natively.
• Rewriting the entire Bootstrap variable override mechanism using @use "bootstrap" with (...).

Neither option is viable in the short term.

Decision

• Suppress the Sass @import deprecation warning in angular.json via stylePreprocessorOptions.sass.silenceDeprecations: ["import"].
• Keep the existing @import-based Bootstrap loading chain intact.
• Fix other Dart Sass deprecations properly: color.red/green/blue() replaced with color.channel(), global if() replaced with @if/@else.

Consequences

• Positive: Bootstrap customisation works correctly with no behaviour change.
• Negative: Deprecation silenced rather than fixed. @import will be removed in Dart Sass 3.0.
• Future action: When Bootstrap 6 is released with @use support, migrate the import chain and remove the silenceDeprecations entry. Supersede this ADR at that point.