Guida alla richiesta di informazioni per l’agente di modernizzazione esperienza prompting-guide

La migrazione segue un flusso di lavoro in sette passaggi:

1. L'agente esegue il scraping della pagina di origine.
2. Identifica la struttura della sezione.
3. Esegue analisi di authoring.
4. Il contenuto viene mappato per bloccare le varianti.
5. Genera markdown.
6. Crea infrastrutture di importazione.
7. Visualizza l’anteprima del risultato.

L’agente analizza le pagine utilizzando una gerarchia a due livelli:

• Per prima cosa identifica i limiti della sezione (modifiche di sfondo, spostamenti di spaziatura)
• Quindi identifica le sequenze di contenuto all’interno di ogni sezione.

L'analisi di authoring segue il modello di David.

• per ogni sequenza di contenuto, controlla innanzitutto "Può un autore crearlo digitando normalmente?"
• Il contenuto predefinito (intestazioni, paragrafi, elenchi e immagini in linea) è da preferire rispetto ai blocchi.

L’agente tenta di riutilizzare i blocchi esistenti dalla libreria di blocchi dell’archivio prima di crearne di nuovi.

• Quando il contenuto non può essere mappato su un blocco esistente, crea nuove varianti di blocco.
• Puoi richiedere modifiche, richiedere nuove varianti o regolare le mappature in modo interattivo.

Le varianti di blocco vengono tracciate con i metadati.

• Durante la migrazione di più pagine, l’agente carica prima le varianti personalizzate esistenti e le riutilizza quando lo stile corrisponde a (soglia di somiglianza del 70% in base a scopo, colori, composizione tipografica, spaziatura, layout).

Intestazione, navigazione e piè di pagina sono esclusi dalla migrazione delle pagine. Questi sono gestiti da abilità dedicate.

Ogni migrazione crea un’infrastruttura di importazione (modelli di pagina, parser di blocchi, trasformatori) per le future importazioni in blocco.

• Ciò include modelli di pagina (struttura di sezione), trasformatori (pulizia DOM a livello di sito) e parser (conversione da HTML a tabella specifica per blocco).

• Non deduce modelli da zero.

• La combinazione di modelli in una singola esecuzione non è supportata.

Questo prompt viene in genere richiamato automaticamente come primo passaggio della migrazione delle pagine.

I contenuti nascosti tramite CSS vengono acquisiti anche se presenti nel DOM.

Le immagini caricate con lazy e il contenuto renderizzato lato client vengono gestiti scorrendo la pagina in Chromium headless e lasciando eseguire gli script.

Le immagini WebP/AVIF/SVG vengono convertite in PNG per compatibilità.

Vengono estratti i metadati, inclusi titolo, descrizione, tag Open Graph, dati strutturati JSON-LD, URL canonico.

Le immagini nel DOM sono fisse.

• background-image viene convertito in img.
• Disattivazione degli elementi immagine
• srcset è risolto in src
• Gli URL relativi vengono convertiti in assoluti
• I file SVG in linea vengono convertiti in file di immagine.

Vengono generati percorsi di documenti personalizzati (lettere minuscole senza estensione .html).

Vengono prodotti i seguenti output:

• screenshot.png
• cleaned.html (nessuno script/stili)
• metadata.json
• Cartella images/ con copie locali

Gli utenti possono chiedere informazioni sulle dimensioni della schermata e richiedere dimensioni specifiche del dispositivo (mobile, desktop) per l’estrazione dei contenuti.

L’estrazione del contenuto in più punti di interruzione aumenta il tempo di elaborazione.

La migrazione della progettazione prevede due fasi:

1. La fase 1 (a livello di sito) estrae quanto segue in styles/styles.css:

   • Tavolozza dei colori globale e colori degli accenti
   • Sistema tipografico (caratteri, dimensioni, pesi)
   • Sistema di spaziatura (spaziatura, margini, spazi)
   • Sfondi sezione (chiaro, scuro, colorato)
   • Stili dei componenti di base (pulsanti, collegamenti, immagini)
   • Invia a

2. La fase 2 esegue la migrazione dei singoli stili di blocco e crea CSS specifici per il blocco in /blocks/{name}/{name}.css.

Lo stile del blocco (fase 2) richiede che il progetto a livello di sito (fase 1) sia completo per primo.

• Il sistema di progettazione globale fornisce proprietà personalizzate CSS che bloccano il riferimento.

Tempo stimato:

• Fase 1: 5-10 minuti
• Fase 2: 10-15 minuti

Per impostazione predefinita, le richieste ambigue completano la migrazione (entrambe le fasi).

La critica di blocco confronta un blocco migrato con la sua origine originale e applica iterativamente le correzioni CSS fino a raggiungere una somiglianza visiva dell’85% o a completare tre iterazioni.

L’abilità richiede che il blocco sia stato creato prima dalla migrazione delle pagine.

Una critica di blocco segue un flusso di lavoro in sei passaggi:

1. Acquisisce il blocco originale dalla pagina sorgente utilizzando un selettore XPath.
2. Inizializza la sessione di critica.
3. Controlla il blocco originale (schermate, stili, HTML).
4. Controlla il blocco migrato.
5. Confronta gli elementi e genera un punteggio di somiglianza con le correzioni CSS.
6. Applica correzioni e riesamina fino al raggiungimento dell’obiettivo dell’85%.

Ogni iterazione visualizza un rapporto critico completo con tutte le differenze, applica tutte le correzioni CSS (con priorità in base all’impatto visivo), verifica in anteprima, riesamina e mostra le metriche di miglioramento.

Utilizza la critica di blocco dopo il completamento di migrazione progettazione.

Il criterio di pagina esegue un confronto visivo a pagina intera tra la pagina originale e quella migrata, ripetendo l’iterazione fino a raggiungere un target di somiglianza dell’85% o fino a tre iterazioni completate.

Una critica di pagina prevede un flusso di lavoro in cinque passaggi:

1. Inizializza una sessione critica.
2. Esamina tutti gli elementi della pagina originale.
3. Esamina tutti gli elementi della pagina migrata.
4. Confronta e genera un punteggio di somiglianza con le correzioni CSS con priorità.
5. Applica correzioni e riesamina fino al raggiungimento dell’obiettivo dell’85%.

Un criterio di pagina richiede come input l’URL della pagina sorgente e il percorso migrato (ad esempio,"/about").

Utilizza il criterio di pagina per convalidare la fedeltà complessiva della pagina o più blocchi simultaneamente.

Utilizza la critica del blocco per una convalida incentrata su componenti specifici.

Si consiglia il seguente flusso di lavoro:

1. Migrare una pagina.
2. Applicare una progettazione.
3. Eseguire una critica di blocco sui blocchi chiave
4. Esegui il criterio di pagina per la convalida completa.

Questa abilità consente di eseguire la migrazione di un blocco alla volta, non di pagine intere o file Figma completi.

Per ottenere risultati ottimali:

• Seleziona il blocco specifico di cui vuoi eseguire la migrazione in Figma e copiane il collegamento (con node-id) o il nome.
• Fornisci il parametro node-id nell'URL per eseguire il targeting del blocco esatto.

Quando esegui questa abilità, i seguenti passaggi vengono eseguiti automaticamente nell’ambiente in hosting:

1. Individuazione struttura di blocco: l'agente legge il nodo Figma per comprendere livelli e componenti.
2. Estrazione stile globale: l'agente richiama colori, composizione tipografica e spaziatura in styles/styles.css come proprietà personalizzate CSS (token di progettazione).
3. Creazione di stili specifici del blocco. L'agente crea proprietà personalizzate CSS aggiuntive specifiche per il blocco di cui si esegue la migrazione.
4. Mappatura a blocchi esistenti: l'agente identifica il blocco corrispondente più vicino nella libreria di blocchi del progetto e crea una variante personalizzata.
5. Generazione CSS: l'agente scrive stili che fanno riferimento alle proprietà personalizzate CSS estratte, garantendo la coerenza della progettazione.
6. Download risorse: l'agente salva immagini e icone da Figma nell'area di lavoro dell'ambiente ospitato.
7. Generazione di contenuti Edge Delivery Services: l'agente crea il file markdown seguendo la struttura di blocchi EDS
8. Convalida output: l'agente visualizza in anteprima il risultato ed esegue un confronto visivo con la struttura Figma originale.

L’abilità legge innanzitutto i metadati (passaggio 1) per comprendere la struttura, quindi estrae il contesto di progettazione dettagliato (passaggi 2-5).

• Questo approccio graduale evita problemi con file Figma di grandi dimensioni o complessi.

Questa abilità adotta un approccio basato sugli stili.

• Tutti gli stili vengono estratti come proprietà personalizzate CSS (token di progettazione) prima della scrittura di qualsiasi CSS.
• In questo modo il blocco migrato rimane coerente con il sistema di progettazione.

Il prompt richiede l'URL Figma (con fileKey e l'opzione node-id) o una chiave di file Figma direttamente come input.

La navigazione Edge Delivery Services applica una struttura a tre sezioni (imposta da header.js):

1. Marchio (sezione 1): Logo e collegamento di branding principale
2. Sezioni (sezione 2): menu di navigazione principale con menu a discesa facoltativi
3. Strumenti (sezione 3): collegamenti alle utilità (abbonamento, accesso, carrello)

Il contenuto di navigazione si trova in nav.md nella directory principale.

Le sezioni sono separate da (---) marcatori.

Gli elementi in grassetto (**Text**) con elenchi nidificati creano elenchi a discesa.

I collegamenti nella navigazione possono essere visualizzati come pulsanti a causa del comportamento di wrapping automatico di Document Authoring.

• Il blocco intestazione include codice per eliminare le classi di pulsanti dai collegamenti di navigazione.

L’agente segue Content-Driven Development (CDD), un processo obbligatorio per tutti gli sviluppi Edge Delivery Services.

• Si occuperà di modelli di contenuto e di testare il contenuto prima di scrivere il codice.

La filosofia di CDD è che l’autore deve venire prima delle esigenze dello sviluppatore.

• I modelli di contenuto devono essere intuitivi per gli autori, anche se ciò significa codice di decorazione più complesso.

La creazione del contenuto di test fornisce innanzitutto:

• Funzionalità di test immediato
• Collegamenti di convalida PR per i controlli PSI
• Documentazione live per autori
• Individuazione dei casi edge non raggiunti con l’approccio code-first

L'agente cercherà blocchi simili nella raccolta blocchi e nella parte blocchi prima di implementarli, per trovare modelli e codice riutilizzabile.

Ignora CDD solo per modifiche banali apportate solo a CSS (ma identifica comunque il contenuto di test per la convalida).

Edge Delivery Services dispone di quattro tipi di modelli canonici:

• Autonomo: elementi visivi/narrativi distinti (hero, blockquote)
  • Tabella singola con contenuto blocco
• Raccolta: contenuto semistrutturato ripetuto (schede, carosello)
  • Tabella con pattern di righe ripetuto
• Configurazione: contenuto dinamico o basato su API in cui vengono visualizzati i controlli di configurazione (elenco blog, risultati ricerca)
  • Tabella con righe di configurazione chiave-valore.
• Bloccato automaticamente: strutture complesse create dagli autori come sezioni/contenuto predefinito e trasformate (schede, incorporamenti YouTube)

C'è un limite di quattro celle per riga.

• Raggruppa elementi correlati in celle.

Preferisci le varianti di blocco alle celle di configurazione per le differenze di stile.

Segui la legge di Postel: Sii flessibile sulla struttura di input.

• Un blocco hero deve funzionare sia che il contenuto si trovi in una cella, diviso in due celle o in righe separate.

Questa abilità viene in genere richiamata automaticamente dallo sviluppo basato sui contenuti durante la creazione dei blocchi.

La Raccolta blocchi è gestita da Adobe e valutata per le best practice, la modellazione dei contenuti eccellente, le prestazioni elevate e l'accessibilità.

• È limitato ai blocchi comunemente necessari. Inizia qui.

Il Blocca festa è guidato dalla community e offre una varietà più ampia, inclusi gli approcci sperimentali.

• Include inoltre plug-in per la barra laterale, strumenti di creazione (webpack, vite, sass) e integrazioni.
• Da utilizzare quando la raccolta Blocca non dispone di ciò che è necessario.

Considera nomi alternativi durante la ricerca

• FAQ = Pannello a soffietto
• Galleria = carosello/presentazione
• Navigazione = menu/intestazione

Il Blocca parte restituisce solo le voci approvate/curate.

I test seguono una filosofia di "valore rispetto ai costi" in cui si creano e gestiscono test quando il loro valore supera i costi.

• I test Keeper (unit test) sono per utilità pesanti per la logica, elaborazione dati, integrazioni API. Si tratta di regressioni rapide, facili da mantenere e intercettate nel codice riutilizzato.
• I test di eliminazione (test del browser) sono per trasformazioni DOM e convalida visiva. Utilizza per convalidare l’implementazione, acquisire screenshot per la revisione PR e quindi eliminarlo.

I test di eliminazione vengono eseguiti in test/tmp/ e il contenuto dei test in drafts/tmp/ (entrambi ignorati).

Prima di aprire una PR, accertati di:

• Test esistenti superati
• Gli unit test vengono scritti per la nuova logica
• Convalida del browser completata
• Tutte le varianti vengono testate
• Il comportamento reattivo è verificato
• Passate di colorazione

I problemi comuni presentano pattern noti:

• Immagini che mostrano "about:error": chiamata createOptimizedPicture generalmente mancante nel blocco JS o chiamata prima della ristrutturazione DOM
• Blocchi senza rendering: controlla il formato del nome del blocco in markdown e verifica che il blocco contenga .js e .css file in blocks/.
• Impossibile caricare il file CSS: controllare i percorsi dei file, verificare che il file CSS esista e controllare la scheda Rete nel browser.
• Modifiche non visualizzate: la sincronizzazione del codice richiede 3-5 secondi. Prova ad aggiornare (Ctrl+Maiusc+R).

L'agente controlla sistematicamente ogni livello:

1. File Source
2. Output di rendering
3. Codice di blocco
4. Console del browser

L'agente è in grado di controllare le anteprime locali alle http://localhost:3000.