adastra_app/docs/decisions/0003-dual-ui-library-progressive-migration.md

ADR 0003: Dual UI Library — Progressive Migration Strategy

Date: 2026-04-26 Status: Accepted (transitional)

Context

The application currently uses two UI libraries simultaneously:

• Angular Material — component library (buttons, dialogs, tables, forms, etc.)
• Bootstrap 5 — layout utilities, typography, spacing, and some components

This coexistence is a legacy of a progressive migration: Bootstrap was the original styling layer, and Angular Material was introduced incrementally. Maintaining both libraries increases bundle size, creates styling inconsistencies, and adds cognitive overhead.

Decision

Accept the dual-library state as a transitional phase. The long-term goal is to consolidate to a single UI library. Neither Angular Material nor Bootstrap is guaranteed to be the final choice — the decision will be made when consolidation is actively prioritised, potentially in favour of a different library altogether.

In the meantime:

• Angular Material handles interactive components (dialogs, forms, navigation).
• Bootstrap handles layout (grid, spacing utilities) and fills gaps where Material has no equivalent.

Consequences

• Positive: No big-bang UI rewrite required at this stage.
• Negative: Two styling systems in tension. Bootstrap's @import-based Sass is incompatible with the @use module system; Dart Sass deprecation warnings are silenced in angular.json as a workaround (see ADR 0012).
• Future action: When consolidation is prioritised, evaluate the available options (Material 3, PrimeNG, Spartan/shadcn-angular, or custom) and supersede this ADR.