Community코딩 & 개발github.com

depth-scroll

깊이 스크롤 페이지를 구축합니다. WhatTheFad(whatthefad.netlify.app)의 랜딩 필드를 모델로, 뷰어를 향해 다가오는 일련의 패널(드로잉, 원 카드, 단계)을 깊이 축의 정거장으로 설정하여 스크롤이 아래로 이동합니다.

depth-scroll란 무엇인가요?

이 스킬은 사용자가 스크롤을 통해 콘텐츠를 '통과'하는 듯한 경험을 제공하는 깊이 스크롤 페이지(depth-scroll page)를 만드는 방법을 설명합니다. WhatTheFad 웹사이트의 랜딩 페이지에서 영감을 받았으며, 각 패널(정거장)은 깊이 축을 따라 배치되어 사용자가 스크롤하면 멀리서 나타나 화면 평면에서 선명해지고 시청자를 지나쳐 뒤로 사라집니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트와 함께 사용하도록 설계되었습니다. 템플릿 HTML(`template.html`), 빌드 Python 스크립트(`build.py`), 헤드리스 캡처 및 탐색 검사 도구(`capture.mjs`) 등 네 가지 핵심 파일을 제공합니다. 사용자는 JSON 사양 파일을 작성하고 빌드 스크립트를 실행하여 독립적인 HTML 파일을 생성합니다. 이 스킬은 4~12개의 자체 완결적 패널을 읽는 데 적합하며, 긴 산문이나 표에는 적합하지 않습니다. 깊이 효과는 CSS 3D 변환과 JavaScript를 사용하여 구현되며, 접근성을 위해 JavaScript가 비활성화되거나 'prefers-reduced-motion' 설정이 활성화된 경우 평면 페이지로 대체됩니다. 또한 `capture.mjs`를 통해 다양한 시나리오(정지 상태, 전환 중, 모바일 화면, 축소 모션 등)에서 페이지를 자동으로 확인할 수 있습니다.

지원 대상✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/rafaelcarlosabbariao/skills/tree/HEAD/agnostic/depth-scroll

Installed? Explore more 코딩 & 개발 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

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

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

문서

이 폴더에 SKILL.local.md가 있으면 먼저 읽으십시오. 해당 파일에는 경로, 데이터 및 내부 규칙이 포함되어 있습니다.

깊이 스크롤

독자가 한 번에 하나씩 통과하는 그림 집합을 위한 페이지 형식입니다. 첫 번째 빌드는 설명 그림 집합을 뷰어를 향한 스크롤로 변환했으며, WhatTheFad(whatthefad.netlify.app, 소스: github.com/rafaelcarlosabbariao/cultural-archaeology)의 랜딩 페이지를 모델로 했습니다.

이 스킬은 다음 네 개의 파일을 포함합니다:

파일설명
template.html페이지: 정거장 크롬, 스트림, 레일 및 이를 실행하는 스크립트
build.py명령줄 또는 모듈로 사용하여 사양에서 템플릿을 채움
capture.mjsDevTools 프로토콜을 통한 실시간 헤드리스 캡처 및 탐색 검사
SKILL.md이 파일

적합한 경우

  • 적합함 한 번에 하나씩 읽는 4~12개의 자체 완결적 패널: 드로잉, 한 가지 아이디어 카드, 시퀀스 단계.
  • 적합하지 않음 긴 산문, 표, 또는 독자가 나란히 비교하거나 앞뒤로 스캔해야 하는 모든 것. 이런 경우 평면 페이지를 만드십시오.
  • 출력 페이지는 외부 스크립트나 WebGL 없이 완전히 독립적인 .html 파일 하나입니다. 템플릿은 :root 토큰에 따뜻한 크림색과 잉크색 팔레트를 제공합니다. 취향에 맞게 다시 스타일링하십시오.

작동 방식

WhatTheFad의 필드, 출처

WhatTheFad의 index.html (#landing-trendfield CSS 및 renderTrendField 함수)을 참조하십시오.

  • 투영 필드는 perspective: 900px인 컨테이너이며, 각 칩은 translate3d(x, y, z)로 배치됩니다. 브라우저는 칩을 900 / (900 − z) 비율로 그립니다: z = −2800에서 0.24, 화면 평면에서 1, z = 220에서 1.3.
  • 클록이 움직임을 구동 requestAnimationFrame 루프는 각 칩을 150px/s 속도로 뷰어를 향해 이동시키며, 칩별 계수 0.75에서 1.25를 곱합니다. z = 220을 지나면 z = −2800의 타원형 링에서 다시 생성됩니다.
  • 페이드 및 그리기 순서 칩은 깊이의 첫 1/4 구간에서 나타나고(fade in) z = 60과 220 사이에서 사라집니다(fade out). 필드는 preserve-3d를 사용하지 않으므로 각 칩의 z-index가 깊이에서 설정되어 가까운 칩이 위에 그려집니다.
  • 조용한 중심 방사형 mask-image가 중간 부분을 숨깁니다. 멀리 있는 칩이 소실점에 모입니다.
  • 칩 잡기 브라우저는 포인터가 움직일 때만 :hover를 다시 확인하므로, 정지된 커서 아래로 드리프트하는 칩은 결코 강조되지 않습니다. WhatTheFad는 매 프레임마다 각 칩의 투영된 사각형에 대해 포인터를 테스트하고, 잡힌 칩은 필드 속도를 8%로 늦춥니다.

이 형식이 추가하는 것

  • 스크롤이 카메라입니다
    • 긴 트랙(main.depth)은 정거장당 한 정지점을 보유하며, scroll-snap-type: y proximity로 한 단계 높이 간격입니다.
    • 고정된 헤더 아래 고정된 스테이지가 장면을 보유합니다.
    • 스크롤 위치는 각 정지점에서 정수인 정거장 인덱스가 됩니다. 카메라는 이를 향해 부드럽게 이동(ease)하고(초당 9회), 정거장 i는 z = (camera − i) × 1400에 그려집니다.
  • 정거장의 통과
    • 뒤에서 기다리는 정거장은 흐릿하고 약간 아래에 위치하여, 앞으로 올라오며 제자리에 오릅니다.
    • 정지 상태에서는 z = 0, 배율 1이며 정수 픽셀로 표시되어 텍스트가 평면 페이지처럼 선명합니다.
    • 뷰어를 지나면 z = 300에서 1.5배율로 사라집니다.
    • 스테이지보다 큰 정거장은 맞춰서 축소됩니다.
  • 스트림 마스크를 포함한 WhatTheFad의 필드입니다. 카드의 속도는 기본 46에 카메라 속도의 0.9를 더한 값이므로, 앞으로 스크롤하면 카드가 빠르게 지나가고 뒤로 스크롤하면 멀어집니다. 정거장은 그릴 카드 그룹을 (lit으로) 지정하며, 해당 카드는 정거장이 앞에 있는 동안 불이 켜집니다.
  • 입력 휠, 트랙패드, 터치, 화살표 키, 레일 및 헤더의 콘텐츠는 모두 하나의 네이티브 스크롤을 움직이므로 모든 입력이 동일한 정지점에 도달합니다.
  • 포커스 앞에 있지 않은 정거장에 포커스가 들어오면 해당 정거장으로 스크롤됩니다.
  • 스트림은 장식용이며, 정지 상태의 정거장만 포인터 이벤트를 받으므로 프레임별 히트 테스트가 필요하지 않습니다.
  • 폴백 JavaScript가 없거나 prefers-reduced-motion: reduce 설정이 있는 경우, 페이지는 정거장이 평평하게 쌓인 형태입니다. 깊이는 스크립트가 추가하는 deep 클래스에 의해 활성화됩니다. 평면 모드에서는 정거장 콘텐츠의 앵커가 정거장 자체로 이동합니다.

하나 만들기

SK는 이 스킬이 설치된 위치입니다(예: ~/.claude/skills/depth-scroll).

  1. 콘텐츠 우선 각 패널을 <figure class="fig">로 평면 페이지에 배치하고, .plate(드로잉)와 figcaption을 포함시킵니다. 평면 페이지는 읽기용 복사본이기도 합니다. 정거장은 대신 html을 직접 가질 수 있습니다.
  2. 사양 작성 (아래 참조) JSON 파일로 작성하거나, 값이 계산되는 경우(예: 데이터 파일에서 읽은 카드 이름) 프로젝트 자체 빌드 스크립트의 딕셔너리로 작성합니다.
  3. 빌드
    python3 -I $SK/build.py spec.json
    
    또는 스크립트에서:
    sys.path.insert(0, str(Path.home() / '.claude/skills/depth-scroll'))
    import build
    build.write(spec, base=HERE)
    
  4. 선택적 헤더 템플릿은 고정 헤더(--pin-h, header.pin, nav.pin-toc)를 위한 공간을 남겨둡니다. 헤더가 없으면 스테이지가 창 상단에서 시작됩니다.
  5. 확인 capture.mjs(아래 참조)로 확인한 후 커밋합니다.

사양

경로는 base를 기준으로 합니다: 사양 파일의 폴더 또는 write에 전달된 폴더. 이미지 경로는 제공된 대로 페이지에 기록되므로, 출력 페이지를 기준으로 제공하십시오.

필드설명
out작성할 페이지
title<title>, 유형별로 이름 지정 (<주제> <유형 명사>)
source선택적 평면 페이지. figure.fig 블록은 fig: n이 되고, 스타일 블록(헤더의 것은 제외)이 복사되어 드로잉이 클래스를 유지함
kicker섹션 수준 정거장 위의 작은 레이블; 하위 섹션의 kicker는 해당 섹션의 이름
door첫 번째 정거장의 HTML: 간략 소개, 참고 사항, 평면 페이지 링크
stations[]id; sec 및/또는 sub (콘텐츠 행; sec만 있으면 섹션, sub만 있으면 하위 섹션, 둘 다 있으면 이 정거장에서 섹션 시작); title (기본값 sub, 그다음 sec); lead (HTML, 한두 문장); fig 또는 html; cards ([{img, label}], 작은 이미지 행); lit (밝힐 스트림 그룹)
cards_label정거장 이미지 행 끝의 레이블
close마지막 정거장(보통 출처)의 {title, kicker, html}
stream[]카드당 {label, img, group}. 40~80개가 스트림으로 적절함
css선택적 추가 CSS, 마지막에 추가됨

확인

K=$SK/capture.mjs
node $K file:///path/page.html at-2.png 2                  # 정지 상태의 정거장
node $K file:///path/page.html transit.png 4.4 --wait=900  # 두 정거장 사이, 스냅 해제됨
node $K file:///path/page.html last.png 9                  # 마지막 정지점에 도달 가능
node $K file:///path/page.html light.png 5 --light         # 밝은 바탕
node $K file:///path/page.html phone.png 3 375 700         # 전화기 너비
node $K file:///path/page.html flat.png 0 --reduce         # 축소 모션 페이지
node $K "file:///path/page.html#st-model" hash.png -       # 로드 시 정지점 링크
node $K file:///path/page.html nav.png 0 --nav             # 화살표, 마지막 콘텐츠 링크, 레일

각 실행은 정지점과 단계별로 y, front(포인터 이벤트를 받는 정거장), rail, cardsShown, cardsLit, deep 및 pageWidth를 출력합니다. 정지 상태의 정거장은 front가 인덱스와 같습니다. pageWidth는 뷰포트 너비를 읽어야 합니다(옆으로 페이지 스크롤 없음). 완료했다고 판단하기 전에 모든 이미지를 두 바탕 모두에서 그리고 전화기 너비에서 확인하십시오. 이미지가 폴더 외부에 있는 페이지의 경우, 먼저 절대 이미지 경로를 사용하여 페이지를 스크래치패드로 복사하십시오.

chrome --headless --screenshot으로 확인하지 마십시오. --virtual-time-budget에서는 애니메이션 프레임이 거의 진행되지 않아 이지드 카메라가 도착하지 못하고, 스크롤된 창의 스크린샷이 빈 상태로 반환될 수 있습니다. capture.mjs는 실시간 헤드리스 Chrome을 구동하여 프레임이 실제 속도로 실행됩니다.

조정

상수는 template.html의 스크립트 헤드에 있습니다.

상수값영향
PERSP900.stations 및 .field의 CSS perspective와 일치해야 함
GAP1400두 정거장 사이의 세계 깊이
AHEAD2.2 × GAP정거장이 그려지는 최대 앞 깊이
PASS300지나가는 정거장이 사라지는 깊이 (배율 1.5)
LIFT36기다리는 정거장이 GAP 거리당 낮게 위치하는 픽셀 수
DEPTH, NEAR2800, 220스트림의 생성 깊이와 카드가 지나간 깊이
BASE46정지 상태의 스트림 속도, px/s
camera ease초당 9회카메라가 스크롤을 따라잡는 속도

첫 번째 빌드에서 잘못된 점

각 문제는 확인을 통해 발견되었으며, 템플릿에서 수정되었습니다.

  • 헤더의 스크롤 여백 고정 헤더는 모든 [id]에 scroll-margin-top을 제공하므로 앵커가 헤더 아래에 배치됩니다. 정지점이 0으로 설정될 때까지 점프는 각 정지점보다 126px 짧게 도달했습니다.
  • 트랙이 헤더 하나만큼 짧았습니다 마지막 정지점이 상단에 도달하기 전에 페이지가 끝났습니다. 트랙 높이는 스테이지 높이가 아닌 창 높이를 사용합니다.
  • 카드가 콘텐츠 열 뒤로 날아갔습니다 해당 열은 고정되어 있고 투명하므로 카드가 텍스트를 통해 보였습니다. 열이 고정되면 스테이지가 오른쪽에서 시작됩니다.
  • 먼 카드가 소실점에 모였습니다 WhatTheFad의 마스크가 해결했습니다.
  • 지나가는 정거장이 큰 흐릿함으로 남았습니다 더 짧은 PASS와 제곱 페이드로 수정되었습니다.
  • 기다리는 정거장이 짧은 정거장 아래에 표시되었습니다 흐리게(제곱) 그려집니다.
  • 평면 모드의 콘텐츠가 숨겨진 정지점을 가리켰습니다 정지점이 정거장으로 이동합니다.
  • 로드 이벤트 전에 도착한 스크롤이 짧은 페이지에 도달했습니다 문서가 구문 분석되자마자 트랙 레이아웃이 설정되고, 글꼴과 이미지가 안정되면 다시 설정되므로 복원된 스크롤과 #st-<id> 링크가 모두 정상적으로 도달합니다.
  • 전화기에서 넓은 드로잉은 플레이트 내에서 옆으로 패닝되고, 이미지 행은 숨겨지며, 정거장은 좁아져서 레일이 오른쪽 가장자리를 유지합니다.

열린 작업

  • 카드 잡기 WhatTheFad에서는 잡힌 칩이 발굴을 엽니다. 여기서는 카드가 해당 기록을 열 수 있으며, 대상 페이지가 URL에서 ID를 받고 위의 투영 히트 테스트가 필요합니다.
  • 일시 정지 제어 스트림은 페이지가 열려 있는 동안 계속 움직입니다. 축소 모션은 스트림을 멈추지만, WCAG 2.2.2가 5초 이상 지속되는 다른 콘텐츠와 함께 제공되는 모션에 요구하는 일시 정지 버튼은 없습니다.
  • 실제 트랙패드와 전화기에서의 느낌 및 프레임 속도 실제 사용자가 평가하지 않았습니다.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

관련 스킬