Token-Tooling: Style Dictionary

Style Dictionary ist ein Open-Source-Build-Tool von Amazon, das eine Token-JSON-Quelle in plattformspezifische Ausgaben umwandelt: CSS Custom Properties, SCSS-Variablen, iOS-Swift-Konstanten, Android-XML sowie JavaScript-/TypeScript-Module – alles aus einer einzigen Quelle der Wahrheit.

Organisieren Sie Tokens im Verzeichnis tokens/ als JSON- oder JSON5-Dateien. Style Dictionary führt alle Dateien automatisch zusammen. Trennen Sie die Dateien nach Kategorie: tokens/color.json, tokens/spacing.json, tokens/typography.json.

Jeder Token ist ein verschachteltes Objekt mit einem Schlüssel value sowie optionalen Feldern type, description und comment. Style Dictionary flacht die Verschachtelung für die Ausgabe zu Namen in Punktnotation ab.

In config.json werden Quellen (Token-Dateien), Plattformen (Web, iOS, Android) sowie Transformationen und Formate je Plattform festgelegt. Jede Plattform kann unterschiedliche Transformationen anwenden und unterschiedliche Dateiformate ausgeben.

Transformationen ändern Tokenwerte während des Builds: color/css formatiert Farben als Hexadezimalwerte, size/rem konvertiert px in rem und name/cti/kebab erzeugt Namen im Kebab-Case aus der verschachtelten Struktur aus Kategorie, Typ und Element.

Formate bestimmen den Inhalt der Ausgabedateien. Integrierte Formate sind: css/variables gibt einen CSS-:root-Block aus, scss/variables gibt SASS-Variablen aus und javascript/module exportiert ein JS-Objekt. Benutzerdefinierte Formate ermöglichen jede benötigte Ausgabeform.

Verweisen Sie mit der Syntax geschweifter Klammern auf andere Tokens: {"value": "{color.brand.primary}"}. Style Dictionary löst Referenzen zur Build-Zeit auf und gibt konkrete Werte aus. Referenzen bilden die Zuordnung zwischen Alias und globalem Token.

Registrieren Sie benutzerdefinierte Transformationen für projektspezifische Anforderungen: Entfernen Sie den Alpha-Kanal aus Farben, konvertieren Sie Opazitätswerte aus Designtools oder fügen Sie Vendor-Präfixe hinzu. Benutzerdefinierte Transformationen werden wie integrierte Transformationen in die Build-Pipeline eingefügt.

Führen Sie npx style-dictionary build aus oder fügen Sie den Befehl Ihrem npm-Build-Skript hinzu. Die Ausgabedateien werden in den konfigurierten buildPath-Verzeichnissen abgelegt. Sie können die generierten Dateien versionieren oder sie zur Build-Zeit in CI erzeugen – beide Vorgehensweisen sind üblich.

Tokens Studio for Figma synchronisiert Token-JSON mit einem GitHub-Repository. Style Dictionary wird in CI ausgeführt, sobald sich das JSON ändert, und generiert automatisch aktualisierte CSS- und Plattformdateien. Designänderungen werden ohne manuelles Kopieren und Einfügen in den Code übernommen.

Versionieren Sie Ihr Token-Paket in npm. Abhängige Projekte legen eine Version fest und führen Upgrades bewusst durch. Änderungsprotokolle dokumentieren hinzugefügte, veraltete und entfernte Tokens. Semantische Versionierung macht deutlich, ob es sich um Breaking Changes oder sichere Aktualisierungen handelt.

Style Dictionary wandelt eine einzige Token-JSON-Quelle mithilfe konfigurierbarer Transformationen und Formate in plattformspezifische Ausgaben um. Dadurch ermöglicht es die Synchronisierung von Figma zu Code, plattformübergreifende Konsistenz und versionierte Token-Pakete, die Teams bewusst verwenden und aktualisieren können.