Communitygithub.com

cursorfit

사이트의 디자인 토큰을 분석하여 맞춤형 커서를 선택하고 구현합니다. 저장소의 팔레트, 타이포그래피, 모션, 레이아웃을 감사하고 다섯 가지 축으로 디자인 성격을 점수화한 뒤, 하나의 커서 계열을 선택하여 사이트 자체 디자인 토큰을 사용해 구현합니다. 사용자 정의 커서, 마우스 팔로워, 커서 트레일, 자기 커서, 블렌드 모드 커서, 점-링 커서를 요청하거나 어떤 커서 스타일이 사이트에 맞는지 질문할 때 사용하세요. 저장소나 CSS 파일을 읽으며 실시간 URL은 필요하지 않습니다.

cursorfit란 무엇인가요?

cursorfit은 웹사이트의 시각적 정체성을 분석하여 가장 적합한 사용자 정의 커서를 선택하고 구현하는 AI 에이전트 기술입니다. 이 기술은 저장소의 프레임워크, 색상, 타이포그래피, 모션, 레이아웃을 자동으로 감사하고, 5가지 축(절제-표현, 정밀-유기, 밀집-통풍, 차분-활기, 상업-에디토리얼)으로 사이트의 디자인 성격을 점수화합니다. 감사 결과를 바탕으로 가장 적합한 커서 계열을 결정하고, 사이트의 자체 디자인 토큰을 활용하여 구현 코드를 생성합니다. Claude Code, Cursor, Codex 등 다양한 AI 코딩 도구와 함께 사용할 수 있으며, 실시간 URL 없이 로컬 저장소만으로 작업이 가능합니다. 중요한 점은 '커서가 사이트에 어울리지 않는다'는 판단도 내릴 수 있으며, 모든 추천은 저장소에서 발견된 증거(파일, 토큰, 측정값)에 기반해야 한다는 엄격한 규칙을 따릅니다. 접근성과 사용성을 최우선으로 하여 터치스크린에서는 커서를 비활성화하고, JS가 실패할 경우 기본 커서로 폴백되도록 설계되었습니다.

지원 대상~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/HusainMain/cursorfit/tree/HEAD

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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. 실제로 렌더링되는 padding, radius 및 type size는 무엇인가요? 인라인 스타일과 유틸리티 클래스는 스타일시트 스캔이 본 적 없는 값을 보유합니다.
  2. 컴포넌트 래퍼가 구조를 변경하나요? <Button>은 <button>이 아닌 클릭 핸들러가 있는 <div>를 렌더링할 수 있습니다. 이는 data-cursor를 컨트롤에 연결하는 상태-레이블 레시피를 변경합니다.
  3. 감사가 볼 수 없는 레이아웃 또는 쌓임 컨텍스트가 있나요? 스티키 래퍼, 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

규칙:

  1. 축당 최소 두 개의 증거 항목. 더 적으면 UNKNOWN이며, UNKNOWN은 중앙값 추측이 아닌 갭 채우기 질문이 됩니다.
  2. 점수는 사이트를 설명하며, 커서를 설명하지 않습니다. 절제된 사이트가 절제된 커서를 원하는 것이 아닙니다. 화려한 커서가 페이지에서 유일하게 화려한 요소가 될 것임을 알려주는 것입니다.
  3. 모션 시그니처는 느낌이 아니라 측정입니다. 실제 이징 곡선, 중앙값 지속 시간, 키프레임 개수 및 스프링 또는 오버슈트하는 항목이 있는지 기록하십시오.
  4. 모든 점수는 신뢰도를 갖습니다. high, medium 또는 low이며, 감사의 커버리지 블록에서 가져옵니다. medium 점수는 숫자가 아닌 범위로 인용됩니다. low 점수는 전혀 인용되지 않으며 갭 채우기 질문이 됩니다. 전체 규칙은 references/profile.md에 있습니다.

단계 3 — 갭 채우기

최대 세 가지 질문을 하며, UNKNOWN으로 반환된 축 또는 저장소가 보유할 수 없는 사실에 대해서만 질문합니다. 모든 질문에는 기본값이 제공되므로 "모르겠습니다"라고 해도 여전히 결정이 생성됩니다.

일반적으로 물어볼 가치가 있는 세 가지:

  1. 이 페이지에 누가 먼저 도착하나요? 제품을 평가하는 고객 / 문서를 읽는 개발자 / 포트폴리오를 평가하는 클라이언트. 기본값: 고객.
  2. 커서가 얼마나 많은 개성을 전달할 수 있나요? 폴리시만 / 눈에 띔 / 시그니처. 기본값: 눈에 띔.
  3. 사용해야 하거나 사용하지 말아야 할 색상이 있나요? 기본값: 저장소에서 가장 채도가 높은 브랜드 토큰.

저장소가 이미 답하는 것은 묻지 마십시오. 모델이 결정할 수 있는 미용적인 질문은 하지 마십시오. 답변이 추천을 전혀 바꾸지 않는다면 그것은 질문이 아니었습니다.

단계 4 — 결정

references/families.md의 모든 계열을 프로필에 대해 점수화한 다음 하드 게이트를 적용하십시오. magnetic은 수정자입니다 — 선택된 계열에 하나 또는 두 개의 요소에 추가되며 절대 기본이 될 수 없습니다. 하나의 기본과 두 개의 대안을 출력하십시오. 절대 평면 메뉴가 아닙니다 — 메뉴는 결정권을 요청한 사람에게 다시 돌려줍니다.

각 대안은 각주가 아닌 같은 문장에 단점을 함께 제시해야 합니다:

대안 B — 마스크 리빌. 세 가지 중 가장 강력한 에디토리얼 적합성; 모든 프로젝트 이미지 위에 캔버스 레이어가 필요하며, 이미지 로드에 실패한 카드에서는 깨져 보일 것입니다.

"기본 커서 유지"는 유효한 판결입니다. 사이트가 읽기 중심이거나, 양식 중심이거나, 접근성이 중요한 경우 그렇게 말하고 — 여전히 가장 위험이 적은 옵션과 그 비용을 제시하십시오. 상대방이 커서를 요청했는데 완전히 거절하는 것은 누구에게도 도움이 되지 않습니다.

순위를 재정의할 수 있지만, 절대 조용히 하지 마십시오. 숫자는 결정 지원 도구이지 측정이 아니며, 감사는 읽을 수 없었던 것을 알지 못합니다. 커버리지 패스가 스크립트가 놓친 것(실제 상호작용 패턴, 컨트롤 구조를 변경하는 컴포넌트, CSS 스캔이 볼 수 없었던 쌓임 컨텍스트)을 찾았을 때 재정의가 허용됩니다. 재정의를 주장하려면 네 가지를 모두 명시하십시오:

  1. 감사가 1순위로 평가한 계열과 그 적합성,
  2. 이를 변경하는 특정 증거(파일 경로 또는 측정값 포함),
  3. 대신 선택하는 계열,
  4. 재정의를 통해 독자가 잃는 것.

파일 경로가 없는 재정의는 취향입니다. 취향은 마지막 단계(크기, 이징, 정확한 레이블)에서 허용되며, 계열 선택에서는 절대 허용되지 않습니다.

단계 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 — 이미지 커서

관련 스킬