Créer des apps, pour les agents

Comment un agent crée une app Laze que les personnes ont envie d’utiliser : règles de conception, kit, épingles et partage, pushs sur trunk et vérification de son propre travail.

Cette page est écrite pour un agent d'IA chargé de créer ou de modifier une app Laze. Lisez-la avant votre premier laze app create. Les personnes jugent une app en cinq secondes : donnez-lui un aspect fini, placez-la là où elle a été demandée et vérifiez-la vous-même avant de dire qu'elle est prête.

Le workflow#

1. Créez-la dans la conversation qui l'a demandée :

   laze app create "Insights" --channel <channel>

   L'app démarre vide, avec un dossier à vous : créez-la de zéro, en commençant par index.html, puis laze app push. --channel épingle l'app comme onglet de cette conversation. Toutes les personnes qui y participent, ainsi que leurs agents, peuvent l'ouvrir et la modifier (Éditeur). Donnez à l'app un nom lisible par des personnes, pas un slug.

   Référencez le kit de la plateforme et le client depuis votre page :

   <link rel="stylesheet" href="/_laze/theme.css" />
   <link rel="stylesheet" href="/_laze/kit.css" />
   <script src="/_laze/laze.js"></script>

   Les diapositives, un deck ou une présentation orale sont la seule exception : ils partent de --template slides, le seul modèle. Ses fichiers sont la première version en ligne de l'app, à vous de les modifier. Chaque diapositive est un fichier dans slides/, listé dans l'ordre dans slides/deck.json ; le README.md du modèle explique comment ajouter, réordonner et styliser les diapositives. Le deck a un rail de diapositives, une navigation au clavier, un mode Présentation plein écran, et des boutons Export PDF et Export HTML. Ne les recréez donc pas. Avec MCP, create_app avec template: "slides" fait la même chose, et write_app_files modifie une diapositive à la fois.

   Le modèle de diapositives sert uniquement à créer un nouveau deck. Quand une personne envoie des fichiers qui sont déjà une page ou un deck, comme un export HTML, un zip avec index.html ou un site statique, mettez-les en ligne tels quels : créez l'app sans --template, décompressez les fichiers dans son dossier avec index.html à la racine, copiez tout script chargé depuis un CDN, puis poussez. « Déplace-les ici » ou « mets ça ici » avec une pièce jointe signifie exactement cela : faites-le, ne demandez pas ce que cela veut dire.

2. Une app qui existe déjà va dans une conversation avec un onglet épinglé, pas dans un message avec un lien :

   laze app pin <app> --channel <channel>

   --role editor permet aux membres de modifier les données, mais pas le code. --view-only leur permet seulement de regarder. laze app pins <channel> liste les onglets. N'épinglez jamais de nouveau une app qu'une personne a désépinglée.

3. Structurez les données dans laze.app.json : une collection par type d'objet, avec des champs typés et quelques enregistrements de départ. Les données vivent dans des enregistrements, jamais dans le code de la page. Une page qui code en dur ses nombres, ses lignes ou son texte est incorrecte : quand les données changent, l'app doit changer sans push.

4. Modifiez la page, puis regardez-la localement avant sa mise en ligne (voir Vérifiez votre propre travail).

5. Poussez :

   laze app push -m "Added the pipeline board" --seed

   Chaque push devient immédiatement l'app en ligne. Il n'y a pas de brouillons, de branches ni de pull requests : les apps sont basées sur le tronc. Écrivez le message comme une phrase simple sur ce qui a changé pour les personnes. --seed remplit seulement les collections qui n'ont pas encore d'enregistrements.

6. Utilisez Retour quand un push était incorrect : laze app versions, puis laze app revert <version> -m "<why>". C'est une nouvelle version en ligne ; aucun enregistrement n'est perdu. L'historique git dans une app ne sert qu'à cela.

Qui peut l'ouvrir#

Une nouvelle app est Restreinte. Une app épinglée dans une conversation s'ouvre pour toutes les personnes qui y participent. Un onglet épinglé suffit donc généralement pour le partage dont une app d'équipe a besoin. Ne partagez pas une app uniquement avec la personne qui l'a demandée quand elle l'a demandée dans un canal : épinglez-la dans ce canal. Élargissez avec laze app access visibility internal|public seulement si on vous le demande ; la commande indique quand un administrateur doit approuver. laze app members montre qui peut l'ouvrir maintenant. Vérifiez-le avant de dire aux personnes que l'app est prête.

Règles de conception#

Partez de ce que l'app représente, pas d'une mise en page. Demandez-vous comment une personne concernée par le sujet le dessinerait sur un tableau blanc, puis créez cela : un modèle de menace est une carte d'attaque, une roadmap est une chronologie, un budget est un flux d'argent, un processus est un diagramme. Une page de tuiles de statistiques et de listes à puces se lit comme un rapport, et c'est l'app à éviter.

Soyez très visuel : utilisez des animations et des flux dès que possible, et guidez les gens une étape à la fois jusqu'à ce qu'ils comprennent tout. N'écrivez jamais de murs de texte : là où il faut des mots, utilisez des phrases simples et courtes. Une app sert à faire comprendre aux gens, pas à déverser tout ce que vous avez en tête.

Le kit Laze vient de la plateforme (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). C'est une boîte à outils, pas une mise en page à remplir : prenez ses tokens et les contrôles dont vous avez besoin, puis ajoutez votre propre CSS dans votre propre fichier par-dessus. Ne copiez jamais le kit dans l'app.

• Le visuel d'abord. Faites de la représentation du sujet l'app elle-même : SVG inline, canvas, carte, chronologie, diagramme, quelque chose que les personnes cliquent et explorent. Donnez-lui un style propre, avec votre mise en page et vos animations sur les tokens du kit.
• Une tâche par écran. Le premier écran répond à la question pour laquelle l'app existe. Mettez une deuxième tâche dans un onglet (lz-tabs), pas sous la première.
• La bonne forme. Utilisez un tableau (lz-table) ou un tableau de bord (lz-board) quand les personnes parcourent ou déplacent des lignes, une tuile de statistique (lz-stats, lz-stat-value) quand un nombre est l'essentiel, un graphique (lz-chart) pour des nombres dans le temps et des étapes numérotées (lz-steps) pour une courte séquence. Un texte de plus de trois lignes a sa place dans un document, pas dans une app.
• De vraies données. Montrez les enregistrements qui comptent pour les personnes, avec leurs vrais noms et dates. Pas de « Lorem », « Élément 1 » ni de graphiques d'exemple. Chaque affirmation sur la page vient d'un enregistrement ou d'un lien.
• Échelle typographique. Un titre de page (lz-title), une ligne dessous (lz-lede), des titres de section (lz-h2 ou lz-card-title), du texte de corps. N'ajoutez pas d'autres tailles.
• Espacement. Utilisez les classes de page (lz-page), de carte (lz-card lz-card-body) et de grille (lz-grid, lz-row) ; elles maintiennent un rythme de 12 à 20 px. N'empilez pas des cartes dans des cartes.
• Les deux thèmes. Les couleurs viennent uniquement des tokens (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) et les tons lz-badge-*). Une couleur hexadécimale casse le mode sombre.
• Largeur étroite. Les apps s'ouvrent dans un panneau latéral d'environ 380 px de large. Ajoutez data-label aux cellules de tableau pour que les lignes s'empilent, et gardez les en-têtes sur une ligne.
• États vides et d'erreur. Une liste vide dit ce qui apparaîtra et comment ajouter le premier élément. Un appel qui échoue affiche Laze.fail(error), jamais une page blanche.
• Les statuts en badges. Affichez les états avec lz-badge et un ton (-success, -warning, -danger, -info, -primary), pas avec du texte coloré.
• Les formulaires restent discrets. Placez « Nouvel élément » derrière un bouton ; la liste est le contenu principal.

Référence du kit#

Les scripts se chargent uniquement depuis la propre origine de l'app : un CDN <script> est refusé. Copiez donc la bibliothèque dont vous avez besoin dans le dossier de l'app. Lorsque vous portez un artefact claude.ai ou une autre page React, compilez son JSX avant de pousser, par exemple npx esbuild app.jsx --bundle --minify --outfile=app.js, et liez le fichier généré. Babel dans le navigateur fonctionne aussi, mais il charge des mégaoctets à chaque ouverture.

Dans le script de la page, Laze.records("<collection>") liste, crée, met à jour et supprime les enregistrements, Laze.subscribe recharge lors des changements, Laze.h crée les éléments et Laze.mount les dessine.

Raccourcis clavier#

Laze laisse passer ses propres raccourcis depuis votre app vers Laze, sauf si votre app les gère. Les personnes peuvent donc appuyer sur Cmd+K (Ctrl+K sur Windows et Linux) pour quitter une app sans devoir d'abord cliquer en dehors. Les raccourcis transmis sont Cmd+K, Cmd+[ et Cmd+], Cmd+1 à Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. et Cmd+/, ainsi que Alt+Up et Alt+Down hors des champs de texte. Toutes les autres touches restent dans votre app.

Pour garder l'un d'eux pour votre app, gérez la touche et appelez event.preventDefault() ; Laze n'y touche alors pas :

document.addEventListener("keydown", (event) => {
  if ((event.metaKey || event.ctrlKey) && event.key === "k") {
    event.preventDefault();
    openSearch();
  }
});

Vérifiez votre propre travail#

Regardez chaque changement avant de le pousser :

laze app serve --port 4173

Cela sert votre dossier sur http://127.0.0.1:4173/ avec le kit de la plateforme et les enregistrements de l'app en ligne, en lecture seule. Il faut une version en ligne, donc lancez d'abord laze app push une fois. Ouvrez-la avec votre outil de navigateur et faites-en une capture d'écran dans les deux thèmes et à la largeur du panneau, par exemple :

npx -y playwright install chromium   # once
npx -y playwright screenshot --viewport-size=1100,800 http://127.0.0.1:4173/ light.png
npx -y playwright screenshot --viewport-size=1100,800 "http://127.0.0.1:4173/?theme=dark" dark.png
npx -y playwright screenshot --viewport-size=390,800 http://127.0.0.1:4173/ narrow.png

Regardez chaque image. Corrigez le texte qui déborde, les colonnes qui ne tiennent pas, les couleurs qui disparaissent en mode sombre et tout ce qui dit encore « démo ».

Avant de publier l'app :

• Elle est épinglée là où elle a été demandée, et laze app members liste les personnes qui doivent pouvoir l'ouvrir.
• Le premier écran répond à la demande sans faire défiler.
• Les captures d'écran en clair, en sombre et à 390 px ont un aspect fini.
• Votre message donne le nom de l'app et une ligne sur ce qu'elle fait. L'onglet dans la conversation est le lien.

Demandez en cas de doute#

Posez une courte question à la personne au lieu de créer la mauvaise chose. N'attendez pas un « feu vert » pour les étapes déjà demandées : si la personne a demandé une app dans ce canal, créez-la là, épinglez-la et dites-le-lui.