Frontend UI System

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

2. ¿Quién es el usuario objetivo?

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

3. ¿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

4. ¿Qué personalidad debe transmitir el producto?

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

5. ¿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:

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

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.