diff --git a/docs/analysen/adaptive-widgets-bericht-2026-11-18.md b/docs/analysen/adaptive-widgets-bericht-2026-11-18.md new file mode 100644 index 0000000..47e3403 --- /dev/null +++ b/docs/analysen/adaptive-widgets-bericht-2026-11-18.md @@ -0,0 +1,173 @@ +# Abschlussbericht: Adaptive Widgets und Premium-Design v1.6 + +Stand: 18.11.2026. +- Branch: `feature/adaptive-widgets`, abgezweigt vom Stand `feature/design-iteration-1` einschließlich der beiden Doku-Commits von Lars. +- Per Fast-Forward auf `develop` übernommen und über `deploy-test.yml` auf der Testinstanz bereitgestellt. +- **Kein Merge nach `main`.** `develop` liegt 73 Commits vor `main`. + +| Schritt | Stand | +|---|---| +| Commit Umsetzung | `0bfb534` | +| CI Feature-Branch | Lauf 4834 grün | +| Deploy Testinstanz | Lauf 4835 erfolgreich, `/up` 200 | +| Bericht | dieser Commit | + +Entscheidung: ADR-38 im zentralen Protokoll. Technische Dokumentation: +- `docs/architektur/cms-widget-registry.md` §§2–4, 8, 9, 12 +- `docs/architektur/designsystem.md` §13 + +## 1. Grundlage und Abweichungen vom Kit + +Grundlage war der Repository-Stand `docs/Brand-UI-Kit/12_premium_widgets_adaptiv_v1.6`: Komponenten, CSS, `layout-profiles.json`, Registry-Hinweise, Beispiele und Referenzscreenshots. Die Ordner 07–12 sind im Repository nicht versioniert (untracked). Übernommen wurden Code und CSS, angepasst an die tatsächliche Struktur. Die Kit-Ordner selbst wurden nicht eingecheckt. + +| Kit v1.6 | Umsetzung | Grund | +|---|---|---| +| Kennungen `lf-brand-hero`, `lf-editorial-bild-text` | bestehende Kennungen `hero` und `image_text` als kompatible Weiterentwicklung | Kennungen und Revisionen bleiben erhalten | +| Varianten `photo-split`, `editorial-solid` | `photo_split`, `editorial_solid` | Variantenkennungen der Registry: `^[a-z][a-z0-9_]*$` | +| `settings.image_side` | Variante `image_left` / `image_right` | keine doppelte Einstellung | +| `settings.image_focus {x,y}` | `data.focus_x`, `data.focus_y` (0–100) | `settings` trägt nur Aufzählungswerte | +| Überschriftenebene H1/H2/H3 frei | „Automatisch“ (erstes Widget der Seite = H1), H2, H3 | Regel „genau eine H1 je Seite“; Widerspruch nicht still aufgelöst, sondern dokumentiert | +| Linkziele nur `https`, Pfad, Anker | bestehende `SafeUrl`-Regel (zusätzlich `http`) | Repository-Regel gilt | +| Einstiegsbild immer sofort laden | nur das erste Widget der Seite sofort, alle anderen verzögert | bestehende Ladeprioritäten | +| CSS v1.6 | übernommen nach `resources/css/components/lf-hero.css` und `lf-bild-text.css` | zusätzlich: Überschriften erben Farbe (globale h1–h3-Regeln), Unterstreichung als Block, Fläche „clear“ übernimmt die Farben dunkler Abschnitte, Strahlen-Akzent, Fokusfarbe aus den Tokens | + +Das frühere Hero- und Bild-und-Text-CSS sowie der Randlos-Mechanismus der Designiteration 1 sind entfernt. Es laden keine alten und neuen Stylesheets parallel. + +## 2. Gemeinsamer Layoutmechanismus (ADR-38) + +In der bestehenden Registry (`WidgetType`) erklärt jede Art: +- **zulässige Rasterbreiten** (`supportedUnits()`); die Mindestbreite ist daraus abgeleitet; +- **Höhen** aus einem gemeinsamen Vokabular (`auto`, `compact`, `normal`, `large`, `spacious`, `fill`). Sie werden als `settings.height` gespeichert und wie jede Einstellung geprüft; +- **Darstellungsmodi** (`stages()`) und das **Verhalten bei wenig Platz** (`narrowBehavior()`). + +Wirkung: +- Ein Platz mit nicht unterstützter Breite wird beim Speichern abgewiesen: „… ist für Plätze mit 3 oder 4 Rastereinheiten vorgesehen; dieser Platz hat 2“. +- Der Platzkopf im Editor warnt vorher, und die Widget-Auswahl nennt die zulässigen Breiten. +- Die Höhe erscheint als Klasse `widget-height-*` an der Hülle. +- Die Ansichten reagieren über Container-Abfragen auf die tatsächliche Breite. +- Es gibt keine zweite Registry, kein zweites Abschnittsmodell und keine Migration. + +| Widget | Breiten | Höhen | +|---|---|---| +| Einstieg (Hero) | 3, 4 | compact (mind. 400 px), normal (512 px), large (640 px) | +| Bild und Text | 1–4 | compact, normal, spacious | +| Handlungsaufruf | 1–4 | auto, fill (gleich hoch wie die Nachbarplätze) | +| Überschrift, Fließtext, Karten, Programmkarten | 1–4 | – (nach Inhalt) | +| FAQ | 2–4 | – | + +Die Gestaltung der Bestandswidgets bleibt unverändert. Für schmale Plätze kamen hinzu: +- Umbruch langer Wörter und Adressen; +- Schaltflächen mit `overflow-wrap`, `max-width: 100 %` und mittig ausgerichtetem Text. + +## 3. Premium-Widgets + +**Einstieg (`hero` Version 2):** +- Varianten „Foto mit Textfläche“ und „Markenfläche“. +- Drei Höhen, Label, Überschrift und Ebene, Beschreibung, Bild aus dem öffentlichen Medienbereich (Auswahl oder Hochladen). +- Bildfokus (zwei Schieberegler) und Alternativtext. +- Zwei Schaltflächen und ein Akzent: Unterstreichung, Unterstreichung mit Signalstrahlen oder keiner. +- Ab 860 px Containerbreite die Komposition aus dem Kit, darunter der technische Sicherheitsumbruch (Foto 16:9 über dem Text). + +**Bild und Text (`image_text` Version 3):** +- Fläche creme, ohne eigene Fläche oder navy. +- Bild links oder rechts, drei Höhen, Label, Überschrift und Ebene. +- Formatierter Text (bereinigt), Bild, Fokus, Alternativtext, zwei Schaltflächen. +- Darstellung nach Containerbreite: + +| Containerbreite | Darstellung | +|---|---| +| unter 540 px | gestapelt | +| 540–899 px | flacher Bildstreifen | +| ab 900 px | zweispaltig | + +Die Grenzwerte aus dem Kit haben sich im CMS bewährt und sind unverändert. + +**Bestehende Daten:** +- `hero` Version 1 wird beim Lesen angehoben: `standard`/`stage` → `photo_split`, `highlight`/`editorial` → `editorial_solid`. Der Fokuspunkt wird in Prozent umgerechnet, und nicht mehr vorhandene Einstellungen entfallen. +- `image_text` Version 2 wird ebenso angehoben: Bildformat entfällt, Fokus in Prozent. +- Gespeicherte Revisionen bleiben unverändert. Die data-Schlüssel sind gleich geblieben, damit ein Code-Rollback darstellbar bleibt (siehe `cms-widget-registry.md` §9). + +## 4. Editor + +- **Bearbeitungsdialog:** Reiter **Inhalt**, **Medien** und **Darstellung**, generisch aus der Registry. + - Varianten und Höhen sind Auswahlknöpfe mit Symbol. + - Der Bildfokus wird mit Schiebereglern eingestellt. + - Weitere Darstellungsparameter sind Auswahllisten mit dem Hinweis „Vorgabe der Darstellung“. + - Der Reiter Darstellung nennt die zulässigen Platzbreiten und das Verhalten bei wenig Platz. +- **Live-Vorschau im Dialog:** + - Derselbe Renderer wie die Website, in wählbarer Platzbreite: Smartphone 390 px oder die zulässigen Einheiten mit 310, 640, 960 bzw. 1300 px. + - Verkleinert auf die Dialogbreite; Änderungen erscheinen sofort. +- **Abschnitts- und Widget-Einstellungen sind getrennt:** + - Abschnitt: Raster, Hintergrund, Breite, Abstand, Trenner. + - Widget: Anordnung, Fläche, Höhe, Bild, Fokus, Texte, Schaltflächen, Akzent. + +## 5. Tests und praktische Abnahme + +| Prüfung | Ergebnis | +|---|---| +| `php artisan test` | 199 Tests grün | +| Pint (Code-Pfade) | sauber | +| Build | erfolgreich (Nunito 900 zusätzlich lokal ausgeliefert) | +| CI | 4834 grün | +| Deploy | 4835 erfolgreich | +| 12 bestehende öffentliche Seiten (Status, Titel, Text) vor und nach dem Deploy | unverändert | +| Szenario 1: `/designreferenz`, `/praevention-im-alltag`, `/referenz-abschnitte`, `/t1-landingpage` im Editor geöffnet und unverändert gespeichert | 4/4 ohne Fehler | +| Redaktionsablauf auf Test (`/premium-referenz`, über die Oberfläche) | 16 von 18 Prüfungen im Skript bestanden; die beiden Abweichungen sind Prüffehler, nicht Anwendungsfehler (siehe unten) | +| Matrix lokal (`/pruefmatrix`, mit Kit-Motiven) und auf Test (`/premium-referenz`), 390/768/1200/1440/1920 px | kein seitlicher Überlauf, kein abgeschnittener Text oder Button, genau eine H1 | +| Rahmen (Kopfzeile, Menü, Tastatur, CLS, Bewegung reduzieren) auf Test | 18/18 | + +**Neue Tests in der Suite:** +- `CmsPremiumWidgetsTest`: Upgrades, Varianten, Höhen, Akzente, Fläche, Sanitizing, unsichere Links, Fokusgrenzen, alle Widgets in jeder zulässigen bzw. unzulässigen Breite, Höhe „fill“. +- Editortest: Premium-Einstieg mit Höhe, Ebene, Akzent, Fokus und zwei Schaltflächen speichern und veröffentlichen; Dialogfelder und Live-Vorschau. +- Registry-Tests zum Layoutvertrag. + +**Bewusst angepasste Tests:** +- Einstieg braucht 3 oder 4 statt mindestens 2 Einheiten. +- `image_text` ist Version 3. +- Klassen der neuen Ansichten. +- Die Hero- und Bild-Tests der Designiteration 1 sind ersetzt. + +**Redaktionsablauf auf der Testinstanz (Szenarien 2–11):** +- Angelegt über die Oberfläche: Einstieg in 4/4 (groß, normal) und 3/4 (kompakt, Markenfläche, H3, lange Überschrift und Schaltfläche), Aufruf mit voller Höhe, Bild und Text in 4/4, 3/4, 2/4 und 1/4 mit allen Höhen und Flächen, gemischt mit Überschrift, Fließtext und Karten. +- Danach im Editor geändert: Überschrift, Beschriftung, Höhe und Fokus. + - Die Live-Vorschau zeigt Höhe, Fokus (80/30 %) und Text sofort. + - Die Smartphone-Breite zeigt den Sicherheitsumbruch. +- Veröffentlicht; die öffentliche Seite zeigt alle Änderungen. + +**Die zwei Abweichungen im Skript:** +- Es erwartete 15 Widgets; angelegt waren 13. Die Zahl im Skript war falsch. +- Der Vergleich Vorschau gegen öffentliche Seite meldete einen Unterschied. Das genaue Diff zeigt als einzigen Unterschied den beabsichtigten Vorschauhinweis „Vorschau einer unveröffentlichten Revision“. Das Markup der Widgets ist identisch. + +**Bilder:** +- Lokal wurden die Kit-Motive (`09_hero_widget/assets/lara-felix-park-hero.webp`, `10_bild_text_widget/assets/lara-felix-park.webp`) für den Sichtvergleich mit den Kit-Screenshots verwendet; die Darstellung entspricht ihnen. +- Auf der Testinstanz stehen gekennzeichnete Platzhalter. Begründung: Alles, was im Editor gespeichert wird, ist über `/medien/cms/…` öffentlich abrufbar, und die öffentliche Bildverwendung ist laut Kit nicht freigegeben. + +**Screenshots** (Testinstanz, Platzhalter) unter `docs/analysen/adaptive-widgets-screenshots/`: +- Referenzseite bei 1440, 768 und 390 px +- Dialog „Darstellung“ +- Live-Vorschau bei 390 und 1300 px + +## 6. Verbleibende Einschränkungen + +- **Kit-Dateien verändert (mein Fehler):** + - Ein Pint-Lauf ohne Pfadangabe hat vier untracked PHP-Beispieldateien im Kit umformatiert (nur Leerraum und Klammern): + - `11_bild_text_widget_v1.5/laravel/app/Support/LfBildTextPayload.php` + - `11_bild_text_widget_v1.5/laravel/examples/registry-adapter.example.php` + - `11_bild_text_widget_v1.5/laravel/tests/LfBildTextPayloadTest.php` + - `12_premium_widgets_adaptiv_v1.6/laravel/app/Support/LfBildTextPayload.php` + - Die übrigen 112 Kit-Dateien sind bytegleich mit dem Archiv. + - Das Zurückschreiben aus `Downloads/Lara_Felix_Brand_UI_Kit_v1.6_Adaptive_Premium_Widgets.zip` wurde von der Rechteprüfung blockiert. Bitte diese vier Dateien aus dem Archiv wiederherstellen. +- **Freigaben:** Die öffentliche Verwendung der Lara-&-Felix-Motive ist nicht freigegeben. Die Testseiten zeigen deshalb Platzhalter. +- **Validierungsmeldungen auf Englisch:** Es gibt kein deutsches Sprachpaket (`lang/de` fehlt), zum Beispiel „The … field is required when … is present“. Das betrifft die ganze Anwendung. +- **Livewire-Timing:** Werden Felder schneller ausgefüllt, als die Live-Aktualisierung zurückkommt (unter etwa 0,5 s, nur bei automatischer Eingabe beobachtet), kann ein gerade verlassenes Feld überschrieben werden. Bei menschlichem Tempo trat das nicht auf. +- **Eingeklappter Abschnitt bei der Neuanlage:** „Seite und Suchmaschinen“ bleibt nach dem Bearbeiten einer Seite auch beim Anlegen eingeklappt, weil Filament den Zustand merkt. Das Verhalten stammt aus Iteration 2. +- **Vorschau im Platz:** Sie ist über 28 rem gekürzt; der Einstieg wird dort beschnitten. Vollständig zeigen ihn die Live-Vorschau im Dialog und die Seitenvorschau. +- **Keine responsiven Bildvarianten:** `srcset` fehlt; die Ableitungen gehören in die Hintergrundverarbeitung. +- **Code-Rollback auf die Designiteration:** Ältere Software stellt `hero` v2 und `image_text` v3 „bestmöglich“ dar, kann sie aber nicht speichern (§9 der Registry-Dokumentation). +- **Größe der Repository-Historie:** Mit dem Fast-Forward sind Lars' Commits `5dccbbc` und `3cdb36e` auf `develop` gelandet. Sie enthalten die Kit-Originalbilder und das Kit-ZIP (27,7 MB) in der Historie. Das ZIP ist in `3cdb36e` wieder entfernt, bleibt aber in der Historie. +- **UX-Abnahme:** Die Bedienung durch den Betreiber steht aus (ADR-38 „UX-Abnahme offen“). + +## 7. Auf der Testinstanz angelegt + +- Seite `/premium-referenz` (veröffentlicht), mit Platzhalterbildern `cms/platzhalter-*` (Dateinamen mit Zufallssuffix). +- Neue Entwurfsrevisionen (nicht veröffentlicht) auf `/designreferenz`, `/praevention-im-alltag`, `/referenz-abschnitte` und `/t1-landingpage` aus dem Speichertest. Die veröffentlichten Stände sind unverändert. diff --git a/docs/analysen/adaptive-widgets-screenshots/01-1440-premium-referenz.jpg b/docs/analysen/adaptive-widgets-screenshots/01-1440-premium-referenz.jpg new file mode 100644 index 0000000..e2bd70d Binary files /dev/null and b/docs/analysen/adaptive-widgets-screenshots/01-1440-premium-referenz.jpg differ diff --git a/docs/analysen/adaptive-widgets-screenshots/02-768-premium-referenz.jpg b/docs/analysen/adaptive-widgets-screenshots/02-768-premium-referenz.jpg new file mode 100644 index 0000000..68412fa Binary files /dev/null and b/docs/analysen/adaptive-widgets-screenshots/02-768-premium-referenz.jpg differ diff --git a/docs/analysen/adaptive-widgets-screenshots/03-390-premium-referenz.jpg b/docs/analysen/adaptive-widgets-screenshots/03-390-premium-referenz.jpg new file mode 100644 index 0000000..d497260 Binary files /dev/null and b/docs/analysen/adaptive-widgets-screenshots/03-390-premium-referenz.jpg differ diff --git a/docs/analysen/adaptive-widgets-screenshots/04-editor-dialog-darstellung.jpg b/docs/analysen/adaptive-widgets-screenshots/04-editor-dialog-darstellung.jpg new file mode 100644 index 0000000..c3beae4 Binary files /dev/null and b/docs/analysen/adaptive-widgets-screenshots/04-editor-dialog-darstellung.jpg differ diff --git a/docs/analysen/adaptive-widgets-screenshots/05-editor-live-vorschau-390.jpg b/docs/analysen/adaptive-widgets-screenshots/05-editor-live-vorschau-390.jpg new file mode 100644 index 0000000..370614f Binary files /dev/null and b/docs/analysen/adaptive-widgets-screenshots/05-editor-live-vorschau-390.jpg differ diff --git a/docs/analysen/adaptive-widgets-screenshots/06-editor-live-vorschau-1300.jpg b/docs/analysen/adaptive-widgets-screenshots/06-editor-live-vorschau-1300.jpg new file mode 100644 index 0000000..057c077 Binary files /dev/null and b/docs/analysen/adaptive-widgets-screenshots/06-editor-live-vorschau-1300.jpg differ