O que cursorfit faz?
Um cursor personalizado é uma decisão de design com uma conta de usabilidade anexada. A maioria das skills de cursor vende o efeito e ignora a conta. Esta lê o site primeiro, decide se vale a pena pagar a conta, e só então constrói.
A promessa em uma linha: o cursor combina com este site, ou você descobre por que não deveria ter um.
O que isso responde
- Este site deveria ter um cursor personalizado?
- Qual família, nas cores deste site, na velocidade deste site?
- O que ele faz sobre um botão, uma imagem, um parágrafo, um controle desabilitado, uma tela sensível ao toque?
A regra que mantém isso honesto
Toda afirmação na recomendação deve citar algo encontrado no repositório: um arquivo, um token, um valor medido, uma contagem. Se não puder, é uma opinião e deve ser rotulada como tal. "O site parece moderno e minimalista" não é evidência e nunca deve aparecer na saída.
Pipeline
| Estágio | Saída |
|---|---|
| 0. Ler o repositório | framework, mapa de arquivos, código de cursor existente |
| 1. Auditar | cursorfit.json — tokens, tipo, movimento, densidade, controles e um relatório de cobertura |
| 1b. Ler | os componentes, estilos inline e classes de utilitário que a auditoria não conseguiu ler |
| 2. Pontuar | cinco eixos, cada um com evidência e um nível de confiança; assinatura de movimento |
| 3. Preencher lacunas | no máximo três perguntas, cada uma com um padrão |
| 4. Decidir | um primário + dois alternativos, cada um com sua desvantagem; substituições permitidas com evidência |
| 5. Construir | arquivos escritos no repositório, conectados ao ponto de entrada |
| 6. Verificar | greps, o build e uma verificação no navegador com scripts/verify.mjs |
| 7. Relatar | o formato em references/recommendation.md |
Não pule do estágio 1 para o estágio 4. A pontuação é o que impede a resposta de ser gosto disfarçado de análise.
Estágio 0 — Ler antes de decidir
Mapeie o repositório antes de pontuá-lo. Você precisa saber:
- Framework, porque decide onde o cursor é montado e se
cursor: nonenobodyserá substituído por uma biblioteca de componentes. - Onde os estilos reais estão. Um
tailwind.configmais um arquivo CSS escrito à mão de 2.000 linhas é comum, e o arquivo escrito à mão geralmente vence. Pontue o arquivo que renderiza. - Se um cursor já existe. Procure por
cursor: none,cursor: url(,data-cursor,mousemove,mouse-follow,custom-cursor. Se existir, é um trabalho de reparo antes de ser um trabalho de design — vejareferences/gating.md.
Estágio 1 — Auditar
Execute o auxiliar se o Node estiver disponível:
node scripts/audit.mjs <caminho-do-repositorio> --out cursorfit.json
É um leitor estático. Não abre navegador e não envia requisição de rede. Ele extrai dependências, tokens de cor, pilhas de fontes, keyframes, easings, durações, espaçamento, contagens de controles, código de cursor existente e se as proteções de acessibilidade já existem.
Ele conta <Button> e <Link> assim como <button> e <a>, e lê um bloco de cobertura: quantos arquivos de estilo e marcação ele analisou, quantos estilos inline, listas de classes de utilitário e arquivos CSS-in-JS que não conseguiu ler, e quais cinco arquivos valem a pena abrir primeiro. Uma pontuação só é tão boa quanto essa cobertura, então leia coverage antes de ler scores.
Se o auxiliar não puder ser executado, faça a mesma extração manualmente usando a tabela de sinais em references/audit.md. Cada sinal naquela tabela mapeia para uma entrada de pontuação, então pular um significa que esse eixo se torna UNKNOWN em vez de ser adivinhado.
Estágio 1b — Ler o que a auditoria não conseguiu
A análise estática tem uma lista de pontos cegos conhecida, e fingir que não tem é como um perfil fica confiante sobre um site que leu pela metade. Abra os arquivos em coverage.hotspots e responda três perguntas para cada:
- Qual padding, raio e tamanho de tipo são realmente renderizados? Estilos inline e classes de utilitário contêm valores que a varredura de folhas de estilo nunca viu.
- Os wrappers de componente mudam a estrutura? Um
<Button>pode renderizar um<div>com um manipulador de clique, não um<button>. Isso muda a receita de estado-label, que conectadata-cursora um controle. - Há um contexto de layout ou empilhamento que a auditoria não conseguiu ver? Wrappers sticky, seções
overflow: hidden,isolation: isolate,backdrop-filter— qualquer um pode mover o que o cursor fica acima.
Regras para esta passagem:
- Leia apenas os pontos críticos mais o ponto de entrada e o shell de layout. Não o repositório inteiro.
- Se um ponto crítico mudar um valor medido em mais de ~20%, registre o valor corrigido e diga no relatório que veio da leitura, não do script.
- Se um ponto crítico não puder ser resolvido (estilos gerados, um tema em tempo de build), rebaixe o eixo afetado para
mediume diga qual arquivo causou isso. - Nunca re-execute a auditoria para melhorar um número. A saída do script é evidência, não um rascunho.
Estágio 2 — Pontuar
Cinco eixos, cada um 0–100, mais uma assinatura de movimento. Rubricas completas em references/profile.md.
CONTIDO ──────────▓▓▓ 74 EXPRESSIVO
PRECISO ▓▓▓▓▓▓▓▓░░░░ 58 ORGÂNICO
DENSO ▓▓▓░░░░░░░░░ 31 AÉREO
CALMO ▓▓▓▓▓▓░░░░░░ 47 ENERGÉTICO
PRODUTO ▓▓▓▓▓▓▓▓▓░░░ 68 EDITORIAL
Regras:
- Mínimo de dois itens de evidência por eixo. Menos significa
UNKNOWN, eUNKNOWNse torna uma pergunta de preenchimento de lacuna, não um palpite mediano. - As pontuações descrevem o site, não o cursor. Um site contido não está pedindo um cursor contido; está dizendo que um cursor chamativo seria a única coisa chamativa na página.
- A assinatura de movimento é medida, não sentida. Registre as curvas de easing reais, a duração mediana, a contagem de keyframes e se algo estica ou ultrapassa.
- Cada pontuação carrega uma confiança.
high,mediumoulow, vinda do bloco de cobertura da auditoria. Uma pontuação média é citada como uma faixa, não um número. Uma pontuação baixa não é citada — ela se torna uma pergunta de preenchimento de lacuna. Regras completas emreferences/profile.md.
Estágio 3 — Preencher lacunas
Faça no máximo três perguntas, e apenas para eixos que retornaram UNKNOWN ou para fatos que um repositório não pode conter. Cada pergunta vem com um padrão, então "não sei" ainda produz uma decisão.
As três que geralmente valem a pena perguntar:
- Quem chega primeiro a esta página? Clientes avaliando um produto / desenvolvedores lendo documentação / clientes julgando um portfólio. Padrão: clientes.
- Quanta personalidade o cursor pode carregar? Apenas polimento / notável / marcante. Padrão: notável.
- Alguma cor que deve ou não ser usada? Padrão: o token de marca mais saturado do repositório.
Nunca pergunte o que o repositório já responde. Nunca faça uma pergunta cosmética que o modelo pode decidir. Se a resposta não mudar nada na recomendação, não era uma pergunta.
Estágio 4 — Decidir
Pontue cada família em references/families.md contra o perfil, depois aplique os portões rígidos. magnetic é um modificador — é adicionado à família escolhida em um ou dois elementos e nunca pode ser o primário. Saída um primário e dois alternativos. Nunca um menu plano — um menu devolve a decisão para a pessoa que pediu.
Cada alternativo carrega sua desvantagem no mesmo parágrafo, não em uma nota de rodapé:
Alternativo B — revelação de máscara. Ajuste editorial mais forte dos três; custa uma camada de canvas sobre cada imagem de projeto, e parecerá quebrado em qualquer cartão cuja imagem falhe ao carregar.
"Manter o cursor nativo" é um veredito válido. Quando o site é pesado em leitura, pesado em formulários ou crítico para acessibilidade, diga isso — e ainda assim ofereça a opção de menor risco e seu custo, porque a pessoa pediu um cursor e recusar diretamente não ajuda ninguém.
Você pode substituir a classificação, mas nunca silenciosamente. Os números são suporte à decisão, não uma medição, e a auditoria não sabe o que não conseguiu ler. Uma substituição é permitida quando a passagem de cobertura encontrou algo que o script perdeu — um padrão de interação real, um componente que muda a estrutura de controle, um contexto de empilhamento que a varredura CSS não conseguiu ver. Para reivindicar uma, declare todos os quatro:
- a família que a auditoria classificou em primeiro e seu ajuste,
- a evidência específica que muda isso, com um caminho de arquivo ou um valor medido,
- a família que você está escolhendo em vez disso,
- o que o leitor perde ao aceitar a substituição.
Uma substituição sem caminho de arquivo é gosto. Gosto é permitido na última milha — tamanho, easing, o rótulo exato — nunca na escolha da família.
Estágio 5 — Construir
Implementações completas para cada família estão em references/recipes.md. Copie a receita, depois mude apenas o que o perfil diz para mudar.
Inegociáveis:
- A cor vem de um token, nunca de um novo hex. Vincule à cor de marca mais forte que a auditoria encontrou (
var(--neon-cyan),theme('colors.accent'), uma constante exportada). Um#00f0ffcodificado é a diferença entre "combina com seu site" e "combina com o site de onde foi copiado". - A camada de estado base vem com cada família. Link, botão, texto e desabilitado são resolvidos em
cursor.jse estilizados emcursor.cssantes de qualquer código de família ser adicionado. Nenhuma família os exclui;dotapenas reduz os números. Um cursor que não faz nada ao cruzar um botão está inacabado — o visitante não tem como diferenciá-lo de um adesivo. - Rótulos são o aprimoramento, não o estado.
[data-cursor]adiciona uma palavra sobre um estado que já existe. Se o build só reage onde o site foi anotado, a camada de estado está faltando. - O código da família T1 fica abaixo de ~90 linhas, sobre o núcleo compartilhado. Se a camada da própria família precisar de mais, a família está errada para o site. O núcleo tem ~100 linhas uma vez, porque agora carrega a camada de estado para cada família.
cursor: noneé aplicado pelo JS após o primeiro frame, nunca em CSS estático. Se o script falhar, o usuário mantém um cursor funcional.- Monte uma vez. Um cursor montado por rota resulta em dois, depois três.
- Touch não recebe nada. Nem um cursor menor. Nada.
Vanilla entrega como cursor.css + cursor.js e uma linha <script defer>. React entrega como um componente mais o mesmo CSS, montado acima do roteador.
Dois conjuntos de ativos prontos existem para que o build não pare na arte:
assets/shapes.css— sete silhuetas (círculo, anel, quadrado, mira, pílula, colchete, bolha). Adicione uma classe à marca; a escolha da silhueta vem do perfil.assets/cursors/*.svg— quatro cursores de imagem com seus valores de ponto de acesso, para a família T0. Branco com contorno escuro para sobreviver a seções claras e escuras.
Copie os arquivos para o repositório (geralmente public/cursors/ e src/styles/), não referencie a pasta desta skill em tempo de execução.
Estágio 6 — Verificar
Três níveis, em ordem. Cada um pega o que o anterior não consegue.
1. Greps. Execute as verificações estáticas em references/gating.md. São greps, não opiniões: pointer-events, position: fixed, aria-hidden, proteção de coarse-pointer, proteção de movimento reduzido, sem transition em transform, ocultar em mouseleave, verificação de contexto de mesclagem.
2. Build. npm run build ou tsc --noEmit. Um cursor que quebra o build não é enviado.
3. Navegador. Greps provam que o código diz as coisas certas; eles não podem provar que o cursor funciona. Se o Playwright estiver disponível, execute o harness:
node scripts/verify.mjs http://localhost:3000 --cursor .cf-cursor --json verify.json
Ele abre a página e verifica o que um grep não consegue: o elemento existe e é visível, tem pointer-events: none, ele lag e converge, hover muda seu estado, um clique ainda atinge o controle abaixo, o foco mantém seu anel, uma mudança de rota não gera um segundo, o console permanece limpo, um toque não o faz aparecer, e prefers-reduced-motion desabilita o seguimento. Dez verificações executadas por padrão; adicione --modal "#trigger" para uma décima primeira que abre uma sobreposição e compara seu empilhamento com o cursor.
Playwright é a única dependência opcional no pacote. Se não estiver instalado, ou a página não puder ser servida, faça as mesmas onze verificações manualmente em 1366×768 e 390×844 — e se não fizer, o relatório diz NOT_TESTED: rendered behaviour nessas palavras. Nunca implique que viu.
Uma verificação pulada não é uma aprovação. verify.mjs imprime pulos separadamente por esse motivo: significa que a página não expôs o suficiente para testar, e o relatório tem que dizer qual verificação foi pulada e por quê.
Estágio 7 — Relatar
Use references/recommendation.md. O relatório sempre termina com duas listas: o que olhar e o que está deliberadamente desabilitado.
Limites
- Código não é a renderização. A auditoria lê a fonte. Um
backdrop-filter, um contexto de empilhamento ou umtransformem um ancestral pode mudar a aparência do cursor, e a fonte não mostrará. - Análise estática só vê o que consegue analisar. A estilização pode estar em objetos inline, classes de utilitário resolvidas em tempo de build, CSS-in-JS ou internos de componente. A auditoria conta o que perdeu, nomeia os arquivos que valem a pena abrir e reduz a confiança — ela não encobre a lacuna.
- Verificação no navegador precisa de um navegador.
scripts/verify.mjsrequer Playwright e uma página em execução. Sem isso, o comportamento permaneceNOT_TESTED, e o relatório deve dizer isso. - Pontuações são heurísticas, não medições. Elas classificam famílias contra um site. Não preveem conversão, gosto ou se o chefe do cliente gosta.
- Sem URL ao vivo. Por design — um link permitiria que a skill pulasse o repositório, e o repositório é onde os tokens estão. O custo é que estados renderizados não são verificados.
- T3 precisa de dependências GPU existentes. Um shader WebGPU só é oferecido quando o repositório já possui
three,oglou uma pipeline de shader. Adicionar um renderizador de 600KB para um cursor não é uma decisão de design. - Nenhuma cor de marca inventada. Se a auditoria não encontrar um acento utilizável, isso se torna uma pergunta, não um padrão.
- O nível teatral está fora do escopo — cursores de enxame, personagens desenhados, tomadas de cursor em página inteira. São piadas de site inteiro, não decisões de cursor, e custam mais do que o resto desta skill combinado.
Modos de falha que esta skill existe para prevenir
| Sintoma | Causa |
|---|---|
| Cursor invisível em telefones, página inutilizável | cursor: none sem uma proteção de coarse-pointer |
| Cliques passam através do botão que o cursor cobre | pointer-events ausente, ignorado ou herdado como auto |
| Dois cursores aparecem após navegação | Montagem por rota, montagem por React.StrictMode ou montagem dupla em efeito |
| Cursor pisca ao carregar | cursor: none em CSS estático antes do JS executar |
| Cursor fica atrás de um modal | O contexto de empilhamento não foi verificado, e o modal cria um novo |
| Cursor para em um scroll container | position: fixed sem um pai que não seja o viewport |
| Cursor vaza para todos os projetos em um monorepo | O caminho de importação é relativo em vez de resolvido para o pacote do cursor |
| Fundo do cursor não corresponde ao modo escuro | A cor do cursor veio de uma variável de tema escuro que não existe no escuro, ou de um hex codificado |
Apêndices de referência
| Documento | Conteúdo |
|---|---|
references/profile.md | Rubricas de pontuação, níveis de confiança, assinatura de movimento |
references/audit.md | Tabela de sinais para auditoria manual, cobertura, pontos críticos |
references/gating.md | Portões rígidos, verificações de grep, proteções de acessibilidade |
references/families.md | Catálogo de famílias, tabela de ajuste, modificadores |
references/recipes.md | Implementações completas para cada família, núcleo compartilhado |
references/recommendation.md | Modelo de relatório final |
Relacionado: scripts/audit.mjs, scripts/verify.mjs, assets/shapes.css, assets/cursors/.