Kit Buscar

kit-buscar — o que já existe no acervo

Antes de qualquer comando: resolva o SKILL_DIR

Todo comando abaixo roda um script que viaja junto desta skill, em SKILL_DIR/scripts/. Defina SKILL_DIR como o caminho absoluto da pasta que contém ESTE SKILL.md que você acabou de ler — o seu harness informou esse caminho no resultado da leitura. Funciona em qualquer hospedeiro, sem depender de variável de ambiente de nenhum agente específico:

~/.claude/plugins/cache/cannonball/cannonball/<v>/skills/<nome>/SKILL.md
~/.codex/skills/<nome>/SKILL.md
~/.gemini/skills/<nome>/SKILL.md
~/.agents/skills/<nome>/SKILL.md

Em todos, SKILL_DIR é a pasta do SKILL.md, e SKILL_DIR/scripts/ está ao lado.

Antes de escrever qualquer hero, seção ou página, pergunte ao acervo. Gerar do zero o que já existe é desperdício e produz resultado pior que uma peça que já rodou em produção.

Primeiro: veja de que acervo estamos falando

O acervo é do usuário e muda. Ele pode estar vazio (instalação nova), ter dez peças ou ter milhares. Nada nesta skill afirma um número — quem afirma é o acervo:

python "${SKILL_DIR}/scripts/perfil.py"

Isso devolve, do estado atual: famílias e quanto cada uma tem, setores, stacks, cobertura por função, lacunas (função sem nenhuma peça), quantidade de armadilhas registradas e os avisos de saúde (asset morto, fonte não entregável).

Rode uma vez por conversa, na primeira busca. É o mapa; sem ele você chuta filtro.

O perfil.py termina com um bloco POR ONDE SEGUIR, que muda conforme o acervo: numa instalação nova ele manda vincular a pasta antes de qualquer ingestão. Repasse isso ao usuário — é o passo que, esquecido, deixa o material dele em ~/.cannonball em vez da pasta que ele queria, e mover depois é trabalho manual.

python "${SKILL_DIR}/scripts/vincular.py" --para "<pasta do usuário>"

Se o perfil disser que o acervo está vazio, ou só com as peças de exemplo, diga isso em uma linha e siga construindo do zero — mas ofereça guardar o resultado depois com /kit-ingerir. A partir da segunda peça a busca já começa a valer, e o acervo passa a melhorar sozinho: cada ingestão aumenta o que esta skill encontra e afina o que a kit-cor e a kit-tipo medem.

Como buscar

python "${SKILL_DIR}/scripts/buscar.py" "landing de clínica odontológica"

Filtros combináveis:

Não sabe que setor existe? --listar setor antes de chutar.

Busque por função, não só por aparência

O acervo nasceu indexado por caráter visual ("creme editorial") e por técnica ("pin, scrub, lenis"). Faltava o eixo mais óbvio: o que a peça faz. Sem ele, um template com 475 ocorrências de carrinho e catálogo sumia de uma busca por "grade de produtos".

python "${SKILL_DIR}/scripts/buscar.py" --tag catalogo --tag carrinho

Duas etiquetas para a mesma função, e a diferença importa:

• catalogo — o código implementa. Você copia e funciona.
• spec-catalogo — um design system documenta como deve parecer. É referência de estilo, não código que roda.

Quanto o acervo cobre de cada função, agora:

python "${SKILL_DIR}/scripts/perfil.py" --funcao

A linha lacunas: é a mais útil das duas: são as funções sem nenhuma peça. Quando o pedido cai numa lacuna, não procure mais — construa, e ingira depois. É assim que o acervo fecha buraco: a lacuna de hoje vira a peça de amanhã.

Peça construída para fechar lacuna deve nascer sem nada fixo: toda a aparência saindo de variável CSS (--kit-* ou o token do próprio site), com fallback final em currentColor/inherit, e texto, regra de negócio e campos vindo por prop. Cor, fonte ou raio escritos dentro do componente amarram a peça ao primeiro cliente e matam o reuso — que é a única razão de ela estar no acervo.

Filtre pela stack do projeto

Se a stack já foi dita nesta conversa, use sempre — devolver uma peça Framer para quem trabalha em Next.js gasta o tempo do usuário:

python "${SKILL_DIR}/scripts/buscar.py" "<consulta>" --stack nextjs

Quais stacks o acervo cobre, e quanto de cada uma, sai na linha stacks: do perfil.py. Filtrar por uma stack que o acervo mal tem devolve nada e parece defeito de busca — confira o perfil antes de concluir que "não existe".

Não interrogue a cada busca. Pergunte a stack só quando ela mudar o resultado de verdade — tipicamente na primeira busca da conversa, ou quando o usuário trocar de projeto. Para montar um site inteiro, quem pergunta é a kit-montar.

Quando o usuário citar uma biblioteca que o perfil não lista (é comum com Astro, anime.js, magnetic.js), diga na hora, antes de buscar: as peças ainda servem como referência de técnica, mas não colam prontas — vão precisar de porte à mão.

As famílias

Quantas peças cada família tem sai no perfil.py. O que não muda é a natureza de cada uma, e isso decide como a peça se usa:

• receita — composição de peças que já deu certo num projeto real. Ponto de partida.
• template — projeto de site completo e rodável, com rotas, componentes e build. Você clona e adapta, não constrói.
• design-system — identidade visual extraída de um site real: paleta com papel de cada cor, escala tipográfica, espaçamento, do's and don'ts, CSS custom properties. Não tem layout: dá o como se parece, não o o quê.
• efeito — código pronto. Wrapper WebGL que envolve HTML já existente (vidro, ASCII, partícula, glitch) ou objeto 3D. Você copia.
• ui — componente React pronto. Você copia.
• animacao — demo isolada de uma técnica: menu overlay, scroll com pin, transição de rota, reveal. Você extrai a técnica, não a página.
• html — página completa sem build. Abre direto no navegador.
• mcp — a ficha está no acervo, o código não: é gerado sob medida por um servidor MCP na hora (stack, styling, TypeScript, presets). Você chama a ferramenta.
• prompt — especificação em linguagem natural de uma página ou hero inteiro. Você executa para gerar o código. Flexível, custa tokens, resultado varia.

Ordem de preferência quando mais de uma serve: receita → template → código (efeito/ui/animacao) → prompt. Prompt é o último porque re-gera tudo e o resultado varia; template é o primeiro porque já roda.

Catálogo servido por MCP — a ficha está aqui, o código vem de fora

Peças indexadas com via: mcp:<fonte> têm ficha no acervo e código nenhum. Quando um resultado sai com essa marca, a busca já imprime a chamada pronta. Peça o código com a stack do projeto — exemplo com o OriginKit, que é o caso mais comum:

get_component(name="fluidtrail", stack="nextjs", styling="tailwind", typescript=true)

stack aceita framer react nextjs vite; styling aceita tailwind css cssmodules. Há ainda preset (variante nomeada) e tweaks (mapa de prop → valor, que vence o preset). Sem nenhum dos dois, vem a configuração de preview padrão.

Três coisas que valem para todo componente do OriginKit:

1. São autorados em Framer. A conversão para Next.js funciona, mas deixa resíduo — shim de RenderTarget, JSDoc @framerSupportedLayoutWidth, props: any. Limpe antes de entregar; não é código nativo Next.
2. Exige Tailwind CSS v4. O próprio agentInstructions avisa, e também que os arquivos vão em src/components/originkit quando existe src/.
3. framer-motion vs motion. Parte usa um, parte usa o outro. Padronize num só no projeto — dois pacotes de animação no mesmo bundle é peso e conflito de graça.

Um catálogo externo só compensa onde o acervo tem lacuna — compare com perfil.py --funcao antes de puxar. Onde os dois cobrem a mesma coisa, o acervo vence: é seu, é julgado, não tem cota, e carrega as armadilhas que você já pagou.

Motion Sites — catálogo de prompts, com cota apertada

Se o MCP estiver ligado, ele é a maior fonte de prompt de página pronta. A cota é o que manda no uso. Ver ${SKILL_DIR}/references/motionsites-genjutsu-designdna.md.

Nunca gaste get_prompt num prompt que já está no acervo. Confira antes com buscar.py "<título>" --familia prompt. São 3 aberturas na vida da conta; queimar uma no que você já é dono é desperdício.

Duas coisas que valem sempre, e são de graça:

1. Preview visual, para a peça que não tem. O acervo agora guarda imagem das peças que rodam sozinhas — família html, e animacao/template com um index.html dentro. A busca imprime o caminho do preview.png quando existe, e o painel (python "${SKILL_DIR}/scripts/painel.py" --abrir) mostra a miniatura. Falta imagem de componente React solto, que precisaria de build; para esses, um search_prompts pelo título devolve o preview_url. Mostrar vale mais que descrever, principalmente com cliente na frente.
2. get_related_prompts. Você sabe quais dos seus prompts funcionaram. Peça os parecidos de um que deu certo e o catálogo inteiro vira extensão do acervo, sem cota.

Se acabar usando um prompt que não existe aqui, ingira depois — senão gastou uma das 3 e não guardou.

GetLayers — composição, vídeo e cena 3D original

Outro MCP, outra função. Leia ${SKILL_DIR}/references/getlayers.md antes de usar; getlayers_start é chamada obrigatória e devolve o guia inteiro.

Ele tem três coisas que um acervo de peças não tem por natureza: composições (esqueleto de layout com wireframe ASCII), backgrounds de vídeo, e autoria de cena 3D nova a partir de referência (scene_lab).

getlayers_compositions é gratuito e resolve o pior vício de montagem. Consulte por papel (hero, card-grid, cta, footer…) antes de desenhar qualquer seção nova — mesmo quando todas as peças vierem do acervo. O acervo guarda peça pronta, mas nenhum vocabulário abstrato de arranjo; sem isso, seção nova tende sempre à mesma pilha centralizada.

Fora esses três pontos, o acervo vem primeiro: é seu, é julgado, não tem cota, e carrega as armadilhas que custaram projeto real (o perfil.py diz quantas).

Duas regras de operação que não podem ser esquecidas:

• getlayers_materialize tem cota; buscar não tem. Navegue à vontade, materialize com intenção. Nunca materialize para "dar uma olhada".
• Mídia nunca vem no contexto. Um template cujo .glb ou .mp4 não foi baixado renderiza em branco, sem erro. Baixe antes de editar e confira o tamanho de cada arquivo — link expirado grava página de erro com nome .mp4.

E o conflito de stack: o ambiente nativo do GetLayers anima com react-spring, o acervo é GSAP. Composição, paleta, fonte e background atravessam (são neutros de biblioteca); motor de animação não.

Buscar um design system

Três eixos funcionam bem:

# por caráter visual — é o que melhor funciona
python "${SKILL_DIR}/scripts/buscar.py" "creme quente editorial papel" --familia design-system

# por marca de referência (cada sistema lista marcas parecidas)
python "${SKILL_DIR}/scripts/buscar.py" "Aesop" --familia design-system

# por tema
python "${SKILL_DIR}/scripts/buscar.py" --tag tema-dark --setor fintech

Também dá para buscar por fonte (Inter, Geist, SF Pro) ou por hex da paleta.

Cuidado com a concentração. Todo acervo de design system vira aglomerado: os sistemas são extraídos de sites reais, sites reais copiam uns aos outros, e o resultado é uma dúzia de identidades quase intercambiáveis sob nomes diferentes. O aglomerado mais comum é o editorial branco — parede branca, tipografia preta, acento único ou nenhum, fotografia carregando toda a cor.

Ache os do seu acervo antes de recomendar:

python "${SKILL_DIR}/scripts/buscar.py" --listar tag
python "${SKILL_DIR}/scripts/cor.py" --vies

Tag com contagem muito alta é aglomerado; cor.py --vies mede o mesmo pelo lado da cor e diz de quantos sistemas a sua escolha está chegando perto.

Duas consequências práticas:

• Para escolher dentro do aglomerado, o que diferencia não é o caráter (é o mesmo), é o setor, o par tipográfico e qual é o acento único. Filtre por --setor e leia as fontes, não a tagline.
• Para fugir dele, peça explicitamente o que ele não é: cor saturada, maximalismo, fundo escuro, dois ou mais acentos. Os sistemas que quebram o padrão do acervo são os de maior valor marginal — e são poucos, então vale saber quais são de cor: cor.py --vies lista os que fogem.

Cada arquivo em acervo/design-systems/<id>/design-system.md traz CSS custom properties prontas, uma seção Do's and Don'ts e um Agent Prompt Guide com exemplos de prompt por componente. Leia o arquivo antes de aplicar — o resumo no índice é só a porta de entrada.

Componentes por tipo

A família ui cresce rápido e vira o saco de gatos do acervo. Filtre por --estrutura, e veja os valores que existem de verdade com buscar.py --listar estrutura. Os que costumam aparecer:

Sempre leia o PRECISA JUNTO: que a busca imprime. Componente vindo de registro (smoothui, shadcn) costuma puxar outros — colar sem a base quebra o import, e o erro não diz que falta uma peça, diz que falta um módulo.

Quando a peça veio de um registro, a busca também imprime o npx shadcn@latest add ... correspondente, caso instalar seja melhor que copiar.

Buscar por técnica

Templates e animações são indexados também pelas técnicas que empregam. Isso abre um eixo de busca que o resto do acervo não tem:

python "${SKILL_DIR}/scripts/buscar.py" --tag pin --tag scrub
python "${SKILL_DIR}/scripts/buscar.py" "transição de página" --familia animacao
python "${SKILL_DIR}/scripts/buscar.py" --tag shader --stack nextjs

Vocabulário disponível: scrolltrigger, pin, scrub, split-text, flip, observer, timeline, lenis, three, shader, canvas-2d, clip-path, mask, mix-blend, sticky, page-transition, fisica, webgl-post.

Onde moram os assets de template

Templates e animações têm só o código no acervo. As imagens, vídeos e fontes (835 MB no total) continuam no projeto original — o campo projeto_origem no item.json diz onde. Ao usar uma dessas peças, avise que a mídia vem de lá e normalmente será trocada por material do cliente.

Lendo o resultado

Cada resultado traz USAR: e EVITAR:. Leia os dois. O EVITAR é o que impede você de entregar uma peça que depende de cursor num projeto mobile-first, ou um efeito de quebra de vidro num site de banco.

O marcador * é favorito. ~ é rascunho — incompleto, confira antes de prometer.

ARMADILHA: vale mais que o resto da ficha. É o que foi descoberto montando de verdade — vídeo morto, contraste que reprova, bug de cleanup, reset que anula o espaçamento. Cada uma diz de qual projeto veio. Leia antes de prometer a peça ao usuário, e repasse a ele o que for relevante: são horas economizadas.

O aviso [!] N assets externos que podem cair significa que a peça referencia imagens ou vídeos hospedados em figma.site, cloudfront ou similar. Eles podem já ter expirado. Avise o usuário e troque por assets dele.

O acervo dá a peça, não o critério

O acervo responde "o que eu tenho pra isso". Ele não responde "isso deveria existir assim". Quando a escolha entre duas peças igualmente aderentes travar, ou quando o usuário disser que está tudo "no automático", o critério está em ${SKILL_DIR}/references/fundamentos-visuais.md — as perguntas do §1, os cinco níveis do §2 e os sete testes do §8.

O que mais aparece na prática, e é o risco direto de montar por busca: escolher sempre a peça que cabe na categoria produz um site que poderia ser de qualquer concorrente. É a mesma conformidade que a tag de contagem alta e o cor.py --vies denunciam por outro caminho. Ao apresentar candidatos, diga qual deles pertence ao cliente e qual apenas pertence ao setor — a diferença costuma decidir.

Como apresentar ao usuário

Não despeje a saída bruta. Traga 2 a 4 candidatos, diga em uma linha por que cada um serve para o caso dele, e faça uma recomendação. Se nada servir de verdade, diga isso — inventar aderência gasta o tempo dele numa peça errada.

Se a busca não achar nada, tente termos mais amplos (o acervo é descrito em português, mas os prompts internos são em inglês) e depois --listar setor.