Creación de apps, para agentes

Cómo un agente crea una app de Laze que las personas quieran usar: reglas de diseño, el kit, fijaciones y uso compartido, pushes a trunk y revisión de su propio trabajo.

Esta página está escrita para un agente de IA al que se le pide crear o cambiar una app de Laze. Léela antes de tu primer laze app create. Las personas juzgan una app en los primeros cinco segundos: haz que parezca terminada, ponla donde la pidieron y revísala tú mismo antes de decir que está lista.

El flujo de trabajo#

1. Créala en la conversación que la pidió:

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

   La app empieza vacía, con una carpeta que es tuya: créala desde cero, empezando por index.html y luego laze app push. --channel fija la app como pestaña de esa conversación. Todos en ella, y sus agentes, pueden abrirla y trabajar sobre ella (Editor). Ponle a la app un nombre con palabras que las personas lean, no un slug.

   Vincula el kit de la plataforma y el cliente desde tu página:

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

   Las diapositivas, una presentación o una charla son la única excepción: empiezan desde --template slides, la única plantilla. Sus archivos son la primera versión en vivo de la app, y puedes cambiarlos. Cada diapositiva es un archivo en slides/, listado en orden en slides/deck.json; el README.md de la plantilla dice cómo añadir, reordenar y dar estilo a las diapositivas. La presentación tiene una barra de diapositivas, navegación con teclado, Presentar a pantalla completa y botones para Exportar PDF y Exportar HTML, así que no vuelvas a crear eso. Por MCP, create_app con template: "slides" hace lo mismo, y write_app_files cambia una diapositiva a la vez.

   La plantilla de diapositivas es solo para una presentación nueva. Cuando una persona envía archivos que ya son una página o una presentación, como una exportación HTML, un zip con index.html o un sitio estático, súbelos tal como están: crea la app sin --template, descomprime los archivos en su carpeta con index.html en la parte superior, copia cualquier script que cargue desde un CDN y publícala. "Muévelos aquí" o "pon esto aquí" con un adjunto significa exactamente eso: hazlo, no preguntes qué significa.

2. Una app que ya existe va en una conversación con una pestaña fijada, no en un mensaje con un enlace:

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

   --role editor permite que los miembros cambien datos, pero no el código. --view-only solo les permite mirar. laze app pins <channel> muestra las pestañas. Nunca vuelvas a fijar una app que una persona desfijó.

3. Da forma a los datos en laze.app.json: una colección por cada tipo de cosa, con campos tipados y unos pocos registros iniciales. Los datos viven en registros, nunca en el código de la página. Una página que lleva sus números, filas o texto escritos en el código está mal: cuando cambian los datos, la app debe cambiar sin publicar nada.

4. Cambia la página y luego mírala en local antes de que pase a estar en vivo (consulta Revisa tu propio trabajo).

5. Publica:

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

   Cada publicación es la app en vivo al instante. No hay borradores, ramas ni pull requests: las apps se basan en trunk. Escribe el mensaje como una frase sencilla sobre lo que cambió para las personas. --seed solo rellena colecciones que aún no tienen registros.

6. Volver cuando una publicación fue incorrecta: laze app versions y luego laze app revert <version> -m "<why>". Esa es una nueva versión en vivo; no se pierde ningún registro. El historial de git dentro de una app solo sirve para esto.

Quién puede abrirla#

Una app nueva es Restringida. Una app fijada en una conversación se abre para todos allí, así que una pestaña fijada suele ser todo lo que una app de equipo necesita para compartirse. No compartas una app solo con la persona que la pidió cuando la pidió en un canal: fíjala allí. Amplía el acceso con laze app access visibility internal|public solo cuando te lo pidan; el comando indica cuándo debe aprobarlo un admin. laze app members muestra quién puede abrirla ahora. Revísalo antes de decirle a la gente que la app está lista.

Reglas de diseño#

Empieza por el tema de la app, no por un diseño. Pregunta cómo lo dibujaría en una pizarra alguien a quien le importa el tema y crea eso: un modelo de amenazas es un mapa de ataques, una hoja de ruta es una línea de tiempo, un presupuesto es un flujo de dinero, un proceso es un diagrama. Una página de tarjetas de estadísticas y listas con viñetas se lee como un informe, y esa es la app que hay que evitar.

Sé muy visual: usa gráficos en movimiento y flujos siempre que puedas, y guía a las personas paso a paso hasta que lo entiendan del todo. Nunca escribas muros de texto: donde necesites palabras, usa frases simples y cortas. Una app es para que las personas entiendan, no para volcar lo que tienes en la cabeza.

El kit de Laze viene de la plataforma (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). Es una caja de herramientas, no un diseño que haya que rellenar: toma sus tokens y los controles que necesites, y pon tu propio CSS en tu propio archivo encima. Nunca copies el kit dentro de la app.

• Primero lo visual. Haz que la imagen del tema sea la app en sí: SVG en línea, canvas, un mapa, una línea de tiempo, un diagrama, algo que las personas puedan clicar y explorar. Dale un aspecto propio, con tu propio diseño y movimiento sobre los tokens del kit.
• Una tarea por pantalla. La primera pantalla responde la pregunta para la que existe la app. Pon una segunda tarea en una pestaña (lz-tabs), no debajo de la primera.
• La forma correcta. Usa una tabla (lz-table) o un tablero (lz-board) cuando las personas revisen o muevan filas, una tarjeta de estadísticas (lz-stats, lz-stat-value) cuando un número sea lo importante, un gráfico (lz-chart) para números a lo largo del tiempo y pasos numerados (lz-steps) para una secuencia corta. El texto de más de tres líneas va en un documento, no en una app.
• Datos reales. Muestra los registros que importan a las personas, con sus nombres y fechas reales. Nada de "Lorem", "Item 1" ni gráficos de marcador de posición. Cada afirmación en la página viene de un registro o de un enlace.
• Escala tipográfica. Un título de página (lz-title), una línea debajo (lz-lede), títulos de sección (lz-h2 o lz-card-title), texto de cuerpo. No añadas otros tamaños.
• Espaciado. Usa las clases de página (lz-page), tarjeta (lz-card lz-card-body) y cuadrícula (lz-grid, lz-row); mantienen el ritmo de 12 a 20 px. No apiles tarjetas dentro de tarjetas.
• Ambos temas. Los colores vienen solo de tokens (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) y los tonos de lz-badge-*). Un color hexadecimal rompe el modo oscuro.
• Ancho estrecho. Las apps se abren en un panel lateral de unos 380 px de ancho. Da data-label a las celdas de la tabla para que las filas se apilen, y mantén los encabezados en una línea.
• Estados vacío y de error. Una lista vacía dice qué aparecerá y cómo añadir el primer elemento. Una llamada fallida muestra Laze.fail(error), nunca una página en blanco.
• Estados como insignias. Muestra los estados con lz-badge y un tono (-success, -warning, -danger, -info, -primary), no con texto de color.
• Los formularios no estorban. Pon "Nuevo elemento" detrás de un botón; la lista es el contenido principal.

Referencia del kit#

Los scripts se cargan solo desde el origen propio de la app: un <script> de CDN se rechaza, así que copia cualquier biblioteca que necesites en la carpeta de la app. Al portar un artefacto de claude.ai u otra página de React, compila su JSX antes de publicar, por ejemplo npx esbuild app.jsx --bundle --minify --outfile=app.js, y vincula el archivo generado. Babel en el navegador también funciona, pero carga megabytes cada vez que se abre.

En el script de la página, Laze.records("<collection>") lista, crea, actualiza y elimina registros, Laze.subscribe recarga cuando hay cambios, Laze.h crea elementos y Laze.mount los dibuja.

Atajos de teclado#

Laze pasa sus propios atajos desde tu app a Laze, a menos que tu app los gestione, para que las personas puedan pulsar Cmd+K (Ctrl+K en Windows y Linux) para salir de una app sin tener que hacer clic fuera de ella primero. Los atajos que se pasan son Cmd+K, Cmd+[ y Cmd+], Cmd+1 a Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. y Cmd+/, además de Alt+Up y Alt+Down fuera de campos de texto. Cualquier otra tecla se queda en tu app.

Para conservar uno de estos en tu app, gestiona la tecla y llama a event.preventDefault(); entonces Laze no lo toca:

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

Revisa tu propio trabajo#

Mira cada cambio antes de publicarlo:

laze app serve --port 4173

Sirve tu carpeta en http://127.0.0.1:4173/ con el kit de la plataforma y los registros de la app en vivo, en solo lectura. Necesita una versión en vivo, así que ejecuta laze app push una vez primero. Ábrela con tu herramienta de navegador y haz capturas en ambos temas y con ancho de panel, por ejemplo:

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

Mira cada imagen. Corrige el texto que se desborda, las columnas que no caben, los colores que desaparecen en modo oscuro y cualquier cosa que todavía diga "demo".

Antes de publicar la app:

• Está fijada donde se pidió, y laze app members lista las personas que deberían poder abrirla.
• La primera pantalla responde la solicitud sin desplazarse.
• Las capturas en modo claro, modo oscuro y 390 px se ven terminadas.
• Tu mensaje da el nombre de la app y una línea sobre lo que hace. La pestaña de la conversación es el enlace.

Pregunta si no estás seguro#

Hazle a la persona una pregunta corta en lugar de crear algo incorrecto. No esperes un "adelante" en pasos que ya pidió: si pidió una app en este canal, créala allí, fíjala y avísale.