joo6077/design-system

Gotchas

1. Keine konkreten Werte in Token-Namen verwenden — blue-500, primary-blue ✗ → color.text.primary, color.background.brand ✓. Bei Wertänderungen entsteht eine Diskrepanz, die bei Rebranding oder Dunkelmodus-Umschaltung sofort zerbricht.

2. Nicht nur primitive Token ohne semantische verwenden — Wird color.green.500 direkt an eine Komponente gebunden, ist ein Themawechsel unmöglich. Es muss zwingend die Dreischichtung primitive → semantic(alias) → component durchlaufen werden.

3. Dunkelmodus nicht in Token-Namen einbauen — color-dark-text-primary, color-light-surface ✗. Dies zwingt den Konsumenten zu themenabhängigen Bedingungen. Der korrekte Ansatz ist, einem semantischen Token modusabhängige Werte zuzuordnen.

4. Keine beliebigen Werte ohne Skala hinzufügen — Werden willkürliche spacing/radius-Werte wie 10px, 14px, 18px, 22px angehäuft, bricht das System zusammen. Legen Sie zuerst eine endliche Skala fest, z.B. 2/4/8/12/16/24/32, und lehnen Sie Werte außerhalb dieser Skala ab.

5. Komponenten-Token nicht global wiederverwenden — Wenn button.primary.background in einer anderen Komponente verwendet wird, steigt die Kopplung. Heben Sie einen Token nur dann auf die globale semantische Ebene, wenn er von mehreren Komponenten gemeinsam benötigt wird.

6. Typografie als gebündelte Tokens statt Einzelwerte — Werden font-size-14 und line-height-20 einzeln verwendet, entstehen Kombinationsfehler. Stellen Sie stattdessen semantische Style-Tokens wie font.body.medium bereit, die size/weight/line-height bündeln.

7. Dokumentation der Spacing-Basis zwingend erforderlich — Wenn nicht die 4px-Basis verwendet wird, muss der Grund dokumentiert werden. Wichtiger als die Basis-Zahl ist die Konsistenz bei der Verwendung nur der erlaubten Skala.

8. DTCG-Namensregeln — Token- und Gruppennamen verwenden keine { } . und beginnen nicht mit $ (Das $-Präfix ist für Eigenschaftsschlüssel wie $value und $type reserviert). Hierarchien werden durch verschachtelte JSON-Gruppen gebildet. . erscheint nur in Referenzen als Verbinder von Gruppennamen ({color.text.primary}) und ist kein Zeichen im Namen selbst. Quelle: DTCG Format Module 2025.10.

9. Keine Code-Generierung pro Stack — Dieses Skill gibt nur Prinzipien und Token-Spezifikationen aus. Es erzeugt keinen Flutter/React/CSS-Code direkt. Delegieren Sie dies an die entsprechenden Toolkit-Plugins.

10. DTCG $extends Gruppenvererbung nutzen — Das in DTCG 2025.10 hinzugefügte $extends-Schlüsselwort ermöglicht die Deep-Merge-Vererbung zwischen Gruppen. Definieren Sie nicht denselben primitiven Wert in mehreren semantischen Gruppen, sondern erstellen Sie eine gemeinsame Gruppe und referenzieren Sie sie mit $extends. Zirkuläre Referenzen sind verboten und müssen vom Parser erkannt werden. Quelle: research-log §A.

11. HTML-Beispiele :root CSS-Variablen müssen mit bestehenden Design-Kit-Dateien übereinstimmen — Wenn in Schritt 4 HTML-Snippets als Token-Spezifikationsbeispiele eingefügt werden, müssen die Werte von :root { --color-*: ...; } mit den CSS-Variablenwerten vorhandener HTML-Dateien in design-kit/docs/ oder design-kit/templates/ übereinstimmen. Wertinkonsistenzen sind der Beginn von Systemspaltung und waren ein tatsächlicher Ablehnungsgrund (AR-06). Fügen Sie neue Variablen gleichzeitig in bestehende Dateien ein oder dokumentieren Sie den Grund für die Abweichung.

12. OKLCH für primitive Farben empfehlen — Tailwind CSS v4 (angekündigt 2025-01-22, aktuelles stabiles Release v4.3.3, 2026-07-16) hat die Standardpalette von rgb auf oklch umgestellt, und shadcn/ui v4 hat die Umstellung von HSL auf oklch() abgeschlossen. OKLCH bietet gleichmäßige Rampen auf den Achsen Helligkeit (L), Chroma (C) und Farbton (H) und nutzt den P3-Wide-Gamut, um sRGB-Einschränkungen zu umgehen. Bei der Definition von Primitiven wird oklch(L% C H) bevorzugt; falls ein Fallback für ältere Browser erforderlich ist, geben Sie sRGB-Hex parallel an. Browserunterstützung: Safari 16.4+ / Chrome 111+ / Firefox 128+ (entspricht dem Unterstützungsumfang von Tailwind v4). Figma-Hinweis: Die Figma-Hilfe listet Hex, HSB, HSL, CSS und RGB als Farbmodelle auf, OKLCH ist nicht in der Liste (About color models). Es gibt keine explizite Aussage, dass Figma Variables OKLCH nicht akzeptieren; daher sollte man dies nicht als gegeben annehmen. Es ist jedoch üblich, beim Export nach Figma den Hex-Näherungswert anzugeben (z.B. bei Obra shadcn kit). Quelle: Tailwind v4 blog, Tailwind v4.3.3, shadcn Tailwind v4, Evil Martians OKLCH, MDN oklch().

13. Enumerate-before-Act — Vor Token-Änderungen zwingend vollständige Auflistung — Bei Anfragen zur Verbesserung eines bestehenden Designsystems (z.B. „Dunkelmodus-Unterstützung hinzufügen“, „Semantische Token aufräumen“) muss vor der Bearbeitung zwingend die folgende Reihenfolge eingehalten werden: (1) vollständige Liste der vorhandenen Token-Dateien + Anzahl pro Kategorie, (2) Verteilung auf Tier 1 primitiv / Tier 2 semantisch / Tier 3 Komponente, (3) fehlende Kategorien, Namensverstöße und nicht abgedeckte Dunkelmodus-Elemente als Verstoßliste präsentieren, (4) nach Zustimmung des Benutzers bearbeiten. Teilweise Korrekturen mit dem Hinweis „den Rest können Sie selbst machen“ sind zu vermeiden (insights-report #1 „Proactive quality gaps“ · skill-design-guide §5.5 Enumerate-before-Act-Prinzip).

14. DTCG v1-Schema einhalten — Aliase sind geschweifte Klammern-Referenzen — Die Design Tokens Community Group hat am 28.10.2025 das Design Tokens Format Module 2025.10 als ersten stabilen „Final Community Group Report“ veröffentlicht (DTCG v1). Das JSON-Format verwendet die Präfixe $value, $type, $description; Gruppenobjekte (ohne $value) können einen Standardwert für $type auf Gruppenebene festlegen. $extensions sind Metadaten für Tool-Anbieter. $schema ist nicht in der Liste der Gruppenattribute des Final Reports 2025.10 enthalten – wenn ein Tool es als Erweiterung verwendet, ist dies getrennt von der DTCG-Spezifikation anzugeben.

    Alias-Notation (häufige Fehlerquelle): Die Referenzsyntax der Spezifikation ist eine mit geschweiften Klammern umschlossene Zeichenfolge {group.token}. Gotcha 8 verbietet { } nur in Token-Namen, da die geschweiften Klammern für Referenzen reserviert sind – in Referenz- Werten müssen sie zwingend verwendet werden. Beide Regeln widersprechen sich nicht. Eine reine Punkt-Notation-Zeichenfolge ("color.background.surface") wird als einfacher Zeichenfolgenwert und nicht als Referenz interpretiert. Geschweifte Klammern-Referenzen können nur auf vollständige Tokens (Objekte mit $value) verweisen; für Verweise auf einzelne Eigenschaften innerhalb eines Token-Werts wird $ref im JSON-Pointer-Format (RFC 6901) verwendet (#/path/to/target).

    {
      "color": {
        "brand": { "$type": "color", "$value": { "colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc" } },
        "surface": { "$value": "{color.brand}" }
      }
    }
    

    Verboten: Legacy-value/type-Schlüssel (ohne Präfix), benutzerdefinierte $-Präfix-Schlüssel, ungeklammerte Punkt-Notation-Aliase. Der Wert eines Farb-Tokens ist ein Objekt mit colorSpace / components / hex (optional) / alpha (optional) – das reine Hex-Zeichenfolgenformat ist in der Spezifikation nicht enthalten. Downstream-Tools wie Tokens Studio, Style Dictionary und zeroheight erwarten dieses Format. Quelle: W3C DTCG v1 announcement 2025-10-28, W3C Final Report, DTCG Format Module (drafts), Tokens Studio DTCG vs Legacy.

15. Bestehende App-Farben nicht durch neue Palette ersetzen (Visual Source of Truth Precedence) — Wenn in einem Projekt, das bereits ein Farbsystem verwendet, Tokens eingeführt werden, erstellen Sie keine forschungsbasiert „bessere“ Palette. Extrahieren Sie zuerst alle tatsächlich verwendeten Werte, präsentieren Sie sie und umhüllen Sie diese Werte als Standardansatz mit Tokens. Eine Änderung der Werte selbst ist ein separater Vorschlag und erfordert die Zustimmung des Benutzers. Wenn der Benutzer im Browser bestätigte und genehmigte Design-Farben (.design/approvals/-Aufzeichnungen) hat, haben diese Vorrang vor der Projektpalette – eine Normalisierung des genehmigten Werts auf eine einzelne Tönung oder einen vorhandenen Akzent-Token ist ein Rückschritt. Rangfolge: ../../references/visual-change-protocol.md §1.

    Schlecht:  "Ich habe Hintergrundfarb-Token definiert" (ohne den vorhandenen App-Hintergrund zu lesen, wird eine neue neutrale Rampe erstellt)
              → "Die Hintergrundfarbe sieht immer noch falsch aus, es muss doch die ursprünglich verwendeten Farben geben?"
    Schlecht:  Genehmigter Design-Akzent → Ersetzung durch Projekt-Akzent-Token → "Warum wird eine andere Farbe verwendet?"
    Gut: Alle vorhandenen Werte extrahieren → Als Tabelle präsentieren → "Ich werde diese Werte in semantische Tokens verpacken.
          Bitte informieren Sie mich, wenn Anpassungen erforderlich sind."
    

16. Teiländerungs-Wünsche nur auf den genannten Token beziehen – keine gleichzeitige Anpassung benachbarter Werte — Bei Anfragen wie „nur diese Rahmenfarbe dunkler machen“ oder „nur die Oberfläche eine Stufe dunkler“ sollten Sie nicht gleichzeitig nicht angefragte Tokens (Hintergrund, Füllung, Text, Radius, Elevation) anpassen. Auch ein Neuberechnen benachbarter Schritte mit der Begründung der Rampen-Konsistenz liegt außerhalb des Anfragebereichs. Erstellen Sie vor der Bearbeitung eine Änderung / Beibehaltung-Liste und überprüfen Sie nach der Bearbeitung, ob die Werte der beibehaltenen Liste unverändert sind. Wenn sich Tokens außerhalb der Absicht geändert haben, machen Sie die Änderung rückgängig und wenden Sie die Änderung nur auf die angefragten Werte erneut an. Ein teilweises Zurücksetzen wie „Die Farbe ist jetzt richtig, aber der Gradient soll wie zuvor“ betrifft nur die angefragte Achse. Details: ../../references/visual-change-protocol.md §2.

17. Nur die angefragte Token-Kategorie definieren – keine willkürliche Erweiterung des vollständigen Systems (insights-report #1 Scope-Missverständnis · #3 Überdesign) — Wenn Sie nur nach einer bestimmten Kategorie gefragt werden, z.B. „Erstelle mir nur eine Farbpalette“ oder „Lege eine spacing-Skala fest“, definieren Sie nur diese Kategorie. Bauen Sie nicht ein vollständiges System mit nicht angefragten Typografie-, Radius-, Elevations- oder Motion-Tokens auf einmal. Die Anforderung eines „vollständigen Token-Systems“ (wie in anderen Gotchas die Dreischichtung und semantische Struktur) bezieht sich auf die Vollständigkeit innerhalb der angefragten Kategorie, nicht auf eine willkürliche Erweiterung der Kategorien selbst. Wenn der Umfang unklar ist, raten Sie nicht und erweitern Sie nicht, sondern fragen Sie mit einer Zeile: „Soll ich nur Farben definieren oder das gesamte Token-System einrichten?“ Wenn eine Erweiterung sinnvoll erscheint, packen Sie sie nicht in das Ergebnis, sondern trennen Sie sie als separaten Vorschlag in der Form: „Ich empfehle auch, Typografie-/Spacing-Tokens einzurichten – möchten Sie fortfahren?“. Gleiches gilt für den vollständigen Aufbau der drei Ebenen (primitiv → semantisch → Komponente) – laut der Research von 2026 reichen für die meisten Teams die zwei Ebenen primitiv + semantisch aus; die Komponenten-Token-Ebene wird nur auf Unternehmensebene benötigt. Geben Sie nicht standardmäßig drei Ebenen aus, ohne dass die Anfrage oder Größenordnung dies rechtfertigt. Quelle: zeroheight Design Systems Report 2026 (zweistufiges Modell ist Industriestandard, volles dreistufiges nur etwa die Hälfte der Teams), material-design.md:281 (schrittweise Einführung).

Prozess

Schritt 1: Designsystem des Projekts erkennen

Durchsuchen Sie das Projektverzeichnis nach Design-Token-/Theme-Dateien:

# Suchmuster (stack-unabhängig)
**/theme/**
**/tokens/**
**/design/**
**/styles/**
**/colors.*
**/typography.*

• Gefunden: HAS_DS=true, analysieren der vorhandenen Token-Struktur
• Nicht gefunden: HAS_DS=false, Modus zum Vorschlagen eines neuen Token-Systems

Schritt 2: Entwurf der 3-stufigen Token-Architektur

Jeder Token wird in die folgenden 3 Stufen unterteilt. Überspringen Sie keine Stufen.

Stufe 1 — Primitiv (Wertspeicher)
  Beispiel: color.palette.green.500 = #22c55e
      space.scale.4 = 4px

Stufe 2 — Semantisch (Rollen-/Intent-Alias)
  Beispiel: color.text.success → {color.palette.green.500}
      color.background.surface → {color.palette.neutral.50}  (heller Modus)
      color.background.surface → {color.palette.neutral.900} (dunkler Modus)

Stufe 3 — Komponente (Komponenten-spezifischer Überschreibung)
  Beispiel: button.primary.background → {color.background.brand}
      card.border.radius → {radius.md}
  ※ Nur auf Stufe 2 anheben, wenn er von mehreren Komponenten gemeinsam benötigt wird

Erforderliche/optionale Kategorien und semantische Namenskonventionen:

Kategorie	Erforderlich	Semantisches Beispiel	Skalierungsstandard
Farbe	Erforderlich	text.primary, text.secondary, text.disabled, background.surface, background.brand, border.default, border.subtle	—
Typografie	Erforderlich	font.display.lg, font.heading.md, font.body.sm, font.label.xs (Bündelung size+weight+line-height)	Empfohlen: Modular Scale Verhältnis (1,125 Major Second ~ 1,618 Golden Ratio). Fluid: clamp(min, preferred, max)
Spacing	Erforderlich	space.xs(4), space.sm(8), space.md(16), space.lg(24), space.xl(32), space.2xl(48)	4px Basis. Fluid Spacing: clamp()-basierte kontinuierliche Abstände in Betracht ziehen
Radius	Erforderlich	radius.none(0), radius.sm(4), radius.md(8), radius.lg(16), radius.full(9999)	Endliche Skala
Elevation	Optional	elevation.level-0 ~ level-4 (Schattenwerte)	—
Motion	Optional	motion.duration.fast(100ms), motion.duration.normal(200ms), motion.easing.standard	—

Hinweis — Material 3 Expressive (Mai 2025 angekündigt): Die offizielle Material-Dokumentation gibt an, dass M3 Expressive auf 46 Studien und über 18.000 Teilnehmern basiert und ein breiteres Farbspektrum, dynamische Farben, Personalisierung und ein spring-basiertes Motion-Physics-System bietet. Die Erstellung einer tonalen Palette pro Farbe mit HCT und die Zuordnung dieser Töne zu Farbrollen ist keine exklusive Funktion von Expressive, sondern eine Beschreibung des gesamten M3-Farbsystems. Variable Fonts wie Roboto Flex sind eine Option für Ausdruckskraft und nicht Teil der M3-Typografie-Skala. Die Zuordnung der Töne der tonalen Palette zu Primitiven und der Farbrollen zu semantischen Aliassen ist keine offizielle Regel, sondern eine Konvention dieses Repositorys für die 3-stufige Token-Struktur. Quelle: Start building with Material 3 Expressive, Color system, Typography, Motion (abgerufen am 28.09.2026).

Schritt 3: HAS_DS=true → Analyse des bestehenden Systems

Vergleichen Sie bestehende Tokens mit der 3-stufigen Architektur und geben Sie einen Bericht aus:

• Fehlende Stufen: Primitiven, die direkt an Komponenten gebunden werden
• Namensverstöße: Tokens mit Werten im Namen (blue-500, color-dark-*)
• Fehlende Dunkelmodus-Unterstützung: Farb-semantische Tokens ohne Modus-Alias
• Skalenabweichungen: Verwendung von beliebigen Werten außerhalb der erlaubten Skala
• Missbrauch von Komponenten-Tokens: Wiederverwendung von Komponenten-Tokens in anderen Komponenten
• Typografie-Trennung: Wenn size/weight/line-height nur als einzelne Tokens bereitgestellt werden

Schritt 4: HAS_DS=false → Token-Spezifikation erstellen

Erstellen Sie die Token-Spezifikation im Format templates/design-tokens.md. Stellen Sie dem Benutzer die folgenden Kategorien der Reihe nach zur Auswahl und holen Sie Zustimmung ein:

1. Festlegung der Markenfarbpalette (primitiv)
2. Semantische Farb-Tokens – einschließlich Mapping für hell/dunkel
3. Spacing-Skala (Standard 4px Basis, bei Änderung Begründung angeben)
4. Typografie-Stil-Tokens gebündelt
5. Radius-Skala
6. Elevation/Motion (falls erforderlich)

Schritt 5: Ergebnisprüfung

• Prüfung, ob alle erforderlichen Kategorien in 3 Stufen unterteilt sind
• Prüfung, ob semantische Tokens als primitive Aliase definiert sind (keine direkten Werte ✗)
• Prüfung, ob das Mapping für hell/dunkel auf beiden semantischen Seiten existiert
• Prüfung, ob keine beliebigen Werte außerhalb der erlaubten Skala vorhanden sind
• Prüfung, ob der Geltungsbereich von Komponenten-Tokens auf die betreffende Komponente beschränkt ist
• Validierung der CSS-Variablenkonsistenz :root (Gotcha #11) — Wenn das Ergebnis HTML-:root-Snippets enthält, vergleichen Sie diese mit den CSS-Variablenwerten vorhandener HTML-Dateien in design-kit/docs/ und design-kit/templates/, um Inkonsistenzen zu vermeiden. Bei Inkonsistenzen aktualisieren Sie die vorhandenen Dateien gleichzeitig oder dokumentieren Sie den Grund.
• Hinweis zur Pipeline Figma Variables → Tokens Studio → Style Dictionary v5 — Bei der Erstellung der Token-Spezifikation informieren Sie den Benutzer über die Pipeline: Figma Variables (primitiv + semantisch) → Tokens Studio DTCG JSON-Export → Style Dictionary v5 plattformspezifische Konvertierung → Git-Synchronisation. Empfehlen Sie die Aktivierung von Code Syntax, die Nutzung des Description-Felds und die Einschränkung des Geltungsbereichs. v5 erfordert Node.js 22 oder höher und akzeptiert keine Verweise auf Nicht-Token-Werte, Verweise mit .value oder geänderte Referenzsyntax – überprüfen Sie diese drei Punkte zuerst beim Migrieren von v4-Einstellungen. Das Prototype-Pollution-Sicherheitsproblem in der convertTokenData-Objektausgabe wurde in v5.5.5 (2026-09-20) behoben; verwenden Sie keine Versionen darunter. Quelle: research-log §I, Style Dictionary v5.0.0, v5.5.5, v5 Migration.
• Fluid Typography Guide — Bei der Definition von Typografie-Tokens präsentieren Sie zusätzlich zu festen Größen die Option einer fluid Skala basierend auf clamp(min, preferred, max). Empfehlen Sie ein für das Projekt geeignetes Verhältnis der Modular Scale (1,125 Major Second ~ 1,618 Golden Ratio) und verweisen Sie auf den Utopia-Ansatz (Interpolation zwischen zwei Skalen für kleine/große Bildschirme). Quelle: research-log §E.
• Fluid Spacing Guide — Präsentieren Sie für Spacing-Tokens neben Fixed (fest) auch Fluid (clamp()) und Adaptive (Umschaltung je Breakpoint) Optionen. Geben Sie die Regel Internal ≤ External (Innenabstand ≤ Außenabstand) an. Quelle: research-log §F.

Referenzen

• references/token-principles.md — Details zu Token-Design-Prinzipien
• templates/design-tokens.md — Ausgabeformat der Token-Spezifikation
• ../../references/visual-change-protocol.md — Visuelle Priorität · Teiländerungs-Isolation (SSOT)