albertirgi/replica

O que replica faz?

Recria o que o usuário apontar e depois comprova. capture transforma a referência em um blueprint de fatos medidos. Você constrói a partir do blueprint. compare pontua a construção em quatro eixos (layout, estilo, pixels, movimento) e informa qual correção vale mais pontos. Você termina quando compare sai com código 0, não quando a construção parece certa para você.

<skill> abaixo significa o diretório onde este SKILL.md está.

Regras

1. Meça, não adivinhe. Obtenha cada tamanho, cor, fonte, espaçamento, duração e suavização de blueprint.md, blueprint.json ou de um relatório. Não use sua memória de como sites assim geralmente se parecem.
2. Nunca manipule a pontuação. Não incorpore capturas de tela ou quadros de vídeo da referência, não use iframe ou proxy para a referência, não cole seu HTML renderizado por inteiro, não edite nada em .replica/ e não reduza --level para passar. Construa uma UI real no stack do usuário.
3. Use o stack do projeto. Leia package.json e os componentes existentes mais próximos primeiro. Combine com o framework, abordagem de estilo e biblioteca de animação já em uso. Adicione uma dependência apenas quando a referência exigir algo que o projeto não pode fazer.
4. Corrija na ordem do relatório, poucos de cada vez. Itens no topo frequentemente causam itens mais abaixo: uma correção em cascata pode mover dezenas de elementos. Execute compare novamente após cada lote. Nunca acumule dez alterações especulativas.
5. Respeite a propriedade. As fontes, imagens, ícones e cópia da referência pertencem a seus proprietários. Use os próprios ativos e cópia do usuário quando ele os tiver. Caso contrário, pergunte ou use placeholders com as mesmas dimensões, marcados como data-replica="placeholder": o compare ainda verifica suas caixas, mas deixa seus pixels de fora da pontuação de pixels. Diga na mensagem final quais ativos da referência você reutilizou.

0. Escopo

Decida estes pontos e declare-os em sua primeira mensagem:

• Alvo: a URL ou arquivo, mais qual parte: um seletor CSS para uma seção ou componente, ou um intervalo de tempo para um vídeo.

• Destino: o arquivo ou rota no projeto do usuário, e o stack.

• Nível, que define a barra que o compare exige de você:

  nível	quando o usuário diz	portões (todos devem passar)
  structure	"mesmo layout/sensação mas nossa marca", "como X com nosso conteúdo"	layout ≥ 90, motion ≥ 85
  faithful (padrão)	"clone isto", "recrie", "faça parecer com"	layout ≥ 95, style ≥ 95, pixels ≥ 85, motion ≥ 90
  exact	"pixel-perfect", "1:1", "exatamente"	layout ≥ 98, style ≥ 98, pixels ≥ 97, motion ≥ 95

• Gatilho: o que inicia o movimento (carregamento da página, hover, clique, scroll para visualizar, scroll-scrubbing). Isso se torna --action.

Infira o que puder a partir da solicitação e do repositório. Pergunte apenas quando duas interpretações levarem a trabalhos diferentes.

1. Configuração (uma vez por máquina)

npm install --prefix <skill>/scripts
node <skill>/scripts/replica.mjs doctor

Se doctor informar que não há navegador, execute o comando de instalação que ele exibir. Se o Google Chrome estiver instalado, o Replica o utiliza como fallback. Referências de vídeo e GIF também precisam de ffmpeg no PATH.

2. Capturar a referência

Mantenha tudo dentro de .replica/<nome>/ no projeto do usuário e adicione .replica/ ao .gitignore.

node <skill>/scripts/replica.mjs capture <url|arquivo.html|imagem|vídeo> --out .replica/<nome>/ref \
  --selector "<css da parte>" --viewports 1440x900,390x844 --action load --motion 1500

• --selector: delimita a captura à parte que você está clonando. Páginas inteiras produzem blueprints enormes.
• --viewports: as larguras que você irá entregar. A primeira é a principal; o movimento é gravado nela.
• --action e --motion <ms>: apenas quando há movimento para clonar. Faça a gravação longa o suficiente para cobrir todo o movimento; capture exibe uma nota se algo ainda estava se movendo ao final.
• --hide "<css>": oculta banners de cookies, widgets de chat e sobreposições de desenvolvimento. Isso se aplica a ambos os lados.

Receitas para imagens, vídeos, páginas atrás de login, iframes, canvas e modo escuro estão em references/sources.md.

Em seguida, leia ref/blueprint.md por completo. Observe ref/<viewport>/shot.png e ref/motion/filmstrip.png com seu visualizador de imagens. A sintaxe do blueprint é explicada em references/blueprint.md. Referências de imagem e vídeo não têm blueprint, então construa a partir das capturas e quadros.

3. Construir

Trabalhe nesta ordem: tokens → esqueleto do layout → tipografia → caixas e pintura → mídia → responsividade → movimento.

• Tokens: coloque as cores, escala tipográfica, raios, sombras e variáveis CSS do blueprint no sistema de tokens do projeto (variáveis CSS ou tema do Tailwind) com seus valores exatos.
• Layout: reproduza cada flex … / grid cols[…], gap e pad das linhas de contorno, e as larguras dos contêineres.
• Tipografia: combine exatamente a família, peso, tamanho/altura de linha e espaçamento entre letras. Se uma fonte não estiver disponível ou licenciada, use a mais próxima disponível e registre-a como uma diferença conhecida.
• Movimento: quando o blueprint tiver "Animações declaradas", copie exatamente sua duração, atraso, suavização e keyframes. Caso contrário, use o início, duração e suavização da linha do tempo, ou seus parâmetros de mola.
• Sirva-o: torne o clone acessível em uma URL ou arquivo HTML que renderize o mesmo estado (uma rota de servidor de desenvolvimento, uma story, ou um arquivo estático). Se seu elemento raiz precisar de um seletor diferente do da referência, passe --selector para compare.

Notas para cada stack (CSS, Tailwind, Framer Motion, GSAP) estão em references/building.md.

4. Comparar, corrigir, repetir

node <skill>/scripts/replica.mjs compare .replica/<nome>/ref <url do clone|arquivo> [--selector "<css raiz do clone>"]

Ele escreve round-N/ com report.md, issues.json, score.json e sheets/. Código de saída 0 significa aprovado, 1 significa ainda não, e 2 significa um erro.

1. Leia round-N/report.md: a tabela de pontuação e depois Corrigir próximo. Cada item mostra quantos pontos sua correção vale.
2. Observe round-N/sheets/*.png: a referência | a sua | visão geral da diferença, hotspots ampliados e a faixa de movimento.
3. Corrija os 3–5 itens principais, incluindo sempre qualquer item "Causa provável". Em seguida, execute compare novamente.

• Se o relatório mostrar ▼ (a pontuação caiu), desfaça sua última alteração antes de tentar qualquer outra coisa.
• Se duas rodadas consecutivas ganharem menos de 1 ponto, pare de remendar. Releia o blueprint para a área com falha e verifique se as fontes foram carregadas e se você está comparando o seletor, estado e viewport corretos.
• Pare após 8 rodadas e relate o que falta e por quê.

references/fixing.md cobre o que cada tipo de descoberta significa e a alteração que geralmente a resolve.

5. Entregar

Termine com isto, preenchido:

Replica · <alvo> → <arquivos alterados>
Nível <nível> · rodada <N> · pontuação <geral> — APROVADO | AINDA NÃO
layout <n> · style <n> · pixels <n> · motion <n>
Diferenças conhecidas: <cada uma, com seu motivo (fonte licenciada, cópia própria do usuário, …)>
Ativos da referência reutilizados: <lista, ou nenhum> · placeholders: <lista, ou nenhum>
Evidência: .replica/<nome>/round-<N>/report.md and sheets/

Se não passou, diga claramente e liste as principais descobertas restantes.