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 中的檔案,並為每個檔案回答三個問題:
- 實際渲染的內距、圓角和字型大小是多少? 內聯樣式和工具類別包含了樣式表掃描從未見過的值。
- 組件包裝器是否改變了結構? 一個
<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會變成一個需填補的缺口問題,而不是一個中位數猜測。 - 分數描述的是網站,不是游標。 一個內斂的網站並不是在要求一個內斂的游標;它是在告訴你,一個喧鬧的游標會是頁面上唯一喧鬧的東西。
- 動態特徵是測量出來的,不是感覺出來的。 記錄實際的緩動曲線、中位數持續時間、關鍵影格數量,以及是否有任何東西會彈跳或超調。
- 每個分數都帶有一個信心等級。
high、medium或low,來自稽核的覆蓋率區塊。中等信心的分數以區間帶形式引用,而非單一數字。低信心的分數完全不引用 — 它會變成一個需填補的缺口問題。完整規則在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由 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 沒有粗指針防護 |
| 點擊穿透 |
…(因篇幅截斷)