Das DTCG-Token-Format erklärt

DTCG ist das JSON-Austauschformat für design tokens, definiert von der Design Tokens Community Group. Jeder Token ist ein Objekt mit einem $value und einem $type; Verschachtelung bildet Gruppen; Strings wie {color.brand.600} verweisen auf andere Tokens; und zusammengesetzte Typen bündeln zusammengehörige Eigenschaften — ein Typography-Token trägt Familie, Größe, Schnitt und Zeilenhöhe als einen einzigen Wert. Eine Datei in diesem Format liest sich für jedes Tool, das es unterstützt, gleich — und genau das ist der Daseinsgrund des Formats.

Dieser Artikel geht die Anatomie an echten Beispielen durch, benennt die Typen, die du kennen solltest, und geht dann über das Spec-Minimum hinaus: was eine vollständig generierte Token-Datei tatsächlich enthält und welche Disziplin eine Datei gesund hält, wenn Tools und Menschen sie gemeinsam bearbeiten. Es ist das Format-Kapitel unseres Leitfadens zu design tokens.

Wie sieht eine DTCG-Datei aus?

Ein gekürztes, aber strukturell getreues Beispiel:

{
  "color": {
    "$description": "Palette generated from one blue seed.",
    "brand": {
      "600": {
        "$value": "#2563eb",
        "$type": "color",
        "$description": "Core brand step — oklch(0.546 0.215 262.9)"
      }
    }
  },
  "semantic": {
    "accent": { "$value": "{color.brand.600}", "$type": "color" }
  },
  "type": {
    "body-md": {
      "$type": "typography",
      "$value": {
        "fontFamily": "Inter",
        "fontSize": "16px",
        "fontWeight": 400,
        "lineHeight": "24px"
      }
    }
  }
}

Fünf Mechanismen tragen den Großteil des Formats:

$value — was der Token speichert. Die einzige Pflichteigenschaft.
$type — wie der Wert zu interpretieren ist: Ist "16px" eine dimension oder ein String? Der Typ beantwortet Fragen, die das rohe JSON nicht kann.
Gruppen durch Verschachtelung. Einfache Objekte gruppieren Tokens, und aus dem Pfad wird der Name: color.brand.600. Gruppen können einen $type tragen, den ihre Tokens erben — deshalb setzen echte Dateien ihn oft einmal pro Abschnitt.
$description — Dokumentation, die mit dem Token mitreist, in generierte Docs und Exporte hinein, statt in einem Wiki zu leben, das auseinanderdriftet.
Referenzen. Ein $value von "{color.brand.600}" macht einen Token zum Alias eines anderen — der Mechanismus, aus dem die semantische Ebene aufgebaut ist.

Das letzte Teil ist $extensions: ein namensraum-gebundener Behälter für tool-spezifische Daten, damit ein Tool Tokens annotieren kann, ohne mit der Spec oder mit anderen Tools zu kollidieren.

Welche Token-Typen sind in der Praxis wichtig?

Die primitiven Typen, denen du tatsächlich begegnest: color, dimension (Längen wie 23px oder 1.5rem), fontFamily, fontWeight, number und duration. Darüber liegen die zusammengesetzten Typen, bei denen der Wert eines Tokens ein Objekt aus zusammengehörigen Teilwerten ist: typography (das Beispiel oben), shadow (Farbe, Offsets, Weichzeichnung, Ausbreitung), border und transition.

Zusammengesetzte Typen existieren, weil manche Stile nur als Bündel korrekt sind. Ein body-md, das eine Größe trüge, aber nicht seine Zeilenhöhe, würde die halbe Stildefinition dem überlassen, was der Kontext zufällig erbt; der zusammengesetzte Typ macht das Bündel zur Einheit der Wiederverwendung. Von der Menge her dominieren color- und dimension-Tokens die meisten Dateien, während eine Handvoll zusammengesetzter Typen die typografische Schwerstarbeit leistet.

Warum ist ein Standardformat wichtig?

Wegen des Austauschproblems. Vor einem gemeinsamen Format erfand jedes Design-Tool und jede Build-Pipeline seinen eigenen JSON-Dialekt, und Tokens zwischen zwei beliebigen davon zu bewegen bedeutete einen Adapter — bei N Tools nähert sich das N² Adaptern, jeder davon eine Stelle, an der Werte falsch übersetzt werden können. Ein Standard bringt die Adapter zum Verschwinden: Schreib die Datei einmal, und jedes konforme Tool kann sie lesen.

Der Status verdient eine ehrliche Einordnung: Die DTCG-Format-Spezifikation ist ein Entwurf einer W3C-Community-Group, noch kein fertiger Standard. Die Tools haben sich weitgehend darauf verständigt, noch vor der formalen Standardisierung — ein häufiges Muster bei Formaten, die ein akutes Problem lösen —, aber Details können sich noch verschieben, und deshalb ist dieser Artikel als einer markiert, den man mit der Zeit erneut prüfen sollte.

Was enthält eine echte generierte Token-Datei?

Spec-Beispiele sind bewusst minimal — drei Tokens und eine Gruppe. Eine Datei, die ein echtes Design-System beschreibt, ist ein anderes Leseerlebnis, und ihre Abschnittsreihenfolge verrät dir die Architektur des Systems. Der Export von Scale Composer ist hier das durchgearbeitete Beispiel; von oben nach unten trägt er:

$description — eine Zeile, die sagt, was die Datei ist und woher sie stammt.
meta — Fakten auf Dateiebene, einschließlich der Einheit, in der das System ausgedrückt ist (px oder rem).
scale — die drei gemeinsamen Parameter (Basis, Ratio, Schritte pro Intervall), aus denen sowohl Typografie als auch Abstände abgeleitet werden.
System-Anker — die kleine Menge fester Werte, an die der Rest des Systems angeheftet ist.
color — die generierten Farbrampen, hex neben OKLCH.
spacing — die benannten Schritte.
typography — der zusammengesetzte Rollen-Satz, von Caption bis Display.
semantic und semantic-dark — die Rolle-zu-Wert-Zuordnungen, eine pro Theme, beide aus denselben Ausgangsfarben generiert.
layout — Breakpoints und Container-Breiten.
$metadata — Verwaltungsdaten am Ende.

In der Reihenfolge gelesen heißt das: zuerst die Parameter, dann das Rohmaterial, dann die Bedeutung, dann die Bedeutung pro Theme, dann die Struktur auf Seitenebene. Wer die Abschnittsreihenfolge kennt, kann die Frage „Wo würde X leben?” beantworten, ohne zu suchen. Öffne eine generierte Datei in der Export-Ansicht von Scale Composer — die Abschnitte in genau dieser Reihenfolge, mit den Werten live: Ändere einen Skala-Parameter und beobachte, wie sich die abgeleiteten Abschnitte neu generieren.

Die Export-Ansicht von Scale Composer mit einer vollständig generierten DTCG-Token-Datei: die Abschnitte description, meta, scale, color, spacing, typography, semantic und semantic-dark

Was passiert, wenn Tools und Menschen dieselbe Datei bearbeiten?

Das ist die Format-Frage, die die Spec nicht für dich beantworten kann, weil es um den Workflow geht. Eine Token-Datei im echten Einsatz hat zwei Arten von Autor: einen Generator, dem die Abschnitte gehören, die er ableitet, und Menschen, die hinzufügen, wovon der Generator nichts weiß — eine Komponenten-Gruppe, projektspezifische $extensions, eine zusätzliche Farbrampe, die von woanders importiert wurde.

Die Regel, die das sicher hält: Ein Tool sollte bewahren, was ihm nicht gehört. Wenn ein Generator eine Datei neu schreibt, müssen Abschnitte, die er nicht erstellt hat, unverändert durchkommen. Der Import-Pfad von Scale Composer hält das als getestete Eigenschaft ein — lade eine bestehende DTCG-Datei, passe sie an, exportiere neu, und der Round-Trip lässt die Abschnitte, die er nicht generiert, intakt; Speichern, Laden und erneutes Speichern erzeugt dieselbe Datei. Die Folge ist praktisch statt theoretisch: Deine von Hand hinzugefügten Abschnitte überleben die Regenerierung, also bedeutet die Einführung eines Generators nicht, ihm die ganze Datei zu überlassen. Ohne die Regel löscht die erste Regenerierung stillschweigend Arbeit — und stillschweigendes Löschen in einer so zentralen Datei ist teuer, wenn man es zu spät bemerkt.

Lies deinen eigenen Export

Formate hören auf, einschüchternd zu sein, sobald du zum ersten Mal eine Datei liest, die dir gehört. Lade eine bestehende DTCG-Datei in Scale Composer — oder exportiere eine frische — geh die Abschnitte anhand der Liste oben durch, finde, wo $type von einer Gruppe geerbt wird, folge einer {reference} bis zu ihrem Ziel, und exportiere dann neu und mach ein Diff: Die Abschnitte, die du nicht angefasst hast, kommen unverändert zurück.