heygen-com/hyperframes

Instalação de plugins: Antes de comandos de configuração ou atualização, siga as regras de execução de plugins quando esta skill estiver dentro de um plugin HyperFrames. Instalações independentes mantêm as instruções de atualização abaixo.

Primeiro, mantenha esta skill atualizada — confirme com o usuário antes de executar: npx hyperframes skills update figma. Uma operação rápida e sem efeitos quando tudo está atualizado; caso contrário, atualiza esta skill e as skills de domínio principais das quais ela depende antes que você confie nelas.

Figma → HyperFrames

Traga o trabalho do usuário no Figma para uma composição. Dividido por capacidade (especificação de design §2):

Fase	O quê	Transporte	Superfície
1	Ativos estáticos	REST	hyperframes figma asset
2	Tokens/estilos de 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 sempre que possível (usável em volume, sem cabeçalho). Um conector Figma compatível é opcional para dados de movimento e shaders; sem ele, solicite uma exportação nativa. Cada caminho congela ativos localmente para que as renderizações permaneçam determinísticas. As reconstruções de storyboard compõem exportações de ativos da Fase 1 (REST) com montagem de linha do tempo orientada por agente — nenhum conector necessário. Ativos congelados existentes, registros de manifesto e vínculos não são afetados por mudanças de roteamento — a divisão apenas altera qual credencial a próxima importação usará.

Autenticação — duas credenciais, com escopo

Pré-voo — antes da primeira chamada CLI, verifique se um token existe: variável de ambiente do shell ([ -n "$FIGMA_TOKEN" ]) ou o .env do projeto (a CLI carrega automaticamente — uma entrada .env conta como configurada). Se nenhum dos dois existir, NÃO execute o comando para colher o erro — oriente o usuário pela configuração única primeiro, depois pare e aguarde:

1. figma.com/settings → Segurança → Tokens de acesso pessoal → Gerar novo token.
2. Escopos — somente leitura é tudo que esta integração jamais 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 tokens em 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 omitia). Opcionalmente Variáveis: Somente leitura para variáveis de marca — apenas Enterprise; sem ele, tokens degrada para estilos publicados automaticamente (esperado, não é um erro — diga isso). Um erro 403 agora nomeia o escopo exato que está faltando; erros 429 são repetidos automaticamente (limite por minuto, respeita Retry-After).
3. Faça o usuário configurar FIGMA_TOKEN em seu perfil do shell ou .env do projeto; nunca peça para ele colar o token na conversa.

Durante a integração, também estabeleça expectativas em uma só frase: cada importação resulta em um arquivo local congelado com proveniência registrada — as renderizações nunca chamam o Figma, reexecutar um comando reimporta apenas o que mudou no Figma, e um token funciona para ativos, 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 ele estiver indisponível ou não autenticado, peça ao usuário para conectá-lo ou fornecer uma exportação nativa, depois 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; gere novamente. FORBIDDEN (403) → a mensagem nomeia o escopo exato que está faltando (por exemplo, library_content:read para 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á tentou novamente com backoff (isso se aplica a TODA leitura — ativos, tokens, estilos, árvores de nós, versões — a repetição reside no caminho de requisição compartilhado; Retry-After é respeitado, limitado a 60s); se ainda assim aparecer, aguarde um minuto ou importe menos nós por chamada.

Consciência de limite de taxa (especificação §2.1): as cotas do conector variam por plano Figma — agrupe requisições de quadros pai, pule capturas de tela de verificação a menos que sejam solicitadas e armazene em cache respostas brutas para que a rederivação nunca gaste uma segunda chamada. REST é por minuto (10+/min, buckets por endpoint) — funciona bem em volume, reduza a frequência em caso de 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" → Ativo (CLI)
• "pegue 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 extrair do Figma; depois disso, 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 ligações). O usuário nunca deve precisar perguntar "funcionou?" ou "e agora?".

Ativos (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 em .media/images/, anexa o manifesto com proveniência, regenera .media/index.md (o inventário de uso de mídia compartilhada), imprime um trecho <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 + <img alt>); adicione --entity "<nome>" para marcas nomeadas para que a resolução de media-use resolve --entity as encontre depois (correspondências de entidade funcionam entre 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'. Todas renderizam em uma única chamada /v1/images, que é a própria resposta do Figma ao limite de taxa por minuto — prefira isso a N comandos separados ao extrair todos os ativos de um quadro. --description/--entity aplicam-se a todos os nós no lote, então agrupe nós que compartilham um propósito. Erros 429 também são repetidos automaticamente com backoff.

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 ligação (.media/figma-bindings.jsonl). As variáveis são limitadas ao 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 permite que as cores do componente sejam vinculadas a variáveis de marca em vez de criar duplicatas.

Caminho de variáveis não Enterprise (testado em campo): As variáveis REST são limitadas ao Enterprise, mas um conector compatível pode fornecer definições de variáveis. Quando tokens relata REQUIRES_ENTERPRISE e o conector está disponível, recupere as variáveis da cena pai uma vez, armazene a resposta bruta em cache em .media/figma-cache/ e use-a para construir o índice de ligação. O boundVariables da árvore de nós REST fornece VariableIDs por propriedade; junte-os por nó e propriedade, depois escreva linhas .media/figma-bindings.jsonl ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}) mais as entradas de variáveis da composição. Tudo a jusante (resolução de componente var(), 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 diretamente de hyperframes figma tokens."

O tempo de execução define cada variável de composição declarada como uma propriedade personalizada CSS (raiz do documento + hosts de subcomponentes), então var(--slug, literal) importada preenche a recolorização quando o padrão da variável muda — atualizar um valor em data-composition-variables renova a marca de cada componente importado sem reimportar nada. hyperframes render --variables '<json>' as substitui no momento da renderização.

Componentes (Fase 3 — CLI)

hyperframes figma component '<url-ou-fileKey:nodeId>'

Árvore de nós → HTML editável na geometria exata do figma, empacotado como um item de registro em compositions/components/<nome>/. Vetores/operações booleanas são auto-rasterizados via exportação da Fase 1. Passagem de ligaçã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 principal): após importar, renderize o fragmento e compare com os pixels do próprio figma — figma asset <mesmo nó> --format png é a verdade absoluta. Texto é o eixo de desvio conhecido: uma caixa de texto do figma mais curta que sua altura de linha tem limites verticalmente cortados (o mapeador emite text-box-trim para estes; o desvio medido sem ele era de ~6px em uma fonte de 70px). Se a comparação mostrar desvio que o mapeador não cobre, relate — não ajuste o fragmento manualmente em silêncio.
• Preenchimento vinculado a um token importado → var(--slug, #literal) — a atualização da marca se propaga.
• Vinculado a um token desconhecido → literal + sinalizador data-figma-unresolved. O comando informa você; ofereça ao usuário: execute tokens no arquivo de origem (ou biblioteca) e reimporte o componente para vinculá-los. Pergunte uma vez por biblioteca desconhecida qual arquivo ela é — nunca adivinhe, nunca corresponda por hexadecimal.

Movimento (Fase 4 — assistido por conector)

Beacon de uso: as fases assistidas por conector não têm ponto de contato CLI, então dispare o beacon da skill no início e no final (anônimo, com consentimento, nunca falha): npx hyperframes events --skill=figma-motion quando você 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 entregue sua saída aos helpers puros em @hyperframes/core/figma; caso contrário, solicite uma exportação nativa:

1. 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 ao lado do projeto (.media/figma-cache/) para que a retradução seja gratuita.
2. Normalize em MotionDocs com motionContextToDocs(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 trechos motion.dev (a codificação confiável — os trechos CSS esticam as durações e podem discordar; eles são ignorados), remove keyframes finais de loop-wrap (segmentos submilissegundos em tempos ≈0,9999→1 são o reset instantâneo do loop, não movimento criado — o wrap é realizado pela reinicialização de repeat) e preserva eases bezier literalmente. selectorFor deve 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 declarar pronto — obrigatório: exporte o quadro raiz da coorte através do conector disponível e execute node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y — ele compara deltas de energia de movimento (a fidelidade de importação estática se cancela) e falha abaixo de 15dB de PSNR de movimento mínimo (calibrado: fiel ≈ 20+, divergente ≈ 5). Meça --crop a partir das bordas reais do cartão na renderização, não adivinhe. FALHA significa verificar a tradução, não o limite.
3. motionToGsap(doc) → emitTimelineScript(spec) → injete como um <script> após as tags CDN do GSAP + CustomEase. Pausado, finito, registrado em window.__timelines com uma chave literal.
4. Faixa intraduzível (orientada por shader, propriedade não suportada, máscaras complexas) → exporte através do conector, congele o MP4 e incorpore-o como <video class="clip">. Exceção: faixas orientadas por shader — o caminho de exportação do Figma achata shaders para a cor base (veja Shaders abaixo), então uma consolidação aí perde silenciosamente o shader; peça ao usuário uma exportação nativa do Figma. Sempre diga qual caminho você usou e por quê. Eases nomeadas fora do conjunto mapeado caem para linear — a tabela de mapeamento vive em motionEase.ts; sinalize o fallback ao usuário quando ele ocorrer.
5. Execute npx hyperframes check antes de declarar pronto.

Shaders (Fase 5 — principalmente manual)

O caminho de renderização do conector do Figma não executa shaders (eles são achatados para a cor base), e a origem 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) e importe-o como um ativo/clipe 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: os quadros do 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 reproduza os quadros como uma sequência de imagens estáticas. Um logotipo desenhado em quatro quadros consecutivos em y decrescente é UM elemento subindo através de quatro keyframes. Reproduzir os quadros do storyboard consecutivamente é o modo de falha; reconstruir as linhas do tempo do elemento que eles implicam é o trabalho.

Os arquivos de storyboard seguem uma gramática que você pode analisar mecanicamente — não olhe, decodifique:

1. Unidades de cena: dentro da SEÇÃO, cada nó do tamanho de um quadro é uma cena — tanto FRAMEs nomeados quanto RECTANGLEs soltos de quadro inteiro (designers colam imagens estáticas diretamente na seção). Filtre por tamanho (≈ proporção da composição, por exemplo, >1400×900), não por tipo de nó ou nome.
2. Ordem = posição x (linha principal se a tira quebrar). Classifique as cenas por absoluteBoundingBox.x.
3. Diferença entre adjacentes...

... [truncado para tradução]