Protonicwave/web-ui-craft

Web UI craft

La interfaz genérica no es un estilo. Es lo que llena cada decisión que nadie tomó: el modelo, la plantilla o el framework proporciona su respuesta más común, y el resultado podría pertenecer a cualquier producto. Los sitios de mejor apariencia (Linear, Vercel, Stripe, Family, los ganadores de Awwwards) dejan casi nada al azar. Calculan un sistema pequeño, se comprometen con una idea y mantienen los detalles funcionales en estándares medibles.

Así que el trabajo es tomar decisiones, escribirlas y rastrear cada una hasta el tema, el usuario o la física de la percepción. Sigue los cinco pasos a continuación en orden. Escálalos según la tarea: un solo botón obtiene una oración de brief y una crítica rápida; una landing page recibe el tratamiento completo.

1. Lee el tema

Antes de cualquier elección visual, establece:

• Tema: qué es realmente el producto, la organización o el contenido, y el mundo al que pertenece (su industria, materiales, vocabulario, artefactos).
• Audiencia: quién llega, qué sabe ya, en qué dispositivo probablemente está.
• Trabajo principal: la única cosa que la página o pantalla debe lograr. Todo lo demás está subordinado a ella.
• Restricciones existentes: activos de marca, un sistema de diseño existente, tokens, librería de componentes o framework en el repositorio. Si existen tokens, úsalos y aplica esta habilidad dentro de ellos. No impongas una nueva identidad a un producto establecido a menos que se te pida.

Si el usuario dio poca información, infiere a partir del tema y expresa tus suposiciones en el brief en lugar de hacer una lista de preguntas.

2. Escribe el brief de diseño

Escribe un brief compacto en tu respuesta antes de escribir código. Es el diseño, por lo que debe ser lo suficientemente específico como para que alguien más pueda construir lo mismo a partir de él.

Dirección:    una estética nombrada y por qué encaja con este tema (una o dos líneas)
Firma:        la única idea por la que se recuerda esta página, la pieza estrella que la sostiene, y cómo
              se hará esa pieza (activos proporcionados, una imagen generada, o construida en código)
Paleta:       neutro (teñido hacia ...), un acento (rol), colores semánticos; valores OKLCH
Tipografía:   familia y rol para cada una (display, texto, mono si es necesario) y qué comparte cada una con
              el tema; cómo actúa la tipografía display en la composición; ratio de escala; tamaño del cuerpo
Layout:       dos o tres opciones para la primera pantalla, cada una un concepto de una línea y un wireframe
              ASCII; la elegida y por qué; rejilla, medida, densidad, ritmo de sección
Profundidad:  cómo se separan las superficies (pasos de tono, líneas finas, sombras), de dónde viene la luz
              y sobre qué cae
Movimiento:   el nivel (producto o marca), el momento de firma y su elemento principal, qué
              más se mueve y por cuánto tiempo, y qué deliberadamente no se mueve
Imaginario:   fotografía, ilustración, 3D, interfaz de producto o solo tipografía; dirección de arte en una línea
Copia:        el titular y la acción principal, escritos para esta audiencia; el nombre de la acción,
              mantenido desde el botón hasta la confirmación
Presupuesto:  script comprimido para toda la página y la parte que la capa de espectáculo puede tomar
              (365 KiB en total por defecto; 75 KiB para una página sin espectáculo)

Reglas para el brief:

• Deriva, no decores. Cada línea responde "¿por qué esto, para este tema?". Una paleta tomada de los materiales del producto, una tipografía de su lenguaje vernáculo, un héroe que abre con lo más característico de su mundo.
• Una firma, todo lo demás en calma. Stripe tiene su onda de gradiente, Apple sus tomas de producto desplazadas con scroll, Family sus bandejas voladoras. Gasta audacia una vez. La contención a su alrededor es lo que la hace legible.
• La contención es una dirección válida. Un sistema tranquilo, liderado por tipografía, monocromático con un acento, es tan deliberado como un héroe de WebGL, y generalmente la elección correcta para herramientas y documentación.
• Tranquilo no es vacío. La contención limita cuántas ideas tiene una página, no cuán rica es cada una. La firma debe recompensar una mirada larga: una ilustración dibujada para este tema, datos reales expuestos con cuidado, textura, tipografía a escala de display real. Los temas de comida, cultura, consumo y marca generalmente necesitan imágenes o ilustraciones para transmitir calidez, por lo que una página solo con tipografía para uno de ellos necesita una razón declarada.
• La pieza estrella es donde va el esfuerzo. Los sitios aclamados rompen muchas reglas y aún así se ven caros porque una pieza está hecha con un estándar muy alto: una pantalla de producto con datos creíbles, un objeto iluminado, una ilustración original. Elígela y constrúyela con references/artefacts.md. Una caja redondeada con barras grises no es una toma de producto.
• La tipografía es parte de la composición, no un soporte para ella. A tamaño de display, el ajuste es el diseño: escala contra el texto más pequeño de la página, peso, ancho, caja, dónde se rompen las líneas, contra qué se sienta el titular. El titular de 64 px de Linear sobre texto de interfaz de 12 px es una gran parte de su efecto.
• Compara layouts antes de elegir uno. Esboza dos o tres primeras pantallas genuinamente diferentes (no un layout con la imagen movida) y elige según el trabajo principal del tema. El primer layout que viene a la mente suele ser la plantilla.
• Afirmación, prueba, acción. La mayoría de las páginas necesitan una declaración clara, una evidencia real (vista del producto, número en vivo, cliente, demo) y una acción principal. La estructura sigue al contenido, no a una plantilla.
• Un nombre por acción. El botón que dice "Publicar" produce una confirmación que dice "Publicado", no "Guardado". El vocabulario de la interfaz es cómo las personas se orientan en ella.

Lee references/exemplars.md al elegir una dirección o firma, references/visual-system.md al establecer la paleta, tipografía, layout y profundidad, y la sección de movimiento de references/interaction.md al escribir la línea de Movimiento.

3. Desafía el brief

Antes de construir, atácalo:

• Prueba de intercambio. ¿Podría el nombre de un competidor reemplazar este sin que nadie lo note? Si es así, el brief aún no ha tomado sus decisiones.
• Prueba por elección. Para cada línea, pregúntate si podría pertenecer a cualquier producto. Si es así, debe ser un valor predeterminado deliberado y bien ajustado de la hoja de construcción a continuación, o debe cambiar.
• Prueba de convergencia. Esboza en unas pocas líneas el brief que escribirías para un tema vecino: otra herramienta en la misma categoría, otro creador en el mismo oficio. Cada línea que resulta igual es un valor predeterminado, no una decisión. Cámbiala y di en el brief qué cambió y por qué. Una línea puede quedarse solo cuando se sigue de un hecho que ambos temas comparten (ambos productos son hardware, ambas audiencias leen código); nombra el hecho.
• Verificación de tics. Compara contra references/slop-tells.md, incluidos los grupos de apariencia completa. No cambies un valor predeterminado por el siguiente más común (Inter por Space Grotesk, púrpura por verde azulado). Reemplázalo con una elección que tenga una razón.

Revisa el brief, luego construye.

4. Construye

• Tokens primero. Escribe la paleta, escala tipográfica, espaciado, radios, sombras y movimiento como propiedades personalizadas de CSS (o el sistema de tokens del proyecto) antes de cualquier componente. Los componentes usan solo nombres de tokens, nunca valores crudos como bg-indigo-500 o #6366f1.
• Estructura segundo. HTML semántico, enlaces reales para navegación, encabezados en orden, luego estilo.
• Aplica la hoja de construcción a continuación y los detalles en references/visual-system.md y references/interaction.md.
• Diseña cada estado. Hover, activo, focus-visible, deshabilitado, cargando, vacío, error, éxito, contenido largo y contenido corto. La UI generada es más débil aquí, y las correcciones son más baratas aquí.
• Mantén el espectáculo barato y opcional. Los efectos pesados (WebGL, video, desenfoque grande) viven en una capa aislada dentro del presupuesto del brief, comienzan después del primer pintado, tienen un respaldo estático y se sitúan detrás de prefers-reduced-motion: no-preference.

5. Critica y recorta

Trata la primera construcción como un borrador.

1. Ejecuta el verificador estático, usando el propio directorio de la habilidad para la ruta del script. Necesita Python 3.12 o posterior y ningún paquete. Apúntalo a toda la fuente del front-end, no solo a los archivos que cambiaste: las reglas de focus y reduced-motion buscan un estilo global en cualquier lugar del escaneo, por lo que un escaneo parcial reporta defectos falsos.

   python <skill-dir>/scripts/check_slop.py <carpeta-de-fuente-del-front-end>
   

   Arregla cada defect (el código de salida 1 significa que al menos uno permanece). Para cada tell, cámbialo o di en tu informe por qué se queda. El verificador solo lee texto fuente, por lo que un resultado limpio es necesario, no suficiente.

2. Renderiza la página y mírala a 1440 px y 375 px de ancho, en ambos esquemas de color si tiene dos. Usa una herramienta de navegador si la sesión tiene una. De lo contrario, la mayoría de las máquinas tienen Chrome o Edge sin cabeza; escribe capturas de pantalla y el perfil del navegador en una carpeta temporal, luego lee las imágenes:

   chrome --headless=new --hide-scrollbars --user-data-dir=<temp>/profile --window-size=1440,2600 --virtual-time-budget=4000 --screenshot=<temp>/desktop.png <archivo o URL HTTP>
   

   La captura de pantalla es una ventana gráfica del tamaño dado, no la página completa, así que haz la ventana lo suficientemente alta para contener el contenido que necesitas ver. Chrome sin cabeza no hará una ventana más estrecha que aproximadamente 500 px, por lo que una captura de 390 px se recorta silenciosamente de un layout más ancho. Una pieza que se reproduce a sí misma se captura en un punto aleatorio de su bucle: añade --force-prefers-reduced-motion para el fotograma terminado, y toma una captura más sin él para ver un fotograma a mitad del bucle. Para la verificación en teléfono, captura una pequeña página contenedora que sostenga el sitio en un <iframe> de 375 px de ancho. Los elementos revelados al hacer scroll pueden no aparecer en las capturas sin cabeza; verifica en la fuente que su estado inicial oculto se aplica mediante script (ver references/interaction.md). Con una herramienta de navegador real, también tabula a través de cada flujo.

3. Mide la página en lugar de estimarla. Sírvela a través de HTTP (para una carpeta estática, python -m http.server en esa carpeta), ejecuta Lighthouse en su perfil móvil predeterminado, luego lee el informe con el lector de presupuesto:

   npx [email protected] <URL HTTP> --output=json --output-path=<temp>/report.json --quiet --chrome-flags="--headless=new --user-data-dir=<temp>/lh-profile"
   python <skill-dir>/scripts/check_budgets.py <temp>/report.json --script-kib <el presupuesto del brief>
   

   Verifica LCP (2,5 s), CLS (0,1), tiempo total de bloqueo (200 ms, el sustituto de laboratorio para INP), peso del script contra el brief, y enumera cada animación no compuesta por elemento. Arregla cada breach (código de salida 1). El código de salida 2 significa que una cifra está sin medir o el informe no es utilizable: vuelve a ejecutar, y si aún falla, reporta la cifra como no medida, nunca como aprobada. http.server no comprime, por lo que el peso del script se lee alto, lo que es seguro. Establece CHROME_PATH si Lighthouse no puede encontrar Chrome. Si Node o la red no están disponibles, dímelo en el informe. Lighthouse no mide la velocidad de fotogramas del momento de firma: graba un rastro de rendimiento con una herramienta de navegador si la sesión tiene una, y de lo contrario di que no se ha medido.

4. Pregúntate si la primera pantalla le da al ojo algo que valga la pena mirar, y ejecuta la lista de verificación de fidelidad en references/artefacts.md en la pieza estrella. Una página que es correcta pero olvidable tiene una firma tímida: fortalece la firma en lugar de añadir más elementos.

5. Compara la página contra una referencia. Elige un sitio aclamado en la dirección elegida, uno que un diseñador en el campo del tema admiraría (references/exemplars.md nombra algunos), captura su primera pantalla a 1440 px con el comando en el punto 2, y mira las dos imágenes una al lado de la otra. Compara la fidelidad de la pieza estrella, el espacio entre el tipo más grande y el detalle más pequeño, cuánto detalle creíble hay, y la luz. Nombra la brecha más grande y ciérrala, o di en el informe por qué se queda. La referencia establece el estándar para la artesanía, no la apariencia: no tomes nada de su superficie. Si no se puede acceder al sitio, dímelo en el informe.

6. Recorre la lista de verificación en references/interaction.md (estados, foco, objetivos, formularios, rendimiento).

7. Vuelve a ejecutar la verificación de tics en references/slop-tells.md contra la página construida, no contra el brief. Cubre tics estructurales que el verificador no puede ver, como el héroe de insignia centrada, las tres tarjetas idénticas y los grupos de apariencia completa.

8. Elimina cualquier cosa que no sirva al tema o al usuario: divisores decorativos, etiquetas encima de contenido autoexplicativo, insignias, brillos, iconos que repiten su texto, un segundo color de acento. Eliminar suele ser la mejora más grande disponible.

9. Reporta el brief, lo que la crítica cambió, la brecha más grande contra la referencia, las cifras medidas contra sus presupuestos, y cualquier cosa que no pudiste verificar (por ejemplo, contraste renderizado sin un navegador).

Hoja de construcción

Valores iniciales bien fundamentados. Protegen las buenas decisiones; no reemplazan las decisiones de identidad en el brief.

Dimensión	Valor predeterminado
Texto del cuerpo	16 a 20 px, altura de línea aproximadamente 1.5, medida de 45 a 90 caracteres (apunta a aproximadamente 65)
Encabezados	Altura de línea 1.0 a 1.2, tracking aproximadamente -0.02em desde 24 px hacia arriba, text-wrap: balance
Párrafos	text-wrap: pretty; negrita y cursiva nunca juntas
Escala tipográfica	Fluida mediante clamp(), ratio aproximadamente 1.2 en pantallas pequeñas a 1.25 en grandes
Mayúsculas	Raras, en una línea, interletraje 0.05em a 0.12em
Color	OKLCH; una escala neutra teñida, un acento, tres o cuatro colores semánticos, cada uno con pasos basados en roles
Contraste	WCAG 4.5:1 cuerpo, 3:1 texto grande y partes de UI; apunta a APCA Lc 75 o más en texto del cuerpo
Modo oscuro	Una paleta separada: base gris oscura (aproximadamente oklch(0.18 0.01 h)), superficies más claras para elevación, acento desaturado
Gradientes	Interpolar in oklch; matices adyacentes; grano fino opcional; como máximo un gradiente deliberado
Espaciado	Base de 4 px: 4, 8, 12, 16, 24, 32, 48, 64, 96, 128; el espacio entre grupos al menos el doble del espacio dentro
Profundidad	Pasos de tono y bordes finos primero; sombras en capas, una fuente de luz, teñidas con el matiz de la superficie
Radios	Dos o tres valores; radio anidado = radio exterior menos padding
Iconos	Una familia, una cuadrícula, un ancho de trazo, un tamaño; una semántica de color (sin colores arbitrarios); icono decorativo si la etiqueta está presente, icono informativo si no hay etiqueta
Diálogo de navegación	Siempre un enlace o botón <button> HTML real; pantalla ancha: mostrar un enlace por elemento de primer nivel, menú desplegable para los hijos; pantalla estrecha: panel de cajón; nunca superposición a pantalla completa
Motivos de carga	Esqueleto que esboza el contenido real, con transición a la página; nunca un spinner
Estados vacíos	Una ilustración o un mensaje que le dice al usuario qué hacer a continuación, no "No hay resultados"
Formularios	Etiqueta visible en todo momento (no solo marcador de posición); el botón de envío deshabilitado solo después de un envío exitoso
Animación	prefers-reduced-motion respetado: sin desplazamiento de paralaje, sin animación de carga que dure más de 1.5 s, sin degradados animados en fondos
Rendimiento	content-visibility: auto en secciones fuera de pantalla; imágenes con dimensiones y lazy loading a menos que estén en la primera pantalla
Clics	Objetivos de al menos 44 x 44 px; elementos interactivos distinguibles sin hover
Teclado	Orden de tabulación visible y lógico; sin trampa de teclado; role y aria-* solo cuando el HTML nativo es insuficiente
Fuentes	Se entregan como woff2; se cargan con font-display: swap con un tiempo de espera; las fuentes variables se subconjuntan a los pesos utilizados
Script de terceros	Cargado con async o defer e iniciado después del primer pintado; el brief justifica su necesidad en lugar de su conveniencia

Referencias

• references/exemplars.md — sitios aclamados organizados por dirección de diseño, con notas sobre qué hace que cada uno funcione
• references/visual-system.md — pautas detalladas para paleta de color, tipografía, espaciado, profundidad y rejilla
• references/interaction.md — movimiento, estados, foco, formularios, verificación de rendimiento
• references/artefacts.md — construcción de la pieza estrella: tomas de producto, ilustraciones, datos, imágenes
• references/slop-tells.md — tics de IA a evitar

Cada una de esas referencias es una especificación independiente. La habilidad las llama cuando son relevantes.