Inno-Merkle-TH/social-mockup-studio

Social Mockup Studio

Transforma um briefing em maquetes fiéis aos pixels de telas do LINE, Facebook e TikTok, para qualquer marca, no iOS, Android ou desktop. O kit separa duas coisas que nunca devem se misturar:

• Chrome da plataforma (barra de status, cabeçalho do LINE, barra de abas do FB, trilho do TikTok…) reside em assets/kit.css. Ele sempre se parece com o aplicativo real, nunca com a marca.
• Conteúdo da marca (mensagens Flex, arte do menu rico, criativo do anúncio, avatar, estilo do CTA) é controlado apenas pelas variáveis de <project>/brand.css.

Trocar marcas = trocar brand.css + imagens + texto. É isso que torna os resultados comparáveis entre marcas.

Fluxo de Trabalho

0. Pré-verificação (antes da primeira pergunta). Execute python3 scripts/preflight.py --brand <site da marca> --surfaces <line,fb,tiktok>. Coloque suas linhas DIGA AO USUÁRIO em sua primeira resposta:
   • Sem navegador: diga que nada pode ser renderizado, exportado ou verificado visualmente aqui.
   • Site da marca ou fontes de imagem bloqueados: informe, nomeie os arquivos exatos para enviar (logotipo, imagem herói da mensagem rica, imagens de tile…, além das cores hexadecimais da marca e texto do CTA), ou peça ao usuário para permitir o domínio.
   • Nunca construa com arte inventada para preencher a lacuna.
   • Copie o resultado para notes.md → Ambiente.
1. Coleta de requisitos (pergunte, não adivinhe). Leia references/intake.md e faça as perguntas em rodadas com AskUserQuestion. Defina as telas primeiro (Rodada 1b): pergunte se o usuário já sabe quais telas deseja (aceite a lista como fornecida) ou precisa de ajuda (pergunte o objetivo, então proponha 2–3 storyboards de tamanhos diferentes). Confirme uma tabela de storyboard numerada antes de construir, e nunca adicione ou remova telas silenciosamente. Para cada tela de chat do LINE, sempre pergunte se o menu rico está aberto (aberto / recolhido / nenhum) e se deve mostrar apenas a nova mensagem (ancorada ao topo) ou as mensagens anteriores também. Para um menu rico, mostre a imagem do seletor de layout primeiro (templates/richmenu-picker.svg/.png, a intake.md Rodada 3b explica como por ambiente), depois pergunte qual código. Para LINE, sempre pergunte mensagem rica, Flex ou ambos (Q3c, com a comparação visual de references/line.md). Pergunte cedo pelo logotipo, as cores da marca (hex) e o texto exato do CTA. Registre cada resposta em notes.md → Brief, e cada suposição em → Suposições para confirmar. Pule uma pergunta apenas se o usuário já respondeu ou se um padrão sensato está listado. Nunca invente ofertas, preços, datas, programas de fidelidade ou alegações de produto. Pergunte, ou marque como placeholders.
2. Estruturação. bash scripts/new_project.sh <caminho/para/nome-do-projeto> → copia o kit, um index.html inicial, brand.css e notes.md.
3. Marca + imagens. Preencha brand.css a partir da coleta de requisitos. Coloque fontes licenciadas em brand/fonts/ e o logotipo (marca monocromática para avatares) em brand/. Limpe cada upload primeiro: python3 scripts/clean_image.py <arquivos> --for <posicionamento> --edges /tmp/edges.png. Ele corta faixas de bordas brancas e as registra em assets/clean-log.txt, verifica o tamanho em relação a references/line-image-sizes.md e gera uma folha de bordas. Abra a folha e olhe para ela. Uma mensagem rica tem 1040×1040 a menos que o usuário confirme outro tamanho do OA Manager. Qualquer limite de plataforma que você citar precisa de duas ou mais fontes; se elas entrarem em conflito, informe e escolha o mais seguro. Cada espaço de imagem recebe uma foto real. Gradientes CSS ou texto placeholder no lugar de fotografia é o que faz uma maquete parecer falsa. Siga references/image-sourcing.md: fornecido pelo usuário → site da marca/sala de imprensa → encontrar online (scripts/find_images.py "<consulta>" --orient portrait cria uma folha de contato que você olha; depois scripts/fetch_image.py <url> assets/<nome>.jpg --crop 4:5). Você também pode pesquisar na web qualquer página (notícias, varejista, rede social da marca) e passar sua URL para fetch_image.py; ele lê a imagem principal da página. Cada download é registrado em assets/credits.json.
4. Construir capturas. A galeria tem um exemplo por superfície, não toda superfície × combinação de SO (veja a matriz abaixo). Copie o bloco mais próximo de templates/gallery.html para index.html, depois troque o dispositivo usando references/devices.md: troque .dev.android ↔ .dev.ios e aplique as diferenças de chrome desse SO (ex. abas do FB no topo ↔ barra de abas inferior). Edite o texto e as imagens. Especificidades da plataforma estão em references/line.md, facebook.md, tiktok.md.
   • Dê a cada captura um data-shot único; ele se torna o nome do arquivo. O CSS por captura pode ser delimitado com [data-shot="id"].
   • Nomeie as classes do projeto com um prefixo do projeto (ex. .sb-hero, não .kv/.hero) para que nunca colidam com as classes do kit.
   • Fontes e proporções (leia references/typography-and-ratios.md): o texto que o aplicativo desenha (balões, Flex, texto da postagem, botões CTA, legendas) é sempre a fonte da plataforma, então nunca coloque --brand-head/--brand-body nela. As fontes da marca vão apenas dentro das imagens. As caixas de mídia recebem uma proporção, nunca uma altura fixa: feed do FB 4:5, carrossel 1:1, Stories/Reels/TikTok 9:16, mensagem rica do LINE 1040×1040 por padrão (outros tamanhos apenas após confirmação, veja references/line-image-sizes.md; a geometria edge-to-edge é NÃO VERIFICADA), herói Flex 20:13.
   • Nunca remova, encurte ou mova o conteúdo do briefing para fazê-lo caber (ex. removendo o balão de texto para que uma imagem quadrada caiba com o menu aberto, ou ancorando na parte inferior um chat "apenas nova mensagem"). Informe o usuário e ofereça opções: um menu compacto, texto mais curto ou uma tela extra com o menu recolhido.
   • Detalhes do kit marcados como NÃO VERIFICADOS (atualmente a margem, raio e largura da mensagem rica em references/line.md) vão em notes.md → Não verificado e em sua mensagem de entrega.
   • Texto em tailandês: envolva preços, datas, unidades e partículas finais em <span style="white-space:nowrap"> para que as linhas nunca terminem com um "ค่ะ", "ml" ou uma palavra dividida órfã.
5. Exportar (em um Mac, para que o texto do iOS seja renderizado com a SF Pro + Thonburi reais). node scripts/export.cjs <projeto> (primeira vez em uma máquina: cd scripts && npm install; ele usa o Google Chrome instalado se o navegador do Playwright não estiver baixado). Ele serve apenas a pasta do projeto. → captures/NN-<id-da-captura>.png (3× telefones, 2× desktop, transparente), 00-overview.png, qa.json. Corrija cada requisição falha e problema de QA que ele imprimir.
   • Se a exportação não puder ser executada aqui (aplicativo Claude / sandbox do Cowork sem Node, Playwright ou internet): tente cd scripts && npm install && npx playwright install chromium uma vez. Se ainda falhar, tente Python (pip install playwright && python -m playwright install chromium) e faça capturas de tela de cada .frame em 3× você mesmo. Como último recurso, execute python3 scripts/bundle.py <projeto> para criar um único HTML autocontido (dist/<nome>.html, que abre com duplo clique). Entregue-o com o ZIP do projeto e informe claramente ao usuário: "Não consegui renderizar nada aqui, então estas telas não foram verificadas visualmente. Abra o HTML no Chrome; para salvar uma tela, clique com o botão direito → Inspecionar → Capture node screenshot no quadro do telefone, ou execute a exportação em um Mac." Em seguida, liste os detalhes não verificados. Nunca apresente um resultado não renderizado como verificado e nunca pare sem ter nada para mostrar.
   • HTML de arquivo único: sempre construa-o com scripts/bundle.py, nunca com um script ad-hoc. Ele verifica a sintaxe de cada script embutido (node --check), falha se algum id de ícone ou arquivo estiver faltando e, quando um navegador existe, confirma que as barras de status e ícones renderizam. Um empacotador ad-hoc uma vez corrompeu o sprite de ícones e matou o kit.js, deixando sem barra de status ou ícones.
   • Fora do macOS, o texto do iOS usa Inter em vez de SF Pro (kit.js faz a troca). Informe em notes.md e ofereça uma reexportação no Mac para arquivos finais do cliente.
6. Revise como um cliente faria. Abra cada PNG em tamanho real (não apenas o painel geral) e execute references/qa-checklist.md. Preencha notes.md → "Verificação pré-entrega contra o Brief" para cada captura: todo o texto do briefing presente, ancoragem, estado do menu e formato da mensagem conforme solicitado, nada removido. Coloque sua maquete lado a lado com uma captura de dispositivo real de references/screens/device/ (ou peça ao usuário capturas de tela frescas do telefone da mesma superfície). As UIs das plataformas mudam a cada poucos meses, e uma captura real é a única verdade absoluta.
7. Registre e entregue honestamente. Atualize notes.md: placeholders, suposições, detalhes não verificados, fontes de imagem e registro de limpeza, cronograma. A mensagem de entrega deve conter: (a) os caminhos dos arquivos; (b) o que foi e o que não foi verificado, ex. "renderizado e verificado a 100%" vs "não renderizado aqui"; (c) Suposições a confirmar, como uma lista curta (primeira entrega especialmente); (d) Detalhes não verificados; (e) qualquer item do briefing que você não pôde encaixar, com as opções que está oferecendo.

Matriz da galeria (✓ = captura pré-pronta; outros = adaptar da mesma linha)

Superfície	Android	iOS	Desktop
Chat OA LINE + Flex	✓ escuro	✓ claro	– (ainda não no kit)
Menu rico LINE (12 modelos OA Manager + personalizado + abas)	✓ escuro L6, ✓ com abas	✓ grande L4b, ✓ compacto C2l	– (não mostrado no LINE PC)
Push / tela de bloqueio LINE	adaptar (.android .notif)	✓	–
Feed FB imagem única	✓ claro	✓ escuro	✓
Carrossel FB	adaptar	✓ claro	adaptar
Stories/Reels FB	adaptar	✓	–
In-feed / Spark / cartão de produto TikTok	✓ in-feed	✓ Spark, ✓ cartão de produto	✓

Regras de realismo (aprendidas da maneira mais difícil)

Leia references/realism-rules.md uma vez por projeto. A versão resumida:

• O chrome da plataforma nunca é da cor da marca. Cabeçalhos do LINE, UI do FB/TikTok permanecem nativos.
• Uma linha do tempo coerente em todas as telas (teaser → lançamento → pré-venda → à venda → sustentação). Datas, dias da semana, contagens regressivas e "válido até" devem concordar. Verifique o dia da semana de cada data.
• Não invente benefícios (pontos, níveis de associação, brindes) que a marca não oferece. Se o briefing não diz, é um placeholder ou uma pergunta.
• O conteúdo ancora onde o aplicativo real ancora. Um tópico novo do LINE começa no topo; um longo é alinhado na parte inferior (.ln-msgs.bottom). Grandes vazios parecem falsos.
• As imagens devem ser legíveis no tamanho do telefone. Uma miniatura de produto com menos de ~60 px é invisível, então corte mais apertado ou aumente.
• Use números plausíveis (curtidas, comentários, horários, bateria) e mantenha os horários da barra de status consistentes com a história (um push às 07:30 não deve mostrar 21:14).
• Um menu rico do LINE é uma imagem projetada (2500×1686 ou 2500×843), não blocos de UI nativos. Projete-o como arte.

Quando algo não está no kit

Construa-o no <style> do index.html do projeto usando as mesmas convenções (variáveis de plataforma vs marca). Se for reutilizável (uma nova superfície como LINE VOOM, FB Messenger, TikTok TopView), adicione-o a assets/kit.css + templates/gallery.html e mencione para que a equipe possa enviá-lo para upstream.

Arquivos

Caminho	O quê
assets/kit.css, kit.js, icons.svg, fonts/	o kit (copiado para cada projeto como kit/)
templates/gallery.html	toda superfície × SO, copie blocos daqui
templates/brand.example.css	variáveis da marca com comentários
templates/index.starter.html, notes.template.md	iniciadores de projeto
scripts/new_project.sh	estruturar um projeto
scripts/preflight.py	passo 0: podemos renderizar? é um Mac? o site da marca e as fontes de imagem estão acessíveis? imprime o que dizer ao usuário
scripts/clean_image.py	cortar bordas brancas de uploads (registrado), verificação de tamanho por posicionamento, folha de QA de zoom de borda
scripts/bundle.py	um único HTML autocontido (CSS/JS/fontes/imagens/sprite embutidos), com verificações de sintaxe, ícone e renderização
templates/richmenu-picker.svg / .png	todo layout de menu rico com seu código, mostrado ao usuário na coleta de requisitos; reconstruir com scripts/richmenu_picker.py --png
references/line-image-sizes.md	mensagem rica LINE / menu rico / Flex / tamanhos de imagem por rota de envio, com fontes e conflitos
scripts/find_images.py, fetch_image.py	encontrar fotos reais online (folha de contato) · baixar + cortar + registrar fonte
references/image-sourcing.md	de onde vêm as imagens, cortes por posicionamento, regras de criação de anúncios
scripts/export.cjs	renderizar + QA (precisa de npm install em scripts/ uma vez)
references/intake.md	as rodadas de perguntas + padrões
references/line.md, facebook.md, tiktok.md	anatomia, limites, mapa de classes por plataforma
references/devices.md	quadros, barras de status, diferenças de SO
references/realism-rules.md, qa-checklist.md, localization-th.md	barras de qualidade
references/screens/	capturas de tela do aplicativo real datadas + réplicas calibrate/
references/typography-and-ratios.md	qual fonte cada plataforma realmente usa, tamanhos medidos, proporções de mídia
scripts/calibrate.cjs	sobrepor uma réplica do kit em uma captura de tela real (lado/misturar/diferença + pontuação por banda)