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 <ID> ä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); 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 `snapshot_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.