3
Design token
Nucleo comuneDesign Tokens
I token sono l'unico modo in cui un componente nomina un colore, una misura o un'ombra. Un esadecimale scritto in un componente è un difetto, non una scelta: rende il prodotto non ritematizzabile e la palette non reversibile.
3.1Nessun valore letterale nei componenti. Niente #540409, 12px, rgba(...) nel markup o negli stili di componente: sempre var(--token).nucleo
3.2I componenti citano ruoli, non palette. --primary-fill, non --mae-bordeaux. I token di identità esistono come riferimento e non si usano nell'interfaccia.struttura
3.3Due fogli, non tre. base.css più una palette. Non si mescolano le due palette nello stesso prodotto, nemmeno per sezione.struttura
3.4Le sostituzioni stanno nel tema, non nei componenti. Se una regola vale per tutta l'applicazione va in theme.components, dove si cambia in un punto.nucleo
3.5Ogni token ha il proprio valore in tema scuro. Nessun valore del tema chiaro si riusa su fondo scuro senza verifica di contrasto.nucleo
Cosa dichiara un progetto, e cosa no
Un committente porta un colore, e da quello se ne ricavano otto valori. Tutto il resto del sistema non si tocca.
Un cliente dice: il nostro colore è #1F5130
| --primary-fill | #1F5130 | Il colore com'è: azioni primarie |
| --primary-hover | #17401F | Lo stesso, più scuro |
| --primary-text | #1F5130 | Lo stesso come testo, se passa 4,5:1 |
| --active-line | #1F5130 | Il filetto della voce attiva e della riga selezionata |
| --bg | #F0F5F1 | Lo stesso all'8% su bianco: il fondo |
| --card-line | #D4E3D8 | Lo stesso al 18%: il bordo delle card |
| --nav-bg | #153A22 | Lo stesso scurito, se la sidebar è in tinta |
| --chart-1 · 2 · 3 | #1F5130 | Tre passi della stessa rampa |
Otto righe, tutte ricavate da un colore solo. È l'intero contenuto di un foglio di palette.
| Token | Prodotto di gruppo | Commessa |
| Dominante e derivati | Bordeaux o celeste | Del committente |
| Semantici — success, warning, danger, info | Armonizzati sulla dominante nel foglio di palette | Predefiniti neutri di base.css, dalla palette di Mantine |
| Link, attesa, focus ring | Armonizzati sul celeste di gruppo | Blu neutri |
| Inchiostri, filetti, superfici | Identici | Identici |
| Forma, spazio, tipografia, densità | Identici | Identici |
3.6Su commessa i semantici restano neutri. Un verde tarato sul bordeaux, messo accanto al marchio di un altro, non armonizza più niente: è solo un verde strano. E se il cliente è verde, il suo verde e quello di “completato” diventano indistinguibili.nucleo
3.7I predefiniti neutri sono quelli di Mantine, alle gradazioni che passano il contrasto: bordo alla 8, testo alla 9. Non si inventa una tavolozza di stati per ogni cliente.struttura
3.8Un committente porta i suoi colori, non un altro sistema. Forma dei tag, maiuscolo delle etichette, tratto invece del pieno, lineetta del valore mancante, misure e comportamento: restano.nucleo
3.9Se il colore di marca non passa il contrasto, si scurisce. Variante scura per il testo, quello di marca per i pieni. La soglia non si abbassa (5.1).nucleo
StrutturaNel pacchetto c'è palette-committente.css, un modello da copiare: dichiara solo quelle otto righe, e in fondo elenca cosa non si tocca. Le tinte armonizzate dei prodotti di gruppo stanno in 5 · Sistema di colore, che è identità Maestrale.
Superfici e inchiostri
Il fondo dell'applicativo non è bianco: è un grigio neutro, e le superfici bianche vi si appoggiano sopra. È questo salto, non il bordo, a portare la separazione.
| Token | Chiaro | Scuro | Uso |
| --bg | #F4F5F7 | #0F1115 | Fondo dell'applicativo |
| --surface | #FFFFFF | #16191F | Card, pannelli, tabelle, strati sovrapposti |
| --surface-2 | #F1F3F5 | #1C2027 | Intestazioni di tabella, campi inerti, modale in scuro |
| --row-alt | #F8F9FA | #1A1E24 | Righe alterne della griglia |
| --ink-900 | #0F1115 | #FFFFFF | Titoli, valori, testo enfatizzato |
| --ink-700 | #2A2D33 | #C9CCD2 | Testo corrente |
| --ink-500 | #5A5E66 | #9CA0A8 | Testo secondario, etichette |
| --ink-300 | #9CA0A8 | #6A6E76 | Segnaposto, disattivato, valore mancante |
Tratti
| Token | Chiaro | Scuro | Uso |
| --line | #DFE1E5 | #2E333B | Bordo di riposo: tabelle, avvisi, campi, barre |
| --line-strong | #B9BDC4 | #454B55 | Hover, bottone secondario, enfasi |
| --line-inset | #EDEEF0 | #23282F | Separatori interni, righe di tabella |
| --line-float | = --line | #5A616D | Bordo degli strati sovrapposti. In scuro serve un tono a sé: è l'unico che raggiunge 3:1 sul fondo |
Elevazione
Quattro passi, non sei. L'ombra risponde a una domanda sola: l'oggetto galleggia sopra il contenuto o ne fa parte? L'importanza non si dichiara con un alone: si fa con lo spazio e col peso del testo.
I quattro passi, sul fondo dell'applicativo
0 · appoggiatocard, riquadro, pannello
1 · ancoratoheader sticky
2 · sovrappostomenu, popover, notifica
3 · modalemodale, pannello, foglio
Ogni strato dal passo 2 in su porta anche un bordo di 1px. Con le ombre ridotte dal sistema, in tema scuro o in stampa, l'ombra non c'è: la forma deve restare delimitata comunque. L'ombra aggiunge profondità, non la definisce.
| Token | Valore | Scuro | Uso |
| --elev-card | 0 1px 2px rgba(15,17,21,.05), 0 1px 1px rgba(15,17,21,.04) | none | Card e pannelli, che non hanno bordo |
| --elev-raised | 0 1px 3px rgba(15,17,21,.06) | 0 1px 3px rgba(0,0,0,.40) | Solo mentre il contenuto scorre sotto |
| --elev-overlay | 0 6px 20px rgba(15,17,21,.10) | 0 6px 20px rgba(0,0,0,.45) | Ciò che copre e si chiude |
| --elev-modal | 0 18px 48px rgba(15,17,21,.16) | 0 18px 48px rgba(0,0,0,.60) | Ciò che blocca l'interazione |
In scuroL'ombra non separa: un'ombra nera su fondo quasi nero non ha luminanza da togliere. La distanza si dichiara schiarendo la superficie — --surface per gli strati sovrapposti, --surface-2 per la modale — più --line-float. È l'inverso del chiaro.
Raggi
Tre passi 6 / 10 / 14
Nessuna pillola a raggio pieno, per nessun elemento: tag, chip, bottoni, contatori. Il predefinito di Mantine 9 è md: il tema dichiara defaultRadius: 'sm', ed è una sostituzione consapevole.
StratoI raggi sono identità. Se il brand manual prescrive 12 / 16 / 22, questa scala è una deroga motivata dal contesto gestionale e va approvata come tale. Con un committente che impone i propri, si sostituiscono tre valori e nessun componente cambia.
Spaziatura
Scala a 4px
Gutter minimo 16px, padding di card 16px, stacco fra sezioni 32–48px. Nessun valore fuori scala: se serve 14px, serve 12 o 16.
Densità di riga
| Token | Valore | Quando |
| --row-comfy | 44px | Elenchi brevi, righe con due livelli di testo, telefono |
| --row-std | 36px | Predefinito delle griglie |
| --row-tight | 30px | Densità alta, scelta dall'utente e ricordata |
NucleoLa densità si ottiene con lo spazio, non col corpo del testo: il pavimento tipografico resta 13px anche nella riga compatta.
Movimento e livelli
| Token | Valore | Uso |
| --dur-fast · --dur-base | 120ms · 200ms | Stati e hover · entrate e uscite. Sempre nel rispetto di prefers-reduced-motion |
| --ease-standard | cubic-bezier(.4, 0, .2, 1) | Tutto, salvo gli strati che entrano in scena |
| --z-dropdown … --z-tooltip | 1000 · 1100 · 1200 · 1300 · 1400 · 1500 | Discesa, appiccicato, pannello, modale, notifica, suggerimento. Nessun numero sparso nel codice |
| --state-hover · --state-pressed | rgba(15,17,21,.03) · .07 | In scuro diventano chiari. Gli stati sono variazione di tratto, non di fondo |
| --opacity-disabled | 0.45 | Un elemento disattivato porta sempre il motivo, scritto accanto |
Il perchéL'argomentazione di queste scelte — il linguaggio a tratto, i quattro passi di elevazione, il fondo tinto e la scala dei raggi — sta in Forma e nelle Correzioni v3, voci 01–04.