Spécification UI à partir du code
La vidéo reconstruit l'interface du produit en HTML et CSS au lieu de l'enregistrer, de sorte que l'interface n'est aussi fidèle que la spécification sur laquelle elle est construite. Les approximations sont détectées : dans la production d'où proviennent ces compétences, un relecteur a rejeté des icônes et logos dessinés à la main lors de la première relecture, et un badge fabriqué à la main avec une taille et un nom incorrects l'a rendu furieux. Les correctifs viennent de la lecture du code, et le code cachait des pièges que personne ne voit à l'œil nu : la taille de police racine était définie au temps d'exécution par le shell de l'application (14 px, pas les 10 px déclarés dans la feuille de style), plusieurs variables CSS n'existaient pas en production et affichaient leur valeur de repli, un composant avait perdu sa barre d'accentuation dans un commit deux mois plus tôt, et deux « dialogues » étaient des pop-ups personnalisés, pas le dialogue de la bibliothèque.
Donc chaque valeur dans une spécification est littérale et citée, et une valeur que vous ne pouvez pas citer est signalée, jamais devinée.
Entrées
videos/<video>/SOURCES.mdde source-recon : chaque écran, sa route, ses composants et son état. S'il manque, exécutez d'abord source-recon.sources/<rôle>/etsources.lock. Chaque citation utilise le sha verrouillé.product.yaml:app_canvas.logical(le viewport dans lequel l'UI est reconstruite),app_canvas.theme,app_canvas.rem_px,sources[].framework.- L'adaptateur pour le framework :
references/adapters/<framework>.md. Lisez-le avant d'écrire les invites des sous-agents ; il indique où se cachent les valeurs dans cette pile.
| framework dans product.yaml | adaptateur | statut |
|---|---|---|
angular-primeng | references/adapters/angular-primeng.md | prouvé en production |
react | references/adapters/react.md | non prouvé |
vue | references/adapters/vue.md | non prouvé |
| toute pile utilisant Tailwind | references/adapters/tailwind.md (avec celui du framework) | non prouvé |
html, other, templates serveur | references/adapters/html.md | non prouvé |
Pour un adaptateur non prouvé, dites à l'utilisateur qu'il n'est pas prouvé, suivez-le et ajoutez ce que vous apprenez à la fin (une courte section « Appris sur »), afin que le prochain produit parte de plus loin.
1. Faits de rendu globaux (une fois par produit)
Avant tout écran, établissez les faits dont dépend chaque écran et écrivez-les dans
kit/render-facts.md avec des citations :
- Taille de police racine au moment de l'exécution (cherchez dans le shell de l'application le code qui la définit, pas seulement le CSS),
pour que
remse convertisse correctement. Mettez à jourapp_canvas.rem_pxdans product.yaml s'il diffère. - Thème : quel sélecteur active le thème de la vidéo, et s'il est activé par défaut.
- Fichiers de tokens, l'ordre des couches CSS ou des importations (quelles règles l'emportent), et la bibliothèque de composants avec sa version exacte issue du fichier lock et son préréglage de thème.
- Polices réellement chargées (balises link,
@font-face, paquets de polices), pas seulement nommées dans le CSS. Une police qui est déclarée mais jamais chargée s'affiche comme police de repli en production. - Le point de rupture bureau, pour confirmer que
app_canvas.logicalaffiche la maquette bureau.
Ensuite, écrivez les tokens, résolus en littéraux pour le thème de la vidéo :
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/ui-spec-from-code/scripts/resolve_tokens.py" <répertoire_produit> \
[--role frontend] [--theme-selector "html.dark"] [--files src/styles/tokens.css ...]
Il lit les propriétés personnalisées CSS, les variables SCSS de niveau supérieur et un thème Tailwind v3 (statiquement)
depuis sources/<rôle>/, résout chaque var() et $variable, et écrit kit/tokens.css avec
une citation /* rôle/chemin:ligne@sha */ sur chaque ligne. Les lignes signalées UNDEFINED sont des variables
que la production ne définit pas (un problème probable) ; needs a Sass compile marque les valeurs construites avec des fonctions
Sass, que le sous-agent doit résoudre manuellement à partir de la fonction et de ses entrées. Utilisez
--files lorsque l'exportation contient des feuilles de style non liées (sites de documentation, modèles d'e-mail, CSS
vendu).
2. Un sous-agent par écran
Lancez un sous-agent en lecture seule par écran (ou par panneau d'un grand écran), tous en parallèle, avec
references/ui-spec-prompt.md rempli et la liste « où se cachent les valeurs » de l'adaptateur ajoutée.
Pointez chacun vers sources/<rôle>/ (pas vers le checkout de l'utilisateur) et donnez-lui le contexte de rendu :
taille logique du canevas, thème, rem, faits de rendu, tokens et le CSS des pièces déjà reconstruites pour que
la nouvelle pièce corresponde.
Chacun renvoie : géométrie dans le canevas, HTML statique par état (pas de syntaxe framework), un bloc CSS avec des valeurs littérales et une citation par valeur, les états survol/actif/focus/désactivé/chargement en tant que classes supplémentaires, les transitions et images clés avec durées et easings exacts, les icônes par bibliothèque et nom (ou SVG en ligne textuellement), chaque chaîne visible, et une liste explicite « non vérifié ».
Le coordinateur (vous) n'extrait pas lui-même les spécifications : un écran d'une application réelle peut prendre des dizaines de kilooctets de résultats, et un coordinateur dont le contexte se remplit au milieu de la vidéo perd la trace de l'ensemble de la construction.
3. Icônes et images
Les icônes proviennent des propres jeux d'icônes et ressources du produit, jamais dessinées et jamais issues d'un profil de
navigateur ou d'un dossier d'extension. Exécutez references/icon-extraction-prompt.md une fois par produit (et
à nouveau pour les nouveaux écrans) pour mapper chaque icône dont une vidéo a besoin à sa bibliothèque et son nom, puis transmettez les
noms à collect_icons.py de product-kit, qui copie les SVG dans kit/icons/ avec
citations. Pour les polices d'icônes sans fichiers SVG, la construction écrit les points de code à partir du CSS
propre de la bibliothèque et doit échouer sur un nom inconnu plutôt que d'afficher un cadre vide.
4. Écrire les spécifications
Pour chaque écran, videos/<video>/specs/<écran>.md et specs/<écran>.html :
# Spec: <écran>
Source: frontend@1a2b3c4 (voir SOURCES.md). Canvas 1440x810, thème clair, rem 16.
## Géométrie
| élément | x | y | w | h | citation |
## États
E1 <nom> : <ce qui est affiché, données fictives>. HTML dans <écran>.html, section E1.
## CSS
<un bloc, valeurs littérales, chaque ligne avec /* rôle/chemin:ligne@sha */>
## Mouvement
| quoi | propriété | de | à | durée | easing | délai | citation |
## Icônes
| clé | bibliothèque | nom | fichier dans kit/icons | citation |
## Chaînes
| clé | texte | citation |
## Correctifs (défauts de production corrigés dans la vidéo)
| quoi | production fait | vidéo fait | pourquoi |
## Non vérifié
- <valeur ou comportement, pourquoi, et la meilleure référence disponible>
Conserver l'apparence, corriger les défauts
Reconstruisez la disposition, les tokens et le comportement 1:1, y compris les animations, les survols, les états de frappe et de chargement qui donnent l'impression d'être le vrai produit. Mais corrigez les défauts de production visibles, car la vidéo montre le produit sous son meilleur jour et un relecteur demandera pourquoi un bug est à l'écran : remplissage manquant, débordement, texte tronqué, un contrôle natif du navigateur (un lecteur audio gris par défaut) alors que le produit signifie un contrôle conçu, une variable non définie affichant une valeur de repli, un anneau de focus laissé après un clic. Listez chaque correctif dans le tableau des correctifs de la spécification et dans les notes BRIEF. Conservez les bizarreries qui sont des décisions de conception (un pied de page collant couvrant un champ, une barre latérale qui défile avec son contenu) ; les modifier est une refonte, pas un correctif.
Deux autres transformations que la spécification applique et enregistre :
- Noms canoniques. Remplacez les chaînes héritées de
product.yaml namespar le nom canonique même lorsque l'UI en direct montre encore l'ancien, et conservez tout le reste sur cet élément. - Termes interdits. Si un écran réel montre un fournisseur ou un terme dans
banned_terms(un sélecteur de modèle, une carte d'intégration), laissez cette partie hors cadre. Elle ne doit pas paraître vide ou cassée ; choisissez un cadrage ou un état où elle est naturellement absente.
Données
Les spécifications ne portent que des données fictives, issues de product.yaml cast. Les fixtures, les seeds et les captures d'écran dans
le dépôt peuvent contenir des vrais noms ; utilisez leur forme, jamais leurs valeurs.
Liste de contrôle avant de remettre les spécifications à la construction
- Commit verrouillé cité ; faits de rendu écrits ; tokens résolus pour le thème de la vidéo
- Taille du canevas au-dessus du point de rupture bureau ; rem correspond au runtime
- Chaque
var()résolue ; les non définies listées avec leur valeur de repli (ou corrigées comme un défaut) - Chaque chaîne provenant du fichier i18n ou du template ; noms canoniques appliqués
- Chaque icône provenant des bibliothèques de l'application ; la construction échoue sur un glyphe manquant
- Logos et images provenant des ressources du dépôt
- États par défaut (onglets, accordéons, bascules) correspondent au code
- Temporisations des superpositions, pop-ups et transitions avec easings exacts
- Plages de défilement dans le contenu réel ; aucun texte coupé à un bord
- Aucun fournisseur, terme interdit, identifiant interne ou donnée client réelle dans le cadre
- Correctifs et bizarreries conservés listés ; valeurs non vérifiées listées pour le relecteur