Style Dictionary: transformera och generera tokens

Style Dictionary (skapat av Amazon) är ett byggverktyg som tar designtokensdefinitioner i JSON-format och matar ut dem i valfritt målformat: CSS custom properties, JavaScript ES-moduler, Sass-variabler, iOS Swift-konstanter, Android XML-resurser och alla egna format som definieras. En enda källa till sanning, många utdataformat.

Installera med npm install --save-dev style-dictionary. Initiera en projektstruktur med npx style-dictionary init, vilket skapar en config.json (eller config.js) och en tokens/-katalog. Konfigurationen anger var Style Dictionary ska hitta tokenfilerna och var utdata ska skrivas.

Style Dictionary använder en nästlad JSON-struktur där lövnoderna har egenskapen value. Till exempel: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. Sökvägen till värdet (color, primary, 500) blir tokennamnet efter transformeringen, vanligtvis formaterat som color-primary-500 eller --color-primary-500.

Kör npx style-dictionary build --config config.json (eller style-dictionary build om det har konfigurerats i skripten i package.json). Style Dictionary läser alla tokenfiler från den konfigurerade källan, tillämpar transformeringar och skriver utdata till de konfigurerade målen. Fel i tokenformatet rapporteras tillsammans med filnamn och sökväg.

config.json definierar plattformar: css (matar ut en CSS-fil med custom properties), js (matar ut ett JS-objekt) och scss (matar ut Sass-variabler). Varje plattform anger utdatakatalog, filnamn, format (mallen) och vilka transformeringar (funktionerna för bearbetning av namn och värden) som ska tillämpas.

Style Dictionary innehåller inbyggda transformeringar: name/cti/kebab omvandlar den nästlade sökvägen till color-primary-500, name/cti/camel skapar colorPrimary500, size/rem omvandlar pixelvärden till rem och color/hex normaliserar färger till hexadecimalt format. Transformeringar kan kombineras och tillämpas i ordning.

Man kan registrera egna transformeringar med StyleDictionary.registerTransform(). Det kan till exempel vara en transformering som omvandlar pixelvärden till iOS-punkter eller en som lägger till ett företagsspecifikt prefix till alla tokennamn. Egna transformeringar ger full kontroll över hur värden bearbetas före utmatning.

Egna format definierar mallen för utdatafilen. StyleDictionary.registerFormat() tar emot ordboken med transformerade tokens och returnerar en sträng – filens innehåll. Man kan mata ut tokens som TypeScript-typer, som ett React-temaobjekt, som en utökning av en Tailwind-konfiguration eller i vilket annat format som helst som behövs i teknikstacken.

Efter bygget importerar man CSS-utdata i den globala stilmallen: @import './tokens/tokens.css'. Importera JS-utdata i komponenter eller i Tailwind-konfigurationen: import tokens from './tokens/tokens.js'. CSS ger custom properties för temabyte vid körning, medan JS ger typade konstanter för Tailwind och JavaScript-logik.

Style Dictionary stöder tokenreferenser med klammerparenteser: { "value": "{color.primary.500}" }. Detta skapar alias för semantiska tokens – den semantiska token refererar till en primitiv token. Vid bygget löser Style Dictionary referenserna och matar ut det slutgiltiga lösta värdet (eller en CSS-variabelreferens, beroende på formatet).

Kör Style Dictionary som ett npm-skript för prebuild så att tokens alltid genereras om innan applikationen byggs. Lägg till "prebuild": "style-dictionary build" i package.json. Detta säkerställer att alla ändringar i token-JSON-filerna återspeglas i CSS- och JS-utdata innan React-bygget bearbetar dem.

Style Dictionary omvandlar token-JSON till valfritt utdataformat: CSS-variabler, JS-moduler, Sass, iOS och Android. Token-JSON använder nästlade objekt med lövnoder som innehåller value. Transformeringar bearbetar namn och värden (camelCase, px-till-rem), medan format definierar mallen för utdata. Tokenreferenser ({color.primary.500}) möjliggör semantiska alias. Automatisera med ett prebuild-skript så att tokens alltid är uppdaterade före React-bygget.