imgcli

O que imgcli faz?

Componentes copiáveis para vídeos Remotion. Os componentes são instalados via shadcn e ficam em components/imgcli/ — você é dono do código.

Instalação

Pré-requisitos: um projeto Remotion (npx create-video@latest).

# Instalar a partir do registry Imgcli
npx shadcn@latest add https://imgcli.com/r/text-reveal.json

# O componente fica em components/imgcli/text-reveal.tsx

Para usar a forma abreviada @imgcli/<name>, mapeie @imgcli para https://imgcli.com/r/{name}.json em components.json. Veja o guia de instalação para configurar o projeto.

Dependências instalam automaticamente

Muitos componentes puxam outros via registryDependencies — shadcn os instala transitivamente. Por exemplo, instalar search-typing também puxa snap-cn-ui, input e caret.

• @imgcli/snap-cn-ui é a biblioteca central compartilhada (hook de timeline, contexto de tema, matemática de cores). A maioria das Primitivas de UI depende dela. Raramente você a instala diretamente.

Dois níveis

Imgcli tem dois tipos de componentes — eles têm APIs diferentes:

• Nível de Animação (cenas e animações) — animações de texto, transições, fundos, simulações de blocos de UI, cartões de marca/sociais, composições completas. Baseados em quadros. Props compartilhados: speed (multiplicador de tempo), e para texto: fontSize, color, fontWeight.
• Primitivas de UI (snap-cn-ui) — primitivos no estilo shadcn orientados por timeline. Dois disponíveis hoje: input e caret. Props baseados em estado (state, style, size, theme) — o estado aberto/digitando é uma função pura da timeline. Sem prop speed. Construídos sobre @imgcli/snap-cn-ui.

Categorias de componentes

Escolha com base no que você está construindo. O catálogo é dividido em um arquivo por componente em references/components/. Comece em references/components/index.md — uma tabela de roteamento agrupada por estas categorias com um sinal de Use for / Avoid for por componente. Examine-a, escolha candidatos e depois abra apenas os arquivos references/components/<name>.md que você precisa (props completos, exemplo, todas as notas de uso / não uso). Não leia todos os arquivos.

Categoria	Nível	Componentes
Texto e Títulos	Animação	text-reveal, type-morph, text-swell, text-highlight, text-swap, text-build, text-rewrite, text-select, word-flip, punch-lines, word-gather, word-wheel
Legendas	Animação	word-captions, karaoke-captions
Entrada de Chat de IA	Animação	prompt-send, search-typing, prompt-zoom, answer-stream, answer-highlight, agent-steps
Telas e Dispositivos	Animação	phone-frame, laptop-frame, terminal-simulator, screen-recording, cursor-track
Logotipos	Animação	logo-assemble, logo-flicker, logo-collapse, logo-drift, block-wordmark, wordmark-cut
Cenas	Animação	announce-title, hero-launch, orbit-gallery, moodboard-reveal, status-cycle, count-grid, roster-grant, orb-swarm, reel-collage, card-rail, cut-lockup, bloom-lockup, gather-lockup, sky-lockup
Prova Social	Animação	follower-rush, channel-thread
Efeitos	Animação	pulsing-border
Primitivas de UI	snap-cn-ui	input, caret (+ snap-cn-ui, a biblioteca central compartilhada)

Use o índice de componentes ao vivo para confirmar quais nomes são instaláveis. As referências abaixo incluem nomes antigos e seus substitutos.

Padrões de componentes

As convenções diferem por nível — não assuma props do nível de animação em uma primitiva.

Nível de Animação (cenas e animações)

• Interface Props nomeada por componente (ex.: TextRevealProps).
• speed?: number — multiplicador global de tempo (padrão 1), aplicado como frame * speed.
• Componentes de texto: fontSize, color, fontWeight.
• Transições de cena para cena não estão neste registry — use as próprias transições do Remotion @remotion/transitions (slide, wipe, fade, flip) dentro de um <TransitionSeries>.
• className?: string na raiz.

Primitivas de UI (snap-cn-ui)

• Baseadas em estado, não baseadas em speed: state (ex.: "open" / "closed"), style, variant, size, theme?: Partial<SnapCnTheme>.
• O estado aberto/fechado/ativo é uma função pura da timeline (predefinições com keyframes).
• Componha primitivas de camada modal (dialog, alert-dialog, drawer) com um elemento de gatilho — veja o exemplo de cada componente.

API de Animação

import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";

const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
const scale = spring({ fps, frame, config: { damping: 12, mass: 1, stiffness: 100 } });

// Aleatoriedade determinística (NUNCA Math.random())
import { random } from "@remotion/random";
const jitter = random(`seed-${frame}`);

Estrutura de composição

import { Sequence, Series } from "remotion";

<Sequence from={30} durationInFrames={60}>
  <TextReveal text="Ship it in React" />
</Sequence>

<Series>
  <Series.Sequence durationInFrames={60}><SceneA /></Series.Sequence>
  <Series.Sequence durationInFrames={60}><SceneB /></Series.Sequence>
</Series>

Canvas e temporização

• Padrão do Canvas: 1280×720 @ 30fps. Os componentes são projetados para ele.
• Defina o orçamento de cada Sequence em torno da duração natural do componente — a coluna Length em components/index.md (e Natural length de cada arquivo). Sub-orçar corta a animação; super-orçar deixa ar morto.
• Combinação de tom: cada entrada do catálogo carrega uma tag vibe (tech/premium/data/clean/ playful/social) — escolha componentes cuja vibe combine com a marca.
• Paleta e fontes: mantenha-se dentro dos tokens da biblioteca (references/design.md → tokens) para que seus próprios elementos não conflitem.

Padrões de design — evite AI-slop

Ao escrever seu próprio texto, moldura de cena ou cartões (não os componentes prontos), mantenha-se contido:

• Sem letter-spacing decorativo em texto de corpo/título que você adicionar.
• Sem text-transform: uppercase / TUDO EM MAIÚSCULAS como padrão — prefira caixa de frase (Launch, não LAUNCH).
• Sem preenchimentos gradientes de texto ou lavagens gradientes decorativas — gradientes apenas como fundos intencionais.
• Sem brilho / sombras projetadas coloridas ou grandes raios de desfoque (blur > ~24px, propagação, multicamadas) — elevação sutil de 1px apenas.

Exceção: nunca remova estes de componentes cuja essência é o efeito — a palavra gradiente de word-flip, o baralho de cores de block-wordmark, o brilho de announce-title, o próprio pulsing-border, e os contornos pesados das predefinições de legenda são todos legítimos. As regras regem suas adições, não a biblioteca.

Exemplos completos de fazer/não fazer: references/design.md. Para qualidade de movimento (temporização, antecipação, encenação, suavização), veja references/motion-principles.md.

Armadilhas (específicas do Imgcli)

• Nenhum componente de transição é fornecido — uma mudança de cena é <TransitionSeries.Transition> de @remotion/transitions, não um componente Imgcli. text-swap troca uma linha, não uma cena.
• A rolagem do terminal é instantânea — translateY em função degrau, nunca mola/suavize a rolagem.
• overflow: hidden em layouts divididos — evita quebra de conteúdo durante animações de largura.
• O piscar do cursor é determinístico — Math.floor(frame / 15) % 2 === 0, não intervalos.
• Arquivos estáticos vão em public/ — carregue via staticFile('cursor.svg'), não imports.
• Cartões sociais renderizam offline — avatarUrl="" / coverUrl="" recorrem a gradientes; sem fetch.

Regras gerais do Remotion (sem Math.random(), sem setInterval, anime transform não top/left, carregue fontes antes de renderizar) estão nas habilidades próprias do Remotion, não nesta: npx skills add remotion-dev/skills.

Compondo um vídeo

Não despeje componentes — componha uma história. Quando solicitado a construir um vídeo completo ("fazer uma demonstração de produto", "vídeo de changelog", "introdução para minha landing"):

1. Decida a estratégia — template pronto vs compor a partir de componentes vs construir um novo componente. Veja references/anatomy.md §1.
2. Siga os momentos — uma demonstração de produto é Gancho → Posicionamento → Revelação do produto → Funcionalidades → Prova → CTA (os dois últimos opcionais). Veja references/anatomy.md §2.
3. Use a receita — references/archetypes/index.md direciona para construções por arquétipo: contrato de conteúdo (inferir → perguntar → placeholder), variantes de duração, slots de momento para componente e um esqueleto trabalhado de <TransitionSeries>.
4. Escolha o componente de cada momento em references/components/index.md; combine a tag vibe com a marca e defina o orçamento de cada <Sequence durationInFrames> em torno de sua duração natural.
5. Verifique o padrão de qualidade — um acento, tipo cinético em caixa de frase, conteúdo real, sem halos de brilho, sem enumeração de lista de funcionalidades, sem lavagem gradiente decorativa atrás do tipo. Veja references/anatomy.md §3.

Fluxos de trabalho

Para um vídeo completo, use a Skill de fluxo de trabalho correspondente quando disponível. Cada um compõe componentes Imgcli momento a momento e verifica o resultado no Remotion. O guia do agente cobre instalação e descoberta pública de componentes.

• remotion-launch-video para filmes de lançamento, anúncios, promos do Product Hunt / X.
• remotion-product-demo para demonstrações a partir de uma gravação de tela real, demos de CLI e apps de IA.
• remotion-motion-graphics para tipo cinético, animações de logotipo, estatísticas e aberturas curtas.
• remotion-kinetic-typography para texto animado e cartões de título.
• remotion-logo-animation para revelações de logotipo, vinhetas de introdução e encerramento.
• remotion-explainer-video para vídeos explicativos narrados com legendas fixas.

Referência

• references/anatomy.md — compondo um vídeo completo: estratégia (template/compor/novo), os momentos de demonstração de produto e o padrão de qualidade bom-vs-slop.
• references/archetypes/index.md — direcionador para receitas de construção por arquétipo (demonstração de produto principal + changelog, anúncio de funcionalidade, showcase de OSS, demonstração de ferramenta CLI, reel de depoimento, resumo do ano, revelação de preço, bumper de logotipo): contrato de conteúdo, variantes de duração, mapa de momento para slot.
• references/components/index.md — tabela de roteamento (todos os componentes, agrupados por categoria, com Use for / Avoid for). Abra references/components/<name>.md para props completos, exemplo e notas de uso / não uso de um componente.
• references/design.md — padrões de design anti-slop (fazer/não fazer) + tokens de design (paleta, fontes, canvas).
• references/motion-principles.md — princípios de design de movimento adaptados ao Imgcli + Remotion.
• references/anti-patterns.md — erros comuns de geração e suas correções.