Captura de referência de UI
O código fornece estrutura, estilos, strings e ícones. Ele não fornece o que acontece em tempo de execução (o que um backend responde, em qual ordem as coisas aparecem, quanto tempo o aplicativo real espera), e não diz nada sobre a interface de outra empresa. Esta skill preenche essas lacunas com referências, em uma ordem fixa de preferência, e nunca improvisa no navegador pessoal de alguém.
Essa última regra tem um histórico. Na produção de onde essas skills vêm, um agente teve permissão para entrar no navegador logado do revisor para capturar um aplicativo ao vivo. Os fluxos ao vivo travaram, o agente continuou fazendo etapas de "limpeza" depois que o revisor disse para parar, deixou itens soltos em um espaço de teste, e a sessão terminou mal após cerca de 68 minutos sem nada utilizável construído. As mesmas capturas foram posteriormente recuperadas da transcrição da sessão em minutos. Referências offline primeiro; um navegador apenas quando o usuário pedir um, isolado, e parado no momento em que disser para parar.
Onde as coisas vão
- Entradas (gravações, exportações, capturas de tela fornecidas pelo usuário): copie-as para
products/<slug>/references/<name>/assim que chegarem. Pastas de Downloads e as pastas de captura temporárias do SO são limpas, e uma gravação na produção de origem estava em uma pasta que o sistema teria deletado. Nomes de gravação do macOS contêm um espaço estreito sem quebra (U+202F) antes de AM/PM: encontre-os com um glob, não digitando o nome. - Material de trabalho (milhares de quadros, capturas recuperadas, OCR bruto): uma pasta temporária fora de
todo repositório, ex.
$TMPDIR/pvs-<slug>-<name>/. - Resultados que valem a pena manter (a linha do tempo do OCR, quadros-chave com dados reais recortados, a análise):
references/<name>/, citados a partir de SOURCES.md.
Gravações e capturas de um espaço de trabalho real contêm nomes reais de clientes, e-mails, números de telefone, ids internos e conversas de outras pessoas. Eles nunca vão para o repositório do workbench, e o vídeo nunca os mostra: a seção 1, passo 6 lista o que deve mudar.
Escolha a técnica
| Você tem | Técnica | Leia |
|---|---|---|
| Uma gravação de tela do produto | 1. Analisar a gravação | references/recording-analysis.md |
| Sessões anteriores que visualizaram o aplicativo | 2. Recuperar capturas de transcrições | este arquivo, seção 2 |
| Um aplicativo que pode ser executado localmente | 3. Instância local compilada como produção | references/local-instance.md |
| Produto de outra empresa | 4. Pesquisa web, apenas fontes públicas | references/third-party-ui-prompt.md |
| Nada (uma chamada telefônica, um cartão final, texto gerado) | Projete a partir do kit e marque-o | product-truth (mock) |
Tente-os nessa ordem. Antes de pedir a alguém para gravar, verifique a seção 2: as capturas podem já existir. Se nenhuma das quatro funcionar, diga isso; não recorra ao navegador do revisor.
1. Analisar uma gravação de tela
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/ui-reference-capture/scripts"
W="$TMPDIR/pvs-acme-board" # temporário, fora do repositório
bash "$S/frames.sh" references/board/rec.mov "$W" --fps 10 --logical-width 1440
bash "$S/ocr.sh" "$W/logical" "$W/ocr.jsonl" # apenas macOS
"$PVS_HOME/bin/pvs-py" "$S/ocr_events.py" "$W/ocr.jsonl" references/board/ocr-timeline.txt --fps 10 \
--region "panel=0.6,0,1,[email protected]"
"$PVS_HOME/bin/pvs-py" "$S/grid.py" sheet "$W/overview.png" "$W/logical" --every 20 --cols 4
frames.shescreve miniaturas pequenas (detecção de mudança) e quadros na largura lógica do aplicativo (uma gravação retina é 2x: a largura lógica é metade da largura em pixels), então um pixel de quadro é um CSS px do aplicativo reconstruído.ocr.shcompilaocr.swift(Apple Vision) uma vez em uma pasta de cache e escreve uma linha JSON por quadro. No Linux, ele sai com "unsupported": leia as folhas de contato.ocr_events.pytransforma OCR por quadro em intervalos estáveis,start-end [region] text. Essa linha do tempo fornece as strings exatas que o aplicativo real mostra e quando, o que é melhor do que adivinhar a partir de um vídeo a olho nu.grid.py sheetcria folhas de contato: uma visão geral a cada 2 s, depois folhas densas de 10 fps por fase.grid.py overlaydesenha uma grade em px lógicos em um quadro para medição.- Salve quadros-chave como
references/<name>/frames/<t>-<state>.jpg(recortados de dados reais). - Escreva
references/<name>/analysis.mdcom a estrutura emreferences/recording-analysis.md: a linha do tempo real com strings exatas, movimento medido (quanto tempo um painel leva para abrir, quanto tempo o cursor descansa), uma tabela "deve mudar para o vídeo" (nomes reais, e-mails, telefones, espaços de trabalho, ids internos, longas esperas, cromada do SO, como o Dock) e lacunas do produto a serem levantadas antes que alguém construa sobre elas (uma etapa que a história precisa e que a gravação mostra falhando).
As gravações escondem lacunas quando as esperas são comprimidas; anote cada espera que você encurtar.
2. Recuperar capturas de sessões passadas
Cada imagem que uma ferramenta retornou em uma sessão do Claude Code (capturas de tela do navegador, capturas de janela, imagens lidas) e cada imagem colada no chat é armazenada no JSONL dessa sessão.
"$PVS_HOME/bin/pvs-py" "$S/recover_transcript_images.py" ~/.claude/projects/<project>/<session>.jsonl \
[--from-line N] [--tool screenshot]
Sem uma pasta de saída, ele escreve em uma nova pasta temporária e recusa qualquer pasta dentro de uma árvore de trabalho
git, porque essas capturas mostram contas reais. Ele escreve index.tsv (arquivo, hora, ferramenta, entrada)
para que você possa encontrar as telas de que precisa. Revise-as em folhas de contato (`grid.py sheet
3. Uma instância local compilada como produção
A referência mais fiel quando o aplicativo pode ser executado na máquina do usuário: compile-o a partir do
commit de produção com os argumentos de compilação de produção, alimente-o com dados fictícios, isole-o
de todo sistema compartilhado e capture-o com um navegador headless. Leia
references/local-instance.md antes de começar; o usuário deve concordar em executar seu aplicativo, e ele
nunca usa suas contas ou bancos de dados compartilhados.
4. UI de terceiros
Para telas de outra empresa, lance um subagente de pesquisa com
references/third-party-ui-prompt.md: apenas fontes públicas (documentação oficial, centrais de ajuda, kits de
imprensa, capturas de tela de marketing, demonstrações públicas incorporadas de propriedade do fornecedor), nunca um login, nunca
um envio ou uma reserva, cerca de 30 minutos. Cada valor retorna marcado como verificado, medido ou
inferido. Prefira o componente próprio do produto quando ele tiver um (um produto que renderiza uma prévia
de um aplicativo de chat tem um componente de prévia; use-o em vez de reconstruir o aplicativo de chat). Mostre uma tela
completa de terceiros apenas quando ela provar uma integração real; em outros lugares, use logotipos e selos dentro
do produto.
Paridade: prove que a reconstrução corresponde
"$PVS_HOME/bin/pvs-py" "$S/pair.py" snapshots/nocam-12.4s.png references/board/frames/12.4-board.png \
640 40 1100 300 "$W/pair-board-header.png" --ref-scale 2 --logical-width 1440 --render-width 1920
Pegue nosso snapshot com a câmera na escala 1 (uma cópia da composição com
#camera{transform:none!important}), recorte a mesma caixa lógica de ambos e empilhe-os. O
script imprime a diferença absoluta média por canal; itere até que pare de cair e a imagem
empilhada não mostre deslocamento. Meça em px do aplicativo e converta explicitamente: escalas confusas foram uma
fonte recorrente de coordenadas erradas.
Regras e porquê
- Nunca o navegador ou perfil pessoal do revisor, e nada obtido dele (fontes, ícones, armazenamento). Quando alguém disser para parar, pare toda ação do navegador imediatamente, incluindo a limpeza.
- Nunca faça login, nunca leia tokens ou armazenamento do navegador. Se uma captura precisar de um login, a pessoa digitá sua própria senha em sua própria sessão, ou a captura não acontece.
- Material recuperado e gravado permanece privado. Pasta temporária primeiro, apenas cópias recortadas.
- Marque todo valor inferido. Uma referência que é meio adivinhada deve dizer qual metade.