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#1F5130Il colore com'è: azioni primarie
--primary-hover#17401FLo stesso, più scuro
--primary-text#1F5130Lo stesso come testo, se passa 4,5:1
--active-line#1F5130Il filetto della voce attiva e della riga selezionata
--bg#F0F5F1Lo stesso all'8% su bianco: il fondo
--card-line#D4E3D8Lo stesso al 18%: il bordo delle card
--nav-bg#153A22Lo stesso scurito, se la sidebar è in tinta
--chart-1 · 2 · 3#1F5130Tre passi della stessa rampa
Otto righe, tutte ricavate da un colore solo. È l'intero contenuto di un foglio di palette.
TokenProdotto di gruppoCommessa
Dominante e derivatiBordeaux o celesteDel committente
Semantici — success, warning, danger, infoArmonizzati sulla dominante nel foglio di palettePredefiniti neutri di base.css, dalla palette di Mantine
Link, attesa, focus ringArmonizzati sul celeste di gruppoBlu neutri
Inchiostri, filetti, superficiIdenticiIdentici
Forma, spazio, tipografia, densitàIdenticiIdentici
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.

TokenChiaroScuroUso
--bg#F4F5F7#0F1115Fondo dell'applicativo
--surface#FFFFFF#16191FCard, pannelli, tabelle, strati sovrapposti
--surface-2#F1F3F5#1C2027Intestazioni di tabella, campi inerti, modale in scuro
--row-alt#F8F9FA#1A1E24Righe alterne della griglia
--ink-900#0F1115#FFFFFFTitoli, valori, testo enfatizzato
--ink-700#2A2D33#C9CCD2Testo corrente
--ink-500#5A5E66#9CA0A8Testo secondario, etichette
--ink-300#9CA0A8#6A6E76Segnaposto, disattivato, valore mancante

Tratti

TokenChiaroScuroUso
--line#DFE1E5#2E333BBordo di riposo: tabelle, avvisi, campi, barre
--line-strong#B9BDC4#454B55Hover, bottone secondario, enfasi
--line-inset#EDEEF0#23282FSeparatori interni, righe di tabella
--line-float= --line#5A616DBordo 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.
TokenValoreScuroUso
--elev-card0 1px 2px rgba(15,17,21,.05), 0 1px 1px rgba(15,17,21,.04)noneCard e pannelli, che non hanno bordo
--elev-raised0 1px 3px rgba(15,17,21,.06)0 1px 3px rgba(0,0,0,.40)Solo mentre il contenuto scorre sotto
--elev-overlay0 6px 20px rgba(15,17,21,.10)0 6px 20px rgba(0,0,0,.45)Ciò che copre e si chiude
--elev-modal0 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
6px · controlli e tag
10px · card e tabelle
14px · modale e foglio
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
1 · 4
2 · 8
3 · 12
4 · 16
5 · 24
6 · 32
7 · 48
8 · 64
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

TokenValoreQuando
--row-comfy44pxElenchi brevi, righe con due livelli di testo, telefono
--row-std36pxPredefinito delle griglie
--row-tight30pxDensità 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

TokenValoreUso
--dur-fast · --dur-base120ms · 200msStati e hover · entrate e uscite. Sempre nel rispetto di prefers-reduced-motion
--ease-standardcubic-bezier(.4, 0, .2, 1)Tutto, salvo gli strati che entrano in scena
--z-dropdown … --z-tooltip1000 · 1100 · 1200 · 1300 · 1400 · 1500Discesa, appiccicato, pannello, modale, notifica, suggerimento. Nessun numero sparso nel codice
--state-hover · --state-pressedrgba(15,17,21,.03) · .07In scuro diventano chiari. Gli stati sono variazione di tratto, non di fondo
--opacity-disabled0.45Un 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.