julien/adastra_app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(adr): convert all ADRs to MADR 2.1.2 format

Browse Source 
Rewrites all 12 frontend ADRs from a custom structure to the MADR 2.1.2
template required by the VS Code ADR Manager extension: bullet metadata
(Status/Date), standardised section headings, "Chosen option: X, because Y"
wording, and explicit Pros/Cons blocks per option.
This commit is contained in:
Julien Gautier
2026-04-26 16:50:34 +02:00
parent 8f2632f456
commit c8e2fba13e
12 changed files with 478 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/decisions/0003-dual-ui-library-progressive-migration.md
+45 -17
View File
@@ -1,28 +1,56 @@
# ADR 0003: Dual UI Library — Progressive Migration Strategy
# Coexist Angular Material and Bootstrap during UI library consolidation
**Date:** 2026-04-26
**Status:** Accepted (transitional)
- Status: accepted
- Date: 2026-04-26
## Context
## Context and Problem Statement
The application currently uses two UI libraries simultaneously:
The application currently uses two UI libraries: Angular Material (interactive components) and Bootstrap 5 (layout, spacing utilities). Bootstrap was the original styling layer; Angular Material was introduced incrementally. Maintaining both increases bundle size, creates styling inconsistencies, and adds cognitive overhead. Which strategy should be adopted?
- **Angular Material** — component library (buttons, dialogs, tables, forms, etc.)
- **Bootstrap 5** — layout utilities, typography, spacing, and some components
## Considered Options
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.
- Keep both libraries and consolidate later
- Consolidate to Angular Material only
- Consolidate to Bootstrap only
- Migrate to a different library (PrimeNG, Spartan/shadcn-angular, etc.)
## Decision
## Decision Outcome
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.
Chosen option: "Keep both libraries and consolidate later", because a big-bang UI rewrite is not justified at this stage and the final target library has not yet been chosen.
In the meantime:
### Positive Consequences
- Angular Material handles interactive components (dialogs, forms, navigation).
- Bootstrap handles layout (grid, spacing utilities) and fills gaps where Material has no equivalent.
- No immediate rewrite required — development velocity is preserved.
- Each library covers the other's gaps during the transition period.
## Consequences
### Negative 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.
- Two styling systems in tension, leading to inconsistent UX.
- Bootstrap's `@import`-based Sass is incompatible with the `@use` module system, requiring a deprecation workaround (see ADR 0012).
- Larger CSS bundle than a single-library solution.
## Pros and Cons of the Options
### Keep both libraries and consolidate later
- Good, because no rewrite cost now.
- Bad, because styling inconsistency and larger bundle persist until consolidation.
### Consolidate to Angular Material only
- Good, because single coherent design system.
- Bad, because Bootstrap layout utilities would need to be replaced.
### Consolidate to Bootstrap only
- Good, because removes Angular Material dependency.
- Bad, because Angular Material components (dialogs, date pickers, etc.) would need rebuilding.
### Migrate to a different library
- Good, because could address limitations of both current libraries.
- Bad, because highest rewrite cost; unknown tradeoffs until evaluated.
## Links
- Related to [ADR 0012](0012-scss-bootstrap-import-deprecation.md)