Communitygithub.com

Design-System-Sync

Verwendet, wenn eine Design-Aufgabe in einem Projekt beginnt, dessen Designsystem bereits im Code lebt (UI-Paket, Design-Tokens, Komponentenbibliothek), aber nicht im Design-Tool vorhanden ist, oder wenn das Designsystem, Tokens oder Komponenten in das Tool importiert oder Änderungen aus dem Guide zurück in den Code übertragen werden sollen.

Was ist Design-System-Sync?

Dieses Skill synchronisiert ein im Code definiertes Designsystem mit einem Design-Tool (Paper, Figma, HTML) und umgekehrt. Der Import überträgt Code-Tokens und ausgewählte Komponenten unter denselben Namen in das Tool, während der Export Änderungen aus dem Tool-Guide als geprüften Diff zurück in den Code überführt. Es erkennt automatisch die Wertquelle, erstellt ein Inventar, fragt nach Konflikten und zeichnet nur abgestimmte Werte in der `design-sync.json` auf. Der Code bleibt die maßgebliche Quelle, bis ein Export explizit genehmigt wird. Das Skill unterstützt die Adapter aus `references/adapters/`, listet Konflikte klar auf und stellt sicher, dass keine Werte stillschweigend überschrieben werden. Es eignet sich für Teams, die ihr Designsystem im Code pflegen und im Tool einen aktuellen, abgestimmten Spiegel benötigen, ohne doppelte Arbeit oder Drift.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/diego3g/craft/tree/HEAD/skills/craft-sync

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht Design-System-Sync?

Überblick

Wenn ein Designsystem bereits im Code lebt, sollte das Design-Tool es spiegeln, nicht neu erfinden.

  • Import bringt die Code-Tokens und die vom Entwickler ausgewählten Komponenten unter denselben Namen in das Tool.
  • Export überträgt Änderungen aus dem Guide des Tools als geprüften Diff zurück in den Code.

Eine kleine Datei im Projekt-Root, design-sync.json, merkt sich den letzten Sync-Stand. Der Code bleibt die maßgebliche Quelle, bis der Entwickler etwas anderes sagt: Änderungen werden zuerst im Tool gezeichnet und landen erst durch einen genehmigten Export im Code.

Wann verwenden

  • Eine Design-Aufgabe beginnt in einem Projekt mit einem Designsystem im Code und keinem Guide im Tool. craft-setup und craft übergeben dann an dieses Skill.
  • „Importiere / bringe unser Designsystem (Tokens, Komponenten) in Paper / Figma / das Design-Tool.“
  • „Wende / pushe / sync die Änderungen aus dem Guide in den Code.“

Wann NICHT verwenden

  • Kein Designsystem im Code: craft-system (Erstellmodus).
  • Eine Review, Optionen oder eine kleine Bearbeitung in einem solchen Projekt: Diese Skills arbeiten mit dem Code wie er ist.
  • Ein einzelner vom Entwickler diktierter Token-Wert („mach den Akzent #3d7f69 im Code“): direkt bearbeiten, design-sync.json für diesen Namen aktualisieren, angeben was betroffen ist.

Vor dem Start

  1. Lies DESIGN.md (Brand sagt, wo das System lebt) und design-sync.json falls vorhanden.
  2. Wähle den Adapter deines Tools in references/adapters/ (paper.md, figma.md, html.md). Passt kein Adapter zu deinem Tool, führe dieselben Verben in deinem Tool aus und gib an, welche du manuell zugeordnet hast. Gibt es gar kein Design-Tool, baue in HTML (html.md). Wenn du nur ein Bild hast, gib an, dass daraus gelesene Werte Schätzungen sind.

design-sync.json

{
  "source": "packages/ui/tokens.css",
  "tool": "paper: file 'Fieldnote', page 'Guide'",
  "naming": "CSS-Custom-Property-Namen wie im Quellcode",
  "synced": "2026-11-15",
  "tokens": { "--color-accent": "#2e6b57", "--radius-md": "10px" },
  "components": { "Button": "drawn", "Badge": "drawn", "Input": "in code only" }
}
  • tokens enthält nur die Werte, auf die beide Seiten beim letzten Sync sich geeinigt haben.
  • Ein Komponenten-Import ändert nur den eigenen components-Eintrag.

Import (Code → Design-Tool)

  1. Erkennen mit den Signalen. Finde die Wertquelle (die Token-Quelle, kein generiertes Output) und die Namensregel, die das Tool verwenden wird. Zwei UI-Pakete → beide auflisten und fragen, welches die Quelle ist.

  2. Inventar erstellen, dann stoppen. Verwende das Inventarformat:

    • Tokens nach Rolle, mit Anzahlen und Pfaden;
    • Komponenten (gruppiert mit Anzahlen bei mehr als etwa 15);
    • Richtliniendokumente;
    • Lücken;
    • Konflikte: jeder Name, der im Tool bereits mit einem anderen Wert existiert, und jeder Token-Typ, den das Tool nicht halten kann.

    Frage, welche Komponenten jetzt gezeichnet werden sollen, schlage 3–6 für die nächsten Bildschirme vor, und wie jeder Konflikt gelöst werden soll. Zeichne nie standardmäßig alles.

  3. Im Tool bauen nach den Antworten:

    • Tokens unter der Namensregel registrieren; überschreibe niemals einen Tool-Wert, den der Entwickler nicht geklärt hat;
    • eine Seite für das Fundament des Guides erstellen, mit Richtliniendokumenten als Legende;
    • einen Komponentenindex erstellen: Name, Code-Pfad, Status (drawn / in code only), mit ausgefüllten Varianten sobald gezeichnet;
    • die ausgewählten Komponenten mit ihrer Zustandsmatrix zeichnen, unter Verwendung der Werte aus dem Code. Ein Zustand, den der Code nicht definiert, wird gezeichnet und als „proposed“ gekennzeichnet.
  4. Selbstprüfung. Rendere den Guide. Wenn der Code die Komponente rendern kann (Storybook, eine Demo-Seite), vergleiche in derselben Größe. Andernfalls gib an, dass die Werte aus dem Code gelesen, ungerendert sind.

  5. Aufzeichnen:

    • design-sync.json schreiben (alle Token-Werte sind jetzt auf beiden Seiten gleich, plus Komponenten-Status);
    • in DESIGN.md bekommt Brand „Designsystem-Quelle: <path>; der -Guide spiegelt sie“, und das Entscheidungsprotokoll erhält eine datierte Importzeile;
    • wenn es keine DESIGN.md gibt, eine erstellen, deren erste Zeile <!-- sync record only: run craft-setup for the brief --> ist, mit nur Brand und dem Entscheidungsprotokoll. craft behandelt eine DESIGN.md ohne Product-Abschnitt als fehlend.

Import einer einzelnen Komponente (von craft)

Der Entwickler hat bereits zugestimmt, das System zu spiegeln, daher gibt es keinen Inventar-Stopp:

  • diese Komponente zeichnen;
  • ihren components-Eintrag auf drawn setzen;
  • tokens unverändert lassen.

Wenn das Tool noch keinen Guide hat, oder der Entwickler einem Import nie zugestimmt hat (oder ihn abgelehnt hat), einmal fragen: „Input existiert nur im Code. Soll ich ihn zuerst in den Guide importieren?“

Export (Design-Tool → Code)

  1. Werte lesen (Tool-Werte via Adapter und Code-Werte) nach Name.

  2. Jeden Namen klassifizieren mit design-sync.json und dem Diff-Format:

    • jetzt gleich → synchron;
    • Guide geändert → vorschlagen;
    • Code geändert → anbieten, den Guide zu aktualisieren;
    • beide geändert → die drei Werte zeigen und fragen, welcher gewinnt.

    Ohne design-sync.json jeden Unterschied auflisten und für jeden die Richtung erfragen.

  3. Bearbeitungen vorschlagen an den Quelldateien (niemals einem generierten Output): Datei und Zeile, was jeweils betroffen ist, und den Kontrast für Farben. „Proposed“-Zustände und ersetzte Schriften sind keine zu exportierenden Änderungen. Stoppen.

  4. Nur das Genehmigte anwenden, den Guide für alles aktualisieren, was zugunsten des Codes entschieden wurde, und die Checks des Projekts ausführen (Lint, Typecheck, Tests, visuelle Tests), oder sagen, dass es keine gibt.

  5. Aufzeichnen:

    • design-sync.json mit den nun auf beiden Seiten gleichen Werten aktualisieren;
    • eine datierte Zeile zum Entscheidungsprotokoll in DESIGN.md hinzufügen;
    • offene Konflikte zu Offenen Fragen hinzufügen.

Regeln

RegelWarum
Gleiche Namen in Code und Tool, nach einer schriftlichen NamensregelEin Name pro Entscheidung; keine Zuordnung, die abdriften kann
design-sync.json zeichnet nur abgestimmte Werte aufOhne den zuletzt abgestimmten Wert ist „Wer hat es geändert?“ eine Schätzung
Inventar und Auswahl vor dem Zeichnen; Konflikte dort auflistenGroße Pakete und vorhandene Tool-Tokens brauchen die Zustimmung des Entwicklers
Werte aus dem Code, niemals aus ScreenshotsScreenshots runden Farben und Größen
Fehlende Zustände als „proposed“ zeichnenDer Guide darf nicht behaupten, der Code täte etwas, was er nicht tut
Export schlägt vor, dann stoppt; bearbeitet die Quelle, nicht generiertes OutputCode wird an Benutzer ausgeliefert; eine generierte Datei wird vom nächsten Build überschrieben
Beide geändert → nachfragenDas Überschreiben einer Seite verliert die Entscheidung einer Person
Code ist die maßgebliche Quelle, bis der Entwickler etwas anderes sagtPasst zu „Code schlägt ein veraltetes Briefing“

Fertig wenn

  • Import: Inventar und Konflikte geklärt; ausgewählte Komponenten gezeichnet; Guide gerendert (oder „ungerendert“ vermerkt); design-sync.json und DESIGN.md geschrieben.
  • Eine Komponente: gezeichnet, mit aktualisiertem Status.
  • Export: genehmigte Bearbeitungen angewendet, Checks durchgeführt (oder „keine“ vermerkt), design-sync.json aktualisiert, Konflikte entschieden oder offen.

Häufige Fehler

GedankeRealität
„Der Code hat das System, also braucht das Setup nur das Briefing“Biete den Import an, sonst bekommt das Tool nie einen Guide und die Bildschirme driften vom Code ab.
„Ich baue das Fundament und einen Index, Komponenten später“Zeige das Inventar und frage, welche Komponenten jetzt gezeichnet werden sollen.
„Ich benenne --sand-200 in einen Rollennamen um, während ich importiere“Behalte den Namen aus dem Code; schlage eine Rolle als offene Frage vor.
„Das Tool hat bereits --color-accent, ich aktualisiere es“Das ist ein Konflikt für den Inventar-Stopp, kein stilles Überschreiben.
„Guide und Code unterscheiden sich, also ist der Guide veraltet“Prüfe design-sync.json: es könnte die nicht exportierte Änderung des Entwicklers sein.
„Der Diff ist winzig, ich wende ihn einfach an“Vorschlagen, stoppen, dann anwenden und die Checks des Projekts ausführen.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Verwandte Skills