Communitygithub.com

cursorfit

為網站選擇並建立合適的自訂游標。稽核儲存庫的調色盤、排版、動態與佈局,在五個軸線上為網站設計特性評分,然後選擇一個游標系列並使用網站本身的設計權杖來實作。當有人要求自訂游標、滑鼠跟隨器、游標軌跡、磁性游標、混合模式游標、點與環游標,或詢問哪種游標風格適合他們的網站時使用。讀取儲存庫或 CSS 檔案;無需即時 URL。

cursorfit 是什麼?

cursorfit 是一個專業的 AI 代理技能,專為 Claude Code、Cursor 和 Codex 等平台設計,用於在建置自訂游標之前,先對網站的設計系統進行理性稽核。與其他僅專注於視覺效果的游標技能不同,cursorfit 會先分析儲存庫的調色盤、排版、動態、間距與控制項密度,並在包含「內斂-表現性」、「精確-有機」、「密集-通透」、「冷靜-活力」與「產品-編輯」等五個軸線上為網站生成一個設計特徵分數。接著,它會使用這個分數從一個預定義的系列庫(例如點與環、遮罩顯現、磁性修飾符)中選擇最合適的游標系列,並使用從儲存庫中提取的實際設計權杖(例如 CSS 變數、Tailwind 設定)來實作它。該技能在作出決定前,會先透過覆蓋率報告與熱點檢查來驗證其分析,確保不會忽略內聯樣式或 CSS-in-JS。它支援無頭模式(不需即時 URL)、驗證腳本(含 Playwright),並為 React 和 Vanilla JS 專案產生已組裝好、可供部署的游標組件。cursorfit 也會明確說明何時應完全避免自訂游標,例如在內容密集或無障礙性關鍵的頁面中。

相容平台~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 加上一個 2,000 行的手寫 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. 每個分數都帶有一個信心等級。 high、medium 或 low,來自稽核的覆蓋率區塊。中等信心的分數以區間帶形式引用,而非單一數字。低信心的分數完全不引用 — 它會變成一個需填補的缺口問題。完整規則在 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 由 JavaScript 在第一個影格之後套用,永遠不要在靜態 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 沒有粗指針防護
點擊穿透

…(因篇幅截斷)

相關技能