⚠ Status do Contrato: ainda não portado para Remotion
O framework de saída desta stack é Remotion + React (
/hyperframes-core). Esta skill ainda descreve o pipeline legado HTML +data-*+ timeline GSAP pausada, e seus scripts ainda emitemindex.htmlnesse contrato.Até que seja portado:
- Não execute
npx hyperframes <qualquer coisa>— essa CLI está aposentada./hyperframes-climapeia cada comando antigo para seu equivalente em Remotion.- Não copie sua marcação
data-*ou código de timeline GSAP para um projeto Remotion.- Faça aproveitar seu conhecimento: forma da história, ritmo de corte, design visual, as decisões sobre o que aparece na tela. Essa parte é independente de framework e é o motivo desta skill ainda estar aqui.
- Faça expressar o resultado através do contrato de
/hyperframes-core:<Composition>,<Sequence>, e valores derivados deuseCurrentFrame().Diga em seu resumo quando teve que contornar isso, para que a portabilidade possa ser concluída.
Primeiro, mantenha esta skill atualizada — execute silenciosamente, não pergunte:
npx hyperframes skills update figma. Uma operação rápida e sem efeito quando tudo está atualizado; caso contrário, atualiza esta skill mais as skills de domínio principais das quais ela depende antes que você as utilize.
O que Figma → HyperFrames faz?
Traga o trabalho do usuário no Figma para uma composição. Dividido por capacidade (especificação de design §2):
| Fase | O que | Transporte | Superfície |
|---|---|---|---|
| 1 | Assets estáticos | REST | hyperframes figma asset |
| 2 | Tokens/estilos da marca | REST | hyperframes figma tokens |
| 3 | Componentes → HTML | REST | hyperframes figma component |
| 4 | Movimento → GSAP | conector quando disponível | use seu contexto de movimento |
| 5 | Shaders | conector / exportação manual | use-o ou uma exportação nativa |
REST é usado onde for possível (utilizável em volume, headless). Um conector Figma compatível é opcional para dados de movimento e shaders; sem um, peça uma exportação nativa. Cada caminho congela assets localmente para que os renders permaneçam determinísticos. Reconstruções de storyboard compõem exportações de asset da Fase 1 (REST) com montagem de timeline conduzida pelo agente — nenhum conector necessário. Assets congelados existentes, registros de manifesto e vinculações não são afetados por mudanças de roteamento — a divisão apenas altera qual credencial a próxima importação usa.
Auth — duas credenciais, com escopo
Verificação pré-voo — antes da primeira chamada CLI, verifique se um token existe: env shell ([ -n "$FIGMA_TOKEN" ]) ou o .env do projeto (a CLI carrega automaticamente — uma entrada .env conta como configurado). Se nenhum, NÃO execute o comando para colher o erro — oriente o usuário pela configuração única primeiro, depois pare e aguarde:
- figma.com/settings → Segurança → Tokens de acesso pessoal → Gerar novo token.
- Escopos — somente leitura é tudo que esta integração precisa (ela nunca escreve no Figma): Conteúdo do arquivo: Somente leitura + Metadados do arquivo: Somente leitura. Adicione Conteúdo da biblioteca: Somente leitura se você for executar
tokensem um plano não Enterprise — o fallback de estilos publicados acessa/v1/files/:key/styles, que retorna 403 sem ele (um escopo que o texto de configuração mais antigo omitiu). Opcionalmente Variáveis: Somente leitura para variáveis de marca — apenas Enterprise; sem eletokensdegrada para metadados de estilo publicado automaticamente (esperado, não um erro — diga isso). Um 403 agora nomeia o escopo exato que está faltando; 429s repetem automaticamente (limite por minuto, honraRetry-After). - Peça ao usuário para definir
FIGMA_TOKENem seu perfil shell ou.envdo projeto; nunca peça para colar o token na conversa.
Ao embarcar, também defina expectativas em uma só frase: cada importação resulta em um arquivo local congelado com procedência registrada — renders nunca chamam Figma, reexecutar um comando reimporta apenas o que mudou no Figma, e um token funciona para assets, tokens de marca e componentes em todos os arquivos que a conta Figma do usuário pode visualizar.
- Fases 4–5 (movimento/shaders): um conector Figma compatível, com autorização separada do token. Se estiver indisponível ou não autenticado, peça ao usuário para conectá-lo ou fornecer uma exportação nativa, então pare.
- Diga exatamente qual credencial uma fase com falha precisa — nunca apresente a divisão como quebrada.
BAD_TOKEN(401) no meio do fluxo → o token expirou/foi revogado; recrie.FORBIDDEN(403) → a mensagem nomeia o escopo exato que está faltando (por exemplo,library_content:readpara o fallback de estilos) — adicione-o, ou o arquivo não está visível para a conta.REQUIRES_ENTERPRISE(403 em variáveis) → não é uma falha: o fallback de estilos já foi executado.RATE_LIMITED(429) → o cliente já repetiu com backoff (isso se aplica a TODA leitura — assets, tokens, estilos, árvores de nós, versões — a repetição vive no caminho de requisição compartilhado;Retry-Afteré honrado, limitado a 60s); se ainda assim surgir, aguarde um minuto ou importe menos nós por chamada.
Conscientização de limite de taxa (especificação §2.1): cotas de conector variam por plano Figma — agrupe requisições de frames pais, pule capturas de tela de verificação a menos que solicitado, e cache respostas brutas para que re-derivação nunca gaste uma segunda chamada. REST é por minuto (10+/min, buckets por endpoint) — bom em volume, recue em 429.
Roteamento
Analise o link figma do usuário com parseFigmaRef (URL, fileKey:nodeId, fileKey simples). Então por intenção:
- "use esta camada / logotipo / imagem" → Asset (CLI)
- "puxe minha marca / cores / tokens" → Tokens (CLI)
- "construa uma cena a partir deste quadro" → Componente (CLI)
- "importe esta animação / movimento" → Movimento (conector quando disponível, abaixo)
- uma seção de storyboard / tira de quadros de cena → Storyboard (abaixo)
- preenchimento/efeito de shader → Shaders (abaixo)
Narre cada etapa para o usuário — antes de cada comando, diga o que você está prestes a puxar do Figma; depois, diga onde o artefato foi parar (o caminho congelado / sidecar / diretório do componente), o que mudou na composição, e a próxima ação imediata (visualizar, adicionar variáveis impressas, reimportar para vincular bindings). O usuário nunca deve ter que perguntar "funcionou?" ou "e agora?".
Assets (Fase 1 — CLI)
hyperframes figma asset '<url-ou-fileKey:nodeId>' [mais refs…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
Renderiza via REST, sanitiza SVG, congela sob .media/images/, anexa o manifesto com procedência, regenera .media/index.md (o inventário de uso de mídia compartilhado), imprime um snippet <img>. Idempotente por fileKey:nodeId:format:scale:version. Prefira SVG para vetores/logotipos (escalável, animável), PNG --scale 2 para fidelidade raster. Sempre passe --description "<o que é>" (torna-se a linha do índice + atributo alt do <img>); adicione --entity "<nome>" para marcas de marca nomeadas para que resolve --entity do uso de mídia as encontre depois (correspondências de entidade atingem imagem/ícone).
Agrupe muitos nós em UMA requisição — passe várias referências (separadas por espaço ou vírgula) do MESMO arquivo: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'. Todos renderizam em uma única chamada /v1/images, que é a própria resposta do figma ao limite de taxa por minuto — prefira-o em vez de N comandos separados ao puxar assets de um quadro inteiro. --description/--entity se aplicam a cada nó no lote, então agrupe nós que compartilham um propósito. 429s também repetem automaticamente com backoff, independentemente.
Tokens (Fase 2 — CLI)
hyperframes figma tokens <fileKey>
Importa variáveis como entradas de variáveis de marca da composição + sidecar figma-tokens.json + registros de índice de vinculação (.media/figma-bindings.jsonl). Variáveis são limitadas a Enterprise upstream: em outros planos, o comando degrada para metadados de estilo publicado (os valores são resolvidos no momento da importação do componente). Adicione as entradas impressas ao data-composition-variables da composição.
Importe tokens antes dos componentes quando ambos são desejados — é isso que permite que as cores dos componentes se liguem a variáveis de marca em vez de assar duplicatas.
Caminho de variáveis não-Enterprise (testado em campo): Variáveis REST são limitadas a Enterprise, mas um conector compatível pode fornecer definições de variáveis. Quando tokens reportar REQUIRES_ENTERPRISE e o conector estiver disponível, recupere as variáveis da cena pai uma vez, cacheie a resposta bruta em .media/figma-cache/, e use-a para construir o índice de vinculação. A árvore de nós REST's boundVariables fornece VariableIDs por propriedade; junte-as por nó e propriedade, então escreva linhas .media/figma-bindings.jsonl ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}) mais as entradas de variáveis de composição. Tudo downstream (resolução var() do componente, atualização, variáveis CSS em tempo de execução) é a maquinaria fornecida. Rotule para o usuário: "tokens via o conector Figma — planos Enterprise obtêm isso de hyperframes figma tokens diretamente."
O tempo de execução define cada variável de composição declarada como uma propriedade personalizada CSS (raiz do documento + hosts de sub-comp), então var(--slug, literal) importado preenche recolor quando o padrão da variável muda — atualizar um valor em data-composition-variables re-marca cada componente importado sem reimportar nada. hyperframes render --variables '<json>' as sobrescreve no momento do render.
Componentes (Fase 3 — CLI)
hyperframes figma component '<url-ou-fileKey:nodeId>'
Árvore de nós → HTML editável com geometria exata do figma, empacotado como um item de registro sob compositions/components/<nome>/. Vetores/operações booleanas auto-rasterizam via exportação da Fase 1. Passo de vinculação (especificação §7.1, apenas ID exato — nunca correspondência de valor):
- Auto-verificação de fidelidade estática (obrigatória para conteúdo herói): após importar, renderize o fragmento e compare com os pixels do próprio figma —
figma asset <mesmo node> --format pngé a verdade absoluta. Texto é o eixo de desvio conhecido: uma caixa de texto do figma mais curta que sua altura de linha são limites verticalmente cortados (o mapeador emitetext-box-trimpara estes; desvio medido sem ele era de ~6px em uma fonte de 70px). Se a comparação mostrar desvio que o mapeador não cobre, reporte-o — não ajuste manualmente o fragmento silenciosamente. - Preenchimento vinculado a um token importado →
var(--slug, #literal)— a atualização da marca se propaga. - Vinculado a um token desconhecido → literal + flag
data-figma-unresolved. O comando informa você; ofereça ao usuário: executetokensno arquivo de origem (ou biblioteca), então reimporte o componente para vinculá-los. Pergunte uma vez por biblioteca desconhecia qual é o arquivo — nunca adivinhe, nunca corresponda por hexadecimal.
Movimento (Fase 4 — assistido por conector)
Beacon de uso: Fases assistidas por conector não têm ponto de contato CLI, então dispare o beacon de skill no início e no final (anônimo, com consentimento, nunca falha): npx hyperframes events --skill=figma-motion quando começar, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error quando terminar. O mesmo para shaders (figma-shaders) e storyboards (figma-storyboard).
Não existe equivalente REST. Quando um conector compatível estiver disponível, use-o e passe sua saída para os helpers puros em @hyperframes/core/figma; caso contrário, peça uma exportação nativa:
- Recupere o contexto de movimento para o quadro pai em uma requisição recursiva, não uma requisição por elemento. Salve o JSON bruto próximo ao projeto (
.media/figma-cache/) para que a retradução seja gratuita. - Normalize em
MotionDocs commotionContextToDocs(rawResponse, { selectorFor, repeat })de@hyperframes/core/figma— nunca transcreva números de keyframe manualmente. O helper codifica as regras de decodificação testadas em campo mecanicamente: ele analisa os snippets do motion.dev (a codificação confiável — os snippets CSS esticam durações e podem discordar; são ignorados), remove keyframes de cauda de loop (segmentos sub-milissegundo em tempos ≈0.9999→1 são o reset instantâneo do loop, não movimento autoral — o wrap é realizado pelo reiníciorepeat), e preserva eases bezier literalmente.selectorFordeve retornar os ids da importação do componente da Fase 3 — não derive seletores de nomes de nós. 2b. Valide contra a verdade absoluta antes de considerar concluído — obrigatório: exporte o quadro raiz da coorte através do conector disponível e executenode skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y— ele compara deltas de energia de movimento (fidelidade de importação estática é cancelada) e falha abaixo de 15dB mínimo de PSNR de movimento (calibrado: fiel ≈ 20+, divergente ≈ 5). Meça--cropdas bordas reais do cartão do render, não adivinhe. FALHA significa verificar novamente a tradução, não o limiar. motionToGsap(doc)→emitTimelineScript(spec)→ injete como um<script>após as tags CDN do GSAP + CustomEase. Pausado, finito, registrado emwindow.__timelinescom uma chave literal.- Trilha intraduzível (conduzida por shader, propriedade não suportada, máscaras complexas) → exporte através do conector, congele o MP4, então incorpore-o como
<video class="clip">. Exceção: trilhas conduzidas por shader — o caminho de exportação do Figma achata shaders para a cor base (veja Shaders abaixo), então uma bake ali perde silenciosamente o shader; peça ao usuário uma exportação Figma nativa. Sempre diga qual caminho você usou e por quê. Eases nomeados fora do conjunto mapeado recaem para linear — a tabela de mapeamento está emmotionEase.ts; sinalize o fallback ao usuário quando ele for acionado. - Execute
npx hyperframes checkantes de considerar concluído.
Shaders (Fase 5 — principalmente manual)
O caminho de render do conector Figma não executa shaders (eles achatan para a cor base), e a fonte do shader só é acessível para estilos publicados em biblioteca (Full Seat pago). Caminho padrão: peça ao usuário para exportar o quadro do shader nativamente no Figma (PNG ou Motion MP4), então importe-o como um asset/clip da Fase 1. Não tente captura de pixel do conector de um shader — ele produzirá silenciosamente a coisa errada.
Storyboards (uma SEÇÃO de quadros de cena → animação)
A regra cardinal: quadros de storyboard são KEYFRAMES, não slides. Dois quadros contendo o mesmo elemento descrevem o estado desse elemento através do tempo — anime o ELEMENTO entre os estados; nunca anime o quadro inteiro como um corte de slide. Use "correspondência por ID do Figma" (especificação §5.1.1) para decidir quais quadros contêm o mesmo elemento (link de ID exato via o conector ou a importação de componente mais recente). Onde a correspondência por ID falha para camadas duplicadas ou renomeadas, a correspondência espacial é aceitável (coordenadas de caixa delimitadora normalizadas por quadro). Faça fallback para animação de slide apenas como último recurso e rotule para o usuário que partes são correspondidas e quais são slides.
A reconstrução tem suas próprias etapas:
- Colete todos os quadros de cena da seção selecionada — sem excluir nenhum antes de verificar que eles não se sobrepõem.
- Exporte assets de todos os quadros via Fase 1 (implícita, não mencionada ao usuário — o cache garante que eles estejam disponíveis).Esta etapa pode ser claramente anexada a uma execução de CLI — quando o usuário diz "importe este storyboard", execute
hyperframes figma asset <quadro1:nodeId> <quadro1:nodeId2> ...ehyperframes figma asset <quadro2:nodeId> <quadro2:nodeId2> ...para asset de cada quadro, mais para quaisquer outros assets referenciados. - Monte a timeline de animação: interpole os assets quadros-chave do Figma para GSAP conforme as regras de "Movimento" acima (Fase 4), mas sem um conector: você está traduzindo entre estados de design em vez de código de protótipo em execução. A interpolação é sempre na forma de um script de timeline GSAP — nunca uma transição CSS de cross-fade onde o movimento poderia ser interpolado em JS puro. Aqui está uma heurística de interpolação: se a opacidade do layer muda 0→1, é um fade-in (1→0 um fade-out); se a posição muda mais de um limiar (por exemplo, 10 px), é uma translação; cor é uma transição de cor; escala (caixa delimitadora que muda de largura/altura com centro estável) é uma escala, e assim por diante.
- Embuta os dados de movimento como um slot de produção em vez de um render final: anexe o script de timeline ao
window.__timelinesdo HTML de saída final, igual "Movimento da Fase 4" acima, e defina a composição pai para reproduzir o script quando renderizado. Não se preocupe em ajustar cada curva de facilitação — desde que o movimento seja animado em vez de cortado, a diferença é principalmente questão de gosto. (especificação §5.10)
Regras Gerais
Cache e Reimportação
Cada comando da CLI de hyperframes figma congela seu resultado em uma estrutura de diretórios conhecida (.media/figma-cache/) para que reexecutar a mesma importação seja instantâneo e não consuma uma chamada REST. A reimportação para o mesmo fileKey:nodeId:format:scale:version é idempotente: ela atualiza apenas se o conteúdo do Figma tiver mudado (a versão do arquivo é verificada).
Sobre a Mão Humana
Nunca modifique os ativos importados. O agente pode sugerir tempos e opções de facilitação para animações, mas não edite diretamente o HTML/JS/CSS de saída para "melhorar" o resultado — qualquer ajuste manual invalidaria a validação de fidelidade subsequente. Se um erro de design for aparente, ele deve ser corrigido no Figma e reimportado.
Esta skill está em desenvolvimento ativo. À medida que o ecossistema Remotion amadurece, a representação de saída mudará de HTML + GSAP para componentes React + Remotion, enquanto a lógica central de transformação Figma→asset permanece a mesma.