Inno-Merkle-TH/social-mockup-studio

Social Mockup Studio (Estudio de Maquetas para Redes Sociales)

Convierte un breve en maquetas fieles de pantallas de LINE, Facebook y TikTok, para cualquier marca, en iOS, Android o escritorio. Este kit separa dos cosas que nunca deben mezclarse:

• El 'chrome' de la plataforma (barra de estado, encabezado de LINE, barra de pestañas de FB, carril de TikTok…) reside en assets/kit.css. Siempre se ve como la app real, nunca como la marca.
• El contenido de la marca (mensajes Flex, arte del menú rico, anuncios creativos, avatar, estilo del CTA) se define únicamente mediante las variables de <project>/brand.css.

Cambiar de marca = cambiar brand.css + imágenes + texto. Eso es lo que hace que los resultados sean comparables entre marcas.

Flujo de trabajo

0. Verificación previa (antes de la primera pregunta). Ejecuta python3 scripts/preflight.py --brand <sitio de la marca> --surfaces <line,fb,tiktok>. Coloca sus líneas DÍLE AL USUARIO en tu primera respuesta:
   • Sin navegador: di que aquí no se puede renderizar, exportar ni verificar visualmente nada.
   • Sitio de la marca o fuentes de imágenes bloqueadas: dilo, nombra los archivos exactos a subir (logotipo, héroe del mensaje enriquecido, imágenes de azulejos…, más los colores hex de la marca y el texto del CTA), o pide al usuario que permita el dominio.
   • Nunca construyas con arte inventado para llenar el vacío.
   • Copia el resultado en notes.md → Entorno.
1. Recepción (pregunta, no adivines). Lee references/intake.md y haz las preguntas en rondas con AskUserQuestion. Primero, define las pantallas (Ronda 1b): pregunta si el usuario ya sabe qué pantallas quiere (toma su lista como dada) o si necesita ayuda (pregunta el objetivo, luego propón 2-3 storyboards de diferentes tamaños). Confirma una tabla de storyboard numerada antes de construir, y nunca agregues o elimines pantallas en silencio. Para cada pantalla de chat de LINE, siempre pregunta si el menú rico está abierto (abierto/contraído/ninguno) y si se debe mostrar solo el mensaje nuevo (anclado arriba) o también los mensajes anteriores. Para un menú rico, muestra primero la imagen del selector de diseño (templates/richmenu-picker.svg/.png, la ronda 3b de intake.md explica cómo según el entorno), luego pregunta qué código. Para LINE, pregunta siempre mensaje enriquecido, Flex o ambos (Q3c, con la comparación visual de references/line.md). Pide pronto el logotipo, los colores de la marca (hex) y el texto exacto del CTA. Registra cada respuesta en notes.md → Brief, y cada suposición en → Suposiciones para confirmar. Solo omite una pregunta si el usuario ya la respondió o si hay un valor predeterminado razonable listado. Nunca inventes ofertas, precios, fechas, programas de fidelización ni afirmaciones sobre productos. Pregúntalo, o márcalo como marcador de posición.
2. Andamiaje. bash scripts/new_project.sh <ruta/al/nombre-del-proyecto> → copia el kit, un index.html inicial, brand.css y notes.md.
3. Marca e imágenes. Completa brand.css con los datos de la recepción. Coloca las fuentes con licencia en brand/fonts/ y el logotipo (marca de un solo color para avatares) en brand/. Limpia cada carga primero: python3 scripts/clean_image.py <archivos> --for <ubicación> --edges /tmp/edges.png. Recorta los bordes blancos y los registra en assets/clean-log.txt, verifica el tamaño con references/line-image-sizes.md, y genera una hoja de bordes. Abre la hoja y mírala. Un mensaje enriquecido es de 1040×1040 a menos que el usuario confirme otro tamaño del OA Manager. Cualquier límite de plataforma que menciones necesita dos o más fuentes; si entran en conflicto, dilo y elige la más segura. Cada espacio de imagen recibe una foto real. Los degradados CSS o el texto de marcador de posición en lugar de fotografía hacen que una maqueta parezca falsa. Sigue references/image-sourcing.md: proporcionado por el usuario → sitio web de la marca/kit de prensa → buscar en línea (scripts/find_images.py "<consulta>" --orient portrait crea una hoja de contacto que revisas; luego scripts/fetch_image.py <url> assets/<nombre>.jpg --crop 4:5). También puedes buscar en la web cualquier página (noticias, minorista, redes sociales de la marca) y pasar su URL a fetch_image.py; lee la imagen principal de la página. Cada descarga se registra en assets/credits.json.
4. Construye las capturas. La galería tiene un ejemplo por superficie, no todas las superficies × combinaciones de SO (ver la matriz a continuación). Copia el bloque más cercano de templates/gallery.html en index.html, luego cambia el dispositivo usando references/devices.md: intercambia .dev.android ↔ .dev.ios y aplica las diferencias de chrome de ese SO (p. ej., pestañas de FB arriba ↔ barra de pestañas abajo). Edita el texto y las imágenes. Los detalles específicos de la plataforma están en references/line.md, facebook.md, tiktok.md.
   • Dale a cada captura un data-shot único; se convertirá en el nombre del archivo. El CSS por captura se puede definir con [data-shot="id"].
   • Nombra las clases del proyecto con un prefijo del proyecto (p. ej., .sb-hero, no .kv/.hero) para que nunca choquen con las clases del kit.
   • Fuentes y proporciones (lee references/typography-and-ratios.md): el texto que dibuja la app (burbujas, Flex, texto de publicaciones, botones CTA, leyendas) siempre usa la fuente de la plataforma, así que nunca le pongas --brand-head/--brand-body. Las fuentes de la marca van solo dentro de las imágenes. Los cuadros de medios tienen una proporción, nunca una altura fija: feed de FB 4:5, carrusel 1:1, Stories/Reels/TikTok 9:16, mensaje enriquecido de LINE 1040×1040 por defecto (otros tamaños solo después de confirmación, ver references/line-image-sizes.md; la geometría de borde a borde es NO VERIFICADA), héroe Flex 20:13.
   • Nunca elimines, acortes o muevas el contenido del brief para que encaje (p. ej., quitando la burbuja de texto para que una imagen cuadrada quepa con el menú abierto, o anclando abajo un chat de "solo mensaje nuevo"). Informa al usuario y ofrece opciones: un menú compacto, texto más corto o una pantalla adicional con el menú contraído.
   • Los detalles del kit marcados como NO VERIFICADOS (actualmente el margen, radio y ancho del mensaje enriquecido en references/line.md) van en notes.md → No verificado y en tu mensaje de entrega.
   • Texto en tailandés: envuelve precios, fechas, unidades y partículas finales en <span style="white-space:nowrap"> para que las líneas nunca terminen con un "ค่ะ" huérfano, "ml" o una palabra partida.
5. Exportación (en un Mac, para que el texto de iOS se renderice con SF Pro + Thonburi reales). node scripts/export.cjs <proyecto> (primera vez en una máquina: cd scripts && npm install; recurre a Google Chrome instalado si el navegador de Playwright no está descargado). Sirve solo la carpeta del proyecto. → captures/NN-<id-captura>.png (3× teléfonos, 2× escritorio, transparente), 00-overview.png, qa.json. Arregla cada solicitud fallida y problema de QA que imprima.
   • Si la exportación no se puede ejecutar aquí (app de Claude / sandbox de Cowork sin Node, Playwright o internet): intenta cd scripts && npm install && npx playwright install chromium una vez. Si eso falla, prueba con Python (pip install playwright && python -m playwright install chromium) y captura cada .frame a 3× tú mismo. Como último recurso, ejecuta python3 scripts/bundle.py <proyecto> para hacer un HTML autónomo (dist/<nombre>.html, que se abre con doble clic). Entrégalo con el ZIP del proyecto, y dile claramente al usuario: "No pude renderizar nada aquí, así que estas pantallas no se han verificado visualmente. Abre el HTML en Chrome; para guardar una pantalla, haz clic derecho → Inspeccionar → Capturar captura de nodo en el marco del teléfono, o ejecuta la exportación en un Mac." Luego enumera los detalles no verificados. Nunca presentes un resultado no renderizado como verificado, y nunca te detengas sin mostrar nada.
   • HTML de un solo archivo: constrúyelo siempre con scripts/bundle.py, nunca con un script ad-hoc. Verifica la sintaxis de cada script en línea (node --check), falla si falta algún id de icono o archivo, y cuando existe un navegador, confirma que las barras de estado y los iconos se rendericen. Un empaquetador ad-hoc una vez corrompió el sprite de iconos y mató kit.js, dejando sin barra de estado ni iconos.
   • Fuera de macOS, el texto de iOS usa Inter en lugar de SF Pro (kit.js lo intercambia). Dilo en notes.md y ofrece una reexportación en Mac para los archivos finales del cliente.
6. Revisa como lo haría un cliente. Abre cada PNG a tamaño completo (no solo la vista general) y ejecuta references/qa-checklist.md. Completa notes.md → "Verificación previa a la entrega contra el Brief" para cada captura: todo el texto del brief presente, anclaje, estado del menú y formato del mensaje según lo solicitado, nada eliminado. Coloca tu maqueta junto a una captura real del dispositivo de references/screens/device/ (o pide al usuario capturas de pantalla frescas del teléfono de la misma superficie). Las interfaces de usuario de las plataformas cambian cada pocos meses, y una captura real es la única verdad absoluta.
7. Registra y entrega con honestidad. Actualiza notes.md: marcadores de posición, suposiciones, detalles no verificados, fuentes de imágenes y registro de limpieza, cronograma. El mensaje de entrega debe contener: (a) las rutas de los archivos; (b) qué fue y qué no fue verificado, p. ej., "renderizado y verificado al 100%" vs "no renderizado aquí"; (c) Suposiciones para confirmar, como una lista corta (especialmente la primera entrega); (d) Detalles no verificados; (e) cualquier elemento del brief que no pudiste incluir, con las opciones que ofreces.

Matriz de la galería (✓ = captura lista; otros = adaptar de la misma fila)

Superficie	Android	iOS	Escritorio
Chat LINE OA + Flex	✓ oscuro	✓ claro	– (aún no en el kit)
Menú rico LINE (12 plantillas OA Manager + personalizado + pestañas)	✓ oscuro L6, ✓ con pestañas	✓ grande L4b, ✓ compacto C2l	– (no se muestra en LINE PC)
Push / pantalla de bloqueo LINE	adaptar (.android .notif)	✓	–
Feed de FB imagen única	✓ claro	✓ oscuro	✓
Carrusel de FB	adaptar	✓ claro	adaptar
Stories/Reels de FB	adaptar	✓	–
In-feed / Spark / tarjeta de producto TikTok	✓ in-feed	✓ Spark, ✓ tarjeta de producto	✓

Reglas de realismo (aprendidas por las malas)

Lee references/realism-rules.md una vez por proyecto. La versión corta:

• El 'chrome' de la plataforma nunca tiene el color de la marca. Los encabezados de LINE, la interfaz de usuario de FB/TikTok se mantienen nativos.
• Una línea de tiempo coherente en todas las pantallas (teaser → lanzamiento → preventa → venta → sostenimiento). Las fechas, los días de la semana, las cuentas atrás y el "válido hasta" deben coincidir. Verifica el día de la semana de cada fecha.
• No inventes beneficios (puntos, niveles de membresía, regalos) que la marca no ofrezca. Si el brief no lo dice, es un marcador de posición o una pregunta.
• El contenido se ancla donde lo ancla la app real. Un hilo nuevo de LINE comienza arriba; uno largo está alineado abajo (.ln-msgs.bottom). Los grandes vacíos se ven falsos.
• Las imágenes deben leerse al tamaño de un teléfono. Una miniatura de producto de menos de ~60 px es invisible, así que recorta más o hazla más grande.
• Usa números plausibles (me gusta, comentarios, horas, batería) y mantén las horas de la barra de estado coherentes con la historia (un push a las 07:30 no debería mostrar las 21:14).
• Un menú rico de LINE es una imagen diseñada (2500×1686 o 2500×843), no mosaicos de interfaz de usuario nativos. Diseñalo como una obra de arte.

Cuando algo no está en el kit

Constrúyelo en el <style> de index.html del proyecto usando las mismas convenciones (variables de plataforma vs marca). Si es reutilizable (una nueva superficie como LINE VOOM, FB Messenger, TikTok TopView), agrégalo a assets/kit.css + templates/gallery.html y menciónalo para que el equipo pueda subirlo.

Archivos

Ruta	Qué es
assets/kit.css, kit.js, icons.svg, fonts/	el kit (copiado en cada proyecto como kit/)
templates/gallery.html	cada superficie × SO, copia los bloques de aquí
templates/brand.example.css	variables de marca con comentarios
templates/index.starter.html, notes.template.md	iniciadores de proyecto
scripts/new_project.sh	andamiar un proyecto
scripts/preflight.py	paso 0: ¿podemos renderizar? ¿es un Mac? ¿son accesibles el sitio de la marca y las fuentes de imágenes? imprime lo que hay que decir al usuario
scripts/clean_image.py	recortar bordes blancos de las cargas (registrado), verificación de tamaño por ubicación, hoja de QA de zoom de bordes
scripts/bundle.py	un HTML autónomo (CSS/JS/fonts/images/sprite incrustados), con verificaciones de sintaxis, iconos y renderizado
templates/richmenu-picker.svg / .png	cada diseño de menú rico con su código, mostrado al usuario en la recepción; reconstruir con scripts/richmenu_picker.py --png
references/line-image-sizes.md	tamaños de imágenes de mensaje enriquecido / menú rico / Flex de LINE por ruta de envío, con fuentes y conflictos
scripts/find_images.py, fetch_image.py	encontrar fotos reales en línea (hoja de contacto) · descargar + recortar + registrar fuente
references/image-sourcing.md	de dónde vienen las imágenes, recortes por ubicación, reglas de creación de anuncios
scripts/export.cjs	renderizar + QA (necesita npm install en scripts/ una vez)
references/intake.md	las rondas de preguntas + valores predeterminados
references/line.md, facebook.md, tiktok.md	anatomía, límites, mapa de clases por plataforma
references/devices.md	marcos, barras de estado, diferencias de SO
references/realism-rules.md, qa-checklist.md, localization-th.md	barras de calidad
references/screens/	capturas de pantalla reales de la app con fecha + réplicas de calibrate/
references/typography-and-ratios.md	qué fuente usa realmente cada plataforma, tamaños medidos, proporciones de medios
scripts/calibrate.cjs	superponer una réplica del kit sobre una captura de pantalla real (lateral/fusión/diferencia + puntuación por banda)