PoC — Theming in Angular Microfrontends

Definitive branch: baseline/mfe-theming-with-shared-design-tokens
This branch contains all the experiment documentation and the reproducible project with the chosen solution.

---

1. Purpose of this PoC

This Proof of Concept (PoC) does not aim to validate a production-ready implementation. Instead, it serves as an architectural decision instrument for how to approach theming in an Angular microfrontends architecture using Angular Material.

The main objective is to evaluate the degree of coupling, the locus of design authority, and the real feasibility of different theming strategies while taking into account Angular Material's actual constraints and the core microfrontends principles (ownership, independence, and decoupled evolution).

This PoC should answer why a strategy is acceptable or not in a given context, not how to optimally implement it.

---

2. Questions this PoC intends to answer

This PoC exists to answer, with technical evidence and critical analysis, the following questions:

1. Is it viable to decouple Angular Material theming from the host without introducing hacks or brittle dependencies?
2. Where does coupling between host and microfrontends actually appear for each strategy?
3. Who exercises design authority and how does that power manifest technically?
4. What impact does each approach have on independent deployment of microfrontends?
5. Which strategy degrades worse in the medium and long term, even if it initially works?

If these questions cannot be answered clearly by the end of the PoC, the PoC should be considered unsuccessful.

---

3. Technical context and constraints

Stack

• Framework: Angular 17+
• UI library: Angular Material 17+
• Architecture: Angular microfrontends (apps, not web components)
• Federation: Module Federation or Native Federation (not an evaluation subject)

Explicit constraints

• Angular Material compiles theming at build-time, not at runtime.
• There is no official support for dynamic injection of complete themes.
• The CSS generated by Material is not a stable contract across versions.

These are not hypotheses: they are verifiable facts that constrain any evaluated approach.

---

4. What this PoC is NOT

To avoid misleading conclusions, it is important to clarify what this PoC does NOT evaluate:

• It does not evaluate performance or bundle size.
• It does not implement a full corporate design system.
• It does not address dynamic runtime dark mode.
• It does not pursue perfect visual consistency.
• It does not simulate a real production environment.

Any conclusion based on those aspects is explicitly out of scope.

---

5. Strategies under evaluation

This PoC evaluates three theming strategies, each isolated in an independent repository branch:

1. Host-centralized theme The host defines and distributes the Angular Material theme to the microfrontends.

2. Theme defined per microfrontend Each microfrontend compiles and manages its own Angular Material theme.

3. Shared design tokens + local theme Microfrontends share versioned design tokens but locally compile their Material theme.

Each strategy is evaluated as an independent hypothesis, not as an incremental evolution.

---

6. Evaluation criteria

Each experiment must be analyzed against the following axes:

1. Degree of real decoupling host ↔ microfrontend.
2. Design authority (explicit or implicit).
3. Autonomy of deployment and versioning.
4. Technical and cognitive complexity.
5. Organizational scalability.
6. Compatibility with future Angular and Angular Material releases.
7. Explicit technical risks.
8. Implicit medium- and long-term risks.

Failure to analyze an experiment in any of these points invalidates the experiment.

---

7. Repository structure

The repository structure is designed to control variables, not to simulate production:

/apps
  /shell
  /mfe-a
  /mfe-b

/libs
  /shared
    /design-tokens

/docs
  README.md
  experiments.md
  adr.md

Key notes:

• libs/shared/design-tokens is a shared design tokens library.
• Microfrontends do not share code among themselves.
• The monorepo is a methodological artifact, not a production architecture recommendation.

---

8. How to read this PoC

• Code exists to confirm or refute hypotheses, not to showcase UI best practices.
• The document has priority over the implementation.
• If the code contradicts the conceptual analysis, the code wins.

---

9. Expected outcome

By the end of this PoC it should be possible to:

• Make an informed architectural decision about theming.
• Explicitly justify the accepted degree of coupling.
• Document non-negotiable trade-offs.
• Detect warning signals that block premature adoption.

This PoC does not determine a universally “best” strategy, but rather in which contexts each approach is acceptable or risky.