Skip to content

Theming

Jump to bottom
simone.tiberti edited this page Apr 22, 2026 · 4 revisions

Temi e branding

La libreria usa Angular Material 3 come sistema di design e Tailwind CSS v4 per le utility. I due sistemi sono collegati tramite un bridge di variabili CSS.

Temi disponibili

Valore theme Colore primario Colore terziario
gpa #274c77 (blu) #cae9ff (celeste)
cobalt #1B44B5 (blu cobalto) #EBDD49 (giallo dorato)
forest #06975e (verde foresta) #aff452 (lime)

Il tema si seleziona nel file environment.json:

{ "theme": "gpa" }

StyleManagerService aggiunge la classe corrispondente su <body> (es. <body class="gpa">). Il cambio è reattivo: se environmentSig().theme cambia a runtime, il tema si aggiorna automaticamente tramite un effect().

Architettura dei temi

environment.json { theme: "cobalt" }
        ↓
StyleManagerService.setTheme("cobalt")
        ↓
<body class="cobalt">
        ↓
styles/_cobalt-theme.scss → --mat-sys-* tokens (Angular Material 3)
        ↓
styles/_color-bridge.scss → --color-*: var(--mat-sys-*) (Tailwind bridge)
        ↓
styles/components.css     → utility Tailwind (bg-surface, text-primary, …)

Variabili Tailwind semantiche

Grazie al color bridge, nelle classi Tailwind sono disponibili variabili semantiche che seguono il tema corrente:

Classe Tailwind Corrisponde a
bg-surface Sfondo neutro della card/pagina
bg-primary Colore primario del tema
text-on-primary Testo su sfondo primario
bg-surface-variant Variante sfondo (usata da core-topbar)
text-on-surface-variant Testo su sfondo variante
border-outline-variant Bordo neutro

Queste classi cambiano valore automaticamente al variare del tema, senza modificare il markup.

Nota WebKit/Safari

I mapping --color-*: var(--mat-sys-*) sono dichiarati dentro i selettori .gpa/.cobalt/.forest e non su :root. Questo è necessario perché WebKit risolve i var() nelle custom properties in modo eagerly durante l'ereditarietà: se le variabili fossero su :root, i --mat-sys-* non sarebbero ancora in scope al momento della risoluzione.

Logo applicazione (app-switcher)

Il logo viene mostrato nel pannello app-switcher se il campo logoUrl è presente in environment.json:

{
  "logoUrl": "https://cdn.example.com/logo-myapp.png"
}

Il valore può essere qualsiasi URL pubblicamente raggiungibile (HTTPS, CDN, path relativo all'origine). Se il campo è assente o undefined, il logo non viene mostrato.

Il componente renderizza:

<img class="app-logo-img" [src]="environment()!.logoUrl" alt="Logo" />

con stile circolare (border-radius: 50%, object-fit: cover, 96×96 px).

Aggiungere un tema personalizzato

  1. Creare styles/_mytema-colors.scss con le variabili colore MD3
  2. Creare styles/_mytema-theme.scss che include il color bridge: 
    @use 'mytema-colors' as mytema-theme;
@use 'color-bridge';

.mytema {
  @include mat.all-component-themes($mytema-theme);
  @include mat.system-level-colors($mytema-theme);
  @include mat.system-level-typography($mytema-theme);
  @include color-bridge.apply();
}
  3. Aggiungere mytema all'array knownThemes in style-manager.service.ts
  4. Aggiungere @forward 'mytema-theme' in themes.scss
  5. Eseguire npm run build:components-css
  6. Configurare logoUrl in environment.json se si vuole mostrare un logo

Tailwind in libreria vs app

File Scopo Chi lo genera
styles/components.css Pre-built Tailwind della libreria npm run build:components-css (maintainer)
src/tailwind-app.css Tailwind specifico dell'app (solo utilities) ng add schematic (una volta per app)
styles/mat-theme-bridge.css Token @theme {} per Tailwind Libreria (pubblicato come asset)

Le classi Tailwind usate nei template della libreria finiscono in components.css. Le classi usate nei template dell'app consumante finiscono in tailwind-app.css (compilato a build time dell'app, scansiona src/**).

Attenzione: classi Tailwind restituite dinamicamente da funzioni (es. rowBackground) non vengono rilevate dallo scanner. Usare valori CSS diretti in questi casi.

Vedi anche

Sviluppato e mantenuto da GPA — Gruppo Progetti Avanzati s.r.l.  ·  gpa@gpagroup.it  ·  +39 065913642  ·  P.IVA 05049391005  ·  ISO 9001 · ISO 27001

Sede legale: Via Ferdinando Galiani, 68 — 00191 Roma  |  Sedi operative: Piazzale Asia 21, Roma  ·  Via Badoero 67, Roma  ·  Viale Chiavellati 9, Foligno (PG)

npm  ·  GitHub  ·  Segnala un problema  ·  Licenza MIT

ng-core-ui Wiki

Home

Per iniziare

Layout

Componenti UI

Servizi e sistema

Temi e stili

Clone this wiki locally