Token in Tailwind, variabili CSS e CSS-in-JS

L'output della piattaforma CSS di Style Dictionary genera un file di proprietà personalizzate CSS: --color-primary-500: #3b82f6; --spacing-4: 16px; e così via. Queste variabili sono definite su :root, quindi sono disponibili globalmente. Questa è la base per l'utilizzo di tutti i token nell'applicazione.

Importi il file CSS dei token generato nel foglio di stile globale o nel componente di layout radice: @import './tokens/tokens.css'. In Next.js, lo importi in app/layout.tsx o in styles/globals.css. Una volta importato, ogni regola CSS e ogni componente dell'applicazione può fare riferimento alle proprietà personalizzate.

Faccia riferimento alle variabili CSS nei fogli di stile dei componenti o nei CSS Modules: background-color: var(--color-primary-500); e padding: var(--spacing-4);. Se il valore del token cambia nella sorgente JSON, la ricostruzione di Style Dictionary aggiorna il file CSS e tutti i componenti che usano quella variabile riflettono automaticamente il nuovo valore.

Le proprietà personalizzate CSS consentono di cambiare tema a runtime. Per la modalità scura, sovrascriva i valori dei token sotto un selettore del tema: [data-theme="dark"] { --color-background: #1a1a2a; --color-text: #f0f0f0; }. Impostando document.documentElement.setAttribute('data-theme', 'dark') si cambiano istantaneamente tutti i valori dei token, senza ricaricare né ricostruire l'applicazione.

Estenda il tema di Tailwind in tailwind.config.js per usare i valori dei token: theme: { extend: { colors: { primary: { 500: tokenOutput.color.primary[500] } } } }. Importi l'output JS di Style Dictionary nella configurazione di Tailwind, così le classi Tailwind (bg-primary-500) usano sempre i valori di riferimento dei token.

Per i temi commutabili a runtime in Tailwind, configuri il colore in modo che faccia riferimento a una variabile CSS: 'primary': 'rgb(var(--color-primary-rgb) / <alpha-value>)'. È necessario che la variabile CSS contenga i componenti RGB senza il wrapper rgb() (--color-primary-rgb: 59 130 246). Tailwind gestirà quindi automaticamente le utility per l'opacità.

Le librerie CSS-in-JS utilizzano un oggetto tema in JavaScript. Passi l'output JS di Style Dictionary come valore del provider del tema: <ThemeProvider theme={tokens}>. I componenti accedono ai token tramite const theme = useTheme() e theme.color.primary[500]. Style Dictionary genera l'oggetto tipizzato dei token; il provider del tema lo distribuisce.

Il plugin stylelint-no-hardcoded-colors e le regole ESLint personalizzate possono imporre che nei fogli di stile o nei file dei componenti non compaiano valori esadecimali scritti direttamente. Se uno sviluppatore scrive color: #3b82f6 invece di color: var(--color-primary-500), il linter lo segnala. In questo modo il sistema di token rimane l'unica fonte dei colori.

Quando i nomi delle classi Tailwind vengono costruiti dinamicamente a partire dai nomi dei token a runtime, il purge di Tailwind potrebbe rimuovere tali classi, perché non compaiono come stringhe statiche nel codice sorgente. Aggiunga i pattern delle classi dinamiche alla safelist in tailwind.config.js: safelist: [{ pattern: /bg-primary-/ }].

Il plugin Figma Tokens esporta direttamente i valori dei token di Figma nel formato JSON di Style Dictionary. Il flusso di lavoro è il seguente: i designer aggiornano i colori in Figma Variables, li esportano tramite il plugin, eseguono il commit del JSON aggiornato, lo script di prebuild esegue Style Dictionary e gli output CSS e JS aggiornati vengono utilizzati nell'app React. Design e codice restano sincronizzati.

Le proprietà personalizzate CSS hanno come ambito l'elemento su cui sono definite e i relativi discendenti. Questo consente di applicare override del tema a livello di componente: un componente card può impostare --color-background: var(--color-surface-elevated) sul proprio elemento radice e tutti i discendenti useranno il colore della superficie rialzata senza ricorrere al prop drilling.

Style Dictionary genera proprietà personalizzate CSS da importare globalmente e oggetti JS per l'integrazione con Tailwind e CSS-in-JS. Le variabili CSS consentono di cambiare tema a runtime tramite override [data-theme]. Tailwind estende la propria configurazione con i valori dei token provenienti dall'output JS; per una tematizzazione che supporti l'opacità, configuri Tailwind affinché faccia riferimento a variabili CSS RGB. Le regole di linting impongono l'uso esclusivo dei token per i colori, mantenendo i valori hardcoded fuori dal codebase.