Princípios e padrões de design com IA
Como desenhar experiências de inteligência artificial no Admin — as três formas de IA, quando referenciar a Lumi e os padrões do Nimbus para torná-las reconhecíveis, transparentes e controláveis.
Toda experiência de inteligência artificial no Admin precisa ser reconhecível (o merchant sabe que é IA), transparente (sabe o que ela fez e em que anda) e controlável (pode editá-la, descartá-la ou tentar de novo). Este guia cobre o marco conceitual —Lumi, features e produtos potencializados com IA— e os padrões do Nimbus para desenhar cada uma dessas experiências. A referência técnica de IA cobre as props, os tokens e os ícones exatos.
A IA se manifesta de três maneiras. Identificar qual se quer desenhar é o primeiro passo, porque mudam as peças, as expectativas e o modelo de interação. As três compartilham a mesma identidade visual e os mesmos componentes do Nimbus; o que muda é o alcance.
Feature potencializada com IA
IA embutida em uma tela que já existe.
- O que é: uma ação pontual dentro de um fluxo existente (um campo, uma sugestão, um resumo).
- Quando escolher esta forma: para acelerar uma tarefa pontual sem tirar o merchant de onde está.
- Exemplo: "Melhorar descrição" no editor de produto.
Produto potencializado com IA
Uma experiência com nome e identidade próprios.
- O que é: várias features de IA que formam uma experiência especializada, com nome e entrada próprios; não é "uma feature grande".
- Quando escolher esta forma: a proposta de valor merece nome, entrada e narrativa próprios.
- Exemplo: "Assistente de Vendas no Chat".
Lumi (o agente)
O assistente conversacional, com sua superfície de chat.
- O que é: diálogo de vários turnos, contexto acumulado, delegação de tarefas abertas.
- Quando escolher esta forma: a tarefa é aberta ou conversacional e o merchant quer delegar, não preencher um campo.
- Exemplo: "Peça à Lumi que…" a partir da sua superfície de chat.
Como decidir
Em ordem:
- O merchant precisa conversar ou delegar uma tarefa aberta? → Lumi.
- É uma ação pontual dentro de uma tela existente? → Feature potencializada com IA.
- É uma experiência com nome próprio, feita de várias features? → Produto potencializado com IA.
As três vivem sobre o Nimbus: feature e produto se montam com os mesmos padrões e componentes deste guia. A Lumi compartilha essa identidade e esses componentes, mas soma a superfície de chat, que é exclusiva. Ver Lumi: quando e como referenciá-la e Componentes e padrões.
A Lumi é uma das três formas de experiências de IA no Admin, mas também é transversal: uma feature pode precisar passar uma tarefa a ela. Estas regras valem tanto ao desenhar a Lumi quanto ao desenhar uma feature que a invoca.
Nomeia-se "Lumi" só quando o merchant interage com o agente: ao abrir o chat ou ao delegar algo. Ex.: "Peça à Lumi que…". Em uma feature potencializada com IA não se nomeia a Lumi: nomeia-se a ação pelo benefício.
A Lumi é aberta quando a tarefa supera o pontual
Exige conversa, vários turnos ou contexto que não cabe em um campo. Se a necessidade se resolve na mesma tela com uma geração, é uma feature com IA e não deveria abrir ou referenciar a Lumi. Regra: não encaminhar o merchant à Lumi para algo que pode ser resolvido onde ele já está.
- Handoff explícito: a feature oferece "Seguir com a Lumi" quando a tarefa virou conversacional.
- Entrada direta: o acesso global à Lumi, sempre disponível no header do Admin, independente de qualquer feature. É o CTA principal para abrir a Lumi.
A UI do chat —avatar, balões, histórico, input conversacional, welcome screen— é exclusiva da Lumi e não se replica em features nem produtos. Todo o resto que a Lumi mostra embutido usa os mesmos componentes do Nimbus. O critério é a superfície, não o time que constrói. Ver Componentes e padrões.
Usam-se o avatar e o naming oficiais; não se inventam variantes visuais do agente. O acesso à Lumi mantém a linguagem visual de IA (gradiente, ícones). Para o texto de invocação, aplicam-se as regras de nomenclatura.
A identidade da IA é compartilhada. A nomenclatura é contextual
O avatar, os componentes, os padrões de interação e a linguagem visual são consistentes em todo o ecossistema. O que muda é como se nomeia cada experiência para o merchant.
| Forma | Como se nomeia | Exemplo |
|---|---|---|
Feature potencializada com IA | Nome orientado à ação ou ao benefício, não à tecnologia. | "Completar informações", "Melhorar descrição" |
Produto potencializado com IA | Um nome próprio que represente sua especialização. | "Assistente de Vendas no Chat" |
Lumi (o agente) | Nomeia-se "Lumi" só ao abrir ou pedir algo ao agente. | "Peça à Lumi", "Abrir com a Lumi" |
Evitar:
- Não chamar de "Lumi" uma feature embutida que não é o agente.
- Não apresentar o resultado gerado como definitivo, sem indicar que é editável.
- Não comunicar quando a geração falhou.
- Não prometer demais no texto do botão. Ex.: "Escrever o texto perfeito" em vez de "Melhorar descrição".
- Não distinguir entre "este campo foi gerado por IA" e "este botão gera com IA".
Uma feature ou um produto com IA se monta combinando alguns poucos padrões, agrupados pela promessa que sustentam: reconhecível, transparente e controlável. Cada padrão enlaça sua API na referência técnica de IA.
Identificar e atribuir a IA
Sinalizar de forma explícita que um conteúdo ou ação envolve IA. A confiança se constrói quando o merchant reconhece, sem esforço, o que foi gerado automaticamente.
- Quando: sempre que se mostrar conteúdo gerado ou uma ação de IA.
- Aplica a: Feature · Produto · Lumi.
- Texto: rotular a origem, não a tecnologia em abstrato. Ex.: "Gerado com IA".
Tag · ai-generative
Icon · color ai-generative
Disparar uma geração
O ponto de entrada a partir do qual o merchant pede à IA que faça algo. Um ponto de entrada claro e hierarquizado evita que a IA pareça intrusiva ou escondida.
- Quando: há uma ação de IA que o merchant dispara.
- Aplica a: Feature · Produto · Lumi.
- Texto: nomear a ação pelo benefício, não a tecnologia. Ex.: "Melhorar descrição", não "Gerar com IA".
Evitar rotular o CTA só com cor de texto
Não usar Text color="ai-generative" como forma principal de rotular uma ação de IA. O mecanismo recomendado são os componentes (Button, IconButton, Link, Tag). A cor de texto fica para títulos ou chamadas breves, não para CTAs.
Button · ai-primary
Ação principal de IA.
Button · ai-secondary
Ação complementar de IA.
IconButton · ai-generative
Fundo com gradiente.
IconButton · color ai-generative
Ícone tingido com o gradiente, contêiner neutro.
Link + Icon · ai-generative
Não é um componente próprio: compõe-se com Icon + Link.
Escolher o ícone pela ação, não por padrão: o ícone genérico (GenerativeStarsIcon) serve para ações amplas como "Gerar com IA", mas é conveniente ser mais descritivo no texto acompanhado de um ícone que descreva melhor a ação pontual — ex. GenerativePencilIcon + o link "Melhorar descrição com IA". Se nenhum ícone disponível acompanhar bem a ação, é possível somar um novo ao grupo de ícones de IA.
Comunicar o processo
Mostrar que a IA está trabalhando. As gerações demoram; comunicar o progresso sustenta a confiança e evita que o merchant pense que algo falhou.
- Quando: a geração não é instantânea.
- Aplica a: Feature · Produto · Lumi.
Quando usar cada um
ActionableToast · loading inline (ainda não disponível no Nimbus, pendente de desenvolvimento) quando a geração ocorre na mesma tela e o merchant não muda de contexto. ProgressBar quando a ação leva a outra experiência já existente do produto, onde o merchant aguarda e vê o resultado nesse destino.
ProgressBar · ai-generative
ActionableToast · loading inline
Loading inline na mesma tela, enquanto a IA gera.
Mostrar o resultado
Inserir o conteúdo gerado onde o merchant estava trabalhando, pronto para revisar e editar, sem abrir outra tela. A prop aiGenerated destaca o valor e adiciona o anel de foco próprio.
- Quando: a IA produz um valor que o merchant vai revisar.
- Aplica a: Feature · Produto · Lumi.
- Texto: deixar claro que é editável; nunca o apresentar como definitivo.
Input · aiGenerated
Textarea · aiGenerated
Select · aiGenerated
Chip · aiGenerated
Frete grátis
Checkbox · aiGenerated
Comunicar o erro e permitir tentar de novo
Quando uma geração falha, comunica-se com clareza e oferece-se uma saída. Esconder o erro ou deixar o campo em um estado indefinido quebra a confiança mais do que a própria falha.
- Quando: a geração falha, se corta ou não há créditos.
- Aplica a: Feature · Produto · Lumi.
- Texto: um texto honesto que explique o que aconteceu e como seguir. Ex.: "Não conseguimos gerar a descrição. Tentar de novo". Se o bloqueio for por falta de créditos, desabilitar o CTA e explicar como conseguir mais, em vez de falhar em silêncio.
Alert · danger
Não conseguimos gerar a descrição
FormField.Input · danger
Não conseguimos gerar a descrição. Tentar de novo.
As experiências de IA do Admin vivem dentro do Nimbus. Algo é próprio da Lumi só se for exclusivo da superfície de chat do agente. Tudo o que vive embutido em telas do Admin —seja disparado pela Lumi ou por uma feature com IA independente— é reutilizável do Nimbus.
Componentes com suporte de IA, renderizados ao vivo. A API completa está no Catálogo de componentes.
Button · ai-primary
Disparar uma geração, com hierarquia.
Input · aiGenerated
Campo com valor autogerado (mesmo critério de Textarea e Select).
Tag · ai-generative
Identificar conteúdo gerado por IA.
Chip · aiGenerated
Etiqueta ou critério sugerido por IA.
Sugerido por IA
Checkbox · aiGenerated
Seleção sugerida por IA.
ProgressBar · ai-generative
Progresso de um processo de IA.
IconButton · ai-generative
Ação de IA só com ícone.
Icon · color ai-generative
Ícone tingido com o gradiente.
Padrões que hoje vivem fora do design system, mas são reutilizáveis em qualquer tela do Admin (disparados pela Lumi ou não). As capturas são do showcase da Lumi; essas composições são construídas a partir das primitivas do Nimbus.
Ainda não disponíveis no Nimbus
As 6 composições desta grade estão pendentes de desenvolvimento como componentes instaláveis de @nimbus-ds/components. O tag "Pendente" em cada card marca esse estado.
ActionableToast · loading inline — Loading inline e feedback (👍/👎) após uma geração.
GenerateWithAiLink — Link para disparar uma geração, ao lado do label de um campo (padrão Link).
AiGeneratedBox — Wrapper com borda gradiente para conteúdo gerado.
Alert — Aviso contextual, por exemplo por informação incompleta.
Modal de geração — Progresso em tela cheia durante uma geração longa.
AiCreditsBadge — Indicador de créditos ou usos de IA restantes.
A UI do chat da Lumi é exclusiva da sua superfície conversacional: não se replica fora dela.
UI do chat do agente — Avatar, mensagens, histórico, input, welcome screen. Exclusivo da superfície de chat.
Ao construir experiências de IA no Admin, convém cobrir as três promessas declaradas.
Antes · reconhecível
Antecipar o que a IA vai fazer.
- Comunicar claramente o que a IA vai fazer antes de gerar.
- Nomear a ação pelo benefício, não pela tecnologia.
Durante · transparente
Comunicar o progresso.
- Mostrar que a IA está trabalhando. Ver Comunicar o processo.
- Escolher loading inline ou progresso no destino conforme onde ocorre.
Depois · controlável
Entregar e dar controle.
- Destacar visualmente o que foi gerado ou alterado.
- Permitir editar ou regenerar o resultado.
- Oferecer um mecanismo de feedback (👍/👎 ou equivalente).
✅ Do
- Reservar o estilo para conteúdo e ações realmente assistidos por IA.
- Identificar sempre a IA e deixar claro o que ela gerou.
- Deixar o resultado editável e permitir descartar ou regenerar.
- Manter um único ponto de IA por contexto.
- Consumir tokens, gradientes e componentes do sistema.
❌ Don't
- Não usar o gradiente como decoração nem em conteúdo que não foi gerado por IA.
- Não substituir as aparências de validação (success, warning, danger).
- Não apresentar um resultado de IA como definitivo.
- Não replicar a UI do chat da Lumi fora da sua superfície conversacional.
- Não depender só da cor para comunicar a origem.