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 中的文件,并为每个文件回答三个问题:
- 实际渲染的内边距、圆角和字体大小是多少? 内联样式和工具类包含了样式表扫描从未见到的值。
- 组件包装器是否改变了结构? 一个
<Button>可能渲染一个带有点击处理器的<div>,而不是<button>。这会改变状态标签的配方,该配方将data-cursor挂接到控件上。 - 是否存在审计无法看到的布局或层叠上下文? 粘性包装器、
overflow: hidden部分、isolation: isolate、backdrop-filter— 任何一个都可能移动光标所在的位置。
此遍的规则:
- 只读取热点文件加上入口点和布局外壳。不是整个仓库。
- 如果一个热点改变了测量值超过约 20%,则记录校正后的值,并在报告中说明该值来自手动读取,而非脚本。
- 如果一个热点无法解析(生成的样式、构建时主题),则将受影响的维度降级为
medium,并说明是哪个文件导致的。 - 永远不要重新运行审计以使数字更好看。脚本的输出是证据,而不是草稿。
阶段 2 — 评分
五个维度,每个 0–100,加上一个动效特征。完整评分标准见 references/profile.md。
克制 ──────────▓▓▓ 74 表现
精确 ▓▓▓▓▓▓▓▓░░░░ 58 有机
密集 ▓▓▓░░░░░░░░░ 31 通透
冷静 ▓▓▓▓▓▓░░░░░░ 47 活力
产品 ▓▓▓▓▓▓▓▓▓░░░ 68 编辑
规则:
- 每个维度至少两个证据项。 少于两个意味着
UNKNOWN,而UNKNOWN会变成一个补全问题,而不是中位数猜测。 - 分数描述的是网站,而不是光标。 一个克制的网站不是在要求一个克制的光标;它是在告诉你,一个喧闹的光标将是页面上唯一喧闹的东西。
- 动效特征是测量出来的,而不是感觉出来的。 记录实际的缓动曲线、中位持续时间、关键帧数量,以及是否有任何弹簧或过冲效果。
- 每个分数都带有置信度。
高、中或低,来自审计的覆盖率块。中等分数以范围形式引用,而不是单一数字。低分根本不引用 — 它变成一个补全问题。完整规则见references/profile.md。
阶段 3 — 补全
最多问三个问题,并且只针对返回 UNKNOWN 的维度或仓库无法容纳的事实。每个问题都附带一个默认值,所以「我不知道」仍然能产生一个决策。
通常值得问的三个问题:
- 谁最先访问这个页面? 评估产品的客户 / 阅读文档的开发者 / 评判作品集的客户。默认:客户。
- 光标允许承载多少个性? 仅润色 / 引人注目 / 标志性。默认:引人注目。
- 是否有必须使用或绝对不能使用的颜色? 默认:仓库中最饱和的品牌令牌。
永远不要问仓库已经回答了的问题。永远不要问模型可以决定的装饰性问题。如果答案不会改变推荐内容,那它就不是一个问题。
阶段 4 — 决策
根据 references/families.md 中的评分标准对每个系列进行评分,然后应用硬性门槛。magnetic 是一个修饰符 — 它被添加到所选系列的一个或两个元素上,并且永远不能作为主要系列。输出一个主要系列和两个备选。永远不要提供一个扁平菜单 — 菜单把决策权交回给提出需求的人。
每个备选都必须附带其劣势,而不是在脚注中:
备选 B — 遮罩揭示。 三者中编辑拟合度最强;但它需要为每个项目图片添加一个画布层,并且在任何图片加载失败的卡片上会显得异常。
「保留原生光标」是一个有效的裁决。 当网站是重阅读型、重表单型或对可访问性要求严格时,请明确说明 — 然后仍然提供风险最低的选项及其成本,因为提出需求的人想要一个光标,直接拒绝对任何人都没有帮助。
你可以覆盖排名,但绝不能悄无声息。 数字是决策支持,而不是度量标准,审计无法知道它未能读取的内容。当覆盖率测试发现了脚本遗漏的内容时 — 一个真实的交互模式、一个改变控件结构的组件、一个 CSS 扫描无法看到的层叠上下文 — 才允许覆盖。要声称覆盖,请说明全部四点:
- 审计排名第一的系列及其拟合度,
- 改变这一点的具体证据,附带文件路径或测量值,
- 你选择替代的系列,
- 读者因采用覆盖而失去的内容。
没有文件路径的覆盖是品味。品味在最后一英里是可以的 — 尺寸、缓动、确切的标签 — 但绝不能在选择系列时使用。
阶段 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 |