Come installare e usare Card Mod per personalizzare Lovelace

Card Mod è una risorsa frontend custom per applicare CSS a card e componenti dell’interfaccia Lovelace. È software di presentazione: non modifica dispositivi, entità o automazioni e non aggiunge sicurezza. Le selettori interni possono cambiare con gli aggiornamenti di Home Assistant o della card, quindi usa stili semplici, backup e test dopo ogni aggiornamento.

Prerequisiti & Hardware Necessario

• Home Assistant aggiornato con HACS configurato.
• Una dashboard Lovelace funzionante e almeno una card da personalizzare.
• Accesso all’editor YAML della card o alla modalità di configurazione YAML della dashboard.
• Browser desktop per il debug e dispositivo mobile/tablet per il controllo responsive.
• Nessun prodotto d’acquisto: Card Mod è software frontend custom.

Procedura passo-passo

1. Fai un backup. Salva dashboard e configurazione Home Assistant prima di installare risorse custom. Se usi YAML, conserva il file della dashboard fuori dal solo editor web.
2. Installa Card Mod da HACS. Apri HACS → Frontend, cerca card-mod e verifica il repository thomasloven/lovelace-card-mod. Installa una release compatibile con la tua versione di Home Assistant.
3. Ricarica le risorse frontend. Esegui un hard refresh del browser e riapri l’app Companion. HACS gestisce la risorsa dashboard; non aggiungere manualmente un secondo URL card-mod.js se la risorsa è già registrata, altrimenti potresti ottenere caricamenti duplicati.
4. Apri l’editor della card. Modifica una dashboard, aggiungi o modifica una card e apri l’editor YAML. Card Mod si applica aggiungendo la chiave card_mod alla card, non creando un nuovo dispositivo.
5. Applica uno stile base.

   type: tile
   entity: light.soggiorno
   name: Soggiorno
   card_mod:
     style: |
       ha-card {
         border-radius: 20px;
         background: rgba(30, 35, 45, 0.88);
         box-shadow: 0 4px 14px rgba(0, 0, 0, 0.20);
       }

   Usa colori leggibili e non rimuovere indicatori di stato importanti solo per estetica.
6. Personalizza un’Entities Card.

   type: entities
   entities:
     - entity: sensor.temperatura_soggiorno
       name: Temperatura
   card_mod:
     style: |
       ha-card {
         padding: 8px;
       }
       .card-content {
         font-size: 16px;
       }

   Lo stile dipende dalla struttura DOM della card: se una proprietà non cambia, controlla la console browser e la documentazione della release invece di aggiungere selettori casuali.
7. Usa le variabili CSS quando disponibili. Preferisci variabili e proprietà del tema alle regole che penetrano molti shadow root. Esempio:

   card_mod:
     style: |
       ha-card {
         --ha-card-border-radius: 18px;
         --ha-card-border-width: 0;
         --ha-card-box-shadow: none;
       }

   Non tutte le variabili sono supportate da ogni card; verifica il risultato.
8. Applica uno stile condizionale semplice. Per cambiare aspetto in base allo stato, usa una card/template o un tema quando possibile. Un esempio Card Mod con stato di un sensore è:

   type: tile
   entity: binary_sensor.porta_ingresso
   card_mod:
     style: |
       ha-card {
         {% if is_state(config.entity, 'on') %}
           --tile-color: var(--error-color);
         {% else %}
           --tile-color: var(--success-color);
         {% endif %}
       }

   Se il template non viene valutato nella tua combinazione di card/versione, passa a una Conditional Card o a una Mushroom Template Card.
9. Gestisci lo stile di una singola riga. Non confondere lo stile della card con quello di un elemento interno. Per le Entities Card usa la struttura documentata da Card Mod e applica il CSS alla riga solo dopo aver verificato il DOM; un selettore interno può rompersi al prossimo aggiornamento.
10. Non usare Card Mod per la logica. Visibilità, azioni e condizioni devono restare nella configurazione Lovelace; automazioni e sicurezza devono restare nelle rispettive configurazioni. CSS non impedisce a un utente autorizzato di controllare un’entità.
11. Testa mobile e desktop. Verifica overflow, contrasto, focus da tastiera, touch target e modalità scura/chiara. Un’ombra o un padding eccessivo può rendere una card inutilizzabile su smartphone.
12. Aggiorna in modo controllato. Dopo aggiornamenti Home Assistant o Card Mod, controlla le card personalizzate una alla volta. Se la dashboard si rompe, rimuovi temporaneamente card_mod dalla card interessata o ripristina il backup.

Verifica del funzionamento

1. Controlla in HACS che Card Mod sia installato e senza errore.
2. Ricarica il frontend e verifica che la card con card_mod venga renderizzata.
3. Cambia lo stato dell’entità e verifica che testo, colore e controllo restino leggibili.
4. Apri la dashboard su desktop, smartphone e tablet.
5. Riavvia Home Assistant e ripeti il test per escludere un effetto temporaneo della cache.

Problemi comuni

FAQ essenziali

Card Mod modifica il dispositivo sottostante?

No. Modifica solo lo stile dell’interfaccia Lovelace. Stato, automazioni e permessi restano invariati.

Posso usare Card Mod con Mushroom Cards?

Sì, ma sono due risorse software distinte. Installa e aggiorna separatamente; se un selettore dipende dalla struttura interna di Mushroom, verifica la compatibilità dopo ogni aggiornamento.