docs: Guides für Farben, Variablen, Theme-Optionen, Schriften, Snapshots und Schleifen-Inhalte

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs/guides/divi-design-system.md

@@ -7,7 +7,8 @@
   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.
+- **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.
 
@@ -20,8 +21,32 @@ 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 im
-   Divi-Builder anzulegen, statt feste Werte zu verteilen.
+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
 
@@ -45,14 +70,10 @@ Regeln:
   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` – vor jeder Änderung legt LIT MCP einen Snapshot an
-  (je Bereich die letzten 20); wiederherstellen mit `snapshot_id`.
+- `lit/divi-design-snapshots` / `lit/divi-design-restore` – Snapshots listen und wiederherstellen (siehe
+  „Snapshots und Wiederherstellen“).
 
-Ablauf jeder Änderung: Aufruf ohne `confirm` = Probelauf (`confirm_required` mit `diff`, betroffenen Seiten und
-`design_rev`), dem Nutzer die Änderung zeigen, dann derselbe Aufruf mit `confirm: true` und `design_rev`. 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, kommt `conflict` – kurz warten und den
-Probelauf wiederholen.
+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
@@ -130,3 +151,109 @@ Einzelne Module bekommen Presets mit `lit-divi-insert`, `lit-divi-update` und `l
   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.