kinqsradio/motion-match

Igualar movimento

Use isto quando o usuário apontar para algo que se move e quiser que o nosso se mova da mesma forma, ou quiser prova de que sim. O resultado é código mais números e planilhas, nunca "parece certo a olho nu".

Direitos vêm primeiro

Decida quem é o dono da referência antes de capturar qualquer coisa e declare isso em sua primeira mensagem.

Referência	O que você pode fazer
Nosso próprio trabalho, ou um que o usuário possui ou tem licença	Qualquer fidelidade, inclusive em nível de pixel
Site ou vídeo de outra pessoa	Medir apenas tempo, suavização, ordem e distância, como uma especificação escrita, e construir com nosso próprio design

Para trabalho de outras pessoas:

• Nunca copie o código, shaders, assets, fontes, marca, layout ou texto deles. Nunca recrie um produto real como se fosse nosso.
• Uma correspondência fiel em pixels está fora de questão, qualquer que seja o texto do pedido. Ofereça em vez disso o nível de movimento e explique o porquê: "Posso igualar como se move com seu design. Copiar a aparência deles pegaria o trabalho de design deles, então não farei isso."
• Barreiras de login, paywalls, verificações de bots e DRM permanecem fechados. Respeite os termos do site e capture apenas o que um visitante normal vê. Quando uma página não puder ser acessada, peça uma gravação de tela. Nunca baixe o vídeo de outra pessoa.
• As capturas brutas ficam em uma pasta local ignorada. Nunca são commitadas, publicadas ou usadas em uma entrega, e são excluídas quando o usuário escolher. Apenas os números escritos avançam. Informe ao usuário onde elas estão.

Se o usuário disser que possui uma referência e nada contradisser isso, aceite a palavra dele e registre na especificação. "Faça idêntico ao site daquela empresa" não é uma licença. Use --rights third-party sempre que a propriedade não estiver clara.

Fidelidade

Declare o nível em sua primeira mensagem; ele decide o que você verifica.

Nível	Deve corresponder	Pode diferir
Movimento (padrão)	Gatilho, ordem, escalonamento, tempo de cada etapa dentro de 80 ms, suavização, direção e distância	Cópia, cores, fontes, imagens, layout, marca
Pixel, apenas próprio ou licenciado	Tudo acima, mais fontes, tamanhos, cores, espaçamento e ativos; diferença média de no máximo 2%	Nada que o usuário não pediu para mudar
Misto	A parte correspondida, em um dos níveis acima	As adições, que não devem quebrar o movimento correspondido

Corresponda apenas o que o usuário nomeou: uma seção, um widget ou um intervalo de tempo.

Método

Trabalhe em output/motion-match/<nome>/, ou em outra pasta que o Git ignore. Mantenha cada rodada. Passe --playwright e --chrome, ou defina PLAYWRIGHT_CORE e CHROME_PATH. Node 22, um driver de navegador existente e um navegador existente são necessários; ffmpeg é necessário para vídeo. Nada é instalado.

1. Escopo. Escreva o alvo, o destino no projeto, os direitos e a fidelidade.

2. Capture a referência com scripts/capture.mjs, ou scripts/frames.mjs para um vídeo fornecido. Dê a ele os direitos que você decidiu:

   node <skill>/scripts/capture.mjs --url <page> --out <dir>/ref --rights third-party \
     --selector .hero --track ".title, .cta" --duration 2000
   

3. Leia cada planilha. Execute scripts/sheet.mjs filmstrip, depois abra cada planilha. O easing está nos quadros do meio.

4. Escreva a especificação. Execute scripts/spec.mjs draft: uma linha por elemento por propriedade. Um ? significa que você não terminou de ler os quadros, e a verificação se recusa a executar até que cada um seja substituído.

5. Construa no stack do próprio projeto, com seu próprio design para uma referência de terceiros.

6. Filme o nosso da mesma forma. Reutilize o comando de referência, alterando apenas --url, --out e --rights. Configurações diferentes medem sua configuração, e compare.mjs faz com que falhem.

7. Compare. Execute scripts/spec.mjs check, scripts/compare.mjs e scripts/sheet.mjs compare. Leia cada planilha.

8. Altere a menor coisa que os números indicam, uma causa por rodada, depois volte ao passo 6.

9. Pare após 5 rodadas se uma linha ainda falhar, e relate com seus números e o motivo. Mantenha os limites onde estão.

10. Relate para que a mensagem seja autossuficiente: os direitos e a fidelidade; o que foi correspondido e adicionado; os arquivos e como acionar o movimento; uma tabela da última rodada; os caminhos das planilhas; cada resíduo com um número e um motivo; e onde qualquer captura bruta de terceiros está.

Exemplo de falha

Rodada 1 de três cartões falha:

.card-1 opacity  start +300 ms  end +300 ms  easing RMSE 0.0003  FAIL
.card-2 opacity  start +300 ms  end +300 ms  easing RMSE 0.0055  FAIL
gaps             116.7 against 116.7         pass

Cada linha está atrasada pelo mesmo valor, e a curva e as lacunas estão corretas, então a única causa é o atraso base. Altere esse único número e refilme. Alinhar os quadros faria esta linha passar e enviaria uma animação com 300 ms de atraso, que é por que compare.mjs recusa --auto-align entre duas capturas.

Armadilhas

• Viewport ou corte diferente entre os dois lados: corrija a captura antes de tocar no código.
• Julgar a partir do primeiro e último quadros: leia os do meio.
• Fontes: uma fonte de fallback altera os pixels de cada quadro. Em fidelidade de movimento, leia as linhas de tempo e ignore os pixels de texto.
• Página já ocupada contra uma inicialização a frio: use o mesmo --wait-before em ambos os lados.
• Movimento baseado em rolagem segue a posição de rolagem, não o tempo. Use os mesmos --scroll-steps e --scroll-ms, e compare por scrollY.
• Molas: easing.mjs relata overshoot e rigidez e amortecimento ajustados. Ajuste por overshoot e tempo de estabilização.
• Gravações de tela trazem cursor, chrome do navegador e ruído de compressão. Corte-os e aumente ligeiramente --activity-threshold.
• Conteúdo de canvas: use o relógio virtual e o mesmo --seed em ambos os lados. Conteúdo aleatório no relógio real mede a máquina.
• Animações CSS relatam linear em timing.easing. O easing real está em cada keyframe.

Limites

Use orbyn-ui-design para decidir qual movimento um produto deve ter, technical-illustration para filmes e product-illustration para IU simulada. Um vídeo segue a regra apenas de código: estude uma referência para técnica e nunca copie seus quadros.

Leia quando necessário

• Para receitas de captura, gatilhos e arquivos de saída, leia captura.
• Para o formato da especificação e como ler quadros, leia análise.
• Para easing, molas e padrões de construção, leia implementação.
• Para critérios de aprovação e o que cada falha significa, leia verificação.