Communitygithub.com

cursorfit

Elige y construye el cursor personalizado adecuado para un sitio web. Analiza la paleta, tipografía, movimiento y diseño del repositorio, puntúa el carácter de diseño del sitio en cinco ejes, luego selecciona una familia de cursores y la implementa usando los tokens de diseño del propio sitio. Úsalo cuando alguien pida un cursor personalizado, seguidor de ratón, estela de cursor, cursor magnético, cursor con modo de fusión, cursor de punto y anillo, o pregunte qué estilo de cursor se adapta a su sitio. Lee un repositorio o archivos CSS; no necesita una URL en vivo.

¿Qué es cursorfit?

cursorfit es una habilidad especializada para asistentes de IA (como Claude Code, Cursor, Codex) que automatiza la selección e implementación de cursores personalizados en sitios web. A diferencia de otras habilidades que simplemente añaden un efecto de cursor llamativo sin considerar el diseño del sitio, cursorfit primero analiza el repositorio para evaluar si un cursor personalizado es apropiado. Su pipeline de siete etapas incluye leer el repositorio, auditar tokens de diseño (colores, tipografía, movimiento, espaciado, controles), puntuar el sitio en cinco ejes (Contenido, Precisión, Densidad, Calma, Editorial) con niveles de confianza, decidir la familia de cursor más adecuada (con al menos dos alternativas, cada una con su desventaja), y construir los archivos necesarios en el repositorio, integrados en el punto de entrada. Es compatible con cualquier framework, utiliza tokens de diseño existentes para colores y estilos, y verifica el resultado mediante comprobaciones estáticas, compilación y pruebas en navegador (vía Playwright). La habilidad impone reglas estrictas: cada afirmación en la recomendación debe estar respaldada por evidencia del repositorio, las puntuaciones describen el sitio (no el cursor), y está permitido concluir que no se necesita cursor personalizado si el sitio es pesado en lectura, formularios o accesibilidad. Su objetivo es evitar fallos comunes como cursores invisibles en móviles, clics que no funcionan, o problemas de rendimiento. El repositorio se analiza localmente; no se requiere una URL en vivo.

Compatible con~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/HusainMain/cursorfit/tree/HEAD

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace cursorfit?

Un cursor personalizado es una decisión de diseño con una factura de usabilidad adjunta. La mayoría de las habilidades de cursor venden el efecto y se saltan la factura. Esta lee el sitio primero, decide si vale la pena pagar la factura, y solo entonces construye.

La promesa en una línea: el cursor coincide con este sitio, o te dicen por qué no debería tener uno.

Qué responde esto

  • ¿Debería este sitio tener un cursor personalizado?
  • ¿Qué familia, con los colores de este sitio, a la velocidad de este sitio?
  • ¿Qué hace sobre un botón, una imagen, un párrafo, un control deshabilitado, una pantalla táctil?

La regla que mantiene esto honesto

Cada afirmación en la recomendación debe citar algo encontrado en el repositorio: un archivo, un token, un valor medido, un recuento. Si no puede, es una opinión y se etiqueta como tal. "El sitio se siente moderno y minimalista" no es evidencia y nunca debe aparecer en la salida.

Pipeline

EtapaSalida
0. Leer el repositorioframework, mapa de archivos, código de cursor existente
1. Auditarcursorfit.json — tokens, tipo, movimiento, densidad, controles, y un informe de cobertura
1b. Leerlos componentes, estilos en línea y clases de utilidad que la auditoría no pudo leer
2. Puntuarcinco ejes, cada uno con evidencia y un nivel de confianza; firma de movimiento
3. Completar vacíoscomo máximo tres preguntas, cada una con un valor predeterminado
4. Decidirun primario + dos alternativas, cada una con su desventaja; se permiten anulaciones con evidencia
5. Construirarchivos escritos en el repositorio, integrados en el punto de entrada
6. Verificargrep, la compilación, y una pasada en navegador con scripts/verify.mjs
7. Informarel formato en references/recommendation.md

No saltes de la etapa 1 a la etapa 4. La puntuación es lo que evita que la respuesta sea gusto disfrazado de análisis.

Etapa 0 — Leer antes de decidir

Mapea el repositorio antes de puntuarlo. Necesitas saber:

  • Framework, porque decide dónde se monta el cursor y si cursor: none en body será anulado por una biblioteca de componentes.
  • Dónde viven los estilos reales. Un tailwind.config más un archivo CSS escrito a mano de 2,000 líneas es común, y el archivo escrito a mano generalmente gana. Puntúa el archivo que renderiza.
  • Si ya existe un cursor. Busca cursor: none, cursor: url(, data-cursor, mousemove, mouse-follow, custom-cursor. Si existe, esto es un trabajo de reparación antes que un trabajo de diseño — consulta references/gating.md.

Etapa 1 — Auditar

Ejecuta el helper si Node está disponible:

node scripts/audit.mjs <ruta-repo> --out cursorfit.json

Es un lector estático. No abre ningún navegador ni envía ninguna solicitud de red. Extrae dependencias, tokens de color, pilas de fuentes, keyframes, easing, duraciones, espaciado, recuentos de controles, código de cursor existente, y si las protecciones de accesibilidad ya existen.

Cuenta <Button> y <Link> así como <button> y <a>, y lee un bloque de cobertura: cuántas hojas de estilo y archivos de marcado analizó, cuántos estilos en línea, listas de clases de utilidad y archivos CSS-in-JS que no pudo leer, y qué cinco archivos vale la pena abrir primero. Una puntuación solo es tan buena como esa cobertura, así que lee coverage antes de leer scores.

Si el helper no puede ejecutarse, haz la misma extracción manualmente usando la tabla de señales en references/audit.md. Cada señal en esa tabla se asigna a una entrada de puntuación, por lo que saltarse una significa que ese eje se convierte en UNKNOWN en lugar de adivinado.

Etapa 1b — Leer lo que la auditoría no pudo

El análisis estático tiene una lista de puntos ciegos conocidos, y fingir lo contrario es cómo un perfil se vuelve confiado sobre un sitio que leyó a medias. Abre los archivos en coverage.hotspots y responde tres preguntas para cada uno:

  1. ¿Qué padding, radio y tamaño de tipo se renderizan realmente? Los estilos en línea y las clases de utilidad contienen valores que el escaneo de hojas de estilo nunca vio.
  2. ¿Los envoltorios de componentes cambian la estructura? Un <Button> puede renderizar un <div> con un controlador de clic, no un <button>. Eso cambia la receta de etiqueta de estado, que engancha data-cursor a un control.
  3. ¿Hay un contexto de diseño o apilamiento que la auditoría no pudo ver? Envoltorios sticky, secciones overflow: hidden, isolation: isolate, backdrop-filter — cualquiera de estos puede mover lo que el cursor se sitúa encima.

Reglas para esta pasada:

  • Lee solo los hotspots, más el punto de entrada y el shell de diseño. No todo el repositorio.
  • Si un hotspot cambia un valor medido en más de ~20 %, registra el valor corregido y di en el informe que provino de la lectura, no del script.
  • Si un hotspot no se puede resolver (estilos generados, un tema en tiempo de compilación), degrada el eje afectado a medium y di qué archivo lo causó.
  • Nunca vuelvas a ejecutar la auditoría para hacer un número más bonito. La salida del script es evidencia, no un borrador.

Etapa 2 — Puntuar

Cinco ejes, cada uno 0–100, más una firma de movimiento. Rúbricas completas en references/profile.md.

CONTENIDO  ──────────▓▓▓  74  EXPRESIVO
PRECISIÓN  ▓▓▓▓▓▓▓▓░░░░  58  ORGÁNICO
DENSIDAD   ▓▓▓░░░░░░░░░  31  AIREADO
CALMA      ▓▓▓▓▓▓░░░░░░  47  ENERGÉTICO
EDITORIAL  ▓▓▓▓▓▓▓▓▓░░░  68  EDITORIAL

Reglas:

  1. Mínimo dos elementos de evidencia por eje. Menos significa UNKNOWN, y UNKNOWN se convierte en una pregunta de completar vacíos, no en una mediana adivinada.
  2. Las puntuaciones describen el sitio, no el cursor. Un sitio contenido no está pidiendo un cursor contenido; te está diciendo que uno ruidoso sería lo único ruidoso en la página.
  3. La firma de movimiento se mide, no se siente. Registra las curvas de easing reales, la duración mediana, el recuento de keyframes, y si algo tiene resorte o sobrepasa.
  4. Cada puntuación lleva una confianza. high, medium o low, del bloque de cobertura de la auditoría. Una puntuación media se cita como una banda, no como un número. Una puntuación baja no se cita en absoluto — se convierte en una pregunta de completar vacíos. Reglas completas en references/profile.md.

Etapa 3 — Completar vacíos

Haz como máximo tres preguntas, y solo para ejes que volvieron UNKNOWN o para hechos que un repositorio no puede contener. Cada pregunta viene con un valor predeterminado, así que "No sé" aún produce una decisión.

Las tres que generalmente vale la pena hacer:

  1. ¿Quién llega primero a esta página? Clientes evaluando un producto / desarrolladores leyendo documentación / clientes juzgando un portafolio. Predeterminado: clientes.
  2. ¿Cuánta personalidad se le permite llevar al cursor? Solo pulido / notable / distintivo. Predeterminado: notable.
  3. ¿Algún color que deba o no deba usarse? Predeterminado: el token de marca más saturado del repositorio.

Nunca preguntes lo que el repositorio ya responde. Nunca hagas una pregunta cosmética que el modelo pueda decidir. Si la respuesta no cambia nada sobre la recomendación, no era una pregunta.

Etapa 4 — Decidir

Puntúa cada familia en references/families.md contra el perfil, luego aplica las puertas estrictas. magnetic es un modificador — se añade a la familia elegida en uno o dos elementos y nunca puede ser el primario. Salida un primario y dos alternativas. Nunca un menú plano — un menú devuelve la decisión a la persona que la pidió.

Cada alternativa lleva su desventaja en la misma frase, no en una nota al pie:

Alternativa B — revelación con máscara. El mejor ajuste editorial de las tres; cuesta una capa de canvas sobre cada imagen de proyecto, y se verá rota en cualquier tarjeta cuya imagen no cargue.

"Mantener el cursor nativo" es un veredicto válido. Cuando el sitio es pesado en lectura, formularios, o crítico para la accesibilidad, dilo — luego ofrece la opción de menor riesgo y su costo, porque la persona pidió un cursor y negarse rotundamente no ayuda a nadie.

Puedes anular la clasificación, pero nunca en silencio. Los números son soporte para la decisión, no una medición, y la auditoría no sabe lo que no pudo leer. Se permite una anulación cuando la pasada de cobertura encontró algo que el script pasó por alto — un patrón de interacción real, un componente que cambia la estructura de control, un contexto de apilamiento que el escaneo de CSS no pudo ver. Para reclamar una, expón las cuatro:

  1. la familia que la auditoría clasificó primero y su ajuste,
  2. la evidencia específica que lo cambia, con una ruta de archivo o un valor medido,
  3. la familia que estás eligiendo en su lugar,
  4. qué pierde el lector al tomar la anulación.

Una anulación sin ruta de archivo es gusto. El gusto está permitido en la última milla — tamaño, easing, la etiqueta exacta — nunca en la elección de la familia.

Etapa 5 — Construir

Las implementaciones completas para cada familia viven en references/recipes.md. Copia la receta, luego cambia solo lo que el perfil dice cambiar.

Innegociables:

  • El color proviene de un token, nunca de un nuevo hex. Vincula al color de marca más fuerte que encontró la auditoría (var(--neon-cyan), theme('colors.accent'), una constante exportada). Un #00f0ff hardcodeado es la diferencia entre "coincide con tu sitio" y "coincide con el sitio del que fue copiado".
  • La capa de estado base se envía con cada familia. Enlace, botón, texto y deshabilitado se resuelven en cursor.js y se estilizan en cursor.css antes de que se añada cualquier código de familia. Ninguna familia los elimina; dot solo baja los números. Un cursor que no hace nada cuando cruza un botón está incompleto — el visitante no tiene forma de distinguirlo de una pegatina.
  • Las etiquetas son la mejora, no el estado. [data-cursor] añade una palabra sobre un estado que ya existe. Si la construcción solo reacciona donde el sitio fue anotado, la capa de estado falta.
  • El código de la familia T1 se mantiene por debajo de ~90 líneas, además del núcleo compartido. Si la propia capa de la familia necesita más, la familia es incorrecta para el sitio. El núcleo es de ~100 líneas una vez, porque ahora lleva la capa de estado para cada familia.
  • cursor: none se aplica mediante JS después del primer fotograma, nunca en CSS estático. Si el script falla, el usuario conserva un cursor funcional.
  • Montar una vez. Un cursor montado por ruta te da dos, luego tres.
  • Táctil no recibe nada. Ni un cursor más pequeño. Nada.

Vanilla se envía como cursor.css + cursor.js y una línea <script defer>. React se envía como un componente más el mismo CSS, montado sobre el enrutador.

Existen dos conjuntos de recursos listos para usar para que la construcción no se detenga en el arte:

  • assets/shapes.css — siete siluetas (círculo, anillo, cuadrado, mira, píldora, corchete, blob). Añade una clase a la marca; la elección de la silueta proviene del perfil.
  • assets/cursors/*.svg — cuatro cursores de imagen con sus valores de punto activo, para la familia T0. Blancos con un contorno oscuro para que sobrevivan tanto a secciones claras como oscuras.

Copia los archivos en el repositorio (generalmente public/cursors/ y src/styles/), no hagas referencia a la carpeta de esta habilidad en tiempo de ejecución.

Etapa 6 — Verificar

Tres niveles, en orden. Cada uno atrapa lo que el anterior no puede.

1. Greps. Ejecuta las comprobaciones estáticas en references/gating.md. Son greps, no opiniones: pointer-events, position: fixed, aria-hidden, guardia de puntero grueso, guardia de movimiento reducido, sin transition en transform, ocultar en mouseleave, comprobación de contexto de fusión.

2. Compilación. npm run build o tsc --noEmit. Un cursor que rompe la compilación no se envía.

3. Navegador. Los greps prueban que el código dice lo correcto; no pueden probar que el cursor funciona. Si Playwright está disponible, ejecuta el arnés:

node scripts/verify.mjs http://localhost:3000 --cursor .cf-cursor --json verify.json

Abre la página y comprueba lo que un grep no puede: el elemento existe y es visible, tiene pointer-events: none, se retrasa luego converge, hover cambia su estado, un clic aún alcanza el control debajo, el foco mantiene su anillo, un cambio de ruta no genera un segundo, la consola se mantiene limpia, un toque no lo hace aparecer, y prefers-reduced-motion desactiva el seguimiento. Diez comprobaciones se ejecutan por defecto; añade --modal "#trigger" para una undécima que abre una superposición y compara su apilamiento con el cursor.

Playwright es la única dependencia opcional en el paquete. Si no está instalado, o la página no se puede servir, haz las mismas once comprobaciones a mano a 1366×768 y 390×844 — y si no lo haces, el informe dice NOT_TESTED: comportamiento renderizado en esas palabras. Nunca insinúes que lo viste.

Una comprobación omitida no es un aprobado. verify.mjs imprime las omisiones por separado por esa razón: significa que la página no expuso lo suficiente para probar, y el informe tiene que decir qué comprobación se omitió y por qué.

Etapa 7 — Informar

Usa references/recommendation.md. El informe siempre termina con dos listas: qué mirar y qué está deliberadamente deshabilitado.

Límites

  • El código no es el renderizado. La auditoría lee el código fuente. Un backdrop-filter, un contexto de apilamiento, o un transform en un ancestro pueden cambiar cómo se ve el cursor, y el código fuente no lo mostrará.
  • El análisis estático solo ve lo que puede analizar. El estilo puede vivir en objetos en línea, clases de utilidad resueltas en tiempo de compilación, CSS-in-JS, o internos de componentes. La auditoría cuenta lo que se perdió, nombra los archivos que vale la pena abrir, y baja la confianza — no encubre la brecha.
  • La verificación en navegador necesita un navegador. scripts/verify.mjs requiere Playwright y una página en ejecución. Sin ello, el comportamiento permanece NOT_TESTED, y el informe debe decirlo.
  • Las puntuaciones son heurísticas, no mediciones. Clasifican familias contra un sitio. No predicen conversión, gusto, o si al jefe del cliente le gusta.
  • Sin URL en vivo. Por diseño — un enlace permitiría que la habilidad se salte el repositorio, y el repositorio es donde están los tokens. El costo es que los estados renderizados no se verifican.
  • T3 necesita dependencias GPU existentes. Un shader WebGPU solo se ofrece cuando el repositorio ya incluye three, ogl, o un pipeline de shaders. Añadir un renderizador de 600KB para un cursor no es una decisión de diseño.
  • Sin color de marca inventado. Si la auditoría no encuentra un acento utilizable, eso se convierte en una pregunta, no en un valor predeterminado.
  • El nivel teatral está fuera del alcance — cursores enjambre, personajes dibujados, tomas de control de página completa con el cursor. Son bromas de sitio completo, no decisiones de cursor, y cuestan más que el resto de esta habilidad combinado.

Modos de fallo que esta habilidad existe para prevenir

SíntomaCausa
Cursor invisible en teléfonos, página inutilizablecursor: none sin una guardia de puntero grueso
Los clics atraviesan el cursor cuando la página se desplazapointer-events: none aplicado demasiado tarde o faltante
El cursor parpadea en cada cambio de rutaEl cursor se monta por ruta, no una vez
Dos cursores tras una animación de entrada de páginaEl estado base se renderiza antes de que el script deshabilite el cursor nativo
El cursor ignora los botonesNo se implementó la capa de estado base

Skills relacionados