WP-LIT-MCP/docs/guides/divi-design-system.md

Divi-Designsystem

lit-divi-design-system liest das Designsystem der Website live aus Divi:

• Globale Farben (colors): ID (gcid-…), Name, Wert und der Platzhalter für neue Inhalte, z. B. {{color:primary}} für die Primärfarbe oder {{color:Nachtblau}} für eine eigene globale Farbe. Die fünf Theme-Farben heißen primary, secondary, heading, body und link.
• Globale Variablen (variables): Zahlen, Texte, Bilder, Links (gvid-…), Platzhalter {{var:<Name>}}.
• Theme-Schriften (fonts): Überschrift und Fließtext, Platzhalter {{font:heading}} / {{font:body}}.
• Größen (sizes): Schriftgrößen, Inhaltsbreite und Spaltenabstand aus den Theme-Optionen. Alle 20 Theme-Optionen mit Standardwerten liefert lit/divi-theme-options-get (siehe „Theme-Optionen“).
• Presets (presets): Modul-Presets je Modul (kind: module, z. B. alle Button-Presets) und Gruppen-Presets (kind: group); default: true markiert das Standard-Preset eines Moduls.

Auf großen Websites eingrenzen: only (Liste aus colors, variables, presets) liefert nur diese Teile (Schriften und Größen sind immer dabei), module (z. B. "button") nur die Presets dieses Moduls; höchstens 200 Presets je Antwort (notes sagt, wenn es mehr gibt).

Regeln:

1. Vor dem Gestalten einer Seite das Designsystem lesen.
2. Globale Farben, Variablen und Presets vor festen Werten verwenden; feste Farben oder Schriften nur, wenn der Nutzer es ausdrücklich möchte.
3. Gibt es für einen Zweck noch keine Farbe, Variable oder kein Preset, dem Nutzer vorschlagen, es anzulegen (lit/divi-colors-set, lit/divi-variables-set, lit/divi-presets-set), statt feste Werte zu verteilen – zuerst Probelauf, nach Rückfrage confirm: true.
4. Das Designsystem wirkt auf alle Seiten der Website. Werte, Schriften und Abstände nennt der Nutzer; nichts erfinden und nie ohne seine Rückfrage bestätigen.
5. Alle Schritte eines Designwechsels (Schriften, Farben, Variablen, Theme-Optionen, Presets) beschreibt workflows, Abschnitt „Corporate Design übernehmen“.

Ablauf jeder Änderung

Presets, Farben, Variablen und Theme-Optionen (lit/divi-presets-set, lit/divi-presets-delete, lit/divi-colors-set, lit/divi-variables-set, lit/divi-theme-options-update) sowie lit/divi-design-restore und lit/divi-design-detach laufen gleich, alle über mcp-adapter-execute-ability:

1. Aufruf ohne confirm = Probelauf. Er schreibt nichts und antwortet mit confirm_required: diff (was sich ändert), je nach Werkzeug die betroffenen Seiten und warnings, dazu die design_rev.
2. Dem Nutzer die Änderung zeigen und erst nach seiner Antwort denselben Aufruf mit confirm: true und der design_rev senden (wo der Probelauf eine nennt).
3. Vor dem Schreiben legt LIT MCP einen Snapshot an; die Antwort nennt seine snapshot_id (siehe „Snapshots und Wiederherstellen“).
4. Hat sich der Bestand inzwischen geändert (z. B. im Divi-Builder), kommt rev_mismatch – neu prüfen. confirm: true ohne design_rev ergibt validation_failed; läuft gerade eine andere Änderung am selben Bereich, kommt conflict – kurz warten und den Probelauf wiederholen.

Eigene Schriften hochladen (lit/divi-fonts-upload) hat einen eigenen Probelauf und keinen Snapshot, siehe „Eigene Schriften hochladen“.

Presets anlegen, ändern, löschen

Über mcp-adapter-execute-ability:

• lit/divi-preset-get – ein Preset mit Einstellungen (attrs als Pfad → Wert wie bei lit-divi-node-get), verschachtelten Gruppen-Presets und den Seiten, die es verwenden (usage).
• lit/divi-presets-set – items mit module (z. B. "button") oder group (z. B. "font-body"):
  • neu: name + Einstellungen (name nur für neue Presets); ändern: preset (Name oder ID), optional rename (nur zusammen mit preset); Namen 1–100 Zeichen ohne HTML, innerhalb des Moduls bzw. der Gruppe eindeutig;
  • Einstellungen in attrs (Vollform, Platzhalter {{color:…}}, {{var:…}}, {{font:…}}) oder aus einem gestalteten Modul: from_node = {"post_id": 12, "id": "s0.r0.c1.m2"} (Pfad-ID aus lit-divi-outline);
  • Presets tragen nur Gestaltung – Texte, Links und Bilder gehören ins Modul (sonst validation_failed);
  • group_presets (nur Modul-Presets), z. B. {"font": "Button-Schrift"}; make_default: true macht das Preset zum Standard seines Moduls bzw. seiner Gruppe;
  • neue Gruppen-Presets brauchen das Modul, aus dem die Gruppe stammt: source_module oder from_node.
• lit/divi-presets-delete – nur Presets, die nirgends ausdrücklich verwendet werden (Seiten, Bibliothek, Theme Builder, verschachtelt in anderen Presets); sonst in_use mit den Fundstellen und dem Hinweis auf lit/divi-design-detach. Ein Standard-Preset darf gelöscht werden, auch wenn Module es ohne eigenes Preset nutzen: der Probelauf listet diese Seiten, danach zeigen sie das Divi-Standardaussehen. Das gilt auch für Standard-Gruppen-Presets: gelistet werden die Seiten mit Modulen, die diese Gruppe haben, aber kein eigenes Gruppen-Preset dafür.
• lit/divi-design-snapshots / lit/divi-design-restore – Snapshots listen und wiederherstellen (siehe „Snapshots und Wiederherstellen“).

Der Ablauf (Probelauf, confirm: true, design_rev) steht oben unter „Ablauf jeder Änderung“.

Rechte: Presets ändern verlangt das Recht, das Design anzupassen, und in Divis Rollen-Editor den Visual Builder. Konten ohne das Recht unfiltered_html (z. B. Redakteure) werden abgewiesen (forbidden), wenn vorhandene Presets HTML oder CSS enthalten – Divi würde es beim Speichern entfernen; dann einen Administrator bitten. Das gilt auch für das Löschen und für lit/divi-design-restore.

Presets auf Seiten zuweisen und Verweise entfernen

Einzelne Module bekommen Presets mit lit-divi-insert, lit-divi-update und lit-content-create (Stapel, group_presets, clear_overrides: siehe divi-shortform). Für viele Seiten gibt es zwei Werkzeuge (über mcp-adapter-execute-ability); beide ändern Seiteninhalt, nicht den Preset-Bestand.

lit/divi-presets-assign – ein Preset oder einen Stapel (preset) und/oder Gruppen-Presets (group_presets) allen Modulen eines Typs (module, z. B. "button") zuweisen:

• Filter: post_ids (1–50 Einträge; ohne die Angabe alle Fundstellen mit diesem Modultyp), only_without_preset: true (nur Module ohne Preset) oder only_with_preset: "<Name>" (nur Module, die dieses Preset schon tragen; nicht zusammen), clear_overrides: true (lokale Werte entfernen, die das Preset überdecken).
• preset: null, ein leerer Text und null oder ein leerer Text als Wert in group_presets werden abgewiesen (validation_failed): site-weit entfernt lit/divi-design-detach Verweise.
• Ablauf: erst ohne confirm aufrufen (Probelauf: confirm_required mit pages – je Seite post_id, title, status, die betroffenen Knoten mit Pfad-ID, Modul und Label sowie warnings zu überdeckten Werten –, dazu pages_count, nodes_count, skipped und gegebenenfalls blocked_ids). Dem Nutzer Seiten, Anzahl der Module und Überdeckungen zeigen und erst nach seiner Antwort denselben Aufruf mit confirm: true senden. Ohne confirm wird nie etwas geschrieben. Ist nichts zu ändern, antwortet der Probelauf normal mit „nichts zu tun“ (kein confirm_required).
• Je Aufruf werden höchstens 50 Seiten geschrieben. Die Antwort nennt saved (je Seite post_id, revision_id, Anzahl Module) und remaining: Ist remaining größer als 0, denselben Aufruf wiederholen – bereits umgestellte Module ändern sich nicht noch einmal. Jede Seite bekommt ihre eigene WordPress-Revision; einen Snapshot gibt es für Seiteninhalte nicht.
• Blockaden: Ohne post_ids verweigert der Aufruf alles und schreibt nichts: mit forbidden (und blocked_ids), wenn das Konto eine veröffentlichte, private oder geplante Fundstelle nicht bearbeiten darf, mit unsupported, wenn es mehr als 2000 solcher Fundstellen gibt.
• Mit post_ids blockieren nur die genannten Seiten, die Obergrenze von 2000 gilt nicht. Eine genannte veröffentlichte, private oder geplante Seite ohne Bearbeitungsrecht verweigert den ganzen Aufruf (forbidden mit blocked_ids, nichts wird geschrieben; der Probelauf listet sie unter blocked_ids). Eine genannte Seite, die nicht live ist (Entwurf usw.) und nicht bearbeitet werden darf, steht unter skipped. Gibt es mehr als 2000 Live-Fundstellen, entfällt die Vorabprüfung der Bearbeitungsrechte; dann steht auch eine genannte Live-Seite ohne Bearbeitungsrecht unter skipped statt in forbidden.
• Die Sperre für Live-Seiten ergibt sich allein aus der Fundstellensuche: Eine Live-Seite, die das Konto nicht bearbeiten darf, blockiert den ganzen Aufruf, auch wenn die Filter (only_with_preset, only_without_preset) auf dieser Seite nichts ändern würden.
• Scheitert das Speichern mitten im Lauf, meldet partial_write die bis dahin gespeicherten Seiten (saved): zuerst die genannte fehlgeschlagene Seite prüfen (lit-divi-outline), dann denselben Aufruf mit confirm: true wiederholen; bereits geänderte Module trifft er nicht noch einmal.
• Globale Module und die Bibliothek: Eine globale Instanz ([global <ID>] in lit-divi-outline) wird auf der Seite nicht umgeschrieben, sondern unter skipped gemeldet – „globales Modul – im Bibliothekseintrag ändern“, wenn das Konto Bibliotheks-IDs sehen darf, sonst „globales Modul – im Divi-Builder ändern“. Der Bibliothekseintrag selbst ist eine eigene Fundstelle und wird wie eine Seite umgeschrieben (wirkt dann überall, siehe divi-library). Seiten, die sich nicht ändern lassen (Divi 4, beschädigtes Markup), stehen mit dem Grund unter skipped.
• Rechte wie bei den Presets (Recht, das Design anzupassen, und Visual Builder) plus edit_post für jede Fundstelle; Theme-Builder-Layouts nach den Regeln des Theme Builders.

lit/divi-design-detach – Verweise auf ein Preset überall entfernen, damit es sich löschen lässt:

• Eingabe: preset ist ein Objekt {"module": "button", "preset": "<Name oder ID>"} bzw. {"group": "font", "preset": "<Name oder ID>"}, optional post_ids (Filter wie oben, 1–50).
• Ablauf wie bei jeder Änderung des Bestands: Probelauf (confirm_required mit Seiten und, wenn andere Presets das Gruppen-Preset verschachteln, diff und design_rev), dem Nutzer zeigen, dann confirm: true (mit design_rev, wenn der Probelauf eine nannte; veraltet: rev_mismatch, dann wird weder am Bestand noch an Seiten etwas geschrieben). Gibt es keine Verweise mehr, ist der Probelauf ein normales „nichts zu tun“.
• Ohne post_ids werden zuerst verschachtelte Verweise in anderen Presets entfernt (mit Snapshot, wie lit/divi-presets-set), danach die Seiten (höchstens 50 je Aufruf, remaining wie oben; ein weiterer Aufruf findet keine verschachtelten Verweise mehr und macht mit den Seiten weiter). Scheitert das Speichern der ersten Seite nach diesem Presets-Schritt, nennt die Fehlermeldung Snapshot und diff: die Verweise in den Presets sind dann schon entfernt. Mit post_ids werden nur diese Seiten geändert, Verweise in Presets bleiben.
• Die Module fallen auf das nächste Preset ihres Stapels zurück, sonst auf das Standard-Preset bzw. Divis Standardaussehen. Ein Standard-Preset wird nicht „entkoppelt“, weil Divi es ohne Verweis anwendet; detach entfernt dort nur ausdrückliche Verweise und sagt das in warnings. Zum Beenden der Standardwirkung das Preset löschen (lit/divi-presets-delete) oder mit make_default: false den Standard aufheben.
• Variablen: variable (Name oder ID) ersetzt jeden ganzen Verweis auf die Variable durch ihren aktuellen Wert, auch in Presets; danach lässt sie sich mit lit/divi-variables-set archivieren (löschen kann Divi sie nicht).
• Meldet die Antwort hidden_count größer als 0, können Seiten, die dieses Konto nicht lesen darf, noch Verweise enthalten; dann nennt sie den Hinweis auf lit/divi-presets-delete nicht.
• Danach lit/divi-presets-delete aufrufen (Probelauf, confirm, design_rev); es meldet kein in_use mehr, solange niemand das Preset neu zugewiesen hat.

Farben und Variablen anlegen und ändern

Über mcp-adapter-execute-ability, Ablauf wie oben, bis zu 50 Einträge je Aufruf in items. Farben und Variablen werden nie gelöscht, nur deaktiviert bzw. archiviert. Angelegte Farben und Variablen lassen sich sofort als {{color:<Name>}} und {{var:<Name>}} verwenden (divi-placeholders). Fehlerhafte Angaben (unbekannte ID, vergebener oder mehrdeutiger Name – die Meldung nennt dann die IDs –, ungültiger Wert) sammelt das Werkzeug unter fields als validation_failed; nichts wird gespeichert.

lit/divi-colors-set – je Eintrag:

• id nennt eine vorhandene Farbe (ID gcid-…, Name, Alias primary, secondary, heading, body, link oder Optionsname wie accent_color); ohne id entsteht aus label (Name) und color eine neue Farbe.
• color: Hex (#rgb, #rrggbb, auch mit Alpha), rgb()/rgba()/hsl()/hsla(), ein Farbname (z. B. red) oder der Platzhalter {{color:<Name>}} zusammen mit relative. So entstehen abgeleitete Farben, z. B. {"label": "Primär abgestuft", "color": "{{color:primary}}", "relative": {"lightness": 20}}; relative nimmt hue (−360 bis 360), saturation, lightness und opacity (je −100 bis 100).
• label benennt um, status: inactive deaktiviert die Farbe, active holt sie zurück.
• Die fünf Hauptfarben (primary, secondary, heading, body, link) ändern nur color, und nur mit einem festen Wert (kein Platzhalter, kein label, folder oder status).

lit/divi-variables-set – je Eintrag:

• id nennt eine vorhandene Variable (ID gvid-… oder Name); ohne id entsteht aus type (numbers, strings, images, links oder fonts), label und value eine neue. Der Typ einer Variable bleibt.
• value wird je Typ geprüft (Zahl, Text, Bild- oder Link-Adresse; Schrift-Variablen nur mit einem Schriftnamen, den Divi kennt). Aktive Variablen brauchen einen Wert.
• label benennt um, status: archived archiviert, active holt die Variable zurück.
• Vor dem Archivieren die Verweise ersetzen: lit/divi-design-detach mit variable setzt auf Seiten und in Presets den aktuellen Wert ein.

Der Probelauf beider Werkzeuge nennt die betroffenen Seiten und warnings. Die Rechte stehen unter „Rechte im Überblick“.

Theme-Optionen: Schriften, Größen und Layout

lit/divi-theme-options-get liefert je Theme-Option den gespeicherten Wert (null = nicht gesetzt), den wirksamen Wert, den Divi-Standard, Typ und Bereich bzw. Auswahl und die design_rev; keys grenzt auf einzelne Optionen ein. lit/divi-theme-options-update ändert sie mit set ({"Schlüssel": Wert}, Probelauf und confirm wie oben); null setzt eine Option auf den Divi-Standard zurück. Die 20 Schlüssel:

• Schriften: heading_font, body_font, primary_nav_font, secondary_nav_font – der exakte Name einer Schrift, die Divi kennt (Google-Schrift, Web-Safe-Schrift oder hochgeladene Schrift); bei unbekannten Namen antwortet das Werkzeug mit validation_failed und bis zu fünf Vorschlägen. Stärken: heading_font_weight, body_font_weight (100–900).
• Größen: body_font_size (10–32), body_header_size (22–72) und je eine Tablet- und Smartphone-Größe (tablet_body_font_size, phone_body_font_size, tablet_header_font_size, phone_header_font_size); sie erben vom nächstgrößeren Wert, solange sie nicht gesetzt sind.
• Text: body_font_height, body_header_height (Zeilenhöhe, 0,8–3), body_header_spacing (Buchstabenabstand, −2 bis 10), body_header_style (italic, uppercase oder underline; Divi kennt hier nur einen Wert).
• Layout: content_width (960–1920), gutter_width (1–4), section_padding, row_padding (je 0–10).

Die Hauptfarben gehören nicht hierher, sondern in lit/divi-colors-set. Theme-Optionen wirken auf die gesamte Website: den Nutzer ausdrücklich fragen. Jede Änderung legt einen Snapshot an.

Eigene Schriften hochladen

lit/divi-fonts-upload lädt eine Schrift von öffentlichen Adressen in Divis hochgeladene Schriften:

• files: je Format eine Datei (woff2, woff, ttf, otf) als öffentliche http(s)-Adresse, höchstens 5 MB je Datei; name: 1–100 Zeichen aus A–Z, a–z, 0–9, Leerzeichen, _ und - (keine Umlaute), kein Name einer Google-, Web-Safe- oder schon hochgeladenen Schrift (auch nicht in anderer Schreibweise); weights: "all" oder eine Liste aus 100 bis 900; generic_family: serif, sans-serif (Standard), monospace, cursive oder fantasy.
• Ablauf: Der Probelauf (ohne confirm) lädt die Dateien wirklich, prüft Inhalt und Format und nennt je Datei Format, Größe und SHA-256 – installiert aber nichts. Dem Nutzer zeigen, nach seiner Antwort denselben Aufruf mit confirm: true; er lädt die Dateien erneut.
• Fehler: font_fetch_failed (eine Adresse ist nicht erreichbar), font_invalid (die Datei passt nicht zum Format, etwa ein Bild als woff2), conflict (der Name ist vergeben), validation_failed (Name oder Angaben ungültig). Nichts wird gespeichert.
• Es gibt keinen Snapshot und keine Rücknahme per Werkzeug: Eine hochgeladene Schrift entfernt nur der Nutzer im Divi-Builder.
• Datenschutz: Hochgeladene Schriften liefert der eigene Server aus, nicht Google. Die Lizenz der Schrift klärt der Nutzer.
• Danach ist die Schrift ein gültiger Name für lit/divi-theme-options-update (z. B. body_font) und für Schrift-Variablen (lit/divi-variables-set mit type: fonts).

Snapshots und Wiederherstellen

Vor jeder Änderung an Presets, Farben, Variablen und Theme-Optionen sichert LIT MCP den Bereich (je Bereich bleiben die letzten 20 Snapshots; eine Gesamtgrenze von 8 MB entfernt ältere früher); die Antwort nennt die snapshot_id. Wäre der Bereich zu groß für eine Sicherung (über 2 MB), antwortet das Werkzeug mit snapshot_too_large und schreibt nichts.

• lit/divi-design-snapshots mit area (presets, colors, variables oder theme_options; Standard presets) listet die Snapshots eines Bereichs, neueste zuerst, mit Zeitpunkt, Werkzeug und Protokolleintrag.
• lit/divi-design-restore mit snapshot_id: Der Probelauf zeigt den Unterschied zum aktuellen Stand (diff, design_rev); nach Rückfrage confirm: true. Vorher sichert LIT MCP den aktuellen Stand selbst – auch eine Wiederherstellung lässt sich zurücknehmen. Ist die ID unbekannt oder verdrängt, kommt not_found.
• Was ein Restore macht, hängt vom Bereich ab: Farben, die es im Snapshot nicht gibt, entfallen. Variablen, die erst nach dem Snapshot entstanden, bleiben archiviert erhalten (Divi löscht keine). Theme-Optionen, die im Snapshot nicht gesetzt waren, kehren zum Divi-Standard zurück. Presets: Rechte-Regel unfiltered_html wie oben.
• Nicht gesichert und nicht wiederherstellbar: Seiteninhalt (dort gibt es die WordPress-Revision, die revision_id der Antwort) und hochgeladene Schriften.

Rechte im Überblick

Fehlt ein Recht, antwortet das Werkzeug mit forbidden; die Meldung nennt das Recht, den fehlenden Divi-Rollenwert bitte ein Administrator unter Divi → Rollen-Editor freigeben.

• Presets und Farben: edit_theme_options und in Divis Rollen-Editor „Visual Builder verwenden“.
• Variablen: dasselbe und der Variablen-Manager.
• Theme-Optionen: edit_theme_options und die Theme-Anpassung (Divis Customizer, kein Visual Builder nötig).
• Schriften hochladen: upload_files, edit_theme_options und „Eigene Schriften verwalten“.
• Snapshots listen: edit_theme_options; wiederherstellen: die Rechte des jeweiligen Bereichs.
• Seiten umschreiben (lit/divi-presets-assign, lit/divi-design-detach): zusätzlich edit_post je Seite.