Instalação como plugin: Antes de comandos de configuração ou atualização, siga as regras de execução de 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 sem efeitos quando tudo está atualizado; caso contrário, atualiza esta skill e as skills de domínio principais 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 (design spec §2):
| Fase | O quê | Transporte | Superfície |
|---|---|---|---|
| 1 | Ativos 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 shader; sem um, peça por uma exportação nativa. Cada caminho congela os ativos localmente para que as renderizações permaneçam determinísticas. Reconstruções de storyboard compõem exportações de ativos da Fase 1 (REST) com montagem de linha do tempo orientada por agente — nenhum conector é necessário. Ativos 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 usará.
Auth — duas credenciais, escopo definido
Pré-voo — antes da primeira chamada CLI, verifique se existe um token: variável de ambiente do shell ([ -n "$FIGMA_TOKEN" ]) ou .env do projeto (a CLI o carrega automaticamente — uma entrada no .env conta como configurado). Se nenhum dos dois, NÃO execute o comando para obter o erro — oriente o usuário pela configuração única primeiro, depois pare e aguarde:
- figma.com/settings → Security → Personal access tokens → Gerar novo token.
- Escopos — somente leitura é tudo que esta integração jamais precisa (ela nunca escreve no Figma): File content: Read-only + File metadata: Read-only. Adicione Library content: Read-only se for executar
tokensem um plano não Enterprise — o fallback de estilos publicados atinge/v1/files/:key/styles, que retorna 403 sem ele (um escopo ausente no texto de configuração anterior). Opcionalmente Variables: Read-only para variáveis de marca — exclusivo Enterprise; sem eletokensdegrada 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, 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 chega como um arquivo congelado local com proveniência registrada — as renderizações nunca chamam o Figma, reexecutar um comando reimporta apenas o que mudou no Figma, e um único token funciona para ativos, 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) durante o fluxo → o token está expirado/revogado; regere.FORBIDDEN(403) → a mensagem nomeia o escopo exato ausente (por exemplo,library_content:readpara o fallback de estilos) — adicione-o, ou o arquivo não é visível para a conta.REQUIRES_ENTERPRISE(403 nas 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 — ativos, 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.
Conscientização sobre limite de taxa (spec §2.1): as cotas do conector variam conforme o plano Figma — agrupe requisições de quadros pai, pule capturas de tela de verificação a menos que solicitado 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) — ok em volume, recue em 429.
Roteamento
Analise o link figma do usuário com parseFigmaRef (URL, fileKey:nodeId, fileKey simples). Em seguida, por intenção:
- "use esta camada / logotipo / imagem" → Asset (CLI)
- "pegue minha marca / cores / tokens" → Tokens (CLI)
- "construa uma cena a partir deste quadro" → Component (CLI)
- "importe esta animação / movimento" → Motion (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 chegou (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?".
Ativos (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 sob .media/images/, anexa ao manifesto com proveniência, regenera .media/index.md (o inventário de uso de mídia compartilhada), 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 resolve --entity do media-use as encontre posteriormente (os hits da entidade correspondem a imagem/ícone).
Agrupe muitos nós em UMA única 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 são renderizadas 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 puxar um conjunto inteiro de ativos de um quadro. --description/--entity aplicam-se a cada nó no lote, portanto agrupe nós que compartilham um propósito. 429s também repetem 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 binding (.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 forem desejados — é isso que permite que as cores dos componentes se liguem às 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 reportar 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 binding. 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 da variável de composição. Tudo a jusante (resolução de 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 declara cada variável de composição como uma propriedade personalizada CSS (raiz do documento + hosts de sub-composição), portanto o var(--slug, literal) importado preenche a recolorização quando o padrão da variável muda — atualizar um valor em data-composition-variables renova a marca de 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 sob compositions/components/<nome>/. Vetores/operações booleanas são rasterizados automaticamente via exportação da Fase 1. Passagem de binding (spec §7.1, apenas ID exato — nunca correspondência de valor):
- Autoverificação de fidelidade estática (obrigatória para conteúdo principal): após a importação, 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 são limites verticalmente cortados (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 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 + sinalizador
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 hex.
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 para os helpers puros em @hyperframes/core/figma; caso contrário, peça por uma exportação nativa:
- Recupere o contexto de movimento para o quadro pai em uma única 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. - 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 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 editado — 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 é cancelada) e falha abaixo de 15dB de movimento-PSNR mínimo (calibrado: fiel ≈ 20+, divergente ≈ 5). Meça--cropa partir das bordas reais do cartão da renderização, não adivinhe. FALHA significa reverificar a tradução, não o limite. motionToGsap(doc)→emitTimelineScript(spec)→ injetar como uma<script>após as tags CDN GSAP + CustomEase. Pausado, finito, registrado emwindow.__timelinescom uma chave literal.- Faixa intraduzível (orientada por shader, propriedade não suportada, máscaras complexas) → exportar através do conector, congelar o MP4, então incorporar como
<video class="clip">. Exceção: faixas orientadas por shader — o caminho de exportação do Figma achata shaders para a cor base (consulte Shaders abaixo), portanto uma renderização ali perde silenciosamente o shader; peça ao usuário uma exportação Figma nativa. Sempre diga qual caminho você usou e por quê. Eases nomeados fora do conjunto mapeado recaem para linear — a tabela de mapeamento vive 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 origem 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 MP4 de movimento), depois importe-o como um ativo/clip da Fase 1. Não tente a captura de pixels do conector para 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 decrescente é UM elemento subindo através de quatro keyframes. Reproduzir quadros de storyboard consecutivamente é o modo de falha; reconstruir as linhas do tempo do elemento que eles implicam é o trabalho.
Os arquivos de storyboard seguem uma gramática que você pode analisar mecanicamente — não olhe com os olhos, decodifique:
- Unidades de cena: dentro da SEÇÃO, cada nó do tamanho do quadro é uma cena — tanto FRAMEs nomeados quanto RECTANGLEs soltos de quadro completo (designers colam imagens diretamente na seção). Filtre por tamanho (≈ proporção da composição, por ex., >1400×900), não por tipo de nó ou nome.
- Ordem = posição x (linha-major se a tira quebrar). Ordene as cenas por
absoluteBoundingBox.x. - Diff entre cenas adjacentes para extrair mudanças de estado por elemento. Para cada elemento em comum entre
frameNeframeN+1, registre o estado em cada quadro como um par deMotionDoc(transform, opacity, fill). Elementos que aparecem ou desaparecem são implícitos com um estado nulo em um dos lados — a máquina de linha do tempo lida com isso. - Construir linha do tempo: para cada par
(elemento, cena i → cena i+1), crie um trecho demotionToGsapligando os estados, com a duração do intervalo derivada do tempo de exibição do quadros (suponha 1s se não especificado, ou use a duração da exportação da cena, se disponível). Keyframes implícitos (elemento entra ou sai) usam fade-in/fade-out de 0.3s padrão. - Montar script final: combine todos os trechos em uma linha do tempo sequencial com um
timelineLabel: "storyboard-section-<index>". Injete como um<script>após GSAP (Fase 4), exatamente como a montagem de movimento. Não importe mais nada do Figma — a Diff e a montagem são pura computação local.
Exemplo
Uma seção de storyboard com 3 quadros:
| Elemento | Quadro 1 | Quadro 2 | Quadro 3 |
|---|---|---|---|
| Logo | y=100 | y=50 | y=0 |
| Botão | (oculto) | opacity=0 | opacity=1 |
Resultado: Logo anima de y=100→50→0 ao longo de 3s (1s por quadro). Botão aparece com fade-in de 0.3s no quadro 3.
- Executar verificação de sanidade: renderize um trecho de 1s das cenas reconstruídas e compare com uma exportação de vídeo do storyboard (se disponível). Se o movimento diferir significativamente (energy-PSNR < 15dB), sinalize e ofereça ajustar a duração dos keyframes manualmente.
Execução de verificação (todas as fases)
Sempre termine com:
npx hyperframes check
Para relatar problemas de ativo/fragmento/conexão antes de declarar a importação concluída. A saída de check é pensada para ser visível; se passar, o usuário pode renderizar ou visualizar imediatamente.