Drama2557/4RealDigital-Video-Studio

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, ela atualiza esta skill e as skills de domínio principal das quais ela depende antes de você utilizá-las.

Figma → HyperFrames

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

Fase	O que	Transporte	Superfície
1	Assets 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	usar seu contexto de movimento
5	Shaders	conector / exportação manual	usá-lo ou uma exportação nativa

REST é usado sempre que possível (utilizável em volume, sem cabeça). Um conector Figma compatível é opcional para dados de movimento e shader; sem um, solicite uma exportação nativa. Cada caminho congela assets localmente para que as renderizações permaneçam determinísticas. As reconstruções de storyboard compõem exportações de assets da Fase 1 (REST) com montagem de linha do tempo orientada por agente — nenhum conector necessário. Assets congelados existentes, registros de manifesto e ligações não são afetados por alterações de roteamento — a divisão apenas altera qual credencial a próxima importação usa.

Autenticação — duas credenciais, com escopo

Pré-voo — antes da primeira chamada CLI, verifique se um token existe: env do shell ([ -n "$FIGMA_TOKEN" ]) ou o .env do projeto (a CLI carrega automaticamente — uma entrada .env conta como configurada). Se nenhum existir, NÃO execute o comando para obter 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 o 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 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 403 agora nomeia o escopo exato ausente; 429s são repetidos automaticamente (limite por minuto, respeita Retry-After).
3. Peça ao usuário para definir FIGMA_TOKEN em seu perfil do shell ou .env do projeto; nunca peça para colar o token na conversa.

Durante a integração, também defina expectativas em uma única 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 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, 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 ausente (ex.: 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 — assets, 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 frames pai, pule capturas de tela de verificação a menos que solicitado, e armazene em cache respostas brutas para que a rederivação nunca gaste uma segunda chamada. REST é por minuto (10+/min, buckets por endpoint) — bom em volume, faça backoff em 429.

Roteamento

Analise o link figma do usuário com parseFigmaRef (URL, fileKey:nodeId, fileKey simples). Em seguida, por intenção:

• "usar esta camada / logotipo / imagem" → Asset (CLI)
• "puxar minha marca / cores / tokens" → Tokens (CLI)
• "construir uma cena a partir deste frame" → Componente (CLI)
• "importar esta animação / movimento" → Movimento (conector quando disponível, abaixo)
• uma seção de storyboard / tira de frames 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, 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?".

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 em .media/images/, anexa o manifesto com proveniê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 + <img alt>); adicione --entity "<nome>" para marcas nomeadas para que media-use resolve --entity as encontre depois (correspondências de entidade funcionam em imagem/ícone).

Agrupe vários nós em UMA requisição — passe várias refs (separadas por espaço ou vírgula) do MESMO arquivo: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'. Todas são renderizadas 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 um conjunto inteiro de assets de um frame. --description/--entity se aplicam a todos os nós 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 ligação (.media/figma-bindings.jsonl). Variáveis são controladas pelo 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 se liguem a variáveis de marca em vez de criar duplicatas.

Caminho de variáveis não-Enterprise (testado em campo): variáveis REST são controladas pelo 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-as 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 var() do componente, atualização, variáveis CSS de tempo de execução) é a mecânica 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-componentes), então o var(--slug, literal) importado preenche a recolor quando o padrão da variável muda — atualizar um valor em data-composition-variables renomeia 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-rasterizadas 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 reais do 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-o — não ajuste o fragmento manualmente silenciosamente.
• 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; ofereça ao usuário: execute tokens no arquivo de origem (ou biblioteca) e depois reimporte o componente para vinculá-los. Pergunte uma vez por biblioteca desconhecida qual 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 da skill no início e no final (anônimo, com consentimento, nunca falha): npx hyperframes events --skill=figma-motion quando você iniciar, 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 frame 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.
2. Normalize em MotionDocs com motionContextToDocs(respostaBruta, { 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 motion.dev (a codificação confiável — os snippets CSS alongam as durações e podem discordar; eles são ignorados), remove keyframes finais de loop-wrap (segmentos de submilissegundo em tempos ≈0.9999→1 são o reset instantâneo do loop, não movimento criado — o wrap é realizado pela reinicialização repeat), e preserva eases bezier textualmente. 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 considerar concluído — obrigatório: exporte o frame 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 da importação estática se cancela) e falha abaixo de 15dB de PSNR mínimo de movimento (calibrado: fiel ≈ 20+, divergente ≈ 5). Meça --crop das bordas reais do cartão da renderização, não adivinhe. FALHA significa verificar a tradução novamente, não o limite.
3. motionToGsap(doc) → emitTimelineScript(especificação) → 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, depois 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 gravação lá perde silenciosamente o shader; solicite ao usuário uma exportação nativa do Figma. Sempre diga qual caminho você usou e por quê. Eases nomeados fora do conjunto mapeado caem para linear — a tabela de mapeamento vive em motionEase.ts; sinalize o fallback ao usuário quando ele disparar.
5. Execute npx hyperframes check antes de considerar concluído.

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: solicite ao usuário que exporte o frame do shader nativamente no Figma (PNG ou MP4 de movimento) e depois importe-o como um asset/clip da Fase 1. Não tente captura de pixel do conector de um shader — isso produzirá silenciosamente a coisa errada.

Storyboards (uma SEÇÃO de frames de cena → animação)

A regra cardinal: frames de storyboard são KEYFRAMES, não slides. Dois frames contendo o mesmo elemento descrevem o estado desse elemento através do tempo — anime o ELEMENTO entre os estados; nunca reproduza os frames como uma sequência de imagens estáticas. Um logotipo desenhado em quatro frames consecutivos com y decrescente é UM elemento subindo através de quatro keyframes. Reproduzir frames de storyboard consecutivamente é o modo de falha; reconstruir as linhas do tempo dos elementos que eles implicam é o trabalho.

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

1. Unidades de cena: dentro da SEÇÃO, todo nó do tamanho de um frame é uma cena — tanto FRAMEs nomeados quanto RECTANGLEs soltos em tamanho de frame (designers colam imagens estáticas diretamente na seção). Filtre por tamanho (≈ proporção da composição, ex.: >1400×900), não por tipo de nó ou nome.
2. Ordem = posição x (linha principal se a tira quebrar). Ordene cenas por absoluteBoundingBox.x.
3. Diferencie frames adjacentes em cadeias de elementos — é aqui que a animação vive. Combine filhos em frames consecutivos: primeiro por nome (mesmo nome = mesmo elemento → tween seu x/y/w/h relativo entre estados), depois por semelhança geométrica (tamanho semelhante + centroide próximo — correspondência aproximada com tolerância de 20px é segura). Elementos órfãos (vistos no frame 1, não no frame 2) desaparecem (animar para opacity:0 + sumir de display:none). Novos elementos no frame 2 (não no frame 1) aparecem (animar de opacity:0).
4. Converta essas cadeias em uma grade de keyframes — para cada elemento, cada frame onde ele aparece é um keyframe. Se ele não aparecer em um frame subsequente, assuma opacity:0 para o keyframe final daquele elemento.
5. Gere um script GSAP que tweena cada elemento através de seus keyframes com easing (assumir "power2.out" a menos que seu dif fsame geometrico consistente sugira um "linear" — nunca crie eases personalizados não fornecidos pelo Figma para storyboards). Inclua o elemento <style> com opacity:0 para elementos componentes que serão animados. Defina timeline.play() no final.

Ferramenta de decodificação automática: Execute npx hyperframes figma storyboard '<seção-fileKey:sectionNodeId>' — ela executa a lógica de decodificação programática acima e imprime o script GSAP (mais o manifesto de assets congelados para quaisquer cenas que contenham imagens do Figma, que são exportadas e congeladas primeiro). A ferramenta também escreve o script de timeline em compositions/timelines/storyboard-<sectionName>.js, registra a composição pai para incluir a timeline, e adiciona linhas ao manifesto de proveniência de mídia. Se um frame de cena não contém referências de imagem, não exporte ativos do Figma para ele — a ferramenta é inteligente sobre assets ausentes.

Validação pós-executação fiduciária (obrigatória): capture uma renderização da composição e verifique com skills/figma/scripts/verify-storyboard-reconstruction.mjs — ele compara a contagem de elementos por frame, a sequência de propriedades animadas e as coordenadas de destino final contra o JSON bruto da sessão do storyboard salva. A ferramenta de verificação precisa de argumentos --reference-dir <path> (contendo renderizações PNG de cada cena) e --render-dir <path> (contendo PNGs do mesmo tamanho da composição composta). Se o usuário não puder fornecer capturas de referência, execute a verificação apenas nos metadados: npx skills/figma/scripts/verify-storyboard-reconstruction.mjs --metadata-only (que verifica a contagem de elementos e a cobertura de propriedades).

Preocupações comuns

Repetição de asset

Assets congelados já existentes são ignorados — um asset só é re-extraído se seu fileKey:nodeId:format:scale:version não tiver sido congelado antes. Os assets são endereçados por asset://figma/<fileKey>/<nodeId>?format=<fmt>&scale=<s>; ao congelar, a referência de asset extraída é armazenada no manifesto. Renderizações que não precisam de assets Figma nunca o tocam; aquelas que precisam o fazem a partir do cache local. Os assets congelados são arquivos estáticos e nunca acionam chamadas de rede, a menos que você execute hyperframes figma refresh (explicitamente, nunca implícito). Veja a seção de cache.

Cache de rede (especificação §6 — compensação por limite de taxa)

Todas as respostas REST do Figma são armazenadas em cache em .media/figma-cache/ com chave por URL completa + timestamp (carimbo de data/hora para versões de arquivo). A primeira chamada por sessão usa o cache existente; chamadas posteriores para o mesmo recurso servem do cache. Os arquivos de cache expiram após 24 horas ou são invalidados por hyperframes figma refresh. A CLI também respeita cabeçalhos Cache-Control (max-age, must-revalidate) — se o Figma definir um TTL explícito, o cache o honra em vez de usar o padrão de 24 horas. A sobrecarga de cache é ~1ms por pesquisa.

Ferramenta de verificação de diffs visuais

Qualquer ferramenta de diff visual deve ser executada localmente, nunca no Figma. A ferramenta recomendada é Pixelmatch (npm: pixelmatch) — ela está incluída em @hyperframes/tools/diff. Execute-a como: npx pixelmatch reference.png render.png diff.png --threshold 0.05. Isso gera uma imagem diff com diferenças em vermelho e uma porcentagem de diferença no fluxo de saída padrão. Os dados de saída não devem ser interpretados como "aprovado" ou "reprovado" — apenas informe o valor ao usuário e pergunte se parece aceitável.

Referência de comandos

Comando	Caminho Figma	Descrição
hyperframes figma asset	Sessão 1	Exportar asset estático via REST
hyperframes figma tokens	Sessão 2	Importar tokens/estilos de marca
hyperframes figma component	Sessão 3	Importar componente Figma como HTML

Especificações de instalação e dependência

• Uma versão funcional do HyperFrames (CLI e SDK) deve estar instalada (npx hyperframes setup).
• Node.js 18+ (para suporte a fetch nativo).
• A CLI do HyperFrames baixa automaticamente quaisquer dependências ausentes.
• GSAP é fornecido via CDN nos fragmentos de saída — nenhum pacote npm necessário.
• Execute npx hyperframes check para validar a instalação.

Terminologia

• Composição: um documento de vídeo/motion gráfico do HyperFrames (.html com atributos de dados especiais).
• Asset: um arquivo estático (SVG, PNG, JPG, PDF) exportado do Figma.
• Token: uma variável de design (cor, tipografia, espaçamento) do sistema de design do Figma.
• Componente: um elemento HTML reconstruído a partir de um nó Figma.
• Storyboard: uma seção do Figma contendo múltiplos frames de cena em sequência.
• Ligação: uma conexão entre uma propriedade HTML e uma variável Figma, permitindo atualizações dinâmicas.

Resolução de problemas

Sintoma	Causa provável	Solução
401 Unauthorized	Token Figma ausente/ inválido	Definir FIGMA_TOKEN no ambiente e verificar escopos
403 Forbidden	Escopo insuficiente	Adicionar library_content:read para tokens, file_content:read para assets
429 Rate Limited	Limite de taxa excedido	Aguarde um minuto ou reduza o número de nós por requisição
Asset incorreto	fileKey/nodeId errado	Verifique o link Figma e tente novamente
Movimento não traduz	Conector ausente	Conecte o conector Figma ou forneça uma exportação nativa (MP4/PNG)