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의 파일을 열고 각각에 대해 세 가지 질문에 답하십시오:
- 실제로 렌더링되는 padding, radius 및 type size는 무엇인가요? 인라인 스타일과 유틸리티 클래스는 스타일시트 스캔이 본 적 없는 값을 보유합니다.
- 컴포넌트 래퍼가 구조를 변경하나요?
<Button>은<button>이 아닌 클릭 핸들러가 있는<div>를 렌더링할 수 있습니다. 이는data-cursor를 컨트롤에 연결하는 상태-레이블 레시피를 변경합니다. - 감사가 볼 수 없는 레이아웃 또는 쌓임 컨텍스트가 있나요? 스티키 래퍼,
overflow: hidden섹션,isolation: isolate,backdrop-filter— 이들 중 어느 것이라도 커서가 위에 위치하는 것을 이동시킬 수 있습니다.
이 패스의 규칙:
- 핫스팟, 진입점 및 레이아웃 셸만 읽으십시오. 전체 저장소를 읽지 마십시오.
- 핫스팟이 측정값을 ~20% 이상 변경하는 경우 수정된 값을 기록하고 보고서에 스크립트가 아닌 읽기에서 왔다고 명시하십시오.
- 핫스팟을 해결할 수 없는 경우(생성된 스타일, 빌드 타임 테마) 영향을 받는 축을
medium으로 낮추고 어떤 파일이 원인인지 말하십시오. - 숫자를 더 좋게 만들기 위해 감사를 다시 실행하지 마십시오. 스크립트의 출력은 증거이지 초안이 아닙니다.
단계 2 — 점수화
다섯 가지 축, 각각 0–100, 그리고 모션 시그니처. 전체 루브릭은 references/profile.md에 있습니다.
RESTRAINED ──────────▓▓▓ 74 EXPRESSIVE
PRECISE ▓▓▓▓▓▓▓▓░░░░ 58 ORGANIC
DENSE ▓▓▓░░░░░░░░░ 31 AIRY
CALM ▓▓▓▓▓▓░░░░░░ 47 ENERGETIC
PRODUCT ▓▓▓▓▓▓▓▓▓░░░ 68 EDITORIAL
규칙:
- 축당 최소 두 개의 증거 항목. 더 적으면
UNKNOWN이며,UNKNOWN은 중앙값 추측이 아닌 갭 채우기 질문이 됩니다. - 점수는 사이트를 설명하며, 커서를 설명하지 않습니다. 절제된 사이트가 절제된 커서를 원하는 것이 아닙니다. 화려한 커서가 페이지에서 유일하게 화려한 요소가 될 것임을 알려주는 것입니다.
- 모션 시그니처는 느낌이 아니라 측정입니다. 실제 이징 곡선, 중앙값 지속 시간, 키프레임 개수 및 스프링 또는 오버슈트하는 항목이 있는지 기록하십시오.
- 모든 점수는 신뢰도를 갖습니다.
high,medium또는low이며, 감사의 커버리지 블록에서 가져옵니다. medium 점수는 숫자가 아닌 범위로 인용됩니다. low 점수는 전혀 인용되지 않으며 갭 채우기 질문이 됩니다. 전체 규칙은references/profile.md에 있습니다.
단계 3 — 갭 채우기
최대 세 가지 질문을 하며, UNKNOWN으로 반환된 축 또는 저장소가 보유할 수 없는 사실에 대해서만 질문합니다. 모든 질문에는 기본값이 제공되므로 "모르겠습니다"라고 해도 여전히 결정이 생성됩니다.
일반적으로 물어볼 가치가 있는 세 가지:
- 이 페이지에 누가 먼저 도착하나요? 제품을 평가하는 고객 / 문서를 읽는 개발자 / 포트폴리오를 평가하는 클라이언트. 기본값: 고객.
- 커서가 얼마나 많은 개성을 전달할 수 있나요? 폴리시만 / 눈에 띔 / 시그니처. 기본값: 눈에 띔.
- 사용해야 하거나 사용하지 말아야 할 색상이 있나요? 기본값: 저장소에서 가장 채도가 높은 브랜드 토큰.
저장소가 이미 답하는 것은 묻지 마십시오. 모델이 결정할 수 있는 미용적인 질문은 하지 마십시오. 답변이 추천을 전혀 바꾸지 않는다면 그것은 질문이 아니었습니다.
단계 4 — 결정
references/families.md의 모든 계열을 프로필에 대해 점수화한 다음 하드 게이트를 적용하십시오. magnetic은 수정자입니다 — 선택된 계열에 하나 또는 두 개의 요소에 추가되며 절대 기본이 될 수 없습니다. 하나의 기본과 두 개의 대안을 출력하십시오. 절대 평면 메뉴가 아닙니다 — 메뉴는 결정권을 요청한 사람에게 다시 돌려줍니다.
각 대안은 각주가 아닌 같은 문장에 단점을 함께 제시해야 합니다:
대안 B — 마스크 리빌. 세 가지 중 가장 강력한 에디토리얼 적합성; 모든 프로젝트 이미지 위에 캔버스 레이어가 필요하며, 이미지 로드에 실패한 카드에서는 깨져 보일 것입니다.
"기본 커서 유지"는 유효한 판결입니다. 사이트가 읽기 중심이거나, 양식 중심이거나, 접근성이 중요한 경우 그렇게 말하고 — 여전히 가장 위험이 적은 옵션과 그 비용을 제시하십시오. 상대방이 커서를 요청했는데 완전히 거절하는 것은 누구에게도 도움이 되지 않습니다.
순위를 재정의할 수 있지만, 절대 조용히 하지 마십시오. 숫자는 결정 지원 도구이지 측정이 아니며, 감사는 읽을 수 없었던 것을 알지 못합니다. 커버리지 패스가 스크립트가 놓친 것(실제 상호작용 패턴, 컨트롤 구조를 변경하는 컴포넌트, CSS 스캔이 볼 수 없었던 쌓임 컨텍스트)을 찾았을 때 재정의가 허용됩니다. 재정의를 주장하려면 네 가지를 모두 명시하십시오:
- 감사가 1순위로 평가한 계열과 그 적합성,
- 이를 변경하는 특정 증거(파일 경로 또는 측정값 포함),
- 대신 선택하는 계열,
- 재정의를 통해 독자가 잃는 것.
파일 경로가 없는 재정의는 취향입니다. 취향은 마지막 단계(크기, 이징, 정확한 레이블)에서 허용되며, 계열 선택에서는 절대 허용되지 않습니다.
단계 5 — 빌드
모든 계열의 완전한 구현은 references/recipes.md에 있습니다. 레시피를 복사한 다음 프로필이 변경하라고 말하는 것만 변경하십시오.
양보할 수 없는 사항:
- 색상은 토큰에서 가져오며, 새로운 hex를 사용하지 않습니다. 감사가 찾은 가장 강력한 브랜드 색상에 바인딩하십시오(
var(--neon-cyan),theme('colors.accent'), 내보낸 상수). 하드코딩된#00f0ff는 "사이트와 일치"와 "복사된 사이트와 일치"의 차이입니다. - 기본 상태 레이어는 모든 계열과 함께 제공됩니다. 링크, 버튼, 텍스트 및 비활성화는
cursor.js에서 해결되고cursor.css에서 스타일링되며 계열 코드가 추가되기 전에 이루어집니다. 어떤 계열도 이를 삭제하지 않습니다;dot는 숫자만 낮춥니다. 버튼 위에서 아무것도 하지 않는 커서는 미완성입니다 — 방문자는 이를 스티커와 구분할 방법이 없습니다. - 레이블은 상태의 개선이지 상태 자체가 아닙니다.
[data-cursor]는 이미 존재하는 상태 위에 단어를 추가합니다. 빌드가 사이트에 주석이 달린 곳에서만 반응한다면 상태 레이어가 누락된 것입니다. - T1 계열 코드는 공유 코어 위에 약 90줄 미만으로 유지됩니다. 계열 자체 레이어에 더 많은 것이 필요하다면 계열이 사이트에 잘못된 것입니다. 코어는 모든 계열에 대한 상태 레이어를 전달하기 때문에 한 번 약 100줄입니다.
cursor: none은 정적 CSS가 아닌 JS가 첫 번째 프레임 이후에 적용합니다. 스크립트가 실패하면 사용자는 작동하는 커서를 유지합니다.- 한 번만 마운트하십시오. 라우트당 마운트된 커서는 두 개, 그 다음 세 개가 됩니다.
- 터치는 아무것도 얻지 못합니다. 더 작은 커서도 아닙니다. 아무것도 아닙니다.
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, coarse-pointer 가드, reduced-motion 가드, transform에 transition 없음, 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이 팔로우를 비활성화합니다. 기본적으로 10개의 검사가 실행됩니다. 열한 번째 검사를 위해 --modal "#trigger"를 추가하여 오버레이를 열고 커서에 대한 쌓임을 비교하십시오.
Playwright는 패키지의 유일한 선택적 의존성입니다. 설치되지 않았거나 페이지를 제공할 수 없는 경우 동일한 11개 검사를 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 의존성이 필요합니다. WebGPU 셰이더는 저장소가 이미
three,ogl또는 셰이더 파이프라인을 제공하는 경우에만 제공됩니다. 커서를 위해 600KB 렌더러를 추가하는 것은 디자인 결정이 아닙니다. - 발명된 브랜드 색상이 없습니다. 감사가 사용 가능한 강조 색상을 찾지 못하면 기본값이 아닌 질문이 됩니다.
- 연극적 계층은 범위를 벗어납니다 — 떼 커서, 그려진 캐릭터, 전체 페이지 커서 장악. 이들은 사이트 전체 개그이지 커서 결정이 아니며, 이 기술의 나머지 부분을 합친 것보다 더 많은 비용이 듭니다.
이 기술이 방지하기 위해 존재하는 실패 모드
| 증상 | 원인 |
|---|---|
| 휴대폰에서 커서가 보이지 않고 페이지를 사용할 수 없음 | coarse-pointer 가드 없는 cursor: none |
| 클릭이 아래 컨트롤을 통과함 | pointer-events: none 누락 |
| 경로 변경 후 두 개의 커서가 나타남 | 라우트당 마운트, 전역당 마운트 아님 |
| 어두운 섹션에서 커서가 사라짐 | 하드코딩된 밝은 색상, 반전 없음 |
| 스크롤 후 커서가 튀거나 뒤처짐 | position: fixed 누락 또는 requestAnimationFrame 누락 |
| 접근성 검사기가 커서에 플래그 지정 | aria-hidden="true" 누락 |
| 모션 선호도가 '축소'로 설정된 사용자가 커서를 볼 수 없음 | prefers-reduced-motion 가드 누락 |
| 커서가 실제 스타일과 일치하지 않음(색상, 반경, 크기) | 감사 건너뛰기, 토큰 대신 hardcode 사용 |
참조
references/audit.md— 수동 감사 신호 표references/families.md— 사용 가능한 계열 및 점수화references/gating.md— 정적 검사(grep)references/profile.md— 점수화 루브릭references/recipes.md— 구현 레시피references/recommendation.md— 보고서 템플릿scripts/audit.mjs— 감사 헬퍼scripts/verify.mjs— Playwright 검증 하네스assets/shapes.css— 일곱 개의 실루엣assets/cursors/*.svg— 이미지 커서