Que fait cursorfit ?
Un curseur personnalisé est une décision de design accompagnée d'une facture d'utilisabilité. La plupart des compétences liées aux curseurs vendent l'effet et ignorent la facture. Celle-ci lit d'abord le site, décide si la facture vaut la peine d'être payée, et ensuite seulement construit.
La promesse en une ligne : le curseur correspond à ce site, ou on vous explique pourquoi il ne devrait pas en avoir un.
Ce à quoi cela répond
- Ce site devrait-il avoir un curseur personnalisé ?
- Quelle famille, dans les couleurs de ce site, à la vitesse de ce site ?
- Que fait-il sur un bouton, une image, un paragraphe, un contrôle désactivé, un écran tactile ?
La règle qui garantit l'honnêteté
Chaque affirmation dans la recommandation doit citer quelque chose trouvé dans le dépôt : un fichier, un token, une valeur mesurée, un comptage. Si ce n'est pas le cas, c'est une opinion et elle doit être étiquetée comme telle. « Le site semble moderne et minimal » n'est pas une preuve et ne doit jamais apparaître dans le résultat.
Pipeline
| Étape | Sortie |
|---|---|
| 0. Lire le dépôt | framework, plan des fichiers, code de curseur existant |
| 1. Audit | cursorfit.json — tokens, type, mouvement, densité, contrôles, et un rapport de couverture |
| 1b. Lire | les composants, styles en ligne et classes utilitaires que l'audit n'a pas pu lire |
| 2. Notation | cinq axes, chacun avec des preuves et un niveau de confiance ; signature de mouvement |
| 3. Complément d'informations | au maximum trois questions, chacune avec une valeur par défaut |
| 4. Décision | un primaire + deux alternatives, chacune avec son inconvénient ; surcharges autorisées avec preuves |
| 5. Construction | fichiers écrits dans le dépôt, intégrés dans le point d'entrée |
| 6. Vérification | greps, la compilation, et un passage navigateur avec scripts/verify.mjs |
| 7. Rapport | le format dans references/recommendation.md |
Ne sautez pas de l'étape 1 à l'étape 4. La notation est ce qui empêche la réponse d'être du goût déguisé en analyse.
Étape 0 — Lire avant de décider
Cartographiez le dépôt avant de le noter. Vous devez savoir :
- Le framework, car il décide où le curseur se monte et si
cursor: nonesurbodysera écrasé par une bibliothèque de composants. - Où se trouvent les styles réels. Un
tailwind.configplus un fichier CSS manuscrit de 2000 lignes est courant, et le fichier manuscrit gagne généralement. Notez le fichier qui s'affiche. - Si un curseur existe déjà. Recherchez
cursor: none,cursor: url(,data-cursor,mousemove,mouse-follow,custom-cursor. S'il en existe un, c'est un travail de réparation avant d'être un travail de design — voirreferences/gating.md.
Étape 1 — Audit
Exécutez l'assistant si Node est disponible :
node scripts/audit.mjs <chemin-du-depot> --out cursorfit.json
C'est un lecteur statique. Il n'ouvre aucun navigateur et n'envoie aucune requête réseau. Il extrait les dépendances, les tokens de couleur, les polices de caractères, les keyframes, les easings, les durées, l'espacement, les nombres de contrôles, le code de curseur existant, et si les gardes d'accessibilité existent déjà.
Il compte <Button> et <Link> ainsi que <button> et <a>, et il lit un bloc de couverture : combien de feuilles de style et de fichiers de balisage il a analysés, combien de styles en ligne, de listes de classes utilitaires et de fichiers CSS-in-JS il n'a pas pu lire, et quels cinq fichiers valent la peine d'être ouverts en premier. Un score n'est aussi bon que sa couverture, alors lisez coverage avant de lire scores.
Si l'assistant ne peut pas s'exécuter, effectuez la même extraction manuellement en utilisant la table des signaux dans references/audit.md. Chaque signal de cette table correspond à une entrée de notation, donc en sauter un signifie que cet axe devient UNKNOWN plutôt que deviné.
Étape 1b — Lire ce que l'audit n'a pas pu
L'analyse statique a une liste connue d'angles morts, et faire semblant du contraire est ainsi qu'un profil devient confiant à propos d'un site qu'il a à moitié lu. Ouvrez les fichiers dans coverage.hotspots et répondez à trois questions pour chacun :
- Quel padding, rayon et taille de police sont réellement affichés ? Les styles en ligne et les classes utilitaires contiennent des valeurs que l'analyse des feuilles de style n'a jamais vues.
- Les wrappers de composants changent-ils la structure ? Un
<Button>peut afficher un<div>avec un gestionnaire de clic, pas un<button>. Cela change la recette des étiquettes d'état, qui accrochedata-cursorsur un contrôle. - Y a-t-il un contexte de mise en page ou d'empilement que l'audit n'a pas pu voir ? Les wrappers sticky, les sections
overflow: hidden,isolation: isolate,backdrop-filter— chacun d'eux peut déplacer ce sur quoi le curseur se trouve.
Règles pour ce passage :
- Lisez uniquement les hotspots plus le point d'entrée et la coque de mise en page. Pas l'ensemble du dépôt.
- Si un hotspot modifie une valeur mesurée de plus d'environ ~20%, enregistrez la valeur corrigée et dites dans le rapport qu'elle provient de la lecture, pas du script.
- Si un hotspot ne peut pas être résolu (styles générés, un thème au moment de la compilation), abaissez l'axe affecté à
mediumet dites quel fichier en est la cause. - Ne réexécutez jamais l'audit pour améliorer un chiffre. La sortie du script est une preuve, pas un brouillon.
Étape 2 — Notation
Cinq axes, chacun de 0 à 100, plus une signature de mouvement. Rubriques complètes dans references/profile.md.
RESTREINT ──────────▓▓▓ 74 EXPRESSIF
PRÉCIS ▓▓▓▓▓▓▓▓░░░░ 58 ORGANIQUE
DENSE ▓▓▓░░░░░░░░░ 31 AÉRÉ
CALME ▓▓▓▓▓▓░░░░░░ 47 ÉNERGIQUE
PRODUIT ▓▓▓▓▓▓▓▓▓░░░ 68 ÉDITORIAL
Règles :
- Deux éléments de preuve minimum par axe. Moins signifie
UNKNOWN, etUNKNOWNdevient une question de complément d'informations, pas une estimation médiane. - Les scores décrivent le site, pas le curseur. Un site restreint ne demande pas un curseur restreint ; il vous dit qu'un curseur bruyant serait la seule chose bruyante sur la page.
- La signature de mouvement est mesurée, pas ressentie. Enregistrez les courbes d'easing réelles, la durée médiane, le nombre de keyframes, et si quelque chose rebondit ou dépasse.
- Chaque score porte une confiance.
high,mediumoulow, provenant du bloc de couverture de l'audit. Un score moyen est cité comme une fourchette, pas un nombre. Un score faible n'est pas cité du tout — il devient une question de complément d'informations. Règles complètes dansreferences/profile.md.
Étape 3 — Complément d'informations
Posez au maximum trois questions, et uniquement pour les axes qui sont revenus UNKNOWN ou pour des faits qu'un dépôt ne peut pas contenir. Chaque question est livrée avec une valeur par défaut, donc « Je ne sais pas » produit toujours une décision.
Les trois qui valent généralement la peine d'être posées :
- Qui arrive en premier sur cette page ? Clients évaluant un produit / développeurs lisant la documentation / clients jugeant un portfolio. Par défaut : clients.
- Quelle quantité de personnalité le curseur est-il autorisé à porter ? Poli uniquement / visible / signature. Par défaut : visible.
- Une couleur qui doit ou ne doit pas être utilisée ? Par défaut : le token de marque le plus saturé du dépôt.
Ne demandez jamais ce à quoi le dépôt répond déjà. Ne posez jamais une question cosmétique que le modèle peut décider. Si la réponse ne change rien à la recommandation, ce n'était pas une question.
Étape 4 — Décision
Notez chaque famille dans references/families.md par rapport au profil, puis appliquez les gardes strictes. magnetic est un modificateur — il est ajouté à la famille choisie sur un ou deux éléments et ne peut jamais être le primaire. Produisez un primaire et deux alternatives. Jamais un menu plat — un menu rend la décision à la personne qui l'a demandée.
Chaque alternative porte son inconvénient dans la même phrase, pas dans une note de bas de page :
Alternative B — révélation par masque. Le meilleur ajustement éditorial des trois ; cela coûte une couche de canvas sur chaque image de projet, et cela semblera cassé sur toute carte dont l'image ne se charge pas.
« Conserver le curseur natif » est un verdict valide. Lorsque le site est axé sur la lecture, les formulaires, ou critique en termes d'accessibilité, dites-le — puis offrez quand même l'option la moins risquée et son coût, car la personne a demandé un curseur et refuser catégoriquement n'aide personne.
Vous pouvez passer outre le classement, mais jamais en silence. Les chiffres sont une aide à la décision, pas une mesure, et l'audit ne sait pas ce qu'il n'a pas pu lire. Une surcharge est autorisée lorsque le passage de couverture a trouvé quelque chose que le script a manqué — un modèle d'interaction réel, un composant qui modifie la structure du contrôle, un contexte d'empilement que l'analyse CSS n'a pas pu voir. Pour en revendiquer une, énoncez les quatre :
- la famille que l'audit a classée première et son ajustement,
- la preuve spécifique qui la modifie, avec un chemin de fichier ou une valeur mesurée,
- la famille que vous choisissez à la place,
- ce que le lecteur perd en prenant la surcharge.
Une surcharge sans chemin de fichier est une question de goût. Le goût est autorisé dans le dernier kilomètre — taille, easing, l'étiquette exacte — jamais dans le choix de la famille.
Étape 5 — Construction
Les implémentations complètes pour chaque famille se trouvent dans references/recipes.md. Copiez la recette, puis modifiez uniquement ce que le profil dit de modifier.
Non négociables :
- La couleur provient d'un token, jamais d'un nouveau hex. Liez-vous à la couleur de marque la plus forte que l'audit a trouvée (
var(--neon-cyan),theme('colors.accent'), une constante exportée). Un#00f0ffcodé en dur est la différence entre « correspond à votre site » et « correspond au site à partir duquel il a été copié ». - La couche d'état de base est livrée avec chaque famille. Les états lien, bouton, texte et désactivé sont résolus dans
cursor.jset stylisés danscursor.cssavant que tout code de famille ne soit ajouté. Aucune famille ne les supprime ;dotne fait que réduire les chiffres. Un curseur qui ne fait rien lorsqu'il traverse un bouton est inachevé — le visiteur n'a aucun moyen de le distinguer d'un autocollant. - Les étiquettes sont l'amélioration, pas l'état.
[data-cursor]ajoute un mot par-dessus un état qui existe déjà. Si la construction ne réagit que là où le site a été annoté, la couche d'état est manquante. - Le code de la famille T1 reste en dessous d'environ ~90 lignes, par-dessus le noyau partagé. Si la propre couche de la famille a besoin de plus, la famille est erronée pour le site. Le noyau fait ~100 lignes une fois, car il porte désormais la couche d'état pour chaque famille.
cursor: noneest appliqué par JS après la première image, jamais dans le CSS statique. Si le script échoue, l'utilisateur conserve un curseur fonctionnel.- Montez une fois. Un curseur monté par route en donne deux, puis trois.
- Le tactile ne reçoit rien. Pas un curseur plus petit. Rien.
Vanilla est livré comme cursor.css + cursor.js et une ligne <script defer>. React est livré comme un composant plus le même CSS, monté au-dessus du routeur.
Deux ensembles d'actifs prêts à l'emploi existent pour que la construction ne s'arrête pas sur des éléments graphiques :
assets/shapes.css— sept silhouettes (cercle, anneau, carré, réticule, pilule, crochet, blob). Ajoutez une classe à la marque ; le choix de la silhouette provient du profil.assets/cursors/*.svg— quatre curseurs d'image avec leurs valeurs de hotspot, pour la famille T0. Blanc avec un contour foncé pour survivre aux sections claires et sombres.
Copiez les fichiers dans le dépôt (généralement public/cursors/ et src/styles/), ne référencez pas le dossier de cette compétence au moment de l'exécution.
Étape 6 — Vérification
Trois niveaux, dans l'ordre. Chacun attrape ce que le précédent ne peut pas.
1. Greps. Exécutez les vérifications statiques dans references/gating.md. Ce sont des greps, pas des opinions : pointer-events, position: fixed, aria-hidden, garde coarse-pointer, garde reduced-motion, pas de transition sur transform, masquer sur mouseleave, vérification du contexte de fusion.
2. Construction. npm run build ou tsc --noEmit. Un curseur qui casse la construction n'est pas livré.
3. Navigateur. Les greps prouvent que le code dit les bonnes choses ; ils ne peuvent pas prouver que le curseur fonctionne. Si Playwright est disponible, exécutez le harnais :
node scripts/verify.mjs http://localhost:3000 --cursor .cf-cursor --json verify.json
Il ouvre la page et vérifie ce qu'un grep ne peut pas : l'élément existe et est visible, il a pointer-events: none, il retarde puis converge, le survol change son état, un clic atteint toujours le contrôle en dessous, le focus conserve son anneau, un changement de route n'en génère pas un second, la console reste propre, un tap ne le fait pas apparaître, et prefers-reduced-motion désactive le suivi. Dix vérifications sont exécutées par défaut ; ajoutez --modal "#trigger" pour une onzième qui ouvre une superposition et compare son empilement par rapport au curseur.
Playwright est la seule dépendance optionnelle du package. S'il n'est pas installé, ou si la page ne peut pas être servie, effectuez les mêmes onze vérifications manuellement à 1366×768 et 390×844 — et si vous ne le faites pas, le rapport dit NOT_TESTED: rendered behaviour en ces termes. Ne suggérez jamais que vous l'avez vu.
Une vérification ignorée n'est pas une réussite. verify.mjs imprime les ignorés séparément pour cette raison : cela signifie que la page n'a pas exposé assez pour être testée, et le rapport doit dire quelle vérification a été ignorée et pourquoi.
Étape 7 — Rapport
Utilisez references/recommendation.md. Le rapport se termine toujours par deux listes : ce qu'il faut regarder et ce qui est délibérément désactivé.
Limites
- Le code n'est pas le rendu. L'audit lit le source. Un
backdrop-filter, un contexte d'empilement, ou untransformsur un ancêtre peut changer l'apparence du curseur, et le source ne le montrera pas. - L'analyse statique ne voit que ce qu'elle peut analyser. Le style peut résider dans des objets en ligne, des classes utilitaires résolues au moment de la compilation, du CSS-in-JS, ou des parties internes de composants. L'audit compte ce qu'il a manqué, nomme les fichiers qui valent la peine d'être ouverts, et abaisse la confiance — il ne masque pas l'écart.
- La vérification par navigateur nécessite un navigateur.
scripts/verify.mjsnécessite Playwright et une page en cours d'exécution. Sans cela, le comportement resteNOT_TESTED, et le rapport doit le dire. - Les scores sont des heuristiques, pas des mesures. Ils classent les familles par rapport à un site. Ils ne prédisent pas la conversion, le goût, ou si le patron du client l'aime.
- Pas d'URL en direct. Par conception — un lien permettrait à la compétence d'ignorer le dépôt, et le dépôt est là où se trouvent les tokens. Le coût est que les états rendus ne sont pas vérifiés.
- T3 nécessite des dépendances GPU existantes. Un shader WebGPU n'est proposé que lorsque le dépôt contient déjà
three,ogl, ou un pipeline de shaders. Ajouter un moteur de rendu de 600 Ko pour un curseur n'est pas une décision de design. - Pas de couleur de marque inventée. Si l'audit ne trouve aucun accent utilisable, cela devient une question, pas une valeur par défaut.
- Le niveau théâtral est hors de portée — curseurs en essaim, personnages dessinés, prises de contrôle de la page entière par le curseur. Ce sont des gags à l'échelle du site, pas des décisions de curseur, et ils coûtent plus cher que le reste de cette compétence combiné.
Modes d'échec que cette compétence existe pour prévenir
| Symptôme | Cause |
|---|---|
| Curseur invisible sur les téléphones, page inutilisable | cursor: none sans garde coarse-pointer |
| Les clics traversent le curseur et manquent la cible | pointer-events: none manquant |
| Le curseur natif clignote au chargement | cursor défini en CSS statique au lieu de JS |
| Le défilement fait traîner le curseur loin de la souris | Pas de recalcul de position sur le défilement |
| Deux curseurs après une transition de route | Monté par route, pas une fois à la racine |
| Le mode de mouvement réduit est ignoré | La garde CSS prefers-reduced-motion manquante |
| La superposition de débogage est visible pour les utilisateurs | data-cursor-state sans display: none sur l'attribut |
| La forme du curseur est pixelisée sur les écrans Retina | L'image SVG manque viewBox ou la balise svg correcte |