Principios y patrones de diseño con IA
Cómo diseñar experiencias de inteligencia artificial en el Admin — las tres formas de IA, cuándo referenciar a Lumi y los patrones de Nimbus para hacerlas reconocibles, transparentes y controlables.
Toda experiencia de inteligencia artificial en el Admin tiene que ser reconocible (el merchant sabe que es IA), transparente (sabe qué hizo y en qué anda) y controlable (puede editarla, descartarla o reintentar). Esta guía cubre el marco conceptual —Lumi, features y productos potenciados con IA— y los patrones de Nimbus para diseñar cada una de esas experiencias. La referencia técnica de IA cubre las props, los tokens y los iconos exactos.
La IA se manifiesta de tres maneras. Identificar cuál se quiere diseñar es el primer paso, porque cambian las piezas, las expectativas y el modelo de interacción. Las tres comparten la misma identidad visual y los mismos componentes de Nimbus; lo que cambia es el alcance.
Feature potenciada con IA
IA embebida en una pantalla que ya existe.
- Qué es: una acción acotada dentro de un flujo existente (un campo, una sugerencia, un resumen).
- Cuándo elegir esta forma: para acelerar una tarea puntual sin sacar al merchant de donde está.
- Ejemplo: "Mejorar descripción" en el editor de producto.
Producto potenciado con IA
Una experiencia con nombre e identidad propios.
- Qué es: varias features de IA que forman una experiencia especializada, con nombre y entrada propios; no es "una feature grande".
- Cuándo elegir esta forma: la propuesta de valor amerita nombre, entrada y narrativa propios.
- Ejemplo: "Asistente de Ventas en Chat".
Lumi (el agente)
El asistente conversacional, con su superficie de chat.
- Qué es: diálogo multiturno, contexto acumulado, delegación de tareas abiertas.
- Cuándo elegir esta forma: la tarea es abierta o conversacional y el merchant quiere delegar, no completar un campo.
- Ejemplo: "Pídele a Lumi que…" desde su superficie de chat.
Cómo decidir
En orden:
- ¿El merchant necesita conversar o delegar una tarea abierta? → Lumi.
- ¿Es una acción puntual dentro de una pantalla existente? → Feature potenciada con IA.
- ¿Es una experiencia con nombre propio, hecha de varias features? → Producto potenciado con IA.
Las tres viven sobre Nimbus: feature y producto se arman con los mismos patrones y componentes de esta guía. Lumi comparte esa identidad y esos componentes, pero suma la superficie de chat, que es exclusiva. Ver Lumi: cuándo y cómo referenciarla y Componentes y patrones.
Lumi es una de las tres formas de experiencias IA en el Admin, pero también es transversal: una feature puede necesitar derivarle una tarea. Estas reglas valen tanto al diseñar Lumi como al diseñar una feature que la invoca.
Se nombra a "Lumi" solo cuando el merchant interactúa con el agente: al abrir su chat o al delegarle algo. Ej.: "Pídele a Lumi que…". En una feature potenciada con IA no se nombra a Lumi: se nombra la acción por su beneficio.
Lumi se abre cuando la tarea supera lo puntual
Requiere conversación, varios turnos o contexto que no entra en un campo. Si la necesidad se resuelve en la misma pantalla con una generación, es una feature con IA y no debería abrir o referenciar a Lumi. Regla: no derivar al merchant a Lumi para algo que puede resolverse donde ya está.
- Handoff explícito: la feature ofrece "Seguir con Lumi" cuando la tarea se volvió conversacional.
- Entrada directa: el acceso global a Lumi, siempre disponible en el header del Admin, independiente de cualquier feature. Es el CTA principal para abrir Lumi.
La UI del chat —avatar, burbujas, historial, input conversacional, welcome screen— es exclusiva de Lumi y no se replica en features ni productos. Todo lo demás que Lumi muestra embebido usa los mismos componentes de Nimbus. El criterio es la superficie, no el equipo que la construye. Ver Componentes y patrones.
Se usan el avatar y el naming oficiales; no se inventan variantes visuales del agente. El acceso a Lumi mantiene el lenguaje visual de IA (gradiente, iconos). Para el texto de invocación, aplican las reglas de nomenclatura.
La identidad de la IA es compartida. La nomenclatura es contextual
El avatar, los componentes, los patrones de interacción y el lenguaje visual son consistentes en todo el ecosistema. Lo que cambia es cómo se nombra cada experiencia al merchant.
| Forma | Cómo se nombra | Ejemplo |
|---|---|---|
Feature potenciada con IA | Nombre orientado a la acción o al beneficio, no a la tecnología. | "Completar información", "Mejorar descripción" |
Producto potenciado con IA | Un nombre propio que represente su especialización. | "Asistente de Ventas en Chat" |
Lumi (el agente) | Se nombra a "Lumi" solo al abrir o pedirle algo al agente. | "Pídele a Lumi", "Abrir con Lumi" |
Evitar:
- No llamar "Lumi" a una feature embebida que no es el agente.
- No presentar el resultado generado como definitivo, sin indicar que es editable.
- No comunicar cuando la generación falló.
- No prometer de más en el texto del botón. Ej.: "Escribir el texto perfecto" en vez de "Mejorar descripción".
- No distinguir entre "este campo fue generado por IA" y "este botón genera con IA".
Una feature o un producto con IA se arma combinando unos pocos patrones, agrupados por la promesa que sostienen: reconocible, transparente y controlable. Cada patrón enlaza con su API en la referencia técnica de IA.
Identificar y atribuir la IA
Señalar de forma explícita que un contenido o acción involucra IA. La confianza se construye cuando el merchant reconoce, sin esfuerzo, qué fue generado automáticamente.
- Cuándo: siempre que se muestre contenido generado o una acción de IA.
- Aplica a: Feature · Producto · Lumi.
- Copy: etiquetar el origen, no la tecnología en abstracto. Ej.: "Generado con IA".
Tag · ai-generative
Icon · color ai-generative
Disparar una generación
El punto de entrada desde el que el merchant pide a la IA que haga algo. Un punto de entrada claro y jerarquizado evita que la IA se sienta intrusiva o escondida.
- Cuándo: hay una acción de IA que el merchant dispara.
- Aplica a: Feature · Producto · Lumi.
- Copy: nombrar la acción por su beneficio, no la tecnología. Ej.: "Mejorar descripción", no "Generar con IA".
Evitar etiquetar el CTA solo con color de texto
No usar Text color="ai-generative" como forma principal de rotular una acción de IA. El mecanismo recomendado son los componentes (Button, IconButton, Link, Tag). El color de texto queda para títulos o llamados breves, no para CTAs.
Button · ai-primary
Acción principal de IA.
Button · ai-secondary
Acción complementaria de IA.
IconButton · ai-generative
Fondo con gradiente.
IconButton · color ai-generative
Ícono teñido con el gradiente, contenedor neutro.
Link + Icon · ai-generative
No es un componente propio: se compone con Icon + Link.
Elegir el ícono por la acción, no por defecto: el ícono genérico (GenerativeStarsIcon) sirve para acciones amplias como "Generar con IA", pero es conveniente ser más descriptivo en el copy acompañado de un ícono que describa mejor la acción puntual — ej. GenerativePencilIcon + el link "Mejorar descripción con IA". Si ningún ícono disponible acompaña bien la acción, se puede sumar uno nuevo al grupo de íconos de IA.
Comunicar el proceso
Mostrar que la IA está trabajando. Las generaciones tardan; comunicar el progreso sostiene la confianza y evita que el merchant crea que algo falló.
- Cuándo: la generación no es instantánea.
- Aplica a: Feature · Producto · Lumi.
Cuándo usar cada uno
ActionableToast · loading inline (aún no disponible en Nimbus, pendiente de desarrollo) cuando la generación ocurre en la misma pantalla y el merchant no cambia de contexto. ProgressBar cuando la acción lleva a otra experiencia ya existente del producto, donde el merchant espera y ve el resultado en ese destino.
ProgressBar · ai-generative
ActionableToast · loading inline
Loading inline en la misma pantalla, mientras la IA genera.
Mostrar el resultado
Insertar el contenido generado donde el merchant estaba trabajando, listo para revisar y editar, sin abrir otra pantalla. La prop aiGenerated resalta el valor y suma el anillo de foco propio.
- Cuándo: la IA produce un valor que el merchant va a revisar.
- Aplica a: Feature · Producto · Lumi.
- Copy: dejar claro que es editable; nunca presentarlo como definitivo.
Input · aiGenerated
Textarea · aiGenerated
Select · aiGenerated
Chip · aiGenerated
Envío gratis
Checkbox · aiGenerated
Comunicar el error y permitir reintentar
Cuando una generación falla, se comunica con claridad y se ofrece una salida. Ocultar el error o dejar el campo en un estado indefinido rompe la confianza más que el propio fallo.
- Cuándo: la generación falla, se corta o no hay créditos.
- Aplica a: Feature · Producto · Lumi.
- Copy: un texto honesto que explique qué pasó y cómo seguir. Ej.: "No pudimos generar la descripción. Reintentar". Si el bloqueo es por falta de créditos, deshabilitar el CTA y explicar cómo conseguir más, en vez de fallar en silencio.
Alert · danger
No pudimos generar la descripción
FormField.Input · danger
No pudimos generar la descripción. Reintentar.
Las experiencias IA del Admin viven dentro de Nimbus. Algo es propio de Lumi solo si es exclusivo de la superficie de chat del agente. Todo lo que vive embebido en pantallas del Admin —lo dispare Lumi o una feature con IA independiente— es reutilizable de Nimbus.
Componentes con soporte de IA, renderizados en vivo. La API completa está en el Catálogo de componentes.
Button · ai-primary
Disparar una generación, con jerarquía.
Input · aiGenerated
Campo con valor autogenerado (mismo criterio que Textarea y Select).
Tag · ai-generative
Etiquetar contenido generado por IA.
Chip · aiGenerated
Etiqueta o criterio sugerido por IA.
Sugerido por IA
Checkbox · aiGenerated
Selección sugerida por IA.
ProgressBar · ai-generative
Progreso de un proceso de IA.
IconButton · ai-generative
Acción de IA solo con ícono.
Icon · color ai-generative
Ícono teñido con el gradiente.
Patrones que hoy viven fuera del design system, pero son reutilizables en cualquier pantalla del Admin (lo dispare Lumi o no). Las capturas son del showcase de Lumi; estas composiciones se construyen a partir de las primitivas de Nimbus.
Aún no disponibles en Nimbus
Las 6 composiciones de esta grilla están pendientes de desarrollo como componentes instalables de @nimbus-ds/components. El tag "Pendiente" en cada card marca ese estado.
ActionableToast · loading inline — Loading inline y feedback (👍/👎) tras una generación.
GenerateWithAiLink — Link para disparar una generación, junto al label de un campo (patrón Link).
AiGeneratedBox — Wrapper con borde gradiente para contenido generado.
Alert — Aviso contextual, por ejemplo por información incompleta.
Modal de generación — Progreso a pantalla completa durante una generación larga.
AiCreditsBadge — Indicador de créditos o usos de IA restantes.
La UI del chat de Lumi es exclusiva de su superficie conversacional: no se replica fuera de ella.
UI del chat del agente — Avatar, mensajes, historial, input, welcome screen. Exclusivo de la superficie de chat.
A la hora de construir experiencias IA en el Admin, conviene cubrir las tres promesas declaradas.
Antes · reconocible
Anticipar qué hará la IA.
- Comunicar claramente qué va a hacer la IA antes de generar.
- Nombrar la acción por su beneficio, no por la tecnología.
Durante · transparente
Comunicar el progreso.
- Mostrar que la IA está trabajando. Ver Comunicar el proceso.
- Elegir loading inline o progreso a destino según dónde ocurre.
Después · controlable
Entregar y dar control.
- Destacar visualmente lo generado o alterado.
- Permitir editar o regenerar el resultado.
- Ofrecer un mecanismo de feedback (👍/👎 o equivalente).
✅ Do
- Reservar el estilo para contenido y acciones realmente asistidos por IA.
- Identificar siempre la IA y dejar claro qué generó.
- Dejar el resultado editable y permitir descartar o regenerar.
- Mantener un único punto de IA por contexto.
- Consumir tokens, gradientes y componentes del sistema.
❌ Don't
- No usar el gradiente como decoración ni en contenido que no fue generado por IA.
- No reemplazar las apariencias de validación (success, warning, danger).
- No presentar un resultado de IA como definitivo.
- No replicar la UI del chat de Lumi fuera de su superficie conversacional.
- No depender solo del color para comunicar el origen.