Real-Fruit-Snacks/killer-design

Killer design

El objetivo es un sitio que la gente cargue y piense "guau": uno que un estudio de primer nivel podría haber hecho para este proyecto. Ordenado, correcto y de buen gusto es el mínimo, no la meta. Una página que solo evita errores es olvidable. Tres hábitos te llevan allí, y esta habilidad se basa en ellos:

1. Decide el diseño antes de escribir código. Los sitios genéricos vienen de no tomar decisiones. Las fuentes, colores y diseño por defecto son los que usa toda plantilla. Una breve dirección escrita, arraigada en el tema (o en la marca, si la hay), le da a cada elección posterior una razón.
2. Diseña un momento impactante. Dale a la primera pantalla una pieza central, arraigada en el concepto, que haga que alguien se detenga: una demo en vivo, tipografía audaz, luz que responde al puntero, una escena que se construye al desplazarte. Ejecútala con un alto estándar y mantén todo lo demás a su alrededor tranquilo para que tenga espacio. Consulta references/motion-and-wow.md.
3. Mira el resultado. El CSS escrito a ciegas siempre falla: diseños móviles apretados, jerarquía débil, texto gris que nadie puede leer, animación que se arrastra. Renderiza la página, incluido el movimiento, mírala como un crítico, corrige los problemas y vuelve a mirar.

El trabajo se desarrolla en seis pasos: entender el proyecto, establecer una dirección, escribir el contenido, construir, revisar las capturas de pantalla y corregir, y luego pulir y entregar. Los rediseños añaden un paso de inventario primero (consulta "Rediseñando un sitio existente").

1. Entender el proyecto

Lee lo que ya existe antes de preguntar nada. Eso significa el README, la documentación, los metadatos del paquete o la aplicación, el contenido existente, los logotipos y archivos de marca, las capturas de pantalla y cualquier DESIGN.md. Averigua:

• Qué es, en una frase que un desconocido entendería.
• Quién llega, y qué necesita decidir o hacer. Nombra la única acción principal: instalar, reservar, registrarse, ponerse en contacto.
• Los detalles concretos: comandos reales, números, nombres, horarios, lugares, funciones, restricciones, historia. Esta es la materia prima para el contenido y los visuales, y el detalle específico es lo que evita que un sitio se sienta genérico.
• Personalidad: tres adjetivos, más una cosa que no es. "Preciso, tranquilo, confiable; no juguetón."
• Restricciones: alojamiento (por ejemplo, GitHub Pages estático), cualquier cosa que deba permanecer y los activos de marca existentes.
• Intención documentada: lo que el README o la documentación dicen que es el sitio, y lo que deliberadamente omiten ("una página, un botón a GitHub; la lista completa vive en otro lado"). Esa es una decisión que alguien ya tomó. Mantenla, y ofrece cualquier cosa más allá como propuesta en la entrega en lugar de construirla.
• Si existe un sistema de marca: una guía de marca (BRAND.md, una guía de estilo, un repositorio de marca), tokens de diseño, un DESIGN.md, o un conjunto consistente de activos de marca terminados (tarjetas sociales, banners, portadas de README, el sitio actual). Si existe, el paso 2 funciona de manera diferente. Consulta "Trabajando dentro de una marca existente" a continuación.

Pregunta al usuario solo por cosas que no puedas encontrar o inferir razonablemente y que cambiarían el diseño. El ejemplo obvio es lo que realmente hace el producto. Para todo lo demás, toma una decisión razonable y enumera tus suposiciones en la entrega. Reaccionar a una página real les resulta más fácil que responder un cuestionario.

2. Establecer la dirección de diseño

Si el proyecto ya tiene un sistema de marca, su marca es la dirección. Salta a "Trabajando dentro de una marca existente" y vuelve para el paso 3. Lo que sigue es para proyectos que necesitan un diseño inventado.

"Limpio y moderno" no es una dirección. Es lo que obtienes cuando no se tomó ninguna decisión.

Encuentra el concepto en el tema. Pregunta en qué mundo vive el proyecto. Un taller de reparación de violines sugiere abeto y barniz, etiquetas escritas a mano, dibujos a escala. Un portal de datos abiertos de una ciudad sugiere mapas de tránsito, sistemas de señalización y horarios. Un gimnasio de escalada sugiere mapas topográficos, tiza y grados de ruta. Ve más allá de la primera asociación hacia algo específico: "papel y tinta" se aplica a casi cualquier cosa, mientras que "un sobre de semillas de un catálogo de los años 50" no. El concepto debe dar forma al tipo, la paleta, la textura y el diseño. No debe convertirse en clip art o juegos de palabras.

Bosqueja tres direcciones genuinamente diferentes en una o dos líneas cada una, variando el concepto, el tipo, la temperatura de color y la actitud del diseño. Luego elige la que mejor se adapte a la audiencia y la personalidad. La primera idea que viene a la mente suele ser la más genérica, por eso escribes tres. Verifica la dirección elegida con "Qué hace que un sitio parezca hecho por IA" cerca del final de este archivo. Si se reduce a una de las paletas estándar más las secciones habituales, empújala más allá.

Elige el momento impactante. Pregunta cuál es la única cosa verdadera más interesante sobre el proyecto, y cómo la primera pantalla podría mostrarla en lugar de decirla. Escribe dos o tres momentos candidatos y elige el que sea más acorde con el concepto y que puedas ejecutar maravillosamente. Lee references/motion-and-wow.md para conocer el menú de técnicas y las recetas probadas. Luego pregúntate honestamente si alguien que vea esto diría "guau" o "bonito". Si la respuesta es "bonito", sé más audaz: aumenta la escala, crea un contraste más fuerte, haz que el momento esté más vivo.

Escribe la dirección en DESIGN.md en la raíz del sitio, usando la plantilla a continuación. El archivo mantiene la consistencia entre páginas futuras y sesiones futuras. Si ya existe un DESIGN.md, síguelo y amplíalo en lugar de inventar un nuevo aspecto, a menos que el usuario haya solicitado una nueva dirección.

Antes de elegir tipo y color, lee references/typography.md y references/color.md. Contienen combinaciones de fuentes y un método de paleta que evitan los valores predeterminados habituales. references/layout.md cubre composiciones más allá de "héroe más tres tarjetas".

# Diseño: <proyecto>

## Concepto
Una o dos frases: el mundo en el que esto vive y la sensación que un visitante debería llevarse.

## Audiencia y acción principal
Quién llega, qué necesita saber, la única cosa que queremos que hagan.

## Tipo
Display: <familia, pesos>, y por qué. Texto: <familia, pesos>, y por qué. Mono, si lo hay.
Escala: tamaño base y proporción (de scripts/scale.mjs).

## Color
Rol -> valor: bg, surface, ink, ink-muted, line, accent, on-accent, focus.
Reglas de uso (ej. "acento solo en la acción principal y estados activos").

## Diseño
Cuadrícula y anchos, ritmo de secciones, actitud general (editorial, denso, aireado, asimétrico...).

## Firma
El uno o dos movimientos por los que la gente recordará este sitio.

## Momento impactante
Lo que hace que alguien se detenga en la primera pantalla, y cómo funciona. También cómo se ve sin JS, con movimiento reducido y en un teléfono.

## Imágenes y textura
De qué son los visuales y cómo se hacen, dados los activos que existen.

## Movimiento
Qué se mueve, cómo y cuánto. Respeta el movimiento reducido.

## Voz
Cómo suena el texto; palabras para usar y palabras para evitar.

## Alternativas consideradas
Las otras dos direcciones, una línea cada una, para que el usuario pueda redirigir.

Elige una dirección y constrúyela. No te detengas a pedirle al usuario que elija entre abstracciones. Enumera las alternativas en la entrega para que puedan redirigir una vez que hayan visto una página real.

3. Escribir el contenido primero

El diseño sigue al contenido. Un diseño dibujado alrededor de lorem ipsum produce cajas genéricas, y un texto genérico hace que incluso un buen diseño se lea como una plantilla. Escribe las palabras reales antes de diseñar cualquier cosa:

• Titular: qué es, o qué cambia para el visitante, en palabras sencillas. Lo específico vence a lo ingenioso. "Reserva una cancha en cualquier club de tenis público de Leeds" vence a "Tu juego, elevado."

• Usa los detalles específicos del proyecto: comandos reales, números reales, nombres reales, los horarios y lugares reales.

• Elimina el lenguaje de marketing genérico: desbloquear, elevar, sin fisuras, empoderar, revolucionar, recargar, sin esfuerzo, de vanguardia, robusto, apalancar, juego cambiante, "lleva X al siguiente nivel", "en el mundo acelerado de hoy". Si una frase podría aparecer en cualquier sitio web, reescríbela.

• Evita tanto las formas de frases de IA como las palabras de IA. Presta atención a:

  • cada encabezado de sección construido sobre la misma fórmula de dos tiempos ("Un binario. Elige cómo lo consigues.", "Recupéralo, ahora o entonces.");
  • "Sin X. Sin Y. Solo Z.";
  • tripletes de adjetivos;
  • un juego de palabras en cada encabezado.

  Una etiqueta simple ("Instalar", "Restaurar una instantánea") suele ser más fuerte que una línea ingeniosa, y le da al único titular que está elaborado espacio para destacar.

• Las etiquetas de los botones dicen lo que sucede: "Descargar la aplicación", "Reservar una mesa", "Reservar una reparación", no "Comenzar" o "Saber más".

• Nunca presentes hechos inventados como reales. Sin precios, direcciones, horarios, estadísticas, testimonios, logotipos de clientes inventados o "confiado por 10,000 equipos". Estos son los proyectos del propio usuario, y las afirmaciones fabricadas son un riesgo que tiende a enviarse por accidente. Cuando una sección realmente necesite un hecho que no tienes, pon un marcador visible, como <span class="todo">[precio]</span> estilizado para que destaque, y enumera cada uno en la entrega.

4. Construir

Tokens primero. Antes de cualquier componente, define el sistema como propiedades personalizadas de CSS al principio de styles.css: roles de color, pasos de tipo, pasos de espacio, radios, sombras, medida de texto y tiempos de movimiento. Genera las escalas de tipo y espacio fluidas con:

node <skill-dir>/scripts/scale.mjs --min-ratio 1.2 --max-ratio 1.333   # elige proporciones que se adapten a la dirección

Después de eso, usa tokens en lugar de números codificados. Los números codificados se desvían, y esa desviación es lo que hace que el espaciado se vea ligeramente mal en todas partes.

Los scripts necesitan Node 20 o más reciente. Si node no está en el PATH, ejecútalos con ~/.cache/killer-skills-node/node.exe en su lugar: el instalador de Windows coloca Node allí cuando falta.

Fuentes. Auto-alójalas desde el paquete de fuentes de killer-skills, que tiene cada cara que references/typography.md nombra:

node <skill-dir>/scripts/fonts.mjs list                       # familias, con sus pesos o ejes
node <skill-dir>/scripts/fonts.mjs add ruta/al/sitio "Newsreader" "IBM Plex Mono" --weights 400,600

add copia los archivos y sus licencias en assets/fonts/ y escribe assets/fonts/fonts.css. Enlaza esa hoja de estilo antes de styles.css, y precarga solo la cara de la que depende la primera pantalla (el script imprime la línea). No necesita red, y el sitio terminado no solicita nada de un host de fuentes. Si el paquete no está instalado o no tiene la cara, cárgala desde Google Fonts como describe references/typography.md.

Archivos. Para un sitio nuevo, a menos que el proyecto dicte lo contrario:

sitio/            (o donde el usuario o proyecto quiera)
  index.html
  styles.css
  DESIGN.md
  icon.svg, favicon.ico, apple-touch-icon.png, icon-192/512.png, icon-maskable-512.png, manifest.webmanifest
  assets/        (svg, imágenes, fonts/)
  script.js      (el momento impactante y pequeñas interacciones; mantenlo corto)

HTML. Usa puntos de referencia semánticos (header, nav, main, section con encabezados, footer), un h1 y encabezados en orden. Usa <button> para acciones y <a> para navegación, y dale a cada campo de formulario una <label>. Cada página necesita lang, la metaetiqueta viewport, un <title> real, una meta descripción, etiquetas Open Graph y un conjunto completo de favicon e iconos de aplicación.

CSS. CSS moderno y simple, móvil primero:

• grid y flex para diseño, con patrones intrínsecos como repeat(auto-fit, minmax(min(100%, 18rem), 1fr)).
• Tokens fluidos mediante clamp(), y una medida de lectura de alrededor de 60–70 caracteres.
• Estilos :focus-visible que se adapten al diseño. Los efectos de hover van dentro de @media (hover: hover).
• text-wrap: balance en encabezados y text-wrap: pretty en párrafos.
• @media (prefers-reduced-motion: reduce).

JavaScript. Úsalo donde mejore la experiencia: el momento impactante, efectos de puntero, un interruptor de tema que barra, una demo en vivo, un alternador de navegación móvil (un <button aria-expanded>, o <details>). Mantenlo vanilla y escrito a mano en los propios archivos del sitio: sin frameworks, sin CDNs, nada cargado desde otro lugar, y generalmente menos de cien líneas. Constrúyelo como una mejora. El contenido debe ser visible sin JS. Nunca ocultes secciones con opacity: 0 mientras esperas que un script las revele, porque cuando el script falla, el contenido desaparece. Prefiere CSS para cualquier cosa que CSS pueda hacer (entradas, efectos de escritura, escenas impulsadas por desplazamiento).

Movimiento. El movimiento en todas partes se mantiene rápido y silencioso: transiciones de hover y foco de 150–250 ms, entradas pequeñas. Esa calma es lo que permite que el momento impactante aterrice. Cada animación va dentro de @media (prefers-reduced-motion: no-preference) o detrás de una verificación matchMedia, y la versión de movimiento reducido es un diseño estático terminado. Las recetas y reglas de rendimiento están en references/motion-and-wow.md.

Favicon e iconos de aplicación. Diseña el favicon con tanta seriedad como el héroe: es la pieza más vista del diseño. A 16px una marca denominativa se convierte en una mancha, por lo que la mayoría de las marcas necesitan una versión reducida para tamaños pequeños, como una letra en negrita o una forma, en un mosaico que se lea tanto en pestañas claras como oscuras. Lee references/favicons.md. Luego construye el conjunto a partir de un SVG y verifícalo:

node <skill-dir>/scripts/icons.mjs build mark.svg --out ruta/al/sitio --bg "#hex" --name "Sitio" --theme-color "#hex"
node <skill-dir>/scripts/icons.mjs audit ruta/al/sitio     # hoja de vista previa: pestañas a 1x/2x, claro/oscuro, pantallas de inicio

Visuales sin fotos de stock:

• Software: construye la interfaz real del producto en HTML y CSS, como una sesión de terminal estilizada con comandos y salida reales, o una ventana de aplicación con datos realistas. Es más convincente que cualquier ilustración y se mantiene en la marca.
• Tipografía como imagen: titulares de gran tamaño, números, citas destacadas, un menú configurado como una tarjeta impresa.
• SVG y CSS: formas geométricas, diagramas, mapas, gráficos, patrones, textura de grano (un filtro SVG feTurbulence con baja opacidad), iconos simples en línea con un ancho de trazo consistente.
• Ten cuidado al dibujar cosas reales a mano. La comida, las personas, los animales, las plantas, los edificios y las herramientas son donde el SVG codificado a mano falla con mayor frecuencia. Las proporciones se desvían, y un detalle (una marca de puntuación en un pan, un resaltado, una mano) se lee como otra cosa y atrae la mirada por la razón equivocada. Una ilustración torpe daña una página más que no tener ninguna. Por lo tanto:
  • Prefiere los visuales que el código puede generar de forma fiable. Si necesitas una imagen de un lugar o un producto real y la página la necesita para cumplir su propósito (por ejemplo, "muestra el producto"), usa una foto real.

5. Revisar las capturas de pantalla y corregir

Después de construir, usa el script de Playwright empaquetado para tomar capturas de pantalla y motion capture en tres tamaños, luego carga el informe y corrige lo que está mal.

node <skill-dir>/scripts/screenshots.mjs ruta/al/sitio --url http://localhost:8080   # o --file index.html si no hay servidor

Lee la salida. Verifica:

• Diseño móvil: ¿todo es legible? ¿El momento impactante funciona? ¿Los objetivos táctiles tienen al menos 44px? ¿Desplazarse se siente bien?
• Diseño de tableta: ¿el texto es demasiado ancho? ¿Las tarjetas se rompen? ¿El menú de navegación es usable?
• Diseño de escritorio: ¿el momento impactante tiene espacio? ¿El espaciado se siente generoso o perdido? ¿Los enlaces y botones tienen hover?
• Movimiento: reproduce el video en cámara lenta. ¿El momento impactante es suave? ¿Las animaciones se superponen o titubean? ¿El bucle se siente bien?
• Modo oscuro (si es compatible): ¿los contrastes funcionan? ¿El favicon es legible?
• Carga de fuentes: ¿alguna parpadea? ¿El texto se ve correcto inmediatamente en el segundo fotograma?
• Fallos de JS: abre la consola. Cero errores.
• Rendimiento: ¿el momento impactante se renderiza a 60 fps? ¿El tiempo de carga se siente instantáneo para el texto?

Corrige los problemas. Luego vuelve a ejecutar las capturas de pantalla y mira de nuevo hasta que el sitio esté sólido en los tres tamaños.

6. Pulir y entregar

Verifica la lista de verificación final:

• lang y metaetiqueta viewport en <html>
• <title> real y meta descripción
• Etiquetas Open Graph (og:title, og:description, og:image, og:url)
• Conjunto completo de favicon e iconos de aplicación (más de 5 tamaños, manifest.webmanifest)
• :focus-visible y @media (hover: hover)
• @media (prefers-reduced-motion: reduce) con animaciones desactivadas
• Sin dependencias de red
• Sin errores de consola
• Código HTML/CSS/JS validado

Redacta la entrega en la respuesta al usuario o en un archivo HANDOFF.md. Enumera:

• Lo que construiste
• La dirección de diseño (concepto, tipo, color, momento impactante)
• Suposiciones que hiciste ("asumí que el producto se llama X")
• Alternativas consideradas (las otras dos direcciones, para que puedan redirigir si quieren algo diferente)
• Elementos de sección que necesitan contenido real ("el precio es [precio]")
• Próximos pasos sugeridos ("añadir página de precios", "conectar formulario a un backend")

Y entrega.

Rediseñando un sitio existente

Cuando un usuario dice "este sitio se ve anticuado", "rediseña X", "moderniza Y" o "haz que esto se vea mejor", añade un paso de inventario antes del paso 1:

Inventario. Toma capturas de pantalla del sitio existente en tres tamaños, lee su HTML y CSS, y enumera:

• Lo que funciona y debe conservarse (contenido, marca, activos)
• Lo que está roto o se siente desactualizado (diseño, tipografía, colores, movimiento)
• El flujo de la página: ¿qué hace un visitante, y el sitio actual lo apoya bien?
• Lo que falta (sin favicon o iconos, sin modo oscuro, sin etiquetas OG, sin meta descripción)
• Lo que es específico del proyecto y debe mantenerse (nombres de productos, comandos, números)

Luego procede con los pasos 1–6, pero usa el inventario como base para la dirección y el contenido. No reinventes la marca a menos que el usuario lo pida; mejora lo que hay.

Trabajando dentro de una marca existente

Cuando el proyecto ya tiene un sistema de marca (guía de marca, tokens de diseño, DESIGN.md, o un conjunto consistente de activos de marca terminados), la marca es la dirección. Aún diseñas un momento impactante y construyes el sitio, pero todas las elecciones de tipo, color y diseño provienen de la marca existente. Tu trabajo es:

• Usar la paleta de la marca, las fuentes y los principios de diseño de la guía.
• Extender los tokens de diseño donde falten (añadir pasos de espacio, radios, sombras) sin contradecir la marca.
• Diseñar un momento impactante que se sienta como si perteneciera a la marca.
• Escribir contenido en la voz de la marca.
• Entregar el sitio como una actualización que honra la marca.

Si la marca tiene una DESIGN.md, síguela y amplíala. Si tiene un BRAND.md, úsalo como la única fuente de verdad para tipo, color y personalidad. Si solo tiene un logotipo y unos pocos colores, infiere la dirección a partir de ellos y enumera tus suposiciones en la entrega.

Qué hace que un sitio parezca hecho por IA

Los sitios que parecen generados por IA (en lugar de diseñados) tienden a tener estas señales. Evítalas:

• Paletas de color de valores predeterminados: azul (#3B82F6) + gris (#6B7280) + blanco (#FFFFFF) + un acento (#10B981 o #F59E0B). Si tu paleta coincide con Tailwind por defecto, parece IA.
• Fuentes del sistema: Inter, Roboto, Open Sans, Lato, Montserrat, Poppins, o cualquier otra cara ampliamente usada. Las fuentes del sistema gritan "no se tomó ninguna decisión", y también lo hacen las pilas de fuentes estándar. Usa fuentes auto-alojadas de references/typography.md.
• Secciones en orden fijo: héroe → características → cómo funciona → testimonios → precio → CTA → pie de página. Eso es el diseño 'SaaS genérico'. Los visitantes lo han visto mil veces. Varía el orden, omite secciones, combina funciones en el héroe.
• Tamaños de fuente que siguen una escala matemática exactamente: h1 a 3rem, h2 a 2rem, p a 1rem, etc. La escala de tipo realista tiene saltos irregulares y sorpresas.
• Bordes redondeados y sombras en todas partes: tarjetas con radio 16px + sombra + relleno blanco es el diseño 'caja genérica'. No todo necesita ser una tarjeta.
• Demasiado espaciado: el espaciado generoso es bueno. El espaciado que no deja que nada se toque parece una plantilla de Figma recién abierta. Deja que algunos elementos se asienten cerca unos de otros.
• Iconos en círculos coloreados: cada característica tiene un icono en un círculo azul o verde. Es el patrón de características número uno hecho por IA. Usa iconos en línea, o iconos sin fondo, o ningún icono.
• Encabezados de sección con juegos de palabras: "Un mundo de posibilidades", "Donde los sueños se encuentran con el código", etc. Si suena a eslogan de una taza de café, reescríbelo como un titular simple.
• Sin personalidad: el sitio podría ser para un estudio de diseño, una empresa de contabilidad o una aplicación de música, y se vería igual. Eso es el fracaso número uno. Tu dirección de concepto está ahí para evitarlo exactamente.

Referencias

• references/typography.md — combinaciones de fuentes, reglas de escala, cómo auto-alojar
• references/color.md — método de paleta, roles de color, accesibilidad
• references/layout.md — composiciones de página, cuadrícula, diseños de sección
• references/motion-and-wow.md — recetas de movimiento, técnicas de momento impactante, rendimiento
• references/favicons.md — diseño de favicon, formatos, generación de sprites
• scripts/scale.mjs — generador de escala de tipo y espacio fluido
• scripts/fonts.mjs — gestor de paquetes de fuentes (lista, añadir)
• scripts/icons.mjs — constructor y auditor de favicon/icono de aplicación
• scripts/screenshots.mjs — script de Playwright para capturas de pantalla y video