Primeiro, mantenha esta skill atualizada — confirme com o usuário antes de executar:
npx hyperframes skills update figma. Um no-op rápido quando tudo está atualizado; caso contrário, atualiza esta skill e as skills do domínio principal das quais ela depende antes que você possa usá-las.
Figma → HyperFrames
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 (usável em volume, headless). Um conector Figma compatível é opcional para dados de movimento e shaders; sem ele, peça uma exportação nativa. Cada caminho congela os assets localmente para que os renders permaneçam determinísticos. Reconstruções de storyboard compõem exports de assets da Fase 1 (REST) com montagem de linha do tempo orientada pelo agente — nenhum conector necessário. Assets congelados existentes, registros de manifesto e ligações 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: env do shell ([ -n "$FIGMA_TOKEN" ]) ou o .env do projeto (a CLI carrega automaticamente — uma entrada no .env conta como configurada). Se nenhum dos dois, NÃO execute o comando para colher o erro — oriente o usuário na 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 antigo omitia). Opcionalmente Variáveis: Somente leitura para variáveis de marca — apenas para Enterprise; sem eletokensdegrada para estilos publicados automaticamente (esperado, não um erro — diga isso). Um 403 agora nomeia o escopo exato faltando; 429s são repetidos automaticamente (limite por minuto, respeitaRetry-After). - Peça ao usuário para definir
FIGMA_TOKENem seu perfil do shell ou.envdo projeto; nunca peça para ele colar o token na conversa.
Ao integrar, também defina expectativas de uma só vez: cada importação chega como um arquivo local congelado com proveniência registrada — os 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, e 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 faltando (ex: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é 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 as respostas brutas para que a re-derivação nunca gaste uma segunda chamada. REST é por minuto (10+/min, buckets por endpoint) — bom em volume, reduza 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)
- "pegue minha marca / cores / tokens" → Tokens (CLI)
- "crie 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, 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 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 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 resolve --entity de uso de mídia as encontre mais tarde (correspondências de entidade funcionam em imagem/ícone).
Agrupe vários 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 isso a N comandos separados ao extrair vários assets de um quadro inteiro. --description/--entity se aplicam a todos os nós no lote, portanto 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 restritas 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 forem desejados — é isso que 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): Variáveis REST são restritas a 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 em cache a resposta bruta 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ável 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 toda variável de composição declarada como uma propriedade personalizada CSS (raiz do documento + hosts de sub-composição), portanto var(--slug, literal) importado preenche a recoloração quando o padrão da variável muda — atualizar um valor em data-composition-variables renova a marca de todo 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 sob 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 emitetext-box-trimpara estes; o desvio medido sem ele foi de ~6px em uma fonte de 70px). Se a comparação mostrar desvio que o mapeador não cobre, relate — 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: executetokensno arquivo de origem (ou biblioteca), 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 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 entregue sua saída aos 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 ao lado do projeto (
.media/figma-cache/) para que a retradução seja gratuita. - Normalize em
MotionDocs commotionContextToDocs(respostaBruta, { selectorFor, repeat })de@hyperframes/core/figma— nunca transcreva números de keyframe manualmente. O helper codifica mecanicamente as regras de decodificação testadas em campo: ele analisa os snippets motion.dev (a codificação confiável — os snippets CSS esticam as 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 criado — o wrap é realizado pelo reinício derepeat), e preserva curvas bezier verbatim.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 (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--cropdas bordas reais do cartão no render, não adivinhe. FALHA significa verificar a tradução, não o limite. motionToGsap(doc)→emitTimelineScript(especificação)→ injete como um<script>após as tags CDN do GSAP + CustomEase. Pausado, finito, registrado emwindow.__timelinescom uma chave literal.- Faixa intraduzível (orientada por shader, propriedade não suportada, máscaras complexas) → exporte através do conector, congele o MP4, então incorpore 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 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ê. Eases nomeadas fora do conjunto mapeado recaem para linear — a tabela de mapeamento está emmotionEase.ts; sinalize o fallback para o usuário quando ele ocorrer. - Execute
npx hyperframes checkantes 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 o código-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 shader nativamente no Figma (PNG ou MP4 de Movimento), depois importe-o como um asset/clip da Fase 1. Não tente captura de pixel do conector de um shader — 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 reproduza os quadros como uma sequência de imagens paradas. Um logotipo desenhado em quatro quadros consecutivos com y decrescente é UM elemento subindo através de quatro keyframes. Reproduzir quadros de storyboard consecutivamente é o modo de falha; reconstruir as linhas do tempo de elemento que eles implicam é o trabalho.
Arquivos de storyboard seguem uma gramática que você pode analisar mecanicamente — não avalie manualmente, decodifique:
- Unidades de cena: dentro da SEÇÃO, todo nó do tamanho de um quadro é uma cena — tanto FRAMEs nomeados quanto RECTANGLEs de quadro completo soltos (designers colam imagens paradas diretamente na seção). Filtre por tamanho (≈ proporção da composição, ex: >1400×900), não por tipo de nó ou nome.
- Ordem = posição x (linha principal se a tira quebrar). Ordene cenas por
absoluteBoundingBox.x. - Diferencie quadros adjacentes em cadeias de elemento — é aqui que a animação reside. Combine filhos em quadros consecutivos: primeiro por nome (mesmo nome = mesmo elemento → interpole seu x/y/w/h relativo entre estados), depois por similaridade geométrica (largura/altura/posição similar).
- Construa linhas do tempo de elemento: para cada cadeia, primeiro quadro define o estado inicial; cada quadro subsequente adiciona um keyframe. Interpolação padrão é linear a menos que o conector forneça curvas de easing;
- Saída: um único script GSAP que anima todos os elementos através de todos os keyframes, sincronizado com a duração do storyboard.
- Fallback sem conector: se nenhum conector estiver disponível para extrair dados de easing, use easing linear e informe o usuário: "Easing de storyboard será linear — conecte o conector Figma para easing preciso."
- Sempre verifique: após construir a animação, execute
npx hyperframes previewe confirme visualmente se a animação corresponde à intenção do storyboard.
Linhas de comando de uso geral
# Verificar integridade do projeto
npx hyperframes check
# Visualizar composição atual
npx hyperframes preview
# Renderizar composição final
npx hyperframes render [--output <caminho>]
# Atualizar skills
npx hyperframes skills update [figma|all]
Tratamento de erros
A skill trata graciosamente erros comuns de API e orienta o usuário:
- 401 Não Autorizado: Token FIGMA_TOKEN inválido ou expirado — peça ao usuário para gerar um novo token.
- 403 Proibido: Escopo insuficiente — a mensagem de erro nomeia o escopo exato faltando; instrua o usuário a adicioná-lo.
- 429 Muitas Requisições: Limite de taxa excedido — repete automaticamente com backoff; se persistir, sugira esperar ou importar menos nós.
- REQUIRES_ENTERPRISE: Variáveis são apenas Enterprise — degrade para estilos publicados ou use conector.
- Arquivo não encontrado: Verifique se o fileKey está correto e se o token tem acesso ao arquivo.
Notas de dependência
Esta skill depende de:
@hyperframes/core/figma(funcionalidade central)@hyperframes/skills/figma-shared(caminhos de requisição compartilhados, repetição)- Figma connector opcional (fases 4-5)
- Node.js >= 18
Execute npx hyperframes skills update figma para atualizar todas as dependências para as versões mais recentes.