Design token

01Panoramica

I design token sono i valori condivisi del sito: colori, spazi, scala dei testi, font, raggi, ombre e contenitori. L'opzione nucleo_tokens salva solo i valori cambiati rispetto ai default. Il plugin li unisce ai default.

Un documento cita un token con la forma $gruppo.chiave, per esempio $color.primary. Il compilatore lo sostituisce con var(--nc-gruppo-chiave).

Il plugin scrive l'artefatto tokens: le regole @font-face dei font importati e un blocco :root con tutte le variabili. Il frontend accoda questo CSS inline prima di ogni altro stile. Il tema nucleo-canvas legge le stesse variabili in base.css.

I font arrivano da Google Fonts, ma il plugin li salva in locale. I visitatori non contattano Google.

Gli agenti leggono e scrivono i token con nucleo/tokens-get e nucleo/tokens-set. La CLI locale propone i token da un file HTML con nucleo tokens suggest.

02Gruppi di token

I gruppi sono fissi: color, space, text, font, radius, shadow, container. Un gruppo diverso restituisce invalid_tokens.

Ogni gruppo ha chiavi di default. Si possono aggiungere chiavi nuove (vedi Chiavi nuove).

Gruppo color

Cosa fa: definisce i colori del sito.

Come si usa: $color.primary in un valore di stile. Variabile: --nc-color-primary.

Parametri:

Formati ammessi: esadecimale a 3, 4, 6 o 8 cifre; rgb(), rgba(), hsl(), hsla(), hwb(), lab(), lch(), oklab(), oklch(); var(--nc-…); le parole transparent, currentColor e i 16 nomi CSS base (black, silver, gray, white, maroon, red, purple, fuchsia, green, lime, olive, yellow, navy, blue, teal, aqua).

Permessi: come nucleo/tokens-set.

Edizione: Free

Limiti noti: gli altri nomi CSS (per esempio orange) sono rifiutati. Dentro le funzioni colore sono ammessi solo cifre, ., %, ,, spazio, /, - e deg. La pagina admin Design system accetta solo #rgb e #rrggbb (vedi Pagina Design system).

Gruppo space

Cosa fa: definisce la scala degli spazi per padding, margin e gap.

Come si usa: $space.4. Variabile: --nc-space-4, valore 1rem.

Parametri:

Permessi: come nucleo/tokens-set.

Edizione: Free

Limiti noti: il valore è un numero, non una stringa: "1rem" è rifiutato. 1 rem vale 16 px.

Gruppo text

Cosa fa: definisce la scala dei corpi di testo, fluida tra due valori.

Come si usa: $text.xl. Variabile: --nc-text-xl, con clamp() (vedi Testi fluidi con clamp()).

Parametri:

Permessi: come nucleo/tokens-set.

Edizione: Free

Limiti noti: la coppia deve avere esattamente due numeri. Con min uguale a max la variabile ha un valore fisso. Il valore grezzo del token è il massimo.

Gruppo font

Cosa fa: definisce le famiglie di caratteri del testo e dei titoli.

Come si usa: $font.heading. Variabile: --nc-font-heading.

Parametri:

Permessi: come nucleo/tokens-set.

Edizione: Free

Limiti noti: il valore segue le regole dei valori di stile dei documenti (vedi Validazione dei gruppi). Importare un font non cambia questo gruppo: il nome della famiglia va scritto con nucleo/tokens-set.

Gruppo radius

Cosa fa: definisce i raggi degli angoli.

Come si usa: $radius.md. Variabile: --nc-radius-md.

Parametri:

Permessi: come nucleo/tokens-set.

Edizione: Free

Limiti noti: il codice non controlla che il valore sia una lunghezza. Controlla solo la sicurezza del testo CSS.

Gruppo shadow

Cosa fa: definisce le ombre.

Come si usa: $shadow.md. Variabile: --nc-shadow-md.

Parametri:

Permessi: come nucleo/tokens-set.

Edizione: Free

Limiti noti: le virgole sono ammesse, quindi due ombre in un token sono valide.

Gruppo container

Cosa fa: definisce le larghezze massime dei contenitori.

Come si usa: $container.lg. Variabile: --nc-container-lg, valore 1024px. Il riquadro interno di nc/section usa max-width: var(--nc-container-lg).

Parametri:

Permessi: come nucleo/tokens-set.

Edizione: Free

Limiti noti: il valore deve essere un intero. Un numero decimale, anche 1200.0, è rifiutato.

Chiavi nuove

Cosa fa: estende la scala di un gruppo con una chiave che i default non hanno, per esempio $space.20 o $color.brand-dark.

Come si usa: nucleo/tokens-set con {"tokens": {"space": {"20": 6}}}. Il token $space.20 vale 6rem.

Parametri:

Permessi: come nucleo/tokens-set.

Edizione: Free

Limiti noti: al massimo 48 chiavi per gruppo, default compresi. Le chiavi di default non si tolgono: null le riporta al default. Il riferimento in un documento segue la forma $[a-z]+.[a-z0-9-]+.

03Validazione

Validazione dei gruppi

Cosa fa: unisce i valori dati ai default e controlla ogni valore. Un errore non salva nulla e restituisce il codice invalid_tokens.

Come si usa: interna. La usano nucleo/tokens-set, l'import di site.json e l'applicazione di un kit.

Parametri: regole per gruppo.

Il controllo dei valori CSS rifiuta ;, {, }, <, >, \, i caratteri di controllo, i commenti /* */, url(, expression(, @import, image-set(, image(, cross-fade(, element(, src(, javascript: e le parentesi o virgolette non chiuse.

Permessi: nessuno a questo livello.

Edizione: Free

Limiti noti:

• Gruppo sconosciuto: Unknown token group: <gruppo>.
• Gruppo non oggetto: Group <gruppo> must be an array.
• Chiave non valida: Invalid token key.
• Troppe chiavi: Too many tokens in group <gruppo> (maximum 48).
• Se l'opzione salvata non è valida, il plugin usa i default senza errore.

Riferimenti ai token nei documenti

Cosa fa: il validatore dei documenti rifiuta un $gruppo.chiave che non esiste nei token del sito. Il compilatore sostituisce i token anche nei valori composti, per esempio 1px solid $color.border.

Come si usa: scrivi il token nel valore di stile, per esempio "padding": "$space.12 0".

Parametri: nessuno.

Permessi: quelli del salvataggio del documento.

Edizione: Free

Limiti noti: errore di validazione unknown token: $space.20, con il suggerimento di usare nucleo/tokens-get o nucleo/tokens-set. Nel compilatore una dichiarazione con un token sconosciuto si scarta.

Regola qualità style.token.literal

Cosa fa: segnala un valore di stile letterale uguale al valore di un token. Il valore va scritto come riferimento al token.

Come si usa: automatica nel motore qualità.

Parametri: proprietà controllate per gruppo.

Le chiavi di stato (per esempio colorHover) usano il gruppo della chiave base.

Permessi: nessuno.

Edizione: Free

Limiti noti:

• Gravità error, quindi blocca la pubblicazione finché un umano non la riconosce.
• Il confronto è sull'intero valore: non trova token dentro valori composti.
• px e rem si confrontano in rem (16 px = 1 rem). Lo zero non conta. #abc vale #aabbcc.
• I gruppi text e container non sono controllati.

04Uscita CSS

Variabili CSS in :root

Cosa fa: scrive un blocco :root{…} minificato con una variabile per ogni chiave di ogni gruppo.

Come si usa: il nome è --nc-<gruppo>-<chiave>. Esempi: --nc-color-primary:#2563eb, --nc-space-4:1rem, --nc-container-lg:1024px.

Parametri: conversione dei valori.

Permessi: nessuno.

Edizione: Free

Limiti noti: i numeri hanno al massimo 4 decimali, senza zeri finali.

Testi fluidi con clamp()

Cosa fa: converte la coppia [min, max] del gruppo text in un corpo che cresce con la larghezza della finestra.

Come si usa: automatico. Esempio per base con i default: --nc-text-base:clamp(1rem, calc(0.9712rem + 0.1282vw), 1.125rem).

Parametri: viewport minima 360 px, viewport massima 1920 px, 1 rem = 16 px.

Permessi: nessuno.

Edizione: Free

Limiti noti: i due estremi della viewport sono costanti nel codice. Non si configurano.

Pubblicazione dell'artefatto tokens

Cosa fa: scrive l'artefatto tokens con tre campi: css, version (primi 8 caratteri dello SHA-1 del CSS) e preload (elenco di URL dei font da precaricare, al massimo due).

Come si usa: automatico. Parte dopo tokens-set, dopo fonts-import, all'attivazione del plugin, dopo l'import di site.json e nella manutenzione dello store in admin.

Parametri: nessuno.

Permessi: quelli dell'operazione che la avvia.

Edizione: Free

Limiti noti: il CSS contiene prima le @font-face dei font importati, poi le @font-face di ripiego, poi il blocco :root. Negli stack dei font aggiunge il font di ripiego metrico dopo la prima famiglia; l'opzione salvata non cambia. Il codice non ricompila i documenti al cambio dei token.

Caricamento sul frontend

Cosa fa: il frontend registra lo stile nucleo-tokens e aggiunge l'artefatto come CSS inline. Lo accoda prima degli altri stili.

Come si usa: automatico sulle pagine costruite con Nucleo. Sulle altre pagine lo accoda il frontend quando un layout (header, footer) si applica.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: nessun CSS se l'artefatto manca o è vuoto. Il tema nucleo-canvas usa le variabili in base.css con un valore di riserva, per esempio var(--nc-color-primary,#2563eb). Le anteprime dell'editor ricevono lo stesso CSS nel campo tokensCss.

Esposizione a Gutenberg e theme.json

Cosa fa: produce un array theme.json versione 3: color.palette dai colori, typography.fontSizes dai testi (con fluid min e max), typography.fontFamilies dai font, spacing.spacingSizes dagli spazi, layout.contentSize da container.lg e layout.wideSize da container.xl. Ad ogni pubblicazione l'array è salvato nell'opzione nucleo_theme_json.

Come si usa: automatico. L'array si aggiorna ad ogni pubblicazione dell'artefatto tokens.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: Gutenberg riceve i token solo con il tema nucleo-canvas: il tema legge nucleo_theme_json nel filtro wp_theme_json_data_theme, mentre con altri temi i token non arrivano all'editor a blocchi. I gruppi radius e shadow non sono nell'export.

05Font

Import da Google Fonts

Cosa fa: scarica una famiglia Google Fonts e la salva in locale come file woff2. Registra le facce nell'opzione nucleo_fonts (autoload off) e ripubblica l'artefatto tokens.

Come si usa: ability nucleo/fonts-import, oppure la pagina admin Design system, scheda Tipografia, riquadro "Import from Google Fonts".

Parametri: vedi nucleo/fonts-import.

Permessi: edit_theme_options.

Edizione: Free

Limiti noti:

• CSS da https://fonts.googleapis.com/css2, file solo da https://fonts.gstatic.com. Un altro host dà font_host_rejected.
• Timeout 10 secondi, nessun redirect, massimo 2 MB per risposta (font_too_large).
• Il file deve iniziare con la firma wOF2, altrimenti font_format. Se la risposta non ha nessun sottoinsieme ammesso, anche font_format.
• Sottoinsiemi scaricati: latin e latin-ext di default. L'opzione nucleo_font_subsets dà l'elenco di partenza (valori in minuscolo, lettere a-z, cifre e trattino; vuota o non valida torna al default); il filtro nucleo/font_subsets ha l'ultima parola. Ogni sottoinsieme è un download in più.
• Cartella: uploads/nucleo/fonts/. Nome file: <slug>-<peso>-<stile>[-<subset>].woff2.
• Un nuovo import della stessa famiglia (confronto senza maiuscole) sostituisce le facce e cancella i file vecchi.
• Nessuna funzione rimuove un font importato.
• Altri codici di errore: invalid_family, invalid_weights, font_network, uploads_unavailable, font_write.

Regole @font-face locali

Cosa fa: genera una regola @font-face per ogni file installato, con font-display:swap e unicode-range quando presente.

Come si usa: automatico, dentro l'artefatto tokens.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: le voci di nucleo_fonts malformate (famiglia, peso, stile, URL o range non validi) si ignorano.

Font di ripiego metrico

Cosa fa: crea una famiglia '<Famiglia> Fallback' basata su un font locale, con size-adjust, ascent-override, descent-override e line-gap-override. Riduce lo spostamento del layout mentre il font si carica.

Come si usa: automatico. Il ripiego segue la categoria della famiglia: Arial per i sans-serif, Times New Roman per i serif, Courier New per i monospace.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: funziona solo per le famiglie presenti nei dati di metriche del plugin (da @capsizecss/metrics 3.7.0). La regola @font-face di ripiego nasce solo per le famiglie importate. Il nome di ripiego entra negli stack di font per ogni prima famiglia con metriche.

Preload dei font

Cosa fa: sceglie fino a due file da precaricare e li invia nell'intestazione HTTP Link: <url>; rel=preload; as=font; type="font/woff2"; crossorigin.

Come si usa: automatico. Il primo file è quello della prima famiglia di font.body che risulta importata: peso 400 normale se esiste, altrimenti la prima faccia della famiglia. Il secondo è il file a peso 700 di font.heading, se la famiglia è importata. Gli URL duplicati si tolgono.

Parametri: nessuno.

Permessi: nessuno.

Edizione: Free

Limiti noti: precarica al massimo due file, senza duplicati. Se font.body non usa font importati, il primo file è la prima faccia installata di qualsiasi famiglia. L'intestazione parte solo sulle pagine costruite con Nucleo e solo se gli header non sono già partiti.

06Ability e comandi

nucleo/tokens-get

Cosa fa: restituisce i token effettivi del sito, default compresi, raggruppati per gruppo.

Come si usa: ability via MCP. Scheda completa in Abilities di lettura.

Parametri: nessuno. Uscita {"ok": true, "tokens": {…}}.

Permessi: edit_posts; scope nucleo:read.

Edizione: Free

Limiti noti: nessuno rilevato.

nucleo/tokens-set

Cosa fa: unisce i valori inviati ai token salvati, valida, salva l'opzione nucleo_tokens e ripubblica l'artefatto tokens.

Come si usa: ability via MCP, oppure la pagina admin Design system. Scheda completa in Abilities di scrittura. Esempio: {"tokens": {"color": {"primary": "#1d4ed8"}, "text": {"xl": [1.25, 1.5]}}}.

Parametri:

Permessi: edit_theme_options; scope nucleo:design.

Edizione: Free

Limiti noti: un valore non valido restituisce {"ok": false, "error": {"code": "invalid_tokens", …}} e non salva nulla. tokens non oggetto: invalid_input. Il risultato contiene contrast: i problemi di contrasto che i nuovi token causano nei documenti pubblicati (al massimo 50 documenti). Il salvataggio non si blocca per il contrasto. L'operazione finisce nel registro di attività come tokens-set.

nucleo/fonts-import

Cosa fa: importa una famiglia Google Fonts in locale e ripubblica i token.

Come si usa: ability via MCP, oppure la pagina admin Design system. Scheda completa in Abilities di scrittura. Esempio: {"family": "Inter", "weights": [400, 700]}.

Parametri:

Permessi: edit_theme_options; scope nucleo:design.

Edizione: Free

Limiti noti: in uscita faces contiene family, weight, style e url. Il percorso sul server non esce. Gli errori restituiscono ok: false con i codici di Import da Google Fonts. La pagina admin limita i pesi a 6.

Riferimento nucleo/catalog-get con topic: tokens

Cosa fa: restituisce le regole dei token per gli agenti: gruppi, formati, nomi delle variabili, comportamento di tokens-set. In data ci sono le chiavi di default (keys), i default (defaults) e i token salvati del sito (current).

Come si usa: nucleo/catalog-get con {"topic": "tokens"}. Vedi Abilities di lettura.

Parametri: topic = tokens.

Permessi: edit_posts; scope nucleo:read.

Edizione: Free

Limiti noti: il testo dice che theme.json riceve contentSize e wideSize. L'array è salvato nell'opzione nucleo_theme_json a ogni pubblicazione (vedi Esposizione a Gutenberg e theme.json).

nucleo tokens suggest

Cosa fa: legge un file HTML e propone l'input di nucleo/tokens-set. Considera i valori ripetuti almeno 3 volte negli stili <style> e negli attributi style="".

Come si usa: nucleo tokens suggest <design.html>. Lo standard output contiene solo {"tokens": {…}}. Lo standard error elenca le prove (color.primary: #a4462a (7)) e i valori senza token (no token: …). Vedi CLI locale.

Parametri:

Permessi: nessuno. Il comando non contatta il sito e non scrive file.

Edizione: Free

Limiti noti:

• Colori: solo #rgb, #rrggbb, rgb(), rgba(), hsl(), hsla() nelle proprietà di colore. Le chiavi si scelgono per luminosità e saturazione. Le ombre non generano colori.
• Spazi e testi: solo px e rem, assegnati alla chiave di default più vicina. I testi escono come coppia fissa [v, v].
• Raggi: sm, md, lg e full (da 999 px o 50%). Ombre: sm, md, lg.
• Font: body è il più frequente, heading il più usato nei selettori di titolo.
• Le durate di transition e animation finiscono sempre in no token: il sistema non ha un gruppo per le durate.
• Gli script e le regole @font-face si ignorano. Con almeno 3 variabili CSS definite, il comando legge le variabili e ignora le regole che non stilano il markup.
• Argomenti diversi danno Usage: nucleo tokens suggest <design.html>.

nucleo push --use-tokens

Cosa fa: prima del push sostituisce nei file locali i valori uguali a un token con $gruppo.chiave.

Come si usa: nucleo push [dir] --use-tokens. Con --dry-run conta le sostituzioni senza scrivere. Vedi CLI locale.

Parametri: nessuno oltre a quelli di push.

Permessi: quelli di nucleo/tokens-get (edit_posts; scope nucleo:read) più quelli del push.

Edizione: Free

Limiti noti: confronta con i token del sito sovrascritti dai tokens di site.json locale. Le proprietà per gruppo coincidono con quelle della regola style.token.literal; i test di parità verificano questa corrispondenza.

07Pagina admin

Pagina Design system

Cosa fa: mostra e modifica i token nella pagina admin "Design system" (slug nucleo-design). Ha cinque schede: Colors, Typography, Spaces, Shapes, Containers.

Come si usa: menu Nucleo AI → Design system. La pagina legge con nucleo/tokens-get e salva con nucleo/tokens-set, inviando solo i valori cambiati.

Parametri: cosa si modifica per scheda.

Permessi: edit_theme_options.

Edizione: Free

Limiti noti:

• I colori accettano solo #rgb e #rrggbb. Un colore salvato in altro formato (per esempio rgb()) risulta un errore e blocca il salvataggio.
• La scala dei testi chiede numeri maggiori di zero; il server accetta anche lo zero.
• Il pulsante "Add custom token" è disattivato.
• La tabella di contrasto controlla cinque coppie (text/background, text/surface, muted/background, muted/surface, background/primary) con soglia 4,5:1.
• L'etichetta indica "Fluid between 375 and 1920 px". Il server calcola il clamp() tra 360 e 1920 px.
• Dopo il salvataggio la pagina mostra "Documents are rebuilding in the background".