Instalação do plugin: Antes de comandos de configuração ou atualização, siga as regras de execução do plugin quando este skill estiver dentro de um plugin HyperFrames. Instalações autônomas mantêm as instruções de atualização abaixo.
Primeiro, mantenha este skill atualizado — confirme com o usuário antes de executar:
npx hyperframes skills update figma. Uma operação rápida (no-op) quando tudo está atualizado; caso contrário, ele atualiza este skill mais os skills de domínio principais dos quais depende antes de você utilizá-los.
Figma → HyperFrames
Traga o trabalho do Figma do usuário para uma composição. Dividido por capacidade (design spec §2):
| 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 | 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, headless). Um conector Figma compatível é opcional para dados de movimento e shaders; sem ele, peça uma exportação nativa. Cada caminho congela assets localmente para que as renderizações permaneçam determinísticas. Reconstruções de storyboard compõem exportações de assets da Fase 1 (REST) com montagem de linha do tempo conduzida pelo agente — nenhum conector necessário. Assets congelados existentes, registros de manifesto e bindings não são afetados por mudanças de roteamento — a divisão apenas altera qual credencial a próxima importação usa.
Autenticação — duas credenciais, com escopo
Pré-verificação — antes da primeira chamada CLI, verifique se um token existe: shell env ([ -n "$FIGMA_TOKEN" ]) ou o .env do projeto (a CLI carrega automaticamente — uma entrada .env conta como configurada). Se nenhum dos dois, NÃO execute o comando para capturar o erro — guie 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 (nunca escreve no Figma): Conteúdo do arquivo: Somente leitura + Metadados do arquivo: Somente leitura. Adicione Conteúdo da biblioteca: Somente leitura se 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 estilos publicados automaticamente (esperado, não é um erro — informe). Um 403 agora nomeia o escopo ausente exato; 429s são repetidos automaticamente (limite por minuto, respeitaRetry-After). - Peça ao usuário para definir
FIGMA_TOKENno perfil do shell ou no.envdo projeto; nunca peça para colar o token na conversa.
Durante a integração, também defina expectativas em uma frase: cada importação termina como um arquivo local congelado com proveniência registrada — 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 um novo.FORBIDDEN(403) → a mensagem nomeia o escopo ausente exato (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á tentou novamente com backoff (isso se aplica a TODAS as leituras — assets, tokens, estilos, árvores de nós, versões — a repetição está 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 (spec §2.1): as cotas do conector variam por plano Figma — agrupe requisições de quadros pai, evite 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, reduza em 429.
Roteamento
Analise o link figma do usuário com parseFigmaRef (URL, fileKey:nodeId, fileKey simples). Depois, 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 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 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 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 media-use resolve --entity as encontre posteriormente (correspondências de entidade 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 renderizam em uma única chamada /v1/images, que é a própria resposta do Figma ao limite de taxa por minuto — prefira-a em vez de N comandos separados ao extrair um conjunto inteiro de assets de um quadro. --description/--entity se aplicam a cada nó no lote, então agrupe nós que compartilham um propósito. 429s 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 bindings (.media/figma-bindings.jsonl). Variáveis são controladas pelo Enterprise upstream: em outros planos, o comando degrada para metadados de estilos publicados (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 dos componentes sejam vinculadas a variáveis de marca em vez de 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 bindings. A árvore de nós REST boundVariables 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 da composição. Tudo a jusante (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 diretamente de hyperframes figma tokens."
O runtime define cada variável de composição declarada como uma propriedade personalizada CSS (raiz do documento + hosts de sub-componentes), então var(--slug, literal) importado preenche a recolorização 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 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 bindings (spec §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 a importação, 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 Figma mais curta que sua altura de linha tem limites verticalmente aparados (o mapeador emitetext-box-trimpara 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 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: 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 do 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 está disponível, use-o e entregue 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 ao lado do 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 trechos motion.dev (a codificação confiável — os trechos CSS esticam durações e podem discordar; eles são ignorados), remove keyframes de cauda de loop (segmentos de submilissegundo 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 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 <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--cropa partir das bordas reais do cartão na renderização, não adivinhe. FALHA significa verificar a tradução, não o limiar. motionToGsap(doc)→emitTimelineScript(spec)→ injete como uma<script>após as tags CDN do GSAP + CustomEase. Pausado, finito, registrado emwindow.__timelinescom uma chave literal.- Faixa intraduzível (conduzida por shader, propriedade não suportada, máscaras complexas) → exporte através do conector, congele o MP4, depois incorpore como
<video class="clip">. Exceção: faixas conduzidas 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ê. Eases nomeadas fora do conjunto mapeado caem para linear — a tabela de mapeamento está emmotionEase.ts; sinalize o fallback ao 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 a fonte do shader só é acessível para estilos publicados em biblioteca (plano Full pago). Caminho padrão: peça ao usuário para exportar o quadro do shader nativamente no Figma (PNG ou Motion MP4), depois importe-o como um asset/clip da Fase 1. Não tente captura de pixels 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 reproduza os quadros como uma sequência de imagens estáticas. Um logotipo desenhado em quatro quadros consecutivos com y descendente é UM elemento subindo através de quatro keyframes. Reproduzir quadros de storyboard consecutivamente é o modo de falha; reconstruir as linhas do tempo dos elementos que eles implicam é o trabalho.
Arquivos de storyboard seguem uma gramática que você pode analisar mecanicamente — não olhe, decodifique:
- Unidades de cena: dentro da SEÇÃO, cada nó do tamanho de um quadro é uma cena — tanto FRAMEs nomeados quanto RECTANGLEs soltos em tela cheia (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.
- Ordem = posição-x (linha-mestre se a tira quebrar). Ordene cenas por
absoluteBoundingBox.x. - Diff entre adjacentes → extraia os pares de propriedade-valor que mudaram (coordenadas
x/y,opacity,rotation,fillsão suportadas). Se um fill mudar, verifique se os dois valores são referências de token — se sim, a animação é uma transição de variável, não uma interpolação de cores. Se um elemento aparecer no quadro n mas não no n+1, o agente ainda deve transportar o estado — ele pode ser invisível (opacidade=0, transparência total) ou estar fora da tela. - Em seguida, agrupe por ID de nó entre os quadros da cena 0…N para construir uma linha do tempo de keyframes por elemento. Cada linha do tempo começa no estado inicial (quadro 0) e tem tantos keyframes quantos quadros onde o elemento aparece.
- Mova cada linha do tempo para o contexto de movimento como um
MotionDoc— alimente-o emmotionToGsap(doc)→ script injetado, exatamente como a Fase 4. Se o storyboard descrever um movimento de 10 quadros ao longo de 300px em 24fps, a duração é de ~0,42s —motionContextToDocsaceita um parâmetroframeRate(padrão 30 — a taxa de quadros de despejo do Figma; use 24 se o arquivo for do FigJam). Se você não conhece a taxa de quadros, pergunte ao usuário. - Storyboards de reprodução única vs. loop: A menos que o usuário peça loop explicitamente, compile a linha do tempo como reprodução única (play). Se o último keyframe de um elemento for idêntico ao primeiro, normalize-o e defina
repeat: -1(loop infinito) na especificação da linha do tempo. Apenas loops de elementos onde todo o ciclo de volta é evidente (posição final = posição inicial, opacidade final = opacidade inicial, etc.). - Todas as fontes de assets para storyboards vêm da Fase 1 (assets congelados) — nunca tente renderizar ao vivo do Figma durante a montagem da linha do tempo. Se um elemento de storyboard se referir a um nó que não foi exportado como asset, execute
hyperframes figma asset <nó>primeiro, depois use o caminho congelado.
Execute npx hyperframes check antes de considerar concluído.
Marca de conclusão
Narrar o resultado: Após cada operação, resuma: o que foi importado, onde está (caminhos congelados, sidecars, manifestos, bindings), e a ação mais útil a seguir (visualizar, vetorizar, reimportar para vincular token, conectar conector para movimento).
Estrutura do projeto (referência)
compositions/
<nome-do-projeto>/
data-composition-variables # variáveis de marca — 1 por linha
compositions/
sections/ # seções de storyboard (se usadas)
components/ # componentes importados (Fase 3)
.media/
index.md # inventário de mídia compartilhado (imagens + ícones)
figma-manifest.json # mapeia figmaId → frozenPath + proveniência
figma-tokens.json # sidecar de tokens (Fase 2)
figma-bindings.jsonl # registros de índices de bindings
figma-cache/ # respostas brutas em cache (conector, REST)
images/ # assets congelados (Fase 1)