Creazione di app, per gli agenti

Come un agente crea un'app Laze che le persone vogliono usare: regole di design, kit, elementi fissati e condivisione, push su trunk e verifica del proprio lavoro.

Questa pagina è scritta per un agente AI a cui viene chiesto di creare o modificare un'app Laze. Leggila prima del tuo primo laze app create. Le persone giudicano un'app nei primi cinque secondi: falla sembrare completa, mettila dove è stata richiesta e controllala tu prima di dire che è pronta.

Il flusso di lavoro#

1. Creala nella conversazione che l'ha richiesta:

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

   L'app parte vuota, con una cartella tutta tua: creala da zero, iniziando da index.html, poi laze app push. --channel fissa l'app come scheda di quella conversazione. Tutte le persone presenti, e i loro agenti, possono aprirla e continuare a svilupparla (Editor). Dai all'app un nome fatto di parole che le persone leggono, non uno slug.

   Collega il kit della piattaforma e il client dalla tua pagina:

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

   Le slide, una presentazione o un talk sono l'unica eccezione: partono da --template slides, l'unico modello. I suoi file sono la prima versione live dell'app, da modificare come vuoi. Ogni slide è un file in slides/, elencato in ordine in slides/deck.json; il README.md del modello spiega come aggiungere, riordinare e stilizzare le slide. La presentazione ha una barra delle slide, navigazione da tastiera, Present a schermo intero e pulsanti Export PDF ed Export HTML, quindi non crearli di nuovo. Su MCP, create_app con template: "slides" fa la stessa cosa, e write_app_files modifica una slide alla volta.

   Il modello per slide serve solo per una nuova presentazione. Quando una persona invia file che sono già una pagina o una presentazione (un export HTML, uno zip con index.html, un sito statico), pubblicali così come sono: crea l'app senza --template, estrai i file nella sua cartella con index.html in alto, copia dentro ogni script che carica da una CDN e fai il push. «Spostali qui» o «metti questo qui» con un allegato significa esattamente quello: fallo, non chiedere cosa significa.

2. Un'app già esistente va in una conversazione con una scheda fissata, non in un messaggio con un link:

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

   --role editor permette ai membri di modificare i dati ma non il codice, --view-only permette solo di guardare. laze app pins <channel> elenca le schede. Non fissare mai di nuovo un'app che una persona ha rimosso.

3. Dai forma ai dati in laze.app.json: una raccolta per ogni tipo di cosa, con campi tipizzati e alcuni record iniziali. I dati stanno nei record, mai nel codice della pagina. Una pagina che contiene numeri, righe o testo fissi nel codice è sbagliata: quando i dati cambiano, l'app deve cambiare senza un push.

4. Modifica la pagina, poi guardala in locale prima che vada live (vedi Controlla il tuo lavoro).

5. Fai il push:

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

   Ogni push diventa subito l'app live. Non ci sono bozze, branch o pull request: le app sono basate su trunk. Scrivi il messaggio come una frase semplice su cosa è cambiato per le persone. --seed riempie solo le raccolte che non hanno ancora record.

6. Torna indietro quando un push era sbagliato: laze app versions, poi laze app revert <version> -m "<why>". Questa è una nuova versione live; nessun record viene perso. La cronologia git dentro un'app serve solo a questo.

Chi può aprirla#

Una nuova app è Riservata. Un'app fissata in una conversazione si apre per tutti lì, quindi di solito una scheda fissata è tutta la condivisione che serve a un'app del team. Non condividere un'app solo con la persona che l'ha richiesta quando l'ha chiesta in un canale: fissala lì. Allarga l'accesso con laze app access visibility internal|public solo quando viene richiesto; il comando dice quando un admin deve approvare. laze app members mostra chi può aprirla ora. Controllalo prima di dire alle persone che l'app è pronta.

Regole di design#

Parti da ciò di cui parla l'app, non da un layout. Chiediti come una persona interessata all'argomento lo disegnerebbe su una lavagna, e crea quello: un modello di minaccia è una mappa di attacco, una roadmap è una timeline, un budget è un flusso di denaro, un processo è un diagramma. Una pagina di riquadri statistici e liste puntate sembra un report, ed è l'app da evitare.

Sii molto visivo: usa motion graphics e flussi dove puoi, e guida le persone un passo alla volta finché non hanno capito tutto. Non scrivere mai muri di testo: dove servono parole, usa frasi semplici e brevi. Un'app serve a far capire alle persone, non a riversare tutto quello che hai in testa.

Il kit Laze arriva dalla piattaforma (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). È una cassetta degli attrezzi, non un layout da riempire: prendi i suoi token e i controlli che ti servono, e metti sopra il tuo CSS nel tuo file. Non copiare mai il kit nell'app.

• Prima la parte visiva. Fai dell'immagine del soggetto l'app stessa: SVG inline, canvas, una mappa, una timeline, un diagramma, qualcosa su cui le persone possono fare clic ed esplorare. Dalle un aspetto suo, con il tuo layout e il tuo movimento sui token del kit.
• Un compito per schermata. La prima schermata risponde alla domanda per cui l'app esiste. Metti un secondo compito in una scheda (lz-tabs), non sotto il primo.
• La forma giusta. Usa una tabella (lz-table) o una bacheca (lz-board) quando le persone scorrono o spostano righe, un riquadro statistico (lz-stats, lz-stat-value) quando il punto è un solo numero, un grafico (lz-chart) per numeri nel tempo e passaggi numerati (lz-steps) per una breve sequenza. Il testo più lungo di tre righe appartiene a un documento, non a un'app.
• Dati reali. Mostra i record che contano per le persone, con i loro nomi e date reali. Niente «Lorem», «Item 1» o grafici segnaposto. Ogni affermazione nella pagina viene da un record o da un link.
• Scala tipografica. Un titolo di pagina (lz-title), una riga sotto (lz-lede), titoli di sezione (lz-h2 o lz-card-title), testo del corpo. Non aggiungere altre dimensioni.
• Spaziatura. Usa le classi di pagina (lz-page), scheda (lz-card lz-card-body) e griglia (lz-grid, lz-row); mantengono il ritmo da 12 a 20 px. Non impilare schede dentro altre schede.
• Entrambi i temi. I colori vengono solo dai token (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) e i toni lz-badge-*). Un colore esadecimale rompe la modalità scura.
• Larghezza ridotta. Le app si aprono in un pannello laterale largo circa 380 px. Dai alle celle delle tabelle data-label così le righe si impilano, e tieni le intestazioni su una sola riga.
• Stati vuoti e di errore. Una lista vuota dice cosa apparirà e come aggiungere il primo elemento. Una chiamata non riuscita mostra Laze.fail(error), mai una pagina vuota.
• Stati come badge. Mostra gli stati con lz-badge e un tono (-success, -warning, -danger, -info, -primary), non con testo colorato.
• I moduli non devono intralciare. Metti «Nuovo elemento» dietro un pulsante; la lista è il contenuto principale.

Riferimento del kit#

Gli script si caricano solo dall'origine dell'app: una CDN <script> viene rifiutata, quindi copia nella cartella dell'app una libreria che ti serve. Quando porti un artefatto claude.ai o un'altra pagina React, compila il suo JSX prima del push (per esempio npx esbuild app.jsx --bundle --minify --outfile=app.js) e collega il file compilato. Anche Babel nel browser funziona, ma carica megabyte a ogni apertura.

Nello script della pagina, Laze.records("<collection>") elenca, crea, aggiorna e rimuove record, Laze.subscribe ricarica quando ci sono cambiamenti, Laze.h crea elementi e Laze.mount li disegna.

Scorciatoie da tastiera#

Laze passa le proprie scorciatoie dalla tua app a Laze, a meno che la tua app non le gestisca, così le persone possono premere Cmd+K (Ctrl+K su Windows e Linux) per uscire da un'app senza dover prima fare clic fuori. Le scorciatoie inoltrate sono Cmd+K, Cmd+[ e Cmd+], da Cmd+1 a Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. e Cmd+/, più Alt+Up e Alt+Down fuori dai campi di testo. Ogni altro tasto resta nella tua app.

Per tenere una di queste scorciatoie per la tua app, gestisci il tasto e chiama event.preventDefault(); Laze poi la lascia stare:

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

Controlla il tuo lavoro#

Guarda ogni modifica prima di fare il push:

laze app serve --port 4173

Serve la tua cartella su http://127.0.0.1:4173/ con il kit della piattaforma e i record dell'app live, in sola lettura. Ha bisogno di una versione live, quindi esegui prima laze app push una volta. Aprila con il tuo strumento browser e fai screenshot in entrambi i temi e alla larghezza del pannello, per esempio:

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

Guarda ogni immagine. Correggi il testo che sborda, le colonne che non entrano, i colori che spariscono in modalità scura e qualsiasi cosa dica ancora «demo».

Prima di presentare l'app:

• È fissata dove è stata richiesta, e laze app members elenca le persone che devono poterla aprire.
• La prima schermata risponde alla richiesta senza scorrere.
• Gli screenshot chiaro, scuro e a 390 px sembrano completi.
• Il tuo messaggio dà il nome dell'app e una riga su cosa fa. La scheda nella conversazione è il link.

Chiedi quando non sei sicuro#

Fai alla persona una sola domanda breve invece di creare la cosa sbagliata. Non aspettare un «via» sui passaggi che ha già richiesto: se ha chiesto un'app in questo canale, creala lì, fissala e diglielo.