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-setupundcraftü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.jsonfür diesen Namen aktualisieren, angeben was betroffen ist.
Vor dem Start
- Lies
DESIGN.md(Brand sagt, wo das System lebt) unddesign-sync.jsonfalls vorhanden. - 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" }
}
tokensenthä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)
-
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.
-
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.
-
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.
-
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.
-
Aufzeichnen:
design-sync.jsonschreiben (alle Token-Werte sind jetzt auf beiden Seiten gleich, plus Komponenten-Status);- in
DESIGN.mdbekommt Brand „Designsystem-Quelle:<path>; der -Guide spiegelt sie“, und das Entscheidungsprotokoll erhält eine datierte Importzeile; - wenn es keine
DESIGN.mdgibt, eine erstellen, deren erste Zeile<!-- sync record only: run craft-setup for the brief -->ist, mit nur Brand und dem Entscheidungsprotokoll.craftbehandelt eineDESIGN.mdohne 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 aufdrawnsetzen; tokensunverä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)
-
Werte lesen (Tool-Werte via Adapter und Code-Werte) nach Name.
-
Jeden Namen klassifizieren mit
design-sync.jsonund 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.jsonjeden Unterschied auflisten und für jeden die Richtung erfragen. -
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.
-
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.
-
Aufzeichnen:
design-sync.jsonmit den nun auf beiden Seiten gleichen Werten aktualisieren;- eine datierte Zeile zum Entscheidungsprotokoll in
DESIGN.mdhinzufügen; - offene Konflikte zu Offenen Fragen hinzufügen.
Regeln
| Regel | Warum |
|---|---|
| Gleiche Namen in Code und Tool, nach einer schriftlichen Namensregel | Ein Name pro Entscheidung; keine Zuordnung, die abdriften kann |
design-sync.json zeichnet nur abgestimmte Werte auf | Ohne den zuletzt abgestimmten Wert ist „Wer hat es geändert?“ eine Schätzung |
| Inventar und Auswahl vor dem Zeichnen; Konflikte dort auflisten | Große Pakete und vorhandene Tool-Tokens brauchen die Zustimmung des Entwicklers |
| Werte aus dem Code, niemals aus Screenshots | Screenshots runden Farben und Größen |
| Fehlende Zustände als „proposed“ zeichnen | Der Guide darf nicht behaupten, der Code täte etwas, was er nicht tut |
| Export schlägt vor, dann stoppt; bearbeitet die Quelle, nicht generiertes Output | Code wird an Benutzer ausgeliefert; eine generierte Datei wird vom nächsten Build überschrieben |
| Beide geändert → nachfragen | Das Überschreiben einer Seite verliert die Entscheidung einer Person |
| Code ist die maßgebliche Quelle, bis der Entwickler etwas anderes sagt | Passt 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.jsonundDESIGN.mdgeschrieben. - Eine Komponente: gezeichnet, mit aktualisiertem Status.
- Export: genehmigte Bearbeitungen angewendet, Checks durchgeführt (oder „keine“ vermerkt),
design-sync.jsonaktualisiert, Konflikte entschieden oder offen.
Häufige Fehler
| Gedanke | Realitä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. |