@esfaenza/dpe-builder 20.3.12 → 20.3.13

package/styles/dpe-builder.css

@@ -51,6 +51,34 @@
   --dpe-text-muted: #6b7086;
   --dpe-text-subtle: #98a2b3;
 
+  /*
+   * Il testo attenuato fa **due mestieri**, e per questo sono due token. La divisione e' la stessa
+   * gia' applicata agli stati (`--dpe-*-text` qui sotto): non un gusto, una soglia.
+   *
+   *  - `--dpe-text-subtle` e' **decorazione**: testo secondario e ridondante, che dice una cosa gia'
+   *    leggibile altrove. Il nome tecnico sulla card del nodo lo ripete la testata della dialog,
+   *    l'etichetta di una porta la ripete il colore dell'arco, un separatore «·» non dice niente.
+   *    Sta a 2.58:1 su bianco e va bene cosi': attenuare e' il suo lavoro.
+   *  - `--dpe-text-subtle-strong` e' **informazione**: testo che l'utente deve leggere per agire e
+   *    che non trova da nessun'altra parte. Sta sopra 4.5:1 su **tutte** le superfici chiare,
+   *    compresa la piu' scura (`--dpe-surface-sunken`): da 4.6 a 5.2.
+   *
+   * Criterio per scegliere, uno solo: **se questo testo fosse illeggibile, l'utente perderebbe
+   * qualcosa che non trova altrove?** Si' -> `-strong`. No -> il token attenuato.
+   *
+   * Perche' non alzare il token unico: lo userebbero anche i trenta punti decorativi, e la card del
+   * nodo si appiattirebbe — nome tecnico, sottotitolo ed etichette delle porte tutti allo stesso
+   * peso del titolo. Perche' non usare `--dpe-text-muted` al loro posto: misura **4.29:1** su
+   * `--dpe-surface-sunken`, cioe' sotto il minimo proprio dove finiscono i messaggi di stato vuoto.
+   *
+   * Nota onesta sul valore: in tema chiaro non esiste un grigio **piu' chiaro** di
+   * `--dpe-text-muted` che regga 4.5:1 (il limite su bianco e' circa #767676, misurato in LV1), e
+   * lo stesso vale in scuro. Il token informativo cade quindi nella fascia di `--dpe-text-muted`,
+   * e la gerarchia fra i due la fanno corpo e peso, non il colore. Restano token distinti perche'
+   * governano usi diversi con soglie diverse e l'ospite deve poterli ritingere separatamente.
+   */
+  --dpe-text-subtle-strong: #666c80;
+
   /* Accento e stati */
   --dpe-accent: #2f7d8f;
   --dpe-accent-strong: #226270;
@@ -60,13 +88,46 @@
   --dpe-success: #22a06b;
   --dpe-info: #3b6fd4;
 
+  /*
+   * Gli stessi stati **quando colorano lettere**, e sono token separati per un fatto misurato, non
+   * per gusto.
+   *
+   * Un colore di stato fa due mestieri con due soglie diverse: bordo, pastiglia e banner sono
+   * elementi di interfaccia (WCAG chiede 3:1), un rilievo scritto e' testo (4.5:1). Su superficie
+   * chiara i valori qui sopra reggono il primo mestiere e non il secondo: `--dpe-warning` misura
+   * **3.64:1** su `--dpe-surface` e `--dpe-success` **3.33:1**. Un rilievo che l'utente fatica a
+   * leggere e' un rilievo che non arriva, e l'avviso e' il colore con cui arriva
+   * `DPE_EXPR_TYPE_WIDENED`.
+   *
+   * Perche' separare invece di alzare il token unico: alzarlo avrebbe imbrunito insieme al testo
+   * anche i bordi dei nodi, le pastiglie e il fondo tinto del banner — cioe' il linguaggio visivo
+   * dell'editor — e avrebbe chiesto di **argomentare** che nessuno di quegli usi peggiora. Con due
+   * token quegli usi restano identici al bit, e cambia solo il colore delle lettere.
+   *
+   * I valori chiari stanno sopra 4.5:1 su **tutte** le superfici chiare, compresa la piu' scura
+   * (`--dpe-surface-sunken`) e i fondi tinti del catalogo: da 5.0 a 5.9 su `--dpe-surface`.
+   *
+   * Regola d'uso, una sola: **se colora lettere si usa la variante `-text`; se colora un bordo o un
+   * fondo si usa il token di stato.**
+   */
+  --dpe-error-text: #c81e1e;
+  --dpe-warning-text: #8f6115;
+  --dpe-success-text: #177a4f;
+  --dpe-info-text: #3161bd;
+
   /*
    * Nodo valido ma **non compilabile** (`DPE_NODE_NOT_COMPILABLE`, I10): non e' un errore
    * dell'utente ed e' l'unica distinzione che deve leggersi a colpo d'occhio nel pannello
    * delle diagnostiche. Colore proprio, ne' rosso ne' giallo, per non farlo confondere con
    * qualcosa da correggere.
+   *
+   * Vale la stessa divisione di mestiere: il viola pieno disegna bordo e tratteggio, la variante
+   * `-text` scrive la pastiglia e l'etichetta. Il pieno su `--dpe-surface-alt` misura 4.53:1 e sulla
+   * riga tinta del pannello 4.47:1 — sopra e sotto il minimo a seconda di dove finisce, che e'
+   * esattamente il tipo di fortuna su cui non si costruisce.
    */
   --dpe-not-compilable: #7c5cd6;
+  --dpe-not-compilable-text: #6f4fc4;
 
   /*
    * Velo della dialog modale (`::backdrop`). E' un token perche' la regola della casa e' «colori
@@ -94,8 +155,23 @@
   --dpe-cat-uncompilable: #7c5cd6;
   --dpe-cat-uncompilable-soft: #ebe6fa;
 
-  /* Colori degli archi per tipo di ingresso */
-  --dpe-edge-source: #98a2b3;
+  /*
+   * Colori degli archi per tipo di ingresso.
+   *
+   * Un arco del DAG e' un **oggetto grafico necessario a capire il contenuto** (WCAG 1.4.11, 3:1):
+   * senza archi non c'e' grafo, e la topologia non e' scritta da nessun'altra parte
+   * dell'interfaccia. L'arco predefinito misurava **2.36:1** sul fondo del canvas in tema chiaro,
+   * cioe' sotto il minimo; e' lo stesso grigio-azzurro, trenta punti piu' scuro su ogni canale, e
+   * ora sta a **3.46:1**. Gli altri quattro erano gia' sopra (3.05-4.43) e non si toccano.
+   *
+   * In tema scuro il valore non cambia: li' l'arco predefinito misura gia' 4.18:1 sul canvas. La
+   * separazione esiste dove serve e non dove non serve.
+   *
+   * Nota: questa famiglia **coincide per valore** con i token di stato in piu' punti, ma e' una
+   * famiglia sua. Cambiare un colore di stato non cambia un arco, e viceversa — le due cose si
+   * assomigliano, non si condividono.
+   */
+  --dpe-edge-source: #7a8496;
   --dpe-edge-primary: #2f7d8f;
   --dpe-edge-secondary: #8b5cf6;
   --dpe-edge-append: #22a06b;
@@ -161,6 +237,12 @@
   --dpe-text: #e8eaf0;
   --dpe-text-muted: #8b90a0;
   --dpe-text-subtle: #6b7684;
+  /*
+   * Qui la separazione **serve in entrambi i temi**, al contrario di quella degli stati: su fondo
+   * scuro `--dpe-text-subtle` misura 3.81:1 sulla superficie e 3.21:1 su quella incassata, cioe'
+   * sotto il minimo ovunque. Il valore informativo sta fra 4.9 e 5.8 sulle tre superfici scure.
+   */
+  --dpe-text-subtle-strong: #8d94a6;
   --dpe-accent: #5fb3c4;
   --dpe-accent-strong: #7ac6d6;
   --dpe-accent-contrast: #0c0e14;
@@ -169,6 +251,17 @@
   --dpe-success: #63b57f;
   --dpe-info: #7ea6f0;
   --dpe-not-compilable: #a78bfa;
+  /*
+   * In tema scuro la separazione fra colore di stato e colore del testo **non serve**: misurati su
+   * tutte le superfici scure, fondi tinti compresi, i cinque stanno fra 4.8:1 e 7.6:1. Le varianti
+   * puntano quindi al token di stato invece di ripeterne il valore, cosi' un ospite che ritinge uno
+   * stato in tema scuro si porta dietro anche il testo senza doverlo sapere.
+   */
+  --dpe-error-text: var(--dpe-error);
+  --dpe-warning-text: var(--dpe-warning);
+  --dpe-success-text: var(--dpe-success);
+  --dpe-info-text: var(--dpe-info);
+  --dpe-not-compilable-text: var(--dpe-not-compilable);
   /* Su fondo scuro il velo deve pesare piu': la superficie sotto e' gia' scura. */
   --dpe-scrim: rgba(4, 5, 8, 0.66);
   /*
@@ -296,6 +389,11 @@ dpe-builder {
 /*
  * Indicatore di stato sporco. Colore **e** simbolo: il colore da solo non basta a distinguere
  * due stati per chi non lo percepisce, e questo e' l'indicatore su cui si decide se salvare.
+ *
+ * **Decorativo nello stato a riposo**, informativo in quello acceso — che infatti prende
+ * `--dpe-warning-text` qui sotto. «○ nessuna modifica» e' la meta' ridondante della coppia:
+ * l'assenza di «● modificata» dice la stessa cosa, e «Salva» e' comunque spento con il motivo nel
+ * titolo. Attenuarlo e' voluto, perche' lo stato a riposo non deve chiamare l'attenzione.
  */
 .dpe-shell__dirty {
   flex: 0 0 auto;
@@ -305,7 +403,7 @@ dpe-builder {
 }
 
 .dpe-shell__dirty--on {
-  color: var(--dpe-warning, #b7791f);
+  color: var(--dpe-warning-text, #8f6115);
   font-weight: 600;
 }
 
@@ -352,7 +450,7 @@ dpe-builder {
   padding: 2px 8px;
   border: 1px solid var(--dpe-success, #22a06b);
   border-radius: 999px;
-  color: var(--dpe-success, #22a06b);
+  color: var(--dpe-success-text, #177a4f);
   font-size: 11px;
   font-weight: 600;
   white-space: nowrap;
@@ -398,19 +496,24 @@ dpe-builder {
   font-size: 11px;
 }
 
+/*
+ * Pastiglie di stato: il bordo porta il colore di stato, le lettere la sua variante `-text`. E' la
+ * divisione dichiarata in testa al foglio, e qui si vede il perche': il bordo e il testo stanno
+ * sullo stesso fondo ma hanno due soglie diverse.
+ */
 .dpe-shell__pill--ok {
   border-color: var(--dpe-success, #22a06b);
-  color: var(--dpe-success, #22a06b);
+  color: var(--dpe-success-text, #177a4f);
 }
 
 .dpe-shell__pill--error {
   border-color: var(--dpe-error, #dc2626);
-  color: var(--dpe-error, #dc2626);
+  color: var(--dpe-error-text, #c81e1e);
 }
 
 .dpe-shell__pill--busy {
   border-color: var(--dpe-info, #3b6fd4);
-  color: var(--dpe-info, #3b6fd4);
+  color: var(--dpe-info-text, #3161bd);
 }
 
 /* Banner di riga intera: disallineamento del dialetto, salvataggio fallito. Non e' un tooltip. */
@@ -729,6 +832,9 @@ dpe-canvas .dpe-flow .dpe-port {
   min-width: 0;
 }
 
+/* **Decorativo**: quale porta sia quale lo dice gia' il **colore dell'arco** che ci arriva (vedi la
+   sezione «archi»), e la dialog del nodo nomina sorgente primaria e secondaria per esteso. A 9px
+   l'etichetta e' un promemoria sulla card, non la fonte del fatto. */
 dpe-canvas .dpe-flow .dpe-port__label {
   max-width: 96px;
   overflow: hidden;
@@ -795,7 +901,7 @@ dpe-canvas .dpe-flow .dpe-node .dpe-connector--out {
   border: 2px solid var(--dpe-surface, #fff);
   border-radius: 50%;
   background: var(--dpe-border-strong, #cfd4de);
-  /* Sporge oltre il bordo inferiore: e' lì che gli archi partono. */
+  /* Sporge oltre il bordo inferiore: e' li' che gli archi partono. */
   margin-bottom: -6px;
   /*
    * `--ff-connector-connected-color` e' il token con cui la libreria colora un connettore
@@ -858,6 +964,7 @@ dpe-canvas .dpe-flow .dpe-node__sub {
   white-space: nowrap;
 }
 
+/* **Decorativo**: e' un separatore «·», non porta nessun contenuto. */
 dpe-canvas .dpe-flow .dpe-node__dot {
   padding: 0 4px;
   color: var(--dpe-text-subtle, #98a2b3);
@@ -886,7 +993,7 @@ dpe-canvas .dpe-flow .dpe-node__btn:hover {
 
 dpe-canvas .dpe-flow .dpe-node__btn--remove:hover {
   border-color: var(--dpe-error, #dc2626);
-  color: var(--dpe-error, #dc2626);
+  color: var(--dpe-error-text, #c81e1e);
 }
 
 dpe-canvas .dpe-flow .dpe-node__meta {
@@ -898,6 +1005,10 @@ dpe-canvas .dpe-flow .dpe-node__meta {
   min-height: 18px;
 }
 
+/* **Decorativo**, ed e' il posto che il token attenuato esiste per servire: il nome tecnico lo
+   ripetono la testata della dialog (`.dpe-dialog__name`) e il pannello dello schema
+   (`.dpe-schema__name`), entrambi leggibili. Alzarlo qui appiattirebbe la card, che e' il danno
+   che la divisione dei due token evita. */
 dpe-canvas .dpe-flow .dpe-node__name {
   overflow: hidden;
   max-width: 130px;
@@ -918,24 +1029,29 @@ dpe-canvas .dpe-flow .dpe-badge {
   white-space: nowrap;
 }
 
+/*
+ * Le pastiglie sulla card: bordo con il colore di stato, lettere con la variante `-text`. Qui il
+ * fondo e' `--dpe-surface-alt`, dove il viola pieno scendeva a 4.53:1 e l'azzurro a 4.48:1 — una
+ * pastiglia da 10px e' il posto peggiore dove restare al filo del minimo.
+ */
 dpe-canvas .dpe-flow .dpe-badge--error {
   border-color: var(--dpe-error, #dc2626);
-  color: var(--dpe-error, #dc2626);
+  color: var(--dpe-error-text, #c81e1e);
 }
 
 dpe-canvas .dpe-flow .dpe-badge--warning {
   border-color: var(--dpe-warning, #b7791f);
-  color: var(--dpe-warning, #b7791f);
+  color: var(--dpe-warning-text, #8f6115);
 }
 
 dpe-canvas .dpe-flow .dpe-badge--info {
   border-color: var(--dpe-info, #3b6fd4);
-  color: var(--dpe-info, #3b6fd4);
+  color: var(--dpe-info-text, #3161bd);
 }
 
 dpe-canvas .dpe-flow .dpe-badge--not-compilable {
   border-color: var(--dpe-not-compilable, #7c5cd6);
-  color: var(--dpe-not-compilable, #7c5cd6);
+  color: var(--dpe-not-compilable-text, #6f4fc4);
 }
 
 /* =================================================================== archi */
@@ -952,8 +1068,8 @@ dpe-canvas .dpe-flow .dpe-badge--not-compilable {
  */
 
 .dpe-edge {
-  --ff-connection-color: var(--dpe-edge-source, #98a2b3);
-  --ff-marker-color: var(--dpe-edge-source, #98a2b3);
+  --ff-connection-color: var(--dpe-edge-source, #7a8496);
+  --ff-marker-color: var(--dpe-edge-source, #7a8496);
   --ff-connection-selected-color: var(--dpe-accent, #2f7d8f);
 }
 
@@ -1029,7 +1145,10 @@ dpe-node-palette input[type='search'] {
   font-size: 12px;
 }
 
-/* Intestazione di gruppo: piu' piccola del titolo della palette, e non cliccabile. */
+/* Intestazione di gruppo: piu' piccola del titolo della palette, e non cliccabile.
+   **Decorativa**: «Sorgenti / Trasformazioni / Scritture» e' il riassunto delle voci che contiene,
+   e ogni voce porta la propria etichetta leggibile piu' l'icona colorata per famiglia. Illeggibile
+   l'intestazione, non si perde nessuna voce. */
 dpe-node-palette .dpe-palette__group {
   margin: 8px 2px 2px;
   color: var(--dpe-text-subtle, #98a2b3);
@@ -1136,7 +1255,7 @@ dpe-node-palette .dpe-palette__flag {
   padding: 0 5px;
   border: 1px solid var(--dpe-not-compilable, #7c5cd6);
   border-radius: 999px;
-  color: var(--dpe-not-compilable, #7c5cd6);
+  color: var(--dpe-not-compilable-text, #6f4fc4);
   font-size: 9px;
   font-weight: 700;
   letter-spacing: 0.04em;
@@ -1187,24 +1306,41 @@ dpe-node-icon {
   font-weight: 600;
 }
 
+/*
+ * Il suggerimento sotto un campo: testo attenuato, **non** testo che si puo' non leggere. Con
+ * `--dpe-text-subtle` misurava 2.58:1 in tema chiaro e 3.81:1 in scuro — sotto il minimo in
+ * entrambi — e ci passano le colonne disponibili e il conteggio del catalogo delle formule, cioe'
+ * cio' che si legge per capire cosa si puo' scrivere nel campo sopra.
+ *
+ * Colore proprio e non token alzato: sulle nostre superfici chiare **non esiste** un terzo grigio
+ * piu' chiaro di `--dpe-text-muted` che stia sopra 4.5:1 (su bianco il limite e' circa #767676, e
+ * `--dpe-text-muted` e' gia' li'). Alzare `--dpe-text-subtle` lo renderebbe un doppione di
+ * `--dpe-text-muted` e appiattirebbe dove serve davvero attenuare — il nome tecnico sulla card del
+ * nodo. La gerarchia qui la fanno corpo e peso: etichetta 12px/600, suggerimento 11px/400.
+ */
 .dpe-field__hint {
-  color: var(--dpe-text-subtle, #98a2b3);
+  color: var(--dpe-text-muted, #6b7086);
   font-size: 11px;
 }
 
-/* Un rilievo del backend sul campo: si mostra sotto, non in un tooltip. */
+/*
+ * Un rilievo del backend sul campo: si mostra sotto, non in un tooltip — e con le varianti `-text`
+ * degli stati, perche' qui il colore e' **lettere**. L'avviso con `--dpe-warning` misurava 3.64:1
+ * sul fondo della dialog: e' il colore con cui arriva `DPE_EXPR_TYPE_WIDENED`, la diagnostica piu'
+ * frequente dell'editor di formule.
+ */
 .dpe-field__issue {
-  color: var(--dpe-error, #dc2626);
+  color: var(--dpe-error-text, #c81e1e);
   font-size: 11px;
   line-height: 1.45;
 }
 
 .dpe-field__issue--warning {
-  color: var(--dpe-warning, #b7791f);
+  color: var(--dpe-warning-text, #8f6115);
 }
 
 .dpe-field__issue--info {
-  color: var(--dpe-info, #3b6fd4);
+  color: var(--dpe-info-text, #3161bd);
 }
 
 .dpe-form input[type='text'],
@@ -1230,7 +1366,18 @@ dpe-node-icon {
   outline-offset: 1px;
 }
 
-.dpe-form input[aria-invalid='true'] {
+/*
+ * Il bordo del rilievo vale per **tutti** i controlli, non per i soli `input`.
+ *
+ * Con la regola sul solo `input` l'utente impara «bordo rosso = qualcosa non va» e poi la tendina
+ * che il backend segnala non ce l'ha: la diagnostica e' sotto il campo, ma il campo sembra sano.
+ * Che questo cambi l'aspetto di ogni tendina diagnosticata non e' un effetto collaterale, e' la
+ * correzione — dovevano gia' averlo tutte. Resta legato ad `aria-invalid`, che e' scritto solo
+ * dove una diagnostica del backend nomina quel campo: nessuna regola locale decide il colore.
+ */
+.dpe-form input[aria-invalid='true'],
+.dpe-form select[aria-invalid='true'],
+.dpe-form textarea[aria-invalid='true'] {
   border-color: var(--dpe-error, #dc2626);
 }
 
@@ -1318,7 +1465,7 @@ dpe-node-icon {
 
 .dpe-btn--danger:hover:not(:disabled) {
   border-color: var(--dpe-error, #dc2626);
-  color: var(--dpe-error, #dc2626);
+  color: var(--dpe-error-text, #c81e1e);
 }
 
 .dpe-btn--icon {
@@ -1366,16 +1513,177 @@ dpe-node-icon {
   border-left-color: var(--dpe-error, #dc2626);
 }
 
+/*
+ * **Informativo.** Un messaggio di stato vuoto e' l'**unico** contenuto della sua area: se non si
+ * legge, al suo posto non c'e' un testo piu' debole, c'e' uno spazio bianco — e uno spazio bianco
+ * non distingue «non c'e' niente» da «non e' ancora arrivato». Diversi di questi messaggi portano
+ * anche la conseguenza («Nessun campo: la sorgente non produce colonne»), che non e' scritta
+ * altrove.
+ */
 .dpe-empty {
-  color: var(--dpe-text-subtle, #98a2b3);
+  color: var(--dpe-text-subtle-strong, #666c80);
   font-size: 12px;
   font-style: italic;
 }
 
-/* Dialetto citato nell'editor di espressioni: e' testo tecnico, quindi monospaziato. */
-.dpe-expr__dialect {
+/*
+ * Il **linguaggio di formule** nominato nell'etichetta del campo (ADR 0031/0036). Sostituisce
+ * `.dpe-expr__dialect`, che nominava il dialetto: da quando le espressioni sono formule il
+ * dialetto non c'entra piu' con cio' che si scrive li'.
+ *
+ * Non e' un avviso e non ne prende i colori: e' un'etichetta di contesto, quindi tono attenuato.
+ * L'avviso rosso che stava sotto questo campo diceva «cio' che scrivi verra' eseguito», ed e'
+ * sparito perche' non e' piu' vero.
+ */
+.dpe-expr__language {
+  margin-left: 6px;
+  padding: 1px 6px;
+  /* Scala dei raggi **unica**: niente pillola inventata qui, il gradino piu' piccolo e' questo. */
+  border-radius: var(--dpe-radius-xs, 6px);
+  background: var(--dpe-surface-alt, #f7f8fa);
+  border: 1px solid var(--dpe-border, #e2e5eb);
+  color: var(--dpe-text-muted, #6b7086);
   font-family: var(--dpe-font-mono, monospace);
+  font-size: 10px;
   font-weight: 600;
+  text-transform: none;
+  letter-spacing: 0;
+}
+
+/*
+ * La **forma** pretesa dal campo (`DpeFormulaCatalogResult.requiredForm`), accanto al linguaggio.
+ *
+ * Deve leggersi come una cosa **diversa** dalla pastiglia del linguaggio, che le sta a fianco: due
+ * pastiglie identiche una accanto all'altra si leggono come un'unica etichetta spezzata. Stessa
+ * scala di raggi e stesso corpo — la morbidezza e' unica in tutta la libreria — ma tinta d'accento
+ * invece che di superficie.
+ *
+ * Il testo prende `--dpe-accent-strong` e non `--dpe-accent`: qui il colore e' **lettere**, ed e' la
+ * stessa divisione di mestiere che LV1 ha introdotto per gli stati. Non si apre un token nuovo
+ * perche' quello giusto esiste gia': in tema chiaro e' la versione scurita dell'accento (6.9:1 su
+ * bianco, ~6.3:1 sul fondo tinto al 10%), in tema scuro la versione schiarita — cioe' in entrambi
+ * i temi punta dalla parte leggibile senza che questa regola debba saperlo.
+ */
+.dpe-expr__form {
+  margin-left: 6px;
+  padding: 1px 6px;
+  border-radius: var(--dpe-radius-xs, 6px);
+  background: color-mix(in srgb, var(--dpe-accent, #2f7d8f) 10%, var(--dpe-surface, #fff));
+  border: 1px solid color-mix(in srgb, var(--dpe-accent, #2f7d8f) 35%, var(--dpe-surface, #fff));
+  color: var(--dpe-accent-strong, #226270);
+  font-size: 10px;
+  font-weight: 600;
+  text-transform: none;
+  letter-spacing: 0;
+}
+
+/*
+ * La stessa pastiglia **mentre una validazione e' in volo** (ADR 0042). La forma arriva da
+ * `validate`, quindi fra il gesto che la cambia e la risposta c'e' una finestra — misurata a
+ * 2,58 s dentro la pagina — in cui questa pastiglia mostra la forma **precedente** con la faccia
+ * di un fatto. Qui non si afferma piu'.
+ *
+ * Come si ottiene «non asserito» senza togliere leggibilita': si **sottrae la tinta d'accento** —
+ * che e' cio' che la faceva leggere come corrente — e si mette il bordo **tratteggiato**, che e'
+ * l'idioma della cosa provvisoria. Non si abbassa l'opacita': un'etichetta che spiega un campo
+ * bloccato deve restare leggibile per intero, e l'opacita' avrebbe portato il testo sotto la
+ * soglia del contrasto proprio dove serve.
+ *
+ * Nessun token nuovo, e non per parsimonia: la coppia giusta esiste gia' ed e' quella che LV2 ha
+ * fissato per il **testo attenuato che porta informazione** — `--dpe-text-subtle-strong` su
+ * `--dpe-surface-alt`, misurata 4.91:1 in chiaro e 5.37:1 in scuro. Un token nuovo per questo
+ * stato sarebbe una seconda dichiarazione della stessa decisione.
+ *
+ * La specificita' e' la stessa della regola qui sopra (0,1,0 contro 0,1,0) e questa viene **dopo**:
+ * e' l'unico caso del foglio in cui l'ordine e' il presidio giusto, perche' i due selettori sono
+ * lo stesso stato in due momenti — il modificatore non contende con una regola generale, la
+ * specializza.
+ */
+.dpe-expr__form--updating {
+  background: var(--dpe-surface-alt, #f7f8fa);
+  border: 1px dashed var(--dpe-border-strong, #cfd4de);
+  color: var(--dpe-text-subtle-strong, #666c80);
+}
+
+/* Il marcatore dentro la pastiglia: non e' un'altra pastiglia — due accostate si leggono come
+   un'unica etichetta spezzata — quindi non ha fondo ne' bordo, solo il corsivo del provvisorio. */
+.dpe-expr__form-note {
+  font-style: italic;
+  font-weight: 500;
+}
+
+/*
+ * Il campo formula **bloccato**: la forma che questo nodo pretende non e' fra quelle che il
+ * compilatore registrato sa produrre (`DpeEnvironment.supportedForms` incrociato con
+ * `requiredForm`).
+ *
+ * Il selettore dichiara la specificita' che gli serve — `.dpe-form .dpe-expr__input--blocked` e'
+ * (0,2,0) contro (0,1,1) di `.dpe-form textarea` — invece di sperare nell'ordine: una classe sola
+ * perderebbe fondo e colore contro la regola generale del controllo, che e' il modo tipico in cui
+ * uno stato «si vede in ispezione e non a schermo».
+ *
+ * Il colore e' `--dpe-text-subtle-strong` e non `--dpe-text-muted`: qui dentro c'e' una formula
+ * **scritta dall'utente**, cioe' testo che deve restare leggibile per essere portato altrove, e
+ * per la divisione di LV2 il testo attenuato che porta informazione prende il token informativo.
+ * Misurato: 4.91:1 in chiaro e 5.37:1 in scuro sulla superficie attenuata, contro 4.61:1 e 5.12:1
+ * dell'altro — ed e' in elenco nel test di contrasto, perche' il colore non si giudica a occhio.
+ *
+ * Il controllo e' `readonly`, non `disabled`: `disabled` lo toglierebbe dalla tabulazione e ne
+ * renderebbe il testo non selezionabile, cioe' toglierebbe la formula proprio a chi deve
+ * riscriverla altrove. Per questo il fondo lo dichiara questa regola e non `:disabled`.
+ */
+.dpe-form .dpe-expr__input--blocked {
+  background: var(--dpe-surface-alt, #f7f8fa);
+  color: var(--dpe-text-subtle-strong, #666c80);
+  cursor: not-allowed;
+}
+
+/* Il motivo, attaccato al campo che spiega: e' l'unica cosa che l'utente puo' leggere per capire
+   perche' non si scrive. Stessa scala di spaziatura dei rilievi qui sopra. */
+.dpe-expr__blocked {
+  margin-top: 4px;
+}
+
+/*
+ * La riga in testa del blocco «il catalogo non e' stato prodotto»: e' l'unica che l'utente deve
+ * leggere per forza, quindi prende il colore pieno del testo invece dell'attenuato del blocco.
+ */
+.dpe-expr__catalog-lead {
+  margin: 0;
+  color: var(--dpe-text, #1a1c23);
+  font-weight: 600;
+}
+
+/*
+ * Le strutturali che spiegano la causa, chiuse per difetto. Il sacco riguarda **tutta** la
+ * definizione e puo' contenere voci che con questo nodo non c'entrano: non si filtrano per
+ * pertinenza — l'errore che spiega lo schema puo' stare a piu' salti di distanza — quindi si
+ * dichiarano come dettaglio. Aperte per difetto sarebbero il muro indistinguibile che la riga in
+ * testa esiste per evitare.
+ */
+.dpe-expr__catalog-details {
+  margin-top: 4px;
+  font-size: 11px;
+}
+
+.dpe-expr__catalog-details summary {
+  cursor: pointer;
+  color: var(--dpe-text-muted, #6b7086);
+}
+
+/*
+ * Cosa il linguaggio offre in questo nodo: un conteggio dentro il suggerimento, non un elenco.
+ *
+ * Colore **proprio** e non quello ereditato dal suggerimento: `--dpe-text-subtle` sul fondo del
+ * pannello stava a 2.6:1 in tema chiaro, sotto il minimo WCAG, e questo e' testo che si legge per
+ * capire se il catalogo e' arrivato. Il rilievo su `.dpe-field__hint` accanto, riportato allora
+ * all'architetto, e' stato chiuso dopo: adesso il suggerimento porta lo stesso token e i due non
+ * si contraddicono piu'. La dichiarazione resta esplicita invece di ereditare, cosi' il conteggio
+ * si legge anche se un giorno finisce fuori da un suggerimento.
+ */
+.dpe-expr__catalog {
+  color: var(--dpe-text-muted, #6b7086);
+  font-style: italic;
 }
 
 /* ================================================= ispettore e fatti del nodo */
@@ -1652,7 +1960,7 @@ dpe-node-facts .dpe-badge {
 
 dpe-node-facts .dpe-badge--not-compilable {
   border-color: var(--dpe-not-compilable, #7c5cd6);
-  color: var(--dpe-not-compilable, #7c5cd6);
+  color: var(--dpe-not-compilable-text, #6f4fc4);
 }
 
 /*
@@ -1769,7 +2077,7 @@ dpe-node-facts .dpe-badge--not-compilable {
 
 .dpe-dialog__btn--danger:hover {
   border-color: var(--dpe-error, #dc2626);
-  color: var(--dpe-error, #dc2626);
+  color: var(--dpe-error-text, #c81e1e);
 }
 
 /* ============================================================ diagnostiche */
@@ -1850,8 +2158,14 @@ dpe-diagnostics-panel {
   flex: 1 1 auto;
 }
 
+/*
+ * **Informativo**, ed e' il caso che decide la regola. E' l'unica resa testuale del percorso
+ * diagnostico, cioe' esattamente l'aiuto per cui questo pannello esiste: un pannello in cui il
+ * «dove» e' il pezzo meno leggibile e' un difetto di scopo, non di stile. Con il token decorativo
+ * misurava 2.39:1 sulla riga «non compilabile», che e' anche il fondo peggiore delle tre.
+ */
 .dpe-diag__where {
-  color: var(--dpe-text-subtle, #98a2b3);
+  color: var(--dpe-text-subtle-strong, #666c80);
   font-size: 10px;
 }
 
@@ -1864,17 +2178,25 @@ dpe-diagnostics-panel {
   text-transform: uppercase;
 }
 
+/*
+ * Le due etichette della riga: 9px maiuscoletto, con il bordo che prende il colore dal testo
+ * (`currentcolor`). Quindi qui la variante `-text` colora **entrambi**, ed e' voluto: a 9px il
+ * testo e' il vincolo piu' stretto dei due, e la riga «non compilabile» ha pure un fondo tinto che
+ * portava il viola pieno a 4.47:1.
+ */
 .dpe-diag__tag--not-compilable {
-  color: var(--dpe-not-compilable, #7c5cd6);
+  color: var(--dpe-not-compilable-text, #6f4fc4);
 }
 
 .dpe-diag__tag--dialect {
-  color: var(--dpe-info, #3b6fd4);
+  color: var(--dpe-info-text, #3161bd);
 }
 
+/* **Informativo**: e' la riga che distingue «nessun rilievo» da «non ancora validata», e sono due
+   stati che portano a due decisioni opposte. Vedi `.dpe-empty`. */
 .dpe-diag__empty {
   padding: 10px;
-  color: var(--dpe-text-subtle, #98a2b3);
+  color: var(--dpe-text-subtle-strong, #666c80);
   font-size: 11px;
   font-style: italic;
 }
@@ -1910,6 +2232,8 @@ dpe-schema-panel {
   color: var(--dpe-accent, #2f7d8f);
 }
 
+/* **Decorativa**: la riga e' identificata da `.dpe-schema__name`, e la categoria del nodo si legge
+   sulla card del canvas e nella testata della dialog. Qui e' un promemoria, non la fonte. */
 .dpe-schema__category {
   color: var(--dpe-text-subtle, #98a2b3);
   font-size: 10px;
@@ -1951,7 +2275,7 @@ dpe-schema-panel {
 
 .dpe-col--dropped {
   border-color: var(--dpe-warning, #b7791f);
-  color: var(--dpe-warning, #b7791f);
+  color: var(--dpe-warning-text, #8f6115);
   text-decoration: line-through;
 }
 
@@ -1959,13 +2283,15 @@ dpe-schema-panel {
   padding: 0 6px;
   border: 1px solid var(--dpe-not-compilable, #7c5cd6);
   border-radius: 999px;
-  color: var(--dpe-not-compilable, #7c5cd6);
+  color: var(--dpe-not-compilable-text, #6f4fc4);
   font-size: 9px;
   text-transform: uppercase;
 }
 
+/* **Informativo**: «in attesa della propagazione» e «nessuno schema propagato» sono l'unico modo di
+   sapere se lo schema sta arrivando o non arrivera'. Vedi `.dpe-empty`. */
 .dpe-schema__empty {
-  color: var(--dpe-text-subtle, #98a2b3);
+  color: var(--dpe-text-subtle-strong, #666c80);
   font-size: 11px;
   font-style: italic;
 }
@@ -2047,8 +2373,11 @@ dpe-sql-preview td {
   text-align: left;
 }
 
+/* **Informativo**, e qui il testo porta **I10**: «nessuna istruzione prodotta» e «nessuna anteprima
+   richiesta» sono situazioni diverse, e il pannello dell'SQL non ha altro da mostrare quando una
+   delle due vale. Vedi `.dpe-empty`. */
 .dpe-sql__empty {
-  color: var(--dpe-text-subtle, #98a2b3);
+  color: var(--dpe-text-subtle-strong, #666c80);
   font-size: 11px;
   font-style: italic;
 }
@@ -2137,6 +2466,9 @@ dpe-catalog {
   color: var(--dpe-accent-strong);
 }
 
+/* **Decorativo** per la ragione piu' forte delle altre: un controllo disattivato e' escluso dal
+   requisito di contrasto (WCAG 1.4.3), e attenuarlo e' *come* si dice che e' disattivato. Il motivo
+   per cui lo e' sta nel `title` e in pagina, non nelle lettere del bottone. */
 .dpe-cat__btn:disabled {
   color: var(--dpe-text-subtle);
   cursor: not-allowed;
@@ -2151,7 +2483,7 @@ dpe-catalog {
 
 .dpe-cat__btn--danger:not(:disabled) {
   border-color: var(--dpe-error);
-  color: var(--dpe-error);
+  color: var(--dpe-error-text);
 }
 
 .dpe-cat__btn:focus-visible,
@@ -2170,7 +2502,12 @@ dpe-catalog {
   padding: 7px 14px;
   border-bottom: 1px solid var(--dpe-border);
   background: color-mix(in srgb, var(--dpe-error) 10%, var(--dpe-surface));
-  color: var(--dpe-error);
+  /*
+   * Fondo tinto del proprio stesso colore: il rosso pieno ci misurava 4.13:1, meno che sul bianco.
+   * Un banner d'errore e' il posto in cui il testo conta di piu' e quello in cui il fondo aiuta di
+   * meno.
+   */
+  color: var(--dpe-error-text);
   font-size: 11px;
 }
 
@@ -2246,6 +2583,7 @@ dpe-catalog {
   font-size: 10px;
 }
 
+/* **Decorativo**: separatore «·» fra i fatti del sommario, come sulla card del nodo. */
 .dpe-cat__dot {
   color: var(--dpe-text-subtle);
 }
@@ -2262,7 +2600,7 @@ dpe-catalog {
 .dpe-cat__flag--errors {
   border-color: var(--dpe-error);
   background: color-mix(in srgb, var(--dpe-error) 8%, transparent);
-  color: var(--dpe-error);
+  color: var(--dpe-error-text);
 }
 
 .dpe-cat__actions,
@@ -2320,6 +2658,7 @@ dpe-catalog {
   font-size: 12px;
 }
 
+/* **Decorativo**: come il bottone disattivato qui sopra, e' un controllo inattivo. */
 .dpe-cat__input:disabled {
   background: var(--dpe-surface-sunken);
   color: var(--dpe-text-subtle);