frontend-ui-system

Diseña e implementa interfaces modernas, limpias y coherentes con design system, jerarquía clara, componentes reutilizables y enfoque mobile-first para apps...

minthymed-sh@minthymed-sh

Install

openclaw skills install @minthymed-sh/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:

piense antes de codificar
proponga dirección visual
documente un mini design system
defina arquitectura de pantallas
implemente con componentes reutilizables
revise jerarquía visual, spacing y consistencia
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

¿Qué tipo de producto es?

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

¿Quién es el usuario objetivo?

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

¿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

¿Qué personalidad debe transmitir el producto?

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

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

Token	Uso
`primary`	marca, CTA principal, foco
`primary-foreground`	texto sobre primary
`background`	fondo principal
`foreground`	texto principal
`card`	fondo de superficies
`card-foreground`	texto en cards
`muted`	fondos secundarios
`muted-foreground`	texto secundario
`accent`	badges, highlights, estados activos
`accent-foreground`	texto sobre accent
`border`	separadores y bordes
`destructive`	errores y acciones destructivas
`success`	confirmaciones si aplica
`warning`	alertas 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

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:

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

Pantalla	Estructura	CTA principal	Componentes clave
Home	hero / resumen / accesos rápidos	acción principal	cards, hero, quick actions
Lista	filtros + listado	click/tap en item	filter bar, item card
Detalle	header + contenido + acción	CTA fija o visible	gallery, info, summary
Formulario	pasos + campos + submit	confirmar	field, summary, stepper
Perfil	datos + acciones + historial	editar/continuar	profile sections

Para cada pantalla definir

qué ve primero el usuario
qué debe hacer
qué estados necesita
cómo navega desde y hacia ella
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

Pensar primero en 375px aprox.
Luego expandir a tablet y desktop.
Asegurar CTA claros en móvil.
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

flex
grid cuando el layout realmente lo necesite
absolute/fixed solo cuando tenga sentido real
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:

¿Esto se ve como demo rápida o como producto serio?
¿La jerarquía visual es obvia en 3 segundos?
¿El spacing está realmente bien o solo “aceptable”?
¿El CTA principal destaca lo suficiente?
¿Hay demasiada información compitiendo?
¿Las cards y contenedores tienen buenas proporciones?
¿La UI transmite la personalidad correcta?
¿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í:

No saltar directo a escribir una UI sin criterio.
Pensar en producto, usuario y acción principal.
Proponer dirección visual si hace falta.
Definir un pequeño sistema antes de implementar.
Construir con componentes reutilizables.
Mantener consistencia entre pantallas.
Revisar estados y responsive.
Ser crítico consigo mismo antes de finalizar.
Evitar caer en la primera solución genérica.
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

entender producto, usuario y acción
definir dirección visual
elegir estilo recomendado
documentar mini design system
definir arquitectura de pantallas
implementar con componentes reutilizables
revisar estados y responsive
autocriticar resultado
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.