¿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
| Etapa | Salida |
|---|---|
| 0. Leer el repositorio | framework, mapa de archivos, código de cursor existente |
| 1. Auditar | cursorfit.json — tokens, tipo, movimiento, densidad, controles, y un informe de cobertura |
| 1b. Leer | los componentes, estilos en línea y clases de utilidad que la auditoría no pudo leer |
| 2. Puntuar | cinco ejes, cada uno con evidencia y un nivel de confianza; firma de movimiento |
| 3. Completar vacíos | como máximo tres preguntas, cada una con un valor predeterminado |
| 4. Decidir | un primario + dos alternativas, cada una con su desventaja; se permiten anulaciones con evidencia |
| 5. Construir | archivos escritos en el repositorio, integrados en el punto de entrada |
| 6. Verificar | grep, la compilación, y una pasada en navegador con scripts/verify.mjs |
| 7. Informar | el 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: noneenbodyserá anulado por una biblioteca de componentes. - Dónde viven los estilos reales. Un
tailwind.configmá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 — consultareferences/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:
- ¿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.
- ¿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 enganchadata-cursora un control. - ¿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
mediumy 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:
- Mínimo dos elementos de evidencia por eje. Menos significa
UNKNOWN, yUNKNOWNse convierte en una pregunta de completar vacíos, no en una mediana adivinada. - 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.
- 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.
- Cada puntuación lleva una confianza.
high,mediumolow, 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 enreferences/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:
- ¿Quién llega primero a esta página? Clientes evaluando un producto / desarrolladores leyendo documentación / clientes juzgando un portafolio. Predeterminado: clientes.
- ¿Cuánta personalidad se le permite llevar al cursor? Solo pulido / notable / distintivo. Predeterminado: notable.
- ¿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:
- la familia que la auditoría clasificó primero y su ajuste,
- la evidencia específica que lo cambia, con una ruta de archivo o un valor medido,
- la familia que estás eligiendo en su lugar,
- 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#00f0ffhardcodeado 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.jsy se estilizan encursor.cssantes de que se añada cualquier código de familia. Ninguna familia los elimina;dotsolo 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: nonese 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 untransformen 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.mjsrequiere Playwright y una página en ejecución. Sin ello, el comportamiento permaneceNOT_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íntoma | Causa |
|---|---|
| Cursor invisible en teléfonos, página inutilizable | cursor: none sin una guardia de puntero grueso |
| Los clics atraviesan el cursor cuando la página se desplaza | pointer-events: none aplicado demasiado tarde o faltante |
| El cursor parpadea en cada cambio de ruta | El cursor se monta por ruta, no una vez |
| Dos cursores tras una animación de entrada de página | El estado base se renderiza antes de que el script deshabilite el cursor nativo |
| El cursor ignora los botones | No se implementó la capa de estado base |