bruno-baeta/clean-ui

Clean UI

Interfaz minimalista, moderna, con tema claro y oscuro, que cabe en la pantalla, con datos en primer lugar y con aspecto de producto hecho por personas, no por IA. Las reglas siguientes provienen de solicitudes reales de ajuste. Cada una ya ha irritado al usuario cuando se ha incumplido: trátalas como requisitos, no como sugerencias.

Archivos de la skill

Rutas relativas a la carpeta de esta skill.

Archivo	Cuándo usarlo
references/informacion.md	Toda pantalla nueva o rediseño, antes del layout. Cómo elegir qué mostrar, el orden de prioridad y la posición de cada información (inventario, preguntas del usuario, niveles, filtro, mapa de posiciones, plan escrito).
references/patrones-aprobados.md	Bloques que el usuario ha aprobado ("quedó mucho mejor"): tarjeta de decisión, gráfico de la medida de la decisión con la línea del límite, tarjeta de situación con saldo a lo largo del tiempo, lista del propio usuario, apoyo estacional, encabezado del móvil, orden por prioridad, ultra ancho. Úsalos como punto de partida para el contenido, no como esqueleto fijo.
references/trampas.md	Errores técnicos que ya han costado retrabajo (Tailwind v4, cn sin merge, especificidad de [&>*]:, next-themes, servidor con CSS viejo, probar estados que la base de datos local no tiene). Léelos antes de escribir el código.
references/migracion.md	Rediseñar la app entera (varias pantallas): pantalla de referencia aprobada primero, base hecha por ti (marco, piezas de página, tokens en el body, tema guardado), frentes paralelos con brief común, integración (pedidos para el kit, borrar código antiguo solo al final, reiniciar, verificar todo).
references/ejemplos.md	Casos reales de incorrecto y correcto. Léelos al crear una pantalla nueva o cuando dudes si algo está bien.
references/dashboards.md	Toda pantalla con números, gráficos o mapas. Lo que separa lo amateur de lo profesional, principios (NN/g, Stephen Few, IBM Carbon), 7 composiciones (elige la que sirva al plan de información), reglas para pantallas anchas y ultra anchas, color y acabado de los gráficos.
references/paletas.md	Paletas listas y validadas (Cobalto, Índigo, Ciano, Coral) con grises, color de acento, escala ordenada y colores de series para los dos temas. Elige por aquí, nunca colores sueltos.
assets/tokens.css	Proyecto nuevo o sin identidad: tema claro y oscuro (sigue el sistema, con cambio manual), fuente, foco, gráficos y toque ya configurados (Tailwind v4). Viene con la paleta Cobalto solo como punto de partida: cámbiala por el bloque completo de la elegida (final de paletas.md). Incluye la variante tall, positivo/negativo/aviso y la manita.
references/ejemplos-dashboards/	Las 7 referencias del usuario de dashboard moderno. Ábrelas todas antes de diseñar cualquier dashboard.
references/anatomia-dashboard.md	Las referencias traducidas en medidas: tarjeta, título, indicador, chips, números en la parte superior del gráfico, gráficos, partes de un todo, medidor, tabla, móvil, y qué no copiar.
assets/dashboard.tsx	Kit de dashboard medido según las referencias: DashCard, Kpi, IconCircle, DeltaChip, StatusChip, TrendDot, CountBadge, Tabs, SeriesStat, StatColumns, Dashed, KeyValue, StackedBar, LegendGrid, Gauge, clases TH/TR de tabla, TooltipCard, PillMark, props chart para Recharts, ListaAlta (la lista en una tarjeta vertical, con páginas por altura), Divergentes (lo que sumó y lo que restó), Quadro100 (de cada 100), Columnas (columnas flotantes; cascada y embudo fueron rechazados por difíciles), useFitRows (cuántas filas caben) y useFitHeight (altura de un gráfico según lo que sobra de la ventana; mide de nuevo cuando la tarjeta de arriba crece).
assets/panel.tsx	Ayudantes de mapa: useMapColumns (ancho de la columna del mapa) y FillMap (mapamundi que rellena).
assets/ui.tsx	Componentes base listos (Card, Section, IconBox, Chip, Pill, Button, BottomActions, ListRow, ListCard, StatCard, DateBlock, FillEmpty, InfoTip, NavLoading, Spinner, ThemeToggle, FitScreen). Reutilízalos o adáptalos en lugar de inventar. Si el proyecto ya tiene equivalentes, usa los del proyecto.
scripts/lint-ui.mjs	node <skill>/scripts/lint-ui.mjs src: recorre el código modificado (hover que mueve, puntos suspensivos, bordes de colores, ancho estrecho, fuentes prohibidas, color fijo que rompe uno de los temas, "—", "·", minúscula, "Etiqueta: valor").
scripts/check-ui.mjs	node <skill>/scripts/check-ui.mjs http://localhost:3000/ruta --out=capturas: toma capturas en 320 y 390 px (móvil) y en el área útil del navegador en 1366×650, 1536×730 y 1920×950 (portátiles y monitor) y 2560×960, 2752×1100 (21:9 con zoom del 125% de Windows) y 3440×1300 (ultra ancho 21:9), en los temas oscuro y claro, y mide desbordamiento horizontal y vertical (tarjeta que pasa del borde inferior de la primera pantalla o más alta que la pantalla), listas parecidas repetidas, gráfico estirado y línea de lista demasiado ancha, "…", tarjetas vecinas con alturas diferentes (también dentro de un envoltorio sin fondo), tarjeta con hueco vacío por dentro o contenido esparcido, grid incompleto, icono sin contenedor, hover que mueve, scroll interno, contenido estrecho, fuente, clicable sin manita, bordes de tarjetas casi alineados entre filas, globo del "i" fuera de la pantalla (abre cada uno), barra de desplazamiento en el móvil, línea de tabla demasiado ancha (cualquier línea repetida), texto apretado, línea de lista con título o descripción que se rompe en el móvil y página vacía o de error (espera la carga; si los datos no llegaron, el check no vale). Cada hallazgo viene con tamaño y tema. Necesita Playwright en el proyecto; --user/--pass para páginas con contraseña.

Los scripts son guías: comprueba cada hallazgo y, sobre todo, abre las capturas y míralas.

1. Proceso (lo que más causa retrabajo)

1. Haz solo lo que se pidió. Nunca elimines, cambies o "simplifiques" elementos existentes sin una solicitud explícita. Si la propuesta exige quitar algo, pregunta antes. En caso de duda, mantenlo.
2. Respeta el breakpoint solicitado. Si pidió ajuste en móvil: lo web no cambia (usa sm:/md: para preservar lo web, y viceversa).
3. Muestra antes de publicar, mirando todos los tamaños. Antes de decir que está bien, abre la captura de cada tamaño del check (incluidos 1366, 1536 y 2752, donde la tabla se rompe y la tarjeta sobra), no solo 390 y 1920. El trabajo de agente delegado también: compruébalo tú mismo. Ejecuta localmente, toma captura en móvil (390 px, y comprueba 320 px) y en web (1366×650, 1536×730 y 1920×950, el área útil real del navegador), en los dos temas, mira de verdad cada captura y solo haz commit/push/deploy con aprobación explícita.
4. Pantalla nueva o rediseño: primero la información, después el layout. Sigue references/informacion.md (y mira los bloques de references/patrones-aprobados.md y los errores de references/trampas.md): inventario de lo que el producto sabe (incluido todo lo que mostraba la pantalla antigua), preguntas del usuario en orden de urgencia, niveles de prioridad, filtro de cada información, mapa de posiciones y el plan escrito. La composición sale de ese plan. Elige tú la composición y la paleta (la de la marca, si el proyecto la tiene; si no, la de paletas.md que combine con el tema). No montes varias versiones o visiones de la pantalla para que el usuario elija. Construye una, la mejor, y di en pocas líneas por qué cada cosa está donde está. Nunca partas del esqueleto de un proyecto anterior ni repitas "4 indicadores + cuadrícula de tarjetas + listas" por defecto.
5. Detalle rechazado dos veces = opciones lado a lado. Solo cuando el usuario ya haya rechazado el mismo detalle (posición de un chip, fuente) dos veces, muestra 2 o 3 variaciones de ese detalle en captura. Nunca para la pantalla entera.
6. Después de borrar o recrear archivos, reinicia el servidor de desarrollo (o guarda el CSS de nuevo) antes del check: Tailwind puede seguir sirviendo el CSS antiguo, sin las clases nuevas.
7. Revisa con la lista de verificación (sección 10) antes de cada captura. Si no hay simetría, no está listo.

2. Tipografía

• Prohibidas (cara de IA): Inter, Roboto, Arial, Helvetica, system-ui como fuente de marca, Geist, Poppins, Montserrat, Space Grotesk, Open Sans, Lato.
• Buenas y poco usadas por IA: Plus Jakarta Sans (preferida y ya aprobada), Manrope, Onest, Figtree, Hanken Grotesk, Schibsted Grotesk, Instrument Sans, Albert Sans, Familjen Grotesk. Para títulos destacados, Bricolage Grotesque. Una sola familia por app.
• Números con font-variant-numeric: tabular-nums (tabular-nums). Nada de fuente mono con cero tachado o punteado.
• Jerarquía por peso y tamaño moderados. Etiqueta pequeña arriba (12 px, color apagado) y valor abajo (16 px, semibold). Valores lado a lado con el mismo tamaño de fuente. Nada de texto gigante colorido.
• Todo texto visible comienza con mayúscula, incluidas abreviaturas sueltas ("Jue", "Vie"). En medio de una frase, escribe normal: "Vs martes anterior", no "Vs Mar anterior". Títulos en sentence case, nunca MAYÚSCULAS.

3. Color y tema

• Siempre dos temas, claro y oscuro. Toda app nace con los dos: sigue el tema del sistema (prefers-color-scheme) y tiene un botón para cambiarlo (ThemeToggle en assets/ui.tsx), con la elección guardada. Los correos y vistas previas también responden a prefers-color-scheme. Ninguna pantalla puede existir solo en un tema.
• Colores siempre por token (var(--card), bg-card, text-muted-foreground). Nada de #000, #fff, bg-black, text-white o hex suelto en componente, gráfico o SVG: eso rompe el otro tema.
• Oscuro: fondo muy oscuro (cerca del negro), tarjeta un escalón por encima, borde discreto, texto casi blanco. Claro: fondo gris muy claro, tarjeta blanca, borde suave, texto casi negro. Ambos con el mismo cuidado y comprobados en capturas.
• La paleta no es fija, pero tampoco suelta. No existe "negro + naranja" estándar: usa una paleta entera de references/paletas.md (grises, acento, escala y series que combinan y ya han sido validadas para contraste y daltonismo), elegida por el tema y mostrada renderizada. Nada de juntar colores sueltos (el azul de un sitio, el amarillo de otro, el rojo de otro). El proyecto con marca sigue la suya (p. ej., MegaLab eligió naranja); color nuevo solo con contraste de al menos 3:1 contra la tarjeta en los dos temas y distinguible para daltónicos (si el agente tiene la guía dataviz, usa su validador).
• Base neutra, color con propósito. Los grises hacen ~90% de la pantalla. Un color de acento por app (versión por tema). Dato ordenado (magnitud, nivel, rango) usa la escala de un solo color (--seq-1..4), nunca arcoíris de gris, azul, amarillo y rojo. Series sin orden usan --cat-1..3 en orden fijo. Rojo/amarillo de alerta solo para estado real, con icono y etiqueta. Verde nunca es color de marca, pero puede aparecer en datos: chip de variación "mejoró", estado bueno y la serie categórica 3 de las paletas validadas. Sin morado aleatorio, sin marrón.
• Números nunca pintados. Los valores y etiquetas van en el color del texto; el color del dato va en una marca pequeña al lado (punto, barra fina, sello neutro con barrita de color).
• Variación para mejor y para peor (como en las referencias del usuario): chip verde suave y chip rojo suave, siempre con flecha para quien no distinga los colores (DeltaChip). Igual: chip gris.
• Estados parecidos (p. ej., Erré, Difícil, Bueno, Fácil) necesitan colores claramente diferentes entre sí.
• Sin bordes o anillos de colores para destacar tarjetas. Resalta solo con fondo suave del color (bg-primary/10).
• Texto siempre legible en los dos temas, incluidas leyendas y tooltips de gráficos después de hacer clic.

4. Layout y simetría

• Ancho completo en web. Nada de contenido estrecho centrado (max-w-* + mx-auto en la página). Usa grid para ocupar la pantalla.
• Pantalla ancha gana columnas, no estirar. Desde 1920 px hacia arriba y en ultra ancho 21:9 (2560 y 3440 px), aumenta el número de columnas con 3xl: (1920 px) y 4xl: (2560 px), definidos en tokens.css; nunca min-[1920px]: (en Tailwind v4 pierde frente a lg:), abre paneles que antes estaban ocultos (detalle al lado, tabla al lado del gráfico) y limita la proporción: gráfico de tiempo hasta ~4:1, barras y mapas hasta ~2,5:1, línea de lista hasta ~720 px. Consulta references/dashboards.md sección 4.
• Mobile first. Espaciado lateral cómodo (16 px), nada apretado, carrusel con respiro horizontal, primer elemento con espacio arriba.
• Cabe en la altura de la pantalla. El contenido se adapta a la ventana en ambas direcciones, no solo al ancho. Ningún mapa, gráfico, imagen o tarjeta de tamaño fijo pasa del borde inferior de la primera pantalla ni es más alto que la ventana (solo las listas continúan abajo, desplazando la página): mapas, gráficos e imágenes grandes tienen la altura limitada por la ventana (max-h-[calc(100dvh-<encabezado>)], h-[min(…,60dvh)], SVG con preserveAspectRatio="xMidYMid meet" dentro de un contenedor de altura definida). Nunca dimensiones un visual ancho solo por el ancho (w-full h-auto, aspect-[2/1]): en un monitor ancho o en un portátil se desborda hacia abajo. La primera pantalla (encabezado, indicadores y el bloque principal) cabe entera en 390×844, 1366×650, 1536×730 y 1920×950 (área útil del navegador, ya descontadas las barras; la pantalla entera no sirve como medida). Usa FitScreen de assets/ui.tsx.
• Pantalla siempre rellena. El último bloque se estira hasta el final (flex-1). Sin media pantalla vacía: usa contenido real o un estado vacío visual (icono en contenedor + 1 línea).
• La simetría es obligatoria:
  • tarjetas lado a lado con la misma altura (items-stretch, h-full), y el contenido interno (gráfico, tabla) crece junto y ocupa toda la altura;
  • mismo número de líneas de texto a la izquierda y a la derecha;
  • tarjeta estirada por la cuadrícula no tiene hueco por dentro: líneas de lista con altura fija y el bloque (título + líneas) centrado verticalmente, nunca justify-around/justify-between esparciendo las líneas; columnas comparables (A x B) con la misma altura de línea, para que las líneas se alineen (ver references/trampas.md, "Tarjeta que estira");
  • filas del grid completas (sin 3 + 1 sobrante);
  • en la misma columna, elementos y chips con el mismo ancho;
  • columnas de …

... [truncado para traducción]