Prompting Guide for Experience Modernization Agent prompting-guide

Die Migration folgt einem siebenstufigen Workflow:

1. Der Agent kratzt die Quellseite.
2. Es identifiziert die Abschnittsstruktur.
3. Es führt eine Authoring- und Analysefunktion durch.
4. Dabei wird der Inhalt Blockvarianten zugeordnet.
5. Er generiert einen Markdown.
6. Es schafft eine Importinfrastruktur.
7. Sie zeigt eine Vorschau des Ergebnisses an.

Der Agent analysiert Seiten mithilfe einer zweistufigen Hierarchie:

• Zuerst werden Abschnittsgrenzen (Hintergrundänderungen, Abstandsverschiebungen) identifiziert
• Anschließend werden Inhaltssequenzen in jedem Abschnitt identifiziert.

Die Erstellung der Analyse folgt Davids Modell.

• Für jede Inhaltssequenz wird zunächst überprüft: „Kann ein Autor dies durch normale Eingabe erstellen?“
• Standardinhalte (Überschriften, Absätze, Listen, Inline-Bilder) werden gegenüber Blöcken bevorzugt.

Der Agent versucht, vorhandene Blöcke aus der Blockbibliothek des Repositorys wiederzuverwenden, bevor neue erstellt werden.

• Wenn Inhalte nicht einem vorhandenen Block zugeordnet werden können, werden neue Blockvarianten erstellt.
• Sie können zu Änderungen auffordern, neue Varianten anfordern oder Zuordnungen interaktiv anpassen.

Blockvarianten werden mit Metadaten verfolgt.

• Bei der Migration mehrerer Seiten lädt der Agent zuerst vorhandene benutzerdefinierte Varianten und verwendet sie dann erneut, wenn die Formatierung übereinstimmt (70 % Ähnlichkeitsschwellenwert basierend auf Zweck, Farben, Typografie, Abstand, Layout).

Kopf-, Navigations- und Fußzeile sind von der Seitenmigration ausgeschlossen. Diese werden von dedizierten Fähigkeiten gehandhabt.

Bei jeder Migration wird eine Importinfrastruktur (Seitenvorlagen, Block-Parser, Transformatoren) für zukünftige Massenimporte erstellt.

• Dazu gehören Seitenvorlagen (Abschnittsstruktur), Transformatoren (Site-Wide DOM Cleanup) und Parser (blockspezifische Konvertierung von HTML in Tabellen).

• Es leitet Vorlagen nicht von Grund auf ab.

• Das Mischen von Vorlagen in einer einzigen Ausführung wird nicht unterstützt.

Diese Eingabeaufforderung wird in der Regel automatisch als erster Schritt der Seitenmigration aufgerufen.

Über CSS ausgeblendeter Inhalt wird ebenfalls erfasst, wenn er im DOM vorhanden ist.

Lazy-Loading-Bilder und Client-seitig gerenderte Inhalte werden verarbeitet, indem Sie durch die Seite in Headless-Chromium scrollen und Skripte ausführen lassen.

WebP/AVIF/SVG-Bilder werden aus Kompatibilitätsgründen in PNG konvertiert.

Metadaten werden extrahiert, einschließlich Titel, Beschreibung, Open-Graph-Tags, JSON-LD-strukturierte Daten und kanonischer URL.

Bilder im DOM sind unveränderlich.

• background-image wird zu img konvertiert.
• Bildelemente werden entpackt
• srcset wird zu src aufgelöst
• Relative URLs werden in absolute URLs konvertiert
• Inline-SVG in werden in img-Dateien konvertiert.

Bereinigte Dokumentpfade werden generiert (Kleinbuchstaben ohne .html).

Folgende Ergebnisse werden erzeugt:

• screenshot.png
• cleaned.html (keine Scripts/Stile)
• metadata.json
• Ordner mit lokalen Kopien images/

Benutzer können nach den Abmessungen des Screenshots fragen und bestimmte Gerätegrößen (Smartphone und Tablet) für die Inhaltsextraktion anfordern.

Das Extrahieren von Inhalten an mehreren Haltepunkten verlängert die Verarbeitungszeit.

Die Designmigration umfasst zwei Phasen:

1. Phase 1 (standortweit) extrahiert Folgendes nach styles/styles.css:

   • Farbpalette und Akzentfarben weltweit
   • Typografie-System (Schriftarten, Größen, Gewichtungen)
   • Abstandssystem (Abstand, Ränder, Lücken)
   • Abschnittshintergründe (hell, dunkel, farbig)
   • Stile der Basiskomponenten (Schaltflächen, Links, Bilder)
   • Ausgaben an

2. Phase 2 migriert einzelne Blockstile und erstellt blockspezifische CSS-Dateien in /blocks/{name}/{name}.css.

Um die Blockformatierung (Phase 2) durchzuführen, muss zunächst das Site-Wide Design (Phase 1) abgeschlossen sein.

• Das globale Designsystem stellt benutzerdefinierte CSS-Eigenschaften bereit, die Verweise blockieren.

Geschätzte Zeit:

• Phase 1: 5-10 Minuten
• Phase 2: 10-15 Minuten

Bei mehrdeutigen Anfragen wird die Migration standardmäßig abgeschlossen (beide Phasen).

Die Blockkritik vergleicht einen migrierten Block mit seiner ursprünglichen Quelle und wendet iterativ CSS-Korrekturen an, bis eine visuelle Ähnlichkeit von 85 % erreicht ist oder drei Iterationen abgeschlossen sind.

Für die Kenntnis muss der Block zuerst durch Seitenmigration erstellt worden sein.

Eine Blockkritik folgt einem sechsstufigen Workflow:

1. Erfasst den ursprünglichen Block aus der Quellseite mithilfe einer XPath-Auswahl.
2. Es initialisiert die Kritik-Sitzung.
3. Es überprüft den Originalblock (Screenshots, Stile, HTML).
4. Er überprüft den migrierten Block.
5. Es vergleicht Elemente und generiert einen Ähnlichkeitswert mit CSS-Korrekturen.
6. Es werden Fehlerbehebungen vorgenommen und die Prüfungen wiederholt, bis das 85-%-Ziel erreicht ist.

Jede Iteration zeigt einen vollständigen Kritikbericht mit allen Unterschieden an, wendet alle CSS-Korrekturen an (priorisiert durch visuelle Auswirkungen), prüft in der Vorschau, überprüft erneut und zeigt Verbesserungsmetriken an.

Verwenden Sie die Blockkritik, nachdem Design-Migration abgeschlossen ist.

Die Seitenkritik führt einen ganzseitigen visuellen Vergleich zwischen der ursprünglichen und der migrierten Seite durch und iteriert, bis ein Ähnlichkeitsziel von 85 % erreicht ist oder drei Iterationen abgeschlossen sind.

Eine Seitenkritik hat einen fünfstufigen Workflow:

1. Es initialisiert eine Kritiksitzung.
2. Es werden alle Elemente auf der Originalseite überprüft.
3. Es werden alle Elemente auf der migrierten Seite überprüft.
4. Er vergleicht und generiert einen Ähnlichkeitswert mit priorisierten CSS-Fehlerbehebungen.
5. Es werden Fehlerbehebungen vorgenommen und die Prüfungen wiederholt, bis das 85-%-Ziel erreicht ist.

Eine Seitenkritik benötigt die URL der Quellseite und den migrierten Pfad (z. B. "/about„) als Eingabe.

Verwenden Sie die Seitenkritik bei der Validierung der Gesamtseitentreue oder der gleichzeitigen Validierung mehrerer Blöcke.

Blockkritik verwenden für fokussierte Validierung auf bestimmte Komponenten.

Der folgende Workflow wird empfohlen:

1. Migrieren einer Seite.
2. Wenden Sie ein Design an.
3. Blockkritik auf Schlüsselblöcke ausführen
4. Führen Sie eine Seitenkritik zur vollständigen Validierung aus.

Diese Fähigkeit migriert einen Block nach dem anderen, nicht ganze Seiten oder vollständige Figma-Dateien.

Für optimale Ergebnisse:

• Wählen Sie den spezifischen Block aus, den Sie in Figma migrieren möchten, und kopieren Sie seinen Link (mit node-id) oder Namen.
• Geben Sie in der URL den node-id an, um den genauen Block auszuwählen.

Wenn Sie diese Fähigkeit ausführen, werden die folgenden Schritte automatisch in der gehosteten Umgebung ausgeführt:

1. Blockstrukturerkennung - Der Agent liest den Figma-Knoten, um Ebenen und Komponenten zu verstehen.
2. Globale Stilextraktion - Der Agent zieht Farben, Typografie und Abstände in styles/styles.css als benutzerdefinierte CSS-Eigenschaften (Design-Token) ein.
3. Blockspezifische Stilerstellung - Der Agent erstellt zusätzliche benutzerdefinierte CSS-Eigenschaften, die für den migrierten Block spezifisch sind.
4. Zuordnung zu vorhandenen Blöcken - Der Agent identifiziert den Block in der Blockbibliothek Ihres Projekts, der am ehesten damit übereinstimmt, und erstellt eine benutzerdefinierte Variante.
5. CSS-Generierung - Der Agent schreibt Stile, die auf die extrahierten benutzerdefinierten CSS-Eigenschaften verweisen, und stellt so die Konsistenz des Designs sicher.
6. Asset-: Der Agent speichert Bilder und Symbole aus Figma im Arbeitsbereich der gehosteten Umgebung.
7. Edge Delivery Services-Inhaltserstellung - Der Agent erstellt die Markdown-Datei entsprechend der EDS-Blockstruktur
8. Ausgabevalidierung - Der Agent zeigt eine Vorschau des Ergebnisses an und führt einen visuellen Vergleich mit dem ursprünglichen Figma-Design durch.

Die Kenntnis liest zunächst Metadaten (Schritt 1), um die Struktur zu verstehen, und extrahiert dann einen detaillierten Design-Kontext (Schritte 2-5).

• Dieser stufenweise Ansatz verhindert Probleme mit großen oder komplexen Figma-Dateien.

Diese Fähigkeit verwendet einen Ansatz, bei dem Stile Vorrang haben.

• Alle Stile werden als benutzerdefinierte CSS-Eigenschaften (Design-Token) extrahiert, bevor CSS geschrieben wird.
• Dadurch wird sichergestellt, dass der migrierte Block konsistent mit Ihrem Design-System bleibt.

Die Eingabeaufforderung erfordert die Figma-URL (mit fileKey und optionalem node-id) oder einen Figma-Dateischlüssel direkt als Eingabe.

Die Edge Delivery Services-Navigation erzwingt eine Struktur mit drei Abschnitten (erzwungen von header.js):

1. Marke (Abschnitt 1): Logo und primärer Branding-Link
2. Abschnitte (Abschnitt 2): Hauptnavigationsmenü mit optionalen Dropdown-Listen
3. Tools (Abschnitt 3): Link zu Dienstprogrammen (abonnieren, anmelden, Warenkorb)

Der Navigationsinhalt ist in nav.md im Stammverzeichnis vorhanden.

Abschnitte werden durch (---) -Markierungen getrennt.

Fett gedruckte Elemente (**Text**) mit verschachtelten Listen erstellen Dropdown-Listen.

Links in der Navigation werden aufgrund des automatischen Umbruchs bei der Dokumenterstellung möglicherweise als Schaltflächen gerendert.

• Der Kopfzeilenblock enthält Code zum Entfernen von Schaltflächenklassen von Navigations-Links.

Der Agent folgt der Content-Driven Development (CDD), einem obligatorischen Prozess für die gesamte Edge Delivery Services-Entwicklung.

• Vor dem Schreiben von Code werden Fragen zu Inhaltsmodellen gestellt und Inhalte getestet.

Die Philosophie der CDD besteht darin, dass der Autor vor dem Entwickler kommen muss.

• Inhaltsmodelle müssen für Autoren intuitiv sein, auch wenn dies komplexeren Dekorations-Code bedeutet.

Das Erstellen von Testinhalten bietet zunächst:

• Sofortige Testfunktion
• PR-Validierungs-Links für PSI-Prüfungen
• Living-Dokumentation für Autoren
• Erkennung von Edge-Fällen, die bei Code-First-Ansätzen verpasst werden

Der Agent sucht vor der Implementierung nach ähnlichen Blöcken in Blocksammlung und Blockpartei, um Muster und wiederverwendbaren Code zu finden.

Nur CDD für triviale CSS-basierte Anpassungen überspringen (aber dennoch Testinhalte für die Validierung identifizieren).

Edge Delivery Services verfügt über vier kanonische Modelltypen:

• Eigenständig: Unterschiedliche visuelle/erzählerische Elemente (Held, Blockquote)
  • Einzelne Tabelle mit Blockinhalt
• Sammlung Wiederholen von teilweise strukturierten Inhalten (Karten, Karussell)
  • Tabelle mit sich wiederholendem Zeilenmuster
• Konfiguration: API-gesteuerte oder dynamische Inhalte, in denen Konfigurationssteuerelemente angezeigt werden (Blog-Auflistung, Suchergebnisse)
  • Tabelle mit Schlüssel-Wert-Konfigurationszeilen.
• Automatisch blockiert: Komplexe Strukturen, die Autorinnen und Autoren als Abschnitte/Standardinhalte erstellen und dann transformiert werden (Registerkarten, YouTube-Einbettungen)

Pro Zeile sind maximal vier Zellen zulässig.

• Gruppieren verwandter Elemente in Zellen.

Aus Gründen der Formatierungsunterschiede sollten Blockvarianten gegenüber Konfigurationszellen bevorzugt werden.

Befolgen Sie das Postel'-Gesetz: Seien Sie flexibel bei der Eingabestruktur.

• Ein Hero-Block sollte unabhängig davon funktionieren, ob sich der Inhalt in einer Zelle, auf zwei Zellen oder in separaten Zeilen befindet.

Diese Fähigkeit wird in der Regel automatisch durch die inhaltsgesteuerte Entwicklung während der Blockerstellung aufgerufen.

Die Blocksammlung wird von Adobe gepflegt und auf Best Practices, hervorragende Inhaltsmodellierung, hohe Leistung und Barrierefreiheit hin überprüft.

• Es ist auf häufig benötigte Blöcke beschränkt. Beginnen Sie hier.

Die Block Party ist gemeinschaftsorientiert und bietet eine größere Vielfalt einschließlich experimenteller Ansätze.

• Es enthält auch Sidekick-Plug-ins, Build-Tools (webpack, Vite, Sass) und Integrationen.
• Verwenden Sie diese Option, wenn die Blocksammlung nicht das enthält, was Sie benötigen.

Denken Sie bei der Suche an alternative Namen.

• FAQ = Akkordeon
• Galerie = Karussell/Diashow
• Navigation = Menü/Kopfzeile

Die Blockpartei gibt nur genehmigte/kuratierte Einträge zurück.

Tests folgen der Philosophie „Wert vs. Kosten“, nach der Sie Tests erstellen und verwalten, wenn ihr Wert die Kosten überschreitet.

• Keeper-Tests (Unit-Tests) sind für logiklastige Dienstprogramme, Datenverarbeitung und API-Integrationen bestimmt. Diese sind schnell, einfach zu pflegen und erfassen Regressionen im wiederverwendeten Code.
• Wegwerftests (Browser-Tests) dienen zur DOM-Transformation und visuellen Validierung. Verwenden Sie , um die Implementierung zu validieren, Screenshots zur PR-Überprüfung zu erfassen und dann zu verwerfen.

Wegwerftests werden test/tmp/ und Testinhalte in drafts/tmp/ (beide werden ignoriert).

Stellen Sie vor dem Öffnen eines PR Folgendes sicher:

• Bestehende Tests erfolgreich
• Modultests werden für neue Logik geschrieben
• Browser-Validierung abgeschlossen
• Alle Varianten werden getestet
• Responsives Verhalten ist verifiziert
• Linting Pässe

Häufige Probleme weisen bekannte Muster auf:

• Bilder mit „about:error": Fehlt normalerweise createOptimizedPicture Aufruf in Block JS oder wird vor der DOM-Umstrukturierung aufgerufen
• Blöcke werden nicht gerendert: Überprüfen Sie das Blocknamenformat im Markdown und stellen Sie sicher, dass der Block sowohl .js- als auch .css-Dateien in blocks/ hat.
• CSS wird nicht geladen: Überprüfen Sie die Dateipfade, ob die CSS-Datei vorhanden ist, und überprüfen Sie die Registerkarte „Netzwerk“ im Browser.
• Änderungen werden nicht angezeigt: Die Codesynchronisierung dauert 3-5 Sekunden. Versuchen Sie, die Seite zu aktualisieren (Strg+Umschalt+R).

Der Agent prüft jede Ebene systematisch:

1. Source-Dateien
2. Gerenderte Ausgabe
3. Blockcode
4. Browser-Konsole

Der Agent hat die Möglichkeit, lokale Vorschauen auf http://localhost:3000 zu überprüfen.