Cultiva Assistant — Design System v1.0

01

Contexto y objetivos

Intención de diseño: Cultiva Assistant es una interfaz de delegación de tareas: el usuario describe lo que quiere en lenguaje natural y el agente lo ejecuta. El diseño no debe competir con el agente; debe desaparecer para que la atención se centre en el resultado.

Principio 1

⚡

Delegar, no navegar

La interfaz expone una sola acción primaria: describir una tarea. Los controles secundarios son accesibles pero no dominantes.

Principio 2

🎯

Resultados claros

Cada respuesta del agente expone un output concreto y accionable. Evitar respuestas ambiguas o vagamente útiles.

Principio 3

♿

Accesible por defecto

WCAG 2.2 AA no es opcional. El diseño funciona sin mouse, sin visión, con movimiento reducido y en alta resolución.

02

Tokens de diseño

Variables CSS — layer: foundation

/* Colores */
--color-primary: #FF5701;
--color-primary-hover: #E04A00;
--color-primary-light: #FFF1EB;
--color-secondary: #F6F6F1;
--color-success: #16A34A;
--color-warning: #D97706;
--color-danger: #DC2626;
--color-text: #111827;
--color-text-muted: #6B7280;

/* Espaciado (8pt grid) */
--space-1: 8px;   --space-2: 16px;
--space-3: 24px;  --space-4: 32px;
--space-5: 40px;  --space-6: 48px;

/* Radios */
--radius-sm: 4px;  --radius-md: 8px;
--radius-lg: 16px; --radius-full: 9999px;

03

Paleta de colores

Colores semánticos

Primary

--color-primary

#FF5701

Secondary

--color-secondary

#F6F6F1

Text

--color-text

#111827

Surface

--color-surface

#FFFFFF

Success

--color-success

#16A34A

Warning

--color-warning

#D97706

Danger

--color-danger

#DC2626

Uso semántico de colores

Token	Valor	Uso	Nunca usar para
primary	#FF5701	CTAs principales, iconos activos, bordes de foco, badges de marca	Texto de cuerpo largo, fondos de pantalla completa
secondary	#F6F6F1	Fondos de página, headers de card, chips ghost	Texto sobre fondo blanco (ratio insuficiente)
success	#16A34A	Estados completados, validaciones positivas, badges de tarea done	Acciones primarias (confunde semántica)
warning	#D97706	Clarificaciones pendientes, información incompleta	Errores destructivos (usar danger en su lugar)
danger	#DC2626	Errores, acciones irreversibles, validaciones fallidas	Decoración, acentos de marca

04

Tipografía

Escala tipográfica

display

Playfair Display · 40px · 800

Cultiva AI

h1

Playfair Display · 32px · 700

Genera tu campaña

h2

Playfair Display · 24px · 700

Resultado del análisis

body-lg

Playfair Display · 18px · 400

El agente ha procesado tu solicitud y ha generado tres opciones de contenido.

body-md

Playfair Display · 16px · 400

Esta es la tipografía por defecto para respuestas del agente y texto de interfaz general.

body-sm

Playfair Display · 14px · 400

Metadata, ayuda contextual, etiquetas secundarias y descripciones de acción.

label-caps

JetBrains Mono · 12px · 600 · UPPERCASE

Tarea completada · 3 resultados

code

JetBrains Mono · 13px · 400

--color-primary: #FF5701;

Reglas tipográficas

Regla	Valor	Nota
Line-height cuerpo	1.6–1.7	Mejora legibilidad en respuestas largas del agente
Line-height títulos	1.1–1.2	Compactar para jerarquía visual clara
Max-width texto	65ch	Previene líneas demasiado largas (>75ch reduce legibilidad)
Contraste mínimo	4.5:1 (AA)	Verificar siempre text sobre secondary (#F6F6F1)
Mono reservado para	labels, status, código	Nunca usar JetBrains Mono para cuerpo conversacional

05

Sistema de espaciado (8pt grid)

Escala base

--space-1
8px

--space-2
16px

--space-3
24px

--space-4
32px

--space-5
40px

--space-6
48px

Regla: Todos los valores de padding, margin y gap deben ser múltiplos de 8px. Excepción permitida solo para bordes (1–2px) y ring de foco (3px).

06

Componentes

C-01 · Chat Composer (Delegación de tarea)

El componente de entrada es el núcleo del producto. Debe sentirse natural, cómodo y seguro para escribir.

Estado: Default

Estado: Focus (borde primary)

Anatomía	Token/Valor	Regla
Container border (default)	--color-border · 2px · radius-xl	Debe usar 2px (no 1px) para distinguirse del fondo
Container border (focus)	--color-border-focus (#FF5701) · 2px	MUST: visible en modo de alto contraste
Textarea font	--font-primary · text-base · 400	Nunca mono para input conversacional
Send button	44×44px · radius-full · primary	MUST: mín. 44px touch target (WCAG 2.5.5)
Send button (disabled)	opacity: 0.4 · cursor: not-allowed	Deshabilitar mientras textarea esté vacío

C-02 · Agent Response Card

Contiene el output estructurado del agente. Jerarquía clara: quién habla → qué tarea → resultado → acciones.

C

Cultiva Assistant

Tarea: Análisis de márgenes · Shopify

Completado

He analizado 847 pedidos del último mes. Aquí los 3 productos con margen negativo:

Producto	Margen	Unidades
Kit Inicio Specialty	-12.4%	34
Suscripción Mensual S	-8.1%	21
Muestra Gratis Café	-2.3%	156

Anatomía	Token/Valor	Regla
Card border	--color-border · 1px · radius-lg	Sombra shadow-sm solo en respuesta activa
Header background	--color-secondary	Diferencia visual agente vs. usuario. MUST mantener
Avatar	32px · radius-full · primary bg	Siempre initial del agente + fondo primary
Task label	font-mono · 11px · text-muted	Describe la tarea ejecutada, no el tipo de IA
Footer acciones	flex wrap · gap-1	Máx. 3 acciones visibles sin scroll. Priorizar la más probable

C-03 · Task Status Indicator

Comunica el estado de ejecución de una tarea delegada. Nunca ambiguo: el usuario siempre sabe si el agente está trabajando, terminó o necesita atención.

Procesando… running

Completado done

Esperando datos waiting

Error error

/* Animación solo para 'running' — respetar prefers-reduced-motion */
@media (prefers-reduced-motion: no-preference) {
  .status-running .status-dot {
    animation: pulse 1.5s infinite;
  }
}
@keyframes pulse {
  0%, 100% { opacity: 1; }
  50%       { opacity: 0.3; }
}

C-04 · Action Chips (Sugerencias rápidas)

Acciones sugeridas por el agente o atajos frecuentes del usuario. Reducen fricción sin saturar la interfaz.

Variante	Uso	Estilo
chip-primary	Acción más probable / recomendada	bg-primary · texto blanco · hover: bg-primary-hover
chip-outline	Acciones secundarias alternativas	border-border · texto text · hover: border-primary
chip-ghost	Acciones adicionales de menor peso	bg-secondary · texto muted · hover: bg-primary-light

MUST: mín. 44px de altura · MUST: etiquetas claras y accionables · NO: más de 4 chips visibles sin colapsar

C-05 · Estados de Error y Clarificación

CLARIFICACIÓN

Necesito más información

Para analizar las ventas, necesito saber el rango de fechas exacto. ¿Te refieres al mes anterior completo (mayo 2026) o los últimos 30 días?

ERROR

No pude completar la tarea

No tengo acceso a tu Shopify en este momento. Por favor verifica la conexión en Ajustes → Integraciones.

ESTADO LOADING (esqueleto)

07

Accesibilidad — WCAG 2.2 AA

Criterios de contraste

REGLA: text-muted solo se usa en texto 18px+ o con font-weight:700 a 14px. Nunca para cuerpo informativo.

Criterios de interacción (testables)

Criterio WCAG	Implementación requerida	Cómo verificar
2.4.7 Focus Visible	outline: 3px solid --color-primary · offset: 2px en todos los elementos interactivos	Tab por la página: todo elemento activo debe mostrar anillo naranja
2.5.3 Label en nombre	aria-label descriptivo en botón enviar: "Enviar tarea al agente"	Screen reader anuncia la acción, no el icono
2.3.3 Movimiento	@media (prefers-reduced-motion) suspende todas las animaciones	Activar reduced-motion en OS, verificar que skeleton y pulse se detienen
1.4.3 Contraste	Mín. 4.5:1 para texto normal, 3:1 para texto grande (+18px o 14px bold)	Pasar axe-core o WAVE sobre cada componente
2.5.8 Target Size	Mín. 44×44px para todos los botones interactivos	Inspeccionar computed height de chips y botones en mobile
4.1.3 Status Messages	role="status" o role="alert" en indicadores de tarea	Screen reader anuncia cambios de estado sin mover foco

08

Tono y estándares de contenido

Principios de escritura

Hacer — ejemplos correctos

✅ "He analizado 847 pedidos. Aquí los resultados."
✅ "¿Quieres que lo exporte a CSV o PDF?"
✅ "No puedo acceder a tu Shopify. Revisa Ajustes → Integraciones."
✅ "Tarea completada en 4 segundos."

No hacer — ejemplos incorrectos

❌ "Por supuesto, estaré encantado de ayudarte con eso."
❌ "Procesando tu solicitud mediante análisis multimodal de LLM…"
❌ "Ha ocurrido un error en el servicio de terceros."
❌ "Hecho." (sin contexto de qué se hizo)

Reglas de etiquetado de acciones

Contexto	Formato recomendado	Ejemplo
Botón de acción primaria	Verbo + objeto (sin artículo)	"Exportar CSV" no "Descargar el archivo CSV"
Placeholder de textarea	Instrucción abierta, no pregunta	"Describe qué necesitas que haga el agente…"
Etiquetas de status	Participio presente o infinitivo	"Procesando…" / "Completado" / "Error"
Mensajes de clarificación	Pregunta directa + opciones concretas	"¿Qué rango de fechas? [Opción A] [Opción B]"
Mensajes de error	Qué falló + cómo resolverlo	"Sin acceso a Shopify. Revisar Integraciones."

09

Anti-patrones prohibidos

❌ Prohibido

Botón sin mínimo 44px de altura:

altura: ~22px — falla WCAG 2.5.8

✅ Correcto

Botón con touch target adecuado:

altura: 44px — cumple WCAG 2.5.8

❌ Prohibido

Texto muted pequeño sobre secondary:

Resultado del análisis completado.

ratio ~3.1:1 — falla WCAG 1.4.3

✅ Correcto

Texto legible sobre secondary:

Resultado del análisis completado.

ratio 8.3:1 — cumple WCAG 1.4.3

❌ Prohibido

Spacing no múltiplo de 8:

padding: 5px 11px

rompe grid · genera desalineaciones

✅ Correcto

Spacing en grid de 8pt:

padding: 8px 16px

--space-1 · --space-2 · alineado

10

QA Checklist — Code Review

Ejecutar en cada pull request que modifique componentes de Cultiva Assistant.

Tokens: Todos los colores, espaciados y radios usan variables CSS del sistema. Ningún valor hardcoded.
foundation
Touch targets: Todos los elementos interactivos tienen mínimo 44×44px (inspeccionar en DevTools mobile).
a11y
Contraste: Pasar axe-core sobre el componente. Zero errores de contraste WCAG 1.4.3.
a11y
Focus visible: Tab por todos los interactivos. Anillo de foco naranja (--color-primary, 3px) visible en cada elemento.
a11y
Reduced motion: Activar "Reducir movimiento" en macOS/iOS. Todas las animaciones (skeleton, pulse) se detienen.
a11y
Screen reader: VoiceOver/NVDA anuncia nombre, rol y estado de cada componente sin saltar nada.
a11y
Estados completos: Cada botón/chip tiene implementados: default, hover, focus, active, disabled. No solo "default".
ux
Estado vacío: El composer deshabilitado cuando textarea está vacío. El card de respuesta tiene estado loading implementado.
ux
Etiquetas de acción: Todos los botones usan "Verbo + Objeto". Ninguno etiquetado como "OK", "Hecho" o "Continuar" sin contexto.
content
Responsive: Chips-group hace wrap en mobile. Cards no overflow en 375px. Composer funciona en single-line y multiline.
responsive
Tipografía: JetBrains Mono solo en labels/status/código. Playfair Display en todo el resto. Sin mezclas.
foundation
Semántica HTML: Botones son <button>, links son <a>. Status indicators tienen role="status". Inputs tienen <label> asociado.
a11y