Paidax01/web-to-design-md

Site Web vers DESIGN.md

Aperçu

Utilisez cette compétence pour transformer un site web réel en un document design.md ou DESIGN.md réutilisable, accompagné d'un aperçu HTML.

Le but n'est pas de cloner le site. Le but est de l'inspecter suffisamment en profondeur pour qu'un autre agent puisse reproduire le même langage de conception, le même ton de contenu et la même sensation d'interaction sans avoir besoin de voir le site original.

L'aperçu HTML est une surface de révision pratique. Il doit traduire le markdown en un tableau de conception consultable afin que l'utilisateur puisse inspecter la palette, la typographie, l'espacement, les indices de composants et le code source markdown sans rouvrir le site.

Règle universelle du navigateur

Cette compétence doit toujours utiliser agent-browser en premier.

• Utilisez agent-browser open, agent-browser wait et surtout agent-browser eval comme workflow d'extraction principal.
• Ne commencez pas par vérifier sur quelle application ou plateforme se trouve l'utilisateur.
• Ne créez pas de logique conditionnelle basée sur le fait que l'utilisateur utilise Codex, Trae, Claude, Cursor ou un autre hôte.
• Ne commencez pas par vérifier si le dossier actuel du projet contient Playwright, Chrome CLI ou un package de navigateur local.
• Si agent-browser n'est pas disponible, aidez l'utilisateur à l'installer ou à l'exposer sur PATH, puis continuez avec le même workflow.
• Ne basculez pas silencieusement vers Playwright, Chrome CLI ou une extraction basée sur des captures d'écran, sauf si l'utilisateur demande explicitement un repli séparé.

Style de travail

Travaillez d'abord avec le navigateur et les preuves.

• Préférez agent-browser aux récupérations HTML brutes. Un site web en direct cache souvent des comportements importants derrière l'hydratation, l'état de défilement, l'état de survol ou les changements de mise en page réactive.
• Traitez agent-browser eval comme la couche d'extraction principale. Les preuves principales doivent provenir de la structure DOM, du HTML rendu, des styles calculés, des variables CSS, des règles de feuille de style lisibles et des états d'interaction recueillis à l'intérieur de l'environnement d'exécution du navigateur.
• N'utilisez pas de captures d'écran comme source de preuves par défaut. Lorsque agent-browser eval ou une voie d'évaluation de page équivalente est disponible, utilisez le DOM, les styles calculés, les variables CSS, les règles de feuille de style lisibles et le texte extrait comme preuves principales.
• Utilisez les captures d'écran uniquement comme une ultime vérification croisée facultative lorsque les preuves DOM sont insuffisantes ou que l'utilisateur demande explicitement une vérification visuelle.
• Ne basculez pas silencieusement vers Playwright ou Chrome CLI. Si agent-browser n'est pas disponible, détectez-le explicitement et aidez l'utilisateur à l'installer ou à l'exposer.
• Traitez les fichiers sources statiques comme des preuves complémentaires, pas comme la principale source de vérité.
• Traduisez les détails techniques en langage de conception. Ne déversez pas aveuglément du CSS ; synthétisez-le en quelque chose qu'un agent peut réellement utiliser.
• Distinguez les faits observés des inférences. Si quelque chose est un jugement ou une règle probable plutôt qu'une valeur directement observée, étiquetez-le clairement.
• Traitez l'aperçu HTML comme faisant partie de la livraison par défaut, pas comme un supplément facultatif, sauf si l'utilisateur refuse explicitement.

Préparation

1. Normalisez la cible en une ou plusieurs URL.
2. Vérifiez si agent-browser est déjà utilisable.
3. Si agent-browser est manquant, utilisez scripts/check-browser-tooling.mjs puis aidez l'utilisateur à installer ou exposer agent-browser.
4. N'inspectez pas le dossier actuel pour Playwright, Chrome CLI ou des exécutables de navigateur locaux comme voie principale.
5. Ne basculez pas silencieusement vers Playwright ou Chrome CLI, sauf si l'utilisateur demande explicitement ce repli.
6. Par défaut, le fichier de sortie markdown est DESIGN.md.
7. Par défaut, le fichier d'aperçu compagnon porte le même nom de base suivi de -preview.html, par exemple DESIGN-preview.html ou design-preview.html.
8. Si l'utilisateur demande explicitement design.md, un nom de fichier personnalisé ou un dossier personnalisé, respectez cela exactement et conservez l'aperçu HTML à côté, sauf si l'utilisateur le refuse.
9. Si plusieurs URL sont fournies, inspectez chacune indépendamment, puis synthétisez un système de conception partagé uniquement lorsque le langage visuel est clairement cohérent entre les pages.

Amorçage des outils de navigation

Traitez la configuration des outils de navigateur comme faisant partie de la compétence, pas comme une tâche distincte pour l'utilisateur.

Détection

Vérifiez dans cet ordre :

• si agent-browser est déjà appelable
• si ce n'est pas le cas, s'il peut être installé ou exposé immédiatement

Le script de vérification intégré indique :

• si node et npm sont disponibles
• si agent-browser est appelable
• quel outil doit être utilisé ensuite
• si l'installation est recommandée

Installation par défaut

Si agent-browser n'est pas disponible, aidez l'utilisateur à l'installer ou à l'exposer sur PATH, et vérifiez-le avec agent-browser --help avant d'utiliser la compétence.

Comportement d'installation

• Expliquez que l'installation est nécessaire pour que la compétence puisse utiliser systématiquement agent-browser.
• Si la première tentative d'installation échoue en raison de restrictions réseau ou de bac à sable, demandez l'approbation nécessaire et réessayez.
• Si l'installation réussit, passez directement à l'analyse du site dans le même tour.
• Si l'installation échoue, indiquez clairement à l'utilisateur ce qui manque et arrêtez-vous plutôt que de basculer silencieusement vers un autre extracteur.
• Ne passez pas silencieusement au scraping HTML statique simplement parce que les outils sont absents.

Passes d'extraction requises

Utilisez la liste de contrôle dans references/website-reading-checklist.md lorsque vous avez besoin d'un rappel plus approfondi de ce qu'il faut inspecter.

1. Cadrer la page

• Identifiez l'objectif de la page.
• Identifiez si la page est marketing, produit, tableau de bord, documentation, e-commerce, éditoriale ou mixte.
• Identifiez les sections visibles importantes de haut en bas.
• Notez les zones restreintes ou inaccessibles au lieu de les inventer.

2. Capturer la base

• Inspectez la page d'abord en mode bureau.
• Inspectez également en mode tablette et mobile lorsque la mise en page change de manière significative.
• Faites défiler toute la page lentement avant d'écrire quoi que ce soit afin de ne pas manquer les animations retardées, l'UI collante ou la divulgation progressive.
• Capturez les preuves de code côté navigateur pendant que la page est en direct : HTML rendu, outerHTML des nœuds clés, variables CSS racine, règles de feuille de style lisibles et styles calculés pour les composants représentatifs.
• Préférez les appels directs à agent-browser eval ou un script wrapper piloté par agent-browser plutôt que de passer à une autre pile de navigateur.
• Utilisez scripts/extract-browser-evidence.mjs uniquement lorsque l'utilisateur souhaite explicitement un artefact JSON généré par le shell tout en restant sur agent-browser.
• Ne faites pas de pause pour la capture d'écran pendant la passe par défaut. Utilisez l'évaluation de la page pour extraire la structure et les styles directement de la page en cours d'exécution.

2.1 Workflow d'évaluation préféré

Lorsque agent-browser eval ou une voie d'évaluation de navigateur équivalente est disponible, suivez cet ordre :

1. ouvrez la page
2. attendez le chargement et l'hydratation
3. faites défiler la page pour déclencher le contenu paresseux et les changements d'état collant
4. extrayez le HTML rendu pour les nœuds représentatifs
5. extrayez les styles calculés pour les titres, les boutons, les cartes, la navigation et les wrappers de sections
6. extrayez les variables CSS racine et les règles de feuille de style lisibles
7. extrayez les extraits de texte visibles et le texte des appels à l'action
8. sondez les états de survol, d'activation, de collage ou d'expansion via les changements DOM ou de style calculé

Ne remplacez pas les étapes 4 à 8 par des captures d'écran.

3. Extraire le système de conception

Capturez les règles réutilisables, pas seulement la surface spécifique à la page :

• couleurs et leurs rôles
• variantes de thème clair et sombre lorsque le site les prend en charge
• hiérarchie typographique
• rythme d'espacement et comportement de la grille
• langage des rayons de bordure
• traitement des bordures
• ombres et superposition de surfaces
• style d'imagerie
• style d'icônes
• style de mouvement et de transition
• densité et philosophie des espaces blancs
• conventions de feuille de style et de variables CSS lorsqu'elles sont observables
• motifs DOM qui expliquent comment les composants répétés sont réellement structurés

4. Extraire les composants et les états

Inspectez les motifs répétés majeurs :

• navigation
• barres d'annonces
• blocs hero
• boutons et liens
• cartes
• badges
• formulaires et champs de saisie
• onglets ou pills
• accordéons
• tableaux
• pieds de page

Pour chaque composant important, inspectez les états visibles qui comptent :

• état par défaut
• survol
• état actif ou sélectionné
• état focalisé s'il est visible
• état désactivé s'il est visible
• variantes défilées ou collantes
• états ouverts ou développés
• variantes en mode clair et sombre lorsque le site prend en charge le changement de thème

5. Extraire le comportement interactif

Ne vous arrêtez pas aux visuels statiques.

Documentez :

• ce qui change au défilement
• ce qui change au survol
• ce qui change au clic
• ce qui change lorsque l'utilisateur bascule entre le mode clair et sombre
• ce qui est animé en vue
• si les carrousels, les onglets ou les barres latérales collantes sont pilotés par le clic, le défilement ou le temps
• à quelle vitesse le mouvement semble et s'il est subtil, net, cinématographique, ludique ou retenu
• quels états CSS ou DOM changent pendant ces interactions lorsqu'ils sont observables dans le navigateur

6. Extraire le contenu et la voix de la marque

Capturez le ton qui façonne la conception :

• style des titres
• formulation des appels à l'action
• densité des phrases
• cadrage du produit
• signaux de confiance
• motifs de dénomination des fonctionnalités
• si le texte est technique, ludique, premium, direct, académique ou conversationnel

Ceci est important car un bon DESIGN.md doit guider à la fois les visuels et le style de présentation.

6.1 Balayage du mode de thème

Si le site prend en charge le changement d'apparence :

• déclenchez la bascule du mode clair et sombre directement dans le navigateur
• extrayez les preuves DOM et de style calculé pour les deux modes
• documentez quels jetons s'inversent par rapport aux accents qui restent stables
• notez si l'imagerie, les ombres, les bordures, les cartes et les blocs de code changent de traitement entre les modes
• intégrez les deux modes dans le markdown final et l'aperçu HTML

Contrat de sortie

Rédigez le document final en utilisant la structure de assets/DESIGN.template.md.

Une fois le markdown écrit, générez un aperçu HTML compagnon en utilisant scripts/render-design-preview.mjs lorsque c'est possible.

Lorsque les outils de navigateur sont disponibles, préférez une passe d'extraction DOM-et-style avant d'écrire. L'ordre de preuve attendu est :

1. HTML rendu et structure des nœuds clés
2. styles calculés et variables CSS
3. différences d'état d'interaction
4. vérification croisée facultative par capture d'écran uniquement si l'utilisateur le demande explicitement ou si les preuves DOM sont ambiguës

Si la page prend en charge les thèmes clair et sombre, le contrat de sortie exige également :

1. une documentation explicite des Modes de thème dans DESIGN.md
2. des notes séparées sur les jetons en mode clair et sombre lorsqu'ils diffèrent matériellement
3. un bloc visible de résumé du thème clair/sombre dans l'aperçu HTML compagnon

Le document doit généralement contenir ces sections :

1. Thème visuel et ambiance
2. Palette de couleurs et rôles
3. Règles typographiques
4. Styles des composants
5. Principes de mise en page
6. Profondeur et élévation
7. À faire et à ne pas faire
8. Comportement réactif
9. Guide de sollicitation d'agent

Ajoutez des annexes facultatives uniquement lorsqu'elles apportent une réelle valeur ajoutée :

• Modes d'interaction
• Modes de contenu et de messagerie
• Pages observées
• Notes sur les preuves

Au sein de ces sections, préférez des sous-sections de style "Stitch" plus riches lorsque le site les prend en charge :

• Caractéristiques clés
• Primaire, Interactif, Échelle neutre, Surface et superposition, Ombres et profondeur
• Famille de polices, Hiérarchie, Principes
• Boutons, Cartes et conteneurs, Champs de saisie et formulaires, Navigation, Traitement des images, Composants distinctifs
• Système d'espacement, Grille et conteneur, Philosophie des espaces blancs, Échelle des rayons de bordure
• Points de rupture, Cibles tactiles, Stratégie de réduction
• Référence rapide des couleurs, Exemples de sollicitations de composants, Guide d'itération

Ne maintenez pas le document au niveau d'un résumé général si le site expose suffisamment de preuves pour être plus précis.

Contrat d'aperçu HTML

Générez un fichier HTML à côté du markdown par défaut.

L'aperçu doit :

• utiliser le DESIGN.md final comme source de vérité plutôt qu'un résumé séparé maintenu à la main
• utiliser un modèle d'aperçu fixe, pas un cadre HTML nouvellement inventé à chaque exécution
• afficher les règles visuelles les plus utiles à gauche, par exemple l'aperçu, la palette, la typographie, l'espacement, le rayon, les boutons, les cartes, la profondeur et les notes réactives
• garder la source markdown visible dans un volet dédié afin que l'utilisateur puisse inspecter ou copier le document original rapidement
• donner l'impression d'un tableau de conception soigné plutôt que d'un rendu markdown brut
• utiliser les jetons de conception extraits lorsque c'est pratique afin que l'aperçu lui-même reflète le système documenté

Utilisez assets/design-preview-shell.template.html comme coque par défaut lorsqu'elle est disponible. Traitez ce modèle comme une infrastructure stable et remplissez-y uniquement les jetons et le contenu documentés, sauf si l'utilisateur demande explicitement une nouvelle direction de mise en page.

Lorsque l'utilisateur fournit une référence visuelle pour la mise en page, suivez-la suffisamment fidèlement pour que le HTML soit reconnaissable comme étant de la même famille tout en étant généré à partir des données markdown.

Règles de synthèse

Lors de la rédaction du fichier final :

• Préférez les noms sémantiques aux étiquettes de jetons brutes.
• Incluez les valeurs hexadécimales exactes lorsque la précision des couleurs est importante.
• Traduisez les échelles de rayon, d'espacement, d'ombres et de typographie en langage simple qu'un autre agent peut utiliser immédiatement.
• Gardez le document déterminé et utilisable ; évitez les énormes déversements de données.
• Expliquez les rôles fonctionnels, pas seulement l'apparence.
• Regroupez les motifs récurrents en un système.
• Préservez les nuances. Si le site mélange deux modes visuels, décrivez les deux et quand chacun apparaît.
• Préférez les détails numériques précis lorsqu'ils sont observables : valeurs hexadécimales exactes, tailles de police, hauteurs de ligne, espacement des lettres, valeurs de rayon, unités d'espacement et formules d'ombres multicouches.
• Ajoutez une brève philosophie ou justification lorsqu'un motif est central à l'identité du site, par exemple "ombre-comme-bordure" ou "compression comme identité".
• Incluez des indices d'implémentation spécifiques aux composants lorsqu'ils aident un autre agent à construire une UI correspondante sans voir le site source.
• Incluez des exemples prêts à être utilisés dans le Guide de sollicitation d'agent pour au moins les motifs hero, carte, bouton ou navigation sur les sites substantiels.
• Lorsque certaines valeurs sont déduites plutôt qu'observées, gardez-les clairement étiquetées mais toujours utiles.

Exemple :

• "Les actions principales utilisent un bleu électrique froid #3B82F6"
• "La hauteur de ligne du corps est de 1.625, visant la lisibilité dans des paragraphes denses"
• "L'écart des cartes suit un multiple de l'espacement de base, généralement 16px"