Communitygithub.com

Figma → HyperFrames

Importe conteúdo do Figma para uma composição HyperFrames — assets renderizados, tokens de marca, componentes, seções de storyboard → movimento reconstruído (quadros lidos como estados, não slides) (REST/CLI), movimento assistido por conector quando disponível, e shaders de um conector ou exportação nativa. Use quando o usuário colar um link figma.com ou pedir para trazer um design, quadro, logotipo, marca ou animação do Figma para um vídeo/composição.

O que é Figma → HyperFrames?

Esta skill permite que agentes de IA importem designs do Figma diretamente para composições HyperFrames (Remotion + React). Ela gerencia múltiplas fases de importação: assets estáticos via REST, tokens de marca, componentes HTML editáveis, reconstrução de movimento a partir de quadros de storyboard, e shaders. A skill enfatiza o uso de REST sempre que possível, com suporte opcional a conectores para fases de movimento e shaders. O fluxo de trabalho de autenticação usa tokens de acesso pessoal do Figma com escopos somente leitura. Um princípio chave é que quadros de storyboard são tratados como keyframes de animação, não slides, permitindo a reconstrução de movimento interpolando estados de elementos entre quadros. A skill inclui validação obrigatória de fidelidade — comparando saídas renderizadas com capturas de tela do Figma para garantir precisão. Importações são congeladas localmente com procedência registrada, garantindo renders determinísticos sem chamadas repetidas à API do Figma. Uma seção de aviso de contrato nota que a implementação atual descreve o pipeline legado HTML + GSAP, mas o plano é migrar para o ecossistema Remotion (React), e o agente deve expressar resultados através da API de composições do Remotion.

Funciona com~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/MattiaIppoliti/tia-skills/tree/HEAD/skills/video/figma

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

⚠ Status do Contrato: ainda não portado para Remotion

O framework de saída desta stack é Remotion + React (/hyperframes-core). Esta skill ainda descreve o pipeline legado HTML + data-* + timeline GSAP pausada, e seus scripts ainda emitem index.html nesse contrato.

Até que seja portado:

  • Não execute npx hyperframes <qualquer coisa> — essa CLI está aposentada. /hyperframes-cli mapeia cada comando antigo para seu equivalente em Remotion.
  • Não copie sua marcação data-* ou código de timeline GSAP para um projeto Remotion.
  • Faça aproveitar seu conhecimento: forma da história, ritmo de corte, design visual, as decisões sobre o que aparece na tela. Essa parte é independente de framework e é o motivo desta skill ainda estar aqui.
  • Faça expressar o resultado através do contrato de /hyperframes-core: <Composition>, <Sequence>, e valores derivados de useCurrentFrame().

Diga em seu resumo quando teve que contornar isso, para que a portabilidade possa ser concluída.

Primeiro, mantenha esta skill atualizada — execute silenciosamente, não pergunte: npx hyperframes skills update figma. Uma operação rápida e sem efeito quando tudo está atualizado; caso contrário, atualiza esta skill mais as skills de domínio principais das quais ela depende antes que você as utilize.

O que Figma → HyperFrames faz?

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

FaseO queTransporteSuperfície
1Assets estáticosRESThyperframes figma asset
2Tokens/estilos da marcaRESThyperframes figma tokens
3Componentes → HTMLRESThyperframes figma component
4Movimento → GSAPconector quando disponíveluse seu contexto de movimento
5Shadersconector / exportação manualuse-o ou uma exportação nativa

REST é usado onde for 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. Cada caminho congela assets localmente para que os renders permaneçam determinísticos. Reconstruções de storyboard compõem exportações de asset da Fase 1 (REST) com montagem de timeline conduzida pelo agente — nenhum conector necessário. Assets congelados existentes, registros de manifesto e vinculações não são afetados por mudanças de roteamento — a divisão apenas altera qual credencial a próxima importação usa.

Auth — duas credenciais, com escopo

Verificação pré-voo — antes da primeira chamada CLI, verifique se um token existe: env shell ([ -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 colher o erro — oriente o usuário pela configuração única primeiro, depois pare e aguarde:

  1. figma.com/settings → Segurança → Tokens de acesso pessoal → Gerar novo token.
  2. 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 tokens em 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 ele tokens degrada para metadados de estilo publicado automaticamente (esperado, não um erro — diga isso). Um 403 agora nomeia o escopo exato que está faltando; 429s repetem automaticamente (limite por minuto, honra Retry-After).
  3. Peça ao usuário para definir FIGMA_TOKEN em seu perfil shell ou .env do projeto; nunca peça para colar o token na conversa.

Ao embarcar, também defina expectativas em uma só frase: cada importação resulta em um arquivo local congelado com procedência registrada — renders nunca chamam 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; recrie. FORBIDDEN (403) → a mensagem nomeia o escopo exato que está faltando (por exemplo, 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á 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 é honrado, limitado a 60s); se ainda assim surgir, aguarde um minuto ou importe menos nós por chamada.

Conscientização de limite de taxa (especificação §2.1): cotas de conector variam por plano Figma — agrupe requisições de frames pais, pule capturas de tela de verificação a menos que solicitado, e cache respostas brutas para que re-derivação nunca gaste uma segunda chamada. REST é por minuto (10+/min, buckets por endpoint) — bom em volume, recue 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 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 sob .media/images/, anexa o manifesto com procedê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 + atributo alt do <img>); adicione --entity "<nome>" para marcas de marca nomeadas para que resolve --entity do uso de mídia as encontre depois (correspondências de entidade atingem 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'. Todos renderizam em uma única chamada /v1/images, que é a própria resposta do figma ao limite de taxa por minuto — prefira-o em vez de 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 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 vinculação (.media/figma-bindings.jsonl). Variáveis são limitadas 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 são 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 limitadas a 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, cacheie a resposta bruta em .media/figma-cache/, e use-a para construir o índice de vinculação. A árvore de nós REST's boundVariables fornece VariableIDs por propriedade; junte-as 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 em 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-comp), então var(--slug, literal) importado preenche recolor 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 sobrescreve no momento do render.

Componentes (Fase 3 — CLI)

hyperframes figma component '<url-ou-fileKey:nodeId>'

Árvore de nós → HTML editável com geometria exata do figma, empacotado como um item de registro sob compositions/components/<nome>/. Vetores/operações booleanas auto-rasterizam via exportação da Fase 1. Passo 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 herói): 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 são limites verticalmente cortados (o mapeador emite text-box-trim para estes; desvio medido sem ele era de ~6px em uma fonte de 70px). Se a comparação mostrar desvio que o mapeador não cobre, reporte-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 você; 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 desconhecia qual é o 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 de skill no início e no final (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 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 quadro 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 snippets do motion.dev (a codificação confiável — os snippets CSS esticam 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 autoral — o wrap é realizado pelo reinício repeat), e preserva eases 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 quadro raiz da coorte através do conector disponível e execute node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y — ele compara deltas de energia de movimento (fidelidade de importação estática é cancelada) e falha abaixo de 15dB mínimo de PSNR de movimento (calibrado: fiel ≈ 20+, divergente ≈ 5). Meça --crop das bordas reais do cartão do render, não adivinhe. FALHA significa verificar novamente a tradução, não o limiar.
  3. motionToGsap(doc) → emitTimelineScript(spec) → injete como um <script> após as tags CDN do GSAP + CustomEase. Pausado, finito, registrado em window.__timelines com uma chave literal.
  4. Trilha intraduzível (conduzida 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: trilhas conduzidas por shader — o caminho de exportação do Figma achata shaders para a cor base (veja Shaders abaixo), então uma bake 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 está em motionEase.ts; sinalize o fallback ao usuário quando ele for acionado.
  5. Execute npx hyperframes check antes de considerar concluído.

Shaders (Fase 5 — principalmente manual)

O caminho de render do conector Figma não executa shaders (eles achatan para a cor base), e a 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 do shader nativamente no Figma (PNG ou Motion MP4), então importe-o como um asset/clip 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 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 anime o quadro inteiro como um corte de slide. Use "correspondência por ID do Figma" (especificação §5.1.1) para decidir quais quadros contêm o mesmo elemento (link de ID exato via o conector ou a importação de componente mais recente). Onde a correspondência por ID falha para camadas duplicadas ou renomeadas, a correspondência espacial é aceitável (coordenadas de caixa delimitadora normalizadas por quadro). Faça fallback para animação de slide apenas como último recurso e rotule para o usuário que partes são correspondidas e quais são slides.

A reconstrução tem suas próprias etapas:

  1. Colete todos os quadros de cena da seção selecionada — sem excluir nenhum antes de verificar que eles não se sobrepõem.
  2. Exporte assets de todos os quadros via Fase 1 (implícita, não mencionada ao usuário — o cache garante que eles estejam disponíveis).Esta etapa pode ser claramente anexada a uma execução de CLI — quando o usuário diz "importe este storyboard", execute hyperframes figma asset <quadro1:nodeId> <quadro1:nodeId2> ... e hyperframes figma asset <quadro2:nodeId> <quadro2:nodeId2> ... para asset de cada quadro, mais para quaisquer outros assets referenciados.
  3. Monte a timeline de animação: interpole os assets quadros-chave do Figma para GSAP conforme as regras de "Movimento" acima (Fase 4), mas sem um conector: você está traduzindo entre estados de design em vez de código de protótipo em execução. A interpolação é sempre na forma de um script de timeline GSAP — nunca uma transição CSS de cross-fade onde o movimento poderia ser interpolado em JS puro. Aqui está uma heurística de interpolação: se a opacidade do layer muda 0→1, é um fade-in (1→0 um fade-out); se a posição muda mais de um limiar (por exemplo, 10 px), é uma translação; cor é uma transição de cor; escala (caixa delimitadora que muda de largura/altura com centro estável) é uma escala, e assim por diante.
  4. Embuta os dados de movimento como um slot de produção em vez de um render final: anexe o script de timeline ao window.__timelines do HTML de saída final, igual "Movimento da Fase 4" acima, e defina a composição pai para reproduzir o script quando renderizado. Não se preocupe em ajustar cada curva de facilitação — desde que o movimento seja animado em vez de cortado, a diferença é principalmente questão de gosto. (especificação §5.10)

Regras Gerais

Cache e Reimportação

Cada comando da CLI de hyperframes figma congela seu resultado em uma estrutura de diretórios conhecida (.media/figma-cache/) para que reexecutar a mesma importação seja instantâneo e não consuma uma chamada REST. A reimportação para o mesmo fileKey:nodeId:format:scale:version é idempotente: ela atualiza apenas se o conteúdo do Figma tiver mudado (a versão do arquivo é verificada).

Sobre a Mão Humana

Nunca modifique os ativos importados. O agente pode sugerir tempos e opções de facilitação para animações, mas não edite diretamente o HTML/JS/CSS de saída para "melhorar" o resultado — qualquer ajuste manual invalidaria a validação de fidelidade subsequente. Se um erro de design for aparente, ele deve ser corrigido no Figma e reimportado.


Esta skill está em desenvolvimento ativo. À medida que o ecossistema Remotion amadurece, a representação de saída mudará de HTML + GSAP para componentes React + Remotion, enquanto a lógica central de transformação Figma→asset permanece a mesma.

Individual skills in this repo

This repo contains 6 individual skills — each has its own dedicated page.

MattiaIppoliti/tia-skills

The technique catalog: five velocity-matched SEAMS (zoom-through, INVERSE zoom-through, cut-the-curve, waterfall cut, rack-focus blur-cut) plus the two in-scene techniques — waterfall ENTRY (staggered arrival cascades for title cards / segment openers) and the nudge curve (slow-fast-slow three-phase group slides). Covers partial-travel (~12% of frame) velocity matching via mirrored power4 eases, the Z scale-sign rule, size-scaled blur (10px text / 18-20px full-frame), word-by-word staggered cuts, cascade pacing by element weight, and the 10/65/25 slide ratio. Read before authoring any transition, text-beat handoff, kinetic text entry, or group reposition. [depth, zoom, inverse-zoom, scale-sign, mirrored-zoom, rack-focus, pacing, velocity, cut-the-curve, waterfall, stagger, cascade, kinetic-text, title-card, segment-opener, nudge, slide, easing, group-motion, z-depth, motion-graphics, cinematic, transition, blur, directional-continuity]

MattiaIppoliti/tia-skills

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

MattiaIppoliti/tia-skills

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

MattiaIppoliti/tia-skills

Use when audio already placed in a HyperFrames composition needs to be mixed: fade-in/fade-out, crossfade, track gain or volume, volume automation, ducking, a music bed that fights a voiceover (voiceover carve), effects on a track (EQ, compressor, limiter, gate, saturation, delay, reverb, chorus, phaser, bitcrush), or automation envelopes drawn on a track's volume or any effect parameter. Don't use for sourcing or generating audio — finding BGM, SFX, or making a voiceover is `/media-use`. Don't use for clip timing or track layout, which is `/hyperframes-core`.

MattiaIppoliti/tia-skills

Drive the Remotion CLI development loop: scaffold, studio, type-check, compositions, still probes, single and batch render, bundle, Lambda and Cloud Run rendering, benchmark, versions, upgrade, and GPU checks. Also use when diagnosing a build or render failure, or when looking for a capability the retired HyperFrames CLI used to own.

MattiaIppoliti/tia-skills

The composition contract for building one renderable Remotion project. Use for project structure, `<Composition>` registration, `<Sequence>` timing, layer/track ordering, scene components, props and schemas, framework-owned media playback, deterministic-render rules, and validation. Also covers Tailwind projects and the STORYBOARD.md / SCRIPT.md plan formats. Read before writing composition code.

Habilidades Relacionadas