KI-Coding-Assistenten generieren besseren Code, wenn sie die Design-Tokens des Projekts kennen und verstehen. Der Unterschied zwischen einer KI, die color: #2563EB generiert, und einer, die color: var(--color-action-primary) schreibt, liegt in der Token-Dokumentation. Prompt-Ready Tokens sind so aufbereitet, dass dieser Unterschied systematisch entsteht.

Was KI-Tools von Tokens erwarten

KI-Coding-Assistenten verarbeiten Text. Sie können JSON parsen, TypeScript-Interfaces lesen und Markdown verstehen. Was sie nicht können: Figma-Dateien öffnen, binäre Formate lesen oder implizites Wissen ableiten.

Das bedeutet: Tokens müssen als Text vorliegen – idealerweise in einem Format, das sowohl für Menschen als auch für Maschinen lesbar ist. Das DTCG-Format erfüllt diese Anforderung: JSON mit klaren Schlüsseln ($value, $type, $description), hierarchischer Struktur und Aliasing-Referenzen.

Naming-Conventions für Maschinenlesbarkeit

Token-Namen sind der wichtigste Faktor für die KI-Nutzbarkeit. Gute Namen beschreiben die Funktion, nicht den Wert. Wenn eine KI color.action.primary liest, versteht sie den Kontext sofort. Bei color.blue.500 fehlt die semantische Information.

Regeln für Prompt-Ready Token-Namen: Funktionale Benennung (color.border.subtle statt color.gray.200), konsistente Hierarchie (color.feedback.success, color.feedback.error, color.feedback.warning), keine Abkürzungen (background statt bg, primary statt prim), und klare Trennzeichen (Punkte in JSON, Bindestriche in CSS).

Die $description als AI-Prompt

Das oft vernachlässigte $description-Feld im DTCG-Format ist der Schlüssel zur Prompt-Readiness. Die Description wird zum impliziten Prompt für die KI:

{
  "color": {
    "action": {
      "primary": {
        "$value": "{color.green.600}",
        "$type": "color",
        "$description": "Primary action color. Use for primary buttons, important links, and CTAs. Do not use for decorative elements."
      },
      "primary-hover": {
        "$value": "{color.green.700}",
        "$type": "color",
        "$description": "Hover state for primary action elements. Automatically applied via :hover pseudo-class."
      }
    }
  }
}

Wenn eine KI diese Token-Datei im Kontext hat, generiert sie automatisch Code, der var(--color-action-primary) für Buttons verwendet und die Hover-Variante kennt. Die Description ist das Interface zwischen Design-Entscheidung und KI-generiertem Code.

Context-Dateien und CLAUDE.md-Integration

Die Token-JSON-Datei allein reicht oft nicht. Eine ergänzende Kontext-Datei fasst die wichtigsten Regeln zusammen:

## Token-Nutzung
- Immer Semantic Tokens verwenden, nie Primitive direkt.
- Farben: var(--color-action-primary) für Aktionen,
  var(--color-feedback-success/error/warning) für Feedback.
- Spacing: 4px-Grid. var(--spacing-1) = 4px bis var(--spacing-16) = 64px.
- Typografie: var(--text-body-md-size) für Fließtext,
  var(--text-h40-size) für Überschriften.

## Verbotene Patterns
- Keine hardcoded Hex-Werte.
- Keine px-Werte für Spacing (immer Token-Referenz).
- Keine !important.

Token-Dokumentation als Living Document

Prompt-Ready Tokens sind keine einmalige Einrichtung. Wenn neue Tokens hinzukommen oder sich Werte ändern, muss die Dokumentation mitwachsen. Der effizienteste Ansatz: Descriptions in der DTCG-JSON-Datei pflegen und daraus automatisch Dokumentation generieren – für Menschen als Doku-Site, für KI als Kontext-Datei.

Maßnahme
Wirkung auf KI-Qualität
Aufwand
DTCG-Format verwenden
Tokens sind parsebar
Mittel (einmalig)
$description zu allen Tokens
KI versteht Verwendungszweck
Mittel (fortlaufend)
Funktionale Token-Namen
KI wählt richtige Tokens
Gering (Konvention)
CLAUDE.md / .cursorrules
KI kennt Projekt-Kontext
Gering (einmalig)
TypeScript-Interfaces
Komponenten-API dokumentiert
Mittel (einmalig)
Automatische Doku-Generierung
Immer aktuell
Mittel (einmalig)

Kernpunkte

  • Prompt-Ready Tokens sind so benannt und dokumentiert, dass KI-Tools sie parsen und korrekt anwenden können.
  • Das $description-Feld im DTCG-Format ist der Schlüssel – es wird zum impliziten Prompt für die KI.
  • Funktionale Token-Namen (color.action.primary) sind maschinenlesbarer als wertbasierte (color.blue.500).
  • Eine CLAUDE.md / .cursorrules-Datei im Repository gibt KI-Tools den nötigen Projekt-Kontext.
  • Token-Dokumentation sollte aus der DTCG-JSON-Datei generiert werden – für Menschen und Maschinen gleichermaßen.
  • Prompt-Readiness ist keine KI-Abhängigkeit – dieselben Maßnahmen verbessern auch die Developer Experience für menschliche Entwickler.