Instalação do Plugin: Antes dos comandos de configuração ou atualização, siga as regras de execução do plugin 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 quando tudo está atualizado; caso contrário, atualiza esta skill e as skills de domínio principais das quais ela depende antes de você confiar nelas.
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 (utilizável em volume, headless). Um conector Figma compatível é opcional para dados de movimento e shaders; sem um, peça uma exportação nativa. Todos os caminhos congelam 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 orientada por 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
Verificação prévia — antes da primeira chamada CLI, verifique se existe um token: shell env ([ -n "$FIGMA_TOKEN" ]) ou o .env do projeto (a CLI carrega automaticamente — uma entrada .env conta como configurado). Se nenhum, NÃO execute o comando para obter o erro — oriente o usuário na configuração inicial primeiro, então 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ê executar
tokensem um plano não Enterprise — o fallback de estilos publicados acessa/v1/files/:key/styles, que retorna 403 sem isso (um escopo que o texto de configuração mais antigo omitia). Opcionalmente Variáveis: Somente leitura para variáveis de marca — exclusivo Enterprise; sem isso,tokensdegrada para estilos publicados automaticamente (esperado, não é um erro — informe isso). Um 403 agora nomeia o escopo exato ausente; 429s tentam novamente automaticamente (limite por minuto, respeitaRetry-After). - Peça ao usuário para definir
FIGMA_TOKENno perfil do shell ou.envdo projeto; nunca peça para colar o token na conversa.
Durante a integração, também estabeleça expectativas de uma só vez: cada importação termina como 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, 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 exato ausente (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 reside 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 quadros pai, evite capturas de tela de verificação a menos que solicitado e armazene em cache respostas brutas para que uma rederivação nunca gaste uma segunda chamada. REST é por minuto (10+/min, buckets por endpoint) — ok 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 / 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 puxar 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 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/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 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 puxar assets de um quadro inteiro. --description/--entity se aplicam a cada nó no lote, então agrupe nós que compartilham um propósito. 429s também tentam novamente 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). 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 que 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 relatar REQUIRES_ENTERPRISE e o conector estiver disponível, recupere as variáveis da cena pai uma vez, armazene em cache a resposta bruta para .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, então escreva linhas .media/figma-bindings.jsonl ({kind:"binding", figmaId, sourceFileKey, compositionVariableId:"figma:<nome>", version}) mais as entradas de variáveis de 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 conector Figma — planos Enterprise obtêm isso diretamente de hyperframes figma tokens."
O runtime declara cada variável de composição declarada como uma propriedade personalizada CSS (raiz do documento + hosts de subcomponentes), então o var(--slug, literal) importado preenche a recolorização quando o padrão da variável muda — atualizar um valor em data-composition-variables remarca 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/<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 hero): após importar, renderize o fragmento e compare com os pixels reais do Figma —
figma asset <mesmo node> --format pngé a verdade absoluta. Texto é o eixo de deriva conhecido: uma caixa de texto do Figma mais curta que sua altura de linha tem limites com corte vertical (o mapeador emitetext-box-trimpara estes; a deriva medida sem isso era ~6px em uma fonte de 70px). Se a comparação mostrar deriva 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 de 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), então reimporte o componente para vinculá-los. Pergunte uma vez por biblioteca desconhecida qual arquivo é — nunca adivinhe, nunca corresponda por hex.
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 fim (anônimo, com consentimento, nunca falha): npx hyperframes events --skill=figma-motion quando 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, 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 alongam 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 pelo reinício derepeat), e preserva eases 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 <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 da importação estática se anula) 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 limite. motionToGsap(doc)→emitTimelineScript(spec)→ injete como um<script>após as tags CDN do GSAP + CustomEase. Pausado, finito, registrado emwindow.__timelinescom uma chave literal.- Faixa intraduzível (orientada a 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 a 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; peça ao usuário uma exportação Figma nativa. Sempre diga qual caminho você usou e por quê. Eases nomeadas fora do conjunto mapeado voltam para linear — a tabela de mapeamento está emmotionEase.ts; sinalize o fallback ao usuário quando ocorrer. - Execute
npx hyperframes checkantes 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 (assento Full pago). Caminho padrão: peça ao usuário para exportar o quadro do shader nativamente no Figma (PNG ou MP4 de movimento), então importe como um asset da Fase 1 / clipe. Não tente captura de pixel do conector de um shader — isso 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 ao longo 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 quadros de storyboard um após o outro é 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 veja a olho nu, decodifique:
- Unidades de cena: dentro da SEÇÃO, todo 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, ex.: >1400×900), não por tipo ou nome de nó.
- Ordem = posição x (linha principal se a tira quebrar). Ordene as cenas por
absoluteBoundingBox.x. - Diferença entre adjacentes: emparelhe cenas ordenadas e faça diff dos IDs das subárvores — a árvore de nós não é renderizada, apenas analisada estruturalmente. As IDs consistentes emToda a linha do tempo são os elementos animados. Um elemento cujo ID aparece na cena 1 mas não na cena 2 (+ todas as cenas seguintes) desapareceu (fade out / slide out / mover-se para fora do quadro). Um ID que aparece na cena 2 mas não na cena 1 apareceu (fade in / etc.). IDs comuns em ambas são o mesmo elemento em dois keyframes — normalize as propriedades do elemento (x, y, rotação, opacidade, escala) nos dois pontos para deduzir o tween.
- Reconstrução em 3 passos: (a) uma TimelineMax com todas as cenas como marcadores de tempo uniformemente espaçados (1s por cena = duração natural para storyboard; peça ao usuário para ajustar). (b) Para cada elemento com pelo menos dois keyframes, um TweenMax (ou TweenLite para desaparecimentos/aparições) que anima as propriedades normalizadas entre o marcador de início e fim. (c) Injete o script após os tags CDN GSAP. A saída do Motion (se disponível) sobrescreve as propriedades chave, mas a linha do tempo do storyboard é sempre construída a partir das cenas — nunca mescle a saída do conector de movimento com a linha do tempo do storyboard.
- Restrições: a linha do tempo do storyboard busca fidelidade de movimento estrutural, não fidelidade de estilo. O tweener de aparição assume
opacity:0→opacity:1com duração de 0.3s (comum em storyboard); o tweener de desaparecimento fazopacity:1→opacity:0com duração de 0.3s; a posição assume tween linear (padrão de storyboard: não há eases nos quadros, então inferir um é adivinhação). Propriedades estilísticas (preenchimento, traçado, fonte, tamanho da fonte, etc.) são ignoradas — elas são resolvidas a partir do asset congelado da Fase 1. Cada cena deve ser importada como um asset da Fase 1 ANTES da reconstrução da linha do tempo, para que o asset esteja disponível para ser animado. Etapas exatas para o usuário: (a) importe todos as cenas primeiro como assets da Fase 1 (hyperframes figma asset <fileKey> <nodeId1> <nodeId2> ...), (b) então reconstrua a linha do tempo. 6. Validação contra verdade absoluta (obrigatória): execute o mesmo script de verificação de movimento — <SKILL_DIR>/scripts/verify-motion.mjs — comparando uma exportação de vídeo da linha do tempo com uma exportação de vídeo da seção de storyboard do Figma. A Estrutura de movimento medida pelo script deve corresponder dentro de uma tolerância (consulte a codificação). Se falhar, as regras de dif são provavelmente muito simplificadas — denuncie. Popular o cache do asset reduz o tempo de verificação.
Comandos de atualização
Após qualquer mudança, peça ao usuário para executar npx hyperframes skills update figma para garantir que a skill esteja atualizada. Isso também atualiza as skills de domínio que ela importa.
Esquema de criação de artefatos (para interpretação do agente)
Esta seção fornece uma vista estrutural de como e onde os artefatos são criados. Ela não é executada; é metadados para o agente.
| Comando/Operação | Caminho(s) do artefato criado/atualizado | Formato | Condição de criação (gatilho) | Fase(s) | É efêmero? | Mantido sincronizado com o Figma? (como) |
|---|---|---|---|---|---|---|
hyperframes figma asset | .media/images/<fileKey>-<nodeId>-<format>-<scale>-<version>.<fmt> | Binário SVG ou imagem raster | Após importação do asset | Fase 1 (Assets) | Não | Sim — reexecução reimporta apenas nós alterados; versionamento detecta mudanças |
hyperframes figma asset | .media/index.md | Markdown | Após importação do asset + apêndice do manifesto | Fase 1 | Não | Sim — regenerado em cada importação de asset |
hyperframes figma tokens | .media/figma-tokens.json | JSON | Após importação de tokens | Fase 2 (Tokens) | Não | Sim — via variáveis (Enterprise) ou degradação de estilo; a passagem de ligação do componente conecta |
hyperframes figma tokens | .media/figma-bindings.jsonl | JSONL (delimitado por linha) | Após importação de tokens | Fase 2 | Não | Sim — IDs de variáveis ligam a definições; a resolução de componente as segue |
hyperframes figma component | compositions/components/<component-name>/index.html | HTML | Após importação do componente | Fase 3 (Componentes) | Não | Sim — a reimportação vincula novos tokens; a resolução de variáveis se propaga |
| Fase 4 (Movimento) — conector | <project-dir>/<component>.motion.json | JSON (.motion do conector, armazenado em cache) | Após recuperação do contexto de movimento | Fase 4 | Sim (cache) | Apenas via reexecução |
| Fase 4 (Movimento) — script injetado | Injetado em index.html como elemento <script> | JavaScript (chamadas GSAP/TimelineMax) | Após normalização e verificação | Fase 4 | Sim | Não — congelado; reimportar para atualizar |
| Fase 4 (Movimento) — fallback MP4 | .media/videos/<component>-<timestamp>.mp4 | MP4 | Se a tradução falhar (faixa intraduzível) | Fase 4 | Não | Não — congelado; substitua manualmente |
| Fase 5 (Shaders) — PNG/MP4 | Sob .media/images/ ou .media/videos/ | PNG ou MP4 (fornecido pelo usuário) | Se nenhum conector ou falha de shader | Fase 5 | Não | Não — pedido ao usuário; substitua manualmente |
| Storyboard — asset de cena | .media/images/<fileKey>-<sceneNodeId>-png-1-<version>.png | PNG (importação da Fase 1 de cada cena) | Antes da reconstrução da linha do tempo | Fase 1 (para cenas) | Não | Sim — via importação de asset |
| Storyboard — script da linha do tempo | Injetado em index.html como elemento <script> | JavaScript (TimelineMax do GSAP + tweens) | Após diif de duas ou mais cenas | reconstrução de storyboard (Fase 4 implícita) | Sim | Não — reconstruído a partir de cenas; reconstruir para atualizar |
Comportamento Idempotente:
- Asset: Idempotente por
(fileKey, nodeId, formato, escala, versão); reexecutar não recongela, apenas imprime o trecho. - Tokens: Idempotente em nível de arquivo; reexecutar substitui os arquivos sidecar (não adiciona duplicatas — o manifesto é regenerado).
- Componente: Idempotente por
(fileKey, nodeId); reexecutar substitui o diretório do componente. - Movimento (conector): Idempotente se os dados do conector forem armazenados em cache; sem cache, uma nova requisição recupera (potencialmente dados atualizados) — considere não idempotente se os dados do Figma mudaram.
- Shaders (manual): Não idempotente; sempre uma ação do usuário.
- Storyboard: Não idempotente em sentido estrito (novas cenas podem ser adicionadas), mas reconstruir da mesma definição de seção produz a mesma linha do tempo (as cenas são ordenadas, as comparações de diff são determinísticas).
Limpeza de Artefatos:
- Cache do conector de movimento: Seguro para limpar se os dados do conector do Figma estiverem desatualizados e o usuário desejar uma atualização; remova
.media/figma-cache/. - Assets congelados: Nunca remova automaticamente; o usuário pode excluir manualmente entradas do manifesto / arquivos.
- Diretórios de componentes: Nunca remova; o usuário pode excluir manualmente.
- Fallbacks MP4: Nunca remova; o usuário pode substituir manualmente.