UI clone: meça a referência, reconstrua, prove que corresponde
Cada job segue um único loop: capturar a referência → medir (ler valores exatos quando possível, medir pixels quando não) → escrever a especificação → construir no stack do usuário → capturar a nossa do mesmo jeito → comparar → corrigir, até que a especificação seja aprovada. A entrega é código no projeto do usuário mais evidências (números, imagens de diff, folhas lado a lado), nunca "parece certo". Métodos adaptados de NiazMorshed2007/reanimate e rossark0/rossark-motion-skill (ambos MIT); cada script aqui é nosso.
<skill> = pasta deste skill. O trabalho vai em ./ui-clone/<nome>/ no projeto: ref/, ours/, figma/, compare-N/, diff-N/, spec.md. Adicione ui-clone/ ao .gitignore a menos que o usuário queira que as evidências sejam commitadas.
Configuração (uma vez por máquina)
- Python (numpy + Pillow):
~/.ui-clone/venv/bin/python(crie compython3 -m venv ~/.ui-clone/venv && ~/.ui-clone/venv/bin/pip install numpy pillowse não existir). Execute scripts com-I. - Captura de navegador (Playwright + Chromium, ~250 MB, apenas para entradas URL / servidor dev): executor em
~/.ui-clone/runner(npm i [email protected] && npx [email protected] install chromiumlá). Execute os scripts.mjscomnode <skill>/scripts/<script>.mjs(eles carregam Playwright de~/.ui-clone/runner, ouUICLONE_RUNNER; se o Chromium próprio do Playwright não estiver instalado, eles usam qualquer Chromium no cache do Playwright, ouUICLONE_CHROMIUM). - ffmpeg/ffprobe no PATH. Figma apenas:
FIGMA_TOKEN=...no ambiente, nokeys.envdo projeto, ou em~/.ui-clone/keys.env(token de acesso pessoal somente leitura). Nunca imprima ou faça commit de tokens. Pergunte antes de instalar qualquer coisa que não esteja presente.
0. Escopo (topo de spec.md, antes de qualquer captura)
- Alvo: exatamente o que clonar (URL + seletor, arquivo + intervalo de tempo + recorte, nó Figma) e nada mais.
- Fidelidade (declare na primeira resposta; ela decide o que será verificado):
nível quando deve corresponder pode diferir fiel-ao-movimento (padrão para trabalhos de outros) "fazer o nosso parecer/agir como o deles" estrutura e proporções, ordem, temporização ±0,08 s, família de easing, overshoot, deslocamento relativo ao tamanho, stagger cópia, cores, fontes, imagens, marca fiel-ao-pixel design próprio do usuário (Figma → código), seu próprio site, trabalho de cliente com direitos, ou prática privada tudo acima + fontes, tamanhos, espaçamento, cores, raios, sombras, assets; diferença de screenshot ≤ 2% (≤ 0,5% em repouso), sem deslocamentos medidos nada que ele não pediu para mudar misto "clone X e adicione Y" a parte clonada em um dos níveis acima as adições (mantidas separadas, mostradas, verificado que não quebram o clone) - Direitos: cópias fiéis ao pixel de interfaces, logotipos, ilustrações, fontes e textos de outras empresas são propriedade delas; use-as apenas para aprendizado ou com permissão, e nunca as publique como trabalho próprio do usuário. Quando a referência for um produto de terceiros e o usuário quiser publicá-lo, use por padrão fiel-ao-movimento com seu próprio design e explique o motivo.
- Destino: onde o código vai e em qual stack. Leia
package.json, componentes existentes, o sistema de estilo (configuração do Tailwind, variáveis CSS, design tokens) e a biblioteca de animação já em uso; corresponda a eles em vez de adicionar uma nova biblioteca.
1. Escolha o método de entrada (o mais preciso disponível; diga qual você usa)
| Entrada | Captura | O que você obtém |
|---|---|---|
| URL ativa | inspect_web.mjs + capture_web.mjs | valores CSS exatos, fontes, durações/atrasos/easings declarados, keyframes; gravação quadro a quadro com relógio virtual |
| Servidor dev local (nosso) | mesmos scripts em http://localhost:… | o lado "nosso" de cada comparação, capturado exatamente como a referência |
| Vídeo / GIF / gravação de tela (web ou app) | ref_frames.py | todos os quadros na fps de origem + folhas de temporização/pose; valores medidos em pixels |
| Figma | figma_fetch.py (token) ou quadros PNG exportados | tamanhos exatos, espaçamento, auto-layout, tipografia, cores, efeitos, transições de protótipo + um PNG de referência |
| App mobile | gravação de tela (referência); para a nossa: xcrun simctl io booted recordVideo ours.mp4 (iOS simulator) ou adb shell screenrecord (Android) | como vídeo; a nossa capturada da mesma forma |
| Combine-os: valores de URL + uma gravação para interações difíceis de acionar (fluxos logados, drags); valores do Figma + servidor dev para verificar "meu build corresponde ao design?"; referência de vídeo + captura do servidor dev para a nossa. Páginas com login: peça uma gravação de tela ou que o usuário faça login; nunca lide com as senhas dele. |
2. Capture e meça a referência
URL:
inspect_web.mjs --url URL --selector "<section>" --out ui-clone/<nome>/ref [--state hover --target "<btn>"]→inspect.md: por elemento box + estilos computados, transições declaradas, animações em execução com keyframes, @keyframes, fontes, bibliotecas detectadas (GSAP, Framer Motion, Lottie, three.js, Lenis...), canvases (2d/WebGL), diff de hover/foco. Valores declarados prevalecem sobre os medidos: copie-os.capture_web.mjs --url URL --selector "<section>" --trigger load|hover|click|scroll|none --duration 2 --fps 30 --out ui-clone/<nome>/ref→ frames/, video.mp4, frames.json, animations.json. Padrão--mode seek(relógio virtual: timers JS e requestAnimationFrame no relógio do Playwright, CSS/Web Animations pausados e seekados a cada quadro: capturas idênticas). Use--mode realtimepara páginas que o relógio virtual quebra (elementos de vídeo, algumas bibliotecas WebGL/canvas) e diga isso.--stilldá um screenshot estável para trabalho pixel;--dpr 2para comparações nítidas em retina (--dpr 3para elementos pequenos: um crescimento de hover de 12 px tem poucos pixels para ajustar um easing em 1x);--pad 12adiciona uma margem ao redor de--selectorpara que efeitos de hover/scale que crescem além da box de repouso fiquem no quadro;--viewport 390x844para celulares. O modo seek é verificado como idêntico quadro a quadro entre execuções.--mode realtimetira screenshots reais o mais rápido que a máquina permite (~19/s em um laptop típico) e reamostra; ele imprime a taxa alcançada: a temporização só é tão precisa quanto isso. Vídeo / GIF / gravação:ref_frames.py REF.mp4 --out ui-clone/<nome>/ref [--start --end --crop x:y:w:h]. Figma:figma_fetch.py --url "<figma link with node-id>" --out ui-clone/<nome>/figma --scale 2→ design.md/json + frame.png. Depois meça o movimento (qualquer entrada com quadros):- Cortes e seções:
motion_compare.py <ref> <ref> --out <ref>/self --no-align. - Cores:
track_motion.py <ref>/frames --sample X,Y --at T. - Cada elemento em movimento:
track_motion.py <ref>/frames --name el --colors HEX,HEX --tol 35 --region x,y,w,h(sempre uma região em referências movimentadas). - Cada movimento:
fit_easing.py <ref>/track_el.json --prop cx|cy|w|h|aspect|presence --from A --to B→ temporização, easing, overshoot, e linhas prontas para copiar em CSS / WAAPI / Framer Motion / GSAP / Remotion. Erro ≤ 0,03 = ajuste próximo; "no single ease fits" = divida a janela ou é uma cadeia de keyframes. Quando o erro do segundo colocado estiver dentro de ~0,003 do melhor, trate como empate (ex.: easeOutQuad 0,58 s vs easeOutCubic 0,80 s ajustam os mesmos quadros): diga isso, e prefira valores declarados deinspect.md, do código fonte ou das folhas para desempatar. O rastreamento só vê um elemento por sua cor, então um elemento que aparece gradualmente enquanto se move parece começar tarde: para entradas web, use os valores declarados. Leia você mesmo cada folha (sheets/poses.png,sheets/timing_NN.png): números dizem que, folhas dizem o quê.
3. Escreva a especificação (ui-clone/<nome>/spec.md; cada linha vira uma verificação)
- Estrutura e estilo estático (fiel-ao-pixel): elemento → box, fonte (família/tamanho/peso/altura de linha/espaçamento entre letras), cores, raio, sombra, espaçamento; fonte (
inspect.json/design.json/ medido). - Linha do tempo (movimento):
| # | elemento | propriedade | de → para | início ms | duração ms | easing | stagger / repetição | trigger | fonte |. - Anote o que não se move. Um "?" significa que a referência ainda não foi lida. Mostre a especificação antes de uma grande construção.
4. Construa
No stack e sistema de design do usuário. Copie valores declarados exatamente (fiel-ao-pixel) ou proporções relativas (fiel-ao-movimento). Easings de inspect.json ou da linha de fit_easing.py para a biblioteca deles; springs onde a referência tem overshoot e depois estabiliza; staggers como base + índice × passo. Respeite prefers-reduced-motion (mostre o estado final). Mantenha adições em componentes separados. Dê à nossa uma rota/página que renderize o componente no viewport da referência com o mesmo trigger, para que possa ser capturado de forma idêntica. Efeitos WebGL: reconstrua o shader a partir do que a referência mostra (ou sua fonte legível quando o usuário puder usá-la); passo de tempo fixo a partir do tempo, aleatoriedade com semente.
5. Verifique, corrija, repita (2-5 rodadas; mantenha a pasta de cada rodada)
- Capture a nossa com o mesmo comando da referência (apenas
--url/entrada e--outmudam), ouref_frames.py OURS.mp4 --out ui-clone/<nome>/ours --like <ref>/frames.jsonpara entradas de vídeo. - Pixels:
screenshot_diff.py <ref>/still.png <ours>/still.png --out ui-clone/<nome>/diff-N [--strict] [--max 0.02] [--mask x,y,w,h](fiel-ao-pixel: sempre--strict: limiar por pixel 0.03, max 0.5%, e qualquer região cuja cor derive mais de 3 níveis RGB falha; o padrão é tolerante e deixa passar pequenas mudanças de padding e cor) → % de diferença, piores regiões, deslocamentos de imagem inteira ou por elemento ("algo na região … moveu +0 px x, +6 px y"), deriva de cor,side_by_side.png. Corrija deslocamentos primeiro (eles fazem tudo parecer errado), depois tamanhos, depois cores. Fiel-ao-pixel FALHA em qualquer deslocamento medido; fiel-ao-movimento usa--allow-shifte um--maxmais flexível. - Movimento:
motion_compare.py <ref> <ours> --out ui-clone/<nome>/compare-N(cortes, movimentos, deslocamento; PASSAGEM ±0.08 s;activity.png,sheets/compare_NN.png) e, por linha da especificação,fit_easing.py REF_TRACK --prop P --from A --to B --vs OUR_TRACK. - Leia as folhas a cada rodada. Mude a menor coisa que a evidência apontar; recapture; recompare.
- Após 5 rodadas, relate cada linha ainda falhando com seu número e motivo (licença de fonte, efeito WebGL aproximado, spring ajustado a olho). Nunca afrouxe um limiar silenciosamente.
| Sintoma | Causa usual | Correção |
|---|---|---|
| imagem inteira deslocada N px | scroll/offset/crop diferente ou uma margem de wrapper faltando | iguale viewport, dpr, crop; corrija o espaçamento externo |
| um elemento se moveu | margin/padding/line-height/gap difere | compare sua box com inspect.json / design.json |
| texto ligeiramente errado em toda parte | fonte fallback, peso ou espaçamento entre letras diferente | carregue a mesma fonte (ou o equivalente licenciado do usuário), iguale tamanho/peso/tracking |
| cores ligeiramente erradas em toda parte | espaço de cor, empilhamento de opacidade, paradas de gradiente | copie cores/gradientes computados; verifique opacidade nos pais |
| movimento deslocado por um offset | latência do trigger ou delay faltando | corrija o primeiro delay |
| nossa adiantada / muito rápida | easing mais forte (expo vs cúbico) | use a bezier ajustada ou o easing declarado |
| referência tem overshoot, a nossa não | spring/back vs bezier | spring/back ajustado ao overshoot e estabilização medidos |
| animação de scroll começa cedo/tarde | limiar/offset do trigger | iguale a posição de scroll onde o movimento começa |
| um movimento extra na nossa | uma transição perdida (ex.: transition: all) | limite transições às propriedades que devem animar |
6. Relatório (deve ser autossuficiente)
Nível de fidelidade e o que foi clonado / adicionado; arquivos alterados e como acionar o movimento; as tabelas da última rodada (diferença de pixel e deslocamentos; temporização de cortes/movimentos; easing por elemento), caminhos para side_by_side.png, activity.png e folhas de comparação; cada diferença restante com seu número e motivo; quais verificações foram medidas (um script as produziu) vs avaliadas a olho (olhou para uma folha).
Limites
- A captura com relógio virtual não pode controlar a reprodução de
<video>ou algumas bibliotecas de GPU/física: use--mode realtimee espere ±1-2 quadros de variação; diga isso. - Folhas de estilo e fontes de origem cruzada podem ocultar regras @keyframes/@font-face da inspeção; estilos computados e animações em execução ainda são lidos.
- De vídeos, 3D é combinado como movimento de câmera/objeto, não modelos ou materiais; ação ao vivo movimentada dá ritmo, não valores exatos de elemento.
- Mobile: valores vêm de gravações (sem fonte); capturas de simulador da nossa são comparadas da mesma forma.