Communitygithub.com

cursorfit

为网站选择并构建合适的自定义光标。它会审计仓库的调色板、排版、动效和布局,在五个维度上对网站的设计特性进行评分,然后选择一个光标系列并使用网站自身的设计令牌来实现。

cursorfit 是什么?

cursorfit 是一个专门为网站选择和构建自定义光标的 AI 技能。与大多数只注重效果而忽略可用性的光标技能不同,cursorfit 会先全面审计目标仓库,从调色板、排版、动效和布局等多个维度进行量化评估,然后基于这些数据做出决策。它支持多种平台(如 Claude Code、Cursor 等),无需实时 URL,仅通过分析仓库中的 CSS 文件、JavaScript 和样式令牌即可工作。该技能遵循一个严谨的七阶段流程:从读取仓库结构开始,然后通过静态分析工具或手动方式进行审计和读取未覆盖的样式,接着在五个轴(克制/表现、精确/有机、密集/通透、冷静/活力、产品/编辑)上评分,并通过最多三个补全问题解决未知项。最终,它根据评分选择一个主要光标系列和两个备选,并明确列出每个备选的劣势。cursorfit 还能构建完整的光标实现,包括 CSS 和 JavaScript 文件,并通过 grep、构建验证和浏览器测试(可选 Playwright)进行多级验证。它强调所有推荐必须有证据支持,严禁依赖主观品味,并始终将「保留原生光标」作为有效的裁决。该技能特别适合用于评估一个网站是否真的需要自定义光标,以及如何在最小化可用性风险的前提下实现最合适的方案。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/HusainMain/cursorfit/tree/HEAD

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

cursorfit 是做什么的?

自定义光标是一个附带可用性账单的设计决策。大多数光标技能只兜售效果,而忽略了账单。这个技能会先读取网站,评估是否值得支付这笔账单,然后才构建。

一句话承诺:光标与这个网站匹配,否则你会被告知为什么它不应该有。

它回答了什么问题

  • 这个网站到底该不该有自定义光标?
  • 应该使用哪个系列,用这个网站的颜色,以这个网站的速度?
  • 在按钮、图片、段落、禁用控件、触摸屏上,它分别有什么表现?

保持诚实的规则

推荐中的每个声明都必须引用仓库中找到的内容:一个文件、一个令牌、一个测量值、一个计数。如果不能,那就是一个意见,必须被标记为意见。「这个网站感觉现代而简约」不是证据,绝不能在输出中出现。

流程

阶段输出
0. 读取仓库框架、文件映射、现有的光标代码
1. 审计cursorfit.json — 令牌、类型、动效、密度、控件,以及覆盖率报告
1b. 读取审计无法读取的组件、内联样式和工具类
2. 评分五个维度,每个维度附带证据和置信度;动效特征
3. 补全最多三个问题,每个问题带默认值
4. 决策一个主要系列 + 两个备选,每个备选附带其劣势;允许基于证据的覆盖
5. 构建将文件写入仓库,连接到入口点
6. 验证grep、构建以及使用 scripts/verify.mjs 的浏览器测试
7. 报告格式见 references/recommendation.md

不要从阶段 1 跳到阶段 4。评分是阻止答案沦为披着分析外衣的品味的关键。

阶段 0 — 先读取再决定

在评分前先映射仓库。你需要知道:

  • 框架,因为它决定了光标挂载的位置,以及 body 上的 cursor: none 是否会被组件库覆盖。
  • 真正的样式在哪里。 一个 tailwind.config 加上一个 2000 行的手写 CSS 文件很常见,而手写文件通常胜出。对实际渲染的文件进行评分。
  • 光标是否已经存在。 搜索 cursor: none、cursor: url(、data-cursor、mousemove、mouse-follow、custom-cursor。如果存在,那么在成为设计任务之前,它首先是一个修复任务 — 参见 references/gating.md。

阶段 1 — 审计

如果 Node 可用,运行辅助脚本:

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

它是一个静态读取器。它不打开浏览器,也不发送网络请求。它提取依赖项、颜色令牌、字体栈、关键帧、缓动函数、持续时间、间距、控件数量、现有的光标代码,以及可访问性防护是否已存在。

它会统计 <Button> 和 <Link>,以及 <button> 和 <a>,并读取一个覆盖率块:它解析了多少样式表和标记文件,无法读取的内联样式、工具类列表和 CSS-in-JS 文件有多少,以及哪些是首先值得打开的前五个文件。一个分数只在覆盖率可靠时才有效,所以在读取 scores 之前先读取 coverage。

如果辅助脚本无法运行,则使用 references/audit.md 中的信号表手动进行相同的提取。该表中的每个信号都对应一个评分输入,所以跳过任何一个都意味着该维度会变成 UNKNOWN,而不是被猜测。

阶段 1b — 读取审计无法读取的内容

静态分析有一个已知的盲区列表,假装没有是导致分析在只读取了半个网站时就变得过于自信的原因。打开 coverage.hotspots 中的文件,并为每个文件回答三个问题:

  1. 实际渲染的内边距、圆角和字体大小是多少? 内联样式和工具类包含了样式表扫描从未见到的值。
  2. 组件包装器是否改变了结构? 一个 <Button> 可能渲染一个带有点击处理器的 <div>,而不是 <button>。这会改变状态标签的配方,该配方将 data-cursor 挂接到控件上。
  3. 是否存在审计无法看到的布局或层叠上下文? 粘性包装器、overflow: hidden 部分、isolation: isolate、backdrop-filter — 任何一个都可能移动光标所在的位置。

此遍的规则:

  • 只读取热点文件加上入口点和布局外壳。不是整个仓库。
  • 如果一个热点改变了测量值超过约 20%,则记录校正后的值,并在报告中说明该值来自手动读取,而非脚本。
  • 如果一个热点无法解析(生成的样式、构建时主题),则将受影响的维度降级为 medium,并说明是哪个文件导致的。
  • 永远不要重新运行审计以使数字更好看。脚本的输出是证据,而不是草稿。

阶段 2 — 评分

五个维度,每个 0–100,加上一个动效特征。完整评分标准见 references/profile.md。

克制  ──────────▓▓▓  74  表现
精确  ▓▓▓▓▓▓▓▓░░░░  58  有机
密集  ▓▓▓░░░░░░░░░  31  通透
冷静  ▓▓▓▓▓▓░░░░░░  47  活力
产品  ▓▓▓▓▓▓▓▓▓░░░  68  编辑

规则:

  1. 每个维度至少两个证据项。 少于两个意味着 UNKNOWN,而 UNKNOWN 会变成一个补全问题,而不是中位数猜测。
  2. 分数描述的是网站,而不是光标。 一个克制的网站不是在要求一个克制的光标;它是在告诉你,一个喧闹的光标将是页面上唯一喧闹的东西。
  3. 动效特征是测量出来的,而不是感觉出来的。 记录实际的缓动曲线、中位持续时间、关键帧数量,以及是否有任何弹簧或过冲效果。
  4. 每个分数都带有置信度。 高、中 或 低,来自审计的覆盖率块。中等分数以范围形式引用,而不是单一数字。低分根本不引用 — 它变成一个补全问题。完整规则见 references/profile.md。

阶段 3 — 补全

最多问三个问题,并且只针对返回 UNKNOWN 的维度或仓库无法容纳的事实。每个问题都附带一个默认值,所以「我不知道」仍然能产生一个决策。

通常值得问的三个问题:

  1. 谁最先访问这个页面? 评估产品的客户 / 阅读文档的开发者 / 评判作品集的客户。默认:客户。
  2. 光标允许承载多少个性? 仅润色 / 引人注目 / 标志性。默认:引人注目。
  3. 是否有必须使用或绝对不能使用的颜色? 默认:仓库中最饱和的品牌令牌。

永远不要问仓库已经回答了的问题。永远不要问模型可以决定的装饰性问题。如果答案不会改变推荐内容,那它就不是一个问题。

阶段 4 — 决策

根据 references/families.md 中的评分标准对每个系列进行评分,然后应用硬性门槛。magnetic 是一个修饰符 — 它被添加到所选系列的一个或两个元素上,并且永远不能作为主要系列。输出一个主要系列和两个备选。永远不要提供一个扁平菜单 — 菜单把决策权交回给提出需求的人。

每个备选都必须附带其劣势,而不是在脚注中:

备选 B — 遮罩揭示。 三者中编辑拟合度最强;但它需要为每个项目图片添加一个画布层,并且在任何图片加载失败的卡片上会显得异常。

「保留原生光标」是一个有效的裁决。 当网站是重阅读型、重表单型或对可访问性要求严格时,请明确说明 — 然后仍然提供风险最低的选项及其成本,因为提出需求的人想要一个光标,直接拒绝对任何人都没有帮助。

你可以覆盖排名,但绝不能悄无声息。 数字是决策支持,而不是度量标准,审计无法知道它未能读取的内容。当覆盖率测试发现了脚本遗漏的内容时 — 一个真实的交互模式、一个改变控件结构的组件、一个 CSS 扫描无法看到的层叠上下文 — 才允许覆盖。要声称覆盖,请说明全部四点:

  1. 审计排名第一的系列及其拟合度,
  2. 改变这一点的具体证据,附带文件路径或测量值,
  3. 你选择替代的系列,
  4. 读者因采用覆盖而失去的内容。

没有文件路径的覆盖是品味。品味在最后一英里是可以的 — 尺寸、缓动、确切的标签 — 但绝不能在选择系列时使用。

阶段 5 — 构建

所有系列的完整实现位于 references/recipes.md。复制配方,然后只更改评分标准指示更改的内容。

不可协商的要求:

  • 颜色来自令牌,永远不要使用新的十六进制值。 绑定到审计找到的最强品牌颜色(var(--neon-cyan)、theme('colors.accent')、一个导出的常量)。硬编码的 #00f0ff 是「匹配你的网站」和「匹配它被复制过来的那个网站」之间的区别。
  • 每个系列都附带基础状态层。 链接、按钮、文本和禁用状态在 cursor.js 中解析,并在 cursor.css 中设置样式,在任何系列代码添加之前。没有系列会删除它们;dot 只是调低了数值。一个在越过按钮时不执行任何操作的光标是不完整的 — 访客无法将其与贴纸区分开来。
  • 标签是增强,而不是状态。 [data-cursor] 在已有的状态之上添加一个词。如果构建只对网站标注过的位置做出反应,那么状态层就是缺失的。
  • T1 系列代码保持在约 90 行以内,建立在共享核心之上。 如果系列自身的层需要更多,那么这个系列不适合该网站。核心代码约 100 行,是一次性的,因为它现在为每个系列承载状态层。
  • cursor: none 由 JS 在首帧之后应用,永远不要放在静态 CSS 中。如果脚本失败,用户仍然能使用可用的光标。
  • 只挂载一次。 每个路由挂载一次光标会让你得到两个,然后三个。
  • 触摸设备不获得任何东西。 不是更小的光标。什么都没有。

Vanilla 版本以 cursor.css + cursor.js 和一行 <script defer> 的形式提供。React 版本以一个组件加上相同的 CSS 提供,挂载在路由之上。

两个现成的素材集已经存在,这样构建就不会因为寻找素材而停滞:

  • assets/shapes.css — 七种轮廓(圆形、环形、方形、十字准线、药丸形、括号形、斑点形)。在标记上添加一个类;轮廓的选择来自评分。
  • assets/cursors/*.svg — 四个图片光标及其热点值,用于 T0 系列。白色带有深色轮廓,以便它们在亮色和暗色部分都能存活。

将文件复制到仓库中(通常是 public/cursors/ 和 src/styles/),不要在运行时引用此技能的文件夹。

阶段 6 — 验证

三个级别,按顺序进行。每个级别都能捕捉到前一个级别无法捕捉的问题。

1. Grep。 运行 references/gating.md 中的静态检查。它们是 grep 命令,而不是意见:pointer-events、position: fixed、aria-hidden、粗略指针防护、减少动效防护、没有 transition 作用于 transform、mouseleave 时隐藏、混合上下文检查。

2. 构建。 npm run build 或 tsc --noEmit。破坏构建的光标不会被部署。

3. 浏览器。 Grep 可以证明代码说了正确的事情;但它们无法证明光标能工作。如果 Playwright 可用,运行测试框架:

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

它会打开页面并检查 grep 无法检查的内容:元素存在且可见,它具有 pointer-events: none,它会延迟然后收敛,悬停会改变其状态,点击仍然到达下方的控件,焦点保持其光环,路由变化不会产生第二个光标,控制台保持干净,点击不会让它出现,并且 prefers-reduced-motion 禁用了跟随。默认运行十项检查;添加 --modal "#trigger" 进行第十一项检查,该检查会打开一个覆盖层并将其堆叠顺序与光标进行比较。

Playwright 是此包中唯一可选的依赖项。如果它没有安装,或者页面无法提供,则在 1366×768 和 390×844 的分辨率下手动执行同样的十一项检查 — 如果你不这样做,报告必须明确说明 NOT_TESTED: rendered behaviour。永远不要暗示你看到了。

跳过的检查不等于通过。verify.mjs 会单独打印跳过的检查,原因就在于此:这意味着页面没有暴露足够的测试项,并且报告必须说明哪个检查被跳过以及为什么。

阶段 7 — 报告

使用 references/recommendation.md。报告始终以两个列表结束:需要关注的内容 和 有意禁用的内容。

限制

  • 代码不是渲染结果。 审计读取源代码。backdrop-filter、层叠上下文或祖先元素上的 transform 可能会改变光标的视觉效果,而源代码不会显示出来。
  • 静态分析只能看到它能解析的内容。 样式可能存在于内联对象、构建时解析的工具类、CSS-in-JS 或组件内部。审计会统计它错过了什么,指出值得打开的文件,并降低置信度 — 它不会掩盖差距。
  • 浏览器验证需要浏览器。 scripts/verify.mjs 需要 Playwright 和一个正在运行的页面。没有它,行为仍然为 NOT_TESTED,并且报告必须说明这一点。
  • 评分是启发式的,而不是度量标准。 它们对系列进行排名以匹配网站。它们不能预测转化率、品味,或者客户的老板是否喜欢它。
  • 没有实时 URL。 这是有意为之 — 一个链接会让技能跳过仓库,而令牌就在仓库里。代价是渲染状态无法验证。
  • T3 需要已有的 GPU 依赖项。 只有当仓库已经包含 three、ogl 或着色器管道时,才会提供 WebGPU 着色器。为光标添加一个 600KB 的渲染器不是一个好的设计决策。
  • 没有自创的品牌颜色。 如果审计没有找到可用的强调色,这将变成一个补全问题,而不是使用默认值。
  • 戏剧化层级不在范围内 — 群集光标、绘制字符、全页光标接管。它们是全站的噱头,而不是光标决策,而且它们的成本比此技能的其余部分加起来还要高。

此技能旨在防止的失败模式

症状原因
光标在手机上不可见,页面无法使用cursor: none 没有配合粗略指针防护
点击穿透光标缺少 pointer-events: none
光标在滚动时滞后或不同步mousemove 监听器没有防抖或使用 requestAnimationFrame

相关技能