Style Dictionary: Tokens transformieren und generieren

Style Dictionary (von Amazon entwickelt) ist ein Build-Tool, das Definitionen von Design-Tokens im JSON-Format entgegennimmt und sie in jedes Zielformat ausgibt: CSS Custom Properties, JavaScript-ES-Module, Sass-Variablen, iOS-Swift-Konstanten, Android-XML-Ressourcen und jedes von Ihnen definierte benutzerdefinierte Format. Eine Quelle der Wahrheit, viele Ausgaben.

Installieren Sie Style Dictionary mit npm install --save-dev style-dictionary. Initialisieren Sie eine Projektstruktur mit npx style-dictionary init. Dadurch werden eine config.json (oder config.js) und ein tokens/-Verzeichnis erstellt. Die Konfiguration legt fest, wo Style Dictionary Token-Dateien findet und wohin die Ausgaben geschrieben werden.

Style Dictionary verwendet eine verschachtelte JSON-Struktur, in der die Blattknoten eine value-Eigenschaft besitzen. Ein Beispiel: { "color": { "primary": { "500": { "value": "#3b82f6" } } } }. Der Pfad zum Wert (color, primary, 500) wird nach der Transformation zum Tokennamen, der typischerweise als color-primary-500 oder --color-primary-500 formatiert wird.

Führen Sie npx style-dictionary build --config config.json aus (oder style-dictionary build, wenn der Befehl in den package.json-Skripten konfiguriert ist). Style Dictionary liest alle Token-Dateien aus der konfigurierten Quelle, wendet Transforms an und schreibt die Ausgaben an die konfigurierten Zielorte. Fehler im Token-Format werden mit Dateiname und Pfad gemeldet.

Die config.json definiert Plattformen: css (gibt eine CSS-Datei mit Custom Properties aus), js (gibt ein JS-Objekt aus), scss (gibt Sass-Variablen aus). Jede Plattform legt das Ausgabeverzeichnis, den Dateinamen, das Format (die Vorlage) und die anzuwendenden Transforms (die Funktionen zur Verarbeitung von Namen und Werten) fest.

Style Dictionary enthält integrierte Transforms: name/cti/kebab wandelt den verschachtelten Pfad in color-primary-500 um, name/cti/camel erzeugt colorPrimary500, size/rem wandelt Pixelwerte in rem um und color/hex normalisiert Farben in das Hex-Format. Transforms sind kombinierbar und werden der Reihe nach angewendet.

Sie können eigene Transforms mit StyleDictionary.registerTransform() registrieren. Ein Transform kann beispielsweise Pixelwerte in iOS-Punkte umwandeln oder allen Tokennamen ein unternehmensspezifisches Präfix hinzufügen. Eigene Transforms geben Ihnen vollständige Kontrolle darüber, wie Werte vor der Ausgabe verarbeitet werden.

Eigene Formate definieren die Vorlage der Ausgabedatei. StyleDictionary.registerFormat() erhält das Dictionary der transformierten Tokens und gibt einen String zurück – den Dateiinhalt. Sie können Tokens als TypeScript-Typen, als React-Theme-Objekt, als Erweiterung einer Tailwind-Konfiguration oder in jedem anderen von Ihrem Stack benötigten Format ausgeben.

Importieren Sie nach dem Build die CSS-Ausgabe in Ihr globales Stylesheet: @import './tokens/tokens.css'. Importieren Sie die JS-Ausgabe in Komponenten oder die Tailwind-Konfiguration: import tokens from './tokens/tokens.js'. Das CSS stellt Custom Properties für Theming zur Laufzeit bereit; das JS liefert typisierte Konstanten für Tailwind und JavaScript-Logik.

Style Dictionary unterstützt Token-Referenzen in geschweiften Klammern: { "value": "{color.primary.500}" }. Dadurch entstehen Aliase für semantische Tokens – das semantische Token referenziert ein primitives Token. Beim Build löst Style Dictionary die Referenzen auf und gibt den endgültig aufgelösten Wert aus (oder eine CSS-Variablenreferenz, abhängig von Ihrem Format).

Führen Sie Style Dictionary als npm-Skript prebuild aus, damit die Tokens vor jedem Build der Anwendung neu generiert werden. Fügen Sie "prebuild": "style-dictionary build" zu package.json hinzu. So wird jede Änderung an den Token-JSON-Dateien in den CSS- und JS-Ausgaben berücksichtigt, bevor der React-Build sie verarbeitet.

Style Dictionary wandelt Token-JSON in jedes Ausgabeformat um: CSS-Variablen, JS-Module, Sass, iOS und Android. Token-JSON verwendet verschachtelte Objekte mit Blattknoten der Form value. Transforms verarbeiten Namen und Werte (camelCase, px-zu-rem); Formate definieren die Vorlage der Ausgabe. Token-Referenzen ({color.primary.500}) ermöglichen semantische Aliase. Automatisieren Sie den Vorgang mit einem prebuild-Skript, damit die Tokens vor dem React-Build immer aktuell sind.