cursorfit は何をしますか?
カスタムカーソルは、ユーザビリティという代償を伴うデザイン上の判断です。ほとんどのカーソルスキルは効果を売り込み、代償を無視します。このスキルは、まずサイトを読み取り、代償を払う価値があるかどうかを判断してから、初めて構築します。
一言で言えば、カーソルがこのサイトに合致するか、あるいはなぜカーソルを追加すべきでないのかが提示されます。
このスキルが答えること
- このサイトにカスタムカーソルは必要か?
- どのファミリーを、このサイトの色で、このサイトの速度で使うべきか?
- ボタン、画像、段落、無効化されたコントロール、タッチスクリーンの上で、それはどのように振る舞うか?
誠実さを保つルール
推奨におけるすべての主張は、リポジトリ内で見つかったもの(ファイル、トークン、測定値、カウント)を引用しなければなりません。それができない場合、それは意見であり、そのようにラベル付けされます。「サイトはモダンでミニマルに感じられる」は証拠ではなく、出力に決して現れてはいけません。
パイプライン
| ステージ | 出力 |
|---|---|
| 0. リポジトリを読む | フレームワーク、ファイルマップ、既存のカーソルコード |
| 1. 監査 | cursorfit.json — トークン、タイポグラフィ、モーション、密度、コントロール、およびカバレッジレポート |
| 1b. 読み取り | 監査が読み取れなかったコンポーネント、インラインスタイル、ユーティリティクラス |
| 2. スコアリング | 5軸、各軸に証拠と信頼度、モーションシグネチャ |
| 3. ギャップ補完 | 最大3つの質問、それぞれにデフォルト値あり |
| 4. 決定 | 1つのプライマリ + 2つの代替案、各代替案に欠点を明示、証拠に基づく上書き許可 |
| 5. 構築 | リポジトリにファイルを書き込み、エントリポイントに配線 |
| 6. 検証 | grep、ビルド、および scripts/verify.mjs によるブラウザパス |
| 7. 報告 | references/recommendation.md の形式 |
ステージ1からステージ4に飛ばないでください。スコアリングこそが、回答が分析ではなく好みで飾られるのを防ぎます。
ステージ0 — 決定する前に読む
スコアリングする前にリポジトリをマッピングします。以下を知っておく必要があります:
- フレームワーク: カーソルがどこにマウントされるか、そして
bodyのcursor: noneがコンポーネントライブラリによって上書きされるかどうかを決定します。 - 実際のスタイルがどこにあるか: 1つの
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ファイルの数、そして最初に開く価値のある5つのファイル。スコアはそのカバレッジと同じくらい良好であるため、scores を読む前に coverage を読んでください。
ヘルパーが実行できない場合は、references/audit.md のシグナルテーブルを使用して同じ抽出を手動で行います。そのテーブルのすべてのシグナルはスコアリング入力にマッピングされるため、1つをスキップすると、その軸は推測ではなく UNKNOWN になります。
ステージ1b — 監査ができなかったものを読む
静的解析には既知のブラインドスポットリストがあり、それを無視すると、プロファイルが半分しか読んでいないサイトに自信を持ってしまうことになります。coverage.hotspots のファイルを開き、それぞれについて3つの質問に答えます:
- 実際にレンダリングされているパディング、半径、タイプサイズは? インラインスタイルとユーティリティクラスには、スタイルシートスキャンが決して見なかった値が保持されています。
- コンポーネントラッパーは構造を変更するか?
<Button>は<button>ではなく、クリックハンドラを持つ<div>をレンダリングする可能性があります。これにより、data-cursorをコントロールにフックする状態ラベルのレシピが変更されます。 - 監査が見ることができなかったレイアウトまたはスタッキングコンテキストはあるか? スティッキーラッパー、
overflow: hiddenセクション、isolation: isolate、backdrop-filter— これらのいずれも、カーソルが上に座るものを移動させる可能性があります。
このパスのルール:
- ホットスポットとエントリポイントおよびレイアウトシェルのみを読みます。リポジトリ全体ではありません。
- ホットスポットが測定値を約20%以上変更する場合、修正値を記録し、レポートでそれがスクリプトではなく読み取りから来たことを述べます。
- ホットスポットを解決できない場合(生成されたスタイル、ビルド時のテーマ)、影響を受ける軸を
mediumにダウングレードし、どのファイルが原因かを示します。 - 数値を良くするために監査を再実行しないでください。スクリプトの出力は証拠であり、草案ではありません。
ステージ2 — スコアリング
5軸(各0〜100)とモーションシグネチャ。完全なルーブリックは references/profile.md にあります。
RESTRAINED ──────────▓▓▓ 74 EXPRESSIVE
PRECISE ▓▓▓▓▓▓▓▓░░░░ 58 ORGANIC
DENSE ▓▓▓░░░░░░░░░ 31 AIRY
CALM ▓▓▓▓▓▓░░░░░░ 47 ENERGETIC
PRODUCT ▓▓▓▓▓▓▓▓▓░░░ 68 EDITORIAL
ルール:
- 軸あたり最低2つの証拠項目。 少ない場合は
UNKNOWNとなり、UNKNOWNは中央値の推測ではなく、ギャップ補完の質問になります。 - スコアはサイトを説明し、カーソルを説明しません。 抑制されたサイトは抑制されたカーソルを求めているのではありません。派手なカーソルがページ上で唯一の派手なものになることを伝えています。
- モーションシグネチャは感覚ではなく、測定値です。 実際のイージングカーブ、中央値の時間、キーフレーム数、およびスプリングやオーバーシュートがあるかどうかを記録します。
- すべてのスコアには信頼度が付随します。
high、medium、またはlowで、監査のカバレッジブロックから来ます。mediumスコアは数値ではなく範囲として引用されます。lowスコアはまったく引用されません — ギャップ補完の質問になります。完全なルールはreferences/profile.mdにあります。
ステージ3 — ギャップ補完
最大3つの質問をします。ただし、UNKNOWN で返ってきた軸、またはリポジトリが保持できない事実についてのみです。すべての質問にはデフォルト値が付属しているため、「わかりません」でも決定が生成されます。
通常、尋ねる価値のある3つ:
- このページに最初に訪れるのは誰ですか? 製品を評価する顧客 / ドキュメントを読む開発者 / ポートフォリオを評価するクライアント。デフォルト: 顧客。
- カーソルにどの程度の個性を持たせることができますか? 洗練のみ / 目立つ / 特徴的。デフォルト: 目立つ。
- 使用すべき、または使用してはならない色はありますか? デフォルト: リポジトリ内で最も彩度の高いブランドトークン。
リポジトリが既に答えていることは尋ねないでください。モデルが決定できる外観上の質問をしないでください。答えが推奨を何も変えない場合、それは質問ではありませんでした。
ステージ4 — 決定
references/families.md のすべてのファミリーをプロファイルに対してスコアリングし、ハードゲートを適用します。magnetic は修飾子です — 選択されたファミリーに1つまたは2つの要素に追加され、プライマリになることはできません。1つのプライマリと2つの代替案を出力します。フラットなメニューは決してありません — メニューは決定を依頼者に返してしまいます。
各代替案には、同じ文でその欠点が示されます。脚注ではありません:
代替案B — マスクリビール。 3つの中で最もエディトリアルにフィットします。コストは、すべてのプロジェクト画像の上にキャンバスレイヤーが追加されることです。画像の読み込みに失敗したカードでは壊れて見えます。
「ネイティブカーソルを維持する」は有効な判定です。 サイトが読み取り主体、フォーム主体、またはアクセシビリティに重要な場合、そう言ってください。それでも最もリスクの低いオプションとそのコストを提供します。なぜなら、依頼者はカーソルを求めており、完全に拒否することは誰の助けにもなりません。
ランキングを上書きすることはできますが、決して黙って行ってはいけません。 数値は決定支援であり、測定値ではありません。監査は読み取れなかったものを知りません。上書きは、カバレッジパスがスクリプトが見逃したものを発見した場合に許可されます — 実際のインタラクションパターン、コントロール構造を変更するコンポーネント、CSSスキャンが見ることができなかったスタッキングコンテキスト。上書きを主張するには、次の4つすべてを述べてください:
- 監査が1位にランク付けしたファミリーとその適合度、
- それを変更する特定の証拠、ファイルパスまたは測定値、
- 代わりに選択するファミリー、
- 上書きを採用することで読者が失うもの。
ファイルパスのない上書きは好みです。好みは最後の仕上げ(サイズ、イージング、正確なラベル)では許容されますが、ファミリーの選択では決して許されません。
ステージ5 — 構築
すべてのファミリーの完全な実装は references/recipes.md にあります。レシピをコピーし、プロファイルが変更を指示するものだけを変更します。
非交渉事項:
- 色はトークンから取得し、新しい16進数からは決して取得しません。 監査が見つけた最も強いブランドカラーにバインドします(
var(--neon-cyan)、theme('colors.accent')、エクスポートされた定数)。ハードコードされた#00f0ffは、「あなたのサイトにマッチする」と「コピー元のサイトにマッチする」の違いです。 - ベース状態レイヤーはすべてのファミリーに同梱されます。 リンク、ボタン、テキスト、無効が
cursor.jsで解決され、家族コードが追加される前にcursor.cssでスタイリングされます。どのファミリーもこれらを削除しません。dotは数値を下げるだけです。ボタンを横切っても何もしないカーソルは未完成です — 訪問者はそれをステッカーと区別する方法がありません。 - ラベルは拡張であり、状態ではありません。
[data-cursor]は既に存在する状態の上に単語を追加します。ビルドがサイトに注釈が付けられた場所にのみ反応する場合、状態レイヤーが欠落しています。 - T1ファミリーのコードは、共有コアに加えて約90行以内に収めます。 ファミリー独自のレイヤーがそれ以上必要な場合、そのファミリーはサイトに適していません。コアは一度だけ約100行です。なぜなら、すべてのファミリーの状態レイヤーを運ぶからです。
cursor: noneは最初のフレームの後にJSによって適用され、静的なCSSでは決して適用されません。 スクリプトが失敗した場合、ユーザーは動作するカーソルを保持します。- 一度だけマウントします。 ルートごとにマウントされたカーソルは、2つ、そして3つになります。
- タッチには何も与えません。 小さなカーソルもありません。何もありません。
Vanillaは cursor.css + cursor.js と1行の <script defer> として出荷されます。Reactは1つのコンポーネントと同一のCSSとして出荷され、ルーターの上にマウントされます。
アートワークでビルドが停滞しないように、2つの既製アセットセットが存在します:
assets/shapes.css— 7つのシルエット(円、リング、正方形、クロスヘア、ピル、ブラケット、ブロブ)。マークに1つのクラスを追加します。シルエットの選択はプロファイルから来ます。assets/cursors/*.svg— ホットスポット値を持つ4つのイメージカーソル、T0ファミリー用。暗い輪郭を持つ白で、明るいセクションと暗いセクションの両方で生き残ります。
ファイルをリポジトリにコピーし(通常は public/cursors/ と src/styles/)、実行時にこのスキルのフォルダを参照しないでください。
ステージ6 — 検証
3つのレベルを順番に実行します。それぞれが前のレベルではキャッチできないものをキャッチします。
1. grep。 references/gating.md の静的チェックを実行します。それらは意見ではなくgrepです:pointer-events、position: fixed、aria-hidden、coarse-pointerガード、reduced-motionガード、transform の transition なし、mouseleave での非表示、blend-contextチェック。
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 を持っている、遅れてから収束する、ホバーが状態を変更する、クリックが下のコントロールに届く、フォーカスがリングを保持する、ルート変更が2つ目のカーソルを生成しない、コンソールがクリーンである、タップがカーソルを出現させない、prefers-reduced-motion がフォローを無効にする。デフォルトで10のチェックが実行されます。11番目のチェックとして --modal "#trigger" を追加すると、オーバーレイを開き、そのスタッキングをカーソルと比較します。
Playwrightはパッケージ内で唯一のオプションの依存関係です。インストールされていない場合、またはページを提供できない場合、同じ11のチェックを1366×768と390×844で手動で実行します。実行しない場合、レポートはその言葉で NOT_TESTED: rendered behaviour と表示します。見たことを決して暗示しないでください。
スキップされたチェックは合格ではありません。verify.mjs はその理由からスキップを個別に出力します: ページがテストするのに十分に公開しなかったことを意味し、レポートはどのチェックがスキップされ、なぜかを述べなければなりません。
ステージ7 — 報告
references/recommendation.md を使用します。レポートは常に2つのリストで終わります: 何を見るべきか と 何が意図的に無効化されているか。
制限
- コードはレンダリングではありません。 監査はソースを読み取ります。
backdrop-filter、スタッキングコンテキスト、または祖先のtransformはカーソルの外観を変更する可能性があり、ソースはそれを表示しません。 - 静的解析は解析できるものだけを見ます。 スタイリングはインラインオブジェクト、ビルド時に解決されるユーティリティクラス、CSS-in-JS、またはコンポーネント内部に存在する可能性があります。監査は見逃したものをカウントし、開く価値のあるファイルを命名し、信頼度を下げます — ギャップを隠しません。
- ブラウザ検証にはブラウザが必要です。
scripts/verify.mjsはPlaywrightと実行中のページを必要とします。それがなければ、動作はNOT_TESTEDのままであり、レポートはそう述べなければなりません。 - スコアはヒューリスティックであり、測定値ではありません。 それらはサイトに対してファミリーをランク付けします。コンバージョン、好み、またはクライアントの上司がそれを気に入るかどうかを予測しません。
- ライブURLはありません。 設計上 — リンクがあればスキルがリポジトリをスキップする可能性があり、トークンがあるのはリポジトリです。代償として、レンダリングされた状態は未検証です。
- T3は既存のGPU依存関係を必要とします。 WebGPUシェーダーは、リポジトリが既に
three、ogl、またはシェーダーパイプラインを出荷している場合にのみ提供されます。カーソルに600KBのレンダラーを追加することはデザイン上の判断ではありません。 - 発明されたブランドカラーはありません。 監査が使用可能なアクセントを見つけられない場合、それは質問になり、デフォルトにはなりません。
- 演劇的なティアは範囲外です — スウォームカーソル、描かれたキャラクター、全ページカーソル乗っ取りなど。それらはサイト全体のギャグであり、カーソルの判断ではなく、このスキルの残りの部分を合わせたよりもコストがかかります。
このスキルが存在する理由である障害モード
| 症状 | 原因 |
|---|---|
| 電話でカーソルが見えず、ページが使用不可 | coarse-pointerガードなしの cursor: none |
| クリックがカーソルを通過する |
...
[truncated for translation]