Communitygithub.com

constructor-web-promptory

Muestra a un agente cómo dirigir artísticamente y construir el "constructor web promptory" para que el resultado concreto sea un video terminado. El procedimiento avanza a través del Constructor Web Promptory, la Regla de oro: no rediseñar, el Cuestionario de admisión: PRIMER paso en cada nueva solicitud de sitio web. Úsalo cuando una nueva tarea requiera esta técnica.

¿Qué es constructor-web-promptory?

Esta habilidad proporciona un flujo de trabajo estructurado y detallado para que un agente de IA (como Claude Code, Cursor o Codex) construya sitios web dinámicos y con animaciones fluidas, orientado a producir un "video terminado" como resultado conceptual. Combina tres herramientas principales: Lenis para el desplazamiento suave, GSAP (con ScrollTrigger) para animaciones personalizadas y React Bits para componentes animados preconstruidos. El proceso comienza con un cuestionario de admisión (capturado en `references/intake-questionnaire.md`) para definir el proyecto, y establece reglas claras como la "Regla de oro" (no rediseñar sin permiso) y un barra de calidad para evitar resultados genéricos. La habilidad también incluye guías para la dirección de diseño visual, referencias de movimiento, y una integración precisa de Lenis y GSAP para evitar problemas de rendimiento. Es ideal para agentes que necesitan crear sitios web interactivos y visualmente atractivos con un enfoque en la ejecución precisa y la fidelidad al diseño solicitado.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/moramadan91/promptory-web-builder/tree/HEAD

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Construcción web con Promptory

Tres herramientas, un stack, cada una con un trabajo:

HerramientaFunciónRegla general
LenisMotor de desplazamiento: desplazamiento suave e inercial sobre el desplazamiento nativoInstalado una vez, de forma global. Nunca por sección.
GSAP (+ ScrollTrigger)Motor de animación: líneas de tiempo personalizadas, animación impulsada por desplazamiento, fijaciónCualquier cosa personalizada para el diseño de este sitio.
React BitsComponentes animados listos para usar (texto, fondos, cursores, tarjetas, botones)Recurre primero cuando un componente del catálogo ya haga el efecto.

Comparten un bucle de animación: el ticker de GSAP impulsa Lenis, y ScrollTrigger lee el desplazamiento de Lenis. Conseguir ese cableado es lo más importante en esta habilidad (§3).

Alcance: solo web/DOM en tiempo real. Para renderizado de video (Remotion, reels), esta habilidad no aplica.

0. Regla de oro: no rediseñar

Implementa el diseño y los efectos que el usuario solicitó. No cambies el diseño, colores, fuentes, espaciado o texto por tu cuenta, y no agregues secciones adicionales ni efectos "extra" que nadie pidió. Si un efecto o corrección claramente mejoraría algo, sugiérelo en una línea y espera una confirmación. El movimiento y las comprobaciones de calidad deben servir al diseño existente, no reemplazarlo.

0.5 Cuestionario de admisión: PRIMER paso en cada nueva solicitud de sitio web

Antes de escribir cualquier código para un sitio nuevo, ejecuta el cuestionario de admisión en references/intake-questionnaire.md:

  1. Lee la solicitud y omite cualquier cosa ya respondida.
  2. Haz las preguntas restantes en un máximo de 3 rondas cortas (proyecto → movimiento → entrega). Usa la herramienta AskUserQuestion de Claude Code cuando esté disponible (opciones cliqueables + casilla automática de "Otro"); de lo contrario, imprime cada ronda como un bloque de código con opciones con letras y una línea "✎ Otro" vacía en cada pregunta.
  3. Muestra el Resumen del Proyecto en un bloque de código y espera la autorización.
  4. Luego construye, siguiendo las respuestas exactamente.

Si el usuario dice "ابدأ على طول" / "omitir", usa los valores predeterminados ⭐ y menciónalos en el Resumen. Para ediciones pequeñas de un sitio existente, omite el cuestionario a menos que la solicitud sea ambigua.

El resumen debe registrar: idioma y dirección (árabe/RTL, inglés/LTR o ambos), el objetivo de accesibilidad (por defecto WCAG 2.2 AA), los formularios y su backend, y la herramienta de análisis si la hay.

0.6 Referencias visuales — Prompt Motion

https://prompt-motion.com/ es la biblioteca visual para dirección de movimiento (tipografía cinética, UI de producto, partículas, formas, gráficos..., cada uno con el prompt detrás). Úsala solo cuando el usuario pida inspiración, seleccione "necesita una propuesta" / "movimiento audaz" en el cuestionario, o comparta un enlace de ella. Toma prestada la idea de movimiento, reconstrúyela con GSAP / Lenis / React Bits y mantén el diseño del cliente. Flujo de trabajo, mapa de categoría a componente y la plantilla de especificación de movimiento: references/visual-references.md.

0.7 Barra de calidad: verificar antes de mostrar cualquier cosa

Revisa la construcción en busca de indicios de resultados genéricos (acento índigo predeterminado, iconos emoji, métricas inventadas, lorem ipsum, secciones de plantilla estándar). Corrige lo que esté en tu propio código; sugiere una corrección de una línea para cualquier cosa que esté en el diseño del cliente. Lista completa: references/quality-bar.md.

0.8 Dirección de diseño: cada sitio se ve diferente

Cuando el cliente no tenga un diseño propio, elige una dirección antes de escribir código. Lee references/design-styles.md y:

  1. Preselecciona tres direcciones de la Guía de ajuste para la industria y la audiencia del resumen.
  2. Omite cualquier dirección utilizada en los últimos tres sitios en este chat o proyecto (Registro de estilos).
  3. Escribe una línea en el Resumen del Proyecto: Dirección: <nombre> — <por qué>, con una alternativa.
  4. Construye con las elecciones distintivas de esa dirección y luego ejecuta la verificación de Variedad: al menos cuatro de seis ejes deben diferir del sitio anterior.

Las direcciones son referencias para la estructura y la sensación. Nunca copies la marca, fotos, texto o diseño exacto de una referencia. Si el cliente proporciona un diseño, síguelo y omite este paso (§0 regla de oro).

0.9 Diseño visual distintivo (cuando el resumen lo deja abierto)

Fuente: anthropics/skills, habilidad frontend-design (Apache-2.0, consulte su LICENSE.txt). Aplica solo cuando el resumen deja abierta la dirección visual. §0 prevalece: sigue el diseño del cliente y las propias palabras del resumen, incluso cuando el resumen solicite uno de los aspectos que se enumeran a continuación.

  • Identifica el tema primero: producto, audiencia, trabajo principal. Si el resumen no lo dice, propón uno y confírmalo. La industria y los materiales son de donde provienen las elecciones distintivas.
  • La apertura del héroe comienza con lo más característico del mundo del tema (titular, imagen, demostración en vivo o interacción). Evita el valor predeterminado de un número grande, una etiqueta pequeña y un acento degradado a menos que sea claramente la mejor opción.
  • Tipografía: una familia, o dos que sean claramente distintas. Establece una escala tipográfica clara. En los titulares, el tratamiento tipográfico es parte del diseño.
  • Longitud de línea inferior a 80 caracteres. El texto del cuerpo con serifa necesita un interlineado ligeramente mayor que el sans-serif.
  • Evita los indicios tipográficos: una palabra en cursiva o de color en un titular, etiquetas en mayúsculas sostenidas y etiquetas sobre los encabezados que no añadan nada.
  • Marcadores numerados (01 / 02 / 03) solo cuando el contenido sea realmente una secuencia.
  • Movimiento: un momento orquestado (carga de página o una revelación). Sin desvanecimiento y desplazamiento en cada sección, sin transición hover en cada tarjeta. El movimiento que responde a una acción del usuario (abrir, expandir, confirmar) está bien.
  • Planifica antes de codificar: de 4 a 6 colores hexadecimales con nombre, roles tipográficos, un concepto de diseño (se permite wireframe ASCII) y principios. Revisa el plan contra el resumen. Si una parte se lee como el valor predeterminado genérico para cualquier página similar, revísala y di qué cambió.
  • Aspectos predeterminados a evitar a menos que el resumen los solicite: fondo crema con acento terracota; casi negro con acento verde ácido o bermellón; periódico con reglas finas y radio cero; tarjetas SaaS redondeadas idénticas con un radio y una sombra gris; ceja EN MAYÚSCULAS SOSTENIDAS sobre cada encabezado; cadenas meta con punto medio ('A · B · C'); etiquetas 'PALABRA — fragmento'; #0B0B0B o #111 en lugar de negro; monoespaciado para etiquetas pequeñas; '→' en cada enlace.
  • Gasta la audacia en un solo lugar. Mantén todo lo demás a su alrededor tranquilo. Elimina la decoración que no sirva al resumen.
  • Piso de calidad: responsive a móvil, enfoque visible, movimiento reducido respetado, contraste accesible.
  • Vigila la especificidad de los selectores CSS, especialmente el padding y el margen entre secciones, donde las reglas se anulan entre sí.
  • Texto: palabras llanas para el usuario final, voz activa, mayúscula inicial. Mantén un verbo a lo largo de un flujo ("Publicar" lleva a "Publicado"). Los errores dicen qué sucedió y cómo solucionarlo, sin disculpas. Los estados vacíos invitan a la siguiente acción.

1. Flujo de decisión: qué herramienta para qué solicitud

  1. ** Sitio árabe, bilingüe o RTL** → lee references/rtl-arabic.md antes de escribir cualquier diseño. La dirección es estructural; adaptarla después es costoso.
  2. Desplazamiento suave en cualquier parte del sitio → Lenis (proveedor global, §3). Hazlo una vez en la configuración del proyecto cuando exista cualquier animación de desplazamiento.
  3. ¿Hay un componente de React Bits que ya haga el efecto? → consulta references/react-bits-catalog.md → instálalo (§4). Aciertos típicos: texto dividido/borroso/revuelto, texto con revelación de desplazamiento, fondos animados (aurora, partículas, rejillas, sombreados), cursores personalizados, tarjetas imán/inclinadas, marquesinas, galerías, dock/menús, botones/contadores animados.
  4. El efecto es específico de este diseño (secuencia de introducción del héroe, sección narrativa fijada, sección de desplazamiento horizontal, revelaciones sincronizadas de múltiples elementos) → línea de tiempo de GSAP / ScrollTrigger (§5, detalle completo en references/gsap.md).
  5. El proyecto NO es React (HTML simple/vanilla) → React Bits no está disponible; usa solo Lenis + GSAP (assets/vanilla-setup.js).
  6. Cualquier formulario, lista, reserva o sección basada en datos → references/forms-and-states.md (etiquetas, errores, cinco estados).
  7. Elegir un servicio de terceros (fuentes, backend de formularios, análisis, hosting, imágenes) → references/free-services.md, luego verifica los límites actuales.
  8. Sitio nuevo sin diseño del cliente → elige una dirección primero (§0.8, references/design-styles.md).

2. Instalación

npm install gsap @gsap/react lenis
  • @gsap/react → solo para proyectos React (proporciona useGSAP).
  • lenis/react y lenis/snap vienen incluidos dentro de lenis — sin paquetes adicionales.
  • Todos los plugins de GSAP (ScrollTrigger, SplitText, Flip, ScrollSmoother, Draggable…) vienen incluidos dentro de gsap.
  • Los componentes de React Bits se añaden individualmente a través de CLI (§4); algunos traen sus propias dependencias (motion, three, ogl, matter-js…) — el CLI los instala, pero verifica la columna de Dependencias en el catálogo antes de elegir, para evitar inflar el bundle.

Nunca uses ScrollSmoother de GSAP junto con Lenis: son dos motores de desplazamiento suave que compiten. Lenis es el motor de desplazamiento en este stack.

3. Cableado de Lenis + GSAP + ScrollTrigger (hazlo exactamente así)

React / Next.js

Copia assets/SmoothScroll.jsx en el proyecto (por ejemplo, components/SmoothScroll.jsx) y envuelve la aplicación una vez:

// app/layout.jsx (Next.js App Router)
import SmoothScroll from '@/components/SmoothScroll';
import ScrollToTopOnRoute from '@/components/ScrollToTopOnRoute';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        <SmoothScroll>
          <ScrollToTopOnRoute />
          {children}
        </SmoothScroll>
      </body>
    </html>
  );
}

Para árabe, establece lang y dir desde la configuración regional en <html> (consulta references/rtl-arabic.md §1).

Para Vite/React, envuelve <App /> en main.jsx de la misma manera y omite ScrollToTopOnRoute (usa next/navigation).

Lo que hace el proveedor — y por qué cada línea importa:

  • <ReactLenis root options={{ autoRaf: false }}> → una instancia global en <html>; autoRaf: false porque GSAP lo impulsará.
  • lenis.on('scroll', ScrollTrigger.update) → ScrollTrigger se recalcula en cada frame de desplazamiento suave. Si falta esto = las animaciones se activan tarde/en posiciones incorrectas.
  • gsap.ticker.add(t => lenis.raf(t * 1000)) → un bucle compartido (el tiempo de GSAP está en segundos, Lenis quiere ms).
  • gsap.ticker.lagSmoothing(0) → sin tartamudeo al ponerse al día después de un cambio de pestaña.
  • ScrollTrigger.refresh() después de las fuentes y la carga → las posiciones del disparador coinciden con el diseño final.

Vanilla HTML/JS

Usa assets/vanilla-setup.js como módulo de entrada, importa lenis desde allí donde sea necesario.

4. React Bits: seleccionar e instalar componentes

  1. Encuentra el componente en references/react-bits-catalog.md (agrupados: Animaciones de texto, Animaciones, Componentes, Micro, Fondos — nombre, qué hace, dependencias).
  2. Elige la variante que coincida con el proyecto: JS o TS, luego CSS o TW (Tailwind).
  3. Instala:
    npx shadcn@latest add @react-bits/SplitText-TS-TW
    
    Para la abreviatura @react-bits/, el components.json del proyecto debe contener:
    { "registries": { "@react-bits": "https://reactbits.dev/r/{name}.json" } }
    
    ¿No hay components.json / no es un proyecto shadcn? Usa la URL directa en su lugar:
    npx shadcn@latest add https://reactbits.dev/r/SplitText-TS-TW.json
    # o
    npx jsrepo@latest add https://reactbits.dev/r/SplitText-TS-TW
    
  4. Abre el archivo instalado y lee sus propiedades antes de usarlo — cada componente es configurable (colores, velocidad, retardo, easing, disparadores). Establece las propiedades para que coincidan con los tokens de diseño existentes del sitio (colores, fuentes) en lugar de dejar los valores predeterminados de demostración.
  5. Si el usuario quiere el flujo de trabajo del agente: npx shadcn@latest mcp init --client claude conecta Claude Code al registro a través de MCP.

Notas de integración:

  • Los componentes de React Bits que se animan al desplazarse (ScrollReveal, ScrollFloat, AnimatedContent, SplitText…) usan GSAP ScrollTrigger o IntersectionObserver internamente → funcionan con Lenis automáticamente siempre que §3 esté en su lugar.
  • Los componentes son componentes cliente ('use client'). En Next.js, renderízalos dentro de componentes cliente o páginas que lo permitan.
  • Los fondos WebGL/shader (dependencias three, ogl, vgpu) son pesados: máximo uno o dos por página, carga diferida para los que están debajo del pliegue (next/dynamic con ssr: false o React.lazy), y dales un contenedor de tamaño fijo. Ponlos en pausa cuando estén fuera de la pantalla o cuando la pestaña esté oculta.
  • No apiles dos efectos de cursor o dos fondos en la misma ventana gráfica.
  • Verifica cada componente para ver si tiene un control de pausa si se repite durante más de 5 segundos (consulta references/accessibility-motion.md §5).
  • Licencia: React Bits es MIT + Commons Clause — libre de usar dentro de cualquier sitio web de cliente (incluido trabajo de cliente remunerado), pero los componentes en sí mismos no deben revenderse ni redistribuirse como paquete/plantilla. Nunca pegues el código fuente de React Bits en esta habilidad o en una biblioteca compartida; instala siempre desde el registro.

5. Esenciales de GSAP (animación personalizada)

Siempre en React a través de useGSAP con un scope — nunca useEffect sin procesar:

'use client';
import { useRef } from 'react';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import { useGSAP } from '@gsap/react';
gsap.registerPlugin(ScrollTrigger, useGSAP);

export default function Story() {
  const root = useRef(null);
  useGSAP(() => {
    const tl = gsap.timeline({
      scrollTrigger: { trigger: root.current, start: 'top top', end: '+=150%', scrub: 1, pin: true },
    });
    tl.from('.line', { yPercent: 100, autoAlpha: 0, stagger: 0.15 })
      .to('.image', { scale: 1.15 }, '<');
  }, { scope: root });
  return <section ref={root}>…</section>;
}

Patrones principales (detalles + matchMedia responsive, agrupación, FOUC, lista de verificación en references/gsap.md):

  • Líneas de tiempo para cualquier cosa con >1 elemento; ScrollTrigger.batch() para tarjetas repetidas.
  • scrub para movimiento vinculado al desplazamiento (con Lenis, scrub: true ya es suave; scrub: 1 agrega retardo adicional).
  • pin: true funciona con Lenis en desplazamiento nativo — no se necesitan trucos de pinType cuando Lenis usa root.
  • Sección de desplazamiento horizontal: fija el contenedor, anima la x de la pista a -(track.scrollWidth - innerWidth), scrub: true, invalidateOnRefresh: true. En RTL, invierte la dirección (consulta references/rtl-arabic.md §6).
  • Envuelve los bloques decorativos en gsap.matchMedia() para que los usuarios con movimiento reducido obtengan el sustituto (references/accessibility-motion.md §4).
  • FOUC (Flash de contenido sin estilo) → gsap.set(target, { autoAlpha: 0 }) en matchMedia condicional no iniciado, from() o fromTo() establecen estado inicial, o opacity: 0 en CSS y opacity: 1 en la línea de tiempo.
  • Easing: Power2.out para la mayoría de las UI. Expo.out para movimiento enfático; power4.inOut para desplazamiento horizontal. none para sincronización manual con desplazamiento.
  • Verifica la superposición z-index del contenido fijado (el contexto de apilamiento a menudo rompe la fijación de ScrollTrigger).

6. Diseño adaptable (responsive)

No hay estilos de diseño de cuadrícula personalizados en esta habilidad. references/responsive.md contiene:

  • Colapso de columnas, orden de contenido, navegación móvil y fuentes fluidas.
  • Puntos de interrupción estándar: 480, 768, 1024, 1280.
  • matchMedia de GSAP para animaciones: evita líneas de tiempo de escritorio en móvil.

7. Accesibilidad y movimiento

Resumido de references/accessibility-motion.md:

  • Soporte de prefers-reduced-motion (configuración de sistema operativo/navegador) — consulta la lista de verificación §2.
  • Foco de teclado visible (no outline: none sin reemplazo).
  • Relación de contraste de color (AA es el objetivo).
  • Animaciones inducidas por desplazamiento = no automáticas, por lo que generalmente no rompen la accesibilidad, pero aún así: verifica que las transiciones no eliminen contenido clave (por ejemplo, superposiciones de texto de héroe que se desvanecen antes de que se pueda leer).
  • Estados de carga, vacío, error y borde del teclado (references/forms-and-states.md).

8. Manejo de imágenes

Las reglas de imágenes están en references/images.md (formatos, carga diferida, relación de aspecto, marcadores de posición de desenfoque).

9. Gestión del estado de la aplicación y efectos secundarios (App Router de Next.js)

references/nextjs-app-router.md define cómo manejar el estado de la aplicación, los efectos secundarios y la obtención de datos en el App Router de Next.js.

10. Referencias de la biblioteca

  • references/react-bits-catalog.md — todos los componentes de React Bits.
  • references/rtl-arabic.md — configuración para árabe, bilingüe y RTL.
  • references/gsap.md — patrones detallados de GSAP y solución de problemas.
  • references/forms-and-states.md — formularios, etiquetas, estados, validación.
  • references/free-services.md — servicios gratuitos para fuentes, formularios, etc.
  • references/quality-bar.md — comprobaciones de calidad de salida.
  • references/visual-references.md — referencias visuales de Prompt Motion.
  • references/design-styles.md — direcciones de diseño visual.
  • references/responsive.md — cuadrícula adaptable, puntos de interrupción.
  • references/accessibility-motion.md — movimiento reducido, foco, contraste.
  • references/images.md — optimización y carga de imágenes.
  • references/nextjs-app-router.md — obtención de datos y estado en Next.js.

11. Archivos de activos

  • assets/SmoothScroll.jsx — componente de proveedor Lenis + GSAP para React/Next.js.
  • assets/vanilla-setup.js — instalación de Lenis + GSAP para HTML/JS simple.
  • assets/scroll-to-top.jsx — componente para restablecer el desplazamiento en cambios de ruta de Next.js.

12. Versiones y cambios recientes

  • v1.0 (17/05/2025): Versión inicial.
  • v1.1 (18/05/2025): Cuestionario de admisión añadido, regla de oro aclarada, añadido §0.9. Mapas del sitio movidos a una habilidad separada. Nombres de referencias estandarizados. Añadida comprobación de foco de teclado y prefers-reduced-motion en §7.
  • v1.2 (19/05/2025): Añadido flujo de dirección de diseño (§0.8). Añadida referencia visual Prompt Motion (§0.6). Añadida barra de calidad (§0.7). Mejorada la integración de Lenis + GSAP (§3) para Next.js App Router. Añadido ScrollToTopOnRoute.
  • v1.3 (20/05/2025): Añadido registro de estilos (omitir la dirección de los últimos 3 sitios). Añadida verificación de variedad (4/6 ejes). Añadido diseño visual distintivo (§0.9). Añadido flujo de decisión de formularios/estados. Añadido manejo de imágenes.
  • v1.4 (17/02/2026): Añadida guía de Next.js App Router y estado/reactividad.
  • v1.5 (18/02/2026): Añadido Prompt Motion como referencia de movimiento. Añadidas comprobaciones de audacia y efectos de pila. Añadida advertencia de fondo pesado, control de pausa, verificación de licencia. Añadido MCP. Eliminadas reglas sobre mapas del sitio y wireframes.
  • v1.6 (03/04/2026): Cuestionario de admisión ahora es el paso 0.5. Añadido registro de árabe/RTL en el resumen. Añadido §0.9 con opciones de diseño predeterminadas a evitar. Movimiento en la apertura del héroe ahora es opcional. Eliminado wireframe ASCII del flujo de diseño.

Skills relacionados