Criar apps, para agentes

Como um agente cria um app do Laze que as pessoas querem usar: regras de design, o kit, fixação e compartilhamento, pushes para trunk e verificação do próprio trabalho.

Esta página foi escrita para um agente de IA que recebeu a tarefa de criar ou alterar um app Laze. Leia antes do seu primeiro laze app create. As pessoas julgam um app nos primeiros cinco segundos: faça com que ele pareça pronto, coloque-o onde pediram e confira por conta própria antes de dizer que está pronto.

O fluxo de trabalho#

1. Crie no conversa que pediu:

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

   O app começa vazio, com uma pasta que é sua: crie tudo do zero, começando em index.html, depois laze app push. --channel fixa o app como uma aba dessa conversa. Todo mundo nela, e seus agentes, pode abrir e continuar criando nele (Builder). Dê ao app um nome com palavras que as pessoas leem, não um slug.

   Vincule o kit da plataforma e o cliente a partir da sua página:

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

   Slides, uma apresentação ou uma palestra são a única exceção: eles começam em --template slides, o único template. Os arquivos dele são a primeira versão ativa do app, sua para alterar. Cada slide é um arquivo em slides/, listado em ordem em slides/deck.json; o README.md do template explica como adicionar, reordenar e estilizar slides. A apresentação tem trilho de slides, navegação por teclado, Apresentar em tela cheia e botões Exportar PDF e Exportar HTML, então não crie isso de novo. Via MCP, create_app com template: "slides" faz o mesmo, e write_app_files altera um slide por vez.

   O template de slides serve apenas para uma nova apresentação. Quando uma pessoa envia arquivos que já são uma página ou uma apresentação (uma exportação HTML, um zip com index.html, um site estático), coloque-os no ar como estão: crie o app sem --template, descompacte os arquivos na pasta dele com index.html no topo, copie qualquer script que ele carregue de uma CDN e faça push. "Mova para cá" ou "coloque isto aqui" com um anexo significa exatamente isso: faça, não pergunte o que quer dizer.

2. Um app que já existe entra em uma conversa com um pin, não em uma mensagem com um link:

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

   --role editor permite que membros alterem dados, mas não o código, --view-only permite apenas visualizar. laze app pins <channel> lista as abas. Nunca fixe de novo um app que uma pessoa desafixou.

3. Modele os dados em laze.app.json: uma coleção por tipo de coisa, com campos tipados e alguns registros iniciais. Os dados ficam em registros, nunca no código da página. Uma página que fixa seus números, linhas ou textos no código está errada: quando os dados mudam, o app deve mudar sem um push.

4. Altere a página e depois confira localmente antes de ela entrar no ar (veja Confira seu próprio trabalho).

5. Faça push:

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

   Cada push vira o app ativo imediatamente. Não há rascunhos, branches ou pull requests: os apps seguem trunk based. Escreva a mensagem como uma frase simples sobre o que mudou para as pessoas. --seed preenche apenas coleções que ainda não têm registros.

6. Voltar quando um push estiver errado: laze app versions, depois laze app revert <version> -m "<why>". Isso cria uma nova versão ativa; nenhum registro é perdido. O histórico git dentro de um app serve apenas para isso.

Quem pode abrir#

Um app novo é Restrito. Um app fixado em uma conversa abre para todo mundo ali, então um pin geralmente é todo o compartilhamento de que um app de equipe precisa. Não compartilhe um app apenas com a pessoa que pediu quando ela pediu em um canal: fixe-o ali. Amplie com laze app access visibility internal|public apenas quando pedirem; o comando diz quando um admin precisa aprovar. laze app members mostra quem pode abri-lo agora. Confira isso antes de dizer às pessoas que o app está pronto.

Regras de design#

Comece pelo assunto do app, não por um layout. Pergunte como alguém que se importa com o assunto desenharia aquilo em um quadro branco, e construa isso: um modelo de ameaças é um mapa de ataques, um roadmap é uma linha do tempo, um orçamento é um fluxo de dinheiro, um processo é um diagrama. Uma página com blocos de métricas e listas com marcadores parece um relatório, e esse é o app a evitar.

Seja muito visual: use motion graphics e fluxos sempre que puder, e guie as pessoas um passo de cada vez até elas entenderem por completo. Nunca escreva paredes de texto: onde precisar de palavras, use frases simples e curtas. Um app é para as pessoas entenderem, não para despejar o que está na sua cabeça.

O kit do Laze vem da plataforma (/_laze/theme.css, /_laze/kit.css, /_laze/laze.js). Ele é uma caixa de ferramentas, não um layout para preencher: use os tokens e os controles de que precisa, e coloque seu próprio CSS por cima, no seu próprio arquivo. Nunca copie o kit para dentro do app.

• Priorize o visual. Faça da representação do assunto o próprio app: SVG inline, canvas, um mapa, uma linha do tempo, um diagrama, algo em que as pessoas cliquem e explorem. Dê a ele uma aparência própria, com seu próprio layout e movimento sobre os tokens do kit.
• Uma tarefa por tela. A primeira tela responde à pergunta para a qual o app existe. Coloque uma segunda tarefa em uma aba (lz-tabs), não abaixo da primeira.
• O formato certo. Use uma tabela (lz-table) ou um quadro (lz-board) quando as pessoas precisam ler ou mover linhas, um bloco de métrica (lz-stats, lz-stat-value) quando um número é o ponto principal, um gráfico (lz-chart) para números ao longo do tempo e etapas numeradas (lz-steps) para uma sequência curta. Texto com mais de três linhas pertence a um documento, não a um app.
• Dados reais. Mostre os registros com que as pessoas se importam, com nomes e datas reais. Nada de "Lorem", "Item 1" ou gráficos de placeholder. Toda afirmação na página vem de um registro ou de um link.
• Escala tipográfica. Um título de página (lz-title), uma linha abaixo dele (lz-lede), títulos de seção (lz-h2 ou lz-card-title), texto do corpo. Não adicione outros tamanhos.
• Espaçamento. Use as classes de página (lz-page), card (lz-card lz-card-body) e grid (lz-grid, lz-row); elas mantêm o ritmo de 12 a 20 px. Não empilhe cards dentro de cards.
• Ambos os temas. As cores vêm apenas de tokens (var(--color-fg), var(--color-bg-surface), var(--color-primary), var(--color-border) e os tons de lz-badge-*). Uma cor hex quebra o modo escuro.
• Largura estreita. Apps abrem em um painel lateral com cerca de 380 px de largura. Dê data-label às células da tabela para que as linhas empilhem, e mantenha os cabeçalhos em uma linha.
• Estados vazios e de erro. Uma lista vazia diz o que vai aparecer e como adicionar o primeiro item. Uma chamada com falha mostra Laze.fail(error), nunca uma página em branco.
• Status como badges. Mostre estados com lz-badge e um tom (-success, -warning, -danger, -info, -primary), não com texto colorido.
• Formulários não ficam no caminho. Coloque "Novo item" atrás de um botão; a lista é o conteúdo principal.

Referência do kit#

Scripts carregam apenas da origem do próprio app: uma CDN <script> é recusada, então copie para a pasta do app a biblioteca de que você precisa. Ao portar um artefato do claude.ai ou outra página React, compile o JSX antes do push (por exemplo npx esbuild app.jsx --bundle --minify --outfile=app.js) e vincule o arquivo gerado. Babel no navegador também funciona, mas carrega megabytes a cada abertura.

No script da página, Laze.records("<collection>") lista, cria, atualiza e remove registros, Laze.subscribe recarrega quando há mudanças, Laze.h cria elementos e Laze.mount os desenha.

Atalhos de teclado#

O Laze repassa os próprios atalhos do seu app para o Laze, a menos que o app os trate, para que as pessoas possam pressionar Cmd+K (Ctrl+K no Windows e no Linux) para sair de um app sem precisar clicar fora dele antes. Os atalhos repassados são Cmd+K, Cmd+[ e Cmd+], Cmd+1 a Cmd+9, Cmd+Shift+A, Cmd+Shift+T, Cmd+Shift+M, Cmd+Shift+D, Cmd+. e Cmd+/, além de Alt+Up e Alt+Down fora de campos de texto. Todas as outras teclas ficam no seu app.

Para manter um deles no seu app, trate a tecla e chame event.preventDefault(); então o Laze não interfere:

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

Confira seu próprio trabalho#

Veja cada alteração antes de fazer push:

laze app serve --port 4173

Ele serve sua pasta em http://127.0.0.1:4173/ com o kit da plataforma e os registros do app ativo, somente leitura. Ele precisa de uma versão ativa, então execute laze app push uma vez antes. Abra com sua ferramenta de navegador e faça uma captura de tela nos dois temas e na largura do painel, por exemplo:

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

Observe cada imagem. Corrija texto que transborda, colunas que não cabem, cores que somem no modo escuro e qualquer coisa que ainda diga "demo".

Antes de publicar o app:

• Ele está fixado onde foi pedido, e laze app members lista as pessoas que devem conseguir abri-lo.
• A primeira tela responde ao pedido sem rolar.
• As capturas em modo claro, modo escuro e 390 px parecem prontas.
• Sua mensagem informa o nome do app e uma linha sobre o que ele faz. A aba na conversa é o link.

Pergunte quando não tiver certeza#

Faça uma pergunta curta à pessoa em vez de criar a coisa errada. Não espere um "vai" para etapas que ela já pediu: se ela pediu um app neste canal, crie ali, fixe e avise.