Compositor de demonstração de UI
Um vídeo de produto aqui é uma composição HyperFrames construída a partir de três arquivos que você escreve por vídeo e um kit compartilhado por cada vídeo:
| Arquivo | O que é | Quem edita |
|---|---|---|
video/build.py | A tabela de batidas T: cada tempo derivado da temporização das palavras | Você |
video/src/template.tpl | A UI reconstruída, as camadas de tela e a linha do tempo GSAP | Você |
video/src/app.css | O CSS da UI do produto, valores literais de specs/ | Você |
kit/stage.css, kit/titles.css, kit/stage.js | Camadas do palco e helpers seguros para busca | Esta skill |
products/<slug>/kit/tokens.css, fonts/, icons/, ui/ | Tokens, fontes, ícones e peças de UI compartilhadas do produto | product-kit |
video/index.html | Gerado por build.py. Nunca edite manualmente | Ninguém |
scripts/buildlib.py faz a parte genérica de cada build (temporizações, porta de assinatura,
tags de áudio, inlining, placeholders, ícones, o clamp da câmera) para que build.py permaneça uma lista curta
de batidas.
O modelo do palco
#root > #stage > #camera > #blurWrap > #app o produto, em pixels da aplicação
> #veil, .pvs-ttl, #endS, #lock, #fade espaço da tela, 1920x1080
- A UI é reconstruída em sua viewport real e dimensionada uma vez.
#apptemproduct.yaml app_canvas.logicalpixels CSS (por exemplo 1440x810), dimensionado para 1920x1080 por uma transformação. O CSS de produção mantém seus pixels literais, então um valor de especificação é colado sem alterações e cada medida é comparada 1:1 com o código. Escolha uma largura de desktop acima do ponto de quebra da aplicação, em 16:9; se houver uma gravação de tela, use seu tamanho lógico. Uma tela que não é 16:9 é letterboxed (buildlib avisa). - As posições são medidas, nunca digitadas.
S.box(sel)soma os offsets até#appdepois que as fontes carregam. Se o CSS mudar, o cursor ainda pousa no botão. - O cursor e a ondulação do clique são os últimos filhos de
#app, então eles escalam e desfocam com o produto. Pop-ups (.pvs-modal) e toasts (.pvs-toast-slot) vivem em#apptambém. - Apenas
#camerase move e apenas#blurWrapdesfoca. Nunca faça tween em#appou#stage.
Enquadramento: 1x página cheia por padrão
Padrão para cada batida de produto em 1x, página cheia, com pop-ups em seu tamanho natural e centralizados
da forma como o aplicativo os mostra. Push-ins são suaves (até video.max_zoom, 1.35 por padrão),
mantenha a seção inteira no quadro e nunca coloque uma borda de quadro através de um rótulo. Um enquadramento por
capítulo: faça o movimento atrás do título do capítulo enquanto o produto está fora de foco, ou como um
movimento de assinatura lento.
Por quê: na produção de onde essas skills vêm, um vídeo de configurações foi rejeitado duas vezes por zoom.
Um punch-in de 1,67x cortou rótulos pela metade ("Não consigo entender o que está acontecendo"), e enquadramentos posteriores
de cerca de 2x por coluna pareciam apertados mesmo sem nada cortado. O vídeo que o revisor apresentou como
modelo rodou em 1x o tempo todo. Uma tela mais afastada (mostrada a 50%) ou uma coluna de chat estreita
tolera mais: aumente max_zoom em product.yaml para aquele produto, não por batida.
b.cam() e S.cam() fixam acima de max_zoom e avisam. Detalhes e números:
references/framing-and-pacing.md.
Ritmo: capítulos são pausas
- Abra com contexto, nunca no meio da UI: logotipo, nome do produto e uma linha sobre o que é, sobre o produto fora de foco.
- Cada capítulo abre com um título de dois tons sobre o produto desfocado (desfoque mais um véu), segura por pelo menos cerca de 1,4 s, e o foco retorna pouco antes da palavra que nomeia a primeira ação. As mudanças de tela acontecem atrás do título, então não há cortes bruscos.
- Uma ideia por capítulo, uma mudança de cada vez, com 0,6 a 1 s de intervalo, uma pausa de cerca de 0,8 s no final de cada capítulo. Esperas reais do produto são comprimidas para 1 ou 2 s.
- A tela final mostra amplitude (o que mais o produto faz, com peças reais de UI), depois o lockup.
Por quê: um one-take denso com uma micro-ação a cada 0,5 s foi lido como polimento por seu criador e como ruído pelo revisor ("muito rápido, muita coisa de uma vez, opressivo"); zoom in e out nos resultados os tornou impossíveis de seguir. A versão calma com capítulos foi aprovada.
Cada batida está ancorada em uma palavra
b = buildlib.Build(__file__)
T, w, end = b.T, b.w, b.end
T["N2"] = T["ch1"] + 0.3 # colocar um id de clipe coloca aquele clipe
T["rack1"] = T["N2"] + w("N2", "after") - 0.25 # o foco retorna pouco antes de "after"
T["send1"] = max(T["type1"] + T["type1Dur"] + 0.4, end("N3") + 0.15)
w(clip, prefix, nth=1)é o início da primeira palavra que começa comprefix, relativo ao clipe. Ele levanta uma exceção quando a palavra está faltando (sem fallback silencioso: um fallback que silenciosamente coloca uma batida em um tempo padrão é como o movimento se afasta da voz despercebido).- Um evento de UI lidera a palavra que o nomeia por 0,05 a 0,45 s.
max()garante tanto a ordem da narração quanto "a UI terminou";end(k)éT[k]mais a duração do clipe (oub.dur(k, d)). - A velocidade de digitação é caracteres por segundo (cerca de 17 a 21), ou fixa para caber em uma batida.
- Cliques, digitação e pops recebem seu som no mesmo
T(b.click(t),b.typing(text, t, dur),b.pop(t)), então uma batida retemporizada move seu som também. - Regenerar uma linha de voz retemporiza todo o vídeo. Esse é o ponto.
Por quê: a temporização tem uma única fonte de verdade. Quando uma linha é regenerada, tudo ancorado a ela se move junto; segundos digitados manualmente ficam obsoletos na primeira regravação.
Fluxo de trabalho
- Leia
BRIEF.md(capítulos, enquadramento),COVERAGE.md(o que cada capítulo deve explicar na tela),specs/*.mdeTRUTH.md. Não invente UI: uma tela ou comportamento sem uma fonte emSOURCES.mdouspecs/fica de fora. - Reconstrua as telas em
src/template.tplesrc/app.cssa partir das especificações, com dados fictícios de product.yamlcast. Reutilize peças de produto dekit/ui/com{{UI:name}}em vez de copiá-las de outro vídeo (references/ui-component-library.md). - Escreva as batidas em
build.pye a linha do tempo no template com os helpers do kit (references/stage-kit.mdpara a API,references/beat-recipes.mdpara cada batida,references/end-screen-and-lockup.md). Siga a skill de movimento seguro para busca para cada tween. - Construa um rascunho e leia a tabela de batidas que ele imprime:
Antes de qualquer voz existir,PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)" "$PVS_HOME/bin/pvs-py" <video_dir>/video/build.py --draft--draft --fake-timingsinventa temporizações de palavras a partir delines.tsvpara que você possa organizar as telas. - Lint e verifique, a partir de
<video_dir>/video/:Espere 0 erros e 0 avisos de tempo de execução. Um aviso de lint é esperado para o palco monolítico:"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" . npx --yes [email protected] checkcomposition_file_too_large(o kit está inline). Em seguida, execute o segundocheckque o build imprime,check --at <tempos das batidas de configuração>: as amostras padrão geralmente pousam apenas em momentos desfocados, onde o kit oculta o texto do produto do passe de contraste (está desfocado de propósito), entãocontrast ... checked 0ali auditou nada que um espectador lê.checksozinho não é suficiente: ele passou em um vídeo onde itens em movimento estavam invisíveis na maior parte do seu caminho. Olhe para os frames. - Faça um snapshot de cada batida de configuração e olhe para cada imagem você mesmo. Marque-as com
b.snap(t, label)em build.py; o build imprime o comando exato:npx --yes [email protected] snapshot . --at 3.2,4.7,9.98 --no-end --describe false -o snapshots/setup--no-endcaptura apenas aqueles tempos;--describe falseimpede que frames sejam enviados para uma API de visão externa. Verifique o enquadramento (nada cortado em uma borda), o cursor em seu alvo, pop-ups centralizados em tamanho natural, títulos inteiros.--zoom "#toast" --zoom-scale 2recorta um elemento. Para testar um tween suspeito,--at <início>,<depois>deve corresponder a--at <depois>. - Renderize. Um rascunho para revisão, depois entrega uma vez que BRIEF.md esteja assinado (build.py imprime esta linha):
Em seguida, execute render-qa no MP4. Mantenha o MP4 de cada versão.npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality draft npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality delivery
A porta de assinatura
build.py se recusa a construir até que coverage_signed_by e claims_signed_by estejam definidos em
BRIEF.md (exit 2). --draft constrói de qualquer forma e carimba <meta name="pvs-draft" content="1">
em index.html; QA marca seu relatório como um rascunho e a entrega o recusa. Não assine em nome do
revisor, e não remova o meta: um rascunho é para olhar, nunca para enviar.
Por quê: na produção de onde essas skills vêm, 9 de 26 versões aconteceram porque um vídeo não explicava um recurso com o qual o revisor se importava, e ninguém havia escrito esses recursos antes de construir. A porta faz o acordo vir primeiro.
Regras que vêm de incidentes
- Corrija falhas de produção, mantenha a aparência. Mantenha layout, tokens e comportamento 1:1, mas corrija defeitos visíveis do aplicativo ao vivo (padding faltando, texto transbordando ou cortado, controles nativos cinza, um anel de foco deixado após um clique). Liste cada correção nas notas de BRIEF.md.
- Mostre o que é configurável quando o produto é configurável: as configurações sobre as quais um comprador perguntaria pertencem à tela, não apenas à narração.
- Feche um menu um quadro antes de abrir um modal sobre ele. Um menu suspenso aberto sob um novo diálogo deixou texto fantasma em uma renderização.
- Desvaneça apenas o conteúdo da tela final no lockup, mantenha seu fundo até que o lockup
esteja visível. Desvanecer ambos mostrou um quadro de UI nítida entre eles (
S.lockupfaz isso). - Passe o mouse antes do clique (classe
hovcerca de 0,12 s antes), cursor dentro após o primeiro rack e fora antes da tela final. - Nenhum nome de fornecedor ou proibido na UI, dados ou narração (product.yaml
banned_terms,names). Se uma tela real mostrar um, mantenha essa peça fora do quadro, e nunca a deixe visivelmente vazia. - Não renderize para mostrar progresso cedo. Itere com snapshots; renderize quando as batidas de configuração parecerem corretas.
Arquivos
| Caminho | Leia quando |
|---|---|
references/stage-kit.md | Você precisa da assinatura de um helper, um placeholder, uma variável CSS ou a API buildlib |
references/beat-recipes.md | Você constrói uma batida específica: abertura, capítulo, clique, digitação, streaming, pop-up, dropdown, toast, rolagem, push-in |
references/framing-and-pacing.md | Você escolhe um enquadramento ou um ritmo, ou o revisor diz "zoom", "rápido", "caótico" |
references/end-screen-and-lockup.md | Você constrói o final |
references/ui-component-library.md | Uma peça de UI aparecerá em mais de um vídeo, ou você está prestes a copiar marcação de outro vídeo |
scripts/buildlib.py | Você precisa de comportamento que a referência da API não cobre |
kit/stage.js | O mesmo, para os helpers da linha do tempo |
PVS_HOME/_template/video/video/ | O exemplo build.py, template.tpl e app.css de onde todo novo vídeo começa |