Guide de l’invite pour l’agent de modernisation d’expérience prompting-guide

La migration suit un workflow en sept étapes :

1. L’agent gratte la page source.
2. Il identifie la structure de la section.
3. Il effectue une analyse de création.
4. Il mappe le contenu pour bloquer les variantes.
5. Cela génère du markdown.
6. Cela crée une infrastructure d'importation.
7. Il prévisualise le résultat.

L’agent analyse les pages à l’aide d’une hiérarchie à deux niveaux :

• Il identifie d'abord les limites des sections (changements d'arrière-plan, décalages d'espacement)
• Il identifie ensuite les séquences de contenu dans chaque section.

La création d’une analyse suit le modèle de David.

• pour chaque séquence de contenu, il vérifie d’abord « Un auteur peut-il le créer en saisissant normalement ? »
• Le contenu par défaut (titres, paragraphes, listes, images intégrées) est préférable aux blocs.

L’agent tente de réutiliser des blocs existants de la bibliothèque de blocs du référentiel avant d’en créer de nouveaux.

• Lorsque le contenu ne peut pas être mappé à un bloc existant, il crée des variantes de bloc.
• Vous pouvez demander des modifications, demander de nouvelles variantes ou ajuster les mappages de manière interactive.

Les variantes de bloc sont suivies avec des métadonnées.

• Lors de la migration de plusieurs pages, l’agent charge d’abord les variantes personnalisées existantes et les réutilise lors de la mise en forme des correspondances (seuil de similarité de 70 % en fonction de l’objectif, des couleurs, de la typographie, de l’espacement et de la disposition).

L’en-tête, la navigation et le pied de page sont exclus de la migration. Ils sont gérés par des compétences dédiées.

Chaque migration crée une infrastructure d’importation (modèles de page, analyseurs de blocs, transformateurs) pour les futures importations en bloc.

• Cela inclut les modèles de page (structure de section), les transformateurs (nettoyage DOM à l’échelle du site) et les analyseurs (conversion d’HTML en tableau spécifique au bloc).

• Il ne déduit pas de modèles à partir de zéro.

• Le mélange de modèles dans une seule exécution n’est pas pris en charge.

Cette invite est généralement appelée automatiquement comme première étape de la migration de la page.

Le contenu masqué via CSS est également capturé s’il est présent dans le DOM.

Les images chargées en différé et le contenu rendu côté client sont gérés en faisant défiler la page dans Chromium découplé et en laissant les scripts s’exécuter.

Les images WebP/AVIF/SVG sont converties en PNG à des fins de compatibilité.

Les métadonnées sont extraites, notamment le titre, la description, les balises Open Graph, les données structurées JSON-ID et l’URL canonique.

Les images dans DOM sont corrigées.

• background-image est converti en img.
• Les éléments d'image sont dépliés
• srcset est résolu en src
• Les URL relatives sont converties en URL absolues.
• Le SVG intégré en est converti en fichiers img.

Les chemins d’accès aux documents assainis sont générés (en minuscules sans extension .html).

Les résultats suivants sont produits :

• screenshot.png
• cleaned.html (aucun script/style)
• metadata.json
• Dossier images/ avec copies locales

Les utilisateurs peuvent poser des questions sur les dimensions des captures d’écran et demander des tailles d’appareil spécifiques (mobile, bureau) pour l’extraction de contenu.

L’extraction de contenu à plusieurs points d’arrêt augmente le temps de traitement.

La migration de conception comporte deux phases :

1. La phase 1 (à l’échelle du site) extrait les éléments suivants pour les styles/styles.css :

   • Palette de couleurs globale et couleurs d’accentuation
   • Système de typographie (polices, tailles, poids)
   • Système d'espacement (marge intérieure, marges, espaces)
   • Arrière-plans de section (clair, sombre, coloré)
   • Styles des composants de base (boutons, liens, images)
   • Sorties vers

2. La phase 2 migre les styles de blocs individuels et crée un CSS spécifique au bloc dans /blocks/{name}/{name}.css.

Le style de bloc (phase 2) nécessite que la conception à l’échelle du site (phase 1) soit terminée en premier.

• Le système de conception global fournit des propriétés personnalisées CSS qui bloquent la référence.

Temps estimé :

• Phase 1 : 5-10 minutes
• Phase 2 : 10 à 15 minutes

Les requêtes ambiguës effectuent par défaut la migration complète (les deux phases).

La critique de bloc compare un bloc migré à sa source d’origine et applique de manière itérative des correctifs CSS jusqu’à ce qu’une similarité visuelle de 85 % soit atteinte ou que trois itérations soient terminées.

La compétence nécessite que le bloc ait d’abord été créé par la migration de la page.

Une critique de bloc suit un workflow en six étapes :

1. Il capture le bloc d’origine de la page source à l’aide d’un sélecteur XPath.
2. Il initialise la session critique.
3. Il inspecte le bloc d’origine (captures d’écran, styles, HTML).
4. Il inspecte le bloc migré.
5. Il compare les éléments et génère un score de similarité avec les correctifs CSS.
6. Il applique des correctifs et procède à de nouvelles inspections jusqu’à ce que l’objectif de 85 % soit atteint.

Chaque itération affiche un rapport critique complet avec toutes les différences, applique tous les correctifs CSS (hiérarchisés par impact visuel), vérifie dans l’aperçu, inspecte à nouveau et affiche les mesures d’amélioration.

Utilisez la critique de bloc une fois la migration de conception terminée.

La critique de page effectue une comparaison visuelle sur toute la page entre la page d’origine et la page migrée, en itérant jusqu’à ce qu’une cible de similarité de 85 % ou trois itérations soient atteintes.

Une critique de page comporte un workflow en cinq étapes :

1. Il initialise une session critique.
2. Il inspecte tous les éléments de la page d’origine.
3. Il inspecte tous les éléments de la page migrée.
4. Il compare et génère un score de similarité avec les correctifs CSS prioritaires.
5. Il applique des correctifs et procède à de nouvelles inspections jusqu’à ce que l’objectif de 85 % soit atteint.

Une critique de page nécessite l’URL de la page source et le chemin migré (par exemple, « /about ») comme entrée.

Utilisez la critique de page lors de la validation de la fidélité globale de la page ou de la validation de plusieurs blocs simultanément.

Utilisez la critique de bloc pour une validation ciblée sur des composants spécifiques.

Le workflow suivant est recommandé :

1. Migrer une page.
2. Appliquez une conception.
3. Exécuter une critique de bloc sur les blocs de clés
4. Exécutez la critique de page pour une validation complète.

Cette compétence migre un bloc à la fois, et non des pages entières ou des fichiers Figma complets.

Pour de meilleurs résultats :

• Sélectionnez le bloc spécifique à migrer dans Figma et copiez son lien (avec node-id) ou son nom.
• Fournissez le paramètre node-id dans l’URL pour cibler le bloc exact.

Lorsque vous exécutez cette compétence, les étapes suivantes sont automatiquement exécutées dans l’environnement hébergé :

1. Découverte de structure en blocs — L'agent lit le nœud Figma pour comprendre les couches et les composants.
2. Extraction de style globale : l’agent extrait les couleurs, la typographie et l’espacement dans les styles/styles.css en tant que propriétés personnalisées CSS (jetons de conception).
3. Création de style spécifique au bloc — L’agent crée des propriétés personnalisées CSS supplémentaires spécifiques au bloc en cours de migration.
4. Mappage à des blocs existants — L'agent identifie le bloc correspondant le plus proche dans la bibliothèque de blocs de votre projet et crée une variante personnalisée.
5. Génération CSS — L’agent écrit des styles qui font référence aux propriétés personnalisées CSS extraites, assurant ainsi la cohérence de la conception.
6. Téléchargement des ressources — L'agent enregistre les images et les icônes de Figma dans l'espace de travail de l'environnement hébergé.
7. Génération de contenu Edge Delivery Services — L'agent crée le fichier Markdown en suivant la structure du bloc EDS
8. Validation de la sortie — L'agent prévisualise le résultat et effectue une comparaison visuelle avec la conception Figma d'origine.

La compétence lit d’abord les métadonnées (étape 1) pour comprendre la structure, puis extrait le contexte de conception détaillé (étapes 2 à 5).

• Cette approche progressive permet d’éviter les problèmes liés aux fichiers Figma volumineux ou complexes.

Cette compétence adopte une approche qui privilégie les styles.

• Tous les styles sont extraits en tant que propriétés personnalisées CSS (jetons de conception) avant l’écriture d’un CSS.
• Cela garantit que le bloc migré reste cohérent avec votre système de conception.

L’invite nécessite l’URL Figma (avec les fileKey node-id et facultatifs) ou une clé de fichier Figma directement en entrée.

La navigation dans Edge Delivery Services applique une structure à trois sections (appliquée par header.js) :

1. Marque (section 1) : logo et lien de marque principal
2. Sections (section 2) : menu de navigation principal avec listes déroulantes facultatives
3. Outils (section 3) : liens d’utilitaires (abonnement, connexion, panier)

Le contenu de navigation réside en nav.md dans le répertoire racine.

Les sections sont séparées par des marqueurs (---).

Les éléments en gras (**Text**) avec des listes imbriquées créent des listes déroulantes.

Les liens dans la navigation peuvent s’afficher sous forme de boutons en raison du comportement d’encapsulation automatique de la création de documents.

• Le bloc d’en-tête comprend du code pour supprimer les classes de bouton des liens de navigation.

L’agent suit le développement piloté par le contenu (CDD), un processus obligatoire pour tous les développements Edge Delivery Services.

• Il pose des questions sur les modèles de contenu et teste le contenu avant d’écrire du code.

La philosophie du CDD est que les besoins de l’auteur passent avant ceux du développeur.

• Les modèles de contenu doivent être intuitifs pour les auteurs, même si cela signifie un code de décoration plus complexe.

La création du contenu de test fournit d’abord :

• Fonctionnalité de test immédiat
• Liens de validation des RP pour les contrôles PSI
• Documentation dynamique pour les auteurs
• Découverte de cas Edge dans lesquels les approches code-first ne fonctionnent pas

L’agent recherche des blocs similaires dans les Collection de blocs et Partie de bloc avant l’implémentation, afin de trouver des modèles et du code réutilisable.

Ignorer le CDD uniquement pour les ajustements triviaux de CSS uniquement (mais toujours identifier le contenu du test pour la validation).

Edge Delivery Services comporte quatre types de modèles canoniques :

• Autonome : éléments visuels/narratifs distincts (héros, citation)
  • Tableau unique avec contenu en blocs
• Collection : Répétition de contenu semi-structuré (cartes, carrousel)
  • Tableau avec motif de lignes répétées
• Configuration : contenu dynamique ou piloté par API où les commandes de configuration s’affichent (liste de blogs, résultats de recherche)
  • Tableau avec lignes de configuration clé-valeur.
• Bloqué automatiquement : structures complexes que les auteurs créent en tant que sections/contenu par défaut, puis sont transformées (onglets, incorporations de YouTube).

Il existe une limite de quatre cellules par ligne.

• Regroupez les éléments associés dans des cellules.

Préférez les variantes de bloc aux cellules de configuration pour les différences de style.

Suivez la loi de Postel : soyez flexible en matière de structure d’entrée.

• Un bloc de premier plan doit fonctionner, que le contenu se trouve dans une cellule, fractionné sur deux cellules ou dans des lignes distinctes.

Cette compétence est généralement appelée automatiquement par le développement piloté par le contenu lors de la création du bloc.

La collection de blocs est gérée et contrôlée par Adobe pour garantir de bonnes pratiques, une excellente modélisation de contenu, des performances élevées et l’accessibilité.

• Elle est limitée aux blocs fréquemment nécessaires. Commencez ici.

Le Block Party est axé sur la communauté et offre une plus grande variété, y compris des approches expérimentales.

• Il comprend également des modules externes Sidekick, des outils de création (webpack, vite, sass) et des intégrations.
• À utiliser lorsque la collection de blocs n’a pas ce dont vous avez besoin.

Pensez aux autres noms lors de la recherche

• FAQ = accordéon
• Galerie = carrousel/diaporama
• Navigation = menu/en-tête

La partie bloc renvoie uniquement les entrées approuvées/traitées.

Les tests suivent une philosophie de type « valeur par rapport au coût », selon laquelle vous créez et conservez des tests lorsque leur valeur dépasse le coût.

• Les tests de gardien (tests unitaires) concernent les utilitaires lourds en logique, le traitement des données et les intégrations d’API. Ces éléments sont rapides, faciles à gérer et interceptent les régressions dans le code réutilisé.
• Les tests de suppression (tests de navigateur) sont destinés aux transformations DOM et à la validation visuelle. Utilisez pour valider l’implémentation, capturer des captures d’écran pour la révision PR, puis ignorez.

Les tests de suppression sont test/tmp/ et testent le contenu dans drafts/tmp/ (tous deux ignorés).

Avant d’ouvrir une requête de tirage, assurez-vous que :

• Succès des tests existants
• Les tests unitaires sont écrits pour une nouvelle logique
• Validation du navigateur terminée
• Toutes les variantes sont testées
• Le comportement réactif est vérifié.
• Liaison de passes

Les problèmes courants ont des schémas connus :

• Images montrant « about:error » : appel createOptimizedPicture généralement manquant dans le bloc JS, ou appelé avant la restructuration de DOM
• Blocs non rendus : vérifiez le format du nom du bloc dans Markdown et vérifiez que le bloc contient à la fois des fichiers .js et .css en blocks/.
• Le fichier CSS ne se charge pas : vérifiez les chemins d’accès aux fichiers, l’existence du fichier CSS et l’onglet Réseau dans le navigateur.
• Les modifications n’apparaissent pas : la synchronisation du code prend entre 3 et 5 secondes. Essayez une actualisation complète (Ctrl + Maj + R).

L’agent vérifie systématiquement chaque couche :

1. Fichiers Source
2. Sortie générée
3. Code du bloc
4. Console du navigateur

L’agent a la possibilité de vérifier les aperçus locaux à l’http://localhost:3000.