pretty-ui

¿Qué hace pretty-ui?

Las pantallas creadas por IA se parecen entre sí porque nadie eligió nada. El modelo rellena cada vacío con la respuesta más común que ha visto, y el resultado es una página que podría pertenecer a cualquier producto.

pretty-ui soluciona esto en el orden que lo haría un diseñador: elegir una dirección, escribirla, aplicarla en todas partes y verificar el resultado. La elección la hace la persona, a partir de opciones reales que puede ver, no solo el agente.

La ejecución

Sigue estos pasos en orden. Indica al usuario en qué paso te encuentras.

1. Leer el proyecto

• Averigua qué se está construyendo: una página que se lee y se desplaza (página de aterrizaje, sitio de marketing, portafolio), una pantalla de aplicación web en la que se trabaja (panel de control, configuración, bandeja de entrada) o una aplicación móvil.
• Identifica la pila tecnológica: HTML plano, Tailwind, shadcn/ui, React, Vue, Svelte, React Native, SwiftUI, Compose o Flutter. Trabaja siempre en esa pila. No la migres.
• Busca un sistema visual existente: DESIGN.md, AGENTS.md o CLAUDE.md con notas de diseño, variables de tema de Tailwind o shadcn, una guía de marca, un logotipo. Si la marca ya tiene colores y fuentes, consérvalos. Las direcciones del paso 3 varían entonces el diseño, la escala tipográfica, la densidad y los acentos dentro de la marca, no la marca en sí.
• Recopila contenido real: el nombre del producto, qué hace, para quién es, números reales, capturas de pantalla reales. El contenido de relleno hace que todo diseño parezca genérico.

2. Auditoría (solo cuando ya existe una interfaz)

Lee references/tells.md. Ejecuta el verificador en los archivos que renderizan la interfaz:

node <skill>/scripts/check.mjs <archivos o carpetas>

Enumera los hallazgos para el usuario, agrupados por gravedad, con archivo y línea. Añade todo lo que el verificador no pueda detectar al leer el código: tres tarjetas idénticas, todo centrado, sin punto focal claro, texto de relleno. Si la pantalla ya está bien diseñada, indícalo y sugiere dos o tres pequeños refinamientos en lugar de un rediseño.

3. Ofrecer tres direcciones

Lee references/systems.md. Enumera 24 sistemas de diseño completos, 12 para web y 12 para aplicaciones móviles, cada uno con un DESIGN.md público.

1. Elige tres sistemas que difieran a propósito: por ejemplo uno claro y editorial, uno oscuro y denso, uno suave y amigable. Que coincidan con la plataforma (web o app) y el mundo del producto. Nunca ofrezcas tres variaciones del mismo aspecto.
2. Obtén el DESIGN.md de cada sistema desde su URL.
3. Construye la misma pantalla clave en cada dirección, con el mismo contenido real, como archivos HTML autocontenidos:
   • pretty-ui/directions/a-<slug>.html, b-<slug>.html, c-<slug>.html
   • Páginas web a 1440×900, pantallas móviles a 390×844. CSS en línea, enlaces a Google Fonts, sin imágenes externas.
4. Haz que sean fáciles de comparar:
   • Si las herramientas de lienzo de diseño de Codex están disponibles (por ejemplo create_canvas y add_node), coloca los tres archivos en un mismo lienzo uno al lado del otro y ábrelo.
   • En caso contrario, ejecuta node <skill>/scripts/compare.mjs pretty-ui/directions/*.html --out pretty-ui/directions/index.html y dile al usuario que abra ese archivo.
5. Pide al usuario que elija una, o que combine partes ("el tipo de A con los colores de C"). Si te pidieron que decidas tú, elige la que mejor se adapte al producto y explica por qué en una frase.

Cuando la marca es fija, las tres direcciones usan los colores y fuentes de la marca y difieren en diseño, escala y densidad.

4. Escribir el sistema

• Guarda el sistema elegido como DESIGN.md en la raíz del proyecto. Mantén su formato: metadatos YAML con tokens, luego Resumen, Colores, Tipografía, Diseño, Formas, Componentes y Qué hacer y qué no hacer.
• Aplica cualquier cambio que haya solicitado el usuario (un color de marca, una fuente de encabezado diferente) en el archivo, no solo en el código.
• Añade una línea a AGENTS.md (y a CLAUDE.md si el proyecto tiene uno): Sigue DESIGN.md para cada pantalla: colores, tipo, espaciado, radio y componentes. Codex lee AGENTS.md automáticamente, pero no DESIGN.md.
• Para proyectos con shadcn o Tailwind, mapea los tokens en las variables de tema (--background, --primary, --radius y el resto). Cada página de sistema enlaza un tema shadcn listo: npx shadcn@latest add https://codexdesign.io/r/<slug>.json.

5. Aplicarlo, paso a paso

Trabaja en toda la pantalla una capa a la vez, como una revisión de diseño de un diseñador. Conserva las funcionalidades, el contenido y el orden de las secciones a menos que el usuario indique lo contrario.

1. Tokens. Reemplaza los colores, tamaños y radios escritos en código fijo con los tokens del sistema.
2. Tipografía. Como máximo dos familias. Usa la escala del sistema. Asegúrate de que la línea más importante de la pantalla sea claramente la más grande. Usa cifras tabulares para números que se alineen.
3. Espaciado y diseño. Una unidad de espaciado del sistema y sus múltiplos. Alinea todo a la cuadrícula o al relleno de la pantalla. Agrupa elementos relacionados de manera compacta y separa los grupos generosamente.
4. Color. Los neutros llevan la pantalla. El color primario aparece donde el usuario actúa, aproximadamente una vez por vista. Los gráficos usan los colores del sistema en orden.
5. Componentes. Los botones, campos de entrada, tarjetas, listas y navegación siguen la sección de Componentes del sistema. Iconos reales (Lucide, Phosphor, SF Symbols, Material Symbols), nunca emojis como iconos.
6. Texto. Palabras claras y específicas del producto. Elimina el relleno ("sin fisuras", "desbloquear", "potenciar"). Los titulares dicen qué es o qué hace la cosa.
7. Detalles. Estados de hover, foco y presionado; estados vacío, de carga y de error; contraste de al menos 4.5:1 para texto.
8. Movimiento. Solo donde explica algo: un cambio de estado, una transición entre pantallas. Sin apariciones graduales en cada sección, sin decoraciones pulsantes.

Para aplicaciones móviles, lee también references/app.md.

6. Verificar

• Vuelve a ejecutar el verificador en los archivos modificados y corrige todos los errores y tantas advertencias como tenga sentido.
• Observa el resultado. Si Playwright o una herramienta de navegador está disponible, haz una captura de pantalla a 1440 y 390 de ancho (o el tamaño de dispositivo para apps) y corrige lo que se vea mal: sin punto focal, grupos apretados, texto que se muestra mal, bajo contraste.
• Para un rediseño, crea una página de antes y después que el usuario pueda compartir:

node <skill>/scripts/compare.mjs before.html after.html --labels "Antes,Después" --out pretty-ui/before-after.html

7. Informar

Cuéntale al usuario, brevemente: la dirección elegida y por qué, los archivos modificados, lo que encontró el verificador antes y después, y cualquier cosa que requiera su decisión (fotos reales, un logotipo, texto que solo ellos pueden escribir).

Reglas que siempre aplican

• Muestra opciones antes de comprometerte con una. Nunca elijas un estilo en silencio.
• Mantén la marca, el contenido y la pila del usuario.
• Un sistema de diseño por producto, escrito en DESIGN.md, seguido en todas partes.
• Sin degradados morados o violeta, texto con degradado, paneles de vidrio esmerilado, sombras brillantes, iconos emoji, insignias tipo píldora sobre cada encabezado, ni filas de tarjetas con iconos idénticos, a menos que el usuario lo solicite explícitamente.
• No cambies un cliché por otro. Crema con serifa y acento terracota, o casi negro con un acento verde ácido, son los nuevos valores predeterminados; úsalos solo cuando el mundo del producto lo requiera.
• Eliminar la decoración es la mitad del trabajo. Llena el espacio con contenido real, tipografía más grande para lo que importa y un elemento memorable extraído del propio producto.

Archivos

• references/systems.md: los 24 sistemas de diseño, con plataforma, estilo y URL de DESIGN.md.
• references/tells.md: qué hace que una interfaz parezca creada por IA, y qué hacer en su lugar.
• references/app.md: reglas para pantallas de iOS, Android y multiplataforma.
• scripts/check.mjs: un verificador estático de marcas de IA en archivos HTML, CSS, JSX, TSX, Vue y Svelte. Node 18+, sin dependencias.
• scripts/compare.mjs: genera una página HTML que muestra varias pantallas lado a lado, para elegir una dirección o mostrar antes y después.