Figma → HyperFrames

Instalação do plugin: Antes dos comandos de configuração ou atualização, siga as regras de instalação de plugin quando esta skill estiver dentro de um plugin do 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 sem efeito quando tudo está atualizado; caso contrário, ela atualiza esta skill e as skills de domínio principais das quais ela depende antes de você usá-las.

O que Figma → HyperFrames faz?

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

Fase	O quê	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	use seu contexto de movimento
5	Shaders	conector / exportação manual	use-o ou uma exportação nativa

REST é usado sempre que possível (utilizável em volume, sem interface gráfica). 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 combinam exportações de assets da Fase 1 (REST) com montagem de timeline orientada por agente — nenhum conector necessário. Assets 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, escopadas

Pré-verificação — antes da primeira chamada CLI, verifique se um token existe: variável de ambiente do shell ([ -n "$FIGMA_TOKEN" ]) ou no .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 na configuração única primeiro, então 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 atinge /v1/files/:key/styles, que retorna 403 sem ele (um escopo que o texto de configuração 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 ausente exato; 429s fazem nova tentativa automaticamente (limite por minuto, respeita Retry-After).
3. Peça ao usuário para definir FIGMA_TOKEN no perfil do shell ou no .env do projeto; nunca peça para colar o token na conversa.

Durante a integração, também defina expectativas de uma só vez: cada importação resulta em um arquivo local congelado com proveniência registrada — renders 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, 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; gere novamente. FORBIDDEN (403) → a mensagem nomeia o escopo ausente exato (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 TODAS as leituras — assets, tokens, estilos, árvores de nós, versões — a nova tentativa está no caminho de requisição compartilhado; Retry-After é respeitado, limitado a 60s); se ainda assim surgir, 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 re-derivação nunca gaste uma segunda chamada. REST é por minuto (10+/min, baldes por endpoint) — funciona em volume, faça backoff 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 / logo / imagem" → Asset (CLI)
• "pegue minha marca / cores / tokens" → Tokens (CLI)
• "construa uma cena a partir deste frame" → Componente (CLI)
• "importe 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 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 em .media/images/, anexa ao manifesto com proveniência, regenera .media/index.md (o inventário de uso de mídia compartilhado), imprime um trecho <img>. Idempotente por fileKey:nodeId:format:scale:version. Prefira SVG para vetores/logos (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 o uso de mídia resolve --entity as encontre depois (correspondências de entidade funcionam em 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 um conjunto inteiro de assets de um frame. --description/--entity se aplicam a todos os nós no lote, portanto agrupe nós que compartilham um propósito. 429s também fazem nova tentativa automática 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 controladas por Enterprise upstream: em outros planos, o comando degrada para metadados de estilo publicado (valores 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 forem 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 controladas por Enterprise, mas um conector compatível pode fornecer definições de variáveis. Quando tokens relatar REQUIRES_ENTERPRISE e o conector estiver disponível, recupere as variáveis da cena pai uma vez, armazene a resposta bruta em .media/figma-cache/, e use-a para construir o índice de vinculação. A árvore de nós REST boundVariables fornece VariableIDs por propriedade; junte-os 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 de 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-composição), então var(--slug, literal) importado preenche a recoloração 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>' os 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/<name>/. Vetores/operações booleanas são auto-rasterizados via exportação da Fase 1. Passagem 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 principal): 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 é limites verticalmente aparados (o mapeador emite text-box-trim para estes; desvio medido sem ele era ~6px em uma fonte de 70px). Se a comparação mostrar desvio que o mapeador não cobre, relate-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; ofereça ao usuário: execute tokens no arquivo de origem (ou biblioteca), então 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 ao começar, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error ao 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:

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(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 durações e podem discordar; eles são ignorados), remove keyframes finais de loop-wrap (segmentos sub-milissegundo em tempos ≈0.9999→1 são o reset instantâneo do loop, não movimento criado — o wrap é realizado pelo reinício repeat), e preserva atenuações 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 considerar concluído — obrigatório: exporte o frame raiz do cohort através do conector disponível e execute node <SKILL_DIR>/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 card na renderização, não adivinhe. FALHA significa verificar novamente a tradução, não o limite.
3. motionToGsap(doc) → emitTimelineScript(spec) → injete como uma <script> após as tags CDN do GSAP + CustomEase. Pausada, finita, registrada em window.__timelines com uma chave literal.
4. Faixa não traduzível (impulsionada 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: faixas impulsionadas por shader — o caminho de exportação do Figma achata shaders para a cor base (veja Shaders abaixo), então uma renderização ali perde silenciosamente o shader; peça ao usuário uma exportação nativa do Figma. Sempre diga qual caminho você usou e por quê. Atenuações nomeadas fora do conjunto mapeado recorrem a 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 Figma não executa shaders (eles são achatados para a cor base), e a origem do shader é acessível apenas para estilos publicados em biblioteca (plano Full pago). Caminho padrão: peça ao usuário para exportar o frame do shader nativamente no Figma (PNG ou Motion MP4), então importe-o como um asset / 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 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 em y descendente é UM elemento subindo através de quatro keyframes. Reproduzir frames de storyboard consecutivamente é o modo de falha; reconstruir as timelines de elemento que eles implicam é o trabalho.

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 de tela inteira (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). Classifique cenas por absoluteBoundingBox.x.
3. Diferencie adjacentes para encontrar elementos que persistem: cada nó filho é um elemento se tiver um id que aparece em mais de um frame adjacente. Elementos com id inalterado em posição y/opacidade/escala inalteradas são estáticos — não os anime. Apenas propriedades que realmente mudam entre pares de frames adjacentes devem ser animadas. Cenas sem elementos compartilhados com a anterior são cortes de cena (animação zero, fade out + fade in). A composição deve ter pelo menos um elemento animado por par adjacente, caso contrário, notifique: "o storyboard parece ser um slideshow estático — nenhum elemento compartilhado detectado." A perguntar ao usuário se isso é intencional.
4. Reconstrua GSAP a partir das diferenças: para cada elemento persistente, emita uma timeline GSAP com keyframes brutos (valores literais, sem easing inferido). A duração entre chaves é (indexDiff) * (sceneDuration/numChunks). Sempre emita todas as chaves — nunca interpole. Anexe como um <script> no elemento de composição. Tags de elemento de composição (#current-element) mapeiam para seletores de timeline.
5. Não há interação do usuário ou atrasos — o storyboard é uma animação linear contínua. O loop envolve da última cena de volta para a primeira (não há estado de repouso).
6. Execute uma verificação de sanidade: renderize o storyboard reconstruído e compare visualmente o primeiro e o último frame com a primeira e a última cena do Figma (via figma asset). Se divergir >5% em diferença de pixel, relate e não entregue. A verificação de sanidade é obrigatória.

Regras de saída: (apenas saída de árvore estrutural, sem divagações)

• Se um caminho falhar com um erro que você pode corrigir automaticamente (ex.: escopo ausente, token expirado), corrija e continue sem notificar o usuário, exceto para escopos ausentes (sempre notifique).
• Se um caminho falhar com um erro que requer ação do usuário (exportação nativa, conector ausente), explique o que é necessário em uma frase e pare.
• Nunca improvise um comando CLI que não exista — se a tabela de fases não listar um comando para a intenção, não invente um. Use o caminho de exportação nativa ou peça ao usuário.