Frontend UI System#

Propósito#

Esta skill existe para que el agente diseñe e implemente interfaces de usuario con un nivel visual y estructural mucho más alto que una UI genérica.

El objetivo no es solo producir código funcional. El objetivo es producir una interfaz:

• limpia
• moderna
• coherente
• comercial
• usable
• visualmente jerárquica
• reusable a nivel de componentes
• lista para crecer como producto real

La referencia mental es trabajar más cerca del nivel de criterio de un product designer + frontend engineer, y no como un simple generador de JSX o HTML.

---

Principio fundamental#

No escribir código hasta tener claridad visual suficiente.

El diseño no es decoración.

El diseño es estructura, jerarquía, intención, claridad y sistema.

Cada decisión visual debe tener una razón funcional.

---

Meta principal#

Cuando el usuario pida una app, una web, una landing, un dashboard, una pantalla o una mejora visual, esta skill debe ayudar a producir un resultado que:

• se vea mejor desde la primera iteración
• tenga mejor taste visual por defecto
• evite layouts genéricos o desordenados
• mantenga consistencia entre pantallas
• use un sistema visual claro
• implemente bien el frontend, no solo lo maquille

---

Cuándo usar esta skill#

Usa esta skill cuando el usuario pida cosas como:

• diseñar una app
• rediseñar una pantalla
• mejorar una UI
• hacer una landing page
• construir un dashboard
• crear una web moderna
• hacer una interfaz más premium
• refinar frontend
• hacer una app mobile-first
• mejorar UX/UI
• crear componentes visualmente consistentes
• transformar una interfaz básica en algo más moderno y comercial

También úsala cuando el usuario diga frases vagas como:

• “hazlo más moderno”
• “hazlo más premium”
• “hazlo más limpio”
• “se ve muy básico”
• “quiero que se vea profesional”
• “quiero que parezca producto real”
• “hazlo como una app seria”
• “quiero una UI bonita”

---

Resultado esperado#

Esta skill debe hacer que el agente:

1. piense antes de codificar
2. proponga dirección visual
3. documente un mini design system
4. defina arquitectura de pantallas
5. implemente con componentes reutilizables
6. revise jerarquía visual, spacing y consistencia
7. itere si el resultado sigue viéndose genérico o flojo

---

FASE 0: diagnóstico inicial#

Antes de diseñar o implementar, responder internamente estas preguntas:

Preguntas base#

1. ¿Qué tipo de producto es?

• App móvil
• Web app
• Landing page
• Dashboard
• E-commerce
• SaaS
• Plataforma interna
• Portal
• Sistema administrativo
• Sitio institucional

1. ¿Quién es el usuario objetivo?

• consumidores
• empresas
• profesionales
• jóvenes
• técnicos
• administradores
• clientes finales
• personal operativo

1. ¿Cuál es la acción principal del usuario?

• comprar
• reservar
• registrarse
• explorar
• consultar
• crear contenido
• subir información
• revisar métricas
• gestionar datos
• agendar
• confirmar una acción

1. ¿Qué personalidad debe transmitir el producto?

• premium
• confiable
• moderno
• amigable
• técnico
• corporativo
• juvenil
• sobrio
• innovador
• deportivo
• elegante

1. ¿Cuál es la prioridad del contexto?

• conversión
• claridad
• velocidad
• confianza
• facilidad de uso
• densidad de información
• exploración
• mobile-first
• desktop-first

Regla#

No pasar a implementación sin haber aclarado mentalmente estas cinco cosas.

---

FASE 1: dirección visual#

Regla obligatoria#

Siempre que no exista una dirección visual completamente definida, proponer 2 o 3 estilos visuales distintos antes de implementar.

Formato de propuesta visual#

Para cada estilo, documentar:

Estilo [Letra]: "[Nombre conceptual]"

• Concepto: descripción de 1 línea
• Paleta: color primario + neutrales + acento
• Tipografía: familia y personalidad
• Personalidad: 3 adjetivos
• Fortaleza: por qué funcionaría bien
• Riesgo: qué podría salir mal si se exagera

Ejemplo de estructura#

Estilo A: "Corporate Trust"

• Concepto: profesional, serio y confiable
• Paleta: azul marino + grises + blanco + acento sobrio
• Tipografía: Inter
• Personalidad: confiable, corporativo, claro
• Fortaleza: transmite seguridad
• Riesgo: puede sentirse algo genérico

Estilo B: "Modern Minimal" ⭐ RECOMENDADO

• Concepto: limpio, contemporáneo y premium
• Paleta: negro suave + blanco + gris neutro + verde lima o azul sobrio
• Tipografía: Geist / Inter / Plus Jakarta Sans
• Personalidad: moderno, premium, tecnológico
• Fortaleza: elegante y muy adaptable
• Riesgo: si se exagera, puede verse vacío

Estilo C: "Friendly Product"

• Concepto: accesible y moderno
• Paleta: tonos amigables con neutrales limpios
• Tipografía: Plus Jakarta Sans / Manrope
• Personalidad: accesible, cálido, moderno
• Fortaleza: gran cercanía con el usuario
• Riesgo: puede perder seriedad en ciertos contextos

Recomendación obligatoria#

Marcar uno como RECOMENDADO y justificar por qué encaja mejor con el producto, el usuario y la acción principal.

---

FASE 2: mini design system#

Una vez elegida la dirección visual, documentar un mini sistema antes de codificar.

2.1 Tokens de color#

Definir mínimo estos tokens:

TokenUsoprimarymarca, CTA principal, focoprimary-foregroundtexto sobre primarybackgroundfondo principalforegroundtexto principalcardfondo de superficiescard-foregroundtexto en cardsmutedfondos secundariosmuted-foregroundtexto secundarioaccentbadges, highlights, estados activosaccent-foregroundtexto sobre accentborderseparadores y bordesdestructiveerrores y acciones destructivassuccessconfirmaciones si aplicawarningalertas si aplica

Reglas de color#

• Usar preferentemente máximo 5 colores dominantes en la experiencia.
• Tener 1 color primario claro.
• Usar 2 o 3 neutrales máximos.
• Mantener 1 o 2 acentos funcionales.
• Preferir colores sólidos frente a gradientes innecesarios.
• Usar nombres semánticos, no colores directos, cuando se implementen tokens.
• Verificar contraste suficiente.
• El acento debe ayudar a la jerarquía, no competir con todo.

Evitar#

• demasiados colores compitiendo
• acentos por todas partes
• gradientes sin propósito
• colores chillones en exceso
• usar muchos tonos sin sistema

---

2.2 Tipografía#

Definir:

• familia principal
• pesos usados
• escala base
• line height
• rol de headings, body, caption, labels

Reglas tipográficas#

• Máximo 2 familias tipográficas.
• Tamaño mínimo recomendado para body: 14px.
• Headings con peso 600-700.
• Body con 400-500.
• Mantener line-height cómodo: 1.4 a 1.6.
• Limitar variedad de tamaños.
• La tipografía debe reforzar personalidad y legibilidad.

Escala sugerida#

• 14
• 16
• 18
• 20
• 24
• 30
• 36
• 48

No hace falta usar todos. Solo los necesarios.

---

2.3 Espaciado#

Definir una unidad base y una escala consistente.

Recomendación#

Unidad base: 4px

Escala común:

• 4
• 8
• 12
• 16
• 20
• 24
• 32
• 40
• 48
• 64
• 80

Reglas de spacing#

• El whitespace es una de las herramientas más importantes.
• Mejor pecar por más aire que por saturación.
• El spacing debe marcar agrupación lógica.
• Elementos relacionados: gaps más cortos.
• Secciones distintas: gaps más amplios.
• Repetir la misma lógica de espaciado entre pantallas.

Señal de mala UI#

Si todo está muy junto, la UI se percibe barata o improvisada.

---

2.4 Border radius#

Definir radios por nivel.

Sugerencia:

• XS: 6px
• SM: 8px
• MD: 12px
• LG: 16px
• XL: 20px o 24px
• Full: 9999px

Regla#

Usar radios consistentes según tipo de componente.

No mezclar demasiados radios diferentes sin motivo.

---

2.5 Sombras y profundidad#

Las sombras deben ser suaves y escasas.

Niveles sugeridos#

• ninguna
• suave
• media
• fuerte solo en casos muy puntuales

Regla#

Preferir una interfaz limpia con elevación moderada antes que una interfaz recargada.

Evitar#

• sombras muy oscuras
• muchas profundidades diferentes
• usar sombra para compensar mala jerarquía

---

FASE 3: arquitectura de pantallas#

Antes de codificar, documentar la estructura general.

Tabla mínima#

PantallaEstructuraCTA principalComponentes claveHomehero / resumen / accesos rápidosacción principalcards, hero, quick actionsListafiltros + listadoclick/tap en itemfilter bar, item cardDetalleheader + contenido + acciónCTA fija o visiblegallery, info, summaryFormulariopasos + campos + submitconfirmarfield, summary, stepperPerfildatos + acciones + historialeditar/continuarprofile sections

Para cada pantalla definir#

1. qué ve primero el usuario
2. qué debe hacer
3. qué estados necesita
4. cómo navega desde y hacia ella
5. qué componentes pueden reutilizarse

Regla#

No tratar pantallas como piezas aisladas.

Pensar el flujo completo del producto.

---

FASE 4: reglas visuales estrictas#

Estas reglas buscan evitar resultados genéricos o visualmente flojos.

4.1 Jerarquía visual#

Debe quedar claro:

• qué es lo principal
• qué es secundario
• qué es informativo
• cuál es la acción clave

Reglas#

• Un viewport no debe tener demasiados elementos compitiendo por atención.
• Debe existir un CTA primario claro.
• Los títulos deben diferenciarse claramente del body.
• La información secundaria debe sentirse secundaria.
• El uso del color debe reforzar la jerarquía.

---

4.2 Densidad visual#

Regla#

Reducir ruido.

Si hay duda entre agregar o quitar, normalmente conviene quitar.

Buscar#

• aire
• estructura
• ritmo
• bloques legibles
• agrupación lógica

Evitar#

• demasiados iconos
• demasiados badges
• textos compactos
• cards apretadas
• bordes y sombras en exceso
• microdetalles que distraen

---

4.3 Consistencia#

Regla crítica#

Mismo componente = mismo comportamiento visual y estructural.

Debe mantenerse consistente:#

• radios
• padding interno
• estados
• estilo de botones
• estilo de inputs
• altura de componentes similares
• patrones de card
• chips y badges
• spacing entre bloques
• tono de iconografía

---

4.4 Mobile-first#

Proceso obligatorio#

1. Pensar primero en 375px aprox.
2. Luego expandir a tablet y desktop.
3. Asegurar CTA claros en móvil.
4. Mantener touch targets cómodos.

Reglas#

• mínimo razonable de touch target: 44x44px
• formularios cómodos para móvil
• sticky bottom CTA si ayuda
• no confiar en hover como interacción principal

---

FASE 5: reglas de implementación frontend#

Esta skill no solo diseña. También debe ayudar a implementar bien.

5.1 Filosofía de implementación#

Construir primero una base sólida de componentes y layout.

No escribir una pantalla gigante llena de JSX repetido sin estructura.

5.2 Estructura recomendada#

Separar cuando sea razonable en:

• components/ui
• components/shared
• features/...
• pages o screens
• hooks
• lib
• types

No es obligatorio usar exactamente esos nombres, pero sí mantener organización clara.

---

5.3 Reutilización#

Regla#

Si un patrón se repite 2 o más veces, evaluar extraer componente.

Extraer especialmente:#

• botones
• cards
• headers de sección
• list items
• inputs
• filtros
• barras de acción
• resúmenes
• skeletons
• empty states

---

5.4 Props y variantes#

Cuando haya componentes reutilizables, preferir variantes claras:

• variant
• size
• state
• tone

Ejemplos:

• variant="default|outline|ghost"
• size="sm|md|lg"

Regla#

No duplicar un mismo componente con diferencias mínimas si una variante resuelve el caso.

---

5.5 Estilo de layout#

Prioridad general#

1. flex
2. grid cuando el layout realmente lo necesite
3. absolute/fixed solo cuando tenga sentido real
4. nunca usar hacks viejos si hay una solución moderna y clara

Regla#

El layout debe ser legible y fácil de mantener.

---

5.6 Responsive#

Definir claramente:

• comportamiento móvil
• comportamiento tablet
• comportamiento desktop

No solo “hacerlo caber”.

Debe adaptarse con intención.

---

5.7 Accesibilidad mínima#

Siempre verificar, al menos:

• contraste suficiente
• labels entendibles
• foco visible
• botones e inputs legibles
• touch targets adecuados
• no depender solo del color para comunicar estado

---

5.8 Estados de interacción#

Todo componente importante debería contemplar si aplica:

• hover
• active
• focus
• disabled
• loading

---

FASE 6: patrones obligatorios#

6.1 Empty state#

Toda pantalla con contenido variable debería contemplar empty state si aplica.

Debe tener:

• mensaje claro
• tono útil
• orientación de siguiente paso
• CTA cuando sea útil

No dejar zonas vacías sin explicación.

---

6.2 Loading state#

Usar:

• skeletons para contenido predecible
• spinner solo cuando tenga sentido
• feedback visual claro

No dejar la pantalla vacía mientras carga.

---

6.3 Error state#

Debe tener:

• mensaje entendible
• opción de retry o acción útil
• mantener contexto del usuario cuando sea posible

No mostrar errores técnicos crudos salvo contexto técnico explícito.

---

6.4 Success state#

Debe dejar claro:

• qué se completó
• qué sigue
• si se puede deshacer o continuar

---

6.5 Navegación#

Elegir patrón según producto:

• bottom nav: apps móviles con pocas secciones principales
• sidebar: dashboards o entornos desktop
• header + menu: webs responsive
• breadcrumbs: jerarquías profundas

No mezclar patrones sin lógica.

---

6.6 CTA#

Regla principal#

Debe existir jerarquía clara de acciones.

• CTA primario: la acción principal
• CTA secundario: apoyo
• CTA terciario: link o acción menor

Evitar#

• múltiples primarios compitiendo
• CTA oculto o débil
• demasiadas acciones con igual peso

---

FASE 7: interpretación de pedidos vagos#

Cuando el usuario pida cambios ambiguos, traducirlos a decisiones concretas.

“Hazlo más moderno”#

• reducir ruido
• usar más whitespace
• radios más refinados
• tipografía más limpia
• sombras más suaves
• layout más ordenado
• menos adornos

“Hazlo más premium”#

• menos elementos
• paleta más sobria
• mejor jerarquía
• más aire
• tipografía más elegante
• detalles más sutiles
• evitar colores chillones

“Hazlo más profesional”#

• neutrales dominantes
• acento controlado
• estructura sobria
• sin decoraciones innecesarias
• consistencia estricta

“Hazlo más juvenil”#

• energía controlada
• color más expresivo pero limitado
• bordes más amables
• tipografía con más personalidad
• UI más dinámica

“Hazlo más limpio”#

• quitar elementos
• reducir variedad visual
• reforzar jerarquía
• aumentar espacio entre bloques
• simplificar estructura

“Está muy básico”#

• mejorar composición
• mejor jerarquía tipográfica
• mejor acento
• spacing más intencional
• componentes mejor proporcionados
• detalles sutiles de producto real

“Hazlo más accesible”#

• aumentar legibilidad
• mejorar contraste
• hacer objetivos táctiles más cómodos
• reforzar focus states
• lenguaje más claro

---

FASE 8: revisión crítica antes de entregar#

Antes de considerar que la UI está bien, revisar esta checklist.

Señales de mala UI#

Corregir inmediatamente si aparecen varias de estas:

• elementos demasiado juntos
• demasiados colores
• tipografía inconsistente
• demasiados tamaños y pesos distintos
• botones sin jerarquía clara
• cards deformes o con padding incoherente
• layout plano o sin foco
• demasiados elementos compitiendo
• texto difícil de escanear
• contraste pobre
• componentes similares con estilos diferentes
• CTA poco visible
• demasiado borde, sombra o badge
• sensación de plantilla genérica
• desktop bien pero móvil descuidado
• mobile comprimido y poco cómodo

Señales de buena UI#

• abundante whitespace bien usado
• jerarquía visual evidente
• fluidez de lectura
• componentes consistentes
• CTA claro
• estructura limpia
• color intencional
• flujo entendible
• buenas proporciones
• sensación de producto real

---

FASE 9: autocrítica y segunda iteración#

Si la primera versión aún se siente genérica, no asumir que ya está terminada.

Proceso obligatorio de autocrítica#

Preguntarse:

1. ¿Esto se ve como demo rápida o como producto serio?
2. ¿La jerarquía visual es obvia en 3 segundos?
3. ¿El spacing está realmente bien o solo “aceptable”?
4. ¿El CTA principal destaca lo suficiente?
5. ¿Hay demasiada información compitiendo?
6. ¿Las cards y contenedores tienen buenas proporciones?
7. ¿La UI transmite la personalidad correcta?
8. ¿Móvil se siente diseñado o solo adaptado?

Si varias respuestas son negativas, hacer una segunda iteración antes de cerrar.

---

FASE 10: uso de screenshots y revisión visual#

Si el entorno permite screenshots, navegador o render visual, aprovecharlo.

Qué revisar en capturas#

• jerarquía
• spacing
• legibilidad
• equilibrio visual
• densidad
• CTA
• consistencia
• sensación premium / moderna / profesional según el caso
• adaptación mobile

Regla#

La revisión visual es parte del trabajo, no algo opcional.

---

FASE 11: comportamiento esperado del agente#

Cuando esta skill esté activa, el agente debe comportarse así:

1. No saltar directo a escribir una UI sin criterio.
2. Pensar en producto, usuario y acción principal.
3. Proponer dirección visual si hace falta.
4. Definir un pequeño sistema antes de implementar.
5. Construir con componentes reutilizables.
6. Mantener consistencia entre pantallas.
7. Revisar estados y responsive.
8. Ser crítico consigo mismo antes de finalizar.
9. Evitar caer en la primera solución genérica.
10. Buscar una salida más cercana a un producto real que a una maqueta improvisada.

---

FASE 12: qué evitar#

Evitar especialmente:

• escribir primero y pensar después
• llenar de componentes sin jerarquía
• usar demasiados colores
• meter demasiados estilos distintos
• repetir JSX con cambios mínimos
• hacer UI “bonita” pero incómoda
• descuidar móvil
• esconder la acción principal
• diseñar solo para impresionar sin pensar en tarea real
• entregar una primera versión floja como si ya estuviera final

---

FASE 13: guía rápida de decisión#

Si el producto es:#

SaaS / Dashboard#

• claridad
• estructura
• información bien jerarquizada
• sidebar o top nav clara
• cards sobrias
• densidad controlada

App móvil de consumo#

• bottom nav si aplica
• CTA claro
• touch comfort
• menos texto
• componentes grandes y limpios
• ritmo vertical cuidado

Landing page#

• hero fuerte
• narrativa clara
• secciones bien marcadas
• CTA repetido estratégicamente
• visuales limpios
• jerarquía muy clara

E-commerce / reservas / servicios#

• confianza
• búsqueda o exploración clara
• cards potentes
• detalle bien estructurado
• CTA muy visible
• estados y resumen claros

---

FASE 14: salida ideal#

La salida ideal de esta skill no debe quedarse en teoría.

Debe terminar ayudando a producir algo concreto como:

• propuesta visual
• design system
• arquitectura de pantallas
• plan de componentes
• implementación frontend
• revisión crítica
• mejoras iterativas

---

Resumen operativo#

Orden correcto de trabajo#

1. entender producto, usuario y acción
2. definir dirección visual
3. elegir estilo recomendado
4. documentar mini design system
5. definir arquitectura de pantallas
6. implementar con componentes reutilizables
7. revisar estados y responsive
8. autocriticar resultado
9. iterar si todavía se ve genérico

---

Nota final#

Consistencia > ocurrencias aisladas

Claridad > decoración

Whitespace > saturación

Sistema > improvisación

Producto real > demo genérica

Ante la duda, simplificar, ordenar y reforzar jerarquía.