design

Design canvas

Vous concevez des écrans sous forme de fichiers HTML réels dans le projet et les affichez dans le viewer de design local. L'utilisateur voit chaque écran côte à côte, change la taille de l'appareil, bascule le thème clair/sombre, exporte en PNG et commente un écran ; les commentaires vous reviennent sous forme de messages avec un préfixe exact.

Fichiers (le contrat)

design/
  tokens.json            la source unique de vérité pour chaque jeton de design
                         (les deux thèmes) ; le seul endroit où vivent les valeurs de la marque
  design-system.css      GÉNÉRÉ depuis tokens.json : les jetons de design pour
                         [data-theme="light"] et [data-theme="dark"] (ne jamais éditer)
  utilities.css          GÉNÉRÉ depuis tokens.json : le vocabulaire fermé des utilitaires
                         (ne jamais éditer)
  design-system.md       les décisions de marque en mots (court)
  validate.mjs           le validateur (copié une fois par projet — voir Configuration)
  serve.mjs              petit serveur statique pour le viewer (copié une fois par projet)
  viewer.html            le viewer (copié une fois par projet)
  mock.js                runtime mock pour les écrans interactifs (copié une fois par projet)
  mock.css               styles statiques pour les classes du runtime mock (copiés une fois par
                         projet) — états toast/overlay/enter-transition ; les écrans le lient en tant que
                         `../mock.css` ; mock.js ne fait que basculer ces classes et n'injecte jamais de CSS
  scripts/               copiés une fois par projet (voir Configuration)
    gen-tokens.mjs       régénère design-system.css + utilities.css depuis
                         tokens.json
    sync-components.mjs  rematérialise chaque région de marqueur de composant à partir de son
                         partial (copié une fois par projet)
    marker-parser.mjs    le parseur de grammaire de marqueur partagé que sync importe à
                         l'exécution (copié une fois par projet)
  components/            registre des composants + partials seed (copiés une fois par
                         projet) : components.json + un partial par composant
  vendor/html-to-image.js  bibliothèque d'export PNG (copiée une fois par projet)
  index.json             {"canvases": ["login", ...]} pour que le viewer puisse les lister
  <canvas>/              un dossier par canvas, en kebab-case (login, dashboard)
    canvas.json
    data.json            données fictives optionnelles ; objet "scenarios" optionnel
                         avec des surcharges nommées de premier niveau (vides, critiques…)
    01-<screen>.html     un document HTML complet par écran
    assets/              images/scripts locaux optionnels

canvas.json (les écrans apparaissent dans cet ordre) :

{
  "title": "Login do app",
  "screens": [
    { "id": "login", "name": "Login", "file": "01-login.html", "device": "mobile" },
    { "id": "cadastro", "name": "Cadastro", "file": "02-cadastro.html", "device": "mobile" }
  ]
}

• device : mobile = 390×844, tablet = 834×1112, desktop = 1440×900 ; width/height optionnelles (entiers 100–10000) pour le remplacer.
• group (optionnel) : étiquette qui regroupe les écrans en blocs titrés dans la bande du viewer — les projets complexes restent lisibles (ex. "group": "Checkout").
• transition (optionnelle) : fade, slide-left ou none (par défaut). C'est l'animation d'entrée de l'écran après Mock.go — voir Workflow étape 3 pour la règle même-canvas/cross-canvas.
• id unique et non vide ; name non vide ; title optionnel.
• file est relatif au dossier du canvas : jamais .., / en tête, \ ou un schéma (http:, file:…).

Configuration unique par projet

Si design/ n'existe pas encore, créez-le et copiez depuis le dossier de cette compétence (le dossier contenant ce SKILL.md) :

• scripts/validate.mjs → design/validate.mjs
• assets/viewer.html → design/viewer.html
• assets/serve.mjs → design/serve.mjs
• assets/mock.js → design/mock.js
• assets/mock.css → design/mock.css (styles pour les classes du runtime mock ; les écrans lient ../mock.css)
• assets/docs.html → design/docs.html (guide d'utilisation, lié depuis le bouton 📘 Docs du viewer)
• assets/vendor/html-to-image.js → design/vendor/html-to-image.js
• scripts/gen-tokens.mjs → design/scripts/gen-tokens.mjs
• assets/components/ → design/components/ (registre + partials seed)
• scripts/sync-components.mjs → design/scripts/sync-components.mjs
• scripts/marker-parser.mjs → design/scripts/marker-parser.mjs (le module parseur partagé que sync importe, requis à l'exécution)
• scripts/export-tokens.mjs → design/scripts/export-tokens.mjs (l'export W3C/DTCG d'échange : tokens.json → tokens.w3c.json ; artefact dérivé, jamais édité à la main)

Règle pour cette liste de copie : seuls les fichiers qui existent déjà y entrent ("só entra no copy list arquivo que já existe"). Les fichiers à venir rejoignent uniquement à leur vague de Contrat : export-tokens.mjs a rejoint à la vague 6 du contrat (todo 30) et est listé ci-dessus — la règle est satisfaite (le fichier existe depuis le todo 26). (mock.css a rejoint à la vague 3 et est listé ci-dessus.)

Chaque fois que tokens.json change, régénérez les deux fichiers générés depuis la racine du projet :

node design/scripts/gen-tokens.mjs

Créez design/index.json ({"canvases": []}) et ajoutez-y chaque nouveau nom de canvas au fur et à mesure que vous créez des canvases. Un exemple complet et valide se trouve dans le dossier assets/example/ de cette compétence — un système d'application de stock fonctionnel sur deux canvases : login/ (connexion, inscription, et une modale de confirmation de suppression de compte ouverte comme overlay depuis un simple lien) et dashboard/ (aperçu interactif avec une longue liste d'articles, un rafraîchissement "Atualizar lista" sur le même canvas qui illustre la transition fade et la restauration du défilement), où la connexion et l'inscription naviguent entre les canvases vers l'aperçu, qui lit ses articles fictifs, supporte les scénarios nommés et se déconnecte pour revenir au canvas de connexion. Lisez-le avant de commencer un nouveau système de design ou canvas et adaptez-le. Le example/components/ seed est une copie octet par octet de assets/components/ ("example/components/ é cópia byte-idêntica de assets/components/ (fonte única)") : éditez les partials uniquement dans assets/components/, jamais dans la copie d'exemple.

Workflow

1. Système de design d'abord. Lisez design/design-system.css et design/design-system.md. S'ils n'existent pas, demandez à l'utilisateur la marque (couleur primaire, style de police, ton ; proposez une palette neutre comme option), puis créez les deux. Les canvases ultérieurs les réutilisent. Ne modifiez les jetons qu'après avoir demandé.
2. Demandez uniquement ce qui manque. Si la demande est vague (quels écrans, quelle plateforme, quelles données), demandez une fois ; si elle est claire, commencez.
3. Construisez le canvas. Lisez d'abord assets/craft.md depuis le dossier de cette compétence (il fusionne les compétences de conception sœurs — taste, emil-design-eng, impeccable — en règles pour les écrans du canvas) et appliquez-le à chaque écran. Créez ensuite canvas.json et les écrans. Règles pour chaque écran :
   • Politique de style : le vocabulaire des utilitaires est le vocabulaire. Tout ce qui est basé sur des jetons (couleurs, typographie, espacement, rayon) passe par les utilitaires générés : liez <link rel="stylesheet" href="../design-system.css"> et <link rel="stylesheet" href="../utilities.css">, puis utilisez des classes comme bg-accent, p-2, text-heading, rounded-md. Les écrans interactifs lient aussi <link rel="stylesheet" href="../mock.css"> (les classes du runtime mock : toast, overlay, transitions d'entrée). Les classes sémantiques ne portent que la structure et la mise en page. Les var(--…) sont autorisés là où aucun utilitaire ne convient, et un bloc <style> en ligne est autorisé mais doit contenir ZÉRO couleur littérale. La chasse aux interdits scanne les couleurs littérales dans <style>, style="" et les positions VALEUR de fill=/stroke= en SVG ; elle interdit aussi http(s):// partout dans les écrans, les classes de la palette Tailwind comme bg-zinc-900, et les valeurs arbitraires comme text-[13px].
   • Travaillez dans les deux thèmes via les jetons ; le thème arrive sous la forme data-theme sur <html> (light par défaut — incluez l'attribut).
   • Pas de CDN ni d'URL distante d'aucune sorte (le canvas est hors ligne et sandboxé) : icônes SVG en ligne, polices système ou fichiers de polices sous design/, images locales.
   • Texte réel dans la langue de l'utilisateur (portugais brésilien par défaut) et données d'exemple plausibles — pas de lorem ipsum.
   • Couvrez les états vides, de chargement et d'erreur quand ils sont pertinents, en tant qu'écrans supplémentaires.
   • Bases d'accessibilité : étiquettes sur les entrées, focus visible, contraste suffisant, cibles tactiles ≥ 44 pixels sur mobile.
   • La mise en page doit tenir à la largeur de l'appareil de l'écran.
   • Les composants sont des instances de partials, jamais de balisage de composant libre ("instância usa partial, nunca markup solto de componente"). Encadrez chaque instance dans la paire de marqueurs <!-- component:id size=md tone=primary state=default -->…<!-- /component:id --> avec les TROIS arguments requis size=, tone=, state= (les valeurs doivent être dans les énumérations du registre de design/components/components.json), et remplissez ses emplacements avec des marqueurs appairés <!-- slot:name -->…<!-- /slot:name -->. Préséance : les arguments du marqueur sont la source de vérité (marker-args-win). La synchronisation réémet data-size/data-tone/data-state et les classes de variante depuis le marqueur à chaque exécution ; le contenu des emplacements et les attributs data-* supplémentaires de l'utilisateur sur la racine survivent.
   • Faites-en un aperçu système, pas une affiche. Lorsque la demande implique un produit fonctionnel, connectez les écrans avec le runtime mock (<script src="../mock.js"></script>, copié par Configuration) : les formulaires valident et soumettent, les boutons donnent un retour, les écrans naviguent avec Mock.go('03-dashboard.html'), les données fictives vivent dans le fichier data.json du canvas (await Mock.data('items')), l'état du flux (utilisateur connecté, articles créés en cours de route) vit dans Mock.state (session, espaces de noms par canvas), et les actions simulées confirment avec Mock.toast('…'). Chaque écran doit toujours être rendu comme une composition statique si JS échoue. Le viewer affiche un bouton ↺ início sur les cartes qui ont navigué et "⟲ Reset fluxo" pour recommencer tout le flux. Couvrez les états qui comptent sous forme de scenarios nommés dans data.json (surcharges de premier niveau, ex. "vazio": {"items": []}) — le viewer gagne un sélecteur pour eux, le choix survit à la navigation, et chaque scénario doit bien composer (liste vide, tous les articles en dessous du minimum, échec API). Un système peut couvrir plusieurs canvases (un par flux) : naviguez entre eux avec Mock.go('../<canvas>/<screen>.html') — l'état du flux est partagé à l'échelle du projet, donc le canvas de connexion définit l'utilisateur et le canvas du tableau de bord le lit. Le sélecteur de canvas du viewer saute entre les canvases (chaque canvas conserve son propre scénario, thème et appareil). Les modales et les boîtes de dialogue de confirmation sont aussi des écrans de canvas complets (une source de vérité) : le déclencheur est un lien d'écran simple, <a href="03-modal.html">, que le runtime mock intercepte en Mock.overlay('03-modal.html') — sans JS, le href non modifié navigue vers l'écran de la modale lui-même (la solution de repli JS off). La navigation persistante (barre latérale, menu supérieur, onglets) doit changer d'écran pour de vrai : mettez data-go="02-cadastro.html" sur chaque élément (gardez un vrai href="02-cadastro.html" sur le même lien comme solution de repli JS off — le runtime route data-go vers Mock.go, en conservant ?scenario= et la transition d'entrée). Les liens simples restent réservés aux déclencheurs d'overlay (modales/détails — un lien d'écran simple ouvre toujours un overlay) ; répétez le même bloc de navigation sur chaque écran du canvas et marquez l'élément actif. Les écrans peuvent déclarer "transition": "fade"|"slide-left"|"none" dans canvas.json : Mock.go passe une classe d'entrée à la destination (mock-enter-fade/mock-enter-slide-left, auto-supprimée en 300 ms). La remise lit le canvas.json du canvas ACTUEL correspondant au nom de fichier de la destination, donc cela fonctionne pour les sauts sur le même canvas (une auto-navigation comme Mock.go('01-overview.html') est le modèle de rafraîchissement) — un Mock.go('../<canvas>/<screen>.html') inter-canvas est une navigation simple sans classe d'entrée. La position de défilement est préservée par écran (scroll.<canvas>.<file> dans sessionStorage, restaurée lorsque l'écran revient et survivant à ⟲ Reset fluxo, qui efface uniquement mock.*).
4. Validez et corrigez. Synchronisation OBLIGATOIRE d'abord : après avoir édité un partial dans design/components/ (ou les arguments d'un marqueur), exécutez node design/scripts/sync-components.mjs depuis la racine du projet avant de présenter quoi que ce soit ; il rematérialise chaque instance à partir de son partial (marker-args-win). --check est la forme à blanc : il imprime un diff fichier:ligne par région divergente et se termine avec 1 en cas de divergence (0 propre), sans jamais écrire. Exécutez ensuite depuis la racine du projet : node design/validate.mjs design/<canvas>. Corrigez chaque problème qu'il liste et exécutez à nouveau jusqu'à ce qu'il ne reste que la ligne récapitulative. Ne présentez jamais un canvas qui a des problèmes. L'argument du validateur est une racine de design (mode projet) ou un seul dossier de canvas (mode canvas) ; sans argument, il prend par défaut ./design. Les vérifications structurelles ne couvrent que les écrans listés dans canvas.json ; le mode projet vérifie en plus l'obsolescence des jetons/CSS généré, les composants et les commentaires. Les règles de composants sont scannées sur chaque .html non exempté, indépendamment de canvas.json, avec les codes component-unknown, component-variant, component-marker, component-divergence et slot-marker. --allow-stale saute UNIQUEMENT la vérification d'obsolescence ; --mark-stale est la seule écriture du validateur (il marque les épingles de commentaires dont l'ancre a disparu) ; --example-inventory est la vérification du contrat d'exemple (liste de fichiers exacte de inventory.json + "_demo": true sur chaque épingle ; pas de inventory.json = saute, sortie 0). 4b. Audit impeccable. Après la validation, exécutez l'audit technique de la compétence sœur impeccable sur le canvas (layout installé, win32) : <skill-impeccable>/scripts/impeccable.cmd audit design/<canvas> - le chemin est résolu depuis le répertoire installé.

…

[truncé pour la traduction]